cadet-agent 0.43.1 → 0.45.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.43.1",
+  "version": "0.45.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,

package/src/harness/reachability.mjs

@@ -0,0 +1,431 @@
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+/**
+ * Mechanical reachability verification (Harness contract v6).
+ *
+ * Closes a defect class the framework previously had no check for at all: work
+ * that is fully tested and fully compiled while being reachable from nothing.
+ * Every gate could be green for many stories in a row and no user could reach a
+ * single one of them, because nothing asserted that a delivered capability is
+ * WIRED to anything a user or operator can touch.
+ *
+ * Three responsibilities:
+ *   1. parseReachabilityDeclaration — read a story's declared reachability: how
+ *      its deliverable becomes witnessable, or which work item will make it so.
+ *   2. validateReachabilityDeclaration — check the declaration against the work
+ *      items that exist, so a deferral cannot name a phantom target.
+ *   3. reconcileDeferrals — the falsifiability check. A deferral is a claim
+ *      about the future, so it is re-examined once its target is `done`: a
+ *      deferral that outlives its owner is a gap wearing a plan's clothes.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: it cannot know how a given project wires
+ * things, so a `witnessed` declaration is treated as a STATEMENT, not a proof.
+ * The proof comes from the project's own command
+ * (`reachability.command` in .cadet/harness.json), which the CLI runs and whose
+ * exit code is the verdict. That split is the point: a generic rule that tried
+ * to guess per-project wiring would be wrong often enough to be switched off,
+ * which is how a check erodes. No project command configured means the
+ * declaration level is all that is enforceable, and the CLI says so rather than
+ * implying a stronger guarantee.
+ *
+ * Nothing here passes on missing input: a story that declares nothing is a
+ * failure, not a default. Silence is not reachability, exactly as an acceptance
+ * criterion that declares no test is not coverage.
+ */
+
+export const REACHABILITY_KINDS = Object.freeze(['witnessed', 'deferred']);
+
+/** Bound on how much of a story is scanned, mirroring the report bound in verify-acs. */
+export const DEFAULT_MAX_STORY_BYTES = 1024 * 1024;
+
+/** Bound on sibling stories scanned for the deferral graph. */
+export const DEFAULT_MAX_SIBLING_STORIES = 200;
+
+/**
+ * Normalize a work-item reference so `epic::story.md`, `story.md` and a bare
+ * epic id can be compared.
+ *
+ * The canonical form is `epicKey::storyFile` (what state.json stores). Anything
+ * else is resolved leniently: a bare file name matches an existing story file,
+ * and an epic key matches that epic. Case-insensitive, because a hand-written
+ * deferral target is prose-adjacent and casing drift is not the defect this
+ * check exists to catch.
+ */
+export function normalizeWorkItemRef(ref) {
+  if (ref === null || ref === undefined) return '';
+  const s = String(ref).trim().replace(/\\/g, '/');
+  const withoutAnchor = s.replace(/^#/, '');
+  return withoutAnchor.toLowerCase();
+}
+
+/**
+ * Extract the set of work items that exist, from a state document.
+ *
+ * Includes stories (`epic::story`), bare story file names and epic keys, plus
+ * spike ids — deferring to a spike is legitimate, because a spike is exactly how
+ * an unverified assumption becomes a deliverable.
+ *
+ * Returns `{ refs, status }` where `refs` is a Set of normalized references and
+ * `status` maps a normalized reference to `'done' | 'planned' | 'in-progress' |
+ * 'complete' | 'planned'` so the caller can tell an in-flight target from a
+ * finished one.
+ */
+export function collectWorkItems(state) {
+  const refs = new Set();
+  const status = new Map();
+
+  const add = (ref, value) => {
+    const key = normalizeWorkItemRef(ref);
+    if (!key) return;
+    refs.add(key);
+    if (value) status.set(key, String(value).toLowerCase());
+  };
+
+  const epics = state && typeof state === 'object' && state.epics && typeof state.epics === 'object'
+    ? state.epics
+    : {};
+
+  for (const [epicKey, epic] of Object.entries(epics)) {
+    const epicStatus = epic && typeof epic === 'object' ? epic.status : undefined;
+    add(epicKey, epicStatus);
+    const stories = epic && typeof epic.stories === 'object' ? epic.stories : {};
+    for (const [storyFile, storyStatus] of Object.entries(stories)) {
+      const full = `${epicKey}::${storyFile}`;
+      add(full, storyStatus);
+      add(storyFile, storyStatus);
+    }
+  }
+
+  const spikes = state && typeof state === 'object' && state.spikes && typeof state.spikes === 'object'
+    ? state.spikes
+    : {};
+  for (const [spikeId, spikeStatus] of Object.entries(spikes)) {
+    add(spikeId, spikeStatus);
+  }
+
+  const active = state && typeof state === 'object' ? state.activeWorkItem : null;
+  if (active && active.epicId && active.storyId) {
+    add(`${active.epicId}::${active.storyId}`);
+    add(active.storyId);
+  }
+
+  return { refs, status };
+}
+
+/**
+ * Parse a story's reachability declaration.
+ *
+ * Expected shape (per the story template), one line, in the story header block:
+ *
+ *   Reachability: witnessed — <what a user/operator does and what they see>
+ *   Reachability: deferred to <work-item ref> — <why it cannot be witnessed yet>
+ *
+ * Returns `{ declared, kind, witness, deferTo, reason, line, errors }`.
+ * `errors` is non-empty only for a MALFORMED declaration (a recognised keyword
+ * with no content). A story with no declaration at all is `declared: false`,
+ * which the validator reports as a gap rather than a parse error — the two are
+ * different findings and the caller keeps them apart.
+ *
+ * Fenced code blocks are skipped, so a story may quote an example declaration in
+ * a note without it being mistaken for its own.
+ */
+export function parseReachabilityDeclarationText(text, { maxBytes = DEFAULT_MAX_STORY_BYTES } = {}) {
+  const raw = typeof text === 'string' ? text : String(text ?? '');
+  const body = raw.length > maxBytes ? raw.slice(0, maxBytes) : raw;
+  const lines = body.split(/\r?\n/);
+
+  const errors = [];
+  let inFence = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (/^```/.test(trimmed)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    const m = /^Reachability\s*:\s*(.*)$/i.exec(trimmed);
+    if (!m) continue;
+
+    const rest = m[1].trim();
+    const line = i + 1;
+    if (rest === '') {
+      errors.push(`line ${line}: "Reachability:" declares nothing — state either "witnessed — <how>" or "deferred to <work item> — <why>".`);
+      return { declared: false, kind: null, witness: null, deferTo: null, reason: '', line, errors };
+    }
+
+    const deferred = /^deferred\s+to\s+(\S+)\s*(?:[—-]\s*(.*))?$/i.exec(rest);
+    if (deferred) {
+      const target = deferred[1].replace(/[.,;]$/, '');
+      const reason = (deferred[2] || '').trim();
+      if (!reason) {
+        errors.push(`line ${line}: a deferral must say WHY it cannot be witnessed yet ("deferred to ${target} — <reason>"); an unexplained deferral is how a gap becomes permanent.`);
+      }
+      return { declared: true, kind: 'deferred', witness: null, deferTo: target, reason, line, errors };
+    }
+
+    const witnessed = /^witnessed\s*(?:[—-]\s*(.*))?$/i.exec(rest);
+    if (witnessed) {
+      const witness = (witnessed[1] || '').trim();
+      if (witness === '') {
+        errors.push(`line ${line}: "witnessed" must say what a user or operator does and what they see ("witnessed — <how>").`);
+      }
+      return { declared: true, kind: 'witnessed', witness, deferTo: null, reason: '', line, errors };
+    }
+
+    // A line that begins "Reachability:" with an unrecognised form. Reported
+    // rather than ignored: an ignored declaration is indistinguishable from a
+    // missing one, and a story that is wrong in a new way must not read as a
+    // story that is fine.
+    errors.push(`line ${line}: unrecognised reachability declaration "${rest}" — expected "witnessed — <how>" or "deferred to <work item> — <why>".`);
+    return { declared: false, kind: null, witness: null, deferTo: null, reason: '', line, errors };
+  }
+
+  return { declared: false, kind: null, witness: null, deferTo: null, reason: '', line: null, errors };
+}
+
+/** File variant of parseReachabilityDeclarationText. */
+export function parseReachabilityDeclaration(storyPath) {
+  const text = readFileSync(storyPath, 'utf-8');
+  return parseReachabilityDeclarationText(text);
+}
+
+/**
+ * Validate one declaration against the work items that exist.
+ *
+ * Returns `{ ok, code, message }`. Codes are stable so a caller can branch and a
+ * test can assert the FINDING rather than the prose:
+ *   malformed               — the declaration parsed with errors. Checked FIRST:
+ *                             a reasonless deferral or a content-free "witnessed"
+ *                             parses far enough to be typed, and must still be
+ *                             refused — the parser said no, and the parser's no
+ *                             is the rule (contract v6 §1).
+ *   not-declared            — the story declares nothing at all.
+ *   deferral-self           — a deferral names the story itself (`self`).
+ *   unknown-target          — a deferral names a work item that does not exist.
+ *   deferral-target-done    — a deferral names a work item that is already done,
+ *                             so the witness it promised can never arrive.
+ *
+ * `self` is the story's own reference (bare file name, or a list of its
+ * references) so a story cannot be made "reachable" by deferring to itself.
+ *
+ * `deferral-target-done` is the tooth that matters. A deferral is only honest
+ * while its owner is still ahead; once the owner lands, the deferral is a claim
+ * that has been overtaken by events, and it is reported as a gap rather than
+ * inherited forever.
+ */
+export function validateReachabilityDeclaration(declaration, { workItems = null, self = null } = {}) {
+  if (declaration && Array.isArray(declaration.errors) && declaration.errors.length > 0) {
+    return { ok: false, code: 'malformed', message: declaration.errors.join(' ') };
+  }
+
+  if (!declaration || declaration.declared !== true) {
+    return {
+      ok: false,
+      code: 'not-declared',
+      message: 'the story declares no reachability — add "Reachability: witnessed — <how a user/operator reaches and sees this>" or "Reachability: deferred to <work item> — <why>". A story that says nothing about reachability is indistinguishable from one whose deliverable cannot be reached.',
+    };
+  }
+
+  if (declaration.kind === 'witnessed') {
+    return { ok: true, code: 'witnessed', message: `witnessed: ${declaration.witness}` };
+  }
+
+  // Deferred.
+  const target = declaration.deferTo;
+  const selfRefs = Array.isArray(self)
+    ? self.map(normalizeWorkItemRef)
+    : (self ? [normalizeWorkItemRef(self)] : []);
+  if (selfRefs.length > 0 && selfRefs.includes(normalizeWorkItemRef(target))) {
+    return {
+      ok: false,
+      code: 'deferral-self',
+      message: `the deferral names "${target}", which is this story itself. A story cannot be made reachable by deferring to itself: declare "witnessed", or name the work item that will wire it.`,
+    };
+  }
+  if (!workItems) {
+    // No state to check against — the target cannot be verified, and "cannot
+    // verify" is reported as such rather than assumed fine.
+    return { ok: true, code: 'deferred-unchecked', message: `deferred to ${target} (no state document to check the target against)` };
+  }
+
+  const key = normalizeWorkItemRef(target);
+  if (!workItems.refs.has(key)) {
+    const known = [...workItems.refs].filter((r) => r.includes('::')).slice(0, 8);
+    return {
+      ok: false,
+      code: 'unknown-target',
+      message: `the deferral names "${target}", which is not a work item in state.json. A deferral to something that does not exist never expires and never lands. Known work items include: ${known.join(', ') || '(none)'}.`,
+    };
+  }
+
+  const status = workItems.status.get(key);
+  if (status === 'done' || status === 'complete') {
+    return {
+      ok: false,
+      code: 'deferral-target-done',
+      message: `the deferral names "${target}", which is already ${status}. The work item that was going to make this reachable has landed, so the deferral has expired: either this story is reachable now (declare "witnessed") or the wiring was missed when "${target}" closed.`,
+    };
+  }
+
+  return { ok: true, code: 'deferred', message: `deferred to ${target} (${status || 'unknown status'})` };
+}
+
+/**
+ * Build a deferral graph from a set of declarations and report every cycle.
+ *
+ * A chain of deferrals that closes on itself is not a plan: nothing in the loop
+ * is ever witnessed, and each item can point at another to explain why. The
+ * cycle is reported as one finding naming the whole chain, because naming a
+ * single node would hide the shape that makes it a gap.
+ *
+ * `declarations` is an array of `{ id, aliases?, declaration }`. `aliases` lets
+ * one node carry both the `epicKey::story.md` form and the bare file name.
+ */
+export function findDeferralCycles(declarations) {
+  // An entry may carry ALIASES (`epicKey::story.md` and the bare `story.md` are
+  // the same node). Without them, a deferral written in the long form and a
+  // sibling found by file name would be two disconnected nodes and a real cycle
+  // would go unreported - a check that cannot see the edge it exists to find.
+  const aliasToNode = new Map();
+  for (const entry of declarations || []) {
+    if (!entry || !entry.id) continue;
+    const ids = [entry.id, ...(Array.isArray(entry.aliases) ? entry.aliases : [])];
+    for (const alias of ids) aliasToNode.set(normalizeWorkItemRef(alias), normalizeWorkItemRef(entry.id));
+  }
+
+  const resolve = (ref) => aliasToNode.get(normalizeWorkItemRef(ref)) ?? normalizeWorkItemRef(ref);
+
+  const target = new Map();
+  for (const entry of declarations || []) {
+    if (entry && entry.declaration && entry.declaration.kind === 'deferred' && entry.declaration.deferTo) {
+      target.set(normalizeWorkItemRef(entry.id), resolve(entry.declaration.deferTo));
+    }
+  }
+
+  const cycles = [];
+  const seenCycleKeys = new Set();
+
+  for (const start of target.keys()) {
+    const path = [];
+    const onPath = new Set();
+    let node = start;
+
+    while (node && target.has(node)) {
+      if (onPath.has(node)) {
+        const at = path.indexOf(node);
+        const chain = path.slice(at);
+        // Canonicalize so the same cycle found from two entry points is one finding.
+        const key = [...chain].sort().join('|');
+        if (!seenCycleKeys.has(key)) {
+          seenCycleKeys.add(key);
+          cycles.push([...chain, node]);
+        }
+        break;
+      }
+      onPath.add(node);
+      path.push(node);
+      node = target.get(node);
+    }
+  }
+
+  return cycles;
+}
+
+/**
+ * Read a story and every sibling `story-*.md` in its directory, and parse each
+ * declaration, so the deferral graph covers the epic rather than one story. The
+ * story itself is ALWAYS a node — its own declaration must participate in the
+ * cycle graph even when its file name does not match the `story-*` pattern.
+ *
+ * Aliases tie the `epicKey::story.md` form and the bare file name to ONE node;
+ * without them a real cycle written in the long form goes unreported (contract
+ * v6 §4.2). The epic key is taken from the caller's work-item index when
+ * supplied — every `epicKey::name` ref that actually exists in state.json —
+ * because deriving it from the directory name is only a heuristic: a bare
+ * relative filename has dirname `.`, and any other layout may not be named
+ * after the epic at all. The directory-name derivation remains as a fallback
+ * for callers without state.
+ *
+ * Returns `[{ id, aliases, path, declaration }]`. Unreadable files are skipped
+ * rather than fatal: the check is about the story under test, and an unreadable
+ * sibling must not turn a reachability verdict into a filesystem error.
+ */
+export function readSiblingDeclarations(storyPath, { max = DEFAULT_MAX_SIBLING_STORIES, workItems = null } = {}) {
+  const dir = dirname(storyPath);
+  // Heuristic fallback: the epic directory's own name is often the epic key
+  // state.json uses. Unreliable on its own — see the docstring above.
+  const dirKey = dir.replace(/\\/g, '/').split('/').filter(Boolean).pop() || '';
+
+  const aliasesFor = (name) => {
+    const key = normalizeWorkItemRef(name);
+    const aliases = new Set();
+    if (dirKey) aliases.add(normalizeWorkItemRef(`${dirKey}::${name}`));
+    if (workItems && workItems.refs) {
+      for (const ref of workItems.refs) {
+        if (ref.endsWith(`::${key}`)) aliases.add(ref);
+      }
+    }
+    aliases.delete(key);
+    return [...aliases];
+  };
+
+  const out = [];
+  const seen = new Set();
+  const add = (name, path) => {
+    const id = normalizeWorkItemRef(name);
+    if (seen.has(id)) return;
+    seen.add(id);
+    try {
+      out.push({
+        id: name,
+        aliases: aliasesFor(name),
+        path,
+        declaration: parseReachabilityDeclaration(path),
+      });
+    } catch {
+      // A file that cannot be read is not this verdict's business.
+    }
+  };
+
+  // The story itself, always — its own deferral edges are the ones being judged.
+  add(basename(storyPath), storyPath);
+
+  let entries = null;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    entries = null;
+  }
+  if (entries) {
+    for (const name of entries.sort()) {
+      if (out.length >= max) break;
+      if (!/^story-.*\.md$/i.test(name)) continue;
+      const path = join(dir, name);
+      if (!existsSync(path)) continue;
+      add(name, path);
+    }
+  }
+  return out;
+}
+
+/**
+ * Format reachability gaps as concrete, actionable lines, in the shape
+ * `describeCoverageGaps` uses for AC gaps so the two read consistently in a
+ * terminal.
+ */
+export function describeReachabilityGaps({ validation, cycles = [], story } = {}) {
+  const lines = [];
+  if (validation && validation.ok !== true) {
+    lines.push(`   reachability: ${validation.message}`);
+  }
+  for (const cycle of cycles) {
+    lines.push(`   reachability deferral cycle: ${cycle.join(' -> ')} — nothing in this loop can ever be witnessed; at least one item must become "witnessed" or the chain is a gap.`);
+  }
+  if (lines.length > 0 && story) {
+    lines.unshift(`   story: ${story}`);
+  }
+  return lines;
+}

package/src/harness/state.mjs

@@ -8,13 +8,18 @@
  */
 
 import { readFileSync, writeFileSync, renameSync, copyFileSync, existsSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, isAbsolute, join } from 'node:path';
 import {
   PHASES, GATES, TRANSITIONS, EVIDENCE_STATUSES, DEFAULT_STRICT_CLOSURE,
   EXCEPTION_CATEGORIES, EXCEPTION_EXPIRY_DAYS, EXCEPTION_REQUIRES_REVIEW_NOTE,
+  REACHABILITY_GATE, REACHABILITY_TRANSITION_FROM,
 } from './policy.mjs';
 import { hashTree, hashFile, hashCriteria, timestamp, isUuid } from './util.mjs';
 import { encodeEvidenceTrailers } from './gitmemo.mjs';
+import {
+  parseReachabilityDeclaration, validateReachabilityDeclaration, collectWorkItems,
+  findDeferralCycles, readSiblingDeclarations,
+} from './reachability.mjs';
 
 export { PHASES, GATES, TRANSITIONS, EVIDENCE_STATUSES };
 export { EXCEPTION_CATEGORIES, EXCEPTION_EXPIRY_DAYS };
@@ -1092,9 +1097,25 @@ export function activeExceptions(state, { workItemId, now = new Date() } = {}) {
 // ── Transitions ─────────────────────────────────────────────────────────────
 
 /** Required gates for a transition target, or null when the target is not gated. */
-export function requiredGates(toPhase) {
+export function requiredGates(toPhase, { reachability = false } = {}) {
   for (const [from, spec] of Object.entries(TRANSITIONS)) {
-    if (spec.to === toPhase) return { from, gates: spec.gates, revalidate: spec.revalidate || [] };
+    if (spec.to === toPhase) {
+      const gates = [...spec.gates];
+      // The reachability gate is appended ONLY to the review -> validation
+      // transition, and only when the repository has opted in
+      // (`reachability.enabled`). Two reasons for both halves of that:
+      //
+      //   - PLACEMENT: reachability is a claim about a delivered, reviewed story,
+      //     so it is checked at the same point as the review gates rather than at
+      //     implementation, where the wiring may legitimately not exist yet.
+      //   - OPT-IN: an entering-`review` requirement would block every in-flight
+      //     story in every existing consumer on a framework update. With the
+      //     default OFF the list is exactly what the matrix declares, so a
+      //     single-argument call — and every existing caller and test — sees
+      //     unchanged behaviour. See REACHABILITY_GATE.
+      if (reachability && from === REACHABILITY_TRANSITION_FROM) gates.push(REACHABILITY_GATE);
+      return { from, gates, revalidate: spec.revalidate || [] };
+    }
   }
   return null;
 }
@@ -1205,6 +1226,60 @@ function checkGate({ gate, state, gates, exceptions, now, workItemId, fromPhase,
   return { missingGates, staleEvidence };
 }
 
+/**
+ * Re-derive the opted-in reachability declaration against the CURRENT state at
+ * `validation -> closed` (contract v6 §4, closure re-examination). A deferral
+ * is a claim about the future, so closure re-reads the story's declaration and
+ * re-validates it the same way `harness verify-reachability` does: a deferral
+ * whose target is now `done`, one whose target has vanished, or a cycle that
+ * has since formed all refuse closure. The evidence record is used only to
+ * LOCATE the story file — its hashes and phase stamp are deliberately not
+ * re-checked, because the record is legitimately created during `review` and
+ * the phase/recency freshness machinery would wrongly reject it here.
+ */
+function recheckReachabilityAtClosure({ state, rootDir }) {
+  const missingGates = [];
+  const staleEvidence = [];
+  const refuse = (reasons) => {
+    missingGates.push(REACHABILITY_GATE);
+    staleEvidence.push({ gate: REACHABILITY_GATE, reasons });
+    return { missingGates, staleEvidence };
+  };
+
+  const record = latestEvidenceForGate(state, REACHABILITY_GATE);
+  if (!record) {
+    return refuse(['no reachability evidence record for the opted-in gate']);
+  }
+  const relevant = Array.isArray(record.relevantFiles) ? record.relevantFiles : [];
+  const storyRef = relevant[0];
+  if (!storyRef) {
+    return refuse(['the reachability evidence record names no story file']);
+  }
+  // Records written since the path-binding fix hold a repo-relative path; older
+  // ones may hold an absolute path, which is used as-is.
+  const storyPath = isAbsolute(storyRef) ? storyRef : join(rootDir, storyRef);
+
+  let declaration;
+  try {
+    declaration = parseReachabilityDeclaration(storyPath);
+  } catch (err) {
+    return refuse([`cannot read the declared story "${storyRef}": ${err.message}`]);
+  }
+
+  const workItems = collectWorkItems(state);
+  const selfName = basename(storyRef.replace(/\\/g, '/'));
+  const validation = validateReachabilityDeclaration(declaration, { workItems, self: selfName });
+  const cycles = findDeferralCycles(readSiblingDeclarations(storyPath, { workItems }));
+
+  const reasons = [];
+  if (validation.ok !== true) reasons.push(validation.message);
+  for (const cycle of cycles) {
+    reasons.push(`reachability deferral cycle: ${cycle.join(' -> ')} — nothing in this loop can ever be witnessed`);
+  }
+  if (reasons.length > 0) return refuse(reasons);
+  return { missingGates, staleEvidence };
+}
+
 /**
  * Evaluate whether a transition is legal and evidence-backed.
  * Returns a machine-readable result:
@@ -1231,7 +1306,9 @@ export function evaluateTransition(state, toPhase, context = {}) {
     return { allowed: false, fromPhase, toPhase, missingGates, staleEvidence, errors, revalidated: [] };
   }
 
-  const spec = requiredGates(toPhase);
+  // The reachability gate joins the requirement only when the repository has
+  // opted in, so a project that has not sees the pre-existing gate list exactly.
+  const spec = requiredGates(toPhase, { reachability: context.policy?.reachability?.enabled === true });
   if (!spec) {
     // Ungated transitions are legal ONLY along the declared forward edges
     // (bootstrap + planning progression). A target that is neither gated nor a
@@ -1280,6 +1357,21 @@ export function evaluateTransition(state, toPhase, context = {}) {
       missingGates.push(...r.missingGates);
       staleEvidence.push(...r.staleEvidence);
     }
+
+    // Contract v6 §4: an opted-in reachability declaration is ALSO re-examined
+    // at `validation -> closed`. This is deliberately NOT routed through the
+    // freshness machinery the other revalidated gates use — the record is
+    // legitimately created during `review`, so phase- and recency-staleness
+    // would wrongly reject it — so the conditional append lives here rather
+    // than in the TRANSITIONS table (which stays exactly as C4 declares it).
+    if (toPhase === 'closed' && context.policy?.reachability?.enabled === true) {
+      revalidated.push(REACHABILITY_GATE);
+      if (!exceptions[REACHABILITY_GATE]) {
+        const r = recheckReachabilityAtClosure({ state, rootDir });
+        missingGates.push(...r.missingGates);
+        staleEvidence.push(...r.staleEvidence);
+      }
+    }
   }
 
   return {
@@ -1299,12 +1391,16 @@ export function evaluateTransition(state, toPhase, context = {}) {
  * Resets the target transition's gates is NOT done here — gates reset when a new
  * work item starts (see `resetGatesForNewWorkItem`).
  */
-export function applyTransition(state, toPhase, { evidenceIds = [], at = new Date(), inputTreeHash = undefined, criteriaHash = undefined, rootDir = undefined, strictClosure = undefined } = {}) {
+export function applyTransition(state, toPhase, { evidenceIds = [], at = new Date(), inputTreeHash = undefined, criteriaHash = undefined, rootDir = undefined, strictClosure = undefined, policy = undefined } = {}) {
   const context = { now: at };
   if (inputTreeHash !== undefined) context.inputTreeHash = inputTreeHash;
   if (criteriaHash !== undefined) context.criteriaHash = criteriaHash;
   if (rootDir !== undefined) context.rootDir = rootDir;
   if (strictClosure !== undefined) context.strictClosure = strictClosure;
+  // The resolved policy, so conditional gates (contract v6 `reachability`) are
+  // enforced by the internal re-evaluation too — not just by the caller's own
+  // pre-check. A library caller that omits it gets the pre-v6 gate list.
+  if (policy !== undefined) context.policy = policy;
   const evaluation = evaluateTransition(state, toPhase, context);
   if (!evaluation.allowed) {
     throw new StateError(