gcf-aif-ext 0.10.2 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/lessons.js CHANGED
@@ -7,7 +7,7 @@ import { readFile } from 'node:fs/promises';
7
7
  import path from 'node:path';
8
8
  import { uiLanguage } from './aif-config.js';
9
9
  import { readRawConfig } from './gcf-paths.js';
10
- import { addInbox } from './inbox.js';
10
+ import { planAdd } from './inbox.js';
11
11
  import { isValidId } from './id.js';
12
12
 
13
13
  export const KINDS = ['tool', 'rules', 'framework', 'template', 'other'];
@@ -104,30 +104,46 @@ export async function lessonsPrompt(projectDir, id, { reply = 'cli' } = {}) {
104
104
  /** A lesson as the agent gave it, checked: `{kind, text, where}`. */
105
105
  function lessonOf(raw, i) {
106
106
  const kind = KINDS.includes(raw?.kind) ? raw.kind : 'other';
107
- const text = String(raw?.text ?? '')
108
- .replace(/\s+/g, ' ')
109
- .trim();
107
+ const text = String(raw?.text ?? '').trim();
110
108
  if (!text) throw new Error(`lesson ${i + 1} has no text`);
111
109
  const where = raw?.where ? String(raw.where).replace(/\s+/g, ' ').trim() : '';
112
110
 
113
- // An agent's free text must not read as an inbox tags field, nor fail the whole batch on it.
114
- const full = (where ? `${text} (${where})` : text).replace(/ \| tags:/g, ' / tags:');
115
-
116
- return { kind, text: full };
111
+ // An entry holds lines: the place it is about goes on the last one.
112
+ return { kind, text: where ? `${text}\n\n${where}` : text };
117
113
  }
118
114
 
119
115
  /**
120
- * Record `lessons` of item `id` as inbox entries; `{kind, text, where?}` each, a kind outside
121
- * KINDS reads as other. Returns the entries written.
116
+ * The plan that records `lessons` of item `id` as inbox entries; `{kind, text, where?}` each, a
117
+ * kind outside KINDS reads as other: the entries, their files, and how to write them.
122
118
  */
123
- export async function addLessons(root, id, lessons) {
119
+ export function planLessons(root, id, lessons, now = new Date().toISOString()) {
124
120
  if (!isValidId(id)) throw new Error(`${id} is not an item id`);
125
121
  if (!Array.isArray(lessons)) throw new Error('lessons must be a JSON array');
126
- const checked = lessons.map(lessonOf);
127
- const out = [];
128
- for (const l of checked) out.push(await addInbox(root, l.text, `lesson:${l.kind}:${id}`));
122
+ const taken = new Set();
123
+ const plans = lessons.map(lessonOf).map((l, i) => {
124
+ // A millisecond apart: the inbox lists them in the order the agent gave them.
125
+ const at = new Date(Date.parse(now) + i).toISOString();
126
+ const p = planAdd(root, l.text, `lesson:${l.kind}:${id}`, { now: at, taken });
127
+ taken.add(p.entry.id);
128
+
129
+ return p;
130
+ });
131
+
132
+ return {
133
+ entries: plans.map((p) => p.entry),
134
+ files: plans.flatMap((p) => p.files),
135
+ apply: async () => {
136
+ for (const p of plans) await p.apply();
137
+ },
138
+ };
139
+ }
140
+
141
+ /** Record `lessons` of item `id` as inbox entries at once (planLessons); returns the entries. */
142
+ export async function addLessons(root, id, lessons) {
143
+ const plan = planLessons(root, id, lessons);
144
+ await plan.apply();
129
145
 
130
- return out;
146
+ return plan.entries;
131
147
  }
132
148
 
133
149
  /** The lessons of a JSON file: an array, as the harness writes it. */
package/lib/plan-check.js CHANGED
@@ -1,27 +1,36 @@
1
1
  // `gcf plan check <id>` (Methodology §5.2.1): the deterministic check after each improve pass —
2
2
  // the plan exists, it holds task checkboxes, and the item's readset fits the context budget.
3
3
  // Whether the plan is any good is the improve passes' job; this only says it is usable.
4
- import { readFile } from 'node:fs/promises';
5
- import { existsSync } from 'node:fs';
4
+ import { existsSync, readFileSync } from 'node:fs';
6
5
  import path from 'node:path';
7
6
  import { buildLedger } from './ledger.js';
8
7
  import { buildContext } from './context.js';
9
8
 
9
+ /**
10
+ * An item's plan and its task checkboxes: `{plan, tasks, done}`, `tasks` null when there is no
11
+ * plan file. `data` is the item's frontmatter.
12
+ */
13
+ export function planTicks(projectDir, data) {
14
+ const plan = data.plan ?? `.ai-factory/plans/${data.id}.md`;
15
+ const file = path.resolve(projectDir, plan);
16
+ if (!existsSync(file)) return { plan, tasks: null, done: 0 };
17
+ const text = readFileSync(file, 'utf8');
18
+
19
+ return {
20
+ plan,
21
+ tasks: (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length,
22
+ done: (text.match(/^\s*- \[[xX]\] /gm) ?? []).length,
23
+ };
24
+ }
25
+
10
26
  export async function planCheck(projectDir, id) {
11
27
  const item = (await buildLedger(projectDir)).item(id);
12
28
  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
13
- const plan = item.data.plan ?? `.ai-factory/plans/${id}.md`;
14
- const file = path.resolve(projectDir, plan);
29
+ const { plan, tasks: found, done } = planTicks(projectDir, { ...item.data, id });
30
+ const tasks = found ?? 0;
15
31
  const problems = [];
16
- let tasks = 0;
17
- let done = 0;
18
- if (!existsSync(file)) problems.push(`no plan at ${plan}`);
19
- else {
20
- const text = await readFile(file, 'utf8');
21
- tasks = (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length;
22
- done = (text.match(/^\s*- \[[xX]\] /gm) ?? []).length;
23
- if (!tasks) problems.push(`${plan} has no task checkboxes (- [ ] …)`);
24
- }
32
+ if (found === null) problems.push(`no plan at ${plan}`);
33
+ else if (!tasks) problems.push(`${plan} has no task checkboxes (- [ ] …)`);
25
34
 
26
35
  const ctx = await buildContext(projectDir, id);
27
36
  if (ctx.over_budget)
package/lib/safe-path.js CHANGED
@@ -62,7 +62,8 @@ export async function withFileRollback(files, action, { gitCwd = null } = {}) {
62
62
  const index = gitCwd ? snapshotIndex(gitCwd, unique) : null;
63
63
  for (const file of unique) {
64
64
  try {
65
- snapshots.push([file, await readFile(file, 'utf8')]);
65
+ // Bytes, not text: a picture comes back as it was.
66
+ snapshots.push([file, await readFile(file)]);
66
67
  } catch (err) {
67
68
  if (err.code !== 'ENOENT') throw err;
68
69
  snapshots.push([file, null]);
@@ -30,6 +30,8 @@ const FROM = {
30
30
  drop: STORED,
31
31
  // What it waits for may change at any status; the core refuses an unknown id and a cycle.
32
32
  depends: STORED,
33
+ // A file given to the item (a chat image) changes no status.
34
+ attach: STORED,
33
35
  };
34
36
 
35
37
  /** Every move an item may be offered, in the board's order. */
package/lib/unit-ops.js CHANGED
@@ -233,7 +233,7 @@ function uncommitted(projectDir, file) {
233
233
  * @param {{files: string[], mutate: () => Promise<void>, commit: boolean, inputs?: string[]}} move
234
234
  */
235
235
  /** A worktree of the integrator (Methodology §7): its gcf/ state is main's to move. */
236
- const onWorkBranch = (projectDir) =>
236
+ export const onWorkBranch = (projectDir) =>
237
237
  /^work\//.test(
238
238
  spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
239
239
  cwd: projectDir,
@@ -77,7 +77,11 @@ const isSlug = (v) => typeof v === 'string' && SLUG.test(v);
77
77
  const slugList = (v) => Array.isArray(v) && v.every(isSlug);
78
78
  const isText = (v) => typeof v === 'string' && v.trim().length > 0;
79
79
  const nullable = (check) => (v) => v === null || v === undefined || check(v);
80
- const LIVE_SHAPE = 'live must be {none: <why>} or {changes: [...]} with at least one change';
80
+ // The exact form (fix D): an agent read the old message and guessed its way to the shape.
81
+ const LIVE_SHAPE =
82
+ 'live must be {none: "<why it changes no capability>"} or {changes: [{id: <capability ' +
83
+ 'slug>, change: added | modified | removed, summary: "<at most two sentences>"}]} with at ' +
84
+ 'least one change; summary is not needed for removed';
81
85
 
82
86
  /** At most two sentences and 250 characters: a table of contents, not a description. */
83
87
  export function summaryProblem(s) {
@@ -245,6 +249,8 @@ export function validateUntil(body) {
245
249
  const errors = [];
246
250
  const lines = String(body).split('\n');
247
251
  lines.forEach((line, i) => {
252
+ // A quoted line (an inbox entry's text in an item's note:) holds no annotation of its own.
253
+ if (line.startsWith('>')) return;
248
254
  for (const m of line.matchAll(/\[until:[^\]]*\]/g)) {
249
255
  if (!UNTIL_OK.test(m[0]))
250
256
  errors.push(
package/lib/work-ops.js CHANGED
@@ -3,8 +3,8 @@
3
3
  // that carries every file it touched: the item, history or graveyard, LIVE.md, the systems
4
4
  // docs, the parent feature, a removal item, the archived plan. Atomic: a refused commit rolls
5
5
  // every file back.
6
- import { readFile, unlink } from 'node:fs/promises';
7
- import { existsSync } from 'node:fs';
6
+ import { copyFile, mkdir, readFile, unlink } from 'node:fs/promises';
7
+ import { existsSync, lstatSync, readdirSync } from 'node:fs';
8
8
  import { spawnSync } from 'node:child_process';
9
9
  import { createHash } from 'node:crypto';
10
10
  import path from 'node:path';
@@ -15,7 +15,7 @@ import { atomicWrite, resolveInside } from './safe-path.js';
15
15
  import { allowedFrom, decisionFits, FEATURE_ONLY, fromOf } from './transitions.js';
16
16
  import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
17
17
  import { isValidId } from './id.js';
18
- import { commitMove, addConstraints } from './unit-ops.js';
18
+ import { commitMove, addConstraints, onWorkBranch } from './unit-ops.js';
19
19
  import { openSystemDoc, upsertBlock } from './systems-doc.js';
20
20
  import {
21
21
  collapseLines,
@@ -35,12 +35,13 @@ import {
35
35
  revertDelta,
36
36
  knownIssueOf,
37
37
  } from './live.js';
38
- import { dropInbox } from './inbox.js';
38
+ import { planTake, untrackedEntries } from './inbox.js';
39
39
  import { cycleMessage, dependsGraph, pathTo } from './design-check.js';
40
40
  import { refuseByPhase } from './phase.js';
41
41
  import { locked, runHolder } from './main-lock.js';
42
42
  import { dropAgentSession, ownsMark, releaseSession, sessionActive } from './session-mark.js';
43
43
  import { dropStamp, unverifiedProblem } from './verify-stamp.js';
44
+ import { planTicks } from './plan-check.js';
44
45
 
45
46
  /**
46
47
  * Options of a committed move; each move reads the ones it needs.
@@ -263,8 +264,27 @@ function verifyGateProblem(projectDir, id, type) {
263
264
  }
264
265
  }
265
266
 
266
- /** The commit's tail of a move made without a green verify. */
267
- const unverifiedTail = (opts) => (opts.unverified ? ` (unverified: ${opts.unverified})` : '');
267
+ /**
268
+ * `close` and `submit` (AD-50), from a command and from the integrator alike: every task of the
269
+ * item's plan ticked, unless the human says why not (`unticked`, written into the move's
270
+ * commit). An item with no plan and a feature are not checked; the check trusts the ticks, not
271
+ * the agent's words. The integrator turns the refusal into a block.
272
+ */
273
+ function needTicked(m, opts) {
274
+ if (opts.unticked || m.item.data.type === 'feature') return;
275
+ const id = String(m.item.data.id);
276
+ const { tasks, done } = planTicks(m.projectDir, { ...m.item.data, id });
277
+ if (tasks !== null && done < tasks)
278
+ throw new Error(
279
+ `${id}: plan tasks not ticked: ${tasks - done} of ${tasks} — tick what is done, or block ` +
280
+ 'the item',
281
+ );
282
+ }
283
+
284
+ /** The commit's tail of a move made without a green verify, or with tasks left unticked. */
285
+ const unverifiedTail = (opts) =>
286
+ (opts.unverified ? ` (unverified: ${opts.unverified})` : '') +
287
+ (opts.unticked ? ` (unticked: ${opts.unticked})` : '');
268
288
 
269
289
  const writeItem = (item, data, body = item.body) => atomicWrite(item.file, serialize(data, body));
270
290
 
@@ -511,6 +531,7 @@ async function submitItemUnlocked(projectDir, id, opts = {}) {
511
531
  if (m.item.data.gate === 'auto')
512
532
  throw new Error(`${id} has gate auto: nobody waits for it — close it with gcf close ${id}`);
513
533
  refuseOpenDepends(m, 'submit', { waiting: true });
534
+ needTicked(m, opts);
514
535
  needVerified(m, opts);
515
536
  const status = m.item.data.gate === 'verdict' ? 'awaiting-verdict' : 'awaiting-decision';
516
537
  const data = { ...without(m.item.data, 'blocked'), status, since: headHash(projectDir) };
@@ -587,6 +608,7 @@ async function closeItemUnlocked(projectDir, id, opts = {}) {
587
608
  if (m.item.data.gate !== 'auto')
588
609
  throw new Error(`${id} has gate ${m.item.data.gate}: submit it, the operator closes it`);
589
610
  refuseOpenDepends(m, 'close');
611
+ needTicked(m, opts);
590
612
  needVerified(m, opts);
591
613
  if (unplayed) closeUnplayed(m);
592
614
  else await closeEnding(m, constraints);
@@ -926,8 +948,18 @@ function newItemText(spec, gate, since) {
926
948
  ...optionalFields(spec, gate, since),
927
949
  created: spec.date ?? today(),
928
950
  };
951
+ // `note`: the rest of the inbox entry it came from, quoted: a line of it that reads `key:`
952
+ // must not open a section of the item.
953
+ // An entry of one line leaves no note.
954
+ const quoted = spec.note
955
+ ? spec.note
956
+ .split('\n')
957
+ .map((l) => (l ? `> ${l}` : '>'))
958
+ .join('\n')
959
+ : '';
929
960
  const body =
930
- `\nintent:\n- ${title ?? 'TBD: what this item changes'}\n` +
961
+ `\nintent:\n- ${title || 'TBD: what this item changes'}\n` +
962
+ (quoted ? `\nnote:\n${quoted}\n` : '') +
931
963
  (type === 'bug' ? '\nrepro:\n- TBD: the steps that show the bug\n' : '');
932
964
 
933
965
  return serialize(data, body);
@@ -1012,10 +1044,57 @@ async function setDependsUnlocked(projectDir, id, { add = [], remove = [], commi
1012
1044
  return { id, depends, hash };
1013
1045
  }
1014
1046
 
1047
+ // An attachment is a picture or a file the operator gave the item (a chat image, a reference).
1048
+ const ATTACH_MAX = 10 * 1024 * 1024;
1049
+
1050
+ /**
1051
+ * Copy `file` into `gcf/work/<id>/attachments/` under its own name (`-2`, `-3`… on a clash)
1052
+ * and commit it alone, `gcf(attach)`. A running item takes it too: the file is new, the item's
1053
+ * own file is not touched; but the commit gate refuses while `gcf/` has uncommitted changes
1054
+ * (a main-mode session's live: delta, an item made and not committed). A link or a file over
1055
+ * 10 MB is refused.
1056
+ */
1057
+ async function attachItemUnlocked(projectDir, id, file, { commit = true } = {}) {
1058
+ const ledger = await buildLedger(projectDir);
1059
+ if (!ledger.item(id)) throw new Error(`${id} is not a work item`);
1060
+ const st = lstatOr(file);
1061
+ if (!st?.isFile()) throw new Error(`${file} is not a file (a link is refused)`);
1062
+ if (st.size > ATTACH_MAX) throw new Error(`${file} is over 10 MB`);
1063
+ const dir = path.join(gcfOf(projectDir), 'work', id, 'attachments');
1064
+ const { name, ext } = path.parse(file);
1065
+ let to = path.join(dir, `${name}${ext}`);
1066
+ for (let n = 2; existsSync(to); n++) to = path.join(dir, `${name}-${n}${ext}`);
1067
+ const hash = await commitMove(projectDir, `gcf(attach): ${id}`, {
1068
+ files: [to],
1069
+ mutate: async () => {
1070
+ await mkdir(dir, { recursive: true });
1071
+ await copyFile(file, to);
1072
+ },
1073
+ commit,
1074
+ });
1075
+
1076
+ return { id, file: path.relative(projectDir, to).replaceAll('\\', '/'), hash };
1077
+ }
1078
+
1079
+ function lstatOr(file) {
1080
+ try {
1081
+ return lstatSync(file);
1082
+ } catch {
1083
+ return null;
1084
+ }
1085
+ }
1086
+
1087
+ /** @type {typeof attachItemUnlocked} */
1088
+ export const attachItem = (projectDir, id, file, opts = {}) =>
1089
+ locked(projectDir, opts.commit ?? true, () => attachItemUnlocked(projectDir, id, file, opts));
1090
+
1015
1091
  /**
1016
1092
  * A new work item in ready (or blocked), no commit. A design unit enters work through `take`,
1017
1093
  * not here: its body is the unit's slots. `from` erases the inbox entry it came from.
1018
1094
  */
1095
+ /** The longest note a new item takes (AD-39): a proposal's, or the operator's. */
1096
+ export const NOTE_MAX = 4000;
1097
+
1019
1098
  async function newItemUnlocked(projectDir, spec) {
1020
1099
  const root = gcfOf(projectDir);
1021
1100
  const ledger = await buildLedger(projectDir);
@@ -1025,8 +1104,14 @@ async function newItemUnlocked(projectDir, spec) {
1025
1104
  throw new Error(`reopens names ${spec.reopens}, which has not ended`);
1026
1105
  const file = path.join(root, 'work', `${spec.id}.md`);
1027
1106
  if (existsSync(file)) throw new Error(`gcf/work/${spec.id}.md already exists`);
1028
-
1029
- const writes = [[file, newItemText(spec, gate, headHash(projectDir))]];
1107
+ if (spec.note !== undefined && spec.note.length > NOTE_MAX)
1108
+ throw new Error(`the note is ${spec.note.length} characters: up to ${NOTE_MAX}`);
1109
+ const take = await takeEntry(projectDir, root, spec);
1110
+ // The note given first, then what the inbox entry it comes from says.
1111
+ const note = [spec.note, take.note].filter((x) => x?.trim()).join('\n\n') || undefined;
1112
+ const item = { ...spec, title: take.title, note };
1113
+
1114
+ const writes = [[file, newItemText(item, gate, headHash(projectDir))]];
1030
1115
  if (spec.parent) {
1031
1116
  const p = ledger.item(spec.parent);
1032
1117
  if (!p || p.data.type !== 'feature')
@@ -1036,14 +1121,12 @@ async function newItemUnlocked(projectDir, spec) {
1036
1121
  }
1037
1122
 
1038
1123
  // `commit` is for a caller with no console to commit from, a board: a run starts from HEAD.
1039
- // The inbox is raw input (merge=union): lines added without a commit ride along with it.
1040
- const inbox = spec.from ? [path.join(root, 'inbox.md')] : [];
1041
1124
  const hash = await commitMove(projectDir, `gcf(item): ${spec.id}`, {
1042
- files: [...writes.map((w) => w[0]), ...inbox],
1043
- inputs: inbox,
1125
+ files: [...writes.map((w) => w[0]), ...take.files],
1126
+ inputs: take.inputs,
1044
1127
  mutate: async () => {
1045
1128
  for (const [f, text] of writes) await atomicWrite(f, text);
1046
- if (spec.from) await dropInbox(root, spec.from);
1129
+ await take.apply();
1047
1130
  },
1048
1131
  commit: spec.commit ?? false,
1049
1132
  });
@@ -1051,6 +1134,50 @@ async function newItemUnlocked(projectDir, spec) {
1051
1134
  return { item: `gcf/work/${spec.id}.md`, hash };
1052
1135
  }
1053
1136
 
1137
+ /**
1138
+ * The inbox entry an item comes from (`--from`): its title for the item's unless one is given,
1139
+ * the rest of its text for the item's `note:` (the whole text when the title is another), its
1140
+ * pictures moved into the item's attachments with the links to them. Refused on a `work/`
1141
+ * branch, whose gcf/ state is main's. Entries not committed yet ride along with a committed
1142
+ * one: raw input. No `from`: nothing to take.
1143
+ */
1144
+ async function takeEntry(projectDir, root, spec) {
1145
+ if (!spec.from)
1146
+ return { title: spec.title, note: undefined, files: [], inputs: [], apply: async () => {} };
1147
+ if (onWorkBranch(projectDir))
1148
+ throw new Error('an inbox entry is taken on main: a work/ branch records no inbox move');
1149
+ const pictures = path.join(root, 'work', spec.id, 'attachments');
1150
+ // An empty folder a failed try left behind holds nothing to overwrite.
1151
+ if (existsSync(pictures) && readdirSync(pictures).length)
1152
+ throw new Error(`gcf/work/${spec.id}/attachments/ already exists`);
1153
+ const take = await planTake(root, spec.from, pictures);
1154
+ const { title: own, text } = take.entry;
1155
+ const relink = (s) => s.replaceAll(`${spec.from}/attachments/`, `${spec.id}/attachments/`);
1156
+ // The entry's own title, given back as it is (a board's "→ item"), counts as the same one.
1157
+ // A blank --title is none: the entry's own goes.
1158
+ const given = spec.title?.trim() ? spec.title : undefined;
1159
+ const same = given === undefined || given === own || given === relink(own);
1160
+ const title = relink(given ?? own);
1161
+ const lines = text.split('\n');
1162
+ const first = lines.findIndex((l) => l.trim());
1163
+ const rest = same
1164
+ ? lines
1165
+ .slice(first + 1)
1166
+ .join('\n')
1167
+ .trim()
1168
+ : text;
1169
+ const note = relink(rest);
1170
+ const loose = spec.commit ? untrackedEntries(projectDir) : [];
1171
+
1172
+ return {
1173
+ ...take,
1174
+ title,
1175
+ note,
1176
+ files: [...take.files, ...loose],
1177
+ inputs: [...take.inputs, ...loose],
1178
+ };
1179
+ }
1180
+
1054
1181
  /** @type {typeof submitItemUnlocked} */
1055
1182
  export const submitItem = (projectDir, id, opts = {}) =>
1056
1183
  locked(projectDir, opts.commit ?? true, () => submitItemUnlocked(projectDir, id, opts));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.10.2",
3
+ "version": "0.12.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: gcf-chat
3
+ description: Talk with the human about the GCF project in the board's project chat - answer questions from gcf/ and the runs, propose new work items, make the moves the human approves. Use when the session is a project chat thread of the board, or the user says "/gcf-chat".
4
+ ---
5
+
6
+ mode: human gate
7
+
8
+ purpose:
9
+ - answer the human's questions about the game, its design, its work items and its runs from what `gcf/` and the run files say
10
+ - turn a bug, an idea or a task the talk finds into a proposed work item the human accepts with one click
11
+ - make a move the human asks for through its `ai-factory gcf` command, which the chat shows the human as a card first
12
+
13
+ inputs:
14
+ - the human's messages, one turn each
15
+ - the thread's context file when the thread is bound to an item: the paths of the item's file, its plan, its run's log and run chat, its commits
16
+
17
+ preconditions:
18
+ - `gcf/` exists and `ai-factory gcf board --json` runs
19
+ - the board started this session: a project chat asks the human before each change
20
+
21
+ forbidden_behaviors:
22
+ - do not make the human's moves: `verdict`, `decide`, `question answer`, `unblock`, `phase next`, `pillar`, `permissions`, `config set`, `hooks-install`; the rules refuse them to any agent
23
+ - do not run `ai-factory gcf-harness run|stop|chat|init` or `ai-factory extension`: the rules refuse them; name the board's button instead
24
+ - do not make a new item with `ai-factory gcf item new`: propose it with the `propose_item_new` tool of the `gcf` MCP server, and the human's click makes it
25
+ - do not write code or edit files to fix what the talk finds: a fix is a work item, and its run builds it
26
+ - do not answer from memory what a file says: read the file, then answer
27
+ - do not ask again for a move the human refused: say what it would have done and leave it
28
+ - do not read the board's own folder: it holds the human's token
29
+
30
+ workflow:
31
+ 1. read `gcf/INDEX.md`, then run `ai-factory gcf board --json` for the phase, the items by status and the inbox
32
+ 2. a thread bound to an item: read the item's file, its plan, its run's log and run chat first, the paths the context file names, before the first answer
33
+ 3. answer the question from the files you read, with the paths that say it; for the runs' numbers run `ai-factory gcf-harness metrics` when the project has the harness
34
+ 4. a bug, an idea or a task that is new work: call `propose_item_new` with its id, type, title, subsystems and a note of what its run should know; note length <= 4000 characters
35
+ 5. a raw thought that is not work yet: propose to put it in the inbox with `ai-factory gcf inbox add`
36
+ 6. a move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
37
+ 7. say in one line what changed, or that nothing did
38
+
39
+ invocation:
40
+ - run at the start of a project chat thread the board opens, and when the user types `/gcf-chat`
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: gcf-triage
3
- description: Triage gcf/inbox.md - playtest notes, CI failures, the agent's ideas and requests - into work items, tunes, ideas for the design, or noise, with the human approving each call. Use after a playtest session or when the user says "разбери инбокс".
3
+ description: Triage the gcf/inbox/ entries - playtest notes, CI failures, the agent's ideas and requests - into work items, tunes, ideas for the design, or noise, with the human approving each call. Use after a playtest session or when the user says "разбери инбокс".
4
4
  ---
5
5
 
6
6
  mode: human gate
@@ -9,7 +9,7 @@ purpose:
9
9
  - turn raw input into decided work: each inbox entry becomes a work item, a tune note, a design unit, a graveyard line, or nothing - and leaves the inbox
10
10
 
11
11
  inputs:
12
- - `gcf/inbox.md`, read through `ai-factory gcf inbox --json`
12
+ - `gcf/inbox/in-<id>.md`, one file an entry, read through `ai-factory gcf inbox --json`: each entry has a `title` (its first line) and a `text` that may run several lines
13
13
 
14
14
  preconditions:
15
15
  - `gcf/` exists and the inbox holds entries
@@ -18,7 +18,8 @@ forbidden_behaviors:
18
18
  - do not create an item or erase an entry without the human's yes: the agent proposes, the human approves
19
19
  - 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
20
20
  - do not open a second item for something `gcf/graveyard.md` already buried: name the line and ask whether the reason still holds
21
- - 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
21
+ - do not edit or delete a file in `gcf/inbox/` by hand: `ai-factory gcf item new --from`, `ai-factory gcf inbox tag` and `ai-factory gcf inbox drop` own the entries
22
+ - do not triage on a `work/` branch: `inbox tag`, `inbox drop` and `item new --from` refuse there; triage on main
22
23
 
23
24
  workflow:
24
25
  1. run `ai-factory gcf inbox --json`; read `gcf/LIVE.md` and `gcf/INDEX.md` to know what exists and what is in work
@@ -27,11 +28,12 @@ workflow:
27
28
  4. for each entry propose one call with its fields: a bug gets type `bug`, severity and a repro; a tune names the item and the note; an idea names the subsystem; a duplicate names the item it repeats
28
29
  5. present the calls to the human, calls per message <= 5, and apply only the approved ones
29
30
  6. a bug or other work: run `ai-factory gcf item new <id> --type <type> [--severity <level>] --from <in-id>`, then write its `intent:` and `repro:`
30
- 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>`
31
- 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>`
32
- 9. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
33
- 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
34
- 11. report what each entry became and how many entries remain
31
+ 7. `--from` without `--title` makes the entry's title the item's title and puts the rest of its text in a `note:` block, its pictures in `gcf/work/<id>/attachments/`; with your own `--title` the whole text goes into `note:`
32
+ 8. 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>`
33
+ 9. 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>`
34
+ 10. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
35
+ 11. 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
36
+ 12. report what each entry became and how many entries remain
35
37
 
36
38
  invocation:
37
39
  - run after a playtest session, after a CI run that added entries, or when the user asks to triage
@@ -6,15 +6,18 @@ gcf_context:
6
6
 
7
7
  gcf_work:
8
8
  - 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
9
- - 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>"`
9
+ - 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>]` (an entry `gcf/inbox/in-<id>.md`), and the gcf-triage skill sorts it later; a text that starts with a hyphen goes as `inbox add --text="<text>"`
10
+ - a text of several lines (its first line becomes the title) goes through stdin: `ai-factory gcf inbox add --text-file - <<'EOF'`, the lines, then `EOF`
10
11
  - before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
11
12
  - 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
12
13
  - 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`
13
14
  - 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
15
+ - the `live:` delta is YAML in the item's frontmatter, one of two forms: `live: {none: "<why it changes no capability>"}`, or `live:` with `changes:`, a list of `{id: <capability slug>, change: added | modified | removed, summary: "<at most two sentences>"}` (a removed one needs no summary)
16
+ - before `submit` or `close`, tick every task of the item's plan that is done, the verify and the review included: both refuse a plan with unticked tasks; `--unticked "<why>"` is the human's call, never the agent's
14
17
  - `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
15
18
  - 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
16
19
  - work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
17
- - 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
20
+ - in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:` and new inbox entries, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
18
21
  - a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
19
22
  - 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
20
23
  - 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>"`
@@ -22,14 +25,18 @@ gcf_work:
22
25
  - `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
23
26
  - 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
24
27
  - 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
28
+ - a picture or file the human gives an item goes to `ai-factory gcf item attach <id> --file <path>` (its `gcf/work/<id>/attachments/`, committed); read an item's attachments before you plan it
25
29
  - 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`
26
30
  - 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
27
31
  - 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`)
28
32
  - 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`
29
33
  - 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>"`
34
+ - a new item's `--note "<text>"` (or `--note-file -` for several lines) says what its run should know, up to 4000 characters
35
+ - in the project chat (the gcf-chat skill) a new item is proposed with the `propose_item_new` tool of the `gcf` MCP server, not made with `item new`: the human's click makes it
36
+ - a chat thread bound to an item reads the item's file, its plan, its run's log and run chat first (the paths its context names), answers the question, and only then proposes a move
30
37
 
31
38
  gcf_forbidden:
32
- - do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md` or `gcf/INDEX.md` by hand: the commands own them
39
+ - do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md`, `gcf/inbox/` or `gcf/INDEX.md` by hand: the commands own them
33
40
  - do not give a verdict or a decision: `verdict` and `decide` belong to the human, through the gcf-verdict skill
34
41
  - do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
35
42
  - do not run `ai-factory gcf phase next`: the phase moves on the human's word only
@@ -40,6 +47,7 @@ gcf_forbidden:
40
47
 
41
48
  gcf_skills:
42
49
  - gcf-vision starts a game that has no design yet, and gcf-ingest imports a GDD into `gcf/design/`
43
- - gcf-card puts work into `gcf/work/`, and gcf-triage sorts `gcf/inbox.md`
50
+ - gcf-card puts work into `gcf/work/`, and gcf-triage sorts the entries of `gcf/inbox/`
44
51
  - gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
45
52
  - gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars
53
+ - gcf-chat is the board's project chat: answers from `gcf/` and the runs, proposals of new items, the moves the human approves
@@ -18,6 +18,13 @@ dod_timeout_min: 60
18
18
  context_handoff_pct: 60
19
19
  context_window: 0
20
20
  auto_compact_pct: 0
21
+ # The chat of a board's agent run (Harness-PRD §10): what the agent asks you by a question card
22
+ # (d1: only your decisions; all: every question of substance; none: nothing, it decides) and the
23
+ # minutes a question waits before the agent takes its default (0: nobody watches, as for a night
24
+ # run; a main run's whole queue waits with it). Uncomment to change:
25
+ # chat:
26
+ # ask: d1
27
+ # answer_timeout_min: 15
21
28
  # Lessons (Methodology §5.2.2): at the end of each session on an item its agent says what got in
22
29
  # its way, into the inbox. `ai-factory gcf lessons prompt <id>` prints the questions. Uncomment to
23
30
  # turn them off, to ask what the project's template should learn, or to add questions: