cclaw-cli 0.46.12 → 0.46.14

package/dist/content/next-command.js

@@ -9,6 +9,9 @@ function flowStatePath() {
 function delegationLogPathLine() {
     return `${RUNTIME_ROOT}/state/delegation-log.json`;
 }
+function reconciliationNoticesPathLine() {
+    return `${RUNTIME_ROOT}/state/reconciliation-notices.json`;
+}
 /**
  * Command contract for /cc-next — the primary progression command.
  * Reads flow-state, starts the current stage if unfinished, or advances if all gates pass.
@@ -17,6 +20,7 @@ export function nextCommandContract() {
     const flowPath = flowStatePath();
     const skillRel = `${RUNTIME_ROOT}/skills/${NEXT_SKILL_FOLDER}/SKILL.md`;
     const delegationPath = delegationLogPathLine();
+    const reconciliationNoticesPath = reconciliationNoticesPathLine();
     return `# /cc-next
 
 ## Purpose
@@ -40,13 +44,14 @@ This is the only progression command the user needs to drive the entire flow. St
 1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing).
 2. Parse JSON. Capture \`currentStage\` and \`stageGateCatalog[currentStage]\`.
 3. If \`staleStages[currentStage]\` exists, do not advance automatically. Re-run the stage artifact work, then clear the marker with \`/cc-ops rewind --ack <currentStage>\`.
-4. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
-5. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
-6. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
-7. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
-8. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if each mandatory agent is **completed** or **waived**.
-9. If any mandatory delegation is missing and no waiver exists: **STOP** and ask the user whether to dispatch now or waive with rationale. Do not mark gates passed while delegation is unresolved.
-10. If \`currentStage === "review"\` and \`catalog.blocked\` includes \`review_criticals_resolved\`, treat this as a hard remediation branch: recommend \`/cc-ops rewind tdd "review_blocked_by_critical"\` with the blocking finding IDs, and do not attempt to advance toward ship.
+4. Read **\`${reconciliationNoticesPath}\`** when present. If it contains entries for \`activeRunId + currentStage\` and the listed gate is still blocked in \`stageGateCatalog[currentStage].blocked\`, emit a structured warning before any stage-advance decision.
+5. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
+6. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
+7. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
+8. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
+9. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if each mandatory agent is **completed** or **waived**.
+10. If any mandatory delegation is missing and no waiver exists: **STOP** and ask the user whether to dispatch now or waive with rationale. Do not mark gates passed while delegation is unresolved.
+11. If \`currentStage === "review"\` and \`catalog.blocked\` includes \`review_criticals_resolved\`, treat this as a hard remediation branch: recommend \`/cc-ops rewind tdd "review_blocked_by_critical"\` with the blocking finding IDs, and do not attempt to advance toward ship.
 
 ### Path A: Current stage is NOT complete (any gate unmet or delegation missing)
 
@@ -107,6 +112,7 @@ This is the only progression command the user needs to drive the entire flow. St
 export function nextCommandSkillMarkdown() {
     const flowPath = flowStatePath();
     const delegationPath = delegationLogPathLine();
+    const reconciliationNoticesPath = reconciliationNoticesPathLine();
     const stageRows = ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"]
         .map((stage) => {
         const schema = stageSchema(stage);
@@ -146,6 +152,7 @@ Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (p
 2. Record \`currentStage\` and \`stageGateCatalog[currentStage]\`.
 3. If \`staleStages[currentStage]\` exists, re-run the stage and clear marker via \`/cc-ops rewind --ack <currentStage>\` before advancing.
 4. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
+5. Read \`${reconciliationNoticesPath}\` when present. For entries matching \`activeRunId + currentStage\` whose gate is still in \`stageGateCatalog[currentStage].blocked\`, show a warning with gate id + reason before proceeding.
 
 ### Step 2: Evaluate gates
 
@@ -157,6 +164,8 @@ Check \`mandatoryDelegations\` via **\`${delegationPath}\`** — satisfied only
 If a mandatory delegation is missing and no waiver exists, **STOP** and ask:
 (A) dispatch now, (B) waive with rationale, (C) cancel stage advance.
 
+If reconciliation warnings were emitted in Step 1, treat them as a pre-advance stop point: require explicit acknowledgement before continuing Path A or Path B.
+
 ### Step 3: Act
 
 **Path A — stage NOT complete (any gate unmet):**

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/doctor.js

@@ -16,7 +16,7 @@ import { TRACK_STAGES } from "./types.js";
 import { checkMandatoryDelegations } from "./delegation.js";
 import { ensureFeatureSystem, listFeatures, readActiveFeature, readFeatureWorktreeRegistry, resolveFeatureWorkspacePath, worktreeRegistryPath } from "./feature-system.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
-import { reconcileAndWriteCurrentStageGateCatalog, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
+import { classifyReconciliationNotices, reconcileAndWriteCurrentStageGateCatalog, readReconciliationNotices, RECONCILIATION_NOTICES_REL_PATH, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
 import { stageSkillFolder } from "./content/skills.js";
 import { doctorCheckMetadata } from "./doctor-registry.js";
@@ -1249,6 +1249,23 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: activeRunId.length > 0,
         details: `${RUNTIME_ROOT}/state/flow-state.json must include activeRunId`
     });
+    const reconciliationNotices = await readReconciliationNotices(projectRoot);
+    const noticeBuckets = classifyReconciliationNotices(flowState, reconciliationNotices.notices);
+    const formatNoticeList = (items) => items
+        .slice(0, 8)
+        .map((notice) => `${notice.stage}.${notice.gateId}`)
+        .join(", ");
+    checks.push({
+        name: "state:reconciliation_notices",
+        ok: noticeBuckets.unsynced.length === 0,
+        details: noticeBuckets.unsynced.length > 0
+            ? `reconciliation notices out of sync in ${RECONCILIATION_NOTICES_REL_PATH}: ${formatNoticeList(noticeBuckets.unsynced)}. Run \`cclaw doctor --reconcile-gates\` to resync and clear stale entries.`
+            : noticeBuckets.currentStageBlocked.length > 0
+                ? `active reconciliation notices for current stage "${flowState.currentStage}": ${formatNoticeList(noticeBuckets.currentStageBlocked)}`
+                : noticeBuckets.activeBlocked.length > 0
+                    ? `active reconciliation notices for run "${flowState.activeRunId}": ${formatNoticeList(noticeBuckets.activeBlocked)}`
+                    : `no active reconciliation notices in ${RECONCILIATION_NOTICES_REL_PATH}`
+    });
     const activeTrack = flowState.track ?? "standard";
     const trackStageList = TRACK_STAGES[activeTrack];
     const skippedFromState = Array.isArray(flowState.skippedStages) ? flowState.skippedStages : [];

package/dist/gate-evidence.d.ts

@@ -1,5 +1,5 @@
 import type { FlowState, StageGateState } from "./flow-state.js";
-import type { FlowStage } from "./types.js";
+import { type FlowStage } from "./types.js";
 export interface GateEvidenceCheckResult {
     ok: boolean;
     stage: FlowStage;
@@ -29,6 +29,27 @@ export interface CompletedStagesClosureResult {
         blocked: string[];
     }>;
 }
+export declare const RECONCILIATION_NOTICES_REL_PATH = ".cclaw/state/reconciliation-notices.json";
+export interface ReconciliationNotice {
+    id: string;
+    runId: string;
+    stage: FlowStage;
+    gateId: string;
+    reason: string;
+    demotedAt: string;
+}
+export interface ReconciliationNoticesPayload {
+    schemaVersion: number;
+    notices: ReconciliationNotice[];
+}
+export interface ReconciliationNoticeBuckets {
+    activeBlocked: ReconciliationNotice[];
+    currentStageBlocked: ReconciliationNotice[];
+    unsynced: ReconciliationNotice[];
+    staleRun: ReconciliationNotice[];
+}
+export declare function readReconciliationNotices(projectRoot: string): Promise<ReconciliationNoticesPayload>;
+export declare function classifyReconciliationNotices(flowState: FlowState, notices: ReconciliationNotice[]): ReconciliationNoticeBuckets;
 export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState): Promise<GateEvidenceCheckResult>;
 export declare function verifyCompletedStagesGateClosure(flowState: FlowState): CompletedStagesClosureResult;
 export interface GateReconciliationResult {
@@ -36,6 +57,7 @@ export interface GateReconciliationResult {
     changed: boolean;
     before: StageGateState;
     after: StageGateState;
+    demotedGateIds: string[];
     notes: string[];
 }
 export interface GateReconciliationWritebackResult extends GateReconciliationResult {

package/dist/gate-evidence.js

@@ -1,11 +1,12 @@
 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 { exists } from "./fs-utils.js";
+import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { readFlowState, writeFlowState } from "./runs.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
+import { FLOW_STAGES } from "./types.js";
 async function currentStageArtifactExists(projectRoot, stage, track) {
     const artifactFile = stageSchema(stage, track).artifactFile;
     const candidates = [
@@ -25,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)];
 }
@@ -33,6 +51,102 @@ function sameStringArray(a, b) {
         return false;
     return a.every((value, index) => value === b[index]);
 }
+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);
+}
+function reconciliationNoticesPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", RECONCILIATION_NOTICES_FILE);
+}
+function defaultReconciliationNoticesPayload() {
+    return {
+        schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
+        notices: []
+    };
+}
+function sanitizeReconciliationNotice(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return null;
+    }
+    const typed = raw;
+    if (typeof typed.id !== "string" ||
+        typeof typed.runId !== "string" ||
+        !isFlowStageValue(typed.stage) ||
+        typeof typed.gateId !== "string" ||
+        typeof typed.reason !== "string" ||
+        typeof typed.demotedAt !== "string") {
+        return null;
+    }
+    return {
+        id: typed.id,
+        runId: typed.runId,
+        stage: typed.stage,
+        gateId: typed.gateId,
+        reason: typed.reason,
+        demotedAt: typed.demotedAt
+    };
+}
+export async function readReconciliationNotices(projectRoot) {
+    const filePath = reconciliationNoticesPath(projectRoot);
+    if (!(await exists(filePath))) {
+        return defaultReconciliationNoticesPayload();
+    }
+    try {
+        const raw = JSON.parse(await fs.readFile(filePath, "utf8"));
+        const notices = Array.isArray(raw.notices)
+            ? raw.notices
+                .map((value) => sanitizeReconciliationNotice(value))
+                .filter((value) => value !== null)
+            : [];
+        return {
+            schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
+            notices
+        };
+    }
+    catch {
+        return defaultReconciliationNoticesPayload();
+    }
+}
+async function writeReconciliationNotices(projectRoot, payload) {
+    const filePath = reconciliationNoticesPath(projectRoot);
+    await ensureDir(path.dirname(filePath));
+    await writeFileSafe(filePath, `${JSON.stringify({
+        schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
+        notices: payload.notices
+    }, null, 2)}\n`);
+}
+export function classifyReconciliationNotices(flowState, notices) {
+    const activeBlocked = [];
+    const currentStageBlocked = [];
+    const unsynced = [];
+    const staleRun = [];
+    for (const notice of notices) {
+        if (notice.runId !== flowState.activeRunId) {
+            staleRun.push(notice);
+            continue;
+        }
+        const stageCatalog = flowState.stageGateCatalog[notice.stage];
+        const blocked = stageCatalog.blocked.includes(notice.gateId);
+        if (!blocked) {
+            unsynced.push(notice);
+            continue;
+        }
+        activeBlocked.push(notice);
+        if (notice.stage === flowState.currentStage) {
+            currentStageBlocked.push(notice);
+        }
+    }
+    return { activeBlocked, currentStageBlocked, unsynced, staleRun };
+}
 export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
     const stage = flowState.currentStage;
     const schema = stageSchema(stage, flowState.track);
@@ -132,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));
@@ -208,6 +353,7 @@ export function reconcileCurrentStageGateCatalog(flowState) {
     const allowedSet = new Set([...required, ...recommended]);
     const catalog = flowState.stageGateCatalog[stage];
     const notes = [];
+    const demotedGateIds = new Set();
     const before = {
         required: [...catalog.required],
         recommended: [...catalog.recommended],
@@ -248,6 +394,7 @@ export function reconcileCurrentStageGateCatalog(flowState) {
             continue;
         }
         passedSet.delete(gateId);
+        demotedGateIds.add(gateId);
         notes.push(`resolved overlap for "${gateId}" in favor of blocked (missing evidence)`);
     }
     for (const gateId of [...passedSet]) {
@@ -256,6 +403,7 @@ export function reconcileCurrentStageGateCatalog(flowState) {
             continue;
         passedSet.delete(gateId);
         blockedSet.add(gateId);
+        demotedGateIds.add(gateId);
         notes.push(`moved "${gateId}" from passed to blocked (missing evidence)`);
     }
     const after = {
@@ -288,6 +436,7 @@ export function reconcileCurrentStageGateCatalog(flowState) {
             changed,
             before,
             after,
+            demotedGateIds: [...required, ...recommended].filter((gateId) => demotedGateIds.has(gateId)),
             notes
         }
     };
@@ -295,8 +444,46 @@ export function reconcileCurrentStageGateCatalog(flowState) {
 export async function reconcileAndWriteCurrentStageGateCatalog(projectRoot) {
     const state = await readFlowState(projectRoot);
     const { nextState, reconciliation } = reconcileCurrentStageGateCatalog(state);
+    const effectiveState = reconciliation.changed ? nextState : state;
     if (reconciliation.changed) {
-        await writeFlowState(projectRoot, nextState);
+        await writeFlowState(projectRoot, effectiveState);
+    }
+    const noticesPayload = await readReconciliationNotices(projectRoot);
+    let noticesChanged = false;
+    const noticeBuckets = classifyReconciliationNotices(effectiveState, noticesPayload.notices);
+    if (noticeBuckets.unsynced.length > 0 || noticeBuckets.staleRun.length > 0) {
+        const dropIds = new Set([...noticeBuckets.unsynced, ...noticeBuckets.staleRun].map((notice) => notice.id));
+        noticesPayload.notices = noticesPayload.notices.filter((notice) => !dropIds.has(notice.id));
+        noticesChanged = true;
+    }
+    if (reconciliation.demotedGateIds.length > 0) {
+        const existing = new Set(noticesPayload.notices.map((notice) => `${notice.runId}:${notice.stage}:${notice.gateId}`));
+        for (const gateId of reconciliation.demotedGateIds) {
+            const dedupeKey = `${effectiveState.activeRunId}:${reconciliation.stage}:${gateId}`;
+            if (existing.has(dedupeKey)) {
+                continue;
+            }
+            const ts = new Date().toISOString();
+            noticesPayload.notices.push({
+                id: `${dedupeKey}:${ts}`,
+                runId: effectiveState.activeRunId,
+                stage: reconciliation.stage,
+                gateId,
+                reason: "demoted from passed to blocked during gate reconciliation (missing evidence)",
+                demotedAt: ts
+            });
+            existing.add(dedupeKey);
+            noticesChanged = true;
+        }
+    }
+    if (noticesChanged) {
+        noticesPayload.notices.sort((a, b) => {
+            if (a.demotedAt === b.demotedAt) {
+                return a.id.localeCompare(b.id);
+            }
+            return a.demotedAt.localeCompare(b.demotedAt);
+        });
+        await writeReconciliationNotices(projectRoot, noticesPayload);
     }
     return {
         ...reconciliation,

package/dist/install.js

@@ -887,6 +887,10 @@ async function ensureSessionStateFiles(projectRoot) {
     if (!(await exists(tddCycleLogPath))) {
         await writeFileSafe(tddCycleLogPath, "");
     }
+    const reconciliationNoticesPath = path.join(stateDir, "reconciliation-notices.json");
+    if (!(await exists(reconciliationNoticesPath))) {
+        await writeFileSafe(reconciliationNoticesPath, `${JSON.stringify({ schemaVersion: 1, notices: [] }, null, 2)}\n`);
+    }
     const flowSnapshotPath = path.join(stateDir, "flow-state.snapshot.json");
     if (!(await exists(flowSnapshotPath))) {
         await writeFileSafe(flowSnapshotPath, `${JSON.stringify({

package/dist/run-archive.js

@@ -16,6 +16,7 @@ const STATE_SNAPSHOT_EXCLUDE = new Set([
 ]);
 const DELEGATION_LOG_FILE = "delegation-log.json";
 const TDD_CYCLE_LOG_FILE = "tdd-cycle-log.jsonl";
+const RECONCILIATION_NOTICES_FILE = "reconciliation-notices.json";
 function runsRoot(projectRoot) {
     return path.join(projectRoot, RUNS_DIR_REL_PATH);
 }
@@ -67,6 +68,7 @@ async function resetCarryoverStateFiles(projectRoot, activeRunId) {
     await ensureDir(stateDir);
     await writeFileSafe(path.join(stateDir, DELEGATION_LOG_FILE), `${JSON.stringify({ runId: activeRunId, entries: [] }, null, 2)}\n`);
     await writeFileSafe(path.join(stateDir, TDD_CYCLE_LOG_FILE), "");
+    await writeFileSafe(path.join(stateDir, RECONCILIATION_NOTICES_FILE), `${JSON.stringify({ schemaVersion: 1, notices: [] }, null, 2)}\n`);
 }
 function toArchiveDate(date = new Date()) {
     const yyyy = date.getFullYear().toString();

package/package.json

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