cclaw-cli 0.51.24 → 0.51.26

package/dist/content/reference-patterns.js

@@ -0,0 +1,391 @@
+export const REFERENCE_PATTERNS = [
+    {
+        id: "socraticode_context_readiness",
+        title: "Context Readiness",
+        intent: "Do not draft from memory. Start once the agent can name upstream artifacts, discovered code patterns, template shape, and open blockers.",
+        useWhen: "Every stage before writing or validating an artifact.",
+        policyNeedles: ["Context Readiness", "upstream freshness", "template shape"],
+        contracts: [
+            {
+                stage: "brainstorm",
+                guidance: [
+                    "Capture discovered project context before asking approval questions.",
+                    "Separate observed facts from assumptions and open blockers."
+                ],
+                artifactSections: ["Context", "Discovered context"]
+            },
+            {
+                stage: "scope",
+                guidance: [
+                    "Name which brainstorm decisions are fresh enough to carry forward.",
+                    "If upstream decisions are stale or missing, stop for re-scope instead of inventing boundaries."
+                ],
+                artifactSections: ["Upstream Handoff", "Scope Contract"]
+            },
+            {
+                stage: "design",
+                guidance: [
+                    "Read blast-radius code before locking architecture.",
+                    "Use reference patterns as examples to adapt, not authority to copy."
+                ],
+                artifactSections: ["Codebase Investigation", "Reference-Grade Contracts"]
+            },
+            {
+                stage: "tdd",
+                guidance: [
+                    "Discover tests and affected contracts before opening a RED vertical slice.",
+                    "Map the slice to the active source item before editing production code."
+                ],
+                artifactSections: ["Test Discovery", "System-Wide Impact Check", "Acceptance Mapping"]
+            },
+            {
+                stage: "review",
+                guidance: [
+                    "Review only after current diff, test evidence, and source-item coverage are known.",
+                    "A no-finding verdict still needs inspected-surface evidence."
+                ],
+                artifactSections: ["Review Evidence Scope", "Completeness Snapshot"]
+            },
+            {
+                stage: "ship",
+                guidance: [
+                    "Ship only after fresh preflight, rollback trigger, and finalization mode are explicit.",
+                    "Treat stale review or missing rollback evidence as a blocker, not a concern."
+                ],
+                artifactSections: ["Preflight Results", "Rollback Plan", "Finalization"]
+            }
+        ]
+    },
+    {
+        id: "addy_reference_grade_contracts",
+        title: "Reference-Grade Contracts",
+        intent: "Promote good examples into explicit contracts: source, invariant, adaptation, rejection boundary, and verification signal.",
+        useWhen: "Brainstorm, scope, and design need reusable patterns without copying unrelated behavior.",
+        policyNeedles: ["Reference Pattern Registry", "Reference-Grade Contracts", "accepted/rejected reference ideas"],
+        contracts: [
+            {
+                stage: "brainstorm",
+                guidance: [
+                    "Record which reference patterns informed each option and which were rejected.",
+                    "A challenger must name the reference idea that makes it meaningfully higher-upside."
+                ],
+                artifactSections: ["Reference Pattern Candidates", "Approaches"]
+            },
+            {
+                stage: "scope",
+                guidance: [
+                    "Lock accepted, rejected, and deferred reference ideas as scope boundaries.",
+                    "Do not let a reference expand scope unless the user explicitly opts in."
+                ],
+                artifactSections: ["Reference Pattern Registry", "Scope Contract"]
+            },
+            {
+                stage: "design",
+                guidance: [
+                    "For every mirrored pattern, name source, invariant, adaptation, and verification evidence.",
+                    "If a reference conflicts with local architecture, reject it and document the revival signal."
+                ],
+                artifactSections: ["Reference-Grade Contracts", "Patterns to Mirror", "Rejected Alternatives"]
+            }
+        ]
+    },
+    {
+        id: "evanflow_coder_overseer",
+        title: "Coder / Overseer Split",
+        intent: "Keep implementation and validation context isolated: coders edit bounded slices, overseers read only, and integration overseers validate shared touchpoints.",
+        useWhen: "TDD, review, and parallel worker orchestration need safe independent implementation with fresh verification.",
+        policyNeedles: ["coder/overseer", "integration overseer", "non-overlap checks"],
+        contracts: [
+            {
+                stage: "plan",
+                guidance: [
+                    "Executable packets name file ownership, shared interfaces, expected failing test, passing command, and stop conditions.",
+                    "Parallel writers are allowed only after non-overlap checks for files, shared interfaces, migrations/config, and baseline cleanliness."
+                ],
+                artifactSections: ["Task List", "Dependency Batches", "Execution Posture"]
+            },
+            {
+                stage: "tdd",
+                guidance: [
+                    "Coder edits only the assigned slice after RED evidence; read-only overseer validates spec fit and assertion quality.",
+                    "When 3+ independent packets run, use an integration overseer for named touchpoints and integration tests."
+                ],
+                artifactSections: ["Execution Posture", "Per-Slice Review", "Verification Ladder"]
+            },
+            {
+                stage: "review",
+                guidance: [
+                    "Layered reviewers reconcile findings by source tag, confidence, owner, and verification requirement.",
+                    "Do not accept implementer self-review as overseer evidence."
+                ],
+                artifactSections: ["Review Evidence Scope", "Review Findings Contract"]
+            }
+        ]
+    },
+    {
+        id: "superpowers_executable_packet",
+        title: "Executable Packet",
+        intent: "Plan tasks as self-contained packets with acceptance mapping, expected RED failure, GREEN command, allowed files, and stop conditions.",
+        useWhen: "Plan and TDD need work items a fresh agent can execute without hidden parent context.",
+        policyNeedles: ["executable packet", "expected failing test", "stop condition"],
+        contracts: [
+            {
+                stage: "plan",
+                guidance: [
+                    "Each task is copy-paste ready for a worker and includes acceptance criteria, file boundaries, expected failing test, passing command, and stop conditions.",
+                    "Tasks that depend on shared interfaces or migration/config files are serialized unless an integration contract exists."
+                ],
+                artifactSections: ["Task List", "Dependency Batches", "Execution Posture"]
+            },
+            {
+                stage: "tdd",
+                guidance: [
+                    "Open one packet as one vertical slice; do not mix unrelated packet evidence.",
+                    "Close packet only when RED, GREEN, REFACTOR, and verification evidence align."
+                ],
+                artifactSections: ["Acceptance Mapping", "RED Evidence", "GREEN Evidence", "REFACTOR Notes"]
+            }
+        ]
+    },
+    {
+        id: "gstack_question_tuning",
+        title: "Question Tuning",
+        intent: "Ask only decision-changing questions, auto-assume low-risk two-way doors, and stop on one-way-door decisions.",
+        useWhen: "Brainstorm/scope/spec interactions could drift into broad interrogation instead of useful approval gates.",
+        policyNeedles: ["one decision-changing question", "two-way door", "one-way door"],
+        contracts: [
+            {
+                stage: "brainstorm",
+                guidance: [
+                    "Ask one decision-changing question at a time and record impact only when it changes direction or blocks progress.",
+                    "Continue on low-risk defaults; stop on scope, architecture, security, data loss, public API, migration, auth/pricing, or approval uncertainty."
+                ],
+                artifactSections: ["Sharpening Questions", "Selected Direction"]
+            },
+            {
+                stage: "scope",
+                guidance: [
+                    "Present labeled scope moves with one recommendation; wait for user opt-in before treating a mode as selected.",
+                    "Record what signal would change the recommendation."
+                ],
+                artifactSections: ["Scope Mode", "Scope Contract"]
+            },
+            {
+                stage: "spec",
+                guidance: [
+                    "Chunk acceptance criteria for approval and stop on assumptions with irreversible impact.",
+                    "Rewrite vague criteria before asking the user to approve."
+                ],
+                artifactSections: ["Acceptance Criteria", "Assumptions Before Finalization", "Approval"]
+            }
+        ]
+    },
+    {
+        id: "evanflow_vertical_slice_tdd",
+        title: "Vertical-Slice TDD",
+        intent: "Execute behavior end-to-end in one reviewable slice instead of collecting unrelated test or implementation fragments.",
+        useWhen: "TDD and review need to prove a source item moved from RED to GREEN with traceable behavior evidence.",
+        policyNeedles: ["vertical slice", "RED vertical slice", "slice victory detector"],
+        contracts: [
+            {
+                stage: "tdd",
+                guidance: [
+                    "One vertical slice is one source item plus one or more ACs, tests, implementation, refactor notes, and verification evidence.",
+                    "Do not open a second vertical slice while RED evidence or regression repair remains open for the current slice."
+                ],
+                artifactSections: ["Execution Posture", "RED Evidence", "GREEN Evidence", "Verification Ladder"]
+            },
+            {
+                stage: "review",
+                guidance: [
+                    "Review source-item coverage by vertical slice, not by file count alone.",
+                    "A slice is review-ready only when RED, GREEN, REFACTOR, and verification evidence all line up."
+                ],
+                artifactSections: ["Completeness Snapshot", "Trace Matrix Check"]
+            }
+        ]
+    },
+    {
+        id: "superclaude_confidence_gates",
+        title: "Confidence Gates",
+        intent: "Require source verification before execution and a fresh self-check before completion claims.",
+        useWhen: "Stage work could proceed from memory, duplicate an existing implementation, or close with stale evidence.",
+        policyNeedles: ["pre-execution confidence", "post-implementation self-check", "source verification"],
+        contracts: [
+            {
+                stage: "design",
+                guidance: [
+                    "Before locking architecture, verify duplicate implementation risk, architecture fit, docs/source truth, and root-cause confidence.",
+                    "If confidence is low, stop for investigation instead of adding fallback layers."
+                ],
+                artifactSections: ["Codebase Investigation", "Architecture Confidence"]
+            },
+            {
+                stage: "review",
+                guidance: [
+                    "Review requirements met, assumptions verified, tests passing, and evidence freshness before any PASS verdict.",
+                    "Separate verified facts from implementer claims."
+                ],
+                artifactSections: ["Review Readiness Snapshot", "Final Verdict"]
+            }
+        ]
+    },
+    {
+        id: "oh_my_worker_lifecycle",
+        title: "Worker Lifecycle Evidence",
+        intent: "Make asynchronous or delegated work inspectable through state, dispatch, evidence refs, and stale-worker handling.",
+        useWhen: "Stages schedule subagents, role-switch work, or generic dispatch and need auditable completion evidence.",
+        policyNeedles: ["dispatch lifecycle", "stale worker", "strict worker JSON schema"],
+        contracts: [
+            {
+                stage: "plan",
+                guidance: [
+                    "Plan only bounded worker packets with clear file ownership, stop conditions, and evidence expectations.",
+                    "Name any dispatch or concurrency governor before workers start."
+                ],
+                artifactSections: ["Task List", "Dependency Batches", "Execution Posture"]
+            },
+            {
+                stage: "tdd",
+                guidance: [
+                    "Every scheduled worker needs a terminal return with evidence refs or an explicit blocker route.",
+                    "A stale worker blocks completion until resolved, failed, or structurally waived."
+                ],
+                artifactSections: ["Execution Posture", "Verification Ladder", "Per-Slice Review"]
+            },
+            {
+                stage: "review",
+                guidance: [
+                    "Synthesize reviewer returns by status, source tag, evidence refs, and unresolved blockers.",
+                    "Do not treat missing worker output as a clean review."
+                ],
+                artifactSections: ["Review Evidence Scope", "Review Findings Contract"]
+            }
+        ]
+    },
+    {
+        id: "gsd_hard_stop_routing",
+        title: "Hard-Stop Routing",
+        intent: "Advance only when unresolved checkpoints, stale handoffs, and verification debt are cleared or routed explicitly.",
+        useWhen: "A stage wants to continue despite missing gates, stale rewind markers, or uncertain next command state.",
+        policyNeedles: ["hard-stop next routing", "goal-backward verification", "operator line"],
+        contracts: [
+            {
+                stage: "tdd",
+                guidance: [
+                    "Start from the outcome that must be true, then verify source, tests, artifact wiring, and gate evidence from that goal backward.",
+                    "If source/test preflight blocks execution, route to the managed blocker taxonomy instead of fabricating RED evidence."
+                ],
+                artifactSections: ["TDD Blocker Taxonomy", "Verification Ladder"]
+            },
+            {
+                stage: "ship",
+                guidance: [
+                    "Block ship on unresolved checkpoints, stale handoffs, or verification debt.",
+                    "Report the compact operator line: stage, scope, validation issues, recovery state, and next action."
+                ],
+                artifactSections: ["Preflight Results", "Completion Status", "Handoff"]
+            }
+        ]
+    },
+    {
+        id: "everyinc_delegation_preflight",
+        title: "Delegation Preflight",
+        intent: "Use delegation only when support, consent, baseline, non-overlap, batch size, and fallback mode are known.",
+        useWhen: "A controller is about to fan out implementation or review work across multiple specialists.",
+        policyNeedles: ["delegation preflight", "non-overlapping files", "layered review synthesis"],
+        contracts: [
+            {
+                stage: "plan",
+                guidance: [
+                    "Before parallel writers, verify support, user consent when needed, baseline cleanliness, non-overlapping files, batch size, and fallback mode.",
+                    "Shared interfaces, migrations, config, and generated surfaces need an integration contract or serial execution."
+                ],
+                artifactSections: ["Dependency Batches", "Execution Posture"]
+            },
+            {
+                stage: "review",
+                guidance: [
+                    "Dedupe layered reviewer findings with confidence, owner, and verification requirement.",
+                    "Keep user-facing synthesis separate from raw worker returns."
+                ],
+                artifactSections: ["Layered Review Synthesis", "Review Findings Contract"]
+            }
+        ]
+    },
+    {
+        id: "ecc_worktree_control_plane",
+        title: "Worktree Control Plane",
+        intent: "Treat isolated worker state, handoff files, and orchestration snapshots as recoverable control-plane data rather than chat memory.",
+        useWhen: "Parallel or resumable work needs clear seed paths, state files, handoffs, and cleanup visibility.",
+        policyNeedles: ["worktree control plane", "handoff files", "orchestration snapshot"],
+        contracts: [
+            {
+                stage: "plan",
+                guidance: [
+                    "Name seed paths, worker handoff expectations, and integration touchpoints before isolated work begins.",
+                    "Cap ad-hoc teams and require agreement/conflict synthesis for any multi-agent result."
+                ],
+                artifactSections: ["Task List", "Dependency Batches", "Execution Posture"]
+            },
+            {
+                stage: "ship",
+                guidance: [
+                    "Confirm handoffs, cleanup, and orchestration state are captured before archive or closeout.",
+                    "Do not rely on chat transcript alone for recoverability."
+                ],
+                artifactSections: ["Handoff", "Completion Status"]
+            }
+        ]
+    },
+    {
+        id: "walkinglabs_victory_detector",
+        title: "Iterate / Victory Detector",
+        intent: "Iterate while evidence is missing; stop only when the stage-specific victory detector is satisfied or a real blocker is named.",
+        useWhen: "Content-only closeout wording for review and ship readiness.",
+        policyNeedles: ["Victory Detector", "iterate until evidence", "fresh evidence"],
+        contracts: [
+            {
+                stage: "review",
+                guidance: [
+                    "Victory Detector: Layer 1, Layer 2, security sweep, structured findings, and trace evidence are complete with no unresolved criticals unless verdict is BLOCKED.",
+                    "If the detector fails, iterate findings or route back to TDD; do not say LGTM."
+                ],
+                artifactSections: ["Review Readiness Snapshot", "Final Verdict"]
+            },
+            {
+                stage: "ship",
+                guidance: [
+                    "Victory Detector: valid review verdict, fresh preflight, rollback trigger/steps, selected finalization enum, and execution result are present.",
+                    "If any detector field is stale or missing, keep status BLOCKED."
+                ],
+                artifactSections: ["Preflight Results", "Rollback Plan", "Finalization", "Completion Status"]
+            }
+        ]
+    }
+];
+export function referencePatternsForStage(stage) {
+    return REFERENCE_PATTERNS.filter((pattern) => pattern.contracts.some((contract) => contract.stage === stage));
+}
+export function referencePatternContractsForStage(stage) {
+    return REFERENCE_PATTERNS.flatMap((pattern) => pattern.contracts
+        .filter((contract) => contract.stage === stage)
+        .map((contract) => ({
+        ...contract,
+        guidance: [...contract.guidance],
+        artifactSections: [...contract.artifactSections]
+    })));
+}
+export function referencePatternPolicyNeedles(stage) {
+    const needles = [];
+    const seen = new Set();
+    for (const pattern of referencePatternsForStage(stage)) {
+        for (const needle of pattern.policyNeedles) {
+            if (seen.has(needle))
+                continue;
+            seen.add(needle);
+            needles.push(needle);
+        }
+    }
+    return needles;
+}

package/dist/content/skills.js

@@ -4,6 +4,7 @@ import { FLOW_STAGES } from "../types.js";
 import { stageExamples } from "./examples.js";
 import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
 import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
+import { referencePatternsForStage } from "./reference-patterns.js";
 const VERIFICATION_STAGES = ["tdd", "review", "ship"];
 function whenNotToUseBlock(items) {
     if (items.length === 0) {
@@ -37,24 +38,17 @@ Before execution:
 2. Load active artifacts from \`.cclaw/artifacts/\`.
 3. Load upstream artifacts required by this stage:
 ${readLines}
-4. Read the state contract for this stage from \`.cclaw/templates/state-contracts/<stage>.json\`.
-   Treat it as the machine-readable skeleton: required top-level fields,
-   closed taxonomies, and the derived markdown path. Do not validate natural-language
-   prose by regex; put semantic quality checks in the review prompts.
-5. Read the canonical artifact template at \`${artifactTemplatePath}\` and reuse its
-   exact section layout — per-row tables with stable column order, calibrated review block;
-   do not invent layouts for sections the template already defines.
-6. Extract upstream decisions, constraints, and open questions into the current
-   artifact's \`Upstream Handoff\` section when that section exists.
-7. Before doing stage work, give a compact user-facing drift preamble: "Carrying forward: <1-3 bullets>. Drift since upstream: None / <specific drift>. Recommendation: continue / re-scope."
-8. If you change an upstream decision, record an explicit drift reason in the
-   current artifact before continuing.
-9. Confirm stage inputs:
+4. Read the state contract from \`.cclaw/templates/state-contracts/<stage>.json\` for required fields, taxonomies, and derived markdown path.
+5. Read the canonical artifact template at \`${artifactTemplatePath}\` and reuse its exact section layout — per-row tables with stable column order, calibrated review block; do not invent layouts.
+6. Extract upstream decisions, constraints, and open questions into the current artifact's \`Upstream Handoff\` section when present.
+7. Confirm context readiness: upstream artifact freshness, required context, canonical template shape, relevant in-repo/reference patterns, and unresolved blockers are known. If any item is missing, load it or stop before drafting.
+8. Before doing stage work, give a compact user-facing drift preamble: "Carrying forward: <1-3 bullets>. Drift since upstream: None / <specific drift>. Recommendation: continue / re-scope."
+9. If you change an upstream decision, record an explicit drift reason in the current artifact before continuing.
+10. Confirm stage inputs:
 ${inputs}
-10. Confirm required context:
+11. Confirm required context:
 ${requiredContext}
-11. Use the injected knowledge digest from session-start; only fall back to full
-   \`.cclaw/knowledge.jsonl\` when the digest is insufficient.
+12. Use the injected knowledge digest; only fall back to full \`.cclaw/knowledge.jsonl\` when insufficient.
 `;
 }
 function autoSubagentDispatchBlock(stage, track) {
@@ -65,35 +59,47 @@ function autoSubagentDispatchBlock(stage, track) {
     const rows = rules
         .map((rule) => {
         const userGate = rule.requiresUserGate ? "required" : "not required";
-        return `| ${rule.agent} | ${rule.mode} | ${userGate} | ${rule.when} | ${rule.purpose} |`;
+        const dispatchClass = rule.dispatchClass ?? "stage-specialist";
+        const returnSchema = rule.returnSchema ?? "agent-default";
+        return `| ${rule.agent} | ${rule.mode} | ${dispatchClass} | ${returnSchema} | ${userGate} | ${rule.when} | ${rule.purpose} |`;
     })
         .join("\n");
     const mandatory = schema.mandatoryDelegations;
     const mandatoryList = mandatory.length > 0 ? mandatory.map((a) => `\`${a}\``).join(", ") : "none";
     const delegationLogRel = `${RUNTIME_ROOT}/state/delegation-log.json`;
+    const delegationEventsRel = `${RUNTIME_ROOT}/state/delegation-events.jsonl`;
     const artifactRef = `${RUNTIME_ROOT}/artifacts/${schema.artifactRules.artifactFile}`;
     return `## Automatic Subagent Dispatch
-| Agent | Mode | User Gate | Trigger | Purpose |
-|---|---|---|---|---|
+| Agent | Mode | Class | Return Schema | User Gate | Trigger | Purpose |
+|---|---|---|---|---|---|---|
 ${rows}
-Mandatory: ${mandatoryList}. Record completion/waiver in \`${delegationLogRel}\` before completion.
-### Harness Dispatch Contract
-Use true harness dispatch: Claude native Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\`, Codex \`.codex/agents/<agent>.toml\`. Run independent read-only/review agents in parallel where safe, write evidence into \`${artifactRef}\`, then append \`${delegationLogRel}\` rows with matching \`fulfillmentMode: "isolated"\` or \`"generic-dispatch"\`. Do not collapse OpenCode or Codex to role-switch by default; role-switch is degraded fallback and must carry non-empty \`evidenceRefs\`. Missing evidence blocks completion.
+Mandatory: ${mandatoryList}. Record lifecycle rows in \`${delegationLogRel}\` and append-only \`${delegationEventsRel}\` before completion.
+### Harness Dispatch Contract — use true harness dispatch: Claude Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\` via Task/@agent, Codex \`.codex/agents/<agent>.toml\`. Do not collapse OpenCode or Codex to role-switch by default. Worker ACK Contract: ACK must include \`spanId\`, \`dispatchId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and \`ackTs\`; never claim \`fulfillmentMode: "isolated"\` without matching lifecycle proof. Helper: \`.cclaw/hooks/delegation-record.mjs --status=<status> --span-id=<spanId> --dispatch-id=<dispatchId> --dispatch-surface=<surface> --agent-definition-path=<path> --json\`. Exact recipe: scheduled -> launched -> acknowledged -> completed with the same span; completed isolated/generic rows require a prior ACK event for that span or \`--ack-ts=<iso>\`.
 `;
 }
 function researchPlaybooksBlock(playbooks) {
     if (playbooks.length === 0)
         return "";
     const rows = playbooks
-        .map((playbook) => `- \`${RUNTIME_ROOT}/skills/${playbook}\``)
-        .join("\n");
+        .map((playbook) => `\`${RUNTIME_ROOT}/skills/${playbook}\``)
+        .join("; ");
     return `## Research Playbooks
-
-Use these in-thread research procedures before locking this stage. They are
-playbooks (not delegated personas), so execute them in the primary agent context
-and record outcomes in the stage artifact when relevant.
-
-${rows}
+Execute in primary agent context before locking the stage; record outcomes in the artifact when relevant: ${rows}.
+`;
+}
+function referencePatternsBlock(stage) {
+    const patterns = referencePatternsForStage(stage);
+    if (patterns.length === 0)
+        return "";
+    const summaries = patterns
+        .map((pattern) => {
+        const contract = pattern.contracts.find((item) => item.stage === stage);
+        const sections = contract ? contract.artifactSections.join(", ") : "n/a";
+        return `${pattern.title} (sections: ${sections})`;
+    })
+        .join("; ");
+    return `## Reference Patterns
+Prompt-only; no runtime/delegation changes. These compact pattern titles come from the internal registry; use the behavior and artifact sections, not the source project history. Use: ${summaries}.
 `;
 }
 function reviewSectionsBlock(sectionsInput) {
@@ -242,8 +248,9 @@ function completionParametersBlock(schema, track) {
 - \`completion helper\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage}\`
 - \`completion helper with evidence\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage} --evidence-json '{"<gate_id>":"<evidence note>"}' --passed=<gate_id>[,<gate_id>]\`
 - \`completion helper JSON diagnostics\`: append \`--json\` to receive a machine-readable validation failure summary.
+- \`delegation record helper\`: \`node .cclaw/hooks/delegation-record.mjs --stage=${schema.stage} --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<spanId> --dispatch-id=<dispatchId> --dispatch-surface=<surface> --agent-definition-path=<path> --json\`. \`delegation helper recipe\`: call \`--status=scheduled\`, then \`--status=launched\`, then \`--status=acknowledged\`, then \`--status=completed\` with the same \`--span-id\`, \`--dispatch-id\`, \`--dispatch-surface\`, and \`--agent-definition-path\`; completed isolated/generic rows fail unless that same span already has an acknowledged event or the completed call includes \`--ack-ts=<iso>\`. For role-switch fallback, use \`--dispatch-surface=role-switch --evidence-ref=<artifact#anchor>\` instead of pretending isolated completion.
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
-- Record mandatory delegation completion/waiver in \`${RUNTIME_ROOT}/state/delegation-log.json\` with rationale as needed.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""}
+- Record mandatory delegation lifecycle in \`${RUNTIME_ROOT}/state/delegation-log.json\` and append proof events to \`${RUNTIME_ROOT}/state/delegation-events.jsonl\`; the ledger is current state, the event log is audit proof.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""}
 - Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If the helper fails, stop and report the exact command/output instead of applying a manual state workaround.
 - Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;
@@ -389,9 +396,8 @@ ${conversationLanguagePolicyMarkdown()}
 ${philosophy.purpose}
 
 ## Complexity Tier
-- Active tier: \`${schema.complexityTier}\`
-- Scale-to-complexity rule: execute required gates and artifact sections, but keep optional/deep sections compact unless risk, novelty, or configuration triggers them. Do not mechanically expand lightweight work into a strategy workshop.
-- Mandatory delegations at this tier: ${mandatoryDelegationSummary}
+- Active tier: \`${schema.complexityTier}\`; mandatory delegations: ${mandatoryDelegationSummary}
+- Scale-to-complexity: execute required gates/sections; keep optional/deep sections compact unless risk, novelty, or config triggers them.
 - Track render context: \`${trackContext.track}\` (${trackContext.usesPlanTerminology ? "plan-first wording" : "acceptance-first wording"})
 
 ## When to Use
@@ -406,14 +412,14 @@ ${mergedAntiPatterns(philosophy, executionModel)}
 
 ## Process
 
-This is the stage **state machine** — the canonical ordered flow. For every detailed step, gate, and wording, follow the Checklist below; this diagram is the map, not the territory.
-
+Stage state machine (map only; Checklist is authoritative):
 ${processFlowMermaid.length > 0 ? processFlowMermaid : "```mermaid\nflowchart TD\n  S1[\"Execute Checklist\"] --> S2[\"Satisfy required gates\"] --> S3[\"Verify before closeout\"]\n```"}
 
 ${platformNotesBlock}${contextLoadingBlock(stage, artifactRules.crossStageTrace, executionModel)}
 ${autoSubagentDispatchBlock(stage, track)}
 ${stackAwareReviewRoutingBlock(stage)}
 ${researchPlaybooksBlock(executionModel.researchPlaybooks ?? [])}
+${referencePatternsBlock(stage)}
 
 ## Checklist
 

package/dist/content/stage-common-guidance.js

@@ -14,6 +14,11 @@ ${conversationLanguagePolicyMarkdown()}
   harvest learnings, then use \`/cc-next\` for progression.
 - Do not create separate protocol files.
 
+## Context readiness
+
+- Before drafting, know the upstream artifact freshness, required template shape, relevant code/reference patterns, and unresolved blockers.
+- If any item is missing, load it or stop with a blocker instead of inventing content.
+
 ## Shared decision protocol
 
 - Ask only decision-changing questions.
@@ -28,7 +33,7 @@ Use this same closeout menu for every stage:
 - **A) Advance** — run \`/cc-next\` and continue the critical path; after \`ship\`, the same command drives \`retro -> compound -> archive\`.
 - **B) Revise this stage** — stay on current stage and apply feedback.
 - **C) Pause / park** — run \`/cc-view status\`, then stop and resume later.
-- **D) Rewind** — run \`npx cclaw-cli internal rewind <target-stage> "<reason>"\` as a support/runtime repair action.
+- **D) Rewind** — run \`npx cclaw-cli internal rewind <target-stage> "<reason>"\` as the managed support/runtime repair action; after redoing the target stage, run \`npx cclaw-cli internal rewind --ack <target-stage>\` to clear the stale marker.
 - **E) Abandon** — only when the user explicitly wants to end a non-ship active run early, archive with \`npx cclaw-cli archive --skip-retro --retro-reason="<reason>"\`. Once in post-ship closeout, continue \`/cc-next\` through retro/compound/archive instead.
 
 Recommendation defaults:
@@ -37,6 +42,12 @@ Recommendation defaults:
 - Completion status \`DONE_WITH_CONCERNS\` -> recommend **B**.
 - Completion status \`BLOCKED\` -> recommend **B** or **C**.
 
+## Iterate / Victory Detector
+
+- Iterate while a required gate, artifact section, or fresh evidence item is missing.
+- Stop only when the stage-specific Victory Detector passes or a named blocker is recorded.
+- Do not use vague closeout wording such as \`looks good\`, \`done enough\`, or \`all set\` without the detector evidence.
+
 ## Completion status vocabulary
 
 - \`DONE\` — all required gates and checks satisfied.
@@ -63,9 +74,12 @@ Rollback / fallback: <if decision proves wrong>
 
 Before closeout, fill the artifact \`## Learnings\` section (do not write
 \`.cclaw/knowledge.jsonl\` by hand):
-- \`- None this stage.\` when nothing reusable emerged.
+- \`- None this stage.\` only when nothing reusable emerged.
 - Or 1-3 JSON bullets with required keys \`type\`, \`trigger\`, \`action\`,
   \`confidence\` (optional fields may mirror knowledge.jsonl schema keys).
+- For meaningful \`design\`, \`tdd\`, or \`review\` work, prefer a small JSON
+  learning over \`None\` when you made a reusable decision, found a testing
+  pattern, or caught a review/security issue.
 During \`node .cclaw/hooks/stage-complete.mjs <stage>\`, cclaw validates those
 bullets, appends unique entries to \`.cclaw/knowledge.jsonl\`, and stamps a
 harvest marker in the artifact.
@@ -78,7 +92,9 @@ Track policy:
 - \`quick\`: recommended only.
 
 \`- None this stage.\` is acceptable only when the stage produced no reusable
-insight (for example, purely mechanical edits with no new decisions).
+insight (for example, purely mechanical edits with no new decisions). If unsure,
+record a concise \`lesson\` with \`confidence":"medium"\` instead of dropping
+operator knowledge.
 
 ## Progressive disclosure baseline
 

package/dist/content/stage-schema.d.ts

@@ -23,11 +23,23 @@ export interface StageStackAwareReviewRoute {
     signals: string[];
     focus: string;
 }
+export interface StageDelegationDispatchRule {
+    agent: string;
+    mode: "mandatory" | "proactive";
+    when: string;
+    purpose: string;
+    requiresUserGate: boolean;
+    requiredAtTier?: StageComplexityTier;
+    dispatchClass: NonNullable<StageAutoSubagentDispatch["dispatchClass"]>;
+    returnSchema: NonNullable<StageAutoSubagentDispatch["returnSchema"]>;
+    skill?: string;
+}
 export interface StageDelegationSummary {
     stage: FlowStage;
     mandatoryAgents: string[];
     proactiveAgents: string[];
     primaryAgents: string[];
+    dispatchRules: StageDelegationDispatchRule[];
     stackAwareRoutes: StageStackAwareReviewRoute[];
 }
 export declare function reviewStackAwareRoutes(): StageStackAwareReviewRoute[];