cadet-agent 0.60.0 → 0.63.1

package/src/harness/acceptance-form.mjs

@@ -1,281 +0,0 @@
-/**
- * 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/play-form.mjs

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