Skip to content

Commit faee14c

Browse files
josealekhinejosealekhine
committed
docs: archive v0.2.0 specs and add v0.3.0 roadmap
 Archive released v0.2.0 specifications: - Move browsable, import, rag, session-schema, thinking specs to specs/released/v0.2.0/ - Add PROMPT.md, RELEASE_NOTES.md, IMPLEMENTATION_PLAN.md for v0.2.0 Add new specs for v0.3.0 development: - active-sessions.md: real-time session monitoring - auditors.md: pluggable validation system - context-health.md: context file health scoring - monitor-architecture.md: background monitoring design - signals.md: cross-session signal detection Update project tracking: - Refocus PROMPT.md for next iteration - Update TASKS.md with v0.3.0 roadmap - Archive completed tasks to tasks-2026-02-03.md - Fix table formatting in AGENT_PLAYBOOK.md Signed-off-by: Jose Alehinne <alehinejose@gmail.com>
1 parent b75fabb commit faee14c

17 files changed

Lines changed: 1691 additions & 306 deletions

‎.context/AGENT_PLAYBOOK.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -371,15 +371,15 @@ Before writing or modifying CLI code (`internal/cli/**/*.go`):
371371

372372
**cmd methods to use:**
373373

374-
| Instead of | Use | Purpose |
375-
|-------------------|--------------------|--------------------------------------|
376-
| `fmt.Printf` | `cmd.Printf` | Formatted stdout |
377-
| `fmt.Println` | `cmd.Println` | Line to stdout |
378-
| `fmt.Print` | `cmd.Print` | Raw stdout |
379-
| `fmt.Fprintf(os.Stderr, ...)` | `cmd.PrintErrf` | Formatted stderr |
380-
| `fmt.Fprintln(os.Stderr, ...)` | `cmd.PrintErrln` | Line to stderr |
381-
| `fmt.Sprintf` | `fmt.Sprintf` | String formatting (OK to keep) |
382-
| `fmt.Errorf` | `fmt.Errorf` | Error creation (OK to keep) |
374+
| Instead of | Use | Purpose |
375+
|--------------------------------|------------------|--------------------------------|
376+
| `fmt.Printf` | `cmd.Printf` | Formatted stdout |
377+
| `fmt.Println` | `cmd.Println` | Line to stdout |
378+
| `fmt.Print` | `cmd.Print` | Raw stdout |
379+
| `fmt.Fprintf(os.Stderr, ...)` | `cmd.PrintErrf` | Formatted stderr |
380+
| `fmt.Fprintln(os.Stderr, ...)` | `cmd.PrintErrln` | Line to stderr |
381+
| `fmt.Sprintf` | `fmt.Sprintf` | String formatting (OK to keep) |
382+
| `fmt.Errorf` | `fmt.Errorf` | Error creation (OK to keep) |
383383

384384
**Why**: cmd methods write to testable buffers; fmt writes to real stdout/stderr.
385385

‎.context/TASKS.md‎

Lines changed: 71 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,82 @@
1-
- [ ] Add integration tests for CLI commands (drift, sync, decision, learnings, serve, recall) - test actual file operations and command execution #added:2026-02-01-062541
2-
31
# Tasks — Context CLI
42

5-
# Tasks
6-
7-
## Phase 0: Cleanup from the previous version
8-
9-
(All tasks archived)
10-
11-
### Phase 1: Parser (DONE)
12-
133
## Phase 1.a: Cleanup and Release
144

