cclaw-cli 0.10.1 → 0.12.0

package/dist/doctor.js

@@ -4,7 +4,7 @@ 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 { CCLAW_AGENTS } from "./content/agents.js";
+import { CCLAW_AGENTS } from "./content/core-agents.js";
 import { readConfig } from "./config.js";
 import { exists } from "./fs-utils.js";
 import { gitignoreHasRequiredPatterns } from "./gitignore.js";
@@ -17,10 +17,13 @@ import { checkMandatoryDelegations } from "./delegation.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { reconcileAndWriteCurrentStageGateCatalog, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { stageSkillFolder } from "./content/skills.js";
+import { doctorCheckMetadata } from "./doctor-registry.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LEGACY_LANGUAGE_RULE_PACK_FOLDERS, UTILITY_SKILL_FOLDERS } from "./content/utility-skills.js";
 import { CONTEXT_MODES, DEFAULT_CONTEXT_MODE } from "./content/contexts.js";
+import { DOCTOR_REFERENCE_MARKDOWN } from "./content/doctor-references.js";
 import { validateHookDocument } from "./hook-schema.js";
 const execFileAsync = promisify(execFile);
+const PREAMBLE_COOLDOWN_MS = 15 * 60 * 1000;
 async function isGitRepo(projectRoot) {
     try {
         await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: projectRoot });
@@ -278,8 +281,8 @@ export async function doctorChecks(projectRoot, options = {}) {
                 { id: "iron_law", pattern: /^\*\*IRON LAW — [A-Z]+:\*\* .+$/m, label: "Iron Law punchcard (<EXTREMELY-IMPORTANT> wrapper)" },
                 { id: "hard_gate", pattern: /^## HARD-GATE$/m, label: "## HARD-GATE" },
                 { id: "checklist", pattern: /^## Checklist$/m, label: "## Checklist" },
-                { id: "completion_protocol", pattern: /^## Stage Completion Protocol$/m, label: "## Stage Completion Protocol" },
-                { id: "handoff_menu", pattern: /^### Handoff Menu$/m, label: "### Handoff Menu" },
+                { id: "completion_parameters", pattern: /^## Completion Parameters$/m, label: "## Completion Parameters" },
+                { id: "shared_guidance", pattern: /^## Shared Stage Guidance$/m, label: "## Shared Stage Guidance" },
                 { id: "good_vs_bad", pattern: /Good vs Bad/i, label: "Good vs Bad examples" },
                 { id: "anti_patterns", pattern: /^## Anti-Patterns & Red Flags$/m, label: "## Anti-Patterns & Red Flags" }
             ];
@@ -303,14 +306,12 @@ export async function doctorChecks(projectRoot, options = {}) {
         const metaContent = await fs.readFile(metaSkillPath, "utf8");
         const requiredSignals = [
             { id: "instruction_priority", pattern: /Instruction Priority/i, label: "Instruction Priority" },
-            { id: "spawned_detection", pattern: /Spawned Subagent Detection/i, label: "Spawned Subagent Detection" },
-            { id: "shared_decision", pattern: /Shared Decision \+ Tool-Use Protocol/i, label: "Shared Decision + Tool-Use Protocol" },
-            { id: "shared_completion", pattern: /Shared Stage Completion Protocol/i, label: "Shared Stage Completion Protocol" },
-            { id: "escalation_rule", pattern: /Escalation Rule \(3 attempts\)/i, label: "Escalation Rule (3 attempts)" },
-            { id: "invocation_preamble", pattern: /Invocation Preamble/i, label: "Invocation Preamble" },
-            { id: "operational_self_improvement", pattern: /Operational Self-Improvement/i, label: "Operational Self-Improvement" },
-            { id: "engineering_ethos", pattern: /Engineering Ethos/i, label: "Engineering Ethos" },
-            { id: "task_classification", pattern: /Task Classification/i, label: "Task Classification" }
+            { id: "routing_flow", pattern: /Routing flow/i, label: "Routing flow" },
+            { id: "task_classification", pattern: /Task classification/i, label: "Task classification" },
+            { id: "stage_map", pattern: /Stage quick map/i, label: "Stage quick map" },
+            { id: "protocol_refs", pattern: /Protocol references/i, label: "Protocol references" },
+            { id: "knowledge_guidance", pattern: /Knowledge guidance/i, label: "Knowledge guidance" },
+            { id: "failure_guardrails", pattern: /Failure guardrails/i, label: "Failure guardrails" }
         ];
         const missingMeta = requiredSignals
             .filter((signal) => !signal.pattern.test(metaContent))
@@ -347,6 +348,20 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: refPath
         });
     }
+    checks.push({
+        name: "harness_ref:matrix",
+        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "references", "harnesses.md")),
+        details: `${RUNTIME_ROOT}/references/harnesses.md`
+    });
+    const doctorRefDir = path.join(projectRoot, RUNTIME_ROOT, "references", "doctor");
+    for (const fileName of Object.keys(DOCTOR_REFERENCE_MARKDOWN)) {
+        const refPath = path.join(doctorRefDir, fileName);
+        checks.push({
+            name: `doctor_ref:${fileName.replace(/\.md$/, "")}`,
+            ok: await exists(refPath),
+            details: refPath
+        });
+    }
     checks.push({
         name: "gitignore:required_patterns",
         ok: await gitignoreHasRequiredPatterns(projectRoot),
@@ -782,6 +797,11 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl")),
         details: `${RUNTIME_ROOT}/knowledge.jsonl must exist`
     });
+    checks.push({
+        name: "knowledge:digest_exists",
+        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "knowledge-digest.md")),
+        details: `${RUNTIME_ROOT}/state/knowledge-digest.md must exist`
+    });
     // There must be NO legacy markdown knowledge store — JSONL is the only store.
     const legacyKnowledgeMdPath = path.join(projectRoot, RUNTIME_ROOT, "knowledge.md");
     const legacyExists = await exists(legacyKnowledgeMdPath);
@@ -807,6 +827,11 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "suggestion-memory.json")),
         details: `${RUNTIME_ROOT}/state/suggestion-memory.json must exist for proactive suggestion memory`
     });
+    checks.push({
+        name: "state:harness_gaps_exists",
+        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 contextModeStatePath = path.join(projectRoot, RUNTIME_ROOT, "state", "context-mode.json");
     checks.push({
         name: "state:context_mode_exists",
@@ -837,6 +862,81 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: modePath
         });
     }
+    const preambleLogPath = path.join(projectRoot, RUNTIME_ROOT, "state", "preamble-log.jsonl");
+    const preambleLogExists = await exists(preambleLogPath);
+    checks.push({
+        name: "state:preamble_log_exists",
+        ok: preambleLogExists,
+        details: `${RUNTIME_ROOT}/state/preamble-log.jsonl must exist for preamble budget tracking`
+    });
+    if (preambleLogExists) {
+        let duplicateHits = 0;
+        let parsedEntries = 0;
+        let malformedEntries = 0;
+        try {
+            const now = Date.now();
+            const byKey = new Map();
+            const raw = await fs.readFile(preambleLogPath, "utf8");
+            const lines = raw
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
+            for (const line of lines) {
+                try {
+                    const parsed = JSON.parse(line);
+                    const tsRaw = parsed.ts;
+                    const stageRaw = parsed.stage;
+                    const triggerRaw = parsed.trigger;
+                    const hashRaw = parsed.hash;
+                    if (typeof tsRaw !== "string" ||
+                        typeof stageRaw !== "string" ||
+                        typeof triggerRaw !== "string" ||
+                        typeof hashRaw !== "string") {
+                        malformedEntries += 1;
+                        continue;
+                    }
+                    const stamp = Date.parse(tsRaw);
+                    if (!Number.isFinite(stamp)) {
+                        malformedEntries += 1;
+                        continue;
+                    }
+                    if (now - stamp > 24 * 60 * 60 * 1000) {
+                        continue;
+                    }
+                    parsedEntries += 1;
+                    const key = `${stageRaw}|${triggerRaw}|${hashRaw}`;
+                    const bucket = byKey.get(key) ?? [];
+                    bucket.push(stamp);
+                    byKey.set(key, bucket);
+                }
+                catch {
+                    malformedEntries += 1;
+                }
+            }
+            for (const stamps of byKey.values()) {
+                stamps.sort((a, b) => a - b);
+                for (let i = 1; i < stamps.length; i += 1) {
+                    if (stamps[i] - stamps[i - 1] < PREAMBLE_COOLDOWN_MS) {
+                        duplicateHits += 1;
+                    }
+                }
+            }
+        }
+        catch {
+            malformedEntries += 1;
+        }
+        checks.push({
+            name: "warning:preamble:dedup",
+            ok: true,
+            details: duplicateHits > 0
+                ? `warning: detected ${duplicateHits} repeated preamble emission(s) inside ${Math.floor(PREAMBLE_COOLDOWN_MS / 60000)}m cooldown window`
+                : parsedEntries > 0
+                    ? `preamble budget healthy (${parsedEntries} recent preamble entry/entries checked)`
+                    : malformedEntries > 0
+                        ? `warning: preamble log exists but entries are malformed (${malformedEntries} line(s) ignored)`
+                        : "preamble log is empty; no recent preamble emissions recorded"
+        });
+    }
     let flowState = await readFlowState(projectRoot);
     if (options.reconcileCurrentStageGates === true) {
         const reconciliation = await reconcileAndWriteCurrentStageGateCatalog(projectRoot);
@@ -908,7 +1008,9 @@ export async function doctorChecks(projectRoot, options = {}) {
         name: "warning:delegation:waived",
         ok: true,
         details: delegation.waived.length > 0
-            ? `warning: waived mandatory delegations for stage "${flowState.currentStage}": ${delegation.waived.join(", ")}`
+            ? `warning: waived mandatory delegations for stage "${flowState.currentStage}": ${delegation.waived.join(", ")}${delegation.autoWaived.length > 0
+                ? ` (auto-waived due to harness limitation: ${delegation.autoWaived.join(", ")})`
+                : ""}`
             : "no waived mandatory delegations for current stage"
     });
     checks.push({
@@ -968,9 +1070,16 @@ export async function doctorChecks(projectRoot, options = {}) {
         name: "gates:evidence:current_stage",
         ok: gateEvidence.ok,
         details: gateEvidence.ok
-            ? `stage "${gateEvidence.stage}" gate evidence is consistent (required=${gateEvidence.requiredCount}, passed=${gateEvidence.passedCount}, blocked=${gateEvidence.blockedCount})`
+            ? `stage "${gateEvidence.stage}" gate evidence is consistent (required=${gateEvidence.requiredCount}, recommended=${gateEvidence.recommendedCount}, conditional=${gateEvidence.conditionalCount}, triggered=${gateEvidence.triggeredConditionalCount}, passed=${gateEvidence.passedCount}, blocked=${gateEvidence.blockedCount})`
             : gateEvidence.issues.join(" ")
     });
+    checks.push({
+        name: "warning:gates:recommended:current_stage",
+        ok: true,
+        details: gateEvidence.missingRecommended.length > 0
+            ? `warning: stage "${gateEvidence.stage}" has unmet recommended gates: ${gateEvidence.missingRecommended.join(", ")}`
+            : `no unmet recommended gates for stage "${gateEvidence.stage}"`
+    });
     const completedClosure = verifyCompletedStagesGateClosure(flowState);
     checks.push({
         name: "gates:closure:completed_stages",
@@ -981,18 +1090,6 @@ export async function doctorChecks(projectRoot, options = {}) {
                 : `all ${flowState.completedStages.length} completed stages have every required gate passed`
             : completedClosure.issues.join(" ")
     });
-    // Self-improvement block in stage skills
-    for (const stage of COMMAND_FILE_ORDER) {
-        const skillPath = path.join(projectRoot, RUNTIME_ROOT, "skills", stageSkillFolder(stage), "SKILL.md");
-        if (await exists(skillPath)) {
-            const content = await fs.readFile(skillPath, "utf8");
-            checks.push({
-                name: `skill:${stage}:self_improvement`,
-                ok: content.includes("## Operational Self-Improvement"),
-                details: `${skillPath} must contain self-improvement block`
-            });
-        }
-    }
     const isRepo = await isGitRepo(projectRoot);
     checks.push({
         name: "git:cclaw_ignored_runtime",
@@ -1027,8 +1124,17 @@ export async function doctorChecks(projectRoot, options = {}) {
     });
     const policy = await policyChecks(projectRoot, { harnesses: configuredHarnesses });
     checks.push(...policy);
-    return checks;
+    return checks.map((check) => {
+        const metadata = doctorCheckMetadata(check.name);
+        return {
+            ...check,
+            severity: check.severity ?? metadata.severity,
+            summary: check.summary ?? metadata.summary,
+            fix: check.fix ?? metadata.fix,
+            docRef: check.docRef ?? metadata.docRef
+        };
+    });
 }
 export function doctorSucceeded(checks) {
-    return checks.every((check) => check.ok);
+    return checks.every((check) => check.ok || check.severity !== "error");
 }

package/dist/flow-state.d.ts

@@ -2,6 +2,10 @@ import type { FlowStage, FlowTrack, TransitionRule } from "./types.js";
 export declare const TRANSITION_RULES: TransitionRule[];
 export interface StageGateState {
     required: string[];
+    recommended: string[];
+    conditional: string[];
+    /** Conditional gates currently considered active for blocking checks. */
+    triggered: string[];
     passed: string[];
     blocked: string[];
 }

package/dist/flow-state.js

@@ -1,5 +1,5 @@
 import { COMMAND_FILE_ORDER } from "./constants.js";
-import { buildTransitionRules, orderedStageSchemas, stageGateIds } from "./content/stage-schema.js";
+import { buildTransitionRules, orderedStageSchemas, stageConditionalGateIds, stageGateIds, stageRecommendedGateIds } from "./content/stage-schema.js";
 import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
 export const TRANSITION_RULES = buildTransitionRules();
 export function isFlowTrack(value) {
@@ -27,6 +27,9 @@ export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTra
     for (const schema of orderedStageSchemas()) {
         stageGateCatalog[schema.stage] = {
             required: stageGateIds(schema.stage),
+            recommended: stageRecommendedGateIds(schema.stage),
+            conditional: stageConditionalGateIds(schema.stage),
+            triggered: [],
             passed: [],
             blocked: []
         };

package/dist/gate-evidence.d.ts

@@ -5,12 +5,19 @@ export interface GateEvidenceCheckResult {
     stage: FlowStage;
     issues: string[];
     requiredCount: number;
+    recommendedCount: number;
+    conditionalCount: number;
+    triggeredConditionalCount: number;
     passedCount: number;
     blockedCount: number;
-    /** True only when every required gate for the stage is in `passed` and none are `blocked`. */
+    /** True only when required + triggered conditional gates are passed and unblocked. */
     complete: boolean;
     /** Required gate ids that are neither passed nor blocked. */
     missingRequired: string[];
+    /** Recommended gates not yet passed (does not block). */
+    missingRecommended: string[];
+    /** Triggered conditional gates that are not yet passed. */
+    missingTriggeredConditional: string[];
 }
 export interface CompletedStagesClosureResult {
     ok: boolean;
@@ -18,6 +25,7 @@ export interface CompletedStagesClosureResult {
     openStages: Array<{
         stage: FlowStage;
         missingRequired: string[];
+        missingTriggeredConditional: string[];
         blocked: string[];
     }>;
 }

package/dist/gate-evidence.js

@@ -36,21 +36,56 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
     const stage = flowState.currentStage;
     const schema = stageSchema(stage);
     const catalog = flowState.stageGateCatalog[stage];
-    const required = schema.requiredGates.map((gate) => gate.id);
+    const required = schema.requiredGates
+        .filter((gate) => gate.tier === "required")
+        .map((gate) => gate.id);
+    const recommended = schema.requiredGates
+        .filter((gate) => gate.tier === "recommended")
+        .map((gate) => gate.id);
+    const conditional = schema.requiredGates
+        .filter((gate) => gate.tier === "conditional")
+        .map((gate) => gate.id);
     const requiredSet = new Set(required);
+    const recommendedSet = new Set(recommended);
+    const conditionalSet = new Set(conditional);
+    const allowedSet = new Set([...required, ...recommended, ...conditional]);
     const issues = [];
     const catalogRequired = unique(catalog.required);
+    const catalogRecommended = unique(catalog.recommended ?? []);
+    const catalogConditional = unique(catalog.conditional ?? []);
+    const catalogTriggered = unique(catalog.triggered ?? []);
     const missingInCatalog = required.filter((gateId) => !catalogRequired.includes(gateId));
     const unexpectedInCatalog = catalogRequired.filter((gateId) => !requiredSet.has(gateId));
+    const missingRecommendedInCatalog = recommended.filter((gateId) => !catalogRecommended.includes(gateId));
+    const unexpectedRecommendedInCatalog = catalogRecommended.filter((gateId) => !recommendedSet.has(gateId));
+    const missingConditionalInCatalog = conditional.filter((gateId) => !catalogConditional.includes(gateId));
+    const unexpectedConditionalInCatalog = catalogConditional.filter((gateId) => !conditionalSet.has(gateId));
     for (const gateId of missingInCatalog) {
         issues.push(`gate "${gateId}" missing from stageGateCatalog.required for stage "${stage}".`);
     }
     for (const gateId of unexpectedInCatalog) {
         issues.push(`unexpected gate "${gateId}" found in stageGateCatalog.required for stage "${stage}".`);
     }
+    for (const gateId of missingRecommendedInCatalog) {
+        issues.push(`gate "${gateId}" missing from stageGateCatalog.recommended for stage "${stage}".`);
+    }
+    for (const gateId of unexpectedRecommendedInCatalog) {
+        issues.push(`unexpected gate "${gateId}" found in stageGateCatalog.recommended for stage "${stage}".`);
+    }
+    for (const gateId of missingConditionalInCatalog) {
+        issues.push(`gate "${gateId}" missing from stageGateCatalog.conditional for stage "${stage}".`);
+    }
+    for (const gateId of unexpectedConditionalInCatalog) {
+        issues.push(`unexpected gate "${gateId}" found in stageGateCatalog.conditional for stage "${stage}".`);
+    }
+    for (const gateId of catalogTriggered) {
+        if (!conditionalSet.has(gateId)) {
+            issues.push(`triggered gate "${gateId}" is not defined as conditional for stage "${stage}".`);
+        }
+    }
     const blockedSet = new Set(catalog.blocked);
     for (const gateId of catalog.passed) {
-        if (!requiredSet.has(gateId)) {
+        if (!allowedSet.has(gateId)) {
             issues.push(`passed gate "${gateId}" is not defined for stage "${stage}".`);
             continue;
         }
@@ -63,7 +98,7 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
         }
     }
     for (const gateId of catalog.blocked) {
-        if (!requiredSet.has(gateId)) {
+        if (!allowedSet.has(gateId)) {
             issues.push(`blocked gate "${gateId}" is not defined for stage "${stage}".`);
         }
     }
@@ -91,14 +126,25 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
         }
     }
     const passedSet = new Set(catalog.passed);
+    const triggeredConditionalSet = new Set([
+        ...catalogTriggered.filter((gateId) => conditionalSet.has(gateId)),
+        ...catalog.passed.filter((gateId) => conditionalSet.has(gateId)),
+        ...catalog.blocked.filter((gateId) => conditionalSet.has(gateId))
+    ]);
     const missingRequired = required.filter((gateId) => !passedSet.has(gateId));
-    const complete = missingRequired.length === 0 && catalog.blocked.length === 0;
+    const missingRecommended = recommended.filter((gateId) => !passedSet.has(gateId));
+    const missingTriggeredConditional = [...triggeredConditionalSet].filter((gateId) => !passedSet.has(gateId));
+    const blockingBlocked = catalog.blocked.filter((gateId) => requiredSet.has(gateId) || triggeredConditionalSet.has(gateId));
+    const complete = missingRequired.length === 0 && missingTriggeredConditional.length === 0 && blockingBlocked.length === 0;
     if (flowState.completedStages.includes(stage) && !complete) {
         if (missingRequired.length > 0) {
             issues.push(`stage "${stage}" is marked completed but required gates are not passed: ${missingRequired.join(", ")}.`);
         }
-        if (catalog.blocked.length > 0) {
-            issues.push(`stage "${stage}" is marked completed but has blocked gates: ${catalog.blocked.join(", ")}.`);
+        if (missingTriggeredConditional.length > 0) {
+            issues.push(`stage "${stage}" is marked completed but triggered conditional gates are not passed: ${missingTriggeredConditional.join(", ")}.`);
+        }
+        if (blockingBlocked.length > 0) {
+            issues.push(`stage "${stage}" is marked completed but has blocking blocked gates: ${blockingBlocked.join(", ")}.`);
         }
     }
     return {
@@ -106,10 +152,15 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
         stage,
         issues,
         requiredCount: required.length,
+        recommendedCount: recommended.length,
+        conditionalCount: conditional.length,
+        triggeredConditionalCount: triggeredConditionalSet.size,
         passedCount: catalog.passed.length,
         blockedCount: catalog.blocked.length,
         complete,
-        missingRequired
+        missingRequired,
+        missingRecommended,
+        missingTriggeredConditional
     };
 }
 export function verifyCompletedStagesGateClosure(flowState) {
@@ -118,16 +169,37 @@ export function verifyCompletedStagesGateClosure(flowState) {
     for (const stage of flowState.completedStages) {
         const schema = stageSchema(stage);
         const catalog = flowState.stageGateCatalog[stage];
-        const required = schema.requiredGates.map((gate) => gate.id);
+        const required = schema.requiredGates
+            .filter((gate) => gate.tier === "required")
+            .map((gate) => gate.id);
+        const conditional = schema.requiredGates
+            .filter((gate) => gate.tier === "conditional")
+            .map((gate) => gate.id);
+        const conditionalSet = new Set(conditional);
         const passedSet = new Set(catalog.passed);
+        const triggeredSet = new Set([
+            ...(catalog.triggered ?? []).filter((gateId) => conditionalSet.has(gateId)),
+            ...catalog.passed.filter((gateId) => conditionalSet.has(gateId)),
+            ...catalog.blocked.filter((gateId) => conditionalSet.has(gateId))
+        ]);
         const missingRequired = required.filter((gateId) => !passedSet.has(gateId));
-        if (missingRequired.length > 0 || catalog.blocked.length > 0) {
-            openStages.push({ stage, missingRequired, blocked: [...catalog.blocked] });
+        const missingTriggeredConditional = [...triggeredSet].filter((gateId) => !passedSet.has(gateId));
+        const blockingBlocked = catalog.blocked.filter((gateId) => required.includes(gateId) || triggeredSet.has(gateId));
+        if (missingRequired.length > 0 || missingTriggeredConditional.length > 0 || blockingBlocked.length > 0) {
+            openStages.push({
+                stage,
+                missingRequired,
+                missingTriggeredConditional,
+                blocked: [...blockingBlocked]
+            });
             if (missingRequired.length > 0) {
                 issues.push(`completed stage "${stage}" has unpassed required gates: ${missingRequired.join(", ")}.`);
             }
-            if (catalog.blocked.length > 0) {
-                issues.push(`completed stage "${stage}" still has blocked gates: ${catalog.blocked.join(", ")}.`);
+            if (missingTriggeredConditional.length > 0) {
+                issues.push(`completed stage "${stage}" has unpassed triggered conditional gates: ${missingTriggeredConditional.join(", ")}.`);
+            }
+            if (blockingBlocked.length > 0) {
+                issues.push(`completed stage "${stage}" still has blocking blocked gates: ${blockingBlocked.join(", ")}.`);
             }
         }
     }
@@ -135,29 +207,55 @@ export function verifyCompletedStagesGateClosure(flowState) {
 }
 export function reconcileCurrentStageGateCatalog(flowState) {
     const stage = flowState.currentStage;
-    const required = stageSchema(stage).requiredGates.map((gate) => gate.id);
+    const required = stageSchema(stage).requiredGates
+        .filter((gate) => gate.tier === "required")
+        .map((gate) => gate.id);
+    const recommended = stageSchema(stage).requiredGates
+        .filter((gate) => gate.tier === "recommended")
+        .map((gate) => gate.id);
+    const conditional = stageSchema(stage).requiredGates
+        .filter((gate) => gate.tier === "conditional")
+        .map((gate) => gate.id);
     const requiredSet = new Set(required);
+    const recommendedSet = new Set(recommended);
+    const conditionalSet = new Set(conditional);
+    const allowedSet = new Set([...required, ...recommended, ...conditional]);
     const catalog = flowState.stageGateCatalog[stage];
     const notes = [];
     const before = {
         required: [...catalog.required],
+        recommended: [...catalog.recommended],
+        conditional: [...catalog.conditional],
+        triggered: [...catalog.triggered],
         passed: [...catalog.passed],
         blocked: [...catalog.blocked]
     };
     const passedSet = new Set(unique(catalog.passed).filter((gateId) => {
-        const keep = requiredSet.has(gateId);
+        const keep = allowedSet.has(gateId);
         if (!keep) {
             notes.push(`removed unknown passed gate "${gateId}"`);
         }
         return keep;
     }));
     const blockedSet = new Set(unique(catalog.blocked).filter((gateId) => {
-        const keep = requiredSet.has(gateId);
+        const keep = allowedSet.has(gateId);
         if (!keep) {
             notes.push(`removed unknown blocked gate "${gateId}"`);
         }
         return keep;
     }));
+    const triggeredSet = new Set(unique(catalog.triggered).filter((gateId) => {
+        const keep = conditionalSet.has(gateId);
+        if (!keep) {
+            notes.push(`removed unknown triggered gate "${gateId}"`);
+        }
+        return keep;
+    }));
+    for (const gateId of [...passedSet, ...blockedSet]) {
+        if (conditionalSet.has(gateId)) {
+            triggeredSet.add(gateId);
+        }
+    }
     for (const gateId of [...passedSet]) {
         if (!blockedSet.has(gateId))
             continue;
@@ -180,10 +278,16 @@ export function reconcileCurrentStageGateCatalog(flowState) {
     }
     const after = {
         required: [...required],
-        passed: required.filter((gateId) => passedSet.has(gateId)),
-        blocked: required.filter((gateId) => blockedSet.has(gateId) && !passedSet.has(gateId))
+        recommended: [...recommended],
+        conditional: [...conditional],
+        triggered: conditional.filter((gateId) => triggeredSet.has(gateId)),
+        passed: [...required, ...recommended, ...conditional].filter((gateId) => passedSet.has(gateId)),
+        blocked: [...required, ...recommended, ...conditional].filter((gateId) => blockedSet.has(gateId) && !passedSet.has(gateId))
     };
     const changed = !sameStringArray(before.required, after.required) ||
+        !sameStringArray(before.recommended, after.recommended) ||
+        !sameStringArray(before.conditional, after.conditional) ||
+        !sameStringArray(before.triggered, after.triggered) ||
         !sameStringArray(before.passed, after.passed) ||
         !sameStringArray(before.blocked, after.blocked);
     const nextState = changed

package/dist/harness-adapters.d.ts

@@ -4,8 +4,15 @@ export declare const CCLAW_MARKER_END = "<!-- cclaw-end -->";
 export interface HarnessAdapter {
     id: HarnessId;
     commandDir: string;
+    capabilities: {
+        nativeSubagentDispatch: "full" | "partial" | "none";
+        hookSurface: "full" | "plugin" | "limited" | "none";
+        structuredAsk: "AskUserQuestion" | "AskQuestion" | "plain-text";
+    };
 }
 export declare const HARNESS_ADAPTERS: Record<HarnessId, HarnessAdapter>;
+export type HarnessTier = "tier1" | "tier2" | "tier3";
+export declare function harnessTier(harnessId: HarnessId): HarnessTier;
 /** Removes the cclaw AGENTS.md block. */
 export declare function stripCclawBlock(content: string): string;
 export declare function removeCclawFromAgentsMd(projectRoot: string): Promise<void>;

package/dist/harness-adapters.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
-import { CCLAW_AGENTS, agentMarkdown } from "./content/agents.js";
+import { CCLAW_AGENTS, agentMarkdown } from "./content/core-agents.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 export const CCLAW_MARKER_START = "<!-- cclaw-start -->";
 export const CCLAW_MARKER_END = "<!-- cclaw-end -->";
@@ -12,11 +12,57 @@ const RUNTIME_AGENTS_BLOCK_SOURCE = `${escapeRegExp(CCLAW_MARKER_START)}[\\s\\S]
 const RUNTIME_AGENTS_BLOCK_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOURCE, "u");
 const RUNTIME_AGENTS_BLOCK_GLOBAL_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOURCE, "gu");
 export const HARNESS_ADAPTERS = {
-    claude: { id: "claude", commandDir: ".claude/commands" },
-    cursor: { id: "cursor", commandDir: ".cursor/commands" },
-    opencode: { id: "opencode", commandDir: ".opencode/commands" },
-    codex: { id: "codex", commandDir: ".codex/commands" }
+    claude: {
+        id: "claude",
+        commandDir: ".claude/commands",
+        capabilities: {
+            nativeSubagentDispatch: "full",
+            hookSurface: "full",
+            structuredAsk: "AskUserQuestion"
+        }
+    },
+    cursor: {
+        id: "cursor",
+        commandDir: ".cursor/commands",
+        capabilities: {
+            nativeSubagentDispatch: "partial",
+            hookSurface: "full",
+            structuredAsk: "AskQuestion"
+        }
+    },
+    opencode: {
+        id: "opencode",
+        commandDir: ".opencode/commands",
+        capabilities: {
+            nativeSubagentDispatch: "partial",
+            hookSurface: "plugin",
+            structuredAsk: "plain-text"
+        }
+    },
+    codex: {
+        id: "codex",
+        commandDir: ".codex/commands",
+        capabilities: {
+            nativeSubagentDispatch: "none",
+            hookSurface: "full",
+            structuredAsk: "plain-text"
+        }
+    }
 };
+export function harnessTier(harnessId) {
+    const capabilities = HARNESS_ADAPTERS[harnessId].capabilities;
+    if (capabilities.nativeSubagentDispatch === "full" &&
+        capabilities.structuredAsk !== "plain-text" &&
+        capabilities.hookSurface === "full") {
+        return "tier1";
+    }
+    if (capabilities.hookSurface === "full" ||
+        capabilities.hookSurface === "plugin" ||
+        capabilities.nativeSubagentDispatch === "partial") {
+        return "tier2";
+    }
+    return "tier3";
+}
 function agentsMdBlock() {
     return `${CCLAW_MARKER_START}
 ## Cclaw — Workflow Adapter
@@ -63,10 +109,6 @@ When in doubt, prefer **non-trivial** — the quick track is opt-in and only saf
 **Stage order:** brainstorm > scope > design > spec > plan > tdd > review > ship.
 \`/cc-next\` loads the right stage skill automatically. Gates must pass before handoff.
 
-### Invocation Preamble (non-trivial turns)
-
-Before starting substantive work, emit a one-paragraph preamble: **Stage**, **Goal**, **Plan** (next 1–3 actions), **Guardrails**. Skip for pure questions, trivial edits, and dispatched subagent invocations.
-
 ### Verification Discipline
 
 No completion claims without fresh evidence. No "Done" / "All good" / "Tests pass" without running the command in this message. Failed tool calls are diagnostic data, not instructions.
@@ -78,7 +120,9 @@ If the same approach fails three times in a row (same command, same finding, sam
 ### Detail Level
 
 - This managed AGENTS block is intentionally minimal for cross-project use.
+- Harness coverage is tiered: Tier1 (claude), Tier2 (cursor/opencode/codex), Tier3 (fallback/manual-only).
 - Detailed operating procedures live in \`.cclaw/skills/using-cclaw/SKILL.md\`.
+- Preamble budget and cooldown rules live in \`.cclaw/references/protocols/ethos.md\`.
 - Subagent orchestration patterns: \`.cclaw/skills/subagent-dev/SKILL.md\` and \`.cclaw/skills/parallel-dispatch/SKILL.md\`.
 ${CCLAW_MARKER_END}`;
 }

package/dist/init-detect.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessId } from "./types.js";
+export declare function detectHarnesses(projectRoot: string): Promise<HarnessId[]>;