cclaw-cli 0.46.15 → 0.48.0

package/dist/content/stage-schema.js

@@ -1,6 +1,17 @@
-import { COMMAND_FILE_ORDER } from "../constants.js";
+import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "../types.js";
+import { STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { BRAINSTORM, SCOPE, DESIGN, SPEC, PLAN, TDD, REVIEW, SHIP } from "./stages/index.js";
 import { tddStageForTrack } from "./stages/tdd.js";
+const ARTIFACT_STAGE_BY_PATH = {
+    ".cclaw/artifacts/01-brainstorm.md": "brainstorm",
+    ".cclaw/artifacts/02-scope.md": "scope",
+    ".cclaw/artifacts/03-design.md": "design",
+    ".cclaw/artifacts/04-spec.md": "spec",
+    ".cclaw/artifacts/05-plan.md": "plan",
+    ".cclaw/artifacts/06-tdd.md": "tdd",
+    ".cclaw/artifacts/07-review.md": "review",
+    ".cclaw/artifacts/08-ship.md": "ship"
+};
 const REQUIRED_GATE_IDS = {
     brainstorm: [
         "brainstorm_approaches_compared",
@@ -91,6 +102,16 @@ function tieredArtifactValidation(stage, rows) {
         };
     });
 }
+function readsFromForTrack(readsFrom, track) {
+    const stageSet = new Set(TRACK_STAGES[track]);
+    return readsFrom.filter((artifactPath) => {
+        const stage = ARTIFACT_STAGE_BY_PATH[artifactPath];
+        if (!stage) {
+            return true;
+        }
+        return stageSet.has(stage);
+    });
+}
 // ---------------------------------------------------------------------------
 // Stage map and accessors
 // ---------------------------------------------------------------------------
@@ -198,8 +219,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         },
         {
             agent: "reviewer",
-            mode: "proactive",
-            when: "When the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
+            mode: "mandatory",
+            when: "Mandatory when the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
             purpose: "Adversarial second-opinion review on large or trust-sensitive diffs. The second reviewer treats the implementation as hostile and tries to break it (hostile-user, future-maintainer, competitor lenses) instead of sympathetically explaining it.",
             requiresUserGate: false,
             skill: "adversarial-review"
@@ -232,23 +253,29 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
 };
 /** Transition guard: agents with `mode: "mandatory"` in auto-subagent dispatch for this stage. */
 export function mandatoryDelegationsForStage(stage) {
-    return STAGE_AUTO_SUBAGENT_DISPATCH[stage]
-        .filter((d) => d.mode === "mandatory")
-        .map((d) => d.agent);
+    return [...new Set(STAGE_AUTO_SUBAGENT_DISPATCH[stage]
+            .filter((d) => d.mode === "mandatory")
+            .map((d) => d.agent))];
 }
 export function stageSchema(stage, track = "standard") {
     const base = stage === "tdd" ? tddStageForTrack(track) : STAGE_SCHEMA_MAP[stage];
     const tieredGates = tieredStageGates(stage, base.requiredGates, track);
     const tieredValidation = tieredArtifactValidation(stage, base.artifactValidation);
+    const crossStageTrace = {
+        ...base.crossStageTrace,
+        readsFrom: readsFromForTrack(base.crossStageTrace.readsFrom, track)
+    };
     return {
         ...base,
+        skillFolder: STAGE_TO_SKILL_FOLDER[stage],
+        crossStageTrace,
         requiredGates: tieredGates,
         artifactValidation: tieredValidation,
         mandatoryDelegations: mandatoryDelegationsForStage(stage)
     };
 }
 export function orderedStageSchemas(track = "standard") {
-    return COMMAND_FILE_ORDER.map((stage) => stageSchema(stage, track));
+    return FLOW_STAGES.map((stage) => stageSchema(stage, track));
 }
 export function stageGateIds(stage, track = "standard") {
     return stageSchema(stage, track).requiredGates
@@ -266,15 +293,27 @@ export function nextCclawCommand(stage) {
 }
 export function buildTransitionRules() {
     const rules = [];
-    for (const schema of orderedStageSchemas()) {
-        if (schema.next === "done") {
-            continue;
+    const seen = new Set();
+    // Derive transitions from every track so medium/quick (which skip stages)
+    // get their neighbour edges registered alongside the standard chain.
+    // Previously only the standard track produced rules, so `canTransition`
+    // returned false for legitimate medium/quick transitions (e.g. brainstorm
+    // -> spec on medium) even though `nextStage` correctly advanced them.
+    for (const track of FLOW_TRACKS) {
+        const ordered = TRACK_STAGES[track];
+        for (let i = 0; i < ordered.length - 1; i += 1) {
+            const from = ordered[i];
+            const to = ordered[i + 1];
+            const key = `${from}->${to}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            rules.push({
+                from,
+                to,
+                guards: stageGateIds(from, track)
+            });
         }
-        rules.push({
-            from: schema.stage,
-            to: schema.next,
-            guards: stageGateIds(schema.stage)
-        });
     }
     // Review can explicitly route back to TDD when the verdict is BLOCKED.
     rules.push({

package/dist/content/stages/design.js

@@ -10,7 +10,7 @@ export const DESIGN = {
     ironLaw: "NO DESIGN DECISION WITHOUT A LABELED DIAGRAM, A REJECTED ALTERNATIVE, AND A NAMED FAILURE MODE.",
     purpose: "Lock architecture, data flow, failure modes, and test/performance expectations through rigorous interactive review.",
     whenToUse: [
-        "After scope contract approval",
+        "After scope agreement approval",
         "Before writing final spec and execution plan",
         "When architecture risks need explicit treatment"
     ],
@@ -79,7 +79,7 @@ export const DESIGN = {
         "What-already-exists section produced.",
         "Completion dashboard lists every review section status, decision count, and unresolved items (or 'None')."
     ],
-    inputs: ["scope contract", "system constraints", "non-functional requirements"],
+    inputs: ["scope agreement artifact", "system constraints", "non-functional requirements"],
     requiredContext: [
         "parallel research synthesis from `.cclaw/artifacts/02a-research.md`",
         "existing architecture and boundaries",

package/dist/content/stages/review.js

@@ -201,7 +201,7 @@ export const REVIEW = {
     },
     artifactValidation: [
         { section: "Layer 1 Verdict", required: true, validationRule: "Per-criterion pass/fail with references." },
-        { section: "Layer 2 Findings", required: false, validationRule: "Each finding has severity, description, and resolution status." },
+        { section: "Layer 2 Findings", required: false, validationRule: "Each finding has severity, description, and resolution status. Security coverage must include either explicit security findings or `NO_CHANGE_ATTESTATION: <reason>` when no security-relevant changes were found." },
         { section: "Review Army Contract", required: true, validationRule: "Structured findings include id/severity/confidence/fingerprint/reportedBy/status with dedup reconciliation summary." },
         { section: "Review Readiness Dashboard", required: false, validationRule: "Includes a per-pass table (Layer 1 / Layer 2 / Adversarial / Schema) with a 'Completed at' column, a Delegation log snapshot block (path .cclaw/state/delegation-log.json with required/completed/waived/pending), a Staleness signal block (commit at last review pass and current commit), and a Headline with open critical blockers + ship recommendation. At minimum, the section text must contain the substrings 'Completed at', 'delegation-log.json', 'commit at last review pass', and 'Ship recommendation'." },
         { section: "Completeness Score", required: false, validationRule: "Records AC coverage, task coverage, test-slice coverage, and adversarial-review pass status as numeric or boolean values. At minimum, a line like 'AC coverage: N/M' or 'AC coverage: 100%'." },

package/dist/content/stages/ship.js

@@ -100,6 +100,8 @@ export const SHIP = {
         "FINALIZE_NO_VCS"
     ],
     artifactFile: "08-ship.md",
+    // `done` exits the stage pipeline. Archive semantics are handled by the
+    // closeout substate machine (`idle` -> ... -> `archived`) in flow-state.
     next: "done",
     reviewSections: [
         {

package/dist/content/stages/tdd.js

@@ -63,7 +63,8 @@ export const TDD = {
         { id: "tdd_green_full_suite", description: "Full relevant suite passes in GREEN state." },
         { id: "tdd_refactor_completed", description: "Refactor pass completed with behavior preservation verified." },
         { id: "tdd_verified_before_complete", description: "Fresh verification evidence includes test command, commit SHA, and explicit pass/fail status." },
-        { id: "tdd_traceable_to_plan", description: "Change traceability to plan slice is explicit." }
+        { id: "tdd_traceable_to_plan", description: "Change traceability to plan slice is explicit." },
+        { id: "tdd_docs_drift_check", description: "When public API/config/CLI surfaces change, docs drift is addressed via a completed doc-updater pass." }
     ],
     requiredEvidence: [
         "Artifact updated at `.cclaw/artifacts/06-tdd.md` with RED, GREEN, and REFACTOR sections.",
@@ -206,9 +207,12 @@ function tddQuickTrackVariant() {
         checklist: TDD.checklist.map(quickTrackText),
         interactionProtocol: TDD.interactionProtocol.map(quickTrackText),
         process: TDD.process.map(quickTrackText),
-        requiredGates: TDD.requiredGates.map((gate) => gate.id === "tdd_traceable_to_plan"
-            ? { ...gate, description: "Change traceability to acceptance criterion is explicit." }
-            : gate),
+        requiredGates: TDD.requiredGates
+            .filter((gate) => gate.id !== "tdd_traceable_to_plan")
+            .map((gate) => ({
+            ...gate,
+            description: quickTrackText(gate.description)
+        })),
         requiredEvidence: TDD.requiredEvidence.map(quickTrackText),
         inputs: TDD.inputs.map(quickTrackText),
         requiredContext: ["spec artifact", "existing test patterns"],

package/dist/content/templates.js

@@ -1,5 +1,5 @@
-import { COMMAND_FILE_ORDER } from "../constants.js";
 import { orderedStageSchemas } from "./stage-schema.js";
+import { FLOW_STAGES } from "../types.js";
 export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `---
 stage: brainstorm
@@ -522,6 +522,7 @@ inputs_hash: sha256:pending
 | ID | Severity | Category | Description | Status |
 |---|---|---|---|---|
 | R-1 | Critical/Important/Suggestion | correctness/security/performance/architecture |  | open/resolved |
+- NO_CHANGE_ATTESTATION: <required when Category=security has no entries; explain why no security-relevant changes were detected>
 
 ## Incoming Feedback Queue
 | ID | Source | Severity | File:line | Request | Status | Evidence |
@@ -802,7 +803,7 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 export function buildRulesJson() {
     return {
         version: 1,
-        stage_order: COMMAND_FILE_ORDER,
+        stage_order: FLOW_STAGES,
         stage_gates: Object.fromEntries(orderedStageSchemas().map((schema) => [
             schema.stage,
             schema.requiredGates.map((gate) => gate.id)
@@ -820,7 +821,7 @@ export function buildRulesJson() {
             "conventional_commits"
         ],
         MUST_NEVER: [
-            "skip_test_stage",
+            "skip_tdd_stage",
             "ship_with_critical_findings",
             "implement_in_brainstorm",
             "manual_edit_generated",

package/dist/delegation.js

@@ -1,11 +1,14 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { RUNTIME_ROOT } from "./constants.js";
 import { readConfig } from "./config.js";
 import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
 import { stageSchema } from "./content/stage-schema.js";
+const execFileAsync = promisify(execFile);
 function delegationLogPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-log.json");
 }
@@ -15,6 +18,82 @@ function delegationLockPath(projectRoot) {
 function createSpanId() {
     return `dspan-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
+async function resolveReviewDiffBase(projectRoot) {
+    let head = "";
+    try {
+        head = (await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: projectRoot })).stdout.trim();
+    }
+    catch {
+        return null;
+    }
+    const candidates = ["origin/main", "origin/master", "main", "master"];
+    for (const candidate of candidates) {
+        try {
+            await execFileAsync("git", ["rev-parse", "--verify", candidate], { cwd: projectRoot });
+            const { stdout } = await execFileAsync("git", ["merge-base", "HEAD", candidate], {
+                cwd: projectRoot
+            });
+            const base = stdout.trim();
+            if (base.length > 0 && base !== head) {
+                return base;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD~1"], {
+            cwd: projectRoot
+        });
+        const base = stdout.trim();
+        return base.length > 0 ? base : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function detectReviewTriggers(projectRoot) {
+    const empty = {
+        changedFiles: 0,
+        changedLines: 0,
+        trustBoundaryChanged: false,
+        requireAdversarialReviewer: false
+    };
+    const base = await resolveReviewDiffBase(projectRoot);
+    if (!base) {
+        return empty;
+    }
+    try {
+        const range = `${base}..HEAD`;
+        const shortstat = await execFileAsync("git", ["diff", "--shortstat", range], {
+            cwd: projectRoot
+        });
+        const short = shortstat.stdout.trim();
+        const changedFiles = Number((/(\d+)\s+files?\s+changed/u.exec(short)?.[1] ?? "0"));
+        const insertions = Number((/(\d+)\s+insertions?\(\+\)/u.exec(short)?.[1] ?? "0"));
+        const deletions = Number((/(\d+)\s+deletions?\(-\)/u.exec(short)?.[1] ?? "0"));
+        const changedLines = insertions + deletions;
+        const names = await execFileAsync("git", ["diff", "--name-only", range], {
+            cwd: projectRoot
+        });
+        const changedPaths = names.stdout
+            .split(/\r?\n/gu)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        const trustBoundaryChanged = changedPaths.some((filePath) => /(auth|security|secret|token|credential|permission|acl|policy|oauth|session|encrypt|decrypt|input|validation)/iu.test(filePath));
+        const requireAdversarialReviewer = changedLines > 100 || changedFiles > 10 || trustBoundaryChanged;
+        return {
+            changedFiles,
+            changedLines,
+            trustBoundaryChanged,
+            requireAdversarialReviewer
+        };
+    }
+    catch {
+        return empty;
+    }
+}
 function isDelegationTokenUsage(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -76,6 +155,8 @@ function parseLedger(raw, runId) {
         for (const item of entriesRaw) {
             if (isDelegationEntry(item)) {
                 const ts = item.startTs ?? item.ts ?? new Date().toISOString();
+                const inferredFulfillmentMode = item.fulfillmentMode
+                    ?? (item.status === "completed" ? "isolated" : undefined);
                 entries.push({
                     ...item,
                     spanId: item.spanId ?? createSpanId(),
@@ -85,6 +166,7 @@ function parseLedger(raw, runId) {
                         ? item.retryCount
                         : 0,
                     evidenceRefs: Array.isArray(item.evidenceRefs) ? item.evidenceRefs : [],
+                    fulfillmentMode: inferredFulfillmentMode,
                     schemaVersion: 1
                 });
             }
@@ -126,6 +208,19 @@ export async function appendDelegation(projectRoot, entry) {
         if (!Array.isArray(stamped.evidenceRefs)) {
             stamped.evidenceRefs = [];
         }
+        if (stamped.status === "completed" && stamped.fulfillmentMode === undefined) {
+            const config = await readConfig(projectRoot).catch(() => null);
+            const harnesses = config?.harnesses ?? [];
+            const fallbacks = harnesses.map((h) => HARNESS_ADAPTERS[h].capabilities.subagentFallback);
+            stamped.fulfillmentMode = expectedFulfillmentMode(fallbacks);
+        }
+        // Idempotency: if a caller (or a retried hook) tries to append a row
+        // with a spanId that already exists in the ledger, treat it as a no-op
+        // instead of growing the log with duplicate entries that subsequent
+        // delegation checks would mis-count.
+        if (prior.entries.some((existing) => existing.spanId === stamped.spanId)) {
+            return;
+        }
         const ledger = {
             runId: activeRunId,
             entries: [...prior.entries, stamped]
@@ -167,45 +262,31 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
     const harnesses = config?.harnesses ?? [];
     const fallbacks = harnesses.map((h) => HARNESS_ADAPTERS[h].capabilities.subagentFallback);
     const expectedMode = expectedFulfillmentMode(fallbacks);
-    const onlyWaiverFallback = harnesses.length > 0 && fallbacks.every((f) => f === "waiver");
+    const reviewTriggers = stage === "review" ? await detectReviewTriggers(projectRoot) : null;
     for (const agent of mandatory) {
         const rows = forRun.filter((e) => e.agent === agent);
         const completedRows = rows.filter((e) => e.status === "completed");
         const waivedRows = rows.filter((e) => e.status === "waived");
-        const hasCompleted = completedRows.length > 0;
+        const requiredCompletedCount = stage === "review" &&
+            agent === "reviewer" &&
+            reviewTriggers?.requireAdversarialReviewer
+            ? 2
+            : 1;
+        const hasCompleted = completedRows.length >= requiredCompletedCount;
         const hasWaived = waivedRows.length > 0;
         const ok = hasCompleted || hasWaived;
         if (!ok) {
-            if (onlyWaiverFallback) {
-                const existingHarnessWaiver = rows.some((e) => e.status === "waived" && e.waiverReason === "harness_limitation");
-                if (!existingHarnessWaiver) {
-                    await appendDelegation(projectRoot, {
-                        stage,
-                        agent,
-                        mode: "mandatory",
-                        status: "waived",
-                        waiverReason: "harness_limitation",
-                        fulfillmentMode: "harness-waiver",
-                        ts: new Date().toISOString(),
-                        runId: activeRunId
-                    });
-                }
-                waived.push(agent);
-                autoWaived.push(agent);
-            }
-            else {
-                missing.push(agent);
-            }
+            missing.push(agent);
             continue;
         }
         if (hasWaived) {
             waived.push(agent);
         }
-        // Under role-switch fallback, a `completed` row is only credible if it
-        // carries at least one evidenceRef — otherwise the agent might have
-        // claimed role-switch satisfaction without showing its work.
+        // Evidence is required for any non-isolated completion mode. Legacy rows
+        // without fulfillmentMode are inferred to `isolated` during parse.
+        const evidenceRequired = completedRows.some((e) => (e.fulfillmentMode ?? "isolated") !== "isolated");
         if (hasCompleted &&
-            expectedMode === "role-switch" &&
+            evidenceRequired &&
             !completedRows.some((e) => Array.isArray(e.evidenceRefs) && e.evidenceRefs.length > 0)) {
             missingEvidence.push(agent);
         }

package/dist/doctor.js

@@ -3,16 +3,16 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
-import { COMMAND_FILE_ORDER, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
+import { REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
 import { CCLAW_AGENTS } from "./content/core-agents.js";
-import { readConfig } from "./config.js";
+import { detectAdvancedKeys, readConfig } from "./config.js";
 import { exists } from "./fs-utils.js";
 import { gitignoreHasRequiredPatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, CCLAW_MARKER_START, CCLAW_MARKER_END, harnessShimFileNames, harnessShimSkillNames } from "./harness-adapters.js";
 import { policyChecks } from "./policy.js";
 import { readFlowState } from "./runs.js";
 import { skippedStagesForTrack } from "./flow-state.js";
-import { TRACK_STAGES } from "./types.js";
+import { FLOW_STAGES, 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";
@@ -280,7 +280,7 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: fullPath
         });
     }
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const commandPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${stage}.md`);
         checks.push({
             name: `command:${stage}`,
@@ -377,7 +377,7 @@ export async function doctorChecks(projectRoot, options = {}) {
     // skill's Examples section points here; the file MUST exist or the pointer
     // is a dangling link.
     const stageRefDir = path.join(projectRoot, RUNTIME_ROOT, "references", "stages");
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const refPath = path.join(stageRefDir, `${stage}-examples.md`);
         checks.push({
             name: `stage_examples_ref:${stage}`,
@@ -430,6 +430,18 @@ export async function doctorChecks(projectRoot, options = {}) {
         });
     }
     if (parsedConfig) {
+        const advancedKeys = await detectAdvancedKeys(projectRoot).catch(() => new Set());
+        const hasLegacyTddTestGlobs = advancedKeys.has("tddTestGlobs");
+        const hasModernTddConfig = advancedKeys.has("tdd");
+        checks.push({
+            name: "warning:config:deprecated_tdd_test_globs",
+            ok: !hasLegacyTddTestGlobs,
+            details: hasLegacyTddTestGlobs
+                ? hasModernTddConfig
+                    ? `warning: ${RUNTIME_ROOT}/config.yaml sets deprecated "tddTestGlobs" alongside "tdd.*"; "tdd.testPathPatterns" takes precedence. Remove legacy key.`
+                    : `warning: ${RUNTIME_ROOT}/config.yaml uses deprecated "tddTestGlobs". Migrate to "tdd.testPathPatterns".`
+                : `no deprecated "tddTestGlobs" key detected in ${RUNTIME_ROOT}/config.yaml`
+        });
         const expectedMode = parsedConfig.promptGuardMode === "strict" ? "strict" : "advisory";
         const promptGuardPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", "prompt-guard.sh");
         let promptGuardModeOk = false;
@@ -1191,6 +1203,62 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "harness-gaps.json")),
         details: `${RUNTIME_ROOT}/state/harness-gaps.json must exist for tiered harness capability tracking`
     });
+    const adapterManifestPath = path.join(projectRoot, RUNTIME_ROOT, "adapters", "manifest.json");
+    const adapterManifestExists = await exists(adapterManifestPath);
+    checks.push({
+        name: "state:adapter_manifest_exists",
+        ok: adapterManifestExists,
+        details: `${RUNTIME_ROOT}/adapters/manifest.json must exist for harness adapter provenance`
+    });
+    if (adapterManifestExists) {
+        let harnessesOk = false;
+        let harnessesDetails = "";
+        let sourcesOk = false;
+        let sourcesDetails = "";
+        try {
+            const parsed = JSON.parse(await fs.readFile(adapterManifestPath, "utf8"));
+            const manifestHarnesses = Array.isArray(parsed.harnesses)
+                ? parsed.harnesses.filter((entry) => typeof entry === "string")
+                : [];
+            const expectedHarnesses = configuredHarnesses.length > 0
+                ? [...new Set(configuredHarnesses)].sort()
+                : null;
+            const actualHarnesses = [...new Set(manifestHarnesses)].sort();
+            harnessesOk = expectedHarnesses
+                ? actualHarnesses.length === expectedHarnesses.length &&
+                    actualHarnesses.every((harness, index) => harness === expectedHarnesses[index])
+                : actualHarnesses.length > 0;
+            harnessesDetails = expectedHarnesses
+                ? harnessesOk
+                    ? `adapter manifest harnesses match config.yaml: ${actualHarnesses.join(", ")}`
+                    : `adapter manifest harnesses [${actualHarnesses.join(", ")}] do not match config.yaml [${expectedHarnesses.join(", ")}]`
+                : harnessesOk
+                    ? `adapter manifest declares harnesses: ${actualHarnesses.join(", ")}`
+                    : "adapter manifest must declare at least one harness";
+            const commandSource = typeof parsed.commandSource === "string" ? parsed.commandSource.trim() : "";
+            const skillSource = typeof parsed.skillSource === "string" ? parsed.skillSource.trim() : "";
+            sourcesOk = commandSource.length > 0 && skillSource.length > 0;
+            sourcesDetails = sourcesOk
+                ? `adapter manifest source globs are set (commandSource=${commandSource}; skillSource=${skillSource})`
+                : "adapter manifest must include non-empty commandSource and skillSource";
+        }
+        catch {
+            harnessesOk = false;
+            harnessesDetails = "adapter manifest must be valid JSON with a harnesses array";
+            sourcesOk = false;
+            sourcesDetails = "adapter manifest must be valid JSON with source globs";
+        }
+        checks.push({
+            name: "state:adapter_manifest_harnesses",
+            ok: harnessesOk,
+            details: harnessesDetails
+        });
+        checks.push({
+            name: "state:adapter_manifest_sources",
+            ok: sourcesOk,
+            details: sourcesDetails
+        });
+    }
     const contextModeStatePath = path.join(projectRoot, RUNTIME_ROOT, "state", "context-mode.json");
     checks.push({
         name: "state:context_mode_exists",
@@ -1276,7 +1344,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         name: "flow_state:track",
         ok: skippedConsistent,
         details: skippedConsistent
-            ? `active track "${activeTrack}" (${trackStageList.length}/${COMMAND_FILE_ORDER.length} stages: ${trackStageList.join(" → ")})${expectedSkipped.length > 0 ? `; skippedStages=${expectedSkipped.join(", ")}` : ""}`
+            ? `active track "${activeTrack}" (${trackStageList.length}/${FLOW_STAGES.length} stages: ${trackStageList.join(" → ")})${expectedSkipped.length > 0 ? `; skippedStages=${expectedSkipped.join(", ")}` : ""}`
             : `track "${activeTrack}" expects skippedStages=[${expectedSkipped.join(", ")}] but flow-state has [${skippedFromState.join(", ")}] — run \`cclaw sync\` to repair`
     });
     if (parsedConfig?.trackHeuristics) {
@@ -1441,7 +1509,7 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? "no legacy .cclaw/features snapshot entries remain"
             : `legacy snapshot entries still present (read-only): ${legacyWorkspaceEntries.join(", ")}`
     });
-    const staleStages = Object.keys(flowState.staleStages).filter((value) => COMMAND_FILE_ORDER.includes(value));
+    const staleStages = Object.keys(flowState.staleStages).filter((value) => FLOW_STAGES.includes(value));
     checks.push({
         name: "state:stale_stages_resolved",
         ok: staleStages.length === 0,
@@ -1667,10 +1735,10 @@ export async function doctorChecks(projectRoot, options = {}) {
             const stageOrder = parsed.stage_order;
             const stageGates = parsed.stage_gates;
             const hasStageOrder = Array.isArray(stageOrder) &&
-                COMMAND_FILE_ORDER.every((stage) => stageOrder.includes(stage));
+                FLOW_STAGES.every((stage) => stageOrder.includes(stage));
             const hasStageGates = typeof stageGates === "object" &&
                 stageGates !== null &&
-                COMMAND_FILE_ORDER.every((stage) => Array.isArray(stageGates[stage]));
+                FLOW_STAGES.every((stage) => Array.isArray(stageGates[stage]));
             hasRules = hasCoreLists && hasStageOrder && hasStageGates;
         }
         catch {

package/dist/flow-state.d.ts

@@ -43,6 +43,14 @@ export interface RetroState {
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive
  *   resets flow-state so this value does not persist between runs).
+ *
+ * Layer separation (intentional):
+ * - `next: "done"` in stage schema means "the flow stage chain ended".
+ * - `shipSubstate: "archived"` is closeout-machine progress after ship.
+ * - `shipSubstate: "idle"` is the default closeout value before ship.
+ *
+ * These are not duplicates: `done` lives in stage transitions; `archived` /
+ * `idle` live in closeout lifecycle state.
  */
 export declare const SHIP_SUBSTATES: readonly ["idle", "retro_review", "compound_review", "ready_to_archive", "archived"];
 export type ShipSubstate = (typeof SHIP_SUBSTATES)[number];

package/dist/flow-state.js

@@ -1,4 +1,3 @@
-import { COMMAND_FILE_ORDER } from "./constants.js";
 import { buildTransitionRules, orderedStageSchemas, stageGateIds, stageRecommendedGateIds } from "./content/stage-schema.js";
 import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
 export const TRANSITION_RULES = buildTransitionRules();
@@ -17,6 +16,14 @@ export const TRANSITION_RULES = buildTransitionRules();
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive
  *   resets flow-state so this value does not persist between runs).
+ *
+ * Layer separation (intentional):
+ * - `next: "done"` in stage schema means "the flow stage chain ended".
+ * - `shipSubstate: "archived"` is closeout-machine progress after ship.
+ * - `shipSubstate: "idle"` is the default closeout value before ship.
+ *
+ * These are not duplicates: `done` lives in stage transitions; `archived` /
+ * `idle` live in closeout lifecycle state.
  */
 export const SHIP_SUBSTATES = [
     "idle",
@@ -98,11 +105,7 @@ export function nextStage(stage, track = "standard") {
     const ordered = TRACK_STAGES[track];
     const index = ordered.indexOf(stage);
     if (index < 0) {
-        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
-        if (fallback < 0 || fallback === COMMAND_FILE_ORDER.length - 1) {
-            return null;
-        }
-        return COMMAND_FILE_ORDER[fallback + 1];
+        return null;
     }
     if (index === ordered.length - 1) {
         return null;
@@ -116,11 +119,11 @@ export function previousStage(stage, track = "standard") {
         return null;
     }
     if (index < 0) {
-        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
+        const fallback = FLOW_STAGES.indexOf(stage);
         if (fallback <= 0) {
             return null;
         }
-        return COMMAND_FILE_ORDER[fallback - 1];
+        return FLOW_STAGES[fallback - 1];
     }
     return ordered[index - 1];
 }