cclaw-cli 0.15.1 → 0.18.0

package/dist/content/protocols.js

@@ -90,42 +90,14 @@ Before adding new code/templates/rules:
 - Evidence beats volume.
 - Keep stage output concrete and testable.
 
-## Preamble budget
+## Turn announce discipline
 
-This section is the single source of truth for preamble behavior.
-Do not duplicate preamble rules in AGENTS.md, harness adapters, or stage-local docs.
+Keep orchestration visible without maintaining a dedicated preamble runtime log.
 
-### Emit when
-
-| Trigger | Machine-verifiable condition |
-|---|---|
-| Stage transition | \`flow-state.currentStage\` changes in this turn |
-| Non-trivial implementation turn | agent is about to run source-editing tools outside \`.cclaw/\` |
-| Multi-step risky operation | planned sequence contains 2+ commands with rollback/risk potential |
-
-### Skip when
-
-| Skip reason | Condition |
-|---|---|
-| Pure Q&A | no filesystem or runtime mutation planned |
-| Trivial change | single low-risk edit with no stage or plan drift |
-| Subagent dispatch payload | prompt is for spawned agent/tool call only |
-| Cooldown hit | same stage + same trigger emitted within cooldown window |
-
-### Form contract (max 4 lines)
-
-1. \`Stage:\` current stage id  
-2. \`Goal:\` concrete objective for this turn  
-3. \`Plan:\` next 1-3 actions  
-4. \`Guardrails:\` key constraints / non-goals
-
-### Cooldown
-
-- Record each emitted preamble in \`.cclaw/state/preamble-log.jsonl\` as JSON line:
-  \`{"ts","stage","runId","trigger","hash"}\`.
-- Default cooldown: 15 minutes for identical \`stage + trigger + hash\`.
-- TDD wave mode uses stricter dedupe: one preamble per wave unless scope changes.
-- If the plan changes materially, a new preamble is allowed inside cooldown.
+- Start substantial turns with a 1-2 sentence announce: current stage, intent, next action.
+- Skip announce for trivial single-command actions.
+- Never repeat boilerplate announces when the intent did not change.
+- If plan or risk changes materially, post a fresh announce before executing.
 
 ## Operational learning
 

package/dist/content/rewind-command.d.ts

@@ -1,3 +1,2 @@
 export declare function rewindCommandContract(): string;
-export declare function rewindAcknowledgeCommandContract(): string;
 export declare function rewindCommandSkillMarkdown(): string;

package/dist/content/rewind-command.js

@@ -15,7 +15,8 @@ export function rewindCommandContract() {
 
 ## Purpose
 
-Rewind active flow to an earlier stage and atomically invalidate downstream work.
+Rewind active flow to an earlier stage, or acknowledge stale markers after
+intentional rework.
 
 ## HARD-GATE
 
@@ -26,9 +27,12 @@ Rewind active flow to an earlier stage and atomically invalidate downstream work
 ## Inputs
 
 \`/cc-ops rewind <target-stage> [reason]\`
+or
+\`/cc-ops rewind --ack <stage>\`
 
 ## Algorithm
 
+### rewind mode
 1. Read \`${flowStatePath()}\` and current track.
 2. Validate \`target-stage\` belongs to the active track and is not ahead of current stage.
 3. Compute downstream stages to invalidate (all stages after target that were completed or current).
@@ -42,42 +46,24 @@ Rewind active flow to an earlier stage and atomically invalidate downstream work
    - append \`rewinds[]\` record
 7. Append JSON line to \`${rewindLogPath()}\`.
 
-## Output
-
-- Rewind id
-- from -> to stage
-- Invalidated stages list
-- Number of stale artifacts
-
-## Primary skill
-
-**${RUNTIME_ROOT}/skills/${REWIND_SKILL_FOLDER}/SKILL.md**
-`;
-}
-export function rewindAcknowledgeCommandContract() {
-    return `# /cc-ops rewind-ack
-
-## Purpose
-
-Acknowledge and clear stale-stage markers after downstream work is intentionally redone.
-
-## Input
-
-\`/cc-ops rewind-ack <stage>\`
-
-## HARD-GATE
-
-- Only clear stale marker for the requested stage.
-- Never modify completedStages from this command.
-
-## Algorithm
-
+### acknowledge mode (\`--ack\`)
 1. Read \`${flowStatePath()}\`.
 2. If \`staleStages.<stage>\` is missing, report no-op.
 3. Remove \`staleStages.<stage>\`.
 4. Write updated flow-state.
 5. Print remaining stale stages (if any).
 
+## Output
+
+- In rewind mode:
+  - rewind id
+  - from -> to stage
+  - invalidated stages list
+  - number of stale artifacts
+- In acknowledge mode:
+  - acknowledged stage
+  - remaining stale stages
+
 ## Primary skill
 
 **${RUNTIME_ROOT}/skills/${REWIND_SKILL_FOLDER}/SKILL.md**
@@ -89,7 +75,7 @@ name: ${REWIND_SKILL_NAME}
 description: "Rewind active flow stage safely and acknowledge stale invalidations."
 ---
 
-# /cc-ops rewind + /cc-ops rewind-ack
+# /cc-ops rewind
 
 ## HARD-GATE
 
@@ -105,7 +91,7 @@ Rewind is an atomic state transition. Never leave flow-state half-updated (for e
 5. Record \`rewinds[]\` and \`staleStages\` in flow-state.
 6. Append rewind entry into \`${rewindLogPath()}\`.
 
-### rewind-ack
+### rewind --ack <stage>
 1. Load flow-state stale map.
 2. Remove exactly one stale stage marker.
 3. Report remaining stale stages.

package/dist/content/skills.js

@@ -108,9 +108,8 @@ function waveExecutionModeBlock(stage) {
 
 Execute the current dependency wave task-by-task (RED -> GREEN -> REFACTOR).
 Stop on BLOCKED status or when user input is required.
-Apply preamble budget discipline: one preamble per wave, then continue without
-repeating it for each task. Re-emit only when the wave boundary changes or the
-plan changes materially.
+Apply concise turn announces: one announce per wave boundary (or when risk/plan
+changes materially), then execute tasks without repetitive boilerplate.
 
 Detailed walkthrough:
 \`.cclaw/${STAGE_EXAMPLES_REFERENCE_DIR}/tdd-wave-walkthrough.md\`

package/dist/content/stage-schema.js

@@ -59,14 +59,6 @@ const REQUIRED_GATE_IDS = {
         "ship_finalization_executed"
     ]
 };
-const CONDITIONAL_GATE_RULES = {
-    review: {
-        review_security_audit_swept: "diff_lines_gt:100||files_touched_gt:10||trust_boundary_changed"
-    },
-    ship: {
-        ship_post_merge_tests: "files_touched_gt:10||release_blast_radius_high"
-    }
-};
 const REQUIRED_ARTIFACT_SECTIONS = {
     brainstorm: ["Context", "Problem", "Approaches", "Selected Direction"],
     scope: ["Scope Mode", "In Scope / Out of Scope", "Completion Dashboard", "Scope Summary"],
@@ -77,26 +69,9 @@ const REQUIRED_ARTIFACT_SECTIONS = {
     review: ["Layer 1 Verdict", "Review Army Contract", "Severity Summary", "Final Verdict"],
     ship: ["Preflight Results", "Release Notes", "Rollback Plan", "Finalization"]
 };
-const CONDITIONAL_ARTIFACT_RULES = {
-    review: {
-        "Review Readiness Dashboard": "diff_lines_gt:100||files_touched_gt:10||trust_boundary_changed"
-    },
-    ship: {
-        Monitoring: "release_blast_radius_high"
-    }
-};
 function tieredStageGates(stage, gates) {
     const requiredSet = new Set(REQUIRED_GATE_IDS[stage]);
-    const conditional = CONDITIONAL_GATE_RULES[stage] ?? {};
     return gates.map((gate) => {
-        const condition = conditional[gate.id];
-        if (condition) {
-            return {
-                ...gate,
-                tier: "conditional",
-                condition
-            };
-        }
         return {
             ...gate,
             tier: requiredSet.has(gate.id) ? "required" : "recommended"
@@ -105,17 +80,7 @@ function tieredStageGates(stage, gates) {
 }
 function tieredArtifactValidation(stage, rows) {
     const requiredSections = new Set(REQUIRED_ARTIFACT_SECTIONS[stage]);
-    const conditional = CONDITIONAL_ARTIFACT_RULES[stage] ?? {};
     return rows.map((row) => {
-        const condition = conditional[row.section];
-        if (condition) {
-            return {
-                ...row,
-                tier: "conditional",
-                condition,
-                required: false
-            };
-        }
         const required = requiredSections.has(row.section);
         return {
             ...row,
@@ -291,9 +256,9 @@ export function stageRecommendedGateIds(stage) {
         .map((gate) => gate.id);
 }
 export function stageConditionalGateIds(stage) {
-    return stageSchema(stage).requiredGates
-        .filter((gate) => gate.tier === "conditional")
-        .map((gate) => gate.id);
+    // Conditional gate DSL removed in favor of explicit required/recommended tiers.
+    void stage;
+    return [];
 }
 export function nextCclawCommand(stage) {
     const next = stageSchema(stage).next;

package/dist/content/stages/plan.js

@@ -25,6 +25,8 @@ export const PLAN = {
         "Group tasks into dependency waves — wave N+1 cannot start until wave N has verification evidence.",
         "Slice into vertical tasks — each task targets 2-5 minutes, produces one testable outcome, and touches one coherent area.",
         "Attach verification — every task has an acceptance criterion mapping and a concrete verification command.",
+        "Map scope Locked Decisions — every D-XX from scope is referenced by at least one plan task (or explicitly marked deferred with reason).",
+        "Run anti-placeholder + anti-scope-reduction scans — block `TODO/TBD/...` and phrasing like `v1`, `for now`, `later` for locked boundaries.",
         "Define checkpoints — mark points where progress should be validated before continuing.",
         "WAIT_FOR_CONFIRM — write plan artifact and explicitly pause. **STOP.** Do NOT proceed until user confirms. Then update `flow-state.json` and tell user to run `/cc-next`."
     ],
@@ -33,6 +35,7 @@ export const PLAN = {
         "Split work into small vertical slices (target 2-5 minute tasks).",
         "Publish explicit dependency waves with entry and exit checks for each wave.",
         "Attach verification step to every task.",
+        "Preserve locked scope boundaries: no silent scope reduction language in task rows.",
         "Enforce WAIT_FOR_CONFIRM: present the plan summary with options (A) Approve / (B) Revise / (C) Reject.",
         "**STOP.** Do NOT proceed until user explicitly approves. Then update `flow-state.json` and tell user to run `/cc-next`."
     ],
@@ -40,6 +43,7 @@ export const PLAN = {
         "Build dependency graph and ordered slices.",
         "Group slices into execution waves and define gate criteria per wave.",
         "Define each task with acceptance mapping and verification commands.",
+        "Trace every locked decision (D-XX) to plan tasks or explicit defer rationale.",
         "Record checkpoints and blockers.",
         "Write plan artifact and pause at WAIT_FOR_CONFIRM."
     ],
@@ -54,6 +58,7 @@ export const PLAN = {
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/05-plan.md`.",
         "Task list includes acceptance mapping.",
+        "Locked decision coverage table present with D-XX trace links.",
         "Dependency graph documented.",
         "Dependency waves documented with wave-by-wave verification gates.",
         "WAIT_FOR_CONFIRM status recorded."
@@ -69,6 +74,7 @@ export const PLAN = {
         "tasks too broad",
         "dependency uncertainty unresolved",
         "wave boundaries are unclear",
+        "locked decisions from scope are not mapped to tasks",
         "no explicit confirmation"
     ],
     exitCriteria: [
@@ -81,16 +87,19 @@ export const PLAN = {
         "Horizontal decomposition without end-to-end slices",
         "Tasks without verification steps",
         "Starting execution before approval",
-        "Tasks that touch multiple unrelated areas"
+        "Tasks that touch multiple unrelated areas",
+        "Using placeholder tokens or scope-reduction phrases (`v1`, `for now`, `later`) in task definitions"
     ],
     redFlags: [
         "No dependency graph",
         "No WAIT_FOR_CONFIRM marker",
         "No explicit dependency waves",
         "Tasks exceed one coherent outcome",
-        "No acceptance mapping"
+        "No acceptance mapping",
+        "Locked decisions are missing or not mapped",
+        "Scope-reduction language appears without explicit approved defer decision"
     ],
-    policyNeedles: ["WAIT_FOR_CONFIRM", "Task Graph", "Dependency Waves", "Acceptance Mapping", "verification steps"],
+    policyNeedles: ["WAIT_FOR_CONFIRM", "Task Graph", "Dependency Waves", "Acceptance Mapping", "verification steps", "Locked Decision Coverage"],
     artifactFile: "05-plan.md",
     next: "tdd",
     reviewSections: [
@@ -131,16 +140,18 @@ export const PLAN = {
     crossStageTrace: {
         readsFrom: [".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
         writesTo: [".cclaw/artifacts/05-plan.md"],
-        traceabilityRule: "Every task must trace to a spec acceptance criterion. Every downstream RED test must trace to a plan task."
+        traceabilityRule: "Every task must trace to a spec acceptance criterion. Every locked scope decision (D-XX) must trace to at least one plan task or explicit defer rationale. Every downstream RED test must trace to a plan task."
     },
     artifactValidation: [
         { section: "Dependency Graph", required: true, validationRule: "Ordering and parallel opportunities explicit. No circular dependencies." },
         { section: "Dependency Waves", required: true, validationRule: "Every task belongs to a wave. Each wave has an exit gate and dependency statement." },
         { section: "Task List", required: true, validationRule: "Each task row includes ID, description, acceptance criterion, verification command, and effort estimate (S/M/L). Every task must also carry a minutes estimate within the 2-5 minute budget." },
         { section: "Acceptance Mapping", required: true, validationRule: "Every spec criterion is covered by at least one task." },
+        { section: "Locked Decision Coverage", required: false, validationRule: "Every locked decision ID (D-XX) from scope is listed with linked task IDs or explicit defer rationale." },
         { section: "Risk Assessment", required: false, validationRule: "If present: per-task or per-wave risk identification with likelihood, impact, and mitigation strategy." },
         { section: "Boundary Map", required: false, validationRule: "If present: per-wave or per-task interface contracts listing what each task produces (exports) and consumes (imports) from other tasks." },
         { section: "WAIT_FOR_CONFIRM", required: true, validationRule: "Explicit marker present. Status: pending until user approves." },
-        { section: "No-Placeholder Scan", required: false, validationRule: "If present: confirmation that a text scan for `TODO`, `TBD`, `FIXME`, `<fill-in>`, `<your-*-here>`, `xxx`, or bare ellipses has zero hits in the task list. A placeholder is a deferred decision masquerading as a plan." }
+        { section: "No-Placeholder Scan", required: false, validationRule: "Confirmation that a text scan for `TODO`, `TBD`, `FIXME`, `<fill-in>`, `<your-*-here>`, `xxx`, or bare ellipses has zero hits in the task list. A placeholder is a deferred decision masquerading as a plan." },
+        { section: "No Scope Reduction Language Scan", required: false, validationRule: "Confirmation that scope-reduction phrases (`v1`, `for now`, `later`, `temporary`, `placeholder`) are absent from task rows when locked decisions exist." }
     ]
 };

package/dist/content/stages/scope.js

@@ -50,6 +50,7 @@ export const SCOPE = {
         "Run mode-specific analysis that matches the selected scope mode.",
         "Walk through scope review sections one at a time.",
         "Write explicit scope contract, discretion areas, and deferred items.",
+        "Freeze non-negotiable boundaries as stable Locked Decisions (D-XX IDs).",
         "Produce scope summary plus completion dashboard (checklist findings, number of resolved decisions, unresolved items or `None`)."
     ],
     requiredGates: [
@@ -65,6 +66,7 @@ export const SCOPE = {
         "In-scope and out-of-scope lists are explicit.",
         "Discretion areas are explicit (or marked as `None`).",
         "Selected mode and rationale are documented.",
+        "Locked Decisions section lists stable D-XX IDs for non-negotiable boundaries.",
         "Premise challenge findings documented.",
         "Deferred items list with one-line rationale for each.",
         "Completion dashboard lists checklist findings, decision count, and unresolved items (or `None`)."
@@ -90,6 +92,7 @@ export const SCOPE = {
         "discretion areas recorded explicitly",
         "required gates marked satisfied",
         "deferred list recorded explicitly",
+        "locked decisions captured with stable D-XX IDs",
         "completion dashboard produced",
         "scope summary produced"
     ],
@@ -100,7 +103,8 @@ export const SCOPE = {
         "Sycophantic agreement without evidence-based pushback",
         "Hedged recommendations that avoid taking a position",
         "Batching multiple scope issues into one question",
-        "Re-arguing for smaller scope after user rejects reduction"
+        "Re-arguing for smaller scope after user rejects reduction",
+        "Using scope-reduction placeholders (`v1`, `for now`, `we can do later`) instead of explicit user-approved boundaries"
     ],
     redFlags: [
         "No selected mode in artifact",
@@ -109,9 +113,10 @@ export const SCOPE = {
         "No deferred/not-in-scope section",
         "No user approval marker",
         "Premise challenge missing or superficial",
-        "No implementation alternatives evaluated"
+        "No implementation alternatives evaluated",
+        "Missing Locked Decisions section or decisions without D-XX IDs"
     ],
-    policyNeedles: ["Scope mode", "In Scope", "Out of Scope", "Discretion Areas", "NOT in scope", "Premise Challenge"],
+    policyNeedles: ["Scope mode", "In Scope", "Out of Scope", "Discretion Areas", "NOT in scope", "Premise Challenge", "Locked Decisions"],
     artifactFile: "02-scope.md",
     next: "design",
     reviewSections: [
@@ -173,6 +178,7 @@ export const SCOPE = {
         { section: "Prime Directives", required: true, validationRule: "For each scoped capability: named failure modes, explicit error surface, four data-flow paths, interaction edge cases, observability expectations, and deferred-item handling." },
         { section: "Premise Challenge", required: true, validationRule: "Must contain explicit answers to: right problem? direct path? what if nothing?" },
         { section: "Requirements", required: true, validationRule: "Table of stable requirement IDs (R1, R2, R3…) one per row with observable outcome, priority, and source. IDs are assigned once and never renumbered across scope/design/spec/plan/review; dropped requirements stay with Priority `DROPPED`." },
+        { section: "Locked Decisions (D-XX)", required: false, validationRule: "List of stable locked decisions with IDs D-01, D-02... Each ID appears once, includes rationale, and is intended for downstream cross-stage traceability." },
         { section: "Implementation Alternatives", required: true, validationRule: "2-3 options with Name, Summary, Effort, Risk, Pros, Cons, and Reuses. Must include minimal viable and ideal architecture options." },
         { section: "Scope Mode", required: true, validationRule: "Must state selected mode and rationale with default heuristic justification." },
         { section: "Mode-Specific Analysis", required: true, validationRule: "Must document the analysis matching the selected scope mode: EXPAND (10x and delight opportunities), SELECTIVE (hold-scope baseline then cherry-picked expansions), HOLD (minimum-change-set hardening), REDUCE (ruthless cuts and follow-up split)." },

package/dist/content/stages/tdd.js

@@ -22,9 +22,9 @@ export const TDD = {
     checklist: [
         "Select plan slice — pick one task from the plan. Do not batch multiple tasks.",
         "Map to acceptance criterion — identify the specific spec criterion this test proves.",
-        "RED: Write behavior-focused test — test the expected behavior, not implementation details. Tests MUST fail.",
+        "Dispatch mandatory `test-author` subagent in `TEST_RED_ONLY` mode — produce failing behavior tests and RED evidence only (no production edits).",
         "RED: Capture failure output — copy the exact failure output as RED evidence. Record in artifact.",
-        "GREEN: Minimal implementation — write the smallest code change that makes the RED tests pass. No extra features.",
+        "Dispatch `test-author` subagent in `BUILD_GREEN_REFACTOR` mode — minimal implementation + full-suite GREEN + refactor notes.",
         "GREEN: Run full suite — execute ALL tests, not just the ones you wrote. The full suite must be GREEN.",
         "GREEN: Verify no regressions — if any existing test breaks, fix the regression before proceeding.",
         "REFACTOR: Improve code quality — without changing behavior. Document what you changed and why.",
@@ -34,6 +34,7 @@ export const TDD = {
     ],
     interactionProtocol: [
         "Pick one planned slice at a time.",
+        "Controller owns orchestration; execution runs through the mandatory `test-author` delegation for RED then GREEN/REFACTOR modes.",
         "Write behavior-focused tests before changing implementation (RED).",
         "Capture and store failing output as RED evidence.",
         "Apply minimal change to satisfy RED tests (GREEN).",
@@ -44,9 +45,9 @@ export const TDD = {
     ],
     process: [
         "Select slice and map to acceptance criterion.",
-        "Write test(s) that fail for expected reason (RED).",
+        "Dispatch `test-author` in TEST_RED_ONLY mode and produce failing test(s) for expected reason (RED).",
         "Run tests and capture failure output.",
-        "Implement smallest change needed for GREEN.",
+        "Dispatch `test-author` in BUILD_GREEN_REFACTOR mode and implement smallest change needed for GREEN.",
         "Run full tests and build checks.",
         "Perform refactor pass preserving behavior.",
         "Record RED, GREEN, and REFACTOR evidence in artifact.",

package/dist/content/templates.js

@@ -1,7 +1,16 @@
 import { COMMAND_FILE_ORDER } from "../constants.js";
 import { orderedStageSchemas } from "./stage-schema.js";
 export const ARTIFACT_TEMPLATES = {
-    "01-brainstorm.md": `# Brainstorm Artifact
+    "01-brainstorm.md": `---
+stage: brainstorm
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Brainstorm Artifact
 
 ## Context
 - **Project state:**
@@ -37,7 +46,16 @@ export const ARTIFACT_TEMPLATES = {
 - **Assumptions:**
 - **Open questions (or "None"):**
 `,
-    "02-scope.md": `# Scope Artifact
+    "02-scope.md": `---
+stage: scope
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Scope Artifact
 
 ## Prime Directives
 - Zero silent failures:
@@ -94,6 +112,11 @@ export const ARTIFACT_TEMPLATES = {
 > is later dropped, keep the row and mark Priority \`DROPPED\`; if a new one is
 > added mid-flow, append with the next free R-number — do NOT reuse numbers.
 
+## Locked Decisions (D-XX)
+| Decision ID | Decision | Why locked now | Downstream impact |
+|---|---|---|---|
+| D-01 |  |  |  |
+
 ## In Scope / Out of Scope
 
 ### In Scope
@@ -126,7 +149,16 @@ export const ARTIFACT_TEMPLATES = {
 - Deferred:
 - Explicitly excluded:
 `,
-    "03-design.md": `# Design Artifact
+    "03-design.md": `---
+stage: design
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Design Artifact
 
 ## Codebase Investigation
 | File | Current responsibility | Patterns discovered |
@@ -210,7 +242,16 @@ export const ARTIFACT_TEMPLATES = {
 
 **Decisions made:** 0 | **Unresolved:** 0
 `,
-    "04-spec.md": `# Specification Artifact
+    "04-spec.md": `---
+stage: spec
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Specification Artifact
 
 ## Acceptance Criteria
 | ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref |
@@ -254,7 +295,16 @@ export const ARTIFACT_TEMPLATES = {
 - Approved by:
 - Date:
 `,
-    "05-plan.md": `# Plan Artifact
+    "05-plan.md": `---
+stage: plan
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Plan Artifact
 
 ## Dependency Graph
 - 
@@ -282,6 +332,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 **Rules (apply before writing rows):**
 - Every task fits the **2-5 minute budget**. If \`[~Nm]\` is >5, split the task.
 - **No placeholders.** Forbidden tokens anywhere in this table: \`TODO\`, \`TBD\`, \`FIXME\`, \`<fill-in>\`, \`<your-*-here>\`, \`xxx\`, bare ellipsis. Every file path, test, and verification command must be copy-pasteable as written.
+- **No silent scope reduction.** Forbidden phrasing when locked decisions exist: \`v1\`, \`for now\`, \`later\`, \`temporary\`, \`placeholder\`, \`mock for now\`, \`hardcoded for now\`, \`will improve later\`.
 - If an estimate is genuinely uncertain (new library, unfamiliar subsystem), add a **spike task in wave 0** to de-risk — do NOT hide the uncertainty inside a large estimate.
 
 | Task ID | Description | Acceptance criterion | Verification command | Effort (S/M/L) | Minutes |
@@ -293,6 +344,11 @@ Execution rule: complete and verify each wave before starting the next wave.
 |---|---|
 | AC-1 | T-1 |
 
+## Locked Decision Coverage
+| Decision ID | Source section | Plan tasks implementing decision | Status |
+|---|---|---|---|
+| D-01 | 02-scope.md > Locked Decisions | T-1 | covered |
+
 ## Risk Assessment
 | Task/Wave | Risk | Likelihood | Impact | Mitigation |
 |---|---|---|---|---|
@@ -307,11 +363,24 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Scanned tokens: \`TODO\`, \`TBD\`, \`FIXME\`, \`<fill-in>\`, \`<your-*-here>\`, \`xxx\`, bare ellipsis in task rows.
 - Hits: 0 (required for WAIT_FOR_CONFIRM to resolve).
 
+## No Scope Reduction Language Scan
+- Scanned phrases: \`v1\`, \`for now\`, \`later\`, \`temporary\`, \`placeholder\`, \`mock for now\`, \`hardcoded for now\`, \`will improve later\`.
+- Hits: 0 (required when Locked Decisions section is non-empty).
+
 ## WAIT_FOR_CONFIRM
 - Status: pending
 - Confirmed by:
 `,
-    "06-tdd.md": `# TDD Artifact
+    "06-tdd.md": `---
+stage: tdd
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# TDD Artifact
 
 ## RED Evidence
 | Slice | Test name | Command | Failure output summary |
@@ -366,7 +435,16 @@ Execution rule: complete and verify each wave before starting the next wave.
 |---|---|---|---|---|
 | S-1 |  |  |  |  |
 `,
-    "07-review.md": `# Review Artifact
+    "07-review.md": `---
+stage: review
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Review Artifact
 
 ## Layer 1 Verdict
 | Criterion | Verdict | Evidence |
@@ -444,7 +522,16 @@ Execution rule: complete and verify each wave before starting the next wave.
   }
 }
 `,
-    "08-ship.md": `# Ship Artifact
+    "08-ship.md": `---
+stage: ship
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Ship Artifact
 
 ## Preflight Results
 - Review verdict:
@@ -485,7 +572,16 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Retro artifact path: \`.cclaw/artifacts/09-retro.md\`
 - Archive remains blocked until retro gate is complete.
 `,
-    "09-retro.md": `# Retro Artifact
+    "09-retro.md": `---
+stage: retro
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Retro Artifact
 
 ## Run Summary
 - Flow track:

package/dist/content/utility-skills.js

@@ -1271,7 +1271,7 @@ For each lens, write either a knowledge entry **or** the explicit string
 ## Output protocol
 
 For every harvested insight, append one strict-schema JSON line to
-\`.cclaw/knowledge.jsonl\` (fields: \`type, trigger, action, confidence, domain, stage, created, project\`).
+\`.cclaw/knowledge.jsonl\` (fields: \`type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`).
 See the \`learnings\` skill for the canonical shape. Choose \`type\`:
 
 - \`compound\` for process/speed accelerators.

package/dist/delegation.d.ts

@@ -1,12 +1,34 @@
 import type { FlowStage } from "./types.js";
+export type DelegationMode = "mandatory" | "proactive" | "conditional";
+export type DelegationStatus = "scheduled" | "completed" | "failed" | "waived";
+export interface DelegationTokenUsage {
+    input: number;
+    output: number;
+    model: string;
+}
 export type DelegationEntry = {
     stage: string;
     agent: string;
-    mode: "mandatory" | "proactive" | "conditional";
-    status: "scheduled" | "completed" | "failed" | "waived";
+    mode: DelegationMode;
+    status: DelegationStatus;
+    /**
+     * Span identifier for this delegation unit. Multiple status transitions for
+     * the same delegated unit should reuse the same spanId.
+     */
+    spanId?: string;
+    /** Parent span id when this delegation was spawned from another span. */
+    parentSpanId?: string;
+    /** ISO timestamp when the delegation span started. */
+    startTs?: string;
+    /** ISO timestamp when the delegation span ended (for terminal statuses). */
+    endTs?: string;
+    /**
+     * Legacy timestamp used by historical ledgers. New writers set both `ts` and
+     * `startTs` for backward compatibility.
+     */
     taskId?: string;
     waiverReason?: string;
-    ts: string;
+    ts?: string;
     /**
      * Run id the entry belongs to. Older ledgers written before 0.5.17 may omit this;
      * consumers treat missing runId as unscoped (conservatively excluded from current-run checks).
@@ -17,6 +39,14 @@ export type DelegationEntry = {
      * Recorded for audit so reviewers can see why the second pass was required.
      */
     conditionTrigger?: string;
+    /** Optional token usage captured from the delegated run. */
+    tokens?: DelegationTokenUsage;
+    /** Number of retries attempted for this span. */
+    retryCount?: number;
+    /** Optional references to evidence anchors in artifacts. */
+    evidenceRefs?: string[];
+    /** Schema version marker for span-compatible delegation logs. */
+    schemaVersion?: 1;
 };
 export type DelegationLedger = {
     runId: string;