gcf-aif-ext 0.3.0 → 0.4.1

package/lib/design-check.js

@@ -18,6 +18,7 @@ import {
 } from './design.js';
 import { buildLedger } from './ledger.js';
 import { sourceBodies } from './anchors.js';
+import { collapseLines } from './verdict-fs.js';
 
 // Units a number may carry. A project adds its own in the `units:` block of glossary.md.
 // Bare `px` is absent on purpose: its size depends on the screen density.
@@ -34,6 +35,7 @@ const COMPARISON_RE = new RegExp(
     '(?:\\s+(\\S+)(?: per \\S+)?)?$', //                      and its unit, closing the line
 );
 const ENVELOPE_BLOCKS = ['feel', 'sources', 'sinks'];
+const OPERATOR_BLOCKS = ['tuning', 'notes'];
 const FLAGS = ['src-changed', 'orphan', 'impl?'];
 const REQUIRED_HEADER = ['type', 'route', 'system', 'milestone', 'pillars', 'depends', 'source'];
 const ws = (t) => String(t).replace(/\s+/g, ' ').trim();
@@ -116,7 +118,8 @@ function itemsIn(text, key) {
   return at ? itemsOf(lines, at.line) : [];
 }
 
-const recordsIn = (text, key) => readRecords(itemsIn(text, key)).records.map((r) => r.values);
+export const recordsIn = (text, key) =>
+  readRecords(itemsIn(text, key)).records.map((r) => r.values);
 
 /** `blocks:` of open-questions.md: every reference, and the D1 ones per blocked id. */
 export function questionBlocks(text) {
@@ -172,9 +175,14 @@ const HEADER_RULES = {
 
     return [
       'M1',
-      `a ${u.header.type} is ${soft ? 'soft' : 'hard'}: only mechanic and resource get a card`,
+      `a ${u.header.type} is ${soft ? 'soft' : 'hard'}: only mechanic and resource wait for a ` +
+        'verdict by default',
     ];
   },
+  reopens: (v, u, ctx, ledger) =>
+    ledger.where(v).terminal.length
+      ? null
+      : ['M2', `reopens names ${v}, which has not ended (no history or graveyard line)`],
   system: (v, u) => {
     const list = listOf(v);
     if (list === 'TBD' || !list.length || !list.every((s) => SLUG_RE.test(s)))
@@ -400,36 +408,84 @@ function preambleIssues(design) {
     }));
 }
 
+/** M2 over a work item's references: depends, parent, children, reopens. */
+function itemRefIssues(item, ledger, add) {
+  const d = item.data;
+  const unknown = (d.depends ?? []).filter((x) => x === d.id || !ledger.known(x));
+  if (unknown.length) add('M2', 1, `depends on unknown ${unknown.join(', ')}`);
+  // A parent that already ended is fine: a parked bug may outlive its feature.
+  const parent = d.parent ? ledger.item(d.parent) : null;
+  if (d.parent && !(parent ? parent.data.type === 'feature' : ledger.known(d.parent)))
+    add('M2', 1, `parent ${d.parent} is neither a feature item nor an ended id`);
+  const lost = (d.children ?? []).filter((c) => !ledger.known(c));
+  if (lost.length) add('M2', 1, `children unknown: ${lost.join(', ')}`);
+  if (d.reopens && !ledger.where(d.reopens).terminal.length)
+    add('M2', 1, `reopens names ${d.reopens}, which has not ended (no history or graveyard line)`);
+}
+
 /**
- * A card is a unit in work: the same profile, plus what the card stage owes — no TBD left,
- * `contract` and `interactions` written. Its frontmatter is validated by the schema separately.
+ * A work item. A design-unit item carries the unit's body: the same profile, plus what work
+ * owes — no TBD left, `contract` and `interactions` written. Every item's references are known.
+ * Its frontmatter is validated by the schema separately.
  */
