cadet-agent 0.56.0 → 0.63.1

package/src/cli.mjs

@@ -13,22 +13,26 @@ import {
   parseDesignReviewArtifact, describeDesignReviewGaps, FINDING_DISPOSITIONS,
   DESIGN_REVIEW_GATE, HUMAN_ACCEPTANCE_GATE,
   CONTEXT_LEVELS, buildContextPlan, writeContextPlan, readContextPlan, buildContextRecord,
+  resolveWorkItemDocs,
   writeContextRecord, readContextRecord, parseTranscript, validateContextRecord,
   describeContextState, ContextProtocolError,
   enforcementMatrix, describeEnforcement, INTERCEPTION_ACTIONS,
   ARCHITECTURE_GATE, architectureFitnessActive, runArchitectureChecks, summariseChecks,
   describeCheckResults, DEFAULT_CHECK_TIMEOUT_MS,
-  ACCEPTANCE_TEMPLATE_RELATIVE, buildAcceptanceForm, parseAcceptanceForm, writeAcceptanceForm,
-  acceptanceFormPath, ACCEPTANCE_HUMAN_FIELDS,
   parseTestInventory, parseStoryCriteria, compareCoverage, describeCoverageGaps,
   parseReachabilityDeclaration, validateReachabilityDeclaration, collectWorkItems,
   findDeferralCycles, readSiblingDeclarations, normalizeWorkItemRef, describeReachabilityGaps,
   REACHABILITY_GATE, runCommand,
+  parsePlayDeclaration, validatePlayDeclaration, readSiblingPlayDeclarations, describePlayGaps,
+  USER_PLAY_GATE,
   createEvidence, newId, computeInputTreeHash, hashCriteria,
   collectDeclaredTestNames, reconcileTestNames,
   resolveCommand, describeCommand, describeAllCommands, checkUnattendedRequirements, COMMANDS,
+  selfBoundFiles,
   STATE_VERSION, sealedEvidence, recordEvidence, appendEvidence, sealWorkItem, toStateV4,
   isHistoryExternal, HISTORY_ENTRIES_KEPT, resetGatesForNewWorkItem,
+  buildStateBrief, renderStateBrief, writeStateBrief, CONTEXT_BRIEF_FILE,
+  generateDiagrams, syncDiagramTree, diagramDrift, DIAGRAM_OUT_DIR,
 } from './harness/index.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -57,6 +61,7 @@ function showHelp() {
     npx cadet-agent@latest sync --target <dir>   Sync a specific directory
 
     cadet-agent state init          Create the first .cadet/state.json (never overwrites one)
+    cadet-agent state brief         Print the tier-0 summary: phase, work item, gates, archivable records
     cadet-agent state validate      Validate .cadet/state.json against the schema
     cadet-agent state validate --verify-sealed   Also read sealed evidence from commit trailers
     cadet-agent state migrate       Atomically migrate state to the current version (backup on write)
@@ -72,8 +77,8 @@ function showHelp() {
     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 verify-play  Verify a story's Play: declaration and record the deferral (opt-in)
     cadet-agent harness verify-design-review  Check the design-review artifact and record the gate (opt-in)
-    cadet-agent harness acceptance-form  Write a human-acceptance form for an epic, filled in from state
     cadet-agent harness verify-architecture  Run the project's declared architecture checks (opt-in)
     cadet-agent harness context plan  Write what the phase requires, and why (opt-in protocol)
     cadet-agent harness context record  Record what the host loaded, and the level it can claim
@@ -84,6 +89,8 @@ function showHelp() {
     cadet-agent harness cleanup     Apply the retention policy to .cadet/runs/
     cadet-agent harness capabilities  Report available CLI/Unity/MCP/hook/token/cost telemetry
     cadet-agent harness status      Print the one-line framework health line (ok, or the problem)
+    cadet-agent harness diagram     Render UML component diagrams per package, coloured by progress
+    cadet-agent harness verify-diagrams  Check the committed diagram tree is current (read-only)
 
   Options:
     --target, -t  Target directory (default: current working directory)
@@ -95,14 +102,12 @@ function showHelp() {
     --files        Comma-separated relevant files to bind evidence to (harness verify|confirm)
     --commit       Revision the gate attests, as a hex SHA (harness verify|confirm)
     --expect-phase Refuse to record a gate unless the current phase matches (harness verify|confirm|verify-acs|verify-reachability)
-    --reason       Why automation was unavailable (harness confirm)
+    --reason       Why a human gate is being recorded — the person's own answer (harness confirm)
     --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 or reachability (harness verify-acs|verify-reachability)
-    --artifact     Design-review artifact to check (verify-design-review), or the acceptance form to record from (confirm --gate humanAcceptanceConfirmed)
-    --epic         Epic a generated form belongs to (harness acceptance-form)
-    --out          Where to write the form (default: the epic's plan directory)
+    --story        Story markdown declaring the acceptance criteria, reachability or play declaration (harness verify-acs|verify-reachability|verify-play)
+    --artifact     Design-review artifact to check (harness verify-design-review)
 
     --report       Test report to derive the inventory from (harness verify-acs|matrix-check)
     --matrix       TDD matrix markdown to check (harness matrix-check)
@@ -111,6 +116,10 @@ function showHelp() {
     --relative-to  Directory the emitted links are relative to (harness changes; default .cadet/reports)
     --include-cadet  Keep .cadet/ bookkeeping among the listed files (harness changes)
     --plans-dir    Directory holding the planning artifacts (harness reconcile; default .cadet/agent/project-plans)
+    --out          Output root for the generated diagram tree (harness diagram|verify-diagrams; default .cadet/diagrams)
+    --cs-root      Root of the C# sources to scan (harness diagram|verify-diagrams; default the target directory)
+    --package      Limit the diagram run to one package id (harness diagram|verify-diagrams)
+    --include-tests  Include Unity test assemblies, which are excluded by default (harness diagram|verify-diagrams)
     --agents-md    keep|overwrite|merge for an existing AGENTS.md (init/sync)
     --older-than-ms  Age bound, in ms, for records cleanup may delete (harness cleanup; required)
     --keep         always|active|<work-item ids> for what stays in state.json (state compact; required)
@@ -198,9 +207,7 @@ function parseArgs(argv) {
       case '--files': opts.filesGiven = true; opts.files = value(a).split(',').map((s) => s.trim()).filter(Boolean); break;
       case '--story': opts.story = value(a); break;
       case '--artifact': opts.artifact = value(a); break;
-      case '--out': opts.out = value(a); break;
-      // The epic the command acts on: `state begin`'s new work item, and the epic an
-      // acceptance form is generated for.
+      // The epic the command acts on: `state begin`'s new work item.
       case '--epic': opts.epicId = value(a); break;
       // state compact: keep every record inline instead of applying the
       // within-work-item retention rule. Made explicit at the call site, because
@@ -216,6 +223,12 @@ function parseArgs(argv) {
       case '--relative-to': opts.relativeTo = value(a); break;
       case '--include-cadet': opts.includeCadet = true; break;
       case '--plans-dir': opts.plansDir = value(a); break;
+      // harness diagram: where the tree lands, which sources to scan, and an
+      // optional single-package filter.
+      case '--out': opts.out = value(a); break;
+      case '--cs-root': opts.csRoot = value(a); break;
+      case '--package': opts.packageId = value(a); break;
+      case '--include-tests': opts.includeTests = true; break;
       case '--write-coverage': opts.writeCoverage = true; break;
       case '--strict-orphans': opts.strictOrphans = true; break;
       case '--dry-run': opts.dryRun = true; break;
@@ -578,6 +591,25 @@ async function cmdState(opts) {
     return;
   }
 
+  if (sub === 'brief') {
+    // THE TIER-0 SUMMARY OF THE DOCUMENT (0.63.0). Read-only, and derived: every field is read from
+    // state.json, and the gate rows use `latestEvidenceForGate` — the same reader a gate check uses —
+    // so the brief cannot disagree with the machinery about which record is live. It exists because
+    // the context plan used to name the 94 KB document itself as an always-load reference.
+    const { exists, state } = readState(opts.targetDir);
+    if (!exists) fail(opts, 'No .cadet/state.json found.', () => 2);
+
+    // The story and epic paths are resolved HERE and passed in: the builder is pure, and finding a work
+    // item's own documents needs the filesystem. A host that can see the path needs no second lookup.
+    const brief = buildStateBrief(state, loadPolicy(opts.targetDir), resolveWorkItemDocs(opts.targetDir, state));
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: true, brief });
+    } else {
+      emit(opts, renderStateBrief(brief).trimEnd());
+    }
+    return;
+  }
+
   if (sub === 'compact') {
     const { exists, state } = readState(opts.targetDir);
     if (!exists) fail(opts, 'No .cadet/state.json found.', () => 2);
@@ -853,7 +885,7 @@ async function cmdState(opts) {
     return;
   }
 
-  fail(opts, `Unknown state subcommand: ${sub || '(none)'}. Use validate|migrate|compact|begin|seal|transition.`);
+  fail(opts, `Unknown state subcommand: ${sub || '(none)'}. Use brief|validate|migrate|compact|begin|seal|transition.`);
 }
 
 /**
@@ -911,6 +943,94 @@ async function cmdHarness(opts) {
     return;
   }
 
+  if (sub === 'diagram') {
+    // UML component diagrams, one per (package × epic), coloured by progress.
+    //
+    // The work record is READ, never required: on a repository with no state the
+    // generator still draws the structure and says why every component is red,
+    // which is the same "report, do not fail silently" posture `state validate`
+    // takes for a missing document. The UML source and the SVG both come from one
+    // model, so they cannot disagree.
+    const { exists, state } = readState(opts.targetDir);
+    const csRoot = resolve(opts.targetDir, opts.csRoot || '.');
+    const outDir = resolve(opts.targetDir, opts.out || DIAGRAM_OUT_DIR);
+    let result;
+    try {
+      result = generateDiagrams({
+        rootDir: opts.targetDir,
+        outDir,
+        csRoot,
+        state: exists ? state : null,
+        packageFilter: opts.packageId || null,
+        includeTests: opts.includeTests === true,
+      });
+    } catch (err) {
+      fail(opts, `could not render the diagrams: ${err.message}`, () => 1, { ok: false, code: 'diagram-failed' });
+    }
+    const written = syncDiagramTree(outDir, result.files);
+    const { summary } = result;
+    const shownOut = relative(opts.targetDir, outDir).replace(/\\/g, '/') || '.';
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: true, ...summary, outDir: shownOut, removed: written.removed });
+    } else {
+      console.log(`✅ Component diagrams written to ${shownOut} (${summary.packages.length} package(s), ${summary.diagrams} diagram(s)).`);
+      for (const pkg of summary.packages) {
+        for (const d of pkg.diagrams) {
+          const elided = d.elided ? `, ${d.elided} elided` : '';
+          console.log(`   ${pkg.name} / ${d.epic}: ${d.counts.done} done, ${d.counts['in-progress']} in progress, ${d.counts['not-started']} not started${elided}`);
+        }
+      }
+      if (written.removed) console.log(`   Pruned ${written.removed} file(s) left by a previous run.`);
+      if (summary.warning) console.log(`   ⚠️  ${summary.warning}`);
+      console.log(`   Open: ${join(shownOut, 'index.html')}`);
+    }
+    return;
+  }
+
+  if (sub === 'verify-diagrams') {
+    // Read-only: does the committed tree still match the code and the record?
+    //
+    // It shares one function with `harness reconcile`, so this command and the
+    // closure finding cannot disagree about the same tree — and it deliberately
+    // does not regenerate, because a check that repaired the thing it checks
+    // would always pass.
+    const { exists, state } = readState(opts.targetDir);
+    const csRoot = resolve(opts.targetDir, opts.csRoot || '.');
+    const outDir = resolve(opts.targetDir, opts.out || DIAGRAM_OUT_DIR);
+    const drift = diagramDrift({
+      rootDir: opts.targetDir,
+      outDir,
+      csRoot,
+      state: exists ? state : null,
+      packageFilter: opts.packageId || null,
+      includeTests: opts.includeTests === true,
+    });
+    const shownOut = relative(opts.targetDir, outDir).replace(/\\/g, '/') || '.';
+    if (!drift.available) {
+      emit(opts, `ℹ️  No diagram tree at ${shownOut} — nothing to verify.`, { ok: true, available: false, reason: drift.reason, outDir: shownOut });
+      return;
+    }
+    if (opts.format === 'json') {
+      emit(opts, '', {
+        ok: drift.ok,
+        available: true,
+        outDir: shownOut,
+        expected: drift.expected,
+        missing: drift.missing,
+        changed: drift.changed,
+        extra: drift.extra,
+      });
+    } else if (drift.ok) {
+      console.log(`✅ Diagrams are current: ${drift.expected} file(s) match the code and the work record.`);
+    } else {
+      console.error(`❌ Diagrams are stale: ${drift.missing.length} missing, ${drift.changed.length} changed, ${drift.extra.length} extra file(s).`);
+      for (const file of [...drift.missing, ...drift.changed, ...drift.extra].slice(0, 10)) console.error(`   ${file}`);
+      console.error('   Run "cadet-agent harness diagram" and commit the result.');
+    }
+    if (!drift.ok) process.exit(1);
+    return;
+  }
+
   if (sub === 'confirm') {
     const gate = opts.gate;
     if (!gate) fail(opts, 'harness confirm requires --gate <gate>');
@@ -920,23 +1040,52 @@ async function cmdHarness(opts) {
     if (!exists) fail(opts, 'No .cadet/state.json found. Initialise state before recording confirmation.', () => 2);
     assertExpectedPhase(opts, state);
 
-    // A caller that passes the removed flags is refused by name. The acceptance is recorded from
-    // the form and from nothing else (see below); a witness or a limitation typed here would be
-    // discarded, and a discarded field that looked accepted is exactly the failure this framework
-    // is built to prevent.
+    // A human gate is recorded from the person's own answer, and from nothing else.
+    //
+    // There is no artifact and no form. These two gates ask what a PERSON did and what they saw,
+    // and the answer is a sentence the person said: `--reason` carries it, and the record binds
+    // the active work item and whatever files the answer covers. A form was the earlier route and
+    // was removed (2026-10-03): it added a document to write, read and keep in sync, and its
+    // blank fields stop a lazy agent rather than a dishonest one, so it bought less than it cost.
+    const HUMAN_GATE = gate === HUMAN_ACCEPTANCE_GATE || gate === USER_PLAY_GATE;
+
+    if (opts.artifact) {
+      fail(
+        opts,
+        '--artifact is not accepted by "harness confirm": "harness verify-design-review" is the command that takes an artifact. '
+        + 'Record a human gate from the person\'s words with --reason.',
+        () => 1,
+        { ok: false, gate, code: 'artifact-not-applicable' },
+      );
+    }
+
+    // A caller that passes the removed flags is refused by name rather than recorded, so nothing
+    // they typed is silently discarded.
     const removedFlags = ['witness', 'limitations'].filter((k) => opts[k] !== undefined && opts[k] !== null);
     if (removedFlags.length > 0) {
       const flags = removedFlags.map((k) => `--${k}`);
       fail(
         opts,
-        `${flags.join(' and ')} no longer exist, so nothing was recorded. A human acceptance is recorded from its form: `
-        + 'run "cadet-agent harness acceptance-form --epic <epicId>", fill it in, and pass it back with --artifact <the form>. '
-        + 'The witness and the limitations live in that file, where a reviewer can read them.',
+        `${flags.join(' and ')} no longer exist, so nothing was recorded. A human gate is recorded from the `
+        + 'person\'s own answer: ask them, then pass their words to --reason.',
         () => 1,
         { ok: false, gate, code: 'flag-removed', flags },
       );
     }
 
+    // The answer cannot be empty. The form refused three blank fields; the same refusal now stands
+    // on one field, and it holds whether or not strictClosure is enabled — an attestation that
+    // says nothing is not an attestation.
+    if (HUMAN_GATE && (!opts.reason || String(opts.reason).trim() === '')) {
+      fail(
+        opts,
+        `"${gate}" is a person's record, so --reason must carry what they said. `
+        + 'Ask them what they did and what they saw, then record their answer.',
+        () => 1,
+        { ok: false, gate, code: 'reason-required' },
+      );
+    }
+
     const strict = policy.strictClosure?.enabled === true ? policy.strictClosure : null;
     const mc = strict?.manualConfirmation || null;
     // One reference instant for the whole command, captured before any work.
@@ -947,76 +1096,18 @@ async function cmdHarness(opts) {
 
     // Collect EVERY missing field so the caller fixes the record in one pass,
     // rather than discovering one omission per invocation.
-    //
-    // The two fields the acceptance ARTIFACT supplies are exempt when it is present. The check
-    // below refuses `--scope` and `--environment` beside `--artifact` (they would be a second,
-    // competing source for the same claim), so demanding them here made the command unsatisfiable
-    // in both directions under the shipped policy: with them it was `artifact-conflicts-with-flags`,
-    // without them `strict-metadata-missing`. A gate no caller can satisfy is not a strict gate.
-    // The form carries both, and its completeness is checked when it is parsed.
-    const artifactSuppliesScope = typeof opts.artifact === 'string' && opts.artifact !== '';
     const missing = [];
     if (mc?.requireReason !== false && strict && (!opts.reason || String(opts.reason).trim() === '')) missing.push('--reason');
     if (mc?.requireExpiresAt !== false && strict) {
       if (!opts.expiresAt) missing.push('--expires-at');
       else if (Number.isNaN(Date.parse(opts.expiresAt))) missing.push('--expires-at (not an ISO-8601 date-time)');
     }
-    if (mc?.requireEnvironment !== false && strict && !artifactSuppliesScope && (!opts.environment || String(opts.environment).trim() === '')) missing.push('--environment');
-    if (mc?.requireScope !== false && strict && !artifactSuppliesScope && (!opts.scope || opts.scope.length === 0)) missing.push('--scope');
+    if (mc?.requireEnvironment !== false && strict && (!opts.environment || String(opts.environment).trim() === '')) missing.push('--environment');
+    if (mc?.requireScope !== false && strict && (!opts.scope || opts.scope.length === 0)) missing.push('--scope');
     if (missing.length) {
       fail(opts, `strictClosure requires manual-confirmation metadata. Missing: ${missing.join(', ')}.`, () => 1, { ok: false, gate, code: 'strict-metadata-missing', missing });
     }
 
-    // A human acceptance is recorded from a form, and from nothing else.
-    //
-    // There is no flag route. Two routes to one gate means the weaker route defines the
-    // gate, and the flag route's only advantage was skipping the file — at the cost of a
-    // record no person can read later. The form costs two commands, leaves the acceptance
-    // somewhere a reviewer can open, and removes the second copy that could disagree with
-    // the record. `--witness` and `--limitations` no longer exist; a caller that passes
-    // them is refused here rather than silently recorded, which is why the check is on
-    // the missing artifact rather than on the flags.
-    if (gate === HUMAN_ACCEPTANCE_GATE && !opts.artifact) {
-      fail(opts, `a human acceptance is recorded from a form: run "cadet-agent harness acceptance-form --epic <epicId>" to write one pre-filled from state, fill in its blank fields, then pass it back with --artifact <the form>.`, () => 1, { ok: false, gate, code: 'acceptance-form-required' });
-    }
-
-    // `harness acceptance-form` writes the form pre-filled from state; this reads it back.
-    if (opts.artifact) {
-      if (gate !== HUMAN_ACCEPTANCE_GATE) {
-        fail(opts, `--artifact is only for ${HUMAN_ACCEPTANCE_GATE}: every other gate's evidence comes from its own command or from explicit fields.`, () => 1, { ok: false, gate, code: 'artifact-not-applicable' });
-      }
-      const conflicting = ['scope', 'environment'].filter((k) => opts[k]);
-      if (conflicting.length > 0) {
-        fail(opts, `--artifact already carries the acceptance, so ${conflicting.map((k) => `--${k}`).join(' and ')} would be a second, competing source. Pass the artifact alone.`, () => 1, { ok: false, gate, code: 'artifact-conflicts-with-flags', conflicting });
-      }
-      let formText;
-      try {
-        formText = readFileSync(opts.artifact, 'utf-8');
-      } catch (err) {
-        fail(opts, `the acceptance form could not be read (${err.message}).`, () => 1, { ok: false, gate, code: 'artifact-unreadable' });
-      }
-      const form = parseAcceptanceForm(formText);
-      if (form.incomplete.length > 0) {
-        fail(opts, `the form still has unfilled fields: ${form.incomplete.join(', ')}. Fill them in ${opts.artifact} and run the command again — an acceptance nobody wrote down is not an acceptance.`, () => 1, { ok: false, gate, code: 'acceptance-form-incomplete', missing: form.incomplete });
-      }
-      if (state && form.epic && state.epics && !state.epics[form.epic]) {
-        fail(opts, `the form accepts epic "${form.epic}", which does not exist in state.json. Fix the form, or accept the epic the repository actually has.`, () => 1, { ok: false, gate, code: 'acceptance-form-epic-unknown', epic: form.epic });
-      }
-      opts.witness = form.witness;
-      opts.limitations = form.limitations;
-      opts.environment = form.environment || null;
-      opts.scope = [form.epic];
-      if (!opts.files || opts.files.length === 0) opts.files = form.fileList;
-      opts.files = opts.files && opts.files.length ? opts.files : null;
-      opts.filesGiven = opts.files !== null;
-      opts.acceptedBy = form.acceptor;
-    }
-
-    // No check for empty witness/limitations is needed here: the form is the only route
-    // to this gate, and `parseAcceptanceForm` refuses a form whose fields are blank or
-    // still placeholders, so an empty value cannot reach this point. A second check would
-    // be a guard that cannot fire, and the one that cannot fire is the one that rots.
-
     // 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)) {
@@ -1081,8 +1172,6 @@ async function cmdHarness(opts) {
       rootDir: opts.targetDir,
       approvedBy: opts.approvedBy || 'user',
       commit: opts.commit || null,
-      witness: opts.witness || null,
-      limitations: opts.limitations || null,
       at,
     });
 
@@ -1679,36 +1768,132 @@ async function cmdHarness(opts) {
     return;
   }
 
-  if (sub === 'acceptance-form') {
-    if (!opts.epicId) {
-      fail(opts, 'harness acceptance-form needs --epic <epicId>: the form belongs to the epic being accepted.', () => 1, { ok: false, code: 'epic-required' });
-    }
+  if (sub === 'verify-play') {
+    refuseCommandOverride('harness verify-play', "the story's Play: declaration");
+    // Mechanical play-declaration verification (contract v7 §1). A story states whether a
+    // person can play its deliverable, or which work item will make it playable; this checks
+    // that declaration against the work items that exist.
+    //
+    // WHY THIS COMMAND CANNOT SET THE GATE FOR A PLAYABLE STORY. The gate asks whether a
+    // PERSON played the work. So this records the gate for a `deferred` declaration — the
+    // declaration is the answer, exactly as a reachability deferral is — and REFUSES to
+    // record it for a `required` one, pointing at the form. An agent that could answer
+    // "the user played it" in a sentence would make the gate worthless, which is the whole
+    // reason `userPlaythroughConfirmed` is human-owned in the gate registry.
+    if (!opts.story) fail(opts, 'harness verify-play requires --story <path>');
+    const storyPath = resolve(opts.targetDir, opts.story);
+    const storyRel = relative(opts.targetDir, storyPath).replace(/\\/g, '/') || basename(storyPath);
     const { exists, state } = readState(opts.targetDir);
-    if (!exists) {
-      fail(opts, 'No .cadet/state.json found. The form is generated from state, so there is nothing to fill it from yet.', () => 1, { ok: false, code: 'no-state' });
-    }
-    if (state.epics && !state.epics[opts.epicId]) {
-      fail(opts, `epic "${opts.epicId}" does not exist in state.json. Known epics: ${Object.keys(state.epics).join(', ') || '(none)'}.`, () => 1, { ok: false, code: 'epic-unknown', epic: opts.epicId });
-    }
-    const templatePath = join(opts.targetDir, ...ACCEPTANCE_TEMPLATE_RELATIVE.split('/'));
-    let template;
+    assertExpectedPhase(opts, state);
+    const playEnabled = policy.userPlay?.enabled === true;
+    const workItemId = state ? workItemIdOf(state) : 'unscoped';
+    const phase = state?.session?.currentPhase || 'implementation';
+
+    let playDeclaration;
     try {
-      template = readFileSync(templatePath, 'utf-8');
+      playDeclaration = parsePlayDeclaration(storyPath);
     } catch (err) {
-      fail(opts, `the acceptance template is missing (${ACCEPTANCE_TEMPLATE_RELATIVE}). Run "cadet-agent sync" to restore it — the form is generated from that file so the template and the form cannot drift apart.`, () => 1, { ok: false, code: 'template-missing' });
+      fail(opts, `cannot read story "${opts.story}": ${err.message}`, () => 1, { ok: false, code: 'story-unreadable', story: opts.story });
+    }
+
+    const playWorkItems = exists ? collectWorkItems(state) : null;
+    const playValidation = validatePlayDeclaration(playDeclaration, { workItems: playWorkItems, self: basename(storyPath) });
+    const playSiblings = readSiblingPlayDeclarations(storyPath, { workItems: playWorkItems });
+    const playGraph = playSiblings.length > 0
+      ? playSiblings
+      : [{ id: basename(storyPath), aliases: [], declaration: playDeclaration }];
+    const playCycles = exists ? findDeferralCycles(playGraph) : [];
+    const playGaps = describePlayGaps({ validation: playValidation, cycles: playCycles, story: opts.story });
+
+    // A playable story. The gate is NOT set here; the refusal names the route that can set it —
+    // a person plays the work, and the agent records that person's answer with `--reason`.
+    if (playValidation.ok && playValidation.code === 'required') {
+      fail(
+        opts,
+        `${USER_PLAY_GATE} is a person's record, and this story declares its deliverable playable: ${playDeclaration.instruction} `
+        + `Ask the person to play it, then record their answer: cadet-agent harness confirm --gate ${USER_PLAY_GATE} `
+        + `--reason "<what they did and what they saw>" --files <story>.`,
+        () => 1,
+        { ok: false, gate: USER_PLAY_GATE, code: 'play-required', story: opts.story, declaration: playDeclaration },
+      );
     }
-    const { text } = buildAcceptanceForm({ template, state, epicId: opts.epicId, targetDir: opts.targetDir });
-    const result = writeAcceptanceForm(opts.targetDir, opts.epicId, text, { out: opts.out });
-    if (!result.written) {
-      fail(opts, `harness acceptance-form refuses to overwrite an existing form: ${result.reason} (${result.path}).`, () => 1, { ok: false, code: 'form-exists', path: result.path });
+
+    const playOk = playValidation.ok && playCycles.length === 0;
+
+    if (!playEnabled) {
+      if (opts.format === 'json') {
+        emit(opts, '', { ok: playOk, story: opts.story, declaration: playDeclaration, play: playValidation, cycles: playCycles, gateSet: false, enabled: false });
+      } else if (playOk) {
+        console.log(`✅ Play declaration for ${opts.story}: ${playValidation.message}`);
+        console.log('   userPlay.enabled is false — reported only, state.json unchanged.');
+      } else {
+        console.error(`⚠️  Play gaps in ${opts.story} (userPlay.enabled is false — reported only):`);
+        for (const line of playGaps) console.error(line);
+      }
+      if (!playOk) process.exit(1);
+      return;
     }
-    const shown = result.path.slice(opts.targetDir.length + 1).replace(/\\/g, '/');
+
+    if (!playOk) {
+      const detail = {
+        ok: false,
+        story: opts.story,
+        declaration: playDeclaration,
+        play: playValidation,
+        cycles: playCycles,
+        gateSet: false,
+        code: playValidation.ok !== true ? playValidation.code : 'deferral-cycle',
+      };
+      if (opts.format === 'json') emit(opts, '', detail);
+      else {
+        console.error(`❌ Cannot set ${USER_PLAY_GATE} for ${opts.story}:`);
+        for (const line of playGaps) console.error(line);
+      }
+      process.exit(1);
+    }
+
+    const playAt = new Date();
+    const playEvidence = createEvidence({
+      evidenceId: newId(),
+      workItemId,
+      acceptanceCriterionId: null,
+      phase,
+      gate: USER_PLAY_GATE,
+      status: 'passed',
+      command: `harness verify-play --story ${opts.story}`,
+      result: `play deferred (${playValidation.code})`,
+      exitCode: 0,
+      commit: opts.commit || null,
+      inputTreeHash: computeInputTreeHash(opts.targetDir, [storyRel]),
+      criteriaHash: hashCriteria([
+        workItemId,
+        playValidation.code,
+        playDeclaration.deferTo || playDeclaration.instruction || '',
+      ]),
+      relevantFiles: [storyRel],
+      createdAt: playAt,
+      expiresAt: null,
+      freshnessPolicy: { scope: 'story' },
+      source: 'automated',
+    });
+
+    const playLedger = new RunLedger({ targetDir: opts.targetDir, policy, runId: state?.activeRunId || null, workItemId, phase });
+    playLedger.addEvidence(playEvidence);
+    playLedger.addDecision({ kind: 'stop', reason: `play deferred (${playValidation.code})`, scope: 'declaration only' });
+    playLedger.finalize({ status: 'ok' });
+    const playLedgerPath = playLedger.persist();
+
+    if (exists) {
+      const next = recordEvidence(state, playEvidence);
+      writeState(opts.targetDir, next);
+    }
+
     if (opts.format === 'json') {
-      emit(opts, '', { ok: true, path: shown, epic: opts.epicId, next: `cadet-agent harness confirm --gate ${HUMAN_ACCEPTANCE_GATE} --artifact ${shown}` });
+      emit(opts, '', { ok: true, story: opts.story, play: playValidation, cycles: playCycles, evidenceId: playEvidence.evidenceId, gateSet: exists, runId: playLedger.runId, path: playLedgerPath });
     } else {
-      console.log(`Acceptance form written: ${shown}`);
-      console.log(`   Fill in the three unfilled fields, then run:`);
-      console.log(`   cadet-agent harness confirm --gate ${HUMAN_ACCEPTANCE_GATE} --artifact ${shown}`);
+      console.log(`✅ ${USER_PLAY_GATE} for ${opts.story}: ${playValidation.message}`);
+      console.log('   The story defers the playthrough, so the declaration is the record — no form is needed.');
+      console.log(`   Ledger: ${playLedgerPath}`);
     }
     return;
   }
@@ -1728,7 +1913,13 @@ async function cmdHarness(opts) {
     const { exists, state } = readState(opts.targetDir);
 
     if (action === 'plan') {
-      const plan = buildContextPlan({ targetDir: opts.targetDir, policy, state });
+      // THE BRIEF IS WRITTEN BEFORE THE PLAN IS BUILT, so the plan can name it and hash it. A plan
+      // that named a file nobody had written would report its own tier-0 reference as MISSING, and
+      // the caller would have to run two commands to get one answer.
+      // Resolved once and shared, so the brief that is written and the plan that hashes it agree.
+      const docs = resolveWorkItemDocs(opts.targetDir, state);
+      writeStateBrief(opts.targetDir, state, policy, docs);
+      const plan = buildContextPlan({ targetDir: opts.targetDir, policy, state, docs });
       const planPath = writeContextPlan(opts.targetDir, plan);
       const shown = relative(opts.targetDir, planPath).replace(/\\/g, '/');
       const fit = plan.budget.fits === null ? 'no context budget declared'
@@ -2363,6 +2554,41 @@ export async function run(argv) {
   const opts = parseArgs(argv);
   const commandKey = resolveCommand(argv);
 
+  // A command may not bind its own outputs as the evidence it records.
+  //
+  // A record's `inputTreeHash` covers the files `--files` names, and `harness verify`,
+  // `harness confirm`, `harness verify-acs`, `harness verify-reachability`,
+  // `harness verify-design-review` and `harness verify-architecture` then write the ledger
+  // and `.cadet/state.json`. Binding one of those makes the record stale at the instant it
+  // is created — the write it describes changes a file the hash covers — so the next
+  // `state transition --dry-run` refuses the boundary for a record the harness itself just
+  // wrote. Refused here, in the dispatcher, rather than at each of the four sites that
+  // resolve `--files`: the registry already declares what each command writes, so the check
+  // covers a new command and a new flag the moment they are registered, which is the same
+  // reason `--dry-run` is driven from here (contract C13).
+  if (commandKey && opts.files && opts.files.length) {
+    const selfBound = selfBoundFiles(commandKey, opts.files);
+    if (selfBound.length > 0) {
+      const named = selfBound.join(', ');
+      fail(
+        opts,
+        `--files names ${selfBound.length === 1 ? 'a path' : 'paths'} that "${commandKey}" writes itself: ${named}. `
+        + 'Bind the files this gate JUDGES — sources, tests, and the story or epic markdown — never the ledger '
+        + `or state document the evidence is recorded in: "${commandKey}" writes ${named} as it records the `
+        + 'record, so a binding to it reads as stale the moment it is written ("input tree hash changed since '
+        + 'the evidence was recorded"), and the gate can never be fresh.',
+        () => 1,
+        {
+          ok: false,
+          command: commandKey,
+          code: 'self-bound-files',
+          files: selfBound,
+          writes: COMMANDS[commandKey].writes || [],
+        },
+      );
+    }
+  }
+
   // Global `--dry-run`, driven by the registry rather than by each handler.
   //
   // This is the structural fix for the class of bug where a mutating command