gsdd-cli 0.19.1 → 0.19.3

package/agents/DISTILLATION.md

@@ -54,7 +54,7 @@ Evidence map from each of the 10 canonical GSDD roles to their GSD sources, with
 - Explicit "Scope" table showing scope × trigger × focus × output location
 - Clear statement: "Same algorithm, different scope. The scope is a context input, not a different role."
 
-**Rationale:** The GSD original had two roles (project and phase researcher) that followed the identical algorithm but with a scope parameter. GSDD merged them into one canonical role taking scope as input, reducing the role count from 11 to 9 (later 10 with approach-explorer in D29) while preserving all leverage. This is the clean merger mentioned in D2.
+**Rationale:** The GSD original had two roles (project and phase researcher) that followed the identical algorithm but with a scope parameter. GSDD merged them into one canonical role taking scope as input, reducing duplicate role contracts while preserving the current 10-role catalog. This is the clean merger mentioned in D2.
 
 ---
 
@@ -362,11 +362,23 @@ Cross-source best practices applied to GSDD role contracts, audited against 6 ex
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
-| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic "Building effective agents" (Dec 2024): orchestrator-worker pattern — sub-agents do deep technical work and return condensed summaries | Approach explorer research subagents return ~1000-token summaries; plan-checker runs in fresh context |
+| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic "Building effective agents" (Dec 2024): orchestrator-worker pattern — sub-agents do deep technical work and return condensed summaries | Approach explorer research subagents return 500-800 token agent-mediated summaries; plan-checker runs in fresh context |
 | **JIT context loading** | Never say "read everything." Specify what to extract from each file | LangChain "Context Engineering for Agents" (2025): Select step of Write/Select/Compress/Isolate — load only the specific content needed, not full files | `<input_contract>` with extraction guidance: "From SPEC.md read ONLY locked decisions" |
 | **Intermediate persistence** | For long interactions, write confirmed state to disk incrementally | Anthropic BEA: agent memory outside context window. LangChain CE: Write pattern — confirmed state persisted to disk | Approach explorer writes decisions to disk as they're confirmed during conversation |
 | **Progressive disclosure** | Don't front-load all context; let agents discover incrementally | LangChain CE: Compress/Isolate patterns — agents assemble understanding incrementally rather than loading everything upfront | Gray areas presented individually; research loaded per area on demand |
 
+### Subagent Return Tiers
+
+Use the smallest return that preserves the downstream decision. Full documents stay on disk unless a role explicitly owns a durable artifact update.
+
+| Tier | Use When | Return Size |
+|------|----------|-------------|
+| Routing summary | The orchestrator only needs a signal, category, or next-step recommendation | 100-200 tokens |
+| Human-read summary | The user will read the summary directly to understand options or findings | 300-500 tokens |
+| Agent-mediated discussion | The orchestrator must discuss findings with the user and answer follow-up questions without re-querying the subagent | 500-800 tokens |
+
+This replaces the prior mixed guidance around sentence-count summaries, single-tier token budgets, and larger undifferentiated summaries. The deliberate boundary is conservative: subagents are useful for read-heavy or artifact-backed isolation, not for hidden implementation orchestration or overlapping writes without explicit write-set ownership.
+
 ### Prompt Structure (medium leverage)
 
 | Principle | What It Means | Source | GSDD Implementation |
@@ -381,7 +393,7 @@ Cross-source best practices applied to GSDD role contracts, audited against 6 ex
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
-| **Authority language: intentional leverage** | Anthropic Claude warns "CRITICAL:" can overtrigger on newer models. GSDD decision: **keep CRITICAL: for mandatory initial-read** — a genuine compliance-critical instruction where skipping causes cascading failures. Emphasis markers work when rare and specific (signal-to-noise principle: one CRITICAL: in a role contract is a load-bearing gate; ten would be noise). Use normal language for algorithm steps, scope guidance, and quality rules. | Anthropic Claude prompting docs (overtriggering caution) + technical writing signal-to-noise principle. GSDD applies the caution selectively: only compliance-critical context gates use CRITICAL: | `CRITICAL: Mandatory initial read` kept in all 7 roles. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
+| **Authority language: intentional leverage** | Anthropic Claude warns "CRITICAL:" can overtrigger on newer models. GSDD decision: keep `CRITICAL:` only for compliance-critical context gates where skipping causes cascading failures. Emphasis markers work when rare and specific (signal-to-noise principle: one CRITICAL: in a role contract is a load-bearing gate; ten would be noise). Use normal language for algorithm steps, scope guidance, and quality rules. | Anthropic Claude prompting docs (overtriggering caution) + technical writing signal-to-noise principle. GSDD applies the caution selectively: only compliance-critical context gates use CRITICAL: | Most roles keep `CRITICAL: Mandatory initial read`; executor now uses `CRITICAL: Tiered context intake` so mandatory-now, task-scoped, reference-only, and conditional reads replace blanket preload. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
 | **Tell what to do, not just what not to do** | Anti-patterns alone are insufficient; pair with positive instructions | Anthropic Claude: "Tell Claude what to do instead of what not to do" | Every role has both `<anti_patterns>` AND positive algorithm/process sections |
 | **Context for instructions** | Explain WHY a rule exists so the agent can generalize | Anthropic Claude: "Providing context or motivation behind your instructions helps Claude better understand your goals" | Research quality rules explain WHY: "Training data is a hypothesis. Verify before asserting." |
 
@@ -417,5 +429,5 @@ When sources conflict, these resolutions apply:
 |----------|------------|-----|
 | Authority language ("YOU MUST" vs. normal) | Keep CRITICAL: for mandatory initial-read (compliance-critical). Use normal language elsewhere | Emphasis markers work when rare and specific (signal-to-noise). Anthropic's overtriggering concern applies to general guidance; a single CRITICAL: for a mandatory context gate is a load-bearing instruction, not noise |
 | Example count (2 vs. 3-5) | Target 3+ for conversational agents; inline format examples are sufficient for structured output agents | Anthropic's 3-5 recommendation is general; interactive roles benefit more than output-only roles |
-| Subagent return size (200 vs. 1000-2000 tokens) | Use 300-500 tokens | Anthropic's 1000-2000 is upper bound; 200 was too tight for structured approach summaries with trade-offs |
+| Subagent return size (200 vs. 1000-2000 tokens) | Use the three-tier return model: 100-200 for routing, 300-500 for human-read summaries, and 500-800 for agent-mediated discussion | Anthropic's 1000-2000 is an upper bound; 200 is too tight for structured approach summaries with trade-offs, while returning full raw research defeats context isolation |
 | "Don't invent alternatives" vs. "try fallback strategies" | Keep "don't invent" for approach research; use fallbacks for information retrieval | These solve different problems: manufacturing fake options is worse than acknowledging one viable path |

package/agents/README.md

@@ -11,8 +11,20 @@ Vendor-agnostic role contracts for Workspine's agent architecture.
 
 Roles define what an agent is. Delegates define what an agent does in a specific workflow context.
 
+## Deliberate Subagent Boundary
+
+Workspine uses subagents when isolation earns its cost: research, review, mapping, synthesis, and integration checks may run as read-only or artifact-backed delegation, with summaries returned to the orchestrator and full detail written to disk when detail is needed later.
+
+Subagents must not become hidden implementation orchestration. Implementation remains plan-scoped and write-set constrained; overlapping implementation writes require explicit write-set ownership in the approved plan before any parallelism is safe.
+
+Roadmapper is intentionally role-only/direct invocation in the current catalog. There is no roadmapper delegate because roadmap creation is sequential, coverage-sensitive, and writes `.planning/ROADMAP.md`; a future delegate would need a proven thin-wrapper use case before it is added.
+
+Leverage record: lost flexibility to add delegates by symmetry; kept the two-layer role/delegate architecture and summaries-up/documents-to-disk model; gained a conservative boundary that prevents subagents from implying agent teams, parallel PR orchestration, or runtime parity claims.
+
 ## Lifecycle Roles
 
+The catalog contains 10 canonical roles across lifecycle, audit, and utility responsibilities.
+
 | Role | File | Absorbs From (GSD) |
 |------|------|---------------------|
 | Mapper | `mapper.md` | `gsd-codebase-mapper.md` |

package/agents/approach-explorer.md

@@ -90,7 +90,7 @@ Generate 3-4 **phase-specific** gray areas. Not generic categories — concrete
 
 ## Step 3: Research Approaches (Technical and Hybrid Only)
 
-For each technical or hybrid gray area, research 2-3 viable approaches.
+For each technical or hybrid gray area, use a read-only research subagent when isolation earns its cost, then research 2-3 viable approaches.
 
 **Source hierarchy:**
 1. Existing codebase — what patterns are already established?
@@ -311,7 +311,7 @@ Ready for assumptions?"
 
 <research_subagent_prompt>
 
-When the orchestrator spawns a read-only research subagent for a technical or hybrid gray area, use this prompt template. Substitute the bracketed values. One subagent is spawned per gray area.
+When the orchestrator spawns a read-only research subagent for a technical or hybrid gray area, use this prompt template. Substitute the bracketed values. One subagent is spawned per gray area and returns an agent-mediated discussion summary, not raw notes.
 
 ```
 You are a research subagent for approach exploration. Your job: investigate viable approaches for ONE gray area and return a compressed structured summary. You do NOT interact with the user — read, search, and return findings only.
@@ -341,9 +341,9 @@ Training data is a hypothesis. Verify before asserting. Do NOT recommend a libra
 - Do NOT recommend deprecated or unmaintained libraries
 - Do NOT present "roll your own" as an approach unless existing libraries genuinely fail to solve the problem
 - Do NOT include approaches you cannot source
-- Do NOT exceed 1000 tokens in your response
+- Do NOT exceed 800 tokens in your response
 
-## Output Format (under 1000 tokens)
+## Output Format (500-800 tokens)
 
 For each of 2-3 viable approaches:
 - **Name**

package/agents/integration-checker.md

@@ -5,7 +5,7 @@
 <role>
 You are an integration checker. You verify that phases work together as a system, not just individually.
 
-Your job: check cross-phase wiring, API coverage, auth protection, and end-to-end user flows. Return a structured report to the milestone auditor.
+Your job: check cross-phase wiring, API coverage, auth protection, and end-to-end user flows. This is read-only verification: inspect artifacts and code, return a structured report to the milestone auditor, and do not write implementation changes.
 
 CRITICAL: Mandatory initial read
 
@@ -283,7 +283,7 @@ The integration checker is milestone-scoped:
 - maps each milestone requirement to its integration path
 - does NOT verify single-phase goal completion; that is the verifier's job
 - does NOT run the application or execute tests; this is static analysis
-- does NOT write output to disk; it returns a structured report to the milestone auditor
+- does NOT write output to disk or mutate source files; it is a read-only subagent-style check that returns a structured report to the milestone auditor
   </scope_boundary>
 
 <anti_patterns>

package/agents/mapper.md

@@ -19,7 +19,7 @@ Accountable for producing accurate, file-path-rich analysis of an existing codeb
   - `arch` -> ARCHITECTURE.md
   - `quality` -> CONVENTIONS.md
   - `concerns` -> CONCERNS.md
-- **Return:** Brief confirmation (document names + line counts). NOT document contents -- the point is reducing context transfer to the orchestrator.
+- **Return:** Routing summary only (100-200 tokens: document names, line counts, and the highest-signal flags). NOT document contents -- the point is reducing context transfer to the orchestrator while the full artifacts stay on disk.
 
 ## Downstream Consumers
 
@@ -39,7 +39,7 @@ This means: file paths are critical (planner needs to navigate directly), patter
 2. **Explore the codebase** thoroughly for the assigned focus area. Use file listing, content search, and targeted file reads. Read actual code -- do not guess.
 3. **Fill the document template** with findings. Replace all placeholders with real data. Use "Not detected" for genuinely absent items.
 4. **Write document(s)** to the designated output directory.
-5. **Return confirmation only** -- document names and line counts. Do not echo contents back.
+5. **Return summary only** -- document names, line counts, and highest-signal flags. Do not echo contents back.
 
 ## Focus Area Guidance
 

package/agents/planner.md

@@ -10,6 +10,7 @@ Your job:
 - decompose the phase into dependency-aware plans and waves
 - derive must-haves from the phase goal
 - return structured planning output instead of prose-only recommendations
+- use research or checker subagents only for read-only or fresh-context review; do not plan hidden implementation orchestration
 
 CRITICAL: Mandatory initial read — if the prompt contains a `<files_to_read>` block, read every file listed there before doing any other work. That is your primary context.
 </role>
@@ -176,6 +177,7 @@ Wave 3: C
 Wave rule:
 - if a task's verify step depends on a test file or artifact, an earlier wave must create it
 - if two tasks touch the same critical file or one task's output is another task's input, they are not parallel
+- parallel implementation is allowed only when the approved plan names explicit, disjoint write-set ownership
 </dependency_graph_example>
 
 <output>

package/agents/researcher.md

@@ -26,7 +26,7 @@ Same algorithm, different scope. The scope is a context input, not a different r
 
 - **Artifacts (project scope):** STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md (+ COMPARISON.md or FEASIBILITY.md if applicable mode)
 - **Artifacts (phase scope):** Single RESEARCH.md with sections: Standard Stack, Architecture Patterns, Don't Hand-Roll, Common Pitfalls, Code Examples
-- **Return:** Structured summary with key findings, confidence assessment, and open questions
+- **Return:** Human-read structured summary (300-500 tokens) with key findings, confidence assessment, and open questions. Do not return raw research; full detail belongs in the written artifact.
 
 ## Core Algorithm
 
@@ -43,7 +43,7 @@ Same algorithm, different scope. The scope is a context input, not a different r
    - Single unverified source -> LOW confidence, flag for validation
 5. **Run quality checklist:** All domains investigated? Negative claims verified with official docs? Multiple sources for critical claims? Confidence levels assigned honestly?
 6. **Write output files** to the designated directory.
-7. **Return structured result** to orchestrator. Do not commit -- orchestrator handles git.
+7. **Return structured summary** to orchestrator. Do not return raw research and do not commit -- orchestrator handles git.
 
 ## Quality Guarantees
 

package/agents/roadmapper.md

@@ -5,6 +5,8 @@
 <role>
 You are a roadmapper. You turn requirements into a phased delivery plan that downstream planners can execute without guessing.
 
+Roadmapper is role-only/direct invocation in the current Workspine contract, not a delegate. Roadmap creation is sequential, coverage-sensitive, and owns `.planning/ROADMAP.md`; do not route it through a hidden subagent wrapper unless a future plan explicitly adds that delegate.
+
 Your job:
 - derive phases from requirements instead of imposing a template
 - map every in-scope requirement to exactly one phase
@@ -292,5 +294,5 @@ If a section does not improve requirement coverage, dependency order, or observa
 ## Vendor Hints
 
 - **Tools required:** file read, file write, content search
-- **Parallelizable:** No - roadmapping is sequential and coverage-sensitive
+- **Parallelizable:** No - roadmapping is sequential, coverage-sensitive, and writes `.planning/ROADMAP.md` directly
 - **Context budget:** Moderate - the reasoning work is heavier than the I/O

package/agents/synthesizer.md

@@ -9,7 +9,7 @@ Your job:
 - read the full research outputs
 - extract the most decision-relevant findings
 - cross-reference them into roadmap implications
-- return a structured handoff the roadmapper can use directly
+- return an agent-mediated structured summary the roadmapper can use directly
 
 CRITICAL: Mandatory initial read
 
@@ -75,7 +75,7 @@ Assign confidence by area based on source quality and identify any unresolved ga
 
 ## Step 6: Write the summary and return a structured handoff
 
-Write `.planning/research/SUMMARY.md`. Return a short structured summary to the orchestrator.
+Write `.planning/research/SUMMARY.md`. Return a 500-800 token structured summary to the orchestrator so downstream discussion can preserve recommendation reasoning without returning the full document.
 </execution_flow>
 
 <cross_reference_dimensions>

package/bin/lib/health-truth.mjs

@@ -94,7 +94,7 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, option
     warnings.push({
       id: 'W11',
       severity: 'WARN',
-      message: `Installed generated runtime and workflow-helper surfaces drift from current render output (${summarizeRuntimeFreshnessIssues(options.runtimeFreshnessReport)})`,
+      message: `Renderer-backed generated runtime and workflow-helper surfaces drift from current render output (${summarizeRuntimeFreshnessIssues(options.runtimeFreshnessReport)})`,
       fix: getRuntimeFreshnessRepairGuidance(options.runtimeFreshnessReport),
     });
   }

package/bin/lib/health.mjs

@@ -164,10 +164,10 @@ export function createCmdHealth(ctx) {
         if (!cat.hashes) continue;
         const result = detectModifications(cat.dir, cat.hashes);
         if (result.modified.length > 0) {
-          warnings.push({ id: 'W2', severity: 'WARN', message: `${cat.name}: ${result.modified.length} file(s) modified locally (${result.modified.join(', ')})`, fix: `Intentional? Run \`${cat.fixCommand}\` to reset` });
+          warnings.push({ id: 'W2', severity: 'WARN', message: `${cat.name}: ${result.modified.length} manifest-tracked installed file(s) modified locally (${result.modified.join(', ')})`, fix: `Intentional? Run \`${cat.fixCommand}\` to reset` });
         }
         if (result.missing.length > 0) {
-          warnings.push({ id: 'W3', severity: 'WARN', message: `${cat.name}: ${result.missing.length} file(s) missing from disk (${result.missing.join(', ')})`, fix: `Run \`${cat.fixCommand}\` to restore` });
+          warnings.push({ id: 'W3', severity: 'WARN', message: `${cat.name}: ${result.missing.length} manifest-tracked installed file(s) missing from disk (${result.missing.join(', ')})`, fix: `Run \`${cat.fixCommand}\` to restore` });
         }
       }
     }
@@ -201,16 +201,9 @@ export function createCmdHealth(ctx) {
       }
     }
 
-    // W6: No adapter surfaces detected
-    const adapterPaths = [
-      join(cwd, '.agents', 'skills'),
-      join(cwd, '.claude'),
-      join(cwd, '.opencode'),
-      join(cwd, '.codex'),
-    ];
-    const hasAnyAdapter = adapterPaths.some((p) => existsSync(p));
-    if (!hasAnyAdapter) {
-      warnings.push({ id: 'W6', severity: 'WARN', message: 'No adapter surfaces detected', fix: 'Run `npx -y gsdd-cli init --tools <platform>`' });
+    // W6: No generated workflow adapter surfaces detected
+    if (!hasAnyGeneratedWorkflowSurface(cwd)) {
+      warnings.push({ id: 'W6', severity: 'WARN', message: 'No generated workflow adapter surfaces detected', fix: 'Run `npx -y gsdd-cli init --tools <platform>`' });
     }
 
     const runtimeFreshnessReport = configOk && Array.isArray(ctx.workflows)
@@ -245,15 +238,15 @@ export function createCmdHealth(ctx) {
       });
     }
 
-    // I3: Which adapters are installed
-    const installedAdapters = [];
-    if (existsSync(join(cwd, '.agents', 'skills'))) installedAdapters.push('open-standard-skills');
-    if (existsSync(join(cwd, '.claude'))) installedAdapters.push('claude');
-    if (existsSync(join(cwd, '.opencode'))) installedAdapters.push('opencode');
-    if (existsSync(join(cwd, '.codex'))) installedAdapters.push('codex');
-    if (existsSync(join(cwd, 'AGENTS.md'))) installedAdapters.push('agents');
-    if (installedAdapters.length > 0) {
-      info.push({ id: 'I3', severity: 'INFO', message: `Adapters installed: ${installedAdapters.join(', ')}` });
+    // I3: Which runtime/governance surfaces are installed
+    const installedSurfaces = [];
+    if (hasGeneratedSkillSurface(cwd)) installedSurfaces.push('open-standard-skills');
+    if (hasGeneratedClaudeSurface(cwd)) installedSurfaces.push('claude');
+    if (hasGeneratedOpenCodeSurface(cwd)) installedSurfaces.push('opencode');
+    if (hasGeneratedCodexSurface(cwd)) installedSurfaces.push('codex');
+    if (existsSync(join(cwd, 'AGENTS.md'))) installedSurfaces.push('root AGENTS.md governance-only');
+    if (installedSurfaces.length > 0) {
+      info.push({ id: 'I3', severity: 'INFO', message: `Installed runtime/governance surfaces: ${installedSurfaces.join(', ')}` });
     }
 
     // --- Verdict ---
@@ -281,6 +274,78 @@ export function createCmdHealth(ctx) {
   };
 }
 
+function hasAnyGeneratedWorkflowSurface(cwd) {
+  return hasGeneratedSkillSurface(cwd)
+    || hasGeneratedClaudeEntrySurface(cwd)
+    || hasGeneratedOpenCodeEntrySurface(cwd);
+}
+
+function hasGeneratedSkillSurface(cwd) {
+  return hasGeneratedSkillDirectory(join(cwd, '.agents', 'skills'));
+}
+
+function hasGeneratedClaudeSurface(cwd) {
+  return hasGeneratedClaudeEntrySurface(cwd)
+    || hasGeneratedMarkdownFile(join(cwd, '.claude', 'agents'));
+}
+
+function hasGeneratedClaudeEntrySurface(cwd) {
+  return hasGeneratedSkillDirectory(join(cwd, '.claude', 'skills'))
+    || hasGeneratedMarkdownFile(join(cwd, '.claude', 'commands'));
+}
+
+function hasGeneratedOpenCodeSurface(cwd) {
+  return hasGeneratedOpenCodeEntrySurface(cwd)
+    || hasGeneratedMarkdownFile(join(cwd, '.opencode', 'agents'));
+}
+
+function hasGeneratedOpenCodeEntrySurface(cwd) {
+  return hasGeneratedMarkdownFile(join(cwd, '.opencode', 'commands'))
+}
+
+function hasGeneratedCodexSurface(cwd) {
+  return hasGeneratedTomlFile(join(cwd, '.codex', 'agents'));
+}
+
+function hasGeneratedSkillDirectory(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).some((entry) => {
+      return entry.isDirectory()
+        && entry.name.startsWith('gsdd-')
+        && existsSync(join(dir, entry.name, 'SKILL.md'));
+    });
+  } catch {
+    return false;
+  }
+}
+
+function hasGeneratedMarkdownFile(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).some((entry) => {
+      return entry.isFile() && entry.name.startsWith('gsdd-') && entry.name.endsWith('.md');
+    });
+  } catch {
+    return false;
+  }
+}
+
+function hasGeneratedTomlFile(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).some((entry) => {
+      return entry.isFile() && entry.name.startsWith('gsdd-') && entry.name.endsWith('.toml');
+    });
+  } catch {
+    return false;
+  }
+}
+
 function isFrameworkSourceRepo(cwd) {
-  return existsSync(join(cwd, 'distilled', 'templates')) && existsSync(join(cwd, 'distilled', 'workflows'));
+  if (!existsSync(join(cwd, 'distilled', 'templates')) || !existsSync(join(cwd, 'distilled', 'workflows'))) return false;
+  if (!existsSync(join(cwd, 'bin', 'gsdd.mjs')) || !existsSync(join(cwd, 'package.json'))) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
+    return pkg.name === 'gsdd-cli';
+  } catch {
+    return false;
+  }
 }

package/bin/lib/lifecycle-state.mjs

