cadet-agent 0.56.0 → 0.60.0

package/README.md

@@ -7,9 +7,9 @@ Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished g
 ## Repository Layout
 - `.cadet/agent/core/` contains the shared Cadet-Agent framework documents.
   - `cadet-agent.md` is the thin global directive: identity, non-negotiable rules, workflow routing, hard-gate protocol, and skill dispatch.
-  - `Harness.md` is the canonical harness contract: budgets, evidence-backed gates, retries, context tiers, tool routing, privacy, and escalation.
+  - `HarnessRuntime.md` is the lean runtime contract; `Harness.md` keeps the full harness rationale and reference.
   - `harness.schema.json` and `state.schema.json` are the machine-readable schemas for harness records and session state.
-  - `skills/` contains scoped workflow-phase skills (PlanningReview, Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview, Resume, MCPSetup, AgentReviewer, Handoff, Reconciliation).
+  - `skills/` contains scoped workflow-phase skills (PlanningReview, Requirements, Architecture, DesignReview, Spike, StoryBreakdown, TDD, Debugging, CodeReview, VisualEvidence, Resume, MCPSetup, AgentReviewer, Handoff, Reconciliation).
   - `templates/` contains runtime templates for planning artifacts.
 - `.cadet/harness.json` holds repository-local budget/policy overrides (preserved by sync).
 - `.cadet/runs/` holds sanitized run ledgers (preserved by sync; no secrets or raw prompts by default).
@@ -37,11 +37,13 @@ Cadet-Agent provides the **same skills** across six IDEs — one canonical file
 | Planning Review | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Requirements | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Design Review | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Spike | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Story Breakdown | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | TDD | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Debugging | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Code Review | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Visual Evidence | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Resume | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | MCP Setup | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Reconciliation | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -118,12 +120,12 @@ flowchart TD
     REPORT["Report current phase,<br/>epics, stories & gates"]
     CR["🔍 Context Resolution<br/>classify change size,<br/>calibrate learner,<br/>detect policy"]
     REQ["📋 Requirements<br/>Given/When/Then criteria<br/>assumption audit"]
-    PLANREV["🧩 Planning Review<br/>interview one question<br/>at a time · decision tree"]
+    PLANREV["🧩 Planning Review (skill)<br/>interview one question<br/>at a time · decision tree"]
     ARCH["🏗️ Architecture<br/>technical design,<br/>ADR decisions"]
     SPIKE["🧪 Spikes<br/>resolve unverified<br/>assumptions"]
     BREAKDOWN["📐 Story Breakdown<br/>epics → testable stories"]
     IMPL["🔨 Implementation<br/>TDD per story,<br/>red → green → refactor"]
-    REVIEW["✅ Review<br/>hard gate: 17-step<br/>code review, security"]
+    REVIEW["✅ Review<br/>hard gate: 23-step<br/>code review, security"]
     VALIDATE["✔️ Validation<br/>acceptance criteria,<br/>design artifact sync"]
     CLOSED(["🎉 Closed"])
     NEXT_STORY{"More stories<br/>in epic?"}
@@ -140,13 +142,13 @@ flowchart TD
 
     REQ --> ARCH
     ARCH -->|"unverified assumptions"| SPIKE
-    ARCH -->|"all assumptions resolved"| BREAKDOWN
+    ARCH -->|"all assumptions resolved<br/>gate: designReviewCompleted ✅ (opt-in)"| BREAKDOWN
     SPIKE -->|"spike complete"| ARCH
 
     BREAKDOWN --> IMPL
 
     IMPL -->|"story complete"| REVIEW
-    REVIEW -->|"gate: codeReviewCompleted ✅<br/>gate: securityReviewPassed ✅<br/>gate: reachabilityAddressed ✅ (opt-in)"| VALIDATE
+    REVIEW -->|"gate: codeReviewCompleted ✅<br/>gate: securityReviewPassed ✅<br/>gate: acceptanceCriteriaValidated ✅<br/>gate: reachabilityAddressed ✅ (opt-in)<br/>gate: userPlaythroughConfirmed ✅ (opt-in)"| VALIDATE
     VALIDATE -->|"gate: designArtifactSyncConfirmed ✅"| NEXT_STORY
     NEXT_STORY -->|"yes"| IMPL
     NEXT_STORY -->|"no"| CLOSED
@@ -165,13 +167,15 @@ Use the `/cadet-resume` slash command to pick up where you left off. It reads `.
 
 ### Phase Gating
 
-Hard gates are enforced at every phase transition. The agent reads `.cadet/state.json → gates` before advancing and **blocks** the transition if any required gate is `false`. Gates cannot be skipped without an explicit user-directed exception recorded in `changeHistory`.
+Hard gates are enforced at every phase transition. The agent reads `.cadet/state.json → gates` before advancing and **blocks** the transition if any required gate is `false`. Gates cannot be skipped without an explicit, user-directed exception recorded in `.cadet/state.json → gateExceptions` — bounded by `expiresAt`, and naming the work items it covers. A `v1`–`v3` exception is read out of `changeHistory`, its older home.
 
 | Transition | Required Gates |
 |---|---|
 | architectureComplete → story-breakdown | `designReviewCompleted` when `designReview.enabled` is set — the formal design review, recorded by `harness verify-design-review` |
 | implementation → review | `testsPassed`, `compileCheckConfirmed`, `unityAnalyzerClean`, `storyTrackingUpdated`, and `architectureFitnessPassed` when the project declares architecture checks and enables them |
-| review → validation | `codeReviewCompleted`, `securityReviewPassed`, `acceptanceCriteriaValidated`, and `reachabilityAddressed` when `reachability.enabled` is set |
+| review → validation | `codeReviewCompleted`, `securityReviewPassed`, `acceptanceCriteriaValidated`, `reachabilityAddressed` when `reachability.enabled` is set, and `userPlaythroughConfirmed` when `userPlay.enabled` is set — a story declares `Play: required — <what the user does and what they see>` or `Play: deferred to <work item> — <why>`. A person's own record satisfies `required` (`harness play-form` writes the form, `harness confirm --artifact` records it); `harness verify-play` records `deferred`, and the deferral expires when the named work item closes |
+| validation → closed | `designArtifactSyncConfirmed`, and `humanAcceptanceConfirmed` when `humanAcceptance.enabled` is set — a person's own record (`harness acceptance-form` writes the form, `harness confirm --artifact` records it); no command can produce it |
+
 ### Runtime context protocol (opt-in, and the framework's own claim discipline)
 
 `harness context plan` states what a phase requires (with a reason and a hash for each reference),
@@ -181,42 +185,67 @@ reported as it is — a run reported as `recorded` is never reported as `enforce
 a hook that declares it enforces context. A required reference that was never loaded, or that changed
 after the record, blocks the checkpoint. See `.cadet/agent/core/Harness.md` §2d.
 
-| validation → closed | `designArtifactSyncConfirmed`, and `humanAcceptanceConfirmed` when `humanAcceptance.enabled` is set — a person's own record (`harness acceptance-form` writes the form, `harness confirm --artifact` records it); no command can produce it |
-
 **`closed` is end-of-epic, not per-story.** `validation → closed` is taken only when no stories remain (`NEXT_STORY → no → CLOSED` above). When an epic still has stories, the next story re-enters from `validation → implementation` (`NEXT_STORY → yes → IMPL`). Do not close a story individually: `closed` is terminal, and there is no transition out of it.
 
-The full set of legal transitions is the three gated rows above **plus** the ungated forward edges (classification, planning progression, `story-breakdown → implementation`, and the `validation → implementation` next-story loop). Any transition outside that set is rejected with a named reason.
+The full set of legal transitions is the three gated rows above **plus** the ungated forward edges (classification, planning progression, `story-breakdown → implementation`, and the `validation → implementation` next-story loop). Any transition outside that set is rejected with a named reason. **Planning Review is a skill, not a phase**: the agent dispatches it before requirements or architecture when the plan is fuzzy or contested, and it records no transition.
+
+### The response contract
+
+The framework's only per-reply output is one line: `cadet-agent: ok`, or the problem in its place. `cadet-agent harness status` derives that line — read-only — from the state document and the run ledger, so it cannot claim a health nothing verified. `ok` means the record is readable, valid and fresh, and no recorded run stopped on a budget or failed to run. A gate that is unmet because the story is unfinished is normal, and is not reported. The rest of a reply carries the work: the decisions taken, what changed, what the checks show, and what is unverified or deferred.
 
 ### Harness
 
 Gates are backed by **evidence**, not assertion. Each claimed gate must have a fresh, non-superseded evidence record bound to the current work item, input tree hash, and acceptance criteria. The harness also bounds context, tokens, tool calls, retries, wall-clock time, cost, and archive sizes — and those bounds are enforced, not advisory.
 
-- Rules: `.cadet/agent/core/Harness.md`. Data contract: `docs/core/HarnessContract.md`.
+- Runtime rules: `.cadet/agent/core/HarnessRuntime.md`. Full contract: `.cadet/agent/core/Harness.md`. Data contract: `docs/core/HarnessContract.md`.
 - Overrides: `.cadet/harness.json` (preserved by sync; conservative defaults in `src/harness/policy.mjs`).
 - Ledgers: `.cadet/runs/<runId>.json` (sanitized; artifacts are redacted before they are written; no secrets or raw prompts by default).
 - Transitions recompute the input tree hash from the evidence's relevant files, so editing a relevant file invalidates the evidence.
 - `harness verify` binds evidence to `--files` (or the working tree's changed files), and a `testsPassed` green result requires a prior red record.
+- A `--files` binding may not name a path the recording command itself writes: `--files .cadet/state.json` is refused before anything runs, because the write that follows would stale the record it just wrote.
 - When Git is unavailable and no `--files` are given, verification blocks (`freshness-unavailable`) rather than recording unscoped evidence.
 - `state validate` rejects a `true` gate whose evidence is missing, stale, expired, superseded, or bound to another work item; evidence records are schema-validated in full (`command`, `result`, `criteriaHash`, and a freshness bound).
+- `state validate` errors when a work item that a `storyCompletions` row records as finished, with evidence behind it, still reads `planned`. The remedy is `done` or `superseded`: a finished story must not be indistinguishable from one that was never started.
+- A `changeHistory` entry is a pointer, not a retelling: it is limited to 400 characters, and `state compact` archives a longer entry in place rather than truncating it.
 - Evidence must include a UUID, work item, phase, gate, status, command/result, input-tree hash, criteria hash, relevant files, timestamp, and either `expiresAt` or `freshnessPolicy`.
 - **Evidence history does not live in `state.json`.** A v4 document keeps only the active work item's records inline; a closed work item's evidence is written into the commit that closes it, as `Cadet-*` trailers, and archived to `.cadet/archive/`. `evidenceCoverage` indexes what left, so the "a done story owns evidence" check still works offline. Cadet still never commits: `state seal` prepares a message file and you commit with `git commit -F`.
+- **Two gates are human-owned: `humanAcceptanceConfirmed` and `userPlaythroughConfirmed`.** No
+  command can produce them, and `--command` is refused for them. `harness acceptance-form --epic <id>`
+  and `harness play-form --story <path>` write the form; `harness confirm --gate <gate> --artifact <form>`
+  records what the person wrote. A form still holding a placeholder is refused, and a form someone has
+  started is never overwritten.
 - Command output counts against the output budget; a configured cost budget cannot be satisfied by unmeasurable cost (the run is blocked, `budget-blocked`).
 - State and run ledgers are written atomically, so an interrupted write cannot truncate a record; persisted artifacts are redacted before hashing or writing.
 - Empty freshness coverage is an explicit policy decision: set `allowEmptyFreshness: true` in `.cadet/harness.json` only when unscoped evidence is acceptable.
 
 ```bash
+cadet-agent state init --workflow-path large     # write the first state document (validated before it lands)
 cadet-agent state validate                       # validate state against the schema (read-only)
 cadet-agent state validate --verify-sealed       # also read evidence out of commit trailers
 cadet-agent state migrate                        # atomically upgrade v1 → the current version
 cadet-agent state migrate --to 4                 # archive closed work items' evidence; build the index
 cadet-agent state compact --keep active          # routine housekeeping on a v4 state
 cadet-agent state seal                           # write the active work item's evidence as commit trailers
+cadet-agent state begin --epic <id> --story <id> # start a work item; archive the previous item's evidence
 cadet-agent state transition --to review         # enforce the matrix + evidence
+cadet-agent harness status                       # the health line: ok, or the problem (read-only)
 cadet-agent harness verify --gate testsPassed --files src/a.cs   # bounded, classified loop
+cadet-agent harness verify-acs --story <path>    # derive coverage from the run report, then record the gate
+cadet-agent harness verify-reachability --story <path>           # check the declaration; run the project probe
+cadet-agent harness verify-design-review --artifact <path> --files <design,requirements,ADRs>
+cadet-agent harness verify-architecture          # run the project's declared fitness checks
+cadet-agent harness verify-play --story <path>   # check a story's `Play:` declaration; record a deferral
+cadet-agent harness play-form --story <path>     # write a user-playthrough form for a person to fill
+cadet-agent harness acceptance-form --epic <id>  # write the epic's human-acceptance form
+cadet-agent harness confirm --gate <gate> --artifact <form>      # record a person's own account
+cadet-agent harness changes                      # the files a story changed, with links (read-only)
 cadet-agent harness report                       # budget consumption and failures (no secrets)
 cadet-agent harness reconcile                    # reconcile the planning chain against state.json (read-only)
+cadet-agent harness matrix-check                 # reconcile a TDD matrix against the test inventory (read-only)
+cadet-agent harness context plan|record|validate # plan what a phase loads, record what it loaded, decide
 cadet-agent harness cleanup --older-than-ms <n>  # apply the retention policy (bound required)
 cadet-agent harness capabilities                 # available CLI/Unity/MCP/hook/token/cost telemetry
+cadet-agent harness capabilities --verify-host   # probe the configured interception, per action
 ```
 
 Every command supports `--format human|json` and exits nonzero for invalid state, failed verification, budget exhaustion, stale evidence, or safety rejection.
@@ -332,13 +361,14 @@ If a specific game repository needs local conventions, add a policy file under `
 
 ## Package Output
 Running `./package-agent.ps1` produces `cadet-agent.zip` with this layout:
-- `.cadet/agent/core/` (including `Harness.md`, `harness.schema.json`, and `state.schema.json`)
+- `.cadet/agent/core/` (including `HarnessRuntime.md`, `Harness.md`, `harness.schema.json`, and `state.schema.json`)
 - `.cadet/agent/core/skills/`
 - `.cadet/agent/core/templates/`
 - `.github/agents/cadet.agent.md`
 - `.github/agents/cadet-agent-reviewer.agent.md`
 - `.github/prompts/cadet-*.prompt.md`
-- `.github/hooks/`
+- `.github/hooks/` (the Copilot `git-guard` hook and its scripts)
+- `.githooks/pre-commit` (the portable Git hook; installed by you with `git config core.hooksPath .githooks`)
 - `.cursor/rules/cadet-agent.md`
 - `.cursor/rules/cadet-agent-reviewer.md`
 - `.continue/rules/cadet-agent.md`
@@ -346,6 +376,10 @@ Running `./package-agent.ps1` produces `cadet-agent.zip` with this layout:
 - `.continue/config.yaml`
 - `.claude/skills/cadet-agent/SKILL.md`
 - `.claude/skills/cadet-*/SKILL.md`
+- `.agents/skills/cadet-agent/SKILL.md` (the cross-client root Deep Code and Hermes read)
+- `.agents/skills/cadet-*/SKILL.md`
+- `AGENTS.md` (create-only: an existing consumer copy is never overwritten)
+- `.cadet/harness.json` (create-only: the new-consumer policy seed)
 
 ## Notes
 - `.cadet/agent/core/FrameworkManifest.json` defines the managed and preserved paths for packaged installs.

package/package.json

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

package/src/cli.mjs

@@ -24,9 +24,13 @@ import {
   parseReachabilityDeclaration, validateReachabilityDeclaration, collectWorkItems,
   findDeferralCycles, readSiblingDeclarations, normalizeWorkItemRef, describeReachabilityGaps,
   REACHABILITY_GATE, runCommand,
+  parsePlayDeclaration, validatePlayDeclaration, readSiblingPlayDeclarations, describePlayGaps,
+  USER_PLAY_GATE, buildPlayForm, parsePlayForm, writePlayForm, readPlayTemplate,
+  PLAY_FORM_GATE, PLAY_FORM_SUFFIX,
   createEvidence, newId, computeInputTreeHash, hashCriteria,
   collectDeclaredTestNames, reconcileTestNames,
   resolveCommand, describeCommand, describeAllCommands, checkUnattendedRequirements, COMMANDS,
+  selfBoundFiles,
   STATE_VERSION, sealedEvidence, recordEvidence, appendEvidence, sealWorkItem, toStateV4,
   isHistoryExternal, HISTORY_ENTRIES_KEPT, resetGatesForNewWorkItem,
 } from './harness/index.mjs';
@@ -72,6 +76,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 play-form   Write a user-playthrough form for a story, filled in from state (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)
@@ -99,8 +105,8 @@ function showHelp() {
     --expires-at   ISO-8601 expiry bounding the confirmation (harness confirm)
     --environment  key=value,... describing what was verified (harness confirm)
     --scope        Comma-separated scope of the confirmation (harness confirm)
-    --story        Story markdown declaring the acceptance criteria 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)
+    --story        Story markdown declaring the acceptance criteria, reachability or play declaration (harness verify-acs|verify-reachability|verify-play|play-form)
+    --artifact     Design-review artifact to check (verify-design-review), or the acceptance/playthrough form to record from (confirm --gate humanAcceptanceConfirmed|userPlaythroughConfirmed)
     --epic         Epic a generated form belongs to (harness acceptance-form)
     --out          Where to write the form (default: the epic's plan directory)
 
@@ -976,40 +982,73 @@ async function cmdHarness(opts) {
     // 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.
+    const FORM_RECORDED_GATES = new Set([HUMAN_ACCEPTANCE_GATE, USER_PLAY_GATE]);
     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' });
     }
+    // A playthrough is recorded from a form too, and from nothing else. The gate asks whether a
+    // PERSON played the delivered work, so the only route is that person's own account of it —
+    // which is also why `harness verify-play` refuses a `required` declaration.
+    if (gate === USER_PLAY_GATE && !opts.artifact) {
+      fail(opts, `a playthrough is recorded from a form: run "cadet-agent harness play-form --story <path>" to write one pre-filled from state, play the work, fill in its blank fields, then pass it back with --artifact <the form>.`, () => 1, { ok: false, gate, code: 'play-form-required' });
+    }
 
-    // `harness acceptance-form` writes the form pre-filled from state; this reads it back.
+    // `harness acceptance-form` and `harness play-form` write 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 isPlaythrough = gate === USER_PLAY_GATE;
+      if (!FORM_RECORDED_GATES.has(gate)) {
+        fail(opts, `--artifact is only for ${HUMAN_ACCEPTANCE_GATE} and ${USER_PLAY_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 });
+        fail(opts, `--artifact already carries the record, 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 });
+        fail(opts, `the ${isPlaythrough ? 'playthrough' : 'acceptance'} form could not be read (${err.message}).`, () => 1, { ok: false, gate, code: 'artifact-unreadable' });
       }
-      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 });
+
+      if (isPlaythrough) {
+        const form = parsePlayForm(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 — a playthrough nobody described is not a playthrough.`, () => 1, { ok: false, gate, code: 'play-form-incomplete', missing: form.incomplete });
+        }
+        // The record binds to the ACTIVE work item, so a form that plays a different story is
+        // refused rather than recorded against the one in flight — the same failure the
+        // story-bound evidence rules exist to prevent, wearing a filled-in form.
+        const activeStory = state?.activeWorkItem?.storyId || null;
+        const formStory = String(form.story || '');
+        if (activeStory && formStory && !formStory.includes(activeStory)) {
+          fail(opts, `the form plays "${form.story}", but the active work item is "${activeStory}". Record a playthrough of the work in flight, or begin that story first.`, () => 1, { ok: false, gate, code: 'play-form-story-mismatch', story: form.story, active: activeStory });
+        }
+        opts.witness = form.witness;
+        opts.limitations = form.limitations;
+        opts.environment = form.environment || null;
+        opts.scope = [form.story || activeStory || 'playthrough'];
+        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.playedBy = form.player;
+      } else {
+        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;
       }
-      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
@@ -1679,6 +1718,179 @@ async function cmdHarness(opts) {
     return;
   }
 
+  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);
+    assertExpectedPhase(opts, state);
+    const playEnabled = policy.userPlay?.enabled === true;
+    const workItemId = state ? workItemIdOf(state) : 'unscoped';
+    const phase = state?.session?.currentPhase || 'implementation';
+
+    let playDeclaration;
+    try {
+      playDeclaration = parsePlayDeclaration(storyPath);
+    } catch (err) {
+      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, and the refusal names the route that can.
+    if (playValidation.ok && playValidation.code === 'required') {
+      const formHint = `run "cadet-agent harness play-form --story ${opts.story}" to write one pre-filled from state, play the game, fill in the three blank fields, then pass it back with --artifact <the form>.`;
+      fail(
+        opts,
+        `${USER_PLAY_GATE} is a person's record, and this story declares its deliverable playable: ${playDeclaration.instruction}. ${formHint}`,
+        () => 1,
+        { ok: false, gate: USER_PLAY_GATE, code: 'play-form-required', story: opts.story, declaration: playDeclaration },
+      );
+    }
+
+    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;
+    }
+
+    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, story: opts.story, play: playValidation, cycles: playCycles, evidenceId: playEvidence.evidenceId, gateSet: exists, runId: playLedger.runId, path: playLedgerPath });
+    } else {
+      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;
+  }
+
+  if (sub === 'play-form') {
+    if (!opts.story) {
+      fail(opts, 'harness play-form needs --story <path>: the form belongs to the story being played.', () => 1, { ok: false, code: 'story-required' });
+    }
+    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' });
+    }
+    const storyPath = resolve(opts.targetDir, opts.story);
+    const storyRel = relative(opts.targetDir, storyPath).replace(/\\/g, '/') || basename(storyPath);
+    let playDeclaration = null;
+    try {
+      playDeclaration = parsePlayDeclaration(storyPath);
+    } catch (err) {
+      fail(opts, `cannot read story "${opts.story}": ${err.message}`, () => 1, { ok: false, code: 'story-unreadable', story: opts.story });
+    }
+    let playTemplate;
+    try {
+      playTemplate = readPlayTemplate(opts.targetDir);
+    } catch (err) {
+      fail(opts, `${err.message}. 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' });
+    }
+    const playText = buildPlayForm({
+      template: playTemplate,
+      state,
+      storyPath,
+      storyRel,
+      targetDir: opts.targetDir,
+      declaration: playDeclaration,
+    });
+    const playResult = writePlayForm(opts.targetDir, storyRel, playText, { out: opts.out });
+    if (!playResult.written) {
+      fail(opts, `harness play-form refuses to overwrite an existing form: ${playResult.reason} (${playResult.path}).`, () => 1, { ok: false, code: 'form-exists', path: playResult.path });
+    }
+    const playShown = playResult.path.slice(opts.targetDir.length + 1).replace(/\\/g, '/');
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: true, path: playShown, story: opts.story, next: `cadet-agent harness confirm --gate ${PLAY_FORM_GATE} --artifact ${playShown}` });
+    } else {
+      console.log(`Playthrough form written: ${playShown}`);
+      console.log('   Play the work, fill in the three unfilled fields, then run:');
+      console.log(`   cadet-agent harness confirm --gate ${PLAY_FORM_GATE} --artifact ${playShown}`);
+    }
+    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' });
@@ -2363,6 +2575,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

package/src/harness/commands.mjs

@@ -165,6 +165,24 @@ export const COMMANDS = {
     writes: ['.cadet/runs/**', '.cadet/state.json'],
     unattended: true,
   },
+  'harness verify-play': {
+    mutates: true,
+    summary: 'Verify a story\'s Play: declaration; record the gate for a deferral, refuse it for a playable story.',
+    // Same posture as verify-reachability: it records evidence for its gate, so it writes
+    // the ledger and state. It writes no artifact of its own — the declaration lives in the
+    // story, and a playable story's record comes from the person's form instead.
+    writes: ['.cadet/runs/**', '.cadet/state.json'],
+    unattended: true,
+  },
+  'harness play-form': {
+    mutates: true,
+    summary: 'Write a user-playthrough form for a story, pre-filled from state.',
+    // One file, and only when it does not exist: a form is a person's worksheet once they
+    // have touched it, and regenerating it would discard what they wrote. It never writes
+    // state — recording the gate is `harness confirm --artifact`.
+    writes: ['.cadet/agent/project-plans/**'],
+    unattended: true,
+  },
   'harness acceptance-form': {
     mutates: true,
     summary: 'Write a human-acceptance form for an epic, pre-filled from state.',
@@ -229,6 +247,63 @@ export function readOnlyCommands() {
   return Object.entries(COMMANDS).filter(([, c]) => !c.mutates).map(([k]) => k);
 }
 
+/** Repository-relative form of a path: forward slashes, no leading `./`. */
+function normaliseRepoPath(path) {
+  return String(path).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/**
+ * Does one of a command's `writes` patterns cover a path?
+ *
+ * The shipped table uses exactly three shapes, and the matcher supports those and no more:
+ * an exact path (`AGENTS.md`), a directory subtree (`<dir>/**`), and a root-level suffix
+ * wildcard (`*.coverage.json`). `**` crosses directory boundaries and `*` does not — the
+ * distinction a shell makes, and the reason a `*` that crossed directories would refuse a
+ * file the command never touches.
+ *
+ * Wildcards are replaced FIRST, with placeholders that survive the escape pass. Doing it the
+ * other way round turns `**` into a literal `\*\*` and every declaration stops matching — the
+ * defect this function shipped with for one run, caught by the generated test below it.
+ *
+ * Absolute paths are deliberately not translated: `--files` carries repository-relative paths
+ * by contract, so an absolute path is a different mistake and not this function's to guess at.
+ */
+function writePatternMatches(pattern, path) {
+  const escaped = normaliseRepoPath(pattern)
+    .replace(/\*\*/g, '\u0000')
+    .replace(/\*/g, '\u0001')
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\u0000/g, '.*')
+    .replace(/\u0001/g, '[^/]*');
+
+  return new RegExp(`^${escaped}$`).test(normaliseRepoPath(path));
+}
+
+/**
+ * The `--files` entries a command declares it WRITES, and which must therefore never be
+ * bound as its evidence.
+ *
+ * Why this exists: a record's `inputTreeHash` covers the files it binds, and the command
+ * then writes its own outputs — the run ledger and `.cadet/state.json`. Binding one of those
+ * makes the record stale at the instant it is created, because the write it records changes
+ * a file the hash covers. Measured on a consumer on 2026-10-01: a `storyTrackingUpdated`
+ * record that bound the story, the epic and `.cadet/state.json` was refused by the very next
+ * `state transition --dry-run` with "input tree hash changed since the evidence was
+ * recorded", and the gate had to be re-recorded twice before the boundary was allowed.
+ *
+ * The answer is a refusal rather than a filter. Filtering would leave the record claiming a
+ * coverage it does not have, and the caller asked for a binding that provably cannot hold —
+ * the same choice `AGENT_OWNED_GATES` and the swallowed `--command` flag both resolved the
+ * loud way. It is derived from the registry rather than hardcoded, so a new command's
+ * outputs are covered the moment it is registered.
+ */
+export function selfBoundFiles(commandKey, files = []) {
+  const writes = COMMANDS[commandKey]?.writes || [];
+  if (writes.length === 0 || !Array.isArray(files) || files.length === 0) return [];
+
+  return files.filter((file) => writes.some((pattern) => writePatternMatches(pattern, file)));
+}
+
 /**
  * Resolve the command key for a parsed invocation.
  *