gcf-aif-ext 0.5.3 → 0.6.0

package/README.md

@@ -50,6 +50,14 @@ 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.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

@@ -321,7 +321,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 +644,9 @@ 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('--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,8 +664,11 @@ function registerItem(gcf) {
         milestone: o.milestone,
         version: o.release,
         channel: o.channel,
+        model: o.model,
+        effort: o.effort,
+        commit: o.commit === true,
       });
-      console.log(r.item);
+      console.log(`${r.item}${shortHash(r.hash)}`);
     });
 }
 
@@ -736,6 +743,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 +786,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 +844,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;
     });
 }

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

package/lib/board.js

@@ -12,29 +12,80 @@ 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';
+
+// 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 {
@@ -68,42 +119,69 @@ 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', 'tune_count', 'since', 'model', 'effort'];
+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 ||
+    (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));
 
   const config = await readConfig(root);
   const live = await readLive(root);
 
   return {
+    schema: BOARD_SCHEMA,
     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)]),
     ),
@@ -111,5 +189,7 @@ export async function board(projectDir) {
     wip: wipOf(ledger.items, config),
     inbox: await listInbox(root),
     questions: await questions(root),
+    history: await historyOf(root),
+    graveyard: await graveyardOf(root),
   };
 }

package/lib/integrate.js

@@ -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/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/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';
@@ -646,10 +645,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 +655,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 +724,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 +740,20 @@ function checkRelease(spec) {
     throw new Error('--release and --channel belong to a release item');
 }
 
+const RUN_KEYS = ['model', 'effort'];
+
+/** The model and effort a new item gives: the run passes them to the agent's command line. */
+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',
+      );
+
+  return Object.fromEntries(RUN_KEYS.filter((k) => spec[k]).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 +804,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 } : {}),
   };
 }
@@ -838,14 +853,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.6.0",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",

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,7 @@ 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
 - 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: