gcf-aif-ext 0.34.0 → 0.36.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.
@@ -9,7 +9,7 @@ import { existsSync } from 'node:fs';
9
9
  import path from 'node:path';
10
10
  import { commitMove } from './commit-move.js';
11
11
  import { atomicWrite } from './safe-path.js';
12
- import { gcfRoot, RUN_WORD } from './gcf-paths.js';
12
+ import { gcfRoot, PHASE_DEFAULTS, RUN_PHASES, RUN_WORD } from './gcf-paths.js';
13
13
  import { configDoc, ensureMap } from './config-doc.js';
14
14
 
15
15
  const GROUPS_SHAPE = 'gcf/config.yml: agent.groups must map a group id to true or false';
@@ -184,7 +184,8 @@ export const DENY_GROUPS = [
184
184
  id: 'human-moves',
185
185
  label:
186
186
  "the human's GCF moves: verdict, answer, unblock, a card's gates or text, phase, pillars, " +
187
- 'settings, permissions, setup, hand edits (decide the core holds by the gates)',
187
+ 'settings, permissions, setup, hand edits, project rules, lesson reports (decide the core ' +
188
+ 'holds by the gates)',
188
189
  on: true,
189
190
  rules: shell(
190
191
  'ai-factory gcf verdict*',
@@ -206,6 +207,11 @@ export const DENY_GROUPS = [
206
207
  'ai-factory gcf edits discard*',
207
208
  // What goes into the operator's commit is theirs to say; an agent commits with git.
208
209
  'ai-factory gcf changes commit*',
210
+ // The project's standing instructions to its agents, and what leaves it for GCF or the
211
+ // template (Lessons-Review-Plan d6): an agent proposes them.
212
+ 'ai-factory gcf rules add*',
213
+ 'ai-factory gcf rules save*',
214
+ 'ai-factory gcf lessons report*',
209
215
  'ai-factory gcf-harness init*',
210
216
  // The space keeps `gcf-harness runs`, the history of past runs, a read the agent may make.
211
217
  'ai-factory gcf-harness run *',
@@ -334,11 +340,11 @@ function choices(agent) {
334
340
  * without its own pick runs on; null, or `default` written by hand, leaves it to the agent's
335
341
  * defaults (Opus, High: Board-PRD decision 36). One word each, as an item's.
336
342
  */
337
- function picksOf(agent) {
343
+ function picksOf(agent, where = 'agent') {
338
344
  const pick = (k) => {
339
345
  const v = agent[k] ?? null;
340
346
  if (v !== null && !(typeof v === 'string' && RUN_WORD.test(v)))
341
- throw new Error(`gcf/config.yml: agent.${k} must be one plain word, e.g. opus`);
347
+ throw new Error(`gcf/config.yml: ${where}.${k} must be one plain word, e.g. opus`);
342
348
 
343
349
  return v?.toLowerCase() === 'default' ? null : v;
344
350
  };
@@ -346,6 +352,23 @@ function picksOf(agent) {
346
352
  return { model: pick('model'), effort: pick('effort') };
347
353
  }
348
354
 
355
+ /**
356
+ * The project's model and effort of each phase (`agent.plan|implement.model|effort`,
357
+ * Plan-Review-Rework-Plan d10), over `agent.model|effort` in that phase; `phase_defaults`, GCF's
358
+ * own of each, under them.
359
+ */
360
+ function phasePicksOf(agent) {
361
+ const out = {};
362
+ for (const phase of RUN_PHASES) {
363
+ const v = agent[phase] ?? {};
364
+ if (typeof v !== 'object' || Array.isArray(v))
365
+ throw new Error(`gcf/config.yml: agent.${phase} must map model and effort`);
366
+ out[phase] = picksOf(v, `agent.${phase}`);
367
+ }
368
+
369
+ return { ...out, phase_defaults: PHASE_DEFAULTS };
370
+ }
371
+
349
372
  /**
350
373
  * The `agent:` section resolved: the project's model and effort, each group on or off, the deny
351
374
  * rules the run gets, the extra allow rules (for an agent run without bypass). No section: the
@@ -375,6 +398,7 @@ export function agentOf(config) {
375
398
 
376
399
  return {
377
400
  ...picksOf(agent),
401
+ ...phasePicksOf(agent),
378
402
  groups,
379
403
  deny_extra: extra,
380
404
  deny: claudeOf(denied),
package/lib/board.js CHANGED
@@ -33,7 +33,7 @@ import { handoffOf } from './handoff.js';
33
33
 
34
34
  // The version of the JSON below (Methodology §11): a board refuses one it does not know. Bump it
35
35
  // when a field changes meaning or goes away; a new field does not bump it.
36
- export const BOARD_SCHEMA = 6;
36
+ export const BOARD_SCHEMA = 7;
37
37
 
38
38
  /**
39
39
  * Plan progress `{tasks, done}` from its checkboxes and the plan's project path, both null
@@ -148,7 +148,7 @@ async function phaseOf(projectDir) {
148
148
  * or unreadable;
149
149
  * `error` says why a file that is there cannot be read: the run buttons hide with no harness.
150
150
  */
151
- async function extensionsOf(projectDir) {
151
+ export async function extensionsOf(projectDir) {
152
152
  const file = path.join(path.resolve(projectDir), '.ai-factory.json');
153
153
  let text;
154
154
  try {
@@ -230,6 +230,14 @@ const SCALARS = [
230
230
  'since',
231
231
  'model',
232
232
  'effort',
233
+ // A phase's own model and effort (Plan-Review-Rework-Plan d10).
234
+ 'plan_model',
235
+ 'plan_effort',
236
+ 'implement_model',
237
+ 'implement_effort',
238
+ // The plan review's cycle now (a tune, an unblock, an amend opens one): which passes and
239
+ // findings a board shows as current (Plan-Review-Rework-Plan d2).
240
+ 'plan_cycle',
233
241
  'run_mode',
234
242
  'skip_gates',
235
243
  'gate_why',
package/lib/changes.js CHANGED
@@ -9,6 +9,7 @@ import { isValidId } from './id.js';
9
9
  import { verifiedBranches, worktreeOf } from './integrate.js';
10
10
  import { branchState } from './push.js';
11
11
  import { refusal } from './refusal.js';
12
+ import { isInstruction } from './rules.js';
12
13
  import { fileState, newFileDiff, readHead } from './tree-file.js';
13
14
 
14
15
  // What a run leaves that is not work (the harness's NOT_WORK); all else unwanted is .gitignore's.
@@ -489,7 +490,12 @@ async function readTree(projectDir, asked) {
489
490
  return { tree, rows: rowsOf(tree, worktree), noDiff: await noDiffOf(projectDir) };
490
491
  }
491
492
 
492
- const outward = ({ modes: _m, xy: _x, openFrom: _o, ...row }) => row;
493
+ // `instructions`: a file an agent reads as its instructions (Lessons-Review-Plan d9), whoever wrote
494
+ // it: the board marks it. A rename marks from either side: one renamed away is gone from them.
495
+ const outward = ({ modes: _m, xy: _x, openFrom: _o, ...row }) =>
496
+ isInstruction(row.path) || (row.from && isInstruction(row.from))
497
+ ? { ...row, instructions: true }
498
+ : row;
493
499
 
494
500
  /**
495
501
  * What is uncommitted in the main checkout, or a run's worktree (`worktree`: its item's id).
@@ -7,6 +7,8 @@ import { withFileRollback } from './safe-path.js';
7
7
  import { writeIndex } from './index-gen.js';
8
8
  import { operationInProgress, commitPaths, dirtyGcf, dirtyRefusal } from './git.js';
9
9
  import { withMainLock } from './main-lock.js';
10
+ import { planDrop, planGroup, untrackedEntries } from './inbox.js';
11
+ import { gcfRoot } from './gcf-paths.js';
10
12
 
11
13
  /** A file's text at a git revision spec (`HEAD:./x`, `:./x` for the index), '' when absent. */
12
14
  function gitText(projectDir, spec) {
@@ -23,7 +25,7 @@ function gitText(projectDir, spec) {
23
25
  * True when `file` differs from HEAD in the index or on disk. Line endings do not count: a file
24
26
  * stored with CRLF and checked out with LF is not an edit.
25
27
  */
26
- function uncommitted(projectDir, file) {
28
+ export function uncommitted(projectDir, file) {
27
29
  const rel = `./${path.relative(projectDir, file).replaceAll('\\', '/')}`;
28
30
  const norm = (t) => String(t).replace(/\r\n/g, '\n').trimEnd();
29
31
  const head = norm(gitText(projectDir, `HEAD:${rel}`));
@@ -44,7 +46,7 @@ export const onWorkBranch = (projectDir) =>
44
46
 
45
47
  /**
46
48
  * @typedef {{files: string[], mutate: () => Promise<unknown>, commit: boolean, inputs?: string[],
47
- * key?: string, items?: string[], proposal?: string}} Move
49
+ * key?: string, items?: string[], proposal?: string, reason?: string, empty?: boolean}} Move
48
50
  */
49
51
 
50
52
  /**
@@ -55,24 +57,67 @@ export const onWorkBranch = (projectDir) =>
55
57
  * their own uncommitted edits (an answer, a live: delta) ride along on purpose.
56
58
  * @param {string} projectDir
57
59
  * @param {string} message
58
- * `key` is the domain's move key, `items` the ids it touched and `proposal` the board's proposal
59
- * it carries out: the commit's trailers (moveTrailers).
60
+ * `key` is the domain's move key, `items` the ids it touched, `proposal` the board's proposal
61
+ * it carries out and `reason` why: the commit's trailers (moveTrailers). `empty`: it commits
62
+ * even with nothing to change, so its trailers stand (an erase of entries never committed).
60
63
  * @param {Move} move
61
64
  * @returns {Promise<string | null>} the commit's hash, null when it does not commit
62
65
  */
63
66
  export async function commitMove(projectDir, message, move) {
67
+ const { proposal, reason } = move;
68
+ if (proposal !== undefined && !/^[\w-]+\/[\w-]+$/.test(proposal))
69
+ throw new Error(`--proposal is <thread>/<proposal id>, not ${proposal}`);
70
+ // A trailer is one line: a line break in it would forge another.
71
+ if (reason !== undefined && /[\r\n]/.test(reason)) throw new Error('a reason is one line');
72
+
64
73
  // A move that commits holds the main lock while it writes and commits (Methodology §7).
65
74
  return move.commit
66
75
  ? withMainLock(projectDir, () => record(projectDir, message, move))
67
76
  : record(projectDir, message, move);
68
77
  }
69
78
 
79
+ /**
80
+ * A move that writes files of its own and erases inbox entries `move.ids` in one commit
81
+ * (Lessons-Review-Plan d3): `make` gives its `files` and how to `write` them, made under the main
82
+ * lock, as the entries' plans are, each checked before any is written. Entries never committed
83
+ * ride along, as with an inbox move. Returns the commit's hash.
84
+ * @param {string} projectDir
85
+ * @param {string} message
86
+ * @param {Omit<Move, 'files' | 'mutate' | 'inputs'> & {ids: string[]}} move
87
+ * `undo` takes back what `write` put outside the project's rollback, when the attempt fails.
88
+ * @param {() => Promise<{files: string[], write: () => Promise<unknown>,
89
+ * undo?: () => Promise<unknown>}>} make
90
+ */
91
+ export async function commitWithEntries(projectDir, message, { ids, ...move }, make) {
92
+ const go = async () => {
93
+ const { files, write, undo } = await make();
94
+ const drop = await planGroup(ids, (id) => planDrop(gcfRoot(projectDir), id));
95
+ const loose = move.commit ? untrackedEntries(projectDir) : [];
96
+
97
+ try {
98
+ return await commitMove(projectDir, message, {
99
+ ...move,
100
+ files: [...files, ...drop.files, ...loose],
101
+ inputs: [...files, ...drop.inputs, ...loose],
102
+ mutate: async () => {
103
+ await write();
104
+ await drop.apply();
105
+ },
106
+ });
107
+ } catch (e) {
108
+ // What it wrote outside the rollback goes in each failed attempt: one that waits behind a
109
+ // main run and goes again (withMainLock) starts from nothing written.
110
+ await undo?.();
111
+ throw e;
112
+ }
113
+ };
114
+
115
+ return move.commit ? withMainLock(projectDir, go) : go();
116
+ }
117
+
70
118
  /** @param {string} projectDir @param {string} message @param {Move} move */
71
- async function record(
72
- projectDir,
73
- message,
74
- { files, mutate, commit, inputs = [], key, items, proposal },
75
- ) {
119
+ async function record(projectDir, message, move) {
120
+ const { files, mutate, commit, inputs = [], items } = move;
76
121
  if (commit && onWorkBranch(projectDir))
77
122
  throw new Error(
78
123
  `cannot record ${message} on a work/ branch: a worktree records no move — the run ` +
@@ -106,7 +151,7 @@ async function record(
106
151
  async () => {
107
152
  await mutate();
108
153
  await writeIndex(root);
109
- if (commit) hash = commitPaths(projectDir, message, touched, { key, items, proposal });
154
+ if (commit) hash = commitPaths(projectDir, message, touched, move);
110
155
  },
111
156
  { gitCwd: commit ? path.resolve(projectDir) : null },
112
157
  );
package/lib/config-set.js CHANGED
@@ -25,6 +25,7 @@ import {
25
25
  REVIEW_DEFAULTS,
26
26
  reviewRowProblem,
27
27
  RUN_MODES,
28
+ RUN_PHASES,
28
29
  RUN_WORD,
29
30
  } from './gcf-paths.js';
30
31
  import { AIF_CONFIG, LANGUAGE_RE, languageIn, readAifConfig } from './aif-config.js';
@@ -100,8 +101,9 @@ export const SETTINGS = [
100
101
  key: 'review.plan',
101
102
  kind: 'passes',
102
103
  label:
103
- 'the passes of a plan review, row k makes pass k: the next goes only while the last found ' +
104
- 'something blocking; the rows over, the card blocks for you (none: no review)',
104
+ 'the passes of a plan review, row k makes pass k: the first reviews the whole plan, the ' +
105
+ "rest check the author's fixes; the next goes only while the last found something " +
106
+ 'blocking; the rows over, the card blocks for you (none: no review)',
105
107
  },
106
108
  {
107
109
  key: 'review.code',
@@ -294,7 +296,33 @@ for (const s of SETTINGS) {
294
296
  if (EXAMPLE[s.key]) Object.assign(s, { example: EXAMPLE[s.key] });
295
297
  }
296
298
 
297
- const BY_KEY = new Map(SETTINGS.map((s) => [s.key, s]));
299
+ /**
300
+ * A phase's own model and effort (Plan-Review-Rework-Plan d10), set by `gcf config set` but no
301
+ * row of a settings screen yet: the screen's phase pair shows what a phase inherits and tells a
302
+ * pick from a reset (t4). GCF's own defaults are `PHASE_DEFAULTS`, under `agent.model|effort`.
303
+ * @type {typeof SETTINGS}
304
+ */
305
+ const PHASE_SETTINGS = RUN_PHASES.flatMap((phase) =>
306
+ ['model', 'effort'].map((k) => ({
307
+ key: `agent.${phase}.${k}`,
308
+ kind: /** @type {Kind} */ ('word'),
309
+ label: `the ${k} of the ${phase} phase of a run, over agent.${k}`,
310
+ })),
311
+ );
312
+
313
+ /**
314
+ * The phase keys the project sets, each with its value: `gcf config` lists them (d10).
315
+ * @public gcf.js imports lib modules by name at run time, out of knip's sight.
316
+ */
317
+ export const phaseValues = (raw) =>
318
+ PHASE_SETTINGS.flatMap((s) => {
319
+ const [, phase, k] = s.key.split('.');
320
+ const v = raw?.agent?.[phase]?.[k];
321
+
322
+ return v === null || v === undefined ? [] : [{ ...s, value: v }];
323
+ });
324
+
325
+ const BY_KEY = new Map([...SETTINGS, ...PHASE_SETTINGS].map((s) => [s.key, s]));
298
326
 
299
327
  // What a settings screen groups the keys under, in its order.
300
328
  /** @type {[string, string[]][]} */
@@ -466,6 +494,17 @@ function numberOf(setting, t) {
466
494
  return n;
467
495
  }
468
496
 
497
+ /**
498
+ * Write one key of two or three levels (`agent.plan.effort`), each level above it a map; null
499
+ * takes it off.
500
+ */
501
+ function setKey(doc, keys, value, name) {
502
+ for (let n = 1; n < keys.length; n++)
503
+ ensureMap(doc, keys.slice(0, n), `${name}: ${keys.slice(0, n).join('.')} must map its keys`);
504
+ if (value === null) doc.deleteIn(keys);
505
+ else doc.setIn(keys, value);
506
+ }
507
+
469
508
  /** `review.*` set: the keys it replaces go with it, in the same commit (t2 d1). */
470
509
  function dropOldReview(doc, keys) {
471
510
  if (keys[0] !== 'review') return;
@@ -491,7 +530,7 @@ const trackedByGit = (projectDir, file) =>
491
530
  */
492
531
  export async function setConfig(projectDir, key, text, { commit = true } = {}) {
493
532
  const setting = BY_KEY.get(key);
494
- if (!setting) throw new Error(`no setting ${key}: ${SETTINGS.map((s) => s.key).join(' | ')}`);
533
+ if (!setting) throw new Error(`no setting ${key}: ${[...BY_KEY.keys()].join(' | ')}`);
495
534
  const value = valueOf(setting, text);
496
535
  const name = setting.file ?? 'gcf/config.yml';
497
536
  const file = setting.file
@@ -515,14 +554,12 @@ export async function setConfig(projectDir, key, text, { commit = true } = {}) {
515
554
  const text = existsSync(file) ? await readFile(file, 'utf8') : '';
516
555
  const doc = configDoc(text, name);
517
556
  // A reset of a key whose parent is not there changes nothing: no empty map is written.
518
- if (value === null && keys.length > 1 && !YAML.isMap(doc.getIn([keys[0]], true))) {
557
+ if (value === null && keys.length > 1 && !YAML.isMap(doc.getIn(keys.slice(0, -1), true))) {
519
558
  unchanged = true;
520
559
  throw NO_CHANGE;
521
560
  }
522
561
 
523
- if (keys.length > 1) ensureMap(doc, [keys[0]], `${name}: ${keys[0]} must map its keys`);
524
- if (value === null) doc.deleteIn(keys);
525
- else doc.setIn(keys, value);
562
+ setKey(doc, keys, value, name);
526
563
  dropOldReview(doc, keys);
527
564
  const raw = doc.toJS();
528
565
  // `agent:` is read by its own rules: a key set here must not leave a broken section.
@@ -560,7 +597,7 @@ export async function setConfigs(projectDir, pairs, { commit = true } = {}) {
560
597
  if (!pairs.length) throw new Error('name a key=value to set');
561
598
  const changes = pairs.map(([key, text]) => {
562
599
  const setting = BY_KEY.get(key);
563
- if (!setting) throw new Error(`no setting ${key}: ${SETTINGS.map((s) => s.key).join(' | ')}`);
600
+ if (!setting) throw new Error(`no setting ${key}: ${[...BY_KEY.keys()].join(' | ')}`);
564
601
  if (setting.file) throw new Error(`${key} lives in ${setting.file}: set it on its own`);
565
602
 
566
603
  return { key, keys: key.split('.'), value: valueOf(setting, text) };
@@ -572,12 +609,13 @@ export async function setConfigs(projectDir, pairs, { commit = true } = {}) {
572
609
  const doc = configDoc(text, 'gcf/config.yml');
573
610
  for (const c of changes) {
574
611
  // A reset of a key whose parent is not there changes nothing: no empty map is written.
575
- if (c.value === null && c.keys.length > 1 && !YAML.isMap(doc.getIn([c.keys[0]], true)))
612
+ if (
613
+ c.value === null &&
614
+ c.keys.length > 1 &&
615
+ !YAML.isMap(doc.getIn(c.keys.slice(0, -1), true))
616
+ )
576
617
  continue;
577
- if (c.keys.length > 1)
578
- ensureMap(doc, [c.keys[0]], `gcf/config.yml: ${c.keys[0]} must map its keys`);
579
- if (c.value === null) doc.deleteIn(c.keys);
580
- else doc.setIn(c.keys, c.value);
618
+ setKey(doc, c.keys, c.value, 'gcf/config.yml');
581
619
  dropOldReview(doc, c.keys);
582
620
  }
583
621
 
package/lib/domain.js CHANGED
@@ -4,7 +4,9 @@
4
4
  // draws these and builds each command from `args` and `fields`; it hard-codes none of them.
5
5
  import { ITEM_MOVES, STORED } from './transitions.js';
6
6
  import { DEFAULT_GATE, GATES, ITEM_TYPES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
7
- import { BASE_CATEGORIES, mergeVocabulary, questionOnly } from './inbox-categories.js';
7
+ import { BASE_CATEGORIES, mergeVocabulary, questionOnly, REPORT_TO } from './inbox-categories.js';
8
+ import { DROP_REASONS } from './inbox.js';
9
+ import { INSTRUCTION_PATHS, RULE_FILES, RULE_MAX } from './rules.js';
8
10
  import { NOTE_MAX } from './work-ops.js';
9
11
  import { SESSION_TTL_MS } from './session-mark.js';
10
12
  import { RUN_MODES } from './gcf-paths.js';
@@ -188,7 +190,9 @@ const ITEM_SPECS = {
188
190
  label: 'model / effort',
189
191
  help: 'The model and effort of its runs: the next run takes them',
190
192
  args: ['gcf', 'item', 'agent', '{id}'],
191
- fields: [MODEL, EFFORT],
193
+ // `phase`: a board's Plan / Implement pick fills it, the phase's own then
194
+ // (Plan-Review-Rework-Plan d10); none, the item's own.
195
+ fields: [MODEL, EFFORT, text('phase', 'Phase: plan | implement', { hidden: true })],
192
196
  rare: true,
193
197
  },
194
198
  gates: {
@@ -283,11 +287,12 @@ const ITEM_SPECS = {
283
287
  { key: 'text', label: 'Blocks to replace', kind: 'longtext', stdin: true },
284
288
  { key: 'add', label: 'Lines to add to notes', kind: 'longtext', max: NOTE_MAX },
285
289
  text('title', 'Title'),
286
- text('from', 'Inbox entry it takes: erased'),
290
+ text('from', 'Inbox entry it takes: erased', { help: 'several of one cause as in-a,in-b' }),
287
291
  text('base', 'Read at', { hidden: true }),
288
292
  ],
289
293
  rare: true,
290
294
  propose: true,
295
+ proposal_trailer: true,
291
296
  // `--dry-run --json` says what it would change: a board shows that before the move.
292
297
  preview: true,
293
298
  // A human fixing a built card: the fix reaches its next run, not the code it has.
@@ -377,9 +382,20 @@ const NEW_ITEM = {
377
382
  max: NOTE_MAX,
378
383
  stdin: true,
379
384
  },
380
- // The inbox entry it comes from: the form fills it, the operator does not.
381
- text('from', 'From inbox entry', { hidden: true }),
385
+ // The inbox entries it comes from: the form fills it, the operator does not; an agent
386
+ // proposes the group it read (Lessons-Review-Plan d7).
387
+ {
388
+ key: 'from',
389
+ label: 'From inbox entries',
390
+ kind: 'ids',
391
+ inbox: true,
392
+ help: 'erased in its commit; several are a bullet each in its note, unless a note is given',
393
+ hidden: true,
394
+ propose: true,
395
+ },
382
396
  ],
397
+ // Its commit names the board's proposal it makes (`--proposal`): a recovery finds it by that.
398
+ proposal_trailer: true,
383
399
  };
384
400
 
385
401
  // A part of the design a save names (`gcf design part`): its kind, and the hash it was read at.
@@ -503,6 +519,16 @@ const PLAY_SAY =
503
519
  'command, or the folder is not ignored, propose a tech card with propose_item_new instead: one ' +
504
520
  'command builds the game into an ignored folder, one starts it with the folder and a port, ' +
505
521
  'AGENTS.md names both.';
522
+ // The files that steer an agent (rules.js INSTRUCTION_PATHS: a file as it is, a folder whole, no
523
+ // `:(exclude)` left, a plan is no review's to write either): a lessons review's
524
+ // agent writes none of them, by an edit or by a shell command that names one.
525
+ // shortcut: a command that spells a path another way (`.claude\x`, a variable, an assembled
526
+ // string) passes the shell rule, and native Windows has no Claude Code sandbox to stop it; the
527
+ // backstop is the board's Changes mark of dirty instruction files (`gcf changes` `instructions`).
528
+ // Upgrade when the agent runs in a sandbox that confines its writes.
529
+ const INSTRUCTION_EDITS = INSTRUCTION_PATHS.filter((p) => !p.startsWith(':')).map((p) =>
530
+ RULE_FILES.includes(p) ? p : `${p}/**`,
531
+ );
506
532
  const STARTS = {
507
533
  vision: {
508
534
  label: 'Create with agent',
@@ -621,6 +647,24 @@ const STARTS = {
621
647
  say: `${PLAY_SAY} The setup now and what went wrong: {text}`,
622
648
  edits: [],
623
649
  },
650
+ // A lessons review (Lessons-Review-Plan d1, d2): `{text}` the lesson ids, the board passes only
651
+ // inbox entries of category `entries`. Its agent proposes, the operator clicks; a rule goes
652
+ // through `rules add`, never an edit: `deny` holds under YOLO too. `next`: what the board's
653
+ // Next sends once the agent's turn with its cards is over (gcf-triage: "the human says next").
654
+ 'lessons-review': {
655
+ label: 'Review lessons',
656
+ help: 'The agent groups the lessons by cause and proposes one outcome a group: you click',
657
+ skill: 'gcf-triage',
658
+ takes: 'text',
659
+ entries: 'lesson',
660
+ say: 'Review the lessons {text} with me, group by group.',
661
+ edits: [],
662
+ deny: INSTRUCTION_EDITS.flatMap((pattern) => [
663
+ { kind: 'edit', pattern },
664
+ { kind: 'shell', pattern: `*${pattern.replace('/**', '/')}*` },
665
+ ]),
666
+ next: 'next',
667
+ },
624
668
  };
625
669
 
626
670
  // The way from an empty project to its first work, in order: the board shows each step done or
@@ -739,13 +783,28 @@ const BLOCK_SPECS = {
739
783
  ],
740
784
  propose: true,
741
785
  },
786
+ // A group of entries in one commit (Lessons-Review-Plan d3): `{ids}`, why in its commit.
742
787
  'inbox-drop': {
743
788
  label: 'erase',
744
- help: 'Noise: the entry is erased, nothing is made of it',
745
- args: ['gcf', 'inbox', 'drop', '{id}', '--commit'],
746
- fields: [],
789
+ help: 'Noise: the entries are erased, nothing is made of them',
790
+ args: ['gcf', 'inbox', 'drop', '{ids}', '--commit'],
791
+ fields: [
792
+ {
793
+ key: 'reason',
794
+ label: 'Why',
795
+ kind: 'choice',
796
+ options: [
797
+ { value: '', label: 'not said' },
798
+ ...Object.entries(DROP_REASONS).map(([value, help]) => ({ value, label: value, help })),
799
+ ],
800
+ },
801
+ text('of', 'Of: the item, entry or commit it duplicates or that did it', {
802
+ when: { key: 'reason', is: ['done', 'duplicate', 'reported', 'amended'] },
803
+ }),
804
+ ],
747
805
  danger: true,
748
806
  propose: true,
807
+ proposal_trailer: true,
749
808
  },
750
809
  'inbox-category': {
751
810
  label: 'sort',
@@ -757,10 +816,11 @@ const BLOCK_SPECS = {
757
816
  },
758
817
  'inbox-later': {
759
818
  label: 'later',
760
- help: 'Put the entry away to Later: nothing there asks for you now',
761
- args: ['gcf', 'inbox', 'later', '{id}', '--commit'],
819
+ help: 'Put the entries away to Later: nothing there asks for you now',
820
+ args: ['gcf', 'inbox', 'later', '{ids}', '--commit'],
762
821
  fields: [],
763
822
  propose: true,
823
+ proposal_trailer: true,
764
824
  },
765
825
  'inbox-back': {
766
826
  label: 'back',
@@ -768,6 +828,74 @@ const BLOCK_SPECS = {
768
828
  args: ['gcf', 'inbox', 'later', '{id}', '--off', '--commit'],
769
829
  fields: [],
770
830
  },
831
+ // The outcomes of a lessons review the core writes (Lessons-Review-Plan d5-d7): the human's
832
+ // moves, an agent proposes them. `preview`: a board shows their `--dry-run --json` (the rules'
833
+ // diff, the report's files) before the move.
834
+ 'rules-add': {
835
+ label: 'add rule',
836
+ help: 'A line under ## Project rules of AGENTS.md, and of a CLAUDE.md that does not import it',
837
+ args: ['gcf', 'rules', 'add', '--commit'],
838
+ fields: [
839
+ text('text', 'Rule: one line every agent of the project reads', {
840
+ required: true,
841
+ max: RULE_MAX,
842
+ }),
843
+ { key: 'from', label: 'Inbox entries it settles: erased', kind: 'ids', inbox: true },
844
+ // The board fills it from the dry run it showed: files changed since are refused.
845
+ text('base', 'Read at', { hidden: true }),
846
+ ],
847
+ propose: true,
848
+ proposal_trailer: true,
849
+ preview: true,
850
+ },
851
+ 'lessons-report': {
852
+ label: 'report',
853
+ help: 'Lessons about GCF or the template: a file each in ~/.gcf/lessons/, the entries erased',
854
+ args: ['gcf', 'lessons', 'report', '--commit'],
855
+ fields: [
856
+ { key: 'from', label: 'Lessons', kind: 'ids', required: true, inbox: true },
857
+ {
858
+ key: 'to',
859
+ label: 'To',
860
+ kind: 'choice',
861
+ required: true,
862
+ options: REPORT_TO.map((value) => ({ value, label: value })),
863
+ },
864
+ ],
865
+ propose: true,
866
+ proposal_trailer: true,
867
+ preview: true,
868
+ },
869
+ // The Rules screen's save (d8): the human's whole text of one file, GCF's block as it was read.
870
+ // The screen fills every field: `base` from `gcf rules --json`, so a file changed since is
871
+ // refused; the text goes on stdin. Its preview is the diff from HEAD.
872
+ 'rules-save': {
873
+ label: 'save rules',
874
+ help: "Save the human's text of AGENTS.md or CLAUDE.md; GCF's block stays as it is",
875
+ args: ['gcf', 'rules', 'save', '--commit'],
876
+ fields: [
877
+ {
878
+ key: 'file',
879
+ label: 'File',
880
+ kind: 'choice',
881
+ required: true,
882
+ hidden: true,
883
+ options: RULE_FILES.map((value) => ({ value, label: value })),
884
+ },
885
+ text('base', 'Read at', { required: true, hidden: true }),
886
+ // `clear`: an empty text is a value, a file with no block emptied.
887
+ {
888
+ key: 'text',
889
+ label: 'Text',
890
+ kind: 'longtext',
891
+ required: true,
892
+ clear: true,
893
+ stdin: true,
894
+ hidden: true,
895
+ },
896
+ ],
897
+ preview: true,
898
+ },
771
899
  // A chat's button to play: the board opens what it starts (docs/Play-Plan.md d17).
772
900
  play: {
773
901
  label: 'play',
@@ -962,7 +1090,9 @@ const SECTIONS = {
962
1090
  // `commit`: its `gcf changes commit` takes the operator's ticked files and message.
963
1091
  // `push`, `pull`: `gcf changes push|pull`, fast-forward only (docs/Push-Plan.md).
964
1092
  changes: { commit: true, push: true, pull: true },
965
- lessons: {},
1093
+ // A lessons review (Lessons-Review-Plan d1, d10): the start, and the moves of the manual strip
1094
+ // beside the inbox's own erase and Later.
1095
+ lessons: { review: 'lessons-review', rule: 'rules-add', report: 'lessons-report' },
966
1096
  playtest: {
967
1097
  // The inbox category a note from the playtest screen goes with.
968
1098
  category: 'playtest',
@@ -1033,6 +1163,9 @@ const CHANGES = [
1033
1163
  'inbox migrate',
1034
1164
  'inbox drop',
1035
1165
  'lessons add',
1166
+ 'lessons report',
1167
+ 'rules add',
1168
+ 'rules save',
1036
1169
  'config set',
1037
1170
  'permissions',
1038
1171
  'worktree',
package/lib/gcf-paths.js CHANGED
@@ -29,6 +29,16 @@ export const DEFAULT_CONFIG = {
29
29
  session_timeout_min: 120,
30
30
  };
31
31
 
32
+ // The phases of an item's run, each with its own model and effort (Plan-Review-Rework-Plan d10).
33
+ export const RUN_PHASES = ['plan', 'implement'];
34
+
35
+ // GCF's own model and effort of a phase: below the project's `agent.model|effort`, over the
36
+ // agent's defaults. The plan's author judges the review's findings: high.
37
+ export const PHASE_DEFAULTS = {
38
+ plan: { model: null, effort: 'high' },
39
+ implement: { model: null, effort: null },
40
+ };
41
+
32
42
  // A model or effort word as the agent's command line takes it; a leading hyphen would read as a
33
43
  // flag of it.
34
44
  export const RUN_WORD = /^[A-Za-z0-9][\w.-]*$/;
@@ -113,11 +123,12 @@ function gatesOf(v = {}) {
113
123
 
114
124
  // The review passes of a plan and of the code (Operator-Tasks-Plan t2 d1): row k makes pass k,
115
125
  // the next goes only while the last found something blocking; the rows over, the operator
116
- // decides. An empty list: no review of that kind.
126
+ // decides. An empty list: no review of that kind. The plan's first row makes the one full review,
127
+ // the rest check the author's fixes (Plan-Review-Rework-Plan d3, d9): the first runs high.
117
128
  export const REVIEW_AGENTS = ['claude', 'codex'];
118
129
  export const REVIEW_DEFAULTS = {
119
130
  plan: [
120
- { agent: 'codex', model: 'astra', effort: 'medium' },
131
+ { agent: 'codex', model: 'astra', effort: 'high' },
121
132
  { agent: 'claude', model: 'fable', effort: 'medium' },
122
133
  { agent: 'claude', model: 'fable', effort: 'medium' },
123
134
  ],