cclaw-cli 0.48.31 → 0.48.33

package/dist/content/seed-shelf.d.ts

@@ -0,0 +1,36 @@
+export interface SeedShelfEntry {
+    fileName: string;
+    absPath: string;
+    relPath: string;
+    createdOn: string;
+    title: string;
+    triggerWhen: string[];
+    sourceStage: string | null;
+    sourceArtifact: string | null;
+    hypothesis: string | null;
+    action: string | null;
+    summary: string;
+    raw: string;
+}
+export interface SeedTemplateInput {
+    title: string;
+    triggerWhen: readonly string[];
+    hypothesis: string;
+    action: string;
+    sourceStage?: string;
+    sourceArtifact?: string;
+    createdAt?: Date;
+}
+export interface ResolvedSeedPath {
+    fileName: string;
+    absPath: string;
+    relPath: string;
+}
+export declare function seedShelfDir(projectRoot: string): string;
+export declare function seedSlug(title: string): string;
+export declare function seedFileName(title: string, createdAt?: Date): string;
+export declare function resolveSeedPathForWrite(projectRoot: string, title: string, createdAt?: Date): Promise<ResolvedSeedPath>;
+export declare function readSeedShelf(projectRoot: string): Promise<SeedShelfEntry[]>;
+export declare function seedMatchesPrompt(seed: SeedShelfEntry, prompt: string): boolean;
+export declare function findMatchingSeeds(projectRoot: string, prompt: string, maxMatches?: number): Promise<SeedShelfEntry[]>;
+export declare function renderSeedTemplate(input: SeedTemplateInput): string;

package/dist/content/seed-shelf.js

@@ -0,0 +1,236 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+import { RUNTIME_ROOT } from "../constants.js";
+const SEED_FILE_NAME_PATTERN = /^SEED-(\d{4}-\d{2}-\d{2})-([a-z0-9]+(?:-[a-z0-9]+)*)(?:-(\d+))?\.md$/u;
+const DEFAULT_MAX_MATCHES = 3;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeTriggerList(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => typeof item === "string" || typeof item === "number" ? String(item).trim() : "")
+            .filter((item) => item.length > 0);
+    }
+    if (typeof value === "string") {
+        return value
+            .split(/,\s*/u)
+            .map((item) => item.trim())
+            .filter((item) => item.length > 0);
+    }
+    return [];
+}
+function parseSeedFrontmatter(raw) {
+    if (!raw.startsWith("---")) {
+        return { values: {}, body: raw };
+    }
+    const lines = raw.split(/\r?\n/u);
+    let closingIndex = -1;
+    for (let index = 1; index < lines.length; index += 1) {
+        if (lines[index]?.trim() === "---") {
+            closingIndex = index;
+            break;
+        }
+    }
+    if (closingIndex < 0) {
+        return { values: {}, body: raw };
+    }
+    const frontmatterRaw = lines.slice(1, closingIndex).join("\n");
+    const body = lines.slice(closingIndex + 1).join("\n");
+    try {
+        const parsed = parse(frontmatterRaw);
+        if (isRecord(parsed)) {
+            return { values: parsed, body };
+        }
+        return { values: {}, body };
+    }
+    catch {
+        return { values: {}, body };
+    }
+}
+function firstHeading(body) {
+    const match = /^#\s+(.+)$/mu.exec(body);
+    if (!match)
+        return null;
+    const title = match[1]?.trim() ?? "";
+    return title.length > 0 ? title : null;
+}
+function firstNonEmptyParagraph(body) {
+    const lines = body.split(/\r?\n/u);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (/^#\s+/u.test(trimmed))
+            continue;
+        if (/^[-*]\s+/u.test(trimmed))
+            continue;
+        return trimmed;
+    }
+    return "";
+}
+function fromFileNameFallbackTitle(fileName) {
+    const stem = fileName.replace(/\.md$/u, "");
+    const withoutPrefix = stem.replace(/^SEED-\d{4}-\d{2}-\d{2}-/u, "");
+    return withoutPrefix
+        .split("-")
+        .filter((part) => part.length > 0 && !/^\d+$/u.test(part))
+        .map((part) => part[0]?.toUpperCase() + part.slice(1))
+        .join(" ")
+        .trim();
+}
+export function seedShelfDir(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "seeds");
+}
+export function seedSlug(title) {
+    const normalized = title
+        .toLowerCase()
+        .trim()
+        .replace(/[`"'“”‘’()[\]{}<>]/gu, " ")
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-+/u, "")
+        .replace(/-+$/u, "");
+    if (normalized.length === 0) {
+        return "seed";
+    }
+    return normalized.slice(0, 48);
+}
+function isoDate(value) {
+    return value.toISOString().slice(0, 10);
+}
+export function seedFileName(title, createdAt = new Date()) {
+    return `SEED-${isoDate(createdAt)}-${seedSlug(title)}.md`;
+}
+async function pathExists(absPath) {
+    try {
+        await fs.stat(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveSeedPathForWrite(projectRoot, title, createdAt = new Date()) {
+    const seedsDir = seedShelfDir(projectRoot);
+    await fs.mkdir(seedsDir, { recursive: true });
+    const baseFile = seedFileName(title, createdAt);
+    const baseStem = baseFile.replace(/\.md$/u, "");
+    let candidate = baseFile;
+    let index = 2;
+    while (await pathExists(path.join(seedsDir, candidate))) {
+        candidate = `${baseStem}-${index}.md`;
+        index += 1;
+    }
+    return {
+        fileName: candidate,
+        absPath: path.join(seedsDir, candidate),
+        relPath: path.join(RUNTIME_ROOT, "seeds", candidate)
+    };
+}
+export async function readSeedShelf(projectRoot) {
+    const dir = seedShelfDir(projectRoot);
+    let names = [];
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const fileName of names) {
+        if (!SEED_FILE_NAME_PATTERN.test(fileName))
+            continue;
+        const absPath = path.join(dir, fileName);
+        let raw = "";
+        try {
+            raw = await fs.readFile(absPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const frontmatter = parseSeedFrontmatter(raw);
+        const title = (typeof frontmatter.values.title === "string" && frontmatter.values.title.trim().length > 0
+            ? frontmatter.values.title.trim()
+            : null) ??
+            firstHeading(frontmatter.body) ??
+            fromFileNameFallbackTitle(fileName) ??
+            "Untitled seed";
+        const triggerWhen = normalizeTriggerList(frontmatter.values.trigger_when ?? frontmatter.values.triggerWhen);
+        const sourceStage = typeof frontmatter.values.source_stage === "string"
+            ? frontmatter.values.source_stage
+            : typeof frontmatter.values.sourceStage === "string"
+                ? frontmatter.values.sourceStage
+                : null;
+        const sourceArtifact = typeof frontmatter.values.source_artifact === "string"
+            ? frontmatter.values.source_artifact
+            : typeof frontmatter.values.sourceArtifact === "string"
+                ? frontmatter.values.sourceArtifact
+                : null;
+        const hypothesis = typeof frontmatter.values.hypothesis === "string" ? frontmatter.values.hypothesis : null;
+        const action = typeof frontmatter.values.action === "string" ? frontmatter.values.action : null;
+        const createdOn = SEED_FILE_NAME_PATTERN.exec(fileName)?.[1] ?? "1970-01-01";
+        const summary = firstNonEmptyParagraph(frontmatter.body);
+        entries.push({
+            fileName,
+            absPath,
+            relPath: path.join(RUNTIME_ROOT, "seeds", fileName),
+            createdOn,
+            title,
+            triggerWhen,
+            sourceStage,
+            sourceArtifact,
+            hypothesis,
+            action,
+            summary,
+            raw
+        });
+    }
+    entries.sort((a, b) => b.fileName.localeCompare(a.fileName));
+    return entries;
+}
+export function seedMatchesPrompt(seed, prompt) {
+    const normalizedPrompt = prompt.toLowerCase().trim();
+    if (normalizedPrompt.length === 0)
+        return false;
+    if (seed.triggerWhen.length === 0)
+        return false;
+    return seed.triggerWhen.some((trigger) => normalizedPrompt.includes(trigger.toLowerCase()));
+}
+export async function findMatchingSeeds(projectRoot, prompt, maxMatches = DEFAULT_MAX_MATCHES) {
+    const seeds = await readSeedShelf(projectRoot);
+    const matches = seeds.filter((seed) => seedMatchesPrompt(seed, prompt));
+    return matches.slice(0, Math.max(1, maxMatches));
+}
+export function renderSeedTemplate(input) {
+    const triggerWhen = [...input.triggerWhen].map((item) => item.trim()).filter((item) => item.length > 0);
+    const createdAt = input.createdAt ?? new Date();
+    const sourceStage = input.sourceStage?.trim() || "unknown";
+    const sourceArtifact = input.sourceArtifact?.trim() || "unknown";
+    return `---
+title: ${input.title.trim()}
+created_at: ${createdAt.toISOString()}
+source_stage: ${sourceStage}
+source_artifact: ${sourceArtifact}
+trigger_when:
+${triggerWhen.length > 0 ? triggerWhen.map((trigger) => `  - ${trigger}`).join("\n") : "  - <trigger token>"}
+hypothesis: ${input.hypothesis.trim()}
+action: ${input.action.trim()}
+---
+
+# ${input.title.trim()}
+
+## Why capture this seed
+${input.hypothesis.trim()}
+
+## Trigger when
+${triggerWhen.length > 0 ? triggerWhen.map((trigger) => `- ${trigger}`).join("\n") : "- <trigger token>"}
+
+## Suggested action
+${input.action.trim()}
+
+## Notes
+- Expected payoff:
+- Risks:
+`;
+}

package/dist/content/skills.js

@@ -82,6 +82,18 @@ function reviewSectionsBlock(sectionsInput) {
 ${sections}
 `;
 }
+function reviewLoopBlock(reviewLoop) {
+    if (!reviewLoop)
+        return "";
+    const checklist = reviewLoop.checklist.map((item) => `- \`${item}\``).join("\n");
+    return `## Outside Voice Review Loop
+- Stage: \`${reviewLoop.stage}\`
+- Target score: \`${reviewLoop.targetScore}\`
+- Max iterations: \`${reviewLoop.maxIterations}\`
+- Checklist dimensions:
+${checklist}
+`;
+}
 function verificationBlock(stage) {
     if (!VERIFICATION_STAGES.includes(stage))
         return "";
@@ -297,6 +309,59 @@ function normalizedGuidanceKey(value) {
         .trim()
         .toLowerCase();
 }
+function mermaidNodeLabel(raw, index) {
+    const stripped = raw
+        .replace(/`[^`]+`/gu, "")
+        .replace(/\*\*/gu, "")
+        .replace(/[*_]/gu, "")
+        .replace(/\[[^\]]*\]\([^)]*\)/gu, "")
+        .split(/[—:.;]/u)[0]
+        ?.trim() ?? "";
+    const words = stripped.split(/\s+/u).filter((word) => word.length > 0);
+    const short = words.slice(0, 4).join(" ");
+    const label = short.length === 0
+        ? `Step ${index + 1}`
+        : short.replace(/["`]/gu, "");
+    return label.length > 48 ? `${label.slice(0, 45)}...` : label;
+}
+const MERMAID_PROCESS_MAX_NODES = 10;
+function renderProcessFlowMermaid(executionModel) {
+    if (executionModel.processFlow && executionModel.processFlow.trim().length > 0) {
+        return `\`\`\`mermaid\n${executionModel.processFlow.trim()}\n\`\`\``;
+    }
+    const source = executionModel.process.length > 0
+        ? executionModel.process
+        : executionModel.checklist;
+    if (source.length === 0) {
+        return "";
+    }
+    const limited = source.slice(0, MERMAID_PROCESS_MAX_NODES);
+    const nodes = limited.map((item, index) => ({
+        id: `S${index + 1}`,
+        label: mermaidNodeLabel(item, index)
+    }));
+    const lines = ["flowchart TD"];
+    for (const node of nodes) {
+        lines.push(`  ${node.id}["${node.label}"]`);
+    }
+    for (let i = 0; i < nodes.length - 1; i += 1) {
+        lines.push(`  ${nodes[i].id} --> ${nodes[i + 1].id}`);
+    }
+    if (source.length > MERMAID_PROCESS_MAX_NODES) {
+        lines.push(`  S${nodes.length} --> More["...see full Checklist"]`);
+    }
+    return `\`\`\`mermaid\n${lines.join("\n")}\n\`\`\``;
+}
+function renderPlatformNotesBlock(notes) {
+    if (!notes || notes.length === 0) {
+        return "";
+    }
+    const body = notes.map((item) => `- ${item}`).join("\n");
+    return `## Platform Notes
+${body}
+
+`;
+}
 function dedupeGuidance(items, blockedBy) {
     const blocked = new Set(blockedBy
         .map((item) => normalizedGuidanceKey(item))
@@ -333,8 +398,10 @@ export function stageSkillMarkdown(stage, track = "standard") {
         .map((item, i) => `${i + 1}. ${item}`)
         .join("\n");
     const interactionFocus = dedupeGuidance(executionModel.interactionProtocol, [...executionModel.checklist, ...executionModel.process]).slice(0, 5);
-    const processSummary = dedupeGuidance(executionModel.process, executionModel.checklist).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(", ")
         : "none";
@@ -373,7 +440,10 @@ ${philosophy.hardGate}
 ${mergedAntiPatterns(philosophy, executionModel)}
 
 ## Process
-${processSummary.length > 0 ? processSummary.map((item, i) => `${i + 1}. ${item}`).join("\n") : "1. Execute the Checklist in order.\n2. Satisfy every required gate.\n3. Complete verification before stage closeout."}
+
+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.
+
+${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)"}
@@ -381,7 +451,7 @@ ${executionModel.inputs.length > 0 ? executionModel.inputs.map((item) => `- ${it
 ## Required Context
 ${executionModel.requiredContext.length > 0 ? executionModel.requiredContext.map((item) => `- ${item}`).join("\n") : "- None beyond this skill"}
 
-${contextLoadingBlock(artifactRules.crossStageTrace)}
+${platformNotesBlock}${contextLoadingBlock(artifactRules.crossStageTrace)}
 ${autoSubagentDispatchBlock(stage, track)}
 ${researchPlaybooksBlock(executionModel.researchPlaybooks ?? [])}
 
@@ -394,6 +464,9 @@ ${checklistItems}
 ${stageExamples(stage)}
 
 ## Interaction Protocol
+
+These are **rules for HOW you interact with the user** during this stage — tone, question shape, decision gating. Ordered steps of *what to do* live in the Checklist; do not treat these as an alternative sequence.
+
 ${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}\`
@@ -418,7 +491,7 @@ ${crossStageTraceBlock(artifactRules.crossStageTrace)}
 ${artifactValidationBlock(artifactRules.artifactValidation)}
 
 ## Review Lens
-## Outputs
+${reviewLoopSection ? `${reviewLoopSection}\n` : ""}## Outputs
 ${reviewLens.outputs.map((item) => `- ${item}`).join("\n")}
 
 ${reviewSectionsBlock(reviewLens.reviewSections)}

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

@@ -1,6 +1,6 @@
 import type { FlowStage, FlowTrack, TransitionRule } from "../types.js";
 import type { StageComplexityTier, StageAutoSubagentDispatch, StageSchema } from "./stages/schema-types.js";
-export type { ArtifactValidation, CrossStageTrace, ReviewSection, StageComplexityTier, StageExecutionModel, StagePhilosophy, StageArtifactRules, StageReviewLens, StageAutoSubagentDispatch, StageGate, StageSchemaLegacyInput, StageSchema, StageSchemaInput, StageSchemaV2Input } from "./stages/schema-types.js";
+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 interface SkillEnvelope {

package/dist/content/stage-schema.js

@@ -145,13 +145,23 @@ const REQUIRED_GATE_IDS = {
     ]
 };
 const REQUIRED_ARTIFACT_SECTIONS = {
-    brainstorm: ["Context", "Problem", "Approaches", "Selected Direction"],
+    brainstorm: [
+        "Context",
+        "Problem",
+        "Approach Tier",
+        "Approaches",
+        "Approach Reaction",
+        "Selected Direction"
+    ],
     scope: ["Scope Mode", "In Scope / Out of Scope", "Completion Dashboard", "Scope Summary"],
     design: [
         "Research Fleet Synthesis",
         "Architecture Boundaries",
         "Architecture Diagram",
         "Failure Mode Table",
+        "Security & Threat Model",
+        "Observability & Debuggability",
+        "Deployment & Rollout",
         "Completion Dashboard"
     ],
     spec: ["Acceptance Criteria", "Edge Cases", "Testability Map", "Approval"],
@@ -214,6 +224,8 @@ function normalizeStageSchemaInput(value) {
         whenNotToUse: value.philosophy.whenNotToUse,
         interactionProtocol: value.executionModel.interactionProtocol,
         process: value.executionModel.process,
+        processFlow: value.executionModel.processFlow,
+        platformNotes: value.executionModel.platformNotes,
         requiredGates: value.executionModel.requiredGates,
         requiredEvidence: value.executionModel.requiredEvidence,
         inputs: value.executionModel.inputs,
@@ -227,6 +239,7 @@ function normalizeStageSchemaInput(value) {
         next: value.next,
         checklist: value.executionModel.checklist,
         reviewSections: value.reviewLens.reviewSections,
+        reviewLoop: value.reviewLens.reviewLoop,
         completionStatus: value.artifactRules.completionStatus,
         crossStageTrace: value.artifactRules.crossStageTrace,
         artifactValidation: value.artifactRules.artifactValidation,
@@ -434,6 +447,8 @@ export function stageSchema(stage, track = "standard") {
     const executionModel = {
         interactionProtocol: base.interactionProtocol,
         process: base.process,
+        processFlow: base.processFlow,
+        platformNotes: base.platformNotes,
         checklist: base.checklist,
         requiredGates: tieredGates,
         requiredEvidence: base.requiredEvidence,
@@ -453,7 +468,8 @@ export function stageSchema(stage, track = "standard") {
     const reviewLens = {
         outputs: base.outputs,
         reviewSections: base.reviewSections,
-        mandatoryDelegations
+        mandatoryDelegations,
+        reviewLoop: base.reviewLoop
     };
     return {
         ...base,

package/dist/content/stages/brainstorm.js

@@ -44,6 +44,7 @@ export const BRAINSTORM = {
             "**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`.",
@@ -74,6 +75,7 @@ export const BRAINSTORM = {
             "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.",
@@ -93,6 +95,7 @@ export const BRAINSTORM = {
             "2-3 approaches with trade-offs are recorded, including one higher-upside challenger option.",
             "User reaction to approaches is captured before final recommendation.",
             "Final recommendation explicitly reflects user reaction.",
+            "When a promising option is parked, a seed file is created under `.cclaw/seeds/` and referenced in the artifact.",
             "Approved direction and approval marker are present.",
             "Assumptions and open questions are captured (or explicitly marked as none)."
         ],
@@ -116,6 +119,11 @@ export const BRAINSTORM = {
             "required gates marked satisfied",
             "no implementation action taken",
             "artifact reviewed by user"
+        ],
+        platformNotes: [
+            "Write artifact paths in POSIX form (`.cclaw/artifacts/01-brainstorm-<slug>.md`) even on Windows — the runtime normalizes separators. Do NOT commit Windows-style backslashes into the artifact or flow-state.",
+            "Slugify titles with lowercase ASCII letters, digits, and single dashes only — avoid spaces and case-sensitive names so the file resolves identically on case-insensitive filesystems (macOS/Windows default).",
+            "When linking to files inside the artifact, use repo-relative forward-slash paths (`src/foo/bar.ts`) so reviewers on any OS can click through."
         ]
     },
     artifactRules: {
@@ -130,13 +138,21 @@ export const BRAINSTORM = {
             { section: "Context", required: true, validationRule: "Must reference project state and relevant existing code or patterns." },
             { 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: false, validationRule: "Must classify depth as Lightweight/Standard/Deep and explain why." },
-            { section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs and include one higher-upside challenger option." },
-            { section: "Approach Reaction", required: false, 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, and explicit approval marker." },
+            { 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: "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." },
             { section: "Design", required: false, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
             { section: "Visual Companion", required: false, validationRule: "If architecture/data-flow complexity is medium+, include compact ASCII/Mermaid diagram or explicitly justify omission." },
             { section: "Assumptions and Open Questions", required: false, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }
+        ],
+        trivialOverrideSections: [
+            "Context",
+            "Problem",
+            "Approach Tier",
+            "Short-Circuit Decision",
+            "Selected Direction"
         ]
     },
     reviewLens: {

package/dist/content/stages/design.js

@@ -1,3 +1,4 @@
+import { REVIEW_LOOP_CHECKLISTS } from "../review-loop.js";
 // ---------------------------------------------------------------------------
 // DESIGN — reference: gstack Eng review
 // ---------------------------------------------------------------------------
@@ -44,7 +45,7 @@ export const DESIGN = {
             "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:** architecture for all tiers; Standard/Deep adds Data-Flow Shadow Paths and Error Flow.",
+            "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.",
@@ -52,7 +53,9 @@ export const DESIGN = {
             "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.",
+            "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."
@@ -86,8 +89,9 @@ export const DESIGN = {
             "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, architecture + shadow/error diagrams, failure mode table.",
-            "Run outside-voice spec review loop (up to 3 iterations, quality score target >= 0.8).",
+            "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.",
             "Write design lock artifact for downstream spec/plan."
         ],
@@ -102,12 +106,15 @@ export const DESIGN = {
             "Research artifact written to `.cclaw/artifacts/02a-research.md` with stack/features/architecture/pitfalls sections plus synthesis.",
             "Artifact written to `.cclaw/artifacts/03-design-<slug>.md`.",
             "Failure-mode table exists in Method/Exception/Rescue/UserSees format.",
-            "Data-flow shadow and error-flow diagrams are present for Standard+ complexity.",
+            "Tier-required diagram markers are present: architecture (all tiers), +shadow/error (Standard+), +state-machine/rollback/deployment-sequence (Deep).",
+            "When `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is true, stale diagram audit finding is clear (no blast-radius file newer than diagram markers without explicit update).",
             "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.",
             "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.",
             "What-already-exists section produced.",
             "Completion dashboard lists review section status, critical/open gap counts, decision count, and unresolved items (or 'None')."
@@ -135,6 +142,11 @@ export const DESIGN = {
             "required gates marked satisfied",
             "completion dashboard present with all review-section statuses",
             "artifact complete for spec handoff"
+        ],
+        platformNotes: [
+            "Architecture diagrams (ASCII, Mermaid) must use plain ASCII punctuation — avoid smart quotes and em-dashes that render differently across Windows CMD (cp1252), macOS Terminal (UTF-8), and Linux consoles.",
+            "When referencing build or runtime tools in the design, name them by binary (`node`, `python`, `go`) rather than by IDE-specific run configurations (`npm: start (WebStorm)`, `launch.json:Debug`) so the design stays OS-agnostic.",
+            "File system layouts drawn in the artifact use forward slashes; explicitly note when a platform-specific path style is required (e.g. Windows long-path `\\\\?\\` prefix, macOS bundle `.app/Contents/MacOS/`)."
         ]
     },
     artifactRules: {
@@ -154,13 +166,23 @@ export const DESIGN = {
             { section: "Codebase Investigation", required: false, validationRule: "Must list blast-radius files with current responsibilities and discovered patterns." },
             { 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: "At least one diagram (ASCII, Mermaid, or image) showing component boundaries and data flow direction. Diagram must: (1) label every node with a concrete component name (no generic 'Service A/B'), (2) label every arrow with the action or message (no unlabeled arrows), (3) mark direction of data flow explicitly, (4) distinguish synchronous from asynchronous edges (e.g. solid vs dashed, or `sync:` / `async:` prefix), (5) include at least one failure/degraded edge line that contains an arrow plus a failure keyword (`timeout`, `error`, `fallback`, `degraded`, `retry`, etc.). Standard/Deep complexity must also include `Data-Flow Shadow Paths` and `Error Flow Diagram` sections." },
-            { section: "Data Flow", required: false, validationRule: "Must include happy path, nil input, empty input, upstream error paths, plus interaction edge-case matrix (double-click, navigate-away, stale-state, large-result, background-job abandonment)." },
+            { 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: "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." },
+            { section: "Deployment Sequence Diagram", required: false, validationRule: "Deep: include `<!-- diagram: deployment-sequence -->` marker with rollout order and guard checks." },
+            { section: "Data Flow", required: false, validationRule: "Must include happy path, nil input, empty input, upstream error paths, plus Interaction Edge Case matrix rows for: double-click, nav-away-mid-request, 10K-result dataset, background-job abandonment, zombie connection. Each row must declare handled yes/no and deferred item when not handled." },
+            { section: "Stale Diagram Audit", required: false, validationRule: "When `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is true: blast-radius files from Codebase Investigation must not be newer than the current design diagram-marker baseline unless explicitly refreshed." },
             { section: "Failure Mode Table", required: true, validationRule: "Use Method/Exception/Rescue/UserSees columns and treat silent user impact without rescue as critical." },
-            { section: "Security & Threat Model", required: false, validationRule: "Must list trust boundaries, abuse/failure scenarios, mitigations, and residual risks." },
+            { section: "Security & Threat Model", required: true, validationRule: "Must list trust boundaries, abuse/failure scenarios, mitigations, and residual risks." },
             { section: "Test Strategy", required: false, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },
             { section: "Performance Budget", required: false, validationRule: "For each critical path: metric name, target threshold, and measurement method." },
+            { 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: "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." },
@@ -178,6 +200,12 @@ export const DESIGN = {
             "What-already-exists section",
             "design completion dashboard"
         ],
+        reviewLoop: {
+            stage: "design",
+            checklist: REVIEW_LOOP_CHECKLISTS.design.map((dimension) => dimension.id),
+            maxIterations: 3,
+            targetScore: 0.8
+        },
         reviewSections: [
             {
                 title: "Architecture Review",