cap-pro 1.0.0

package/commands/cap/annotate.md

@@ -0,0 +1,165 @@
+---
+name: cap:annotate
+description: "Retroactively annotate existing code with @cap-feature and @cap-todo tags. Invokes cap-prototyper in ANNOTATE mode."
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<!-- @cap-context CAP v2.0 annotate command -- invokes cap-prototyper in annotate mode to add @cap-feature tags to existing unannotated code. Primary entry point after brownfield init. -->
+<!-- @cap-decision Annotate is a thin command wrapper over cap-prototyper ANNOTATE mode. This avoids a separate agent and keeps all code generation/modification in one agent with mode dispatch. -->
+<!-- @cap-decision Annotate targets a specific directory or defaults to project root src/. Scoped annotation prevents overwhelming the user with changes across the entire codebase at once. -->
+
+<!-- @cap-todo(ref:AC-89) /cap:annotate shall invoke cap-prototyper in annotate mode -->
+
+<objective>
+Add @cap-feature and @cap-todo tags to existing unannotated code by invoking cap-prototyper in ANNOTATE mode. This is the recommended next step after brownfield /cap:init.
+
+**Arguments:**
+- `[path]` -- directory or file to annotate (defaults to `src/` or project root)
+- `--feature F-NNN` -- scope annotation to a specific Feature Map entry
+- `--dry-run` -- preview annotations without writing files
+
+**Requires:** FEATURE-MAP.md must exist (run /cap:init first).
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+</context>
+
+<process>
+
+## Step 1: Validate prerequisites
+
+Check that CAP is initialized:
+
+```bash
+test -d .cap && echo "CAP_INITIALIZED" || echo "NOT_INITIALIZED"
+test -f FEATURE-MAP.md && echo "FEATURE_MAP_EXISTS" || echo "NO_FEATURE_MAP"
+```
+
+If not initialized, abort with: "CAP is not initialized. Run /cap:init first."
+
+## Step 2: Parse arguments
+
+- Extract `path` from positional argument (default: `src/` if exists, else `.`)
+- Extract `--feature` flag if present
+- Extract `--dry-run` flag if present
+
+## Step 3: Load context for annotate mode
+
+Read FEATURE-MAP.md to understand available features and ACs.
+
+Check for existing tags in target path:
+
+```bash
+node -e "
+const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');
+const tags = scanner.scanDirectory(process.cwd());
+const groups = scanner.groupByFeature(tags);
+console.log(JSON.stringify({
+  totalTags: tags.length,
+  features: Object.keys(groups),
+  filesWithTags: new Set(tags.map(t => t.file)).size
+}));
+"
+```
+
+Load stack docs if available:
+
+```bash
+ls .cap/stack-docs/*.md 2>/dev/null | head -10 || echo "no stack docs"
+```
+
+## Step 4: Invoke cap-prototyper in ANNOTATE mode
+
+Use the Task tool to spawn cap-prototyper with ANNOTATE mode:
+
+```
+Task("cap-prototyper", "
+**MODE: ANNOTATE**
+
+**Target path:** {resolved_path}
+**Feature scope:** {feature_id or 'all'}
+**Dry run:** {dry_run}
+
+**FEATURE-MAP.md content:**
+{feature_map_content}
+
+**Existing tags found:**
+{existing_tag_summary}
+
+**Stack docs available:**
+{stack_docs_list}
+
+**Instructions:**
+1. Scan {target_path} for source files without @cap-feature tags
+2. Read each unannotated file and identify significant functions, classes, modules
+3. Match code to Feature Map entries based on purpose and file paths
+4. Use the Edit tool to add @cap-feature tags WITHOUT changing code logic
+5. Add @cap-todo tags for any unfinished work discovered during annotation
+6. {If dry_run: 'OUTPUT the proposed changes but do NOT write files'}
+")
+```
+
+## Step 5: Run scan after annotation
+
+After the prototyper completes, run a scan to update Feature Map:
+
+```bash
+node -e "
+const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const tags = scanner.scanDirectory(process.cwd());
+const updated = fm.enrichFromTags(process.cwd(), tags);
+console.log(JSON.stringify({
+  totalTags: tags.length,
+  featuresWithFiles: updated.features.filter(f => f.files.length > 0).length,
+  totalFileRefs: updated.features.reduce((sum, f) => sum + f.files.length, 0)
+}));
+"
+```
+
+## Step 6: Report results
+
+```
+cap:annotate complete.
+
+Files annotated: {N}
+Tags added: {N}
+  @cap-feature: {N}
+  @cap-todo:    {N}
+  @cap-risk:    {N}
+  @cap-decision:{N}
+
+Feature Map updated:
+  Features with file refs: {N}
+  Total file references:   {N}
+
+Next steps:
+  /cap:scan      -- verify tag coverage
+  /cap:prototype -- build out features that need implementation
+  /cap:status    -- view project dashboard
+```
+
+## Step 7: Update session
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:annotate',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'annotated'
+});
+"
+```
+
+</process>

package/commands/cap/brainstorm.md

@@ -0,0 +1,393 @@
+---
+name: cap:brainstorm
+description: Interactive feature discovery — produces FEATURE-MAP.md entries (acceptance criteria, dependencies, feature grouping) from a structured conversation. TRIGGER when the user wants to plan a new feature, says "let's add X / build Y / we need a feature for Z", describes a problem without concrete ACs yet, references a Feature ID that doesn't exist in FEATURE-MAP.md, or asks "what should we build next". DO NOT trigger for refining an existing feature (use cap:iterate) or bug fixes (use cap:debug). Spawns cap-brainstormer agent.
+argument-hint: "[--resume] [--multi]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<!-- @cap-context CAP v2.0 brainstorm command -- orchestrates conversational feature discovery. Spawns cap-brainstormer agent, receives structured Feature Map entries, writes to FEATURE-MAP.md after user approval. -->
+<!-- @cap-decision Writes directly to FEATURE-MAP.md (not PRD files). Feature Map is the single source of truth in CAP. PRDs are an intermediate artifact that CAP eliminates. -->
+<!-- @cap-decision Command layer owns all file I/O -- agent is stateless. Proven pattern from GSD brainstorm.md. -->
+<!-- @cap-constraint No Feature Map entries are written without explicit user approval -- confirmation gate is mandatory -->
+
+<objective>
+Spawns the `cap-brainstormer` agent to have a structured conversation about what needs to be built. The agent returns structured Feature Map entries. This command presents the entries for user confirmation, then writes to FEATURE-MAP.md.
+
+<!-- @cap-todo(ref:AC-36) /cap:brainstorm shall invoke the cap-brainstormer agent for conversational feature discovery. -->
+
+**Arguments:**
+- `--resume` -- resume a previous brainstorm session using .cap/SESSION.json context
+- `--multi` -- hint that the project has multiple independent feature areas
+
+**Key guarantee:** No Feature Map entries are written until the user explicitly approves.
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+@.cap/SESSION.json
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for:
+- `--resume` -- if present, set `resume_mode = true`
+- `--multi` -- if present, set `multi_mode = true`
+
+Log: "cap:brainstorm | resume: {resume_mode} | multi: {multi_mode}"
+
+## Step 1: Load existing Feature Map and session state
+
+Read FEATURE-MAP.md:
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+// @cap-todo(ac:F-081/AC-4 iter:2) Migrated to {safe: true} opt-in to preserve CLI on duplicate-ID FEATURE-MAP.
+// @cap-decision(F-081/iter2) Warn on parseError; continue with partial map for read-only display.
+const featureMap = fm.readFeatureMap(process.cwd(), undefined, { safe: true });
+if (featureMap && featureMap.parseError) {
+  console.warn('cap: brainstorm — duplicate feature ID detected, existing-features list uses partial map: ' + String(featureMap.parseError.message).trim());
+}
+console.log(JSON.stringify({
+  featureCount: featureMap.features.length,
+  existingIds: featureMap.features.map(f => f.id),
+  existingTitles: featureMap.features.map(f => f.title)
+}));
+"
+```
+
+Store as `existing_features`.
+
+If `resume_mode`:
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const s = session.loadSession(process.cwd());
+console.log(JSON.stringify(s));
+"
+```
+
+Store as `session_context`.
+
+## Step 1b: Check for prior brainstorm threads
+
+Check if the user's topic has been explored before. This gives the brainstormer context about prior discussions.
+
+```bash
+node -e "
+const tracker = require('./cap/bin/lib/cap-thread-tracker.cjs');
+const threads = tracker.listThreads(process.cwd());
+console.log(JSON.stringify({ threadCount: threads.length, threads: threads.slice(0, 10) }));
+"
+```
+
+Store as `prior_threads`.
+
+If `resume_mode` and `session_context.activeThread`:
+
+```bash
+node -e "
+const tracker = require('./cap/bin/lib/cap-thread-tracker.cjs');
+const thread = tracker.loadThread(process.cwd(), '{session_context.activeThread}');
+console.log(JSON.stringify(thread));
+"
+```
+
+Store as `resume_thread`. This is the thread from the previous brainstorm session to continue.
+
+If `prior_threads.threadCount > 0` and NOT `resume_mode`:
+- Display prior threads briefly:
+  ```
+  Found {threadCount} prior brainstorm thread(s):
+  {For each thread:}
+    - {thread.name} ({thread.timestamp}) — features: {thread.featureIds.join(', ') || 'none'}
+  {End for}
+  ```
+- The brainstormer agent will receive this context and can reference prior threads during conversation.
+
+## Step 1c: Passively check thread affinity before brainstorm
+
+<!-- @cap-todo(ac:F-040/AC-5) /cap:brainstorm passively checks thread affinity at session start and presents relevant prior threads (notify band and above) before beginning discovery questions -->
+
+If prior threads exist, check realtime affinity to surface relevant ones:
+
+```bash
+node -e "
+const realtimeAffinity = require('./cap/bin/lib/cap-realtime-affinity.cjs');
+const clusterDisplay = require('./cap/bin/lib/cap-cluster-display.cjs');
+const tracker = require('./cap/bin/lib/cap-thread-tracker.cjs');
+const session = require('./cap/bin/lib/cap-session.cjs');
+
+try {
+  const threads = tracker.listThreads(process.cwd());
+  if (threads.length > 0) {
+    const s = session.loadSession(process.cwd());
+    // Use the most recent thread as reference point for affinity detection
+    const latestThread = threads[0];
+    const fullThread = tracker.loadThread(process.cwd(), latestThread.id);
+    if (fullThread) {
+      const notifications = realtimeAffinity.onSessionStart(process.cwd(), fullThread);
+      const output = clusterDisplay.formatRealtimeNotifications(notifications);
+      if (output) console.log(output);
+      else console.log('');
+    } else {
+      console.log('');
+    }
+  } else {
+    console.log('');
+  }
+} catch (e) {
+  console.log('');
+}
+"
+```
+
+If output is non-empty, display it before spawning the brainstormer:
+
+```
+{thread_affinity_output}
+```
+
+This gives the user awareness of related prior discussions before beginning a new brainstorm.
+
+## Step 2: Spawn cap-brainstormer agent
+
+<!-- @cap-todo(ref:AC-37) cap-brainstormer shall produce structured PRD output with numbered acceptance criteria. -->
+<!-- @cap-todo(ref:AC-39) cap-brainstormer shall assign feature IDs in sequential format (F-001, F-002, ...). -->
+
+Spawn `cap-brainstormer` via the Task tool with the following context:
+
+```
+$ARGUMENTS
+
+**Session context:**
+Resume mode: {resume_mode}
+Multi-feature hint: {multi_mode}
+Existing features: {existing_features.featureCount} features already in FEATURE-MAP.md
+Existing IDs: {existing_features.existingIds}
+Next available ID: F-{padded next number}
+
+{If resume_mode and resume_thread:}
+**Resuming prior thread:**
+Thread ID: {resume_thread.id}
+Thread name: {resume_thread.name}
+Problem statement: {resume_thread.problemStatement}
+Solution shape: {resume_thread.solutionShape}
+Boundary decisions: {resume_thread.boundaryDecisions}
+Prior feature IDs: {resume_thread.featureIds}
+{End if}
+
+{If prior_threads.threadCount > 0 and NOT resume_mode:}
+**Prior brainstorm threads (for reference):**
+{For each thread in prior_threads.threads:}
+- {thread.name} ({thread.timestamp}) — keywords: {thread.keywords.slice(0,8).join(', ')} — features: {thread.featureIds.join(', ') || 'none'}
+{End for}
+NOTE: If the user's topic overlaps with a prior thread, reference it. Ask if they want to continue that line of thinking or explore something new.
+{End if}
+
+{If resume_mode and session_context and NOT resume_thread:}
+**Previous session context (no thread found):**
+Active feature: {session_context.activeFeature}
+Last step: {session_context.step}
+Last command: {session_context.lastCommand}
+{End if}
+
+**Instructions:**
+1. Have a conversational exchange with the user to understand what needs to be built
+2. Ask targeted questions ONE AT A TIME -- do not present a list of questions
+3. After sufficient understanding, cluster features into logical groups
+4. Surface dependencies between feature groups
+5. For each feature, draft numbered acceptance criteria in imperative form
+6. Assign feature IDs:
+   - For single-app projects: sequential `F-NNN` starting from {next available ID}
+   - For monorepo projects (apps/* or workspace packages > 1): prefer descriptive `F-<App>-<Slug>` IDs (e.g., `F-Hub-Spotlight-Carousel`). Detect monorepo: presence of `apps/` directory or `package.json:workspaces`. Both formats may coexist.
+7. Return the feature entries in the exact structured format below
+
+**Return format (delimited):**
+
+=== BRAINSTORM OUTPUT ===
+FEATURE_COUNT: N
+
+=== FEATURE: F-NNN ===
+TITLE: {verb+object title}
+GROUP: {logical group name}
+DEPENDS_ON: {comma-separated F-IDs or "none"}
+AC-1: {imperative description}
+AC-2: {imperative description}
+...
+=== END FEATURE ===
+
+{Repeat for each feature}
+
+=== DECISIONS ===
+- {decision 1}
+- {decision 2}
+=== END DECISIONS ===
+
+=== END BRAINSTORM OUTPUT ===
+
+Do NOT write any files -- return structured output only.
+```
+
+Wait for `cap-brainstormer` to complete.
+
+**Parse the agent output:**
+
+1. Extract between `=== BRAINSTORM OUTPUT ===` and `=== END BRAINSTORM OUTPUT ===`
+2. Parse `FEATURE_COUNT:` line
+3. For each `=== FEATURE: F-NNN ===` block, extract: TITLE, GROUP, DEPENDS_ON, and all AC-N lines
+4. Extract decisions from `=== DECISIONS ===` block
+5. Build Feature objects:
+
+```javascript
+{
+  id: "F-NNN",
+  title: "extracted title",
+  state: "planned",
+  acs: [{ id: "AC-1", description: "...", status: "pending" }, ...],
+  files: [],
+  dependencies: ["F-NNN", ...],
+  metadata: { group: "group name" }
+}
+```
+
+## Step 3: Present features for user approval
+
+<!-- @cap-todo(ref:AC-38) cap-brainstormer shall write discovered features directly to FEATURE-MAP.md with state planned. -->
+<!-- @cap-todo(ref:AC-40) cap-brainstormer output shall be directly consumable by /cap:prototype without manual translation. -->
+
+Display the parsed features:
+
+```
+Brainstorm complete. {feature_count} features discovered:
+
+{For each feature:}
+  {feature.id}: {feature.title} [{feature.state}]
+    Group: {group}
+    Dependencies: {deps or "none"}
+    Acceptance criteria:
+      AC-1: {description}
+      AC-2: {description}
+      ...
+{End for}
+
+Decisions made:
+{For each decision:}
+  - {decision}
+{End for}
+```
+
+Use AskUserQuestion:
+> "Review the {feature_count} features above. Approve writing to FEATURE-MAP.md? [yes / provide corrections / restart]"
+
+- If `yes`, `y`, or `approve`: proceed to Step 4
+- If corrections: Re-spawn `cap-brainstormer` with original context + `**Corrections from user:** {user text}`. Re-parse and re-display. Loop back to approval gate.
+- If `restart`: Clear all parsed data. Go back to Step 2 with fresh Task() call.
+
+**IMPORTANT:** No code path reaches Step 4 without explicit user approval.
+
+## Step 4: Write approved features to FEATURE-MAP.md
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+// @cap-todo(ac:F-081/AC-4 iter:2) Migrated to {safe: true} opt-in to preserve CLI on duplicate-ID FEATURE-MAP.
+// @cap-decision(F-081/iter2) Bail on parseError — do not persist partial enrichment (write-back path).
+const featureMap = fm.readFeatureMap(process.cwd(), undefined, { safe: true });
+if (featureMap && featureMap.parseError) {
+  console.error('cap: brainstorm write aborted — duplicate feature ID detected: ' + String(featureMap.parseError.message).trim());
+  process.exit(2);
+}
+const newFeatures = {JSON.stringify(parsed_features)};
+const updated = fm.addFeatures(featureMap, newFeatures);
+fm.writeFeatureMap(process.cwd(), updated);
+console.log('Written ' + newFeatures.length + ' features to FEATURE-MAP.md');
+"
+```
+
+## Step 5: Persist brainstorm thread
+
+Save this brainstorm session as a conversation thread. This enables future sessions to reference prior discussions.
+
+Build the thread from the brainstorm results:
+- `problemStatement`: The user's initial problem or topic (from the conversation)
+- `solutionShape`: The high-level approach that emerged
+- `boundaryDecisions`: Key scope decisions from the `=== DECISIONS ===` block
+- `featureIds`: The IDs of features written to the Feature Map
+
+```bash
+node -e "
+const tracker = require('./cap/bin/lib/cap-thread-tracker.cjs');
+const resumeThreadId = '{resume_thread?.id || null}';
+const parentThread = resumeThreadId !== 'null' ? tracker.loadThread(process.cwd(), resumeThreadId) : null;
+
+const threadParams = {
+  problemStatement: '{problem_statement from conversation}',
+  solutionShape: '{solution_shape from conversation}',
+  boundaryDecisions: {JSON.stringify(decisions_from_brainstorm)},
+  featureIds: {JSON.stringify(feature_ids_written)},
+};
+
+let thread;
+if (parentThread) {
+  // Branching from resumed thread
+  thread = tracker.branchThread(parentThread, {
+    ...threadParams,
+    divergencePoint: 'Continued from prior session'
+  });
+} else {
+  thread = tracker.createThread(threadParams);
+}
+
+tracker.persistThread(process.cwd(), thread);
+console.log(JSON.stringify({ threadId: thread.id, threadName: thread.name }));
+"
+```
+
+Store as `persisted_thread`.
+
+## Step 5b: Update session state
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:brainstorm',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'brainstorm-complete',
+  activeThread: '{persisted_thread.threadId}'
+});
+"
+```
+
+## Step 6: Final report
+
+```
+cap:brainstorm complete.
+
+Features written to FEATURE-MAP.md: {feature_count}
+  {For each feature: feature.id: feature.title}
+
+Decisions recorded: {decision_count}
+Thread saved: {persisted_thread.threadName} ({persisted_thread.threadId})
+
+Next steps:
+  - Run /cap:start to select a feature to work on
+  - Run /cap:prototype --features {first_feature_id} to build initial code
+  - Run /cap:brainstorm --resume to continue this thread later
+```
+
+</process>

package/commands/cap/checkpoint.md

@@ -0,0 +1,106 @@
+---
+name: cap:checkpoint
+description: Advisory checkpoint detection — nudges /compact at natural breakpoints, saves a labeled snapshot via cap-historian before the context fills up.
+argument-hint: ""
+allowed-tools:
+  - Task
+  - Bash
+  - Read
+  - Write
+---
+
+<!-- @cap-feature(feature:F-057) Checkpoint Command for Strategic Compact -->
+<!-- @cap-todo(ac:F-057/AC-1) /cap:checkpoint ist aufrufbar — this file registers the slash command. -->
+<!-- @cap-todo(ac:F-057/AC-2) Command prueft SESSION.json (step-Transitions, AC-Status-Updates) und FEATURE-MAP-Diff seit letzter Checkpoint-Zeit auf logische Breakpoints. Delegated to cap-checkpoint.analyzeAndApply(). -->
+<!-- @cap-todo(ac:F-057/AC-3) Bei erkanntem Breakpoint gibt Command Empfehlung aus: "Jetzt /compact, weil {konkreter Grund}". -->
+<!-- @cap-todo(ac:F-057/AC-4) Bei erkanntem Breakpoint wird vor der Empfehlung implizit ein Snapshot mit Label `checkpoint-{feature_id}` angelegt. -->
+<!-- @cap-decision Breakpoint-Heuristik bleibt in cap-checkpoint.cjs (analyzeAndApply). Die Save-Aktion wurde von "/cap:save chained" auf "Task() → cap-historian MODE: SAVE" umgestellt — gleiches Outcome (Snapshot in .cap/snapshots/), zusätzlich JSONL-Index-Eintrag. -->
+<!-- @cap-todo(ac:F-057/AC-6) /cap:checkpoint bleibt advisory: KEIN Auto-/compact, KEIN --force-Flag. User entscheidet. -->
+<!-- @cap-todo(ac:F-057/AC-5) Kein Breakpoint erkannt -> Message "Kein natürlicher Kontextbruch erkannt.", keine weitere Action. -->
+
+<objective>
+Detect natural breakpoints in the CAP workflow and nudge the user toward `/compact` before auto-compact degrades context quality. When a breakpoint is detected, the command first writes a `checkpoint-{feature_id}` snapshot via the cap-historian agent.
+
+**Purely advisory.** Never runs `/compact` itself. No `--force` flag. The user decides.
+</objective>
+
+<process>
+
+## Step 1: Analyze and persist breakpoint state
+
+`analyzeAndApply` reads SESSION.json and FEATURE-MAP.md, computes the plan, and — if a breakpoint was detected — persists `lastCheckpointAt` + `lastCheckpointSnapshot` in a single Node call (closes the TOCTOU window).
+
+```bash
+node -e "
+const capCheckpoint = require('./cap/bin/lib/cap-checkpoint.cjs');
+const result = capCheckpoint.analyzeAndApply(process.cwd());
+console.log(JSON.stringify(result, null, 2));
+"
+```
+
+Output shape:
+
+```
+{
+  "breakpoint": { "kind": "...", "featureId": "F-057", "reason": "..." } | null,
+  "plan": {
+    "shouldSave": true | false,
+    "saveLabel": "checkpoint-F-057" | null,
+    "message": "Jetzt /compact, weil ..." | "Kein natürlicher Kontextbruch erkannt."
+  },
+  "currentSnapshot": { "featureStates": {...}, "acStatuses": {...} },
+  "persisted": true | false
+}
+```
+
+## Step 2: Branch on breakpoint
+
+**If `plan.breakpoint` is null:**
+
+Print verbatim and stop:
+
+```
+Kein natürlicher Kontextbruch erkannt.
+```
+
+(AC-5)
+
+**If `plan.breakpoint` is non-null:** continue. Checkpoint state is already persisted (AC-4).
+
+## Step 3: Save snapshot via cap-historian
+
+Spawn `cap-historian` in SAVE mode with `plan.saveLabel` as the snapshot name:
+
+```
+**MODE: SAVE**
+
+{plan.saveLabel}
+
+Save the current session as a checkpoint snapshot. Use the active feature for
+linkage (default behavior — no --unassigned, no --platform). Reuse
+cap-snapshot-linkage.cjs and cap-session-extract.cjs.
+
+Return `=== HISTORIAN SAVE RESULTS ===` verbatim.
+```
+
+Wait for cap-historian to complete.
+
+## Step 4: Print recommendation
+
+Print `plan.message` verbatim:
+
+```
+Jetzt /compact, weil {konkreter Grund}.
+```
+
+## Step 5: Advisory boundary
+
+Do NOT invoke `/compact`. The only side effects of this command are:
+
+1. The checkpoint snapshot written by cap-historian (Step 3).
+2. `lastCheckpointAt` + `lastCheckpointSnapshot` updated in SESSION.json (Step 1).
+3. The recommendation printed to the user (Step 4).
+
+If the user wants to compact, they run `/compact` themselves.
+
+</process>