gsdd-cli 0.18.4 → 0.19.0

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

@@ -1,26 +1,26 @@
-**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-Map the architecture and structure of this codebase. Read key source files to understand component boundaries, data flow, and patterns.
-
-Write ARCHITECTURE.md to `.planning/codebase/` using the template at `.planning/templates/codebase/architecture.md`.
-
-Include:
-- Major components and their responsibilities (what belongs in each, what doesn't)
-- Data flow direction (not just "they communicate" — which way does data move)
-- "Change Routing" table: where to add new code by change type (new endpoint? new model? new UI component?)
-- Key architectural patterns used (e.g., event-driven, layered, modular monolith)
-- Golden files per layer: for each major layer, the single most-imported file (highest inbound import count = most stable, most understood); use import frequency as the signal, not judgment
-
-**Anti-staleness:** Do NOT include static directory trees or full file inventories. DO include file paths for key components, entry points, and architectural boundaries (e.g., `src/services/user.ts`) -- downstream agents navigate directly to files.
-
-<quality_gate>
-- [ ] Components have clear responsibility boundaries
-- [ ] Data flow direction is explicit
-- [ ] Change Routing table is populated (where to add new code by type)
-- [ ] Hard-to-reverse architectural decisions flagged
-- [ ] Golden files table populated with at least one file per major layer
-</quality_gate>
-
-Write to: `.planning/codebase/ARCHITECTURE.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
-Guardrails: Max Agent Hops = 3. No static directory dumps.
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the architecture and structure of this codebase. Read key source files to understand component boundaries, data flow, and patterns.
+
+Write ARCHITECTURE.md to `.planning/codebase/` using the template at `.planning/templates/codebase/architecture.md`.
+
+Include:
+- Major components and their responsibilities (what belongs in each, what doesn't)
+- Data flow direction (not just "they communicate" — which way does data move)
+- "Change Routing" table: where to add new code by change type (new endpoint? new model? new UI component?)
+- Key architectural patterns used (e.g., event-driven, layered, modular monolith)
+- Golden files per layer: for each major layer, the single most-imported file (highest inbound import count = most stable, most understood); use import frequency as the signal, not judgment
+
+**Anti-staleness:** Do NOT include static directory trees or full file inventories. DO include file paths for key components, entry points, and architectural boundaries (e.g., `src/services/user.ts`) -- downstream agents navigate directly to files.
+
+<quality_gate>
+- [ ] Components have clear responsibility boundaries
+- [ ] Data flow direction is explicit
+- [ ] Change Routing table is populated (where to add new code by type)
+- [ ] Hard-to-reverse architectural decisions flagged
+- [ ] Golden files table populated with at least one file per major layer
+</quality_gate>
+
+Write to: `.planning/codebase/ARCHITECTURE.md`
+Return: 3-5 sentence summary to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3. No static directory dumps.

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

@@ -1,27 +1,27 @@
-**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-Map the technical debt, security concerns, and risks in this codebase.
-
-**Security check first (hard stop):** Follow the Hard stop directive in `.planning/templates/roles/mapper.md` — grep for secrets before writing anything. If found: STOP and report to Orchestrator immediately.
-
-If no secrets found, write CONCERNS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/concerns.md`.
-
-Include:
-- Known bugs or fragile areas (with file references where possible)
-- Security vulnerabilities or missing validations
-- Performance bottlenecks
-- Missing test coverage for critical paths
-- Deprecated or end-of-life dependencies
-- Downstream impact ranking: top 3 concerns ranked by how much future work they block (concerns blocking multiple change-routing rows from ARCHITECTURE.md rank highest, not just by severity)
-
-<quality_gate>
-- [ ] Secret scan completed and result reported
-- [ ] Concerns are specific (file references, not vague "some places")
-- [ ] Severity assigned per concern: critical / moderate / minor
-- [ ] Deprecated dependencies listed with EOL dates if known
-- [ ] Downstream impact table ranks at least top 3 concerns with Blocks column populated
-</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.
-Guardrails: Max Agent Hops = 3. Hard stop on secrets.
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the technical debt, security concerns, and risks in this codebase.
+
+**Security check first (hard stop):** Follow the Hard stop directive in `.planning/templates/roles/mapper.md` — grep for secrets before writing anything. If found: STOP and report to Orchestrator immediately.
+
+If no secrets found, write CONCERNS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/concerns.md`.
+
+Include:
+- Known bugs or fragile areas (with file references where possible)
+- Security vulnerabilities or missing validations
+- Performance bottlenecks
+- Missing test coverage for critical paths
+- Deprecated or end-of-life dependencies
+- Downstream impact ranking: top 3 concerns ranked by how much future work they block (concerns blocking multiple change-routing rows from ARCHITECTURE.md rank highest, not just by severity)
+
+<quality_gate>
+- [ ] Secret scan completed and result reported
+- [ ] Concerns are specific (file references, not vague "some places")
+- [ ] Severity assigned per concern: critical / moderate / minor
+- [ ] Deprecated dependencies listed with EOL dates if known
+- [ ] Downstream impact table ranks at least top 3 concerns with Blocks column populated
+</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.
+Guardrails: Max Agent Hops = 3. Hard stop on secrets.

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

@@ -1,28 +1,28 @@
-**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-Map the conventions and quality patterns of this codebase. Read existing tests, lint config, and code samples.
-
-Write CONVENTIONS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/conventions.md`.
-
-Include:
-- Naming patterns (files, functions, variables, exports)
-- Code style rules enforced by lint/format config
-- Testing and mocking boundaries — explicit "Do mock" / "Do NOT mock" rules with examples
-- External integration patterns: webhook signature verification, auth session management, environment config
-- CI reliability rules (what must pass before merge)
-- Convention adoption rates: for each major convention, estimate `~N% (stable|rising|declining)` using grep-counting (≥5 occurrences required; below that write "prevalence unknown — seen in multiple files")
-- Golden files: 2–3 production files with the highest density of documented conventions (not scaffolding, not generated, not tests); format: `file path — which conventions it demonstrates`
-
-**Anti-staleness:** Do NOT enumerate test files or list every convention observed. Document rules and patterns: the invariants, not the inventory.
-
-<quality_gate>
-- [ ] Mocking boundaries are explicit ("Do mock: X" / "Do NOT mock: Y")
-- [ ] External integration security rules included (webhook, auth, env config)
-- [ ] Rules are actionable ("always do X"), not descriptive ("the codebase uses X")
-- [ ] At least one convention has a quantified adoption rate (e.g., `~N% (stable|rising|declining)`)
-- [ ] Golden files section lists at least 2 files with rationale
-</quality_gate>
-
-Write to: `.planning/codebase/CONVENTIONS.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
-Guardrails: Max Agent Hops = 3. Rules not inventories.
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the conventions and quality patterns of this codebase. Read existing tests, lint config, and code samples.
+
+Write CONVENTIONS.md to `.planning/codebase/` using the template at `.planning/templates/codebase/conventions.md`.
+
+Include:
+- Naming patterns (files, functions, variables, exports)
+- Code style rules enforced by lint/format config
+- Testing and mocking boundaries — explicit "Do mock" / "Do NOT mock" rules with examples
+- External integration patterns: webhook signature verification, auth session management, environment config
+- CI reliability rules (what must pass before merge)
+- Convention adoption rates: for each major convention, estimate `~N% (stable|rising|declining)` using grep-counting (≥5 occurrences required; below that write "prevalence unknown — seen in multiple files")
+- Golden files: 2–3 production files with the highest density of documented conventions (not scaffolding, not generated, not tests); format: `file path — which conventions it demonstrates`
+
+**Anti-staleness:** Do NOT enumerate test files or list every convention observed. Document rules and patterns: the invariants, not the inventory.
+
+<quality_gate>
+- [ ] Mocking boundaries are explicit ("Do mock: X" / "Do NOT mock: Y")
+- [ ] External integration security rules included (webhook, auth, env config)
+- [ ] Rules are actionable ("always do X"), not descriptive ("the codebase uses X")
+- [ ] At least one convention has a quantified adoption rate (e.g., `~N% (stable|rising|declining)`)
+- [ ] Golden files section lists at least 2 files with rationale
+</quality_gate>
+
+Write to: `.planning/codebase/CONVENTIONS.md`
+Return: 3-5 sentence summary to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3. Rules not inventories.

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

@@ -1,25 +1,25 @@
-**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-Map the technology stack of this codebase. Read package manifests, lockfiles, and entry points.
-
-Write STACK.md to `.planning/codebase/` using the template at `.planning/templates/codebase/stack.md`.
-
-Include:
-- Languages and runtimes (with versions)
-- Frameworks and key libraries (10-20 most important, not the full lockfile)
-- Infrastructure and deployment tooling
-- For each package: why it matters to this project (not just what it is)
-- Must-know packages: 3–5 packages where misuse causes the hardest-to-debug problems; include risk index (low/medium/high) and the common mistake to avoid
-
-**Anti-staleness:** Do NOT dump the full lockfile or dependency tree. Include only packages with architectural significance and note why they matter.
-
-<quality_gate>
-- [ ] 10-20 packages listed with version + rationale (not a lockfile dump)
-- [ ] Build/deploy tooling included
-- [ ] Any deprecated or risky dependencies flagged
-- [ ] Must-know packages section identifies at least 3 packages with risk index (low/medium/high)
-</quality_gate>
-
-Write to: `.planning/codebase/STACK.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
-Guardrails: Max Agent Hops = 3. No static dependency dumps.
+**Role contract:** Read `.planning/templates/roles/mapper.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+Map the technology stack of this codebase. Read package manifests, lockfiles, and entry points.
+
+Write STACK.md to `.planning/codebase/` using the template at `.planning/templates/codebase/stack.md`.
+
+Include:
+- Languages and runtimes (with versions)
+- Frameworks and key libraries (10-20 most important, not the full lockfile)
+- Infrastructure and deployment tooling
+- For each package: why it matters to this project (not just what it is)
+- Must-know packages: 3–5 packages where misuse causes the hardest-to-debug problems; include risk index (low/medium/high) and the common mistake to avoid
+
+**Anti-staleness:** Do NOT dump the full lockfile or dependency tree. Include only packages with architectural significance and note why they matter.
+
+<quality_gate>
+- [ ] 10-20 packages listed with version + rationale (not a lockfile dump)
+- [ ] Build/deploy tooling included
+- [ ] Any deprecated or risky dependencies flagged
+- [ ] Must-know packages section identifies at least 3 packages with risk index (low/medium/high)
+</quality_gate>
+
+Write to: `.planning/codebase/STACK.md`
+Return: 3-5 sentence summary to the Orchestrator when done.
+Guardrails: Max Agent Hops = 3. No static dependency dumps.

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

@@ -1,68 +1,68 @@
-**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`.
-
-Read only the explicit inputs provided by the orchestrator:
-- target phase goal and requirement IDs
-- relevant locked decisions or deferred items from `.planning/SPEC.md`
-- approach decisions from `.planning/phases/*-APPROACH.md` (if provided)
-- any relevant phase research file
-- the produced `.planning/phases/*-PLAN.md` file(s)
-
-Do NOT inherit the planner's hidden reasoning. Treat the current plans as untrusted drafts that must prove they will achieve the phase goal before execution.
-
-Verify these dimensions:
-- `requirement_coverage`: every phase requirement is covered by at least one concrete task
-- `task_completeness`: every executable task has files, action, verify, and done fields. Additionally check verify quality:
-  - **Runnable?** Does `<verify>` contain at least one command that an executor can run programmatically (e.g., a shell command, test runner invocation, curl request)? If ALL verify items are observational text with no runnable command -> `blocker`.
-  - **Fast?** Do verify commands complete quickly? Flag full E2E suites (playwright, cypress, selenium) without a faster smoke test -> `warning`. Flag watch-mode flags (`--watchAll`, `--watch`) -> `blocker`. Flag arbitrary delays > 30s -> `warning`.
-  - **Ordered?** If a verify command references a test file, does an earlier task in the plan create that file? If the referenced file has no prior task producing it -> `blocker`.
-- `dependency_correctness`: ordering, dependencies, and plan structure are coherent
-- `key_link_completeness`: important wiring/integration links are planned, not just isolated artifacts
-- `scope_sanity`: plans are sized so an executor can complete them without context collapse
-- `must_have_quality`: success criteria and must-haves are specific, observable, and reflected in tasks
-- `context_compliance`: locked decisions are honored and deferred ideas stay out of scope. Additionally check scope consistency:
-  - **Must-have coverage?** Every must-have requirement mapped to this phase in SPEC.md must appear in at least one plan task. A must-have that silently disappears from the plan is a `blocker`.
-  - **Deferred exclusion?** Items marked "Nice to Have", "Deferred", or "Out of Scope" in SPEC.md must not appear as plan tasks. Present → `blocker`.
-  - **Cross-surface consistency?** If SPEC.md marks an item as must-have but APPROACH.md marks it as deferred (or vice versa), surface the contradiction → `blocker`. Include a `fix_hint` asking the planner to resolve the conflict with the user before proceeding.
-- `goal_achievement`: does the plan, if executed perfectly, actually achieve the stated phase goal? Check:
-  - **Goal addressed?** Compare the phase goal statement to the plan's collective task outputs. Would successful completion of all tasks deliver the goal? If the goal says "users can authenticate" but tasks only set up database schema → `blocker`.
-  - **Success criteria reachable?** Are the phase success criteria from ROADMAP.md achievable through the planned tasks? Each success criterion should be traceable to at least one task's verify output → `blocker` if unreachable.
-  - **Outcome observable?** After execution, could a human or automated check confirm the goal was met? Plans that produce only internal artifacts with no user-visible or testable outcome → `warning`.
-- `approach_alignment`: when APPROACH.md is provided, verify that plan tasks implement the chosen approaches from the user's decisions. Check:
-  - **Chosen honored?** Does each plan task align with the approach chosen in APPROACH.md for its gray area? A task that implements an alternative the user explicitly rejected -> `blocker`.
-  - **Discretion respected?** "Agent's Discretion" items allow planner flexibility — do NOT flag these as misalignment.
-  - **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:
-
-```json
-{
-  "status": "passed",
-  "summary": "One sentence overall assessment",
-  "issues": [
-    {
-      "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
-      "severity": "blocker",
-      "description": "What is wrong",
-      "plan": "01-PLAN",
-      "task": "1-02",
-      "fix_hint": "Specific revision instruction"
-    }
-  ]
-}
-```
-
-Rules:
-- Status must be either `"passed"` or `"issues_found"`.
-- Use `"status": "passed"` only when no blockers remain. Warnings may still be listed.
-- Use `"status": "issues_found"` when any blocker exists or when warnings should be surfaced for revision.
-- Keep `fix_hint` targeted. The planner should patch the existing plan, not replan from scratch, unless the issue is fundamental.
-- If there are no issues, return `"issues": []`.
-
-Guardrails:
-- Do NOT write or edit plan files yourself.
-- Do NOT accept vague tasks such as "implement auth" without concrete files, actions, and verification.
-- Do NOT verify codebase reality; you are checking whether the plan will work, not whether the code already exists.
-- Do NOT silently approve missing wiring or missing requirement coverage.
+**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`.
+
+Read only the explicit inputs provided by the orchestrator:
+- target phase goal and requirement IDs
+- relevant locked decisions or deferred items from `.planning/SPEC.md`
+- approach decisions from `.planning/phases/*-APPROACH.md` (if provided)
+- any relevant phase research file
+- the produced `.planning/phases/*-PLAN.md` file(s)
+
+Do NOT inherit the planner's hidden reasoning. Treat the current plans as untrusted drafts that must prove they will achieve the phase goal before execution.
+
+Verify these dimensions:
+- `requirement_coverage`: every phase requirement is covered by at least one concrete task
+- `task_completeness`: every executable task has files, action, verify, and done fields. Additionally check verify quality:
+  - **Runnable?** Does `<verify>` contain at least one command that an executor can run programmatically (e.g., a shell command, test runner invocation, curl request)? If ALL verify items are observational text with no runnable command -> `blocker`.
+  - **Fast?** Do verify commands complete quickly? Flag full E2E suites (playwright, cypress, selenium) without a faster smoke test -> `warning`. Flag watch-mode flags (`--watchAll`, `--watch`) -> `blocker`. Flag arbitrary delays > 30s -> `warning`.
+  - **Ordered?** If a verify command references a test file, does an earlier task in the plan create that file? If the referenced file has no prior task producing it -> `blocker`.
+- `dependency_correctness`: ordering, dependencies, and plan structure are coherent
+- `key_link_completeness`: important wiring/integration links are planned, not just isolated artifacts
+- `scope_sanity`: plans are sized so an executor can complete them without context collapse
+- `must_have_quality`: success criteria and must-haves are specific, observable, and reflected in tasks
+- `context_compliance`: locked decisions are honored and deferred ideas stay out of scope. Additionally check scope consistency:
+  - **Must-have coverage?** Every must-have requirement mapped to this phase in SPEC.md must appear in at least one plan task. A must-have that silently disappears from the plan is a `blocker`.
+  - **Deferred exclusion?** Items marked "Nice to Have", "Deferred", or "Out of Scope" in SPEC.md must not appear as plan tasks. Present → `blocker`.
+  - **Cross-surface consistency?** If SPEC.md marks an item as must-have but APPROACH.md marks it as deferred (or vice versa), surface the contradiction → `blocker`. Include a `fix_hint` asking the planner to resolve the conflict with the user before proceeding.
+- `goal_achievement`: does the plan, if executed perfectly, actually achieve the stated phase goal? Check:
+  - **Goal addressed?** Compare the phase goal statement to the plan's collective task outputs. Would successful completion of all tasks deliver the goal? If the goal says "users can authenticate" but tasks only set up database schema → `blocker`.
+  - **Success criteria reachable?** Are the phase success criteria from ROADMAP.md achievable through the planned tasks? Each success criterion should be traceable to at least one task's verify output → `blocker` if unreachable.
+  - **Outcome observable?** After execution, could a human or automated check confirm the goal was met? Plans that produce only internal artifacts with no user-visible or testable outcome → `warning`.
+- `approach_alignment`: when APPROACH.md is provided, verify that plan tasks implement the chosen approaches from the user's decisions. Check:
+  - **Chosen honored?** Does each plan task align with the approach chosen in APPROACH.md for its gray area? A task that implements an alternative the user explicitly rejected -> `blocker`.
+  - **Discretion respected?** "Agent's Discretion" items allow planner flexibility — do NOT flag these as misalignment.
+  - **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:
+
+```json
+{
+  "status": "passed",
+  "summary": "One sentence overall assessment",
+  "issues": [
+    {
+      "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
+      "severity": "blocker",
+      "description": "What is wrong",
+      "plan": "01-PLAN",
+      "task": "1-02",
+      "fix_hint": "Specific revision instruction"
+    }
+  ]
+}
+```
+
+Rules:
+- Status must be either `"passed"` or `"issues_found"`.
+- Use `"status": "passed"` only when no blockers remain. Warnings may still be listed.
+- Use `"status": "issues_found"` when any blocker exists or when warnings should be surfaced for revision.
+- Keep `fix_hint` targeted. The planner should patch the existing plan, not replan from scratch, unless the issue is fundamental.
+- If there are no issues, return `"issues": []`.
+
+Guardrails:
+- Do NOT write or edit plan files yourself.
+- Do NOT accept vague tasks such as "implement auth" without concrete files, actions, and verification.
+- Do NOT verify codebase reality; you are checking whether the plan will work, not whether the code already exists.
+- Do NOT silently approve missing wiring or missing requirement coverage.

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

@@ -1,30 +1,30 @@
-**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-You are researching ONE dimension: how systems in this domain are typically structured.
-
-The Orchestrator has provided you with:
-- Project goal / domain (in your Context)
-- Milestone context: `greenfield` or `subsequent` (in your Context)
-
-**If greenfield:** How are systems in this domain typically structured? What are the major components and boundaries?
-**If subsequent:** How do the target features integrate with existing architecture? What are the integration patterns?
-
-**Research question:** How are systems in this domain typically structured? What are the major components, their boundaries, and the suggested build order?
-
-Your output informs phase structure in ROADMAP.md. Include:
-- Component map: what each component is responsible for
-- Data flow: how information moves between components (direction matters)
-- Suggested build order: which components have dependencies ("Auth must exist before any user-scoped feature")
-- Key decision points: architectural choices that are hard to reverse
-
-<quality_gate>
-- [ ] Components have clear boundaries (what belongs, what doesn't)
-- [ ] Data flow direction explicit (not just "they communicate")
-- [ ] Build order implications documented (what blocks what)
-- [ ] Hard-to-reverse decisions flagged explicitly
-</quality_gate>
-
-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.
-Guardrails: Max Agent Hops = 3.
+**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+You are researching ONE dimension: how systems in this domain are typically structured.
+
+The Orchestrator has provided you with:
+- Project goal / domain (in your Context)
+- Milestone context: `greenfield` or `subsequent` (in your Context)
+
+**If greenfield:** How are systems in this domain typically structured? What are the major components and boundaries?
+**If subsequent:** How do the target features integrate with existing architecture? What are the integration patterns?
+
+**Research question:** How are systems in this domain typically structured? What are the major components, their boundaries, and the suggested build order?
+
+Your output informs phase structure in ROADMAP.md. Include:
+- Component map: what each component is responsible for
+- Data flow: how information moves between components (direction matters)
+- Suggested build order: which components have dependencies ("Auth must exist before any user-scoped feature")
+- Key decision points: architectural choices that are hard to reverse
+
+<quality_gate>
+- [ ] Components have clear boundaries (what belongs, what doesn't)
+- [ ] Data flow direction explicit (not just "they communicate")
+- [ ] Build order implications documented (what blocks what)
+- [ ] Hard-to-reverse decisions flagged explicitly
+</quality_gate>
+
+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.
+Guardrails: Max Agent Hops = 3.

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

@@ -1,30 +1,30 @@
-**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-You are researching ONE dimension: what features exist in this domain.
-
-The Orchestrator has provided you with:
-- Project goal / domain (in your Context)
-- Milestone context: `greenfield` or `subsequent` (in your Context)
-
-**If greenfield:** What features do products in this domain have? What's table stakes vs differentiating?
-**If subsequent:** How do the target features typically work? What do users expect as baseline behavior?
-
-**Research question:** What features do products in this domain have? What's table stakes (users leave without it) vs differentiating (competitive advantage) vs anti-feature (actively harmful to include in v1)?
-
-Your output feeds SPEC requirements. Categorize explicitly:
-- **Table Stakes**: Must have or users leave (each with brief why)
-- **Differentiators**: Competitive advantage (each with complexity estimate: low/medium/high)
-- **Anti-features**: Things to deliberately NOT build in v1 (with rationale)
-- Dependencies between features (Feature B requires Feature A)
-
-<quality_gate>
-- [ ] All three categories populated (table stakes / differentiators / anti-features)
-- [ ] Complexity estimate per differentiator (low/medium/high)
-- [ ] Dependencies between features identified
-- [ ] v1 vs v2 recommendation for differentiators
-</quality_gate>
-
-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.
-Guardrails: Max Agent Hops = 3.
+**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+You are researching ONE dimension: what features exist in this domain.
+
+The Orchestrator has provided you with:
+- Project goal / domain (in your Context)
+- Milestone context: `greenfield` or `subsequent` (in your Context)
+
+**If greenfield:** What features do products in this domain have? What's table stakes vs differentiating?
+**If subsequent:** How do the target features typically work? What do users expect as baseline behavior?
+
+**Research question:** What features do products in this domain have? What's table stakes (users leave without it) vs differentiating (competitive advantage) vs anti-feature (actively harmful to include in v1)?
+
+Your output feeds SPEC requirements. Categorize explicitly:
+- **Table Stakes**: Must have or users leave (each with brief why)
+- **Differentiators**: Competitive advantage (each with complexity estimate: low/medium/high)
+- **Anti-features**: Things to deliberately NOT build in v1 (with rationale)
+- Dependencies between features (Feature B requires Feature A)
+
+<quality_gate>
+- [ ] All three categories populated (table stakes / differentiators / anti-features)
+- [ ] Complexity estimate per differentiator (low/medium/high)
+- [ ] Dependencies between features identified
+- [ ] v1 vs v2 recommendation for differentiators
+</quality_gate>
+
+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.
+Guardrails: Max Agent Hops = 3.

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

@@ -1,30 +1,30 @@
-**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-You are researching ONE dimension: what goes wrong in projects in this domain.
-
-The Orchestrator has provided you with:
-- Project goal / domain (in your Context)
-- Milestone context: `greenfield` or `subsequent` (in your Context)
-
-**If greenfield:** What do projects in this domain commonly get wrong? Critical mistakes in early decisions?
-**If subsequent:** What are common mistakes when adding the target features to existing projects? Integration anti-patterns?
-
-**Research question:** What do projects in this domain commonly get wrong? What are the critical mistakes that are expensive to fix later?
-
-Your output prevents mistakes in roadmap and planning. For each pitfall:
-- Warning signs: how to detect it early
-- Prevention strategy: specific and actionable ("do X"), not vague ("be careful")
-- Which phase should address it (Phase 1? Phase 3?)
-- Severity: critical (breaks the product) / moderate (slows development) / minor (cleanup later)
-
-<quality_gate>
-- [ ] Pitfalls are specific to THIS domain, not generic advice
-- [ ] Prevention strategies are actionable ("do X"), not vague ("be careful")
-- [ ] Phase mapping included where relevant
-- [ ] Sources cited for non-obvious claims
-</quality_gate>
-
-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.
-Guardrails: Max Agent Hops = 3.
+**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+You are researching ONE dimension: what goes wrong in projects in this domain.
+
+The Orchestrator has provided you with:
+- Project goal / domain (in your Context)
+- Milestone context: `greenfield` or `subsequent` (in your Context)
+
+**If greenfield:** What do projects in this domain commonly get wrong? Critical mistakes in early decisions?
+**If subsequent:** What are common mistakes when adding the target features to existing projects? Integration anti-patterns?
+
+**Research question:** What do projects in this domain commonly get wrong? What are the critical mistakes that are expensive to fix later?
+
+Your output prevents mistakes in roadmap and planning. For each pitfall:
+- Warning signs: how to detect it early
+- Prevention strategy: specific and actionable ("do X"), not vague ("be careful")
+- Which phase should address it (Phase 1? Phase 3?)
+- Severity: critical (breaks the product) / moderate (slows development) / minor (cleanup later)
+
+<quality_gate>
+- [ ] Pitfalls are specific to THIS domain, not generic advice
+- [ ] Prevention strategies are actionable ("do X"), not vague ("be careful")
+- [ ] Phase mapping included where relevant
+- [ ] Sources cited for non-obvious claims
+</quality_gate>
+
+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.
+Guardrails: Max Agent Hops = 3.

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

@@ -1,30 +1,30 @@
-**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
-
-You are researching ONE dimension: the technology stack for the project domain.
-
-The Orchestrator has provided you with:
-- Project goal / domain (in your Context)
-- Milestone context: `greenfield` or `subsequent` (in your Context)
-
-**If greenfield:** Research the standard stack for building this domain from scratch.
-**If subsequent:** Research what libraries/tools are needed to ADD the target features to an existing app. Don't re-research the existing system.
-
-**Research question:** What is the current (2025/2026) standard stack for this domain? Which libraries are proven vs risky?
-
-Your output feeds the roadmapper. Be prescriptive:
-- Specific package names with current versions (verify via web search — do NOT rely on training data)
-- Clear rationale for each choice: why this, not the alternatives
-- Explicit "Do NOT use" list with reasons
-- Confidence level per recommendation: ✅ verified (official docs), ⚠️ likely, ❓ uncertain
-
-<quality_gate>
-- [ ] Versions verified against current official docs or registry (not training data)
-- [ ] Every recommendation has a rationale AND a counterpoint (when you'd choose differently)
-- [ ] "What NOT to use" section populated with specific packages and reasons
-- [ ] Confidence level assigned to each recommendation
-</quality_gate>
-
-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.
-Guardrails: Max Agent Hops = 3.
+**Role contract:** Read `.planning/templates/roles/researcher.md` before starting. Follow its algorithm, quality guarantees, and anti-patterns.
+
+You are researching ONE dimension: the technology stack for the project domain.
+
+The Orchestrator has provided you with:
+- Project goal / domain (in your Context)
+- Milestone context: `greenfield` or `subsequent` (in your Context)
+
+**If greenfield:** Research the standard stack for building this domain from scratch.
+**If subsequent:** Research what libraries/tools are needed to ADD the target features to an existing app. Don't re-research the existing system.
+
+**Research question:** What is the current (2025/2026) standard stack for this domain? Which libraries are proven vs risky?
+
+Your output feeds the roadmapper. Be prescriptive:
+- Specific package names with current versions (verify via web search — do NOT rely on training data)
+- Clear rationale for each choice: why this, not the alternatives
+- Explicit "Do NOT use" list with reasons
+- Confidence level per recommendation: ✅ verified (official docs), ⚠️ likely, ❓ uncertain
+
+<quality_gate>
+- [ ] Versions verified against current official docs or registry (not training data)
+- [ ] Every recommendation has a rationale AND a counterpoint (when you'd choose differently)
+- [ ] "What NOT to use" section populated with specific packages and reasons
+- [ ] Confidence level assigned to each recommendation
+</quality_gate>
+
+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.
+Guardrails: Max Agent Hops = 3.