gcf-aif-ext 0.5.3 → 0.7.0

package/README.md

@@ -50,6 +50,23 @@ 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`.
+- `item new --model <m> --effort <e>`: the run of the item uses them (gcf-harness-aif-ext 0.7). One word each.
+- `playtest session --json` and `live check --json` answer JSON: the flag went to the parent command, which printed text.
+- `--commit` on `item new`, `inbox add` and `inbox drop` records the move alone (`gcf(item): <id>`, `gcf(inbox): …`) for a caller with no console, a board. Without it nothing is committed, as before. Inbox lines added earlier without a commit go into the same commit: the inbox is raw input.
+- `inbox add --text=<text>`: a text that starts with a hyphen ("-5 fps on level 3") reads as a flag at every level of ai-factory's commands, `--` included.
+
 ### 0.5.3
 
 - `gcf init` restamps an unplayed item frozen by 0.4.0 (the hash of its body alone), so its `live:` is guarded too — only while that `live:` is still the one its close committed. Commit the restamped items it names.

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.
@@ -321,7 +356,8 @@ function registerPlaytest(gcf) {
       const r = await (
         await lib('playtest-list')
       ).playtestSession(process.cwd(), { build: Boolean(o.build) });
-      out(o.json, r, sessionText);
+      // Commander gives a flag both levels define to the parent: `playtest session --json`.
+      out(o.json || playtest.opts().json, r, sessionText);
       if (r.build && !r.build.ok) process.exitCode = 1;
     });
 }
@@ -643,6 +679,10 @@ 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')
     .action(async (id, o) => {
       const { newItem } = await lib('work-ops');
       const r = await newItem(process.cwd(), {
@@ -660,18 +700,45 @@ function registerItem(gcf) {
         milestone: o.milestone,
         version: o.release,
         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);
+      console.log(`${r.item}${shortHash(r.hash)}`);
     });
 }
 
 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)}`);
     });
@@ -684,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 });
@@ -716,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 });
@@ -736,6 +807,36 @@ function registerDecide(gcf) {
     });
 }
 
+/**
+ * An inbox edit; with `commit`, committed alone under the main lock — a board has no console to
+ * commit from. Returns the commit hash, or null.
+ * @param {boolean | undefined} commit
+ * @param {string} message
+ * @param {(root: string) => Promise<unknown>} edit
+ */
+async function inboxMove(commit, message, edit) {
+  const { gcfRoot } = await lib('gcf-paths');
+  const root = gcfRoot();
+  if (!commit) {
+    await edit(root);
+
+    return null;
+  }
+
+  const { commitMove } = await lib('unit-ops');
+  const inbox = path.join(root, 'inbox.md');
+
+  // Raw input (merge=union): lines added before without a commit ride along with this one.
+  return commitMove(process.cwd(), message, {
+    files: [inbox],
+    inputs: [inbox],
+    mutate: async () => {
+      await edit(root);
+    },
+    commit: true,
+  });
+}
+
 function registerInbox(gcf) {
   const inbox = gcf
     .command('inbox')
@@ -749,21 +850,34 @@ function registerInbox(gcf) {
       );
     });
   inbox
-    .command('add <text>')
+    .command('add [text]')
     .description('Append an entry')
     .option('--source <source>', 'playtest | ci | agent | operator', 'operator')
-    .action(async (text, o) => {
-      const { gcfRoot } = await lib('gcf-paths');
-      const e = await (await lib('inbox')).addInbox(gcfRoot(), text, o.source);
-      console.log(e.id);
+    // A text that starts with a hyphen ("-5 fps on level 3") reads as a flag at every level of
+    // ai-factory's commands, `--` included: as `--text=<text>` it stays one value.
+    .option('--text <text>', 'the entry, when it starts with a hyphen')
+    .option('--commit', 'commit it (gcf(inbox)): for a caller with no console, e.g. a board')
+    .action(async (arg, o) => {
+      const text = o.text ?? arg;
+      if (!text || (o.text !== undefined && arg !== undefined))
+        throw new Error('give the entry once: as the argument, or as --text=<text>');
+      const { addInbox } = await lib('inbox');
+      let id = '';
+      const hash = await inboxMove(o.commit, 'gcf(inbox): add', async (root) => {
+        id = (await addInbox(root, text, o.source)).id;
+      });
+      console.log(`${id}${shortHash(hash)}`);
     });
   inbox
     .command('drop <in-id>')
     .description('Erase an entry: triaged as noise, a duplicate, or turned into an item')
-    .action(async (id) => {
-      const { gcfRoot } = await lib('gcf-paths');
-      await (await lib('inbox')).dropInbox(gcfRoot(), id);
-      console.log(`erased ${id}`);
+    .option('--commit', 'commit it (gcf(inbox)): for a caller with no console, e.g. a board')
+    .action(async (id, o) => {
+      const { dropInbox } = await lib('inbox');
+      const hash = await inboxMove(o.commit, `gcf(inbox): drop ${id}`, (root) =>
+        dropInbox(root, id),
+      );
+      console.log(`erased ${id}${shortHash(hash)}`);
     });
 }
 
@@ -794,7 +908,7 @@ function registerLive(gcf) {
     .option('--json', 'machine output')
     .action(async (o) => {
       const r = await (await lib('live')).checkLive(process.cwd());
-      out(o.json, r.issues, (l) => (l.length ? l.join('\n') : 'clean'));
+      out(o.json || live.opts().json, r.issues, (l) => (l.length ? l.join('\n') : 'clean'));
       if (r.issues.length) process.exitCode = 1;
     });
 }
@@ -807,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'),
@@ -822,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);
@@ -1009,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.5.3",
+  "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

@@ -12,29 +12,82 @@ import { verifiedBranches, worktreeOf } from './integrate.js';
 import { resolveInside } from './safe-path.js';
 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.
+export const BOARD_SCHEMA = 1;
 
 const COLUMNS = ['ready', 'blocked', 'awaiting-verdict', 'awaiting-decision', 'unplayed', 'parked'];
 
 /**
- * Plan progress `{tasks, done}` from its checkboxes, null without a plan file (§3.3); a plan:
- * outside the project or not a file reads as `{error}`, the rest of the board still shows.
+ * Plan progress `{tasks, done}` from its checkboxes and the plan's project path, both null
+ * without a plan file (§3.3); a plan: outside the project or not a file reads as `{error}`, the
+ * rest of the board still shows.
  */
 async function progress(projectDir, item) {
+  const plan = item.data.plan ?? `.ai-factory/plans/${item.data.id}.md`;
   try {
-    const plan = item.data.plan ?? `.ai-factory/plans/${item.data.id}.md`;
     const file = resolveInside(projectDir, plan);
-    if (!existsSync(file)) return null;
+    if (!existsSync(file)) return { plan: null, plan_file: null };
     const text = await readFile(file, 'utf8');
 
     return {
-      tasks: (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length,
-      done: (text.match(/^\s*- \[[xX]\] /gm) ?? []).length,
+      plan: {
+        tasks: (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length,
+        done: (text.match(/^\s*- \[[xX]\] /gm) ?? []).length,
+      },
+      plan_file: plan,
     };
   } catch (e) {
-    return { error: e.message };
+    return { plan: { error: e.message }, plan_file: null };
   }
 }
 
+/** The lines `- <a> | <b> | …` of a gcf record file, split on the pipes. */
+async function records(root, name) {
+  const file = path.join(root, name);
+  if (!existsSync(file)) return [];
+
+  return (await readFile(file, 'utf8')).split(/\r?\n/).flatMap((l) => {
+    const m = l.match(/^- (\S+)\s*\|(.*)$/);
+
+    return m ? [[m[1], ...m[2].split('|').map((f) => f.trim())]] : [];
+  });
+}
+
+/** history.md: `- <id> | <event> | <date>` (§9). */
+const historyOf = async (root) =>
+  (await records(root, 'history.md')).map(([id, event, date]) => ({
+    id,
+    event: event || null,
+    date: date || null,
+  }));
+
+/**
+ * graveyard.md: `- <id> | <type> | <reason> | tags: <tags>`; a 0.3 line has no type, and its
+ * second field is a type only when it names one (§9).
+ */
+const graveyardOf = async (root) =>
+  (await records(root, 'graveyard.md')).map(([id, ...fields]) => {
+    const tags = fields.at(-1)?.startsWith('tags:') ? fields.pop() : null;
+    const typed = fields.length > 1 && ITEM_TYPES.includes(fields[0]);
+
+    return {
+      id,
+      type: typed ? fields[0] : null,
+      reason: (typed ? fields.slice(1) : fields).join(' | ') || null,
+      tags: (tags ?? '')
+        .slice('tags:'.length)
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean),
+    };
+  });
+
 /** Verified branches; none outside a repository. */
 function verifiedOf(projectDir) {
   try {
@@ -44,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 {
@@ -68,48 +106,92 @@ async function phaseOf(projectDir) {
   }
 }
 
+/** The release block with every field: one a malformed block lacks is null (live check says so). */
+const releaseOf = (r) =>
+  r && {
+    version: r.version,
+    ...Object.fromEntries(['channel', 'date', 'phase'].map((k) => [k, r[k] ?? null])),
+  };
+
+/** The run log of an item, project-relative, or null before its first run. */
+function logOf(projectDir, id) {
+  const log = `.gcf-session/runs/${id}.log`;
+
+  return existsSync(path.join(projectDir, log)) ? log : null;
+}
+
+// Fields of the item file a board shows as they are: null or [] when the file has none.
+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. */
+async function itemOf(projectDir, c, verified) {
+  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);
+  // `running` and `verify` are not stored (§4): a live harness run, or a worktree of a ready
+  // 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 {
+    id,
+    type: c.data.type,
+    gate: c.data.gate,
+    status: c.data.status,
+    ...Object.fromEntries(SCALARS.map((k) => [k, c.data[k] ?? null])),
+    ...Object.fromEntries(LISTS.map((k) => [k, c.data[k] ?? []])),
+    ...(c.data.severity ? { severity: c.data.severity } : {}),
+    ...(c.data.blocked ? { blocked: c.data.blocked } : {}),
+    running,
+    verified: ready,
+    // What a board may offer (§4.1): nothing while a run drives the item.
+    moves: running ? [] : movesOf(c.data),
+    file: `gcf/work/${c.name}`,
+    log: logOf(projectDir, id),
+    ...(await progress(projectDir, c)),
+  };
+}
+
 export async function board(projectDir) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const ledger = await buildLedger(projectDir);
   const verified = verifiedOf(projectDir);
   const items = [];
-  for (const c of ledger.items) {
-    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);
-    items.push({
-      id,
-      type: c.data.type,
-      gate: c.data.gate,
-      status: c.data.status,
-      title: c.data.title ?? null,
-      parent: c.data.parent ?? null,
-      children: c.data.children ?? [],
-      system: c.data.system ?? [],
-      ...(c.data.severity ? { severity: c.data.severity } : {}),
-      ...(c.data.blocked ? { blocked: c.data.blocked } : {}),
-      // `running` and `verify` are not stored (§4): a live harness run, or a worktree of a ready
-      // item, is a run; a trailer is a passed DoD.
-      running:
-        runHolder(projectDir, id) !== null ||
-        (c.data.status === 'ready' && !ready && existsSync(worktreeOf(projectDir, id))),
-      verified: ready,
-      plan: await progress(projectDir, c),
-    });
-  }
+  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),
-    release: live.release,
+    // A malformed block reads with fields missing (live check names it): null, not absent.
+    release: releaseOf(live.release),
     columns: Object.fromEntries(
       COLUMNS.map((s) => [s, items.filter((i) => i.status === s).map((i) => i.id)]),
     ),
     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') : '';
@@ -238,7 +238,7 @@ async function integrateMerged(projectDir, id, item) {
   if (!item || item.data.status !== 'ready' || movedSinceMerge(projectDir, id))
     return { id, skipped: `${branchOf(id)} is in main already`, ...cleanUp(projectDir, id) };
 
-  return { id, ...(await recordMove(projectDir, item)), ...cleanUp(projectDir, id) };
+  return { ...(await recordMove(projectDir, item)), id, ...cleanUp(projectDir, id) };
 }
 
 async function integrateOne(projectDir, id) {
@@ -250,7 +250,7 @@ async function integrateOne(projectDir, id) {
   if (git(projectDir, ancestor, { check: false }).ok) return integrateMerged(projectDir, id, item);
   if (!item || item.data.status !== 'ready')
     return { id, skipped: `${id} is ${item ? item.data.status : 'not a work item'} on main` };
-  if (item.data.type === 'spike') return { id, ...(await integrateSpike(projectDir, item)) };
+  if (item.data.type === 'spike') return { ...(await integrateSpike(projectDir, item)), id };
   const foreign = foreignGcfEdits(projectDir, id);
   if (foreign.length)
     return {
@@ -263,7 +263,7 @@ async function integrateOne(projectDir, id) {
   if (failed) return { id, ...failed };
   const moved = await recordMove(projectDir, (await buildLedger(projectDir)).item(id));
 
-  return { id, ...moved, ...cleanUp(projectDir, id) };
+  return { ...moved, id, ...cleanUp(projectDir, id) };
 }
 
 /**

package/lib/live.js

@@ -66,7 +66,7 @@ export function parseLive(text) {
   /** A record line of capabilities or known-issues; false when the line is not one. */
   const recordLine = (line) => {
     const start = line.match(/^- id:\s*(\S+)\s*$/);
-    if (start && section) {
+    if (start && section && section !== 'release') {
       rec = { id: start[1], summary: '' };
       out[section].push(rec);
 
@@ -106,7 +106,11 @@ const recordText = (r) =>
 
 const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
 
-/** LIVE.md text: records sorted by id, so two branches touching different ids merge cleanly. */
+/**
+ * LIVE.md text: records sorted by id, so two branches touching different ids merge cleanly.
+ * @param {{phase?: string | null, release?: LiveRelease | null, capabilities: LiveRecord[],
+ *   knownIssues: LiveRecord[]}} live
+ */
 export function serializeLive({ phase = null, release = null, capabilities, knownIssues }) {
   const block = (key, list) =>
     `${key}:\n${list.length ? [...list].sort(byId).map(recordText).join('\n') : NONE[key]}\n`;

package/lib/playtest-list.js

@@ -73,7 +73,7 @@ export async function playtestSession(
     commit: git(projectDir, ['rev-parse', '--short', 'HEAD']),
     // No commit (no repository, or none yet): the build is unknown, not clean.
     dirty: dirty === null ? null : Boolean(dirty),
-    build: null,
+    build: /** @type {ReturnType<typeof runDod> | null} */ (null),
     items,
   };
   if (build) session.build = runDod(projectDir, await readConfig(root), 'build', stdio);

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/transitions.js

@@ -37,6 +37,31 @@ export function allowedFrom(move, status) {
 /** Statuses `move` starts from, for error messages. */
 export const fromOf = (move) => FROM[move] ?? [];
 
+export const FEATURE_ONLY = ['close', 'continue', 'kill'];
+const BUG_ONLY = ['wontfix', 'known'];
+
+/** Whether a decision fits an item's type: a feature has its own, wontfix and known a bug's. */
+export const decisionFits = (choice, type) =>
+  FEATURE_ONLY.includes(choice) === (type === 'feature') &&
+  (!BUG_ONLY.includes(choice) || type === 'bug');
+
+/** Whether a move fits the item beyond its status: its gate for submit and close, its type. */
+function fits(move, { type, gate }) {
+  const [cmd, arg] = move.split(':');
+  if (cmd === 'submit') return gate !== 'auto';
+  if (cmd === 'close') return gate === 'auto';
+
+  return cmd !== 'decide' || decisionFits(arg, type);
+}
+
+/**
+ * The moves an item may take now (§4.1), named as `allowedFrom` names them: `verdict:keep`,
+ * `decide:go`, `unblock`… A board offers these and nothing else; each command still checks the
+ * rest itself (dependencies, a live: delta, the tune limit).
+ */
+export const movesOf = (data) =>
+  Object.keys(FROM).filter((m) => allowedFrom(m, data.status) && fits(m, data));
+
 /** A status an item FILE may carry. */
 export function isStorable(status) {
   return STORED.includes(status);

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

@@ -11,9 +11,8 @@ import path from 'node:path';
 import { parse, serialize } from './frontmatter.js';
 import { buildLedger } from './ledger.js';
 import { readConfig } from './gcf-paths.js';
-import { atomicWrite, withFileRollback } from './safe-path.js';
-import { writeIndex } from './index-gen.js';
-import { allowedFrom, fromOf } from './transitions.js';
+import { atomicWrite } 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';
 import { commitMove, addConstraints } from './unit-ops.js';
@@ -39,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.
@@ -174,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 = [];
@@ -203,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));
 
@@ -646,10 +658,9 @@ const DECIDE = {
   },
   kill: killFeature,
 };
-const FEATURE_ONLY = ['close', 'continue', 'kill'];
-
 /** Refuse a decision that does not fit the item's type. */
 function fitDecision(choice, item) {
+  if (decisionFits(choice, item.data.type)) return;
   const feature = item.data.type === 'feature';
   if (FEATURE_ONLY.includes(choice) !== feature)
     throw new Error(
@@ -657,8 +668,7 @@ function fitDecision(choice, item) {
         ? `${item.data.id} is a feature: decide close | continue | kill`
         : `decide ${choice} is for a feature; ${item.data.id} is a ${item.data.type}`,
     );
-  if (['wontfix', 'known'].includes(choice) && item.data.type !== 'bug')
-    throw new Error(`decide ${choice} is for a bug; ${item.data.id} is a ${item.data.type}`);
+  throw new Error(`decide ${choice} is for a bug; ${item.data.id} is a ${item.data.type}`);
 }
 
 /** The operator's decisions (Methodology §4.1): spikes, decision items, bugs and features.
@@ -727,6 +737,9 @@ export async function dropItem(projectDir, id, opts = {}) {
   return { id, hash: await finish(m, 'drop', id, commit), removal };
 }
 
+// A leading hyphen would read as a flag of the agent's command line.
+export const RUN_WORD = /^[A-Za-z0-9][\w.-]*$/;
+
 /** The version and channel of a new item: well-formed, and only on a release. */
 function checkRelease(spec) {
   const { type, version, channel } = spec;
@@ -740,6 +753,28 @@ function checkRelease(spec) {
     throw new Error('--release and --channel belong to a release item');
 }
 
+const RUN_KEYS = ['model', 'effort'];
+
+/**
+ * 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]))
+      throw new Error(
+        `--${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, 'priority'].filter((k) => spec[k] !== undefined).map((k) => [k, spec[k]]),
+  );
+}
+
 /** Refuse a spec `item new` cannot honour; returns the gate the item gets. */
 function checkNew(ledger, spec) {
   const { id, type, gate, severity } = spec;
@@ -790,6 +825,7 @@ function optionalFields(spec, gate, since) {
     ...(spec.milestone ? { milestone: spec.milestone } : {}),
     ...(spec.version ? { version: spec.version } : {}),
     ...(spec.channel ? { channel: spec.channel } : {}),
+    ...runFields(spec),
     ...(live ? { live } : {}),
   };
 }
@@ -815,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.
@@ -838,14 +915,18 @@ export async function newItem(projectDir, spec) {
     writes.push([p.file, serialize({ ...p.data, children }, p.body)]);
   }
 
-  await withFileRollback(
-    [...writes.map((w) => w[0]), path.join(root, 'inbox.md'), path.join(root, 'INDEX.md')],
-    async () => {
+  // `commit` is for a caller with no console to commit from, a board: a run starts from HEAD.
+  // The inbox is raw input (merge=union): lines added without a commit ride along with it.
+  const inbox = spec.from ? [path.join(root, 'inbox.md')] : [];
+  const hash = await commitMove(projectDir, `gcf(item): ${spec.id}`, {
+    files: [...writes.map((w) => w[0]), ...inbox],
+    inputs: inbox,
+    mutate: async () => {
       for (const [f, text] of writes) await atomicWrite(f, text);
       if (spec.from) await dropInbox(root, spec.from);
-      await writeIndex(root);
     },
-  );
+    commit: spec.commit ?? false,
+  });
 
-  return { item: `gcf/work/${spec.id}.md` };
+  return { item: `gcf/work/${spec.id}.md`, hash };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.5.3",
+  "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

@@ -6,7 +6,7 @@ gcf_context:
 
 gcf_work:
 - every piece of work is one work item `gcf/work/<id>.md`: find the item before writing code for a feature, a bug or a tech task, or create it with the gcf-card skill
-- a raw idea, a playtest note or a CI finding that is not work yet goes to `ai-factory gcf inbox add "<text>"`, and the gcf-triage skill sorts it later
+- a raw idea, a playtest note or a CI finding that is not work yet goes to `ai-factory gcf inbox add "<text>"`, and the gcf-triage skill sorts it later; a text that starts with a hyphen goes as `inbox add --text="<text>"`
 - before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
 - drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
 - after the code, write the item's `live:` delta and run `ai-factory gcf verify <id>`: fix what it reports and run it again until every check is green
@@ -18,6 +18,9 @@ gcf_work:
 - the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --source playtest "<note>"`
 - 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: