gsdd-cli 0.19.2 → 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/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.
 
@@ -1356,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.
 
@@ -1389,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:**
 
@@ -2776,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

@@ -232,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; full findings stay in the output artifact.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
@@ -242,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; full findings stay in the output artifact.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
@@ -252,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; full findings stay in the output artifact.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
@@ -262,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; full findings stay in the output artifact.
+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 x 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.
 
@@ -279,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; full synthesis stays in the output artifact.
+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.
 
@@ -345,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:
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.19.2",
+  "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": {