gcf-aif-ext 0.22.1 → 0.23.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
@@ -1,6 +1,7 @@
1
1
  // Lessons (Methodology §5.2.2): at the end of a session on a work item, its agent says what got in
2
2
  // its way — a tool, a rule, the framework, the project's template. Each answer is an inbox entry
3
- // of the category `lesson`, its kind the detail, with its `item`, so the operator triages it like any raw input and the
3
+ // of the category `lesson`, its kind the detail, with its `item`, so the operator triages it like
4
+ // any raw input and the
4
5
  // board shows where agents struggle. The questions stay out of the agent's working context until
5
6
  // the session ends: the harness asks them in one more turn, `/gcf-run` asks them at its close.
6
7
  import { readFile } from 'node:fs/promises';
package/lib/main-lock.js CHANGED
@@ -31,7 +31,7 @@ export const alive = (pid) => {
31
31
  */
32
32
  export const MAIN_RUN = '.main-run';
33
33
 
34
- /** The item a run lock names on its second line (the main run's: the item it works now), or null. */
34
+ /** The item a run lock names on its second line (a main run's: what it works now), or null. */
35
35
  export function lockedItem(projectDir, id) {
36
36
  try {
37
37
  const file = path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${id}.lock`);
package/lib/migrate.js CHANGED
@@ -200,6 +200,7 @@ export function unitText(c, id, depends) {
200
200
  ...prov,
201
201
  ].join('\n');
202
202
  }
203
+
203
204
  /** The slug of a name, Cyrillic transliterated, or null when nothing in it slugs. */
204
205
  /** The slug of a name, or null when the name has no latin letter or digit to slug. */
205
206
  function safeSlug(name) {
@@ -55,7 +55,8 @@ function holdsBuild(ledger, item) {
55
55
  * the D1 questions that hold it), its items by status (a release is the operator's and counts
56
56
  * for nothing), and `empty`, `built`, `played`; then `build_milestone` (the first not built)
57
57
  * and `play_milestone` (the first built and not played) by name, and `milestone_order`: each
58
- * item of an earlier milestone that depends on an item of a later one. `units` is the design check's unit summaries.
58
+ * item of an earlier milestone that depends on an item of a later one. `units` is the design
59
+ * check's unit summaries.
59
60
  * @param {string} projectDir
60
61
  * @param {any} ledger buildLedger's
61
62
  * @param {{id: string, milestone: string, blocked_by: string[]}[]} units
@@ -59,8 +59,14 @@ export function putBlock(lines, specs, spec, rendered, { raw = false } = {}) {
59
59
  // Header fields stand line under line; a block stands apart from its neighbours.
60
60
  const tight = (b) => Boolean(spec.header && header(b));
61
61
  const prev = blocks.filter((b) => order.indexOf(b.key) < order.indexOf(spec.key)).at(-1);
62
- if (!prev)
63
- return blocks.length ? [...rendered, ...(tight(blocks[0]) ? [] : ['']), ...lines] : rendered;
62
+ if (!prev && blocks.length) return [...rendered, ...(tight(blocks[0]) ? [] : ['']), ...lines];
63
+ if (!prev) {
64
+ // A body of words with no block keeps them, over the new one.
65
+ const last = lines.findLastIndex((l) => l.trim());
66
+
67
+ return last < 0 ? rendered : [...lines.slice(0, last + 1), '', ...rendered, ''];
68
+ }
69
+
64
70
  const tail = lines.slice(prev.end);
65
71
  const gap = tight(prev) ? [] : [''];
66
72
  const after = !tight(prev) && tail[0]?.trim() ? [''] : [];
@@ -97,11 +103,53 @@ export function upsertBlock(rawBody, key, addLines, order) {
97
103
  while (lines.length > 1 && !lines[0].trim()) lines.shift();
98
104
  while (lines.length > 1 && !lines.at(-1).trim() && !lines.at(-2).trim()) lines.pop();
99
105
  }
106
+
100
107
  const put = putBlock(lines, specs, { key }, [`${key}:`, ...kept, ...fresh], { raw: true });
101
108
 
102
109
  return `${lead}${put.join('\n')}`.replace(/\n{3,}/g, '\n\n');
103
110
  }
104
111
 
112
+ /**
113
+ * The blocks a text names, each with its lines as written, and `outside`: its first line with
114
+ * words that stand in no block, or null. `lines` empty: only its key, with no value or item.
115
+ * @param {string} rawText
116
+ */
117
+ export function blocksNamed(rawText) {
118
+ const text = lf(rawText);
119
+ const raw = text.split('\n');
120
+ const blocks = blocksOf(text, { raw: true });
121
+ const inBlock = (n) => blocks.some((b) => n >= b.start && n <= b.end);
122
+ const outside = parseBlocks(text).lines.findIndex((l, i) => l.trim() && !inBlock(i + 1));
123
+ const lines = (b) => {
124
+ const own = raw.slice(b.start - 1, b.end);
125
+
126
+ return own.length === 1 && !String(b.value ?? '').trim() ? [] : own;
127
+ };
128
+
129
+ return {
130
+ blocks: blocks.map((b) => ({ key: b.key, lines: lines(b) })),
131
+ outside: outside < 0 ? null : raw[outside],
132
+ };
133
+ }
134
+
135
+ /**
136
+ * The body with block `key` set to `rendered`: in place, or where `order` (the profile's block
137
+ * keys, see blockOrder) puts a new one; `rendered` empty takes it out.
138
+ * @param {string} rawBody
139
+ * @param {string} key
140
+ * @param {string[]} rendered
141
+ * @param {string[]} order
142
+ */
143
+ export function replaceBlock(rawBody, key, rendered, order) {
144
+ const body = lf(rawBody);
145
+ const specs = (order.includes(key) ? order : [...order, key]).map((k) => ({ key: k }));
146
+ const lead = body.match(/^\n*/)[0];
147
+ const lines = body.slice(lead.length).split('\n');
148
+ const put = putBlock(lines, specs, { key }, rendered, { raw: true });
149
+
150
+ return `${lead}${put.join('\n')}`.replace(/\n{3,}/g, '\n\n');
151
+ }
152
+
105
153
  /**
106
154
  * The `key:` bullet block without `dropLines` — the inverse of upsertBlock. A block left empty
107
155
  * gets the `- none:` placeholder back, as a new systems doc starts.
@@ -38,6 +38,8 @@ const FROM = {
38
38
  mode: STORED,
39
39
  // Nor its card's gates: they hold its next move.
40
40
  gates: STORED,
41
+ // Nor a fix of its text; only an unplayed body is frozen (§5.4).
42
+ amend: STORED.filter((s) => s !== 'unplayed'),
41
43
  };
42
44
 
43
45
  /** Every move an item may be offered, in the board's order. */
package/lib/work-ops.js CHANGED
@@ -16,7 +16,7 @@ import { allowedFrom, decisionFits, FEATURE_ONLY, fromOf } from './transitions.j
16
16
  import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
17
17
  import { deriveId, isValidId } from './id.js';
18
18
  import { commitMove, addConstraints, onWorkBranch } from './unit-ops.js';
19
- import { openSystemDoc, upsertBlock } from './systems-doc.js';
19
+ import { blocksNamed, blocksOf, openSystemDoc, replaceBlock, upsertBlock } from './systems-doc.js';
20
20
  import { blockOrder } from './design.js';
21
21
  import {
22
22
  collapseLines,
@@ -54,6 +54,7 @@ import {
54
54
  } from './git.js';
55
55
  import { verdictDeferred } from './gates.js';
56
56
  import { appendQuestions, questionsFile } from './questions.js';
57
+ import { refusal } from './refusal.js';
57
58
 
58
59
  /**
59
60
  * Options of a committed move; each move reads the ones it needs.
@@ -204,12 +205,12 @@ function refuseRunning(projectDir, id, self = process.env.GCF_RUN_ITEM ?? null)
204
205
  * Open a move on item `id` from the statuses `move` allows: the files it touches, its steps,
205
206
  * and the LIVE.md edits folded into a single write at the end.
206
207
  */
207
- async function begin(projectDir, id, move) {
208
+ async function begin(projectDir, id, move, refuse = refuseRunning) {
208
209
  const root = gcfOf(projectDir);
209
210
  const ledger = await buildLedger(projectDir);
210
211
  const item = itemOf(ledger, id);
211
212
  need(move, item);
212
- refuseRunning(projectDir, id);
213
+ refuse(projectDir, id);
213
214
  const files = [item.file];
214
215
  const steps = [];
215
216
  const liveOps = [];
@@ -224,6 +225,8 @@ async function begin(projectDir, id, move) {
224
225
  /** @type {Set<string>} every item the move touches, for its commit's GCF-Items */
225
226
  items: new Set([id]),
226
227
  files,
228
+ /** @type {string[]} the files it may carry with edits not yet committed */
229
+ inputs: [item.file],
227
230
  touch: (...f) => files.push(...f.filter((x) => !files.includes(x))),
228
231
  step: (fn) => steps.push(fn),
229
232
  live: (fn) => {
@@ -250,7 +253,7 @@ async function finish(m, key, tail, commit) {
250
253
  files: m.files,
251
254
  mutate: m.run,
252
255
  commit,
253
- inputs: [m.item.file],
256
+ inputs: m.inputs,
254
257
  key,
255
258
  items: [...m.items],
256
259
  });
@@ -1107,6 +1110,181 @@ async function unblockItemUnlocked(projectDir, id, opts = {}) {
1107
1110
  return { id, hash: await finish(m, 'unblock', id, commit) };
1108
1111
  }
1109
1112
 
1113
+ // The blocks `amend` leaves alone: where the card came from, and the record of its verdicts.
1114
+ const NOT_AMENDED = ['provenance', 'tuning'];
1115
+
1116
+ /** Refuse a fix of the text a live run reads, in words a person can act on. */
1117
+ function refuseAmendLive(projectDir, id) {
1118
+ if (!runHolder(projectDir, id) && !sessionActive(projectDir, id)) return;
1119
+ throw refusal(
1120
+ 'running',
1121
+ {},
1122
+ `${id} is being worked on right now, and that agent reads this text: tell it through the ` +
1123
+ 'chat of its run, or amend the card once the run has ended',
1124
+ );
1125
+ }
1126
+
1127
+ /** The hash of what a card's form shows: an edit of its text since then is not overwritten. */
1128
+ const amendBase = ({ data, body }) =>
1129
+ createHash('sha1')
1130
+ .update(`${data.title ?? ''}\n${String(body).replace(/\r\n/g, '\n').trim()}`)
1131
+ .digest('hex');
1132
+
1133
+ /** The card's text a human edits: the blocks `amend` may replace. */
1134
+ const amendableText = (body) => {
1135
+ const text = NOT_AMENDED.reduce((t, key) => replaceBlock(t, key, [], []), body);
1136
+ const lines = text.split('\n');
1137
+
1138
+ // The blocks alone: words outside them stay in the card, and a text may not name them.
1139
+ return blocksOf(text, { raw: true })
1140
+ .map((b) => lines.slice(b.start - 1, b.end).join('\n'))
1141
+ .join('\n\n');
1142
+ };
1143
+
1144
+ /** The lines of each block of a body, by key. */
1145
+ const blockLinesOf = (body) => {
1146
+ const lines = String(body).split('\n');
1147
+
1148
+ return new Map(
1149
+ blocksOf(body, { raw: true }).map((b) => [b.key, lines.slice(b.start - 1, b.end)]),
1150
+ );
1151
+ };
1152
+
1153
+ /** What a fix changes, block by block, in the order of the new text. */
1154
+ function amendChanges(item, title, body) {
1155
+ const before = blockLinesOf(String(item.body).replace(/\r\n/g, '\n'));
1156
+ const after = blockLinesOf(body);
1157
+ const same = (a = [], b = []) => a.join('\n') === b.join('\n');
1158
+ const keys = [...after.keys(), ...[...before.keys()].filter((k) => !after.has(k))];
1159
+ const was = item.data.title ?? '';
1160
+
1161
+ return [
1162
+ ...(title === was ? [] : [{ block: 'title', old: was ? [was] : [], new: [title] }]),
1163
+ ...keys
1164
+ .filter((k) => !same(before.get(k), after.get(k)))
1165
+ .map((k) => ({ block: k, old: before.get(k) ?? [], new: after.get(k) ?? [] })),
1166
+ ];
1167
+ }
1168
+
1169
+ /** `text`, in block syntax, over `body`: the blocks it names, none the card must keep. */
1170
+ function replaceNamed(body, text, item, order) {
1171
+ const { blocks, outside } = blocksNamed(text);
1172
+ if (outside !== null)
1173
+ throw new Error(
1174
+ `the text has a line outside its blocks: "${outside}" — a block starts with its key at the ` +
1175
+ 'start of a line, e.g. check:',
1176
+ );
1177
+ if (!blocks.length) throw new Error('the text names no block: a block starts with its key');
1178
+ const named = blocks.map((b) => b.key);
1179
+ const twice = named.find((k, i) => named.indexOf(k) !== i);
1180
+ if (twice) throw new Error(`the text names block ${twice}: twice`);
1181
+ const kept = named.find((k) => NOT_AMENDED.includes(k));
1182
+ if (kept)
1183
+ throw new Error(`${kept}: stays as it is: an amend changes neither provenance: nor tuning:`);
1184
+ const alien = order && named.find((k) => !order.includes(k));
1185
+ if (alien)
1186
+ throw new Error(
1187
+ `a ${item.data.type} has no block ${alien}: its blocks are ${order.join(', ')}`,
1188
+ );
1189
+
1190
+ return blocks.reduce((b, { key, lines }) => replaceBlock(b, key, lines, order ?? []), body);
1191
+ }
1192
+
1193
+ /** The inbox entry a fix takes: its words for `notes:`, its pictures to the card, one by one. */
1194
+ async function amendEntry(projectDir, m, from) {
1195
+ if (onWorkBranch(projectDir))
1196
+ throw new Error('an inbox entry is taken on main: a work/ branch records no inbox move');
1197
+ const id = String(m.item.data.id);
1198
+ const take = await planTake(m.root, from, path.join(m.root, 'work', id, 'attachments'));
1199
+ const taken = take.pictures.filter((f) => existsSync(f)).map((f) => path.basename(f));
1200
+ if (taken.length)
1201
+ throw new Error(`gcf/work/${id}/attachments/ already holds ${taken.join(', ')}: rename it`);
1202
+ const relink = (s) => s.replaceAll(`${from}/attachments/`, `${id}/attachments/`);
1203
+ const lines = take.entry.text.split('\n');
1204
+ const rest = lines
1205
+ .slice(lines.findIndex((l) => l.trim()) + 1)
1206
+ .join('\n')
1207
+ .trim();
1208
+
1209
+ // An entry of one line is its title: nothing of what it says may be lost with it.
1210
+ return { ...take, note: relink(rest || take.entry.title), relink };
1211
+ }
1212
+
1213
+ /**
1214
+ * Fix a live card's text (docs/Amend-Plan.md): `text` replaces the blocks it names, `add` goes to
1215
+ * `notes:`, `title` replaces the title, `from` takes an inbox entry in the same commit. Its status
1216
+ * stays; a finding on the new text comes from the pre-commit gate, with its rollback. `dryRun`
1217
+ * writes nothing and may read a card a run holds: a form and a proposal show it.
1218
+ * @param {string} projectDir
1219
+ * @param {string} id
1220
+ * @param {{text?: string, add?: string, title?: string, from?: string, base?: string,
1221
+ * dryRun?: boolean, commit?: boolean}} [opts]
1222
+ */
1223
+ async function amendItemUnlocked(projectDir, id, opts = {}) {
1224
+ const { dryRun = false, commit = true } = opts;
1225
+ const asked = amendAsked(opts);
1226
+ const m = await begin(projectDir, id, 'amend', dryRun ? () => {} : refuseAmendLive);
1227
+ const entry = asked.from ? await amendEntry(projectDir, m, asked.from) : null;
1228
+ const { body, title } = await amendedCard(m.item, asked, entry);
1229
+ const changes = amendChanges(m.item, title, body);
1230
+ if (dryRun) return { id, base: amendBase(m.item), title, text: amendableText(body), changes };
1231
+ refuseAmendPointless(m.item, { asked, base: opts.base, changes, entry });
1232
+ if (entry) carryEntry(m, entry, commit);
1233
+ const data = asked.title ? { ...m.item.data, title } : m.item.data;
1234
+ m.step(() => writeItem(m.item, data, body));
1235
+
1236
+ return { id, changes, hash: await finish(m, 'amend', id, commit) };
1237
+ }
1238
+
1239
+ /** What a fix asks for, trimmed: a blank field is none, an over-long or broken one refused. */
1240
+ function amendAsked(opts) {
1241
+ const [text, add, title, from] = [opts.text, opts.add, opts.title, opts.from].map((v) =>
1242
+ String(v ?? '').trim(),
1243
+ );
1244
+ if (add.length > NOTE_MAX)
1245
+ throw new Error(`the lines to add are ${add.length} characters: up to ${NOTE_MAX}`);
1246
+ if (/[\r\n]/.test(title)) throw new Error('--title is one line');
1247
+
1248
+ return { text, add, title, from };
1249
+ }
1250
+
1251
+ /** The card's title and body after a fix: the blocks named, then the lines added. */
1252
+ async function amendedCard(item, { text, add, title }, entry) {
1253
+ const type = item.data.type;
1254
+ const order = UNIT_ITEM_TYPES.includes(type) ? await blockOrder(`unit-${type}`) : null;
1255
+ const named = text
1256
+ ? replaceNamed(String(item.body), text, item, order)
1257
+ : String(item.body).replace(/\r\n/g, '\n');
1258
+ const note = add ? (entry?.relink(add) ?? add) : entry?.note;
1259
+
1260
+ return {
1261
+ title: title || (item.data.title ?? ''),
1262
+ body: note ? await upsertItemNote({ ...item, body: named }, 'notes', note) : named,
1263
+ };
1264
+ }
1265
+
1266
+ /** A fix with nothing in it, or over a card edited since its form was read. */
1267
+ function refuseAmendPointless(item, { asked, base, changes, entry }) {
1268
+ const id = item.data.id;
1269
+ if (!asked.text && !asked.add && !asked.title && !asked.from)
1270
+ throw new Error(`${id}: nothing to change: give --text, --add, --title or --from`);
1271
+ if (base && base !== amendBase(item))
1272
+ throw refusal(
1273
+ 'stale',
1274
+ {},
1275
+ `${id} changed since this form was opened: read it again, nothing was written`,
1276
+ );
1277
+ if (!changes.length && !entry) throw new Error(`${id}: the card already says this`);
1278
+ }
1279
+
1280
+ /** An entry into the move's commit; one added without a commit rides along, as with `item new`. */
1281
+ function carryEntry(m, entry, commit) {
1282
+ const loose = commit ? untrackedEntries(m.projectDir) : [];
1283
+ m.touch(...entry.files, ...loose);
1284
+ m.inputs.push(...entry.inputs, ...loose);
1285
+ m.step(entry.apply);
1286
+ }
1287
+
1110
1288
  /** Any stored status → graveyard; an unplayed item leaves as a kill does.
1111
1289
  * @param {MoveOpts} [opts]
1112
1290
  */
@@ -1366,7 +1544,8 @@ async function setDependsUnlocked(projectDir, id, { add = [], remove = [], commi
1366
1544
 
1367
1545
  /**
1368
1546
  * Set how item `id`'s runs go: its `model` and `effort`, each given one a plain word, `default`
1369
- * taking the field off (the project's `agent.model|effort`, else Opus and High). One commit `gcf(item)`. A run in progress keeps
1547
+ * taking the field off (the project's `agent.model|effort`, else Opus and High). One commit
1548
+ * `gcf(item)`. A run in progress keeps
1370
1549
  * its own; the item's next run takes the new value.
1371
1550
  * @param {string} projectDir
1372
1551
  * @param {string} id
@@ -1578,8 +1757,9 @@ async function newItemUnlocked(projectDir, given) {
1578
1757
  if (spec.note !== undefined && spec.note.length > NOTE_MAX)
1579
1758
  throw new Error(`the note is ${spec.note.length} characters: up to ${NOTE_MAX}`);
1580
1759
  const take = await takeEntry(projectDir, root, spec);
1581
- // The note given first, then what the inbox entry it comes from says.
1582
- const note = [spec.note, take.note].filter((x) => x?.trim()).join('\n\n') || undefined;
1760
+ // A note given goes over what the entry says: a board's form shows that text and sends it back,
1761
+ // and a human's edit of it is the note.
1762
+ const note = spec.note?.trim() ? take.relink(spec.note) : take.note || undefined;
1583
1763
  const item = { ...spec, title: take.title, note };
1584
1764
 
1585
1765
  const writes = [
@@ -1613,7 +1793,14 @@ async function newItemUnlocked(projectDir, given) {
1613
1793
  */
1614
1794
  async function takeEntry(projectDir, root, spec) {
1615
1795
  if (!spec.from)
1616
- return { title: spec.title, note: undefined, files: [], inputs: [], apply: async () => {} };
1796
+ return {
1797
+ title: spec.title,
1798
+ note: undefined,
1799
+ relink: (s) => s,
1800
+ files: [],
1801
+ inputs: [],
1802
+ apply: async () => {},
1803
+ };
1617
1804
  if (onWorkBranch(projectDir))
1618
1805
  throw new Error('an inbox entry is taken on main: a work/ branch records no inbox move');
1619
1806
  const pictures = path.join(root, 'work', spec.id, 'attachments');
@@ -1643,6 +1830,7 @@ async function takeEntry(projectDir, root, spec) {
1643
1830
  ...take,
1644
1831
  title,
1645
1832
  note,
1833
+ relink,
1646
1834
  files: [...take.files, ...loose],
1647
1835
  inputs: [...take.inputs, ...loose],
1648
1836
  };
@@ -1669,6 +1857,11 @@ export const blockItem = (projectDir, id, opts = {}) =>
1669
1857
  /** @type {typeof unblockItemUnlocked} */
1670
1858
  export const unblockItem = (projectDir, id, opts = {}) =>
1671
1859
  locked(projectDir, opts.commit ?? true, () => unblockItemUnlocked(projectDir, id, opts));
1860
+ /** @type {typeof amendItemUnlocked} */
1861
+ export const amendItem = (projectDir, id, opts = {}) =>
1862
+ locked(projectDir, !opts.dryRun && (opts.commit ?? true), () =>
1863
+ amendItemUnlocked(projectDir, id, opts),
1864
+ );
1672
1865
  /** @type {typeof dropItemUnlocked} */
1673
1866
  export const dropItem = (projectDir, id, opts = {}) =>
1674
1867
  locked(projectDir, opts.commit ?? true, () => dropItemUnlocked(projectDir, id, opts));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.22.1",
3
+ "version": "0.23.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -8,7 +8,8 @@ mode: human gate
8
8
  purpose:
9
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
10
  - turn a bug, an idea or a task the talk finds into a proposed work item the human accepts with one click
11
- - propose a move on an item, an inbox entry or an open question (block, drop, depends, unblock, a verdict, a decision, an answer, inbox add, category, Later, erase) as a card the human makes with one click
11
+ - propose a move on an item, an inbox entry or an open question (amend, block, drop, depends, unblock, a verdict, a decision, an answer, inbox add, category, Later, erase) as a card the human makes with one click
12
+ - carry a decision the talk takes about a live item into that item's text, with one proposal
12
13
  - make another move the human asks for through its `ai-factory gcf` command, which the chat shows the human as a card first
13
14
 
14
15
  inputs:
@@ -22,7 +23,9 @@ preconditions:
22
23
  - with YOLO a framework move that changes the project runs without a card too: a move with a `propose_` tool stays a proposal, and any other move is one the human asked for
23
24
 
24
25
  forbidden_behaviors:
25
- - do not make the human's moves: `verdict`, `decide`, `question answer`, `unblock`, `phase next`, `pillar`, `permissions`, `config set`, `hooks-install`, `edits commit`, `edits discard`; the rules refuse them to any agent
26
+ - do not make the human's moves: `verdict`, `decide`, `question answer`, `unblock`, `item amend`, `phase next`, `pillar`, `permissions`, `config set`, `hooks-install`, `edits commit`, `edits discard`; the rules refuse them to any agent
27
+ - do not put a decision about a live item into the inbox or a new item: a run reads neither, and it blocks on what its card does not say; the decision goes into the card with `propose_amend`
28
+ - do not add a line to `notes:` that contradicts a slot of the card: replace the slot through `text`, as only the slots reach the documents of the systems
26
29
  - do not run a verdict, a decision, an unblock or an answer: propose it to the human with its `propose_` tool
27
30
  - 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
28
31
  - 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
@@ -40,13 +43,17 @@ workflow:
40
43
  1. read `gcf/INDEX.md`, then run `ai-factory gcf board --json` for the phase, the items by status and the inbox
41
44
  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
42
45
  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
43
- 4. a bug, an idea or a task that is new work: call `propose_item_new` with its title, type, subsystems and a note of what its run should know, no id: the core makes it from the title; note length <= 4000 characters
44
- 5. a raw thought that is not work yet: propose it for the inbox with `propose_inbox_add` and the category it is: `idea`, `request` (what only a person can give), `bug` or `finding` (a remark about the code), a detail word when one fits
45
- 6. a move the human asks for, or one the talk shows is due, that has a `propose_<move>` tool: call it with the `id` of the item, inbox entry or question it acts on, and say why in one line; name an item by its title with the id in brackets
46
- 7. a kill, a no or a wontfix: its reason is the human's words; the graveyard keeps it, and the move does not go without it
47
- 8. an open D1 question the talk answers: call `propose_question_answer` with its id and the human's words, or your draft when the human asks for one
48
- 9. another move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
49
- 10. say in one line what changed, or that nothing did
46
+ 4. a decision about a live item, or a line of its card the talk shows wrong: call `propose_amend` with its `id`
47
+ 5. its `text` holds the blocks it replaces in the card's block syntax, each whole; a superseded note leaves by `notes:` there, whole, without that line
48
+ 6. its `add` holds only what adds to them, length <= 4000 characters
49
+ 7. a run works that item: call `propose_amend` all the same: the human's card sends the decision to the run's chat; say so in one line
50
+ 8. a bug, an idea or a task that is new work: call `propose_item_new` with its title, type, subsystems and a note of what its run should know, no id: the core makes it from the title; note length <= 4000 characters
51
+ 9. a raw thought that is not work yet: propose it for the inbox with `propose_inbox_add` and the category it is: `idea`, `request` (what only a person can give), `bug` or `finding` (a remark about the code), a detail word when one fits
52
+ 10. a move the human asks for, or one the talk shows is due, that has a `propose_<move>` tool: call it with the `id` of the item, inbox entry or question it acts on, and say why in one line; name an item by its title with the id in brackets
53
+ 11. a kill, a no or a wontfix: its reason is the human's words; the graveyard keeps it, and the move does not go without it
54
+ 12. an open D1 question the talk answers: call `propose_question_answer` with its id and the human's words, or your draft when the human asks for one
55
+ 13. another move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
56
+ 14. say in one line what changed, or that nothing did
50
57
 
51
58
  invocation:
52
59
  - run at the start of a project chat thread the board opens, and when the user types `/gcf-chat`
@@ -18,22 +18,24 @@ 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 or delete a file in `gcf/inbox/` by hand: `ai-factory gcf item new --from`, `ai-factory gcf inbox category`, `inbox later` and `inbox drop` own the entries
21
+ - do not run `ai-factory gcf item amend`: it is the human's move
22
+ - do not edit or delete a file in `gcf/inbox/` by hand: `item new --from`, `item amend --from`, `inbox category`, `later` and `drop` own the entries
22
23
  - do not triage on a `work/` branch: `inbox category`, `inbox later`, `inbox drop` and `item new --from` refuse there; triage on main
23
24
 
24
25
  workflow:
25
26
  1. run `ai-factory gcf inbox --json`; read `gcf/LIVE.md` and `gcf/INDEX.md` to know what exists and what is in work
26
- 2. classify each entry: bug, tune of a live or unplayed item, idea for the design, request (an asset file, a question), duplicate, or noise; search `gcf/graveyard.md` for each idea and bug; an `unsorted` entry gets a category
27
+ 2. classify each entry: bug, tune of a live or unplayed item, a fix of a live item, idea for the design, request (an asset file, a question), duplicate, or noise; search `gcf/graveyard.md` for each idea and bug; an `unsorted` entry gets a category
27
28
  3. a lesson (category `lesson`, its kind the `detail`, with the `item` it came from) is what got in an agent's way: propose the fix it asks for - a project rule, a tech item, a note for the framework or the template - or noise
28
29
  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
29
30
  5. present the calls to the human, calls per message <= 5, and apply only the approved ones
30
31
  6. a bug or other work: run `ai-factory gcf item new --type <type> [--severity <level>] --from <in-id>`; the core makes the id from the title and prints it first; then write its `intent:` and `repro:`
31
32
  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 sorts: `ai-factory gcf inbox category <in-id> --category <c> [--detail <word>]` (`inbox categories` lists them); one kept for later: `ai-factory gcf inbox later <in-id>`, left in the inbox
36
- 12. report what each entry became and how many entries remain
33
+ 8. a fix of a live item's text: in the board's chat call `propose_amend` with its `id` and `from`; in a console give the human the line `ai-factory gcf item amend <id> --from <in-id>` to run
34
+ 9. 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>`
35
+ 10. 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>`
36
+ 11. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
37
+ 12. an entry the human sorts: `ai-factory gcf inbox category <in-id> --category <c> [--detail <word>]` (`inbox categories` lists them); one kept for later: `ai-factory gcf inbox later <in-id>`, left in the inbox
38
+ 13. report what each entry became and how many entries remain
37
39
 
38
40
  invocation:
39
41
  - run after a playtest session, after a CI run that added entries, or when the user asks to triage