cclaw-cli 0.49.0 → 0.51.0

package/dist/run-persistence.js

@@ -1,8 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
-import { canTransition, createInitialCloseoutState, createInitialFlowState, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
-import { ensureFeatureSystem, syncActiveFeatureSnapshot } from "./feature-system.js";
+import { canTransition, createInitialCloseoutState, createInitialFlowState, FLOW_STATE_SCHEMA_VERSION, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { FLOW_STAGES } from "./types.js";
 export class InvalidStageTransitionError extends Error {
@@ -283,6 +282,7 @@ function coerceFlowState(parsed) {
         ? activeRunIdRaw.trim()
         : next.activeRunId;
     return {
+        schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         activeRunId,
         currentStage: isFlowStage(parsed.currentStage) ? parsed.currentStage : next.currentStage,
         completedStages: sanitizeCompletedStages(parsed.completedStages),
@@ -334,9 +334,7 @@ async function quarantineCorruptState(statePath, cause) {
     throw new CorruptFlowStateError(statePath, quarantinedPath, cause);
 }
 export async function readFlowState(projectRoot, options = {}) {
-    if (options.repairFeatureSystem !== false) {
-        await ensureFeatureSystem(projectRoot);
-    }
+    void options;
     const statePath = flowStatePath(projectRoot);
     if (!(await exists(statePath))) {
         return createInitialFlowState();
@@ -361,7 +359,6 @@ export async function readFlowState(projectRoot, options = {}) {
     return coerceFlowState(parsed);
 }
 export async function writeFlowState(projectRoot, state, options = {}) {
-    await ensureFeatureSystem(projectRoot);
     const doWrite = async () => {
         const statePath = flowStatePath(projectRoot);
         if (!options.allowReset && (await exists(statePath))) {
@@ -389,7 +386,6 @@ export async function writeFlowState(projectRoot, state, options = {}) {
     else {
         await withDirectoryLock(flowStateLockPath(projectRoot), doWrite);
     }
-    await syncActiveFeatureSnapshot(projectRoot);
 }
 /**
  * Exposed path helper so callers that need to serialize a multi-step
@@ -400,7 +396,6 @@ export function flowStateLockPathFor(projectRoot) {
     return flowStateLockPath(projectRoot);
 }
 export async function ensureRunSystem(projectRoot, _options = {}) {
-    await ensureFeatureSystem(projectRoot);
     await ensureDir(runsRoot(projectRoot));
     await ensureDir(activeArtifactsPath(projectRoot));
     const statePath = flowStatePath(projectRoot);
@@ -408,6 +403,5 @@ export async function ensureRunSystem(projectRoot, _options = {}) {
     if (!(await exists(statePath))) {
         await writeFlowState(projectRoot, state, { allowReset: true });
     }
-    await syncActiveFeatureSnapshot(projectRoot);
     return state;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {
@@ -40,7 +40,6 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "openai": "^4.104.0",
     "yaml": "^2.8.1"
   },
   "devDependencies": {

package/dist/content/archive-command.d.ts

@@ -1,2 +0,0 @@
-export declare function archiveCommandContract(): string;
-export declare function archiveCommandSkillMarkdown(): string;

package/dist/content/archive-command.js

@@ -1,124 +0,0 @@
-import { RUNTIME_ROOT } from "../constants.js";
-const ARCHIVE_SKILL_FOLDER = "flow-archive";
-const ARCHIVE_SKILL_NAME = "flow-archive";
-function flowStatePath() {
-    return `${RUNTIME_ROOT}/state/flow-state.json`;
-}
-function runsPath() {
-    return `${RUNTIME_ROOT}/runs`;
-}
-function activeArtifactsPath() {
-    return `${RUNTIME_ROOT}/artifacts`;
-}
-export function archiveCommandContract() {
-    return `# /cc-ops archive
-
-## Purpose
-
-Finalize the active cclaw run: move artifacts to \`${runsPath()}/<archive-id>\`,
-snapshot state, write a manifest, and reset runtime for the next run.
-
-Auto-triggered by \`/cc-next\` when \`closeout.shipSubstate === "ready_to_archive"\`.
-Direct invocation from a harness command is supported but rarely needed.
-
-## HARD-GATE
-
-- Do not archive with \`closeout.shipSubstate !== "ready_to_archive"\`.
-- Do not archive a shipped run when \`retro.completedAt\` is missing and
-  \`closeout.retroSkipped !== true\`.
-- Never hand-move files between \`${activeArtifactsPath()}\` and \`${runsPath()}\`.
-  Always run the archive runtime command so the snapshot+manifest stay
-  atomic.
-
-## Inputs
-
-\`/cc-ops archive [--name=<slug>]\`
-
-(Legacy flags \`--skip-retro --retro-reason=<text>\` still exist for CLI
-invocations; in-harness the skip path is driven by \`closeout.retroSkipped\`
-set during retro.)
-
-## Algorithm
-
-1. Read \`${flowStatePath()}\`.
-2. Verify \`closeout.shipSubstate === "ready_to_archive"\`. If not, report
-   \`closeout not ready (state=<substate>) | run: /cc-next\` and stop.
-3. Build archive command:
-   - base: \`npx cclaw archive\`,
-   - optional: \`--name=<slug>\`,
-   - legacy override: \`--skip-retro --retro-reason=<text>\` (only when user
-     explicitly wants the CLI skip path).
-4. Execute the archive command in project root.
-5. On success, flow-state is reset to the initial stage for the default
-   track; \`closeout.shipSubstate\` returns to \`"idle"\` on reset.
-6. Surface:
-   - archive id/path,
-   - reset stage,
-   - knowledge curation hint when \`activeEntryCount >= softThreshold\`.
-
-## Output format
-
-\`\`\`
-cclaw archive
-  status: archived
-  run: <archive-id>
-  path: .cclaw/runs/<archive-id>
-  next: /cc <new-idea>
-\`\`\`
-
-## Primary skill
-
-**${RUNTIME_ROOT}/skills/${ARCHIVE_SKILL_FOLDER}/SKILL.md**
-`;
-}
-export function archiveCommandSkillMarkdown() {
-    return `---
-name: ${ARCHIVE_SKILL_NAME}
-description: "Finalize the active cclaw run. Auto-triggered by /cc-next when shipSubstate=ready_to_archive."
----
-
-# /cc-ops archive
-
-## HARD-GATE
-
-Never simulate archive by hand-editing runtime files. Always execute the
-archive runtime command so state snapshots and manifest generation stay
-atomic. Never bypass the substate check — if retro/compound haven't
-advanced the substate to \`ready_to_archive\`, stop and surface the
-mismatch.
-
-## Protocol
-
-1. Read \`${flowStatePath()}\`:
-   - if \`closeout.shipSubstate !== "ready_to_archive"\`, stop and route
-     the user back to \`/cc-next\` (it will resume at the correct step),
-   - sanity-check: \`completedStages\` must include \`"ship"\`,
-   - sanity-check: \`retro.completedAt\` is set **or**
-     \`closeout.retroSkipped === true\` with a reason.
-2. Build shell command:
-   - \`npx cclaw archive\`,
-   - append \`--name=<slug>\` when provided,
-   - append legacy \`--skip-retro --retro-reason=<text>\` only when the user
-     explicitly requests the CLI skip path (normally not needed — skip is
-     captured in \`closeout\` during retro).
-3. Run command from repo root.
-4. Relay key lines from output:
-   - archive destination under \`${runsPath()}\`,
-   - flow reset confirmation,
-   - knowledge curation recommendation if \`activeEntryCount >= 50\`.
-
-## Resume semantics
-
-Archive is idempotent on a per-run basis. If a previous session ran
-archive successfully, the active artifacts directory is empty and
-\`closeout.shipSubstate\` is \`"idle"\`; \`/cc-next\` will simply report
-"Flow complete" or prompt for a new \`/cc\` input.
-
-## Validation
-
-- \`${runsPath()}\` contains a new archive folder for this run.
-- \`${activeArtifactsPath()}\` is reset for the next run.
-- \`${flowStatePath()}\` is valid JSON and points to the initial stage.
-- \`closeout.shipSubstate === "idle"\` after reset.
-`;
-}

package/dist/content/compound-command.d.ts

@@ -1,5 +0,0 @@
-export interface CompoundCommandOptions {
-    recurrenceThreshold?: number;
-}
-export declare function compoundCommandContract(options?: CompoundCommandOptions): string;
-export declare function compoundCommandSkillMarkdown(options?: CompoundCommandOptions): string;

package/dist/content/compound-command.js

@@ -1,193 +0,0 @@
-import { RUNTIME_ROOT } from "../constants.js";
-const COMPOUND_SKILL_FOLDER = "flow-compound";
-const COMPOUND_SKILL_NAME = "flow-compound";
-const DEFAULT_RECURRENCE_THRESHOLD = 3;
-const SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD = 5;
-const SMALL_PROJECT_RECURRENCE_THRESHOLD = 2;
-function resolveRecurrenceThreshold(options) {
-    const threshold = options.recurrenceThreshold;
-    if (typeof threshold === "number" && Number.isInteger(threshold) && threshold >= 1) {
-        return threshold;
-    }
-    return DEFAULT_RECURRENCE_THRESHOLD;
-}
-export function compoundCommandContract(options = {}) {
-    const recurrenceThreshold = resolveRecurrenceThreshold(options);
-    return `# /cc-ops compound
-
-## Purpose
-
-Lift repeated lessons from \`${RUNTIME_ROOT}/knowledge.jsonl\` into durable
-project assets (rules, protocols, skills) so the next run is easier and safer.
-
-Auto-triggered by \`/cc-next\` when \`closeout.shipSubstate === "compound_review"\`.
-Direct invocation is supported but rarely needed.
-
-## HARD-GATE
-
-- Do not mutate rules/skills/protocols without explicit user approval.
-- Every proposal must cite concrete knowledge evidence (line refs or IDs).
-- Keep scope focused: one compound change set per run.
-- Do not block the archive step if no clusters qualify — record an empty
-  compound pass and advance.
-
-## Inputs
-
-\`/cc-ops compound\` (no flags). The structured ask presents candidates;
-the user can approve individual lifts, accept-all, or skip.
-
-## Algorithm
-
-1. Read \`${RUNTIME_ROOT}/knowledge.jsonl\` (strict JSONL, one entry per line).
-2. Cluster entries by \`trigger\` + \`action\` similarity.
-3. Resolve recurrence policy:
-   - base threshold = \`${recurrenceThreshold}\` (from \`config.compound.recurrenceThreshold\`),
-   - count archived runs under \`${RUNTIME_ROOT}/runs/\`,
-   - if archived run count is < ${SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD}, use
-     effective threshold = \`min(base threshold, ${SMALL_PROJECT_RECURRENCE_THRESHOLD})\` for this pass.
-4. Filter candidates that satisfy at least one trigger:
-   - recurrence count >= effective threshold, or
-   - any knowledge entry in the cluster has \`severity: "critical"\`
-     (critical override, recurrence can be 1).
-5. If **no candidates** exist:
-   - set \`closeout.compoundCompletedAt = <ISO>\`,
-   - set \`closeout.compoundPromoted = 0\`,
-   - set \`closeout.shipSubstate = "ready_to_archive"\`,
-   - emit \`compound: no candidates | next: /cc-next\` and stop.
-6. **Drift check** each surviving candidate before presenting it (see
-   "Drift check" section in the skill): confirm the lift target file is
-   current, spot-check the repo for contradictions, demote stale clusters
-   into a new superseding entry instead of a lift.
-7. Otherwise, present **one** structured ask via the harness's native ask
-   tool (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` /
-   \`request_user_input\`; plain-text lettered list as fallback) summarising
-   all candidates at once:
-   - \`apply-all\` (default) — apply every listed lift,
-   - \`apply-selected\` — prompt per-candidate,
-   - \`skip\` — record a skip reason and advance without changes.
-8. Apply approved lifts to the target file(s). Each lift also appends a
-   \`type: "compound"\` entry back to \`${RUNTIME_ROOT}/knowledge.jsonl\`
-   summarising what was lifted.
-9. Update flow-state:
-   - \`closeout.compoundCompletedAt = <ISO>\`,
-   - \`closeout.compoundPromoted = <count>\`,
-   - \`closeout.compoundSkipped = true\` if user picked skip,
-   - \`closeout.shipSubstate = "ready_to_archive"\`.
-10. Emit one-line summary: \`compound: promoted=<N> skipped=<bool> | next: /cc-next\`.
-
-## Primary skill
-
-**${RUNTIME_ROOT}/skills/${COMPOUND_SKILL_FOLDER}/SKILL.md**
-`;
-}
-export function compoundCommandSkillMarkdown(options = {}) {
-    const recurrenceThreshold = resolveRecurrenceThreshold(options);
-    return `---
-name: ${COMPOUND_SKILL_NAME}
-description: "Lift repeated learnings into durable rules/protocols/skills. Auto-triggered after retro accept."
----
-
-# /cc-ops compound
-
-## Announce at start
-
-"Using flow-compound to lift repeated learnings into durable workflow assets."
-
-## HARD-GATE
-
-No silent codification. Every lift requires explicit user approval. An
-empty pass is allowed and must advance \`closeout.shipSubstate\` to
-\`"ready_to_archive"\`.
-
-## Protocol
-
-1. Parse \`.cclaw/knowledge.jsonl\` and group repeated lessons by
-   trigger+action similarity.
-2. Resolve recurrence policy:
-   - base threshold = \`${recurrenceThreshold}\` from \`config.compound.recurrenceThreshold\`,
-   - count archived runs under \`.cclaw/runs/\`,
-   - if archived run count is < ${SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD}, use
-     effective threshold = \`min(base threshold, ${SMALL_PROJECT_RECURRENCE_THRESHOLD})\` for this pass.
-3. Keep only candidates that meet at least one trigger:
-   - recurrence >= effective threshold and actionable lift path, or
-   - a cluster entry with \`severity: critical\` (critical override, recurrence can be 1).
-4. If none qualify, record an empty pass:
-   - \`closeout.compoundCompletedAt = <ISO>\`,
-   - \`closeout.compoundPromoted = 0\`,
-   - \`closeout.shipSubstate = "ready_to_archive"\`,
-   - announce \`compound: no candidates\` and stop.
-5. **Drift check — run before presenting any candidate.** Knowledge lines
-   are append-only, so textual repetition alone does not prove the rule is
-   still true. For every cluster that survives the recurrence filter:
-
-   - **Read the lift target.** Open the rule/protocol/skill file you would
-     edit. If the current contents already encode a stronger version of
-     the cluster's \`action\`, drop the candidate (nothing to lift).
-   - **Grep for contradictions.** Run a quick repo search on the cluster's
-     \`trigger\` keywords. If recent code or docs contradict the cluster,
-     treat the cluster as stale.
-   - **Check age.** Inspect \`last_seen_ts\` across the cluster's lines. If
-     every contributing line is older than ~90 days with no fresh
-     observation, treat the cluster as stale.
-   - **Handle stale clusters correctly.** Do **not** silently skip them.
-     Append a new superseding \`type: "lesson"\` line to
-     \`.cclaw/knowledge.jsonl\` whose \`trigger\` explicitly references the
-     old pattern (e.g. \`"when previous rule about X no longer holds: ..."\`)
-     and whose \`action\` documents the replacement or archive reason.
-     Then drop the candidate from the lift list.
-   - **Cite line IDs.** Every surviving candidate must list the concrete
-     knowledge line indices (1-based) that back it, not just a
-     summary string. This is what makes the lift auditable.
-   - **Include qualification reason.** Mark each candidate as
-     \`recurrence\` or \`critical_override\` so reviewers can see why it passed
-     the filter.
-   - Optionally invoke the \`knowledge-curation\` utility skill's
-     stale/duplicate/supersede heuristics if you want a second pass.
-
-6. Otherwise, render each candidate as:
-
-\`\`\`
-Candidate: <short title>
-Qualification: <recurrence|critical_override>
-Evidence: <knowledge line-ids>
-Freshness: <newest last_seen_ts among evidence lines>
-Lift target: <rule/protocol/skill file>
-Change type: <add/update/remove>
-Expected benefit: <what regressions this prevents>
-\`\`\`
-
-7. Present **one** structured question with three options:
-   - \`apply-all\` (default) — apply every candidate,
-   - \`apply-selected\` — prompt per-candidate approval next,
-   - \`skip\` — record a skip reason and advance.
-
-8. For approved candidates:
-   - edit the target file(s) with the lift,
-   - append a \`type: "compound"\` entry to \`.cclaw/knowledge.jsonl\`
-     describing what was promoted, including the source line IDs.
-
-9. Update flow-state \`closeout\`:
-   - \`compoundCompletedAt\`,
-   - \`compoundPromoted\` (count),
-   - \`compoundSkipped\` (boolean) + \`compoundSkipReason\` when applicable,
-   - \`shipSubstate = "ready_to_archive"\`.
-
-## Resume semantics
-
-A new session with \`shipSubstate === "compound_review"\` re-runs the scan
-and re-asks the structured question. If the user already applied lifts in
-a previous session but the state file was not updated, they should pick
-\`skip\` with reason \`already-applied\` — compound is idempotent from the
-closeout chain's perspective.
-
-## Validation
-
-- \`closeout.compoundCompletedAt\` is set.
-- \`closeout.shipSubstate === "ready_to_archive"\`.
-- If lifts were applied, the target files show the edit and at least one
-  new \`compound\` line exists in \`.cclaw/knowledge.jsonl\`, and the new
-  line references the source knowledge line IDs.
-- If drift check demoted any cluster, a new superseding \`lesson\` line
-  exists on the same run documenting the replacement.
-`;
-}

package/dist/content/contexts.d.ts

@@ -1,18 +0,0 @@
-export declare const DEFAULT_CONTEXT_MODE = "default";
-/**
- * Valid context mode identifiers used by the session hooks and the
- * `context-engineering` skill. Mode bodies no longer live as separate
- * `.cclaw/contexts/<mode>.md` files — the guidance was merged into the
- * `context-engineering` skill. This list only exists so `doctor` can
- * validate that `state/context-mode.json#activeMode` references a known
- * mode name.
- */
-export declare const AVAILABLE_CONTEXT_MODES: readonly ["default", "execution", "review", "incident"];
-/** Legacy alias: kept so existing imports keep typechecking. */
-export declare const CONTEXT_MODES: Record<string, true>;
-export interface ContextModeState {
-    activeMode: string;
-    updatedAt: string;
-    availableModes: string[];
-}
-export declare function createInitialContextModeState(nowIso?: string): ContextModeState;

package/dist/content/contexts.js

@@ -1,24 +0,0 @@
-export const DEFAULT_CONTEXT_MODE = "default";
-/**
- * Valid context mode identifiers used by the session hooks and the
- * `context-engineering` skill. Mode bodies no longer live as separate
- * `.cclaw/contexts/<mode>.md` files — the guidance was merged into the
- * `context-engineering` skill. This list only exists so `doctor` can
- * validate that `state/context-mode.json#activeMode` references a known
- * mode name.
- */
-export const AVAILABLE_CONTEXT_MODES = [
-    "default",
-    "execution",
-    "review",
-    "incident"
-];
-/** Legacy alias: kept so existing imports keep typechecking. */
-export const CONTEXT_MODES = Object.fromEntries(AVAILABLE_CONTEXT_MODES.map((mode) => [mode, true]));
-export function createInitialContextModeState(nowIso = new Date().toISOString()) {
-    return {
-        activeMode: DEFAULT_CONTEXT_MODE,
-        updatedAt: nowIso,
-        availableModes: [...AVAILABLE_CONTEXT_MODES]
-    };
-}

package/dist/content/contracts.d.ts

@@ -1,2 +0,0 @@
-import type { FlowStage, FlowTrack } from "../types.js";
-export declare function stageCommandContract(stage: FlowStage, track?: FlowTrack): string;

package/dist/content/contracts.js

@@ -1,51 +0,0 @@
-import { stagePolicyNeedles, stageSchema } from "./stage-schema.js";
-import { stageSkillFolder } from "./skills.js";
-export function stageCommandContract(stage, track = "standard") {
-    const schema = stageSchema(stage, track);
-    const skillPath = `.cclaw/skills/${stageSkillFolder(stage)}/SKILL.md`;
-    const reads = schema.crossStageTrace.readsFrom;
-    const readsLine = reads.length > 0 ? reads.join(", ") : "(first stage)";
-    const hydrationLines = reads.length > 0
-        ? reads.map((readPath) => `- \`${readPath}\``).join("\n")
-        : "- (first stage — no upstream artifacts)";
-    const gateIds = schema.requiredGates
-        .map((g) => `\`${g.id}\``)
-        .join(", ");
-    const writes = schema.crossStageTrace.writesTo;
-    const writesLine = writes.map((w) => `\`${w}\``).join(", ");
-    const primaryArtifact = `.cclaw/artifacts/${schema.artifactFile}`;
-    const writeStepPaths = writes.length > 1
-        ? writes.map((w) => `\`${w}\``).join(" and ")
-        : `\`${primaryArtifact}\``;
-    const policyNeedles = stagePolicyNeedles(stage, track);
-    return `# /cc-${stage}
-
-Load and follow **${skillPath}** — it contains the full checklist, examples, interaction protocol, and verification discipline.
-
-## HARD-GATE
-${schema.hardGate}
-
-## In / Out
-- **Reads:** ${readsLine}
-- **Writes:** ${writesLine}
-- **Next:** \`/cc-next\` (updates flow-state and loads the next stage)
-
-## Context Hydration (mandatory before stage work)
-1. Read \`.cclaw/state/flow-state.json\`.
-2. Resolve active artifact root: \`.cclaw/artifacts/\`.
-3. Load required upstream artifacts for this stage:
-${hydrationLines}
-4. Stream \`.cclaw/knowledge.jsonl\` and apply relevant JSON-line entries (strict schema: type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project; optional: source, severity).
-5. Write stage output to ${writeStepPaths}.
-6. Do NOT copy artifacts into \`.cclaw/runs/\`; archival is handled by \`/cc-ops archive\` (agent-facing wrapper over archive runtime).
-
-## Gates
-${gateIds}
-
-## Exit
-${schema.exitCriteria.map((v) => `- ${v}`).join("\n")}
-
-## Anchors
-${policyNeedles.map((v) => `- ${v}`).join("\n")}
-`;
-}

package/dist/content/doctor-references.d.ts

@@ -1,2 +0,0 @@
-export declare const DOCTOR_REFERENCE_DIR = ".cclaw/references/doctor";
-export declare const DOCTOR_REFERENCE_MARKDOWN: Record<string, string>;

package/dist/content/doctor-references.js

@@ -1,150 +0,0 @@
-import { RUNTIME_ROOT } from "../constants.js";
-export const DOCTOR_REFERENCE_DIR = `${RUNTIME_ROOT}/references/doctor`;
-export const DOCTOR_REFERENCE_MARKDOWN = {
-    "README.md": `# Doctor Reference Index
-
-Reference docs for \`cclaw doctor\` checks.
-
-## Categories
-
-- \`runtime-layout.md\` - runtime directories, generated commands, and skill files
-- \`hooks-and-lifecycle.md\` - hook wiring and harness lifecycle integration
-- \`harness-and-routing.md\` - harness shims, AGENTS/CLAUDE routing blocks, cursor rule
-- \`state-and-gates.md\` - flow-state integrity and gate evidence contracts
-- \`delegation-and-preamble.md\` - mandatory delegations and lightweight announce discipline
-- \`traceability.md\` - spec/plan/tdd trace matrix expectations
-- \`tooling-capabilities.md\` - local runtime prerequisites (node only)
-- \`config-and-policy.md\` - config schema, rules policy, and validation references
-`,
-    "runtime-layout.md": `# Runtime Layout
-
-## Expected surfaces
-
-- \`.cclaw/\` root and generated subdirectories
-- stage command contracts under \`.cclaw/commands/\`
-- stage skills under \`.cclaw/skills/\`
-- utility command contracts (\`start\`, \`next\`, \`learn\`, \`status\`)
-- state files under \`.cclaw/state/\`
-
-## Typical fixes
-
-1. Run \`cclaw sync\` to re-materialize generated assets.
-2. If runtime is severely drifted, run \`cclaw upgrade\`.
-3. Avoid manual edits under generated runtime paths unless explicitly supported.
-`,
-    "hooks-and-lifecycle.md": `# Hooks And Lifecycle
-
-## Expected behavior
-
-- session start rehydrates flow + knowledge digest
-- pre-tool hooks run prompt/workflow guards
-- post-tool hooks run context monitor
-- stop hooks checkpoint progress
-- OpenCode uses plugin-based lifecycle integration
-
-## Typical fixes
-
-1. Re-run \`cclaw sync\` after harness config changes.
-2. Ensure harness is enabled in \`.cclaw/config.yaml\`.
-3. Validate hook JSON shape and remove malformed manual edits.
-`,
-    "harness-and-routing.md": `# Harness And Routing
-
-## Expected behavior
-
-- command shims exist for every enabled harness
-- managed routing block is present in \`AGENTS.md\` (and \`CLAUDE.md\` when applicable)
-- cursor rule mirrors workflow activation guidance
-- opencode plugin path is registered in opencode config
-
-## Typical fixes
-
-1. Confirm \`harnesses\` list in \`.cclaw/config.yaml\`.
-2. Run \`cclaw sync\` to re-generate shims/routing files.
-3. Remove stale harness artifacts for disabled harnesses via \`cclaw sync\`.
-`,
-    "state-and-gates.md": `# State And Gates
-
-## Expected behavior
-
-- \`flow-state.json\` has activeRunId, current stage, and consistent track/skippedStages
-- current-stage gate evidence is internally consistent
-- completed stages only include passed required gates
-
-## Typical fixes
-
-1. Run \`cclaw doctor --reconcile-gates\` to refresh current-stage gate catalog.
-2. Repair inconsistent stage artifacts, then re-run doctor.
-3. Do not manually mutate gate arrays without matching artifact evidence.
-`,
-    "delegation-and-preamble.md": `# Delegation And Preamble
-
-## Delegation contract
-
-- mandatory delegations for the current stage must be completed or waived
-- waivers should include an explicit reason
-- stale entries from previous runs are ignored by current-run checks
-- delegation entries use span-compatible fields (\`spanId\`, \`startTs\`, \`endTs\`, \`retryCount\`, \`evidenceRefs\`)
-
-## Announce discipline contract
-
-- no dedicated preamble runtime log is required
-- substantial turns should still start with a concise announce (stage + goal + next action)
-- do not spam repeated announces when intent did not change
-
-## Typical fixes
-
-1. Append missing delegation records with \`completed\` or \`waived\` status.
-2. Record harness-limitation waivers when native delegation is unavailable.
-3. Keep announces concise and only refresh when plan/risk materially changes.
-`,
-    "traceability.md": `# Traceability
-
-## Expected behavior
-
-- spec criteria map to plan tasks
-- plan tasks map to tdd slices/tests
-- no orphaned criteria/tasks/tests when downstream artifacts exist
-
-## Typical fixes
-
-1. Add stable IDs to spec/plan/tdd sections.
-2. Ensure mapping tables include every active criterion/task/slice.
-3. Re-run \`cclaw doctor\` after artifact updates.
-`,
-    "tooling-capabilities.md": `# Tooling Capabilities
-
-## Required
-
-- \`node\` (>=20) — the only runtime dependency. All hooks, git-hook relays, and the
-  \`cclaw\` CLI itself run on Node.js. No \`bash\`, \`python3\`, or \`jq\` required.
-- \`git\` — needed for worktree and pre-commit/pre-push relays.
-
-## Not required (removed)
-
-Earlier releases relied on \`bash\` to execute generated shell hooks and on
-\`python3\`/\`jq\` as JSON fallback parsers. Node-only mode removes both: hooks
-dispatch through \`.cclaw/hooks/run-hook.cmd <hook-name>\` (which forwards to
-Node), so these tools
-are no longer part of the supported runtime contract.
-
-## Typical fixes
-
-1. Install Node.js 20 or newer (matches \`package.json\` \`engines\`) and ensure \`node\` is on \`PATH\`.
-2. Re-run \`cclaw sync\` to regenerate hook configs after upgrading Node.
-`,
-    "config-and-policy.md": `# Config And Policy
-
-## Expected behavior
-
-- \`.cclaw/config.yaml\` parses and uses supported keys/values
-- \`.cclaw/rules/rules.json\` matches generated policy schema
-- policy needles and required sections remain present in generated contracts
-
-## Typical fixes
-
-1. Repair invalid config values and run \`cclaw sync\`.
-2. Re-generate policy files via \`cclaw sync\` if drift is detected.
-3. Keep generated contracts aligned with stage schemas and policy needles.
-`
-};