gcf-aif-ext 0.7.14 → 0.8.0

package/commands/gcf.js

@@ -731,6 +731,27 @@ function registerItem(gcf) {
     });
 }
 
+function registerDepends(gcf) {
+  gcf
+    .command('depends <id>')
+    .description(
+      'Change the items it waits for: refuses an unknown or killed id and a cycle (commit)',
+    )
+    .option('--add <ids>', 'ids to add, comma-separated')
+    .option('--remove <ids>', 'ids to remove, comma-separated')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, o) => {
+      const r = await (
+        await lib('work-ops')
+      ).setDepends(process.cwd(), id, {
+        add: splitList(o.add),
+        remove: splitList(o.remove),
+        commit: o.commit,
+      });
+      console.log(`${id} depends on ${r.depends.join(', ') || 'nothing'}${shortHash(r.hash)}`);
+    });
+}
+
 function registerItemMoves(gcf) {
   const ops = () => lib('work-ops');
   gcf
@@ -741,6 +762,7 @@ function registerItemMoves(gcf) {
       const r = await (await ops()).prioritizeItems(process.cwd(), ids, { commit: o.commit });
       console.log(`ranked ${r.ids.join(', ')}${shortHash(r.hash)}`);
     });
+  registerDepends(gcf);
   const question = gcf.command('question').description('Open questions (gcf/open-questions.md)');
   question
     .command('answer <qid>')
@@ -861,6 +883,26 @@ async function inboxMove(commit, message, edit) {
   });
 }
 
+function registerInboxTag(inbox) {
+  inbox
+    .command('tag <in-id>')
+    .description('Add tags to an entry and remove others')
+    .option('--add <tags>', 'tags to add, comma-separated')
+    .option('--remove <tags>', 'tags to remove, comma-separated')
+    .option('--commit', 'commit it (gcf(inbox)): for a caller with no console, e.g. a board')
+    .action(async (id, o) => {
+      const { tagInbox } = await lib('inbox');
+      let tags = [];
+      const hash = await inboxMove(o.commit, `gcf(inbox): tag ${id}`, async (root) => {
+        ({ tags } = await tagInbox(root, id, {
+          add: splitList(o.add),
+          remove: splitList(o.remove),
+        }));
+      });
+      console.log(`${id} tags: ${tags.join(', ') || 'none'}${shortHash(hash)}`);
+    });
+}
+
 function registerInbox(gcf) {
   const inbox = gcf
     .command('inbox')
@@ -874,8 +916,9 @@ function registerInbox(gcf) {
           ? l
               .map((e) => {
                 const source = e.kind ? `lesson:${e.kind}:${e.item}` : e.source;
+                const tags = e.tags.length ? ` (tags: ${e.tags.join(', ')})` : '';
 
-                return `${e.id} [${source}] ${e.text}`;
+                return `${e.id} [${source}] ${e.text}${tags}`;
               })
               .join('\n')
           : 'inbox empty',
@@ -888,6 +931,7 @@ function registerInbox(gcf) {
     // 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('--tags <tags>', 'its tags, comma-separated: idea, later, ui:hud')
     .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;
@@ -896,10 +940,11 @@ function registerInbox(gcf) {
       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;
+        id = (await addInbox(root, text, o.source, { tags: splitList(o.tags) })).id;
       });
       console.log(`${id}${shortHash(hash)}`);
     });
+  registerInboxTag(inbox);
   inbox
     .command('drop <in-id>')
     .description('Erase an entry: triaged as noise, a duplicate, or turned into an item')

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.7.14",
+  "version": "0.8.0",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/lib/aif-config.js

@@ -0,0 +1,22 @@
+// 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.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+
+/**
+ * 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.
+ */
+export async function uiLanguage(projectDir) {
+  try {
+    const file = path.join(path.resolve(projectDir), '.ai-factory', 'config.yaml');
+    const ui = YAML.parse(await readFile(file, 'utf8'))?.language?.ui;
+
+    // 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';
+  } catch {
+    return 'en';
+  }
+}

package/lib/board.js

@@ -134,6 +134,26 @@ async function phaseOf(projectDir) {
   }
 }
 
+/**
+ * The AI Factory extensions the project has, name → version, from `.ai-factory.json`: the board
+ * shows which framework packages a project runs. `{}` when the file is missing or unreadable.
+ */
+async function extensionsOf(projectDir) {
+  try {
+    const cfg = JSON.parse(
+      await readFile(path.join(path.resolve(projectDir), '.ai-factory.json'), 'utf8'),
+    );
+
+    return Object.fromEntries(
+      (cfg.extensions ?? [])
+        .filter((e) => typeof e?.name === 'string')
+        .map((e) => [e.name, typeof e.version === 'string' ? e.version : null]),
+    );
+  } catch {
+    return {};
+  }
+}
+
 /** The release block with every field: one a malformed block lacks is null (live check says so). */
 const releaseOf = (r) =>
   r && {
@@ -274,6 +294,9 @@ export async function board(projectDir) {
   const inbox = await listInbox(root);
   // Where agents struggle: the lessons in the inbox each item's sessions left.
   for (const i of items) i.lessons = inbox.filter((e) => e.item === i.id).length;
+  // The reverse of depends: the items on the board that wait for this one.
+  for (const i of items)
+    i.needed_by = items.filter((o) => o.depends.includes(i.id)).map((o) => o.id);
 
   const config = await readConfig(root);
   const live = await readLive(root);
@@ -291,6 +314,7 @@ export async function board(projectDir) {
       compact_pct: config.auto_compact_pct,
     },
     phase: await phaseOf(projectDir),
+    extensions: await extensionsOf(projectDir),
     // A malformed block reads with fields missing (live check names it): null, not absent.
     release: releaseOf(live.release),
     columns: Object.fromEntries(

package/lib/design-check.js

@@ -557,10 +557,10 @@ function ledgerIssues(ledger) {
 }
 
 /**
- * M2 over `depends:` of units and items together: a cycle never gets played — every id in it
- * waits for the next one. Each cycle is reported once, from the id DFS meets it at.
+ * `depends:` of every unit and item: id → the ids it waits for. A feature also waits for its
+ * children: it closes only after them, so a child that depends on it never gets played.
  */
-export function dependsCycles(ledger) {
+export function dependsGraph(ledger) {
   /** @type {Map<string, string[]>} */
   const graph = new Map();
   for (const u of ledger.design.flatMap((d) => d.units)) {
@@ -568,7 +568,43 @@ export function dependsCycles(ledger) {
     graph.set(u.id, Array.isArray(list) ? list : []);
   }
 
-  for (const c of ledger.items) graph.set(String(c.data.id), c.data.depends ?? []);
+  for (const c of ledger.items) {
+    const children = c.data.type === 'feature' ? (c.data.children ?? []) : [];
+    graph.set(String(c.data.id), [...(c.data.depends ?? []), ...children]);
+  }
+
+  return graph;
+}
+
+/** The ids from `from` to `to` over `graph`, both included, or null when there is no way. */
+export function pathTo(graph, from, to, seen = new Set()) {
+  if (from === to) return [to];
+  if (seen.has(from)) return null;
+  seen.add(from);
+  for (const next of graph.get(from) ?? []) {
+    const rest = pathTo(graph, next, to, seen);
+    if (rest) return [from, ...rest];
+  }
+
+  return null;
+}
+
+/** Why a depends `cycle` (its ids, the first again at the end) never gets played. */
+export function cycleMessage(ledger, cycle) {
+  const feature = cycle.some((id) => ledger.item(id)?.data.type === 'feature');
+
+  return (
+    `depends cycle ${cycle.join(' -> ')}: none of them can be played first` +
+    (feature ? ' (a feature waits for its children)' : '')
+  );
+}
+
+/**
+ * M2 over `depends:` of units and items together: a cycle never gets played — every id in it
+ * waits for the next one. Each cycle is reported once, from the id DFS meets it at.
+ */
+export function dependsCycles(ledger) {
+  const graph = dependsGraph(ledger);
   /** @type {Issue[]} */
   const out = [];
   const state = new Map(); // id → 'open' while on the DFS path, 'done' after
@@ -583,7 +619,7 @@ export function dependsCycles(ledger) {
         file,
         line: 1,
         id,
-        message: `depends cycle ${cycle.join(' -> ')}: none of them can be played first`,
+        message: cycleMessage(ledger, cycle),
       });
 
       return;

package/lib/inbox.js

@@ -1,6 +1,8 @@
 // gcf/inbox.md (Methodology §5.1): raw input waiting for triage — playtest notes, CI failures,
-// the agent's ideas and requests. One line per entry, `- <in-id> | <source> | <text>`; a triaged
-// line is erased, not marked: the file holds what is still waiting, not what happened to it.
+// the agent's ideas and requests, the operator's ideas and notes. One line per entry,
+// `- <in-id> | <source> | <text>[ | tags: a, b]`; a triaged line is erased, not marked: the file
+// holds what is still waiting, not what happened to it. Tags sort it; an older core reads the
+// tags field as part of the text, which loses nothing.
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { createHash } from 'node:crypto';
@@ -8,48 +10,136 @@ import path from 'node:path';
 import { atomicWrite } from './safe-path.js';
 
 export const INBOX_HEAD =
-  '# Inbox — `- <in-id> | <source> | <text>`, raw input waiting for triage; a triaged line ' +
-  'is erased\n';
+  '# Inbox — `- <in-id> | <source> | <text>[ | tags: a, b]`, raw input waiting for triage; a ' +
+  'triaged line is erased\n';
 export const SOURCES = ['playtest', 'ci', 'agent', 'operator'];
 const LINE = /^- (in-[0-9a-f]+) \| (\S+) \| (.+)$/;
+// The text may hold ` | ` itself: the tags are only the field at the very end.
+const TAGS = / \| tags: ([^|]*)$/;
+const TAG = /^[a-z0-9][a-z0-9:-]{0,39}$/;
 // An agent's lesson (lessons.js): `lesson:<kind>:<item-id>`.
 const LESSON = /^lesson:([a-z]+):([a-z0-9][a-z0-9-]*)$/;
 
 const inboxFile = (root) => path.join(root, 'inbox.md');
 
+/**
+ * The text and the tags of a line's last field. A field that is not a clean tag list (a bad
+ * tag, a tag twice, no text before it) stays part of the text: nothing written is lost.
+ */
+function textAndTags(rest) {
+  const m = rest.match(TAGS);
+  const tags = m ? m[1].split(',').map((t) => t.trim()) : [];
+  const text = m ? rest.slice(0, m.index).trim() : '';
+  const clean = tags.every((t) => TAG.test(t)) && new Set(tags).size === tags.length;
+  if (!m || !clean || !text) return { text: rest.trim(), tags: [] };
+
+  return { text, tags };
+}
+
+const lineOf = (e) =>
+  `- ${e.id} | ${e.source} | ${e.text}${e.tags.length ? ` | tags: ${e.tags.join(', ')}` : ''}`;
+
+/** The entry of one line as written, or null. */
+function rawOf(line) {
+  const m = line.match(LINE);
+
+  return m ? { id: m[1], source: m[2], ...textAndTags(m[3]) } : null;
+}
+
+/**
+ * One entry per id. A union merge of two branches that tagged an entry differently leaves two
+ * lines with its id: they read as one, its first line's text with the tags of both.
+ */
+function mergeById(raws) {
+  /** @type {Map<string, {id: string, source: string, text: string, tags: string[]}>} */
+  const byId = new Map();
+  for (const r of raws) {
+    const seen = byId.get(r.id);
+    if (seen) seen.tags = [...new Set([...seen.tags, ...r.tags])];
+    else byId.set(r.id, { ...r });
+  }
+
+  return [...byId.values()];
+}
+
 /**
  * Every entry; a lesson reads as source `lesson` with its `kind` and the `item` it came from.
- * @typedef {{id: string, source: string, text: string, kind?: string, item?: string}} Entry
+ * @typedef {{id: string, source: string, text: string, tags: string[], kind?: string,
+ *   item?: string}} Entry
  * @returns {Promise<Entry[]>}
  */
 export async function listInbox(root) {
   const file = inboxFile(root);
   if (!existsSync(file)) return [];
+  const raws = (await readFile(file, 'utf8')).split(/\r?\n/).map(rawOf).filter(Boolean);
 
-  return (await readFile(file, 'utf8')).split(/\r?\n/).flatMap((l) => {
-    const m = l.match(LINE);
-    if (!m) return [];
-    const lesson = m[2].match(LESSON);
-    const entry = { id: m[1], source: m[2], text: m[3].trim() };
+  return mergeById(/** @type {any[]} */ (raws)).map((entry) => {
+    const lesson = entry.source.match(LESSON);
 
-    return [lesson ? { ...entry, source: 'lesson', kind: lesson[1], item: lesson[2] } : entry];
+    return lesson ? { ...entry, source: 'lesson', kind: lesson[1], item: lesson[2] } : entry;
   });
 }
 
-/** Append an entry; its id hashes the text and the moment, so two branches never collide. */
-export async function addInbox(root, text, source = 'operator', now = new Date().toISOString()) {
+/** Refuse a tag that is not a lowercase word (`idea`, `later`, `ui:hud`). */
+function checkTags(tags) {
+  const bad = tags.find((t) => !TAG.test(t));
+  if (bad !== undefined)
+    throw new Error(`tag "${bad}" must be a lowercase word: letters, digits, - and :`);
+  if (new Set(tags).size !== tags.length) throw new Error('a tag is named twice');
+}
+
+/**
+ * Append an entry with its `tags`; its id hashes the text and the moment (`now`), so two
+ * branches never collide.
+ */
+export async function addInbox(
+  root,
+  text,
+  source = 'operator',
+  { now = new Date().toISOString(), tags = [] } = {},
+) {
   const clean = String(text).replace(/\s+/g, ' ').trim();
   if (!clean) throw new Error('an inbox entry needs text');
   if (!SOURCES.includes(source) && !LESSON.test(source))
     throw new Error(`source must be ${SOURCES.join(' | ')}`);
+  if (textAndTags(clean).tags.length)
+    throw new Error('the text ends like a tags field: give tags as tags');
+  checkTags(tags);
   const id = `in-${createHash('sha1').update(`${now}\n${clean}`).digest('hex').slice(0, 8)}`;
   const file = inboxFile(root);
   const old = existsSync(file) ? await readFile(file, 'utf8') : INBOX_HEAD;
   const eol = old.includes('\r\n') ? '\r\n' : '\n';
   const head = old.endsWith('\n') ? old : old + eol;
-  await atomicWrite(file, `${head}- ${id} | ${source} | ${clean}${eol}`);
+  const entry = { id, source, text: clean, tags };
+  await atomicWrite(file, `${head}${lineOf(entry)}${eol}`);
+
+  return entry;
+}
+
+/**
+ * Add tags to entry `id` and remove others; refuses one it has, or lacks, already. Lines a
+ * union merge doubled become one again, at the first one's place.
+ */
+export async function tagInbox(root, id, { add = [], remove = [] }) {
+  if (!add.length && !remove.length) throw new Error('name tags to --add or --remove');
+  checkTags([...add, ...remove]);
+  const file = inboxFile(root);
+  const lines = (existsSync(file) ? await readFile(file, 'utf8') : '').split(/(?<=\n)/);
+  const bodyOf = (l) => l.replace(/\r?\n$/, '');
+  const mine = lines.flatMap((l, i) => (rawOf(bodyOf(l))?.id === id ? [i] : []));
+  if (!mine.length) throw new Error(`${id} is not in gcf/inbox.md`);
+  const [entry] = mergeById(mine.map((i) => /** @type {any} */ (rawOf(bodyOf(lines[i])))));
+  const had = add.filter((x) => entry.tags.includes(x));
+  if (had.length) throw new Error(`${id} is tagged ${had.join(', ')} already`);
+  const missing = remove.filter((x) => !entry.tags.includes(x));
+  if (missing.length) throw new Error(`${id} has no tag ${missing.join(', ')}`);
+  entry.tags = [...entry.tags.filter((x) => !remove.includes(x)), ...add];
+  // The line keeps its own ending: a CRLF file stays CRLF.
+  const first = lines[mine[0]];
+  lines[mine[0]] = `${lineOf(entry)}${first.slice(bodyOf(first).length)}`;
+  await atomicWrite(file, lines.filter((_, i) => !mine.slice(1).includes(i)).join(''));
 
-  return { id, source, text: clean };
+  return entry;
 }
 
 /** Erase entry `id`; refuses an id the inbox does not hold. */

package/lib/lessons.js

@@ -5,6 +5,7 @@
 // the session ends: the harness asks them in one more turn, `/gcf-run` asks them at its close.
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { uiLanguage } from './aif-config.js';
 import { readRawConfig } from './gcf-paths.js';
 import { addInbox } from './inbox.js';
 import { isValidId } from './id.js';
@@ -66,6 +67,7 @@ function questionsOf(config) {
 export async function lessonsPrompt(projectDir, id, { reply = 'cli' } = {}) {
   if (!isValidId(id)) throw new Error(`${id} is not an item id`);
   const config = lessonsConfig(await readRawConfig(path.join(path.resolve(projectDir), 'gcf')));
+  const ui = await uiLanguage(projectDir);
   const asked = questionsOf(config)
     .map((q, i) => `${i + 1}. ${q.kind}: ${q.text}`)
     .join('\n');
@@ -83,6 +85,10 @@ export async function lessonsPrompt(projectDir, id, { reply = 'cli' } = {}) {
       'what got in your way, so it can be removed.',
     'Answer from this session only, one finding per entry, in a sentence or two; skip a ' +
       'question with nothing to say, and never invent one.',
+    // The operator reads the answers: they go in the project's language.ui (Methodology §5.2.3).
+    ...(ui === 'en'
+      ? []
+      : [`Write each finding in the language "${ui}"; keep the kinds as they are.`]),
     asked,
     // The harness's turn comes after the item's commit and its verified trailer: an edit then
     // would leave the checkout dirty or move the trailer off the tip.
@@ -104,7 +110,10 @@ function lessonOf(raw, i) {
   if (!text) throw new Error(`lesson ${i + 1} has no text`);
   const where = raw?.where ? String(raw.where).replace(/\s+/g, ' ').trim() : '';
 
-  return { kind, text: where ? `${text} (${where})` : text };
+  // An agent's free text must not read as an inbox tags field, nor fail the whole batch on it.
+  const full = (where ? `${text} (${where})` : text).replace(/ \| tags:/g, ' / tags:');
+
+  return { kind, text: full };
 }
 
 /**

package/lib/unit-ops.js

@@ -8,7 +8,7 @@ import path from 'node:path';
 import { serialize } from './frontmatter.js';
 import { CARD_TYPES, SLUG_RE, listOf } from './design.js';
 import { buildLedger } from './ledger.js';
-import { designCheck } from './design-check.js';
+import { cycleMessage, designCheck, dependsGraph, pathTo } from './design-check.js';
 import { atomicWrite, withFileRollback } from './safe-path.js';
 import { writeIndex } from './index-gen.js';
 import { operationInProgress, commitPaths } from './git.js';
@@ -124,6 +124,20 @@ function featureFor(ledger, root, { id, unitIds, systems, today }) {
   return { file, text: serialize(data, `\nintent:\n- TBD: what ${id} gives the player\n`) };
 }
 
+/**
+ * Refuse taking `units` under `feature` when one waits for the feature: the feature closes only
+ * after its children, so neither would ever be played.
+ */
+function refuseFeatureCycle(ledger, feature, units) {
+  const graph = dependsGraph(ledger);
+  graph.set(feature, [...(graph.get(feature) ?? []), ...units.map((u) => u.id)]);
+  for (const u of units)
+    for (const d of graph.get(u.id) ?? []) {
+      const loop = pathTo(graph, d, u.id);
+      if (loop) throw new Error(cycleMessage(ledger, [u.id, ...loop]));
+    }
+}
+
 /** A unit goes into work only ready: no TBD, no blocking D1, no blocking finding. */
 function refuseUnready(units, summaries) {
   for (const unit of units) {
@@ -163,6 +177,7 @@ export async function takeUnits(
   if (feature) {
     const systems = units.flatMap((u) => listOf(u.header.system)).filter((s) => s !== 'TBD');
     writes.push(featureFor(ledger, root, { id: feature, unitIds: ids, systems, today }));
+    refuseFeatureCycle(ledger, feature, units);
   }
 
   const paths = units.map((u) => basePaths(root, u));

package/lib/verify-stamp.js

@@ -37,9 +37,16 @@ export function codeTree(projectDir) {
     return r.stdout.trim();
   };
 
+  // `git add` fails on an exclude that names an ignored path (`.gcf-session` in .gitignore or
+  // info/exclude), tracked or not, and an ignored path stays out of the add anyway.
+  const ignored = git(projectDir, ['check-ignore', '--no-index', '--', ...NOT_CODE]).stdout.split(
+    /\r?\n/,
+  );
+  const excludes = NOT_CODE.filter((p) => !ignored.includes(p)).map((p) => `:(exclude)${p}`);
+
   try {
     if (existsSync(real)) copyFileSync(real, tmp);
-    step(['add', '-A', '--', '.', ...NOT_CODE.map((p) => `:(exclude)${p}`)]);
+    step(['add', '-A', '--', '.', ...excludes]);
     step(['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', ...NOT_CODE]);
 
     return step(['write-tree']);

package/lib/work-ops.js

@@ -36,6 +36,7 @@ import {
   knownIssueOf,
 } from './live.js';
 import { dropInbox } from './inbox.js';
+import { cycleMessage, dependsGraph, pathTo } from './design-check.js';
 import { refuseByPhase } from './phase.js';
 import { locked, runHolder } from './main-lock.js';
 import { dropAgentSession, releaseSession, sessionActive } from './session-mark.js';
@@ -830,6 +831,31 @@ function runFields(spec) {
   );
 }
 
+/**
+ * Refuse `depends` of item `id` that could never be played (Methodology §4.1): an `added` id
+ * that is the item itself, unknown, or in the graveyard; or a cycle back to the item. A new
+ * child is not in its feature's `children` yet: `parent` adds that edge.
+ */
+function checkDepends(ledger, id, depends, { added = depends, parent = null } = {}) {
+  if (new Set(added).size !== added.length) throw new Error('a dependency is named twice');
+  if (added.includes(id)) throw new Error(`${id} cannot depend on itself`);
+  const unknown = added.filter((d) => !ledger.known(d));
+  if (unknown.length) throw new Error(`depends on unknown ${unknown.join(', ')}`);
+  const dead = added.filter((d) => {
+    const { live, terminal } = ledger.where(d);
+
+    return !live.length && terminal.includes('killed');
+  });
+  if (dead.length)
+    throw new Error(`${dead.join(', ')} ended in the graveyard: it will never be played`);
+  const graph = dependsGraph(ledger).set(id, depends);
+  if (parent) graph.set(parent, [...(graph.get(parent) ?? []), id]);
+  for (const d of added) {
+    const loop = pathTo(graph, d, id);
+    if (loop) throw new Error(cycleMessage(ledger, [id, ...loop]));
+  }
+}
+
 /** Refuse a spec `item new` cannot honour; returns the gate the item gets. */
 function checkNew(ledger, spec) {
   const { id, type, gate, severity } = spec;
@@ -844,6 +870,7 @@ function checkNew(ledger, spec) {
   if (type === 'bug' && !SEVERITIES.includes(severity))
     throw new Error(`a bug needs --severity ${SEVERITIES.join('|')}`);
   checkRelease(spec);
+  checkDepends(ledger, id, spec.depends ?? [], { parent: spec.parent });
 
   return g;
 }
@@ -949,6 +976,42 @@ async function prioritizeItemsUnlocked(projectDir, ids, { commit = true } = {})
   return { ids, hash };
 }
 
+/** `before` with `add` added and `remove` taken out; refuses an id named twice or out of place. */
+function changedDepends(id, before, add, remove) {
+  const twice = [...add, ...remove].find((d, i, all) => all.indexOf(d) !== i);
+  if (twice) throw new Error(`${twice} is named twice`);
+  const listed = add.filter((d) => before.includes(d));
+  if (listed.length) throw new Error(`${id} already depends on ${listed.join(', ')}`);
+  const absent = remove.filter((d) => !before.includes(d));
+  if (absent.length) throw new Error(`${id} does not depend on ${absent.join(', ')}`);
+
+  return [...before.filter((d) => !remove.includes(d)), ...add];
+}
+
+/**
+ * Add ids to item `id`'s `depends` and remove others. One commit `gcf(depends)`. An added id
+ * must be one that can be played and close no cycle; a removed one may be anything listed, an
+ * unknown or a killed one included: removing it is how such a dependency gets fixed.
+ */
+async function setDependsUnlocked(projectDir, id, { add = [], remove = [], commit = true } = {}) {
+  if (!add.length && !remove.length) throw new Error('name ids to --add or --remove');
+  const ledger = await buildLedger(projectDir);
+  const item = ledger.item(id);
+  if (!item) throw new Error(`${id} is not a work item`);
+  refuseRunning(projectDir, id);
+  const depends = changedDepends(id, item.data.depends ?? [], add, remove);
+  checkDepends(ledger, id, depends, { added: add });
+  const hash = await commitMove(projectDir, `gcf(depends): ${id}`, {
+    files: [item.file],
+    // The item's own edits ride along, as with the §4.1 moves: a skill sets depends after it.
+    inputs: [item.file],
+    mutate: () => atomicWrite(item.file, serialize({ ...item.data, depends }, item.body)),
+    commit,
+  });
+
+  return { id, depends, 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.
@@ -1012,6 +1075,9 @@ export const dropItem = (projectDir, id, opts = {}) =>
 /** @type {typeof prioritizeItemsUnlocked} */
 export const prioritizeItems = (projectDir, ids, opts = {}) =>
   locked(projectDir, opts.commit ?? true, () => prioritizeItemsUnlocked(projectDir, ids, opts));
+/** @type {typeof setDependsUnlocked} */
+export const setDepends = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => setDependsUnlocked(projectDir, id, opts));
 /** @type {typeof newItemUnlocked} */
 export const newItem = (projectDir, spec) =>
   locked(projectDir, spec.commit ?? false, () => newItemUnlocked(projectDir, spec));

package/package.json

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

package/skills/gcf-card/SKILL.md

@@ -52,8 +52,9 @@ workflow:
 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
+20. set each item's dependencies with `ai-factory gcf depends <id> --add <ids>`: it commits the item's edits too, and a feature's child never depends on its feature
+21. rank the items with `ai-factory gcf prioritize <id> <id> …`: dependencies first, then by value
+22. 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/skills/gcf-triage/SKILL.md

@@ -18,7 +18,7 @@ forbidden_behaviors:
 - do not create an item or erase an entry without the human's yes: the agent proposes, the human approves
 - do not turn a feel complaint into a bug: "jump feels floaty" is a tune of the item that owns the jump, a bug is behaviour that breaks a rule or a test
 - do not open a second item for something `gcf/graveyard.md` already buried: name the line and ask whether the reason still holds
-- do not edit `gcf/inbox.md` by hand: `ai-factory gcf item new --from` and `ai-factory gcf inbox drop` own its lines
+- do not edit `gcf/inbox.md` by hand: `ai-factory gcf item new --from`, `ai-factory gcf inbox tag` and `ai-factory gcf inbox drop` own its lines
 
 workflow:
 1. run `ai-factory gcf inbox --json`; read `gcf/LIVE.md` and `gcf/INDEX.md` to know what exists and what is in work
@@ -30,7 +30,8 @@ workflow:
 7. a tune of an item waiting for its verdict or unplayed: leave the entry in the inbox, the note's only copy, until `/gcf-verdict <id> tune --note` records it and drops it; a tune of a kept mechanic is new work with `--reopens <id>`
 8. an idea for the design: write a unit with `TBD` slots in `gcf/design/<system>.md` and its backlog line, then run `ai-factory gcf inbox drop <in-id>`
 9. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
-10. report what each entry became and how many entries remain
+10. an entry the human keeps for later (an idea, a note): tag it with the tag the human names, `ai-factory gcf inbox tag <in-id> --add <tags>`, and leave it in the inbox
+11. report what each entry became and how many entries remain
 
 invocation:
 - run after a playtest session, after a CI run that added entries, or when the user asks to triage

package/templates/agents-block.md

@@ -1,42 +1,45 @@
-gcf_context:
-- the game's design and its work live in `gcf/`, and the `ai-factory gcf` commands and the gcf skills change them
-- read `gcf/INDEX.md` before anything else under `gcf/`: it lists every subsystem, design unit and work item
-- `gcf/LIVE.md` says what the game does now, and `gcf/PILLARS.md` says what it must stay
-- `ai-factory gcf board --json` gives the whole state in one read: the phase, the items by status with plan progress, the inbox and the open questions
-
-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 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 and the agent is Claude Code (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
-- a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) is answered by `ai-factory gcf-harness metrics`
-- 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, at most `dod_attempts` of `gcf/config.yml` red runs; still red: block the item with the diagnosis
-- `submit` and `close` refuse code that changed since its last green `gcf verify`: run it again after any fix; `--unverified "<why>"` is the human's call, never the agent's
-- then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
-- work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
-- in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:`, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
-- a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
-- a word added to a `not:` of `gcf/glossary.md` leaves `gcf/design/` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit as M4
-- 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:
-- do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md` or `gcf/INDEX.md` by hand: the commands own them
-- do not give a verdict or a decision: `verdict` and `decide` belong to the human, through the gcf-verdict skill
-- 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 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
-
-gcf_skills:
-- gcf-vision starts a game that has no design yet, and gcf-ingest imports a GDD into `gcf/design/`
-- gcf-card puts work into `gcf/work/`, and gcf-triage sorts `gcf/inbox.md`
-- gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
-- gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars
+gcf_context:
+- the game's design and its work live in `gcf/`, and the `ai-factory gcf` commands and the gcf skills change them
+- read `gcf/INDEX.md` before anything else under `gcf/`: it lists every subsystem, design unit and work item
+- `gcf/LIVE.md` says what the game does now, and `gcf/PILLARS.md` says what it must stay
+- `ai-factory gcf board --json` gives the whole state in one read: the phase, the items by status with plan progress, the inbox and the open questions
+
+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>" [--tags <a,b>]`, 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 and the agent is Claude Code (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
+- a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) is answered by `ai-factory gcf-harness metrics`
+- 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, at most `dod_attempts` of `gcf/config.yml` red runs; still red: block the item with the diagnosis
+- `submit` and `close` refuse code that changed since its last green `gcf verify`: run it again after any fix; `--unverified "<why>"` is the human's call, never the agent's
+- then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
+- work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
+- in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:`, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
+- a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
+- a word added to a `not:` of `gcf/glossary.md` leaves `gcf/design/` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit as M4
+- 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: `ai-factory gcf depends <id> --add <ids>` or `--remove <ids>`, never a hand edit
+- write what the human reads (a question, an assumption, a block reason, an inbox entry, a lesson, a report, an item's `title:`) in `language.ui` of `.ai-factory/config.yaml`, and the body of an item that is not a design unit in its `language.artifacts`
+- write in English whatever lands in a checked document: `gcf/design/`, `gcf/systems/`, `gcf/glossary.md`, `gcf/PILLARS.md`, `gcf/LIVE.md`, the body of a design unit's item but its `tuning:` and `notes:`, an item's `live:` summary; an answer that moves into a unit's slot goes there in English
+- never translate keys, statuses, ids, commands, `TBD`, `answer: q-NNN`, `## Handoff`, a `quote:` (it is verbatim from the GDD) or the fixed start of a block reason (`needs permission:`, `plan did not converge:`, `waits for`)
+- 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:
+- do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md` or `gcf/INDEX.md` by hand: the commands own them
+- do not give a verdict or a decision: `verdict` and `decide` belong to the human, through the gcf-verdict skill
+- 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 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
+
+gcf_skills:
+- gcf-vision starts a game that has no design yet, and gcf-ingest imports a GDD into `gcf/design/`
+- gcf-card puts work into `gcf/work/`, and gcf-triage sorts `gcf/inbox.md`
+- gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
+- gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars