gcf-aif-ext 0.6.0 → 0.7.0

package/README.md

@@ -50,6 +50,15 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
 
 On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
 
+### 0.7.0
+
+- `priority:` on an item: a rank, lower runs sooner. `ai-factory gcf prioritize <id> <id> …` ranks items in that order in one commit; `item new --priority <n>`. `gcf board --json` lists ranked items first and carries `priority`.
+- `ai-factory gcf question answer <q-id> --text="<answer>"` writes the human's answer into its record of `gcf/open-questions.md` and commits. An answered D1 no longer blocks its units; the next agent on the unit puts the answer into its slot (`answer: q-NNN`) and removes the record. `gcf board --json` questions carry `question`, `proposed`, `blocks` and `answer`.
+- `ai-factory gcf claim <id>` / `release <id>`: an agent session working an item in the main checkout marks it running. The session's own `context`, `plan check` and `verify` on the item keep the mark fresh (so do a harness run on main and its readset-guard hook), a move on the item clears it, and 2 hours without either expire it. The board and the audit read it as `running`, so a harness run does not take the item, and the core refuses any move on it but the session's own (`submit`, `close`, `block` with `--claimed`).
+- `prioritize` leaves the rank of a ready item it does not name (a running one): the named items take the free ranks around it.
+- `run_mode: worktree | main` in `gcf/config.yml` (Methodology §7): a project whose agent works through an editor bound to the project folder sets `main`. `gcf board --json` carries it.
+- `/gcf-card` cuts several items along subsystem boundaries, marks two items of one subsystem that change different files `parallel: ok`, ranks them with `prioritize`, and keeps `depends` for real needs only.
+
 ### 0.6.0
 
 - `gcf board --json` carries `schema: 1`, the version of its format (Methodology §11 lists every field); a board refuses a version it does not know. New fields: per item `file`, `plan_file`, `log`, `depends`, `milestone`, `tune_count`, `since`, `model`, `effort` and `moves` (what the item takes now by Methodology §4.1, empty while a run drives it); at the top `history` and `graveyard`.

package/commands/gcf.js

