cclaw-cli 0.48.27 → 0.48.28

package/dist/content/contracts.js

@@ -1,4 +1,4 @@
-import { stageSchema } from "./stage-schema.js";
+import { stagePolicyNeedles, stageSchema } from "./stage-schema.js";
 import { stageSkillFolder } from "./skills.js";
 export function stageCommandContract(stage, track = "standard") {
     const schema = stageSchema(stage, track);
@@ -17,6 +17,7 @@ export function stageCommandContract(stage, track = "standard") {
     const writeStepPaths = writes.length > 1
         ? writes.map((w) => `\`${w}\``).join(" and ")
         : `\`${primaryArtifact}\``;
+    const policyNeedles = stagePolicyNeedles(stage, track);
     return `# /cc-${stage}
 
 Load and follow **${skillPath}** — it contains the full checklist, examples, interaction protocol, and verification discipline.
@@ -45,6 +46,6 @@ ${gateIds}
 ${schema.exitCriteria.map((v) => `- ${v}`).join("\n")}
 
 ## Anchors
-${schema.policyNeedles.map((v) => `- ${v}`).join("\n")}
+${policyNeedles.map((v) => `- ${v}`).join("\n")}
 `;
 }

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, StageSchema, StageSchemaInput } 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 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

@@ -1,6 +1,7 @@
 import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "../types.js";
 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";
 // ---------------------------------------------------------------------------
 // NOTE: The former QUESTION_FORMAT_SPEC / ERROR_BUDGET_SPEC exports were
@@ -178,6 +179,46 @@ function readsFromForTrack(readsFrom, track) {
         return stageSet.has(stage);
     });
 }
+function isStageSchemaV2Input(value) {
+    return value.schemaShape === "v2";
+}
+function normalizeStageSchemaInput(value) {
+    if (!isStageSchemaV2Input(value)) {
+        return value;
+    }
+    return {
+        stage: value.stage,
+        skillFolder: value.skillFolder,
+        skillName: value.skillName,
+        skillDescription: value.skillDescription,
+        complexityTier: value.complexityTier,
+        hardGate: value.philosophy.hardGate,
+        ironLaw: value.philosophy.ironLaw,
+        purpose: value.philosophy.purpose,
+        whenToUse: value.philosophy.whenToUse,
+        whenNotToUse: value.philosophy.whenNotToUse,
+        interactionProtocol: value.executionModel.interactionProtocol,
+        process: value.executionModel.process,
+        requiredGates: value.executionModel.requiredGates,
+        requiredEvidence: value.executionModel.requiredEvidence,
+        inputs: value.executionModel.inputs,
+        requiredContext: value.executionModel.requiredContext,
+        researchPlaybooks: value.executionModel.researchPlaybooks,
+        outputs: value.reviewLens.outputs,
+        blockers: value.executionModel.blockers,
+        exitCriteria: value.executionModel.exitCriteria,
+        commonRationalizations: value.philosophy.commonRationalizations,
+        artifactFile: value.artifactRules.artifactFile,
+        next: value.next,
+        checklist: value.executionModel.checklist,
+        reviewSections: value.reviewLens.reviewSections,
+        completionStatus: value.artifactRules.completionStatus,
+        crossStageTrace: value.artifactRules.crossStageTrace,
+        artifactValidation: value.artifactRules.artifactValidation,
+        batchExecutionAllowed: value.batchExecutionAllowed,
+        trivialOverrideSections: value.artifactRules.trivialOverrideSections
+    };
+}
 // ---------------------------------------------------------------------------
 // Stage map and accessors
 // ---------------------------------------------------------------------------
@@ -357,7 +398,8 @@ export function mandatoryDelegationsForStage(stage, complexityTier = "standard")
             .map((d) => d.agent))];
 }
 export function stageSchema(stage, track = "standard") {
-    const base = stage === "tdd" ? tddStageForTrack(track) : STAGE_SCHEMA_MAP[stage];
+    const rawInput = stage === "tdd" ? tddStageForTrack(track) : STAGE_SCHEMA_MAP[stage];
+    const base = normalizeStageSchemaInput(rawInput);
     const tieredGates = tieredStageGates(stage, base.requiredGates, track);
     const tieredValidation = tieredArtifactValidation(stage, base.artifactValidation);
     const crossStageTrace = {
@@ -396,8 +438,7 @@ export function stageSchema(stage, track = "standard") {
     const reviewLens = {
         outputs: base.outputs,
         reviewSections: base.reviewSections,
-        mandatoryDelegations,
-        policyNeedles: base.policyNeedles
+        mandatoryDelegations
     };
     return {
         ...base,
@@ -464,7 +505,7 @@ export function buildTransitionRules() {
     return rules;
 }
 export function stagePolicyNeedles(stage, track = "standard") {
-    return stageSchema(stage, track).policyNeedles;
+    return stagePolicyNeedlesFromMetadata(stage, track);
 }
 export function stageAutoSubagentDispatch(stage) {
     return STAGE_AUTO_SUBAGENT_DISPATCH[stage];

package/dist/content/stages/_lint-metadata/index.d.ts

@@ -0,0 +1,2 @@
+import type { FlowStage, FlowTrack } from "../../../types.js";
+export declare function stagePolicyNeedlesFromMetadata(stage: FlowStage, track?: FlowTrack): string[];

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

@@ -0,0 +1,79 @@
+import { SHIP_FINALIZATION_MODES } from "../../../constants.js";
+const STAGE_POLICY_NEEDLES = {
+    brainstorm: [
+        "Explore project context",
+        "One question at a time",
+        "2-3 architecturally distinct approaches",
+        "State what is being approved",
+        "Self-review before handoff",
+        "Do NOT implement, scaffold, or modify behavior"
+    ],
+    scope: [
+        "Scope mode",
+        "In Scope",
+        "Out of Scope",
+        "Discretion Areas",
+        "NOT in scope",
+        "Premise Challenge",
+        "Locked Decisions"
+    ],
+    design: [
+        "Parallel Research Fleet",
+        "Architecture",
+        "Data Flow",
+        "Failure Modes and Mitigation",
+        "Performance Budget",
+        "One issue at a time"
+    ],
+    spec: ["Acceptance Criteria", "Constraints", "Testability", "approved spec", "Edge Cases"],
+    plan: [
+        "WAIT_FOR_CONFIRM",
+        "Task Graph",
+        "Dependency Batches",
+        "Acceptance Mapping",
+        "verification steps",
+        "Locked Decision Coverage"
+    ],
+    tdd: [
+        "RED",
+        "GREEN",
+        "REFACTOR",
+        "failing test",
+        "full test suite",
+        "acceptance criteria",
+        "traceable to plan slice"
+    ],
+    review: [
+        "Layer 1",
+        "Layer 2",
+        "Critical",
+        "Review Army",
+        "Ready to Ship",
+        "ROUTE_BACK_TO_TDD",
+        "One issue at a time"
+    ],
+    ship: [
+        "Pre-Ship Checks",
+        "Release Notes",
+        "Rollback Plan",
+        ...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);
+    }
+    return [...needles];
+}

package/dist/content/stages/brainstorm.js

@@ -2,149 +2,150 @@
 // BRAINSTORM — reference: superpowers brainstorming
 // ---------------------------------------------------------------------------
 export const BRAINSTORM = {
+    schemaShape: "v2",
     stage: "brainstorm",
     complexityTier: "standard",
     skillFolder: "brainstorming",
     skillName: "brainstorming",
     skillDescription: "Design-first stage. Explore context, understand intent through collaborative dialogue, propose distinct approaches, and lock an approved direction before scope/design work.",
-    hardGate: "Do NOT invoke implementation skills, write code, scaffold projects, or mutate product behavior until a concrete direction is approved by the user.",
-    ironLaw: "NO ARTIFACT IS COMPLETE WITHOUT AN EXPLICITLY APPROVED DIRECTION — SILENCE IS NOT APPROVAL.",
-    purpose: "Turn an initial idea into an approved design direction through natural collaborative dialogue — understanding the problem before proposing solutions.",
-    whenToUse: [
-        "Starting a new feature or behavior change",
-        "Requirements are ambiguous or trade-offs are unclear",
-        "Before any implementation-stage command or architecture commitment"
-    ],
-    whenNotToUse: [
-        "A valid approved direction already exists and only execution remains",
-        "The request is a pure release/finalization action with no new product decisions",
-        "The task is retrospective only (post-ship audit with no new solution choices)"
-    ],
-    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.",
-        "**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.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`."
-    ],
-    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."
-    ],
-    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.",
-        "Present design sections incrementally, get approval after each.",
-        "Write approved direction to `.cclaw/artifacts/01-brainstorm.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."
-    ],
-    requiredGates: [
-        { id: "brainstorm_approaches_compared", description: "2-3 architecturally distinct approaches were compared with real trade-offs and a recommendation." },
-        { id: "brainstorm_direction_approved", description: "User approved a concrete direction and what exactly was approved is stated." },
-        { id: "brainstorm_artifact_reviewed", description: "User reviewed the written brainstorm artifact and confirmed readiness." }
-    ],
-    requiredEvidence: [
-        "Artifact written to `.cclaw/artifacts/01-brainstorm.md`.",
-        "Project context was explored (files, docs, or recent activity referenced).",
-        "Clarifying questions and their answers are captured.",
-        "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.",
-        "Approved direction and approval marker are present.",
-        "Assumptions and open questions are captured (or explicitly marked as none)."
-    ],
-    inputs: ["problem statement", "constraints", "success criteria"],
-    requiredContext: [
-        "existing project context and patterns",
-        "current behavior of affected area",
-        "business and delivery constraints"
-    ],
-    researchPlaybooks: [
-        "research/repo-scan.md",
-        "research/learnings-lookup.md"
-    ],
-    outputs: [
-        "approved design direction",
-        "alternatives with trade-offs",
-        "brainstorm artifact"
-    ],
-    blockers: [
-        "no explicit approval",
-        "critical ambiguity unresolved",
-        "project context not explored"
-    ],
-    exitCriteria: [
-        "approved design direction documented",
-        "required gates marked satisfied",
-        "no implementation action taken",
-        "artifact reviewed by user"
-    ],
-    commonRationalizations: [
-        "Asking questions without exploring existing project context first",
-        "Asking bundled or purely informational questions that don't change decisions",
-        "Proposing cosmetic option variants instead of architecturally distinct approaches",
-        "Revealing recommendation before collecting user reaction",
-        "Three same-altitude approaches with no higher-upside challenger",
-        "Jumping directly into implementation",
-        "Requesting approval without stating what decision is being approved",
-        "Questions that only gather preferences without design impact",
-        "Options that are variants of one approach, not distinct alternatives"
-    ],
-    policyNeedles: [
-        "Explore project context",
-        "One question at a time",
-        "2-3 architecturally distinct approaches",
-        "State what is being approved",
-        "Self-review before handoff",
-        "Do NOT implement, scaffold, or modify behavior"
-    ],
-    artifactFile: "01-brainstorm.md",
-    next: "scope",
-    reviewSections: [],
-    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
-    crossStageTrace: {
-        readsFrom: [],
-        writesTo: [".cclaw/artifacts/01-brainstorm.md"],
-        traceabilityRule: "Scope and design decisions must trace back to explored context and approved brainstorm direction."
+    philosophy: {
+        hardGate: "Do NOT invoke implementation skills, write code, scaffold projects, or mutate product behavior until a concrete direction is approved by the user.",
+        ironLaw: "NO ARTIFACT IS COMPLETE WITHOUT AN EXPLICITLY APPROVED DIRECTION — SILENCE IS NOT APPROVAL.",
+        purpose: "Turn an initial idea into an approved design direction through natural collaborative dialogue — understanding the problem before proposing solutions.",
+        whenToUse: [
+            "Starting a new feature or behavior change",
+            "Requirements are ambiguous or trade-offs are unclear",
+            "Before any implementation-stage command or architecture commitment"
+        ],
+        whenNotToUse: [
+            "A valid approved direction already exists and only execution remains",
+            "The request is a pure release/finalization action with no new product decisions",
+            "The task is retrospective only (post-ship audit with no new solution choices)"
+        ],
+        commonRationalizations: [
+            "Asking questions without exploring existing project context first",
+            "Asking bundled or purely informational questions that don't change decisions",
+            "Proposing cosmetic option variants instead of architecturally distinct approaches",
+            "Revealing recommendation before collecting user reaction",
+            "Three same-altitude approaches with no higher-upside challenger",
+            "Jumping directly into implementation",
+            "Requesting approval without stating what decision is being approved",
+            "Questions that only gather preferences without design impact",
+            "Options that are variants of one approach, not distinct alternatives"
+        ]
     },
-    artifactValidation: [
-        { 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: "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." }
-    ]
+    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.",
+            "**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.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`."
+        ],
+        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."
+        ],
+        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.",
+            "Present design sections incrementally, get approval after each.",
+            "Write approved direction to `.cclaw/artifacts/01-brainstorm.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."
+        ],
+        requiredGates: [
+            { id: "brainstorm_approaches_compared", description: "2-3 architecturally distinct approaches were compared with real trade-offs and a recommendation." },
+            { id: "brainstorm_direction_approved", description: "User approved a concrete direction and what exactly was approved is stated." },
+            { id: "brainstorm_artifact_reviewed", description: "User reviewed the written brainstorm artifact and confirmed readiness." }
+        ],
+        requiredEvidence: [
+            "Artifact written to `.cclaw/artifacts/01-brainstorm.md`.",
+            "Project context was explored (files, docs, or recent activity referenced).",
+            "Clarifying questions and their answers are captured.",
+            "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.",
+            "Approved direction and approval marker are present.",
+            "Assumptions and open questions are captured (or explicitly marked as none)."
+        ],
+        inputs: ["problem statement", "constraints", "success criteria"],
+        requiredContext: [
+            "existing project context and patterns",
+            "current behavior of affected area",
+            "business and delivery constraints"
+        ],
+        researchPlaybooks: [
+            "research/repo-scan.md",
+            "research/learnings-lookup.md"
+        ],
+        blockers: [
+            "no explicit approval",
+            "critical ambiguity unresolved",
+            "project context not explored"
+        ],
+        exitCriteria: [
+            "approved design direction documented",
+            "required gates marked satisfied",
+            "no implementation action taken",
+            "artifact reviewed by user"
+        ]
+    },
+    artifactRules: {
+        artifactFile: "01-brainstorm.md",
+        completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+        crossStageTrace: {
+            readsFrom: [],
+            writesTo: [".cclaw/artifacts/01-brainstorm.md"],
+            traceabilityRule: "Scope and design decisions must trace back to explored context and approved brainstorm direction."
+        },
+        artifactValidation: [
+            { 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: "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." }
+        ]
+    },
+    reviewLens: {
+        outputs: [
+            "approved design direction",
+            "alternatives with trade-offs",
+            "brainstorm artifact"
+        ],
+        reviewSections: []
+    },
+    next: "scope"
 };