context-planning 0.7.0

package/bin/cp.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * cp — context-planning CLI entry.
+ *
+ * v0.6: thin dispatcher. Each command lives in bin/commands/<name>.js as
+ * a module exporting { name, run(args) }. The registry in
+ * bin/commands/index.js maps subcommand names to their handlers.
+ *
+ * To add a new command:
+ *   1. Drop bin/commands/<name>.js exporting { name, run }.
+ *   2. Add an entry to bin/commands/index.js.
+ *   3. (Optional) Update bin/commands/_usage.js if it should appear in `cp help`.
+ *
+ * To see the full subcommand list, run: `cp help`.
+ */
+
+const usage = require('./commands/_usage');
+const registry = require('./commands');
+const { normalizeArgv } = require('./commands/_helpers');
+
+function main(argv) {
+  const normalized = normalizeArgv(argv.slice(2));
+  const [cmd, ...rest] = normalized;
+
+  // Registry-first dispatch.
+  if (cmd && Object.prototype.hasOwnProperty.call(registry, cmd)) {
+    return registry[cmd].run(rest);
+  }
+
+  // Built-in aliases not in the registry.
+  switch (cmd) {
+    case '--version':
+    case '-v':
+      return registry.version.run();
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      return usage();
+    default:
+      console.error(`unknown command: ${cmd}`);
+      usage();
+      process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main(process.argv);
+}
+
+// Public exports — kept for back-compat with tests and external require()s.
+module.exports = { normalizeArgv, main, registry };

package/commands/cp/capture.md

@@ -0,0 +1,107 @@
+---
+description: Triage open inbox items — route each to a quick task, phase note, seed, or discard
+---
+
+# /cp-capture — inbox triage
+
+`/cp-capture` walks the user through the open `.planning/INBOX.md` items
+one at a time and routes each to its right destination. cp owns the inbox
+state; the **workflow provider** (default: Superpowers) does the actual
+implementation work for items that become quick tasks or phase additions.
+
+`/cp-capture` is the COMPANION to `cp capture "..."`. The CLI command
+appends a free-form line to `INBOX.md`; this slash command processes the
+backlog interactively.
+
+---
+
+## Behaviour
+
+You are the orchestrator. Do this in order:
+
+1. **Inspect the inbox.**
+   Run `cp inbox --json` and parse it. If `open` is empty, tell the user
+   "Inbox is empty — nothing to triage." and stop. Otherwise show a brief
+   summary: `N open items, M previously triaged. Walk through the open
+   items one at a time?` and confirm.
+
+2. **For each open item (in `open` order):**
+
+   a. Display the item to the user (timestamp + text).
+
+   b. Propose a classification. Use one of these destination tags:
+
+      | Tag                          | When to use                                                              | Action |
+      |------------------------------|---------------------------------------------------------------------------|--------|
+      | `quick:<slug>`               | Small bug / fix / chore. Single PR, no planning.                          | Defer to the workflow provider's quick-task skill. |
+      | `phase:<NN-name>`            | Goes into an existing phase as a sub-task or PLAN.md update.              | Append the item text to that phase's PLAN.md `## Notes` (or appropriate section). |
+      | `phase-seed:<short-name>`    | Future phase — write it down for the next roadmap cut.                    | Append to `.planning/STATE.md` `### Pending Todos`. |
+      | `milestone-seed:<name>`      | Bigger than a phase — surfaces a future milestone.                        | Append to `.planning/STATE.md` `## Deferred Items`. |
+      | `note:<where>`               | Standalone reference info (a decision, an observation, a constraint).     | Append to `.planning/STATE.md` `## Accumulated Context > ### Decisions` (or where the user picks). |
+      | `discard`                    | Noise. Tracking complete; nothing to do.                                  | No side-effect beyond marking triaged. |
+
+      Propose one classification with a one-sentence rationale. Always ask
+      the user to confirm or override (use AskUserQuestion when available,
+      otherwise plain text). The user can also pick **skip** (leave open) or
+      **edit** (rewrite the item before classifying).
+
+   c. **Execute the routing action.**
+      - For `quick:*`: hand off to the workflow provider's quick-task
+        primitive (Superpowers's `/quick`, GSD's `/gsd-quick`, etc.). Pass
+        the item text as the task description.
+      - For `phase:*`: read the matching phase's `PLAN.md` (long-form or
+        short-form), append a bullet under `## Notes` with the item text
+        prefixed by `> inbox [<ts>]:`. Use `cp tick`'s file convention. Do
+        NOT auto-tick anything.
+      - For `phase-seed:*` / `milestone-seed:*` / `note:*`: read
+        `.planning/STATE.md`, append a bullet to the right section
+        (preserve all other content verbatim), write it back.
+      - For `discard`: no extra file write.
+
+   d. **Mark triaged.** Once the routing action succeeds (or for `discard`,
+      immediately), run:
+      ```
+      cp inbox --tick <N> --note "<destination-tag>"
+      ```
+      where `<N>` is the open item's index from step 2a. This moves the
+      item from `Open` to `Triaged` in `INBOX.md` and auto-commits.
+
+3. **Summary.** After the loop, run `cp inbox --all` and show the user
+   what was triaged. End with: "Inbox triaged. `M` items moved, `K` left
+   open."
+
+---
+
+## Rules
+
+- **Always confirm classifications with the user.** Never silently route an
+  item — these are the user's notes; they get final say on what each one means.
+- **One item at a time.** Don't batch-classify; the user might catch a bad
+  routing decision mid-loop and want to stop.
+- **Atomic commits.** `cp inbox --tick` commits each triage on its own. If
+  you also wrote to a phase PLAN or STATE.md, those go in a separate commit
+  via your normal file-edit flow — don't try to bundle the inbox tick with
+  unrelated file edits.
+- **Idempotent.** If the user re-runs `/cp-capture` mid-session, items
+  already in `Triaged` should not be revisited; only items still in `Open`.
+
+## Provider integration
+
+The Mappings table assumes the workflow provider is one of:
+- **Superpowers** (default): `/quick` for quick tasks; for phase edits and
+  state edits, use your own filesystem tools.
+- **GSD**: `/gsd-quick` or `/gsd-capture` for quick tasks; otherwise as above.
+- **None**: cp's CLI still works (`cp capture`, `cp inbox --tick`); you
+  perform routing edits with your harness's filesystem tools.
+
+Read `.planning/config.json` `cp.workflow_provider` to know which is active.
+
+## Don't
+
+- Don't write to `INBOX.md` directly — always go through `cp inbox --tick`.
+- Don't strip the original item text when writing to a phase / state file
+  — preserve `> inbox [<ts>]: <text>` so the provenance stays clear.
+- Don't classify the same item twice in one run.
+- Don't auto-create new phases or milestones from inbox items. Surface them
+  as `phase-seed:*` / `milestone-seed:*` and let `/cp-new-milestone` or
+  `/cp-plan-phase` pick them up later.

package/commands/cp/complete-milestone.md

@@ -0,0 +1,166 @@
+---
+name: cp-complete-milestone
+description: Close out a milestone — verify all phases done, roll up SUMMARYs, collapse in ROADMAP, archive to MILESTONES.md.
+argument-hint: "<milestone name, optional — defaults to current>"
+requires: []
+---
+
+# /cp-complete-milestone
+
+You are running `cp-complete-milestone`. A milestone has finished all its
+phases; your job is to archive it cleanly so the project state shows the
+milestone shipped and the next milestone has a clean slate.
+
+**This command is destructive in the GSD-compatible way:** it COLLAPSES the
+shipped phases inside `<details>` in ROADMAP.md (does NOT delete them),
+APPENDS a digest to MILESTONES.md, and DELETES `.planning/MILESTONE-CONTEXT.md`
+(since GSD treats this file as transient per-milestone).
+
+## TL;DR — use the `cp` CLI wrapper
+
+The entire 7-step close-out is wrapped by **`cp complete-milestone`**. The
+wrapper handles verification, digest aggregation, ROADMAP collapse,
+MILESTONE-CONTEXT deletion, STATE reset, AND the atomic git commit.
+
+**Recommended flow:**
+
+```bash
+# 1. Confirm what's about to change (no writes)
+cp complete-milestone --dry-run "$MILESTONE_NAME"
+# (omit name to use the current in-progress milestone)
+
+# 2. Show the user the action plan and the rendered digest preview
+#    (Get the rendered digest from MILESTONES.md after the dry-run? No —
+#     dry-run doesn't write. Use --json to get the agg object and render
+#     a preview inline, OR just describe the actions list and run real.)
+
+# 3. Run real
+cp complete-milestone "$MILESTONE_NAME"
+
+# 4. Confirm
+cp status        # should now show "(none in-progress)" for milestone
+```
+
+**Exit-code contract:**
+- `0` → milestone successfully closed (or dry-run produced an action list)
+- `1` → blocking error (incomplete phases, missing SUMMARYs, milestone not found, etc.)
+
+If the wrapper fails, read the structured error and tell the user exactly
+which phase / plan / SUMMARY is missing.
+
+## Step 1 — Resolve the milestone name
+
+- If `$ARGUMENTS` is provided, use it as the milestone name.
+- Else, read `.planning/MILESTONE-CONTEXT.md` and pull its name.
+- Else, let `cp complete-milestone` (with no arg) detect the current
+  in-progress milestone via `cp status`.
+- If `cp` returns `reason: no-current-milestone`, stop and ask the user.
+
+## Step 2 — Dry-run preview
+
+```bash
+cp complete-milestone --dry-run [<milestone name>]
+```
+
+The CLI prints:
+```
+Milestone:   v0.1 MVP
+Phases:      1, 2
+Subsystems:  storage, search
+Files:       5 created, 1 modified
+
+Actions (dry-run):
+  ✓ write  .planning\MILESTONES.md
+  ✓ write  .planning\ROADMAP.md
+  ✗ delete .planning\MILESTONE-CONTEXT.md
+  ✓ write  .planning\STATE.md
+```
+
+If `--dry-run` exits non-zero, the milestone isn't complete — `cp` lists
+which phases still have unticked plans or missing SUMMARYs. Tell the user
+and stop; suggest `/cp-execute-phase {N}` for any incomplete phase.
+
+## Step 3 — Show the user; ask for sign-off
+
+Present the action list + a short summary (which milestone, how many
+phases, what subsystems). Ask for explicit confirmation. **Do not auto-run
+the real `cp complete-milestone` without it.**
+
+## Step 4 — Run for real
+
+```bash
+cp complete-milestone [<milestone name>]
+```
+
+The CLI does everything atomically:
+1. Verifies every phase has all plans `[x]` and a SUMMARY on disk.
+2. Reads + aggregates every SUMMARY frontmatter (union-and-dedupe of
+   `subsystem`, `tags`, `requires/provides/affects`, `tech-stack`,
+   `key-files`, `key-decisions`, `patterns-established`,
+   `requirements-completed`).
+3. Renders the milestone digest (heading, requirements delivered,
+   subsystems touched, key decisions/patterns with phase tags, files
+   created/modified, phase-summary links).
+4. Appends the digest to `.planning/MILESTONES.md` (preserves prior
+   content; adds blank line before the new entry).
+5. Collapses the milestone in `.planning/ROADMAP.md` — wraps the
+   `### {emoji} {name} (In Progress)` heading and every `### Phase N: ...`
+   block inside a single `<details>` element with
+   `<summary>✅ {name} (Phases X-Y) — SHIPPED {today}</summary>`.
+   Preserves every phase block byte-for-byte for GSD round-tripping.
+6. Deletes `.planning/MILESTONE-CONTEXT.md` if present.
+7. Resets `.planning/STATE.md` Current Position to `Idle`, Last activity
+   to `shipped {milestone}`, Session Continuity Stopped at →
+   `shipped {milestone}`.
+8. Runs `git add -A && git commit -m "cp: /cp-complete-milestone {name}"`
+   (unless `--no-commit` is passed).
+
+The CLI prints the actions list and the commit hash.
+
+## Step 5 — Report
+
+After the wrapper completes, print:
+
+```
+✓ Milestone "{name}" shipped.
+  Phases:        X-Y ({plan count} plans)
+  Archived to:   .planning/MILESTONES.md
+  Roadmap:       collapsed inside <details>
+  Cleared:       .planning/MILESTONE-CONTEXT.md
+  Committed:     {short hash}
+
+Next:
+  /cp-new-milestone "{suggested next}"   # start the next milestone
+  cp status                              # confirm the new "you are here"
+```
+
+## Fallback — when `cp` CLI is not available
+
+If `cp` is not on PATH (e.g. the user installed cp into a harness without
+the Node CLI), drive the same flow by calling the lib functions directly.
+**Beware of the lib contracts** — these were the bugs the wrapper hides:
+
+- `milestone.aggregateSummaries(summaries)` takes `[{fm, phaseNum}]`
+  — NOT raw strings. Use `milestone.readSummaries(phaseNums, root)` to
+  build that shape.
+- `milestone.collapseMilestoneInRoadmap(content, name, isoDate)` returns
+  `{content, changed, reason?}`. Always use `.content`.
+- `milestone.renderDigest(name, isoDate, phaseNums, agg, phaseNames)` —
+  positional args, not an options object.
+- SUMMARY frontmatter uses **kebab-case**: `subsystem` (singular!),
+  `key-files.{created,modified}`, `key-decisions`,
+  `patterns-established`, `requirements-completed`, `tech-stack.added`.
+- `state.updatePosition(content, opts)` takes `content`, NOT a path.
+- Append to `MILESTONES.md` AFTER all other edits succeed, so a mid-flight
+  failure leaves the archive intact.
+
+## Notes
+
+- **GSD-compat hard contract:** do NOT change phase numbering, do NOT
+  remove any phase block, do NOT alter frontmatter inside SUMMARY/PLAN
+  files. Everything stays parseable by GSD's `gsd-complete-milestone`.
+- This command is the only one in cp that DELETES a file
+  (`MILESTONE-CONTEXT.md`). Show the user the dry-run actions list before
+  running real.
+- If the user wants to undo, the atomic commit makes `git revert HEAD` a
+  one-shot rollback.

package/commands/cp/execute-phase.md

@@ -0,0 +1,220 @@
+---
+name: cp-execute-phase
+description: Execute a planned phase by handing PLAN.md to the provider's execute skill, then record SUMMARY.md and update STATE.md/ROADMAP.md.
+argument-hint: "<phase number>"
+requires: []
+---
+
+# /cp-execute-phase
+
+You are running `cp-execute-phase`. PLAN.md exists; your job is to drive it
+through to a green build and atomic commits via the configured workflow
+provider, then record the result back into the state layer.
+
+**The state-layer bookkeeping is wrapped by `cp tick` and
+`cp write-summary`** — you don't need to touch `lib/roadmap.setPlanDone` or
+write SUMMARY files by hand. Use the wrappers; they validate frontmatter,
+keep ROADMAP + phase PLAN.md in sync, and commit atomically.
+
+## Step 1 — Resolve the phase + plan
+
+- `PHASE_NUM` = `$ARGUMENTS` (sanitize as in cp-plan-phase).
+- Run `cp status --json` to confirm the milestone, current phase, and the
+  **next pending plan** (`.nextPlan.planId`). If `nextPlan` is null, all
+  plans in this phase are done — suggest `/cp-plan-phase {PHASE_NUM+1}` or
+  `/cp-complete-milestone`.
+- If `cp status` reports a *different* phase than `PHASE_NUM`, ask the user
+  whether to switch.
+- Read the phase's `PLAN.md` and each `{NN-MM}-PLAN.md` per-plan file to
+  pull tasks + acceptance criteria. Read the milestone's ROADMAP block for
+  Goal / Success Criteria / Requirements.
+
+## Step 2 — Set the start markers
+
+Update PLAN.md frontmatter for the current plan: add `status: in-progress`,
+`started: {ISO timestamp}`. Update STATE.md is OPTIONAL here — the wrappers
+in steps 6-7 will reset it correctly on completion.
+
+If `cp.behavior.atomic_commits` is true, commit:
+```
+cp: start {phase}-{plan} execution
+```
+
+## Step 3 — Resolve the execute skill
+
+```bash
+cp doctor
+```
+
+Find the resolved `execute` role under "Roles -> resolved skill":
+
+- Default: Superpowers' `subagent-driven-development` — fires one fresh
+  subagent per task with two-stage review.
+- Alternative: Superpowers' `executing-plans` (simpler batch execution).
+- If the resolved provider is `manual`: walk through each task one at a
+  time, confirming intent, doing the work, running verification, committing.
+
+## Step 4 — Delegate execution
+
+Invoke the execute skill with:
+- The current plan's `{phase}-{plan}-PLAN.md` as the work plan
+- The phase Goal, Success Criteria, and Requirements as the must-haves
+- An instruction: each task gets an atomic commit using Conventional
+  Commits style (feat/fix/refactor/test/docs), prefixed with
+  `({phase}-{plan}) ` (e.g. `feat(01-02): add JWT verifier`).
+
+The execute skill OWNS what happens during the work — TDD, verification,
+code review between tasks, deviations. Do not intervene unless it returns
+control.
+
+## Step 4.5 — Append to REVIEW-LOG.md (v0.7)
+
+After EACH review cycle returned by SP `subagent-driven-development`
+(spec-compliance OR code-quality), append one block to
+`.planning/phases/{phase-dir}/REVIEW-LOG.md` BEFORE the
+`<!-- REVIEW-LOG-ENTRIES-BELOW -->` marker is irrelevant — APPEND after
+the marker:
+
+```
+## {{DATE}} {{TIME}} — Plan {{PLAN-ID}} Task {{TASK-N}} — {{REVIEWER-ROLE}}
+
+**Verdict:** {approved | rejected | needs-revision}
+
+**Findings:**
+
+- {bullet list of substantive findings}
+
+**Resolution:**
+
+{what changed; commit SHA if applied; "N/A — accepted on first pass" allowed}
+
+---
+```
+
+Skip empty findings on clean approvals (use "Resolution: approved on
+first pass" and omit findings bullet list).
+
+If the file does not exist (older milestones), create it from
+`templates/REVIEW-LOG.md` with substituted frontmatter first.
+
+The cp aggregator counts these entries (via `aggregateSummaries`
+`reviewCount`) when rolling up the milestone summary.
+
+## Step 5 — Verify Success Criteria
+
+When the execute skill reports the plan complete:
+
+1. Verify Success Criteria from ROADMAP.md actually hold. (Ask the
+   provider's `verify` skill, e.g. `verification-before-completion`, or
+   do an inline check.)
+2. If any criterion fails: **do not** tick or write SUMMARY. Tell the user
+   and pause for instructions.
+
+## Step 6 — Write SUMMARY with `cp write-summary`
+
+Collect the per-plan facts into a JSON blob, then call:
+
+```bash
+cp write-summary {phase}-{plan} --from /tmp/summary-{phase}-{plan}.json [--body /tmp/summary-{phase}-{plan}-body.md]
+```
+
+The CLI:
+- Writes to `.planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md`
+  (correct GSD-compatible filename — NO slug in the middle).
+- Validates and **normalises both kebab-case AND snake_case** field names
+  (`subsystem`/`subsystems`, `key-files.created`/`files_created`,
+  `requirements-completed`/`requirements_completed`,
+  `key-decisions`/`key_decisions`, etc.).
+- Backfills `phase`, `plan`, and `completed` if absent.
+
+Required JSON fields (kebab-case canonical names — snake_case also accepted):
+
+```json
+{
+  "subsystem": "<pick one: auth, payments, ui, api, database, infra, testing, docs, tooling — ask user if ambiguous>",
+  "tags":      ["jwt", "prisma", "react"],
+  "requires":  ["..."],
+  "provides":  ["..."],
+  "affects":   ["src/..."],
+  "tech-stack": { "added": ["..."], "patterns": ["..."] },
+  "key-files":  { "created": ["..."], "modified": ["..."] },
+  "key-decisions":         ["decision 1", "decision 2"],
+  "patterns-established":  ["pattern 1"],
+  "requirements-completed":["REQ-04"],
+  "duration": "32min"
+}
+```
+
+The body markdown file should contain the human-readable
+**Accomplishments / Task Commits / Files Created / Decisions Made /
+Deviations / Issues / Next Phase Readiness** sections — derive from
+`git log --oneline {start_sha}..HEAD` and `git diff --name-only`.
+
+After `cp write-summary` succeeds, update the per-plan PLAN.md frontmatter:
+`status: complete`, `completed: {ISO ts}`.
+
+## Step 7 — Tick the plan with `cp tick`
+
+```bash
+cp tick {phase}-{plan}
+```
+
+The CLI:
+- Marks the plan `[x]` in BOTH `.planning/ROADMAP.md` AND
+  `.planning/phases/{phase-dir}/PLAN.md` (one command, not two).
+- Idempotent — no-op if already ticked.
+- Commits as `cp: tick plan {phase}-{plan}` (pass `--no-commit` to skip).
+
+## Step 8 — Status check + next step
+
+```bash
+cp status
+```
+
+If `cp status` shows another pending plan in the same phase:
+```
+Next:     /cp-execute-phase {N}    # continues with next plan
+```
+
+If `nextPlan` is null for this phase but other phases remain pending:
+```
+Next:     /cp-plan-phase {N+1}     # if next phase has no PLAN yet
+          /cp-execute-phase {N+1}  # if it does
+```
+
+If all plans across all phases are done:
+```
+Next:     /cp-complete-milestone   # ship it!
+```
+
+## Step 9 — Report
+
+```
+✓ Plan {phase}-{plan} complete: {phase name}
+  Duration: {X} min, {tasks} tasks, {files} files
+  SUMMARY:  .planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md
+  Next:     {derived from `cp status` in Step 8}
+```
+
+## Fallback — when `cp` CLI is not available
+
+If `cp` is not on PATH, write the SUMMARY manually using the exact
+filename `{phase}-{plan}-SUMMARY.md` (NOT `{phase}-{plan}-{slug}-SUMMARY.md`)
+and tick the plan in BOTH `ROADMAP.md` AND the phase `PLAN.md` using
+`lib/roadmap.setPlanDone(content, '{phase}-{plan}', true)`. Frontmatter
+**must** use kebab-case canonical names (`subsystem` singular,
+`key-files.created`, etc.) for `aggregateSummaries` to pick them up at
+milestone close.
+
+## Notes
+
+- Never write SUMMARY.md if Success Criteria aren't met.
+- If the execute skill pauses mid-task, leave PLAN.md `status: in-progress`
+  so the user can resume by re-invoking `/cp-execute-phase {N}`.
+- Don't re-implement the execute skill. Delegate. Your job is the state
+  layer + bookkeeping.
+- Filenames are GSD-compatible: `{phase}-{plan}-PLAN.md` and
+  `{phase}-{plan}-SUMMARY.md`. The `cp` wrappers enforce this.
+- Frontmatter is the canonical cross-tool interop surface — GSD's
+  gsd-planner relies on these fields, so populate them faithfully. The
+  `cp write-summary` wrapper validates this.