cadet-agent 0.56.0 → 0.63.1

package/src/harness/gates.mjs

@@ -43,7 +43,7 @@
  * Contract: docs/core/HarnessContract.md C14.
  */
 
-import { GATES, REACHABILITY_GATE, MANUAL_ONLY_GATES } from './policy.mjs';
+import { GATES, REACHABILITY_GATE, MANUAL_ONLY_GATES, USER_PLAY_GATE } from './policy.mjs';
 
 /**
  * Who owns the evidence for a gate.
@@ -186,6 +186,28 @@ export const GATE_BUILDERS = Object.freeze({
     binds: 'files',
     attests: 'a named person accepted the delivered work against a stated witness, with the limitations they accepted',
   },
+  userPlaythroughConfirmed: {
+    owner: 'human',
+    contract: 1,
+    // No automated path and no project override, for the same reason
+    // humanAcceptanceConfirmed has neither: the gate asks whether a PERSON played the
+    // delivered work. A command cannot answer it, and neither can a reviewer's record —
+    // the record's substance is the person's own account of what they played and what
+    // they saw, so the route is to ask them for it and record their answer with
+    // `harness confirm --gate userPlaythroughConfirmed --reason "<their answer>"`, and
+    // `verify-play` refuses to record a `required` declaration on their behalf.
+    automatedPath: null,
+    command: null,
+    projectCommand: false,
+    manual: true,
+    // `files`, where its sibling `reachabilityAddressed` binds `story`. The difference is
+    // the subject: reachability's evidence is a declaration about a work item, while this
+    // gate's evidence is an account of a build the person actually ran, so a later edit to
+    // the sources that produced it must invalidate the record. The deferral route
+    // (`Play: deferred to <work item>`) binds the story, which is where the declaration is.
+    binds: 'files',
+    attests: 'a named person played the delivered work and recorded what they did and what they saw',
+  },
   codeReviewCompleted: {
     owner: 'agent',
     contract: 1,
@@ -360,5 +382,11 @@ export function auditGateRegistry() {
   if (gateBuilder(REACHABILITY_GATE)?.projectCommand !== false) {
     problems.push(`gate "${REACHABILITY_GATE}" must not accept a project command`);
   }
+  if (gateBuilder(USER_PLAY_GATE)?.projectCommand !== false) {
+    problems.push(`gate "${USER_PLAY_GATE}" must not accept a project command`);
+  }
+  if (gateBuilder(USER_PLAY_GATE)?.owner !== 'human') {
+    problems.push(`gate "${USER_PLAY_GATE}" must stay human-owned: a person plays the work`);
+  }
   return problems;
 }

package/src/harness/index.mjs

@@ -13,6 +13,7 @@ export {
   DEFAULT_REACHABILITY, REACHABILITY_GATE,
   DEFAULT_DESIGN_REVIEW, DESIGN_REVIEW_GATE, DESIGN_REVIEW_TRANSITION_FROM,
   DEFAULT_HUMAN_ACCEPTANCE, HUMAN_ACCEPTANCE_GATE, HUMAN_ACCEPTANCE_TRANSITION_FROM,
+  DEFAULT_USER_PLAY, USER_PLAY_GATE, USER_PLAY_TRANSITION_FROM,
   DEFAULT_ARCHITECTURE_FITNESS, ARCHITECTURE_GATE, ARCHITECTURE_TRANSITION_FROM,
   ARCHITECTURE_TRANSITION_TO, CHECK_SEVERITIES, architectureFitnessActive,
   validatePolicy, defaultPolicy, loadPolicy, budgetForScope, policyPath, PolicyError,
@@ -46,6 +47,7 @@ export {
   HISTORY_ENTRIES_KEPT, MAX_HISTORY_ENTRY_CHARS, historyEntryLength, compactHistory, DEFAULT_MAX_LIVE_EVIDENCE, retainLiveRecords,
   createEvidence, computeInputTreeHash, workItemIdOf, evidenceFreshness,
   latestEvidenceForGate, activeExceptions, requiredGates, conditionalEdgeGates, isUngatedForwardEdge,
+  buildStateBrief, renderStateBrief, legalEdgesFrom,
   evaluateTransition, resolveStrict,
   applyTransition, resetGatesForNewWorkItem, statePathFor, readState, writeState, writeJsonAtomic, StateError,
 } from './state.mjs';
@@ -71,7 +73,8 @@ export {
 } from './hosts.mjs';
 
 export {
-  CONTEXT_LEVELS, CONTEXT_DIR, CONTEXT_PLAN_FILE, CONTEXT_RECORD_FILE, PHASE_SKILL,
+  CONTEXT_LEVELS, CONTEXT_DIR, CONTEXT_PLAN_FILE, CONTEXT_RECORD_FILE, CONTEXT_BRIEF_FILE, PHASE_SKILL,
+  writeStateBrief, resolveWorkItemDocs,
   ContextProtocolError, planEntries, buildContextPlan, writeContextPlan, readContextPlan,
   buildContextRecord, writeContextRecord, readContextRecord, parseTranscript,
   validateContextRecord, describeContextState, declaresContextEnforcement,
@@ -82,12 +85,6 @@ export {
   runArchitectureChecks, summariseChecks, describeCheckResults,
 } from './architecture.mjs';
 
-export {
-  ACCEPTANCE_FORM_GATE, ACCEPTANCE_FORM_FILENAME, ACCEPTANCE_TEMPLATE_RELATIVE,
-  ACCEPTANCE_HUMAN_FIELDS, acceptanceFormPath, acceptanceCandidates, buildAcceptanceForm,
-  parseAcceptanceForm, writeAcceptanceForm, isUnfilled,
-} from './acceptance-form.mjs';
-
 export {
   ContextManifest, buildBaseManifest, tier0References, TIER_REASONS_REQUIRED,
   DEFAULT_MAX_EXPANSION_PER_STEP, ContextError,
@@ -136,8 +133,28 @@ export {
 } from './reachability.mjs';
 
 export {
-  COMMANDS, mutatingCommands, readOnlyCommands, resolveCommand,
+  PLAY_KINDS,
+  parsePlayDeclaration, parsePlayDeclarationText,
+  validatePlayDeclaration, readSiblingPlayDeclarations, describePlayGaps,
+} from './play.mjs';
+
+export {
+  COMMANDS, mutatingCommands, readOnlyCommands, resolveCommand, selfBoundFiles,
   describeCommand, describeAllCommands, checkUnattendedRequirements,
 } from './commands.mjs';
 
 export { computeStatus, STATUS_OK_LINE, STATUS_PREFIX } from './status.mjs';
+
+export {
+  DEFAULT_EXCLUDED_DIRS, scanPackages, scanComponents, componentEdges,
+} from './csharp.mjs';
+
+export {
+  DIAGRAM_OUT_DIR, DIAGRAM_MANIFEST, STATUS_COLORS, STATUS_CLASS,
+  collectWorkItemFiles, indexComponents, componentWorkMap, statusesFromWork, componentStatusMap,
+  componentSlugs, buildDiagramModel, buildStructureModel,
+  renderNoml, renderIndexHtml, renderPackageHtml, renderComponentHtml,
+  writeDiagramFiles, syncDiagramTree, generateDiagrams, diagramDrift,
+} from './diagram.mjs';
+
+export { renderSvg as renderNomlSvg, nomnomlVersion } from './noml.mjs';

package/src/harness/noml.mjs

@@ -0,0 +1,47 @@
+/**
+ * nomnoml renderer wrapper — the only place the framework's UML dependency is
+ * touched.
+ *
+ * nomnoml is CommonJS; this package is ESM. `createRequire` is the interop that
+ * works regardless of how Node's named-export detection reads the bundle, and it
+ * keeps the load lazy so a run that never renders a diagram never pays for it.
+ *
+ * The dependency is deliberate and is recorded in the plan and the architecture
+ * decision: it breaks the framework's long-standing "dependency-free" property in
+ * exchange for a real UML renderer instead of a hand-drawn one.
+ */
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+let cached = null;
+
+function loadRenderer() {
+  if (cached) return cached;
+  try {
+    cached = require('nomnoml');
+  } catch (err) {
+    throw new Error(
+      `the UML renderer "nomnoml" is not installed (${err.message}). Run "npm install" in the cadet-agent package.`,
+    );
+  }
+  return cached;
+}
+
+/** Render nomnoml source to an SVG string. */
+export function renderSvg(source) {
+  const nomnoml = loadRenderer();
+  if (typeof nomnoml.renderSvg !== 'function') {
+    throw new Error('nomnoml did not expose renderSvg; the installed version is not the expected one.');
+  }
+  return nomnoml.renderSvg(String(source));
+}
+
+/** The installed nomnoml version, or null when it cannot be read. */
+export function nomnomlVersion() {
+  try {
+    return loadRenderer().version || null;
+  } catch {
+    return null;
+  }
+}

package/src/harness/play.mjs

@@ -0,0 +1,271 @@
+/**
+ * The `Play:` declaration — can a person play this story's deliverable, and if not,
+ * which work item will make it playable (contract v7 §1).
+ *
+ * Why this exists. Every gate in the framework can be satisfied by a command or by a
+ * reviewer's judgement, so a project can go fully green for many stories in a row with
+ * nothing ever on screen. The reachability gate names that risk and does not close it:
+ * a `witnessed` declaration is checked for shape, and with no project probe configured
+ * it passes on a sentence. The one gate that does ask a person — `humanAcceptanceConfirmed`
+ * — fires at epic closure, which is the point by which every story has already been
+ * marked done.
+ *
+ * So a story states, in one line, whether the user can play it:
+ *
+ *   Play: required — <what the user does, and what they should see>
+ *   Play: deferred to <work item> — <why it cannot be played yet>
+ *
+ * A `required` declaration is satisfied only by a person's own record, asked for and recorded
+ * in the conversation; `harness verify-play` refuses to record it. A `deferred` declaration
+ * is satisfied by the declaration itself, exactly as a reachability deferral is, and it
+ * expires the moment its target is done — a gap with an owner and a term, never a parked
+ * excuse. There is deliberately no third form: a story with no playable surface of its
+ * own is still reached through the running game, so "not applicable" would be an escape
+ * hatch an agent could write for itself, which is the class of check this framework keeps
+ * having to delete.
+ *
+ * The mechanics are deliberately the same as reachability's, and the deferral-graph
+ * helpers are IMPORTED rather than re-implemented: a deferral cycle spanning a `Play:`
+ * edge and a `Reachability:` edge is one graph, and two copies of the walk could disagree
+ * about it.
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+import {
+  DEFAULT_MAX_STORY_BYTES,
+  DEFAULT_MAX_SIBLING_STORIES,
+  normalizeWorkItemRef,
+  collectWorkItems,
+  findDeferralCycles,
+} from './reachability.mjs';
+
+/** The two forms a `Play:` declaration may take. */
+export const PLAY_KINDS = Object.freeze(['required', 'deferred']);
+
+/**
+ * Parse a story's `Play:` declaration out of its text.
+ *
+ * Returns `{ declared, kind, instruction, deferTo, reason, line, errors }`. The first
+ * `Play:` line outside a fenced block wins, and a malformed line returns `declared:
+ * false` WITH errors — a declaration that is wrong in a new way must not read as a
+ * story that is fine.
+ */
+export function parsePlayDeclarationText(text, { maxBytes = DEFAULT_MAX_STORY_BYTES } = {}) {
+  const errors = [];
+  const raw = String(text ?? '');
+  const scanned = raw.length > maxBytes ? raw.slice(0, maxBytes) : raw;
+  const lines = scanned.split(/\r?\n/);
+
+  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 = /^Play\s*:\s*(.*)$/i.exec(trimmed);
+    if (!m) continue;
+
+    const rest = m[1].trim();
+    const line = i + 1;
+
+    if (rest === '') {
+      errors.push(`line ${line}: "Play:" declares nothing — state either "required — <what the user does and sees>" or "deferred to <work item> — <why>".`);
+      return { declared: false, kind: null, instruction: '', 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 the work cannot be played yet ("deferred to ${target} — <reason>"); an unexplained deferral is how a gap becomes permanent.`);
+      }
+      return { declared: true, kind: 'deferred', instruction: '', deferTo: target, reason, line, errors };
+    }
+
+    const required = /^required\s*(?:[—-]\s*(.*))?$/i.exec(rest);
+    if (required) {
+      const instruction = (required[1] || '').trim();
+      if (instruction === '') {
+        errors.push(`line ${line}: "required" must say what the user does and what they should see ("required — <how to reach it and what to look for>"); a play nobody can follow is a play that will not happen.`);
+      }
+      return { declared: true, kind: 'required', instruction, deferTo: null, reason: '', line, errors };
+    }
+
+    errors.push(`line ${line}: unrecognised play declaration "${rest}" — expected "required — <what the user does and sees>" or "deferred to <work item> — <why>".`);
+    return { declared: false, kind: null, instruction: '', deferTo: null, reason: '', line, errors };
+  }
+
+  return { declared: false, kind: null, instruction: '', deferTo: null, reason: '', line: null, errors };
+}
+
+/** File variant of parsePlayDeclarationText. */
+export function parsePlayDeclaration(storyPath) {
+  const text = readFileSync(storyPath, 'utf-8');
+  return parsePlayDeclarationText(text);
+}
+
+/**
+ * Validate one declaration against the work items that exist.
+ *
+ * Returns `{ ok, code, message }`. Codes are stable, so a caller branches and a test
+ * asserts the FINDING rather than the prose:
+ *   malformed            — the parser rejected the line. Checked first: a reasonless
+ *                          deferral parses far enough to be typed and must still be
+ *                          refused, because the parser's no is the rule.
+ *   not-declared         — the story declares nothing at all. Silence is not coverage.
+ *   deferral-self        — a deferral names the story itself.
+ *   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
+ *                          playthrough it promised can never arrive.
+ *
+ * A `required` declaration with a non-empty instruction is valid: the play itself is the
+ * person's, and the gate is what records whether they made it.
+ */
+export function validatePlayDeclaration(declaration, { workItems = null, self = null } = {}) {
+  const d = declaration || {};
+
+  if (Array.isArray(d.errors) && d.errors.length > 0) {
+    return { ok: false, code: 'malformed', message: d.errors.join(' ') };
+  }
+  if (!d.declared) {
+    return {
+      ok: false,
+      code: 'not-declared',
+      message: 'the story declares no "Play:" line, so nothing says whether a person can play it. A story that cannot be played yet says so: "Play: deferred to <work item> — <why>".',
+    };
+  }
+
+  if (d.kind === 'required') {
+    // The code matters: `harness verify-play` branches on it to REFUSE recording a playable
+    // story's gate. Returning null here would let this command set the gate for a story only a
+    // person can settle, which is the hole the gate exists to close.
+    return { ok: true, code: 'required', message: `play required: ${d.instruction}` };
+  }
+
+  const target = d.deferTo;
+  const selfRefs = new Set(
+    (Array.isArray(self) ? self : [self])
+      .filter((value) => typeof value === 'string' && value.trim() !== '')
+      .map((value) => normalizeWorkItemRef(value)),
+  );
+
+  if (selfRefs.has(normalizeWorkItemRef(target))) {
+    return {
+      ok: false,
+      code: 'deferral-self',
+      message: `the deferral names "${target}", which is this story itself. A story cannot become playable by deferring to itself: declare "required", or name the work item that will make it playable.`,
+    };
+  }
+
+  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 story playable has landed, so the deferral has expired: either the work can be played now (declare "required") or the playable surface was missed when "${target}" closed.`,
+    };
+  }
+
+  return { ok: true, code: 'deferred', message: `play deferred to ${target} (${status || 'unknown status'})` };
+}
+
+/**
+ * The `Play:` declarations of a story's own epic directory, for the deferral graph.
+ *
+ * The same shape as `readSiblingDeclarations` in `reachability.mjs`, parsing `Play:`
+ * lines instead: a cycle can only be found if every sibling's edge is read.
+ */
+export function readSiblingPlayDeclarations(storyPath, { max = DEFAULT_MAX_SIBLING_STORIES, workItems = null } = {}) {
+  const dir = dirname(storyPath);
+  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) || out.length >= max) return;
+    seen.add(id);
+    try {
+      out.push({ id: name, aliases: aliasesFor(name), path, declaration: parsePlayDeclaration(path) });
+    } catch {
+      // A file that cannot be read is not this verdict's business.
+    }
+  };
+
+  add(basename(storyPath), storyPath);
+
+  let entries = null;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    entries = null;
+  }
+
+  for (const entry of entries || []) {
+    if (out.length >= max) break;
+    if (!entry.endsWith('.md')) continue;
+    if (entry === basename(storyPath)) continue;
+    add(entry, join(dir, entry));
+  }
+
+  return out;
+}
+
+/**
+ * One line per play gap, for a human-readable failure.
+ *
+ * AN ARRAY, NOT A JOINED STRING, and the difference is not style: the CLI iterates this
+ * (`for (const line of gaps) console.error(line)`), which is the contract its sibling
+ * `describeReachabilityGaps` already has. A joined string iterates its CHARACTERS, so the
+ * first release of this command printed the refusal one letter per line — a useless message
+ * from the one command whose whole job is to tell a caller what to do next. Found by running
+ * the released CLI against a real story, which is why the test now asserts the shape.
+ */
+export function describePlayGaps({ validation, cycles = [], story } = {}) {
+  const lines = [];
+  if (validation && !validation.ok) lines.push(`- ${story || 'the story'}: ${validation.message}`);
+  for (const cycle of cycles) {
+    lines.push(`- the play deferrals form a cycle, so none of these can ever be played: ${cycle.join(' → ')}`);
+  }
+  return lines;
+}
+
+/** Re-exported so the CLI and its tests need one import for both halves of the walk. */
+export { collectWorkItems, findDeferralCycles };

package/src/harness/policy.mjs

@@ -51,6 +51,11 @@ export const GATES = Object.freeze([
   // APPENDED by the architecture-fitness change. OPT-IN, and required only when the
   // project has declared checks — see ARCHITECTURE_GATE.
   'architectureFitnessPassed',
+  // APPENDED by the user-play change. HUMAN-OWNED, for the same reason
+  // humanAcceptanceConfirmed is: only a person can answer whether they played the
+  // delivered work and what they saw. OPT-IN, and required on the story boundary —
+  // see USER_PLAY_GATE.
+  'userPlaythroughConfirmed',
 ]);
 
 /**
@@ -141,6 +146,46 @@ export const DEFAULT_HUMAN_ACCEPTANCE = Object.freeze({
   enabled: false,
 });
 
+/**
+ * The user-playthrough gate.
+ *
+ * It answers the one question the workflow otherwise never asks: did a PERSON play the
+ * delivered work. Every other gate can be satisfied by a command or by a reviewer, so a
+ * project can go green for many stories in a row with nothing ever on screen — the
+ * condition `humanAcceptanceConfirmed` only reaches at epic closure, and the condition a
+ * `Reachability: witnessed` line states without proving.
+ *
+ * Required on `review -> validation`, which IS the story boundary: `validation ->
+ * implementation` is the next-story loop and stays unblocked, so "before moving on to
+ * the next story" is this edge. It sits beside `reachabilityAddressed` because the two
+ * ask the same question at different strengths — reachability asks whether a person CAN
+ * reach the deliverable, and this asks whether one DID.
+ *
+ * A story that cannot be played yet declares `Play: deferred to <work item>`, and that
+ * declaration satisfies the gate exactly as a reachability deferral does: it names an
+ * owner and expires when the owner is done, so "we will see it later" is a plan with a
+ * term rather than a gap. There is deliberately NO "not applicable" form — a story with
+ * no playable surface of its own still has a reachable one (the game still runs), and an
+ * escape hatch an agent can write for itself is the class of check this framework keeps
+ * having to delete.
+ */
+export const USER_PLAY_GATE = 'userPlaythroughConfirmed';
+
+/** The `from` phase the user-playthrough gate attaches to (`-> validation`). */
+export const USER_PLAY_TRANSITION_FROM = 'review';
+
+/**
+ * Default user-play policy.
+ *
+ * Opt-in, on the same reasoning as every other switch in this file: adopting a framework
+ * version must not add a requirement to a repository that did not ask for it. A consumer
+ * turns it on in its own `.cadet/harness.json`, and a project that has never been played
+ * is the condition this gate exists for.
+ */
+export const DEFAULT_USER_PLAY = Object.freeze({
+  enabled: false,
+});
+
 /**
  * The architecture-fitness gate.
  *
@@ -459,6 +504,7 @@ export const MANUAL_ONLY_GATES = Object.freeze([
   'securityReviewPassed',
   'designArtifactSyncConfirmed',
   'humanAcceptanceConfirmed',
+  'userPlaythroughConfirmed',
 ]);
 
 /**
@@ -744,6 +790,18 @@ function resolveHumanAcceptance(raw) {
   return { enabled: raw.enabled === true };
 }
 
+function resolveUserPlay(raw) {
+  if (raw === undefined) return { ...DEFAULT_USER_PLAY };
+  if (!isPlainObject(raw)) throw new PolicyError('"userPlay" must be an object.');
+  for (const key of Object.keys(raw)) {
+    if (key !== 'enabled') throw new PolicyError(`Unknown "userPlay" key "${key}".`);
+  }
+  if (raw.enabled !== undefined && typeof raw.enabled !== 'boolean') {
+    throw new PolicyError('"userPlay.enabled" must be a boolean.');
+  }
+  return { enabled: raw.enabled === true };
+}
+
 function resolveDesignReview(raw) {
   if (raw === undefined) return { ...DEFAULT_DESIGN_REVIEW };
   if (!isPlainObject(raw)) throw new PolicyError('"designReview" must be an object.');
@@ -769,7 +827,7 @@ export function validatePolicy(raw, defaults = DEFAULT_BUDGETS) {
     'budgets', 'archive', 'output', 'retention', 'estimation', 'hook',
     'allowBudgetCeilingOverride', 'scopes', 'model', 'analyzerCommand',
     'compileCommand', 'testCommand', 'allowEmptyFreshness', 'strictClosure',
-    'reachability', 'designReview', 'humanAcceptance', 'architectureFitness',
+    'reachability', 'designReview', 'humanAcceptance', 'architectureFitness', 'userPlay',
   ]);
   for (const key of Object.keys(raw)) {
     if (!allowed.has(key)) {
@@ -840,6 +898,7 @@ export function validatePolicy(raw, defaults = DEFAULT_BUDGETS) {
   const designReview = resolveDesignReview(raw.designReview);
   const humanAcceptance = resolveHumanAcceptance(raw.humanAcceptance);
   const architectureFitness = resolveArchitectureFitness(raw.architectureFitness);
+  const userPlay = resolveUserPlay(raw.userPlay);
 
   const resolved = {
     budgets,
@@ -855,6 +914,7 @@ export function validatePolicy(raw, defaults = DEFAULT_BUDGETS) {
     designReview,
     humanAcceptance,
     architectureFitness,
+    userPlay,
     scopes: raw.scopes || { perRun: {}, perStory: {} },
     model: raw.model || null,
     analyzerCommand: raw.analyzerCommand || null,

package/src/harness/reconcile.mjs

@@ -56,6 +56,7 @@ import { basename, dirname, isAbsolute, join, relative } from 'node:path';
 
 import { PHASES } from './policy.mjs';
 import { activeExceptionEntries } from './state.mjs';
+import { diagramDrift, DIAGRAM_OUT_DIR } from './diagram.mjs';
 import {
   collectWorkItems,
   parseReachabilityDeclaration,
@@ -247,8 +248,13 @@ export function parseEpicHeader(text) {
 /**
  * Every directory under `root`, breadth-first and depth-bounded. Skipping the
  * usual game-repo ballast keeps a walk of a real project cheap.
+ *
+ * EXPORTED, because the context plan needs the same discovery this module worked out for the
+ * reconciler. A real project nests its plans (`<project>/epics/<epic-N>/`) and names its own files,
+ * so a plan built from fixed paths reports a correct project's own story as missing — the lesson
+ * REQUIRED_ARTIFACTS above already records. One walk, two consumers.
  */
-function walkDirs(root, maxDepth = MAX_SCAN_DEPTH) {
+export function walkDirs(root, maxDepth = MAX_SCAN_DEPTH) {
   const found = [];
   let level = [root];
   for (let depth = 0; depth <= maxDepth && level.length > 0; depth++) {
@@ -659,7 +665,33 @@ export function reconcileArtifacts(targetDir, {
     }
   }
 
-  // ── 4. Sort, number, and summarise ────────────────────────────────────────
+  // ── 4. The generated diagram tree ─────────────────────────────────────────
+  //
+  // The diagrams are DERIVED — from the code and from `state.json` — so a tree
+  // that no longer matches is a projection of the record that has stopped
+  // agreeing with the record: exactly the class of inconsistency this module
+  // exists to find, one step further down the chain.
+  //
+  // BLOCKING, not a warning. `designArtifactSyncConfirmed` is supported only when
+  // the run reports no unexcused blocking finding, so a warning here would report
+  // the drift and gate nothing.
+  //
+  // Opt-in by PRESENCE: a repository that has never generated the tree has no
+  // manifest and is not checked, so adopting this release changes nothing until
+  // diagrams are actually produced.
+  const drift = diagramDrift({ rootDir: targetDir, state });
+  if (drift.available && !drift.ok) {
+    const counts = [];
+    if (drift.missing.length) counts.push(`${drift.missing.length} missing`);
+    if (drift.changed.length) counts.push(`${drift.changed.length} changed`);
+    if (drift.extra.length) counts.push(`${drift.extra.length} extra`);
+    add('diagram-drift', 'blocking', 'diagrams', `${toPosix(DIAGRAM_OUT_DIR)}/`,
+      `the committed diagram tree no longer matches the code and the work record (${counts.join(', ')} file(s)). `
+      + 'Run `cadet-agent harness diagram` and commit the result, so the diagrams travel with the change that moved them.',
+      [...drift.missing, ...drift.changed, ...drift.extra].slice(0, 3).join(', ') || null);
+  }
+
+  // ── 5. Sort, number, and summarise ────────────────────────────────────────
   findings.sort((a, b) => {
     const s = (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9);
     if (s !== 0) return s;