-async function checkCard(card, ctx) {
+async function checkItem(item, ctx, ledger) {
   /** @type {Issue[]} */
   const issues = [];
-  const file = `cards/${card.name}`;
-  const raw = await readFile(card.file, 'utf8');
-  const offset = raw.split('\n').length - card.body.split('\n').length;
+  const file = `work/${item.name}`;
+  const raw = await readFile(item.file, 'utf8');
+  const offset = raw.split('\n').length - item.body.split('\n').length;
   const add = (check, line, message, severity = 'block') =>
-    issues.push({ check, severity, file, line: line + offset, id: card.data.id, message });
-  if (!CARD_TYPES.includes(card.data.type)) return issues;
+    issues.push({ check, severity, file, line: line + offset, id: item.data.id, message });
+  itemRefIssues(item, ledger, add);
+  if (!UNIT_TYPES.includes(item.data.type)) return issues;
 
-  const { profile, issues: shape } = await bodyProblems(card.body, card.data.type);
+  const { profile, issues: shape } = await bodyProblems(item.body, item.data.type);
   for (const i of shape) add('M1', i.line, i.message);
-  const values = slotValues(card.body, profile);
+  // `tuning:` and `notes:` are the operator's words to the next build, not design slots: a
+  // "dash 20% shorter" there is a remark, not a number outside an envelope.
+  const values = slotValues(item.body, profile).filter((v) => !OPERATOR_BLOCKS.includes(v.block));
   for (const v of values.filter((x) => isTbd(x.value)))
-    add('M1', v.line, `a card carries no TBD: ${v.block}`);
+    add('M1', v.line, `a unit in work carries no TBD: ${v.block}`);
   for (const [c, line, m] of valueIssues(values, ctx)) add(c, line, m);
-  for (const r of provenanceOf(card.body)) {
+  for (const r of provenanceOf(item.body)) {
     const problem = recordProblem(r, ctx);
-    // A card's quotes go stale when the GDD moves on: that is a D1 for the human, not a gate.
+    // An item's quotes go stale when the GDD moves on: that is a D1 for the human, not a gate.
     if (problem) add('M9', r.line, problem, isDrift(problem) ? 'report' : 'block');
   }
 
   return issues;
 }
 
-/** M12: one live place per id, and no silent return from a terminal state. */
+/**
+ * M15: an unplayed item's lines are all in its systems docs — the body is what a tune or a kill
+ * takes back out (Methodology §5.4), so a line edited away there could never leave.
+ */
+async function unplayedIssues(root, ledger) {
+  /** @type {Issue[]} */
+  const out = [];
+  for (const item of ledger.items.filter((i) => i.data.status === 'unplayed')) {
+    for (const s of item.data.system ?? []) {
+      const text = await readIf(path.join(root, 'systems', `${s}.md`));
+      const doc = String(text ?? '').replace(/\r\n/g, '\n');
+      const missing = Object.values(collapseLines(item.body))
+        .flat()
+        .find((l) => !doc.split('\n').includes(l));
+      if (missing)
+        out.push({
+          check: 'M15',
+          severity: 'block',
+          file: `work/${item.name}`,
+          line: 1,
+          id: item.data.id,
+          message: `unplayed ${item.data.id}: systems/${s}.md lost its line "${missing}"`,
+        });
+    }
+  }
+
+  return out;
+}
+
+/** M12: one live place per id, and no return from a terminal state — ids are never reused. */
 function ledgerIssues(ledger) {
   /** @type {Issue[]} */
   const out = [];
@@ -440,10 +496,15 @@ function ledgerIssues(ledger) {
       out.push({ check: 'M12', severity: 'block', file, line: 1, id, message });
     if (live.length > 1)
       add(`${id} lives in ${live.length} places: ${live.map((p) => p.file).join(', ')}`);
-    if (live.length && terminal.length && !reopens(ledger, id)) {
+    // An id ends once; two ends (a merge of branches that each ended it) leave its dependents
+    // counting it as played or dead depending on which line wins.
+    if (terminal.length > 1)
+      add(`${id} ended ${terminal.join(' and ')}: keep one line in history.md or graveyard.md`);
+    if (live.length && terminal.length) {
       add(
-        `${id} is ${terminal.join(' and ')} already: a live copy needs "reopens: <why>" ` +
-          '(an undone move: take its line out of history.md or graveyard.md)',
+        `${id} is ${terminal.join(' and ')} already: ids are never reused — give the new one ` +
+          `its own id and "reopens: ${id}" (an undone move: take its line out of history.md ` +
+          'or graveyard.md)',
       );
     }
   }
@@ -451,11 +512,47 @@ function ledgerIssues(ledger) {
   return out;
 }
 
-function reopens(ledger, id) {
-  const unit = ledger.design.flatMap((d) => d.units).find((u) => u.id === id);
-  const card = ledger.cards.find((c) => c.data.id === id);
+/**
+ * M2 over `depends:` of units and items together: a cycle never gets played — every id in it
+ * waits for the next one. Each cycle is reported once, from the id DFS meets it at.
+ */
+export function dependsCycles(ledger) {
+  /** @type {Map<string, string[]>} */
+  const graph = new Map();
+  for (const u of ledger.design.flatMap((d) => d.units)) {
+    const list = listOf(u.header.depends ?? '');
+    graph.set(u.id, Array.isArray(list) ? list : []);
+  }
 
-  return Boolean(unit?.header.reopens || card?.data.reopens);
+  for (const c of ledger.items) graph.set(String(c.data.id), c.data.depends ?? []);
+  /** @type {Issue[]} */
+  const out = [];
+  const state = new Map(); // id → 'open' while on the DFS path, 'done' after
+  const visit = (id, trail) => {
+    if (state.get(id) === 'done') return;
+    if (state.get(id) === 'open') {
+      const cycle = [...trail.slice(trail.indexOf(id)), id];
+      const file = ledger.where(id).live[0]?.file ?? 'design';
+      out.push({
+        check: 'M2',
+        severity: 'block',
+        file,
+        line: 1,
+        id,
+        message: `depends cycle ${cycle.join(' -> ')}: none of them can be played first`,
+      });
+
+      return;
+    }
+
+    state.set(id, 'open');
+    for (const d of graph.get(id) ?? []) visit(d, [...trail, id]);
+    state.set(id, 'done');
+  };
+
+  for (const id of graph.keys()) visit(id, []);
+
+  return out;
 }
 
 /** M14: backlog.md is the order of the units in design/, each exactly once. */
@@ -527,6 +624,31 @@ function pillarReport(units, ctx) {
   };
 }
 
+/** A unit's line in the report: its TBD count and whether it is ready to take. */
+function unitSummary(u, own, values, ctx) {
+  const pillars = listOf(u.header.pillars ?? '');
+  // Once PILLARS.md exists, a mechanic or resource says which pillar it serves before work:
+  // `take` would turn the TBD into an empty list and the unit would serve nothing silently.
+  const pillarsTbd =
+    pillars === 'TBD' && ctx.pillarIds.length && CARD_TYPES.includes(u.header.type) ? 1 : 0;
+  const tbd = values.filter((v) => isTbd(v.value)).length + pillarsTbd;
+  const blockedBy = ctx.questions.d1.get(u.id) ?? [];
+
+  return {
+    id: u.id,
+    file: u.file,
+    system: u.system,
+    type: u.header.type ?? null,
+    milestone: u.header.milestone ?? 'TBD',
+    pillars,
+    pillars_owed: Boolean(pillarsTbd),
+    values: values.length,
+    tbd,
+    blocked_by: blockedBy,
+    ready: tbd === 0 && !blockedBy.length && !own.some((i) => i.severity === 'block'),
+  };
+}
+
 /**
  * Run every design check over a project. `blocking` counts the issues that refuse a commit;
  * the rest of the report (completeness, readiness, pillars) is a reading, not a gate.
@@ -541,27 +663,14 @@ export async function designCheck(projectDir) {
   for (const u of ledger.design.flatMap((d) => d.units)) {
     const { issues: own, values } = await checkUnit(u, ctx, ledger);
     issues.push(...own);
-    const tbd = values.filter((v) => isTbd(v.value)).length;
-    const blockedBy = ctx.questions.d1.get(u.id) ?? [];
-    const pillars = listOf(u.header.pillars ?? '');
-    units.push({
-      id: u.id,
-      file: u.file,
-      system: u.system,
-      type: u.header.type ?? null,
-      milestone: u.header.milestone ?? 'TBD',
-      pillars,
-      values: values.length,
-      tbd,
-      blocked_by: blockedBy,
-      ready: tbd === 0 && !blockedBy.length && !own.some((i) => i.severity === 'block'),
-    });
+    units.push(unitSummary(u, own, values, ctx));
   }
 
-  for (const c of ledger.cards) issues.push(...(await checkCard(c, ctx)));
+  for (const c of ledger.items) issues.push(...(await checkItem(c, ctx, ledger)));
+  issues.push(...(await unplayedIssues(root, ledger)));
   for (const doc of ['game', 'glossary']) issues.push(...(await checkDoc(root, doc, ctx)));
   issues.push(...preambleIssues(ledger.design));
-  issues.push(...ledgerIssues(ledger), ...questionIssues(ctx, ledger));
+  issues.push(...ledgerIssues(ledger), ...dependsCycles(ledger), ...questionIssues(ctx, ledger));
   if (ledger.design.length) {
     const backlog = await readIf(path.join(root, 'backlog.md'));
     issues.push(...backlogIssues(backlog, new Set(units.map((u) => u.id))));

package/lib/design.js

@@ -1,5 +1,5 @@
 // Design Model (GCF-PRD §5.7): gcf/design/<system>.md holds design units, one `## <id>`
-// section each. A unit's body is the body its card carries once it is taken into work,
+// section each. A unit's body is the body its work item carries once it is taken into work,
 // so one CNL-P profile per type serves both places.
 import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
@@ -9,7 +9,7 @@ import { parseBlocks, itemsOf, readRecords, loadProfileAt } from 'cnlp-kit';
 
 export const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 export const UNIT_TYPES = ['mechanic', 'resource', 'rule', 'constraint', 'entity'];
-// Only a soft unit becomes a card; a hard one leaves design/ through `gcf done`.
+// A soft unit waits for a verdict by default; a hard one closes by its tests.
 export const CARD_TYPES = ['mechanic', 'resource'];
 export const HEADER_KEYS = [
   'type',

package/lib/gcf-paths.js

@@ -1,5 +1,5 @@
 import { readFile, readdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
 import { parse } from './frontmatter.js';
@@ -13,6 +13,9 @@ const DEFAULT_CONFIG = {
   context_budget: 30000,
   pillars_budget: 1500,
   envelope_default_spread: 0.3,
+  unplayed_warn_after: 5,
+  plan_passes: 5,
+  dod_attempts: 2,
 };
 
 /** `gcf/` lives at the repository root (GCF-PRD §5.1). Throws when absent. */
@@ -64,7 +67,15 @@ async function listDocs(dir) {
   return out;
 }
 
-export const listCards = (root) => listDocs(path.join(root, 'cards'));
+export const listItems = (root) => listDocs(path.join(root, 'work'));
+
+/** Schema 2 card files left in gcf/cards/: GCF 0.4 reads gcf/work/ and does not migrate them. */
+export function legacyCards(root) {
+  const dir = path.join(root, 'cards');
+
+  return existsSync(dir) ? readdirSync(dir).filter((n) => n.endsWith('.md')) : [];
+}
+
 export const listSystems = (root) => listDocs(path.join(root, 'systems'));
 
 /** First bullet of a `key:` block in a CNL-P body, for one-line descriptions. */

package/lib/id.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 
 // GCF-PRD §5.8: a unit's id is a slug, one for every stage — the `## <id>` section in design/,
-// the card file cards/<id>.md, the graveyard line, the verdict commit. It is frozen once made.
+// the work item work/<id>.md, the history or graveyard line, the move's commit. Frozen once made.
 const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
 /** Derive a slug from a free-text name. Created once; never re-derived. */
@@ -19,7 +19,7 @@ export function isValidId(id) {
   return ID_RE.test(String(id ?? ''));
 }
 
-/** Card filename invariant: `cards/<id>.md`. */
+/** Work item filename invariant: `work/<id>.md`. */
 export function stemMatches(file, id) {
   return path.basename(file, '.md') === id;
 }

package/lib/inbox.js

@@ -0,0 +1,54 @@
+// gcf/inbox.md (Methodology §5.1): raw input waiting for triage — playtest notes, CI failures,
+// the agent's ideas and requests. One line per entry, `- <in-id> | <source> | <text>`; a triaged
+// line is erased, not marked: the file holds what is still waiting, not what happened to it.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { atomicWrite } from './safe-path.js';
+
+export const INBOX_HEAD =
+  '# Inbox — `- <in-id> | <source> | <text>`, raw input waiting for triage; a triaged line ' +
+  'is erased\n';
+export const SOURCES = ['playtest', 'ci', 'agent', 'operator'];
+const LINE = /^- (in-[0-9a-f]+) \| (\S+) \| (.+)$/;
+
+const inboxFile = (root) => path.join(root, 'inbox.md');
+
+/** @returns {Promise<Array<{id: string, source: string, text: string}>>} */
+export async function listInbox(root) {
+  const file = inboxFile(root);
+  if (!existsSync(file)) return [];
+
+  return (await readFile(file, 'utf8')).split(/\r?\n/).flatMap((l) => {
+    const m = l.match(LINE);
+
+    return m ? [{ id: m[1], source: m[2], text: m[3].trim() }] : [];
+  });
+}
+
+/** Append an entry; its id hashes the text and the moment, so two branches never collide. */
+export async function addInbox(root, text, source = 'operator', now = new Date().toISOString()) {
+  const clean = String(text).replace(/\s+/g, ' ').trim();
+  if (!clean) throw new Error('an inbox entry needs text');
+  if (!SOURCES.includes(source)) throw new Error(`source must be ${SOURCES.join(' | ')}`);
+  const id = `in-${createHash('sha1').update(`${now}\n${clean}`).digest('hex').slice(0, 8)}`;
+  const file = inboxFile(root);
+  const old = existsSync(file) ? await readFile(file, 'utf8') : INBOX_HEAD;
+  const eol = old.includes('\r\n') ? '\r\n' : '\n';
+  const head = old.endsWith('\n') ? old : old + eol;
+  await atomicWrite(file, `${head}- ${id} | ${source} | ${clean}${eol}`);
+
+  return { id, source, text: clean };
+}
+
+/** Erase entry `id`; refuses an id the inbox does not hold. */
+export async function dropInbox(root, id) {
+  const file = inboxFile(root);
+  const text = existsSync(file) ? await readFile(file, 'utf8') : '';
+  const lines = text.split(/(?<=\n)/);
+  // Each split line keeps its own ending, and `$` without the m flag does not stop before it.
+  const kept = lines.filter((l) => l.replace(/\r?\n$/, '').match(LINE)?.[1] !== id);
+  if (kept.length === lines.length) throw new Error(`${id} is not in gcf/inbox.md`);
+  await atomicWrite(file, kept.join(''));
+}

package/lib/index-gen.js

@@ -1,7 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { listCards, listSystems, firstBullet } from './gcf-paths.js';
+import { listItems, listSystems, firstBullet } from './gcf-paths.js';
+import { parseLive } from './live.js';
 import { atomicWrite } from './safe-path.js';
 import { readDesign, slotValues, loadDocProfile, isTbd, UNIT_TYPES } from './design.js';
 
@@ -40,11 +41,7 @@ export async function generate(root) {
     row(['system', `systems/${s.name}`, '-', s.data.system ?? '-', purpose]);
   }
 
-  for (const c of await listCards(root)) {
-    const system = (c.data.system ?? []).join(',');
-    row(['card', `cards/${c.name}`, c.data.status ?? '?', system, firstBullet(c.body, 'intent')]);
-  }
-
+  await workRows(root, row);
   await endRows(root, row);
 
   const txt = await readIfExists(root, 'open-questions.md');
@@ -57,11 +54,29 @@ export async function generate(root) {
   return `${lines.join('\n')}\n`;
 }
 
+/** One row per work item, then the inbox and LIVE.md counts. */
+async function workRows(root, row) {
+  for (const c of await listItems(root)) {
+    const system = (c.data.system ?? []).join(',') || '-';
+    const kind = `${c.data.type ?? '?'}/${c.data.gate ?? '?'}`;
+    const descr = `${kind}: ${c.data.title ?? firstBullet(c.body, 'intent')}`;
+    row(['item', `work/${c.name}`, c.data.status ?? '?', system, descr]);
+  }
+
+  const inbox = await readIfExists(root, 'inbox.md');
+  if (inbox !== null)
+    row(['inbox', 'inbox.md', '-', '-', `${count(inbox, /^- in-\S+ \|/gm)} entries to triage`]);
+  const live = await readIfExists(root, 'LIVE.md');
+  if (live === null) return;
+  const { capabilities: caps, knownIssues: known } = parseLive(live);
+  row(['live', 'LIVE.md', '-', '-', `${caps.length} capabilities, ${known.length} known issues`]);
+}
+
 /** The rows of the files that record how lives ended: one count per file. */
 async function endRows(root, row) {
   for (const [type, what] of [
-    ['history', 'built or kept'],
-    ['graveyard', 'killed ideas'],
+    ['history', 'ended accepted'],
+    ['graveyard', 'killed or dropped'],
   ]) {
     const text = await readIfExists(root, `${type}.md`);
     if (text !== null) row([type, `${type}.md`, '-', '-', `${count(text, /^- \S+ \|/gm)} ${what}`]);

package/lib/ledger.js

@@ -1,15 +1,16 @@
-// Where an id lives (GCF-PRD §5.8): a live place is a section of design/ or a file of cards/,
-// an end is the line the move wrote in the commit that ended the life — history.md for done and
-// keep, graveyard.md for drop and kill. Files, not commit messages: a squash, a shallow clone or
-// a rewritten history keeps them, and a revert of the move takes its line out with it.
+// Where an id lives (Methodology §2, §9): a live place is a section of design/ or a work item of
+// work/, an end is the line the move wrote in the commit that ended the life — history.md for
+// done, collapsed and decided, graveyard.md for every drop and kill. Files, not commit messages:
+// a squash, a shallow clone or a rewritten history keeps them, and a revert of the move takes
+// its line out with it.
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { readDesign } from './design.js';
-import { listCards } from './gcf-paths.js';
+import { listItems } from './gcf-paths.js';
 
-const HISTORY_EVENTS = ['done', 'collapsed'];
+export const HISTORY_EVENTS = ['done', 'collapsed', 'decided'];
 
 /** `[id, second field]` of each line `- <id> | <field> | …` of a gcf file. */
 async function recordLines(root, name) {
@@ -29,18 +30,18 @@ const gitOut = (args, cwd) => {
   return res.status === 0 ? res.stdout : null;
 };
 
-/** Ids HEAD holds as a card file or a design section. */
+/** Ids HEAD holds as a work item file or a design section. */
 function headIds(projectDir) {
   const files = gitOut(
-    ['ls-tree', '-r', '--name-only', 'HEAD', '--', 'gcf/cards', 'gcf/design'],
+    ['ls-tree', '-r', '--name-only', 'HEAD', '--', 'gcf/work', 'gcf/design'],
     projectDir,
   );
   const ids = new Set();
-  // Top level only, as readDesign and listCards read: a nested archive file is not a unit.
+  // Top level only, as readDesign and listItems read: a nested archive file is not a unit.
   for (const f of (files ?? '')
     .split('\n')
-    .filter((x) => /^gcf\/(cards|design)\/[^/]+\.md$/.test(x))) {
-    if (f.startsWith('gcf/cards/')) ids.add(path.basename(f, '.md'));
+    .filter((x) => /^gcf\/(work|design)\/[^/]+\.md$/.test(x))) {
+    if (f.startsWith('gcf/work/')) ids.add(path.basename(f, '.md'));
     // `./` makes the path relative to the cwd, as ls-tree printed it.
     else
       for (const m of (gitOut(['show', `HEAD:./${f}`], projectDir) ?? '').matchAll(/^## (\S+)/gm))
@@ -52,23 +53,23 @@ function headIds(projectDir) {
 
 /**
  * @typedef {object} Place
- * @property {'design' | 'card'} state
+ * @property {'design' | 'item'} state
  * @property {string} file gcf-relative
  */
 
 /**
  * Build the ledger of a project: `where(id)` answers `{ live, terminal }` — the live places
- * (a design section, a card file) and the terminal events (collapsed, killed, done).
+ * (a design section, a work item) and the terminal events (done, collapsed, decided, killed).
  */
 export async function buildLedger(projectDir) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const design = await readDesign(root);
-  const cards = await listCards(root);
+  const items = await listItems(root);
   /** @type {Map<string, Place[]>} */
   const live = new Map();
   const add = (id, place) => live.set(id, [...(live.get(id) ?? []), place]);
   for (const d of design) for (const u of d.units) add(u.id, { state: 'design', file: d.file });
-  for (const c of cards) add(String(c.data.id), { state: 'card', file: `cards/${c.name}` });
+  for (const c of items) add(String(c.data.id), { state: 'item', file: `work/${c.name}` });
 
   /** @type {Map<string, Set<string>>} */
   const terminal = new Map();
@@ -77,13 +78,14 @@ export async function buildLedger(projectDir) {
     if (HISTORY_EVENTS.includes(event)) mark(id, event);
   for (const [id] of await recordLines(root, 'graveyard.md')) mark(id, 'killed');
   // An id HEAD holds that has no live place and no terminal line is vanishing in this commit:
-  // it is not known, so a card or unit still citing it fails M2 in this very commit, and
+  // it is not known, so an item or unit still citing it fails M2 in this very commit, and
   // `vanished()` lets the gate warn that its reason was lost.
   const vanished = [...headIds(projectDir)].filter((id) => !live.has(id) && !terminal.has(id));
 
   return {
     design,
-    cards,
+    items,
+    item: (id) => items.find((c) => c.data.id === id),
     where: (id) => ({ id, live: live.get(id) ?? [], terminal: [...(terminal.get(id) ?? [])] }),
     known: (id) => live.has(id) || terminal.has(id),
     ids: () => [...new Set([...live.keys(), ...terminal.keys()])].sort(),

package/lib/linter.js

@@ -8,7 +8,8 @@ const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 // a unit is any non-letter in any script: `\w` is ASCII-only, and "5 слотов" is not "5 с".
 const UNIT_WORDS = [...UNITS, 'мс', 'с', 'сек', 'dmg', 'hp', 'px'].map(esc).join('|');
 const UNIT_NUM = new RegExp(`\\d+(?:[.,]\\d+)?\\s?(?:${UNIT_WORDS})(?![\\p{L}\\p{N}_-])`, 'u');
-const SIGNATURE = /\w+\s*\([^)]*\b(?:int|float|bool|string|void|var|ref|out)\b[^)]*\)/;
+// No space before the paren: "respawn the player (out of the arena)" is prose, not a call.
+const SIGNATURE = /\w+\([^)]*\b(?:int|float|bool|string|void|var|ref|out)\b[^)]*\)/;
 const CAMEL = /\b[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)+\b/;
 const ENVELOPE_FIELD = /^\s*(?:- )?(?:question|assumed|proposed):/;