cadet-agent 0.44.0 → 0.46.0

package/README.md

@@ -141,7 +141,7 @@ flowchart TD
     BREAKDOWN --> IMPL
 
     IMPL -->|"story complete"| REVIEW
-    REVIEW -->|"gate: codeReviewCompleted ✅<br/>gate: securityReviewPassed ✅"| VALIDATE
+    REVIEW -->|"gate: codeReviewCompleted ✅<br/>gate: securityReviewPassed ✅<br/>gate: reachabilityAddressed ✅ (opt-in)"| VALIDATE
     VALIDATE -->|"gate: designArtifactSyncConfirmed ✅"| NEXT_STORY
     NEXT_STORY -->|"yes"| IMPL
     NEXT_STORY -->|"no"| CLOSED
@@ -165,7 +165,7 @@ Hard gates are enforced at every phase transition. The agent reads `.cadet/state
 | Transition | Required Gates |
 |---|---|
 | implementation → review | `testsPassed`, `compileCheckConfirmed`, `unityAnalyzerClean`, `storyTrackingUpdated` |
-| review → validation | `codeReviewCompleted`, `securityReviewPassed`, `acceptanceCriteriaValidated` |
+| review → validation | `codeReviewCompleted`, `securityReviewPassed`, `acceptanceCriteriaValidated`, and `reachabilityAddressed` when `reachability.enabled` is set |
 | validation → closed | `designArtifactSyncConfirmed` |
 
 **`closed` is end-of-epic, not per-story.** `validation → closed` is taken only when no stories remain (`NEXT_STORY → no → CLOSED` above). When an epic still has stories, the next story re-enters from `validation → implementation` (`NEXT_STORY → yes → IMPL`). Do not close a story individually: `closed` is terminal, and there is no transition out of it.

package/package.json

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

package/src/cli.mjs

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { install, sync } from './install.mjs';
 import {
   validateState, migrateStateFile, readState, writeState, evaluateTransition, applyTransition,
@@ -8,6 +8,9 @@ import {
   runVerificationLoop, commandForGate, detectCapabilities, runsDir, gitChangedFiles, PolicyError, StateError,
   detectRepoRole, describeRepoRole, GATES, manualConfirmation,
   parseTestInventory, parseStoryCriteria, compareCoverage, describeCoverageGaps,
+  parseReachabilityDeclaration, validateReachabilityDeclaration, collectWorkItems,
+  findDeferralCycles, readSiblingDeclarations, normalizeWorkItemRef, describeReachabilityGaps,
+  REACHABILITY_GATE, runCommand,
   createEvidence, newId, computeInputTreeHash, hashCriteria,
   collectDeclaredTestNames, reconcileTestNames,
   resolveCommand, describeCommand, describeAllCommands, checkUnattendedRequirements, COMMANDS,
@@ -53,6 +56,7 @@ function showHelp() {
     cadet-agent harness confirm     Record manual-confirmation evidence (writes ledger + state)
     cadet-agent harness verify      Run a bounded, classified verification loop
     cadet-agent harness verify-acs  Verify declared AC↔test coverage against a test report
+    cadet-agent harness verify-reachability  Verify a story's declared reachability (opt-in)
     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
@@ -70,7 +74,7 @@ function showHelp() {
     --expires-at   ISO-8601 expiry bounding the confirmation (harness confirm)
     --environment  key=value,... describing what was verified (harness confirm)
     --scope        Comma-separated scope of the confirmation (harness confirm)
-    --story        Story markdown declaring the acceptance criteria (harness verify-acs)
+    --story        Story markdown declaring the acceptance criteria or reachability (harness verify-acs|verify-reachability)
     --report       Test report to derive the inventory from (harness verify-acs|matrix-check)
     --matrix       TDD matrix markdown to check (harness matrix-check)
     --inventory    Newline-separated test names, when no report is available (harness matrix-check)
@@ -552,7 +556,18 @@ async function cmdState(opts) {
     // ask "would this transition be allowed?" — running the command without the
     // flag applies the transition. A check that is documented as a dry run must
     // not have side effects, so the write below is gated on `!opts.dryRun`.
-    const evaluation = evaluateTransition(state, opts.to, { rootDir: opts.targetDir });
+    // `policy` is loaded here: `cmdState` does not otherwise need it, but the
+    // transition verdict does — the reachability gate joins the requirement only
+    // for a repository that has opted in (see requiredGates / REACHABILITY_GATE).
+    const transitionPolicy = loadPolicy(opts.targetDir);
+    // `strictClosure` is passed alongside the policy so strict closure (v3) is
+    // decided from the resolved repository policy on the CLI path too — the
+    // same verdict a library caller gets by passing the block explicitly.
+    const evaluation = evaluateTransition(state, opts.to, {
+      rootDir: opts.targetDir,
+      policy: transitionPolicy,
+      strictClosure: transitionPolicy.strictClosure,
+    });
     if (!evaluation.allowed) {
       const detail = {
         ok: false,
@@ -579,7 +594,13 @@ async function cmdState(opts) {
       );
       return;
     }
-    const next = applyTransition(state, opts.to, { rootDir: opts.targetDir });
+    // The same policy context the pre-check used, so the applied transition is
+    // judged by exactly the same rules that allowed it (reachability, strict closure).
+    const next = applyTransition(state, opts.to, {
+      rootDir: opts.targetDir,
+      policy: transitionPolicy,
+      strictClosure: transitionPolicy.strictClosure,
+    });
     writeState(opts.targetDir, next);
     emit(opts, `✅ Transitioned to ${opts.to}.`, { ok: true, allowed: true, dryRun: false, applied: true, to: opts.to });
     return;
@@ -665,7 +686,12 @@ async function cmdHarness(opts) {
     // A gate listed in disallowManualFor may never be satisfied by a human
     // assertion; point at the automated path instead of accepting the record.
     if (strict && Array.isArray(strict.disallowManualFor) && strict.disallowManualFor.includes(gate)) {
-      fail(opts, `manual-confirmation is not permitted for gate "${gate}" under strictClosure.disallowManualFor; run "cadet-agent harness verify --gate ${gate}" instead.`, () => 1, { ok: false, gate, code: 'manual-disallowed' });
+      // The reachability gate's automated path is its dedicated command, not
+      // `harness verify` — which is blocked for it as an agent-checkable gate.
+      const automatedPath = gate === REACHABILITY_GATE
+        ? '"cadet-agent harness verify-reachability --story <path>"'
+        : `"cadet-agent harness verify --gate ${gate}"`;
+      fail(opts, `manual-confirmation is not permitted for gate "${gate}" under strictClosure.disallowManualFor; run ${automatedPath} instead.`, () => 1, { ok: false, gate, code: 'manual-disallowed' });
     }
 
     // Bound the validity window: an expiry far in the future is how a manual
@@ -1104,6 +1130,158 @@ async function cmdHarness(opts) {
     return;
   }
 
+  if (sub === 'verify-reachability') {
+    // Mechanical reachability verification (contract v6 §2). A story declares how
+    // its deliverable becomes witnessable, or which work item will make it so;
+    // this checks that declaration against the work items that exist, and runs
+    // the repository's own probe when one is configured.
+    //
+    // WHY THE PROBE IS WHAT PROVES IT. Cadet cannot know how a given repository
+    // wires its pieces together, so a `witnessed` declaration is a statement and
+    // not a proof. The proof is the project's command, whose exit code is the
+    // verdict. Without one, the declaration level is all that is enforceable, and
+    // the output says so rather than implying more.
+    if (!opts.story) fail(opts, 'harness verify-reachability requires --story <path>');
+    // The story is resolved against the target repository, and the evidence
+    // binds to the REPO-RELATIVE path. An absolute path never resolves under
+    // the root when freshness is re-derived at transition time, so both hashes
+    // would be computed over a missing file and match — the staleness binding
+    // would be silently inert.
+    const storyPath = resolve(opts.targetDir, opts.story);
+    const storyRel = relative(opts.targetDir, storyPath).replace(/\\/g, '/') || basename(storyPath);
+    const { exists, state } = readState(opts.targetDir);
+    const enabled = policy.reachability?.enabled === true;
+    const probeCommand = policy.reachability?.command || null;
+    const workItemId = state ? workItemIdOf(state) : 'unscoped';
+    const phase = state?.session?.currentPhase || 'implementation';
+
+    let declaration;
+    try {
+      declaration = parseReachabilityDeclaration(storyPath);
+    } catch (err) {
+      fail(opts, `cannot read story "${opts.story}": ${err.message}`, () => 1, { ok: false, code: 'story-unreadable', story: opts.story });
+    }
+
+    const workItems = exists ? collectWorkItems(state) : null;
+    const validation = validateReachabilityDeclaration(declaration, { workItems, self: basename(storyPath) });
+
+    // The deferral graph over this story's own epic. A cycle is the gap no single
+    // declaration can reveal: every item in the loop points at another to explain
+    // why it is not witnessed. `workItems` supplies the epic-key aliases, so the
+    // long `epicKey::story.md` form and the bare file name resolve to one node
+    // regardless of where the story file physically sits.
+    const siblings = readSiblingDeclarations(storyPath, { workItems });
+    const graph = siblings.length > 0
+      ? siblings
+      : [{ id: basename(storyPath), aliases: [], declaration }];
+    const cycles = exists ? findDeferralCycles(graph) : [];
+
+    let probe = null;
+    if (enabled && probeCommand) {
+      const res = await runCommand(probeCommand, { cwd: opts.targetDir });
+      probe = {
+        command: probeCommand,
+        exitCode: res.exitCode,
+        ok: res.exitCode === 0,
+        durationMs: res.durationMs,
+        preview: String(res.preview || '').trim(),
+      };
+    }
+
+    const gaps = describeReachabilityGaps({ validation, cycles, story: opts.story });
+    const ok = validation.ok && cycles.length === 0 && (probe === null || probe.ok === true);
+
+    // NOT OPTED IN: report and write nothing. This is the compatibility rule that
+    // makes adopting the framework version a no-op for a repository that has not
+    // enabled the policy, and it mirrors how verify-acs behaves with
+    // strictClosure off. The finding still exits nonzero, because a caller who
+    // ran the command explicitly asked the question.
+    if (!enabled) {
+      if (opts.format === 'json') {
+        emit(opts, '', { ok, story: opts.story, declaration, reachability: validation, cycles, probe, gateSet: false, enabled: false });
+      } else if (ok) {
+        console.log(`✅ Reachability declared for ${opts.story}: ${validation.message}`);
+        console.log('   reachability.enabled is false — reported only, state.json unchanged.');
+      } else {
+        console.error(`⚠️  Reachability gaps in ${opts.story} (reachability.enabled is false — reported only):`);
+        for (const line of gaps) console.error(line);
+      }
+      if (!ok) process.exit(1);
+      return;
+    }
+
+    if (!ok) {
+      const detail = {
+        ok: false,
+        story: opts.story,
+        declaration,
+        reachability: validation,
+        cycles,
+        probe,
+        gateSet: false,
+        code: validation.ok !== true ? validation.code : (cycles.length > 0 ? 'deferral-cycle' : 'probe-failed'),
+      };
+      if (opts.format === 'json') emit(opts, '', detail);
+      else {
+        console.error(`❌ Cannot set ${REACHABILITY_GATE} for ${opts.story}:`);
+        for (const line of gaps) console.error(line);
+        if (probe && probe.ok !== true) {
+          console.error(`   the project probe "${probe.command}" exited ${probe.exitCode}: the declared reachability is not what the project can demonstrate.`);
+          if (probe.preview) console.error(`   probe output: ${probe.preview}`);
+        }
+      }
+      process.exit(1);
+    }
+
+    const at = new Date();
+    const evidence = createEvidence({
+      evidenceId: newId(),
+      workItemId,
+      acceptanceCriterionId: null,
+      phase,
+      gate: REACHABILITY_GATE,
+      status: 'passed',
+      command: `harness verify-reachability --story ${opts.story}`,
+      result: probe
+        ? `reachability addressed (${validation.code}); project probe exit ${probe.exitCode}`
+        : `reachability addressed (${validation.code}); no project probe configured`,
+      exitCode: 0,
+      inputTreeHash: computeInputTreeHash(opts.targetDir, [storyRel]),
+      criteriaHash: hashCriteria([
+        workItemId,
+        validation.code,
+        declaration.deferTo || declaration.witness || '',
+      ]),
+      relevantFiles: [storyRel],
+      createdAt: at,
+      expiresAt: null,
+      freshnessPolicy: { scope: 'story' },
+      source: 'automated',
+    });
+
+    // Ledger first, then state — the v3 ordering: fail toward "less proven".
+    const ledger = new RunLedger({ targetDir: opts.targetDir, policy, runId: state?.activeRunId || null, workItemId, phase });
+    ledger.addEvidence(evidence);
+    ledger.addDecision({ kind: 'stop', reason: `reachability addressed (${validation.code})`, scope: probe ? `probe exit ${probe.exitCode}` : 'declaration only' });
+    ledger.finalize({ status: 'ok' });
+    const ledgerPath = ledger.persist();
+
+    if (exists) {
+      const next = recordEvidence(state, evidence);
+      writeState(opts.targetDir, next);
+    }
+
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: true, story: opts.story, reachability: validation, cycles, probe, evidenceId: evidence.evidenceId, gateSet: exists, runId: ledger.runId, path: ledgerPath });
+    } else {
+      console.log(`✅ ${REACHABILITY_GATE} for ${opts.story}: ${validation.message}`);
+      if (probe) console.log(`   Project probe "${probe.command}" exited 0 (${probe.durationMs} ms).`);
+      else console.log('   No reachability.command configured — the declaration is checked, the wiring is not proven.');
+      console.log(`   Ledger: ${ledgerPath}`);
+    }
+    return;
+  }
+
   if (sub === 'report') {
     const runs = listRuns(opts.targetDir);
     const target = opts.runId || runs[0]?.runId;
@@ -1212,7 +1390,7 @@ async function cmdHarness(opts) {
     return;
   }
 
-  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|verify-acs|matrix-check|report|cleanup|capabilities.`);
+  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|verify-acs|verify-reachability|matrix-check|report|cleanup|capabilities.`);
 }
 
 export async function run(argv) {

package/src/harness/commands.mjs

@@ -110,6 +110,15 @@ export const COMMANDS = {
     writes: ['.cadet/runs/**', '.cadet/state.json', '*.coverage.json'],
     unattended: true,
   },
+  'harness verify-reachability': {
+    mutates: true,
+    summary: 'Verify a story\'s declared reachability, and run the project probe when configured.',
+    // Same posture as verify-acs: it records evidence for its gate, so it writes
+    // the ledger and state. It writes no artifact of its own — the declaration
+    // lives in the story and the project probe owns its own output.
+    writes: ['.cadet/runs/**', '.cadet/state.json'],
+    unattended: true,
+  },
   'harness report': {
     mutates: false,
     summary: 'Summarize budget consumption and failures.',

package/src/harness/index.mjs

@@ -10,6 +10,7 @@ export {
   DEFAULT_BUDGETS, HARD_CEILINGS, DEFAULT_ARCHIVE_LIMITS, DEFAULT_OUTPUT_POLICY,
   DEFAULT_RETENTION, DEFAULT_ESTIMATION, DEFAULT_HOOK_POLICY, DEFAULT_STRICT_CLOSURE,
   EXCEPTION_CATEGORIES, EXCEPTION_EXPIRY_DAYS, EXCEPTION_REQUIRES_REVIEW_NOTE, AGENT_OWNED_GATES,
+  DEFAULT_REACHABILITY, REACHABILITY_GATE,
   validatePolicy, defaultPolicy, loadPolicy, budgetForScope, policyPath, PolicyError,
 } from './policy.mjs';
 
@@ -82,6 +83,14 @@ export {
   collectDeclaredTestNames, reconcileTestNames, inventoryFromCSharpSources,
 } from './matrix-check.mjs';
 
+export {
+  REACHABILITY_KINDS, DEFAULT_MAX_STORY_BYTES, DEFAULT_MAX_SIBLING_STORIES,
+  normalizeWorkItemRef, collectWorkItems,
+  parseReachabilityDeclaration, parseReachabilityDeclarationText,
+  validateReachabilityDeclaration, findDeferralCycles, readSiblingDeclarations,
+  describeReachabilityGaps,
+} from './reachability.mjs';
+
 export {
   COMMANDS, mutatingCommands, readOnlyCommands, resolveCommand,
   describeCommand, describeAllCommands, checkUnattendedRequirements,

package/src/harness/policy.mjs

@@ -37,8 +37,51 @@ export const GATES = Object.freeze([
   'acceptanceCriteriaValidated',
   'securityReviewPassed',
   'designArtifactSyncConfirmed',
+  // APPENDED, never reordered: C3 forbids renaming a gate, and every recorded
+  // name must keep its meaning. This one is additionally OPT-IN — see
+  // REACHABILITY_GATE and DEFAULT_REACHABILITY below.
+  'reachabilityAddressed',
 ]);
 
+/**
+ * The gate that is required only when a repository enables the reachability
+ * policy.
+ *
+ * WHY IT IS CONDITIONAL RATHER THAN SIMPLY REQUIRED. Every existing consumer has
+ * stories written before the declaration existed, so making this mandatory at
+ * the matrix level would block every in-flight story on a framework update — the
+ * one thing a compatibility-preserving change must not do. The precedent is
+ * `strictClosure` and `allowEmptyFreshness`: a new guarantee ships behind a
+ * switch whose OFF state is byte-identical to the previous behaviour.
+ *
+ * WHAT TURNS IT ON: `reachability.enabled` in `.cadet/harness.json`. When it is
+ * on, `review -> validation` requires this gate; when it is off (the default)
+ * the gate list is exactly what it was before this gate existed.
+ */
+export const REACHABILITY_GATE = 'reachabilityAddressed';
+
+/**
+ * The transition (`from` phase) the reachability gate attaches to: entering
+ * `validation`, i.e. `review -> validation`. Named rather than inlined because
+ * the placement is a decision, and a later edit that silently moved it to
+ * implementation would ask for the wiring before the story has been reviewed.
+ */
+export const REACHABILITY_TRANSITION_FROM = 'review';
+
+/**
+ * Default reachability policy (contract v6 §2).
+ *
+ * `enabled: false` is deliberate and load-bearing: it is what makes adopting
+ * this framework version a no-op for a repository that has not opted in.
+ * `command: null` means no project-owned probe is configured, in which case the
+ * declaration is checked and the CLI states plainly that the wiring itself was
+ * not proven — rather than implying a guarantee it did not establish.
+ */
+export const DEFAULT_REACHABILITY = Object.freeze({
+  enabled: false,
+  command: null,
+});
+
 /**
  * Legal phase transitions (compatibility invariant C4, revised in contract v3).
  *
@@ -215,7 +258,13 @@ export const DEFAULT_STRICT_CLOSURE = Object.freeze({
     // rejected as future-dated.
     clockSkewToleranceMs: 60 * 1000,
   }),
-  disallowManualFor: Object.freeze(['testsPassed']),
+  // `reachabilityAddressed` is in the default set because, whenever the
+  // repository has opted in, the gate is mechanically checkable by
+  // `harness verify-reachability` — the declaration check runs even with no
+  // probe configured — so a manual assertion can add nothing and can skip the
+  // declaration entirely (contract v6 §2). With strictClosure off the refusal
+  // does not apply, matching how `testsPassed` is treated.
+  disallowManualFor: Object.freeze(['testsPassed', 'reachabilityAddressed']),
 });
 
 const STRICT_CLOSURE_KEYS = new Set([
@@ -397,6 +446,49 @@ function resolveStrictClosure(raw) {
   return out;
 }
 
+/**
+ * Resolve and validate the `reachability` policy block (contract v6 §2).
+ *
+ * Rejected rather than tolerated:
+ *   - a `command` set while `enabled` is false, because the probe would never
+ *     run. An inert setting is worse than an absent one: it reads as a guard
+ *     that exists.
+ *   - an empty-string command, which is not a probe.
+ *   - any unknown key, so a typo fails loudly instead of silently defaulting.
+ */
+function resolveReachability(raw) {
+  if (raw === undefined) return { ...DEFAULT_REACHABILITY };
+  if (!isPlainObject(raw)) throw new PolicyError('"reachability" must be an object.');
+
+  for (const key of Object.keys(raw)) {
+    if (key !== 'enabled' && key !== 'command') {
+      throw new PolicyError(`Unknown "reachability" key "${key}".`);
+    }
+  }
+  if (raw.enabled !== undefined && typeof raw.enabled !== 'boolean') {
+    throw new PolicyError('"reachability.enabled" must be a boolean.');
+  }
+  if (raw.command !== undefined && raw.command !== null && typeof raw.command !== 'string') {
+    throw new PolicyError('"reachability.command" must be a string or null.');
+  }
+  // A command key that is present but blank is a probe that would never run —
+  // rejected, rather than silently normalized to null and forgotten.
+  if (typeof raw.command === 'string' && raw.command.trim() === '') {
+    throw new PolicyError('"reachability.command" is empty; omit it, or give the probe command to run.');
+  }
+
+  const out = {
+    enabled: raw.enabled === true,
+    command: typeof raw.command === 'string' ? raw.command.trim() : null,
+  };
+
+  if (out.enabled !== true && out.command !== null) {
+    throw new PolicyError('"reachability.command" is set but "reachability.enabled" is false; the probe would never run. Enable reachability or remove the command.');
+  }
+
+  return out;
+}
+
 /**
  * Parse and validate a repository harness policy document.
  * Unknown top-level keys are rejected so misconfiguration fails loudly.
@@ -410,6 +502,7 @@ export function validatePolicy(raw, defaults = DEFAULT_BUDGETS) {
     'budgets', 'archive', 'output', 'retention', 'estimation', 'hook',
     'allowBudgetCeilingOverride', 'scopes', 'model', 'analyzerCommand',
     'compileCommand', 'testCommand', 'allowEmptyFreshness', 'strictClosure',
+    'reachability',
   ]);
   for (const key of Object.keys(raw)) {
     if (!allowed.has(key)) {
@@ -476,6 +569,7 @@ export function validatePolicy(raw, defaults = DEFAULT_BUDGETS) {
 
   const allowCeilingOverride = raw.allowBudgetCeilingOverride === true;
   const strictClosure = resolveStrictClosure(raw.strictClosure);
+  const reachability = resolveReachability(raw.reachability);
 
   const resolved = {
     budgets,
@@ -487,6 +581,7 @@ export function validatePolicy(raw, defaults = DEFAULT_BUDGETS) {
     allowBudgetCeilingOverride: allowCeilingOverride,
     allowEmptyFreshness: raw.allowEmptyFreshness === true,
     strictClosure,
+    reachability,
     scopes: raw.scopes || { perRun: {}, perStory: {} },
     model: raw.model || null,
     analyzerCommand: raw.analyzerCommand || null,