@opengsd/gsd-core 1.13.0 → 1.14.0

package/gsd-core/workflows/docs-update/detail/elaboration.md

@@ -0,0 +1,179 @@
+# docs-update.md — deferred elaboration
+
+Read in full when `workflow.compact_content` is `false` (the default) — see
+`gsd-core/references/compact-content-gate.md` for the check and resolution rule this
+spine defers to. Each `§` below is the full text the spine condenses at the point it
+names.
+
+## § 1 — sequential_generation
+
+**Read the work manifest first:** `Read .planning/tmp/docs-work-manifest.json` — use `canonical_queue` items for generation order. Update `status` after each doc is generated. Write the updated manifest back to disk after all docs are complete.
+
+When the `Task` tool is unavailable, generate docs sequentially in the current context. This step replaces dispatch_wave_1, collect_wave_1, dispatch_wave_2, and collect_wave_2.
+
+**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (Read, Bash, Write, Grep, Glob, or equivalent tools available in your runtime).
+
+Read `agents/gsd-doc-writer.md` instructions once before beginning. Follow the create_mode or update_mode instructions from that agent for each doc, using the same doc_assignment fields as the parallel path.
+
+**Wave 1 (sequential — complete all three before starting Wave 2):**
+
+For each Wave 1 doc, construct the equivalent doc_assignment block and generate the file inline:
+
+1. **README** — mode from resolve_modes; for update/supplement mode, include existing_content
+   - Construct doc_assignment: `type: readme`, `mode: {create|update|supplement}`, `preservation_mode: {value|null}`, `project_context: {INIT JSON}`, `existing_content:` (if update/supplement)
+   - Explore the codebase (Read, Grep, Glob, Bash) following gsd-doc-writer create_mode / update_mode instructions
+   - Write the file to the resolved path (README.md)
+
+2. **ARCHITECTURE** — mode from resolve_modes; for update/supplement mode, include existing_content
+   - Construct doc_assignment: `type: architecture`, `mode: {create|update|supplement}`, `preservation_mode: {value|null}`, `project_context: {INIT JSON}`, `existing_content:` (if update/supplement)
+   - Explore the codebase following gsd-doc-writer instructions
+   - Write the file to the resolved path (docs/ARCHITECTURE.md, or ARCHITECTURE.md if found at root as fallback)
+
+3. **CONFIGURATION** — mode from resolve_modes; for update/supplement mode, include existing_content
+   - Construct doc_assignment: `type: configuration`, `mode: {create|update|supplement}`, `preservation_mode: {value|null}`, `project_context: {INIT JSON}`, `existing_content:` (if update/supplement)
+   - Apply VERIFY markers to any infrastructure claim not discoverable from the repository
+   - Explore the codebase following gsd-doc-writer instructions
+   - Write the file to the resolved path (docs/CONFIGURATION.md, or CONFIGURATION.md if found at root as fallback)
+
+**Wave 2 (sequential — begin only after all Wave 1 docs are written):**
+
+Wave 2 docs can reference Wave 1 outputs since they are already written. Include `wave_1_outputs` in each doc_assignment.
+
+4. **GETTING-STARTED** — mode from resolve_modes; include wave_1_outputs: [README.md, docs/ARCHITECTURE.md, docs/CONFIGURATION.md]
+5. **DEVELOPMENT** — mode from resolve_modes; include wave_1_outputs
+6. **TESTING** — mode from resolve_modes; include wave_1_outputs
+7. **API** (only if queued) — mode from resolve_modes; include wave_1_outputs
+8. **DEPLOYMENT** (only if queued) — Apply VERIFY markers to any infrastructure claim not discoverable from the repository; include wave_1_outputs
+9. **CONTRIBUTING** (only if queued) — mode from resolve_modes; include wave_1_outputs
+
+**Monorepo per-package READMEs (only if `monorepo_workspaces` is non-empty):**
+
+After all 9 root-level docs are written, generate per-package READMEs sequentially:
+
+For each resolved package directory (from workspace glob expansion) that contains a `package.json`:
+- Determine mode: if `{package_dir}/README.md` exists, mode = `update`; else mode = `create`
+- Construct doc_assignment: `type: readme`, `mode: {create|update}`, `scope: per_package`, `package_dir: {absolute path}`, `project_context: {INIT JSON with project_root set to package directory}`, `existing_content:` (if update)
+- Follow gsd-doc-writer instructions for per_package scope
+- Write the file to `{package_dir}/README.md`
+
+Continue to verify_docs.
+
+## § 2 — fix_loop
+
+**Read the work manifest first:** `Read .planning/tmp/docs-work-manifest.json` — identify ALL docs (canonical AND non-canonical) with `claims_failed > 0` from the verification results in `.planning/tmp/verify-*.json`. Both queues are eligible for fixes.
+
+Correct flagged inaccuracies by re-sending failing docs to the doc-writer in fix mode. Per D-06, max 2 iterations. Per D-05, halt immediately on regression.
+
+**Skip condition:** If all docs passed verification (no failures), skip this step.
+
+**Iteration tracking:**
+- `MAX_FIX_ITERATIONS = 2`
+- `iteration = 0`
+- `previous_passed_docs` = set of doc_paths where claims_failed === 0 after initial verification
+
+**For each iteration (while iteration < MAX_FIX_ITERATIONS and there are docs with failures):**
+
+1. For each doc with `claims_failed > 0` in the latest verification_results:
+   a. Read the current file content from disk (the spine's truncation guard captures its line count from this same read).
+   b. Spawn `gsd-doc-writer` agent (or invoke sequentially) with a fix assignment:
+      ```xml
+      <doc_assignment>
+      type: {original doc type from the queue, e.g. readme}
+      mode: fix
+      doc_path: {relative path}
+      project_context: {the same INIT JSON object every doc_assignment carries}
+      existing_content: {current file content read from disk}
+      failures:
+        - line: {line}
+          claim: "{claim}"
+          expected: "{expected}"
+          actual: "{actual}"
+      </doc_assignment>
+      ```
+   c. Never batch multiple docs' failures into a single spawn — one agent call per doc.
+   d. Once the agent returns, apply the spine's post-fix truncation guard (line-count comparison, restore-and-mark-corrupted on breach). A corrupted doc stays in this iteration's re-verify pass at step 2 below; it just isn't handed another fix attempt.
+
+2. After all fix agents complete, re-verify ALL docs (not just the ones that were fixed):
+   - Re-run the same verification process as verify_docs step.
+   - Read updated result JSONs from `.planning/tmp/verify-{doc_filename}.json`.
+
+3. **Regression detection (D-05):**
+   For each doc in the new verification_results:
+   - If this doc was in `previous_passed_docs` (passed in the prior round) AND now has `claims_failed > 0`, this is a REGRESSION.
+   - If regression detected: HALT the loop immediately. Present:
+     ```
+     REGRESSION DETECTED -- halting fix loop.
+
+     {doc_path} previously passed verification but now has {claims_failed} failures after fix iteration {iteration + 1}.
+
+     This means the fix introduced new errors. Remaining failures require manual review.
+     ```
+     Continue to scan_for_secrets (do not attempt further fixes).
+
+4. Update `previous_passed_docs` with docs that now pass.
+5. Increment `iteration`.
+
+**After loop exhaustion (iteration === MAX_FIX_ITERATIONS and failures remain):**
+
+Present remaining failures:
+```
+Fix loop completed ({MAX_FIX_ITERATIONS} iterations). Remaining failures:
+
+| Doc               | Failed Claims |
+|-------------------|---------------|
+| {doc_path}        | {count}       |
+
+These failures require manual correction. Review the verification output in .planning/tmp/verify-*.json for details.
+```
+
+Continue to scan_for_secrets.
+
+## § 3 — verify_only_report
+
+**Reached when `--verify-only` is present in `$ARGUMENTS`.** This is an early-exit step — do not proceed to dispatch, generation, commit, or report steps after this step.
+
+Invoke the gsd-doc-verifier agent in read-only mode for each file in `existing_docs` from the init JSON:
+
+1. For each doc in `existing_docs`:
+   a. Spawn `gsd-doc-verifier` (or invoke sequentially if Task tool is unavailable), passing `model="{DOC_VERIFIER_MODEL}"` as the Task/Agent call's `model` parameter — not part of the `<verify_assignment>` prompt — so `dynamic_routing`/`model_profile` tiers apply instead of the caller's session model (#3602). Omit the parameter entirely when the value is `"inherit"` or empty (#2517). Each spawn carries:
+      ```xml
+      <verify_assignment>
+      doc_path: {doc.path}
+      project_root: {the project_root field carried in the init JSON}
+      </verify_assignment>
+      ```
+   b. Read the result JSON from `.planning/tmp/verify-{doc_filename}.json`.
+
+2. Also count VERIFY markers in each doc: grep for `<!-- VERIFY:` in the file content.
+
+Present a combined summary table:
+
+```
+--verify-only audit:
+
+| File                     | Claims Checked | Passed | Failed | VERIFY Markers |
+|--------------------------|----------------|--------|--------|----------------|
+| README.md                | 12             | 10     | 2      | 0              |
+| docs/ARCHITECTURE.md     | 8              | 8      | 0      | 0              |
+| docs/CONFIGURATION.md    | 5              | 3      | 2      | 5              |
+| ...                 | ...            | ...    | ...    | ...            |
+
+Total: {total_checked} claims checked, {total_failed} failures, {total_markers} VERIFY markers requiring manual review
+```
+
+If any failures exist, show details:
+```
+Failed claims:
+  README.md:34 - "src/cli/index.ts" (expected: file exists, actual: file not found)
+  docs/CONFIGURATION.md:12 - "npm run deploy" (expected: script in package.json, actual: script not found)
+```
+
+Display note:
+```
+To fix failures automatically: /gsd:docs-update (runs generation + fix loop)
+To regenerate all docs from scratch: /gsd:docs-update --force
+```
+
+Clean up temp files: remove `.planning/tmp/verify-*.json` files.
+
+End workflow — do not proceed to any dispatch, commit, or report steps.

package/gsd-core/workflows/docs-update.md

@@ -10,6 +10,8 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 
 <process>
 
+**Compact Content Gate.** Read and follow `gsd-core/references/compact-content-gate.md` now — it states the `workflow.compact_content` check and the resolution rule this spine defers to. When it directs a Read, read `gsd-core/workflows/docs-update/detail/elaboration.md` in full before continuing past this point; its content elaborates on three steps below (sequential_generation, fix_loop, verify_only_report).
+
 <step name="init_context" priority="first">
 Load docs-update context:
 
@@ -286,7 +288,7 @@ Mode resolution:
 | architecture | docs/architecture/overview.md | create | new directory |
 | getting_started | docs/guides/getting-started.md | update | found, hand-written |
 | development | docs/guides/development.md | create | matched docs/guides/ |
-| testing | docs/guides/testing.md | create | matched docs/guides/ |
+| contributing | docs/guides/contributing.md | create | matched docs/guides/ |
 | configuration | docs/guides/configuration.md | create | matched docs/guides/ |
 | api | docs/api/reference.md | create | new directory |
 | deployment | docs/guides/deployment.md | update | found, hand-written |
@@ -721,56 +723,9 @@ If `section_manifest` (from `INIT_DOCS_UPDATE`) is `null` or `"dispatch-monorepo
 <!-- /gsd:section -->
 
 <step name="sequential_generation" condition="Task tool is NOT available (e.g. Antigravity, Gemini CLI, Codex, Copilot)">
-**Read the work manifest first:** `Read .planning/tmp/docs-work-manifest.json` — use `canonical_queue` items for generation order. Update `status` after each doc is generated. Write the updated manifest back to disk after all docs are complete.
-
-When the `Task` tool is unavailable, generate docs sequentially in the current context. This step replaces dispatch_wave_1, collect_wave_1, dispatch_wave_2, and collect_wave_2.
-
-**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (Read, Bash, Write, Grep, Glob, or equivalent tools available in your runtime).
-
-Read `agents/gsd-doc-writer.md` instructions once before beginning. Follow the create_mode or update_mode instructions from that agent for each doc, using the same doc_assignment fields as the parallel path.
-
-**Wave 1 (sequential — complete all three before starting Wave 2):**
-
-For each Wave 1 doc, construct the equivalent doc_assignment block and generate the file inline:
-
-1. **README** — mode from resolve_modes; for update/supplement mode, include existing_content
-   - Construct doc_assignment: `type: readme`, `mode: {create|update|supplement}`, `preservation_mode: {value|null}`, `project_context: {INIT JSON}`, `existing_content:` (if update/supplement)
-   - Explore the codebase (Read, Grep, Glob, Bash) following gsd-doc-writer create_mode / update_mode instructions
-   - Write the file to the resolved path (README.md)
-
-2. **ARCHITECTURE** — mode from resolve_modes; for update/supplement mode, include existing_content
-   - Construct doc_assignment: `type: architecture`, `mode: {create|update|supplement}`, `preservation_mode: {value|null}`, `project_context: {INIT JSON}`, `existing_content:` (if update/supplement)
-   - Explore the codebase following gsd-doc-writer instructions
-   - Write the file to the resolved path (docs/ARCHITECTURE.md, or ARCHITECTURE.md if found at root as fallback)
-
-3. **CONFIGURATION** — mode from resolve_modes; for update/supplement mode, include existing_content
-   - Construct doc_assignment: `type: configuration`, `mode: {create|update|supplement}`, `preservation_mode: {value|null}`, `project_context: {INIT JSON}`, `existing_content:` (if update/supplement)
-   - Apply VERIFY markers to any infrastructure claim not discoverable from the repository
-   - Explore the codebase following gsd-doc-writer instructions
-   - Write the file to the resolved path (docs/CONFIGURATION.md, or CONFIGURATION.md if found at root as fallback)
-
-**Wave 2 (sequential — begin only after all Wave 1 docs are written):**
-
-Wave 2 docs can reference Wave 1 outputs since they are already written. Include `wave_1_outputs` in each doc_assignment.
-
-4. **GETTING-STARTED** — mode from resolve_modes; include wave_1_outputs: [README.md, docs/ARCHITECTURE.md, docs/CONFIGURATION.md]
-5. **DEVELOPMENT** — mode from resolve_modes; include wave_1_outputs
-6. **TESTING** — mode from resolve_modes; include wave_1_outputs
-7. **API** (only if queued) — mode from resolve_modes; include wave_1_outputs
-8. **DEPLOYMENT** (only if queued) — Apply VERIFY markers to any infrastructure claim not discoverable from the repository; include wave_1_outputs
-9. **CONTRIBUTING** (only if queued) — mode from resolve_modes; include wave_1_outputs
+When the `Task` tool is unavailable, generate all queued docs sequentially in the current context instead of spawning subagents — this step replaces dispatch_wave_1, collect_wave_1, dispatch_wave_2, and collect_wave_2. Read `agents/gsd-doc-writer.md` once, then for each queued doc (Wave 1: README/ARCHITECTURE/CONFIGURATION, complete before Wave 2; Wave 2: GETTING-STARTED/DEVELOPMENT/TESTING plus any queued conditional docs, referencing Wave 1 outputs) construct the same doc_assignment fields the parallel path uses and write the file inline, using only file system tools (never browser-based tools). If `monorepo_workspaces` is non-empty, generate per-package READMEs sequentially afterward. Continue to verify_docs.
 
-**Monorepo per-package READMEs (only if `monorepo_workspaces` is non-empty):**
-
-After all 9 root-level docs are written, generate per-package READMEs sequentially:
-
-For each resolved package directory (from workspace glob expansion) that contains a `package.json`:
-- Determine mode: if `{package_dir}/README.md` exists, mode = `update`; else mode = `create`
-- Construct doc_assignment: `type: readme`, `mode: {create|update}`, `scope: per_package`, `package_dir: {absolute path}`, `project_context: {INIT JSON with project_root set to package directory}`, `existing_content:` (if update)
-- Follow gsd-doc-writer instructions for per_package scope
-- Write the file to `{package_dir}/README.md`
-
-Continue to verify_docs.
+Exact per-doc construction and the monorepo per-package loop: `gsd-core/workflows/docs-update/detail/elaboration.md` § 1.
 </step>
 
 <step name="verify_docs">
@@ -847,39 +802,16 @@ If any doc (canonical OR non-canonical) has `claims_failed > 0`: continue to fix
 </step>
 
 <step name="fix_loop">
-**Read the work manifest first:** `Read .planning/tmp/docs-work-manifest.json` — identify ALL docs (canonical AND non-canonical) with `claims_failed > 0` from the verification results in `.planning/tmp/verify-*.json`. Both queues are eligible for fixes.
-
-Correct flagged inaccuracies by re-sending failing docs to the doc-writer in fix mode. Per D-06, max 2 iterations. Per D-05, halt immediately on regression.
-
-**Skip condition:** If all docs passed verification (no failures), skip this step.
-
-**Iteration tracking:**
-- `MAX_FIX_ITERATIONS = 2`
-- `iteration = 0`
-- `previous_passed_docs` = set of doc_paths where claims_failed === 0 after initial verification
+**Skip condition:** if every doc passed verification (no `claims_failed > 0`), skip this step entirely.
 
-**For each iteration (while iteration < MAX_FIX_ITERATIONS and there are docs with failures):**
+Otherwise, correct flagged inaccuracies by re-sending failing docs to `gsd-doc-writer` in `fix` mode (one spawn per doc, never batched), for at most 2 iterations (D-06). Each spawn carries a `<doc_assignment>` block: `type` (the doc's original type), `mode: fix`, `doc_path`, `project_context`, `existing_content` (current file content), and `failures:` — a structured array of `{line, claim, expected, actual}` objects, one per failed claim.
 
-1. For each doc with `claims_failed > 0` in the latest verification_results:
+For each doc with a failure, per iteration:
    a. Read the current file content from disk. Record the pre-fix line count:
       ```bash
       PRE_FIX_LINES=$(wc -l < "{doc_path}" 2>/dev/null || echo 0)
       ```
-   b. Spawn `gsd-doc-writer` agent (or invoke sequentially) with a fix assignment:
-      ```xml
-      <doc_assignment>
-      type: {original doc type from the queue, e.g. readme}
-      mode: fix
-      doc_path: {relative path}
-      project_context: {INIT JSON}
-      existing_content: {current file content read from disk}
-      failures:
-        - line: {line}
-          claim: "{claim}"
-          expected: "{expected}"
-          actual: "{actual}"
-      </doc_assignment>
-      ```
+   b. Spawn `gsd-doc-writer` with the `<doc_assignment>` block above.
    c. One agent spawn per doc with failures. Do not batch multiple docs into one spawn.
    d. **Post-fix truncation guard:** After the fix agent completes, check for file corruption:
       ```bash
@@ -891,90 +823,17 @@ Correct flagged inaccuracies by re-sending failing docs to the doc-writer in fix
       - Mark this doc as `"fix-corrupted"` in the manifest; it will appear in remaining failures at the end
       - Do NOT attempt to fix this doc again this iteration. It is still included in the step 2 re-verification (so its failures are counted) but no further fix agent will be dispatched for it in this iteration.
 
-2. After all fix agents complete, re-verify ALL docs (not just the ones that were fixed):
-   - Re-run the same verification process as verify_docs step.
-   - Read updated result JSONs from `.planning/tmp/verify-{doc_filename}.json`.
-
-3. **Regression detection (D-05):**
-   For each doc in the new verification_results:
-   - If this doc was in `previous_passed_docs` (passed in the prior round) AND now has `claims_failed > 0`, this is a REGRESSION.
-   - If regression detected: HALT the loop immediately. Present:
-     ```
-     REGRESSION DETECTED -- halting fix loop.
-
-     {doc_path} previously passed verification but now has {claims_failed} failures after fix iteration {iteration + 1}.
-
-     This means the fix introduced new errors. Remaining failures require manual review.
-     ```
-     Continue to scan_for_secrets (do not attempt further fixes).
-
-4. Update `previous_passed_docs` with docs that now pass.
-5. Increment `iteration`.
+After each iteration's fix agents complete, re-verify ALL docs and check for regression (D-05): any doc that previously passed and now fails HALTS the loop immediately — remaining failures require manual review, no further fixes attempted. After 2 iterations with failures remaining, report them and continue.
 
-**After loop exhaustion (iteration === MAX_FIX_ITERATIONS and failures remain):**
+Continue to scan_for_secrets either way.
 
-Present remaining failures:
-```
-Fix loop completed ({MAX_FIX_ITERATIONS} iterations). Remaining failures:
-
-| Doc               | Failed Claims |
-|-------------------|---------------|
-| {doc_path}        | {count}       |
-
-These failures require manual correction. Review the verification output in .planning/tmp/verify-*.json for details.
-```
-
-Continue to scan_for_secrets.
+Exact iteration bookkeeping and the regression-halt report wording: `gsd-core/workflows/docs-update/detail/elaboration.md` § 2.
 </step>
 
 <step name="verify_only_report">
-**Reached when `--verify-only` is present in `$ARGUMENTS`.** This is an early-exit step — do not proceed to dispatch, generation, commit, or report steps after this step.
-
-Invoke the gsd-doc-verifier agent in read-only mode for each file in `existing_docs` from the init JSON:
-
-1. For each doc in `existing_docs`:
-   a. Spawn `gsd-doc-verifier` (or invoke sequentially if Task tool is unavailable), passing `model="{DOC_VERIFIER_MODEL}"` as the Task/Agent call's `model` parameter — not part of the `<verify_assignment>` prompt — so `dynamic_routing`/`model_profile` tiers apply instead of the caller's session model (#3602). Omit the parameter entirely when the value is `"inherit"` or empty (#2517). Each spawn carries:
-      ```xml
-      <verify_assignment>
-      doc_path: {doc.path}
-      project_root: {project_root from init JSON}
-      </verify_assignment>
-      ```
-   b. Read the result JSON from `.planning/tmp/verify-{doc_filename}.json`.
-
-2. Also count VERIFY markers in each doc: grep for `<!-- VERIFY:` in the file content.
-
-Present a combined summary table:
-
-```
---verify-only audit:
-
-| File                     | Claims Checked | Passed | Failed | VERIFY Markers |
-|--------------------------|----------------|--------|--------|----------------|
-| README.md                | 12             | 10     | 2      | 0              |
-| docs/ARCHITECTURE.md     | 8              | 8      | 0      | 0              |
-| docs/CONFIGURATION.md    | 5              | 3      | 2      | 5              |
-| ...                 | ...            | ...    | ...    | ...            |
-
-Total: {total_checked} claims checked, {total_failed} failures, {total_markers} VERIFY markers requiring manual review
-```
-
-If any failures exist, show details:
-```
-Failed claims:
-  README.md:34 - "src/cli/index.ts" (expected: file exists, actual: file not found)
-  docs/CONFIGURATION.md:12 - "npm run deploy" (expected: script in package.json, actual: script not found)
-```
-
-Display note:
-```
-To fix failures automatically: /gsd:docs-update (runs generation + fix loop)
-To regenerate all docs from scratch: /gsd:docs-update --force
-```
-
-Clean up temp files: remove `.planning/tmp/verify-*.json` files.
+**Reached when `--verify-only` is present in `$ARGUMENTS`** — an early-exit reporting mode: do not proceed to dispatch, generation, commit, or report steps after this step. Spawn `gsd-doc-verifier` (read-only) for every file in `existing_docs`, count `<!-- VERIFY:` markers in each, and present a combined claims-checked/passed/failed/markers table plus a "how to fix" pointer to `/gsd:docs-update` (or `--force` to regenerate everything). Clean up `.planning/tmp/verify-*.json` afterward. End the workflow here.
 
-End workflow — do not proceed to any dispatch, commit, or report steps.
+Exact table format and failure-detail wording: `gsd-core/workflows/docs-update/detail/elaboration.md` § 3.
 </step>
 
 <step name="scan_for_secrets">

package/gsd-core/workflows/execute-phase/detail/elaboration.md

@@ -0,0 +1,124 @@
+# execute-phase.md — deferred elaboration
+
+Read in full when `workflow.compact_content` is `false` (the default) — see
+`gsd-core/references/compact-content-gate.md` for the check and resolution rule this
+spine defers to. Each `§` below is the full text the spine condenses at the point it
+names.
+
+(safe_resume_gate, checkpoint_handling, and auto_copy_learnings are stated verbatim in the
+spine itself — pre-existing structural drift guards in this repo's test suite pin their exact
+wording and bash there, so nothing about them is deferred to this file.)
+
+## § 1 — check_interactive_mode
+
+**Parse `--interactive` flag from $ARGUMENTS.**
+
+**If `--interactive` flag present:** Switch to interactive execution mode.
+
+Interactive mode executes plans sequentially **inline** (no subagent spawning) with user
+checkpoints between tasks. The user can review, modify, or redirect work at any point.
+
+**Interactive execution flow:**
+
+1. Load plan inventory as normal (discover_and_group_plans)
+2. For each plan (sequentially, ignoring wave grouping):
+
+   a. **Present the plan to the user:**
+      ```
+      ## Plan {plan_id}: {plan_name}
+
+      Objective: {from plan file}
+      Tasks: {task_count}
+
+      Options:
+      - Execute (proceed with all tasks)
+      - Review first (show task breakdown before starting)
+      - Skip (move to next plan)
+      - Stop (end execution, save progress)
+      ```
+
+   b. **If "Review first":** Read and display the full plan file. Ask again: Execute, Modify, Skip.
+
+   c. **If "Execute":** Read and follow `~/.claude/gsd-core/workflows/execute-plan.md` **inline**
+      (do NOT spawn a subagent). Execute tasks one at a time.
+
+   d. **After each task:** Pause briefly. If the user intervenes (types anything), stop and address
+      their feedback before continuing. Otherwise proceed to next task.
+
+   e. **After plan complete:** Show results, commit, create SUMMARY.md, then present next plan.
+
+3. After all plans: proceed to verification (same as normal mode).
+
+(The spine's own condensed text already states the handle_branching hand-off; not repeated here.)
+
+## § 2 — cross_ai_delegation
+
+**Optional step 2.5 — Delegate plans to an external AI runtime.**
+
+This step runs after plan discovery and before normal wave execution. It identifies plans
+that should be delegated to an external AI command and executes them via stdin-based prompt
+delivery. Plans handled here are removed from the execute_waves plan list so the normal
+executor skips them.
+
+**Activation logic:**
+
+1. If `CROSS_AI_DISABLED` is true (`--no-cross-ai` flag): skip this step entirely.
+2. If `CROSS_AI_FORCE` is true (`--cross-ai` flag): mark ALL incomplete plans for cross-AI execution.
+3. Otherwise: check each plan's frontmatter for `cross_ai: true` AND verify config
+   `workflow.cross_ai_execution` is `true`. Plans matching both conditions are marked for cross-AI.
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+CROSS_AI_ENABLED=$(gsd_run query config-get workflow.cross_ai_execution --raw 2>/dev/null || echo "false")
+CROSS_AI_CMD=$(gsd_run query config-get workflow.cross_ai_command --raw 2>/dev/null || echo "")
+CROSS_AI_TIMEOUT=$(gsd_run query config-get workflow.cross_ai_timeout --raw 2>/dev/null || echo "300")
+```
+
+**If no plans are marked for cross-AI:** Skip to execute_waves.
+
+**If plans are marked but `cross_ai_command` is empty:** Error — tell user to set
+`workflow.cross_ai_command` via `gsd_run query config-set workflow.cross_ai_command "<command>"`.
+
+**For each cross-AI plan (sequentially):**
+
+1. **Construct the task prompt** from the plan file:
+   - Extract `<objective>` and `<tasks>` sections from the PLAN.md
+   - Append PROJECT.md context (project name, description, tech stack)
+   - Format as a self-contained execution prompt
+
+2. **Check for dirty working tree before execution:**
+   ```bash
+   if ! git diff --quiet HEAD 2>/dev/null; then
+     echo "WARNING: dirty working tree detected — the external AI command may produce uncommitted changes that conflict with existing modifications"
+   fi
+   ```
+
+3. **Run the external command** from the project root, writing the prompt to stdin.
+   Never shell-interpolate the prompt — always pipe via stdin to prevent injection:
+   ```bash
+   echo "$TASK_PROMPT" | gsd_run run-with-timeout "${CROSS_AI_TIMEOUT}" -- ${CROSS_AI_CMD} > "$CANDIDATE_SUMMARY" 2>"$ERROR_LOG"
+   EXIT_CODE=$?
+   ```
+
+4. **Evaluate the result:**
+
+   **Success (exit 0 + valid summary):**
+   - Read `$CANDIDATE_SUMMARY` and validate it contains meaningful content
+     (not empty, has at least a heading and description — a valid SUMMARY.md structure)
+   - Write it as the plan's SUMMARY.md file
+   - Update STATE.md plan status to complete
+   - Update ROADMAP.md progress
+   - Mark plan as handled — skip it in execute_waves
+
+   **Failure (non-zero exit or invalid summary):**
+   - Display the error output and exit code
+   - Warn: "The external command may have left uncommitted changes or partial edits
+     in the working tree. Review `git status` and `git diff` before proceeding."
+   - Offer three choices:
+     - **retry** — run the same plan through cross-AI again
+     - **skip** — fall back to normal executor for this plan (re-add to execute_waves list)
+     - **abort** — stop execution entirely, preserve state for resume
+
+5. **After all cross-AI plans processed:** Remove successfully handled plans from the
+   incomplete plan list so execute_waves skips them. Any skipped-to-fallback plans remain
+   in the list for normal executor processing.

package/gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md

@@ -79,7 +79,6 @@ Today's date: {date}
 --paths {affected_paths joined by comma}
 
 Refresh STRUCTURE.md and ARCHITECTURE.md scoped to the listed paths only.
-Stamp last_mapped_commit in each document's frontmatter.
 ${AGENT_SKILLS_MAPPER}"
 )
 ```
@@ -90,8 +89,24 @@ If the spawn fails or the agent reports an error: log `Codebase drift
 auto-remap failed: {reason}` and continue to `verify_phase_goal`. The phase
 is NOT failed by a remap failure.
 
-If the remap succeeds: log `Codebase drift auto-remap completed for paths:
-{affected_paths}` and continue to `verify_phase_goal`.
+If the remap succeeds, stamp the new baseline into the two documents the
+mapper just refreshed:
+
+```bash
+gsd_run stamp-codebase-map --files STRUCTURE.md,ARCHITECTURE.md
+```
+
+The stamp is a shell step, not a line in the mapper's prompt. An agent that
+concludes its work is already done skips a prose instruction silently, and the
+stamp is the one marker no human reviewing the documents would notice missing
+(#3418). `--files` is scoped to what this step actually refreshed -- the other
+five documents were not remapped and must not claim currency at HEAD.
+
+Only stamp on success: stamping after a failed remap would record a baseline
+the map never reached.
+
+Then log `Codebase drift auto-remap completed for paths: {affected_paths}` and
+continue to `verify_phase_goal`.
 
 The two relevant config keys (continue on error / failure if either is invalid):
 - `workflow.drift_threshold` (integer, default 3) — minimum drift elements before action

package/gsd-core/workflows/execute-phase/steps/completion-reconciliation.md

@@ -0,0 +1,56 @@
+# Completion reconciliation (#4217, split A of #3754)
+
+Read and follow this fragment from `execute-phase.md` step 4 whenever an executor's
+completion is in question. It owns the whole reconciliation policy — both arms — so the
+host wait step stays inside the ADR-857 Phase 6 byte ceiling (#1168).
+
+**Reconcile FIRST, classify SECOND.** How the child's session ended is bookkeeping
+about the transport; what it wrote to disk and to git is the evidence about the work.
+
+## When this runs
+
+1. **No terminal response** — a spawned agent does not return a normal terminal
+   completion signal but appears to have finished its work (or may still be running).
+2. **Abnormal end** — the child's session ended without a normal terminal completion
+   response: interrupted, aborted, closed, killed, timed out, or ended `turn_aborted` —
+   INCLUDING ends the orchestrator itself initiated. **An abnormally-ended child is
+   not evidence of failure (#4217):** the orchestrator's own interrupt/close says
+   nothing about whether the work completed; only the artifacts do.
+
+This policy applies to EVERY runtime and every isolation path — harness `Agent()`
+dispatches, orchestrator-worktree process spawns, and sequential dispatch alike. Never
+block indefinitely waiting for a signal; verify via filesystem and git state.
+
+## Probes (per plan in the wave)
+
+```bash
+# For each plan in this wave, check if the executor finished:
+SUMMARY_EXISTS=$(test -f "{phase_dir}/{plan_number}-{plan_padded}-SUMMARY.md" && echo "true" || echo "false")
+# #4003: anchored, zero-pad-tolerant scope (see safe_resume_gate); --since stays.
+SPOT_PHASE_NUMBER="{phase_number}"
+# #4619: same decimal/N-segment handling as safe_resume_gate.
+SPOT_PHASE_INT=${SPOT_PHASE_NUMBER%%.*}; SPOT_PHASE_FRAC=${SPOT_PHASE_NUMBER#"$SPOT_PHASE_INT"}
+SPOT_PHASE_N="$((10#$SPOT_PHASE_INT))${SPOT_PHASE_FRAC//./\\.}"
+SPOT_PLAN_N=$((10#{plan_padded}))
+COMMITS_FOUND=$(git log --oneline --all -E --grep="^[a-z]+\((0*${SPOT_PHASE_N})-(0*${SPOT_PLAN_N})\):" --since="1 hour ago" | head -1)
+COMMITS_SINCE_DISPATCH=$(git log "${EXPECTED_BRANCH}" --since="${DISPATCH_TS}" --oneline | head -1)
+```
+
+## Verdicts
+
+**If SUMMARY.md exists AND matching commits are found:** the agent completed
+successfully — treat the plan as complete WITHOUT requiring another terminal child
+response, proceed to step 5, and do NOT re-dispatch a fresh executor for this plan:
+the work is already committed, and a second executor would redo it on top of itself.
+Log: `"✓ {Plan ID} completed (verified via spot-check — completion signal not received)"`.
+
+**If SUMMARY.md does NOT exist after a reasonable wait:** the agent may still be
+running or may have failed silently. Check `git log --oneline -5` for recent
+activity. If commits are still appearing, wait longer. If no activity, report the
+plan as failed and route to the failure handler in step 6.
+
+Evidence is BOTH probes or neither: a SUMMARY without matching commits, and matching
+commits without a SUMMARY, are each incomplete evidence — never auto-complete on one
+of them. When an abnormal end reconciles to no completion evidence, it stays failed:
+route to the failure handler exactly as a normal failure would, and let the
+safe-resume gate handle any un-summarized commits on the next run.

package/gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md

@@ -149,8 +149,12 @@ Assign the composed prompt to a shell variable so it can be passed as one argume
 #      An unreadable source file is a halt condition (#3637 fail-closed),
 #      never a skip — a child without these texts is not a gsd-executor.
 #   2. Substitute this plan's {plan_number}, {phase_number}, {phase_name},
-#      {phase_dir}, and {plan_file} placeholders (same values the harness
-#      path substitutes into its Agent() prompt).
+#      {phase_dir}, {plan_file}, and {plan_id} placeholders (same values the
+#      harness path substitutes into its Agent() prompt). {plan_id} is this
+#      plan's `id` field from the phase-plan-index JSON — the guard hooks
+#      compare it verbatim against the sentinel the per-plan gate wrote, so a
+#      paraphrase or omission costs the dispatch its recorded isolation
+#      decision.
 #   3. Inline the gsd-executor ROLE DEFINITION: read `agents/gsd-executor.md`
 #      (resolved against the install root the same way the harness runtime
 #      resolves subagent types) and inline it verbatim at the provenance
@@ -175,6 +179,7 @@ TDD_APPLICABLE="$_TDD_APPLICABLE_RAW"
 
 EXECUTOR_PROMPT='<objective>
 Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+[gsd:dispatch phase="{phase_number}" plan="{plan_id}"]
 Commit each task atomically. Create SUMMARY.md.
 Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
 </objective>