cadet-agent 0.56.0 → 0.60.0

package/src/harness/context-protocol.mjs

@@ -66,8 +66,8 @@ export const PHASE_SKILL = Object.freeze({
   closed: 'Resume.md',
 });
 
-/** The runtime contract every phase reads. */
-const HARNESS_CONTRACT = '.cadet/agent/core/Harness.md';
+/** The lean runtime contract every phase reads. */
+const HARNESS_CONTRACT = '.cadet/agent/core/HarnessRuntime.md';
 const KICKOFF = '.cadet/agent/core/cadet-agent.md';
 
 const normalise = (path) => String(path).replace(/\\/g, '/').replace(/^\.\//, '');
@@ -101,7 +101,7 @@ export function planEntries({ targetDir, policy, state = null }) {
     tier: 'tier0', reason: 'always-load: the directive that routes every other decision', authority: 'framework', required: true,
   }));
   required.push(entry(HARNESS_CONTRACT, {
-    tier: 'tier0', reason: 'the runtime contract for gates, evidence and budgets', authority: 'framework', required: true,
+    tier: 'tier0', reason: 'the lean runtime contract for gates, evidence and budgets', authority: 'framework', required: true,
   }));
   for (const ref of ['.cadet/harness.json', '.cadet/state.json']) {
     required.push(entry(ref, {

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,27 @@ 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, which is why the route is a form they fill in 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 +381,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,
@@ -136,7 +137,18 @@ export {
 } from './reachability.mjs';
 
 export {
-  COMMANDS, mutatingCommands, readOnlyCommands, resolveCommand,
+  PLAY_KINDS,
+  parsePlayDeclaration, parsePlayDeclarationText,
+  validatePlayDeclaration, readSiblingPlayDeclarations, describePlayGaps,
+} from './play.mjs';
+
+export {
+  PLAY_FORM_GATE, PLAY_FORM_SUFFIX, PLAY_TEMPLATE_RELATIVE, PLAY_HUMAN_FIELDS,
+  playFormPath, buildPlayForm, parsePlayForm, writePlayForm, readPlayTemplate,
+} from './play-form.mjs';
+
+export {
+  COMMANDS, mutatingCommands, readOnlyCommands, resolveCommand, selfBoundFiles,
   describeCommand, describeAllCommands, checkUnattendedRequirements,
 } from './commands.mjs';
 

package/src/harness/play-form.mjs

@@ -0,0 +1,193 @@
+/**
+ * The user-playthrough form — the only route by which `userPlaythroughConfirmed` is
+ * recorded for a story whose `Play:` declaration is `required`.
+ *
+ * Why a form rather than a flag. The gate asks whether a PERSON played the delivered
+ * work and what they saw. A flag route would let an agent answer that question with a
+ * sentence, which is exactly the failure the gate exists to close; the form leaves the
+ * three fields only a person can supply unfilled, and `harness confirm` refuses a form
+ * that still holds a placeholder. It mirrors the human-acceptance form deliberately —
+ * same shape, same refusal, one story instead of one epic.
+ *
+ * A `Play: deferred to <work item>` declaration never needs a form: the declaration is
+ * the answer, and `harness verify-play` records it. This module is for the other half.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+
+import { isUnfilled } from './acceptance-form.mjs';
+
+/** The gate this form records. */
+export const PLAY_FORM_GATE = 'userPlaythroughConfirmed';
+
+/** The form's file name, written beside the story it belongs to. */
+export const PLAY_FORM_SUFFIX = '-UserPlaythrough.md';
+
+/** The template, relative to the repository root. */
+export const PLAY_TEMPLATE_RELATIVE = '.cadet/agent/core/templates/UserPlaythroughTemplate.md';
+
+/**
+ * The fields only a person can supply. The generator leaves all three unfilled and the
+ * parser refuses a form where any of them still is one.
+ */
+export const PLAY_HUMAN_FIELDS = Object.freeze(['player', 'witness', 'limitations']);
+
+/** The form's path: beside the story, whose name it extends. */
+export function playFormPath(targetDir, storyPath) {
+  const rel = storyPath.replace(/\\/g, '/');
+  const stem = rel.endsWith('.md') ? rel.slice(0, -3) : rel;
+  return join(targetDir, `${stem}${PLAY_FORM_SUFFIX}`);
+}
+
+/** Fill every `<slot id="…"/>` in the template from a value map. */
+function fillSlots(text, values) {
+  return text.replace(/<slot\s+id="([^"]+)"((?:"[^"]*"|[^>"])*)\/>/g, (whole, id, attrs) => {
+    const value = values[id];
+    return value === undefined || value === null ? whole : String(value);
+  });
+}
+
+/** Strip the template's authoring attributes from a filled form. */
+function stripAttributes(text) {
+  return text.replace(/<slot\s+id="([^"]+)"(?:"[^"]*"|[^>"])*\/>/g, (whole, id) => {
+    const m = whole.match(/^<slot\s+id="[^"]+"[^>]*?\/>$/);
+    return m ? `<slot id="${id}"/>` : whole;
+  });
+}
+
+/** The machine's best answer for "which revision is this", or `unknown`. */
+function revisionOf(targetDir) {
+  try {
+    const out = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: targetDir, encoding: 'utf-8' });
+    return out.trim() || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Build the form for one story.
+ *
+ * `storyPath` is repository-relative. The story itself is bound as the relevant file, so
+ * editing the story after the playthrough makes the record stale rather than leaving it
+ * looking current.
+ */
+export function buildPlayForm({ template, state, storyPath, storyRel, epicId = null, targetDir, now = new Date(), declaration = null }) {
+  const storyName = storyRel.replace(/\\/g, '/').split('/').pop() || storyRel;
+  const instruction = declaration && declaration.kind === 'required' && declaration.instruction
+    ? declaration.instruction
+    : '(the story declares no instruction — see its Play: line)';
+
+  const candidates = [];
+  candidates.push(`- \`Play:\` declaration: ${declaration && declaration.declared ? declaration.kind : 'MISSING — the story declares no Play: line'}`);
+  if (state && state.gates && typeof state.gates === 'object') {
+    const unmet = Object.entries(state.gates).filter(([, value]) => value !== true).map(([gate]) => gate);
+    if (unmet.length > 0) candidates.push(`- gates not yet true in state.json: ${unmet.join(', ')}`);
+  }
+  const workItem = state && state.activeWorkItem && state.activeWorkItem.storyId
+    ? `${state.activeWorkItem.epicId}::${state.activeWorkItem.storyId}`
+    : '(no active work item)';
+
+  const values = {
+    story: `\`${storyName}\` (${workItem})`,
+    date: now.toISOString(),
+    revision: revisionOf(targetDir),
+    files: storyRel.replace(/\\/g, '/'),
+    environment: 'editor=<version>, scene=<path>',
+    instruction,
+    candidates: candidates.join('\n'),
+    recording: [
+      'Fill in every field above, then record it — nothing is retyped:',
+      '',
+      '```',
+      `cadet-agent harness confirm --gate ${PLAY_FORM_GATE} \\`,
+      `  --artifact <this file> \\`,
+      `  --reason "<why this playthrough is the record>" --expires-at <ISO-8601>`,
+      '```',
+      '',
+      'A form with an unfilled field is refused. The play is the person\'s; the agent only records it.',
+    ].join('\n'),
+  };
+
+  return stripAttributes(fillSlots(template, values));
+}
+
+/**
+ * Parse a filled form.
+ *
+ * Returns the values it found plus `incomplete`, the human fields still unanswered. It
+ * makes no judgement about the playthrough itself — that is the gate's question, and the
+ * point of the record is that the person answered it.
+ */
+export function parsePlayForm(text) {
+  if (typeof text !== 'string' || text.trim() === '') {
+    return { incomplete: [...PLAY_HUMAN_FIELDS], error: 'the form is empty' };
+  }
+  const lines = text.split(/\r?\n/);
+
+  const scalar = (label) => {
+    const re = new RegExp(`^${label}:\\s*(.*)$`, 'i');
+    for (const line of lines) {
+      const m = line.match(re);
+      if (m) return m[1].trim();
+    }
+    return null;
+  };
+
+  const section = (heading) => {
+    const start = lines.findIndex((line) => line.trim().toLowerCase() === `## ${heading}`.toLowerCase());
+    if (start < 0) return null;
+    const body = [];
+    for (let i = start + 1; i < lines.length; i += 1) {
+      if (/^##\s/.test(lines[i]) || /^---\s*$/.test(lines[i])) break;
+      body.push(lines[i]);
+    }
+    return body.join('\n').trim();
+  };
+
+  const form = {
+    story: (text.match(/^#\s*User Playthrough:\s*(.+)$/m) || [])[1]?.trim() || null,
+    player: scalar('Played by'),
+    date: scalar('Date'),
+    revision: scalar('Revision'),
+    files: scalar('Files'),
+    environment: scalar('Environment'),
+    witness: section('What I did'),
+    instruction: section('What the story claims'),
+    limitations: section('Accepted limitations'),
+  };
+
+  const incomplete = PLAY_HUMAN_FIELDS.filter((field) => isUnfilled(form[field]));
+  if (isUnfilled(form.story)) incomplete.push('story');
+
+  const fileList = (form.files || '')
+    .split(',')
+    .map((f) => f.trim().replace(/\\/g, '/'))
+    .filter((f) => f && !f.startsWith('('))
+    .filter((f) => !isUnfilled(f));
+
+  return { ...form, fileList, incomplete };
+}
+
+/** Write the form, create-only: a half-filled form is never overwritten. */
+export function writePlayForm(targetDir, storyRel, text, { out = null } = {}) {
+  const path = out ? join(targetDir, out) : playFormPath(targetDir, storyRel);
+  if (existsSync(path)) {
+    return { written: false, path, reason: 'a form already exists; edit it and record it, or move it aside to regenerate' };
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text);
+  return { written: true, path };
+}
+
+/** Read the template, or throw with a message a caller can print. */
+export function readPlayTemplate(targetDir) {
+  const path = join(targetDir, PLAY_TEMPLATE_RELATIVE);
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch (err) {
+    throw new Error(`the playthrough template could not be read at ${PLAY_TEMPLATE_RELATIVE}: ${err.message}`);
+  }
+}

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 (the form route in
+ * `play-form.mjs`); `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,