gcf-aif-ext 0.2.7 → 0.4.0

package/lib/verdict-fs.js

@@ -1,193 +1,140 @@
-import { readFile, unlink } from 'node:fs/promises';
+// The writes that end or collapse a work item (Methodology §4.1, §9): an item's slots into its
+// systems docs and back out, the history line, the graveyard line. The moves themselves live in
+// work-ops.js; these are the deterministic pieces they share.
+import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { parse, serialize } from './frontmatter.js';
-import { listCards } from './gcf-paths.js';
-import { atomicWrite, resolveInside, withFileRollback } from './safe-path.js';
-import { writeIndex } from './index-gen.js';
-import { isLegal } from './transitions.js';
-
-// Slot → systems-doc section map (GCF-PRD §8.2). Deterministic merge: lines are
-// carried verbatim and deduplicated; the LLM compression of `behavior` happens in the
-// card BEFORE the verdict (the skill edits the card), not here.
-const MERGE_MAP = [
-  ['behavior', 'behavior'],
-  ['contract', 'code'],
-  ['feel', 'feel'],
-  ['constraints', 'constraints'],
-];
-
-function blockLines(body, key) {
-  const m = String(body).match(new RegExp(`^${key}:\\s*\\n((?:- .*\\n?)*)`, 'm'));
-
-  return m ? m[1].split('\n').filter((l) => l.startsWith('- ')) : [];
-}
+import { parseBlocks, itemsOf, readRecords } from 'cnlp-kit';
+import { serialize } from './frontmatter.js';
+import { atomicWrite, resolveInside } from './safe-path.js';
+import { blockLines, upsertBlock, removeLines, openSystemDoc } from './systems-doc.js';
 
-function upsertBlock(body, key, addLines) {
-  if (!addLines.length) return body;
-  const existing = new Set(blockLines(body, key));
-  const fresh = addLines.filter((l) => !existing.has(l));
-  if (!fresh.length) return body;
-  const re = new RegExp(`(^${key}:\\s*\\n(?:- .*\\n?)*)`, 'm');
-  if (re.test(body))
-    return body.replace(
-      re,
-      (blk) => `${blk.endsWith('\n') ? blk : `${blk}\n`}${fresh.join('\n')}\n`,
-    );
+const ENVELOPE = /^\S+\.\.\S+ /;
+const real = (lines) => lines.filter((l) => !/^- none\b/.test(l));
 
-  return `${body.trimEnd()}\n\n${key}:\n${fresh.join('\n')}\n`;
-}
+function recordsOf(body, key) {
+  const { lines, sections } = parseBlocks(body);
+  const at = sections.find((s) => s.key === key && !s.value);
 
-// `git commit --only <paths>` is a partial commit, which git refuses outright while a merge
-// or a sequencer operation is in progress. Detect it up front so the failure has a reason.
-const IN_PROGRESS = [
-  'MERGE_HEAD',
-  'CHERRY_PICK_HEAD',
-  'REVERT_HEAD',
-  'rebase-merge',
-  'rebase-apply',
-];
-function operationInProgress(projectDir) {
-  const gitDir = spawnSync('git', ['rev-parse', '--git-dir'], {
-    cwd: projectDir,
-    encoding: 'utf8',
-  });
-  if (gitDir.status !== 0) return null;
-  const dir = path.resolve(projectDir, gitDir.stdout.trim());
-
-  return IN_PROGRESS.find((name) => existsSync(path.join(dir, name))) ?? null;
+  return at ? readRecords(itemsOf(lines, at.line)).records.map((r) => r.values) : [];
 }
 
-function gitCommit(projectDir, message, addPaths) {
-  // Stage and commit exactly the files this verdict touched: `git add -- gcf/` would stage a
-  // user's unrelated edits under gcf/, and rollback only restores what it snapshotted.
-  for (const p of addPaths)
-    spawnSync('git', ['add', '--', p], { cwd: projectDir, stdio: 'ignore' });
-  const res = spawnSync('git', ['commit', '-m', message, '--only', '--', ...addPaths], {
-    cwd: projectDir,
-    encoding: 'utf8',
-  });
-  if (res.status !== 0) throw new Error(`verdict commit failed: ${res.stderr || res.stdout}`);
-
-  return spawnSync('git', ['rev-parse', 'HEAD'], {
-    cwd: projectDir,
-    encoding: 'utf8',
-  }).stdout.trim();
+const scalar = (body, key) => parseBlocks(body).sections.find((s) => s.key === key)?.value ?? '';
+
+/** A resource rate: an envelope is a range of intent (feel), a comparison is exact (constraint). */
+function rateLines(body, out) {
+  for (const [key, word] of [
+    ['sources', 'source'],
+    ['sinks', 'sink'],
+  ]) {
+    for (const r of recordsOf(body, key)) {
+      out.behavior.push(`- ${word} ${r.name}`);
+      if (ENVELOPE.test(`${r.rate} `)) out.feel.push(`- ${r.name} rate ${r.rate}`);
+      else out.constraints.push(`- ${r.rate}`);
+    }
+  }
 }
 
-/** Find the card and refuse an unknown verdict or a transition the lifecycle forbids. */
-async function findVerdictCard(root, cardId, verdict) {
-  const card = (await listCards(root)).find((c) => c.data.id === cardId);
-  if (!card) throw new Error(`Card not found: ${cardId}`);
-  const target = { keep: 'validated', tune: 'tuning', kill: 'killed' }[verdict];
-  if (!target) throw new Error(`Unknown verdict: ${verdict}`);
-  if (!isLegal(card.data.status, target)) {
-    throw new Error(
-      `Illegal transition ${card.data.status} -> ${target} for ${cardId} ` +
-        '(verdict needs status=built)',
-    );
+/**
+ * Item → systems-doc lines by the fixed map (GCF-PRD §8.2). Deterministic: a record becomes
+ * one line, a bullet stays itself, `- none:` placeholders carry nothing. A line keeps its
+ * `[until: …]` and stays in its own section, where the reader who needs it looks. Being a pure
+ * function of the body is what lets an unplayed item's lines be taken back out (§5.4).
+ */
+export function collapseLines(body) {
+  /** @type {Record<string, string[]>} */
+  const out = { purpose: [], code: [], behavior: [], feel: [], constraints: [] };
+  out.purpose.push(...real(blockLines(body, 'intent')));
+  for (const r of recordsOf(body, 'behavior')) {
+    out.behavior.push(`- ${r.input} -> ${r.state} -> ${r.feedback}`);
   }
 
-  return card;
+  out.behavior.push(...real(blockLines(body, 'refusal')), ...real(blockLines(body, 'boundaries')));
+  const persistence = scalar(body, 'persistence');
+  if (persistence && !/^none\b/.test(persistence)) out.behavior.push(`- persists: ${persistence}`);
+  rateLines(body, out);
+  const like = scalar(body, 'feel_like');
+  if (like) out.feel.push(`- ${like}`);
+  for (const r of recordsOf(body, 'feel')) out.feel.push(`- ${r.name} ${r.envelope}`);
+  out.code.push(...real(blockLines(body, 'contract')));
+  out.constraints.push(...real(blockLines(body, 'constraints')));
+  out.constraints.push(...real(blockLines(body, 'interactions')));
+
+  return out;
 }
 
-function planTune({ card, note }) {
-  return async () => {
-    const data = { ...card.data, status: 'tuning', tune_count: (card.data.tune_count ?? 0) + 1 };
-    const body = note ? upsertBlock(card.body, 'feel', [`- retune: ${note}`]) : card.body;
-    await atomicWrite(card.file, serialize(data, body));
-  };
-}
+/**
+ * The systems doc files an item writes. `system:` names files, and the pre-commit gate validates
+ * it only after they are written: `../../x` would already have overwritten a file outside gcf/.
+ */
+export const systemFiles = (root, systems) =>
+  systems.map((s) => resolveInside(path.join(root, 'systems'), `${s}.md`));
 
-function planKill({ root, card, cardId, note, tags, systems, touched }) {
-  const gyFile = path.join(root, 'graveyard.md');
-  touched.push(gyFile);
-
-  return async () => {
-    const reason = note || 'no reason recorded';
-    const tagStr = (tags.length ? tags : systems).join(', ');
-    const line = `- ${cardId} | ${card.data.slug} | ${reason} | tags: ${tagStr}\n`;
-    const existing = existsSync(gyFile) ? await readFile(gyFile, 'utf8') : '';
-    await atomicWrite(gyFile, existing + line);
-    await unlink(card.file);
-  };
+/** Merge the item's lines into one systems doc; a new doc starts from design/'s purpose. */
+export async function mergeIntoSystem(root, system, item) {
+  const doc = await openSystemDoc(root, system);
+  let body = doc.body;
+  for (const [section, lines] of Object.entries(collapseLines(item.body))) {
+    body = upsertBlock(body, section, lines);
+  }
+
+  await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: item.data.id }, body));
 }
 
-async function mergeIntoSystem(sysFile, system, card, cardId) {
-  let doc = existsSync(sysFile)
-    ? parse(await readFile(sysFile, 'utf8'))
-    : { data: { system }, body: 'purpose:\n- (fill in)\n' };
+/**
+ * Take an unplayed item's lines back out of a systems doc (tune, kill or drop of an unplayed
+ * item). `keep` are lines other unplayed items still owe the doc. shortcut: a line shared word
+ * for word with an already kept item leaves too — that body is gone; upgrade to per-line origin
+ * marks if that ever bites.
+ */
+export async function unmergeFromSystem(root, system, item, keep = []) {
+  const file = path.join(root, 'systems', `${system}.md`);
+  if (!existsSync(file)) return;
+  const doc = await openSystemDoc(root, system);
   let body = doc.body;
-  for (const [slot, section] of MERGE_MAP) {
-    body = upsertBlock(body, section, blockLines(card.body, slot));
+  for (const [section, lines] of Object.entries(collapseLines(item.body))) {
+    body = removeLines(
+      body,
+      section,
+      lines.filter((l) => !keep.includes(l)),
+    );
   }
 
-  // Lines with a live until: move to `open` (GCF-PRD §8.2.5).
-  const openLines = blockLines(card.body, 'interactions').filter((l) => l.includes('[until:'));
-  body = upsertBlock(body, 'open', openLines);
-  await atomicWrite(sysFile, serialize({ ...doc.data, updated_by: cardId }, body));
+  await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: item.data.id }, body));
 }
 
-function planKeep({ root, card, cardId, systems, touched }) {
-  // `system:` names files, and the pre-commit gate validates it only after they are written:
-  // `../../x` would already have overwritten a file outside gcf/.
-  const sysFiles = systems.map((s) => resolveInside(path.join(root, 'systems'), `${s}.md`));
-  touched.push(...sysFiles);
+export const GRAVEYARD_HEAD =
+  '# Graveyard — `- <id> | <type> | <reason> | tags: <tags>`, one line per idea or piece of ' +
+  'work killed, dropped or refused\n';
 
-  return async () => {
-    for (const [i, sysFile] of sysFiles.entries()) {
-      await mergeIntoSystem(sysFile, systems[i], card, cardId);
-    }
-
-    await unlink(card.file);
-  };
+/** The graveyard line of an id that ended without a keep: `- <id> | <type> | <reason> | tags:`. */
+export async function buryLine(root, id, { type, reason, tags }) {
+  const gyFile = path.join(root, 'graveyard.md');
+  const existing = existsSync(gyFile) ? await readFile(gyFile, 'utf8') : GRAVEYARD_HEAD;
+  // A hand-edited file may end without a newline: the line would glue onto the last one.
+  const eol = existing.match(/\r?\n/)?.[0] ?? '\n';
+  const head = existing && !existing.endsWith('\n') ? existing + eol : existing;
+  const why = String(reason || 'no reason recorded').replace(/\s*\|\s*/g, '; ');
+  const line = `- ${id} | ${type} | ${why} | tags: ${tags.join(', ')}${eol}`;
+  await atomicWrite(gyFile, head + line);
 }
 
-const PLANS = { tune: planTune, kill: planKill, keep: planKeep };
+export const HISTORY_HEAD =
+  '# History — `- <id> | done|collapsed|decided | <date>`, one line per item or unit that ' +
+  'ended accepted; the move writes it in the commit that ends the life\n';
 
 /**
- * The one operation that collapses a card (GCF-PRD §8). Atomic: file changes roll back
- * on failure; the verdict commit has the fixed greppable format. `keep` merges into every
- * touched systems doc; `kill` writes the graveyard line; `tune` bumps the counter and
- * appends the human note to the feel slot.
- *
- * The commit runs INSIDE the rollback: it fires the pre-commit gate, which can reject the
- * merged systems doc, and a card unlinked by a commit that never landed is a lost card.
+ * The history line of an id that ended accepted (`done`, `collapsed`, `decided`). It goes in id
+ * order, not at the end: branches recording different ids touch different places of the file
+ * and merge cleanly, and a revert of the move takes out exactly its line.
  */
-export async function applyVerdict(
-  projectDir,
-  cardId,
-  verdict,
-  { note = '', tags = [], commit = true } = {},
-) {
-  const root = path.join(path.resolve(projectDir), 'gcf');
-  const card = await findVerdictCard(root, cardId, verdict);
-
-  // Before any write: refusing after the files changed would send a failed commit through the
-  // rollback, and restoring a conflicted index entry marks the conflict resolved.
-  const busy = commit ? operationInProgress(projectDir) : null;
-  if (busy)
-    throw new Error(
-      `cannot record a verdict while ${busy} is in progress — finish or abort it first`,
-    );
-
-  const touched = [card.file, path.join(root, 'INDEX.md')];
-  const systems = card.data.system ?? [];
-  const mutate = PLANS[verdict]({ root, card, cardId, note, tags, systems, touched });
-
-  const message = `gcf(verdict): ${verdict} ${cardId} ${card.data.slug} → ${systems.join(',')}`;
-  /** @type {string | null} */
-  let hash = null;
-  await withFileRollback(
-    touched,
-    async () => {
-      await mutate();
-      await writeIndex(root);
-      if (commit) hash = gitCommit(projectDir, message, touched);
-    },
-    { gitCwd: commit ? path.resolve(projectDir) : null },
-  );
-
-  return { verdict, card: cardId, systems, hash };
+export async function recordLine(root, id, event, date = new Date().toISOString().slice(0, 10)) {
+  const file = path.join(root, 'history.md');
+  const old = existsSync(file) ? await readFile(file, 'utf8') : '';
+  // A file kept with CRLF stays CRLF; an empty one starts from the header.
+  const eol = old.includes('\r\n') ? '\r\n' : '\n';
+  const lines = (old.trim() ? old : HISTORY_HEAD).replace(/\s+$/, '').split(/\r?\n/);
+  const at = lines.findIndex((l) => (l.match(/^- (\S+) \|/)?.[1] ?? '') > id);
+  lines.splice(at < 0 ? lines.length : at, 0, `- ${id} | ${event} | ${date}`);
+  await atomicWrite(file, `${lines.join(eol)}${eol}`);
 }