cadet-agent 0.53.0 → 0.56.0

package/src/harness/acceptance-form.mjs

@@ -0,0 +1,281 @@
+/**
+ * Human acceptance: the form, and reading it back.
+ *
+ * The gate is human-owned, but the RECORD should not be homework. Typing the same
+ * acceptance into a hand-written template and then into six CLI flags is duplication,
+ * and duplication is what turns a gate into a documentation chore: the two copies
+ * drift, the person fills both, and the one that matters is whichever the machine read.
+ *
+ * So the capture works the way the design review does — the artifact IS the input —
+ * with one difference that makes it easy rather than merely possible: the form is
+ * GENERATED from state first, so everything the framework already knows (the epic, its
+ * stories, the revision, the files, the candidate limitations) is already written down
+ * and the person fills only the two things only a person can say: what they did and saw,
+ * and what they accepted as missing. The command to record it is printed at the bottom
+ * of the form itself, with the real path in it.
+ *
+ * Two commands, no retyping, and they are the only route — there are no
+ * `--witness`/`--limitations` flags to type the same acceptance into twice:
+ *
+ *   cadet-agent harness acceptance-form --epic <id>          # writes a filled-in form
+ *   cadet-agent harness confirm --gate humanAcceptanceConfirmed --artifact <the form>
+ *
+ * The shape lives in `templates/HumanAcceptanceTemplate.md`, which the generator reads,
+ * so the shipped template and the generated form cannot drift into two formats.
+ */
+
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+
+/** The gate this form records. */
+export const ACCEPTANCE_FORM_GATE = 'humanAcceptanceConfirmed';
+
+/** Where a generated form goes inside an epic's own artifact directory. */
+export const ACCEPTANCE_FORM_FILENAME = 'HumanAcceptance.md';
+
+/** The template the generator fills. A managed path, so a synced repository has it. */
+export const ACCEPTANCE_TEMPLATE_RELATIVE = '.cadet/agent/core/templates/HumanAcceptanceTemplate.md';
+
+/**
+ * The fields only a person can supply. The generator leaves all three as unfilled
+ * slots, and the parser refuses a form where any of them still is one: a sentinel left
+ * in place means the person did not answer, and recording that would put the
+ * framework's own placeholder text into the record as if someone had written it.
+ */
+export const ACCEPTANCE_HUMAN_FIELDS = Object.freeze(['acceptor', 'witness', 'limitations']);
+
+/**
+ * A slot that the generator failed to fill is still a slot.
+ *
+ * Matched attribute-wise rather than up to the first `>`: a slot's `note` is prose and
+ * some notes contain `>` (`revision=<sha>`, for one), so a naive `[^>]*` stops
+ * mid-attribute and leaves the slot unfilled. Silent is the bad part — the form then
+ * records the template's own instructions as an answer.
+ */
+const UNFILLED = /<slot\b/;
+const slotTag = (id) => new RegExp(`<slot\\s+id="${id}"(?:[^>"]|"[^"]*")*/>`);
+
+/** True when a captured value is empty or still the template's placeholder. */
+export function isUnfilled(value) {
+  return value === null || value === undefined || String(value).trim() === '' || UNFILLED.test(String(value));
+}
+
+/** The path of the generated form for an epic. */
+export function acceptanceFormPath(targetDir, epicId) {
+  return join(targetDir, '.cadet', 'agent', 'project-plans', epicId, ACCEPTANCE_FORM_FILENAME);
+}
+
+/** The machine's best answer for "which revision is this", or `unknown`. */
+function revisionOf(targetDir) {
+  try {
+    const r = spawnSync('git', ['-C', targetDir, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf-8', windowsHide: true });
+    const sha = (r.stdout || '').trim();
+    return r.status === 0 && sha ? sha : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/** The Unity editor version, when the repository records one. */
+function editorVersionOf(targetDir) {
+  try {
+    const text = readFileSync(join(targetDir, 'ProjectSettings', 'ProjectVersion.txt'), 'utf-8');
+    const m = text.match(/m_EditorVersion:\s*(\S+)/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What the machine already knows, written into the form so nobody retypes it.
+ *
+ * The candidates section is the part that saves the most work: the limitations a person
+ * would otherwise have to remember are exactly the ones the record already holds — a
+ * deferral that is still open, an exception someone accepted earlier, a story that never
+ * reached validation. They are listed as candidates, not as claims: the person keeps what
+ * applies and deletes the rest, and the parser reads only the Accepted limitations
+ * section, never this list.
+ */
+export function acceptanceCandidates(state) {
+  const out = [];
+  const epic = state?.activeWorkItem?.epicId;
+  const epics = state?.epics || {};
+
+  for (const [epicId, entry] of Object.entries(epics)) {
+    for (const [story, status] of Object.entries(entry?.stories || {})) {
+      if (status !== 'done' && status !== 'validated') {
+        out.push(`${epicId === epic ? '' : `(${epicId}) `}${story} is "${status}", not done — say whether that is accepted or outstanding`);
+      }
+    }
+  }
+
+  for (const exception of state?.gateExceptions || []) {
+    const expiry = exception.expiresAt ? `expires ${String(exception.expiresAt).slice(0, 10)}` : 'no expiry';
+    out.push(`gate \`${exception.gate}\` was excepted as \`${exception.category}\` (${expiry})`);
+  }
+
+  if (Array.isArray(state?.gateEvidence)) {
+    const deferred = state.gateEvidence.filter((e) => typeof e?.result === 'string' && /deferr/i.test(e.result));
+    for (const record of deferred) {
+      out.push(`\`${record.gate}\` recorded a deferral: ${String(record.result).slice(0, 120)}`);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Build the form for an epic by filling the shipped template's known slots.
+ *
+ * Blank slots the person must answer are left exactly as the template wrote them, so an
+ * unfinished form is obvious to a reader and refusable by the parser — no second marker
+ * convention to learn.
+ */
+export function buildAcceptanceForm({ template, state, epicId, targetDir, now = new Date() }) {
+  if (typeof template !== 'string' || template.trim() === '') {
+    throw new Error('the human-acceptance template is empty');
+  }
+  const stories = Object.entries(state?.epics?.[epicId]?.stories || {});
+  const files = [];
+  for (const [story] of stories) {
+    for (const candidate of [
+      join('.cadet', 'agent', 'project-plans', epicId, story),
+      join('.cadet', 'agent', 'story-breakdown', story),
+    ]) {
+      if (existsSync(join(targetDir, candidate))) files.push(candidate.replace(/\\/g, '/'));
+    }
+  }
+
+  const environment = [`revision=${revisionOf(targetDir)}`];
+  const editor = editorVersionOf(targetDir);
+  if (editor) environment.push(`editor=${editor}`);
+  environment.push(`date=${now.toISOString().slice(0, 10)}`);
+
+  const scopeReviewed = stories.length
+    ? stories.map(([story, status]) => `- ${story} — ${status}`).join('\n')
+    : '- (no stories recorded for this epic yet)';
+
+  const candidates = acceptanceCandidates(state);
+  const candidateText = candidates.length
+    ? candidates.map((line) => `- ${line}`).join('\n')
+    : '- (nothing outstanding in state)';
+
+  const formRelative = acceptanceFormPath(targetDir, epicId)
+    .slice(targetDir.length + 1)
+    .replace(/\\/g, '/');
+  const recording = [
+    '1. Fill in **Accepted by**, **## Witness** and **## Accepted limitations** — the three',
+    '   fields with a `<slot .../>` in them. Everything else is already written down.',
+    '2. Record it:',
+    '',
+    '   ```',
+    `   cadet-agent harness confirm --gate ${ACCEPTANCE_FORM_GATE} --artifact ${formRelative} \\`,
+    '     --reason "<one line: why this was accepted>" --expires-at <ISO-8601>',
+    '   ```',
+    '',
+    '   `--reason` and `--expires-at` are required by strict closure, and they are the only',
+    '   fields to pass: the form already carries the scope and the environment, and passing',
+    '   `--scope` or `--environment` as well is refused as a second, competing source.',
+    '',
+    '   The command reads this file, binds the files it names, and records the gate. It',
+    '   refuses a form whose witness or limitations is still a placeholder, so an',
+    '   unfinished form cannot be recorded by accident.',
+    '3. Where a user cannot reach the work at all, do not accept it: record a',
+    '   `non-user-facing` gate exception instead, naming who judged it.',
+  ].join('\n');
+
+  const filled = {
+    epic: epicId,
+    date: now.toISOString().slice(0, 10),
+    files: files.length ? files.join(', ') : '(none found — list the files this acceptance covers)',
+    environment: environment.join(', '),
+    scopeReviewed,
+    candidates: candidateText,
+    recording,
+  };
+
+  let text = template;
+  for (const [id, value] of Object.entries(filled)) {
+    text = replaceSlot(text, id, value);
+  }
+  return { text, filled: Object.keys(filled), files };
+}
+
+/** Replace one `<slot id="x" .../>` occurrence with a value, keeping a trailing newline sane. */
+function replaceSlot(text, id, value) {
+  const re = slotTag(id);
+  if (!re.test(text)) return text;
+  return text.replace(re, value);
+}
+
+/**
+ * Read a filled form back.
+ *
+ * Returns the values it found plus `incomplete`, the human fields still unanswered. It
+ * makes no judgement about the acceptance itself — that is the point of the gate — and it
+ * does not read the candidates section, which exists to help a person write the
+ * limitations section, not to supply it.
+ */
+export function parseAcceptanceForm(text) {
+  if (typeof text !== 'string' || text.trim() === '') {
+    return { incomplete: [...ACCEPTANCE_HUMAN_FIELDS], error: 'the form is empty' };
+  }
+  const lines = text.split(/\r?\n/);
+
+  const scalar = (label) => {
+    const re = new RegExp(`^${label}:\\s*(.*)$`, 'i');
+    for (const line of lines) {
+      const m = line.match(re);
+      if (m) return m[1].trim();
+    }
+    return null;
+  };
+
+  const section = (heading) => {
+    const start = lines.findIndex((line) => line.trim().toLowerCase() === `## ${heading}`.toLowerCase());
+    if (start < 0) return null;
+    const body = [];
+    for (let i = start + 1; i < lines.length; i += 1) {
+      if (/^##\s/.test(lines[i]) || /^---\s*$/.test(lines[i])) break;
+      body.push(lines[i]);
+    }
+    return body.join('\n').trim();
+  };
+
+  const form = {
+    // The epic is the form's title, so it is written once and read once. A second
+    // `Epic:` line would be a copy that can disagree with the heading.
+    epic: (text.match(/^#\s*Human Acceptance:\s*(.+)$/m) || [])[1]?.trim() || null,
+    acceptor: scalar('Accepted by'),
+    date: scalar('Date'),
+    files: scalar('Files'),
+    environment: scalar('Environment'),
+    scopeReviewed: section('Scope reviewed'),
+    witness: section('Witness'),
+    limitations: section('Accepted limitations'),
+  };
+
+  const incomplete = ACCEPTANCE_HUMAN_FIELDS.filter((field) => isUnfilled(form[field]));
+  if (isUnfilled(form.epic)) incomplete.push('epic');
+
+  const fileList = (form.files || '')
+    .split(',')
+    .map((f) => f.trim().replace(/\\/g, '/'))
+    .filter((f) => f && !f.startsWith('('))
+    .filter((f) => !isUnfilled(f));
+
+  return { ...form, fileList, incomplete };
+}
+
+/** Write the form, create-only: a half-filled form is never overwritten. */
+export function writeAcceptanceForm(targetDir, epicId, text, { out = null } = {}) {
+  const path = out || acceptanceFormPath(targetDir, epicId);
+  if (existsSync(path)) {
+    return { written: false, path, reason: 'a form already exists; edit it and record it, or move it aside to regenerate' };
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text);
+  return { written: true, path };
+}

package/src/harness/architecture.mjs

@@ -0,0 +1,201 @@
+/**
+ * Architecture fitness — executable constraints, and the line between them and a review.
+ *
+ * A project declares checks: dependency direction, a forbidden reference, a layer that may
+ * not import another. Each check is a command with a stable id, the files it governs, a
+ * severity, and optionally an artifact it must write. This module answers the three
+ * questions the gate needs:
+ *
+ *   1. which checks apply to the files that changed (`applicableChecks`);
+ *   2. what each applicable check proved (`runArchitectureChecks`);
+ *   3. does the set of results satisfy the gate (`summariseChecks`).
+ *
+ * What it deliberately does NOT do: decide whether the architecture is good. A command can
+ * prove that `using UnityEngine` is absent from a core assembly; it cannot prove the assembly
+ * was a good idea. That question belongs to `designReviewCompleted`, and the two gates are
+ * separate so that neither claim borrows the other's credibility.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { runCommand } from './verification.mjs';
+import { sha256 } from './util.mjs';
+
+/** Default time a single check may run, when the check declares none. */
+export const DEFAULT_CHECK_TIMEOUT_MS = 120000;
+
+/** Every outcome a single check can reach. */
+export const CHECK_STATUSES = Object.freeze(['passed', 'failed', 'blocked']);
+
+const normalise = (path) => String(path).replace(/\\/g, '/').replace(/^\.\//, '');
+
+/**
+ * Does a scope govern a path? Compared at a directory boundary.
+ *
+ * `src/Core` governs `src/Core/EnemyGrid.cs` and does NOT govern `src/CoreX/Other.cs`. A
+ * plain `startsWith` would say yes to the second, and a check that silently governs the
+ * wrong directory is worse than one that governs nothing: it reports a pass for files it
+ * never looked at.
+ */
+export function scopeMatches(scope, path) {
+  const prefix = normalise(scope).replace(/\/+$/, '');
+  const target = normalise(path);
+  return target === prefix || target.startsWith(`${prefix}/`);
+}
+
+/**
+ * The checks that apply to a set of files, and the ones that do not.
+ *
+ * A check with no `files` always applies: it is a constraint on the repository rather than
+ * on a directory. A check with scopes applies when any relevant file is under one of them.
+ */
+export function applicableChecks(checks = [], relevantFiles = []) {
+  const applicable = [];
+  const skipped = [];
+  for (const check of checks) {
+    const scopes = Array.isArray(check?.files) ? check.files : [];
+    const applies = scopes.length === 0 || relevantFiles.some((file) => scopes.some((scope) => scopeMatches(scope, file)));
+    (applies ? applicable : skipped).push(check);
+  }
+  return { applicable, skipped };
+}
+
+/**
+ * Run the applicable checks and classify each outcome.
+ *
+ * The classification matters more than the runner:
+ *
+ *   - `failed` — the check ran and reported a violation (non-zero exit).
+ *   - `blocked` — the check never completed: it timed out, it never launched, or it
+ *     declared an artifact it did not write (or wrote unparseable JSON into). A blocked
+ *     REQUIRED check does not satisfy the gate, and it is not a red: nothing was disproved.
+ *     The framework draws the same line for `harness verify`, and drawing it the other way
+ *     here would report a green tree as broken and a broken check as green.
+ */
+export async function runArchitectureChecks({
+  checks = [],
+  relevantFiles = [],
+  rootDir = process.cwd(),
+  defaultTimeoutMs = DEFAULT_CHECK_TIMEOUT_MS,
+  runCommandImpl = runCommand,
+  evidenceDir = null,
+} = {}) {
+  const { applicable, skipped } = applicableChecks(checks, relevantFiles);
+  const results = [];
+
+  for (const check of applicable) {
+    const timeoutMs = check.timeoutMs ?? defaultTimeoutMs;
+    const run = await runCommandImpl(check.command, {
+      cwd: resolve(rootDir, check.cwd || '.'),
+      timeoutMs,
+      maxInlineBytes: 16000,
+      previewBytes: 2000,
+      artifactDir: evidenceDir,
+    });
+
+    let status = 'passed';
+    let reason = null;
+    if (run.timedOut) {
+      status = 'blocked';
+      reason = `timed out after ${timeoutMs}ms`;
+    } else if (run.launchFailed) {
+      status = 'blocked';
+      reason = `the command never launched (${run.launchFailureReason || 'unknown reason'})`;
+    } else if (run.exitCode !== 0) {
+      status = 'failed';
+      reason = `exit ${run.exitCode}`;
+    }
+
+    let artifactPath = null;
+    let artifactHash = null;
+    if (check.artifact) {
+      const absolute = resolve(rootDir, check.artifact);
+      if (!existsSync(absolute)) {
+        status = status === 'passed' ? 'blocked' : status;
+        reason = `${reason ? `${reason}; ` : ''}the check declared an artifact at ${check.artifact} and wrote none`;
+      } else {
+        const text = readFileSync(absolute, 'utf-8');
+        artifactPath = normalise(check.artifact);
+        artifactHash = sha256(text);
+        if (check.artifactFormat === 'json') {
+          try {
+            JSON.parse(text);
+          } catch (err) {
+            status = status === 'passed' ? 'blocked' : status;
+            reason = `${reason ? `${reason}; ` : ''}the artifact is not valid JSON (${err.message})`;
+          }
+        }
+      }
+    }
+
+    results.push({
+      id: check.id,
+      severity: check.severity || 'required',
+      status,
+      command: check.command,
+      cwd: check.cwd || '.',
+      exitCode: run.exitCode ?? null,
+      reason,
+      durationMs: run.durationMs ?? null,
+      artifactPath,
+      artifactHash,
+      refs: [...(check.refs || [])],
+    });
+  }
+
+  return { results, skipped: skipped.map((c) => c.id) };
+}
+
+/**
+ * The verdict: does this set of results satisfy the gate?
+ *
+ * A required check that failed or was blocked does not. An advisory check that failed does
+ * not block the gate — that is what advisory means — but it is reported in the summary and
+ * written into the record, because an advisory result nobody reads is the same as no check
+ * at all.
+ */
+export function summariseChecks(results = [], { declared = 0, skipped = [] } = {}) {
+  const byId = (status, severity) => results
+    .filter((r) => r.status === status && (severity === undefined || r.severity === severity))
+    .map((r) => r.id);
+
+  const failed = byId('failed', 'required');
+  const blocked = byId('blocked', 'required');
+  const advisoryFailed = [...byId('failed', 'advisory'), ...byId('blocked', 'advisory')];
+  const passed = byId('passed');
+
+  const notes = [];
+  if (results.length === 0) {
+    notes.push(declared === 0
+      ? 'the project declares no architecture checks, so nothing was verified'
+      : `no check was applicable to the changed files (${skipped.length} declared check(s) skipped)`);
+  }
+  if (advisoryFailed.length > 0) {
+    notes.push(`advisory check(s) did not pass and do not block: ${advisoryFailed.join(', ')}`);
+  }
+  if (blocked.length > 0) {
+    notes.push(`required check(s) could not complete: ${blocked.join(', ')}`);
+  }
+
+  return {
+    gatePassed: failed.length === 0 && blocked.length === 0,
+    passed,
+    failed,
+    blocked,
+    advisoryFailed,
+    skipped,
+    note: notes.join('; '),
+  };
+}
+
+/** A one-line-per-check reading for a human, and for `describe*`-style refusals. */
+export function describeCheckResults(results = [], summary = null) {
+  const lines = results.map((r) => {
+    const mark = r.status === 'passed' ? '✅' : r.status === 'failed' ? '❌' : '⚠️';
+    const refs = r.refs?.length ? ` (${r.refs.join(', ')})` : '';
+    return `  ${mark} ${r.id} [${r.severity}] ${r.status}${r.reason ? ` — ${r.reason}` : ''}${refs}`;
+  });
+  if (summary?.skipped?.length) lines.push(`  ⏭  skipped, not applicable: ${summary.skipped.join(', ')}`);
+  return lines;
+}

package/src/harness/commands.mjs

@@ -128,10 +128,62 @@ export const COMMANDS = {
     writes: ['.cadet/runs/**', '.cadet/state.json'],
     unattended: true,
   },
+  'harness verify-design-review': {
+    mutates: true,
+    summary: 'Check the design-review artifact and record designReviewCompleted.',
+    // Like verify-acs and verify-reachability: it records evidence for its gate, so it
+    // writes the ledger and state. The artifact itself is the reviewer's, and this
+    // command never writes it — a check that authored the thing it checks would prove
+    // nothing.
+    writes: ['.cadet/runs/**', '.cadet/state.json'],
+    unattended: true,
+  },
+  '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'],
+    unattended: true,
+  },
+  'harness context record': {
+    mutates: true,
+    summary: 'Record what the host loaded, and the level it can claim for that record.',
+    writes: ['.cadet/context/record.json'],
+    unattended: true,
+  },
+  'harness context validate': {
+    mutates: false,
+    summary: 'Compare the plan, the record and the files as they are now. Read-only.',
+    unattended: true,
+  },
+  'harness verify-architecture': {
+    mutates: true,
+    summary: 'Run the project\'s declared architecture checks and record the gate.',
+    // Same posture as verify-acs, verify-reachability and verify-design-review: it
+    // records evidence for its gate, so it writes the ledger and state. The checks
+    // themselves are the project's, declared in the policy — this command never writes
+    // them, and it accepts no command-line override of what they run.
+    writes: ['.cadet/runs/**', '.cadet/state.json'],
+    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.',
   },
+  // The health line: the framework's entire per-reply output. Read-only, and it
+  // writes no ledger, so printing it cannot change the state it reports on.
+  'harness status': {
+    mutates: false,
+    summary: 'Print the one-line framework health line: ok, or the problem.',
+  },
   'harness changes': {
     mutates: false,
     summary: 'List the files a story changed, with status, line counts, and links.',
@@ -191,6 +243,14 @@ export function resolveCommand(argv) {
   if (top === 'state' || top === 'harness') {
     const sub = argv[3];
     if (!sub || sub.startsWith('-')) return null;
+    // Longest key first: `harness context validate` must resolve to its own entry — a read —
+    // rather than to the group entry that also covers the two commands that write. Otherwise a
+    // read-only command would inherit the group's write declaration and lose its guard.
+    const action = argv[4] && !argv[4].startsWith('-') ? argv[4] : null;
+    if (action) {
+      const nested = `${top} ${sub} ${action}`;
+      if (Object.hasOwn(COMMANDS, nested)) return nested;
+    }
     const key = `${top} ${sub}`;
     return Object.hasOwn(COMMANDS, key) ? key : null;
   }