cclaw-cli 0.46.12 → 0.46.13

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/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

@@ -3,9 +3,10 @@ import path from "node:path";
 import { checkReviewVerdictConsistency, 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 = [
@@ -33,6 +34,95 @@ 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;
+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);
@@ -208,6 +298,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 +339,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 +348,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 +381,7 @@ export function reconcileCurrentStageGateCatalog(flowState) {
             changed,
             before,
             after,
+            demotedGateIds: [...required, ...recommended].filter((gateId) => demotedGateIds.has(gateId)),
             notes
         }
     };
@@ -295,8 +389,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.13",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {