cclaw-cli 0.49.0 → 0.51.0

package/dist/content/stage-schema.js

@@ -3,6 +3,7 @@ import { STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { BRAINSTORM, SCOPE, DESIGN, SPEC, PLAN, TDD, REVIEW, SHIP } from "./stages/index.js";
 import { stagePolicyNeedlesFromMetadata } from "./stages/_lint-metadata/index.js";
 import { tddStageForTrack } from "./stages/tdd.js";
+import { trackRenderContext } from "./track-render-context.js";
 // ---------------------------------------------------------------------------
 // NOTE: The former QUESTION_FORMAT_SPEC / ERROR_BUDGET_SPEC exports were
 // hoisted into `src/content/meta-skill.ts` (Shared Decision + Tool-Use
@@ -14,6 +15,7 @@ export const SKILL_ENVELOPE_KINDS = [
     "gate-result",
     "delegation-record"
 ];
+export const NON_FLOW_ENVELOPE_STAGE = "non-flow";
 const FLOW_STAGE_SET = new Set(FLOW_STAGES);
 const SKILL_ENVELOPE_KIND_SET = new Set(SKILL_ENVELOPE_KINDS);
 const COMPLEXITY_TIER_ORDER = {
@@ -21,6 +23,93 @@ const COMPLEXITY_TIER_ORDER = {
     standard: 1,
     deep: 2
 };
+const REVIEW_STACK_AWARE_ROUTES = [
+    {
+        stack: "TypeScript/JavaScript",
+        agent: "reviewer",
+        signals: ["package.json", "tsconfig.json"],
+        focus: "type safety, package scripts, build/test config, dependency boundaries"
+    },
+    {
+        stack: "Python",
+        agent: "reviewer",
+        signals: ["pyproject.toml", "requirements.txt"],
+        focus: "packaging, virtualenv assumptions, typing, pytest or unittest evidence"
+    },
+    {
+        stack: "Ruby/Rails",
+        agent: "reviewer",
+        signals: ["Gemfile", "config/"],
+        focus: "Rails conventions, migrations, routes/controllers, RSpec or Minitest evidence"
+    },
+    {
+        stack: "Go",
+        agent: "reviewer",
+        signals: ["go.mod"],
+        focus: "interfaces, concurrency, error handling, go test coverage"
+    },
+    {
+        stack: "Rust",
+        agent: "reviewer",
+        signals: ["Cargo.toml"],
+        focus: "ownership, error/result handling, feature flags, cargo test coverage"
+    }
+];
+function stackAwareRoutesForStage(stage) {
+    return stage === "review" ? reviewStackAwareRoutes() : [];
+}
+export function reviewStackAwareRoutes() {
+    return REVIEW_STACK_AWARE_ROUTES.map((route) => ({
+        ...route,
+        signals: [...route.signals]
+    }));
+}
+export function reviewStackAwareRoutingSummary() {
+    const routeList = REVIEW_STACK_AWARE_ROUTES
+        .map((route) => `${route.stack} via ${route.signals.join("/")}`)
+        .join("; ");
+    return `Stack-aware review routing: keep the default reviewer and security-reviewer passes, then proactively route matching reviewer lenses when repo signals or review context match (${routeList}). Do not run every stack lens unconditionally.`;
+}
+function dedupeAgentsInOrder(agents) {
+    const out = [];
+    const seen = new Set();
+    for (const agent of agents) {
+        if (seen.has(agent))
+            continue;
+        seen.add(agent);
+        out.push(agent);
+    }
+    return out;
+}
+/**
+ * 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 function stageDelegationSummary(complexityTier = "standard") {
+    const currentTierRank = COMPLEXITY_TIER_ORDER[complexityTier];
+    return FLOW_STAGES.map((stage) => {
+        const eligibleRows = STAGE_AUTO_SUBAGENT_DISPATCH[stage].filter((row) => {
+            const requiredAt = row.requiredAtTier ?? "standard";
+            return currentTierRank >= COMPLEXITY_TIER_ORDER[requiredAt];
+        });
+        const mandatoryAgents = dedupeAgentsInOrder(eligibleRows
+            .filter((row) => row.mode === "mandatory")
+            .map((row) => row.agent));
+        const proactiveAgents = dedupeAgentsInOrder(eligibleRows
+            .filter((row) => row.mode === "proactive")
+            .map((row) => row.agent));
+        const primaryAgents = dedupeAgentsInOrder([...mandatoryAgents, ...proactiveAgents]);
+        return {
+            stage,
+            mandatoryAgents,
+            proactiveAgents,
+            primaryAgents,
+            stackAwareRoutes: stackAwareRoutesForStage(stage)
+        };
+    });
+}
 function asRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return null;
@@ -39,8 +128,9 @@ export function validateSkillEnvelope(value) {
     if (typeof record.kind !== "string" || !SKILL_ENVELOPE_KIND_SET.has(record.kind)) {
         errors.push(`envelope.kind must be one of: ${SKILL_ENVELOPE_KINDS.join(", ")}.`);
     }
-    if (typeof record.stage !== "string" || !FLOW_STAGE_SET.has(record.stage)) {
-        errors.push(`envelope.stage must be one of: ${FLOW_STAGES.join(", ")}.`);
+    if (typeof record.stage !== "string" ||
+        (record.stage !== NON_FLOW_ENVELOPE_STAGE && !FLOW_STAGE_SET.has(record.stage))) {
+        errors.push(`envelope.stage must be one of: ${FLOW_STAGES.join(", ")} or ${NON_FLOW_ENVELOPE_STAGE}.`);
     }
     if (!Object.prototype.hasOwnProperty.call(record, "payload")) {
         errors.push("envelope.payload is required.");
@@ -114,15 +204,19 @@ const REQUIRED_GATE_IDS = {
     spec: [
         "spec_acceptance_measurable",
         "spec_testability_confirmed",
+        "spec_assumptions_surfaced",
         "spec_user_approved"
     ],
     plan: [
         "plan_tasks_sliced_2_5_min",
         "plan_dependency_batches_defined",
         "plan_acceptance_mapped",
+        "plan_execution_posture_recorded",
         "plan_wait_for_confirm"
     ],
     tdd: (track) => [
+        "tdd_test_discovery_complete",
+        "tdd_impact_check_complete",
         "tdd_red_test_written",
         "tdd_green_full_suite",
         "tdd_refactor_completed",
@@ -164,10 +258,10 @@ const REQUIRED_ARTIFACT_SECTIONS = {
         "Deployment & Rollout",
         "Completion Dashboard"
     ],
-    spec: ["Acceptance Criteria", "Edge Cases", "Testability Map", "Approval"],
-    plan: ["Task List", "Dependency Batches", "Acceptance Mapping", "WAIT_FOR_CONFIRM"],
-    tdd: ["RED Evidence", "GREEN Evidence", "REFACTOR Notes", "Traceability", "Verification Ladder"],
-    review: ["Layer 1 Verdict", "Review Army Contract", "Severity Summary", "Final Verdict"],
+    spec: ["Acceptance Criteria", "Edge Cases", "Assumptions Before Finalization", "Testability Map", "Approval"],
+    plan: ["Task List", "Dependency Batches", "Acceptance Mapping", "Execution Posture", "WAIT_FOR_CONFIRM"],
+    tdd: ["Test Discovery", "System-Wide Impact Check", "RED Evidence", "GREEN Evidence", "REFACTOR Notes", "Traceability", "Verification Ladder"],
+    review: ["Layer 1 Verdict", "Review Findings Contract", "Severity Summary", "Final Verdict"],
     ship: ["Preflight Results", "Release Notes", "Rollback Plan", "Finalization"]
 };
 function resolveRequiredGateIds(stage, track) {
@@ -328,28 +422,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "test-author",
             mode: "mandatory",
             requiredAtTier: "lightweight",
-            when: "Always during TDD cycle (RED phase).",
-            purpose: "Produce failing RED tests only; no production writes.",
+            when: "Always during the TDD cycle.",
+            purpose: "Own phase-specific RED/GREEN/REFACTOR evidence for each slice: failing tests before production writes, minimal GREEN implementation, then behavior-preserving refactor notes.",
             requiresUserGate: false,
-            skill: "tdd-red-phase"
-        },
-        {
-            agent: "test-author",
-            mode: "mandatory",
-            requiredAtTier: "lightweight",
-            when: "Always during TDD cycle (GREEN phase).",
-            purpose: "Implement minimum production changes to satisfy RED and prove full-suite GREEN.",
-            requiresUserGate: false,
-            skill: "tdd-green-phase"
-        },
-        {
-            agent: "test-author",
-            mode: "mandatory",
-            requiredAtTier: "lightweight",
-            when: "Always during TDD cycle (REFACTOR phase).",
-            purpose: "Refactor only after GREEN proof, preserving behavior and test pass state.",
-            requiresUserGate: false,
-            skill: "tdd-refactor-phase"
+            skill: "tdd-cycle-evidence"
         },
         {
             agent: "doc-updater",
@@ -365,7 +441,7 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             mode: "mandatory",
             requiredAtTier: "lightweight",
             when: "Always in review stage.",
-            purpose: "Layer 1 spec compliance pass plus coordination of parallel Layer 2 fan-out (correctness, performance, architecture, external-safety) with source-tagged findings.",
+            purpose: "Layer 1 spec compliance plus integrated Layer 2 review across correctness, performance, architecture, and external-safety tags with source-tagged findings.",
             requiresUserGate: false,
             skill: "review-spec-pass"
         },
@@ -380,10 +456,9 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         },
         {
             agent: "reviewer",
-            mode: "mandatory",
-            requiredAtTier: "lightweight",
-            when: "Mandatory when the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
-            purpose: "Adversarial second-opinion review on large or trust-sensitive diffs. The second reviewer treats the implementation as hostile and tries to break it (hostile-user, future-maintainer, competitor lenses) instead of sympathetically explaining it.",
+            mode: "proactive",
+            when: "When trust boundaries changed, Critical/Important ambiguity remains, or the diff is both large and high-risk.",
+            purpose: "Adversarial second-opinion review for genuinely high-blast-radius changes. Treat the implementation as hostile and try to break it before ship.",
             requiresUserGate: false,
             skill: "adversarial-review"
         },
@@ -394,6 +469,14 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             purpose: "Run the receiving-code-review workflow so every incoming feedback item gets an explicit disposition with evidence, and the queue is mirrored into review artifacts.",
             requiresUserGate: false,
             skill: "receiving-code-review"
+        },
+        {
+            agent: "reviewer",
+            mode: "proactive",
+            when: "When repo signals or review context indicate TypeScript/JavaScript, Python, Ruby/Rails, Go, or Rust coverage is relevant.",
+            purpose: "Route a matching stack-aware reviewer lens while keeping the default general review pass intact; do not run every stack lens unconditionally.",
+            requiresUserGate: false,
+            skill: "stack-aware-review"
         }
     ],
     ship: [
@@ -416,14 +499,9 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
 };
 /** Transition guard: agents with `mode: "mandatory"` in auto-subagent dispatch for this stage. */
 export function mandatoryDelegationsForStage(stage, complexityTier = "standard") {
-    const currentTierRank = COMPLEXITY_TIER_ORDER[complexityTier];
-    return [...new Set(STAGE_AUTO_SUBAGENT_DISPATCH[stage]
-            .filter((d) => d.mode === "mandatory")
-            .filter((d) => {
-            const requiredAt = d.requiredAtTier ?? "standard";
-            return currentTierRank >= COMPLEXITY_TIER_ORDER[requiredAt];
-        })
-            .map((d) => d.agent))];
+    const summary = stageDelegationSummary(complexityTier)
+        .find((row) => row.stage === stage);
+    return summary ? summary.mandatoryAgents : [];
 }
 export function stageSchema(stage, track = "standard") {
     const rawInput = stage === "tdd" ? tddStageForTrack(track) : STAGE_SCHEMA_MAP[stage];
@@ -538,6 +616,9 @@ export function buildTransitionRules() {
 export function stagePolicyNeedles(stage, track = "standard") {
     return stagePolicyNeedlesFromMetadata(stage, track);
 }
+export function stageTrackRenderContext(track = "standard") {
+    return trackRenderContext(track);
+}
 export function stageAutoSubagentDispatch(stage) {
     return STAGE_AUTO_SUBAGENT_DISPATCH[stage];
 }

package/dist/content/stages/_lint-metadata/index.js

@@ -1,4 +1,5 @@
 import { SHIP_FINALIZATION_MODES } from "../../../constants.js";
+import { renderTrackTerminology, trackRenderContext } from "../../track-render-context.js";
 const STAGE_POLICY_NEEDLES = {
     brainstorm: [
         "Explore project context",
@@ -25,13 +26,14 @@ const STAGE_POLICY_NEEDLES = {
         "Performance Budget",
         "One issue at a time"
     ],
-    spec: ["Acceptance Criteria", "Constraints", "Testability", "approved spec", "Edge Cases"],
+    spec: ["Acceptance Criteria", "Constraints", "Assumptions Before Finalization", "Testability", "approved spec", "Edge Cases"],
     plan: [
         "WAIT_FOR_CONFIRM",
         "Task Graph",
         "Dependency Batches",
         "Acceptance Mapping",
         "verification steps",
+        "Execution Posture",
         "Locked Decision Coverage"
     ],
     tdd: [
@@ -39,6 +41,8 @@ const STAGE_POLICY_NEEDLES = {
         "GREEN",
         "REFACTOR",
         "failing test",
+        "Test Discovery",
+        "System-Wide Impact Check",
         "full test suite",
         "acceptance criteria",
         "traceable to plan slice"
@@ -47,7 +51,7 @@ const STAGE_POLICY_NEEDLES = {
         "Layer 1",
         "Layer 2",
         "Critical",
-        "Review Army",
+        "Review Findings",
         "Ready to Ship",
         "ROUTE_BACK_TO_TDD",
         "One issue at a time"
@@ -59,21 +63,11 @@ const STAGE_POLICY_NEEDLES = {
         ...SHIP_FINALIZATION_MODES
     ]
 };
-function quickTrackText(value) {
-    return value
-        .replace(/\btask from the plan\b/giu, "acceptance criterion from the spec")
-        .replace(/\bplan task ID\b/giu, "acceptance criterion ID")
-        .replace(/\bplan task\b/giu, "acceptance criterion")
-        .replace(/\bplan row\b/giu, "acceptance row")
-        .replace(/\bplan slice\b/giu, "acceptance slice")
-        .replace(/\bplan artifact\b/giu, "spec artifact")
-        .replace(/\btraceable to plan slice\b/giu, "traceable to acceptance criterion")
-        .replace(/05-plan\.md/gu, "04-spec.md");
-}
 export function stagePolicyNeedlesFromMetadata(stage, track = "standard") {
     const needles = STAGE_POLICY_NEEDLES[stage];
-    if (stage === "tdd" && track === "quick") {
-        return needles.map(quickTrackText);
+    const renderContext = trackRenderContext(track);
+    if (stage === "tdd" && !renderContext.usesPlanTerminology) {
+        return needles.map((needle) => renderTrackTerminology(needle, renderContext));
     }
     return [...needles];
 }

package/dist/content/stages/brainstorm.js

@@ -36,52 +36,31 @@ export const BRAINSTORM = {
     },
     executionModel: {
         checklist: [
-            "**Explore project context** — check files, docs, recent commits to understand what already exists.",
-            "**Assess depth tier first** — classify the request as Lightweight / Standard / Deep. Lightweight = narrow/localized ask; Standard = cross-module but bounded; Deep = platform or multi-surface product change.",
-            "**Assess scope** — if the request covers multiple independent subsystems, flag it and help decompose before deep-diving. Each sub-project gets its own brainstorm cycle.",
-            "**Short-circuit gate** — if requirements are already concrete and unambiguous, write a minimal brainstorm stub (problem + approved intent + constraints) and hand off to scope.",
-            "**Ask clarifying questions** — one at a time, understand purpose, constraints, and success criteria. Prefer multiple choice when possible. Each question should change what we build, not just gather trivia.",
-            "**Propose 2-3 architecturally distinct approaches** — with real trade-offs and no recommendation yet. At least one option must be a higher-upside challenger that raises ambition vs the user's initial ask.",
-            "**Collect user reaction** — ask which approach feels closest and what concerns remain before stating your recommendation.",
-            "**Recommend only after reaction** — present final recommendation with rationale that explicitly references user feedback.",
-            "**Plant-seed shelf (optional)** — when a non-selected approach is still promising, capture it as `.cclaw/seeds/SEED-<YYYY-MM-DD>-<slug>.md` with `trigger_when`, hypothesis, and suggested action instead of losing it.",
-            "**Present design by sections** — scale each section to its complexity. Ask after each section whether it looks right so far. Cover: architecture, key components, data flow.",
-            "**Optional visual companion** — when architecture/data flow complexity is medium+ offer a compact diagram (ASCII or Mermaid) before artifact write-up.",
-            "**Write artifact** to `.cclaw/artifacts/01-brainstorm-<slug>.md`.",
-            "**Document-quality pass** — run a brief adversarial review of the artifact (gaps, contradictions, missing trade-offs), then patch before user review.",
-            "**Self-review** — scan for placeholders/TODOs, check internal consistency, verify scope is focused, resolve any ambiguity.",
-            "**User reviews artifact** — ask the user to review the written artifact and explicitly approve or request changes.",
-            "**Handoff** — only then complete stage and point to `/cc-next`."
+            "**Explore project context** — inspect existing files/docs/recent activity before asking what to build.",
+            "**Classify depth and scope** — pick Lightweight / Standard / Deep; decompose independent subsystems before deeper work.",
+            "**Short-circuit concrete asks** — for unambiguous requests, write a compact brainstorm stub (context, problem, approved intent, constraints, assumptions) and ask for one explicit approval.",
+            "**Ask only decision-changing questions** — one at a time; if answers would not change approach, state the assumption and continue.",
+            "**Compare 2-3 distinct approaches** — include real trade-offs, withhold recommendation, and include one higher-upside challenger.",
+            "**Collect reaction before recommending** — ask which option feels closest and what concern remains, then recommend based on that reaction.",
+            "**Write and tighten the artifact** — scale sections to complexity, optionally add a compact diagram, then patch contradictions, weak trade-offs, placeholders, and ambiguity.",
+            "**Request explicit approval** — state exactly what direction is being approved; do not advance without approval and artifact review.",
+            "**Handoff** — only after approval, complete the stage and point to `/cc-next`."
         ],
         interactionProtocol: [
-            "Explore what exists before asking what to build — check project files first.",
-            "If the idea is vague or could mean many different things, your FIRST question narrows to a specific kind of project. Do not ask detail questions until the project type is clear.",
-            "Ask exactly one question per turn. Prefer multiple choice. No bundled questions.",
-            "After 2-3 questions, summarize your emerging understanding before continuing so the user can correct course early.",
-            "Each question should change a concrete design decision. Litmus test: if the two most likely answers do not lead to different architectures, make the choice yourself and state it.",
-            "Present design in sections scaled to their complexity — a few sentences for simple aspects, detailed for nuanced ones. Get approval after each section.",
-            "When proposing approaches, do NOT reveal your recommendation yet. Present options first, gather reaction, then recommend.",
-            "At least one approach must be a higher-upside challenger; avoid three same-altitude variants.",
-            "State explicitly what is being approved when requesting approval.",
-            "Run a brief self-review (placeholders, contradictions, scope, ambiguity) before presenting the artifact.",
-            "**STOP.** Wait for explicit user approval after writing the artifact. Do NOT auto-advance."
+            "Start from observed project context; if the idea is vague, first narrow the project type.",
+            "Ask at most one question per turn, only when decision-changing; prefer multiple choice, and summarize after 2-3 answers.",
+            "If likely answers do not change architecture or scope boundaries, choose the default and state the assumption.",
+            "Show approaches before the recommendation; include a higher-upside challenger and gather reaction first.",
+            "State exactly what is being approved, then **STOP** until the user explicitly approves the artifact."
         ],
         process: [
-            "Explore project context: check files, docs, recent activity.",
-            "Classify depth tier (Lightweight / Standard / Deep) before diving.",
-            "Assess scope: flag if request is too broad, help decompose first.",
-            "Apply short-circuit when requirements are already concrete enough for scope.",
-            "Ask clarifying questions one at a time — focus on purpose, constraints, success criteria.",
-            "Propose 2-3 architecturally distinct approaches with trade-offs (one must be higher-upside challenger).",
-            "Collect user reaction before giving your recommendation.",
-            "Recommend after reaction and explain how feedback changed the recommendation.",
-            "Optionally plant promising non-selected approaches into `.cclaw/seeds/SEED-<YYYY-MM-DD>-<slug>.md` with trigger_when/action notes.",
-            "Present design sections incrementally, get approval after each.",
-            "Write approved direction to `.cclaw/artifacts/01-brainstorm-<slug>.md`.",
-            "Run document-quality pass to close contradictions and weak trade-off reasoning.",
-            "Self-review: placeholder scan, internal consistency, scope check, ambiguity check.",
-            "Request explicit user approval of the artifact.",
-            "Handoff to scope only after approval is explicit."
+            "Explore project context and classify depth/scope.",
+            "Short-circuit concrete asks or ask one decision-changing question at a time.",
+            "Compare 2-3 distinct approaches, including a higher-upside challenger.",
+            "Collect reaction, then recommend with rationale tied to that reaction.",
+            "Optionally park promising non-selected ideas in `.cclaw/seeds/`.",
+            "Write and self-review `.cclaw/artifacts/01-brainstorm-<slug>.md`.",
+            "Request explicit approval before handoff to scope."
         ],
         requiredGates: [
             { id: "brainstorm_approaches_compared", description: "2-3 architecturally distinct approaches were compared with real trade-offs and a recommendation." },
@@ -139,7 +118,7 @@ export const BRAINSTORM = {
             { section: "Problem", required: true, validationRule: "Must define what we're solving, success criteria, and constraints." },
             { section: "Clarifying Questions", required: false, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
             { section: "Approach Tier", required: true, validationRule: "Must classify depth as Lightweight/Standard/Deep and explain why." },
-            { section: "Short-Circuit Decision", required: false, validationRule: "Must include Status/Why/Scope handoff lines when short-circuit is discussed." },
+            { section: "Short-Circuit Decision", required: false, validationRule: "Must include Status/Why/Scope handoff lines when short-circuit is discussed; compact stubs are valid for concrete asks." },
             { section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs and include one row labeled `challenger: higher-upside`." },
             { section: "Approach Reaction", required: true, validationRule: "Must summarize user reaction before recommendation, including concerns that changed direction." },
             { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, rationale tied to user reaction/feedback, and explicit approval marker." },

package/dist/content/stages/design.js

@@ -1,4 +1,5 @@
-import { REVIEW_LOOP_CHECKLISTS } from "../review-loop.js";
+import { REVIEW_LOOP_CHECKLISTS, reviewLoopPolicySummary, reviewLoopSecondOpinionSummary } from "../review-loop.js";
+import { decisionProtocolInstruction } from "../decision-protocol.js";
 // ---------------------------------------------------------------------------
 // DESIGN — reference: gstack Eng review
 // ---------------------------------------------------------------------------
@@ -39,60 +40,38 @@ export const DESIGN = {
     },
     executionModel: {
         checklist: [
-            "Trivial-Change Escape Hatch — If scope artifact shows ≤3 files, zero new interfaces, and no cross-module data flow, skip full review sections. Produce a mini-design: one paragraph of rationale, list of changed files, one risk to watch. Proceed to spec.",
-            "Parallel Research Fleet — run `research/research-fleet.md` before architecture lock. Fleet size scales by complexity: Lightweight=1 lens (pitfalls), Standard=2 lenses (architecture+pitfalls), Deep=4 lenses. Record findings in `.cclaw/artifacts/02a-research.md` and summarize resulting decisions in `## Research Fleet Synthesis`.",
-            "Design Doc Check — read existing design docs, scope artifact, brainstorm artifact. If a design doc exists that covers this area, check for 'Supersedes:' and use the latest. Use upstream artifacts as source of truth.",
-            "Codebase Investigation — Before any design decision, read the actual code in the blast radius. List every file that will be touched, its current responsibilities, and existing patterns (error handling, naming, test style). Design must conform to discovered patterns, not impose new ones without justification.",
-            "Step 0: Scope Challenge — what existing code solves sub-problems? Minimum change set? Complexity check: 8+ files or 2+ new services = complexity smell → flag for possible scope reduction.",
-            "Search Before Building — For each technical choice (library, pattern, architecture), search for existing solutions. Label findings: Layer 1 (exact match), Layer 2 (partial match, needs adaptation), Layer 3 (inspiration only), EUREKA (unexpected perfect solution). Default to existing before custom.",
-            "Architecture Review — lock component boundaries and one realistic failure scenario per new codepath. **Mandatory diagrams by tier:** Lightweight=Architecture Diagram, Standard=+Data-Flow Shadow Paths + Error Flow Diagram, Deep=+State Machine Diagram + Rollback Flowchart + Deployment Sequence Diagram.",
-            "Security & Threat Model Review — trust boundaries, authn/authz, input validation, secrets handling, data exposure risks, abuse cases, and mitigation ownership.",
-            "Code Quality Review — code organization, DRY violations, error handling patterns, over/under-engineering assessment. Include stale-diagram audit for touched files.",
-            "Test Review — diagram every new flow, data path, error path. For each: what test type covers it? Does one exist? What is the gap? Produce test plan artifact.",
-            "Performance Review — N+1 queries, memory concerns, caching opportunities, slow code paths. What breaks at 10x load? At 100x?",
-            "Observability & Debuggability Review — logging, metrics, traces, alerts, and on-call diagnosis path for each critical failure mode.",
-            "Deployment & Rollout Review — migration sequencing, flag strategy, rollback plan, compatibility window, and post-deploy verification steps.",
-            "Parallelization Strategy — If multiple independent modules, produce dependency table: which can be built in parallel? Where are conflict risks? Flag shared-state modules.",
-            "Outside Voice + Spec Review Loop — run adversarial second-opinion review, reconcile findings, and iterate up to 3 cycles or until quality score >= 0.8. When `.cclaw/config.yaml::reviewLoop.externalSecondOpinion.enabled` is true, run an additional external-model pass and explicitly resolve score/finding disagreements.",
-            "Stale Diagram Audit (opt-in) — when `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is true, compare blast-radius file mtimes against diagram-marker freshness and flag stale diagrams before design lock.",
-            "Plant-seed shelf (optional) — when an unresolved/deferred design idea has upside, capture it as `.cclaw/seeds/SEED-<YYYY-MM-DD>-<slug>.md` with trigger_when and action so it can be recalled on future `/cc` starts.",
-            "Unresolved Decisions — List any design decisions that could not be resolved in this session. For each: what information is missing? Who can provide it? What is the default if no answer comes?",
-            "Distribution Check — If the plan creates new artifact types (packages, CLI tools, configs), document the build/publish story. How does it reach the user?",
-            "Deferred Items Cross-Reference — Collect every item explicitly deferred during design review. Each must appear in the Unresolved Decisions table or in the upstream scope artifact's deferred list. No deferred item may exist only in conversation — it must be written down."
+            "Trivial-Change Escape Hatch — for <=3 files, no new interfaces, and no cross-module data flow, produce a mini-design (rationale, changed files, one risk) and proceed to spec.",
+            "Tiered Research Fleet — run `research/research-fleet.md` before lock; record `.cclaw/artifacts/02a-research.md` and summarize concrete decisions in `## Research Fleet Synthesis`.",
+            "Design Doc Check — read upstream artifacts and current design docs; latest superseding doc wins.",
+            "Investigator pass — before design decisions, read blast-radius code and record touched files, responsibilities, reuse candidates, and existing patterns.",
+            "Scope Challenge + Search Before Building — find existing solutions, minimum change set, and complexity smells before custom architecture.",
+            "Architecture Review — lock boundaries, one realistic failure scenario per new codepath, and high-risk choices with chosen path, one shadow alternative, switch trigger, and verification evidence; include tier-required diagrams.",
+            "Review core risk areas — security/threat model, code quality, tests, performance, observability/debuggability, deployment/rollout, and parallelization when modules are independent.",
+            `Critic pass — run/reconcile adversarial second opinion on architecture, coupling, failure modes, and cheaper alternatives. ${reviewLoopPolicySummary("design")} ${reviewLoopSecondOpinionSummary("design")}`,
+            "Run optional stale-diagram audit only when configured.",
+            "Capture leftovers — seed high-upside deferred ideas, list unresolved decisions with defaults, document distribution for new artifact types, and cross-reference deferred items to scope or unresolved decisions."
         ],
         interactionProtocol: [
-            "Review architecture decisions section-by-section.",
-            "For EACH issue found in a review section, present it ONE AT A TIME. Do NOT batch multiple issues.",
-            "For each issue: use the Decision Protocol — describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, effort estimate (S/M/L/XL), risk level (Low/Med/High), and mark one as (recommended). Do NOT use a numeric Completeness rubric. If the harness's native structured-ask tool is available (`AskUserQuestion` / `AskQuestion` / `question` / `request_user_input`), send exactly ONE question per call and fall back to plain-text letters on schema/tool failure.",
-            "Only proceed to the next review section after ALL issues in the current section are resolved.",
+            "Review section-by-section: investigator first, critic second, then reconcile.",
+            "Present each issue one at a time; do not batch issues or move sections until current issues are resolved.",
+            decisionProtocolInstruction("each issue", "describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, effort estimate (S/M/L/XL), risk level (Low/Med/High), and mark one as (recommended)", "recommend the option that closes the issue with the smallest blast radius and clearest verification path"),
             "If a section has no issues, say 'No issues found' and move on.",
-            "Do not skip failure-mode mapping.",
-            "Use Failure Mode Table columns in fixed order: Method, Exception, Rescue, UserSees. Silent user impact without rescue is treated as critical.",
-            "For design baseline approval: present the full baseline. **STOP.** Do NOT proceed until user explicitly approves the design.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `node .cclaw/hooks/stage-complete.mjs design` (do not hand-edit `.cclaw/state/flow-state.json`).",
-            "Take a firm position on every recommendation. Do NOT hedge with 'it depends' or 'you could do either'. State your opinion, then justify it.",
-            "Use pushback for weak framing: 'small changes' on shared interfaces can still have large blast radius.",
-            "When the user's proposed architecture is suboptimal, say so directly. Offer the alternative with concrete trade-offs, do not bury criticism in praise.",
-            "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity.",
-            "Before final approval, run outside-voice review loop and reconcile each finding (accept/reject/defer) with rationale.",
-            "Bound review-loop retries: max 3 iterations or early stop at quality score >= 0.8."
+            "Do not skip failure-mode mapping; use Method/Exception/Rescue/UserSees and treat silent user impact without rescue as critical.",
+            "Take a firm position, push back on weak framing, and call out suboptimal architecture with concrete alternatives.",
+            "Classify ambiguity before acting: ask, enumerate-and-pick, or propose a hypothesis with validation path.",
+            "Before final approval, run the critic pass, reconcile material findings, and bound retries with the review-loop policy.",
+            "For baseline approval, present the full design and **STOP** until explicit approval.",
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be completed or explicitly waived, then close via `node .cclaw/hooks/stage-complete.mjs design`."
         ],
         process: [
-            "Read upstream artifacts (brainstorm, scope).",
-            "Run the research fleet playbook with tiered fleet size and write `.cclaw/artifacts/02a-research.md` before locking architecture choices.",
-            "Investigate codebase: read files in blast radius, catalogue current patterns and responsibilities.",
-            "Run Step 0 scope challenge: existing code leverage, minimum change set, complexity check.",
-            "Walk through each review section interactively.",
-            "Define architecture boundaries and ownership.",
-            "Describe data flow and state transitions with edge paths + interaction edge-case matrix.",
-            "Map failure modes and recovery strategy using Method/Exception/Rescue/UserSees table.",
-            "Add security, observability, and deployment reviews for Standard+ changes.",
-            "Run stale-diagram audit in touched files and reconcile drift.",
-            "Define test coverage strategy and performance budget.",
-            "Produce required outputs: NOT-in-scope section, What-already-exists section, tier-required diagrams with markers, failure mode table.",
-            "Optionally plant unresolved high-upside ideas into `.cclaw/seeds/SEED-<YYYY-MM-DD>-<slug>.md` with trigger_when/action notes.",
-            "Run outside-voice spec review loop (up to 3 iterations, quality score target >= 0.8). If configured, include external second opinion and reconcile deltas.",
-            "Produce completion dashboard: status per review section, critical/open gap counts, decision count, unresolved items.",
+            "Read upstream artifacts and current design docs.",
+            "Run tiered research fleet and write `.cclaw/artifacts/02a-research.md` before architecture lock.",
+            "Run investigator pass plus scope challenge/search-before-building.",
+            "Walk review sections interactively and lock boundaries, data flow, state transitions, edge cases, and failure modes.",
+            "Cover security, observability, deployment, tests, and performance for Standard+ changes.",
+            "Run configured stale-diagram audit when enabled.",
+            "Produce required outputs: NOT-in-scope, What-already-exists, tier diagrams, failure table, completion dashboard.",
+            "Plant high-upside deferred ideas when useful and reconcile critic/outside-voice findings.",
             "Write design lock artifact for downstream spec/plan."
         ],
         requiredGates: [
@@ -111,8 +90,8 @@ export const DESIGN = {
             "Security & threat model findings are documented with mitigations.",
             "Observability and deployment plans are explicit for critical flows.",
             "Outside-voice findings and dispositions are recorded (accept/reject/defer).",
-            "Spec review loop summary includes iteration count and quality score trajectory.",
-            "When `.cclaw/config.yaml::reviewLoop.externalSecondOpinion.enabled` is true, external second-opinion disposition is captured.",
+            `Spec review loop summary includes iteration count and quality score trajectory per ${reviewLoopPolicySummary("design")}`,
+            reviewLoopSecondOpinionSummary("design"),
             "Test strategy includes unit/integration/e2e expectations.",
             "When a high-upside idea is deferred, a seed file is created under `.cclaw/seeds/` and referenced in the artifact.",
             "NOT-in-scope section produced.",
@@ -162,12 +141,13 @@ export const DESIGN = {
             traceabilityRule: "Every architecture decision must trace to a scope boundary. Every downstream spec requirement must trace to a design decision."
         },
         artifactValidation: [
-            { section: "Research Fleet Synthesis", required: true, validationRule: "Must summarize all four lenses (stack/features/architecture/pitfalls) and map findings to concrete design decisions." },
-            { section: "Codebase Investigation", required: false, validationRule: "Must list blast-radius files with current responsibilities and discovered patterns." },
+            { section: "Upstream Handoff", required: false, validationRule: "Summarizes scope/research decisions, constraints, open questions, and explicit drift before design choices." },
+            { section: "Research Fleet Synthesis", required: true, validationRule: "Must summarize the tiered lenses actually run (Lightweight=pitfalls, Standard=architecture+pitfalls, Deep=all four) and map findings to concrete design decisions." },
+            { section: "Codebase Investigation", required: false, validationRule: "Investigator pass: list blast-radius files with current responsibilities, discovered patterns, and reuse candidates." },
             { section: "Search Before Building", required: false, validationRule: "For each technical choice: Layer 1 (exact match), Layer 2 (partial match), Layer 3 (inspiration), EUREKA labels with reuse-first default." },
             { section: "Architecture Boundaries", required: true, validationRule: "Must list component boundaries with ownership." },
             { section: "Architecture Diagram", required: true, validationRule: "Must include `<!-- diagram: architecture -->` marker. Diagram must label concrete nodes, label arrows, mark direction, distinguish sync/async edges, and include at least one failure/degraded edge." },
-            { section: "Data-Flow Shadow Paths", required: false, validationRule: "Standard/Deep: include `<!-- diagram: data-flow-shadow-paths -->` marker and path table with trigger plus fallback/degrade behavior." },
+            { section: "Data-Flow Shadow Paths", required: false, validationRule: "Standard/Deep: include `<!-- diagram: data-flow-shadow-paths -->` marker plus a table for high-risk choices: chosen path, shadow alternative, switch trigger, fallback/degrade behavior, and verification evidence." },
             { section: "Error Flow Diagram", required: false, validationRule: "Standard/Deep: include `<!-- diagram: error-flow -->` marker and failure-detection -> rescue -> user-visible outcome flow." },
             { section: "State Machine Diagram", required: false, validationRule: "Deep: include `<!-- diagram: state-machine -->` marker and state transitions for critical flow lifecycle." },
             { section: "Rollback Flowchart", required: false, validationRule: "Deep: include `<!-- diagram: rollback-flowchart -->` marker with trigger -> rollback actions -> verification." },
@@ -181,8 +161,8 @@ export const DESIGN = {
             { section: "Observability & Debuggability", required: true, validationRule: "Must define logs/metrics/traces plus alerting/debug path for critical failure modes." },
             { section: "Deployment & Rollout", required: true, validationRule: "Must define migration/flag strategy, rollback plan, and post-deploy verification steps." },
             { section: "What Already Exists", required: false, validationRule: "For each sub-problem: existing code/library found (Layer 1-3/EUREKA label), reuse decision, and adaptation needed." },
-            { section: "Outside Voice Findings", required: false, validationRule: "List adversarial findings and disposition (accept/reject/defer) with rationale per finding." },
-            { section: "Spec Review Loop", required: false, validationRule: "Record iteration table (max 3) with quality score per iteration, stop reason, and unresolved concerns." },
+            { section: "Outside Voice Findings", required: false, validationRule: "Critic pass: list adversarial findings and disposition (accept/reject/defer) with rationale per material finding." },
+            { section: "Spec Review Loop", required: false, validationRule: `Record iteration table with quality score per iteration, stop reason, and unresolved concerns. Enforce ${reviewLoopPolicySummary("design")}` },
             { section: "NOT in scope", required: false, validationRule: "Work considered and explicitly deferred with one-line rationale." },
             { section: "Parallelization Strategy", required: false, validationRule: "If multi-module: dependency table, parallel lanes, conflict flags." },
             { section: "Unresolved Decisions", required: false, validationRule: "If any: what info is missing, who provides it, default if unanswered." },