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/README.md CHANGED
@@ -50,6 +50,19 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
50
50
 
51
51
  On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
52
52
 
53
+ ### 0.23.0
54
+
55
+ - `gcf item amend <id>` fixes a live card's text from every stored status but `unplayed`, the status unchanged: `--text` (`--text-file`) replaces the blocks it names, a key alone takes one out; `--add` adds to `notes:`; `--title`; `--from <in-id>` takes an inbox entry in the same commit, its pictures one by one. `provenance:` and `tuning:` cannot be named; a unit's block must be in its profile. `--dry-run --json` writes nothing and gives `{base, title, text, changes}`; `--base <hash>` refuses a card changed since (`gcf-refusal: {"code":"stale"}`). The operator's: a run and a thread are refused, the deny group `human-moves` holds it, and a chat agent proposes it (`propose_amend`). Refused during this card's run or session (`{"code":"running"}`). Findings on the new text come from the pre-commit gate, with its rollback. The domain's `preview` and `hint` tell a board.
56
+ - A resumed worktree takes main's card over what a stopped run wrote into its copy, saved or not; other files' conflicts read as before. A `work/<id>` branch whose folder was deleted syncs with main too.
57
+ - `item new --from <in> --note <text>`: the note goes over the entry's text, not beside it, so a board's form does not double it. The entry's links follow its pictures.
58
+ - The domain's `inbox-add` has the `item` field: an agent's proposal may name its card.
59
+ - gcf-chat, gcf-triage and the `AGENTS.md` block: a decision about a live item goes into its card by `propose_amend`, never the inbox or a new item; a decision against a slot replaces the slot. Run `ai-factory gcf init` once to take the new block.
60
+
61
+ ### 0.22.2
62
+
63
+ - A refusal in a terminal is its words and its machine line on stderr, exit 1: no `file:///…` and no node stack over them. A bug (any error type but a plain `Error`) keeps its stack. An older board or harness reads it as before.
64
+ - The `AGENTS.md` block keeps cnlp's line rules: no line past 250 characters, no passive, no open bound; a test holds it. `gcf_*` block names stay the project's to declare. Run `ai-factory gcf init` after the update to take the new text.
65
+
53
66
  ### 0.22.1
54
67
 
55
68
  - An agent may read the history of past runs: the deny group `human-moves` held `ai-factory gcf-harness run*`, which also caught `gcf-harness runs`, the very command `AGENTS.md` tells it to use. The rule is now `ai-factory gcf-harness run *`. A session started after the update takes it; nothing to re-run in the project.
@@ -99,7 +112,7 @@ On Windows, run `extension add` and `extension update` from PowerShell or cmd, n
99
112
  ### 0.19.0
100
113
 
101
114
  Autonomy (docs/Autonomy-Plan.md): the agent works by itself, the operator plays the milestones.
102
- - The core holds the operator's moves: `verdict`, `decide` (but under the gates), `drop` of a work item, `unblock`, `question answer`, `config set`, `permissions`, `phase next`, `pillar`, `hooks-install` and `item gates` refuse a harness run and a board thread (`GCF-By: thread`). A console session and the operator pass.
115
+ - The core holds the operator's moves: `verdict`, `decide` (but under the gates), `drop` of a work item, `unblock`, `question answer`, `config set`, `permissions`, `phase next`, `pillar`, `hooks-install`, `item gates` and `item amend` refuse a harness run and a board thread (`GCF-By: thread`). A console session and the operator pass.
103
116
  - `gates:` in `gcf/config.yml`: `milestone` wait|go, `verdict` wait|defer (a mechanic's or resource's submit closes it unplayed), `decision` wait|agent (a run decides go or no of its own spike, with `--reason`), `question` wait|assume. A card's `skip_gates`: `ai-factory gcf item gates <id> --to skip|wait|project`. `config set --pair key=value …` sets several keys in one commit.
104
117
  - A soft unit whose delta modifies or removes a capability no longer refuses its close: it waits for a verdict, `gate_why: modifies <capability>`.
105
118
  - `--assume "<question> = <value>"` on `submit`, `close`, `decide` files a D2 in the move's commit; `ai-factory gcf question add --class D1|D2 …` files one alone. `decide`'s reason goes into its commit.
@@ -377,7 +390,7 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
377
390
 
378
391
  **A deterministic core** behind `ai-factory gcf …`:
379
392
 
380
- - work items — `take <ids...> [--feature <id>]`, `item new [id] --title <text> --type <type>`, `submit`, `close`, `verdict <id> keep|tune|kill`, `decide <id> go|no|wontfix|known|close|continue|kill`, `block`, `unblock`, `drop`, `done`, `where`
393
+ - work items — `take <ids...> [--feature <id>]`, `item new [id] --title <text> --type <type>`, `submit`, `close`, `verdict <id> keep|tune|kill`, `decide <id> go|no|wontfix|known|close|continue|kill`, `block`, `unblock`, `drop`, `done`, `where`, `item amend <id> [--text <blocks>] [--add <lines>] [--title <text>] [--from <in-id>] [--dry-run --json]`
381
394
  - inbox and snapshot — `inbox [add <text> [--category <c>] [--detail <word>] | add --text-file <path|-> | category <in-id> | later <in-id> [--off] | categories | drop <in-id> | migrate]`, `live`, `live check`
382
395
  - runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session [--build]`, `audit`
383
396
  - project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
package/commands/gcf.js CHANGED
@@ -1,5 +1,6 @@
1
1
  // CLI wrapper over the deterministic core (GCF-PRD §10.1): harness and human call
2
2
  // the same functions. Registered by AIF via extension.json `commands`.
3
+ import { inspect } from 'node:util';
3
4
  import { mkdir, copyFile, readFile, writeFile } from 'node:fs/promises';
4
5
  import { existsSync, readFileSync } from 'node:fs';
5
6
  import { spawnSync } from 'node:child_process';
@@ -1041,9 +1042,54 @@ function registerItem(gcf) {
1041
1042
  });
1042
1043
  registerAttach(item);
1043
1044
  registerAgent(item);
1045
+ registerAmend(item);
1044
1046
  registerHistory(item);
1045
1047
  }
1046
1048
 
1049
+ function registerAmend(item) {
1050
+ item
1051
+ .command('amend <id>')
1052
+ .description(
1053
+ "Fix a live card's text, any status but unplayed: its status stays, its next run reads it " +
1054
+ '(commit)',
1055
+ )
1056
+ .option('--text <blocks>', 'the blocks to replace, in block syntax; a key alone takes it out')
1057
+ .option('--text-file <path>', 'the blocks from a file, - for stdin')
1058
+ .option('--add <lines>', 'lines to add to notes:, up to 4000 characters')
1059
+ .option('--title <text>', 'the new title')
1060
+ .option(
1061
+ '--from <in-id>',
1062
+ 'the inbox entry it takes: erased; its words go to notes: unless --add',
1063
+ )
1064
+ .option('--base <hash>', "the preview's base: refused when the card changed since")
1065
+ .option('--dry-run', 'show what would change; write nothing; a run may hold the card')
1066
+ .option('--json', 'with --dry-run: {base, title, text, changes: [{block, old, new}]}')
1067
+ .option('--no-commit', 'skip the commit (tests only)')
1068
+ .action(async (id, o) => {
1069
+ if (o.text !== undefined && o.textFile !== undefined)
1070
+ throw new Error('give the text once: --text=<blocks> or --text-file <path|->');
1071
+ // A preview changes nothing: a board shows it for an agent's proposal too.
1072
+ if (!o.dryRun) await operatorOnly('item amend');
1073
+ const r = await (
1074
+ await lib('work-ops')
1075
+ ).amendItem(process.cwd(), id, {
1076
+ text: o.textFile === undefined ? o.text : readTextFile(o.textFile),
1077
+ add: o.add,
1078
+ title: o.title,
1079
+ from: o.from,
1080
+ base: o.base,
1081
+ dryRun: o.dryRun === true,
1082
+ commit: o.commit,
1083
+ });
1084
+ if (o.json) console.log(JSON.stringify(r, null, 2));
1085
+ else if (o.dryRun)
1086
+ console.log(
1087
+ r.changes.map((c) => `${c.block}: ${c.new.length} lines`).join('\n') || 'no change',
1088
+ );
1089
+ else console.log(`amended ${id}${shortHash(r.hash)}`);
1090
+ });
1091
+ }
1092
+
1047
1093
  function registerHistory(item) {
1048
1094
  item
1049
1095
  .command('history <id>')
@@ -1960,8 +2006,29 @@ function registerPillar(gcf) {
1960
2006
  });
1961
2007
  }
1962
2008
 
2009
+ let plainRefusals = false;
2010
+
2011
+ /**
2012
+ * A move's refusal is its words on stderr, with its machine line, not node's stack over them; a
2013
+ * bug (any other error type) keeps its report: its stack, what a rollback could not restore.
2014
+ * Past the action: a caller that awaits the parse catches the error first, and another
2015
+ * extension's commands never get here.
2016
+ */
2017
+ function refuseInWords() {
2018
+ if (plainRefusals) return;
2019
+ plainRefusals = true;
2020
+ const fail = (e) => {
2021
+ const words = e instanceof Error && e.name !== 'Error' ? inspect(e) : (e?.message ?? String(e));
2022
+ process.stderr.write(`${words}\n`, () => process.exit(1));
2023
+ };
2024
+
2025
+ process.on('uncaughtException', fail);
2026
+ process.on('unhandledRejection', fail);
2027
+ }
2028
+
1963
2029
  export function register(program) {
1964
2030
  const gcf = program.command('gcf').description('Game Context Framework core');
2031
+ gcf.hook('preAction', refuseInWords);
1965
2032
  registerPillar(gcf);
1966
2033
  registerInit(gcf, program);
1967
2034
  registerIndex(gcf);
package/extension.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
3
3
  "name": "gcf-aif-ext",
4
- "version": "0.22.1",
4
+ "version": "0.23.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -180,7 +180,7 @@ export const DENY_GROUPS = [
180
180
  {
181
181
  id: 'human-moves',
182
182
  label:
183
- "the human's GCF moves: verdict, answer, unblock, a card's gates, phase, pillars, " +
183
+ "the human's GCF moves: verdict, answer, unblock, a card's gates or text, phase, pillars, " +
184
184
  'settings, permissions, setup, hand edits (decide the core holds by the gates)',
185
185
  on: true,
186
186
  rules: shell(
@@ -188,6 +188,7 @@ export const DENY_GROUPS = [
188
188
  'ai-factory gcf question answer*',
189
189
  'ai-factory gcf unblock*',
190
190
  'ai-factory gcf item gates*',
191
+ 'ai-factory gcf item amend*',
191
192
  'ai-factory gcf phase next*',
192
193
  'ai-factory gcf pillar*',
193
194
  'ai-factory gcf permissions*',
package/lib/audit-core.js CHANGED
@@ -403,7 +403,8 @@ const inboxAlerts = (i) => [
403
403
  i.broken_links.length && `${i.broken_links.length} inbox picture link(s) lead nowhere`,
404
404
  i.orphan_dirs.length && `${i.orphan_dirs.length} inbox picture folder(s) without their entry`,
405
405
  i.unmigrated.length &&
406
- `${i.unmigrated.length} inbox entr(ies) from before the categories: ai-factory gcf inbox migrate`,
406
+ `${i.unmigrated.length} inbox entr(ies) from before the categories: ai-factory gcf inbox ` +
407
+ `migrate`,
407
408
  i.unknown_category.length &&
408
409
  `${i.unknown_category.length} inbox entr(ies) of a category the vocabulary lacks: ` +
409
410
  i.unknown_category.join(', '),
package/lib/changes.js CHANGED
@@ -143,6 +143,7 @@ function doubleStar(glob, i) {
143
143
  return atStart && glob[i + 2] === '/' ? ['(?:.*/)?', 3] : ['.*', 2];
144
144
  }
145
145
 
146
+ // Every class git's wildmatch knows, as it reads them: ASCII only.
146
147
  const CLASSES = {
147
148
  alpha: 'a-zA-Z',
148
149
  digit: '0-9',
@@ -150,10 +151,19 @@ const CLASSES = {
150
151
  upper: 'A-Z',
151
152
  lower: 'a-z',
152
153
  xdigit: '0-9a-fA-F',
153
- space: '\\s',
154
+ space: ' \\t\\n\\r',
155
+ blank: ' \\t',
154
156
  punct: '!-\\/:-@\\[-`{-~',
157
+ graph: '!-~',
158
+ print: ' -~',
159
+ cntrl: '\\x00-\\x1f\\x7f',
155
160
  };