@@ -18,6 +18,40 @@ 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';
+
+/** `--claimed`: this move comes from the session that holds the item's mark. */
+const claimedBy = (o, id) => {
+  if (o.claimed) process.env.GCF_RUN_ITEM = id;
+};
+
+/** A session's own command on its item keeps the item's running mark fresh. */
+const touchSession = async (id) => (await lib('session-mark')).touchSession(process.cwd(), id);
+
+function registerSession(gcf) {
+  gcf
+    .command('claim <id>')
+    .description(
+      'An agent session starts working the item on main: the board shows it running until a ' +
+        'move ends it, release, or 30 minutes without a gcf command on it',
+    )
+    .action(async (id) => {
+      const { buildLedger } = await lib('ledger');
+      if (!(await buildLedger(process.cwd())).item(id)) throw new Error(`${id} is not a work item`);
+      await (await lib('session-mark')).claimSession(process.cwd(), id);
+      console.log(`claimed ${id}`);
+    });
+  gcf
+    .command('release <id>')
+    .description('The session stops working the item without a move: it no longer shows running')
+    .action(async (id) => {
+      const { isValidId } = await lib('id');
+      if (!isValidId(id)) throw new Error(`${id} is not an item id`);
+      (await lib('session-mark')).releaseSession(process.cwd(), id);
+      console.log(`released ${id}`);
+    });
+}
+
 /**
  * `--harness` / `--no-harness` decide. Without either, ask only when someone can answer
  * and the answer matters: an agent, CI or MinTTY run has no terminal, and a project
@@ -195,6 +229,7 @@ function registerContext(gcf) {
     .description('Assemble the readset for a work item (GCF-PRD §9.1)')
     .option('--json', 'machine output')
     .action(async (itemId, opts) => {
+      await touchSession(itemId);
       const { buildContext } = await lib('context');
       const ctx = await buildContext(process.cwd(), itemId);
       // Metric 1 (GCF-PRD §14): readset size over time, one csv line per call.
@@ -644,6 +679,7 @@ function registerItem(gcf) {
     .option('--milestone <name>', 'the milestone of game.md it belongs to')
     .option('--release <version>', 'a release: the version it ships')
     .option('--channel <name>', 'a release: where it ships, e.g. steam')
+    .option('--priority <rank>', 'its rank: 1, 2, 3… (lower runs sooner)')
     .option('--model <name>', 'the model its run uses, e.g. opus')
     .option('--effort <level>', 'the effort its run uses, e.g. high')
     .option('--commit', 'commit it (gcf(item)): for a caller with no console, e.g. a board')
@@ -666,6 +702,7 @@ function registerItem(gcf) {
         channel: o.channel,
         model: o.model,
         effort: o.effort,
+        priority: o.priority === undefined ? undefined : Number(o.priority),
         commit: o.commit === true,
       });
       console.log(`${r.item}${shortHash(r.hash)}`);
@@ -674,11 +711,34 @@ function registerItem(gcf) {
 
 function registerItemMoves(gcf) {
   const ops = () => lib('work-ops');
+  gcf
+    .command('prioritize <ids...>')
+    .description('Rank items in this order: priority 1, 2, 3… (lower runs sooner; commit)')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (ids, o) => {
+      const r = await (await ops()).prioritizeItems(process.cwd(), ids, { commit: o.commit });
+      console.log(`ranked ${r.ids.join(', ')}${shortHash(r.hash)}`);
+    });
+  const question = gcf.command('question').description('Open questions (gcf/open-questions.md)');
+  question
+    .command('answer <qid>')
+    .description('The human answers a question: written into its record, commit gcf(answer)')
+    // An answer may start with a hyphen; as `--text=<text>` it stays one value.
+    .requiredOption('--text <text>', 'the answer, one line')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (qid, o) => {
+      const r = await (
+        await lib('questions')
+      ).answerQuestion(process.cwd(), qid, o.text, { commit: o.commit });
+      console.log(`answered ${r.id}${shortHash(r.hash)}`);
+    });
   gcf
     .command('submit <id>')
     .description('ready → awaiting-verdict / awaiting-decision (commit gcf(submit))')
+    .option('--claimed', CLAIMED)
     .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 });
       console.log(`${r.id} → ${r.status}${shortHash(r.hash)}`);
     });
@@ -691,8 +751,10 @@ function registerItemMoves(gcf) {
       (v, p) => [...p, v],
       [],
     )
+    .option('--claimed', CLAIMED)
     .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 });
@@ -723,8 +785,10 @@ function registerDecide(gcf) {
     .command('block <id>')
     .description('ready → blocked, with the reason or the question (commit gcf(block))')
     .requiredOption('--reason <text>', 'why it cannot go on, or the question for you')
+    .option('--claimed', CLAIMED)
     .option('--no-commit', 'skip the commit (tests only)')
     .action(async (id, o) => {
+      claimedBy(o, id);
       const r = await (
         await ops()
       ).blockItem(process.cwd(), id, { reason: o.reason, commit: o.commit });
@@ -857,6 +921,7 @@ function registerPlan(gcf) {
     .description('Deterministic plan check: it exists, has task checkboxes, readset in budget')
     .option('--json', 'machine output')
     .action(async (id, o) => {
+      await touchSession(id);
       const r = await (await lib('plan-check')).planCheck(process.cwd(), id);
       out(o.json, r, (x) =>
         x.ok ? `${x.plan}: ${x.done}/${x.tasks} tasks done` : x.problems.join('\n'),
@@ -872,6 +937,7 @@ function registerVerify(gcf) {
     .option('--mark', 'in its worktree: green and committed → commit the GCF-Verified trailer')
     .option('--json', 'machine output')
     .action(async (id, o) => {
+      await touchSession(id);
       const r = o.mark
         ? await (await lib('integrate')).markVerified(process.cwd(), id)
         : await (await lib('verify')).verifyItem(process.cwd(), id);
@@ -1059,6 +1125,7 @@ export function register(program) {
   registerMoves(gcf);
   registerItem(gcf);
   registerItemMoves(gcf);
+  registerSession(gcf);
   registerDecide(gcf);
   registerInbox(gcf);
   registerLive(gcf);

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

package/lib/audit-core.js

@@ -10,6 +10,7 @@ import { buildLedger } from './ledger.js';
 import { STORED } from './transitions.js';
 import { openDepends } from './work-ops.js';
 import { runHolder } from './main-lock.js';
+import { sessionActive } from './session-mark.js';
 
 function git(args, cwd) {
   // A blame of a long file overflows the 1 MiB default, and an overflow reads as a git failure.
@@ -42,7 +43,7 @@ const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  * @property {number} [schema]
  * @property {Array<{id: string, type: string, gate: string, status: string, system: string[],
  *   depends: string[], parent: string | null, tune_count: number, parallel: string,
- *   running: boolean}>} [items]
+ *   priority: number | null, running: boolean}>} [items]
  * @property {{blocking: number, units: number, ready: number}} [design]
  */
 