@@ -274,7 +274,7 @@ export function readBrownfieldChangeState(planningDir) {
     handoffPath,
     title: extractMarkdownHeading(changeArtifact.body),
     changeId: changeArtifact.frontmatter.change || null,
-    currentStatus: changeArtifact.frontmatter.status || extractBulletLabel(currentStatusSection, 'Current posture'),
+    currentStatus: extractBulletLabel(currentStatusSection, 'Current posture') || changeArtifact.frontmatter.status || null,
     currentIntegrationSurface: extractBulletLabel(currentStatusSection, 'Current branch / integration surface'),
     currentOwnerRuntime: extractBulletLabel(currentStatusSection, 'Current owner / runtime'),
     nextAction: collapseMarkdownSection(nextActionSection),

package/distilled/DESIGN.md

@@ -71,6 +71,7 @@
 58. [Local Workflow Helper Launcher](#d58---local-workflow-helper-launcher)
 59. [Continuity Authority And Planning-State Drift](#d59---continuity-authority-and-planning-state-drift)
 60. [Release Closeout Contract](#d60---release-closeout-contract)
+61. [Deliberate Subagent Contract](#d61---deliberate-subagent-contract)
 
 ---
 
@@ -285,11 +286,11 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 
 | researchDepth | Synthesizer behavior                                                                                                                                                                              |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fast`        | Orchestrator writes SUMMARY.md inline from the 4 x 3-5 sentence summaries it holds in context. No delegate spawned.                                                                               |
+| `fast`        | Orchestrator writes SUMMARY.md inline from the 4 human-read structured summaries it holds in context. No delegate spawned.                                                                         |
 | `balanced`    | ResearchSynthesizer delegate spawned. Reads 4 full research files. Cross-references build order constraints, pitfall-to-phase mappings, feature-architecture conflicts that short summaries omit. |
 | `deep`        | Same as balanced but researchers produce longer output (more material for synthesizer to cross-reference).                                                                                        |
 
-**Why conditional:** The synthesizer's value is in cross-referencing specific data across research dimensions. When `researchDepth=fast`, researchers produce 3-5 sentence summaries only -- there's nothing substantive to cross-reference. Spawning a synthesizer to reformat 4 short paragraphs wastes a context window and an agent hop.
+**Why conditional:** The synthesizer's value is in cross-referencing specific data across research dimensions. When `researchDepth=fast`, researchers return compact summaries and the full research files remain available on disk; spawning a synthesizer to reformat shallow inputs wastes a context window and an agent hop.
 
 **Evidence:**
 
@@ -442,7 +443,7 @@ Codex CLI is skills-first because the terminal CLI supports repository skills di
 
 **GSDD:** Makes this explicit as a design rule.
 
-**The rule:** Delegates write full documents to disk. They return 3-5 sentence summaries to the orchestrator. The orchestrator never receives document contents in its conversation context.
+**The rule:** Delegates write full documents to disk. They return bounded summaries to the orchestrator: routing summaries use 100-200 tokens, human-read summaries use 300-500 tokens, and agent-mediated discussion summaries use 500-800 tokens. The orchestrator never receives document contents in its conversation context.
 
 **Why this matters:**
 
@@ -452,7 +453,7 @@ Codex CLI is skills-first because the terminal CLI supports repository skills di
 
 **Implementation:**
 
-- Each delegate's instructions end with: "Return a 3-5 sentence summary of key findings. Do NOT return the full document contents."
+- Each delegate's instructions identify the correct summary tier and keep full document contents on disk instead of echoing them into orchestrator context.
 - Output templates in `.planning/templates/research/` and `.planning/templates/codebase/` define the on-disk format.
 - The synthesizer reads all 4 research files from disk -- it is the only agent that sees full research content.
 
@@ -958,20 +959,20 @@ Implementation lives under `bin/lib/`:
 | E8 | ERROR | `.planning/templates/` missing critical root files (`spec.md`, `roadmap.md`, `auth-matrix.md`) |
 | E9 | ERROR | `.planning/templates/brownfield-change/` missing or missing critical files (`CHANGE.md`, `HANDOFF.md`, `VERIFICATION.md`) |
 | W1 | WARN | `generation-manifest.json` missing |
-| W2 | WARN | Template files modified locally (hash mismatch vs manifest) |
-| W3 | WARN | Template/role files missing from disk but listed in manifest |
+| W2 | WARN | Manifest-tracked installed templates/helpers modified locally (hash mismatch vs manifest) |
+| W3 | WARN | Manifest-tracked installed templates/helpers missing from disk but listed in manifest |
 | W4 | WARN | Active non-archived phases marked in progress/done are missing from `.planning/phases/` |
 | W5 | WARN | Phase artifact set has PLAN but no matching SUMMARY (stale in-progress) |
-| W6 | WARN | No adapter surfaces detected |
+| W6 | WARN | No generated workflow adapter surfaces detected |
 | W7 | WARN | `distilled/DESIGN.md` health check table differs from implemented check IDs |
 | W8 | WARN | `distilled/README.md` workflow inventory differs from `distilled/workflows/` |
 | W9 | WARN | `.internal-research/gaps.md` references missing repo-local paths |
 | W10 | WARN | ROADMAP lifecycle status drift, including requirement checkbox and overview/detail phase status mismatches |
-| W11 | WARN | Installed generated runtime/helper surfaces drift from current render output |
+| W11 | WARN | Renderer-backed generated runtime/helper surfaces drift from current render output |
 | W12 | WARN | Planning state drifted since last recorded session (fingerprint mismatch) |
 | I1 | INFO | Generation manifest `frameworkVersion` differs from current `FRAMEWORK_VERSION` |
 | I2 | INFO | Phase completion count from ROADMAP |
-| I3 | INFO | Which adapters are installed |
+| I3 | INFO | Which runtime/governance surfaces are installed |
 
 **Verdict logic:**
 - Any ERROR → `broken` (exit code 1)
@@ -994,7 +995,9 @@ Implementation lives under `bin/lib/`:
 
 5. **Reuses existing modules.** `readManifest()` and `detectModifications()` from `manifest.mjs` handle W1-W3. `isProjectInitialized()` pattern from `models.mjs` handles the pre-init guard. Truth checks stay read-only and operate on repo-local artifacts only when those framework files exist.
 
-6. **Framework-source mode skips installed-project template checks.** Inside the GSDD framework repo itself, `distilled/templates/` is the source of truth and `.planning/templates/` is intentionally absent. `npx -y gsdd-cli health` therefore skips the installed-project template/manifest checks (E3-E9, W1-W3) in framework-source mode instead of producing false positives during self-health runs.
+6. **Framework-source mode skips installed-project template checks only for the actual source repo.** Inside the GSDD framework repo itself, `distilled/templates/` is the source of truth and `.planning/templates/` can be intentionally absent. `npx -y gsdd-cli health` therefore skips installed-project template/manifest checks (E3-E9, W1-W3) only when source-repo identity signals also match (`package.json` name plus CLI source), avoiding false suppression in copied or unusual initialized repos that happen to contain `distilled/templates` and `distilled/workflows`.
+
+7. **Generated adapters and governance are reported separately.** W6 checks generated workflow entry surfaces (`.agents/skills`, Claude skills/commands, OpenCode commands) and does not treat root `AGENTS.md`, native checker agents, or Codex native checker TOML as workflow adapters. Codex CLI uses `.agents/skills` as its workflow entry path. I3 may still report native agents and root `AGENTS.md` as installed runtime/governance surfaces so users understand what exists without confusing those files with executable workflow discovery.
 
 **What was removed vs GSD:**
 - `--repair` flag and associated repair actions
@@ -1354,7 +1357,7 @@ Combined, these three workflows provided genuine leverage: the planner could not
 
 **GSDD decision:** Recover the discuss-phase leverage as a single role (`agents/approach-explorer.md`) embedded in the plan workflow, with a hybrid interaction architecture:
 
-1. **Primary path (inline + research subagents):** Conversation runs in the plan workflow's main context (required for user interactivity). For each technical gray area, a read-only research subagent spawns, reads codebase/docs, and returns a compressed ~1000-token structured summary. Only summaries enter the conversation context, not raw file reads.
+1. **Primary path (inline + research subagents):** Conversation runs in the plan workflow's main context (required for user interactivity). For each technical gray area, a read-only research subagent spawns, reads codebase/docs, and returns a compressed 500-800 token structured summary. Only summaries enter the conversation context, not raw file reads.
 
 2. **Native agent optimization:** Runtimes with interactive subagent support (Claude Code with `AskUserQuestion`, Codex interactive agents, OpenCode `mode: agent`) can run the full exploration as a native agent. Falls back to the inline primary path if unavailable.
 
@@ -1387,7 +1390,7 @@ The approach explorer needs two capabilities with opposite context requirements:
 - **Conversation** needs the main context (for user interaction)
 - **Research** generates thousands of tokens of raw content the conversation doesn't need
 
-Isolating research in subagents and returning compressed summaries follows the Compress and Isolate patterns from context engineering literature. The research subagent prompt template lives in the role contract (`<research_subagent_prompt>` section of `agents/approach-explorer.md`) — co-located with the algorithm it serves, and referenced by the portable workflow rather than inlined. The main context budget stays manageable: ~1000 tokens orchestration + ~4000 tokens research summaries (4 areas × ~1000) + ~4000 tokens conversation + ~500 tokens APPROACH.md = ~9500 tokens. The 1000-token budget (matching Anthropic CE's recommended floor) gives research subagents room for the structured format (Name/Pro/Con/Source) plus recommendation reasoning, source verification, and enough project-specific context that the main agent can handle follow-up questions without re-querying the subagent.
+Isolating research in subagents and returning compressed summaries follows the Compress and Isolate patterns from context engineering literature. The research subagent prompt template lives in the role contract (`<research_subagent_prompt>` section of `agents/approach-explorer.md`) — co-located with the algorithm it serves, and referenced by the portable workflow rather than inlined. The main context budget stays manageable: about 1000 tokens orchestration, up to 3200 tokens research summaries (4 areas x 800), about 4000 tokens conversation, and about 500 tokens APPROACH.md. The 500-800 token agent-mediated discussion tier gives research subagents room for the structured format (Name/Pro/Con/Source) plus recommendation reasoning, source verification, and enough project-specific context that the main agent can handle follow-up questions without re-querying the subagent.
 
 **Evidence:**
 
@@ -2774,6 +2777,42 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 - `complete-milestone` now fails closed before archive writes when the passed audit omits or contradicts the release claim contract.
 - Public claims are scoped to tracked public or repo-visible proof, while GitHub Releases, tags, package publication, and release automation remain deferred until explicitly planned.
 
+## D61 - Deliberate Subagent Contract
+
+**Decision (2026-04-28):** Subagents are deliberate isolation tools, not hidden implementation orchestration. Workspine should use them for research, review, mapping, synthesis, and integration checking when the work is read-only or artifact-backed, while implementation remains sequential unless an approved plan explicitly owns disjoint write sets.
+
+**Context:**
+- Phase 50 found that existing subagent wording was over-strong in some planning and role surfaces while summary-size guidance had drifted across 3-5 sentence, 300-500 token, and 1000-token variants.
+- Phase 46 research supported parallel agents for breadth-first research, but warned that coding writes need stronger coordination before parallel PR or multi-worktree orchestration is safe.
+- Phase 53 approach alignment confirmed the conservative boundary: allow read-heavy and artifact-backed delegation, forbid hidden implementation orchestration, keep roadmapper role-only/direct invocation, and do not claim broad S3/S5 closure or native runtime parity.
+
+**Decision:**
+- Allowed subagent use: research, review, mapping, synthesis, and integration checks when they are read-only or when the subagent writes/updates its own bounded durable artifact.
+- Return discipline: routing summaries use 100-200 tokens, human-read summaries use 300-500 tokens, agent-mediated discussion summaries use 500-800 tokens, and full details live in durable documents on disk.
+- Forbidden by default: hidden implementation orchestration, agent teams, parallel PR flows, multi-worktree coding, and overlapping implementation writes without explicit write-set ownership in the approved plan.
+- Roadmapper remains role-only/direct invocation in Phase 53. Roadmap creation is sequential and coverage-sensitive, writes `.planning/ROADMAP.md`, and does not yet have a proven thin-wrapper delegate use case.
+- S3 and S5 remain deferred. This decision narrows the practical Workspine subagent contract but does not close broad subagent orchestration parity or adapter research gaps.
+
+**Leverage:**
+- Lost: less flexibility for future agents to add delegates by symmetry or treat missing delegates as accidental gaps.
+- Kept: the two-layer role/delegate architecture, summaries-up/documents-to-disk, repo-native workflow state, lifecycle preflight, and write-set constraints.
+- Gained: a durable conservative rule that tells agents when subagents earn their keep and when they create hidden orchestration risk.
+
+**Evidence:**
+- `agents/README.md`
+- `agents/DISTILLATION.md`
+- `distilled/templates/delegates/`
+- `distilled/workflows/map-codebase.md`
+- `distilled/workflows/new-project.md`
+- GSD comparison source: `get-shit-done/workflows/new-project.md` and mapper/research workflows use `Task()` subagents heavily, but GSDD keeps the portable core single-agent-safe and only preserves subagent use where isolation, artifact persistence, or fresh-context review pays for the complexity.
+
+**Consequences:**
+- Future role, delegate, and workflow wording must distinguish read-only/artifact-backed delegation from implementation write ownership.
+- A roadmapper delegate must not appear by symmetry; it needs a future explicit design decision and regression updates.
+- Generated runtime freshness may propagate this wording, but generated freshness is not runtime parity proof.
+
+---
+
 ## Maintenance
 
 This document is updated when:

package/distilled/EVIDENCE-INDEX.md

@@ -478,6 +478,13 @@
 - `distilled/DESIGN.md` D50 and D59
 - `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
 
+## D61 — Deliberate Subagent Contract
+- `agents/README.md`, `agents/DISTILLATION.md`, `agents/approach-explorer.md`, `agents/planner.md`, `agents/roadmapper.md`
+- `distilled/templates/delegates/approach-explorer.md`, `distilled/templates/delegates/plan-checker.md`
+- `distilled/workflows/audit-milestone.md`, `distilled/workflows/map-codebase.md`, `distilled/workflows/new-project.md`, `distilled/workflows/plan.md`
+- GSD comparison source: `get-shit-done/workflows/new-project.md`
+- `tests/gsdd.guards.test.cjs`, `tests/gsdd.invariants.test.cjs`
+
 ---
 
 ## Maintenance

package/distilled/templates/delegates/approach-explorer.md

@@ -25,4 +25,4 @@ Classify each gray area before acting on it:
 
 Write `{padded_phase}-APPROACH.md` to the phase directory using the approach template.
 
-Return structured summary: gray areas explored, decisions captured, assumptions validated/corrected, deferred ideas, path to APPROACH.md.
+Return only a structured summary: gray areas explored, decisions captured, assumptions validated/corrected, deferred ideas, and path to APPROACH.md. Full decision detail belongs in the APPROACH.md artifact, not in the orchestrator context.

package/distilled/templates/delegates/mapper-arch.md

@@ -22,5 +22,5 @@ Include:
 </quality_gate>
 
 Write to: `.planning/codebase/ARCHITECTURE.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
+Return: Routing summary to the Orchestrator (100-200 tokens) when done.
 Guardrails: Max Agent Hops = 3. No static directory dumps.

package/distilled/templates/delegates/mapper-concerns.md

@@ -23,5 +23,5 @@ Include:
 </quality_gate>
 
 Write to: `.planning/codebase/CONCERNS.md`
-Return: 3-5 sentence summary to the Orchestrator when done. If secrets found, STOP and report immediately.
+Return: Routing summary to the Orchestrator (100-200 tokens) when done. If secrets found, STOP and report immediately.
 Guardrails: Max Agent Hops = 3. Hard stop on secrets.

package/distilled/templates/delegates/mapper-quality.md

@@ -24,5 +24,5 @@ Include:
 </quality_gate>
 
 Write to: `.planning/codebase/CONVENTIONS.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
+Return: Routing summary to the Orchestrator (100-200 tokens) when done.
 Guardrails: Max Agent Hops = 3. Rules not inventories.

package/distilled/templates/delegates/mapper-tech.md

@@ -21,5 +21,5 @@ Include:
 </quality_gate>
 
 Write to: `.planning/codebase/STACK.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
+Return: Routing summary to the Orchestrator (100-200 tokens) when done.
 Guardrails: Max Agent Hops = 3. No static dependency dumps.

package/distilled/templates/delegates/plan-checker.md

@@ -1,6 +1,6 @@
 **Role contract:** Read `.planning/templates/roles/planner.md` before starting. Reuse its planning vocabulary and quality standards, but this wrapper overrides your objective: you are reviewing plans, not authoring them.
 
-You are the fresh-context plan checker for `/gsdd-plan`.
+You are the fresh-context plan checker for `/gsdd-plan`. This is a read-only review delegate: return the JSON finding summary only, and do not edit plan artifacts yourself.
 
 Read only the explicit inputs provided by the orchestrator:
 - target phase goal and requirement IDs
@@ -45,7 +45,7 @@ Verify these dimensions:
   - **Deferred excluded?** Deferred ideas from APPROACH.md must not appear in plan tasks -> `blocker` if found.
   - If `workflow.discuss` is `true` in the project config and no APPROACH.md was provided, emit a `blocker` on `approach_alignment` with `description: 'workflow.discuss is true but no APPROACH.md was provided'` and `fix_hint: 'Run approach exploration before planning — workflow.discuss=true requires an approved APPROACH.md before a plan can be emitted.'` If `workflow.discuss` is `false` or the key is absent and no APPROACH.md was provided, skip this dimension entirely.
 
-Return JSON only as a single object with this shape:
+Return JSON only as a single finding summary object with this shape:
 
 ```json
 {

package/distilled/templates/delegates/researcher-architecture.md

@@ -26,5 +26,5 @@ Your output informs phase structure in ROADMAP.md. Include:
 
 Write to: `.planning/research/ARCHITECTURE.md`
 Use template: `.planning/templates/research/architecture.md` (if it exists)
-Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Return: Human-read structured summary to the Orchestrator (300-500 tokens) when done.
 Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-features.md

@@ -26,5 +26,5 @@ Your output feeds SPEC requirements. Categorize explicitly:
 
 Write to: `.planning/research/FEATURES.md`
 Use template: `.planning/templates/research/features.md` (if it exists)
-Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Return: Human-read structured summary to the Orchestrator (300-500 tokens) when done.
 Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-pitfalls.md

@@ -26,5 +26,5 @@ Your output prevents mistakes in roadmap and planning. For each pitfall:
 
 Write to: `.planning/research/PITFALLS.md`
 Use template: `.planning/templates/research/pitfalls.md` (if it exists)
-Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Return: Human-read structured summary to the Orchestrator (300-500 tokens) when done.
 Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-stack.md

@@ -26,5 +26,5 @@ Your output feeds the roadmapper. Be prescriptive:
 
 Write to: `.planning/research/STACK.md`
 Use template: `.planning/templates/research/stack.md` (if it exists)
-Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Return: Human-read structured summary to the Orchestrator (300-500 tokens) when done.
 Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-synthesizer.md

@@ -11,7 +11,7 @@ Read these files (all should exist):
 Cross-reference them. Surface conflicts and dependencies between findings. Do NOT do new research — synthesize what exists.
 
 SUMMARY.md MUST include:
-1. **Key Findings** — top 5-7 bullets across all 4 dimensions
+1. **Key Findings** — the highest-signal findings across all 4 dimensions
 2. **Implications for Roadmap** — suggested phase groupings derived from architecture build order + pitfall avoidance (this is the critical handoff to the roadmapper)
 3. **Research Flags** — which phases need deeper research vs standard patterns
 4. **Confidence Assessment** — per domain: stack / features / architecture / pitfalls
@@ -27,5 +27,5 @@ Use template: `.planning/templates/research/summary.md` (if it exists)
 </quality_gate>
 
 Write to: `.planning/research/SUMMARY.md`
-Return: 5-7 bullet key findings to the Orchestrator when done.
+Return: Agent-mediated structured summary to the Orchestrator (500-800 tokens) when done.
 Guardrails: Max Agent Hops = 2. Do not do new research — synthesize only.

package/distilled/workflows/audit-milestone.md

@@ -110,7 +110,7 @@ With phase context collected, delegate cross-phase integration checking:
 
 **Task:** Verify cross-phase wiring, API coverage, auth protection, and E2E user flows. Return structured integration report with wiring summary, API coverage, auth protection, E2E flow status, and Requirements Integration Map.
 
-**Return:** Structured integration report (wiring, APIs, auth protection, flows, requirements map).
+**Return:** Structured integration report summary (wiring, APIs, auth protection, flows, requirements map). The checker is read-only; the auditor owns the milestone audit artifact.
 </delegate>
 
 If the runtime supports spawning a subagent: spawn the integration checker as a separate read-only context for independent verification.

package/distilled/workflows/map-codebase.md

@@ -102,7 +102,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Current working directory. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/mapper-tech.md` for full task instructions. Follow them exactly.
 Output: `.planning/codebase/STACK.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3. No static dumps. Never read .env contents.
 </delegate>
 
@@ -112,7 +112,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Current working directory. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/mapper-arch.md` for full task instructions. Follow them exactly.
 Output: `.planning/codebase/ARCHITECTURE.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3. No static directory dumps. Never read .env contents.
 </delegate>
 
@@ -122,7 +122,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Current working directory. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/mapper-quality.md` for full task instructions. Follow them exactly.
 Output: `.planning/codebase/CONVENTIONS.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3. Rules not inventories. Never read .env contents.
 </delegate>
 
@@ -132,7 +132,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Current working directory. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/mapper-concerns.md` for full task instructions. Follow them exactly. Hard stop if secrets found -- report immediately.
 Output: `.planning/codebase/CONCERNS.md`
-Return: 3-5 sentence summary to Orchestrator. If secrets found, STOP and report immediately.
+Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact. If secrets found, STOP and report immediately.
 Guardrails: Max Agent Hops = 3. Hard stop on secrets. Never read .env contents.
 </delegate>
 </mapping>

package/distilled/workflows/new-project.md

@@ -20,7 +20,7 @@ When `autoAdvance: true`, this workflow runs non-interactively:
 
 5. **Keep quality gates:** All quality checks in `<spec_creation>` and `<roadmap_creation>` still apply. Thoroughness is preserved; only user wait-points are removed.
 
-6. **After completion:** Report what was created and any assumptions inferred from the brief. Do NOT auto-advance to planning — the user or CI system decides when to start planning.
+6. **After completion:** Report what was created and any assumptions inferred from the brief. Do NOT auto-progress into plan, execute, verify, release, or delivery. The user or CI system must start any later lifecycle workflow explicitly.
 
 All other sections (`<detect_mode>`, `<codebase_context>`, `<research>`, `<spec_creation>`, `<roadmap_creation>`, `<success_criteria>`) execute normally. Auto mode bypasses: the `<questioning>` section, both `<approval_gate>` blocks, the user question in `<project_principles>`, and the user question in `<capability_gates>`. All other workflow logic executes normally.
 </auto_mode>
@@ -33,8 +33,8 @@ Before starting, read these files (if they exist):
 4. Project root files: `package.json`, `README.md`, main entry point, `.gitignore`
 5. `.planning/config.json` — The deterministic project settings. Key fields:
    - `researchDepth`: balanced | fast | deep — controls research thoroughness
-   - `parallelization`: true | false � whether to run delegate work in parallel when the platform supports it; when false, run the same delegates sequentially
-   - `workflow.research`: true | false — whether to do SOTA research before spec
+   - `parallelization`: true | false - whether to run delegate work in parallel when the platform supports it; when false, run the same delegates sequentially
+   - `workflow.research`: true | false - whether to do domain research before spec
    - `workflow.planCheck`: true | false — whether plan-check agent runs later
    - `workflow.verifier`: true | false — whether verifier runs after execution
    - `modelProfile`: balanced | quality | budget — model selection hint
@@ -44,7 +44,6 @@ Before starting, read these files (if they exist):
 </load_context>
 
 <project_principles>
-**(SOTA Insight: Derived from Spec-Kit)**
 Before diving into technical specifications, establish the core governing principles of the project.
 If `autoAdvance: true` in `.planning/config.json`, skip this question. Infer core principles
 from the project brief (code quality signals, constraint language, scope decisions) and note
@@ -161,7 +160,7 @@ Before creating a spec, you MUST have clear answers to:
 - **3-5 rounds minimum** for non-trivial projects
 
 ### Categorizing Requirements (Crucial)
-As the user provides answers, you must mentally categorize the features they request using the SOTA framework:
+As the user provides answers, you must mentally categorize the features they request:
 1. **Table Stakes**: Features users absolutely expect. Without them, your product feels broken (e.g., password reset).
 2. **Differentiators**: Features that set this project apart from competitors.
 3. **Out of Scope**: Explicit anti-requirements for v1 to prevent scope creep.
@@ -202,28 +201,27 @@ MANDATORY STEP. After the goal is clarified but BEFORE writing any specs.
 
 **Check config first:** Read `.planning/config.json`.
 - If `workflow.research: false` → skip this section entirely, go to `<spec_creation>`.
-- If `researchDepth: "fast"` � use the same 4 specialists below, then synthesize `SUMMARY.md` inline. Faster and cheaper; acceptable for well-known domains.
-- If `researchDepth: "balanced"` or `"deep"` � use the same 4 specialists below plus the synthesizer (default).
+- If `researchDepth: "fast"` - use the same 4 specialists below, then synthesize `SUMMARY.md` inline. Faster and cheaper; acceptable for well-known domains.
+- If `researchDepth: "balanced"` or `"deep"` - use the same 4 specialists below plus the synthesizer (default).
 
-### Why Parallel Specialists, Not One Generalist
-**(SOTA: Anthropic Agent Teams, OpenAI Multi-Agents — 90.2% performance improvement for complex research tasks)**
+### Why Specialists, Not One Generalist
 
 DO NOT research in this main thread — noisy intermediate output pollutes the context window.
 DO NOT use a single generalist to write all research files — domain switching degrades quality.
 
 Use the same 4 specialized researchers every time. The difference is execution order and synthesis mode.
-- If `parallelization: true` and your platform supports parallel execution (`run_in_background=true`, async tasks, etc.) � run all 4 simultaneously.
-- If `parallelization: false` or your platform lacks parallel execution � run the same 4 researchers sequentially.
-- If `researchDepth: "fast"` � synthesize inline after the 4 researcher outputs return.
-- If `researchDepth: "balanced"` or `"deep"` � use the synthesizer delegate after the 4 researcher outputs are written.
+- If `parallelization: true` and your platform supports parallel execution (`run_in_background=true`, async tasks, etc.) - run all 4 simultaneously.
+- If `parallelization: false` or your platform lacks parallel execution - run the same 4 researchers sequentially.
+- If `researchDepth: "fast"` - synthesize inline after the 4 researcher outputs return.
+- If `researchDepth: "balanced"` or `"deep"` - use the synthesizer delegate after the 4 researcher outputs are written.
 
 
 ```
-◆ Spawning 4 researchers in parallel...
-  → Stack research        → .planning/research/STACK.md
-  → Features research     → .planning/research/FEATURES.md
-  → Architecture research → .planning/research/ARCHITECTURE.md
-  → Pitfalls research     → .planning/research/PITFALLS.md
+Spawning 4 researchers...
+  -> Stack research        -> .planning/research/STACK.md
+  -> Features research     -> .planning/research/FEATURES.md
+  -> Architecture research -> .planning/research/ARCHITECTURE.md
+  -> Pitfalls research     -> .planning/research/PITFALLS.md
 ```
 
 Ensure `.planning/research/` directory exists before spawning.
@@ -234,7 +232,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-stack.md` for full task instructions. Apply the project goal and milestone context provided above.
 Output: `.planning/research/STACK.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
@@ -244,7 +242,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-features.md` for full task instructions. Apply the project goal and milestone context provided above.
 Output: `.planning/research/FEATURES.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
@@ -254,7 +252,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-architecture.md` for full task instructions. Apply the project goal and milestone context provided above.
 Output: `.planning/research/ARCHITECTURE.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
@@ -264,14 +262,14 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-pitfalls.md` for full task instructions. Apply the project goal and milestone context provided above.
 Output: `.planning/research/PITFALLS.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
 **After all 4 researchers complete**, synthesize based on `researchDepth`:
 
 **If `researchDepth: "fast"`:** Synthesize inline.
-You hold 4 × 3-5 sentence summaries. Write `.planning/research/SUMMARY.md` directly using `.planning/templates/research/summary.md`. Cross-reference the summaries. Do NOT spawn another agent.
+You hold 4 human-read structured summaries. Write `.planning/research/SUMMARY.md` directly using `.planning/templates/research/summary.md`. Cross-reference the summaries. Do NOT spawn another agent.
 
 **If `researchDepth: "balanced"` or `"deep"`:** Spawn synthesizer to read the full research files.
 
@@ -281,11 +279,11 @@ Parallel: false
 Context: Researcher summaries returned above. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-synthesizer.md` for full task instructions.
 Output: `.planning/research/SUMMARY.md`
-Return: 5-7 bullet key findings to Orchestrator.
+Return: Agent-mediated structured summary to Orchestrator (500-800 tokens); full synthesis stays in the output artifact.
 Guardrails: Max Agent Hops = 2. Do not do new research — synthesize only.
 </delegate>
 
-*Why the split:* The synthesizer reads the 4 full research files and cross-references specific data points (build order constraints, pitfall-to-phase mappings, feature-architecture conflicts) that 3-5 sentence summaries omit. This depth matters for `balanced`/`deep` runs where the roadmapper needs rich "Implications for Roadmap." For `fast` runs, orchestrator inline synthesis is the acceptable trade-off.
+*Why the split:* The synthesizer reads the 4 full research files and cross-references specific data points (build order constraints, pitfall-to-phase mappings, feature-architecture conflicts) that returned summaries omit. This depth matters for `balanced`/`deep` runs where the roadmapper needs rich "Implications for Roadmap." For `fast` runs, orchestrator inline synthesis is the acceptable trade-off.
 
 Display key findings before moving to spec creation.
 
@@ -293,7 +291,7 @@ Display key findings before moving to spec creation.
 - [ ] All 4 specialist files written to `.planning/research/`
 - [ ] SUMMARY.md written with "Implications for Roadmap" section populated
 - [ ] Negative claims verified with current web docs (not training data)
-- [ ] Confidence levels assigned: ✅ verified, ⚠️ likely, ❓ uncertain
+- [ ] Confidence levels assigned: verified | likely | uncertain
 
 **Commit**: `docs: add domain research`
 </research>
@@ -301,7 +299,7 @@ Display key findings before moving to spec creation.
 **STOP. Research is complete. Do NOT write any application code. Proceed to spec creation below. Your job now is to produce SPEC.md and ROADMAP.md — not to build the project.**
 
 <data_schema_definition>
-Before writing SPEC.md, define core Data Models/Typed Schemas *(SOTA: GitHub Blog — "Multi-agent workflows often fail")*. Multi-agent systems require typed schemas to pass reliable state. These schemas MUST be included in SPEC.md (see item 7 in `<spec_creation>` below). Also define Done-When verification criteria for every requirement (see item 8). *SPEC.md defines WHAT, not HOW — do not include implementation tasks.*
+Before writing SPEC.md, define core Data Models/Typed Schemas. Multi-agent handoffs require typed schemas to pass reliable state. These schemas MUST be included in SPEC.md (see item 7 in `<spec_creation>` below). Also define Done-When verification criteria for every requirement (see item 8). *SPEC.md defines WHAT, not HOW - do not include implementation tasks.*
 </data_schema_definition>
 
 <spec_creation>
@@ -312,15 +310,14 @@ After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
 3. **Requirements have IDs**: `AUTH-01`, `DATA-02`, `UI-03`
 4. **Requirements are ordered** by priority within each category
 5. **Out of Scope is populated** — includes things the developer explicitly said "not now" AND anti-features found in Research.
-6. **Key Decisions are logged** — any choices made during questioning or dictated by the SOTA research.
-7. **Typed Data Schemas** *(SOTA: GitHub Blog — "Multi-agent workflows often fail")*: explicitly define the core Data Models/Typed Schemas the project will use (e.g., `type UserProfile = { id: number; plan: 'free' | 'pro' }`). Multi-agent systems require typed schemas to pass reliable state; natural language instructions fail across agent handoffs. *SPEC.md defines WHAT, not HOW — do not include implementation tasks.*
-8. **Done-When Verification Chain** *(SOTA: Cyanluna)*: For EVERY requirement in the "Must Have (v1)" section, define a clear, verifiable `[Done-When: ...]` criterion. "User can log in" must become "User can log in [Done-When: Login form submits, JWT is received, and User is redirected to Dashboard]". No exceptions.
+6. **Key Decisions are logged** — any choices made during questioning or dictated by the research.
+7. **Typed Data Schemas**: explicitly define the core Data Models/Typed Schemas the project will use (e.g., `type UserProfile = { id: number; plan: 'free' | 'pro' }`). Multi-agent handoffs require typed schemas to pass reliable state; natural language instructions fail across agent handoffs. *SPEC.md defines WHAT, not HOW - do not include implementation tasks.*
+8. **Done-When Verification Chain**: For EVERY requirement in the "Must Have (v1)" section, define a clear, verifiable `[Done-When: ...]` criterion. "User can log in" must become "User can log in [Done-When: Login form submits, JWT is received, and User is redirected to Dashboard]". No exceptions.
 9. **Capability & Security Gates**: Handle per the `<capability_gates>` section at the end of this `<spec_creation>` block.
 10. **Authorization Matrix (optional)**: For projects with multiple user roles or protected resources, create `.planning/AUTH_MATRIX.md` using the template at `.planning/templates/auth-matrix.md`. The integration checker will use this matrix for systematic auth verification during milestone audits.
 11. **ROADMAP phase status is initialized** with Phase 1 marked `[ ]` / not started using the roadmap template's phase-status language.
 
 <capability_gates>
-**(SOTA Insight: Derived from OpenFang - "16 Security Systems & Capability Gates")**
 Before finishing SPEC.md, explicitly define what the agents are NOT allowed to do automatically without human approval.
 If `autoAdvance: true`, skip this question. Add a deferred placeholder to SPEC.md:
 "## Capability & Security Gates\n_Deferred — auto mode cannot elicit gate preferences; requires explicit review before production deployment._"
@@ -348,7 +345,7 @@ Do NOT proceed to roadmap creation until the developer explicitly approves.
 
 <roadmap_creation>
 After `SPEC.md` is approved, you must create `ROADMAP.md`.
-Since you are an Orchestrator with fresh context, you DO NOT need to spawn a subagent for this—write it yourself directly, retaining full thoroughness.
+Since you are an Orchestrator with fresh context, you DO NOT need to spawn a subagent for this; write it yourself directly, retaining full thoroughness. Research and synthesis delegation above are artifact-backed inputs; roadmap creation remains direct and sequential.
 
 Break `SPEC.md` requirements into executable phases:
 
@@ -410,7 +407,7 @@ Init is DONE when ALL of these are true:
 
 - [ ] Codebase audit completed (brownfield) OR greenfield confirmed
 - [ ] Developer was questioned in depth (3+ rounds for non-trivial projects) — [interactive only; skip when autoAdvance: true]
-- [ ] Research subagent spawned and SOTA patterns retrieved
+- [ ] Research subagent spawned and domain patterns retrieved
 - [ ] `SPEC.md` exists with testable requirements, out-of-scope, and current state
 - [ ] SPEC.md was reviewed and approved by the developer — [interactive only; skip when autoAdvance: true]
 - [ ] ROADMAP.md exists with phases, success criteria, and requirement mapping

package/distilled/workflows/plan.md

@@ -436,14 +436,14 @@ Run the approach explorer.
 
 ### Running the Approach Explorer
 **Primary path — inline conversation with research subagents:**
-The conversation with the user runs inline in the main context. For each technical gray area, a read-only research subagent is spawned to isolate heavy codebase and documentation reads, returning only compressed summaries.
+The conversation with the user runs inline in the main context. For each technical gray area, a read-only research subagent is spawned to isolate heavy codebase and documentation reads, returning only compressed summaries while full detail stays out of the orchestrator context.
 
 1. Load context: read ONLY locked decisions from `.planning/SPEC.md` and the target phase goal/requirements from `.planning/ROADMAP.md`.
 
 2. Identify 3-4 domain-specific gray areas. Classify each as **taste** (preference, no research needed), **technical** (trade-offs, research first), or **hybrid** (both).
 
 3. For each **technical or hybrid** gray area, spawn a read-only research subagent.
-   Use the prompt template from `.planning/templates/roles/approach-explorer.md` (`<research_subagent_prompt>` section), substituting the gray area name, classification, phase context, and relevant codebase files. Each subagent returns a structured summary under 1000 tokens.
+   Use the prompt template from `.planning/templates/roles/approach-explorer.md` (`<research_subagent_prompt>` section), substituting the gray area name, classification, phase context, and relevant codebase files. Each subagent returns a structured summary and does not write implementation artifacts.
 
 4. Present each gray area to the user individually:
    - For taste areas: ask directly
@@ -488,7 +488,7 @@ The approach explorer's full role contract is at `.planning/templates/roles/appr
 
 <plan_check_orchestration>
 ### How Plan Checking Works
-After the planner produces a draft plan, an independent checker reviews it in fresh context. The checker does not inherit the planner's hidden reasoning; it treats the plan as an untrusted draft.
+After the planner produces a draft plan, an independent checker reviews it in fresh context. The checker does not inherit the planner's hidden reasoning; it treats the plan as an untrusted draft and returns a structured summary of findings rather than editing the plan directly.
 
 ### What The Checker Verifies
 1. `requirement_coverage` - every phase requirement is covered by at least one concrete task

package/distilled/workflows/quick.md

@@ -169,9 +169,9 @@ Read `.planning/config.json`.
 If the checker returns `issues_found` with blockers and this is the first cycle:
 1. Send the issue list back to the planner for targeted revision of the plan file.
 2. Re-run the checker once more.
-3. If blockers remain after 1 revision cycle, store `$CHECKER_ISSUES` for display in the plan preview. Do NOT block — the user decides in Step 3.7.
+3. If blockers remain after 1 revision cycle, store `$CHECKER_ISSUES` for display in the plan preview and set `$RISK_ACCEPTANCE_REQUIRED=true`. Do not execute from default Enter; the user must explicitly accept the known risk in Step 3.7.
 
-If the checker returns `passed`, or `workflow.planCheck` is false, `$CHECKER_ISSUES` is empty.
+If the checker returns `passed`, or `workflow.planCheck` is false, `$CHECKER_ISSUES` is empty and `$RISK_ACCEPTANCE_REQUIRED=false`.
 
 ---
 
@@ -222,14 +222,18 @@ If `$CHECKER_ISSUES` is non-empty, append:
 Plan check issues: {$CHECKER_ISSUES}
 ```
 
-Present options (default-yes — pressing Enter proceeds):
-- If `$SCOPE_WARNING` is empty: `[Enter to proceed / edit description / abort]`
-- If `$SCOPE_WARNING` contains `/gsdd-new-project`: `[Enter to proceed / switch to /gsdd-new-project / edit description / abort]`
+Present options:
+- If `$CHECKER_ISSUES` is non-empty: `[type "proceed despite issues" to execute / edit description / abort]`
+- Otherwise if `$SCOPE_WARNING` is empty: `[Enter to proceed / edit description / abort]`
+- Otherwise if `$SCOPE_WARNING` contains `/gsdd-new-project`: `[Enter to proceed / switch to /gsdd-new-project / edit description / abort]`
 - Otherwise if `$SCOPE_WARNING` contains `/gsdd-map-codebase`: `[Enter to proceed / switch to /gsdd-map-codebase / edit description / abort]`
 - Otherwise if `$SCOPE_WARNING` is non-empty: `[Enter to proceed / switch to /gsdd-plan / edit description / abort]`
 
+Default-yes applies only when `$CHECKER_ISSUES` is empty. When unresolved checker blockers remain, pressing Enter must not execute; repeat the issues and ask for `proceed despite issues`, `edit description`, or `abort`.
+
 Handle response:
-- **Enter (or "yes"):** proceed to Step 4.
+- **Enter (or "yes") when `$CHECKER_ISSUES` is empty:** proceed to Step 4.
+- **"proceed despite issues" when `$CHECKER_ISSUES` is non-empty:** proceed to Step 4 and record the explicit risk acceptance in the quick summary.
 - **"edit description":** clean up the task directory, then return to Step 1 with `$DESCRIPTION` pre-filled as the starting point.
 - **"switch to /gsdd-new-project":** clean up the task directory, then stop quick workflow and report: "Use `/gsdd-new-project` to define or intentionally widen the work into full lifecycle planning. Task description: {$DESCRIPTION}"
 - **"switch to /gsdd-map-codebase":** clean up the task directory, then stop quick workflow and report: "Use `/gsdd-map-codebase` for a deeper brownfield baseline before quick work. Task description: {$DESCRIPTION}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "description": "Workspine — a repo-native delivery spine for long-horizon AI-assisted work, with directly validated support for Claude Code, Codex CLI, and OpenCode, published as gsdd-cli.",
   "type": "module",
   "bin": {