cclaw-cli 0.49.0 → 0.51.0

package/dist/content/research-playbooks.js

@@ -38,10 +38,11 @@ Reuse prior project knowledge before choosing a direction.
 
 ## Steps
 
-1. Read \`.cclaw/knowledge.jsonl\`.
-2. Match by stage/domain keywords from the current task.
-3. Rank matches by confidence and recency.
-4. Return the top entries verbatim.
+1. Use the session-injected knowledge digest first.
+2. Read \`.cclaw/knowledge.jsonl\` only if the digest is missing or too thin.
+3. Match by stage/domain keywords from the current task.
+4. Rank matches by confidence and recency.
+5. Return the top entries verbatim.
 
 ## Output Contract
 
@@ -107,18 +108,17 @@ Summarize citable domain practices for a narrow design decision.
 
 ## Purpose
 
-Run a four-lens investigation before design lock so architecture choices are grounded
+Run a tiered investigation before design lock so architecture choices are grounded
 in current ecosystem data, not intuition.
 
-## Dispatch Lenses (fan-out)
+## Dispatch Lenses (tiered)
 
-Launch four independent investigation threads in parallel when the harness supports it
-(or sequentially with explicit role-switch logs when it does not):
+Choose the smallest tier that matches the change; use parallel threads only when the
+harness supports it and the lenses are independent:
 
-1. **stack-researcher** — dependency compatibility, alternatives, deprecations.
-2. **features-researcher** — domain conventions and product/UX patterns.
-3. **architecture-researcher** — architecture options and trade-off matrix.
-4. **pitfalls-researcher** — known failure modes, CVEs, and operational traps.
+- **Lightweight:** pitfalls-researcher only — known failure modes, CVEs, and operational traps.
+- **Standard:** architecture-researcher + pitfalls-researcher.
+- **Deep:** stack-researcher + features-researcher + architecture-researcher + pitfalls-researcher.
 
 ## Output Contract
 
@@ -130,8 +130,8 @@ Write findings to \`.cclaw/artifacts/02a-research.md\` with these sections:
 - \`## Pitfalls & Risks\`
 - \`## Synthesis\`
 
-Each section must contain concrete notes and at least one evidence reference
-(source URL, file path, or command output anchor).
+Each section that was run must contain concrete notes and at least one evidence reference
+(source URL, file path, or command output anchor). Sections skipped by tier should say \`Not run for this tier\`.
 
 ## Guardrails
 

package/dist/content/review-loop.d.ts

@@ -100,6 +100,8 @@ export interface RunReviewLoopOptions {
     shouldOptOut?: () => boolean;
     emitEnvelope?: (envelope: ReviewLoopEnvelope) => void;
 }
+export declare function reviewLoopPolicySummary(stage: ReviewLoopStage): string;
+export declare function reviewLoopSecondOpinionSummary(stage: ReviewLoopStage): string;
 export declare const REVIEW_LOOP_CHECKLISTS: {
     readonly scope: readonly [{
         readonly id: "premise_fit";

package/dist/content/review-loop.js

@@ -22,6 +22,14 @@ const REVIEW_LOOP_RESPONSE_SCHEMA = `{
     }
   ]
 }`;
+export function reviewLoopPolicySummary(stage) {
+    const checklist = REVIEW_LOOP_CHECKLISTS[stage];
+    const ids = checklist.map((dimension) => `\`${dimension.id}\``).join(", ");
+    return `outside-voice review loop policy: use checklist dimensions ${ids}; stop at quality score >= ${REVIEW_LOOP_DEFAULT_TARGET_SCORE} or max ${REVIEW_LOOP_DEFAULT_MAX_ITERATIONS} iterations.`;
+}
+export function reviewLoopSecondOpinionSummary(stage) {
+    return `when \`.cclaw/config.yaml::reviewLoop.externalSecondOpinion.enabled\` is true, run an extra external-model pass for ${stage} and explicitly reconcile score/finding disagreements.`;
+}
 export const REVIEW_LOOP_CHECKLISTS = {
     scope: [
         {

package/dist/content/session-hooks.js

@@ -19,25 +19,24 @@ These are prompt-discipline guidelines that complement the real hooks cclaw gene
 
 ## HARD-GATE
 
-**Never end a session with uncommitted or untested changes.** If you must stop, create a checkpoint first.
+**Never end a session with uncommitted or untested changes.** If you must stop, leave a short handoff in the current artifact or commit message.
 
 ## Session Start Protocol
 
 When a new session begins in any harness:
 
 1. **Read flow state:** Load \`.cclaw/state/flow-state.json\` to find the current stage and completed stages.
-2. **Load knowledge:** Stream the tail of \`.cclaw/knowledge.jsonl\` (strict JSONL store) and surface the most relevant rules/patterns.
+2. **Load knowledge:** Use the session-injected knowledge digest first; stream \`.cclaw/knowledge.jsonl\` only when the digest is missing or insufficient.
 3. **Check for in-progress work:** If the last stage is incomplete, remind the user and offer to resume.
-4. **Load suggestion memory:** Read \`.cclaw/state/suggestion-memory.json\` and honor \`enabled=false\` opt-out.
-5. **Load iron laws:** Read \`.cclaw/state/iron-laws.json\` to know which laws are strict in this repo.
-6. **Read AGENTS.md:** The cclaw block contains routing and rules — follow them.
+4. **Load iron laws:** Read \`.cclaw/state/iron-laws.json\` to know which laws are strict in this repo.
+5. **Read AGENTS.md:** The cclaw block contains routing and rules — follow them.
 
 ### What to show the user at session start
 
 \`\`\`
 Cclaw flow state: [current stage] ([N] of 8 stages completed)
 Knowledge highlights: [rule/pattern 1], [rule/pattern 2], [rule/pattern 3]
-Next action: /cc-[stage] to continue, or describe what you'd like to do.
+Next action: /cc-next to continue, /cc to start new work, or describe what you'd like to do.
 \`\`\`
 
 ## Session Stop Protocol
@@ -47,7 +46,7 @@ Before ending a session or when context is full:
 1. **Verify no pending changes:** All modified files must be either committed or explicitly reverted.
 2. **Update flow state:** Mark the current stage as its actual status (DONE / DONE_WITH_CONCERNS / BLOCKED).
 3. **Write knowledge:** If any non-obvious reusable insight appears, append one strict-schema JSON line to \`.cclaw/knowledge.jsonl\` with type \`rule\`, \`pattern\`, \`lesson\`, or \`compound\`.
-4. **Create checkpoint:** Write a brief status note to the current artifact or as a comment in flow-state.json.
+4. **Leave handoff context:** Put blockers and remaining work in the current stage artifact, not a separate state file.
 
 ### Stop conditions (agent must halt and report)
 
@@ -61,44 +60,13 @@ Before ending a session or when context is full:
 When resuming work after a break:
 
 1. Re-read \`.cclaw/state/flow-state.json\` (may have changed externally).
-2. Re-read the current stage's artifact to verify it matches your last checkpoint.
-3. Re-load recent knowledge entries.
+2. Re-read the current stage's artifact to verify it matches the last handoff.
+3. Re-load the knowledge digest first, then scan \`.cclaw/knowledge.jsonl\` only if the digest lacks enough evidence.
 4. Continue from the last incomplete step — do not restart the stage.
 
-## Proactive Suggestion Memory
+### Optional session-history scan for compound
 
-Cclaw can emit short stage-specific reminders at session start to reduce misses.
-
-- State file: \`.cclaw/state/suggestion-memory.json\`
-- Default: \`enabled: true\`
-- Persistent opt-out: set \`enabled: false\` and keep the file in repo-local state
-- Optional per-stage mute: add stage names to \`mutedStages\`
-
-Example:
-
-\`\`\`json
-{
-  "enabled": false,
-  "mutedStages": ["plan"],
-  "lastSuggestedStage": "review",
-  "lastSuggestedAt": "2026-04-11T14:30:00Z"
-}
-\`\`\`
-
-## Checkpoint Format
-
-When creating a checkpoint at session boundaries:
-
-\`\`\`json
-{
-  "stage": "tdd",
-  "status": "in_progress",
-  "lastCompletedStep": "GREEN for task T2",
-  "remainingSteps": ["REFACTOR T2", "RED T3", "GREEN T3", "REFACTOR T3"],
-  "blockers": [],
-  "timestamp": "2026-04-11T14:30:00Z"
-}
-\`\`\`
+During post-ship \`compound_review\`, ask before scanning external session history. If the user opts in, inspect only relevant Cursor/Claude/Codex transcripts for repeated failures or process lessons, summarize matches, and then apply the same overlap/refresh/supersede rules before touching \`.cclaw/knowledge.jsonl\`.
 
 ## Context Management
 
@@ -114,14 +82,14 @@ When approaching context limits:
 | Rationalization | Reality |
 |---|---|
 | "I'll remember where I was" | Context is lost between sessions. Write it down. |
-| "This is almost done, no need for checkpoint" | "Almost done" is the most dangerous state — changes are half-applied. |
+| "This is almost done, no need for handoff" | "Almost done" is the most dangerous state — changes are half-applied. |
 | "The tests will tell me the state" | Tests tell you pass/fail, not intent or remaining work. |
 
 ## Red Flags
 
 - Ending a session with modified but uncommitted files
 - No flow state update after completing work
-- Restarting a stage from scratch instead of resuming from checkpoint
+- Restarting a stage from scratch instead of resuming from artifact context
 - Ignoring knowledge from prior sessions
 `;
 }
@@ -130,8 +98,8 @@ export function sessionHooksAgentsMdBlock() {
 
 Session boundary behavior (real hooks inject context automatically; guidelines cover manual steps):
 - **Start:** Hooks inject flow state + knowledge snapshot. Check for in-progress work, show status.
-- **Stop:** Hooks remind about checkpoint. Verify no pending changes, update flow state, append useful knowledge.
-- **Resume:** Re-read state, verify artifact, re-load knowledge, continue from last step.
+- **Stop:** Hooks remind about handoff. Verify no pending changes, update flow state, append useful knowledge after overlap check.
+- **Resume:** Re-read state, verify artifact, re-load knowledge, continue from last step. For compound closeout, optional session-history scans require user opt-in.
 
 Skill: \`.cclaw/skills/session/SKILL.md\`
 Policy: \`.cclaw/skills/iron-laws/SKILL.md\`

package/dist/content/skills.d.ts

@@ -1,8 +1,3 @@
 import type { FlowStage, FlowTrack } from "../types.js";
-/**
- * Long-form Batch Execution walkthrough. Rendered once into
- * \`.cclaw/references/stages/tdd-batch-walkthrough.md\` by the installer.
- */
-export declare const TDD_BATCH_WALKTHROUGH_MARKDOWN = "# TDD \u2014 Batch Execution Walkthrough\n\nDetailed RED / GREEN / REFACTOR transcript for a 3-task batch. Illustrative\nonly \u2014 do not copy the command names blindly, match them to your stack.\n\n## Batch 1 example tasks\n\n| Task ID | Description | AC | Verification |\n|---|---|---|---|\n| T-1 `[~3m]` | Add `User.emailNormalized` column | AC-1 | `npm test -- users/schema` |\n| T-2 `[~4m]` | Normalize on write in `UserRepo.save` | AC-1 | `npm test -- users/repo` |\n| T-3 `[~3m]` | Reject duplicates in `UserService.signup` | AC-2 | `npm test -- users/service` |\n\n## Execution transcript\n\n### T-1 \u2014 RED\n\n> Run: `npm test -- users/schema` \u2192 **FAIL** (missing column: `emailNormalized`). Captured the failure stack as RED evidence. No production code touched yet.\n\n### T-1 \u2014 GREEN\n\n> Added the column in the schema module. Re-ran `npm test -- users/schema` \u2192 **PASS**. Ran the full suite `npm test` \u2192 **PASS**. Captured both outputs as GREEN evidence.\n\n### T-1 \u2014 REFACTOR\n\n> Extracted the column definition into a shared `NormalizedEmail` type used by T-2/T-3. Re-ran `npm test` \u2192 **PASS**. Captured REFACTOR note: \"Extracted NormalizedEmail type to keep T-2/T-3 DRY; zero behavior change, all tests still green.\"\n\n### T-2 \u2014 RED / GREEN / REFACTOR\n\nWrite the repo test that expects normalised writes, watch it fail (RED), implement normalisation inside `UserRepo.save` only (GREEN), then refactor the normaliser out of the repo into a helper shared with T-3 (REFACTOR).\n\n### T-3 \u2014 RED / GREEN / REFACTOR\n\nWrite the service-level duplicate test that expects a rejection, watch it fail (RED), add the duplicate check in `UserService.signup` (GREEN), refactor the error message into a named constant (REFACTOR).\n\n## Batch gate check\n\nAfter T-3 REFACTOR, before declaring Batch 1 done:\n\n1. Run the full suite (`npm test`) one final time \u2192 **PASS** captured as batch-exit evidence.\n2. Verify the TDD artifact contains RED, GREEN, and REFACTOR evidence for T-1, T-2, **and** T-3. No partial batches.\n3. Only now mark Batch 1 complete. Batch 2 cannot start until this step.\n\n## When to stop mid-batch (do NOT push through)\n\n- A RED test fails for a reason you did not predict (e.g. an unrelated flaky test) \u2192 **pause**, diagnose, log an operational-self-improvement entry, and decide with the user before proceeding.\n- A GREEN step would require touching code outside the task's acceptance criterion \u2192 **pause**, the task is scoped wrong; adjust the plan or open a follow-up task.\n- The same RED failure reappears after a GREEN change \u2192 **escalate** per the 3-attempts rule; do not keep patching.\n";
 export declare function stageSkillFolder(stage: FlowStage): string;
 export declare function stageSkillMarkdown(stage: FlowStage, track?: FlowTrack): string;

package/dist/content/skills.js

@@ -1,10 +1,7 @@
 import { RUNTIME_ROOT, STAGE_TO_SKILL_FOLDER } from "../constants.js";
-import { STAGE_EXAMPLES_REFERENCE_DIR, stageExamples } from "./examples.js";
-import { STAGE_COMMON_GUIDANCE_REL_PATH } from "./stage-common-guidance.js";
-import { stageAutoSubagentDispatch, stageSchema } from "./stage-schema.js";
+import { stageExamples } from "./examples.js";
+import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
 const VERIFICATION_STAGES = ["tdd", "review", "ship"];
-const DECISION_PROTOCOL_PATH = `${RUNTIME_ROOT}/references/protocols/decision.md`;
-const COMPLETION_PROTOCOL_PATH = `${RUNTIME_ROOT}/references/protocols/completion.md`;
 function whenNotToUseBlock(items) {
     if (items.length === 0) {
         return "";
@@ -14,10 +11,16 @@ ${items.map((item) => `- ${item}`).join("\n")}
 
 `;
 }
-function contextLoadingBlock(trace) {
+function contextLoadingBlock(trace, executionModel) {
     const readLines = trace.readsFrom.length > 0
         ? trace.readsFrom.map((value) => `- \`${value}\``).join("\n")
         : "- (first stage — no upstream artifacts)";
+    const inputs = executionModel.inputs.length > 0
+        ? executionModel.inputs.map((item) => `- ${item}`).join("\n")
+        : "- (first stage — no required inputs)";
+    const requiredContext = executionModel.requiredContext.length > 0
+        ? executionModel.requiredContext.map((item) => `- ${item}`).join("\n")
+        : "- None beyond this skill";
     return `## Context Loading
 
 Before execution:
@@ -25,7 +28,16 @@ Before execution:
 2. Load active artifacts from \`.cclaw/artifacts/\`.
 3. Load upstream artifacts required by this stage:
 ${readLines}
-4. Use the injected knowledge digest from session-start; only fall back to full
+4. Extract upstream decisions, constraints, and open questions into the current
+   artifact's \`Upstream Handoff\` section when that section exists.
+5. 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."
+6. If you change an upstream decision, record an explicit drift reason in the
+   current artifact before continuing.
+7. Confirm stage inputs:
+${inputs}
+8. Confirm required context:
+${requiredContext}
+9. Use the injected knowledge digest from session-start; only fall back to full
    \`.cclaw/knowledge.jsonl\` when the digest is insufficient.
 `;
 }
@@ -82,6 +94,20 @@ function reviewSectionsBlock(sectionsInput) {
 ${sections}
 `;
 }
+function stackAwareReviewRoutingBlock(stage) {
+    if (stage !== "review")
+        return "";
+    const routes = reviewStackAwareRoutes()
+        .map((route) => `- ${route.stack}: ${route.signals.map((signal) => `\`${signal}\``).join(", ")} -> ${route.agent} lens for ${route.focus}.`)
+        .join("\n");
+    return `## Stack-Aware Review Routing
+${reviewStackAwareRoutingSummary()}
+
+Default general review still runs. Add only the matching stack lens when repo signals or changed files justify it.
+
+${routes}
+`;
+}
 function reviewLoopBlock(reviewLoop) {
     if (!reviewLoop)
         return "";
@@ -99,14 +125,16 @@ function verificationBlock(stage) {
         return "";
     return `## Verification Before Completion
 
-Provide fresh, stage-local verification evidence from this turn:
+This is the gate function for completion claims. No "done", "all good", or
+"tests pass" unless fresh evidence from this turn proves it.
 
-1. Run verification commands (tests/build/lint/type-check) for the changed scope.
-2. Confirm output, do not infer success from prior runs.
-3. If this is a bug fix, capture RED -> GREEN evidence for the regression path.
+- Run verification commands (tests/build/lint/type-check) for the changed scope.
+- Confirm output directly; do not infer success from prior runs or green memories.
+- If this is a bug fix, capture RED -> GREEN evidence for the regression path.
+- If a command fails, report the failure as diagnostic evidence and stop before completion.
+- If you only inspected files or reasoned about the change, say so; that is not verification.
 
-Reference utility skill:
-\`.cclaw/skills/verification-before-completion/SKILL.md\`
+Keep this verification evidence in the artifact before completion.
 `;
 }
 function batchExecutionModeBlock(stage, track) {
@@ -121,7 +149,7 @@ Apply concise turn announces: one announce per batch boundary (or when risk/plan
 changes materially), then execute tasks without repetitive boilerplate.
 
 Detailed walkthrough:
-\`.cclaw/${STAGE_EXAMPLES_REFERENCE_DIR}/tdd-batch-walkthrough.md\`
+Use the current plan artifact for batch order and keep RED -> GREEN -> REFACTOR evidence in the TDD artifact.
 `;
 }
 function crossStageTraceBlock(trace) {
@@ -170,46 +198,6 @@ function mergedAntiPatterns(philosophy, execution) {
     }
     return merged.map((item) => `- ${item}`).join("\n");
 }
-function stageSpecificSeeAlso(stage) {
-    const refs = {
-        brainstorm: [
-            `- \`${RUNTIME_ROOT}/skills/learnings/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/references/stages/brainstorm-examples.md\``
-        ],
-        scope: [
-            `- \`${RUNTIME_ROOT}/skills/learnings/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/references/stages/scope-examples.md\``
-        ],
-        design: [
-            `- \`${RUNTIME_ROOT}/skills/security/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/skills/performance/SKILL.md\``
-        ],
-        spec: [
-            `- \`${RUNTIME_ROOT}/skills/docs/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/references/stages/spec-examples.md\``
-        ],
-        plan: [
-            `- \`${RUNTIME_ROOT}/skills/subagent-dev/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/skills/parallel-dispatch/SKILL.md\``
-        ],
-        tdd: [
-            `- \`${RUNTIME_ROOT}/skills/debugging/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/references/stages/tdd-batch-walkthrough.md\``
-        ],
-        review: [
-            `- \`${RUNTIME_ROOT}/skills/security/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/skills/parallel-dispatch/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/skills/verification-before-completion/SKILL.md\``
-        ],
-        ship: [
-            `- \`${RUNTIME_ROOT}/skills/ci-cd/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/skills/docs/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/skills/verification-before-completion/SKILL.md\``,
-            `- \`${RUNTIME_ROOT}/skills/finishing-a-development-branch/SKILL.md\``
-        ]
-    };
-    return refs[stage];
-}
 function completionParametersBlock(schema, track) {
     const gateList = schema.executionModel.requiredGates.map((g) => `\`${g.id}\``).join(", ");
     const mandatory = schema.reviewLens.mandatoryDelegations.length > 0
@@ -230,7 +218,7 @@ function completionParametersBlock(schema, track) {
 - 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.
 - Use the completion helper instead of raw \`flow-state.json\` edits (legacy direct edits trigger workflow-guard warnings or strict-mode blocks).
-- Completion protocol reference: \`${COMPLETION_PROTOCOL_PATH}\`
+- Completion protocol: verify required gates, update the artifact, then use the completion helper.
 `;
 }
 function quickStartBlock(stage, track) {
@@ -244,59 +232,6 @@ function quickStartBlock(stage, track) {
 4. Satisfy gates (${gatePreview}${schema.executionModel.requiredGates.length > 3 ? ` +${schema.executionModel.requiredGates.length - 3}` : ""}).
 `;
 }
-/**
- * Long-form Batch Execution walkthrough. Rendered once into
- * \`.cclaw/references/stages/tdd-batch-walkthrough.md\` by the installer.
- */
-export const TDD_BATCH_WALKTHROUGH_MARKDOWN = `# TDD — Batch Execution Walkthrough
-
-Detailed RED / GREEN / REFACTOR transcript for a 3-task batch. Illustrative
-only — do not copy the command names blindly, match them to your stack.
-
-## Batch 1 example tasks
-
-| Task ID | Description | AC | Verification |
-|---|---|---|---|
-| T-1 \`[~3m]\` | Add \`User.emailNormalized\` column | AC-1 | \`npm test -- users/schema\` |
-| T-2 \`[~4m]\` | Normalize on write in \`UserRepo.save\` | AC-1 | \`npm test -- users/repo\` |
-| T-3 \`[~3m]\` | Reject duplicates in \`UserService.signup\` | AC-2 | \`npm test -- users/service\` |
-
-## Execution transcript
-
-### T-1 — RED
-
-> Run: \`npm test -- users/schema\` → **FAIL** (missing column: \`emailNormalized\`). Captured the failure stack as RED evidence. No production code touched yet.
-
-### T-1 — GREEN
-
-> Added the column in the schema module. Re-ran \`npm test -- users/schema\` → **PASS**. Ran the full suite \`npm test\` → **PASS**. Captured both outputs as GREEN evidence.
-
-### T-1 — REFACTOR
-
-> Extracted the column definition into a shared \`NormalizedEmail\` type used by T-2/T-3. Re-ran \`npm test\` → **PASS**. Captured REFACTOR note: "Extracted NormalizedEmail type to keep T-2/T-3 DRY; zero behavior change, all tests still green."
-
-### T-2 — RED / GREEN / REFACTOR
-
-Write the repo test that expects normalised writes, watch it fail (RED), implement normalisation inside \`UserRepo.save\` only (GREEN), then refactor the normaliser out of the repo into a helper shared with T-3 (REFACTOR).
-
-### T-3 — RED / GREEN / REFACTOR
-
-Write the service-level duplicate test that expects a rejection, watch it fail (RED), add the duplicate check in \`UserService.signup\` (GREEN), refactor the error message into a named constant (REFACTOR).
-
-## Batch gate check
-
-After T-3 REFACTOR, before declaring Batch 1 done:
-
-1. Run the full suite (\`npm test\`) one final time → **PASS** captured as batch-exit evidence.
-2. Verify the TDD artifact contains RED, GREEN, and REFACTOR evidence for T-1, T-2, **and** T-3. No partial batches.
-3. Only now mark Batch 1 complete. Batch 2 cannot start until this step.
-
-## When to stop mid-batch (do NOT push through)
-
-- A RED test fails for a reason you did not predict (e.g. an unrelated flaky test) → **pause**, diagnose, log an operational-self-improvement entry, and decide with the user before proceeding.
-- A GREEN step would require touching code outside the task's acceptance criterion → **pause**, the task is scoped wrong; adjust the plan or open a follow-up task.
-- The same RED failure reappears after a GREEN change → **escalate** per the 3-attempts rule; do not keep patching.
-`;
 export function stageSkillFolder(stage) {
     return STAGE_TO_SKILL_FOLDER[stage];
 }
@@ -383,6 +318,7 @@ function dedupeGuidance(items, blockedBy) {
 }
 export function stageSkillMarkdown(stage, track = "standard") {
     const schema = stageSchema(stage, track);
+    const trackContext = stageTrackRenderContext(track);
     const philosophy = schema.philosophy;
     const executionModel = schema.executionModel;
     const artifactRules = schema.artifactRules;
@@ -400,7 +336,6 @@ export function stageSkillMarkdown(stage, track = "standard") {
     const interactionFocus = dedupeGuidance(executionModel.interactionProtocol, [...executionModel.checklist, ...executionModel.process]).slice(0, 5);
     const processFlowMermaid = renderProcessFlowMermaid(executionModel);
     const platformNotesBlock = renderPlatformNotesBlock(executionModel.platformNotes);
-    const stageRefs = stageSpecificSeeAlso(stage);
     const reviewLoopSection = reviewLoopBlock(reviewLens.reviewLoop);
     const mandatoryDelegationSummary = mandatoryDelegations.length > 0
         ? mandatoryDelegations.map((name) => `\`${name}\``).join(", ")
@@ -428,6 +363,7 @@ ${philosophy.purpose}
 ## Complexity Tier
 - Active tier: \`${schema.complexityTier}\`
 - Mandatory delegations at this tier: ${mandatoryDelegationSummary}
+- Track render context: \`${trackContext.track}\` (${trackContext.usesPlanTerminology ? "plan-first wording" : "acceptance-first wording"})
 
 ## When to Use
 ${philosophy.whenToUse.map((item) => `- ${item}`).join("\n")}
@@ -445,14 +381,9 @@ This is the stage **state machine** — the canonical ordered flow. For every de
 
 ${processFlowMermaid.length > 0 ? processFlowMermaid : "```mermaid\nflowchart TD\n  S1[\"Execute Checklist\"] --> S2[\"Satisfy required gates\"] --> S3[\"Verify before closeout\"]\n```"}
 
-## Inputs
-${executionModel.inputs.length > 0 ? executionModel.inputs.map((item) => `- ${item}`).join("\n") : "- (first stage — no required inputs)"}
-
-## Required Context
-${executionModel.requiredContext.length > 0 ? executionModel.requiredContext.map((item) => `- ${item}`).join("\n") : "- None beyond this skill"}
-
-${platformNotesBlock}${contextLoadingBlock(artifactRules.crossStageTrace)}
+${platformNotesBlock}${contextLoadingBlock(artifactRules.crossStageTrace, executionModel)}
 ${autoSubagentDispatchBlock(stage, track)}
+${stackAwareReviewRoutingBlock(stage)}
 ${researchPlaybooksBlock(executionModel.researchPlaybooks ?? [])}
 
 ## Checklist
@@ -469,7 +400,7 @@ These are **rules for HOW you interact with the user** during this stage — ton
 
 ${interactionFocus.length > 0 ? interactionFocus.map((item, i) => `${i + 1}. ${item}`).join("\n") : "- Keep communication concise and decision-focused; rely on the Checklist for execution order."}
 
-Decision protocol reference: \`${DECISION_PROTOCOL_PATH}\`
+Decision protocol: ask only decision-changing questions, record the chosen option, rationale, risk, and rollback when the stage makes a non-trivial call.
 
 ${batchExecutionModeBlock(stage, track)}
 ## Required Gates
@@ -480,7 +411,7 @@ ${evidenceList}
 
 ${verificationBlock(stage)}
 
-## Verification
+## Exit Criteria
 ${executionModel.exitCriteria.map((item) => `- [ ] ${item}`).join("\n")}
 
 ${completionParametersBlock(schema, track)}
@@ -497,15 +428,9 @@ ${reviewLens.outputs.map((item) => `- ${item}`).join("\n")}
 ${reviewSectionsBlock(reviewLens.reviewSections)}
 
 ## Shared Stage Guidance
-See:
-- \`${STAGE_COMMON_GUIDANCE_REL_PATH}\`
-- \`${DECISION_PROTOCOL_PATH}\`
-- \`${COMPLETION_PROTOCOL_PATH}\`
-
-## See Also
-- \`${RUNTIME_ROOT}/skills/using-cclaw/SKILL.md\`
-- \`${RUNTIME_ROOT}/skills/session/SKILL.md\`
-${stageRefs.join("\n")}
-- \`${RUNTIME_ROOT}/commands/${stage}.md\`
+- Follow the handoff menu: advance, revise, pause, rewind, or archive only when the user explicitly chooses it.
+- Carry upstream decisions forward explicitly; record drift instead of silently changing direction.
+- Before closeout, fill \`## Learnings\` with \`- None this stage.\` or 1-3 strict JSON bullets.
+- Keep decisions explicit: context, options, chosen option, rationale, risk, and rollback.
 `;
 }

package/dist/content/stage-common-guidance.d.ts

@@ -1,2 +1 @@
-export declare const STAGE_COMMON_GUIDANCE_REL_PATH = ".cclaw/references/stages/common-guidance.md";
 export declare function stageCommonGuidanceMarkdown(): string;

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

@@ -1,5 +1,3 @@
-import { RUNTIME_ROOT } from "../constants.js";
-export const STAGE_COMMON_GUIDANCE_REL_PATH = `${RUNTIME_ROOT}/references/stages/common-guidance.md`;
 export function stageCommonGuidanceMarkdown() {
     return `# Common Stage Guidance
 
@@ -8,25 +6,28 @@ per-stage skills can stay focused on stage-specific work.
 
 ## Shared completion protocol
 
-- Stage-specific skills expose **Completion Parameters** only.
-- Generic execution steps live in \`.cclaw/references/protocols/completion.md\`.
-- Do not restate the protocol in each stage file.
+- Stage-specific skills expose **Completion Parameters** plus the gates that
+  matter for that stage.
+- Generic execution stays inline: verify required gates, update the artifact,
+  harvest learnings, then use \`/cc-next\` for progression.
+- Do not create separate protocol files.
 
 ## Shared decision protocol
 
-- Decision wording, ask-tool format, retry budget, and escalation rules live in
-  \`.cclaw/references/protocols/decision.md\`.
-- Stage files should reference that path, not duplicate the full text.
+- Ask only decision-changing questions.
+- Prefer one focused question over broad questionnaires.
+- When choices are equivalent, recommend one path and state the trade-off.
+- If a blocker remains after a short retry, stop and ask the user.
 
 ## Shared handoff menu
 
 Use this same closeout menu for every stage:
 
-- **A) Advance** — run \`/cc-next\` and continue.
+- **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 \`/cc-ops rewind <target-stage>\`.
-- **E) Abandon** — archive with \`/cc-ops archive --skip-retro --retro-reason="<reason>"\` when user explicitly wants to end the run.
+- **D) Rewind** — run \`cclaw internal rewind <target-stage> "<reason>"\`.
+- **E) Abandon** — only when the user explicitly wants to end a non-ship active run early, archive with \`cclaw archive --skip-retro --retro-reason="<reason>"\`. Once in post-ship closeout, continue \`/cc-next\` through retro/compound/archive instead.
 
 Recommendation defaults:
 
@@ -80,8 +81,8 @@ insight (for example, purely mechanical edits with no new decisions).
 ## Progressive disclosure baseline
 
 - Start with the current stage skill.
-- Load deeper references only when required by a blocker or gate.
-- Prefer \`.cclaw/references/stages/<stage>-examples.md\` and protocol files over
-  copying large instruction blocks into stage skills.
+- Load deeper skills or docs only when required by a blocker or gate.
+- Keep examples as short shape cues inside the current skill instead of
+  materializing separate reference files.
 `;
 }

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

@@ -3,10 +3,12 @@ import type { StageComplexityTier, StageAutoSubagentDispatch, StageSchema } from
 export type { ArtifactValidation, CrossStageTrace, ReviewSection, StageComplexityTier, StageExecutionModel, StagePhilosophy, StageArtifactRules, StageReviewLoop, StageReviewLens, StageAutoSubagentDispatch, StageGate, StageSchemaLegacyInput, StageSchema, StageSchemaInput, StageSchemaV2Input } from "./stages/schema-types.js";
 export declare const SKILL_ENVELOPE_KINDS: readonly ["stage-output", "gate-result", "delegation-record"];
 export type SkillEnvelopeKind = (typeof SKILL_ENVELOPE_KINDS)[number];
+export declare const NON_FLOW_ENVELOPE_STAGE: "non-flow";
+export type SkillEnvelopeStage = FlowStage | typeof NON_FLOW_ENVELOPE_STAGE;
 export interface SkillEnvelope {
     version: "1";
     kind: SkillEnvelopeKind;
-    stage: FlowStage;
+    stage: SkillEnvelopeStage;
     payload: unknown;
     emittedAt: string;
     agent?: string;
@@ -15,6 +17,28 @@ export interface SkillEnvelopeValidation {
     ok: boolean;
     errors: string[];
 }
+export interface StageStackAwareReviewRoute {
+    stack: string;
+    agent: "reviewer";
+    signals: string[];
+    focus: string;
+}
+export interface StageDelegationSummary {
+    stage: FlowStage;
+    mandatoryAgents: string[];
+    proactiveAgents: string[];
+    primaryAgents: string[];
+    stackAwareRoutes: StageStackAwareReviewRoute[];
+}
+export declare function reviewStackAwareRoutes(): StageStackAwareReviewRoute[];
+export declare function reviewStackAwareRoutingSummary(): string;
+/**
+ * Canonical delegation summary derived from STAGE_AUTO_SUBAGENT_DISPATCH.
+ *
+ * Keep all generated routing surfaces (skills, AGENTS.md) on this helper so
+ * stage->agent defaults are maintained in one place.
+ */
+export declare function stageDelegationSummary(complexityTier?: StageComplexityTier): StageDelegationSummary[];
 export declare function validateSkillEnvelope(value: unknown): SkillEnvelopeValidation;
 export declare function parseSkillEnvelope(raw: string): SkillEnvelope | null;
 /** Transition guard: agents with `mode: "mandatory"` in auto-subagent dispatch for this stage. */
@@ -26,4 +50,5 @@ export declare function stageRecommendedGateIds(stage: FlowStage, track?: FlowTr
 export declare function nextCclawCommand(stage: FlowStage): string;
 export declare function buildTransitionRules(): TransitionRule[];
 export declare function stagePolicyNeedles(stage: FlowStage, track?: FlowTrack): string[];
+export declare function stageTrackRenderContext(track?: FlowTrack): import("./track-render-context.js").TrackRenderContext;
 export declare function stageAutoSubagentDispatch(stage: FlowStage): StageAutoSubagentDispatch[];