cclaw-cli 0.49.0 → 0.51.1

package/dist/content/subagents.js

@@ -1,3 +1,5 @@
+import { stageDelegationSummary } from "./stage-schema.js";
+import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 /**
  * Markdown content generators for Cclaw’s subagent orchestration skills and enhanced
  * specialist payloads. Cclaw materializes static instructions — this module does not
@@ -10,6 +12,22 @@ const SUBAGENT_AGENT_NAMES = [
     "test-author",
     "doc-updater"
 ];
+function formatAgentList(agents) {
+    return agents.length > 0 ? agents.join(", ") : "none";
+}
+function automaticStageDelegationTable() {
+    const summary = stageDelegationSummary("standard");
+    const rows = summary.map((row) => {
+        return `| ${row.stage} | ${formatAgentList(row.mandatoryAgents)} | ${formatAgentList(row.proactiveAgents)} |`;
+    }).join("\n");
+    return `| Stage | Mandatory agents | Proactive agents |
+|---|---|---|
+${rows}`;
+}
+function stageSummary(stage) {
+    return stageDelegationSummary("standard").find((row) => row.stage === stage)
+        ?? { stage, mandatoryAgents: [], proactiveAgents: [], primaryAgents: [], stackAwareRoutes: [] };
+}
 export function subagentDrivenDevSkill() {
     return `---
 name: subagent-driven-development
@@ -30,56 +48,48 @@ This pattern is intentionally **Superpowers-style**: cheap parallelism where it
 
 ## Automatic Stage Delegation in Cclaw
 
-For cclaw flow stages, machine-only specialist work should auto-dispatch without waiting for a manual user request:
+For cclaw flow stages, machine-only specialist work should auto-dispatch without waiting for a manual user request. The table below is generated from the canonical stage dispatch registry:
 
-- **design/plan:** planner
-- **tdd:** test-author
-- **review:** reviewer + security-reviewer (security-reviewer is always mandatory; produce an explicit no-change attestation when no trust boundaries moved)
-- **ship:** doc-updater
+${automaticStageDelegationTable()}
 
 Human input remains mandatory only at explicit approval gates (plan approval, user challenge resolution, release finalization mode).
 
-### Review parallel fan-out protocol
+### Review dispatch protocol
 
-In review stage, prefer a fixed six-pass fan-out before reconciliation:
+In review stage, run mandatory specialists \`${formatAgentList(stageSummary("review").mandatoryAgents)}\` by default:
 
-1. \`review-spec\` (Layer 1)
-2. \`review-correctness\` (Layer 2a)
-3. \`review-security\` (Layer 2b)
-4. \`review-performance\` (Layer 2c)
-5. \`review-architecture\` (Layer 2d)
-6. \`review-external-safety\` (Layer 2e)
+1. \`reviewer\` owns Layer 1 spec compliance plus integrated Layer 2 tags (correctness, performance, architecture, external-safety).
+2. \`security-reviewer\` owns the mandatory security sweep or no-change attestation.
+3. Add \`adversarial-review\` only when trust boundaries changed, Critical/Important ambiguity remains, or the diff is both large and high-risk.
 
-Dispatch these in parallel where the harness supports isolated workers, then run
-one reconciliation pass that merges findings into \`.cclaw/artifacts/07-review-army.json\`
-with explicit source tags per finding.
+Reconcile findings into \`.cclaw/artifacts/07-review-army.json\` with explicit source tags per finding.
 
-### TDD phase fan-out protocol
+### TDD evidence protocol
 
-Treat RED, GREEN, and REFACTOR as separate delegated intents:
+Treat RED, GREEN, and REFACTOR as phase intents inside one mandatory \`test-author\` delegation by default:
 
 - \`tdd-red\`: tests only, no production writes
 - \`tdd-green\`: minimal production implementation, no new RED tests
 - \`tdd-refactor\`: cleanup only after GREEN is proven
 
 Set \`CCLAW_ACTIVE_AGENT\` to the active phase name when possible so workflow-guard
-can enforce phase-appropriate write boundaries.
+can enforce phase-appropriate write boundaries. Use separate workers only when the harness and slice boundary make the split genuinely useful; the mandatory gate is the evidence-backed \`test-author\` row, not three default subagents.
 
 ## Model & Harness Routing Notes
 
 ### Harness routing
 
-| Harness | Fallback | Delegation tool | Structured ask | Parity playbook |
+| Harness | Fallback | Delegation tool | Structured ask | Capability source |
 |---|---|---|---|---|
-| Claude | \`native\` | Task (named subagent_type) | AskUserQuestion | \`.cclaw/references/harnesses/claude-playbook.md\` |
-| Cursor | \`generic-dispatch\` | Task (generic subagent_type: explore/generalPurpose/…) | AskQuestion | \`.cclaw/references/harnesses/cursor-playbook.md\` |
-| OpenCode | \`role-switch\` | plugin dispatch _or_ in-session role-switch | \`question\` (permission-gated; \`permission.question: "allow"\`) | \`.cclaw/references/harnesses/opencode-playbook.md\` |
-| Codex | \`role-switch\` | in-session role-switch (mandatory evidenceRefs) | \`request_user_input\` (experimental; Plan / Collaboration mode) | \`.cclaw/references/harnesses/codex-playbook.md\` |
+| Claude | \`native\` | Task (named subagent_type) | AskUserQuestion | \`npx cclaw-cli doctor\` |
+| Cursor | \`generic-dispatch\` | Task (generic subagent_type: explore/generalPurpose/…) | AskQuestion | \`npx cclaw-cli doctor\` |
+| OpenCode | \`role-switch\` | plugin dispatch _or_ in-session role-switch | \`question\` (permission-gated; \`permission.question: "allow"\`) | \`npx cclaw-cli doctor\` |
+| Codex | \`role-switch\` | in-session role-switch (mandatory evidenceRefs) | \`request_user_input\` (experimental; Plan / Collaboration mode) | \`npx cclaw-cli doctor\` |
 
 **Dispatch rules driven by \`subagentFallback\`:**
 
 - \`native\` — use the harness's own named subagent primitive; delegation entry uses \`fulfillmentMode: "isolated"\`.
-- \`generic-dispatch\` — map each cclaw agent onto the generic dispatcher via the harness playbook; delegation entry uses \`fulfillmentMode: "generic-dispatch"\`.
+- \`generic-dispatch\` — map each cclaw agent onto the generic dispatcher with a role prompt; delegation entry uses \`fulfillmentMode: "generic-dispatch"\`.
 - \`role-switch\` — announce the role in-session, perform the work, append a delegation row with \`fulfillmentMode: "role-switch"\` and ≥1 \`evidenceRef\`. Without evidenceRefs the \`delegation:mandatory:current_stage\` check reports \`missingEvidence\` and blocks stage completion.
 
 The only time a \`harness_limitation\` waiver fires automatically is when every installed harness declares \`subagentFallback: "waiver"\`. cclaw 0.33 no longer maps Codex onto auto-waiver — the agent must role-switch with evidence.
@@ -115,9 +125,9 @@ Concrete per-stage rules so the controller does not have to guess which tier fit
 | design | planner (always) | security-reviewer (if trust boundary touched) | run \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` in-thread | escalate one specialist to \`deep\` only if a failure mode is Critical-severity |
 | spec | — | reviewer (if spec > 200 lines or multiple ACs) | — | escalate to \`deep\` only for spec ↔ design contradictions |
 | plan | planner (solo, always) | — | — | never fan out at plan stage; one owner for dependency graph |
-| tdd | — | test-author (each slice) · reviewer (slice-local) | doc-updater (API surface changes) | escalate to \`deep\` only when a RED test cannot be expressed (design leak) |
-| review | — | reviewer · security-reviewer (both mandatory) | doc-updater for release-note drift checks | escalate a \`balanced\` reviewer to \`deep\` only when two reviewers disagree on severity |
-| ship | — | security-reviewer (if blast radius is high) | doc-updater (changelog/migration notes) | escalate to \`balanced\` reviewer only if preflight finds a regression |
+| tdd | — | ${formatAgentList(stageSummary("tdd").primaryAgents)} (per slice, carrying RED/GREEN/REFACTOR evidence) · reviewer (slice-local only when sliceReview triggers) | doc-updater (API surface changes) | escalate to \`deep\` only when a RED test cannot be expressed (design leak) |
+| review | — | ${formatAgentList(stageSummary("review").mandatoryAgents)} (both mandatory) | doc-updater for release-note drift checks | escalate a \`balanced\` reviewer to \`deep\` only when two reviewers disagree on severity |
+| ship | — | ${formatAgentList(stageSummary("ship").proactiveAgents)} (if blast radius is high) | doc-updater (changelog/migration notes) | escalate to \`balanced\` reviewer only if preflight finds a regression |
 
 **De-escalation rules (avoid over-spending):**
 - If a \`deep\` planner run returns low-uncertainty output (single unambiguous plan), do **not** add a second \`deep\` pass in the same stage.
@@ -127,10 +137,21 @@ Concrete per-stage rules so the controller does not have to guess which tier fit
 
 ## HARD-GATE
 
+${conversationLanguagePolicyMarkdown()}
 **Never dispatch a subagent without a concrete, self-contained task description pasted into the prompt. Do not pass file references the subagent must read to understand its task.**
 
 If you catch yourself writing “read PLAN.md Task 3” or “implement the next unchecked item,” stop: expand the work into explicit text in the Task body before dispatching.
 
+## Anti-Drift Team Defaults
+
+Borrow the good part of Team/Ruflo-style orchestration without adding a swarm runtime:
+
+- **One controller owns alignment.** The parent keeps the task list, gate state, and final synthesis.
+- **Small fan-out by default.** Run at most 3-5 parallel agents, and only for independent read-only research or non-overlapping files.
+- **No parallel writes to adjacent surfaces.** If tasks may touch the same module, serialize them.
+- **Checkpoint before synthesis.** Each agent returns status, files inspected/changed, evidence, and blockers before the parent acts.
+- **Consensus is for hard calls only.** Use two reviewers when severity or architecture is disputed; otherwise one evidence-backed reviewer is enough.
+
 ## When to Use
 
 - Mid/large plans with multiple discrete tasks, dependencies, or risky overlap.
@@ -175,6 +196,7 @@ CONTEXT: {paste relevant file paths, types, patterns}
 CONSTRAINTS: {paste from spec — what NOT to do}
 
 After implementation:
+0. Write user-facing narrative in the parent/user language; keep status tokens unchanged.
 1. Run the full test suite
 2. Report your status: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
 3. If DONE_WITH_CONCERNS, list each concern
@@ -316,6 +338,7 @@ This document bridges **Superpowers-style task isolation** with the **gstack “
 
 ## HARD-GATE
 
+${conversationLanguagePolicyMarkdown()}
 **Never dispatch parallel IMPLEMENTATION agents that write to the same codebase. Parallel agents are for investigation, analysis, and review ONLY.**
 
 Implementation that touches shared source trees must remain **sequential** unless you have proven disjoint filesystem ownership (rare) and an explicit merge protocol.

package/dist/content/templates.d.ts

@@ -1,4 +1,4 @@
 export declare const ARTIFACT_TEMPLATES: Record<string, string>;
 export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n- Follow flow order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\n- Require explicit user confirmation after plan before TDD\n- Keep evidence artifacts in `.cclaw/artifacts/`\n- Enforce RED before GREEN in TDD\n- Run two-layer review (spec_compliance and code_quality) before ship\n- Validate all inputs before processing \u2014 never trust external data without sanitization\n- Prefer immutable data patterns and pure functions where the language supports them\n- Follow existing repo conventions, patterns, and directory structure \u2014 match the codebase\n- Verify claims with fresh evidence: \"tests pass\" requires running tests in this message\n- Use conventional commits: `type(scope): description` (feat, fix, refactor, test, docs, chore)\n\n## MUST_NEVER\n- Skip RED phase and jump directly to GREEN in TDD\n- Ship with critical review findings\n- Start implementation during /brainstorm\n- Modify generated cclaw files manually when CLI can regenerate them\n- Commit `.cclaw/` or generated shim files\n- Expose secrets, tokens, API keys, or absolute system paths in agent output\n- Duplicate existing functionality without explicit justification \u2014 search before building\n- Bypass security checks, linting hooks, or type checking to \"move faster\"\n- Claim success (\"Done,\" \"All good,\" \"Tests pass\") without running verification in this message\n- Make changes outside the blast radius of the current task without user consent\n\n## DELEGATION\nWhen a task requires specialist knowledge (security audit, performance profiling, database review),\ndelegate to a specialized agent or skill if the harness supports it. The primary agent should:\n1. Identify the specialist domain\n2. Provide focused context (relevant files, the specific concern)\n3. Evaluate the specialist output before acting on it \u2014 do not blindly apply recommendations\n";
-export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc-next`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick or medium track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc-next` = only progression path.\n- `/cc-learn` = knowledge capture and recall.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive via `/cc-ops archive` (agent flow) or archive runtime.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization).\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Protocols: `.cclaw/references/protocols/*.md`.\n- Preamble budget: `.cclaw/references/protocols/ethos.md`.\n";
+export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc-next`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick or medium track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc-next` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive via `npx cclaw-cli archive`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization).\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -2,15 +2,23 @@ import { CCLAW_VERSION, SHIP_FINALIZATION_MODES } from "../constants.js";
 import { orderedStageSchemas } from "./stage-schema.js";
 import { FLOW_STAGES } from "../types.js";
 const SHIP_FINALIZATION_ENUM_LINES = SHIP_FINALIZATION_MODES.map((mode) => `  - ${mode}`).join("\n");
-export const ARTIFACT_TEMPLATES = {
-    "01-brainstorm.md": `---
-stage: brainstorm
+const MARKDOWN_CODE_FENCE = "```";
+function artifactFrontmatter(stage) {
+    return `---
+stage: ${stage}
 schema_version: 1
 version: ${CCLAW_VERSION}
-feature: <feature-id>
+run: <run-id>
 locked_decisions: []
 inputs_hash: sha256:pending
----
+---`;
+}
+const SEED_SHELF_SECTION = `## Seed Shelf Candidates (optional)
+| Seed file | Trigger when | Suggested action | Status (planted/deferred/ignored) |
+|---|---|---|---|
+| .cclaw/seeds/SEED-YYYY-MM-DD-<slug>.md |  |  |  |`;
+export const ARTIFACT_TEMPLATES = {
+    "01-brainstorm.md": `${artifactFrontmatter("brainstorm")}
 
 # Brainstorm Artifact
 
@@ -53,10 +61,7 @@ inputs_hash: sha256:pending
 - **Rationale:**
 - **Approval:** pending
 
-## Seed Shelf Candidates (optional)
-| Seed file | Trigger when | Suggested action | Status (planted/deferred/ignored) |
-|---|---|---|---|
-| .cclaw/seeds/SEED-YYYY-MM-DD-<slug>.md |  |  |  |
+${SEED_SHELF_SECTION}
 
 ## Design
 - **Architecture:**
@@ -70,17 +75,17 @@ inputs_hash: sha256:pending
 ## Learnings
 - None this stage.
 `,
-    "02-scope.md": `---
-stage: scope
-schema_version: 1
-version: ${CCLAW_VERSION}
-feature: <feature-id>
-locked_decisions: []
-inputs_hash: sha256:pending
----
+    "02-scope.md": `${artifactFrontmatter("scope")}
 
 # Scope Artifact
 
+## Upstream Handoff
+- Source artifacts: \`00-idea.md\`, \`01-brainstorm-<slug>.md\`
+- Decisions carried forward:
+- Constraints carried forward:
+- Open questions:
+- Drift from upstream (or \`None\`):
+
 ## Pre-Scope System Audit
 | Check | Command | Findings |
 |---|---|---|
@@ -165,10 +170,7 @@ inputs_hash: sha256:pending
 |---|---|
 |  |  |
 
-## Seed Shelf Candidates (optional)
-| Seed file | Trigger when | Suggested action | Status (planted/deferred/ignored) |
-|---|---|---|---|
-| .cclaw/seeds/SEED-YYYY-MM-DD-<slug>.md |  |  |  |
+${SEED_SHELF_SECTION}
 
 ## Error & Rescue Registry
 | Capability | Failure mode | Detection | Fallback |
@@ -201,14 +203,7 @@ inputs_hash: sha256:pending
 ## Learnings
 - None this stage.
 `,
-    "02a-research.md": `---
-stage: design
-schema_version: 1
-version: ${CCLAW_VERSION}
-feature: <feature-id>
-locked_decisions: []
-inputs_hash: sha256:pending
----
+    "02a-research.md": `${artifactFrontmatter("design")}
 
 # Research Report
 
@@ -242,17 +237,17 @@ inputs_hash: sha256:pending
 ## Learnings
 - None this stage.
 `,
-    "03-design.md": `---
-stage: design
-schema_version: 1
-version: ${CCLAW_VERSION}
-feature: <feature-id>
-locked_decisions: []
-inputs_hash: sha256:pending
----
+    "03-design.md": `${artifactFrontmatter("design")}
 
 # Design Artifact
 
+## Upstream Handoff
+- Source artifacts: \`02-scope-<slug>.md\`, \`02a-research.md\` when present
+- Decisions carried forward:
+- Constraints carried forward:
+- Open questions:
+- Drift from upstream (or \`None\`):
+
 ## Codebase Investigation
 | File | Current responsibility | Patterns discovered |
 |---|---|---|
@@ -282,9 +277,9 @@ inputs_hash: sha256:pending
 
 <!-- diagram: architecture -->
 
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 (ASCII, Mermaid, or tool-generated diagram showing component boundaries and data flow direction)
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 
 ## Data-Flow Shadow Paths
 <!-- diagram: data-flow-shadow-paths -->
@@ -296,33 +291,33 @@ inputs_hash: sha256:pending
 
 <!-- diagram: error-flow -->
 
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 (failure detection -> rescue action -> user-visible outcome)
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 
 ## State Machine Diagram
 
 <!-- diagram: state-machine -->
 
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 (state transitions for the critical flow lifecycle)
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 
 ## Rollback Flowchart
 
 <!-- diagram: rollback-flowchart -->
 
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 (trigger -> rollback actions -> verification)
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 
 ## Deployment Sequence Diagram
 
 <!-- diagram: deployment-sequence -->
 
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 (rollout order, guard checks, and verification sequence)
-\`\`\`
+${MARKDOWN_CODE_FENCE}
 
 ## Stale Diagram Audit
 | File | Last modified | Diagram marker baseline | Status | Notes |
@@ -413,10 +408,7 @@ inputs_hash: sha256:pending
 |---|---|---|---|
 |  |  |  |  |
 
-## Seed Shelf Candidates (optional)
-| Seed file | Trigger when | Suggested action | Status (planted/deferred/ignored) |
-|---|---|---|---|
-| .cclaw/seeds/SEED-YYYY-MM-DD-<slug>.md |  |  |  |
+${SEED_SHELF_SECTION}
 
 ## Completion Dashboard
 | Review Section | Status | Issues |
@@ -435,17 +427,17 @@ inputs_hash: sha256:pending
 ## Learnings
 - None this stage.
 `,
-    "04-spec.md": `---
-stage: spec
-schema_version: 1
-version: ${CCLAW_VERSION}
-feature: <feature-id>
-locked_decisions: []
-inputs_hash: sha256:pending
----
+    "04-spec.md": `${artifactFrontmatter("spec")}
 
 # Specification Artifact
 
+## Upstream Handoff
+- Source artifacts: \`02-scope-<slug>.md\`, \`03-design-<slug>.md\`
+- Decisions carried forward:
+- Constraints carried forward:
+- Open questions:
+- Drift from upstream (or \`None\`):
+
 ## Acceptance Criteria
 | ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref |
 |---|---|---|---|
@@ -464,6 +456,11 @@ inputs_hash: sha256:pending
 - Constraints:
 - Assumptions:
 
+## Assumptions Before Finalization
+| Assumption | Source / confidence | Validation path | Disposition |
+|---|---|---|---|
+|  |  |  | accepted/rejected/open |
+
 ## Testability Map
 | Criterion ID | Verification approach | Command/manual steps |
 |---|---|---|
@@ -491,17 +488,17 @@ inputs_hash: sha256:pending
 ## Learnings
 - None this stage.
 `,
-    "05-plan.md": `---
-stage: plan
-schema_version: 1
-version: ${CCLAW_VERSION}
-feature: <feature-id>
-locked_decisions: []
-inputs_hash: sha256:pending
----
+    "05-plan.md": `${artifactFrontmatter("plan")}
 
 # Plan Artifact
 
+## Upstream Handoff
+- Source artifacts: \`03-design-<slug>.md\`, \`04-spec.md\`
+- Decisions carried forward:
+- Constraints carried forward:
+- Open questions:
+- Drift from upstream (or \`None\`):
+
 ## Dependency Graph
 - 
 
@@ -540,6 +537,12 @@ Execution rule: complete and verify each batch before starting the next batch.
 |---|---|
 | AC-1 | T-1 |
 
+## Execution Posture
+- Posture: sequential | dependency-batched | parallel-safe | blocked
+- Stop conditions:
+- Risk triggers:
+- TDD checkpoint plan: RED commit/checkpoint -> GREEN commit/checkpoint -> REFACTOR commit/checkpoint (or deferred because: )
+
 ## Locked Decision Coverage
 | Decision ID | Source section | Plan tasks implementing decision | Status |
 |---|---|---|---|
@@ -570,17 +573,32 @@ Execution rule: complete and verify each batch before starting the next batch.
 ## Learnings
 - None this stage.
 `,
-    "06-tdd.md": `---
-stage: tdd
-schema_version: 1
-version: ${CCLAW_VERSION}
-feature: <feature-id>
-locked_decisions: []
-inputs_hash: sha256:pending
----
+    "06-tdd.md": `${artifactFrontmatter("tdd")}
 
 # TDD Artifact
 
+## Upstream Handoff
+- Source artifacts: \`04-spec.md\`, \`05-plan.md\`
+- Decisions carried forward:
+- Constraints carried forward:
+- Open questions:
+- Drift from upstream (or \`None\`):
+
+## Test Discovery
+| Slice | Existing tests / helpers / fixtures | Exact command(s) | Pattern to extend |
+|---|---|---|---|
+| S-1 |  |  |  |
+
+## System-Wide Impact Check
+| Slice | Callbacks/state/interfaces/contracts affected | Coverage decision |
+|---|---|---|
+| S-1 |  | covered/out-of-scope because  |
+
+## Execution Posture
+- Posture: sequential | dependency-batched | blocked
+- RED/GREEN/REFACTOR checkpoint plan:
+- Incremental commits: yes/no/deferred because
+
 ## RED Evidence
 | Slice | Test name | Command | Failure output summary |
 |---|---|---|---|
@@ -637,17 +655,17 @@ inputs_hash: sha256:pending
 ## Learnings
 - None this stage.
 `,
-    "07-review.md": `---
-stage: review
-schema_version: 1
-version: ${CCLAW_VERSION}
-feature: <feature-id>
-locked_decisions: []
-inputs_hash: sha256:pending
----
+    "07-review.md": `${artifactFrontmatter("review")}
 
 # Review Artifact
 
+## Upstream Handoff
+- Source artifacts: \`04-spec.md\`, \`05-plan.md\`, \`06-tdd.md\`
+- Decisions carried forward:
+- Constraints carried forward:
+- Open questions:
+- Drift from upstream (or \`None\`):
+
 ## Layer 1 Verdict
 | Criterion | Verdict | Evidence |
 |---|---|---|
@@ -664,46 +682,25 @@ inputs_hash: sha256:pending
 |---|---|---|---|---|---|---|
 | CR-1 | reviewer / bot / ci | Critical/Important/Suggestion | path:line or n/a |  | open/in-progress/resolved/accepted-risk/rejected-with-evidence |  |
 
-## Review Army Contract
+## Review Findings Contract
 - See \`07-review-army.json\`
 - Reconciliation summary:
 
-## Review Readiness Dashboard
+## Review Readiness Snapshot
 
-| Pass | Status | Completed at (UTC) | Reviewer / source | Commit at review | Drift vs HEAD |
-|---|---|---|---|---|---|
-| Layer 1 — spec compliance | pass / fail / pending | <ISO 8601> | reviewer | <short sha> | <files changed since> |
-| Layer 2 — correctness | pass / fail / pending | <ISO 8601> | reviewer | <short sha> | <files changed since> |
-| Layer 2 — security | pass / fail / pending | <ISO 8601> | security-reviewer | <short sha> | <files changed since> |
-| Layer 2 — performance | pass / fail / pending | <ISO 8601> | reviewer | <short sha> | <files changed since> |
-| Layer 2 — architecture | pass / fail / pending | <ISO 8601> | reviewer | <short sha> | <files changed since> |
-| Adversarial review | pass / fail / n/a | <ISO 8601 or —> | adversarial-review skill | <short sha or —> | <drift or —> |
-| Review army schema valid | pass / fail | <ISO 8601> | jsonschema | <short sha> | n/a |
-
-### Delegation log snapshot (current run, current stage)
-- Path: \`.cclaw/state/delegation-log.json\`
-- Required: <list of mandatory specialists>
-- Completed: <list with timestamps>
-- Waived (with reason): <list or "none">
-- Pending: <list or "none">
-
-### Staleness signal
-- Worktree commit at last review pass: \`<short sha>\`
-- Worktree commit now: \`<short sha>\`
-- Files changed since last review pass: \`<count>\` (run \`git diff --stat <sha>..HEAD\` to inspect)
-- If drift > 0 lines, mark Layer 1 / Layer 2 results as **STALE — re-run before ship**.
-
-### Headline
-- Open critical blockers: <count>
-- Adversarial review pass: pass / fail / n/a
+- Completed checks: Layer 1, Layer 2 tags, security sweep, schema validation
+- Delegation log: \`.cclaw/state/delegation-log.json\` required/completed/waived/pending
+- Staleness signal: commit at last review pass vs current commit
+- Open critical blockers:
 - Ship recommendation: APPROVED | APPROVED_WITH_CONCERNS | BLOCKED
 
-## Completeness Score
+
+## Completeness Snapshot
 - AC coverage: <N>/<M> (<percent>%)
 - Task coverage (tasks backed by ≥1 test slice): <N>/<M>
 - Slice coverage (slices linked to ≥1 AC): <N>/<M>
-- Adversarial review pass: true | false
-- Overall score: <0-100>
+- Adversarial review: not triggered | pass | fail
+- Overall: complete | concerns | blocked
 
 ## Trace Matrix Check
 - Command: \`cclaw internal trace-matrix\`
@@ -754,17 +751,17 @@ inputs_hash: sha256:pending
   }
 }
 `,
-    "08-ship.md": `---
-stage: ship
-schema_version: 1
-version: ${CCLAW_VERSION}
-feature: <feature-id>
-locked_decisions: []
-inputs_hash: sha256:pending
----
+    "08-ship.md": `${artifactFrontmatter("ship")}
 
 # Ship Artifact
 
+## Upstream Handoff
+- Source artifacts: \`06-tdd.md\`, \`07-review.md\`
+- Decisions carried forward:
+- Constraints carried forward:
+- Open questions:
+- Drift from upstream (or \`None\`):
+
 ## Preflight Results
 - Review verdict:
 - Build:
@@ -798,21 +795,14 @@ ${SHIP_FINALIZATION_ENUM_LINES}
 - Exceptions (if any):
 
 ## Retro Gate Handoff
-- Run \`/cc-ops retro\` before archive.
+- Complete the retro gate before archive.
 - Retro artifact path: \`.cclaw/artifacts/09-retro.md\`
 - Archive remains blocked until retro gate is complete.
 
 ## Learnings
 - None this stage.
 `,
-    "09-retro.md": `---
-stage: retro
-schema_version: 1
-version: ${CCLAW_VERSION}
-feature: <feature-id>
-locked_decisions: []
-inputs_hash: sha256:pending
----
+    "09-retro.md": `${artifactFrontmatter("retro")}
 
 # Retro Artifact
 
@@ -919,13 +909,13 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 
 - \`/cc\` = entry and resume.
 - \`/cc-next\` = only progression path.
-- \`/cc-learn\` = knowledge capture and recall.
+- Knowledge capture and recall use the \`learnings\` skill when requested.
 
 ## Verification Discipline
 
 - No completion claim without fresh command evidence in this turn.
 - Do not mark gates passed from memory.
-- Keep evidence in \`.cclaw/artifacts/\`; archive via \`/cc-ops archive\` (agent flow) or archive runtime.
+- Keep evidence in \`.cclaw/artifacts/\`; archive via \`npx cclaw-cli archive\`.
 
 ## Delegation And Approvals
 
@@ -936,8 +926,9 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 ## Routing Source Of Truth
 
 - Primary router: \`.cclaw/skills/using-cclaw/SKILL.md\`.
-- Protocols: \`.cclaw/references/protocols/*.md\`.
-- Preamble budget: \`.cclaw/references/protocols/ethos.md\`.
+- Stage behavior: current stage skill plus \`.cclaw/state/flow-state.json\`.
+- Preamble budget: keep role/status announcements brief and avoid repeating
+  them unless the stage or role changes.
 `;
 export function buildRulesJson() {
     return {

package/dist/content/track-render-context.d.ts

@@ -0,0 +1,17 @@
+import type { FlowTrack } from "../types.js";
+export interface TrackRenderContext {
+    track: FlowTrack;
+    usesPlanTerminology: boolean;
+    traceabilitySourceNoun: string;
+    traceabilityIdNoun: string;
+    traceabilitySliceNoun: string;
+    upstreamArtifactLabel: string;
+    upstreamArtifactPath: string;
+}
+export declare function trackRenderContext(track: FlowTrack): TrackRenderContext;
+/**
+ * Render track-aware terminology for text that defaults to standard-track plan
+ * wording. Keep this centralized so quick-track rewrites do not drift across
+ * stage content generators.
+ */
+export declare function renderTrackTerminology(value: string, context: TrackRenderContext): string;