cap-pro 1.0.0

package/commands/cap/reconcile.md

@@ -0,0 +1,121 @@
+---
+name: cap:reconcile
+description: One-shot status drift reconciliation -- propose AC promotions and feature-state corrections for FEATURE-MAP.md, with dry-run preview and audit log.
+argument-hint: "[--apply] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<!-- @cap-context CAP v2.0 reconcile command -- one-shot cleanup of historical status drift in FEATURE-MAP.md introduced before F-041 (parser fix) and F-042 (state propagation) shipped. Combines AC-status drift detection (Phase 1) with implementation-presence drift detection (Phase 2). -->
+<!-- @cap-decision Dry-run by default. The --apply flag is required to actually mutate FEATURE-MAP.md, and a confirmation prompt is shown before writes (skippable with -y for CI). -->
+<!-- @cap-decision F-043 (this feature) is excluded from Phase 2 self-promotion -- the developer decides when to ship F-043, not the tool. -->
+<!-- @cap-feature(feature:F-043) /cap:reconcile is the user-facing entry point for the reconciliation tool. -->
+
+<objective>
+<!-- @cap-todo(ac:F-043/AC-1) Scan FEATURE-MAP.md and propose AC status updates for every drifting feature (state shipped/tested with pending ACs). -->
+<!-- @cap-todo(ac:F-043/AC-2) Output a dry-run diff first; require explicit confirmation (--apply + prompt) before writing. -->
+
+Reconciles status drift in FEATURE-MAP.md by:
+1. **Phase 1** -- promoting pending ACs to `tested` for every feature whose state is `shipped` or `tested` (catches drift introduced by the F-041 parser bug).
+2. **Phase 2** -- updating `planned` features to `prototyped` or `tested` based on actual code presence detected via `@cap-feature` tags + sibling test-file probe.
+3. **Phase 3** -- verifying that `detectDrift` returns zero entries after the changes, and emitting `.cap/memory/reconciliation-2026-04.md` audit log.
+
+**Arguments:**
+- `--apply` -- actually write the changes (default is dry-run)
+- `-y` / `--yes` -- skip the confirmation prompt (CI use)
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for:
+- `--apply` -- if present, set `apply_mode = true`
+- `-y` or `--yes` -- if present, set `skip_confirm = true`
+
+If neither flag is present: `apply_mode = false` (dry-run).
+
+Log: `cap:reconcile | mode: {dry-run|apply} | confirm: {prompt|skip}`
+
+## Step 1: Build the plan and print the dry-run preview
+
+<!-- @cap-todo(ac:F-043/AC-2) Always print the dry-run preview first, even when --apply is set. The confirmation prompt comes after. -->
+
+```bash
+node -e "
+const r = require('./cap/bin/lib/cap-reconcile.cjs');
+const plan = r.planReconciliation(process.cwd());
+console.log(r.formatPlan(plan));
+console.log('---');
+console.log('PLAN_TOTAL_CHANGES=' + plan.totalChanges);
+"
+```
+
+Display the preview verbatim. Capture `PLAN_TOTAL_CHANGES`.
+
+If `PLAN_TOTAL_CHANGES === 0`: report "Feature Map is already consistent -- no reconciliation needed." and **stop**.
+
+## Step 2: Dry-run exit (when --apply is not set)
+
+If `apply_mode` is false: report "Dry-run only. Re-run with `--apply` to commit changes." and **stop**. Exit code 0.
+
+## Step 3: Confirm before applying (when --apply is set)
+
+<!-- @cap-todo(ac:F-043/AC-2) Confirmation prompt is the second safety gate before writes. -->
+
+If `skip_confirm` is false:
+- Use AskUserQuestion to present: `"Apply N changes to FEATURE-MAP.md? Audit log will be written to .cap/memory/reconciliation-2026-04.md"` with options `["yes", "no"]`.
+- If the user picks `no`: report "Aborted -- no changes written." and **stop**. Exit code 0.
+
+## Step 4: Execute the plan
+
+<!-- @cap-todo(ac:F-043/AC-3) executeReconciliation walks the lifecycle path for Phase 2 transitions and propagates AC promotions on every 'tested' hop. -->
+<!-- @cap-todo(ac:F-043/AC-4) The audit log is written by executeReconciliation as part of Phase 3. -->
+<!-- @cap-todo(ac:F-043/AC-5) executeReconciliation re-runs detectDrift after writing and includes the count in its result. -->
+
+```bash
+node -e "
+const r = require('./cap/bin/lib/cap-reconcile.cjs');
+const plan = r.planReconciliation(process.cwd());
+const result = r.executeReconciliation(process.cwd(), plan);
+console.log(JSON.stringify(result, null, 2));
+process.exit(result.success ? 0 : 1);
+"
+```
+
+## Step 5: Report results
+
+If success:
+```
+Reconciliation complete.
+  Changes applied: {plan.totalChanges}
+  Post-reconciliation drift: 0
+  Audit log: .cap/memory/reconciliation-2026-04.md
+
+Suggested next:
+  git diff FEATURE-MAP.md   # review the rewritten Feature Map
+  git add FEATURE-MAP.md .cap/memory/reconciliation-2026-04.md
+  git commit -m "fix: reconcile status drift in Feature Map"
+```
+
+If failure:
+```
+Reconciliation failed: {result.error}
+  Pre-drift count: {plan.preDriftCount}
+  Post-drift count: {result.postDriftCount}
+
+Recovery: git checkout -- FEATURE-MAP.md   # revert to pre-reconciliation state
+```
+
+Exit code 0 on success, 1 on failure.
+
+</process>