156
161
 
162
+ const NAMED_CLASS = /\[:([^\]]*):\]/g;
163
+
164
+ /** A name as git's wildmatch reads it, byte by byte: one letter outside ASCII is several. */
165
+ const asBytes = (s) => Buffer.from(s, 'utf8').toString('latin1');
166
+
157
167
  /** Where the bracket at `i` ends, past `[:digit:]` inside it; a first `]` is its own letter. */
158
168
  function bracketEnd(glob, i) {
159
169
  let at = glob[i + 1] === '!' || glob[i + 1] === '^' ? i + 2 : i + 1;
@@ -166,14 +176,19 @@ function bracketEnd(glob, i) {
166
176
  return at < glob.length ? at : -1;
167
177
  }
168
178
 
169
- /** A bracket as a regex: it never takes a `/`, as git's does not. */
179
+ /**
180
+ * A bracket as a regex: it never takes a `/`, as git's does not. A class git does not know stops
181
+ * its whole pattern there, whatever else the bracket holds.
182
+ */
170
183
  function bracket(glob, i, end) {
171
184
  const inner = glob.slice(i + 1, end);
185
+ const named = [...inner.matchAll(NAMED_CLASS)].map((m) => m[1]);
186
+ if (named.some((n) => !Object.hasOwn(CLASSES, n))) return '(?!)';
172
187
  const not = /^[!^]/.test(inner);
173
188
  const body = (not ? inner.slice(1) : inner)
174
- .replace(/\[:(\w+):\]/g, (_, n) => `\0${n}\0`)
189
+ .replace(NAMED_CLASS, (_, n) => `\0${n}\0`)
175
190
  .replace(/[\\[\]]/g, '\\$&')
176
- .replace(/\0(\w+)\0/g, (_, n) => CLASSES[n] ?? '');
191
+ .replace(/\0(\w+)\0/g, (_, n) => CLASSES[n]);
177
192
 
178
193
  return `(?!/)[${not ? '^' : ''}${body}]`;
179
194
  }
@@ -199,7 +214,7 @@ function globPiece(glob, i) {
199
214
  * @returns {(p: string) => boolean}
200
215
  */
201
216
  export function globTest(written) {
202
- const glob = written.replace(/^(?:\.\/)+/, '');
217
+ const glob = asBytes(written).replace(/^(?:\.\/)+/, '');
203
218
  const folder = glob.endsWith('/');
204
219
  const bare = folder ? glob.slice(0, -1) : glob;
205
220
  const asName = (p) => p.startsWith(`${bare}/`) || (!folder && p === bare);
@@ -213,9 +228,13 @@ export function globTest(written) {
213
228
  try {
214
229
  const test = new RegExp(`^${re}$`);
215
230
 
216
- return (p) => asName(p) || (!folder && test.test(p));
231
+ return (name) => {
232
+ const p = asBytes(name);
233
+
234
+ return asName(p) || (!folder && test.test(p));
235
+ };
217
236
  } catch {
218
- return asName;
237
+ return (name) => asName(asBytes(name));
219
238
  }
220
239
  }
221
240
 
@@ -1,5 +1,6 @@
1
1
  // The design as parts a board edits field by field (Board-PRD §5.24): PILLARS.md, game.md,
2
- // the project's GLOSSARY.md, a subsystem's purpose, a unit. A part reads as the fields its CNL-P profile
2
+ // the project's GLOSSARY.md, a subsystem's purpose, a unit. A part reads as the fields its CNL-P
3
+ // profile
3
4
  // declares; a save writes the edited fields back into the part's text and brings it in as a
4
5
  // one-part bundle (lib/bundle.js), so a form edit passes the same three-way check and the same
5
6
  // design check a designer's import does. The board writes no file of gcf/ itself.
@@ -312,6 +313,7 @@ function changedKeys(before, after) {
312
313
 
313
314
  return new Map(blocksOf(lf(t)).map((b) => [b.key, raw.slice(b.start - 1, b.end).join('\n')]));
314
315
  };
316
+
315
317
  const a = read(before);
316
318
  const b = read(after);
317
319
 
@@ -348,6 +350,7 @@ function pillarIds(part, given) {
348
350
 
349
351
  return { ...p, id };
350
352
  }
353
+
351
354
  const was = before.find((b) => b.id === p.id);
352
355
  if (oneLine(was?.name) && oneLine(p.name) && oneLine(was.name) !== oneLine(p.name)) {
353
356
  const to = deriveId(oneLine(p.name), (x) => x !== p.id && taken.has(x), 'pillar');
@@ -379,7 +382,8 @@ async function refuseLooseForRename(projectDir, renames) {
379
382
  ];
380
383
  if (loose.length)
381
384
  throw new Error(
382
- `a new pillar name renames its id where it is cited: record or discard ${loose.join(', ')} first`,
385
+ `a new pillar name renames its id where it is cited: record or ` +
386
+ `discard ${loose.join(', ')} first`,
383
387
  );
384
388
  }
385
389
 
@@ -416,7 +420,8 @@ async function saveUnlocked(
416
420
  let part = await designPart(projectDir, kind, name, { type });
417
421
  if (part.exists && !base)
418
422
  throw new Error(
419
- `${kind} ${name} exists: pass --base from gcf design part, so an edit made since is not overwritten`,
423
+ `${kind} ${name} exists: pass --base from gcf design part, so an edit made since is ` +
424
+ `not overwritten`,
420
425
  );
421
426
  const owner = part.system ?? system;
422
427
  if (kind === 'unit' && !part.exists && !SLUG_RE.test(String(owner ?? '')))
@@ -441,6 +446,7 @@ async function saveUnlocked(
441
446
  part = await designPart(projectDir, kind, name, { type });
442
447
  base = part.base;
443
448
  }
449
+
444
450
  let next = text === null ? null : lf(text).trim();
445
451
  if (next === null) {
446
452
  const start = part.exists
@@ -540,7 +546,8 @@ async function bundleMove(
540
546
  const drafts = unrecorded.filter((f) => own.includes(f));
541
547
  if (commit && loose.length)
542
548
  throw new Error(
543
- `${loose.join(', ')} holds changes not recorded yet: record the design first (gcf design commit)`,
549
+ `${loose.join(', ')} holds changes not recorded yet: record the design first (gcf ` +
550
+ `design commit)`,
544
551
  );
545
552
  let result = { applied: [], report: [] };
546
553
  try {
@@ -628,7 +635,8 @@ async function commitUnlocked(projectDir, { message = null, commit = true } = {}
628
635
  if (blocking.length) {
629
636
  const first = blocking.slice(0, 3).map((i) => `${i.file}:${i.line} ${i.check} ${i.message}`);
630
637
  throw new Error(
631
- `the design check has ${blocking.length} blocking finding(s), fix them first:\n${first.join('\n')}`,
638
+ `the design check has ${blocking.length} blocking finding(s), fix them ` +
639
+ `first:\n${first.join('\n')}`,
632
640
  );
633
641
  }
634
642
 
package/lib/domain.js CHANGED
@@ -232,11 +232,35 @@ const ITEM_SPECS = {
232
232
  ],
233
233
  rare: true,
234
234
  },
235
+ // `text` goes on stdin, `add` as an argument: a board sends one field on stdin. `base`: the
236
+ // board fills it from the preview it showed, so a card edited meanwhile is not overwritten.
237
+ amend: {
238
+ label: 'amend',
239
+ help: "Fix the card's text: its next run reads it; its status stays",
240
+ args: ['gcf', 'item', 'amend', '{id}'],
241
+ fields: [
242
+ { key: 'text', label: 'Blocks to replace', kind: 'longtext', stdin: true },
243
+ { key: 'add', label: 'Lines to add to notes', kind: 'longtext', max: NOTE_MAX },
244
+ text('title', 'Title'),
245
+ text('from', 'Inbox entry it takes: erased'),
246
+ text('base', 'Read at', { hidden: true }),
247
+ ],
248
+ rare: true,
249
+ propose: true,
250
+ // `--dry-run --json` says what it would change: a board shows that before the move.
251
+ preview: true,
252
+ // A human fixing a built card: the fix reaches its next run, not the code it has.
253
+ hint: {
254
+ status: ['awaiting-verdict', 'awaiting-decision', 'parked'],
255
+ text: 'Its code stays as built: the text changes what its next run reads.',
256
+ },
257
+ },
235
258
  attach: {
236
259
  label: 'attach',
237
260
  help: 'Give the item a file (a chat image, a reference): committed in its attachments',
238
261
  args: ['gcf', 'item', 'attach', '{id}'],
239
- // `file`: the board picks it on the operator's machine and sends its bytes; the core gets a path.
262
+ // `file`: the board picks it on the operator's machine and sends its bytes; the core gets a
263
+ // path.
240
264
  fields: [{ key: 'file', label: 'File', kind: 'file', required: true }],
241
265
  rare: true,
242
266
  },
@@ -257,7 +281,9 @@ const RUN = {
257
281
  // shows the proposal, the operator's click makes it.
258
282
  const NEW_ITEM = {
259
283
  label: 'create',
260
- help: 'A new work item, committed; its id comes from the title; the core refuses a type the phase does not take',
284
+ help:
285
+ 'A new work item, committed; its id comes from the title; the core refuses a type ' +
286
+ 'the phase does not take',
261
287
  args: ['gcf', 'item', 'new', '--commit'],
262
288
  propose: true,
263
289
  fields: [
@@ -332,7 +358,8 @@ const PART_FIELDS = [
332
358
  ];
333
359
 
334
360
  // The design's moves (Board-PRD §5.24): a part saved from its form or as text, a session's
335
- // files recorded, a designer's bundle brought back, a new unit, a draft discarded, a pillar retired, a unit dropped.
361
+ // files recorded, a designer's bundle brought back, a new unit, a draft discarded, a pillar
362
+ // retired, a unit dropped.
336
363
  // Every save goes through the import's three-way check and the design check.
337
364
  const DESIGN_SPECS = {
338
365
  'design-save': {
@@ -494,7 +521,9 @@ const STARTS = {
494
521
  // operator records it, edits it in the form, or discards it.
495
522
  'draft-glossary': {
496
523
  label: 'Draft with agent',
497
- help: 'A draft of the glossary from the vision and the units: you record it, edit or discard it',
524
+ help:
525
+ 'A draft of the glossary from the vision and the units: you record it, edit or ' +
526
+ 'discard it',
498
527
  skill: 'gcf-vision',
499
528
  say: 'Draft GLOSSARY.md from the vision and the design units. Write it, do not record it.',
500
529
  edits: DESIGN_EDITS,
@@ -639,6 +668,8 @@ const BLOCK_SPECS = {
639
668
  { key: 'text', label: 'Text', kind: 'longtext', required: true },
640
669
  CATEGORY('note'),
641
670
  DETAIL,
671
+ // Goes with the entry; a board shows it beside the item's name.
672
+ text('item', 'The item it is about', { help: 'A live item, by its id' }),
642
673
  ],
643
674
  propose: true,
644
675
  },
package/lib/git.js CHANGED
@@ -23,9 +23,11 @@ export function inParts(specs) {
23
23
  part = [];
24
24
  n = 0;
25
25
  }
26
+
26
27
  part.push(s);
27
28
  n += s.length + 1;
28
29
  }
30
+
29
31
  if (part.length) parts.push(part);
30
32
 
31
33
  return parts;
@@ -169,11 +171,13 @@ export function restoreFromHead(projectDir, files) {
169
171
  const r = git(...args);
170
172
  if (r.status !== 0) throw new Error(`git ${args.join(' ')}: ${r.stderr.trim()}`);
171
173
  };
174
+
172
175
  for (const f of files) {
173
176
  if (git('cat-file', '-e', `HEAD:./${f}`).status === 0) {
174
177
  must('checkout', 'HEAD', '--', literal(projectDir, f));
175
178
  continue;
176
179
  }
180
+
177
181
  must('rm', '--cached', '-q', '--ignore-unmatch', '--', literal(projectDir, f));
178
182
  rmSync(path.join(projectDir, f), { force: true });
179
183
  }
@@ -250,7 +254,8 @@ function commitRefusal(message, out) {
250
254
  'gate',
251
255
  { problems },
252
256
  `cannot record ${message}: the gate refuses ${problems.join('; ')}\n` +
253
- 'Nothing was committed. What it names has to change first (the agent can do it), then try again.',
257
+ 'Nothing was committed. What it names has to change first (the agent can do it), then ' +
258
+ 'try again.',
254
259
  );
255
260
  }
256
261
 
@@ -301,6 +306,7 @@ export function commitPaths(projectDir, message, paths, move = {}) {
301
306
  'commit or discard them, then try again',
302
307
  );
303
308
  }
309
+
304
310
  if (res.status !== 0) throw commitRefusal(message, out);
305
311
 
306
312
  return spawnSync('git', ['rev-parse', 'HEAD'], {
@@ -329,6 +335,7 @@ export function snapshotIndex(cwd, files) {
329
335
  if (res.status !== 0) return null;
330
336
  stdout += res.stdout;
331
337
  }
338
+
332
339
  const prefix = spawnSync('git', ['rev-parse', '--show-prefix'], {
333
340
  cwd,
334
341
  encoding: 'utf8',
package/lib/id.js CHANGED
@@ -56,6 +56,7 @@ export function deriveId(title, known, type) {
56
56
 
57
57
  return `${type}-${n}`;
58
58
  }
59
+
59
60
  let id = base;
60
61
  for (let n = 2; known(id); n++) id = `${base}-${n}`;
61
62
 
@@ -159,6 +159,7 @@ export function mergeVocabulary(base, domain = [], project = []) {
159
159
  if (!groups.has(r.group)) throw new Error(`inbox category ${r.id}: no group ${r.group}`);
160
160
  seen.set(r.id, layer);
161
161
  }
162
+
162
163
  const rows = [
163
164
  ...base.map((r) => ({ ...r, layer: 'base' })),
164
165
  ...domain.map((r) => ({ ...r, layer: 'domain' })),
package/lib/inbox.js CHANGED
@@ -91,6 +91,7 @@ export function fromOld({ source, tags = [], kind, item }) {
91
91
  rest.shift();
92
92
  }
93
93
  }
94
+
94
95
  const lostLater = words.includes('later') && !laterOk ? ['later (never on its category)'] : [];
95
96
 
96
97
  return {
@@ -341,7 +342,10 @@ export async function planCategory(
341
342
  const actor = actorOrigin(by);
342
343
  if (questionOnly(c) || !c.set_by.length)
343
344
  throw new Error(
344
- `no entry moves into ${c.id}: ${c.set_by.length ? 'it is an open question' : 'it is for entries from before the categories'}`,
345
+ `no entry moves into ${c.id}: ` +
346
+ (c.set_by.length
347
+ ? 'it is an open question'
348
+ : 'it is for entries from before the categories'),
345
349
  );
346
350
  if (actor === 'agent' && !c.set_by.includes('agent'))
347
351
  throw new Error(
@@ -419,6 +423,7 @@ export async function planTake(root, id, toDir) {
419
423
 
420
424
  return {
421
425
  entry,
426
+ pictures: moves.map((m) => m[1]),
422
427
  files: [...drop.files, ...moves.map((m) => m[1])],
423
428
  inputs: drop.files,
424
429
  apply: async () => {
package/lib/integrate.js CHANGED
@@ -3,11 +3,12 @@
3
3
  // not in memory. `integrate` merges such a branch into main and records the item's move there,
4
4
  // under the main lock; without an id it picks up every verified branch a dead run left behind.
5
5
  import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
6
- import { existsSync } from 'node:fs';
6
+ import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
7
7
  import { spawnSync } from 'node:child_process';
8
8
  import path from 'node:path';
9
9
  import { buildLedger } from './ledger.js';
10
10
  import { parse } from './frontmatter.js';
11
+ import { blockLines } from './systems-doc.js';
11
12
  import { withMainLock, runHolder, lockedItem, MAIN_RUN } from './main-lock.js';
12
13
  import { verifyItem, deltaProblems } from './verify.js';
13
14
  import { submitItem, closeItem, blockItem, decideItem } from './work-ops.js';
@@ -15,7 +16,7 @@ import { readConfig } from './gcf-paths.js';
15
16
  import { agentDecideProblem } from './gates.js';
16
17
  import { isValidId } from './id.js';
17
18
  import { writeIndex } from './index-gen.js';
18
- import { moveTrailers } from './git.js';
19
+ import { moveTrailers, restoreIndex, snapshotIndex } from './git.js';
19
20
 
20
21
  const TRAILER = 'GCF-Verified';
21
22
  export const branchOf = (id) => `work/${id}`;
@@ -53,12 +54,21 @@ function dropLogs(dir) {
53
54
  /**
54
55
  * A merge stopped on gcf/INDEX.md alone: both sides counted something (an inbox entry a branch
55
56
  * added, a move on main). The index is generated, so it is written again and the merge goes on,
56
- * past the commit gate like a merge that needs no hand (git runs no pre-commit for it). True
57
- * when the merge is done; false leaves the caller to abort it.
57
+ * past the commit gate like a merge that needs no hand (git runs no pre-commit for it). `card`,
58
+ * when given, may stop it too: main's text wins, the human's (a fix made while the branch waited).
59
+ * True when the merge is done; false leaves the caller to abort it.
58
60
  */
59
- async function mergedPastIndex(dir) {
60
- const unmerged = git(dir, ['diff', '--name-only', '--diff-filter=U'], { check: false }).out;
61
- if (unmerged.split('\n').filter(Boolean).join() !== 'gcf/INDEX.md') return false;
61
+ async function mergedPastIndex(dir, card = null) {
62
+ const unmerged = git(dir, ['diff', '--name-only', '--diff-filter=U'], { check: false })
63
+ .out.split('\n')
64
+ .filter(Boolean);
65
+ const ours = ['gcf/INDEX.md', ...(card ? [card] : [])];
66
+ if (!unmerged.length || unmerged.some((f) => !ours.includes(f))) return false;
67
+ if (card && unmerged.includes(card)) {
68
+ git(dir, ['checkout', '--theirs', '--', card], { check: false });
69
+ git(dir, ['add', '--', card], { check: false });
70
+ }
71
+
62
72
  try {
63
73
  await writeIndex(path.join(dir, 'gcf'));
64
74
  } catch {
@@ -73,19 +83,63 @@ async function mergedPastIndex(dir) {
73
83
  return git(dir, commit, { check: false }).ok;
74
84
  }
75
85
 
86
+ /**
87
+ * Whether a refused merge stands on the worktree's unsaved card alone: of what is uncommitted
88
+ * there, main changes nothing else. Anything more stays refused, and the card as it is.
89
+ */
90
+ function cardAloneHolds(dir, main, card) {
91
+ if (git(dir, ['rev-parse', '-q', '--verify', 'MERGE_HEAD'], { check: false }).ok) return false;
92
+ const list = (args) => git(dir, args, { check: false }).out.split('\n').filter(Boolean);
93
+ const moved = new Set(list(['diff', '--name-only', `HEAD...${main}`]));
94
+ const loose = [
95
+ ...list(['diff', '--name-only', 'HEAD']),
96
+ ...list(['ls-files', '--others', '--exclude-standard']),
97
+ ];
98
+ const held = loose.filter((f) => moved.has(f));
99
+
100
+ return held.length === 1 && held[0] === card;
101
+ }
102
+
103
+ /** The card as a worktree holds it, on disk and in the index; the call puts it back. */
104
+ function holdCard(dir, card) {
105
+ const file = path.join(dir, card);
106
+ const bytes = existsSync(file) ? readFileSync(file) : null;
107
+ const index = snapshotIndex(dir, [file]);
108
+
109
+ return () => {
110
+ restoreIndex(index);
111
+ if (bytes) writeFileSync(file, bytes);
112
+ else rmSync(file, { force: true });
113
+ };
114
+ }
115
+
76
116
  /**
77
117
  * Bring the main checkout's branch into a resumed worktree: the operator's answer from
78
- * `unblock`, a newer LIVE.md and the other items' states live on main only.
118
+ * `unblock`, a fix from `amend`, a newer LIVE.md and the other items' states live on main only.
119
+ * The item's card on main wins over what a stopped run wrote into its copy, saved or not: the
120
+ * run's edit came from the card's notes, and the next session reads them again; code stays. A
121
+ * merge that does not go leaves the unsaved card as it was.
79
122
  */
80
- async function syncWithMain(projectDir, dir) {
123
+ async function syncWithMain(projectDir, dir, id) {
81
124
  const main = git(projectDir, ['rev-parse', '--abbrev-ref', 'HEAD']).out;
82
125
  if (main === 'HEAD' || main.startsWith('work/')) return {};
83
126
  // An earlier run's lines in the worktree's logs would stop main's newer logs merging in.
84
127
  dropLogs(dir);
85
- const res = git(dir, ['merge', '--no-edit', '-m', `gcf(sync): ${main}`, main], { check: false });
86
- if (res.ok || (await mergedPastIndex(dir))) return {};
128
+ const merge = () =>
129
+ git(dir, ['merge', '--no-edit', '-m', `gcf(sync): ${main}`, main], { check: false });
130
+ const card = `gcf/work/${id}.md`;
131
+ let res = merge();
132
+ let putBack = null;
133
+ if (!res.ok && cardAloneHolds(dir, main, card)) {
134
+ putBack = holdCard(dir, card);
135
+ git(dir, ['checkout', 'HEAD', '--', card], { check: false });
136
+ res = merge();
137
+ }
138
+
139
+ if (res.ok || (await mergedPastIndex(dir, card))) return {};
87
140
  if (git(dir, ['rev-parse', '-q', '--verify', 'MERGE_HEAD'], { check: false }).ok)
88
141
  git(dir, ['merge', '--abort'], { check: false });
142
+ putBack?.();
89
143
 
90
144
  return { sync: `${main} does not merge into the worktree: ${res.err}` };
91
145
  }
@@ -105,7 +159,7 @@ export async function addWorktree(projectDir, id) {
105
159
  path: dir,
106
160
  branch: branchOf(id),
107
161
  created: false,
108
- ...(await syncWithMain(projectDir, dir)),
162
+ ...(await syncWithMain(projectDir, dir, id)),
109
163
  };
110
164
  if (item.data.status !== 'ready')
111
165
  throw new Error(`${id} is ${item.data.status}: a run starts on a ready item`);
@@ -116,8 +170,10 @@ export async function addWorktree(projectDir, id) {
116
170
  const exists = git(projectDir, ['rev-parse', '--verify', '--quiet', ref], { check: false }).ok;
117
171
  const from = exists ? [dir, branchOf(id)] : ['-b', branchOf(id), dir, 'HEAD'];
118
172
  git(projectDir, ['worktree', 'add', ...from]);
173
+ // A branch that outlived its folder lags behind main as a resumed worktree does.
174
+ const sync = exists ? await syncWithMain(projectDir, dir, id) : {};
119
175
 
120
- return { id, path: dir, branch: branchOf(id), created: true };
176
+ return { id, path: dir, branch: branchOf(id), created: true, ...sync };
121
177
  }
122
178
 
123
179
  /**
@@ -178,18 +234,22 @@ function cleanUp(projectDir, id, { force = false } = {}) {
178
234
  return notes.length ? { cleanup: notes } : {};
179
235
  }
180
236
 
181
- /** The item file at `rev` without its `live:`: what a branch must leave as main has it. */
237
+ /**
238
+ * The item file at `rev` as a branch must leave it: its frontmatter but `live:`, and the blocks
239
+ * that hold the operator's words and the record of where it came from.
240
+ */
182
241
  function itemBeyondLive(projectDir, rev, id) {
183
242
  const res = git(projectDir, ['show', `${rev}:./gcf/work/${id}.md`], { check: false });
184
243
  if (!res.ok) return null;
185
244
  const { data, body } = parse(res.out);
186
245
  const { live, ...rest } = data;
187
246
 
188
- return JSON.stringify([rest, String(body).trim()]);
247
+ return JSON.stringify([rest, ['tuning', 'notes', 'provenance'].map((k) => blockLines(body, k))]);
189
248
  }
190
249
 
191
250
  /**
192
- * The branch may change in gcf/ only its own item's `live:` (Methodology §5.2): status, other
251
+ * The branch may change in gcf/ only its own item's `live:` and the slots of its card, which a
252
+ * run rewrites by the operator's word (Methodology §5.2): status, the operator's blocks, other
193
253
  * items and the config move on main through their commands.
194
254
  */
195
255
  const INBOX_ENTRY = /^gcf\/inbox\/in-[0-9a-f]{8}\.md$/;