claude-code-pilot 3.1.1 → 3.3.0

package/src/pilot/workflows/ingest-docs.md

@@ -0,0 +1,328 @@
+# Ingest Docs Workflow
+
+Scan a repo for mixed planning documents (ADR, PRD, SPEC, DOC), synthesize them into a consolidated context, and bootstrap or merge into `.planning/`.
+
+- `[path]` — optional target directory to scan (defaults to repo root)
+- `--mode new|merge` — override auto-detect (defaults: `new` if `.planning/` absent, `merge` if present)
+- `--manifest <file>` — YAML file listing `{path, type, precedence?}` per doc; overrides heuristic classification
+- `--resolve auto|interactive` — conflict resolution (v1: only `auto` is supported; `interactive` is reserved)
+
+---
+
+<step name="banner">
+
+Display the stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► INGEST DOCS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</step>
+
+<step name="parse_arguments">
+
+Parse `$ARGUMENTS`:
+
+- First positional token (if not a flag) → `SCAN_PATH` (default: `.`)
+- `--mode new|merge` → `MODE` (default: auto-detect)
+- `--manifest <file>` → `MANIFEST_PATH` (optional)
+- `--resolve auto|interactive` → `RESOLVE_MODE` (default: `auto`; reject `interactive` in v1 with message "interactive resolution is planned for a future release")
+
+**Validate paths:**
+
+```bash
+case "{SCAN_PATH}" in *..*) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;; esac
+test -d "{SCAN_PATH}" || echo "PATH_NOT_FOUND"
+if [ -n "{MANIFEST_PATH}" ]; then
+  case "{MANIFEST_PATH}" in *..*) echo "SECURITY_ERROR: manifest path contains traversal"; exit 1 ;; esac
+  test -f "{MANIFEST_PATH}" || echo "MANIFEST_NOT_FOUND"
+fi
+```
+
+**Containment (required):** After resolving `SCAN_PATH` and `MANIFEST_PATH` relative to the repo root, canonicalize each with `realpath` (or platform equivalent) and assert the result is under `realpath("$REPO_ROOT")`. Reject absolute paths outside the repo (e.g. `/tmp`, `C:\Windows`) even when they do not contain `..`.
+
+If `PATH_NOT_FOUND` or `MANIFEST_NOT_FOUND`: display error and exit.
+
+</step>
+
+<step name="init_and_mode_detect">
+
+Run the init query:
+
+```bash
+INIT=$(gsd-sdk query init.ingest-docs)
+```
+
+Parse `project_exists`, `planning_exists`, `has_git`, `project_path` from INIT.
+
+**Auto-detect MODE** if not set:
+- `planning_exists: true` → `MODE=merge`
+- `planning_exists: false` → `MODE=new`
+
+If user passed `--mode new` but `.planning/` already exists: display warning and require explicit confirm via `AskUserQuestion` (approve-revise-abort from `references/gate-prompts.md`) before overwriting.
+
+If `has_git: false` and `MODE=new`: initialize git:
+```bash
+git init
+```
+
+**Detect runtime** using the same pattern as `new-project.md`:
+- execution_context path `/.codex/` → `RUNTIME=codex`
+- `/.gemini/` → `RUNTIME=gemini`
+- `/.opencode/` or `/.config/opencode/` → `RUNTIME=opencode`
+- else → `RUNTIME=claude`
+
+Fall back to env vars (`CODEX_HOME`, `GEMINI_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`) if execution_context is unavailable.
+
+</step>
+
+<step name="discover_docs">
+
+Build the doc list from three sources, in order:
+
+**1. Manifest (if provided)** — authoritative:
+
+Read `MANIFEST_PATH`. Expected YAML shape:
+
+```yaml
+docs:
+  - path: docs/adr/0001-db.md
+    type: ADR
+    precedence: 0   # optional, lower = higher precedence
+  - path: docs/prd/auth.md
+    type: PRD
+```
+
+Each entry provides `path` (required, relative to repo root) + `type` (required, one of ADR|PRD|SPEC|DOC) + `precedence` (optional integer).
+
+**2. Directory conventions** (skipped when manifest is provided):
+
+```bash
+# ADRs
+find {SCAN_PATH} -type f \( -path '*/adr/*' -o -path '*/adrs/*' -o -name 'ADR-*.md' -o -regex '.*/[0-9]\{4\}-.*\.md' \) 2>/dev/null
+
+# PRDs
+find {SCAN_PATH} -type f \( -path '*/prd/*' -o -path '*/prds/*' -o -name 'PRD-*.md' \) 2>/dev/null
+
+# SPECs / RFCs
+find {SCAN_PATH} -type f \( -path '*/spec/*' -o -path '*/specs/*' -o -path '*/rfc/*' -o -path '*/rfcs/*' -o -name 'SPEC-*.md' -o -name 'RFC-*.md' \) 2>/dev/null
+
+# Generic docs (fall-through candidates)
+find {SCAN_PATH} -type f -path '*/docs/*' -name '*.md' 2>/dev/null
+```
+
+De-duplicate the union (a file matched by multiple patterns is one doc).
+
+**3. Content heuristics** (run during classification, not here) — the classifier handles frontmatter `type:` and H1 inspection for docs that didn't match a convention.
+
+**Cap:** hard limit of 50 docs per invocation (documented v1 constraint). If the discovered set exceeds 50:
+
+```
+GSD > Discovered {N} docs, which exceeds the v1 cap of 50.
+      Use --manifest to narrow the set to ≤ 50 files, or run
+      /ccp:ingest-docs again with a narrower <path>.
+```
+
+Exit without proceeding.
+
+**Display discovered set** and request approval (see `references/gate-prompts.md` — `yes-no-pick` pattern works; or `approve-revise-abort`):
+
+```
+Discovered {N} documents:
+  {N} ADR | {N} PRD | {N} SPEC | {N} DOC | {N} unclassified
+
+  docs/adr/0001-architecture.md       [ADR]    (from manifest|directory|heuristic)
+  docs/adr/0002-database.md           [ADR]    (directory)
+  docs/prd/auth.md                    [PRD]    (manifest)
+  ...
+```
+
+**Text mode:** apply the same `--text`/`text_mode` rule as other workflows — replace `AskUserQuestion` with a numbered list.
+
+Use `AskUserQuestion` (approve-revise-abort):
+- question: "Proceed with classification of these {N} documents?"
+- header: "Approve?"
+- options: Approve | Revise | Abort
+
+On Abort: exit cleanly with "Ingest cancelled."
+On Revise: exit with guidance to re-run with `--manifest` or a narrower path.
+
+</step>
+
+<step name="classify_parallel">
+
+Create staging directory:
+
+```bash
+mkdir -p .planning/intel/classifications/
+```
+
+For each discovered doc, spawn `gsd-doc-classifier` in parallel. In Claude Code, issue all Task calls in a single message with multiple tool uses so the harness runs them concurrently. For Copilot / sequential runtimes, fall back to sequential dispatch.
+
+Per-spawn prompt fields:
+- `FILEPATH` — absolute path to the doc
+- `OUTPUT_DIR` — `.planning/intel/classifications/`
+- `MANIFEST_TYPE` — the type from the manifest if present, else omit
+- `MANIFEST_PRECEDENCE` — the precedence integer from the manifest if present, else omit
+- `<required_reading>` — `agents/ccp:doc-classifier.md` (the agent definition itself)
+
+Collect the one-line confirmations from each classifier. If any classifier errors out, surface the error and abort without touching `.planning/` further.
+
+</step>
+
+<step name="synthesize">
+
+Spawn `gsd-doc-synthesizer` once:
+
+```
+Task({
+  subagent_type: "gsd-doc-synthesizer",
+  prompt: "
+    CLASSIFICATIONS_DIR: .planning/intel/classifications/
+    INTEL_DIR: .planning/intel/
+    CONFLICTS_PATH: .planning/INGEST-CONFLICTS.md
+    MODE: {MODE}
+    EXISTING_CONTEXT: {paths to existing .planning files if MODE=merge, else empty}
+    PRECEDENCE: {array from manifest defaults or default ['ADR','SPEC','PRD','DOC']}
+
+    <required_reading>
+    - agents/ccp:doc-synthesizer.md
+    - get-shit-done/references/doc-conflict-engine.md
+    </required_reading>
+  "
+})
+```
+
+The synthesizer writes:
+- `.planning/intel/decisions.md`, `.planning/intel/requirements.md`, `.planning/intel/constraints.md`, `.planning/intel/context.md`
+- `.planning/intel/SYNTHESIS.md`
+- `.planning/INGEST-CONFLICTS.md`
+
+</step>
+
+<step name="conflict_gate">
+
+Read `.planning/INGEST-CONFLICTS.md`. Count entries in each bucket (the synthesizer always writes the three-bucket header; parse the `### BLOCKERS ({N})`, `### WARNINGS ({N})`, `### INFO ({N})` lines).
+
+Apply the safety semantics from `references/doc-conflict-engine.md`. Operation noun: `ingest`.
+
+**If BLOCKERS > 0:**
+
+Render the report to the user, then display:
+
+```
+GSD > BLOCKED: {N} blockers must be resolved before ingest can proceed.
+```
+
+Exit WITHOUT writing PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md. The staging intel files remain for inspection. The safety gate holds — no destination files are written when blockers exist.
+
+**If WARNINGS > 0 and BLOCKERS = 0:**
+
+Render the report, then ask via AskUserQuestion (approve-revise-abort):
+- question: "Review the competing variants above. Resolve manually and proceed, or abort?"
+- header: "Approve?"
+- options: Approve | Abort
+
+On Abort: exit cleanly with "Ingest cancelled. Staged intel preserved at `.planning/intel/`."
+
+**If BLOCKERS = 0 and WARNINGS = 0:**
+
+Proceed to routing silently, or optionally display `GSD > No conflicts. Auto-resolved: {N}.`
+
+</step>
+
+<step name="route_new_mode">
+
+**Applies only when MODE=new.**
+
+Audit PROJECT.md field requirements that `gsd-roadmapper` expects. For fields derivable from `.planning/intel/SYNTHESIS.md` (project scope, goals/non-goals, constraints, locked decisions), synthesize from the intel. For fields NOT derivable (project name, developer-facing success metric, target runtime), prompt via `AskUserQuestion` one at a time — minimal question set, no interrogation.
+
+Delegate to `gsd-roadmapper`:
+
+```
+Task({
+  subagent_type: "gsd-roadmapper",
+  prompt: "
+    Mode: new-project-from-ingest
+    Intel: .planning/intel/SYNTHESIS.md (entry point)
+    Per-type intel: .planning/intel/{decisions,requirements,constraints,context}.md
+    User-supplied fields: {collected in previous step}
+
+    Produce:
+    - .planning/PROJECT.md
+    - .planning/REQUIREMENTS.md
+    - .planning/ROADMAP.md
+    - .planning/STATE.md
+
+    Treat ADR-locked decisions as locked in PROJECT.md <decisions> blocks.
+  "
+})
+```
+
+</step>
+
+<step name="route_merge_mode">
+
+**Applies only when MODE=merge.**
+
+Load existing `.planning/ROADMAP.md`, `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, all `CONTEXT.md` files under `.planning/phases/`.
+
+The synthesizer has already hard-blocked on any LOCKED-in-ingest vs LOCKED-in-existing contradiction; if we reach this step, no such blockers remain.
+
+Plan the merge:
+- **New requirements** from synthesized `.planning/intel/requirements.md` that do not overlap existing REQUIREMENTS.md entries → append to REQUIREMENTS.md
+- **New decisions** from synthesized `.planning/intel/decisions.md` that do not overlap existing CONTEXT.md `<decisions>` blocks → write to a new phase's CONTEXT.md or append to the next milestone's requirements
+- **New scope** → derive phase additions following the `new-milestone.md` pattern; append phases to `.planning/ROADMAP.md`
+
+Preview the merge diff to the user and gate via approve-revise-abort before writing.
+
+</step>
+
+<step name="finalize">
+
+Commit the ingest results:
+
+```bash
+gsd-sdk query commit "docs: ingest {N} docs from {SCAN_PATH} (#2387)" \
+  .planning/PROJECT.md \
+  .planning/REQUIREMENTS.md \
+  .planning/ROADMAP.md \
+  .planning/STATE.md \
+  .planning/intel/ \
+  .planning/INGEST-CONFLICTS.md
+```
+
+(For merge mode, substitute the actual set of modified files.)
+
+Display completion:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► INGEST DOCS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Show:
+- Mode ran (new or merge)
+- Docs ingested (count + type breakdown)
+- Decisions locked, requirements created, constraints captured
+- Conflict report path (`.planning/INGEST-CONFLICTS.md`)
+- Next step: `/ccp:plan-phase 1` (new mode) or `/ccp:plan-phase N` (merge, pointing at the first newly-added phase)
+
+</step>
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+- Violate the shared conflict-engine contract in `references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
+- Write PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md when BLOCKERs exist in the conflict report
+- Skip the 50-doc cap — larger sets must use `--manifest` to narrow the scope
+- Auto-resolve LOCKED-vs-LOCKED ADR contradictions — those are BLOCKERs in both modes
+- Merge competing PRD acceptance variants into a combined criterion — preserve all variants for user resolution
+- Bypass the discovery approval gate — users must see the classified doc list before classifiers spawn
+- Skip path validation on `SCAN_PATH` or `MANIFEST_PATH`
+- Implement `--resolve interactive` in this v1 — the flag is reserved; reject with a future-release message

package/src/pilot/workflows/mvp-phase.md

@@ -0,0 +1,199 @@
+<purpose>
+Guide the user through MVP-mode planning for a phase. Prompts for an "As a / I want to / So that" user story, runs SPIDR splitting check on the story, writes the result to ROADMAP.md, and delegates to `/ccp:plan-phase` (which auto-detects MVP via the roadmap mode field shipped in PRD Phase 1).
+</purpose>
+
+<required_reading>
+@~/.claude/pilot/references/user-story-template.md
+@~/.claude/pilot/references/spidr-splitting.md
+@~/.claude/pilot/references/planner-mvp-mode.md
+</required_reading>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent.
+
+**TEXT_MODE fallback:** Set TEXT_MODE=true if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is true. When TEXT_MODE is active, replace every AskUserQuestion call with a plain-text numbered list and ask the user to type their choice number.
+</runtime_note>
+
+<process>
+
+## 1. Parse and validate phase argument
+
+Extract the phase number from `$ARGUMENTS` (integer or decimal like `2.1`). Optional flag: `--force` (allow operating on `in_progress` / `completed` phases).
+
+If no argument:
+```
+ERROR: Phase number required
+Usage: /ccp:mvp-phase <phase-number>
+Example: /ccp:mvp-phase 1
+Example: /ccp:mvp-phase 2.1
+```
+Exit.
+
+Normalize per `@~/.claude/pilot/references/phase-argument-parsing.md` (zero-pad integer phases to two digits).
+
+## 2. Validate phase exists and check status
+
+Read `.planning/ROADMAP.md` and extract the Phase `${PHASE}` block: locate the `### Phase ${PHASE}:` heading, then capture the `**Goal**:`, `**Mode**:` (if present), `**Depends on**:`, and `**Requirements**:` lines that follow. Record the phase name from the heading, the goal text, and the mode (empty string if no `**Mode**:` line exists).
+
+To compute disk status, list the contents of `.planning/phases/` and check whether a directory matching `${PHASE}-*` exists, and whether it contains an `XX-SUMMARY.md` summary file alongside `XX-PLAN.md` files. Apply this mapping:
+
+- If a `phase-complete` summary or all plan summaries are present, treat status as `completed`.
+- If any `XX-PLAN.md` file exists for the phase but the phase is not complete, treat status as `in_progress`.
+- Otherwise, treat status as `not_started`.
+
+If the phase was not found in ROADMAP.md: error and exit. Suggest `/ccp:add-phase` or `/ccp:insert-phase` to create the phase first.
+
+**Status guard.** If the phase is `in_progress` (has plans but not complete) or `completed`, refuse unless `--force` is in `$ARGUMENTS`:
+
+```text
+ERROR: Phase ${PHASE} is currently ${STATUS}.
+Converting an active or completed phase to MVP mode mid-flight will
+invalidate any existing plans and summaries.
+
+To proceed anyway: /ccp:mvp-phase ${PHASE} --force
+```
+
+**Already-MVP guard.** If `PHASE_MODE` is already `mvp`, surface this and ask whether to re-prompt the user story or abort:
+
+> "Phase ${PHASE} is already in MVP mode with goal: «${PHASE_GOAL}». Re-run user-story prompts and SPIDR check?"
+
+Use `AskUserQuestion` with options [Re-prompt / Abort]. On Abort, exit cleanly. On Re-prompt, proceed.
+
+## 3. User story prompts
+
+Run three sequential `AskUserQuestion` calls. Each is free-text. After all three, assemble into the canonical sentence per `@~/.claude/pilot/references/user-story-template.md`:
+
+**Prompt 1 — As a:**
+> "As a [user role]?"
+> (Examples: "new user", "admin", "signed-in customer", "API consumer")
+
+**Prompt 2 — I want to:**
+> "I want to [capability]?"
+> (Examples: "register and log in", "upload a CSV", "see my dashboard")
+
+**Prompt 3 — So that:**
+> "So that [outcome]?"
+> (Examples: "I can access my account", "I can bulk-import contacts", "I can see at a glance what needs attention")
+
+Assemble:
+
+```
+USER_STORY="As a ${ROLE}, I want to ${CAPABILITY}, so that ${OUTCOME}."
+```
+
+If any of the three answers is empty or whitespace-only, error and re-prompt that single field. Do NOT proceed with a partial story.
+
+**Validate the assembled story against the canonical regex** `/^As a .+, I want to .+, so that .+\.$/`. The verb owns this regex and surfaces per-error guidance:
+
+- If the story does not match, identify which clause is missing or malformed (`As a ...`, `I want to ...`, `so that ...`, trailing period) and re-prompt only the offending field(s).
+- Rebuild `USER_STORY` and re-validate before continuing.
+- Do not abort the workflow on first invalid draft.
+
+This guarantees the goal stored in ROADMAP.md will satisfy the same guard the verifier applies later.
+
+## 4. SPIDR splitting check
+
+Run the SPIDR rules from `@~/.claude/pilot/references/spidr-splitting.md`. Briefly:
+
+**Trigger evaluation.** Check the assembled `USER_STORY` against the four size signals from the reference (compound capabilities, multi-actor, length > 120 chars, vague capability). If none fire, **skip SPIDR** entirely — go to step 5.
+
+**If SPIDR triggers.**
+
+a) Restate the story to the user:
+
+> "Your story: «${USER_STORY}»
+>
+> This story has [signal description, e.g., 'two compound capabilities joined by and']. Splitting it into multiple phases will produce a cleaner Walking Skeleton and reduce the risk of mid-phase scope creep.
+>
+> Want to walk through SPIDR splitting?"
+
+Use `AskUserQuestion` with options [Yes, walk through SPIDR / No, proceed with the story as-is].
+
+If "No": skip SPIDR, go to step 5.
+
+If "Yes": continue to (b).
+
+b) Ask which SPIDR axis fits best:
+
+> "Which axis best fits how to split this story?"
+
+Use `AskUserQuestion` with the five options from `spidr-splitting.md` (Spike / Paths / Interfaces / Data / Rules). Each option includes its targeted question as the description so the user can pick by understanding what each axis means.
+
+c) Walk through the chosen axis with **one** targeted question (not all five). For example, if the user picked "Paths":
+
+> "Does this feature have a happy path and one or more error/edge paths?"
+
+Free-text response. Workflow parses to identify the split.
+
+d) Produce a split proposal. Example:
+
+> "Proposed split (Paths axis):
+> - **Phase ${PHASE} (this one):** Happy path — ${HAPPY_STORY}
+> - **Phase ${PHASE+1} (new):** Edge case — ${EDGE_STORY}
+>
+> Accept this split?"
+
+Use `AskUserQuestion` [Accept / Modify / Reject].
+
+- **Accept**: `USER_STORY` becomes the first split's story (`${HAPPY_STORY}` in the example). Surface the remaining splits as a list of `/ccp:add-phase` invocations the user can run after this command completes — do NOT auto-create the new phases (preserve user control over numbering).
+- **Modify**: re-prompt the splits one more time, then accept or reject.
+- **Reject**: revert `USER_STORY` to the original, proceed without splitting.
+
+## 5. Update ROADMAP.md
+
+Read `ROADMAP.md`. Find the section for `Phase ${PHASE}`. Apply two edits:
+
+**Edit 1 — Update Goal line.**
+
+Find: `**Goal:** ${OLD_GOAL_TEXT}`
+Replace with: `**Goal:** ${USER_STORY}`
+
+**Edit 2 — Insert Mode line.**
+
+If `**Mode:**` already exists in the section (replacing or re-running), update it to `**Mode:** mvp`.
+If `**Mode:**` does not exist, insert `**Mode:** mvp` on the line immediately after `**Goal:**`.
+
+Show the user a unified diff (lines being changed) and ask:
+
+> "Apply these changes to ROADMAP.md?"
+
+Use `AskUserQuestion` [Apply / Cancel]. On Cancel, exit without writing.
+
+On Apply, write the updated `ROADMAP.md` atomically (read-edit-write).
+
+## 6. Verify the write
+
+Re-read `.planning/ROADMAP.md` and re-extract the Phase `${PHASE}` block: locate the `### Phase ${PHASE}:` heading and capture the `**Goal**:` and `**Mode**:` lines that follow.
+
+Assert:
+- The new `**Mode**:` value equals `mvp`
+- The new `**Goal**:` value equals the assembled user story
+
+If either assertion fails, surface the discrepancy to the user and exit. Do not proceed to plan-phase delegation with a half-applied write.
+
+## 7. Delegate to /ccp:plan-phase
+
+Invoke `/ccp:plan-phase ${PHASE}` (no flags). Phase 1's MVP_MODE resolution chain (CLI flag → roadmap mode → config → false) will detect the new `**Mode:** mvp` line and run plan-phase in vertical-slice mode automatically.
+
+The Walking Skeleton gate (also from Phase 1) will fire automatically if `${PHASE} == "01"` and there are zero prior phase summaries.
+
+## 8. Surface deferred phase splits (if any)
+
+If SPIDR produced a split in step 4, append a final user-facing message:
+
+> "**SPIDR split deferred phases.**
+>
+> Your original story was split. The first slice is now planned via plan-phase.
+> To create the remaining slice(s) as new phases, run:
+>
+> - `/ccp:add-phase` — for the next slice: «${SPLIT_2_STORY}»
+> - `/ccp:add-phase` — for the next slice: «${SPLIT_3_STORY}»
+>
+> Each will be added to the end of the current milestone. You can then run
+> `/ccp:mvp-phase <new-phase-number>` on each to plan them as MVP slices."
+
+## 9. Exit
+
+Workflow ends. The phase is now in MVP mode with a planned PLAN.md, optionally with deferred follow-up phases surfaced for the user.
+
+</process>