gswd 1.0.1 → 1.1.0

package/commands/gswd/start.md

@@ -1,7 +1,7 @@
 ---
 name: gswd:start
 description: Imagine, specify, audit, and compile — from idea to GSD contract
-argument-hint: "[@idea.md]"
+argument-hint: "[@idea.md] [--auto]"
 allowed-tools:
   - Bash
   - Read
@@ -23,14 +23,18 @@ One command to go from a product idea to a GSD-ready contract.
 - Full GSWD bundle (IMAGINE.md, DECISIONS.md, SPEC.md, JOURNEYS.md, etc.)
 - Compiled GSD contract: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
 
+**Modes:**
+- **Manual (default)** — pauses at each stage boundary with a summary and options (proceed, re-run, other)
+- **Auto (`--auto`)** — runs the full pipeline with no interactive stage-boundary prompts (v1.0 behavior)
+
 **Power-user flags (all optional):**
-- `--auto` — apply auto policy for decision-making (minimal interruptions). Requires @idea.md to skip interactive intake.
+- `--auto` — run the full pipeline automatically with no stage-boundary pauses
 - `--policy=<name>` — select named policy: `strict`, `balanced`, `aggressive`
 - `--resume` — continue from last checkpoint in `.planning/gswd/STATE.json`
 - `--skip-research` — disable research agents
 
 **Hard gates:**
-- Cannot finish if audit is FAIL
+- Cannot finish if audit is FAIL (in auto mode). In manual mode, user chooses.
 - In auto mode, cannot finish if policy requires manual approvals and they are not present
 </objective>
 
@@ -48,19 +52,70 @@ Check if `.planning/gswd/STATE.json` existed before this call. If STATE.json did
 
 The init call is idempotent and safe to run regardless of existing state.
 
-## Step 2 — Check for existing state
+## Step 2 — First-run experience (one-time)
+
+Read `.planning/gswd/STATE.json` using the Read tool. Check the `first_run_complete` field:
+
+- If `first_run_complete` is `true`: skip this step entirely — no logo, no guide, nothing.
+- If `first_run_complete` is missing, `false`, or `undefined`: this is the first run. Display the branding:
+
+1. Show the ASCII logo:
+```bash
+node ./bin/gswd-tools.cjs render logo
+```
+
+2. Show the command guide:
+```bash
+node ./bin/gswd-tools.cjs render first-run-guide
+```
+
+3. Mark first run as complete (write flag AFTER display — prevents flag being set without user seeing branding):
+```bash
+node ./bin/gswd-tools.cjs first-run-complete
+```
+
+The logo, tagline, and guide display as a single welcome block. After this, proceed directly to Step 3.
+
+## Step 3 — Check for existing state
 
 Read `.planning/gswd/STATE.json` using the Read tool. Branch on the `stage` field:
 
-- If `stage` is not `done` and not `init` (work is in progress): ask the user "Resume from [stage]? [yes / start fresh]"
-  - If yes: add `--resume` to the bootstrap call arguments assembled in Step 4
-  - If start fresh: proceed without `--resume`
-- If `stage` is `done` (pipeline already completed): ask the user "You already have a completed spec. Start fresh or resume?"
-  - If resume: add `--resume` to the bootstrap arguments
-  - If fresh: proceed without `--resume`
-- If `stage` is `init` or STATE.json was just created by Step 1: proceed directly to Step 3 (no resume prompt)
+- If `stage` is `init` or STATE.json was just created by Step 1: skip this step — proceed directly to Step 4 (no resume prompt needed for a fresh project)
+
+- If `stage` is not `init` and not `done` (work is in progress): present a choice using AskUserQuestion:
+
+  **Question:** "You have an in-progress session."
+  **Options:**
+  1. Resume previous session — continue from the current stage
+  2. Start new product — discard current state and begin fresh
+
+  If the user selects (1):
+  - Check `manual_mode` in STATE.json:
+    - If `manual_mode.enabled` is `true`: this is a manual mode resume. Read `manual_mode.last_checkpoint_stage` and `manual_mode.interrupt_type`.
+      - If `interrupt_type` is `mid_stage`: the interrupted stage will be re-run from scratch.
+      - If `interrupt_type` is `between_stages`: the next stage after `last_checkpoint_stage` will begin.
+    - Skip intake summary on resume (per CONTEXT.md decision). Just show stage progress:
+      ```bash
+      node ./bin/gswd-tools.cjs status
+      ```
+    - Display a brief recap: which stages are complete and where we are picking up.
+  - If `manual_mode.enabled` is `false` or not present (auto mode resume):
+    - Show status and read DECISIONS.md if it exists for a 2-3 sentence recap
+  - Add `--resume` to the pipeline call arguments assembled in Step 5
+
+  If the user selects (2): proceed without `--resume` (fresh start)
+
+- If `stage` is `done` (pipeline already completed): present a choice using AskUserQuestion:
 
-## Step 3 — Collect idea
+  **Question:** "You already have a completed spec."
+  **Options:**
+  1. Start new product — create a fresh spec from scratch
+  2. Resume from compile — re-run compile with existing spec
+
+  If the user selects (2): add `--resume` to the pipeline arguments
+  If the user selects (1): proceed without `--resume`
+
+## Step 4 — Collect idea
 
 **Path A — Idea file provided in $ARGUMENTS**
 
@@ -70,7 +125,11 @@ Detect Path A if $ARGUMENTS contains any word starting with `@` OR a path ending
 2. Summarize the idea in 2-3 sentences
 3. Ask: "Did I get that right? [yes / edit]"
 4. If the user chooses edit: let them revise, then re-summarize and re-confirm
-5. Once confirmed, proceed to Step 4
+5. Once confirmed, write INTAKE.json for resume support:
+```bash
+node ./bin/gswd-tools.cjs intake write --description "<confirmed summary>" --source file --idea-file "<original file path>"
+```
+6. Proceed to Step 5
 
 **Path B — No file provided in $ARGUMENTS**
 
@@ -80,44 +139,460 @@ Detect Path A if $ARGUMENTS contains any word starting with `@` OR a path ending
 2. After the user responds, summarize their response in 2-3 sentences
 3. Ask: "Did I get that right? [yes / edit]"
 4. If the user chooses edit: let them revise, then re-summarize and re-confirm
-5. Once confirmed, write the confirmed summary to `.planning/gswd/intake.md` using the Write tool so it can be passed to the bootstrap CLI:
-
-```
-# Idea
+5. Once confirmed:
+   a. Write INTAKE.json for resume support:
+   ```bash
+   node ./bin/gswd-tools.cjs intake write --description "<confirmed summary>" --source interactive
+   ```
+   b. Write intake.md for the pipeline CLI (same as before):
+   ```
+   # Idea
 
-<confirmed summary here>
-```
+   <confirmed summary here>
+   ```
+6. Proceed to Step 5
 
-6. Proceed to Step 4
+Note: "Did I get that right?" is the key moment — it is the last manual touchpoint before stages run. INTAKE.json is written AFTER confirmation, BEFORE any stage execution.
 
-Note: "Did I get that right?" is the key moment — it is the last manual touchpoint before automated stages run.
+## Step 5 — Route by mode
 
-## Step 4 — Run the bootstrap pipeline
+Determine mode from $ARGUMENTS:
+- If `--auto` is present: set `mode = auto`
+- Otherwise: set `mode = manual` (the default)
 
-Assemble the CLI command:
+**If mode is auto:**
 
+Assemble and run the bootstrap command exactly as before:
 - Base: `node ./bin/gswd-tools.cjs bootstrap`
 - If Path A: append the original `$ARGUMENTS` (contains the file path and any flags as-is)
 - If Path B: append `@.planning/gswd/intake.md` as the idea file argument, then append any flags from `$ARGUMENTS` that are NOT file paths (e.g., `--skip-research`, `--policy=balanced`)
-- If `--auto` is in `$ARGUMENTS` but no file was provided (Path B): note that `--auto` applies to pipeline stages after intake; proceed with interactive intake first, then pass `--auto` to the bootstrap call along with the intake.md path
-- If `--resume` was added in Step 2: include it in the arguments
+- If `--resume` was added in Step 3: include it in the arguments
 
 Run the assembled command via Bash:
-
 ```bash
 node ./bin/gswd-tools.cjs bootstrap <assembled arguments>
 ```
 
-## Step 5 — Show pipeline progress
+Skip to Step 7 (completion handler).
+
+**If mode is manual:**
+
+Write manual mode to STATE.json:
+```bash
+node ./bin/gswd-tools.cjs state set-manual-mode true
+```
+
+Proceed to Step 6 (manual stage loop).
+
+## Step 6 — Manual stage loop
+
+Run stages in order: Imagine, Specify, Audit, Compile. For each stage, follow the pattern below.
+
+If resuming (`--resume` was added in Step 3), determine the resume point:
+- Read STATE.json `stage_status` and `manual_mode.last_checkpoint_stage`
+- Skip any stage whose status is `done` (or `pass` for audit) AND whose artifacts are valid
+- If `manual_mode.interrupt_type` is `mid_stage`, re-run the stage at `last_checkpoint_stage`
+- If `manual_mode.interrupt_type` is `between_stages`, start the next stage after `last_checkpoint_stage`
+
+### 6.1 — Imagine
+
+If resuming and imagine is already `done` in STATE.json with valid artifacts (IMAGINE.md, ICP.md, GTM.md, COMPETITION.md, DECISIONS.md all exist and non-empty), skip to 6.2.
+
+#### 6.1.1 — Run Imagine
+
+**Extract product context.** Read `.planning/gswd/INTAKE.json` using the Read tool. Extract:
+- `domain`: the first sentence of the `description` field (up to the first period)
+- `targetUser`: the `target_user` field
+- Fallback to "your product" / "your users" if fields are missing
+
+**Display contextual banner.** Render a contextualized stage banner:
+
+For a first run (STATE.json `manual_mode.reruns.imagine` is 0 or missing):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSWD ► IMAGINE
+ Validating product direction for {domain} targeting {targetUser}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+For re-runs (STATE.json `manual_mode.reruns.imagine` > 0):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSWD ► IMAGINE
+ Refining directions based on your feedback about {key concern from revision-notes.md}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Display agent pre-briefing** BEFORE the imagine CLI call. Show all 5 Imagine agents with product-contextualized purposes:
+```
+◆ Spawning 5 research agents:
+  → market-researcher: mapping the {domain} landscape to find gaps
+  → icp-persona: profiling {targetUser} who need {domain}
+  → positioning: finding the angle that makes {domain} obviously necessary
+  → brainstorm-alternatives: exploring 3 distinct product directions for {domain}
+  → devils-advocate: stress-testing assumptions before you commit to a direction
+```
+
+The pre-briefing uses the user's product context, not generic text. Each agent is named explicitly for technical transparency.
+
+**Run imagine** via Bash:
+```bash
+node ./bin/gswd-tools.cjs imagine @.planning/gswd/intake.md {--skip-research if flag present}
+```
+
+If this is a re-run with augmented context:
+```bash
+node ./bin/gswd-tools.cjs imagine @.planning/gswd/intake.md --rerun-context .planning/gswd/revision-notes.md
+```
+
+After imagine completes successfully, read the ImagineResult output. Extract `research_summary`, `selected_direction`, `vision_statement`, `agent_headlines`, and artifact paths.
+
+#### 6.1.2 — Display Agent Completion Headlines and Research Summary
+
+**Display individual agent completion headlines.** After the imagine command returns, display each agent's key finding on its own line. If `agent_headlines` are available in the ImagineResult, use them directly. Otherwise, extract headlines from the raw artifact files (COMPETITION.md, ICP.md, GTM.md) by reading the first sentence after `## Summary` or `## Overview` or the first non-heading line.
+
+```
+✓ market-researcher: {headline from agent output}
+✓ icp-persona: {headline from agent output}
+✓ positioning: {headline from agent output}
+✓ brainstorm-alternatives: {headline from agent output}
+✓ devils-advocate: {headline from agent output}
+```
+
+Show each agent individually — even if multiple agents finished within seconds, each gets its own line. Use ✓ for completed agents and ✗ for any that failed.
+
+Note: Since CLI execution is synchronous (agents run inside `node ./bin/gswd-tools.cjs imagine`), headlines are displayed AFTER the command returns. Each agent still gets its own line with its key finding to meet COMM-03.
+
+Read the output artifacts using the Read tool: `.planning/IMAGINE.md`, `.planning/ICP.md`, `.planning/GTM.md`, `.planning/COMPETITION.md`, `.planning/DECISIONS.md`
+
+**Display the structured research summary.** For each agent section from the ImagineResult `research_summary`:
+
+1. Show the section display name as a ### heading
+2. Show a product-contextualized intro: "*For a product helping {target_user}:*"
+3. Show 3-5 takeaway bullets (highlights only, not full agent output)
+4. Show the bridging paragraph: how these findings shaped the proposed directions
+
+The summary should read like a consultant brief written for the user's specific product, not a generic market report. Reference the user's actual product/problem in section intros.
+
+Mention that full agent outputs are available in their raw artifact files.
+
+#### 6.1.3 — Present Direction Cards
+
+Display each of the 3 directions using direction cards:
+
+For each direction (proposed + 2 alternatives):
+1. Show direction label with **(Recommended)** marker on the proposed direction
+2. Show **"Why this makes sense:"** rationale section FIRST with evidence-based bullets
+3. Show existing fields: ICP, Problem, Wedge, Differentiator, Risks
+
+#### 6.1.4 — Direction Selection
+
+Present direction selection using AskUserQuestion:
+- **header:** "Choose your product direction"
+- **question:** "Review the directions above. Which path fits your vision?"
+- **options:**
+  - "{Direction 1 label}" (the proposed/recommended direction)
+  - "{Direction 2 label}"
+  - "{Direction 3 label}"
+  - "Not satisfied — tell me more"
+
+**Handle response:**
+
+**If user selects a direction (option 1, 2, or 3):** Record the selection. Proceed to 6.1.5 (Vision Statement).
+
+**If user selects "Not satisfied — tell me more":**
+
+1. Ask the user conversationally: "What's missing or wrong? Tell me what you didn't like or what you'd like to explore differently."
+2. Collect their free-text feedback.
+3. **CASCADE-INVALIDATE FIRST** (IMAGINE-08 — this MUST happen before any new artifact writes):
+   ```bash
+   node ./bin/gswd-tools.cjs state cascade-invalidate imagine
+   ```
+4. Write the user's feedback to `.planning/gswd/revision-notes.md`:
+   ```
+   # Imagine Re-run Feedback
+
+   **Re-run #{N}** (from STATE.json manual_mode.reruns.imagine)
+   **Date:** {current date}
+
+   ## User Feedback
+   {user's free-text feedback}
+
+   ## Previous Direction Labels
+   {list the 3 directions from this run}
+   ```
+5. Re-run imagine with augmented context:
+   ```bash
+   node ./bin/gswd-tools.cjs imagine @.planning/gswd/intake.md --rerun-context .planning/gswd/revision-notes.md
+   ```
+   The `--rerun-context` flag causes imagine to pass previous agent outputs + user feedback into agent prompts, so agents build on or pivot from prior findings.
+6. **Loop back to 6.1.2** (display new research summary, present new direction cards, offer selection again).
+
+Re-runs are unlimited — no hard cap (IMAGINE-04). The re-run counter in STATE.json tracks count for visibility/debugging only.
+
+#### 6.1.5 — Vision Statement
+
+After a direction is selected, synthesize a vision statement:
+
+1. Using the research findings and selected direction, generate an aspirational vision statement.
+   - Vision = aspirational future state the product enables ("A world where X is possible")
+   - NOT a product description (what the product does)
+   - Different scope: vision describes the world the product creates, not the product itself
+   - Example: "A world where solo founders never build the wrong thing because their specification process is as rigorous as their code."
+
+2. Present the vision statement to the user using AskUserQuestion:
+   - **header:** "Vision Statement"
+   - **question:** Show the generated vision statement, then ask: "This vision captures the aspirational future your product enables. Accept or edit?"
+   - **options:**
+     - "Accept this vision"
+     - "Edit — I want to adjust it"
+
+3. **Handle response:**
+   - **"Accept this vision":** Proceed with this vision statement.
+   - **"Edit — I want to adjust it":** Ask: "What would you like to change or add?" Collect feedback. Regenerate the vision incorporating the user's additional inputs. Present again with Accept / Edit. Loop until accepted.
+
+4. The accepted vision statement is already written to DECISIONS.md (## Vision section) and IMAGINE.md (## Vision section) by the imagine workflow. If the user edited and regenerated, update both files atomically via CLI:
+   ```bash
+   node ./bin/gswd-tools.cjs imagine update-vision "<accepted vision statement>"
+   ```
+   This replaces the ## Vision section in both DECISIONS.md and IMAGINE.md atomically via safeWriteFile(). Do NOT use the Write tool directly on these files for vision updates — route all vision writes through this command.
+
+#### 6.1.6 — Post-Imagine Summary and Checkpoint
+
+1. Generate a structured summary (same pattern as before):
+   - **Headline:** Count of product directions proposed, mention ICP/GTM/competition coverage, note vision statement frozen
+   - **Section summaries:** One paragraph each for product directions, ICP analysis, GTM strategy, competition landscape, key decisions, and vision statement
+   - **File list:** All files created/updated
+
+2. Display the summary to the user.
+
+3. Record checkpoint in STATE.json:
+```bash
+node ./bin/gswd-tools.cjs state update-manual-checkpoint imagine between_stages
+```
+
+4. Present the checkpoint using AskUserQuestion:
+   - **header:** "Imagine complete"
+   - **question:** Consultant-style summary referencing actual findings: "The research mapped {domain}'s competitive landscape, identified {targetUser} as your primary persona, and produced {N} distinct product directions. You selected '{direction label}' and froze a vision statement. The groundwork for a strong spec is in place. Proceed to Specify?\n\n> **Tip:** Run `/clear` before continuing — the imagine stage consumed significant context."
+   - **options:**
+     - "Proceed to Specify"
+     - "Edit & re-run Imagine"
+     - "Other"
+
+5. Handle response:
+   - **"Proceed to Specify":** Continue to 6.2.
+   - **"Edit & re-run Imagine":** Ask the user: "What would you like to change?" Collect feedback. Run cascade invalidation:
+     ```bash
+     node ./bin/gswd-tools.cjs state cascade-invalidate imagine
+     ```
+     Write feedback to revision-notes.md. Re-run imagine with augmented context. Loop back to 6.1.2. Re-runs are unlimited.
+   - **"Other":** Accept free-text input. Interpret and act accordingly.
+
+### 6.2 — Specify
+
+If resuming and specify is already `done` in STATE.json with valid artifacts (SPEC.md, JOURNEYS.md, NFR.md, ARCHITECTURE.md, INTEGRATIONS.md all exist and non-empty), skip to 6.3.
+
+**Extract enriched product context.** DECISIONS.md now exists after Imagine. Read it to get precise context:
+- Read `**Product Direction:**` from DECISIONS.md for the domain
+- Read `**Target User:**` from DECISIONS.md for the target user
+- These are more precise than INTAKE.json since they reflect the user's chosen direction
+
+**Display contextual banner:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSWD ► SPECIFY
+ Building the execution-grade spec: journeys, requirements, and architecture for {domain}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Display agent pre-briefing** for Specify agents:
+```
+◆ Spawning specification agents:
+  → journey-mapper: mapping user journeys for {targetUser} through {domain}
+  → architecture-drafter: designing the system architecture for {domain}
+  → integrations-checker: evaluating external services {domain} needs to connect with
+```
+
+Run specify via Bash:
+```bash
+node ./bin/gswd-tools.cjs specify
+```
+
+After specify completes successfully:
+
+1. Read the output artifacts using the Read tool: `.planning/SPEC.md`, `.planning/JOURNEYS.md`, `.planning/NFR.md`, `.planning/ARCHITECTURE.md`, `.planning/INTEGRATIONS.md`
+2. Generate a structured summary:
+   - **Headline:** Count of journeys, NFR categories, architecture decisions, integrations
+   - **Section summaries:** One paragraph each for:
+     - Spec overview (scope, key features)
+     - User journeys (count, primary flows)
+     - NFRs (categories, key constraints)
+     - Architecture (stack decisions, patterns)
+     - Integrations (count, key services)
+   - **File list:** All files created/updated
+3. Display the summary
+
+4. Record checkpoint:
+```bash
+node ./bin/gswd-tools.cjs state update-manual-checkpoint specify between_stages
+```
+
+5. Present checkpoint using AskUserQuestion:
+   - **header:** "Specify complete"
+   - **question:** Consultant-style summary referencing actual findings: "Specify mapped {N} user journeys with {M} functional requirements and {K} NFR categories for {domain}. The architecture defines {C} components. Every journey traces to requirements — the spec is execution-ready. Proceed to Audit?\n\n> **Tip:** Run `/clear` before continuing — the specify stage consumed significant context."
+   - **options:**
+     - "Proceed to Audit"
+     - "Edit & re-run Specify"
+     - "Other"
+
+6. Handle response (same pattern as 6.1):
+   - **"Proceed to Audit":** Continue to 6.3
+   - **"Edit & re-run Specify":** Cascade-invalidate specify, collect feedback, re-run with feedback, loop
+     ```bash
+     node ./bin/gswd-tools.cjs state cascade-invalidate specify
+     ```
+   - **"Other":** Interpret free-text
+
+### 6.3 — Audit
+
+If resuming and audit is already `pass` in STATE.json with valid artifacts (AUDIT.md exists and non-empty), skip to 6.4.
+
+**Display contextual banner:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSWD ► AUDIT
+ Verifying spec completeness — every journey, requirement, and edge case for {domain} must trace
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Display pre-run explanation.** Audit has no agents, so no pre-briefing. Instead, show a one-line explanation of what the deterministic checks will do:
+
+"Running deterministic coverage checks: journey-FR tracing, orphan detection, integration validation, and heading compliance."
+
+Run audit via Bash:
+```bash
+node ./bin/gswd-tools.cjs audit
+```
+
+After audit completes:
+
+**If audit PASSED:**
+
+1. Read `.planning/AUDIT.md` and generate summary: total checks, pass count, coverage
+2. Display summary
+
+3. Record checkpoint:
+```bash
+node ./bin/gswd-tools.cjs state update-manual-checkpoint audit between_stages
+```
+
+4. Present checkpoint using AskUserQuestion:
+   - **header:** "Audit passed"
+   - **question:** Consultant-style summary: "Audit passed all {N} checks with full coverage for {domain}. Every journey links to requirements, no orphan specs, and all integration statuses are resolved. The specification is verified and ready for compilation. Proceed to Compile?"
+   - **options:**
+     - "Proceed to Compile"
+     - "Re-run Audit"
+     - "Other"
+
+5. Handle response:
+   - **"Proceed to Compile":** Continue to 6.4
+   - **"Re-run Audit":** Re-run audit, loop
+   - **"Other":** Interpret free-text
+
+**If audit FAILED (manual mode specific handling):**
+
+1. Read `.planning/AUDIT.md` for failure details
+2. Display the audit failures with details — show what failed and why
+
+3. Present checkpoint using AskUserQuestion:
+   - **header:** "Audit failed"
+   - **question:** Consultant-style summary: "Audit found {N} issues in the {domain} specification. {top issue summary}. These gaps need attention before the spec can be trusted as a build contract."
+   - **options:**
+     - "Fix issues & re-run Audit"
+     - "Proceed to Compile anyway"
+     - "Stop here"
+
+4. Handle response:
+   - **"Fix issues & re-run Audit":** Ask user for guidance on what to fix, or attempt automatic fixes. Run cascade-invalidate on audit:
+     ```bash
+     node ./bin/gswd-tools.cjs state cascade-invalidate audit
+     ```
+     Re-run audit. Loop back to check result.
+   - **"Proceed to Compile anyway":** Log the override decision in STATE.json (record that user chose to proceed despite audit failures). Continue to 6.4.
+   - **"Stop here":** Display current status and inform user they can resume later with `/gswd:start --resume`. Exit the pipeline gracefully.
+
+### 6.4 — Compile
+
+**No contextual banner for Compile.** Per CONTEXT.md locked decision: "Skip Compile (deterministic, quick, banner unnecessary)." Keep any existing minimal banner as `renderBanner('COMPILE')` without a context line. Do NOT add a product-contextualized line.
+
+Run compile via Bash:
+```bash
+node ./bin/gswd-tools.cjs compile
+```
+
+After compile completes successfully:
+
+Display a brief informational one-liner (not a banner, just context):
+"Compile is deterministic — same spec inputs always produce the same GSD contract. No advisor commentary needed."
+
+1. Read the output artifacts: `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, `.planning/ROADMAP.md`, `.planning/STATE.md`
+2. Generate a brief completion summary: files compiled, contract completeness
+3. Display the summary
+
+4. Set stage to done in STATE.json:
+```bash
+node ./bin/gswd-tools.cjs state update-stage compile done
+```
+
+5. Clear manual mode checkpoint (pipeline complete):
+```bash
+node ./bin/gswd-tools.cjs state update-manual-checkpoint null null
+```
+
+Proceed to Step 7.
+
+Note: Compile is deterministic given the same inputs. No re-run prompt is needed since compile output cannot diverge from spec input.
+
+## Step 7 — On completion
+
+Display the final completion summary in a consultant-toned format. Frame it as a deliverable, not a log dump.
+
+**For both manual and auto modes, show:**
+
+"Your GSD contract is ready. Here's what was produced for {domain}:"
+
+**Generated Files:**
+
+```bash
+node ./bin/gswd-tools.cjs render file-inventory
+```
+
+Display the file inventory table produced by the command above. Only existing files are shown, so the output reflects what was actually generated.
+
+Follow with:
+- A clear "Pipeline complete" confirmation
+- Suggest running `/gsd:plan-phase 01` to begin the build phase
+- Suggest `/clear` for fresh context
+
+**Next up:** `/gsd:plan-phase 01`
 
-Display stage banners, checkpoint boxes, and output as the CLI emits them.
+**For manual mode additionally show:**
+- Re-run counts per stage if any re-runs occurred (read from STATE.json `manual_mode.reruns`)
+- A note that all artifacts are in `.planning/`
 
-## Step 6 — On completion
+## Step 8 — On failure
 
-Show the Next Up block with generated artifacts and suggest running `/gsd:plan-phase 01`.
+If any stage fails (not an audit FAIL in manual mode — that is handled in 6.3):
 
-## Step 7 — On failure
+**In manual mode:**
+- Display the failure reason clearly
+- Use AskUserQuestion to offer options:
+  - "Re-run the failed stage"
+  - "Stop here"
+- If user chooses to re-run: loop back to the appropriate stage step
+- If user chooses to stop: save state and exit gracefully
 
-If any stage fails (especially audit), display the failure reason and suggest remediation before retrying.
+**In auto mode:**
+- Display the error and exit (existing behavior, no change from v1.0)
 
 </process>