cadet-agent 0.27.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadet-agent",
-  "version": "0.27.0",
+  "version": "0.30.0",
   "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -1,434 +1,447 @@
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { install, sync } from './install.mjs';
-import {
-  validateState, migrateStateFile, readState, writeState, evaluateTransition, applyTransition,
-  workItemIdOf, loadPolicy, RunLedger, loadRun, listRuns, cleanupRuns, buildReport, formatReport,
-  runVerificationLoop, commandForGate, detectCapabilities, runsDir, gitChangedFiles, PolicyError, StateError,
-} from './harness/index.mjs';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-function getVersion() {
-  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
-  return pkg.version;
-}
-
-function showHelp() {
-  console.log(`
-  ██████╗ █████╗ ██████╗ ███████╗████████╗
-  ██╔════╝██╔══██╗██╔══██╗██╔════╝╚══██╔══╝
-  ██║     ███████║██║  ██║█████╗     ██║
-  ██║     ██╔══██║██║  ██║██╔══╝     ██║
-  ╚██████╗██║  ██║██████╔╝███████╗   ██║
-   ╚═════╝╚═╝  ╚═╝╚═════╝ ╚══════╝   ╚═╝
-
-  Cross-IDE agent framework for Unity/C# game-development
-
-  Usage:
-    npx cadet-agent@latest init     Install Cadet-Agent into the current directory
-    npx cadet-agent@latest init --target <dir>   Install into a specific directory
-    npx cadet-agent@latest sync     Update framework, preserving local policies/plans
-    npx cadet-agent@latest sync --target <dir>   Sync a specific directory
-
-    cadet-agent state validate      Validate .cadet/state.json against the v2 schema
-    cadet-agent state migrate       Atomically migrate v1 state to v2 (backup on write)
-    cadet-agent state transition --to <phase>   Enforce the transition matrix + evidence
-
-    cadet-agent harness record      Append a sanitized span/evidence/decision event
-    cadet-agent harness verify      Run a bounded, classified verification loop
-    cadet-agent harness report      Summarize budget consumption and failures
-    cadet-agent harness cleanup     Apply the retention policy to .cadet/runs/
-    cadet-agent harness capabilities  Report available CLI/Unity/MCP/hook/token/cost telemetry
-
-  Options:
-    --target, -t  Target directory (default: current working directory)
-    --source       Release API URL override (for forked deployments)
-    --format       human|json (default: human)
-    --to           Target phase (state transition)
-    --gate         Gate name (harness verify)
-    --command      Command override (harness verify)
-    --files        Comma-separated relevant files to bind evidence to (harness verify)
-    --agents-md    keep|overwrite|merge for an existing AGENTS.md (init/sync)
-    --yes, -y      Never prompt; keep existing files (non-interactive installs)
-    --help, -h    Show this help
-    --version, -v Show version number
-`);
-}
-
-function parseArgs(argv) {
-  const opts = { format: 'human', targetDir: process.cwd(), sourceUrl: null, rest: [] };
-  // argv[2] is the top-level command (`state`/`harness`/`init`/...); argv[3] begins
-  // the subcommand and its options.
-  for (let i = 3; i < argv.length; i++) {
-    const a = argv[i];
-    switch (a) {
-      case '--target': case '-t': opts.targetDir = argv[++i]; break;
-      case '--source': opts.sourceUrl = argv[++i]; break;
-      case '--format': opts.format = argv[++i] || 'human'; break;
-      case '--to': opts.to = argv[++i]; break;
-      case '--gate': opts.gate = argv[++i]; break;
-      case '--command': opts.command = argv[++i]; break;
-      case '--work-item': opts.workItemId = argv[++i]; break;
-      case '--phase': opts.phase = argv[++i]; break;
-      case '--run': opts.runId = argv[++i]; break;
-      case '--type': opts.type = argv[++i]; break;
-      case '--reason': opts.reason = argv[++i]; break;
-      case '--evidence-status': opts.evidenceStatus = argv[++i]; break;
-      case '--files': opts.files = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
-      case '--older-than-ms': opts.olderThanMs = Number(argv[++i]); break;
-      case '--agents-md': opts.agentsMd = argv[++i]; break;
-      case '--yes': case '-y': opts.yes = true; break;
-      default: opts.rest.push(a);
-    }
-  }
-  return opts;
-}
-
-function emit(opts, human, json) {
-  if (opts.format === 'json') {
-    console.log(JSON.stringify(json, null, 2));
-  } else {
-    console.log(human);
-  }
-}
-
-function fail(opts, message, code = json => json.exitCode || 1, json = {}) {
-  const exitCode = code(json);
-  if (opts.format === 'json') {
-    console.error(JSON.stringify({ ok: false, error: message, ...json }, null, 2));
-  } else {
-    console.error(`\n❌ ${message}`);
-  }
-  process.exit(exitCode);
-}
-
-// ── state commands ──────────────────────────────────────────────────────────
-
-async function cmdState(opts) {
-  const sub = opts.rest[0];
-  const statePath = join(opts.targetDir, '.cadet', 'state.json');
-
-  if (sub === 'validate') {
-    const { exists, state } = readState(opts.targetDir);
-    if (!exists) {
-      emit(opts, 'No .cadet/state.json found (nothing to validate).', { ok: true, valid: true, exists: false });
-      return;
-    }
-    // Pass rootDir so stale/foreign evidence is caught at validation time.
-    const result = validateState(state, { rootDir: opts.targetDir });
-    if (opts.format === 'json') {
-      emit(opts, '', { ok: result.valid, valid: result.valid, errors: result.errors, warnings: result.warnings });
-    } else {
-      if (result.valid) console.log(`✅ state.json is valid (v${state.version}).`);
-      else {
-        console.error('❌ state.json is invalid:');
-        for (const e of result.errors) console.error(`   ${e.path}: ${e.message}`);
-      }
-      for (const w of result.warnings) console.log(`   ⚠️  ${w.path}: ${w.message}`);
-    }
-    if (!result.valid) process.exit(1);
-    return;
-  }
-
-  if (sub === 'migrate') {
-    const result = migrateStateFile(statePath, { backup: true });
-    if (opts.format === 'json') {
-      emit(opts, '', { ok: true, migrated: result.migrated, statePath: result.statePath });
-    } else if (result.migrated) {
-      console.log(`✅ Migrated ${statePath} to v2 (backup: ${statePath}.v1.bak).`);
-    } else {
-      console.log('✅ state.json is already v2 — nothing to migrate.');
-    }
-    return;
-  }
-
-  if (sub === 'transition') {
-    if (!opts.to) fail(opts, 'state transition requires --to <phase>');
-    const { exists, state } = readState(opts.targetDir);
-    if (!exists) fail(opts, 'No .cadet/state.json found. Initialise state before transitioning.', () => 2);
-    // Freshness is enforced against the current working tree: evaluateTransition
-    // recomputes each gate's input-tree hash from the evidence's relevant files.
-    const evaluation = evaluateTransition(state, opts.to, { rootDir: opts.targetDir });
-    if (!evaluation.allowed) {
-      const detail = {
-        ok: false,
-        allowed: false,
-        missingGates: evaluation.missingGates,
-        staleEvidence: evaluation.staleEvidence,
-        errors: evaluation.errors,
-      };
-      const lines = ['❌ Transition rejected:'];
-      for (const e of evaluation.errors) lines.push(`   ${e}`);
-      if (evaluation.missingGates.length) lines.push(`   missing gates/evidence: ${evaluation.missingGates.join(', ')}`);
-      for (const s of evaluation.staleEvidence) lines.push(`   stale: ${s.gate} — ${s.reason || (s.reasons || []).join('; ')}`);
-      if (opts.format === 'json') emit(opts, '', detail);
-      else console.error(lines.join('\n'));
-      process.exit(1);
-    }
-    const next = applyTransition(state, opts.to, { rootDir: opts.targetDir });
-    writeState(opts.targetDir, next);
-    emit(opts, `✅ Transitioned to ${opts.to}.`, { ok: true, allowed: true, to: opts.to });
-    return;
-  }
-
-  fail(opts, `Unknown state subcommand: ${sub || '(none)'}. Use validate|migrate|transition.`);
-}
-
-// ── harness commands ────────────────────────────────────────────────────────
-
-async function cmdHarness(opts) {
-  const sub = opts.rest[0];
-  const policy = loadPolicy(opts.targetDir);
-
-  if (sub === 'capabilities') {
-    const caps = detectCapabilities({ targetDir: opts.targetDir });
-    if (opts.format === 'json') emit(opts, '', { ok: true, capabilities: caps });
-    else {
-      console.log('Cadet-Agent capability report');
-      console.log(`  CLI:            ${caps.cli ? 'available' : 'unavailable'}`);
-      console.log(`  Unity CLI:      ${caps.unityCli.available ? `available (${caps.unityCli.version || 'version unknown'})` : 'unavailable — compile/analyzer gates fall back to manual confirmation'}`);
-      console.log(`  MCP:            ${caps.mcp.available ? 'configured' : 'unavailable — live inspection not available'}`);
-      console.log(`  Copilot hook:   ${caps.hook.copilot ? 'installed' : 'not installed'}`);
-      console.log(`  Token telemetry:${caps.tokenTelemetry.provider ? ' provider' : ' estimate/unknown'}`);
-      console.log(`  Cost telemetry: ${caps.costTelemetry.available ? 'available' : `unavailable (${caps.costTelemetry.reason})`}`);
-      console.log(`  Note: ${caps.hook.note}`);
-    }
-    return;
-  }
-
-  if (sub === 'record') {
-    const { state } = readState(opts.targetDir);
-    const ledger = new RunLedger({
-      targetDir: opts.targetDir,
-      policy,
-      runId: opts.runId || state?.activeRunId || null,
-      workItemId: opts.workItemId || (state ? workItemIdOf(state) : null),
-      phase: opts.phase || state?.session?.currentPhase || null,
-    });
-    const type = opts.type || 'tool-call';
-    const reason = opts.reason || opts.rest[1] || 'recorded event';
-    if (type === 'decision') {
-      ledger.addDecision({ kind: 'stop', reason });
-    } else if (type === 'verification') {
-      ledger.addSpan({ kind: 'verification', name: opts.gate || 'manual', status: opts.evidenceStatus || 'ok', reason });
-    } else {
-      ledger.addSpan({ kind: type, name: opts.gate || type, status: 'ok', reason, tool: opts.tool || null });
-    }
-    ledger.finalize();
-    const path = ledger.persist();
-    emit(opts, `✅ Recorded ${type} event in ${path}.`, { ok: true, runId: ledger.runId, path });
-    return;
-  }
-
-  if (sub === 'verify') {
-    const gate = opts.gate;
-    if (!gate) fail(opts, 'harness verify requires --gate <gate>');
-    const { state } = readState(opts.targetDir);
-    const caps = detectCapabilities({ targetDir: opts.targetDir });
-    const descriptor = opts.command
-      ? { command: opts.command, tool: 'custom', automated: true }
-      : commandForGate(gate, { policy, projectPath: opts.targetDir, unityAvailable: caps.unityCli.available });
-
-    if (!descriptor.automated || !descriptor.command) {
-      const detail = { ok: false, gate, blocked: true, reason: descriptor.reason || 'no automated command available' };
-      if (opts.format === 'json') emit(opts, '', detail);
-      else console.error(`❌ Cannot automate gate "${gate}": ${detail.reason}. Record a manual confirmation instead.`);
-      process.exit(1);
-    }
-
-    const ledger = new RunLedger({
-      targetDir: opts.targetDir,
-      policy,
-      runId: state?.activeRunId || null,
-      workItemId: state ? workItemIdOf(state) : null,
-      phase: state?.session?.currentPhase || null,
-      capabilities: caps,
-    });
-
-    // Relevant files bind the evidence to a concrete input tree so later edits
-    // invalidate it. Prefer an explicit --files list; otherwise use the working
-    // tree's changed files. If git cannot be queried and no files were supplied,
-    // freshness coverage cannot be established — fail safe rather than record a
-    // passing gate against an empty input tree. `allowEmptyFreshness` is the
-    // explicit, visible opt-out.
-    const allowEmpty = policy?.allowEmptyFreshness === true;
-    let relevantFiles;
-    let filesSource;
-    if (opts.files && opts.files.length) {
-      relevantFiles = opts.files.map((f) => f.replace(/\\/g, '/'));
-      filesSource = 'explicit';
-    } else {
-      const changed = gitChangedFiles(opts.targetDir);
-      if (!changed.available) {
-        if (!allowEmpty) {
-          const detail = {
-            ok: false,
-            gate,
-            blocked: true,
-            code: 'freshness-unavailable',
-            reason: `cannot establish freshness coverage: ${changed.reason}. Pass --files <paths> to bind evidence to the relevant files, or enable allowEmptyFreshness in .cadet/harness.json to opt into unscoped evidence.`,
-          };
-          if (opts.format === 'json') emit(opts, '', detail);
-          else console.error(`❌ ${detail.reason}`);
-          process.exit(1);
-        }
-        relevantFiles = [];
-        filesSource = 'unscoped (allowEmptyFreshness)';
-      } else {
-        relevantFiles = changed.files;
-        filesSource = 'working-tree';
-      }
-    }
-
-    if (relevantFiles.length === 0 && !allowEmpty && filesSource !== 'explicit') {
-      const detail = {
-        ok: false,
-        gate,
-        blocked: true,
-        code: 'freshness-unavailable',
-        reason: 'no relevant files were found to bind evidence to. Pass --files <paths>, or enable allowEmptyFreshness in .cadet/harness.json to opt into unscoped evidence.',
-      };
-      if (opts.format === 'json') emit(opts, '', detail);
-      else console.error(`❌ ${detail.reason}`);
-      process.exit(1);
-    }
-
-    // Red-before-green applies to testable work items; a `no_test_required`
-    // change is exempt (contract §5).
-    const noTestRequired = state?.session?.workflowPath === 'no_test_required';
-
-    // Record how the relevant files were chosen (provenance) in the ledger.
-    ledger.addDecision({
-      kind: 'stop',
-      reason: `freshness-bound via ${filesSource}`,
-      scope: relevantFiles.join(',') || '(none)',
-    });
-
-    const result = await runVerificationLoop({
-      gate,
-      command: descriptor.command,
-      tool: descriptor.tool,
-      workItemId: ledger.workItemId || 'unscoped',
-      phase: ledger.phase || 'implementation',
-      relevantFiles,
-      rootDir: opts.targetDir,
-      policy,
-      budgets: ledger.tracker,
-      artifactDir: join(runsDir(opts.targetDir), 'artifacts'),
-      priorEvidence: Array.isArray(state?.gateEvidence) ? state.gateEvidence : [],
-      requireRedFirst: noTestRequired ? false : null,
-    });
-
-    for (const a of result.attempts) ledger.addEvidence(a.evidence);
-    ledger.finalize({ status: result.ok ? 'ok' : 'failed' });
-    const path = ledger.persist();
-
-    // Close the loop: record the produced evidence in state.json so
-    // `state transition` can see it. A passing verification flips the gate
-    // only when it is evidence-backed; a failing one records the attempt.
-    let stateUpdated = false;
-    if (state) {
-      const next = { ...state };
-      next.gateEvidence = [...(Array.isArray(state.gateEvidence) ? state.gateEvidence : []), ...result.attempts.map((a) => a.evidence)];
-      if (Array.isArray(next.gateEvidence)) {
-        // Mark prior evidence for this gate as superseded by the new record.
-        const newest = result.finalEvidence?.evidenceId;
-        next.gateEvidence = next.gateEvidence.map((e) =>
-          e.gate === gate && e.evidenceId !== newest && e.status === 'passed' && result.ok
-            ? { ...e, status: 'superseded', supersededBy: newest }
-            : e);
-      }
-      if (result.ok) {
-        next.gates = { ...(state.gates || {}), [gate]: true };
-      }
-      writeState(opts.targetDir, next);
-      stateUpdated = true;
-    }
-
-    if (opts.format === 'json') {
-      emit(opts, '', { ok: result.ok, status: result.status, gate, attempts: result.attempts.length, stopReason: result.stopReason, runId: ledger.runId, path, stateUpdated });
-    } else if (result.ok) {
-      console.log(`✅ Gate "${gate}" verified (${result.attempts.length} attempt(s)). Ledger: ${path}`);
-    } else {
-      console.error(`❌ Gate "${gate}" failed (${result.status}, ${result.stopReason || 'no reason'}). Ledger: ${path}`);
-    }
-    if (!result.ok) process.exit(1);
-    return;
-  }
-
-  if (sub === 'report') {
-    const runs = listRuns(opts.targetDir);
-    const target = opts.runId || runs[0]?.runId;
-    if (!target) fail(opts, 'No run records found in .cadet/runs/.', () => 2);
-    const run = loadRun(opts.targetDir, target);
-    if (!run) fail(opts, `Run ${target} not found.`, () => 2);
-    if (opts.format === 'json') emit(opts, '', { ok: true, report: buildReport(run) });
-    else console.log(formatReport(run));
-    return;
-  }
-
-  if (sub === 'cleanup') {
-    const { deleted, kept } = cleanupRuns(opts.targetDir, policy, {
-      olderThanMs: Number.isFinite(opts.olderThanMs) ? opts.olderThanMs : null,
-    });
-    emit(opts, `✅ Cleanup: deleted ${deleted.length} run(s), kept ${kept.length}.`, { ok: true, deleted, kept });
-    return;
-  }
-
-  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|verify|report|cleanup|capabilities.`);
-}
-
-export async function run(argv) {
-  const command = argv[2];
-  const opts = parseArgs(argv);
-
-  // Validate the create-only policy flag early so a typo fails loudly.
-  const AGENTS_MD_MODES = ['keep', 'overwrite', 'merge'];
-  if (opts.agentsMd !== undefined && !AGENTS_MD_MODES.includes(opts.agentsMd)) {
-    console.error(`Invalid --agents-md value "${opts.agentsMd}" (expected: ${AGENTS_MD_MODES.join('|')})`);
-    process.exit(1);
-  }
-  const installOpts = {
-    sourceUrl: opts.sourceUrl,
-    yes: opts.yes === true,
-    createOnlyPolicy: opts.agentsMd ? { 'AGENTS.md': opts.agentsMd } : undefined,
-  };
-
-  try {
-    switch (command) {
-      case 'init':
-        await install(opts.targetDir, installOpts);
-        break;
-      case 'sync':
-        await sync(opts.targetDir, installOpts);
-        break;
-      case 'state':
-        await cmdState(opts);
-        break;
-      case 'harness':
-        await cmdHarness(opts);
-        break;
-      case '--version':
-      case '-v':
-        console.log(`cadet-agent v${getVersion()}`);
-        break;
-      case '--help':
-      case '-h':
-      case undefined:
-        showHelp();
-        break;
-      default:
-        console.error(`Unknown command: ${command}`);
-        console.error('Run cadet-agent --help for usage.');
-        process.exit(1);
-    }
-  } catch (err) {
-    if (err instanceof PolicyError || err instanceof StateError) {
-      fail(opts, err.message);
-    }
-    throw err;
-  }
-}
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { install, sync } from './install.mjs';
+import {
+  validateState, migrateStateFile, readState, writeState, evaluateTransition, applyTransition,
+  workItemIdOf, loadPolicy, RunLedger, loadRun, listRuns, cleanupRuns, buildReport, formatReport,
+  runVerificationLoop, commandForGate, detectCapabilities, runsDir, gitChangedFiles, PolicyError, StateError,
+  detectRepoRole, describeRepoRole,
+} from './harness/index.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function getVersion() {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+  return pkg.version;
+}
+
+function showHelp() {
+  console.log(`
+  ██████╗ █████╗ ██████╗ ███████╗████████╗
+  ██╔════╝██╔══██╗██╔══██╗██╔════╝╚══██╔══╝
+  ██║     ███████║██║  ██║█████╗     ██║
+  ██║     ██╔══██║██║  ██║██╔══╝     ██║
+  ╚██████╗██║  ██║██████╔╝███████╗   ██║
+   ╚═════╝╚═╝  ╚═╝╚═════╝ ╚══════╝   ╚═╝
+
+  Cross-IDE agent framework for Unity/C# game-development
+
+  Usage:
+    npx cadet-agent@latest init     Install Cadet-Agent into the current directory
+    npx cadet-agent@latest init --target <dir>   Install into a specific directory
+    npx cadet-agent@latest sync     Update framework, preserving local policies/plans
+    npx cadet-agent@latest sync --target <dir>   Sync a specific directory
+
+    cadet-agent state validate      Validate .cadet/state.json against the v2 schema
+    cadet-agent state migrate       Atomically migrate v1 state to v2 (backup on write)
+    cadet-agent state transition --to <phase>   Enforce the transition matrix + evidence
+
+    cadet-agent harness record      Append a sanitized span/evidence/decision event
+    cadet-agent harness verify      Run a bounded, classified verification loop
+    cadet-agent harness report      Summarize budget consumption and failures
+    cadet-agent harness cleanup     Apply the retention policy to .cadet/runs/
+    cadet-agent harness capabilities  Report available CLI/Unity/MCP/hook/token/cost telemetry
+
+  Options:
+    --target, -t  Target directory (default: current working directory)
+    --source       Release API URL override (for forked deployments)
+    --format       human|json (default: human)
+    --to           Target phase (state transition)
+    --gate         Gate name (harness verify)
+    --command      Command override (harness verify)
+    --files        Comma-separated relevant files to bind evidence to (harness verify)
+    --agents-md    keep|overwrite|merge for an existing AGENTS.md (init/sync)
+    --yes, -y      Never prompt; keep existing files (non-interactive installs)
+    --help, -h    Show this help
+    --version, -v Show version number
+`);
+}
+
+function parseArgs(argv) {
+  const opts = { format: 'human', targetDir: process.cwd(), sourceUrl: null, rest: [] };
+  // argv[2] is the top-level command (`state`/`harness`/`init`/...); argv[3] begins
+  // the subcommand and its options.
+  for (let i = 3; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--target': case '-t': opts.targetDir = argv[++i]; break;
+      case '--source': opts.sourceUrl = argv[++i]; break;
+      case '--format': opts.format = argv[++i] || 'human'; break;
+      case '--to': opts.to = argv[++i]; break;
+      case '--gate': opts.gate = argv[++i]; break;
+      case '--command': opts.command = argv[++i]; break;
+      case '--work-item': opts.workItemId = argv[++i]; break;
+      case '--phase': opts.phase = argv[++i]; break;
+      case '--run': opts.runId = argv[++i]; break;
+      case '--type': opts.type = argv[++i]; break;
+      case '--reason': opts.reason = argv[++i]; break;
+      case '--evidence-status': opts.evidenceStatus = argv[++i]; break;
+      case '--files': opts.files = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
+      case '--older-than-ms': opts.olderThanMs = Number(argv[++i]); break;
+      case '--agents-md': opts.agentsMd = argv[++i]; break;
+      case '--yes': case '-y': opts.yes = true; break;
+      default: opts.rest.push(a);
+    }
+  }
+  return opts;
+}
+
+function emit(opts, human, json) {
+  if (opts.format === 'json') {
+    console.log(JSON.stringify(json, null, 2));
+  } else {
+    console.log(human);
+  }
+}
+
+function fail(opts, message, code = json => json.exitCode || 1, json = {}) {
+  const exitCode = code(json);
+  if (opts.format === 'json') {
+    console.error(JSON.stringify({ ok: false, error: message, ...json }, null, 2));
+  } else {
+    console.error(`\n❌ ${message}`);
+  }
+  process.exit(exitCode);
+}
+
+// ── state commands ──────────────────────────────────────────────────────────
+
+async function cmdState(opts) {
+  const sub = opts.rest[0];
+  const statePath = join(opts.targetDir, '.cadet', 'state.json');
+
+  if (sub === 'validate') {
+    const { exists, state } = readState(opts.targetDir);
+    if (!exists) {
+      // Report the detected repo role instead of a bare ok. In the framework
+      // source repository a missing state file is expected, not a silent pass —
+      // saying so prevents story/gate reasoning against a repo that has no story.
+      const role = detectRepoRole(opts.targetDir);
+      const repoRoleDetail = describeRepoRole(role);
+      emit(
+        opts,
+        `No .cadet/state.json found (nothing to validate).\n   Repo role: ${role.role} (${role.source}, ${role.confidence} confidence) — ${repoRoleDetail}`,
+        { ok: true, valid: true, exists: false, repoRole: role.role, repoRoleDetail, repoRoleSource: role.source },
+      );
+      return;
+    }
+    // Pass rootDir so stale/foreign evidence is caught at validation time.
+    const result = validateState(state, { rootDir: opts.targetDir });
+    const role = detectRepoRole(opts.targetDir);
+    const repoRoleDetail = describeRepoRole(role);
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: result.valid, valid: result.valid, errors: result.errors, warnings: result.warnings, repoRole: role.role, repoRoleDetail });
+    } else {
+      if (result.valid) console.log(`✅ state.json is valid (v${state.version}).`);
+      else {
+        console.error('❌ state.json is invalid:');
+        for (const e of result.errors) console.error(`   ${e.path}: ${e.message}`);
+      }
+      for (const w of result.warnings) console.log(`   ⚠️  ${w.path}: ${w.message}`);
+      console.log(`   Repo role: ${role.role} — ${repoRoleDetail}`);
+    }
+    if (!result.valid) process.exit(1);
+    return;
+  }
+
+  if (sub === 'migrate') {
+    const result = migrateStateFile(statePath, { backup: true });
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: true, migrated: result.migrated, statePath: result.statePath });
+    } else if (result.migrated) {
+      console.log(`✅ Migrated ${statePath} to v2 (backup: ${statePath}.v1.bak).`);
+    } else {
+      console.log('✅ state.json is already v2 — nothing to migrate.');
+    }
+    return;
+  }
+
+  if (sub === 'transition') {
+    if (!opts.to) fail(opts, 'state transition requires --to <phase>');
+    const { exists, state } = readState(opts.targetDir);
+    if (!exists) fail(opts, 'No .cadet/state.json found. Initialise state before transitioning.', () => 2);
+    // Freshness is enforced against the current working tree: evaluateTransition
+    // recomputes each gate's input-tree hash from the evidence's relevant files.
+    const evaluation = evaluateTransition(state, opts.to, { rootDir: opts.targetDir });
+    if (!evaluation.allowed) {
+      const detail = {
+        ok: false,
+        allowed: false,
+        missingGates: evaluation.missingGates,
+        staleEvidence: evaluation.staleEvidence,
+        errors: evaluation.errors,
+      };
+      const lines = ['❌ Transition rejected:'];
+      for (const e of evaluation.errors) lines.push(`   ${e}`);
+      if (evaluation.missingGates.length) lines.push(`   missing gates/evidence: ${evaluation.missingGates.join(', ')}`);
+      for (const s of evaluation.staleEvidence) lines.push(`   stale: ${s.gate} — ${s.reason || (s.reasons || []).join('; ')}`);
+      if (opts.format === 'json') emit(opts, '', detail);
+      else console.error(lines.join('\n'));
+      process.exit(1);
+    }
+    const next = applyTransition(state, opts.to, { rootDir: opts.targetDir });
+    writeState(opts.targetDir, next);
+    emit(opts, `✅ Transitioned to ${opts.to}.`, { ok: true, allowed: true, to: opts.to });
+    return;
+  }
+
+  fail(opts, `Unknown state subcommand: ${sub || '(none)'}. Use validate|migrate|transition.`);
+}
+
+// ── harness commands ────────────────────────────────────────────────────────
+
+async function cmdHarness(opts) {
+  const sub = opts.rest[0];
+  const policy = loadPolicy(opts.targetDir);
+
+  if (sub === 'capabilities') {
+    const caps = detectCapabilities({ targetDir: opts.targetDir });
+    if (opts.format === 'json') emit(opts, '', { ok: true, capabilities: caps });
+    else {
+      console.log('Cadet-Agent capability report');
+      console.log(`  CLI:            ${caps.cli ? 'available' : 'unavailable'}`);
+      console.log(`  Unity CLI:      ${caps.unityCli.available ? `available (${caps.unityCli.version || 'version unknown'})` : 'unavailable — compile/analyzer gates fall back to manual confirmation'}`);
+      console.log(`  MCP:            ${caps.mcp.available ? 'configured' : 'unavailable — live inspection not available'}`);
+      console.log(`  Copilot hook:   ${caps.hook.copilot ? 'installed' : 'not installed'}`);
+      console.log(`  Token telemetry:${caps.tokenTelemetry.provider ? ' provider' : ' estimate/unknown'}`);
+      console.log(`  Cost telemetry: ${caps.costTelemetry.available ? 'available' : `unavailable (${caps.costTelemetry.reason})`}`);
+      console.log(`  Note: ${caps.hook.note}`);
+    }
+    return;
+  }
+
+  if (sub === 'record') {
+    const { state } = readState(opts.targetDir);
+    const ledger = new RunLedger({
+      targetDir: opts.targetDir,
+      policy,
+      runId: opts.runId || state?.activeRunId || null,
+      workItemId: opts.workItemId || (state ? workItemIdOf(state) : null),
+      phase: opts.phase || state?.session?.currentPhase || null,
+    });
+    const type = opts.type || 'tool-call';
+    const reason = opts.reason || opts.rest[1] || 'recorded event';
+    if (type === 'decision') {
+      ledger.addDecision({ kind: 'stop', reason });
+    } else if (type === 'verification') {
+      ledger.addSpan({ kind: 'verification', name: opts.gate || 'manual', status: opts.evidenceStatus || 'ok', reason });
+    } else {
+      ledger.addSpan({ kind: type, name: opts.gate || type, status: 'ok', reason, tool: opts.tool || null });
+    }
+    ledger.finalize();
+    const path = ledger.persist();
+    emit(opts, `✅ Recorded ${type} event in ${path}.`, { ok: true, runId: ledger.runId, path });
+    return;
+  }
+
+  if (sub === 'verify') {
+    const gate = opts.gate;
+    if (!gate) fail(opts, 'harness verify requires --gate <gate>');
+    const { state } = readState(opts.targetDir);
+    const caps = detectCapabilities({ targetDir: opts.targetDir });
+    const descriptor = opts.command
+      ? { command: opts.command, tool: 'custom', automated: true }
+      : commandForGate(gate, { policy, projectPath: opts.targetDir, unityAvailable: caps.unityCli.available });
+
+    if (!descriptor.automated || !descriptor.command) {
+      const detail = { ok: false, gate, blocked: true, reason: descriptor.reason || 'no automated command available' };
+      if (opts.format === 'json') emit(opts, '', detail);
+      else console.error(`❌ Cannot automate gate "${gate}": ${detail.reason}. Record a manual confirmation instead.`);
+      process.exit(1);
+    }
+
+    const ledger = new RunLedger({
+      targetDir: opts.targetDir,
+      policy,
+      runId: state?.activeRunId || null,
+      workItemId: state ? workItemIdOf(state) : null,
+      phase: state?.session?.currentPhase || null,
+      capabilities: caps,
+    });
+
+    // Relevant files bind the evidence to a concrete input tree so later edits
+    // invalidate it. Prefer an explicit --files list; otherwise use the working
+    // tree's changed files. If git cannot be queried and no files were supplied,
+    // freshness coverage cannot be established — fail safe rather than record a
+    // passing gate against an empty input tree. `allowEmptyFreshness` is the
+    // explicit, visible opt-out.
+    const allowEmpty = policy?.allowEmptyFreshness === true;
+    let relevantFiles;
+    let filesSource;
+    if (opts.files && opts.files.length) {
+      relevantFiles = opts.files.map((f) => f.replace(/\\/g, '/'));
+      filesSource = 'explicit';
+    } else {
+      const changed = gitChangedFiles(opts.targetDir);
+      if (!changed.available) {
+        if (!allowEmpty) {
+          const detail = {
+            ok: false,
+            gate,
+            blocked: true,
+            code: 'freshness-unavailable',
+            reason: `cannot establish freshness coverage: ${changed.reason}. Pass --files <paths> to bind evidence to the relevant files, or enable allowEmptyFreshness in .cadet/harness.json to opt into unscoped evidence.`,
+          };
+          if (opts.format === 'json') emit(opts, '', detail);
+          else console.error(`❌ ${detail.reason}`);
+          process.exit(1);
+        }
+        relevantFiles = [];
+        filesSource = 'unscoped (allowEmptyFreshness)';
+      } else {
+        relevantFiles = changed.files;
+        filesSource = 'working-tree';
+      }
+    }
+
+    if (relevantFiles.length === 0 && !allowEmpty && filesSource !== 'explicit') {
+      const detail = {
+        ok: false,
+        gate,
+        blocked: true,
+        code: 'freshness-unavailable',
+        reason: 'no relevant files were found to bind evidence to. Pass --files <paths>, or enable allowEmptyFreshness in .cadet/harness.json to opt into unscoped evidence.',
+      };
+      if (opts.format === 'json') emit(opts, '', detail);
+      else console.error(`❌ ${detail.reason}`);
+      process.exit(1);
+    }
+
+    // Red-before-green applies to testable work items; a `no_test_required`
+    // change is exempt (contract §5).
+    const noTestRequired = state?.session?.workflowPath === 'no_test_required';
+
+    // Record how the relevant files were chosen (provenance) in the ledger.
+    ledger.addDecision({
+      kind: 'stop',
+      reason: `freshness-bound via ${filesSource}`,
+      scope: relevantFiles.join(',') || '(none)',
+    });
+
+    const result = await runVerificationLoop({
+      gate,
+      command: descriptor.command,
+      tool: descriptor.tool,
+      workItemId: ledger.workItemId || 'unscoped',
+      phase: ledger.phase || 'implementation',
+      relevantFiles,
+      rootDir: opts.targetDir,
+      policy,
+      budgets: ledger.tracker,
+      artifactDir: join(runsDir(opts.targetDir), 'artifacts'),
+      priorEvidence: Array.isArray(state?.gateEvidence) ? state.gateEvidence : [],
+      requireRedFirst: noTestRequired ? false : null,
+    });
+
+    for (const a of result.attempts) ledger.addEvidence(a.evidence);
+    ledger.finalize({ status: result.ok ? 'ok' : 'failed' });
+    const path = ledger.persist();
+
+    // Close the loop: record the produced evidence in state.json so
+    // `state transition` can see it. A passing verification flips the gate
+    // only when it is evidence-backed; a failing one records the attempt.
+    let stateUpdated = false;
+    if (state) {
+      const next = { ...state };
+      next.gateEvidence = [...(Array.isArray(state.gateEvidence) ? state.gateEvidence : []), ...result.attempts.map((a) => a.evidence)];
+      if (Array.isArray(next.gateEvidence)) {
+        // Mark prior evidence for this gate as superseded by the new record.
+        const newest = result.finalEvidence?.evidenceId;
+        next.gateEvidence = next.gateEvidence.map((e) =>
+          e.gate === gate && e.evidenceId !== newest && e.status === 'passed' && result.ok
+            ? { ...e, status: 'superseded', supersededBy: newest }
+            : e);
+      }
+      if (result.ok) {
+        next.gates = { ...(state.gates || {}), [gate]: true };
+      }
+      writeState(opts.targetDir, next);
+      stateUpdated = true;
+    }
+
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: result.ok, status: result.status, gate, attempts: result.attempts.length, stopReason: result.stopReason, runId: ledger.runId, path, stateUpdated, repoRole: detectRepoRole(opts.targetDir).role });
+    } else if (result.ok) {
+      console.log(`✅ Gate "${gate}" verified (${result.attempts.length} attempt(s)). Ledger: ${path}`);
+    } else {
+      console.error(`❌ Gate "${gate}" failed (${result.status}, ${result.stopReason || 'no reason'}). Ledger: ${path}`);
+    }
+    if (!result.ok) process.exit(1);
+    return;
+  }
+
+  if (sub === 'report') {
+    const runs = listRuns(opts.targetDir);
+    const target = opts.runId || runs[0]?.runId;
+    if (!target) fail(opts, 'No run records found in .cadet/runs/.', () => 2);
+    const run = loadRun(opts.targetDir, target);
+    if (!run) fail(opts, `Run ${target} not found.`, () => 2);
+    if (opts.format === 'json') emit(opts, '', { ok: true, report: buildReport(run) });
+    else console.log(formatReport(run));
+    return;
+  }
+
+  if (sub === 'cleanup') {
+    const { deleted, kept } = cleanupRuns(opts.targetDir, policy, {
+      olderThanMs: Number.isFinite(opts.olderThanMs) ? opts.olderThanMs : null,
+    });
+    emit(opts, `✅ Cleanup: deleted ${deleted.length} run(s), kept ${kept.length}.`, { ok: true, deleted, kept });
+    return;
+  }
+
+  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|verify|report|cleanup|capabilities.`);
+}
+
+export async function run(argv) {
+  const command = argv[2];
+  const opts = parseArgs(argv);
+
+  // Validate the create-only policy flag early so a typo fails loudly.
+  const AGENTS_MD_MODES = ['keep', 'overwrite', 'merge'];
+  if (opts.agentsMd !== undefined && !AGENTS_MD_MODES.includes(opts.agentsMd)) {
+    console.error(`Invalid --agents-md value "${opts.agentsMd}" (expected: ${AGENTS_MD_MODES.join('|')})`);
+    process.exit(1);
+  }
+  const installOpts = {
+    sourceUrl: opts.sourceUrl,
+    yes: opts.yes === true,
+    createOnlyPolicy: opts.agentsMd ? { 'AGENTS.md': opts.agentsMd } : undefined,
+  };
+
+  try {
+    switch (command) {
+      case 'init':
+        await install(opts.targetDir, installOpts);
+        break;
+      case 'sync':
+        await sync(opts.targetDir, installOpts);
+        break;
+      case 'state':
+        await cmdState(opts);
+        break;
+      case 'harness':
+        await cmdHarness(opts);
+        break;
+      case '--version':
+      case '-v':
+        console.log(`cadet-agent v${getVersion()}`);
+        break;
+      case '--help':
+      case '-h':
+      case undefined:
+        showHelp();
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.error('Run cadet-agent --help for usage.');
+        process.exit(1);
+    }
+  } catch (err) {
+    if (err instanceof PolicyError || err instanceof StateError) {
+      fail(opts, err.message);
+    }
+    throw err;
+  }
+}

package/src/harness/index.mjs

@@ -1,60 +1,64 @@
-/**
- * Cadet-Agent harness — stable internal entry point.
- *
- * The CLI and tests import from here so they never depend on the file layout of
- * the individual harness modules.
- */
-
-export {
-  PHASES, GATES, TRANSITIONS, EVIDENCE_STATUSES, RETRY_CLASSES, CONTEXT_TIERS,
-  DEFAULT_BUDGETS, HARD_CEILINGS, DEFAULT_ARCHIVE_LIMITS, DEFAULT_OUTPUT_POLICY,
-  DEFAULT_RETENTION, DEFAULT_ESTIMATION, DEFAULT_HOOK_POLICY,
-  validatePolicy, defaultPolicy, loadPolicy, budgetForScope, policyPath, PolicyError,
-} from './policy.mjs';
-
-export {
-  BudgetTracker, budgetExhaustedResult, budgetReport, evaluateHardStop,
-  estimateTokens, estimateCost, normalizeUsage, BUDGET_RESULTS,
-} from './budget.mjs';
-
-export {
-  newId, isUuid, sha256, sha256Bytes, hashFile, hashTree, hashCriteria, timestamp, canonicalJson, changedFiles, gitChangedFiles,
-} from './util.mjs';
-
-export {
-  STATE_VERSION, validateState, migrateStateV1toV2, migrateStateFile,
-  createEvidence, computeInputTreeHash, workItemIdOf, evidenceFreshness,
-  latestEvidenceForGate, activeExceptions, requiredGates, evaluateTransition,
-  applyTransition, resetGatesForNewWorkItem, statePathFor, readState, writeState, writeJsonAtomic, StateError,
-} from './state.mjs';
-
-export {
-  RETRY_CLASSES as VERIFICATION_RETRY_CLASSES, RESULT_STATUSES, TRANSIENT_BACKOFF_MS,
-  DEFAULT_FLAKY_SIGNATURES, classifyResult, classifyRepair, runCommand,
-  commandForGate, analyzerClean, runVerificationLoop, manualConfirmation, isBudgetExhaustion,
-} from './verification.mjs';
-
-export {
-  ContextManifest, buildBaseManifest, tier0References, TIER_REASONS_REQUIRED,
-  DEFAULT_MAX_EXPANSION_PER_STEP, ContextError,
-} from './context.mjs';
-
-export {
-  TOOL_KINDS, ROUTING_REASONS, detectCapabilities, routeTask, toolCallSpan, RoutingError,
-} from './routing.mjs';
-
-export { redact, redactString, containsSecret, REDACTED, REDACTION_CATEGORIES } from './redaction.mjs';
-
-export {
-  RUN_SCHEMA_VERSION, RunLedger, loadRun, listRuns, cleanupRuns, buildReport, formatReport,
-  runsDir, LedgerError,
-} from './ledger.mjs';
-
-export {
-  extractArchive, readArchiveEntry, readEntries, assertContained, crc32, findEocd,
-  ArchiveError, DEFAULT_ARCHIVE_LIMITS as ARCHIVE_LIMITS,
-} from './archive.mjs';
-
-export {
-  RELEVANT_TOOLS, WRITE_PATTERNS, detectWrite, evaluateHook, hookOutput,
-} from './hook.mjs';
+/**
+ * Cadet-Agent harness — stable internal entry point.
+ *
+ * The CLI and tests import from here so they never depend on the file layout of
+ * the individual harness modules.
+ */
+
+export {
+  PHASES, GATES, TRANSITIONS, EVIDENCE_STATUSES, RETRY_CLASSES, CONTEXT_TIERS,
+  DEFAULT_BUDGETS, HARD_CEILINGS, DEFAULT_ARCHIVE_LIMITS, DEFAULT_OUTPUT_POLICY,
+  DEFAULT_RETENTION, DEFAULT_ESTIMATION, DEFAULT_HOOK_POLICY,
+  validatePolicy, defaultPolicy, loadPolicy, budgetForScope, policyPath, PolicyError,
+} from './policy.mjs';
+
+export {
+  BudgetTracker, budgetExhaustedResult, budgetReport, evaluateHardStop,
+  estimateTokens, estimateCost, normalizeUsage, BUDGET_RESULTS,
+} from './budget.mjs';
+
+export {
+  newId, isUuid, sha256, sha256Bytes, hashFile, hashTree, hashCriteria, timestamp, canonicalJson, changedFiles, gitChangedFiles,
+} from './util.mjs';
+
+export {
+  STATE_VERSION, validateState, migrateStateV1toV2, migrateStateFile,
+  createEvidence, computeInputTreeHash, workItemIdOf, evidenceFreshness,
+  latestEvidenceForGate, activeExceptions, requiredGates, evaluateTransition,
+  applyTransition, resetGatesForNewWorkItem, statePathFor, readState, writeState, writeJsonAtomic, StateError,
+} from './state.mjs';
+
+export {
+  RETRY_CLASSES as VERIFICATION_RETRY_CLASSES, RESULT_STATUSES, TRANSIENT_BACKOFF_MS,
+  DEFAULT_FLAKY_SIGNATURES, classifyResult, classifyRepair, runCommand,
+  commandForGate, analyzerClean, runVerificationLoop, manualConfirmation, isBudgetExhaustion,
+} from './verification.mjs';
+
+export {
+  ContextManifest, buildBaseManifest, tier0References, TIER_REASONS_REQUIRED,
+  DEFAULT_MAX_EXPANSION_PER_STEP, ContextError,
+} from './context.mjs';
+
+export {
+  TOOL_KINDS, ROUTING_REASONS, detectCapabilities, routeTask, toolCallSpan, RoutingError,
+} from './routing.mjs';
+
+export { redact, redactString, containsSecret, REDACTED, REDACTION_CATEGORIES } from './redaction.mjs';
+
+export {
+  RUN_SCHEMA_VERSION, RunLedger, loadRun, listRuns, cleanupRuns, buildReport, formatReport,
+  runsDir, LedgerError,
+} from './ledger.mjs';
+
+export {
+  extractArchive, readArchiveEntry, readEntries, assertContained, crc32, findEocd,
+  ArchiveError, DEFAULT_ARCHIVE_LIMITS as ARCHIVE_LIMITS,
+} from './archive.mjs';
+
+export {
+  RELEVANT_TOOLS, WRITE_PATTERNS, detectWrite, evaluateHook, hookOutput,
+} from './hook.mjs';
+
+export {
+  REPO_ROLES, REPO_ROLE_MARKER, detectRepoRole, isFrameworkSourceWithoutWorkItem, describeRepoRole,
+} from './repo-role.mjs';

package/src/harness/repo-role.mjs

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Repository role detection.
+ *
+ * Cadet is consumed two different ways:
+ *
+ * - `consumer-project` — the normal case: a Unity/game repository that installs
+ *   Cadet and runs the workflow. It has `.cadet/state.json` (or will, once the
+ *   first story starts) and planning artifacts under `.cadet/agent/project-plans/`.
+ * - `framework-source` — the canonical Cadet-Agent repository itself (and any
+ *   fork of it). It ships the *rules about* stories and gates but deliberately
+ *   holds no `.cadet/state.json` and no `.cadet/agent/project-plans/`; those are
+ *   listed in CONTRIBUTING.md as "not in this repo".
+ *
+ * Why this exists: an agent dropped into the framework-source repo sees a tree
+ * full of gate vocabulary (`codeReviewCompleted`, Given/When/Then, story
+ * templates) with no active work item, and can be led to reason about stories
+ * that were never there. Detecting the role lets the CLI and the skills say so
+ * explicitly instead of reporting a bare success for a missing state file.
+ */
+
+export const REPO_ROLES = Object.freeze({
+  CONSUMER: 'consumer-project',
+  FRAMEWORK: 'framework-source',
+});
+
+/** Relative path of the marker file written by install/sync. */
+export const REPO_ROLE_MARKER = '.cadet/.repo-role';
+
+/** Higher confidence wins when both a marker and structural signals are present. */
+const CONFIDENCE = Object.freeze({ marker: 'high', structural: 'medium', unknown: 'low' });
+
+function readMarker(targetDir) {
+  const path = join(targetDir, '.cadet', '.repo-role');
+  if (!existsSync(path)) return null;
+  try {
+    const value = readFileSync(path, 'utf-8').trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detect the role of `targetDir`.
+ *
+ * Resolution order:
+ *   1. Explicit `.cadet/.repo-role` marker (written by install/sync) — high confidence.
+ *   2. Structural signals: an existing `.cadet/state.json` or a
+ *      `.cadet/agent/project-plans/` directory ⇒ consumer-project; a
+ *      FrameworkManifest.json with no state and no project-plans ⇒ framework-source.
+ *   3. Otherwise `unknown`.
+ *
+ * Never throws: a malformed or unreadable marker degrades to structural signals.
+ */
+export function detectRepoRole(targetDir, { marker = undefined } = {}) {
+  const explicit = marker === undefined ? readMarker(targetDir) : marker;
+
+  if (explicit === REPO_ROLES.CONSUMER || explicit === REPO_ROLES.FRAMEWORK) {
+    return {
+      role: explicit,
+      source: 'marker',
+      confidence: CONFIDENCE.marker,
+      marker: REPO_ROLE_MARKER,
+    };
+  }
+
+  const hasState = existsSync(join(targetDir, '.cadet', 'state.json'));
+  const hasPlans = existsSync(join(targetDir, '.cadet', 'agent', 'project-plans'));
+  const hasManifest = existsSync(join(targetDir, '.cadet', 'agent', 'core', 'FrameworkManifest.json'));
+
+  if (hasState || hasPlans) {
+    return {
+      role: REPO_ROLES.CONSUMER,
+      source: 'structural',
+      confidence: CONFIDENCE.structural,
+      signals: { hasState, hasPlans, hasManifest },
+    };
+  }
+
+  if (hasManifest) {
+    // Framework files are present but there is no story state and no plans tree:
+    // this is the framework source (or a fork of it), not a mid-story project.
+    return {
+      role: REPO_ROLES.FRAMEWORK,
+      source: 'structural',
+      confidence: CONFIDENCE.structural,
+      signals: { hasState, hasPlans, hasManifest },
+    };
+  }
+
+  return {
+    role: 'unknown',
+    source: 'structural',
+    confidence: CONFIDENCE.unknown,
+    signals: { hasState, hasPlans, hasManifest },
+  };
+}
+
+/** True when `targetDir` is the framework source and has no active work item. */
+export function isFrameworkSourceWithoutWorkItem(targetDir) {
+  const info = detectRepoRole(targetDir);
+  if (info.role !== REPO_ROLES.FRAMEWORK) return false;
+  return !existsSync(join(targetDir, '.cadet', 'state.json'));
+}
+
+/** Human-readable one-liner explaining the detected role and its consequence. */
+export function describeRepoRole(info) {
+  if (info.role === REPO_ROLES.FRAMEWORK) {
+    return 'framework-source repository — story/gate work is not applicable here; use the contribution workflow (CONTRIBUTING.md).';
+  }
+  if (info.role === REPO_ROLES.CONSUMER) {
+    return 'consumer-project repository — story/gate workflow applies.';
+  }
+  return 'unknown repository role — no Cadet install detected (run `cadet-agent init`).';
+}

package/src/harness/state.mjs

@@ -129,8 +129,23 @@ export function validateState(state, context = {}) {
       const workItemId = activeWorkItem
         ? `${activeWorkItem.epicId || 'none'}::${activeWorkItem.storyId || 'none'}`
         : null;
+
+      // Gate exceptions are honoured here for the same reasons `evaluateTransition`
+      // honours them. Before this, a scoped exception could make a transition legal
+      // while `state validate` still reported the identical document as invalid, so
+      // the two official commands contradicted each other and a reader could not tell
+      // "correctly excepted" from "evidence broken". Exceptions are keyed on the
+      // ACTIVE work item, so they cannot excuse a different story's gates.
+      const exceptions = activeExceptions(state, { workItemId: workItemId || undefined });
+
       for (const gate of GATES) {
         if (state.gates[gate] !== true) continue;
+
+        // An excepted gate is intentionally not held to freshness or work-item
+        // ownership: that is precisely what the exception is for. It still must have
+        // been claimed true, which the loop condition above already guarantees.
+        if (exceptions[gate]) continue;
+
         const evidence = latestEvidenceForGate(state, gate);
         if (!evidence || (evidence.status !== 'passed' && evidence.status !== 'manual-confirmation')) {
           errors.push({

package/src/install.mjs

@@ -1,11 +1,12 @@
-import { readFileSync, unlinkSync, existsSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { readFileSync, unlinkSync, existsSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { runUpgrades } from './upgrades.mjs';
 import {
   extractArchive, readArchiveEntry, findEocd,
   DEFAULT_ARCHIVE_LIMITS, ArchiveError,
 } from './harness/archive.mjs';
+import { REPO_ROLES, REPO_ROLE_MARKER } from './harness/repo-role.mjs';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -247,6 +248,44 @@ async function downloadZip(url) {
   return Buffer.concat(chunks);
 }
 
+// ── Repo-role marker ─────────────────────────────────────────────────────────
+//
+// Cadet is consumed either as a framework source checkout (this repository and
+// its forks) or as a consumer project that installs the framework. The two need
+// different behaviour — story/gate work does not apply to the framework source.
+// Writing a tiny `.cadet/.repo-role` marker makes that boundary machine-checkable
+// instead of relying on prose, and it is neither a managed nor a preserved path,
+// so sync can never delete or overwrite it by accident.
+
+const VALID_ROLES = [REPO_ROLES.CONSUMER, REPO_ROLES.FRAMEWORK];
+
+/** Read the `.cadet/.repo-role` marker. Returns the role string, or null. */
+export function readRepoRoleMarker(targetDir) {
+  const path = join(targetDir, REPO_ROLE_MARKER);
+  if (!existsSync(path)) return null;
+  try {
+    const value = readFileSync(path, 'utf-8').trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the `.cadet/.repo-role` marker, creating `.cadet/` if necessary.
+ * Defaults to `consumer-project` — the role of anything that runs `init`/`sync`.
+ * Throws on an unrecognized role so a typo fails loudly rather than writing junk.
+ */
+export function writeRepoRoleMarker(targetDir, role = REPO_ROLES.CONSUMER) {
+  if (!VALID_ROLES.includes(role)) {
+    throw new Error(`unknown repo role "${role}" (expected: ${VALID_ROLES.join('|')})`);
+  }
+  const path = join(targetDir, REPO_ROLE_MARKER);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${role}\n`, 'utf-8');
+  return path;
+}
+
 // ── Public install entry ────────────────────────────────────────────────────
 
 export async function install(targetDir, opts = {}) {
@@ -275,6 +314,11 @@ export async function install(targetDir, opts = {}) {
   });
   reportCreateOnlySkips(createOnly, targetDir, releaseVersion, opts);
 
+  // 4b. Record the repository role. This install targets a consumer project, and
+  // the marker lets later CLI/skill invocations say so instead of guessing.
+  const roleMarker = writeRepoRoleMarker(targetDir, REPO_ROLES.CONSUMER);
+  console.log(`   Repo role: consumer-project (${roleMarker})`);
+
   // 5. Report
   console.log(`\n✅ Cadet-Agent v${releaseVersion} installed! Extracted ${extracted.length} files.\n`);
 
@@ -596,6 +640,12 @@ export async function sync(targetDir, opts = {}) {
   const oldVersionNorm = normalizeVersion(oldVersion);
   console.log(`   Latest: v${newVersion} (published ${release.published_at})\n`);
 
+  // 2b. Ensure the repo-role marker exists even when no files change, so an
+  // existing install synced by an older CLI still gets the boundary recorded.
+  if (!readRepoRoleMarker(targetDir)) {
+    writeRepoRoleMarker(targetDir, REPO_ROLES.CONSUMER);
+  }
+
   if (oldVersionNorm === newVersion) {
     console.log(`✅ Already up to date (v${oldVersionNorm}). Nothing to sync.\n`);
     return;