gcf-aif-ext 0.9.0 → 0.10.0

package/README.md

@@ -50,6 +50,12 @@ 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.10.0
+
+- `gcf board --json` is `schema: 3`: `domain` describes the whole GCF domain for a board (Methodology §11, Board-PRD decision 16). It names the harness (`gcf-harness` when the project has gcf-harness-aif-ext, else null), the agent's move `run` (offered first in `items[].moves` to a ready item without a green verify, only with the harness), every move's form with its full `ai-factory` words (`gcf …`) — the new item, the phase, the inbox, the answers, the run order and `depends` included —, the item's fields for the card and the drawer, its blocks (`sections`) and the Help terms. `depends` is offered to every item; `waits_for` is empty while a run drives the item. gcf-board 0.4.0 reads it; update both together.
+- `gcf config set language.ui --value=ru` (and `language.artifacts`) sets the agents' language in AI Factory's `.ai-factory/config.yaml`: that key only, its comments kept, one `gcf(config)` commit (an uncommitted file is committed whole; a file git ignores is written, not committed, with a warning). An empty value takes the key off. `gcf config` and the board's settings list them.
+- AGENTS.md: agents leave the language to the human. Run `ai-factory gcf init` after the update.
+
 ### 0.9.0
 
 - `gcf board --json` is `schema: 2`. The new `domain` field gives the board its columns in order (label, tooltip), the status runs start from, and the form of every item move: label, tooltip, command words, fields, and the drop zone that means it (Methodology §11, Board-PRD decision 16). The `columns` map (status → ids) is gone: filter `items` by `status`. gcf-board reads it from 0.3.0 on; an older board refuses schema 2, and gcf-board 0.3.0 refuses an older core: update both together.

package/commands/gcf.js

@@ -1130,14 +1130,14 @@ function registerBoard(gcf) {
 function registerSettings(gcf) {
   const config = gcf
     .command('config')
-    .description("The human's settings of gcf/config.yml: list them, or set one (commit)")
+    .description("The human's settings and the agents' language: list them, or set one (commit)")
     // A misspelt subcommand would read as a stray word and list the settings, as if set.
     .allowExcessArguments(false)
     .option('--json', 'machine output')
     .action(async (o) => {
-      const { gcfRoot, readConfig, readRawConfig } = await lib('gcf-paths');
+      const { gcfRoot, readConfig } = await lib('gcf-paths');
       await readConfig(gcfRoot()); // a config the rules refuse says so here
-      const list = (await lib('config-set')).settingsOf(await readRawConfig(gcfRoot()));
+      const list = await (await lib('config-set')).projectSettings(process.cwd());
       out(o.json, list, (x) =>
         x.map((s) => `${s.key}: ${s.value ?? '-'}  # ${s.label}`).join('\n'),
       );
@@ -1157,7 +1157,11 @@ function registerSettings(gcf) {
         commit: o.commit,
       });
       const now = `${r.key}: ${r.value ?? 'default'}`;
-      console.log(r.unchanged ? `${now} (unchanged)` : `${now}${shortHash(r.hash)}`);
+      // An ignored file is written but not committed: a worktree's agent does not read it.
+      const note = r.ignored
+        ? ' (git ignores the file: not committed, and agents in a worktree will not see it)'
+        : '';
+      console.log(r.unchanged ? `${now} (unchanged)` : `${now}${shortHash(r.hash)}${note}`);
     });
   const many = (v, prev = []) => [...prev, v];
   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.9.0",
+  "version": "0.10.0",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/lib/aif-config.js

@@ -1,22 +1,40 @@
 // The language AI Factory sets in `.ai-factory/config.yaml` for what an agent writes to the
 // human: `language.ui`. GCF adds no setting of its own (Methodology §5.2.3); agents read the
-// file themselves, the core reads it only for the prompts it writes.
+// file themselves, the core reads it for the prompts it writes and sets it for the board
+// (`gcf config set language.ui`).
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import YAML from 'yaml';
 
+/** AI Factory's config file, project-relative. */
+export const AIF_CONFIG = '.ai-factory/config.yaml';
+
+// A language name or code, one word in any script: anything else would break the prompt line it
+// goes in.
+export const LANGUAGE_RE = /^[\p{L}\p{N}_-]{2,32}$/u;
+
 /**
- * The project's `language.ui`, `en` by default. A missing or unreadable file gives `en`: the
- * language is a preference, and a broken one must not stop the work.
+ * `.ai-factory/config.yaml` as the file has it: `{}` when it is missing, unreadable or not a
+ * map. The language is a preference, and a broken file must not stop the work.
+ * @returns {Promise<Record<string, any>>}
  */
-export async function uiLanguage(projectDir) {
+export async function readAifConfig(projectDir) {
   try {
-    const file = path.join(path.resolve(projectDir), '.ai-factory', 'config.yaml');
-    const ui = YAML.parse(await readFile(file, 'utf8'))?.language?.ui;
+    const raw = YAML.parse(await readFile(path.join(path.resolve(projectDir), AIF_CONFIG), 'utf8'));
 
-    // A language name or code, one word: anything else would break the prompt line it goes in.
-    return typeof ui === 'string' && /^[\w-]{2,32}$/.test(ui.trim()) ? ui.trim() : 'en';
+    return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
   } catch {
-    return 'en';
+    return {};
   }
 }
+
+/** A language of the parsed file (`ui`, `artifacts`), or null when it holds no language. */
+export function languageIn(aif, key) {
+  const v = aif?.language?.[key];
+
+  return typeof v === 'string' && LANGUAGE_RE.test(v.trim()) ? v.trim() : null;
+}
+
+/** The project's `language.ui`, `en` by default or when the value is no language. */
+export const uiLanguage = async (projectDir) =>
+  languageIn(await readAifConfig(projectDir), 'ui') ?? 'en';

package/lib/board.js

@@ -5,7 +5,7 @@ import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { buildLedger } from './ledger.js';
-import { readConfig, readRawConfig } from './gcf-paths.js';
+import { readConfig } from './gcf-paths.js';
 import { readLive } from './live.js';
 import { listInbox } from './inbox.js';
 import { phaseStatus } from './phase.js';
@@ -14,16 +14,17 @@ 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 { domainOf, movesOf } from './transitions.js';
+import { movesOf } from './transitions.js';
+import { domainOf, hasHarness, RUNS_FROM } from './domain.js';
 import { openDepends } from './work-ops.js';
 import { listQuestions } from './questions.js';
 import { sessionActive } from './session-mark.js';
 import { agentOf } from './agent-permissions.js';
-import { settingsOf } from './config-set.js';
+import { projectSettings } from './config-set.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 = 2;
+export const BOARD_SCHEMA = 3;
 
 /**
  * Plan progress `{tasks, done}` from its checkboxes and the plan's project path, both null
@@ -230,8 +231,19 @@ function runningKind(projectDir, id) {
   return sessionActive(projectDir, id) ? 'session' : null;
 }
 
+/**
+ * What a board may offer (§4.1): nothing while a run drives the item; with the harness, the
+ * agent's run to an item that waits for one and has no green verify yet.
+ */
+function offered(c, { running, verified, harness }) {
+  if (running) return [];
+  const runs = harness && c.data.status === RUNS_FROM && !verified;
+
+  return [...(runs ? ['run'] : []), ...movesOf(c.data)];
+}
+
 /** One item of the board. */
-async function itemOf(projectDir, c, verified, ledger) {
+async function itemOf(projectDir, c, { verified, ledger, harness }) {
   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);
@@ -263,11 +275,13 @@ async function itemOf(projectDir, c, verified, ledger) {
     resumable,
     resume,
     verified: ready,
-    // The dependencies the run gate would refuse a ready item on now (Board-PRD §5.2).
+    // The dependencies the run gate would refuse a ready item on now (Board-PRD §5.2); none
+    // while it runs, past the gate.
     waits_for:
-      c.data.status === 'ready' ? openDepends(ledger, c.data.depends ?? [], { waiting: true }) : [],
-    // What a board may offer (§4.1): nothing while a run drives the item.
-    moves: running ? [] : movesOf(c.data),
+      c.data.status === 'ready' && !running
+        ? openDepends(ledger, c.data.depends ?? [], { waiting: true })
+        : [],
+    moves: offered(c, { running, verified: ready, harness }),
     file: `gcf/work/${c.name}`,
     log: logOf(projectDir, id),
     // Filled by board() from the inbox.
@@ -280,8 +294,11 @@ export async function board(projectDir) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const ledger = await buildLedger(projectDir);
   const verified = verifiedOf(projectDir);
+  const extensions = await extensionsOf(projectDir);
+  const harness = hasHarness(extensions);
   const items = [];
-  for (const c of ledger.items) items.push(await itemOf(projectDir, c, verified, ledger));
+  for (const c of ledger.items)
+    items.push(await itemOf(projectDir, c, { verified, ledger, harness }));
   inRunOrder(items);
   // When the wait began: the time of the commit `since` names (Board-PRD §13).
   const times = commitTimes(
@@ -304,19 +321,20 @@ export async function board(projectDir) {
     run_mode: config.run_mode,
     // What the harness hands its agent runs (Harness-PRD §7): deny rules and the context limits.
     agent: agentOf(config),
-    // The human's settings of config.yml, each with its value and default (`gcf config set`).
-    settings: settingsOf(await readRawConfig(root)),
+    // The human's settings of config.yml and the agents' language, each with its value and
+    // default (`gcf config set`).
+    settings: await projectSettings(projectDir),
     context: {
       handoff_pct: config.context_handoff_pct,
       window: config.context_window,
       compact_pct: config.auto_compact_pct,
     },
     phase: await phaseOf(projectDir),
-    extensions: await extensionsOf(projectDir),
+    extensions,
     // A malformed block reads with fields missing (live check names it): null, not absent.
     release: releaseOf(live.release),
-    // The columns and the moves as data (Board-PRD decision 16): the board hard-codes neither.
-    domain: domainOf(),
+    // The domain as data (Board-PRD decision 16): its columns, blocks, fields, moves and terms.
+    domain: domainOf(extensions),
     items,
     wip: wipOf(ledger.items, config),
     inbox,

package/lib/config-set.js

@@ -1,25 +1,36 @@
 // `gcf config set` (GCF-PRD §12.4): the human's settings of gcf/config.yml, one key at a time,
 // so a board edits them through the core and never writes the file itself. A change is checked
 // by the same rules a read applies before it is written; the rest of the file keeps its keys
-// and comments. `phases:` and `agent:` have their own commands and are not set here.
+// and comments. `phases:` and `agent:` have their own commands and are not set here. The
+// language agents write in is AI Factory's (`.ai-factory/config.yaml`), set here for the board
+// too, since AI Factory has no command for it (Board-PRD decision 12).
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import YAML from 'yaml';
 import { commitMove } from './unit-ops.js';
+import { withMainLock } from './main-lock.js';
 import { atomicWrite } from './safe-path.js';
-import { configOf, DEFAULT_CONFIG, gcfRoot, RUN_MODES } from './gcf-paths.js';
+import { configOf, DEFAULT_CONFIG, gcfRoot, readRawConfig, RUN_MODES } from './gcf-paths.js';
+import { AIF_CONFIG, LANGUAGE_RE, languageIn, readAifConfig } from './aif-config.js';
 
-/** @typedef {'number' | 'share' | 'mode' | 'command'} Kind */
+/** @typedef {'number' | 'share' | 'mode' | 'command' | 'language'} Kind */
 
 // Thrown inside the move to leave without a write or a commit.
 const NO_CHANGE = new Error('no change');
 
-/** gcf/config.yml as a YAML document with a map on top: an edit keeps its comments. */
-export function configDoc(text) {
+// The languages AI Factory's own setup offers; any other name or code is taken too.
+const LANGUAGES = ['en', 'ru', 'de', 'fr', 'es', 'zh', 'ja', 'ko', 'pt', 'it'];
+
+/** A YAML file as a document with a map on top: an edit keeps its comments. */
+export function configDoc(text, name = 'gcf/config.yml') {
   const doc = YAML.parseDocument(text);
-  if (doc.errors.length) throw new Error(`gcf/config.yml: ${doc.errors[0].message}`);
+  if (doc.errors.length) throw new Error(`${name}: ${doc.errors[0].message}`);
+  // A file of a list or a word on top is not a settings file: replacing it would lose it.
+  if (doc.contents != null && !YAML.isMap(doc.contents) && doc.contents.toJSON() != null)
+    throw new Error(`${name} must map its keys`);
   if (!YAML.isMap(doc.contents)) doc.contents = /** @type {any} */ (doc.createNode({}));
 
   return doc;
@@ -33,8 +44,24 @@ export function ensureMap(doc, keys, error) {
   doc.setIn(keys, doc.createNode({}));
 }
 
-/** @type {{ key: string, kind: Kind, label: string }[]} */
+/** @type {{ key: string, kind: Kind, label: string, file?: string, options?: string[] }[]} */
 export const SETTINGS = [
+  {
+    key: 'language.ui',
+    kind: 'language',
+    file: AIF_CONFIG,
+    options: LANGUAGES,
+    label:
+      'the language agents write to you in: questions, block reasons, inbox entries, lessons, ' +
+      'titles',
+  },
+  {
+    key: 'language.artifacts',
+    kind: 'language',
+    file: AIF_CONFIG,
+    options: LANGUAGES,
+    label: 'the language of plans and of the bodies of items that are not design units',
+  },
   {
     key: 'run_mode',
     kind: 'mode',
@@ -95,28 +122,54 @@ export const SETTINGS = [
 
 const BY_KEY = new Map(SETTINGS.map((s) => [s.key, s]));
 
+/** The default a setting holds while its file does not set it; the artifacts follow the ui. */
+function defaultOf(s, aif) {
+  const [head, sub] = s.key.split('.');
+  if (s.key === 'language.artifacts') return languageIn(aif, 'ui') ?? 'en';
+  if (s.kind === 'language') return 'en';
+  if (sub) return null;
+
+  return head === 'run_mode' ? 'worktree' : (DEFAULT_CONFIG[head] ?? null);
+}
+
 /**
- * Each setting with what the file sets (null: not set, the default holds) and its default:
- * what a settings screen shows. `raw` is the parsed config.yml, before the defaults.
+ * Each setting with what its file sets (null: not set, the default holds) and its default:
+ * what a settings screen shows. `raw` is the parsed config.yml, before the defaults; `aif` the
+ * parsed `.ai-factory/config.yaml`.
  */
-export function settingsOf(raw) {
+export function settingsOf(raw, aif = {}) {
   return SETTINGS.map((s) => {
     const [head, sub] = s.key.split('.');
-    const parent = raw?.[head];
+    const parent = (s.file ? aif : raw)?.[head];
     const value = sub
       ? parent && typeof parent === 'object'
         ? (parent[sub] ?? null)
         : null
       : (parent ?? null);
-    const def = sub ? null : head === 'run_mode' ? 'worktree' : (DEFAULT_CONFIG[head] ?? null);
+    // AI Factory's file is not checked by GCF's rules: a value that is no language shows unset.
+    const shown = s.file ? languageIn(aif, sub) : value;
 
-    return { ...s, value, default: def };
+    return { ...s, value: shown, default: defaultOf(s, aif) };
   });
 }
 
+/** Every setting as the project's two files have them. */
+export const projectSettings = async (projectDir) =>
+  settingsOf(await readRawConfig(gcfRoot(projectDir)), await readAifConfig(projectDir));
+
+/** A language name or code; empty takes the key off, and AI Factory's default holds. */
+function languageOf(setting, t) {
+  if (t && !LANGUAGE_RE.test(t))
+    throw new Error(`${setting.key} must be a language name or code (en, ru…), got ${t}`);
+
+  return t || null;
+}
+
 /** The value of `text` for a setting of `kind`; an empty number goes back to its default. */
 function valueOf(setting, text) {
   const t = String(text ?? '').trim();
+  if (setting.kind === 'language') return languageOf(setting, t);
+
   if (setting.kind === 'command') {
     if (!t) throw new Error(`${setting.key}: name the command, or none`);
 
@@ -138,45 +191,71 @@ function valueOf(setting, text) {
   return n;
 }
 
+/** Whether git ignores `file`: a commit cannot carry it, and a worktree does not have it. */
+const ignoredByGit = (projectDir, file) =>
+  spawnSync('git', ['check-ignore', '-q', '--', file], { cwd: projectDir }).status === 0;
+
+const trackedByGit = (projectDir, file) =>
+  spawnSync('git', ['ls-files', '--error-unmatch', '--', file], { cwd: projectDir }).status === 0;
+
 /**
- * Set one key of gcf/config.yml and commit gcf(config); a number set to nothing goes back to
- * its default. The file is read and checked under the move's lock.
+ * Set one key of gcf/config.yml, or the language of `.ai-factory/config.yaml`, and commit
+ * gcf(config); a number set to nothing goes back to its default. The file is read and checked
+ * under the move's lock. An AI Factory file git ignores is written, not committed (`ignored`).
  */
 export async function setConfig(projectDir, key, text, { commit = true } = {}) {
   const setting = BY_KEY.get(key);
   if (!setting) throw new Error(`no setting ${key}: ${SETTINGS.map((s) => s.key).join(' | ')}`);
   const value = valueOf(setting, text);
-  const file = path.join(gcfRoot(projectDir), 'config.yml');
+  const name = setting.file ?? 'gcf/config.yml';
+  const file = setting.file
+    ? path.join(path.resolve(projectDir), setting.file)
+    : path.join(gcfRoot(projectDir), 'config.yml');
+  const ignored = Boolean(setting.file) && ignoredByGit(projectDir, file);
+  // AI Factory's setup may leave its file uncommitted: the first change commits it whole.
+  const inputs = setting.file && !ignored && !trackedByGit(projectDir, file) ? [file] : [];
   const keys = key.split('.');
-  let raw;
   // A change that changes nothing (the same value, a reset of a key not set) commits nothing.
   let unchanged = false;
-  const hash = await commitMove(projectDir, `gcf(config): ${key}`, {
-    files: [file],
-    mutate: async () => {
-      const text = existsSync(file) ? await readFile(file, 'utf8') : '';
-      const doc = configDoc(text);
-      if (keys.length > 1)
-        ensureMap(doc, [keys[0]], `gcf/config.yml: ${keys[0]} must map its keys`);
-      if (value === null) doc.deleteIn(keys);
-      else doc.setIn(keys, value);
-      raw = doc.toJS();
-      configOf(raw);
-      const out = doc.toString();
-      // The values, not the text: YAML's output may differ in form (a final newline, `{}`).
-      if (isDeepStrictEqual(YAML.parse(text) ?? {}, raw ?? {})) {
-        unchanged = true;
-        throw NO_CHANGE;
-      }
-
-      await atomicWrite(file, out);
-    },
-    commit,
-  }).catch((e) => {
+  const move = () =>
+    commitMove(projectDir, `gcf(config): ${key}`, {
+      files: [file],
+      inputs,
+      mutate,
+      commit: commit && !ignored,
+    });
+  const mutate = async () => {
+    const text = existsSync(file) ? await readFile(file, 'utf8') : '';
+    const doc = configDoc(text, name);
+    // A reset of a key whose parent is not there changes nothing: no empty map is written.
+    if (value === null && keys.length > 1 && !YAML.isMap(doc.getIn([keys[0]], true))) {
+      unchanged = true;
+      throw NO_CHANGE;
+    }
+
+    if (keys.length > 1) ensureMap(doc, [keys[0]], `${name}: ${keys[0]} must map its keys`);
+    if (value === null) doc.deleteIn(keys);
+    else doc.setIn(keys, value);
+    const raw = doc.toJS();
+    if (!setting.file) configOf(raw);
+    const out = doc.toString();
+    // The values, not the text: YAML's output may differ in form (a final newline, `{}`).
+    if (isDeepStrictEqual(YAML.parse(text) ?? {}, raw ?? {})) {
+      unchanged = true;
+      throw NO_CHANGE;
+    }
+
+    await atomicWrite(file, out);
+  };
+
+  // A move that commits nothing takes no lock in commitMove: the ignored file still needs one.
+  const hash = await (ignored && commit ? withMainLock(projectDir, move) : move()).catch((e) => {
     if (e !== NO_CHANGE) throw e;
 
     return null;
   });
+  // The change is made: a broken gcf/config.yml must not read as its failure.
+  const settings = await projectSettings(projectDir).catch(() => []);
 
-  return { key, value, unchanged, settings: settingsOf(raw), hash };
+  return { key, value, unchanged, ignored, settings, hash };
 }

package/lib/domain.js

@@ -0,0 +1,370 @@
+// The GCF domain of the board read (Board-PRD decision 16): what a board shows and offers for a
+// GCF project, as data. Its columns, its blocks (phase, WIP, playtest, inbox…), the fields of an
+// item, every move's form with the `ai-factory` words it runs, the terms of its Help. A board
+// draws these and builds each command from `args` and `fields`; it hard-codes none of them.
+import { ITEM_MOVES, STORED } from './transitions.js';
+import { DEFAULT_GATE, GATES, ITEM_TYPES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
+import { SOURCES } from './inbox.js';
+
+// The status a run starts from; the order of its column is the run order.
+export const RUNS_FROM = 'ready';
+
+// The board's words for each stored status: a column's label and tooltip.
+const COLUMN_TEXT = {
+  ready: ['ready', 'Waits for a run; the order here is the run order'],
+  blocked: ['blocked', 'Stopped: waits for an answer, an asset or a fix of a failed check'],
+  'awaiting-verdict': ['awaiting verdict', 'Built; waits for a playtest and a keep, tune or kill'],
+  'awaiting-decision': ['awaiting decision', 'Waits for the operator to decide: go, no, close…'],
+  unplayed: ['unplayed', 'Closed without a playtest; waits for one'],
+  parked: ['parked', 'A bug kept as a known issue; unblock takes it back to ready'],
+};
+
+const GATE_HELP = {
+  verdict: 'Closed by a playtest: keep, tune or kill',
+  auto: 'Closed by the run itself when its checks are green; no playtest',
+  decision: 'Closed by the operator: go, no, close or continue',
+};
+
+// The form of each move for a board: the `ai-factory` words with `{id}` for its target and
+// `{ids}` for a list of items, and the fields the operator fills. A field goes as
+// `--<flag or key>=<value>`; a list repeats it; `ids` and `tags` go as one comma list;
+// `remove` is `--remove` / `--no-remove`, or the command's own rule when left empty; `slug` is
+// the target id the operator types (`{id}`); a field with `when` goes only while another field
+// holds one of those values.
+const REASON = { key: 'reason', label: 'Reason', kind: 'longtext', required: true };
+const OPTIONAL_REASON = { ...REASON, required: false };
+const REMOVE = { key: 'remove', label: 'Removal item for its code', kind: 'remove' };
+const CONSTRAINT = { key: 'constraint', label: 'Constraint lines', kind: 'list' };
+// close and submit need a green gcf verify of the code as it is now; the operator may say why
+// they go without one, and the reason goes into the move's commit.
+const UNVERIFIED = {
+  key: 'unverified',
+  label: 'No green gcf verify? Why it goes anyway',
+  kind: 'text',
+};
+
+const verdict = (v, help, fields, danger) => ({
+  label: v,
+  help,
+  args: ['gcf', 'verdict', '{id}', v],
+  fields,
+  ...(danger && { danger }),
+});
+const decide = (choice, help, fields = [], danger) => ({
+  label: choice,
+  help,
+  args: ['gcf', 'decide', '{id}', choice],
+  fields,
+  ...(danger && { danger }),
+});
+const text = (key, label, extra = {}) => ({ key, label, kind: 'text', ...extra });
+
+// An item's moves (§4.1), offered by `items[].moves`.
+const ITEM_SPECS = {
+  submit: {
+    label: 'submit',
+    help: 'Built: on to awaiting verdict or awaiting decision, by its gate',
+    args: ['gcf', 'submit', '{id}'],
+    fields: [UNVERIFIED],
+    rare: true,
+  },
+  close: {
+    label: 'close',
+    help: 'Done, gate auto: to history; a mechanic or a resource waits unplayed',
+    args: ['gcf', 'close', '{id}'],
+    fields: [CONSTRAINT, UNVERIFIED],
+    rare: true,
+  },
+  'verdict:keep': verdict('keep', 'Played and kept: it goes to history', [
+    { key: 'note', label: 'Note', kind: 'text' },
+    CONSTRAINT,
+  ]),
+  'verdict:tune': verdict('tune', 'Played; needs a change: back to ready with the note', [
+    { key: 'note', label: 'What to change', kind: 'longtext', required: true },
+  ]),
+  'verdict:kill': verdict(
+    'kill',
+    'Played and rejected: it goes to the graveyard',
+    [{ key: 'note', label: 'Why', kind: 'longtext' }, REMOVE],
+    true,
+  ),
+  'decide:go': decide('go', 'Approved: it goes to history as decided'),
+  'decide:no': decide(
+    'no',
+    'Not doing it: it goes to the graveyard',
+    [OPTIONAL_REASON, REMOVE],
+    true,
+  ),
+  'decide:wontfix': decide(
+    'wontfix',
+    'A bug left as it is: it goes to the graveyard',
+    [OPTIONAL_REASON, REMOVE],
+    true,
+  ),
+  'decide:known': decide('known', 'A bug kept as a known issue: it goes to parked'),
+  'decide:close': decide('close', 'The feature is done: it goes to history'),
+  'decide:continue': decide('continue', 'The feature goes on: back to ready for more children'),
+  'decide:kill': decide(
+    'kill',
+    'The feature is dropped: it goes to the graveyard with its live children',
+    [OPTIONAL_REASON],
+    true,
+  ),
+  block: {
+    label: 'block',
+    help: 'Stop it until the operator answers',
+    args: ['gcf', 'block', '{id}'],
+    fields: [REASON],
+  },
+  unblock: {
+    label: 'unblock',
+    help: 'The answer is given: back to ready (a feature with a dead child: to a decision)',
+    args: ['gcf', 'unblock', '{id}'],
+    fields: [{ key: 'note', label: 'Answer or "file: <path>"', kind: 'longtext' }],
+    drag: RUNS_FROM,
+  },
+  drop: {
+    label: 'drop',
+    help: 'Off the board into the graveyard, from any status',
+    args: ['gcf', 'drop', '{id}'],
+    fields: [REASON, { key: 'tags', label: 'Graveyard tags', kind: 'text' }, REMOVE],
+    danger: true,
+    rare: true,
+    drag: 'graveyard',
+  },
+  depends: {
+    label: 'depends',
+    help: 'The items it waits for: a run starts only after they are played',
+    args: ['gcf', 'depends', '{id}'],
+    fields: [
+      { key: 'add', label: 'Add: ids it waits for', kind: 'ids' },
+      { key: 'remove', label: 'Remove: ids it no longer waits for', kind: 'ids' },
+    ],
+    rare: true,
+  },
+};
+
+// The agent's move: a session of the gcf-run skill builds the item, driven by the harness.
+const RUN = {
+  kind: 'agent',
+  label: 'run',
+  help: 'An agent session builds it: plan, code, the checks, then submit or close',
+  skill: 'gcf-run',
+  args: [],
+  fields: [],
+};
+
+// The new item form (`gcf item new`): work that is not a design unit; a design unit enters work
+// through the gcf-card skill and take.
+const NEW_ITEM = {
+  label: 'create',
+  help: 'A new work item, committed; the core refuses a type the phase does not take',
+  args: ['gcf', 'item', 'new', '{id}', '--commit'],
+  fields: [
+    { key: 'id', label: 'Id (lowercase-hyphen slug)', kind: 'slug', required: true },
+    {
+      key: 'type',
+      label: 'Type',
+      kind: 'choice',
+      required: true,
+      default: 'tech',
+      options: ITEM_TYPES.filter((t) => !UNIT_ITEM_TYPES.includes(t)).map((t) => ({
+        value: t,
+        label: t,
+        help: `gate ${DEFAULT_GATE[t]} by default`,
+      })),
+    },
+    {
+      key: 'gate',
+      label: 'Gate',
+      kind: 'choice',
+      options: [
+        { value: '', label: 'by type' },
+        ...GATES.map((g) => ({ value: g, label: g, help: GATE_HELP[g] })),
+      ],
+    },
+    {
+      key: 'severity',
+      label: 'Severity',
+      kind: 'choice',
+      required: true,
+      options: SEVERITIES.map((s) => ({ value: s, label: s })),
+      when: { key: 'type', is: ['bug'] },
+    },
+    text('release', 'Version', { required: true, when: { key: 'type', is: ['release'] } }),
+    text('channel', 'Channel', { required: true, when: { key: 'type', is: ['release'] } }),
+    text('title', 'Title: one line, what it gives'),
+    text('system', 'Subsystems, comma-separated'),
+    text('depends', 'Depends on ids, comma-separated'),
+    text('parent', 'Parent feature id'),
+    text('milestone', 'Milestone'),
+    text('blocked', 'Start blocked: why (e.g. "file needed")'),
+    text('model', 'Model of its run (e.g. opus)'),
+    text('effort', 'Effort of its run (e.g. high)'),
+    // The inbox entry it comes from: the form fills it, the operator does not.
+    text('from', 'From inbox entry', { hidden: true }),
+  ],
+};
+
+// The moves of the domain's blocks: the phase, the inbox, the questions, the run order.
+const BLOCK_SPECS = {
+  'item-new': NEW_ITEM,
+  'phase-next': {
+    label: 'move on',
+    help: 'On to the next phase; against an unmet criterion only with a reason',
+    args: ['gcf', 'phase', 'next'],
+    fields: [
+      { key: 'reason', label: 'Reason (needed when a criterion is not met)', kind: 'longtext' },
+    ],
+  },
+  'inbox-add': {
+    label: 'add',
+    help: 'A raw note for triage: an idea, a playtest note, a CI finding',
+    args: ['gcf', 'inbox', 'add', '--commit'],
+    fields: [
+      { key: 'text', label: 'Text', kind: 'text', required: true },
+      {
+        key: 'source',
+        label: 'Source',
+        kind: 'choice',
+        default: 'operator',
+        options: SOURCES.map((s) => ({ value: s, label: s })),
+      },
+      { key: 'tags', label: 'Tags', kind: 'tags' },
+    ],
+  },
+  'inbox-drop': {
+    label: 'erase',
+    help: 'Noise: the entry is erased, nothing is made of it',
+    args: ['gcf', 'inbox', 'drop', '{id}', '--commit'],
+    fields: [],
+    danger: true,
+  },
+  'inbox-tag': {
+    label: 'tag',
+    help: 'Sort the entry: tags added and removed',
+    args: ['gcf', 'inbox', 'tag', '{id}', '--commit'],
+    fields: [
+      { key: 'add', label: 'Add tags', kind: 'tags' },
+      { key: 'remove', label: 'Remove tags', kind: 'tags' },
+    ],
+  },
+  'question-answer': {
+    label: 'answer',
+    help: 'The answer goes into the record; the next agent on its units puts it in place',
+    args: ['gcf', 'question', 'answer', '{id}'],
+    fields: [{ key: 'text', label: 'Answer', kind: 'text', required: true }],
+  },
+  prioritize: {
+    label: 'prioritize',
+    help: 'The run order: ranks 1, 2, 3… in one commit',
+    args: ['gcf', 'prioritize', '{ids}'],
+    fields: [],
+  },
+};
+
+// The item fields a board shows: on the card (`card`), in the drawer (all that have a value).
+const GATE_FIELD_OPTIONS = GATES.map((g) => ({ value: g, label: g, help: GATE_HELP[g] }));
+const FIELDS = [
+  { key: 'priority', label: 'priority', kind: 'rank', help: 'Rank: lower runs sooner', card: true },
+  { key: 'type', label: 'type', kind: 'text', card: true, badge: true },
+  {
+    key: 'gate',
+    label: 'gate',
+    kind: 'choice',
+    options: GATE_FIELD_OPTIONS,
+    help: 'Who closes it',
+    card: true,
+    badge: true,
+  },
+  { key: 'severity', label: 'severity', kind: 'text', card: true, badge: true },
+  { key: 'model', label: 'model', kind: 'text', card: true },
+  { key: 'effort', label: 'effort', kind: 'text' },
+  { key: 'tune_count', label: 'tune', kind: 'text', help: 'Tune verdicts so far', card: true },
+  {
+    key: 'waits_for',
+    label: 'waits for',
+    kind: 'ids',
+    help: 'The run gate refuses it until these are played',
+    card: true,
+  },
+  { key: 'depends', label: 'depends', kind: 'ids' },
+  { key: 'needed_by', label: 'needed by', kind: 'ids', help: 'The items that wait for this one' },
+  { key: 'system', label: 'system', kind: 'list' },
+  { key: 'parent', label: 'parent', kind: 'text' },
+  { key: 'children', label: 'children', kind: 'ids' },
+  { key: 'milestone', label: 'milestone', kind: 'text' },
+  { key: 'blocked', label: 'blocked', kind: 'longtext', help: 'Why it stopped', card: true },
+];
+
+// The words of its Help (Board-PRD decision 17): what the board's terms mean in GCF.
+const TERMS = [
+  ['item', 'One piece of work in gcf/work/: a file with its type, gate and status'],
+  ['gate', 'Who closes an item: a verdict (playtest), auto (its checks) or a decision'],
+  ...GATES.map((g) => [`gate: ${g}`, GATE_HELP[g]]),
+  [
+    'feature',
+    'A parent item: when its children are done, the operator decides: close, continue or kill',
+  ],
+  ['design unit', 'A mechanic, resource, rule, constraint or entity of gcf/design/'],
+  ['phase', 'The stage of the project (prototype, vertical slice…): the types it takes'],
+  ['WIP', 'Items built and waiting for a verdict; at the limit new verdict work stops'],
+  ['verify', 'The DoD: the project test and build commands, green on the code as it is'],
+  ['inbox', 'Raw input waiting for triage: it becomes an item or is erased'],
+  ['lesson', 'An inbox entry an agent session left: what got in its way'],
+  ['D1', 'A question only the operator answers; it blocks the units it names'],
+  ['D2', 'An assumption the agent made and works with; it comes back when its trigger fires'],
+  ['unplayed', 'Closed by its checks without a playtest; it waits for one'],
+  ['history', 'What was accepted: history.md'],
+  ['graveyard', 'What was killed or dropped, with the reason: graveyard.md'],
+].map(([term, help]) => ({ term, help }));
+
+const SECTIONS = {
+  phase: { next: 'phase-next' },
+  release: {},
+  wip: { help: 'Items awaiting a verdict / wip_built_limit' },
+  inbox: { add: 'inbox-add', drop: 'inbox-drop', tag: 'inbox-tag' },
+  questions: { answer: 'question-answer' },
+  lessons: {},
+  playtest: {
+    waits: ['awaiting-verdict', 'unplayed'],
+    verdicts: ['verdict:keep', 'verdict:tune', 'verdict:kill'],
+  },
+  history: { label: 'Accepted' },
+  graveyard: { label: 'Graveyard' },
+};
+
+// The extension whose CLI drives agent runs (run, next, stop, metrics with --json).
+const HARNESS = { extension: 'gcf-harness-aif-ext', cli: 'gcf-harness' };
+
+/** Whether the project's AI Factory extensions include the harness (`extensions` of the read). */
+export const hasHarness = (extensions) => Object.hasOwn(extensions ?? {}, HARNESS.extension);
+
+/**
+ * The GCF domain of the board read. `extensions` are the project's AI Factory extensions: the
+ * agent's move, and the runner that drives it, only with the harness.
+ */
+export function domainOf(extensions = {}) {
+  const harness = hasHarness(extensions);
+
+  return {
+    kind: 'gcf',
+    runs_from: RUNS_FROM,
+    harness: harness ? HARNESS.cli : null,
+    columns: STORED.map((status) => ({
+      status,
+      label: COLUMN_TEXT[status][0],
+      help: COLUMN_TEXT[status][1],
+    })),
+    moves: {
+      ...(harness && { run: RUN }),
+      ...Object.fromEntries(ITEM_MOVES.map((m) => [m, ITEM_SPECS[m]])),
+      ...BLOCK_SPECS,
+    },
+    fields: FIELDS,
+    terms: TERMS,
+    sections: SECTIONS,
+    new_item: 'item-new',
+    rank: 'prioritize',
+  };
+}

package/lib/transitions.js

@@ -28,8 +28,13 @@ const FROM = {
   block: ['ready'],
   unblock: ['blocked', 'parked'],
   drop: STORED,
+  // What it waits for may change at any status; the core refuses an unknown id and a cycle.
+  depends: STORED,
 };
 
+/** Every move an item may be offered, in the board's order. */
+export const ITEM_MOVES = Object.keys(FROM);
+
 /** True when `move` (`close`, `verdict:keep`, …) may start from `status`. */
 export function allowedFrom(move, status) {
   return (FROM[move] ?? []).includes(status);
@@ -67,133 +72,3 @@ export const movesOf = (data) =>
 export function isStorable(status) {
   return STORED.includes(status);
 }
-
-// The board's words for each stored status (Board-PRD decision 16): a column's label and tooltip.
-const COLUMN_TEXT = {
-  ready: ['ready', 'Waits for a run; the order here is the run order'],
-  blocked: ['blocked', 'Stopped: waits for an answer, an asset or a fix of a failed check'],
-  'awaiting-verdict': ['awaiting verdict', 'Built; waits for a playtest and a keep, tune or kill'],
-  'awaiting-decision': ['awaiting decision', 'Waits for the operator to decide: go, no, close…'],
-  unplayed: ['unplayed', 'Closed without a playtest; waits for one'],
-  parked: ['parked', 'A bug kept as a known issue; unblock takes it back to ready'],
-};
-
-// The form of each move (§4.1) for a board: the `ai-factory gcf` words with `{id}` for the item,
-// and the fields the operator fills. A field goes as `--<flag or key>=<value>`; a list repeats
-// it; `remove` is `--remove` / `--no-remove`, or the command's own rule when left empty.
-const REASON = { key: 'reason', label: 'Reason', kind: 'longtext', required: true };
-const OPTIONAL_REASON = { ...REASON, required: false };
-const REMOVE = { key: 'remove', label: 'Removal item for its code', kind: 'remove' };
-const CONSTRAINT = { key: 'constraint', label: 'Constraint lines', kind: 'list' };
-// close and submit need a green gcf verify of the code as it is now; the operator may say why
-// they go without one, and the reason goes into the move's commit.
-const UNVERIFIED = {
-  key: 'unverified',
-  label: 'No green gcf verify? Why it goes anyway',
-  kind: 'text',
-};
-
-const verdict = (v, help, fields, danger) => ({
-  label: v,
-  help,
-  args: ['verdict', '{id}', v],
-  fields,
-  ...(danger && { danger }),
-});
-const decide = (choice, help, fields = [], danger) => ({
-  label: choice,
-  help,
-  args: ['decide', '{id}', choice],
-  fields,
-  ...(danger && { danger }),
-});
-
-const SPECS = {
-  submit: {
-    label: 'submit',
-    help: 'Built: on to awaiting verdict or awaiting decision, by its gate',
-    args: ['submit', '{id}'],
-    fields: [UNVERIFIED],
-    rare: true,
-  },
-  close: {
-    label: 'close',
-    help: 'Done, gate auto: to history; a mechanic or a resource waits unplayed',
-    args: ['close', '{id}'],
-    fields: [CONSTRAINT, UNVERIFIED],
-    rare: true,
-  },
-  'verdict:keep': verdict('keep', 'Played and kept: it goes to history', [
-    { key: 'note', label: 'Note', kind: 'text' },
-    CONSTRAINT,
-  ]),
-  'verdict:tune': verdict('tune', 'Played; needs a change: back to ready with the note', [
-    { key: 'note', label: 'What to change', kind: 'longtext', required: true },
-  ]),
-  'verdict:kill': verdict(
-    'kill',
-    'Played and rejected: it goes to the graveyard',
-    [{ key: 'note', label: 'Why', kind: 'longtext' }, REMOVE],
-    true,
-  ),
-  'decide:go': decide('go', 'Approved: it goes to history as decided'),
-  'decide:no': decide(
-    'no',
-    'Not doing it: it goes to the graveyard',
-    [OPTIONAL_REASON, REMOVE],
-    true,
-  ),
-  'decide:wontfix': decide(
-    'wontfix',
-    'A bug left as it is: it goes to the graveyard',
-    [OPTIONAL_REASON, REMOVE],
-    true,
-  ),
-  'decide:known': decide('known', 'A bug kept as a known issue: it goes to parked'),
-  'decide:close': decide('close', 'The feature is done: it goes to history'),
-  'decide:continue': decide('continue', 'The feature goes on: back to ready for more children'),
-  'decide:kill': decide(
-    'kill',
-    'The feature is dropped: it goes to the graveyard with its live children',
-    [OPTIONAL_REASON],
-    true,
-  ),
-  block: {
-    label: 'block',
-    help: 'Stop it until the operator answers',
-    args: ['block', '{id}'],
-    fields: [REASON],
-  },
-  unblock: {
-    label: 'unblock',
-    help: 'The answer is given: back to ready (a feature with a dead child: to a decision)',
-    args: ['unblock', '{id}'],
-    fields: [{ key: 'note', label: 'Answer or "file: <path>"', kind: 'longtext' }],
-    drag: 'ready',
-  },
-  drop: {
-    label: 'drop',
-    help: 'Off the board into the graveyard, from any status',
-    args: ['drop', '{id}'],
-    fields: [REASON, { key: 'tags', label: 'Graveyard tags', kind: 'text' }, REMOVE],
-    danger: true,
-    rare: true,
-    drag: 'graveyard',
-  },
-};
-
-/**
- * The GCF domain of the board read (Board-PRD decision 16): its columns in order, the status a
- * run starts from, and the form of every move `movesOf` may name. A board draws these and
- * builds each command from `args` and `fields`; it hard-codes none of them.
- */
-export const domainOf = () => ({
-  kind: 'gcf',
-  runs_from: 'ready',
-  columns: STORED.map((status) => ({
-    status,
-    label: COLUMN_TEXT[status][0],
-    help: COLUMN_TEXT[status][1],
-  })),
-  moves: Object.fromEntries(Object.keys(FROM).map((m) => [m, SPECS[m]])),
-});

package/package.json

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

package/templates/agents-block.md

@@ -34,7 +34,7 @@ gcf_forbidden:
 - do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
 - do not run `ai-factory gcf phase next`: the phase moves on the human's word only
 - do not change what agent runs may do: `ai-factory gcf permissions` and its deny groups belong to the human
-- do not change a setting of `gcf/config.yml`: `ai-factory gcf config set` belongs to the human
+- do not change a setting of `gcf/config.yml` or the `language` of `.ai-factory/config.yaml`: `ai-factory gcf config set` belongs to the human
 - do not reuse an ended id: rework gets a new id with `reopens: <old id>`
 - do not commit past the gate with `--no-verify`: a refused commit names what to fix