cclaw-cli 0.5.4 → 0.5.6

package/dist/content/skills.js

@@ -2,10 +2,6 @@ import { RUNTIME_ROOT } from "../constants.js";
 import { stageExamples } from "./examples.js";
 import { selfImprovementBlock } from "./learnings.js";
 import { QUESTION_FORMAT_SPEC, ERROR_BUDGET_SPEC, stageAutoSubagentDispatch, stageSchema } from "./stage-schema.js";
-function artifactFileName(artifactPath) {
-    const parts = artifactPath.split("/");
-    return parts[parts.length - 1] ?? artifactPath;
-}
 function rationalizationTable(stage) {
     const schema = stageSchema(stage);
     return `| Rationalization | Reality |
@@ -75,20 +71,17 @@ function contextLoadingBlock(stage) {
     const trace = stageSchema(stage).crossStageTrace;
     const readLines = trace.readsFrom.length > 0
         ? trace.readsFrom
-            .map((value) => {
-            const fileName = artifactFileName(value);
-            return `- Canonical: \`.cclaw/runs/<activeRunId>/artifacts/${fileName}\` (fallback: \`${value}\`)`;
-        })
+            .map((value) => `- \`${value}\``)
             .join("\n")
         : "- (first stage — no upstream artifacts)";
     return `## Context Loading
 
 Before starting stage execution:
-1. Read \`.cclaw/state/flow-state.json\` and capture \`activeRunId\`.
-2. Resolve canonical run artifact root: \`.cclaw/runs/<activeRunId>/artifacts/\`.
+1. Read \`.cclaw/state/flow-state.json\`.
+2. Resolve active artifact root: \`.cclaw/artifacts/\`.
 3. Load upstream artifacts required by this stage:
 ${readLines}
-4. If canonical run artifact is missing, fallback to the \`.cclaw/artifacts/\` mirror and record that fallback.
+4. Read \`.cclaw/knowledge.md\` and apply relevant entries before making decisions.
 `;
 }
 function whenNotToUseBlock(stage) {
@@ -113,7 +106,7 @@ function autoSubagentDispatchBlock(stage) {
         .join("\n");
     const mandatory = stageSchema(stage).mandatoryDelegations;
     const mandatoryList = mandatory.length > 0 ? mandatory.map((a) => `\`${a}\``).join(", ") : "(none — only proactive dispatch applies)";
-    const delegationLogRel = `${RUNTIME_ROOT}/runs/<activeRunId>/delegation-log.json`;
+    const delegationLogRel = `${RUNTIME_ROOT}/state/delegation-log.json`;
     return `## Automatic Subagent Dispatch
 
 Machine-only work should be delegated to specialist agents automatically according to the matrix below.
@@ -174,7 +167,7 @@ When all required gates are satisfied and the artifact is written:
 1. **Update \`${RUNTIME_ROOT}/state/flow-state.json\`:**
 ${stateUpdate}
    - For each passed gate, add an entry to \`guardEvidence\`: \`"<gate_id>": "<artifact path or excerpt proving the gate>"\`. Do NOT leave \`guardEvidence\` empty.
-2. **Persist artifact** at \`${RUNTIME_ROOT}/artifacts/${schema.artifactFile}\`. Do NOT manually copy into run directories; cclaw sync/runtime keeps \`${RUNTIME_ROOT}/runs/<activeRunId>/artifacts/\` aligned.
+2. **Persist artifact** at \`${RUNTIME_ROOT}/artifacts/${schema.artifactFile}\`. Do NOT manually copy into \`${RUNTIME_ROOT}/runs/\`; archival is handled by \`cclaw archive\`.
 ${nextAction}
 
 **STOP.** Do not load the next stage skill yourself. The user will run \`/cc-next\` when ready (same session or new session).
@@ -231,7 +224,7 @@ function progressiveDisclosureBlock(stage) {
 - Primary stage procedure (this file): \`.cclaw/skills/${schema.skillFolder}/SKILL.md\`
 - Orchestrator contract (gate language and handoff): \`.cclaw/commands/${stage}.md\`
 - Artifact structure baseline: \`.cclaw/templates/${schema.artifactFile}\`
-- Runtime state truth source: \`.cclaw/state/flow-state.json\` + \`.cclaw/runs/<activeRunId>/\`
+- Runtime state truth source: \`.cclaw/state/flow-state.json\` + \`.cclaw/artifacts/\` + \`.cclaw/knowledge.md\`
 
 ### See also
 - Meta routing and activation rules: \`.cclaw/skills/using-cclaw/SKILL.md\`
@@ -287,7 +280,7 @@ function quickStartBlock(stage) {
 
 > **Even if you read nothing else, do these 3 things:**
 > 1. Obey the HARD-GATE below — violating it invalidates the entire stage.
-> 2. Complete every checklist step in order and write the artifact to \`.cclaw/artifacts/${schema.artifactFile}\`. Run snapshots in \`.cclaw/runs/<activeRunId>/artifacts/\` are synchronized by cclaw runtime.
+> 2. Complete every checklist step in order and write the artifact to \`.cclaw/artifacts/${schema.artifactFile}\`.
 > 3. Do not claim completion without satisfying gates: ${topGates}${schema.requiredGates.length > 3 ? ` (+${schema.requiredGates.length - 3} more)` : ""}.
 >
 > **After this stage:** update \`flow-state.json\` and tell the user to run \`/cc-next\`.
@@ -385,7 +378,7 @@ ${progressiveDisclosureBlock(stage)}
 ${selfImprovementBlock(stage)}
 ## Handoff
 - Next command: \`/cc-next\` (loads whatever stage is current in flow-state)
-- Required artifact: \`.cclaw/artifacts/${schema.artifactFile}\` (run snapshot at \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`, synchronized by cclaw runtime)
+- Required artifact: \`.cclaw/artifacts/${schema.artifactFile}\`
 - Stage stays blocked if any required gate is unsatisfied
 `;
 }

package/dist/content/stage-schema.js

@@ -22,185 +22,141 @@ const BRAINSTORM = {
     stage: "brainstorm",
     skillFolder: "brainstorming",
     skillName: "brainstorming",
-    skillDescription: "Design-first stage. Clarify intent, compare options, and get explicit approval before implementation planning.",
-    hardGate: "Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.",
-    purpose: "Turn a rough request into an approved design direction with clear assumptions and boundaries.",
+    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.",
+    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 solution path is unclear",
-        "Before any implementation-stage command"
+        "Requirements are ambiguous or trade-offs are unclear",
+        "Before any implementation-stage command or architecture commitment"
     ],
     whenNotToUse: [
-        "An approved design, spec, and plan already exist and work is in execution stages",
-        "The request is strictly branch finalization or release handoff work",
-        "The task is purely retrospective after ship with no new design decisions needed"
+        "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, existing behavior. Summarize what you found (even for seemingly simple projects).",
-        "Assess scope — if the request describes multiple independent subsystems, flag for decomposition before detailed questions.",
-        "Restate the problem — in a SEPARATE message (no questions in this message), summarize what you understood the user wants and why. The restatement message must contain zero clarifying questions and no option prompts. **STOP and wait** for user to confirm or correct before asking any clarifying questions.",
-        "Ask clarifying questions — one at a time, one per message. Each clarification message must ask exactly one decision-seeking question (no bundled sub-questions). You MUST cover these categories before proposing approaches: (a) PURPOSE — why this project exists, who it serves; (b) SCOPE — what it must do, what it must NOT do; (c) BOUNDARIES — error handling, edge cases, failure modes; (d) ENVIRONMENT — how it runs, deploys, installs; (e) CONSTRAINTS — performance, compatibility, dependencies. Skip a category only if the user already provided that info. If user answers 'I don't know' / 'не знаю', convert it into explicit assumptions and ask for confirmation before moving on. Do NOT rush — 3 generic questions are never enough for a non-trivial project.",
-        "Before proposing approaches, perform at least one premise-challenge question (\"Is this the right problem framing?\") and at least one boundary stress-test question (\"What should never happen even on failure?\").",
-        "Propose 2-3 approaches — with real trade-offs (not cosmetic differences) and your explicit recommendation with reasoning. Explain WHY you recommend this option over others.",
-        "Present design — in sections. After each section, explicitly state what you are asking the user to approve: 'Do you approve [specific thing]?' Never ask a bare 'одобряете?/approve?' without context.",
-        "Write design doc — save to `.cclaw/artifacts/01-brainstorm.md`.",
-        "Self-review — scan for placeholders, TBDs, contradictions, ambiguity, scope creep. Fix inline.",
-        "User reviews written artifact — ask user to review the written artifact (not the chat summary). **STOP.** Do NOT proceed until user responds.",
-        "Stage complete — update `flow-state.json` per the Stage Completion Protocol. Tell user to run `/cc-next` to continue to scope."
+        "**Explore project context** — check files, docs, recent commits to understand what already exists.",
+        "**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.",
+        "**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 your recommendation. Lead with the recommended option and explain why.",
+        "**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.",
+        "**Write artifact** to `.cclaw/artifacts/01-brainstorm.md`.",
+        "**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 context first (files, docs, existing behavior). Share a brief summary of what you found.",
-        "Restate the problem in your own words in a SEPARATE message. Do NOT add any questions, options, or approval asks to this message. Wait for user to confirm or correct.",
-        "Ask clarifying questions — one per message. Cover mandatory categories: PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, CONSTRAINTS. Do NOT combine questions. Do NOT propose approaches until all categories are addressed.",
-        "Do not package multiple asks as bullet points in one message; split them into separate turns even if related.",
-        "When user answer is ambiguous or unknown (for example: 'не знаю'), propose explicit defaults as assumptions and get a one-message confirmation before treating that category as closed.",
-        "Include at least one premise-challenge and one boundary stress-test question before locking options. Do not accept 'simple demo' framing without challenge.",
-        "For approach selection: use the Decision Protocol — present labeled options (A/B/C) with REAL trade-offs (not cosmetic) and mark one as (recommended) with clear reasoning. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
-        "Every approval question MUST state what exactly is being approved: 'Do you approve [the architecture / the API shape / the dependency choice]?' Never ask a bare 'approve?' or 'looks good?'.",
-        "Get section-by-section approval before finalizing the design direction.",
-        "Run a self-review pass (ambiguity, placeholders, contradictions) before handoff.",
-        "**STOP.** Wait for explicit user approval after writing the artifact. Do NOT auto-advance to the next stage."
+        "Explore what exists before asking what to build — check project files first.",
+        "Ask exactly one question per turn. Prefer multiple choice. No bundled questions.",
+        "Each question should change a concrete design decision. If a question only gathers trivia, skip 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, lead with your recommendation and explain why.",
+        "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 — files, docs, behavior, recent changes. Share findings.",
-        "Restate the problem — summarize what the user wants and why in a SEPARATE message. Keep this message declarative only; no questions. Wait for confirmation before questions.",
-        "Clarify iteratively — ask questions one at a time covering mandatory categories: PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, CONSTRAINTS. Do not skip to approaches early.",
-        "Convert unknown answers into explicit assumptions and confirm them before approaches.",
-        "Identify whether request should be decomposed into smaller sub-problems.",
-        "Offer 2-3 alternatives with real trade-offs and recommendation with rationale.",
-        "Present design in sections. After each section explicitly name what you ask the user to approve.",
-        "Write artifact to `.cclaw/artifacts/01-brainstorm.md`.",
-        "Run self-review: placeholder scan, internal consistency, scope check, ambiguity check.",
-        "Ask user to review the written artifact. Wait for changes or approval.",
-        "Handoff to scope stage only after approval is explicit."
+        "Explore project context: check files, docs, recent activity.",
+        "Assess scope: flag if request is too broad, help decompose first.",
+        "Ask clarifying questions one at a time — focus on purpose, constraints, success criteria.",
+        "Propose 2-3 architecturally distinct approaches with trade-offs and a recommendation.",
+        "Present design sections incrementally, get approval after each.",
+        "Write approved direction to `.cclaw/artifacts/01-brainstorm.md`.",
+        "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_discovery_purpose", description: "Discovery captured WHY this project exists and WHO it serves, with explicit user confirmation." },
-        { id: "brainstorm_discovery_scope", description: "Discovery captured explicit in-scope and out-of-scope boundaries before approach selection." },
-        { id: "brainstorm_discovery_boundaries", description: "Discovery captured failure modes, edge cases, and error-handling boundaries." },
-        { id: "brainstorm_discovery_environment", description: "Discovery captured runtime/install/deployment environment assumptions." },
-        { id: "brainstorm_discovery_constraints", description: "Discovery captured constraints (performance, compatibility, dependency limits) before deciding architecture." },
-        {
-            id: "brainstorm_problem_restated",
-            description: "Problem was restated in agent's words in a standalone non-question message, and user confirmed the understanding."
-        },
-        { id: "brainstorm_options_compared", description: "At least two alternatives were compared with real trade-offs." },
-        { id: "brainstorm_design_approved", description: "User approved a concrete design direction (with explicit statement of what was approved)." },
-        { id: "brainstorm_self_review_passed", description: "Design doc passed placeholder/ambiguity/consistency checks." },
-        { id: "brainstorm_user_reviewed_artifact", description: "User reviewed the written artifact and confirmed readiness." }
+        { id: "brainstorm_context_explored", description: "Project context (files, docs, existing patterns) was checked before asking questions." },
+        { id: "brainstorm_idea_understood", description: "Agent and user share the same understanding of the problem, constraints, and success criteria." },
+        { 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`.",
-        "Clarification log explicitly records PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, and CONSTRAINTS coverage.",
-        "Clarification sequence evidence shows one explicit question per message (no bundled multi-question turns).",
-        "Clarification log includes at least one premise-challenge question and one boundary stress-test question before approach selection.",
-        "Unknown or ambiguous user answers are converted into explicit assumptions and confirmed (or explicitly waived) before closure.",
-        "Discovery sections include explicit in-scope/out-of-scope boundaries and failure handling boundaries.",
-        "Approved direction captured in artifact.",
-        "Restatement evidence shows a standalone non-question restatement message before clarification Q&A.",
-        "Open questions explicitly listed (if any).",
-        "Self-review pass completed with no unresolved issues."
+        "Project context was explored (files, docs, or recent activity referenced).",
+        "Clarifying questions and their answers are captured.",
+        "2-3 approaches with trade-offs and recommendation are recorded.",
+        "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 docs and patterns",
+        "existing project context and patterns",
         "current behavior of affected area",
         "business and delivery constraints"
     ],
     outputs: [
         "approved design direction",
-        "alternatives and trade-off table",
+        "alternatives with trade-offs",
         "brainstorm artifact"
     ],
     blockers: [
         "no explicit approval",
         "critical ambiguity unresolved",
-        "scope too broad and not decomposed"
+        "project context not explored"
     ],
     exitCriteria: [
         "approved design direction documented",
         "required gates marked satisfied",
         "no implementation action taken",
-        "self-review completed with fixes applied"
+        "artifact reviewed by user"
     ],
     antiPatterns: [
-        "Skipping design because task seems simple",
-        "Asking many questions in one message",
+        "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",
         "Jumping directly into implementation",
-        "Combining visual companion offer with a clarifying question",
-        "Invoking implementation skills before writing plans",
-        "Appending clarifying questions to the restatement message instead of waiting for confirmation",
-        "Packing multiple clarifying questions into one message (including bullet-list question bundles)",
-        "Silently filling defaults after 'не знаю'/'I don't know' without explicit assumption confirmation",
-        "Accepting 'simple/test/demo' framing without premise challenge or failure stress testing",
-        "Asking bare 'approve?' or 'одобряете?' without stating WHAT is being approved",
-        "Presenting a single summary and asking for blanket approval instead of section-by-section review",
-        "Rushing through clarification — asking 1-2 generic questions then jumping to design",
-        "Batching multiple gate confirmations in one message when resuming a session"
+        "Requesting approval without stating what decision is being approved"
     ],
     rationalizations: [
-        { claim: "This is too simple for design.", reality: "Simple tasks fail fast when assumptions are wrong; a short design pass prevents rework." },
-        { claim: "We can figure it out while coding.", reality: "Coding before alignment creates churn and hidden scope growth." },
-        { claim: "There is only one obvious approach.", reality: "Without alternatives, trade-offs stay implicit and risk goes unexamined." },
-        { claim: "The user already knows what they want.", reality: "Unstated assumptions diverge during implementation; explicit design surfaces them early." },
-        { claim: "This is straightforward, 1-2 questions are enough.", reality: "Even simple projects have hidden constraints (error handling, edge cases, deployment). A few extra questions now prevent rework later." }
+        { claim: "I already know what to build, so exploration is unnecessary.", reality: "Checking files and context catches wrong assumptions that waste hours later." },
+        { claim: "Any question is useful context.", reality: "Only questions whose answers change what we build improve the design." },
+        { claim: "Two options that differ only in tooling count as distinct approaches.", reality: "Distinct means different architecture, not different libraries for the same approach." }
     ],
     redFlags: [
-        "No alternatives documented",
-        "No explicit approval checkpoint",
-        "Implementation-related actions before approval",
-        "Self-review skipped or glossed over",
-        "Artifact has TBD or placeholder sections",
-        "Restatement step includes clarifying questions or option prompts",
-        "Clarification turns repeatedly include multi-question bundles instead of single asks",
-        "Unknown user answers are treated as settled requirements without explicit assumption confirmation",
-        "No evidence of premise challenge or failure stress-test questions before options",
-        "Fewer than 3 clarifying questions asked for any non-trivial project",
-        "Approval requested without stating what exactly is being approved"
+        "No project context exploration before questions",
+        "Questions that only gather preferences without design impact",
+        "Options that are variants of one approach, not distinct alternatives",
+        "Approval requested without explicit decision context"
     ],
     policyNeedles: [
-        "Restate problem before questions",
-        "One clarifying question per message",
-        "2-3 approaches with real trade-offs",
+        "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",
     cognitivePatterns: [
-        { name: "Divergent-Convergent Thinking", description: "First expand the solution space widely, then converge on the strongest option. Do not skip the divergent phase." },
-        { name: "YAGNI Ruthlessness", description: "Remove unnecessary features from all designs. Every feature must earn its place against the cost of complexity." },
-        { name: "Decomposition Instinct", description: "When a request describes multiple independent subsystems, decompose before refining. Each sub-project gets its own cycle." },
-        { name: "Isolation Preference", description: "Break the system into units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently." }
+        { name: "Context Before Questions", description: "Understand what exists before asking what to build." },
+        { name: "Depth Matches Complexity", description: "Brief design for simple tasks, thorough exploration for complex ones." },
+        { name: "Diverge Then Commit", description: "Explore multiple architecturally distinct options first, commit only after explicit approval." },
+        { name: "Question Quality Over Quantity", description: "Each question should change what we build, not just gather trivia." }
     ],
     reviewSections: [],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
         readsFrom: [],
         writesTo: [".cclaw/artifacts/01-brainstorm.md"],
-        traceabilityRule: "Every approved direction must be traceable forward through scope and design. Downstream stages must reference brainstorm decisions."
+        traceabilityRule: "Scope and design decisions must trace back to explored context and approved brainstorm direction."
     },
     artifactValidation: [
-        { section: "Problem Statement", required: true, validationRule: "Must describe the user problem, not the solution. Include WHO and WHY and success signal." },
-        { section: "Known Context", required: true, validationRule: "Files, patterns, constraints discovered during exploration. Evidence that context was actually explored." },
-        {
-            section: "Clarification Log",
-            required: true,
-            validationRule: "At least 5 rows covering PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, CONSTRAINTS. Table must use 4 columns: Category, Question asked, User answer, Evidence note."
-        },
-        { section: "Purpose & Beneficiaries", required: true, validationRule: "At least 3 meaningful lines describing why this exists and who benefits." },
-        { section: "Scope Boundaries", required: true, validationRule: "At least 2 scope items including explicit out-of-scope boundaries." },
-        { section: "Failure Boundaries", required: true, validationRule: "At least 2 failure/edge-case expectations and error visibility behavior." },
-        { section: "Runtime Environment", required: true, validationRule: "At least 2 lines describing runtime, install/distribution, and execution environment." },
-        { section: "Constraints", required: true, validationRule: "At least 2 concrete constraints (performance, compatibility, dependency, or policy)." },
-        { section: "Alternatives Table", required: true, validationRule: "At least 2 approaches with real trade-offs (not cosmetic) and recommendation with reasoning." },
-        { section: "Approved Direction", required: true, validationRule: "Must contain explicit approval marker from user. State what was approved." },
-        { section: "Assumptions & Risks", required: true, validationRule: "Explicit assumptions made during design. Known risks. If none, state 'None'." },
-        { section: "Open Questions", required: true, validationRule: "If empty, state 'None' explicitly. Do not omit." }
+        { 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: true, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
+        { section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs and recommendation." },
+        { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, rationale, and explicit approval marker." },
+        { section: "Design", required: true, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
+        { section: "Assumptions and Open Questions", required: true, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }
     ],
     namedAntiPattern: {
         title: "This Is Too Simple To Need A Design",
-        description: "Every project goes through this process. A todo list, a single-function utility, a config change — all of them. 'Simple' projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval."
+        description: "Every project goes through this process. Simple projects are where unexamined assumptions cause the most wasted work. The design can be short, but you MUST present it and get approval."
     }
 };
 // ---------------------------------------------------------------------------

package/dist/content/templates.d.ts

@@ -1,4 +1,4 @@
 export declare const ARTIFACT_TEMPLATES: Record<string, string>;
 export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n- Follow flow order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\n- Require explicit user confirmation after plan before TDD\n- Keep evidence artifacts in `.cclaw/artifacts/`\n- Enforce RED before GREEN in TDD\n- Run two-layer review (spec_compliance and code_quality) before ship\n- Validate all inputs before processing \u2014 never trust external data without sanitization\n- Prefer immutable data patterns and pure functions where the language supports them\n- Follow existing repo conventions, patterns, and directory structure \u2014 match the codebase\n- Verify claims with fresh evidence: \"tests pass\" requires running tests in this message\n- Use conventional commits: `type(scope): description` (feat, fix, refactor, test, docs, chore)\n\n## MUST_NEVER\n- Skip RED phase and jump directly to GREEN in TDD\n- Ship with critical review findings\n- Start implementation during /brainstorm\n- Modify generated cclaw files manually when CLI can regenerate them\n- Commit `.cclaw/` or generated shim files\n- Expose secrets, tokens, API keys, or absolute system paths in agent output\n- Duplicate existing functionality without explicit justification \u2014 search before building\n- Bypass security checks, linting hooks, or type checking to \"move faster\"\n- Claim success (\"Done,\" \"All good,\" \"Tests pass\") without running verification in this message\n- Make changes outside the blast radius of the current task without user consent\n\n## DELEGATION\nWhen a task requires specialist knowledge (security audit, performance profiling, database review),\ndelegate to a specialized agent or skill if the harness supports it. The primary agent should:\n1. Identify the specialist domain\n2. Provide focused context (relevant files, the specific concern)\n3. Evaluate the specialist output before acting on it \u2014 do not blindly apply recommendations\n";
-export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n- Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.\n- Read `.cclaw/state/flow-state.json` before acting; continue from current stage when active.\n- Use `/cc-next` only after required gates pass; never bypass explicit pause/approval rules.\n- Keep evidence in `.cclaw/artifacts/`; cclaw sync/runtime maintains run snapshots in `.cclaw/runs/<activeRunId>/artifacts/`.\n- For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).\n- Treat `.cclaw/skills/using-cclaw/SKILL.md` as routing source of truth; load contextual utility skills only when their triggers apply.\n";
+export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n- Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.\n- Read `.cclaw/state/flow-state.json` before acting; continue from current stage when active.\n- Use `/cc-next` only after required gates pass; never bypass explicit pause/approval rules.\n- Keep evidence in `.cclaw/artifacts/`; archive completed feature artifacts only via `cclaw archive`.\n- For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).\n- Treat `.cclaw/skills/using-cclaw/SKILL.md` as routing source of truth; load contextual utility skills only when their triggers apply.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -3,71 +3,39 @@ import { orderedStageSchemas } from "./stage-schema.js";
 export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `# Brainstorm Artifact
 
-## Problem Statement
-- **User problem:**
-- **Who benefits:**
-- **Why now:**
-- **Success signal:**
-
-## Known Context
-- **Explored files/patterns:**
-- **Existing behavior:**
-- **Relevant dependencies:**
-
-## Clarification Log
-| Category | Question asked | User answer | Evidence note |
-|---|---|---|---|
-| PURPOSE |  |  |  |
-| SCOPE |  |  |  |
-| BOUNDARIES |  |  |  |
-| ENVIRONMENT |  |  |  |
-| CONSTRAINTS |  |  |  |
-
-## Purpose & Beneficiaries
-- **Project purpose:**
-- **Primary users:**
-- **Value outcome:**
-
-## Scope Boundaries
-### In Scope
-- 
+## Context
+- **Project state:**
+- **Relevant existing code/patterns:**
 
-### Out of Scope
-- 
+## Problem
+- **What we're solving:**
+- **Success criteria:**
+- **Constraints:**
 
-## Failure Boundaries
-- **Edge cases to handle:**
-- **Expected failures and behavior:**
-- **Error visibility expectations:**
-
-## Runtime Environment
-- **Runtime/platform:**
-- **Install/distribution model:**
-- **Execution context (local/CI/deploy):**
-
-## Constraints
-- **Performance constraints:**
-- **Compatibility constraints:**
-- **Dependency constraints:**
+## Clarifying Questions
+| # | Question | Answer | Decision impact |
+|---|---|---|---|
+| 1 |  |  |  |
 
-## Alternatives Table
-| Option | Summary | Trade-offs | Recommendation |
+## Approaches
+| Approach | Architecture | Trade-offs | Recommendation |
 |---|---|---|---|
 | A |  |  |  |
 | B |  |  |  |
-| C |  |  |  |
 
-## Approved Direction
-- **Selected option:**
-- **Why selected:**
-- **What was approved:** (state the specific decision)
-- **Approval marker:**
+## Selected Direction
+- **Approach:**
+- **Rationale:**
+- **Approval:** pending
 
-## Assumptions & Risks
-- 
+## Design
+- **Architecture:**
+- **Key components:**
+- **Data flow:**
 
-## Open Questions
-- None
+## Assumptions and Open Questions
+- **Assumptions:**
+- **Open questions (or "None"):**
 `,
     "02-scope.md": `# Scope Artifact
 
@@ -382,7 +350,7 @@ alwaysApply: true
 - Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.
 - Read \`.cclaw/state/flow-state.json\` before acting; continue from current stage when active.
 - Use \`/cc-next\` only after required gates pass; never bypass explicit pause/approval rules.
-- Keep evidence in \`.cclaw/artifacts/\`; cclaw sync/runtime maintains run snapshots in \`.cclaw/runs/<activeRunId>/artifacts/\`.
+- Keep evidence in \`.cclaw/artifacts/\`; archive completed feature artifacts only via \`cclaw archive\`.
 - For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.
 - Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).
 - Treat \`.cclaw/skills/using-cclaw/SKILL.md\` as routing source of truth; load contextual utility skills only when their triggers apply.

package/dist/delegation.js

@@ -4,11 +4,11 @@ import { RUNTIME_ROOT } from "./constants.js";
 import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { readFlowState } from "./runs.js";
 import { stageSchema } from "./content/stage-schema.js";
-function delegationLogPath(projectRoot, runId) {
-    return path.join(projectRoot, RUNTIME_ROOT, "runs", runId, "delegation-log.json");
+function delegationLogPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-log.json");
 }
-function delegationLockPath(projectRoot, runId) {
-    return path.join(projectRoot, RUNTIME_ROOT, "runs", runId, ".delegation.lock");
+function delegationLockPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", ".delegation.lock");
 }
 function isDelegationEntry(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
@@ -45,7 +45,7 @@ function parseLedger(raw, runId) {
 }
 export async function readDelegationLedger(projectRoot) {
     const { activeRunId } = await readFlowState(projectRoot);
-    const filePath = delegationLogPath(projectRoot, activeRunId);
+    const filePath = delegationLogPath(projectRoot);
     if (!(await exists(filePath))) {
         return { runId: activeRunId, entries: [] };
     }
@@ -60,8 +60,8 @@ export async function readDelegationLedger(projectRoot) {
 }
 export async function appendDelegation(projectRoot, entry) {
     const { activeRunId } = await readFlowState(projectRoot);
-    await withDirectoryLock(delegationLockPath(projectRoot, activeRunId), async () => {
-        const filePath = delegationLogPath(projectRoot, activeRunId);
+    await withDirectoryLock(delegationLockPath(projectRoot), async () => {
+        const filePath = delegationLogPath(projectRoot);
         const prior = await readDelegationLedger(projectRoot);
         const ledger = {
             runId: activeRunId,