cclaw-cli 0.46.13 → 0.46.14

package/dist/content/research-playbooks.js

@@ -102,6 +102,42 @@ Summarize citable domain practices for a narrow design decision.
 
 - Cite authoritative sources (official docs/standards).
 - State uncertainty explicitly when consensus is weak.
+`,
+    "research-fleet.md": `# Parallel Research Fleet Playbook
+
+## Purpose
+
+Run a four-lens investigation before design lock so architecture choices are grounded
+in current ecosystem data, not intuition.
+
+## Dispatch Lenses (fan-out)
+
+Launch four independent investigation threads in parallel when the harness supports it
+(or sequentially with explicit role-switch logs when it does not):
+
+1. **stack-researcher** — dependency compatibility, alternatives, deprecations.
+2. **features-researcher** — domain conventions and product/UX patterns.
+3. **architecture-researcher** — architecture options and trade-off matrix.
+4. **pitfalls-researcher** — known failure modes, CVEs, and operational traps.
+
+## Output Contract
+
+Write findings to \`.cclaw/artifacts/02a-research.md\` with these sections:
+
+- \`## Stack Analysis\`
+- \`## Features & Patterns\`
+- \`## Architecture Options\`
+- \`## Pitfalls & Risks\`
+- \`## Synthesis\`
+
+Each section must contain concrete notes and at least one evidence reference
+(source URL, file path, or command output anchor).
+
+## Guardrails
+
+- Investigate first; no production code edits in this playbook.
+- Keep lenses independent during fan-out; merge only in synthesis.
+- If any lens is incomplete, record it explicitly in \`## Synthesis\` as a blocker.
 `,
     "git-history.md": `# Git History Playbook
 

package/dist/content/stage-schema.js

@@ -13,6 +13,7 @@ const REQUIRED_GATE_IDS = {
         "scope_user_approved"
     ],
     design: [
+        "design_research_complete",
         "design_architecture_locked",
         "design_data_flow_mapped",
         "design_failure_modes_mapped",
@@ -53,7 +54,13 @@ const REQUIRED_GATE_IDS = {
 const REQUIRED_ARTIFACT_SECTIONS = {
     brainstorm: ["Context", "Problem", "Approaches", "Selected Direction"],
     scope: ["Scope Mode", "In Scope / Out of Scope", "Completion Dashboard", "Scope Summary"],
-    design: ["Architecture Boundaries", "Architecture Diagram", "Failure Mode Table", "Completion Dashboard"],
+    design: [
+        "Research Fleet Synthesis",
+        "Architecture Boundaries",
+        "Architecture Diagram",
+        "Failure Mode Table",
+        "Completion Dashboard"
+    ],
     spec: ["Acceptance Criteria", "Edge Cases", "Testability Map", "Approval"],
     plan: ["Task List", "Dependency Batches", "Acceptance Mapping", "WAIT_FOR_CONFIRM"],
     tdd: ["RED Evidence", "GREEN Evidence", "REFACTOR Notes", "Traceability", "Verification Ladder"],

package/dist/content/stages/design.js

@@ -21,6 +21,7 @@ export const DESIGN = {
     ],
     checklist: [
         "Trivial-Change Escape Hatch — If scope artifact shows ≤3 files, zero new interfaces, and no cross-module data flow, skip full review sections. Produce a mini-design: one paragraph of rationale, list of changed files, one risk to watch. Proceed to spec.",
+        "Parallel Research Fleet — run `research/research-fleet.md` before architecture lock. Record 4-lens findings in `.cclaw/artifacts/02a-research.md` and summarize resulting decisions in `## Research Fleet Synthesis`.",
         "Design Doc Check — read existing design docs, scope artifact, brainstorm artifact. If a design doc exists that covers this area, check for 'Supersedes:' and use the latest. Use upstream artifacts as source of truth.",
         "Codebase Investigation — Before any design decision, read the actual code in the blast radius. List every file that will be touched, its current responsibilities, and existing patterns (error handling, naming, test style). Design must conform to discovered patterns, not impose new ones without justification.",
         "Step 0: Scope Challenge — what existing code solves sub-problems? Minimum change set? Complexity check: 8+ files or 2+ new services = complexity smell → flag for possible scope reduction.",
@@ -50,6 +51,7 @@ export const DESIGN = {
     ],
     process: [
         "Read upstream artifacts (brainstorm, scope).",
+        "Run the research fleet playbook and write `.cclaw/artifacts/02a-research.md` before locking architecture choices.",
         "Investigate codebase: read files in blast radius, catalogue current patterns and responsibilities.",
         "Run Step 0 scope challenge: existing code leverage, minimum change set, complexity check.",
         "Walk through each review section interactively.",
@@ -62,12 +64,14 @@ export const DESIGN = {
         "Write design lock artifact for downstream spec/plan."
     ],
     requiredGates: [
+        { id: "design_research_complete", description: "Parallel research artifact is complete and synthesized into design decisions." },
         { id: "design_architecture_locked", description: "Architecture boundaries are explicit and approved." },
         { id: "design_data_flow_mapped", description: "Data/state flow includes edge-case paths." },
         { id: "design_failure_modes_mapped", description: "Failure modes and mitigations are documented." },
         { id: "design_test_and_perf_defined", description: "Test strategy and performance budget are defined." }
     ],
     requiredEvidence: [
+        "Research artifact written to `.cclaw/artifacts/02a-research.md` with stack/features/architecture/pitfalls sections plus synthesis.",
         "Artifact written to `.cclaw/artifacts/03-design.md`.",
         "Failure-mode table exists with mitigations.",
         "Test strategy includes unit/integration/e2e expectations.",
@@ -77,15 +81,18 @@ export const DESIGN = {
     ],
     inputs: ["scope contract", "system constraints", "non-functional requirements"],
     requiredContext: [
+        "parallel research synthesis from `.cclaw/artifacts/02a-research.md`",
         "existing architecture and boundaries",
         "operational constraints",
         "security and reliability expectations"
     ],
     researchPlaybooks: [
+        "research/research-fleet.md",
         "research/framework-docs-lookup.md",
         "research/best-practices-lookup.md"
     ],
     outputs: [
+        "parallel research synthesis artifact",
         "architecture lock",
         "risk and failure map",
         "test and performance baseline",
@@ -110,17 +117,14 @@ export const DESIGN = {
         "Missing data-flow edge cases",
         "No performance budget for critical path",
         "Batching multiple design issues into one question",
-        "Skipping review sections because plan seems simple",
         "Agreeing with user's architecture choice without evaluating alternatives",
         "Hedging every recommendation with 'it depends' instead of taking a position",
-        "No explicit architecture boundary section",
-        "No failure recovery strategy",
-        "No defined test/perf baseline",
         "No NOT-in-scope output section",
         "No What-already-exists output section",
         "Design decisions made without reading the actual code first"
     ],
     policyNeedles: [
+        "Parallel Research Fleet",
         "Architecture",
         "Data Flow",
         "Failure Modes and Mitigation",
@@ -186,11 +190,16 @@ export const DESIGN = {
     ],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
-        readsFrom: [".cclaw/artifacts/01-brainstorm.md", ".cclaw/artifacts/02-scope.md"],
+        readsFrom: [
+            ".cclaw/artifacts/01-brainstorm.md",
+            ".cclaw/artifacts/02-scope.md",
+            ".cclaw/artifacts/02a-research.md"
+        ],
         writesTo: [".cclaw/artifacts/03-design.md"],
         traceabilityRule: "Every architecture decision must trace to a scope boundary. Every downstream spec requirement must trace to a design decision."
     },
     artifactValidation: [
+        { section: "Research Fleet Synthesis", required: true, validationRule: "Must summarize all four lenses (stack/features/architecture/pitfalls) and map findings to concrete design decisions." },
         { section: "Codebase Investigation", required: false, validationRule: "Must list blast-radius files with current responsibilities and discovered patterns." },
         { section: "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." },

package/dist/content/templates.js

@@ -152,6 +152,47 @@ inputs_hash: sha256:pending
 - Deferred:
 - Explicitly excluded:
 
+## Learnings
+- None this stage.
+`,
+    "02a-research.md": `---
+stage: design
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Research Report
+
+## Stack Analysis
+| Topic | Finding | Evidence |
+|---|---|---|
+| Dependency compatibility |  |  |
+| Alternatives/deprecations |  |  |
+
+## Features & Patterns
+| Topic | Finding | Evidence |
+|---|---|---|
+| Domain conventions |  |  |
+| UX/product patterns |  |  |
+
+## Architecture Options
+| Option | Trade-offs | Recommendation | Evidence |
+|---|---|---|---|
+| A |  |  |  |
+| B |  |  |  |
+
+## Pitfalls & Risks
+| Risk | Impact | Mitigation | Evidence |
+|---|---|---|---|
+|  |  |  |  |
+
+## Synthesis
+- Key decisions informed by research:
+- Open questions:
+
 ## Learnings
 - None this stage.
 `,
@@ -178,6 +219,14 @@ inputs_hash: sha256:pending
 | Layer 2 |  |  |
 | Layer 3 |  |  |
 
+## Research Fleet Synthesis
+| Lens | Key findings | Design impact | Evidence |
+|---|---|---|---|
+| stack-researcher |  |  |  |
+| features-researcher |  |  |  |
+| architecture-researcher |  |  |  |
+| pitfalls-researcher |  |  |  |
+
 ## Architecture Boundaries
 | Component | Responsibility | Owner |
 |---|---|---|

package/dist/gate-evidence.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { checkReviewVerdictConsistency, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import { checkReviewVerdictConsistency, extractMarkdownSectionBody, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
 import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
@@ -26,6 +26,23 @@ async function currentStageArtifactExists(projectRoot, stage, track) {
         return false;
     }
 }
+async function readArtifactMarkdown(projectRoot, artifactFile) {
+    const candidates = [
+        path.join(projectRoot, RUNTIME_ROOT, "artifacts", artifactFile),
+        path.join(projectRoot, artifactFile)
+    ];
+    for (const candidate of candidates) {
+        if (!(await exists(candidate)))
+            continue;
+        try {
+            return await fs.readFile(candidate, "utf8");
+        }
+        catch {
+            // Try next location.
+        }
+    }
+    return null;
+}
 function unique(values) {
     return [...new Set(values)];
 }
@@ -36,6 +53,13 @@ function sameStringArray(a, b) {
 }
 const RECONCILIATION_NOTICES_FILE = "reconciliation-notices.json";
 const RECONCILIATION_NOTICES_SCHEMA_VERSION = 1;
+const DESIGN_RESEARCH_REQUIRED_SECTIONS = [
+    "Stack Analysis",
+    "Features & Patterns",
+    "Architecture Options",
+    "Pitfalls & Risks",
+    "Synthesis"
+];
 export const RECONCILIATION_NOTICES_REL_PATH = `${RUNTIME_ROOT}/state/${RECONCILIATION_NOTICES_FILE}`;
 function isFlowStageValue(value) {
     return typeof value === "string" && FLOW_STAGES.includes(value);
@@ -222,6 +246,37 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                 }
             }
         }
+        if (stage === "design") {
+            const researchGateRequired = schema.requiredGates.some((gate) => gate.id === "design_research_complete" && gate.tier === "required");
+            if (researchGateRequired) {
+                const researchMarkdown = await readArtifactMarkdown(projectRoot, "02a-research.md");
+                if (!researchMarkdown) {
+                    issues.push("design research gate blocked (design_research_complete): missing `.cclaw/artifacts/02a-research.md`.");
+                }
+                else {
+                    const missingSections = [];
+                    for (const section of DESIGN_RESEARCH_REQUIRED_SECTIONS) {
+                        const body = extractMarkdownSectionBody(researchMarkdown, section);
+                        if (body === null) {
+                            missingSections.push(section);
+                            continue;
+                        }
+                        const meaningfulLines = body
+                            .split(/\r?\n/gu)
+                            .map((line) => line.trim())
+                            .filter((line) => line.length > 0)
+                            .filter((line) => !/^\|?(?:[-:\s|])+$/u.test(line));
+                        const nonPlaceholder = meaningfulLines.filter((line) => !/\b(?:TODO|TBD|FIXME|pending|<fill-in>)\b/iu.test(line));
+                        if (nonPlaceholder.length === 0) {
+                            missingSections.push(`${section} (empty or placeholder)`);
+                        }
+                    }
+                    if (missingSections.length > 0) {
+                        issues.push(`design research gate blocked (design_research_complete): ${missingSections.join(", ")}.`);
+                    }
+                }
+            }
+        }
     }
     const passedSet = new Set(catalog.passed);
     const missingRequired = required.filter((gateId) => !passedSet.has(gateId));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.46.13",
+  "version": "0.46.14",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {