gcf-aif-ext 0.3.0 → 0.4.0

package/lib/verdict-fs.js

@@ -1,14 +1,13 @@
-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 { parseBlocks, itemsOf, readRecords } from 'cnlp-kit';
 import { 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';
-import { operationInProgress, commitPaths, dirtyPaths } from './git.js';
-import { blockLines, upsertBlock, openSystemDoc } from './systems-doc.js';
+import { atomicWrite, resolveInside } from './safe-path.js';
+import { blockLines, upsertBlock, removeLines, openSystemDoc } from './systems-doc.js';
 
 const ENVELOPE = /^\S+\.\.\S+ /;
 const real = (lines) => lines.filter((l) => !/^- none\b/.test(l));
@@ -37,9 +36,10 @@ function rateLines(body, out) {
 }
 
 /**
- * Card → systems-doc lines by the fixed map (GCF-PRD §8.2). Deterministic: a record becomes
+ * 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.
+ * `[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[]>} */
@@ -63,47 +63,70 @@ export function collapseLines(body) {
   return out;
 }
 
-/** 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)',
-    );
+/**
+ * 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`));
+
+/** 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);
   }
 
-  return card;
+  await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: item.data.id }, body));
 }
 
-function planTune({ card, note }) {
-  return async () => {
-    const data = { ...card.data, status: 'tuning', tune_count: (card.data.tune_count ?? 0) + 1 };
-    // The remark goes to `tuning:`, the block the agent reads before the rebuild.
-    const body = note ? upsertBlock(card.body, 'tuning', [`- ${note}`]) : card.body;
-    await atomicWrite(card.file, serialize(data, body));
-  };
+/**
+ * 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 [section, lines] of Object.entries(collapseLines(item.body))) {
+    body = removeLines(
+      body,
+      section,
+      lines.filter((l) => !keep.includes(l)),
+    );
+  }
+
+  await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: item.data.id }, body));
 }
 
-/** The graveyard line of a killed or dropped unit: `- <id> | <reason> | tags: <tags>`. */
-export async function buryLine(root, id, reason, tags) {
+export const GRAVEYARD_HEAD =
+  '# Graveyard — `- <id> | <type> | <reason> | tags: <tags>`, one line per idea or piece of ' +
+  'work killed, dropped or refused\n';
+
+/** 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') : '';
-  const line = `- ${id} | ${reason || 'no reason recorded'} | tags: ${tags.join(', ')}\n`;
-  await atomicWrite(gyFile, existing + line);
+  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);
 }
 
 export const HISTORY_HEAD =
-  '# History — `- <id> | done|collapsed | <date>`, one line per unit built (gcf done) or ' +
-  'card kept by a verdict; the move writes it in the commit that ends the life\n';
+  '# 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 history line of a unit built (`done`) or a card kept (`collapsed`). 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.
+ * 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 recordLine(root, id, event, date = new Date().toISOString().slice(0, 10)) {
   const file = path.join(root, 'history.md');
@@ -115,93 +138,3 @@ export async function recordLine(root, id, event, date = new Date().toISOString(
   lines.splice(at < 0 ? lines.length : at, 0, `- ${id} | ${event} | ${date}`);
   await atomicWrite(file, `${lines.join(eol)}${eol}`);
 }
-
-function planKill({ root, card, cardId, note, tags, systems, touched }) {
-  touched.push(path.join(root, 'graveyard.md'));
-
-  return async () => {
-    await buryLine(root, cardId, note, tags.length ? tags : systems);
-    await unlink(card.file);
-  };
-}
-
-/** Merge the card into one systems doc; a new doc starts from design/'s purpose. */
-async function mergeIntoSystem(root, system, card, cardId) {
-  const doc = await openSystemDoc(root, system);
-  let body = doc.body;
-  for (const [section, lines] of Object.entries(collapseLines(card.body))) {
-    body = upsertBlock(body, section, lines);
-  }
-
-  await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: cardId }, 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, path.join(root, 'history.md'));
-
-  return async () => {
-    for (const s of systems) await mergeIntoSystem(root, s, card, cardId);
-    await recordLine(root, cardId, 'collapsed');
-    await unlink(card.file);
-  };
-}
-
-const PLANS = { tune: planTune, kill: planKill, keep: planKeep };
-
-/**
- * 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 and writes the history line; `kill` writes the graveyard line; `tune`
- * bumps the counter and
- * appends the human note to the `tuning` block.
- *
- * 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.
- */
-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 });
-  // The commit takes whole files: a user's own uncommitted edit in a systems doc or the
-  // graveyard would ride along unseen. The card is the verdict's input and may be dirty.
-  const others = touched.filter((f) => f !== card.file && path.basename(f) !== 'INDEX.md');
-  const dirty = commit ? dirtyPaths(projectDir, others) : [];
-  if (dirty.length)
-    throw new Error(
-      `commit or stash these first, the verdict would carry them: ${dirty.join('; ')}`,
-    );
-
-  const message = `gcf(verdict): ${verdict} ${cardId} → ${systems.join(',')}`;
-  /** @type {string | null} */
-  let hash = null;
-  await withFileRollback(
-    touched,
-    async () => {
-      await mutate();
-      await writeIndex(root);
-      if (commit) hash = commitPaths(projectDir, message, touched);
-    },
-    { gitCwd: commit ? path.resolve(projectDir) : null },
-  );
-
-  return { verdict, card: cardId, systems, hash };
-}