15-
- [x] T1.2.0.1b Add index markers to DECISIONS.md and LEARNINGS.md templates
16-
so new projects start with index structure #priority:low #added:2026-01-29
17-
- [x] T1.2.5 feat: implement `--context-dir` global flag to override context directory path
18-
Documented in cli-reference.md as planned. Should allow `ctx --context-dir /path status`.
19-
#priority:low #added:2026-01-28
20-
- [x] T1.2.6 feat: implement `--quiet` global flag to suppress non-essential output
21-
Documented in cli-reference.md as planned.
22-
#priority:low #added:2026-01-28
23-
- [x] T1.2.7 feat: implement `--no-color` global flag to disable colored output
24-
Documented in cli-reference.md as planned. Currently `NO_COLOR=1` env var works.
25-
#priority:low #added:2026-01-28
26-
- [x] Write AST-based test that warns if CLI functions use fmt.Print* instead of
27-
cmd.Print* #added:2026-01-29-171351 #done:2026-01-31
28-
- [x] feat: `ctx recall export` - export sessions to editable journal files
29-
- `ctx recall export <session-id>` - export one session
30-
- `ctx recall export --all` - export all sessions
31-
- Skip existing files (user may have edited), `--force` to overwrite
32-
- Output to `.context/journal/YYYY-MM-DD-slug-shortid.md`
33-
#added:2026-01-28 #done:2026-01-31
34-
- [x] feat: ctx journal - LLM-powered session analysis and synthesis
35-
- [x] ctx journal site - generate zensical static site #done:2026-01-31
36-
- [x] ctx serve - convenience wrapper for zensical serve #done:2026-01-31
37-
- [x] /ctx-journal-enrich - slash command for frontmatter/tags #done:2026-01-31
38-
- [x] /ctx-journal-summarize - slash command for timeline summaries #done:2026-01-31
395
- [ ] T1.2.9: upstream CI is broken (again)
40-
- [x] T1.2.10: Human code review
41-
- [x] T1.2.11: Human to read all user-facing documentation and update as needed.
42-
- [x] T1.2.12: cut a release (version number is already bumped)
43-
- [ ] T1.2.13: Compose two blog posts: 1) what has changed after the human-guided
6+
- [x] T1.2.13: Compose two blog posts: 1) what has changed after the human-guided
447
refactoring, and what we can learn about this.
458
2) what has happened since the last release cut.
469
- [ ] T1.2.14: There is no documentation about the session site.
10+
- [ ] T1.2.15: Add integration tests for CLI commands (drift, sync, decision,
11+
learnings, serve, recall) - test actual file operations and command execution
12+
#added:2026-02-01-062541
13+
14+
## Phase 1.b: Init Improvements
15+
16+
- [ ] T1.3.1: Add `ctx init --ralph` flag — creates Ralph Loop infrastructure
17+
(PROMPT.md, IMPLEMENTATION_PLAN.md with strict one-task-exit discipline).
18+
Default `ctx init` remains conversational (no "never ask questions" directive).
19+
#added:2026-02-03
20+
21+
## Phase 2: Cross-Session Monitoring (`ctx monitor`)
22+
23+
Enable one agent/process to inform another about context health and audits.
24+
25+
### Phase 2.0: Infrastructure
26+
27+
- [x] T2.0.1: Create specs/monitor-architecture.md — overall design
28+
- [x] T2.0.2: Create specs/active-sessions.md — tombstone + heartbeat lifecycle spec
29+
- [x] T2.0.3: Create specs/context-health.md — health metrics, repetition detection
30+
- [x] T2.0.4: Create specs/auditors.md — programmatic vs semantic auditor system
31+
- [x] T2.0.5: Create specs/signals.md — atomic writes, TTL, hysteresis, session-scoped dirs
32+
33+
### Phase 2.1: Active Session Tracking
34+
35+
- [ ] T2.1.1: Create SessionStart hook — writes tombstone to .context/active-sessions/
36+
- [ ] T2.1.2: Create SessionEnd hook — removes tombstone from .context/active-sessions/
37+
- [ ] T2.1.3: Implement internal/monitor/session/tracker.go — GetActiveSessions()
38+
- [ ] T2.1.4: Add orphan detection — sessions with stale/missing transcripts
39+
40+
### Phase 2.2: Context Health Analysis
41+
42+
- [ ] T2.2.1: Implement internal/monitor/health/analyzer.go — parse JSONL, compute metrics
43+
- [ ] T2.2.2: Token estimation — estimate context % from message content lengths
44+
- [ ] T2.2.3: Repetition detection — hash recent content, detect loops
45+
- [ ] T2.2.4: Turn count and activity tracking
46+
47+
### Phase 2.3: Signal System
48+
49+
- [ ] T2.3.1: Implement internal/monitor/signal/writer.go — WriteSignal(), ClearSignal()
50+
- [ ] T2.3.2: Create UserPromptSubmit hook — reads .context/signals/, injects into context
51+
- [ ] T2.3.3: Signal cleanup — auto-remove after delivery
52+
53+
### Phase 2.4: Monitor Command
54+
55+
- [ ] T2.4.1: Create cmd/ctx/monitor.go — Cobra subcommand skeleton
56+
- [ ] T2.4.2: Implement watch loop — poll active sessions, run health checks
57+
- [ ] T2.4.3: Add --interval flag (default 30s)
58+
- [ ] T2.4.4: Add --once flag (run once and exit)
59+
60+
### Phase 2.5: Pluggable Auditors
61+
62+
- [ ] T2.5.1: Define Auditor interface in internal/monitor/auditor/
63+
- SessionAuditor: CheckSession(session, health) []Alert
64+
- ProjectAuditor: CheckProject(sessions, projectDir) []Alert
65+
- [ ] T2.5.2: Implement ContextHealthAuditor — warn on high usage, repetition (with hysteresis)
66+
- [ ] T2.5.3: Implement AuditReminderAuditor — soft nudge for semantic audits
67+
- Track last audit times in .context/audit-state.json
68+
- Remind after configurable thresholds (tasks: 3d, decisions: 7d, specs: 14d)
69+
- [ ] T2.5.4: Add --auditors flag to select which auditors run
70+
- [ ] T2.5.5: Alert identity and dedupe — stable keys, cooldown tracking, state persistence
71+
72+
### Phase 2.6: Semantic Audit Slash Commands
73+
74+
These are LLM-powered audits triggered by user, not continuous monitoring.
75+
76+
- [ ] T2.6.1: Create /ctx-audit-tasks skill — check if incomplete tasks are actually done
77+
- [ ] T2.6.2: Create /ctx-audit-decisions skill — check if code aligns with recorded decisions
78+
- [ ] T2.6.3: Create /ctx-audit-specs skill — check if implementation matches specs/
79+
- [ ] T2.6.4: Update .context/audit-state.json when audits run (for reminder tracking)
4780

4881
## Backlog
4982

@@ -99,10 +132,6 @@ Additional supporting context:
99132
Depends on: ctx recall export (Phase 2)
100133
#priority:low #phase:future #added:2026-01-28-071638
101134

102-
- [x] feat: /ctx-blog slash command - generate blog post draft from recent activity
103-
- [x] /ctx-blog - from recent activity (sessions, commits, decisions)
104-
- [x] /ctx-blog-changelog - from commit range with theme
105-
#added:2026-01-28-072625 #done:2026-01-31
106135

107136
- [ ] feat: ctx enrich - retroactively expand sparse context entries
108137

‎.context/archive/tasks-2026-02-03.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Task Archive — 2026-02-03
2+
3+
Archived from TASKS.md
4+
5+
- [x] T1.2.0.1b Add index markers to DECISIONS.md and LEARNINGS.md templates
6+
so new projects start with index structure #priority:low #added:2026-01-29
7+
- [x] T1.2.5 feat: implement `--context-dir` global flag to override context directory path
8+
Documented in cli-reference.md as planned. Should allow `ctx --context-dir /path status`.
9+
#priority:low #added:2026-01-28
10+
- [x] T1.2.6 feat: implement `--quiet` global flag to suppress non-essential output
11+
Documented in cli-reference.md as planned.
12+
#priority:low #added:2026-01-28
13+
- [x] T1.2.7 feat: implement `--no-color` global flag to disable colored output
14+
Documented in cli-reference.md as planned. Currently `NO_COLOR=1` env var works.
15+
#priority:low #added:2026-01-28
16+
- [x] Write AST-based test that warns if CLI functions use fmt.Print* instead of
17+
cmd.Print* #added:2026-01-29-171351 #done:2026-01-31
18+
- [x] feat: `ctx recall export` - export sessions to editable journal files
19+
- `ctx recall export <session-id>` - export one session
20+
- `ctx recall export --all` - export all sessions
21+
- Skip existing files (user may have edited), `--force` to overwrite
22+
- Output to `.context/journal/YYYY-MM-DD-slug-shortid.md`
23+
#added:2026-01-28 #done:2026-01-31
24+
- [x] feat: ctx journal - LLM-powered session analysis and synthesis
25+
- [x] ctx journal site - generate zensical static site #done:2026-01-31
26+
- [x] ctx serve - convenience wrapper for zensical serve #done:2026-01-31
27+
- [x] /ctx-journal-enrich - slash command for frontmatter/tags #done:2026-01-31
28+
- [x] /ctx-journal-summarize - slash command for timeline summaries #done:2026-01-31
29+
- [x] T1.2.10: Human code review
30+
- [x] T1.2.11: Human to read all user-facing documentation and update as needed.
31+
- [x] T1.2.12: cut a release (version number is already bumped)
32+
- [x] feat: /ctx-blog slash command - generate blog post draft from recent activity
33+
- [x] /ctx-blog - from recent activity (sessions, commits, decisions)
34+
- [x] /ctx-blog-changelog - from commit range with theme
35+
#added:2026-01-28-072625 #done:2026-01-31

0 commit comments

Comments
 (0)