gcf-aif-ext 0.7.10 → 0.7.14

package/commands/gcf.js

@@ -19,6 +19,23 @@ const out = (json, value, human) =>
 const HARNESS = 'gcf-harness-aif-ext';
 
 const CLAIMED = 'the agent session that claimed the item (gcf claim) records its own move';
+/** close and submit from a command: they need a green verify unless told why not. */
+const verifiedMove = (o) => ({
+  commit: o.commit,
+  requireVerify: true,
+  unverified: o.unverified === undefined ? undefined : reasonOf(o.unverified),
+});
+
+/** The reason of `--unverified`, one line in the commit's subject; an empty one is no reason. */
+function reasonOf(text) {
+  const why = String(text).replace(/\s+/g, ' ').trim();
+  if (!why) throw new Error('--unverified needs the reason the move goes without a green verify');
+
+  return why;
+}
+
+const UNVERIFIED =
+  'move without a green gcf verify of the code as it is now; the reason goes into the commit';
 
 /** `--claimed`: this move comes from the session that holds the item's mark. */
 const claimedBy = (o, id) => {
@@ -442,31 +459,25 @@ function registerAnchor(gcf) {
       'Import a GDD into gcf/source/ with stable section anchors; on re-import prints the delta',
     )
     .option('--json', 'machine output')
+    .option('--done', 'the import is written: the next anchor counts its delta from this one')
     .action(async (file, opts) => {
-      const anchors = await lib('anchors');
-      const { splitSections, importSource, loadAnchorMap, classifyDelta } = anchors;
-      const base = path.basename(file);
-      const oldMap = await loadAnchorMap(process.cwd(), base);
-      const { readFile } = await import('node:fs/promises');
-      const sections = splitSections(await readFile(file, 'utf8'));
-      const delta = oldMap?.anchors ? classifyDelta(oldMap.anchors, sections) : null;
-      await importSource(process.cwd(), file);
-      // A renamed heading moves its anchor: provenance and source: follow it.
-      const rewritten = delta ? await anchors.rewriteAnchors(process.cwd(), delta.renamed) : [];
-      const rebaselined = Boolean(oldMap?.rebaselined);
-      const result = {
-        file: `gcf/source/${base}`,
-        sections: sections.map((s) => ({ anchor: s.anchor, heading: s.heading, lines: s.lines })),
-        delta,
-        rebaselined,
-        rewritten,
-      };
-      out(opts.json, result, (r) =>
+      const { anchorImport, finishImport } = await lib('anchors');
+      if (opts.done) {
+        const done = await finishImport(process.cwd(), file);
+        console.log(done ? `import of ${path.basename(file)} finished` : 'no import to finish');
+
+        return;
+      }
+
+      out(opts.json, await anchorImport(process.cwd(), file), (r) =>
         [
           ...r.sections.map(
             (s) => `${s.anchor}  L${s.lines[0]}-${s.lines[1]}  ${s.heading ?? '(preamble)'}`,
           ),
           anchorDeltaLine(r),
+          ...(r.resumed
+            ? ['resumed: an earlier import of this file did not finish, the delta counts from it']
+            : []),
           ...r.rewritten.map((f) => `renamed anchors rewritten in gcf/${f}`),
         ].join('\n'),
       );
@@ -747,10 +758,11 @@ function registerItemMoves(gcf) {
     .command('submit <id>')
     .description('ready → awaiting-verdict / awaiting-decision (commit gcf(submit))')
     .option('--claimed', CLAIMED)
+    .option('--unverified <why>', UNVERIFIED)
     .option('--no-commit', 'skip the commit (tests only)')
     .action(async (id, o) => {
       claimedBy(o, id);
-      const r = await (await ops()).submitItem(process.cwd(), id, { commit: o.commit });
+      const r = await (await ops()).submitItem(process.cwd(), id, verifiedMove(o));
       console.log(`${r.id} → ${r.status}${shortHash(r.hash)}`);
     });
   gcf
@@ -763,12 +775,13 @@ function registerItemMoves(gcf) {
       [],
     )
     .option('--claimed', CLAIMED)
+    .option('--unverified <why>', UNVERIFIED)
     .option('--no-commit', 'skip the commit (tests only)')
     .action(async (id, o) => {
       claimedBy(o, id);
       const r = await (
         await ops()
-      ).closeItem(process.cwd(), id, { constraints: o.constraint, commit: o.commit });
+      ).closeItem(process.cwd(), id, { ...verifiedMove(o), constraints: o.constraint });
       console.log(`closed ${r.id}${r.unplayed ? ' → unplayed' : ''}${shortHash(r.hash)}`);
     });
 }
@@ -982,6 +995,10 @@ function registerPlan(gcf) {
     .action(async (id, o) => {
       await touchSession(id);
       const r = await (await lib('plan-check')).planCheck(process.cwd(), id);
+      // Harness-PRD §11: the checks a plan took to converge.
+      await (
+        await lib('metrics')
+      ).logMetric(process.cwd(), 'plan-log.csv', [id, r.ok ? 1 : 0, r.problems?.length ?? 0]);
       out(o.json, r, (x) =>
         x.ok ? `${x.plan}: ${x.done}/${x.tasks} tasks done` : x.problems.join('\n'),
       );
@@ -1000,6 +1017,26 @@ function registerVerify(gcf) {
       const r = o.mark
         ? await (await lib('integrate')).markVerified(process.cwd(), id)
         : await (await lib('verify')).verifyItem(process.cwd(), id);
+      // Methodology §6: a green DoD on main is what close and submit ask for, for this code.
+      // A record git cannot write leaves the DoD unproven for the gate: the verify fails.
+      if (r.ok && !o.mark)
+        try {
+          (await lib('verify-stamp')).stampVerified(process.cwd(), id);
+        } catch (e) {
+          r.ok = false;
+          r.checks.push({ name: 'record', ok: false, problems: [e.message] });
+        }
+
+      // Harness-PRD §11: DoD attempts and what failed them.
+      const failed = r.checks.filter((c) => !c.ok).map((c) => c.name);
+      await (
+        await lib('metrics')
+      ).logMetric(process.cwd(), 'verify-log.csv', [
+        id,
+        r.ok ? 1 : 0,
+        failed.join(' '),
+        o.mark ? 1 : 0,
+      ]);
       out(o.json, r, (x) =>
         [
           ...x.checks.flatMap((c) =>

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.7.10",
+  "version": "0.7.14",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/injections/commit-status.md

@@ -1,9 +1,11 @@
-## GCF: work item status after commit (from gcf-aif-ext)
-
-gcf_commit:
-- when `gcf/` exists and the commit implements a work item, commit the implementation first, then move the item with its own command in a follow-up commit
-- gate `verdict` or `decision`: run `ai-factory gcf submit <item-id>` — it waits for the operator, `since:` records where the wait began
-- gate `auto`, every check green: write the item's `live:` delta, then run `ai-factory gcf close <item-id>` — never edit `status:` by hand
-- the work cannot go on: run `ai-factory gcf block <item-id> --reason "<why or the question>"`
-- do not write a terminal status into an item file: a terminal move deletes the file and writes the history or graveyard line itself
-- when the commit makes the tests of a hard unit still in `gcf/design/` green, run `ai-factory gcf done <id>` after it
+## GCF: work item status after commit (from gcf-aif-ext)
+
+gcf_commit:
+- on a `work/<id>` branch (a harness worktree) make none of the moves below: the session marks the branch with `ai-factory gcf verify <item-id> --mark` once its work is done, a stop goes into `.gcf-session/outcome.json`, and `ai-factory gcf integrate` on main records the move
+- when `gcf/` exists and the commit implements a work item, commit the implementation first, then move the item with its own command in a follow-up commit
+- gate `verdict` or `decision`: run `ai-factory gcf submit <item-id>` — it waits for the operator, `since:` records where the wait began
+- gate `auto`, every check green: write the item's `live:` delta, then run `ai-factory gcf close <item-id>` — never edit `status:` by hand
+- `submit` and `close` refuse code that changed since its last green `ai-factory gcf verify <item-id>`: run it again after any fix; `--unverified` is the human's call
+- the work cannot go on: run `ai-factory gcf block <item-id> --reason "<why or the question>"`
+- do not write a terminal status into an item file: a terminal move deletes the file and writes the history or graveyard line itself
+- when the commit makes the tests of a hard unit still in `gcf/design/` green, run `ai-factory gcf done <id>` after it

package/injections/plan-context.md

@@ -2,7 +2,8 @@
 
 gcf_gate:
 - when `gcf/` exists and the task names a work item, run `ai-factory gcf context <item-id>` first
-- the returned file list is the readset: read those files and nothing else under `gcf/`; `gcf/LIVE.md` in it says what the game already does
+- the returned file list is the readset: read those files, `gcf/INDEX.md` and `gcf/config.yml`, and nothing else under `gcf/`; `gcf/LIVE.md` in it says what the game already does
+- its `graveyard_hits` and `d2` lines are context too: what was buried before, and the assumptions in force with their `until:`
 - `over_budget: true` in the result: stop and record a D1 question instead of planning
 - an id in `depends:` that lives in `gcf/design/`, or as an item in any status but unplayed, parked or awaiting-verdict, is not played: do not plan on top of it, stop
 - a dependency awaiting its verdict is planned on: the close of this item then waits for that verdict (`ai-factory gcf block <id> --reason "waits for <dep>"`)

package/injections/review-pillars.md

@@ -6,3 +6,4 @@ gcf_review:
 - check the diff against each pillar's review question: a contradiction is a finding, not a note
 - numeric feel values in code outside the item's envelope: report the value and the envelope bounds
 - a capability the diff adds, changes or removes that the item's `live:` delta does not name: a finding
+- a feature child with `live: none: parent` carries no delta of its own: check the capability against its parent feature's `live:`, and one the parent does not name is a finding on the parent

package/lib/anchors.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, readdir, rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 
@@ -230,3 +230,60 @@ export async function rewriteAnchors(projectDir, renamed) {
 
   return changed;
 }
+
+/** `<base>.import.json`: the anchor map an import that has not finished started from. */
+const heldFile = (projectDir, base) =>
+  path.join(path.resolve(projectDir), 'gcf', 'source', `${base}.import.json`);
+
+/**
+ * `gcf anchor`: copy a GDD into gcf/source/, write its anchor map, and report its sections
+ * with their bodies and the delta. The delta counts from the map the last FINISHED import left:
+ * the map an import starts from is held until `finishImport`, so an import that died after
+ * anchoring reports the same delta again instead of an empty one (`resumed`).
+ */
+export async function anchorImport(projectDir, file) {
+  const base = path.basename(file);
+  const held = heldFile(projectDir, base);
+  const resumed = existsSync(held);
+  const current = await loadAnchorMap(projectDir, base);
+  const start = resumed
+    ? JSON.parse(await readFile(held, 'utf8'))
+    : (current ?? { anchors: null, rebaselined: false });
+  // Read first: a wrong path must leave no held map behind to fake an unfinished import.
+  const sections = splitSections(await readFile(file, 'utf8'));
+  if (!resumed) {
+    await mkdir(path.dirname(held), { recursive: true });
+    await writeFile(held, `${JSON.stringify(start, null, 2)}\n`, 'utf8');
+  }
+
+  const delta = start.anchors ? classifyDelta(start.anchors, sections) : null;
+  await importSource(projectDir, file);
+  // A renamed heading moves its anchor: provenance and source: follow it, from the anchors
+  // they cite now - those of the last anchoring - and from the held start's too, for a file a
+  // rewrite that died left behind; a rename already applied finds nothing to change.
+  const moved = current?.anchors ? classifyDelta(current.anchors, sections).renamed : [];
+  const renamed = [...moved, ...(delta?.renamed ?? [])];
+
+  return {
+    file: `gcf/source/${base}`,
+    sections: sections.map(({ anchor, heading, lines, body }) => ({
+      anchor,
+      heading,
+      lines,
+      body,
+    })),
+    delta,
+    rebaselined: Boolean(start.rebaselined),
+    resumed,
+    rewritten: await rewriteAnchors(projectDir, renamed),
+  };
+}
+
+/** `gcf anchor <file> --done`: the import is written; the next delta counts from it. */
+export async function finishImport(projectDir, file) {
+  const held = heldFile(projectDir, path.basename(file));
+  if (!existsSync(held)) return false;
+  await rm(held);
+
+  return true;
+}

package/lib/board.js

@@ -1,5 +1,6 @@
 // `gcf board --json` (Methodology §11): everything a board shows, in one read. The board is a
 // view: it shows these data and runs the same commands as the console; nothing here is stored.
+import { spawnSync } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
@@ -14,6 +15,7 @@ import { wipOf } from './audit-core.js';
 import { runHolder } from './main-lock.js';
 import { ITEM_TYPES } from './validate-item.js';
 import { movesOf } from './transitions.js';
+import { openDepends } from './work-ops.js';
 import { listQuestions } from './questions.js';
 import { sessionActive } from './session-mark.js';
 import { agentOf } from './agent-permissions.js';
@@ -90,6 +92,30 @@ const graveyardOf = async (root) =>
     };
   });
 
+/**
+ * The commit time of each `since` hash, by hash: one git call for the whole board. A hash git
+ * does not know (rebased away), a short one (the core writes it whole) or text that is no hash
+ * gets no time.
+ */
+function commitTimes(projectDir, hashes) {
+  const asked = [...new Set(hashes.filter((h) => /^([0-9a-f]{40}|[0-9a-f]{64})$/.test(h ?? '')))];
+  if (!asked.length) return new Map();
+  const res = spawnSync(
+    'git',
+    ['log', '--no-walk=unsorted', '--ignore-missing', '--format=%H %cI', ...asked],
+    { cwd: projectDir, encoding: 'utf8' },
+  );
+  const found = (res.status === 0 ? res.stdout : '').split('\n').filter(Boolean);
+
+  return new Map(
+    asked.flatMap((h) => {
+      const line = found.find((l) => l.split(' ')[0] === h);
+
+      return line ? [[h, line.split(' ')[1]]] : [];
+    }),
+  );
+}
+
 /** Verified branches; none outside a repository. */
 function verifiedOf(projectDir) {
   try {
@@ -179,8 +205,15 @@ function inRunOrder(items) {
 
 const LISTS = ['children', 'system', 'depends'];
 
+/** `run`, `session` or null. A harness run's lock wins over the mark its run on main holds. */
+function runningKind(projectDir, id) {
+  if (runHolder(projectDir, id) !== null) return 'run';
+
+  return sessionActive(projectDir, id) ? 'session' : null;
+}
+
 /** One item of the board. */
-async function itemOf(projectDir, c, verified) {
+async function itemOf(projectDir, c, verified, ledger) {
   const id = String(c.data.id);
   // A trailer counts only while the item waits on main for its integrate.
   const ready = c.data.status === 'ready' && verified.has(id);
@@ -188,7 +221,8 @@ async function itemOf(projectDir, c, verified) {
   // is a run; a trailer is a passed DoD. A worktree with neither is a run that stopped (a
   // timeout, a stop, a crash): the item is ready, and its next run resumes that worktree. A
   // session the harness kept (`resume`) is resumed by the next run in either mode.
-  const running = runHolder(projectDir, id) !== null || sessionActive(projectDir, id);
+  const kind = runningKind(projectDir, id);
+  const running = kind !== null;
   const resume = c.data.status === 'ready' ? await resumeOf(projectDir, id) : null;
   const resumable =
     !running &&
@@ -206,9 +240,14 @@ async function itemOf(projectDir, c, verified) {
     ...(c.data.severity ? { severity: c.data.severity } : {}),
     ...(c.data.blocked ? { blocked: c.data.blocked } : {}),
     running,
+    // `run`: a harness run's lock; `session`: an operator's or agent's session mark (`gcf claim`).
+    running_kind: kind,
     resumable,
     resume,
     verified: ready,
+    // The dependencies the run gate would refuse a ready item on now (Board-PRD §5.2).
+    waits_for:
+      c.data.status === 'ready' ? openDepends(ledger, c.data.depends ?? [], { waiting: true }) : [],
     // What a board may offer (§4.1): nothing while a run drives the item.
     moves: running ? [] : movesOf(c.data),
     file: `gcf/work/${c.name}`,
@@ -224,8 +263,14 @@ export async function board(projectDir) {
   const ledger = await buildLedger(projectDir);
   const verified = verifiedOf(projectDir);
   const items = [];
-  for (const c of ledger.items) items.push(await itemOf(projectDir, c, verified));
+  for (const c of ledger.items) items.push(await itemOf(projectDir, c, verified, ledger));
   inRunOrder(items);
+  // When the wait began: the time of the commit `since` names (Board-PRD §13).
+  const times = commitTimes(
+    projectDir,
+    items.map((i) => i.since),
+  );
+  for (const i of items) i.since_at = times.get(i.since) ?? null;
   const inbox = await listInbox(root);
   // Where agents struggle: the lessons in the inbox each item's sessions left.
   for (const i of items) i.lessons = inbox.filter((e) => e.item === i.id).length;

package/lib/integrate.js

@@ -271,6 +271,9 @@ async function integrateOne(projectDir, id) {
  * branch bringing its own lines could not merge over them. Union merge joins the lines.
  */
 function commitMetrics(projectDir) {
+  // A log the harness started on main (run-log, guard-log) is new to git: add it first; only
+  // the logs, never an editor's swap file beside them.
+  git(projectDir, ['add', '--', 'gcf/.metrics/*.csv'], { check: false });
   const dirty = git(projectDir, [
     'status',
     '--porcelain',
@@ -278,17 +281,23 @@ function commitMetrics(projectDir) {
     '--',
     'gcf/.metrics',
   ]);
+  // Best effort: a main mid-rebase or mid-merge keeps its logs for the next integrate, and a
+  // run still starts.
   if (dirty.out)
-    git(projectDir, [
-      'commit',
-      '-q',
-      '--no-verify',
-      '-m',
-      'gcf(metrics): run logs',
-      '--only',
-      '--',
-      'gcf/.metrics',
-    ]);
+    git(
+      projectDir,
+      [
+        'commit',
+        '-q',
+        '--no-verify',
+        '-m',
+        'gcf(metrics): run logs',
+        '--only',
+        '--',
+        'gcf/.metrics',
+      ],
+      { check: false },
+    );
 }
 
 /**
@@ -302,11 +311,13 @@ export async function integrate(projectDir, ids = []) {
     throw new Error(`integrate runs in the main checkout on its branch, not on ${branch}`);
 
   return withMainLock(projectDir, async () => {
-    // Nothing to merge leaves main alone: a run's first integrate must not refuse a dirty tree.
+    // The run logs go in at every integrate, a main-mode run's first one too: nothing else
+    // commits them there. Nothing to merge leaves the rest of main alone: a run's first
+    // integrate must not refuse a dirty tree.
+    commitMetrics(projectDir);
     if (!ids.length && !verifiedBranches(projectDir).length) return [];
     if (git(projectDir, ['status', '--porcelain', '--untracked-files=no', '--', '.', METRICS]).out)
       throw new Error('main has uncommitted changes: commit or stash them before integrating');
-    commitMetrics(projectDir);
     for (const id of ids)
       if (!isVerified(projectDir, id))
         throw new Error(

package/lib/metrics.js

@@ -0,0 +1,41 @@
+// The run logs this module writes to gcf/.metrics (Harness-PRD §11): append-only csv, one
+// line per call, merged by union. A worktree's lines go to the main checkout's logs: the
+// worktree's own gcf/.metrics is thrown away when its branch merges.
+import { spawnSync } from 'node:child_process';
+import { appendFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/** gcf/.metrics of the main checkout of `projectDir`; its own outside a repository. */
+export function metricsDir(projectDir) {
+  const res = spawnSync('git', ['rev-parse', '--git-common-dir'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
+  const common = res.status === 0 ? path.resolve(projectDir, res.stdout.trim()) : '';
+  const main = path.basename(common) === '.git' ? path.dirname(common) : projectDir;
+
+  return path.join(main, 'gcf', '.metrics');
+}
+
+/** A field as csv takes it: no comma, no line break, at most 120 characters. */
+const field = (v) =>
+  String(v ?? '')
+    .replace(/[,\r\n]+/g, ';')
+    .slice(0, 120);
+
+/**
+ * Append one line to a log, timestamped; a project without gcf/ keeps no logs. Best effort: a
+ * log that cannot be written (a csv held open by a spreadsheet) never fails the command.
+ */
+export async function logMetric(projectDir, file, fields) {
+  try {
+    const dir = metricsDir(projectDir);
+    if (!existsSync(path.dirname(dir))) return;
+    await mkdir(dir, { recursive: true });
+    const line = [new Date().toISOString(), ...fields].map(field).join(',');
+    await appendFile(path.join(dir, file), `${line}\n`, 'utf8');
+  } catch {
+    // No line this time.
+  }
+}

package/lib/verify-stamp.js

@@ -0,0 +1,102 @@
+// The record of a green `gcf verify` on main (Methodology §6): `close` and `submit` need one for
+// the code as it is now, so a DoD run some other way cannot stand in for it. The record holds
+// the hash of the project's code, not of a commit: committing the verified code keeps it valid,
+// and any edit after the verify (a review's fix) asks for a new one. In a worktree the
+// `GCF-Verified` trailer does this job, and the integrator's moves need no record.
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Not code: the framework's own files, the plans, the run files. A move or a plan tick there
+// after the verify does not change what the DoD proved.
+const NOT_CODE = ['gcf', '.ai-factory', '.gcf-session'];
+
+const stampFile = (projectDir, id) =>
+  path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${id}.verified`);
+
+const git = (projectDir, args, env = {}) =>
+  spawnSync('git', args, { cwd: projectDir, encoding: 'utf8', env: { ...process.env, ...env } });
+
+/**
+ * The git tree of the project's code as it is on disk, committed or not, new files included
+ * (ignored ones are not); null outside a repository. A git that fails on the code (a file it
+ * cannot read, `core.safecrlf`) throws: a gate that cannot see the code must not let it pass. A
+ * copy of the index keeps git's stat cache, so only changed files are hashed again.
+ */
+export function codeTree(projectDir) {
+  const index = git(projectDir, ['rev-parse', '--git-path', 'index']);
+  if (index.status !== 0) return null;
+  const real = path.resolve(projectDir, index.stdout.trim());
+  const tmp = path.join(os.tmpdir(), `gcf-code-index-${process.pid}-${Date.now()}`);
+  const env = { GIT_INDEX_FILE: tmp };
+  const step = (args) => {
+    const r = git(projectDir, args, env);
+    if (r.status !== 0) throw new Error(`git ${args[0]} on the code failed: ${r.stderr.trim()}`);
+
+    return r.stdout.trim();
+  };
+
+  try {
+    if (existsSync(real)) copyFileSync(real, tmp);
+    step(['add', '-A', '--', '.', ...NOT_CODE.map((p) => `:(exclude)${p}`)]);
+    step(['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', ...NOT_CODE]);
+
+    return step(['write-tree']);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}
+
+/** Record a green verify of the code as it is now. */
+export function stampVerified(projectDir, id) {
+  const tree = codeTree(projectDir);
+  if (!tree) return;
+  const file = stampFile(projectDir, id);
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ tree, at: new Date().toISOString() })}\n`);
+}
+
+/** A move ended the item's work: its record goes with it. */
+export const dropStamp = (projectDir, id) => rmSync(stampFile(projectDir, id), { force: true });
+
+/** The files that differ between two trees, the first few, for a refusal to name. */
+function changed(projectDir, from, to) {
+  const r = git(projectDir, ['diff-tree', '-r', '--name-only', from, to]);
+  const files = r.status === 0 ? r.stdout.split('\n').filter(Boolean) : [];
+  const more = files.length > 5 ? ` and ${files.length - 5} more` : '';
+
+  return files.length ? ` (${files.slice(0, 5).join(', ')}${more})` : '';
+}
+
+/**
+ * Why `close` or `submit` may not take the item now, or null: no green verify on record, or
+ * the code changed since. A feature closes over its children and has no code of its own. The
+ * way past it is named as the human's: an agent reads this text.
+ */
+export function unverifiedProblem(projectDir, id, type) {
+  if (type === 'feature') return null;
+  const tree = codeTree(projectDir);
+  if (!tree) return null;
+  const how =
+    `run ai-factory gcf verify ${id} until it is green; only the human may move it without ` +
+    'one (--unverified "<why>")';
+  const stamp = readStamp(projectDir, id);
+  if (!stamp) return `${id}: no green gcf verify on record — ${how}`;
+  if (stamp.tree !== tree) {
+    const files = changed(projectDir, stamp.tree, tree);
+
+    return `${id}: the code changed since its green gcf verify${files} — ${how}`;
+  }
+
+  return null;
+}
+
+/** @returns {{tree: string, at: string} | null} the record, or null when there is none. */
+function readStamp(projectDir, id) {
+  try {
+    return JSON.parse(readFileSync(stampFile(projectDir, id), 'utf8'));
+  } catch {
+    return null;
+  }
+}

package/lib/work-ops.js

@@ -39,6 +39,7 @@ import { dropInbox } from './inbox.js';
 import { refuseByPhase } from './phase.js';
 import { locked, runHolder } from './main-lock.js';
 import { dropAgentSession, releaseSession, sessionActive } from './session-mark.js';
+import { dropStamp, unverifiedProblem } from './verify-stamp.js';
 
 /**
  * Options of a committed move; each move reads the ones it needs.
@@ -232,10 +233,38 @@ async function finish(m, move, tail, commit) {
   // and no rerun resumes it.
   releaseSession(m.projectDir, String(m.item.data.id));
   dropAgentSession(m.projectDir, String(m.item.data.id));
+  dropStamp(m.projectDir, String(m.item.data.id));
 
   return hash;
 }
 
+/**
+ * `close` and `submit` from a command (Methodology §6): the code as it is now needs a green
+ * `gcf verify`, unless the operator says why not (`unverified`, written into the move's
+ * commit). The integrator's moves rest on the branch's trailer instead.
+ */
+function needVerified(m, opts) {
+  if (!opts.requireVerify || opts.unverified) return;
+  const id = String(m.item.data.id);
+  const problem = verifyGateProblem(m.projectDir, id, m.item.data.type);
+  if (problem) throw new Error(problem);
+}
+
+/** The verify gate's refusal, or null; a git that cannot hash the code refuses too. */
+function verifyGateProblem(projectDir, id, type) {
+  try {
+    return unverifiedProblem(projectDir, id, type);
+  } catch (e) {
+    return (
+      `${id}: cannot hash the code for the verify gate (${e.message}) — fix that, or the ` +
+      'human passes --unverified "<why>"'
+    );
+  }
+}
+
+/** The commit's tail of a move made without a green verify. */
+const unverifiedTail = (opts) => (opts.unverified ? ` (unverified: ${opts.unverified})` : '');
+
 const writeItem = (item, data, body = item.body) => atomicWrite(item.file, serialize(data, body));
 
 /** `data` without the keys named — a field that no longer applies leaves the frontmatter. */
@@ -481,11 +510,12 @@ async function submitItemUnlocked(projectDir, id, opts = {}) {
   if (m.item.data.gate === 'auto')
     throw new Error(`${id} has gate auto: nobody waits for it — close it with gcf close ${id}`);
   refuseOpenDepends(m, 'submit', { waiting: true });
+  needVerified(m, opts);
   const status = m.item.data.gate === 'verdict' ? 'awaiting-verdict' : 'awaiting-decision';
   const data = { ...without(m.item.data, 'blocked'), status, since: headHash(projectDir) };
   m.step(() => writeItem(m.item, data));
 
-  return { id, status, hash: await finish(m, 'submit', id, commit) };
+  return { id, status, hash: await finish(m, 'submit', `${id}${unverifiedTail(opts)}`, commit) };
 }
 
 /** Why a soft gate-auto item cannot close unplayed, or null: only an `added` comes back out. */
@@ -556,11 +586,13 @@ async function closeItemUnlocked(projectDir, id, opts = {}) {
     if (m.item.data.gate !== 'auto')
       throw new Error(`${id} has gate ${m.item.data.gate}: submit it, the operator closes it`);
     refuseOpenDepends(m, 'close');
+    needVerified(m, opts);
     if (unplayed) closeUnplayed(m);
     else await closeEnding(m, constraints);
   }
 
-  const hash = await finish(m, 'close', `${id}${unplayed ? ' → unplayed' : ''}`, commit);
+  const tail = `${id}${unplayed ? ' → unplayed' : ''}${unverifiedTail(opts)}`;
+  const hash = await finish(m, 'close', tail, commit);
 
   return { id, hash, unplayed };
 }

package/package.json

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

package/profiles/pillars.md

@@ -25,7 +25,7 @@ sections:
   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
+- none: a pillar that needs more than its statement, invariant, review question and id is not a pillar yet
 
 enforcement:
 - `npx --yes cnlp-kit check`, over the file a `cnlp.config.json` corpus entry maps to this profile