cadet-agent 0.60.0 → 0.63.1

package/src/cli.mjs

@@ -13,26 +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, buildPlayForm, parsePlayForm, writePlayForm, readPlayTemplate,
-  PLAY_FORM_GATE, PLAY_FORM_SUFFIX,
+  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);
@@ -61,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)
@@ -77,9 +78,7 @@ function showHelp() {
     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)
     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
@@ -90,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)
@@ -101,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, 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)
+    --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)
@@ -117,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)
@@ -204,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
@@ -222,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;
@@ -584,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);
@@ -859,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.`);
 }
 
 /**
@@ -917,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>');
@@ -926,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.
@@ -953,109 +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.
-    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` and `harness play-form` write the form pre-filled from state;
-    // this reads it back.
-    if (opts.artifact) {
-      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 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 ${isPlaythrough ? 'playthrough' : 'acceptance'} form could not be read (${err.message}).`, () => 1, { ok: false, gate, code: 'artifact-unreadable' });
-      }
-
-      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;
-      }
-    }
-
-    // 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)) {
@@ -1120,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,
     });
 
@@ -1755,14 +1805,16 @@ async function cmdHarness(opts) {
     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.
+    // 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') {
-      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}`,
+        `${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-form-required', story: opts.story, declaration: playDeclaration },
+        { ok: false, gate: USER_PLAY_GATE, code: 'play-required', story: opts.story, declaration: playDeclaration },
       );
     }
 
@@ -1846,85 +1898,6 @@ async function cmdHarness(opts) {
     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' });
-    }
-    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;
-    try {
-      template = readFileSync(templatePath, 'utf-8');
-    } 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' });
-    }
-    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 shown = result.path.slice(opts.targetDir.length + 1).replace(/\\/g, '/');
-    if (opts.format === 'json') {
-      emit(opts, '', { ok: true, path: shown, epic: opts.epicId, next: `cadet-agent harness confirm --gate ${HUMAN_ACCEPTANCE_GATE} --artifact ${shown}` });
-    } 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}`);
-    }
-    return;
-  }
-
   if (sub === 'context') {
     // The runtime context boundary: plan, record, validate.
     //
@@ -1940,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'

package/src/harness/commands.mjs

@@ -35,6 +35,10 @@ export const COMMANDS = {
     unattended: true,
   },
 
+  'state brief': {
+    mutates: false,
+    summary: 'Print the tier-0 summary of state.json: phase, active work item, every gate, and what compaction would archive.',
+  },
   'state validate': {
     mutates: false,
     summary: 'Validate .cadet/state.json against the current schema.',
@@ -141,7 +145,7 @@ export const COMMANDS = {
   'harness context plan': {
     mutates: true,
     summary: 'Write the context plan for the current phase: what must be loaded, and why.',
-    writes: ['.cadet/context/plan.json'],
+    writes: ['.cadet/context/plan.json', '.cadet/context/state-brief.md'],
     unattended: true,
   },
   'harness context record': {
@@ -170,28 +174,10 @@ export const COMMANDS = {
     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.
+    // story, and a playable story's record comes from the person's own answer 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.',
-    // It writes exactly one file, and only when that file does not exist: a form is a
-    // person's worksheet once they have touched it, and a regeneration would discard
-    // what they wrote. It never writes state — recording the gate is `harness confirm`.
-    writes: ['.cadet/agent/project-plans/**'],
-    unattended: true,
-  },
   'harness report': {
     mutates: false,
     summary: 'Summarize budget consumption and failures.',
@@ -224,6 +210,23 @@ export const COMMANDS = {
     mutates: false,
     summary: 'Report available CLI/Unity/MCP/hook/token/cost telemetry.',
   },
+  'harness diagram': {
+    mutates: true,
+    summary: 'Render UML component diagrams per package, coloured by workflow progress.',
+    // The tree is fully generated: one .noml + .svg per (package × epic), plus an
+    // index.html per package and at the root. `--out` may redirect it, but the
+    // default is the declared path, which is what the guard keys on.
+    writes: ['.cadet/diagrams/**'],
+    unattended: true,
+  },
+  'harness verify-diagrams': {
+    mutates: false,
+    summary: 'Check the committed diagram tree against a freshly computed model.',
+    // Read-only by construction: it regenerates the model in memory and compares
+    // it with the files on disk. It does not write the tree — a check that
+    // repaired the thing it checks would prove nothing — and `harness reconcile`
+    // calls the same function, so the two cannot disagree.
+  },
   'harness cleanup': {
     mutates: true,
     summary: 'Apply the retention policy to .cadet/runs/, deleting run records.',