cclaw-cli 0.48.31 → 0.48.32

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 "";
@@ -335,6 +347,7 @@ export function stageSkillMarkdown(stage, track = "standard") {
     const interactionFocus = dedupeGuidance(executionModel.interactionProtocol, [...executionModel.checklist, ...executionModel.process]).slice(0, 5);
     const processSummary = dedupeGuidance(executionModel.process, executionModel.checklist).slice(0, 5);
     const stageRefs = stageSpecificSeeAlso(stage);
+    const reviewLoopSection = reviewLoopBlock(reviewLens.reviewLoop);
     const mandatoryDelegationSummary = mandatoryDelegations.length > 0
         ? mandatoryDelegations.map((name) => `\`${name}\``).join(", ")
         : "none";
@@ -418,7 +431,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"],
@@ -227,6 +237,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,
@@ -453,7 +464,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)."
         ],
@@ -130,13 +133,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')."
@@ -154,13 +161,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 +195,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",

package/dist/content/stages/schema-types.d.ts

@@ -70,10 +70,18 @@ export interface StageReviewLens {
     outputs: string[];
     reviewSections: ReviewSection[];
     mandatoryDelegations: string[];
+    reviewLoop?: StageReviewLoop;
 }
 export interface StageReviewLensInput {
     outputs: string[];
     reviewSections: ReviewSection[];
+    reviewLoop?: StageReviewLoop;
+}
+export interface StageReviewLoop {
+    stage: "scope" | "design";
+    checklist: string[];
+    maxIterations: number;
+    targetScore: number;
 }
 export interface StageSchema {
     schemaShape: "v2";
@@ -130,6 +138,8 @@ export interface StageSchema {
     trivialOverrideSections?: string[];
     /** Agent names that MUST be dispatched (or waived) before stage transition — derived from mandatory auto-subagent rows. */
     mandatoryDelegations: string[];
+    /** Optional shared outside-voice loop config for scope/design stages. */
+    reviewLoop?: StageReviewLoop;
 }
 export type StageSchemaLegacyInput = Omit<StageSchema, "schemaShape" | "philosophy" | "executionModel" | "artifactRules" | "reviewLens" | "mandatoryDelegations" | "complexityTier"> & {
     schemaShape?: "legacy";

package/dist/content/stages/scope.js

@@ -1,3 +1,4 @@
+import { REVIEW_LOOP_CHECKLISTS } from "../review-loop.js";
 // ---------------------------------------------------------------------------
 // SCOPE — reference: gstack CEO review
 // ---------------------------------------------------------------------------
@@ -43,7 +44,7 @@ export const SCOPE = {
     },
     executionModel: {
         checklist: [
-            "**Pre-Scope System Audit** — before premise challenge, gather reality snapshot: recent commits (`git log -30 --oneline`), current diff (`git diff --stat`), stash state (`git stash list`), and deferred debt markers (`rg -n 'TODO|FIXME|XXX|HACK'`). Record findings in scope artifact.",
+            "**Pre-Scope System Audit (opt-in)** — when `.cclaw/config.yaml::optInAudits.scopePreAudit` is true, before premise challenge gather reality snapshot: recent commits (`git log -30 --oneline`), current diff (`git diff --stat`), stash state (`git stash list`), and deferred debt markers (`rg -n 'TODO|FIXME|XXX|HACK'`). Record findings in scope artifact.",
             "**Assess complexity** — Read the brainstorm artifact. If project is simple (single component, clear architecture, personal/prototype), run light-touch scope: mode selection, 3-5 key in/out boundaries, deferred items. Skip Dream State Mapping and Temporal Interrogation. If project is complex (multi-component, team delivery, production), run the full checklist.",
             "**Prime Directives** — Zero silent failures. For each in-scope capability, name concrete failure modes, the exact error surface, and trace all four data-flow paths (happy, nil, empty, upstream error). Include interaction edge cases (double-click, navigate-away, stale state), observability commitments, and explicit deferred-item logging.",
             "**Premise Challenge** — Is this the right problem? What if we do nothing? What are we optimizing for?",
@@ -55,7 +56,8 @@ export const SCOPE = {
             "**Temporal Interrogation** — (complex projects only) simulate implementation timeline: HOUR 1 foundations, HOUR 2-3 core logic, HOUR 4-5 integration surprises, HOUR 6+ polish/tests. Decide what must be locked now vs safely deferred.",
             "**Mode Selection** — Present expand/selective/hold/reduce with recommendation and default heuristic: greenfield -> expand, feature enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius (>15 files or multi-team impact) -> reduce.",
             "**Mode-Specific Analysis** — After mode is selected, run the matching analysis: EXPAND (10x and delight opportunities), SELECTIVE (hold-scope rigor then cherry-picked expansions), HOLD (minimum-change-set hardening), REDUCE (ruthless cuts and follow-up split).",
-            "**Outside Voice + Spec Review Loop** — run an adversarial second-opinion pass on the scope artifact, reconcile findings, and iterate up to 3 cycles or until quality score >= 0.8.",
+            "**Plant-seed shelf (optional)** — when a deferred/out-of-scope idea still has upside, capture it as `.cclaw/seeds/SEED-<YYYY-MM-DD>-<slug>.md` with trigger_when and action instead of losing it in prose-only notes.",
+            "**Outside Voice + Spec Review Loop** — run an adversarial second-opinion pass on the scope artifact, 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.",
             "**Error and Rescue Registry** — For each capability: what breaks, how detected, what fallback."
         ],
         interactionProtocol: [
@@ -74,15 +76,16 @@ export const SCOPE = {
             "**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 scope` (do not hand-edit `.cclaw/state/flow-state.json`)."
         ],
         process: [
-            "Run pre-scope system audit (git log/diff/stash/debt markers).",
+            "When `.cclaw/config.yaml::optInAudits.scopePreAudit` is true, run pre-scope system audit (git log/diff/stash/debt markers).",
             "Run premise challenge and existing-solution leverage check.",
             "When mode is EXPAND/SELECTIVE, run brief landscape check before final scope lock.",
             "Calibrate quality bar against 2-3 strong existing modules/files.",
             "Produce 2-3 scope alternatives in a structured format (Name, Summary, Effort, Risk, Pros, Cons, Reuses) with minimum viable and ideal architecture options included.",
             "Choose scope mode with user approval.",
             "Run mode-specific analysis that matches the selected scope mode.",
+            "Optionally plant high-upside deferred ideas into `.cclaw/seeds/SEED-<YYYY-MM-DD>-<slug>.md` with trigger_when/action notes.",
             "Walk through scope review sections one at a time.",
-            "Run outside-voice spec review loop (up to 3 iterations, quality score target >= 0.8).",
+            "Run outside-voice spec review loop (up to 3 iterations, quality score target >= 0.8). If configured, include external second opinion and reconcile deltas.",
             "Write explicit scope contract, discretion areas, and deferred items.",
             "Freeze non-negotiable boundaries as stable Locked Decisions (D-XX IDs).",
             "Produce scope summary plus completion dashboard (section status, critical gaps, resolved decisions, unresolved items or `None`)."
@@ -94,7 +97,7 @@ export const SCOPE = {
         ],
         requiredEvidence: [
             "Artifact written to `.cclaw/artifacts/02-scope-<slug>.md`.",
-            "Pre-Scope System Audit findings are captured (git log/diff/stash/debt markers).",
+            "When `.cclaw/config.yaml::optInAudits.scopePreAudit` is true, Pre-Scope System Audit findings are captured (git log/diff/stash/debt markers).",
             "In-scope and out-of-scope lists are explicit.",
             "Discretion areas are explicit (or marked as `None`).",
             "Selected mode and rationale are documented.",
@@ -102,7 +105,9 @@ export const SCOPE = {
             "Premise challenge findings documented.",
             "Outside Voice findings and dispositions are recorded (accept/reject/defer with rationale).",
             "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.",
             "Deferred items list with one-line rationale for each.",
+            "When an upside deferred idea is parked, a seed file is created under `.cclaw/seeds/` and referenced in the artifact.",
             "Completion dashboard lists per-section status, critical/open gaps, decision count, and unresolved items (or `None`)."
         ],
         inputs: ["brainstorm artifact", "timeline constraints", "product priorities"],
@@ -139,7 +144,7 @@ export const SCOPE = {
             traceabilityRule: "Every scope boundary must be traceable to a brainstorm decision. Every downstream design choice must stay within the scope contract."
         },
         artifactValidation: [
-            { section: "Pre-Scope System Audit", required: false, validationRule: "Must capture git log/diff/stash/debt-marker findings before premise challenge." },
+            { section: "Pre-Scope System Audit", required: false, validationRule: "When `.cclaw/config.yaml::optInAudits.scopePreAudit` is true: must capture git log -30, git diff --stat, git stash list, and debt-marker scan (TODO/FIXME/XXX/HACK) before premise challenge." },
             { section: "Prime Directives", required: false, validationRule: "For each scoped capability: named failure modes, explicit error surface, four data-flow paths, interaction edge cases, observability expectations, and deferred-item handling." },
             { section: "Premise Challenge", required: false, validationRule: "Must contain explicit answers to: right problem? direct path? what if nothing?" },
             { section: "Landscape Check", required: false, validationRule: "When mode is EXPAND/SELECTIVE, include at least one external reference insight and its impact on scope." },
@@ -163,6 +168,12 @@ export const SCOPE = {
     },
     reviewLens: {
         outputs: ["scope mode decision", "scope contract", "discretion areas list", "deferred scope list", "scope summary", "scope completion dashboard"],
+        reviewLoop: {
+            stage: "scope",
+            checklist: REVIEW_LOOP_CHECKLISTS.scope.map((dimension) => dimension.id),
+            maxIterations: 3,
+            targetScore: 0.8
+        },
         reviewSections: [
             {
                 title: "Scope Boundary Audit",