@@ -96,7 +97,10 @@ export async function audit(projectDir) {
     parent: c.data.parent ?? null,
     tune_count: c.data.tune_count ?? 0,
     parallel: c.data.parallel ?? 'serial',
-    running: runHolder(projectDir, c.data.id) !== null,
+    priority: c.data.priority ?? null,
+    // A harness run's live lock, or an interactive session's fresh mark on main.
+    running:
+      runHolder(projectDir, c.data.id) !== null || sessionActive(projectDir, String(c.data.id)),
   }));
   const design = await designCheck(projectDir);
   checkItems(report, items, config, { projectDir, ledger });

package/lib/board.js

@@ -14,6 +14,8 @@ 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 { listQuestions } from './questions.js';
+import { sessionActive } from './session-mark.js';
 
 // The version of the JSON below (Methodology §11): a board refuses one it does not know. Bump it
 // when a field changes meaning or goes away; a new field does not bump it.
@@ -95,21 +97,6 @@ function verifiedOf(projectDir) {
   }
 }
 
-/** Open question records of open-questions.md: id and class. */
-async function questions(root) {
-  const file = path.join(root, 'open-questions.md');
-  if (!existsSync(file)) return [];
-
-  return (await readFile(file, 'utf8'))
-    .replace(/\r\n/g, '\n')
-    .split(/\n(?=- id:)/)
-    .flatMap((rec) => {
-      const id = rec.match(/^- id:\s*(\S+)/)?.[1];
-
-      return id ? [{ id, class: rec.match(/^\s+class:\s*(\S+)/m)?.[1] ?? null }] : [];
-    });
-}
-
 /** The phase status, or the reason it cannot be read: the board still shows the rest. */
 async function phaseOf(projectDir) {
   try {
@@ -134,7 +121,19 @@ function logOf(projectDir, id) {
 }
 
 // Fields of the item file a board shows as they are: null or [] when the file has none.
-const SCALARS = ['title', 'parent', 'milestone', 'tune_count', 'since', 'model', 'effort'];
+const SCALARS = [
+  'title',
+  'parent',
+  'milestone',
+  'priority',
+  'tune_count',
+  'since',
+  'model',
+  'effort',
+];
+
+// Ranked items first, lower rank sooner; the unranked keep their file order after them.
+const byPriority = (a, b) => (a.priority ?? Infinity) - (b.priority ?? Infinity);
 const LISTS = ['children', 'system', 'depends'];
 
 /** One item of the board. */
@@ -146,6 +145,7 @@ async function itemOf(projectDir, c, verified) {
   // item, is a run; a trailer is a passed DoD.
   const running =
     runHolder(projectDir, id) !== null ||
+    sessionActive(projectDir, id) ||
     (c.data.status === 'ready' && !ready && existsSync(worktreeOf(projectDir, id)));
 
   return {
@@ -173,12 +173,14 @@ export async function board(projectDir) {
   const verified = verifiedOf(projectDir);
   const items = [];
   for (const c of ledger.items) items.push(await itemOf(projectDir, c, verified));
+  items.sort(byPriority);
 
   const config = await readConfig(root);
   const live = await readLive(root);
 
   return {
     schema: BOARD_SCHEMA,
+    run_mode: config.run_mode,
     phase: await phaseOf(projectDir),
     // A malformed block reads with fields missing (live check names it): null, not absent.
     release: releaseOf(live.release),
@@ -188,7 +190,7 @@ export async function board(projectDir) {
     items,
     wip: wipOf(ledger.items, config),
     inbox: await listInbox(root),
-    questions: await questions(root),
+    questions: await listQuestions(root),
     history: await historyOf(root),
     graveyard: await graveyardOf(root),
   };

package/lib/design-check.js

@@ -121,7 +121,13 @@ function itemsIn(text, key) {
 export const recordsIn = (text, key) =>
   readRecords(itemsIn(text, key)).records.map((r) => r.values);
 
-/** open-questions.md: every record id, every `blocks:` reference, the D1 ones per blocked id. */
+/** A D1 record nobody answered yet: only such a question holds its units. */
+const blocksUnits = (rec) => /^\s+class:\s*D1\b/m.test(rec) && !/^\s+answer:/m.test(rec);
+
+/**
+ * open-questions.md: every record id, every `blocks:` reference, the D1 ones per blocked id. A
+ * D1 the human answered (`answer:`) blocks no more: the next agent on the unit applies it.
+ */
 export function questionBlocks(text) {
   /** @type {Map<string, string[]>} */
   const d1 = new Map();
@@ -133,7 +139,7 @@ export function questionBlocks(text) {
     const ids = listOf(rec.match(/^\s+blocks:\s*(.+)$/m)?.[1] ?? '');
     if (!qid || ids === 'TBD' || !ids.length) continue;
     refs.push({ qid, ids });
-    if (!/^\s+class:\s*D1\b/m.test(rec)) continue;
+    if (!blocksUnits(rec)) continue;
     for (const id of ids) d1.set(id, [...(d1.get(id) ?? []), qid]);
   }
 

package/lib/gcf-paths.js

@@ -26,7 +26,27 @@ export function gcfRoot(projectDir = process.cwd()) {
   return root;
 }
 
+// How a harness run drives an item (Methodology §7): `worktree` — each in its own copy, several
+// at once; `main` — one at a time in the project's own folder, for an agent that works through
+// a running editor bound to that folder. The project chooses; the framework knows no engine.
+export const RUN_MODES = ['worktree', 'main'];
+
+function runModeOf(v = 'worktree') {
+  if (!RUN_MODES.includes(v))
+    throw new Error(`gcf/config.yml: run_mode must be ${RUN_MODES.join(' | ')}, got ${v}`);
+
+  return v;
+}
+
+/** @returns {Promise<Record<string, any>>} */
 export async function readConfig(root) {
+  const config = await readNumbers(root);
+
+  return { ...config, run_mode: runModeOf(config.run_mode) };
+}
+
+/** @returns {Promise<Record<string, any>>} */
+async function readNumbers(root) {
   const file = path.join(root, 'config.yml');
   if (!existsSync(file)) return { ...DEFAULT_CONFIG };
   const parsed = YAML.parse(await readFile(file, 'utf8')) ?? {};

package/lib/integrate.js

@@ -27,7 +27,7 @@ function git(cwd, args, { check = true } = {}) {
 }
 
 /** `.gcf-session/` stays out of `git status` without a tracked .gitignore change. */
-async function excludeSession(projectDir) {
+export async function excludeSession(projectDir) {
   const common = path.resolve(projectDir, git(projectDir, ['rev-parse', '--git-common-dir']).out);
   const file = path.join(common, 'info', 'exclude');
   const text = existsSync(file) ? await readFile(file, 'utf8') : '';

package/lib/questions.js

@@ -0,0 +1,95 @@
+// gcf/open-questions.md (GCF-PRD §11.8): the questions only the human answers (D1) and the
+// agent's own assumptions (D2). An answer is written into the record itself: an answered D1
+// blocks no unit, and the next agent on the unit puts the answer into its slot (provenance
+// `answer: q-NNN`) and removes the record.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { atomicWrite } from './safe-path.js';
+import { commitMove } from './unit-ops.js';
+
+const FIELDS = ['class', 'question', 'proposed', 'blocks', 'answer'];
+
+const fileOf = (root) => path.join(root, 'open-questions.md');
+
+/**
+ * The records of a file's text, each `{id, text, start}`: a `- id:` line and the indented lines
+ * under it. A blank or unindented line ends the record: a heading after the last record is not
+ * part of it.
+ */
+function recordsOf(text) {
+  const records = [];
+  let at = 0;
+  /** @type {{id: string, text: string, start: number} | null} */
+  let rec = null;
+  for (const line of text.split(/(?<=\n)/)) {
+    const id = line.match(/^- id:\s*(\S+)/)?.[1];
+    if (id) records.push((rec = { id, text: line, start: at }));
+    else if (rec && /^[ \t]+\S/.test(line)) rec.text += line;
+    else rec = null;
+    at += line.length;
+  }
+
+  return records;
+}
+
+/**
+ * Every question: id, class, the question, the proposed answer, the ids it blocks and the
+ * human's answer, each null when the record has none.
+ */
+export async function listQuestions(root) {
+  const file = fileOf(root);
+  if (!existsSync(file)) return [];
+
+  return recordsOf(await readFile(file, 'utf8')).map(({ id, text }) => ({
+    id,
+    ...Object.fromEntries(
+      FIELDS.map((k) => [
+        k,
+        text.match(new RegExp(`^[ \\t]+${k}:[ \\t]*(.*?)\\s*$`, 'm'))?.[1] || null,
+      ]),
+    ),
+  }));
+}
+
+/** The record text with its `answer:` set: an old answer is replaced, a new one appended. */
+function withAnswer(record, answer) {
+  const eol = record.includes('\r\n') ? '\r\n' : '\n';
+  const indent = record.match(/^([ \t]+)\w+:/m)?.[1] || '  ';
+  const line = `${indent}answer: ${answer}`;
+  // A function, not a string: `$&` in the operator's answer is text, not a pattern.
+  if (/^[ \t]+answer:/m.test(record))
+    return record.replace(/^[ \t]+answer:.*?(?=\r?$)/m, () => line);
+  const body = record.replace(/(\r?\n)+$/, '');
+
+  return `${body}${eol}${line}${record.slice(body.length) || eol}`;
+}
+
+/**
+ * The human answers question `qid` (`gcf question answer`): the answer goes into its record, one
+ * line, and commits as `gcf(answer): <qid>`. Refuses an id the file does not hold.
+ */
+export async function answerQuestion(projectDir, qid, answer, { commit = true } = {}) {
+  const text = String(answer ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!text) throw new Error('an answer needs text');
+  const file = fileOf(path.join(path.resolve(projectDir), 'gcf'));
+  const old = existsSync(file) ? await readFile(file, 'utf8') : '';
+  const rec = recordsOf(old).find((r) => r.id === qid);
+  if (!rec) throw new Error(`${qid} is not a record of gcf/open-questions.md`);
+
+  const hash = await commitMove(projectDir, `gcf(answer): ${qid}`, {
+    files: [file],
+    mutate: () =>
+      atomicWrite(
+        file,
+        old.slice(0, rec.start) +
+          withAnswer(rec.text, text) +
+          old.slice(rec.start + rec.text.length),
+      ),
+    commit,
+  });
+
+  return { id: qid, answer: text, hash };
+}

package/lib/session-mark.js

@@ -0,0 +1,52 @@
+// An agent session working an item in the main checkout (Methodology §4: `running`). A harness
+// run holds a lock with its pid; an interactive session has no process the core can see, so
+// `/gcf-run` claims the item with a mark, the session's own gcf commands on the item keep it
+// fresh (and so do a harness run on main and the harness's readset-guard hook on each read),
+// and the move that ends the run clears it. A mark nobody refreshed for SESSION_TTL_MS is a
+// session that stopped: the item reads as not running again.
+import { existsSync, rmSync, statSync, utimesSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { excludeSession } from './integrate.js';
+
+// A run's default timeout: an agent can implement for long without a gcf command. The harness
+// and its readset-guard hook refresh a live session's mark meanwhile.
+export const SESSION_TTL_MS = 120 * 60_000;
+
+const markOf = (projectDir, id) =>
+  path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${id}.session`);
+
+/** Mark item `id` as worked by this session. */
+export async function claimSession(projectDir, id) {
+  const file = markOf(projectDir, id);
+  await excludeSession(projectDir);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${new Date().toISOString()}\n`);
+}
+
+/** Keep a session's mark fresh: its own commands on the item call this; no mark, no-op. */
+export function touchSession(projectDir, id) {
+  const file = markOf(projectDir, id);
+  try {
+    const now = new Date();
+    utimesSync(file, now, now);
+  } catch {
+    // No mark: no session claimed the item.
+  }
+}
+
+/** Clear the mark: the session ended its run, or gave up. */
+export function releaseSession(projectDir, id) {
+  rmSync(markOf(projectDir, id), { force: true });
+}
+
+/** Whether a session works the item now: a mark refreshed within SESSION_TTL_MS. */
+export function sessionActive(projectDir, id) {
+  const file = markOf(projectDir, id);
+  if (!existsSync(file)) return false;
+  try {
+    return Date.now() - statSync(file).mtimeMs < SESSION_TTL_MS;
+  } catch {
+    return false;
+  }
+}

package/lib/validate-item.js

@@ -56,6 +56,7 @@ const FIELDS = [
   'reopens',
   'milestone',
   'parallel',
+  'priority',
   'plan',
   'tune_count',
   'severity',
@@ -146,6 +147,9 @@ const RULES = {
   reopens: (v) => nullable(isSlug)(v) || 'reopens must name the id it reworks, or null',
   milestone: (v) => nullable(isSlug)(v) || 'milestone must be a milestone name or null',
   parallel: (v) => ['ok', 'serial'].includes(v) || 'parallel must be ok or serial',
+  priority: (v) =>
+    nullable((x) => Number.isInteger(x) && x >= 1)(v) ||
+    'priority must be a rank, an integer >= 1 (lower runs sooner), or null',
   plan: (v) => nullable(isText)(v) || 'plan must be a path or null',
   tune_count: (v) => (Number.isInteger(v) && v >= 0) || 'tune_count must be an integer >= 0',
   severity: (v) =>

package/lib/work-ops.js

@@ -38,6 +38,7 @@ import {
 import { dropInbox } from './inbox.js';
 import { refuseByPhase } from './phase.js';
 import { runHolder } from './main-lock.js';
+import { releaseSession, sessionActive } from './session-mark.js';
 
 /**
  * Options of a committed move; each move reads the ones it needs.
@@ -173,6 +174,13 @@ async function begin(projectDir, id, move) {
       `${id} is driven by a harness run (pid ${run}): wait until that run ends; if no harness ` +
         `run is going, delete .gcf-session/runs/${id}.lock`,
     );
+  // 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)
+    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`,
+    );
   const files = [item.file];
   const steps = [];
   const liveOps = [];
@@ -202,13 +210,18 @@ async function begin(projectDir, id, move) {
 }
 
 /** Commit the move as `gcf(<move>): <tail>` with every file it touched (item edits included). */
-const finish = (m, move, tail, commit) =>
-  commitMove(m.projectDir, `gcf(${move}): ${tail}`, {
+async function finish(m, move, tail, commit) {
+  const hash = await commitMove(m.projectDir, `gcf(${move}): ${tail}`, {
     files: m.files,
     mutate: m.run,
     commit,
     inputs: [m.item.file],
   });
+  // A move on the item ends the session that worked it: the board stops showing it running.
+  releaseSession(m.projectDir, String(m.item.data.id));
+
+  return hash;
+}
 
 const writeItem = (item, data, body = item.body) => atomicWrite(item.file, serialize(data, body));
 
@@ -742,7 +755,10 @@ function checkRelease(spec) {
 
 const RUN_KEYS = ['model', 'effort'];
 
-/** The model and effort a new item gives: the run passes them to the agent's command line. */
+/**
+ * How a new item runs: its model and effort (the run passes them to the agent's command line)
+ * and its rank among the items.
+ */
 function runFields(spec) {
   for (const k of RUN_KEYS)
     if (spec[k] !== undefined && !RUN_WORD.test(spec[k]))
@@ -750,8 +766,13 @@ function runFields(spec) {
         `--${k} is one word that starts with a letter or a digit ` +
           '(then letters, digits, dots, hyphens, underscores), e.g. opus',
       );
+  const { priority } = spec;
+  if (priority !== undefined && !(Number.isInteger(priority) && priority >= 1))
+    throw new Error('--priority is a rank: an integer from 1 (lower runs sooner)');
 
-  return Object.fromEntries(RUN_KEYS.filter((k) => spec[k]).map((k) => [k, spec[k]]));
+  return Object.fromEntries(
+    [...RUN_KEYS, 'priority'].filter((k) => spec[k] !== undefined).map((k) => [k, spec[k]]),
+  );
 }
 
 /** Refuse a spec `item new` cannot honour; returns the gate the item gets. */
@@ -830,6 +851,47 @@ function newItemText(spec, gate, since) {
   return serialize(data, body);
 }
 
+/**
+ * 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 } = {}) {
+  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);
+  const items = ids.map((id) => {
+    const item = ledger.item(id);
+    if (!item) throw new Error(`${id} is not a work item`);
+
+    return item;
+  });
+  // A ranked ready item left out of the list (a running one, whose file its run may be editing)
+  // keeps its rank: the listed items take the free ranks around it, so no rank is held twice.
+  const held = new Set(
+    ledger.items
+      .filter((i) => i.data.status === 'ready' && !ids.includes(String(i.data.id)))
+      .map((i) => i.data.priority)
+      .filter(Boolean),
+  );
+  let rank = 0;
+  const ranks = ids.map(() => {
+    do rank++;
+    while (held.has(rank));
+
+    return rank;
+  });
+  const hash = await commitMove(projectDir, `gcf(priority): ${ids.join(', ')}`, {
+    files: items.map((i) => i.file),
+    mutate: async () => {
+      for (const [n, i] of items.entries())
+        await atomicWrite(i.file, serialize({ ...i.data, priority: ranks[n] }, i.body));
+    },
+    commit,
+  });
+
+  return { ids, hash };
+}
+
 /**
  * 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.

package/package.json

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

package/skills/gcf-card/SKILL.md

@@ -18,11 +18,12 @@ preconditions:
 forbidden_behaviors:
 - do not invent a new subsystem name when INDEX carries a synonym: reuse or ask
 - do not answer a `TBD` yourself: ask the human, and offer your draft as the proposed answer
-- do not take a unit an open D1 blocks: `ai-factory gcf design check` names the blocking question, and the human answers it first
+- do not take a unit an open D1 blocks: `ai-factory gcf design check` names the blocking question, and the human answers it first (`ai-factory gcf question answer <q-id> --text="<answer>"`, or on the board)
 - do not write a digit in prose: a number is an envelope `a..b <unit>` in `feel` or a closing comparison
 - do not put `until:` in the frontmatter: it is a line annotation inside slots
 - do not move a section, edit the backlog or write `status:` by hand: `ai-factory gcf take`, `item new`, `done`, `drop` and the item moves own those
 - do not reuse an id: an ended id stays ended; rework gets a new id with `reopens: <old id>`
+- do not put an id in `depends` for order alone: `depends` names an item whose data or code this one uses, and order goes in `priority`
 - do not remove a D2 record cited as `assumed: q-NNN`: it stays in `gcf/open-questions.md` until its `until:` fires; when the human confirms the value earlier, rewrite each citation to `answer: q-NNN` first
 
 outputs:
@@ -43,11 +44,15 @@ workflow:
 10. for `pillars: TBD` propose the ids from `gcf/PILLARS.md` whose statement the unit serves and whose invariant it keeps
 11. when no pillar fits, ask whether the unit is out of scope or a pillar is missing, and write a D1 question for the answer
 12. write each answer into the unit in place, with its `answer:` provenance record
-13. run `ai-factory gcf design check --json` until the unit's entry in `units` reads `ready: true`, then commit the answered unit
-14. run `ai-factory gcf take <id>` for one unit, or `ai-factory gcf take <id> <id> --feature <feature-id>` to group several under a feature; it writes `gcf/work/<id>.md` and removes the sections and backlog lines in one step
-15. in each mechanic or resource item write `contract:` from the code tree and `interactions:` from the units and items that write the same state; a soft unit whose human wants no playtest gets `gate: auto` - it will close as unplayed
-16. write the item's `live:` delta (a feature's children keep `none: parent`; the feature writes the capability), run `ai-factory gcf design check`, and commit
-17. report the item paths, each item's gate, and for a verdict item the one question the playtest will answer
+13. a record of `gcf/open-questions.md` that carries the human's `answer:` and names this unit in `blocks:` goes into its slot with `answer: q-NNN`; the record then leaves the file
+14. run `ai-factory gcf design check --json` until the unit's entry in `units` reads `ready: true`, then commit the answered unit
+15. run `ai-factory gcf take <id>` for one unit, or `ai-factory gcf take <id> <id> --feature <feature-id>` to group several under a feature; it writes `gcf/work/<id>.md` and removes the sections and backlog lines in one step
+16. in each mechanic or resource item write `contract:` from the code tree and `interactions:` from the units and items that write the same state; a soft unit whose human wants no playtest gets `gate: auto` - it will close as unplayed
+17. write the item's `live:` delta (a feature's children keep `none: parent`; the feature writes the capability), run `ai-factory gcf design check`, and commit
+18. when the work is several items (a feature's children, or a batch), cut them along subsystem boundaries: each a thin slice that builds and tests alone
+19. two items of one subsystem that change different files get `parallel: ok`, and their `contract:` or `intent:` names those files
+20. rank the items with `ai-factory gcf prioritize <id> <id> …`: dependencies first, then by value
+21. report the item paths, each item's gate, and for a verdict item the one question the playtest will answer
 
 invocation:
 - run when work starts on a unit or a group of units, when non-design work needs an item, or when a fresh idea needs a home

package/templates/agents-block.md

@@ -19,6 +19,8 @@ gcf_work:
 - a release item carries `version:` and `channel:` (`item new <id> --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
 - `item new` and `take` refuse a type the current phase does not take: run `ai-factory gcf phase` and bring the refusal to the human
 - an item the human wants run on a given model or effort gets `item new <id> --model <m> --effort <e>`: the harness run passes both to the agent
+- ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`, and put an id in `depends` only when the item uses that one's data or code
+- a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
 - a pillar changes only on the human's word: `ai-factory gcf pillar rename <from> <to>`, or `ai-factory gcf pillar retire <id> --reason "<why>"`
 
 gcf_forbidden: