cap-pro 1.0.0

package/commands/cap/completeness.md

@@ -0,0 +1,94 @@
+---
+name: cap:completeness
+description: "Generate a markdown audit of F-048's Implementation Completeness Score (4 signals per AC). Suitable for PR attachment."
+argument-hint: "[--out PATH] [--json]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<!-- @cap-context CAP v3 opt-in completeness-score command (F-048). Read-only by default. -->
+<!-- @cap-decision Writes a markdown file ONLY when --out is provided. Default output is stdout. -->
+<!-- @cap-feature(feature:F-048, primary:true) /cap:completeness orchestrator surfaces cap-completeness.cjs scoring as a PR-ready audit. -->
+
+<objective>
+Produce a per-AC audit using the four signals defined by F-048:
+
+- **T** — `@cap-*` tag in source code references the AC
+- **S** — a test file carries a `@cap-*` tag for the AC
+- **I** — at least one test file statically imports the primary implementation
+- **R** — primary file is reachable via imports from public surface (`bin/install.js`, `hooks/*.js`)
+
+Each AC scores 0–4. Feature average = arithmetic mean of its AC scores. The threshold gate for `shipped` transitions is enforced by `updateFeatureState()` when enabled.
+
+**Flags:**
+- `--out PATH` — write markdown report to `PATH` instead of stdout.
+- `--json` — emit structured JSON for downstream tooling.
+</objective>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+
+## Step 0: Opt-in gate
+
+```bash
+node -e "
+const comp = require('./cap/bin/lib/cap-completeness.cjs');
+const cfg = comp.loadCompletenessConfig(process.cwd());
+if (!cfg.enabled) {
+  console.error('F-048 (completeness score) is opt-in and not enabled for this project.');
+  console.error('To enable: add { \"completenessScore\": { \"enabled\": true } } to .cap/config.json');
+  process.exit(2);
+}
+console.log('threshold=' + cfg.shipThreshold);
+"
+```
+
+On exit 2, show the message and stop.
+
+## Step 1: Parse flags
+
+- `--out PATH` → `outPath`
+- `--json` → `jsonOutput`
+
+## Step 2: Compute scores
+
+```bash
+node -e "
+const comp = require('./cap/bin/lib/cap-completeness.cjs');
+const ctx = comp.buildContext(process.cwd());
+const scores = comp.scoreAllFeatures(ctx);
+const json = process.argv[1] === 'true';
+if (json) {
+  console.log(JSON.stringify(scores, null, 2));
+} else {
+  console.log(comp.formatCompletenessReport(scores));
+}
+" '<JSON>'
+```
+
+## Step 3: Write to file (only with --out)
+
+If `outPath` is set:
+
+```bash
+node -e "
+const fs = require('node:fs');
+const comp = require('./cap/bin/lib/cap-completeness.cjs');
+const ctx = comp.buildContext(process.cwd());
+const scores = comp.scoreAllFeatures(ctx);
+fs.writeFileSync(process.argv[1], comp.formatCompletenessReport(scores), 'utf8');
+console.log('Wrote ' + process.argv[1]);
+" '<OUT_PATH>'
+```
+
+## Step 4: Suggest next action
+
+- If any feature's averageScore < configured `shipThreshold` → "These features cannot transition to `shipped` with the current threshold. Add missing tags/tests, or lower `completenessScore.shipThreshold` in .cap/config.json if appropriate."
+- Otherwise → "All scored features meet the ship threshold. Attach the report to the next PR for audit."
+
+</process>

package/commands/cap/continue.md

@@ -0,0 +1,72 @@
+---
+name: cap:continue
+description: Load a saved context snapshot via the cap-historian agent — restores decisions and file-change history with diff-aware re-reads (only modified files are re-read).
+argument-hint: "[name] [--snapshot=<path>]"
+allowed-tools:
+  - Task
+  - Read
+  - Bash
+  - AskUserQuestion
+---
+
+<!-- @cap-context Thin orchestrator. Snapshot loading + mtime-diff lives in agents/cap-historian.md MODE: CONTINUE. -->
+<!-- @cap-decision /cap:continue delegates to cap-historian. Token-sparing core (stat-first diff, only re-read drifted files) is owned by the agent, not duplicated here. -->
+
+<objective>
+Spawn `cap-historian` in CONTINUE mode to load a previously saved snapshot into this session. The agent computes an mtime-based diff between snapshot capture time and the working tree, and re-reads only the files that drifted.
+
+**Arguments (backwards-compatible):**
+- `[name]` — snapshot name to load. If omitted, the agent picks the most-recent snapshot whose `feature:` matches `SESSION.json.activeFeature` (falls back to absolute most-recent).
+- `--snapshot=<path>` — explicit path to a snapshot `.md` file (overrides `[name]`).
+</objective>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Optional snapshot listing
+
+If `$ARGUMENTS` is empty AND no active feature is set, list available snapshots so the user can pick:
+
+```bash
+ls -t .cap/snapshots/*.md 2>/dev/null | head -10
+```
+
+Then ask the user which snapshot to load. Otherwise skip to Step 2.
+
+## Step 2: Spawn cap-historian
+
+Invoke `cap-historian` via Task tool:
+
+```
+**MODE: CONTINUE**
+
+$ARGUMENTS
+
+Resolve target snapshot (positional [name], --snapshot=<path>, or most-recent
+matching SESSION.json.activeFeature). Parse frontmatter, run mtime-diff against
+files_changed, Read ONLY drifted files. Append a `continue` event to
+.cap/snapshots/index.jsonl.
+
+Return the structured `=== HISTORIAN CONTINUE RESULTS ===` block AND the
+`=== Context Restored from: <name> ===` user-facing summary.
+```
+
+Wait for the agent to complete.
+
+## Step 3: Behavioral rules (post-restore)
+
+After the snapshot is restored:
+
+- Treat all snapshot information as **established context** — do not re-verify decisions.
+- For files flagged as **modified**, the CURRENT file content is authoritative; the snapshot is history.
+- If the snapshot lists open questions or next steps, proactively suggest picking up from there.
+- Do NOT re-summarize the snapshot back to the user — they lived through it.
+
+## Step 4: Optional /cap:start chain
+
+If the snapshot's frontmatter carries a `feature: F-NNN` and `SESSION.json.activeFeature` differs, set the active feature to match (same as `/cap:start` would).
+
+</process>