package/commands/cap/review.md

@@ -0,0 +1,360 @@
+---
+name: cap:review
+description: Two-stage CAP review — Stage 1 verifies AC compliance against FEATURE-MAP.md and @cap-feature tags, Stage 2 evaluates code quality (security, maintainability, complexity, error handling, test coverage). Stage 2 only runs if Stage 1 passes. TRIGGER when a feature is in state `tested` and the user says "review F-XXX / ready to ship / let's review before merge / final check", after `/cap:test` passes, or proactively before any merge to main of CAP-tagged code. --stage2-only skips the AC compliance gate when only quality review is needed. Spawns cap-validator MODE: REVIEW.
+argument-hint: "[--features NAME] [--stage2-only]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<!-- @cap-context CAP v2.0 review command -- orchestrates two-stage code review. Collects test results, reads Feature Map ACs, spawns cap-validator agent. -->
+<!-- @cap-decision Stage 2 only runs if Stage 1 passes -- prevents wasted review cycles on code that does not meet spec. -->
+<!-- @cap-decision Review output goes to .cap/REVIEW.md -- centralized under .cap/ runtime directory. -->
+
+<objective>
+<!-- @cap-todo(ref:AC-58) /cap:review shall invoke the cap-validator agent for two-stage review. -->
+
+Runs two-stage code review:
+1. Stage 1: Check Feature Map AC compliance (does the code implement what was promised?)
+2. Stage 2: Check code quality (security, maintainability, error handling)
+
+Stage 2 only runs if Stage 1 passes.
+
+**Arguments:**
+- `--features NAME` -- scope review to specific Feature Map entries
+- `--stage2-only` -- skip Stage 1, run only code quality review
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+@.cap/SESSION.json
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for:
+- `--features NAME` -- if present, store as `feature_filter`
+- `--stage2-only` -- if present, set `stage2_only = true`
+
+## Step 1: Collect test results
+
+Run existing tests to get current pass/fail state:
+
+```bash
+node --test tests/*.test.cjs 2>&1 | tail -30
+```
+
+Store output as `test_output` and exit code as `test_exit_code`.
+
+## Step 2: Read Feature Map ACs for review scope
+
+<!-- @cap-todo(ref:AC-59) Stage 1: cap-validator shall verify that the implementation satisfies all acceptance criteria listed in the Feature Map entry. -->
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const session = require('./cap/bin/lib/cap-session.cjs');
+const scanner = require('./cap/bin/lib/cap-tag-scanner.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: review — duplicate feature ID detected, AC checklist uses partial map: ' + String(featureMap.parseError.message).trim());
+}
+const s = session.loadSession(process.cwd());
+const tags = scanner.scanDirectory(process.cwd());
+const groups = scanner.groupByFeature(tags);
+
+console.log(JSON.stringify({
+  activeFeature: s.activeFeature,
+  features: featureMap.features.map(f => ({
+    id: f.id, title: f.title, state: f.state,
+    acs: f.acs, files: f.files
+  })),
+  tagGroups: Object.fromEntries(
+    Object.entries(groups).map(([k, v]) => [k, v.map(t => ({ type: t.type, file: t.file, line: t.line, description: t.description }))])
+  )
+}));
+"
+```
+
+**Scope features:**
+- If `feature_filter`: filter to matching IDs
+- Else if active feature: use only that feature
+- Else: use all features with state `tested`
+
+Store as `review_features`.
+
+## Step 3: Spawn cap-validator for Stage 1 (AC compliance)
+
+<!-- @cap-todo(ref:AC-61) cap-validator shall check that all code implementing the feature has appropriate @cap-feature annotations. -->
+
+**Skip Stage 1 if `stage2_only`.**
+
+Spawn `cap-validator` via Task tool:
+
+```
+**MODE: REVIEW**
+
+**STAGE 1: ACCEPTANCE CRITERIA COMPLIANCE**
+
+**Features under review:**
+{For each review_feature:}
+Feature: {feature.id} - {feature.title} [{feature.state}]
+Implementation files: {feature.files.join(', ')}
+Acceptance criteria:
+{For each AC:}
+  {ac.id}: {ac.description} [{ac.status}]
+{End for}
+{End for}
+
+**Tag evidence:**
+{For each feature in tagGroups:}
+  {feature_id}: {tags.length} tags across {unique files}
+{End for}
+
+**Test results:**
+{test_output}
+Test exit code: {test_exit_code}
+
+**Stage 1 checklist:**
+For each AC in each feature under review:
+1. Is there code that implements this AC?
+2. Is the implementing code annotated with @cap-feature(feature:{ID})?
+3. Is there a test that verifies this AC?
+4. Does the test pass?
+
+**Return format:**
+=== STAGE 1 RESULTS ===
+VERDICT: PASS | FAIL
+{For each feature:}
+FEATURE: {id}
+{For each AC:}
+  {ac.id}: PASS | FAIL | PARTIAL -- {evidence or reason}
+{End for}
+{End for}
+MISSING_ANNOTATIONS: [list of files implementing features without @cap-feature tags]
+=== END STAGE 1 RESULTS ===
+```
+
+Parse the Stage 1 results.
+
+**If Stage 1 VERDICT is FAIL and NOT `stage2_only`:**
+
+Display Stage 1 failures and STOP:
+
+```
+cap:review Stage 1 FAILED.
+
+{For each failing AC:}
+  {feature.id}/{ac.id}: FAIL -- {reason}
+{End for}
+
+{If missing annotations:}
+Missing @cap-feature annotations:
+  {For each file: - file}
+{End if}
+
+Stage 2 (code quality) skipped -- fix Stage 1 issues first.
+Run /cap:iterate to address gaps, then re-run /cap:review.
+```
+
+## Step 4: Spawn cap-validator for Stage 2 (code quality)
+
+<!-- @cap-todo(ref:AC-60) Stage 2: cap-validator shall perform code quality review (naming, structure, complexity, test coverage, tag completeness). -->
+
+Spawn `cap-validator` via Task tool:
+
+```
+**MODE: REVIEW** (Stage 2 only)
+
+**STAGE 2: CODE QUALITY REVIEW**
+
+{If not stage2_only:}
+Stage 1 passed. All ACs verified.
+{End if}
+
+**Features under review:**
+{For each review_feature:}
+Feature: {feature.id} - {feature.title}
+Implementation files: {feature.files.join(', ')}
+{End for}
+
+**Review checklist:**
+1. **Naming:** Are function/variable/file names clear and consistent with project conventions?
+2. **Structure:** Is the code organized logically? Are modules appropriately sized?
+3. **Complexity:** Are there functions > 50 lines? Deep nesting > 3 levels? Cyclomatic complexity concerns?
+4. **Error handling:** Are errors handled gracefully? Are edge cases covered?
+5. **Security:** Any hardcoded credentials, SQL injection vectors, XSS risks, path traversal?
+6. **Test coverage:** Are critical paths tested? Are error paths tested?
+7. **Tag completeness:** Does every significant function have @cap-feature annotation?
+8. **Dependencies:** Are there unnecessary imports or tight coupling between modules?
+
+**Return format:**
+=== STAGE 2 RESULTS ===
+VERDICT: PASS | PASS_WITH_NOTES | FAIL
+FINDINGS:
+{numbered list of findings with severity: critical/warning/note}
+TOP_5_ACTIONS:
+1. {actionable improvement}
+2. ...
+=== END STAGE 2 RESULTS ===
+```
+
+Parse Stage 2 results.
+
+## Step 5: Update Feature Map status
+
+<!-- @cap-todo(ref:AC-62) cap-validator shall update the feature state in FEATURE-MAP.md from tested to shipped upon passing both review stages. -->
+
+If both stages pass (or Stage 1 skipped with `stage2_only` and Stage 2 passes):
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const targetIds = {JSON.stringify(target_feature_ids)};
+for (const id of targetIds) {
+  const result = fm.updateFeatureState(process.cwd(), id, 'shipped');
+  console.log(id + ': ' + (result ? 'updated to shipped' : 'state unchanged'));
+}
+"
+```
+
+Write review report:
+
+```bash
+node -e "
+const fs = require('node:fs');
+const path = require('node:path');
+const capDir = path.join(process.cwd(), '.cap');
+if (!fs.existsSync(capDir)) fs.mkdirSync(capDir, { recursive: true });
+// Write review file (content constructed by command layer from parsed results)
+"
+```
+
+Write `.cap/REVIEW.md` using the Write tool with the combined Stage 1 + Stage 2 findings.
+
+Update session:
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:review',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'review-complete'
+});
+"
+```
+
+## Step 6: Generate Manual Testing Checklist
+
+After automated review passes, generate a checklist of things only a human can verify. Derive from the Feature Map ACs and implementation context.
+
+**Categories of manual tests (include all that apply):**
+
+1. **Visual/UX verification** — Does the UI look correct? Is the layout intuitive? Do transitions feel smooth?
+2. **User flow verification** — Can a real user complete the happy path end-to-end? Are error states clear?
+3. **Cross-browser/device** — Does it work on mobile? Different browsers?
+4. **Data verification** — Does real data (not test data) display correctly? Are edge cases handled (empty states, long names, special characters)?
+5. **Permission/access verification** — Can you confirm User A really cannot see User B's data? Try it manually.
+6. **Integration verification** — Do external services (Google Calendar, Zoom, Stripe) actually connect and work?
+7. **Performance perception** — Does it feel fast enough? Any visible loading delays?
+
+**Generate the checklist:**
+
+For each feature under review, analyze the ACs and implementation files to determine which manual tests are needed:
+
+```
+MANUAL TESTING CHECKLIST
+========================
+
+These tests cannot be automated. A human must verify each item
+before the feature is considered production-ready.
+
+Feature: {feature title}
+
+  Visual / UX:
+  [ ] {specific check derived from feature, e.g., "Booking form shows correct time slots for selected date"}
+  [ ] {e.g., "Error message appears when double-booking is attempted"}
+
+  User Flow:
+  [ ] {e.g., "Complete a booking from start to confirmation as a new user"}
+  [ ] {e.g., "Cancel an existing booking and verify calendar is updated"}
+
+  Permissions:
+  [ ] {e.g., "Log in as Berater A — confirm you cannot see Berater B's bookings"}
+  [ ] {e.g., "Log in as Admin — confirm you CAN see all bookings"}
+
+  External Integrations:
+  [ ] {e.g., "Connect Google Calendar — verify new booking appears in calendar"}
+  [ ] {e.g., "Connect Zoom — verify meeting link is generated"}
+
+  Edge Cases:
+  [ ] {e.g., "Book a slot at 23:50 that crosses midnight — verify correct date handling"}
+  [ ] {e.g., "Enter a name with special characters (umlauts, emojis) — verify display"}
+
+Status: [ ] All checks passed  [ ] Issues found (describe below)
+Issues: _______________________________________________
+Verified by: ________________  Date: ________________
+```
+
+Write this checklist to `.cap/MANUAL-TESTS.md` using the Write tool.
+
+Display the checklist to the user with a clear message:
+
+```
+IMPORTANT: The automated review passed, but these manual checks
+are required before shipping to production.
+
+Please work through the checklist above. It takes approximately
+{N} minutes (estimated from item count * 2 min per check).
+
+The checklist is saved at .cap/MANUAL-TESTS.md — share it with
+your team or use it as a sign-off document.
+```
+
+Use AskUserQuestion:
+> "The manual testing checklist has been generated. Would you like to go through it now, or save it for later?"
+> Options: "Go through now" / "Save for later" / "Skip manual tests"
+
+If "Go through now": Walk through each item with the user, asking them to confirm each check.
+If "Save for later": Remind them: ".cap/MANUAL-TESTS.md keeps the manual checklist; revisit it with `/cap:status` or run the checks directly when ready."
+If "Skip": Warn: "Manual tests skipped. Feature will be marked as shipped but .cap/MANUAL-TESTS.md remains open."
+
+## Step 7: Final report
+
+```
+cap:review complete.
+
+Stage 1 (AC compliance):  {PASS or FAIL or SKIPPED}
+Stage 2 (Code quality):   {PASS or PASS_WITH_NOTES or FAIL}
+Stage 3 (Manual tests):   {PENDING — N items to verify}
+
+{If both automated stages pass:}
+Feature state updated: {feature_ids} -> shipped
+Review report: .cap/REVIEW.md
+Manual tests:  .cap/MANUAL-TESTS.md
+
+Top 5 actions:
+{top_5_actions}
+{End if}
+
+{If stage 2 has notes:}
+Review passed with notes. See .cap/REVIEW.md for details.
+{End if}
+
+REMINDER: {N} manual test items pending in .cap/MANUAL-TESTS.md
+```
+
+</process>

package/commands/cap/save.md

@@ -0,0 +1,72 @@
+---
+name: cap:save
+description: Save current session context to a snapshot file via the cap-historian agent. Cross-session continuity without compression losses.
+argument-hint: "[name] [--unassigned] [--platform=<topic>] [--feature=<F-ID>] [--fork=<parent-snapshot>]"
+allowed-tools:
+  - Task
+  - Read
+  - Bash
+---
+
+<!-- @cap-context Thin orchestrator. Real lifecycle work lives in agents/cap-historian.md (modes: SAVE / CONTINUE / FORK). Mirrors the test.md→cap-validator wrapper shape. -->
+<!-- @cap-decision /cap:save delegates to cap-historian via Task() with MODE: SAVE prefix. Backwards-compat: positional [name], --unassigned, --platform=<topic> preserved verbatim. New: --feature=<F-ID> is forwarded; --fork=<parent> redirects to MODE: FORK. -->
+<!-- @cap-feature(feature:F-079) Snapshot-Linkage to Features and Platform — frontmatter `feature:` / `platform:` fields wire snapshots to F-076 per-feature / F-078 platform memory layers. cap-historian reuses cap-snapshot-linkage.cjs; soft-warn semantics inherited. -->
+
+<objective>
+Spawn `cap-historian` to capture current session context as a `.cap/snapshots/<name>.md` snapshot with Frontmatter linkage and a JSONL index entry. The snapshot can later be loaded via `/cap:continue`.
+
+**Arguments (backwards-compatible):**
+- `[name]` — optional snapshot name (default: auto-generated from active feature + date, else `YYYY-MM-DD-HHMM`).
+- `--unassigned` — save without feature/platform linkage (soft-warn on stderr).
+- `--platform=<topic>` — link to platform topic (kebab-case). Mutually exclusive with `--unassigned`.
+- `--feature=<F-ID>` — explicit feature linkage override (default: `SESSION.json.activeFeature`).
+- `--fork=<parent-snapshot>` — branch off a parent snapshot ("what if X instead"). Routes to MODE: FORK; parent is never mutated.
+</objective>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Detect mode
+
+If `$ARGUMENTS` contains `--fork=<parent>`, mode is **FORK**. Otherwise mode is **SAVE**.
+
+## Step 2: Spawn cap-historian
+
+Invoke `cap-historian` via Task tool with the appropriate mode prefix:
+
+```
+**MODE: SAVE**          (or **MODE: FORK** if --fork= present)
+
+$ARGUMENTS
+
+Capture current session context. Reuse cap-snapshot-linkage.cjs for linkage
+resolution and cap-session-extract.cjs for source-JSONL discovery. Write snapshot
+to .cap/snapshots/<name>.md (refuse to overwrite — append -2/-3 if needed) and
+append an event line to .cap/snapshots/index.jsonl.
+
+Return the structured `=== HISTORIAN SAVE RESULTS ===` (or FORK) block verbatim.
+```
+
+Wait for cap-historian to complete. Parse the structured results block.
+
+## Step 3: Confirm to user
+
+After the agent returns, surface the outcome in the legacy-compatible shape:
+
+```
+Snapshot saved to .cap/snapshots/<name>.md
+Linkage: feature=<F-NNN> | platform=<topic> | unassigned
+Files captured: <N>
+
+To continue in a fresh session: /cap:continue <name>
+```
+
+For FORK mode, also include `Forked from: <parent>`.
+
+**Note:** The snapshot is auto-wired into per-feature/platform memory by the
+`hooks/cap-memory.js` pipeline on the next run (F-079/AC-4) — no manual step.
+
+</process>