gcf-aif-ext 0.2.5 → 0.3.0

package/lib/verdict-fs.js

@@ -1,130 +1,207 @@
 import { readFile, unlink } 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 { 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';
 
-// 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('- ')) : [];
+const ENVELOPE = /^\S+\.\.\S+ /;
+const real = (lines) => lines.filter((l) => !/^- none\b/.test(l));
+
+function recordsOf(body, key) {
+  const { lines, sections } = parseBlocks(body);
+  const at = sections.find((s) => s.key === key && !s.value);
+
+  return at ? readRecords(itemsOf(lines, at.line)).records.map((r) => r.values) : [];
 }
 
-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`);
-  return `${body.trimEnd()}\n\n${key}:\n${fresh.join('\n')}\n`;
+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}`);
+    }
+  }
 }
 
-// `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;
+/**
+ * Card → 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.
+ */
+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}`);
+  }
+
+  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 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();
+/** 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)',
+    );
+  }
+
+  return card;
+}
+
+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));
+  };
 }
 
+/** The graveyard line of a killed or dropped unit: `- <id> | <reason> | tags: <tags>`. */
+export async function buryLine(root, id, 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);
+}
+
+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';
+
+/**
+ * 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.
+ */
+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}`);
+}
+
+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; `kill` writes the graveyard line; `tune` bumps the counter and
- * appends the human note to the feel slot.
+ * 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 } = {}) {
+export async function applyVerdict(
+  projectDir,
+  cardId,
+  verdict,
+  { note = '', tags = [], commit = true } = {},
+) {
   const root = path.join(path.resolve(projectDir), 'gcf');
-  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)`);
-  }
+  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`);
+  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 ?? [];
-  let mutate;
-
-  if (verdict === 'tune') {
-    mutate = 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));
-    };
-  } else if (verdict === 'kill') {
-    const gyFile = path.join(root, 'graveyard.md');
-    touched.push(gyFile);
-    mutate = 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);
-    };
-  } else {
-    // `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);
-    mutate = async () => {
-      for (const [i, sysFile] of sysFiles.entries()) {
-        let doc = existsSync(sysFile)
-          ? parse(await readFile(sysFile, 'utf8'))
-          : { data: { system: systems[i] }, body: 'purpose:\n- (fill in)\n' };
-        let body = doc.body;
-        for (const [slot, section] of MERGE_MAP) {
-          body = upsertBlock(body, section, blockLines(card.body, slot));
-        }
-        // 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 unlink(card.file);
-    };
-  }
+  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} ${card.data.slug} → ${systems.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 = gitCommit(projectDir, message, touched);
-  }, { gitCwd: commit ? path.resolve(projectDir) : 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 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",

package/profiles/game.md

@@ -0,0 +1,68 @@
+---
+name: game
+description: The CNL-P profile of gcf/game.md — the vision, the scope and the milestones the design units are planned against.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat and the document is named by its fixed path
+
+frontmatter_fields:
+- none: the file is a singleton at a fixed path and carries no machine fields
+
+lexicon_exempt:
+- none: nothing is exempt in the document that bounds the scope
+
+sections:
+- key: logline
+  form: scalar
+  required: yes
+  note: the game in one line
+
+- key: platforms
+  form: bullet-list
+  required: yes
+  note: platform and input, one per line
+
+- key: audience
+  form: bullet-list
+  required: yes
+  note: who plays, one group per line
+
+- key: references
+  form: bullet-list
+  required: no
+  note: "like X, not like Y", one reference per line
+
+- key: scope_in
+  form: bullet-list
+  required: yes
+  note: what the game holds
+
+- key: scope_out
+  form: bullet-list
+  required: yes
+  note: what the game does not hold, or not in this version
+
+- key: milestones
+  form: record-list
+  required: yes
+  record_keys: name, goal
+  optional_record_keys: content
+  note: the closed vocabulary of a unit's milestone field; content is a volume written as a comparison
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor when the file came from a GDD
+
+custom_sections:
+- none: a block that is not listed above belongs to a unit or to PILLARS.md
+
+enforcement:
+- `ai-factory gcf design check` resolves every unit's milestone against this file

package/profiles/glossary.md

@@ -0,0 +1,37 @@
+---
+name: glossary
+description: The CNL-P profile of gcf/glossary.md — one word per concept, the synonyms it forbids, and the project's own units of measure.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat and the document is named by its fixed path
+
+frontmatter_fields:
+- none: the file is a singleton at a fixed path and carries no machine fields
+
+lexicon_exempt:
+- none: the glossary is the lexicon of the project
+
+sections:
+- key: terms
+  form: record-list
+  required: yes
+  record_keys: term, means
+  optional_record_keys: not
+  note: a term the human confirmed, what it means, and the words that may not name it
+
+- key: units
+  form: bullet-list
+  required: no
+  note: units of measure the project adds to the closed list, one per line as "<unit>: <what it measures>"
+
+custom_sections:
+- none: a block that is not listed above belongs to a unit
+
+enforcement:
+- `ai-factory gcf design check` refuses a forbidden synonym in gcf/design/ and in a card (M4)
+- quoted text is data: a GDD quote keeps the designer's own word

package/profiles/pillars.md

@@ -21,7 +21,8 @@ sections:
   form: record-list
   required: yes
   record_keys: statement, invariant, review_question
-  note: pillar count <= 7 and the token budget are enforced by the gcf audit core, not the checker
+  optional_record_keys: id
+  note: pillar count <= 7 and the token budget are enforced by the gcf audit core; id is the slug a design unit cites in pillars:
 
 custom_sections:
 - none: a pillar that needs more than its three keys is not a pillar yet

package/profiles/unit-constraint.md

@@ -0,0 +1,42 @@
+---
+name: unit-constraint
+description: The CNL-P profile of a GCF design unit of type constraint — a platform, performance or size threshold, accepted by a measurement.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat; the `## <id>` line and the header fields above the blocks name the unit
+
+frontmatter_fields:
+- none: a constraint never becomes a card, so its header lives above the blocks in design/
+
+lexicon_exempt:
+- none: every block is read when the constraint is planned and measured
+
+sections:
+- key: threshold
+  form: bullet-list
+  required: yes
+  note: one comparison per line, "<subject> <op> <value> <unit>"
+
+- key: measure
+  form: bullet-list
+  required: yes
+  note: how the threshold is measured and on what - device, build, scene
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+custom_sections:
+- none: a block that is not listed above is prose looking for a home
+
+enforcement:
+- `ai-factory gcf design check`, over the units in gcf/design/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-entity.md

@@ -0,0 +1,38 @@
+---
+name: unit-entity
+description: The CNL-P profile of a GCF design unit of type entity — the shape of a data noun before code holds it.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat; the `## <id>` line and the header fields above the blocks name the unit
+
+frontmatter_fields:
+- none: an entity never becomes a card, so its header lives above the blocks in design/
+
+lexicon_exempt:
+- none: every block is read when the entity is planned and coded
+
+sections:
+- key: fields
+  form: record-list
+  required: yes
+  record_keys: name, holds
+  note: one record per field - what it holds, never its allowed values, which belong to a rule
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+custom_sections:
+- none: a block that is not listed above is prose looking for a home
+
+enforcement:
+- `ai-factory gcf design check`, over the units in gcf/design/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-mechanic.md

@@ -0,0 +1,106 @@
+---
+name: unit-mechanic
+description: The CNL-P profile of a GCF design unit of type mechanic — one body for its section in design/<system>.md and for its card in cards/<id>.md.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in cards/ the frontmatter does
+
+frontmatter_fields:
+- schema
+- id
+- type
+- title
+- status
+- system
+- depends
+- pillars
+- source
+- reopens
+- tune_count
+- built_at
+- created
+
+lexicon_exempt:
+- none: every block is read when the unit is planned, built or played
+
+sections:
+- key: intent
+  form: bullet-list
+  required: yes
+  note: why the mechanic exists, in the designer's words
+
+- key: behavior
+  form: record-list
+  required: yes
+  record_keys: input, state, feedback
+  note: one record per chain - player input, the state it changes, the feedback the player sees
+
+- key: refusal
+  form: bullet-list
+  required: yes
+  note: what happens when the action is not allowed - no resource, invalid target, already active
+
+- key: boundaries
+  form: bullet-list
+  required: yes
+  note: zero, maximum, overflow, simultaneity; an exact limit is a comparison at the end of its line
+
+- key: persistence
+  form: scalar
+  required: yes
+  note: what survives a reload, a session or a match
+
+- key: feel_like
+  form: scalar
+  required: yes
+  note: the comparison "like X, not like Y"
+
+- key: feel
+  form: record-list
+  required: yes
+  record_keys: name, envelope
+  note: one record per tunable value; an envelope "a..b <unit>" is the only legal range of intent
+
+- key: contract
+  form: bullet-list
+  required: yes
+  note: card stage, absent in design/ - paths and entry points, never member lists or values; an architecture rule is a constraint
+
+- key: interactions
+  form: bullet-list
+  required: yes
+  note: card stage, absent in design/ - "<other id>: how the two cross", one line per crossing
+
+- key: constraints
+  form: bullet-list
+  required: yes
+  note: negative constraints, one prohibition per line, checkable by an analyzer or a reviewer
+
+- key: miss_criterion
+  form: scalar
+  required: yes
+  note: the one question the game in hand answers; the human answers it at the verdict
+
+- key: tuning
+  form: bullet-list
+  required: no
+  note: card stage only - one verdict remark per tune, read before the rebuild
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+custom_sections:
+- none: a block that is not listed above is prose looking for a home
+
+enforcement:
+- `ai-factory gcf design check`, over the units in gcf/design/ and the cards in gcf/cards/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding