gcf-aif-ext 0.7.2 → 0.7.4

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.2",
+  "version": "0.7.4",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/lib/bundle.js

@@ -180,13 +180,21 @@ function plan(bundle, cur, ledger) {
   const writes = [];
   const note = `lines outside any part: ${bundle.stray.join(', ')} (a lost gcf:part marker?)`;
   const report = bundle.stray.length ? [{ part: 'bundle', outcome: 'invalid', note }] : [];
+  const keyOf = (p) => `${p.kind}:${p.name}`;
+  const keys = bundle.parts.map(keyOf);
   for (const p of bundle.parts) {
-    const key = `${p.kind}:${p.name}`;
+    const key = keyOf(p);
     if (!validName(p)) {
       report.push({ part: key, outcome: 'invalid', note: 'not a gcf doc, system or unit name' });
       continue;
     }
 
+    // Which copy is the designer's edit is not ours to guess: the later one would win silently.
+    if (keys.indexOf(key) !== keys.lastIndexOf(key)) {
+      report.push({ part: key, outcome: 'invalid', note: 'the bundle holds this part twice' });
+      continue;
+    }
+
     const v = verdict(p, cur.get(key) ?? null);
     if (p.kind === 'unit' && v === 'new' && ledger.known(p.name)) {
       report.push({ part: key, outcome: 'taken', note: 'the id is used: pick another slug' });

package/lib/integrate.js

@@ -302,6 +302,8 @@ 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.
+    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);

package/lib/ledger.js

@@ -71,9 +71,11 @@ export async function buildLedger(projectDir) {
   for (const d of design) for (const u of d.units) add(u.id, { state: 'design', file: d.file });
   for (const c of items) add(String(c.data.id), { state: 'item', file: `work/${c.name}` });
 
-  /** @type {Map<string, Set<string>>} */
+  // A list, not a set: two equal lines are two ends too (M12), a merge of branches that each
+  // ended the id the same way.
+  /** @type {Map<string, string[]>} */
   const terminal = new Map();
-  const mark = (id, event) => terminal.set(id, (terminal.get(id) ?? new Set()).add(event));
+  const mark = (id, event) => terminal.set(id, [...(terminal.get(id) ?? []), event]);
   for (const [id, event] of await recordLines(root, 'history.md'))
     if (HISTORY_EVENTS.includes(event)) mark(id, event);
   for (const [id] of await recordLines(root, 'graveyard.md')) mark(id, 'killed');

package/lib/work-ops.js

@@ -11,7 +11,7 @@ import path from 'node:path';
 import { parse, serialize } from './frontmatter.js';
 import { buildLedger } from './ledger.js';
 import { readConfig } from './gcf-paths.js';
-import { atomicWrite } from './safe-path.js';
+import { atomicWrite, resolveInside } from './safe-path.js';
 import { allowedFrom, decisionFits, FEATURE_ONLY, fromOf } from './transitions.js';
 import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
 import { isValidId } from './id.js';
@@ -37,7 +37,7 @@ import {
 } from './live.js';
 import { dropInbox } from './inbox.js';
 import { refuseByPhase } from './phase.js';
-import { runHolder } from './main-lock.js';
+import { runHolder, withMainLock } from './main-lock.js';
 import { releaseSession, sessionActive } from './session-mark.js';
 
 /**
@@ -160,14 +160,13 @@ function unfinishedChildren(ledger, feature) {
 }
 
 /**
- * Open a move on item `id` from the statuses `move` allows: the files it touches, its steps,
- * and the LIVE.md edits folded into a single write at the end.
+ * Refuse a move on item `id` while a harness run or another agent session works it. `self` is
+ * the item this session drives itself (null: none).
+ * @param {string} projectDir
+ * @param {string} id
+ * @param {string | null} [self]
  */
-async function begin(projectDir, id, move) {
-  const root = gcfOf(projectDir);
-  const ledger = await buildLedger(projectDir);
-  const item = itemOf(ledger, id);
-  need(move, item);
+function refuseRunning(projectDir, id, self = process.env.GCF_RUN_ITEM ?? null) {
   const run = runHolder(projectDir, id);
   if (run)
     throw new Error(
@@ -176,11 +175,23 @@ async function begin(projectDir, id, move) {
     );
   // The session that claimed the item moves it itself (GCF_RUN_ITEM, set by `--claimed` or by
   // a harness run on main); anyone else waits, as for a run lock.
-  if (sessionActive(projectDir, id) && process.env.GCF_RUN_ITEM !== id)
+  if (sessionActive(projectDir, id) && self !== id)
     throw new Error(
       `${id} is worked by an agent session (gcf claim): wait until it moves the item, or run ` +
         `ai-factory gcf release ${id} when no session works it`,
     );
+}
+
+/**
+ * Open a move on item `id` from the statuses `move` allows: the files it touches, its steps,
+ * and the LIVE.md edits folded into a single write at the end.
+ */
+async function begin(projectDir, id, move) {
+  const root = gcfOf(projectDir);
+  const ledger = await buildLedger(projectDir);
+  const item = itemOf(ledger, id);
+  need(move, item);
+  refuseRunning(projectDir, id);
   const files = [item.file];
   const steps = [];
   const liveOps = [];
@@ -229,6 +240,16 @@ const writeItem = (item, data, body = item.body) => atomicWrite(item.file, seria
 const without = (data, ...keys) =>
   Object.fromEntries(Object.entries(data).filter(([k]) => !keys.includes(k)));
 
+/** Refuse a move on an unplayed item edited since its close; `then` is where the edit goes. */
+function refuseEdited(item, then) {
+  if (matchesFrozen(item)) return;
+  throw new Error(
+    `${item.data.id}: an unplayed item's body and live: are frozen, and this one was edited — ` +
+      `save the edit aside, restore the file (git restore gcf/work/${item.data.id}.md ` +
+      `discards it), make the move, then ${then}`,
+  );
+}
+
 /**
  * The item's lines leave its systems docs and its added capability leaves LIVE.md. A line
  * another unplayed item also wrote stays: that item's body still owes it to systems/.
@@ -236,12 +257,7 @@ const without = (data, ...keys) =>
 function unplay(m, item) {
   // The gate checks `frozen` only on a file that stays unplayed: a tune or a kill of an edited
   // item would take the edited lines out and leave the frozen ones in systems/ for good.
-  if (!matchesFrozen(item))
-    throw new Error(
-      `${item.data.id}: an unplayed item's body and live: are frozen, and this one was edited — ` +
-        `save the edit aside, restore the file (git restore gcf/work/${item.data.id}.md ` +
-        'discards it), make the move, then apply the edit to the ready item',
-    );
+  refuseEdited(item, 'apply the edit to the ready item');
   const systems = item.data.system ?? [];
   m.leaving.add(String(item.data.id));
   m.touch(...systemFiles(m.root, systems));
@@ -283,7 +299,8 @@ function tracked(projectDir, file) {
  */
 function archivePlan(m, item) {
   const rel = item.data.plan ?? `.ai-factory/plans/${item.data.id}.md`;
-  const src = path.resolve(m.projectDir, rel);
+  // The plan is moved and deleted: a `plan:` out of the project would take another tree's file.
+  const src = resolveInside(m.projectDir, rel);
   if (!existsSync(src) || !tracked(m.projectDir, src)) return null;
   const destRel = `.ai-factory/archive/plans/${path.basename(src)}`;
   const dest = path.resolve(m.projectDir, destRel);
@@ -456,7 +473,7 @@ function refuseOpenDepends(m, move, opts = {}) {
 /** ready → awaiting-verdict / awaiting-decision; `since` marks where the wait began.
  * @param {MoveOpts} [opts]
  */
-export async function submitItem(projectDir, id, opts = {}) {
+async function submitItemUnlocked(projectDir, id, opts = {}) {
   const { commit = true } = opts;
   const m = await begin(projectDir, id, 'submit');
   if (m.item.data.gate === 'auto')
@@ -528,7 +545,7 @@ function closeFeature(m) {
  * unit collapses into its systems docs and stays as unplayed; anything else ends in history.
  * @param {MoveOpts} [opts]
  */
-export async function closeItem(projectDir, id, opts = {}) {
+async function closeItemUnlocked(projectDir, id, opts = {}) {
   const { constraints = [], commit = true } = opts;
   const m = await begin(projectDir, id, 'close');
   const unplayed = SOFT.includes(m.item.data.type);
@@ -554,6 +571,8 @@ async function keep(m, constraints) {
   const { item } = m;
   refuseOpenDepends(m, 'verdict keep');
   if (item.data.status === 'unplayed') {
+    // systems/ and LIVE.md hold the frozen body: an edit made since would leave with the file.
+    refuseEdited(item, `carry the edit in a new item with reopens: ${item.data.id}`);
     endToHistory(m, item, 'collapsed', { applyLive: false });
 
     return;
@@ -599,7 +618,7 @@ async function tune(m, note) {
 /** keep | tune | kill on an item waiting for its verdict or unplayed (Methodology §5.4).
  * @param {MoveOpts} [opts]
  */
-export async function verdictItem(projectDir, id, verdict, opts = {}) {
+async function verdictItemUnlocked(projectDir, id, verdict, opts = {}) {
   const { note = '', tags = [], remove, constraints = [], commit = true } = opts;
   if (!['keep', 'tune', 'kill'].includes(verdict)) throw new Error(`Unknown verdict: ${verdict}`);
   const m = await begin(projectDir, id, `verdict:${verdict}`);
@@ -617,9 +636,11 @@ export async function verdictItem(projectDir, id, verdict, opts = {}) {
 function killFeature(m, { reason, remove }) {
   const { item, ledger } = m;
   const shipped = featureShipped(ledger, item);
-  for (const c of item.data.children ?? []) {
-    const child = ledger.item(c);
-    if (!child) continue;
+  const children = (item.data.children ?? []).map((c) => ledger.item(c)).filter(Boolean);
+  // A child's file goes with the feature: an agent working it would lose it mid-run.
+  // No session kills its own item through its feature: the claimed child counts as running too.
+  for (const child of children) refuseRunning(m.projectDir, String(child.data.id), null);
+  for (const child of children) {
     endToGraveyard(m, child, {
       reason: `feature ${item.data.id} killed: ${reason}`,
       removal: false,
@@ -674,7 +695,7 @@ function fitDecision(choice, item) {
 /** The operator's decisions (Methodology §4.1): spikes, decision items, bugs and features.
  * @param {MoveOpts} [opts]
  */
-export async function decideItem(projectDir, id, choice, opts = {}) {
+async function decideItemUnlocked(projectDir, id, choice, opts = {}) {
   const { reason = '', remove, commit = true } = opts;
   if (!DECIDE[choice])
     throw new Error(`Unknown decision: ${choice} (${Object.keys(DECIDE).join(' | ')})`);
@@ -689,7 +710,7 @@ export async function decideItem(projectDir, id, choice, opts = {}) {
 /** ready → blocked, with the reason or the question for the operator.
  * @param {MoveOpts} [opts]
  */
-export async function blockItem(projectDir, id, opts = {}) {
+async function blockItemUnlocked(projectDir, id, opts = {}) {
   const { reason, commit = true } = opts;
   const why = String(reason ?? '').trim();
   if (!why) throw new Error('a block needs a reason or a question');
@@ -703,7 +724,7 @@ export async function blockItem(projectDir, id, opts = {}) {
 /** blocked | parked → ready; a note (an answer, a delivered asset file) goes to `notes:`.
  * @param {MoveOpts} [opts]
  */
-export async function unblockItem(projectDir, id, opts = {}) {
+async function unblockItemUnlocked(projectDir, id, opts = {}) {
   const { note = '', commit = true } = opts;
   const m = await begin(projectDir, id, 'unblock');
   if (m.item.data.status === 'parked') dropKnownIssue(m, id);
@@ -725,7 +746,7 @@ export async function unblockItem(projectDir, id, opts = {}) {
 /** Any stored status → graveyard; an unplayed item leaves as a kill does.
  * @param {MoveOpts} [opts]
  */
-export async function dropItem(projectDir, id, opts = {}) {
+async function dropItemUnlocked(projectDir, id, opts = {}) {
   const { reason, tags = [], remove, commit = true } = opts;
   const m = await begin(projectDir, id, 'drop');
   if (m.item.data.type === 'feature' && (m.item.data.children ?? []).some((c) => m.ledger.item(c)))
@@ -855,7 +876,7 @@ function newItemText(spec, gate, since) {
  * Rank items in the given order: `priority` 1, 2, 3… (lower runs sooner). One commit
  * `gcf(priority)`. A board sends a column's new order after a drag; the console names the ids.
  */
-export async function prioritizeItems(projectDir, ids, { commit = true } = {}) {
+async function prioritizeItemsUnlocked(projectDir, ids, { commit = true } = {}) {
   if (!ids.length) throw new Error('name the items in the order they should run');
   if (new Set(ids).size !== ids.length) throw new Error('an id is named twice');
   const ledger = await buildLedger(projectDir);
@@ -896,7 +917,7 @@ export async function prioritizeItems(projectDir, ids, { commit = true } = {}) {
  * A new work item in ready (or blocked), no commit. A design unit enters work through `take`,
  * not here: its body is the unit's slots. `from` erases the inbox entry it came from.
  */
-export async function newItem(projectDir, spec) {
+async function newItemUnlocked(projectDir, spec) {
   const root = gcfOf(projectDir);
   const ledger = await buildLedger(projectDir);
   const gate = checkNew(ledger, spec);
@@ -930,3 +951,41 @@ export async function newItem(projectDir, spec) {
 
   return { item: `gcf/work/${spec.id}.md`, hash };
 }
+
+/**
+ * A committed move holds the main lock from its first read to its commit (Methodology §7): one
+ * that read the ledger before taking it would write over a move committed meanwhile.
+ * @template T
+ * @param {string} projectDir
+ * @param {boolean} commit
+ * @param {() => Promise<T>} move
+ */
+const locked = (projectDir, commit, move) => (commit ? withMainLock(projectDir, move) : move());
+
+/** @type {typeof submitItemUnlocked} */
+export const submitItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => submitItemUnlocked(projectDir, id, opts));
+/** @type {typeof closeItemUnlocked} */
+export const closeItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => closeItemUnlocked(projectDir, id, opts));
+/** @type {typeof verdictItemUnlocked} */
+export const verdictItem = (projectDir, id, verdict, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => verdictItemUnlocked(projectDir, id, verdict, opts));
+/** @type {typeof decideItemUnlocked} */
+export const decideItem = (projectDir, id, choice, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => decideItemUnlocked(projectDir, id, choice, opts));
+/** @type {typeof blockItemUnlocked} */
+export const blockItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => blockItemUnlocked(projectDir, id, opts));
+/** @type {typeof unblockItemUnlocked} */
+export const unblockItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => unblockItemUnlocked(projectDir, id, opts));
+/** @type {typeof dropItemUnlocked} */
+export const dropItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => dropItemUnlocked(projectDir, id, opts));
+/** @type {typeof prioritizeItemsUnlocked} */
+export const prioritizeItems = (projectDir, ids, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => prioritizeItemsUnlocked(projectDir, ids, opts));
+/** @type {typeof newItemUnlocked} */
+export const newItem = (projectDir, spec) =>
+  locked(projectDir, spec.commit ?? false, () => newItemUnlocked(projectDir, spec));

package/package.json

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