gcf-aif-ext 0.29.0 → 0.29.1

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/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.29.0",
4
+ "version": "0.29.1",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -102,7 +102,7 @@ const sameRule = (a, b) => a?.kind === b?.kind && a?.pattern === b?.pattern;
102
102
  const shell = (...patterns) => patterns.map((pattern) => ({ kind: 'shell', pattern }));
103
103
  const files = (kind, ...globs) => globs.map((pattern) => ({ kind, pattern }));
104
104
 
105
- /** @type {{ id: string, label: string, on: boolean, rules: Rule[] }[]} */
105
+ /** @type {{ id: string, label: string, on: boolean, run_only?: boolean, rules: Rule[] }[]} */
106
106
  export const DENY_GROUPS = [
107
107
  {
108
108
  id: 'git-history',
@@ -55,7 +55,7 @@ export function ticketsOf(projectDir) {
55
55
 
56
56
  return readdirSync(runsOf(dir))
57
57
  .map((name) => TICKET_RE.exec(name))
58
- .filter(Boolean)
58
+ .filter((m) => m !== null)
59
59
  .map((m) => readTicket(dir, Number(m[1])))
60
60
  .filter((t) => t && alive(t.pid))
61
61
  .sort((a, b) => a.n - b.n);
@@ -92,7 +92,10 @@ export function ticketSet(dir, n, fields) {
92
92
  return t;
93
93
  }
94
94
 
95
- /** The ticket goes with what its waiter ended with; a yield naming it lets its run go on. */
95
+ /**
96
+ * The ticket goes with what its waiter ended with; a yield naming it lets its run go on.
97
+ * @param {Record<string, unknown> | null} [outcome]
98
+ */
96
99
  export function ticketClose(projectDir, n, outcome = null) {
97
100
  const dir = path.resolve(projectDir);
98
101
  if (outcome) writeJson(outcomeFile(dir, n), { n, at: new Date().toISOString(), ...outcome });
@@ -219,6 +219,10 @@ async function locate(root, kind, name, type) {
219
219
  * `gcf design part <kind> <name>`: one part as a form shows it. `base` is the hash a save sends
220
220
  * back, so an edit made meanwhile is reported, not overwritten. `type` gives the fields of a
221
221
  * unit not written yet.
222
+ * @param {string} projectDir
223
+ * @param {string} kind
224
+ * @param {string} name
225
+ * @param {{type?: string | null}} [opts]
222
226
  */
223
227
  export async function designPart(projectDir, kind, name, { type = null } = {}) {
224
228
  const root = path.join(path.resolve(projectDir), 'gcf');
@@ -340,6 +344,7 @@ function pillarIds(part, given) {
340
344
  const now = part.fields.find((f) => f.key === 'pillars')?.value ?? [];
341
345
  const before = Array.isArray(now) ? now : [];
342
346
  const taken = new Set([...before, ...given].map((p) => p?.id).filter(Boolean));
347
+ /** @type {[string, string][]} */
343
348
  const renames = [];
344
349
  const records = given.map((p) => {
345
350
  if (!p || typeof p !== 'object') return p;
@@ -400,6 +405,13 @@ async function newUnitId(projectDir, kind, title, type) {
400
405
  return deriveId(oneLine(title), (await buildLedger(projectDir)).known, type);
401
406
  }
402
407
 
408
+ /**
409
+ * @param {string} projectDir
410
+ * @param {string} kind
411
+ * @param {string | null | undefined} given
412
+ * @param {{fields?: Record<string, any> | null, text?: string | null, base?: string | null,
413
+ * system?: string | null, type?: string | null, title?: string | null, commit?: boolean}} opts
414
+ */
403
415
  async function saveUnlocked(
404
416
  projectDir,
405
417
  kind,
@@ -455,7 +467,8 @@ async function saveUnlocked(
455
467
  ? skeleton(specs, { id: name, type: part.type, system: owner, title })
456
468
  : '';
457
469
  let lines = start ? start.split('\n') : [];
458
- for (const [key, value] of Object.entries(edits)) {
470
+ // `fields` is given when `text` is not (checked above).
471
+ for (const [key, value] of Object.entries(/** @type {Record<string, any>} */ (edits))) {
459
472
  const spec = specs.find((s) => s.key === key);
460
473
  if (!spec) throw new Error(`${key} is not a field of ${kind} ${name}`);
461
474
  const field = part.fields.find((f) => f.key === key);
@@ -471,7 +484,7 @@ async function saveUnlocked(
471
484
  next = await withManualAnswers(next, changedKeys(part.text, next), part.type);
472
485
  if (part.exists && hashOf(next) === part.base) return { applied: [], hash: null };
473
486
  // The base goes into the marker line: anything but a hash would break the bundle's shape.
474
- if (part.exists && !/^[0-9a-f]{8}$/.test(base))
487
+ if (part.exists && !/^[0-9a-f]{8}$/.test(/** @type {string} */ (base)))
475
488
  throw new Error(`--base is the 8-hex hash gcf design part gave: ${base}`);
476
489
  const marker = [
477
490
  `<!-- gcf:part ${kind} ${name}`,
@@ -518,6 +531,10 @@ class NothingApplied extends Error {}
518
531
  * Bring `text` in through the import and commit what it wrote. `strict`: a part the import
519
532
  * reports refuses the whole move. Files with changes not recorded yet refuse it up front: the
520
533
  * commit would carry them under the edit's name.
534
+ * @param {string} projectDir
535
+ * @param {string} message
536
+ * @param {string} text
537
+ * @param {{key: string, items?: string[], strict?: boolean, draft?: boolean, commit?: boolean}} opts
521
538
  */
522
539
  async function bundleMove(
523
540
  projectDir,
@@ -549,6 +566,7 @@ async function bundleMove(
549
566
  `${loose.join(', ')} holds changes not recorded yet: record the design first (gcf ` +
550
567
  `design commit)`,
551
568
  );
569
+ /** @type {Awaited<ReturnType<typeof importBundle>>} */
552
570
  let result = { applied: [], report: [] };
553
571
  try {
554
572
  const hash = await commitMove(projectDir, message, {
package/lib/devices.js CHANGED
@@ -84,7 +84,8 @@ const tailOf = (text) => text.trimEnd().split(/\r?\n/).slice(-20).join('\n');
84
84
  /**
85
85
  * `gcf playtest devices <target>`: what the target's script finds, each device placed under a row
86
86
  * of `plays_on` it fits, or why not.
87
- * @returns {Promise<{target: string, rows: object[], devices: object[], unavailable?: string,
87
+ * @returns {Promise<{target: string, rows: object[], devices: Array<Record<string, any>>,
88
+ * unavailable?: string,
88
89
  * problem?: string, tail?: string}>}
89
90
  */
90
91
  export async function devicesOf(projectDir, targetName, { ms = DEVICES_MS } = {}) {
package/lib/gates.js CHANGED
@@ -12,8 +12,9 @@ const AGENT_DECIDES = ['spike', 'decision'];
12
12
  /**
13
13
  * The gates in force for `item` (its frontmatter): the project's, or every item gate on its
14
14
  * second value (`skip_gates: true`) or on `wait` (`false`). `milestone` is the project's only.
15
- * @param {{gates: Record<string, string>}} config readConfig's
15
+ * @param {Record<string, any>} config readConfig's (its `gates`)
16
16
  * @param {Record<string, any> | null} [item]
17
+ * @returns {Record<string, string>}
17
18
  */
18
19
  export function gatePolicy(config, item = null) {
19
20
  const skip = item?.skip_gates;
package/lib/git.js CHANGED
@@ -267,7 +267,7 @@ function commitRefusal(message, out) {
267
267
  * @param {string} projectDir
268
268
  * @param {string} message
269
269
  * @param {string[]} paths
270
- * @param {{key?: string, items?: string[]}} [move]
270
+ * @param {{key?: string, items?: string[], proposal?: string}} [move]
271
271
  */
272
272
  export function commitPaths(projectDir, message, paths, move = {}) {
273
273
  const staged = paths.filter((p) => existsSync(p) || tracked(projectDir, p));
package/lib/handoff.js CHANGED
@@ -285,6 +285,11 @@ export function handoffLines(id, h) {
285
285
  /**
286
286
  * Blocks 0-7 of card `id`'s handoff, or null when it has none (it waits for nothing). `links`:
287
287
  * the snapshots' links, read once for a whole board.
288
+ * @param {string} projectDir
289
+ * @param {string} id
290
+ * @param {{ledger?: Awaited<ReturnType<typeof buildLedger>> | null,
291
+ * config?: Record<string, any> | null,
292
+ * links?: ReturnType<typeof import('./play.js').linksOf>}} [opts]
288
293
  */
289
294
  export async function handoffOf(projectDir, id, { ledger = null, config = null, links } = {}) {
290
295
  const dir = path.resolve(projectDir);
@@ -64,6 +64,15 @@ export const DETAIL = /^[a-z0-9][a-z0-9-]{0,29}$/;
64
64
 
65
65
  // `set_by`: the origins that may file it; `question`: a question record only (D1, D2), never an
66
66
  // entry. `details`: the closed list, or null for a free one. `later`: whether Later may hold it.
67
+ /**
68
+ * @param {string} id
69
+ * @param {string} label
70
+ * @param {string} help
71
+ * @param {number} rank
72
+ * @param {string} group
73
+ * @param {string[]} setBy
74
+ * @param {{details?: string[] | null, later?: boolean}} [opts]
75
+ */
67
76
  const row = (id, label, help, rank, group, setBy, { details = null, later = true } = {}) => ({
68
77
  id,
69
78
  label,
package/lib/inbox.js CHANGED
@@ -82,6 +82,7 @@ export function fromOld({ source, tags = [], kind, item }) {
82
82
  const laterOk = BASE_CATEGORIES.find((c) => c.id === category)?.later ?? true;
83
83
  const later = words.includes('later') && laterOk;
84
84
  const rest = words.filter((t) => t !== 'later');
85
+ /** @type {string | null} */
85
86
  let detail = null;
86
87
  if (lesson) detail = LESSON_KINDS.includes(String(kind)) ? String(kind) : 'other';
87
88
  else if (rest.length) {
@@ -239,6 +240,12 @@ function freeId(root, seed, taken) {
239
240
  }
240
241
  }
241
242
 
243
+ /**
244
+ * planAdd's options.
245
+ * @typedef {{category?: string, detail?: string | null, origin?: string, item?: string | null,
246
+ * by?: string, vocab?: typeof BASE_VOCABULARY, now?: string, taken?: Set<string>}} AddOpts
247
+ */
248
+
242
249
  /**
243
250
  * The origin of a new entry: `origin` when given, else who makes the move (`by`, moveBy). An
244
251
  * agent's run or session files as `agent` only: the channel, not the writer, says where it
@@ -258,6 +265,9 @@ function originOf(origin, by) {
258
265
  * A new entry's plan: its file and how to write it. Its id hashes the text and the moment
259
266
  * (`now`), so two branches never collide; a clash in this folder hashes again. The category
260
267
  * must be one its origin may file in `vocab`; a lesson's detail is its kind.
268
+ * @param {string} root
269
+ * @param {string} text
270
+ * @param {AddOpts} [opts]
261
271
  */
262
272
  export function planAdd(
263
273
  root,
@@ -328,6 +338,10 @@ async function planChange(root, id, change) {
328
338
  * Entry `id` moved to `category` (its own when none) with `detail` (none when the category
329
339
  * changes and no detail is given). The operator moves it to any category but a question's and
330
340
  * `unsorted`; an agent only to one it may file. Its origin stays: it says where it came from.
341
+ * @param {string} root
342
+ * @param {string} id
343
+ * @param {{category?: string, detail?: string | null, by?: string,
344
+ * vocab?: typeof BASE_VOCABULARY}} [opts]
331
345
  */
332
346
  export async function planCategory(
333
347
  root,
@@ -433,7 +447,12 @@ export async function planTake(root, id, toDir) {
433
447
  };
434
448
  }
435
449
 
436
- /** Add an entry at once (planAdd), the operator's note unless `opts` say; returns it. */
450
+ /**
451
+ * Add an entry at once (planAdd), the operator's note unless `opts` say; returns it.
452
+ * @param {string} root
453
+ * @param {string} text
454
+ * @param {AddOpts} [opts]
455
+ */
437
456
  export async function addInbox(root, text, opts = {}) {
438
457
  const plan = planAdd(root, text, { by: 'operator', category: 'note', ...opts });
439
458
  await plan.apply();
package/lib/integrate.js CHANGED
@@ -57,6 +57,8 @@ function dropLogs(dir) {
57
57
  * past the commit gate like a merge that needs no hand (git runs no pre-commit for it). `card`,
58
58
  * when given, may stop it too: main's text wins, the human's (a fix made while the branch waited).
59
59
  * True when the merge is done; false leaves the caller to abort it.
60
+ * @param {string} dir
61
+ * @param {string | null} [card]
60
62
  */
61
63
  async function mergedPastIndex(dir, card = null) {
62
64
  const unmerged = git(dir, ['diff', '--name-only', '--diff-filter=U'], { check: false })
@@ -129,6 +131,7 @@ async function syncWithMain(projectDir, dir, id) {
129
131
  git(dir, ['merge', '--no-edit', '-m', `gcf(sync): ${main}`, main], { check: false });
130
132
  const card = `gcf/work/${id}.md`;
131
133
  let res = merge();
134
+ /** @type {(() => void) | null} */
132
135
  let putBack = null;
133
136
  if (!res.ok && cardAloneHolds(dir, main, card)) {
134
137
  putBack = holdCard(dir, card);
@@ -295,6 +298,7 @@ function movedSinceMerge(projectDir, id) {
295
298
  * it took. Lines may be bullets. Empty when the plan has none.
296
299
  */
297
300
  export function planOutcome(text) {
301
+ /** @type {{decide: string | null, reason: string, assume: string[]}} */
298
302
  const out = { decide: null, reason: '', assume: [] };
299
303
  const at = String(text ?? '').search(/^## Outcome[ \t]*$/m);
300
304
  if (at < 0) return out;
package/lib/play-notes.js CHANGED
@@ -72,8 +72,11 @@ export function playNotesOf(planText) {
72
72
 
73
73
  /** The lines under each `### ` heading; a heading the format lacks goes to `unknown`. */
74
74
  function partsOf(block) {
75
+ /** @type {Record<string, string[]>} */
75
76
  const parts = Object.fromEntries(Object.keys(SECTIONS).map((k) => [k, []]));
77
+ /** @type {string[]} */
76
78
  const unknown = [];
79
+ /** @type {string | null | undefined} */
77
80
  let key = null;
78
81
  for (const line of block) {
79
82
  const h = /^###\s+(.+?)\s*$/.exec(line);
@@ -165,6 +168,7 @@ export function playNotesProblems(notes, rows) {
165
168
  /** The card's notes and their warnings, from its plan in `projectDir` (main or its worktree). */
166
169
  export async function playNotesCheck(projectDir, item) {
167
170
  const dir = path.resolve(projectDir);
171
+ /** @type {ReturnType<typeof playOf>} */
168
172
  let play = null;
169
173
  try {
170
174
  play = playOf(await readConfig(path.join(dir, 'gcf')));
package/lib/play-on.js CHANGED
@@ -8,11 +8,12 @@ const FIELDS = ['play_on', 'played_on'];
8
8
  * What the cards' build names lack. A line of game.md `platforms` (the old form) or a line of
9
9
  * words is a warning until Set up translates it; one word that names no build is an error. A
10
10
  * project with no `play:` (or a broken one: its own command says so) has no names to check.
11
- * @param {{data: object}[]} items
11
+ * @param {{data: Record<string, any>}[]} items
12
12
  * @param {string[]} platforms the `platforms` lines of game.md
13
13
  * @returns {{errors: string[], warnings: string[]}}
14
14
  */
15
15
  export function playOnIssues(items, config, platforms = []) {
16
+ /** @type {{errors: string[], warnings: string[]}} */
16
17
  const issues = { errors: [], warnings: [] };
17
18
  let play;
18
19
  try {
package/lib/play.js CHANGED
@@ -101,6 +101,7 @@ const leftovers = /^.+\.(?:tmp|old)-(\d+)$/;
101
101
  const KEY_RE = /^[0-9a-f]{16}(?:-[a-z0-9]+(?:-[a-z0-9]+)*|\.main)?$/;
102
102
  const CLEAN_KEY = /^[0-9a-f]{16}$/;
103
103
  // A link that cannot be read: nobody knows which snapshot it holds, so it holds them all (d24).
104
+ /** @type {Readonly<{unread: true, snap?: undefined, released?: undefined, source?: undefined}>} */
104
105
  const UNREAD = Object.freeze({ unread: true });
105
106
 
106
107
  function readJson(file) {
@@ -497,10 +498,10 @@ async function holdCheckout(dir, id) {
497
498
  export function linksOf(projectDir) {
498
499
  const dir = path.resolve(projectDir);
499
500
  const links = new Map();
500
- for (const [folder, snaps] of [
501
+ for (const [folder, snaps] of /** @type {[string, boolean][]} */ ([
501
502
  [buildsOf(dir), false],
502
503
  [snapsOf(dir), true],
503
- ])
504
+ ]))
504
505
  for (const e of listOf(folder)) {
505
506
  const f = e.isFile() && slotOfFile(e.name, snaps);
506
507
  if (!f || f.ext !== (snaps ? 'link.json' : 'json')) continue;
@@ -699,7 +700,7 @@ async function refusedNow(dir, who, from, ticket) {
699
700
  * old one with its facts. A card whose status moved on meanwhile (a verdict needs no wait for a
700
701
  * build) takes nothing. `reuse`: a build of the same code that ended meanwhile serves this one, and
701
702
  * this one is thrown away (d23).
702
- * @returns {Promise<{refused: string} | {facts: object}>}
703
+ * @returns {Promise<{refused?: string, stopped?: boolean, facts?: Record<string, any>}>}
703
704
  */
704
705
  async function publish(dir, { slot, key, tmp, facts, source, from, reuse, ticket }) {
705
706
  const target = snapOf(dir, key);
@@ -1576,7 +1577,7 @@ function heldBuild(dir, slot, links) {
1576
1577
  * a snapshot or an attempt of, by build then profile (docs/Handoff-Plan.md t17). A card back at
1577
1578
  * work has none to offer, unless one goes for it in its worktree right now. `links`: linksOf once
1578
1579
  * for a whole board.
1579
- * @returns {object[]}
1580
+ * @returns {Array<Record<string, any>>}
1580
1581
  */
1581
1582
  export function itemBuilds(projectDir, id, status, links = linksOf(projectDir)) {
1582
1583
  const dir = path.resolve(projectDir);
package/lib/push.js CHANGED
@@ -146,7 +146,8 @@ function outOf(dir, range) {
146
146
  .filter(Boolean)
147
147
  .map((rec) => {
148
148
  const [hash, subject, by = ''] = rec.split(FS);
149
- const named = by.trim().split(',').at(-1);
149
+ // A split gives one part at least.
150
+ const named = /** @type {string} */ (by.trim().split(',').at(-1));
150
151
 
151
152
  return { hash, subject, by: BY.includes(named) ? named : 'operator' };
152
153
  });
@@ -301,7 +302,8 @@ export async function pushBranch(dir, { remote, timeoutMs = NET_TIMEOUT_MS } = {
301
302
  const branch = refuseWhereNoPush(dir, 'push');
302
303
  const t = targetOf(dir, branch, remote);
303
304
  const before = hashOf(dir, t.track);
304
- const to = hashOf(dir, 'HEAD');
305
+ // refuseWhereNoPush refused a branch with no commit.
306
+ const to = /** @type {string} */ (hashOf(dir, 'HEAD'));
305
307
  const pushed = count(
306
308
  dir,
307
309
  before ? ['HEAD', `^${before}`] : ['HEAD', '--not', `--remotes=${t.remote}`],
@@ -362,8 +364,9 @@ export async function pullBranch(dir, { remote, timeoutMs = NET_TIMEOUT_MS } = {
362
364
  timeoutMs,
363
365
  );
364
366
  if (f.status !== 0) throw netFailure(f, t, 'pull', timeoutMs);
365
- const theirs = hashOf(dir, t.track);
366
- const head = hashOf(dir, 'HEAD');
367
+ // The fetch wrote the tracking ref; refuseWhereNoPush refused a branch with no commit.
368
+ const theirs = /** @type {string} */ (hashOf(dir, t.track));
369
+ const head = /** @type {string} */ (hashOf(dir, 'HEAD'));
367
370
  const base = { remote: t.remote, branch, upstream: t.short, from: head.slice(0, 7) };
368
371
  const ancestor = (a, b) => git(dir, ['merge-base', '--is-ancestor', a, b]).status === 0;
369
372
  if (ancestor(theirs, head)) return { ...base, to: head.slice(0, 7), pulled: 0 };
package/lib/questions.js CHANGED
@@ -58,6 +58,7 @@ function recordsOf(text) {
58
58
  /**
59
59
  * Every question: id, class, the question, the proposed answer, the ids it blocks and the
60
60
  * human's answer, each null when the record has none.
61
+ * @returns {Promise<Array<{id: string} & Record<string, string | null>>>}
61
62
  */
62
63
  export async function listQuestions(root) {
63
64
  const file = fileOf(root);
@@ -164,7 +165,8 @@ export async function appendQuestions(root, records) {
164
165
  let text = existsSync(file) ? await readFile(file, 'utf8') : '';
165
166
  const ids = [];
166
167
  for (const r of records) {
167
- if (!['D1', 'D2'].includes(r.class)) throw new Error('a question record is class D1 or D2');
168
+ if (!(/** @type {unknown[]} */ (['D1', 'D2']).includes(r.class)))
169
+ throw new Error('a question record is class D1 or D2');
168
170
  if (!oneLine(r.question)) throw new Error('a question record needs its question');
169
171
  const next = withRecord(text, r);
170
172
  ids.push(next.id);
@@ -90,7 +90,7 @@ export function upsertBlock(rawBody, key, addLines, order) {
90
90
  const kept = existing.filter((l) => !/^- none\b/.test(l));
91
91
  // A key the profile does not know goes last, after every block it does.
92
92
  const specs = (order.includes(key) ? order : [...order, key]).map((k) => ({ key: k }));
93
- const lead = body.match(/^\n*/)[0];
93
+ const lead = /** @type {RegExpMatchArray} */ (body.match(/^\n*/))[0];
94
94
  const text = body.slice(lead.length);
95
95
  let lines = text.split('\n');
96
96
  // Out and back in: a block a hand left out of the profile's order moves to its place.
@@ -101,7 +101,8 @@ export function upsertBlock(rawBody, key, addLines, order) {
101
101
  const end = Math.max(at.end, ...itemsOf(prose, at.start).map((i) => i.line));
102
102
  lines = [...lines.slice(0, at.start - 1), ...lines.slice(end)];
103
103
  while (lines.length > 1 && !lines[0].trim()) lines.shift();
104
- while (lines.length > 1 && !lines.at(-1).trim() && !lines.at(-2).trim()) lines.pop();
104
+ while (lines.length > 1 && !lines[lines.length - 1].trim() && !lines[lines.length - 2].trim())
105
+ lines.pop();
105
106
  }
106
107
 
107
108
  const put = putBlock(lines, specs, { key }, [`${key}:`, ...kept, ...fresh], { raw: true });
@@ -143,7 +144,7 @@ export function blocksNamed(rawText) {
143
144
  export function replaceBlock(rawBody, key, rendered, order) {
144
145
  const body = lf(rawBody);
145
146
  const specs = (order.includes(key) ? order : [...order, key]).map((k) => ({ key: k }));
146
- const lead = body.match(/^\n*/)[0];
147
+ const lead = /** @type {RegExpMatchArray} */ (body.match(/^\n*/))[0];
147
148
  const lines = body.slice(lead.length).split('\n');
148
149
  const put = putBlock(lines, specs, { key }, rendered, { raw: true });
149
150
 
@@ -207,8 +207,7 @@ const RULES = {
207
207
  nullable((x) => ['main', 'worktree'].includes(x))(v) || 'run_mode must be main | worktree',
208
208
  skip_gates: (v) => typeof v === 'boolean' || 'skip_gates must be true or false',
209
209
  gate_why: (v) => nullable(isText)(v) || 'gate_why must be text or null',
210
- play_on: (v) =>
211
- (Array.isArray(v) && v.every(isText)) || 'play_on must list names of play.builds',
210
+ play_on: (v) => (Array.isArray(v) && v.every(isText)) || 'play_on must list names of play.builds',
212
211
  version: (v) =>
213
212
  nullable((x) => typeof x === 'string' && /^\S+$/.test(x))(v) ||
214
213
  'version must be one word of text (quote a number: "1.0")',
package/lib/work-ops.js CHANGED
@@ -71,6 +71,7 @@ import { playNotesCheck, playNotesOf, withoutPlayNotes } from './play-notes.js';
71
71
  * @property {string[]} [assume] the agent's assumptions: D2 records in the move's commit
72
72
  * @property {boolean} [dropOutcome] the integrator's: the plan's `## Outcome` leaves in the commit
73
73
  * @property {string} [said] the agent's word for the human, into the commit's subject
74
+ * @property {string[]} [playedOn] a verdict's: where the operator played it
74
75
  */
75
76
 
76
77
  const SOFT = ['mechanic', 'resource'];
@@ -711,6 +712,7 @@ const playChanges = (item) =>
711
712
  /**
712
713
  * A4 in one write: gate verdict, awaiting-verdict, and why (`gate_why`) — status alone would
713
714
  * break "awaiting-verdict needs gate: verdict".
715
+ * @param {string | null} [why]
714
716
  */
715
717
  function awaitVerdict(m, why = null) {
716
718
  const data = {
@@ -1377,14 +1379,14 @@ async function stallItemUnlocked(projectDir, id, { passes, reason = '', commit =
1377
1379
  */
1378
1380
  async function answerStallUnlocked(projectDir, id, { more, accept = false, commit = true }) {
1379
1381
  const move = accept ? 'plan_accept' : 'plan_more';
1380
- if (!accept && !(Number.isInteger(more) && more >= 1))
1382
+ if (!accept && !(more !== undefined && Number.isInteger(more) && more >= 1))
1381
1383
  throw new Error('more passes: a number, 1 or more');
1382
1384
  const m = await begin(projectDir, id, move);
1383
1385
  const stall = m.item.data.stall;
1384
1386
  if (!stall) throw new Error(`${id} is not stalled in planning: nothing to answer`);
1385
1387
  const answered = accept
1386
1388
  ? { ...stall, accepted: true }
1387
- : { ...stall, more: Number(stall.more ?? 0) + more };
1389
+ : { ...stall, more: Number(stall.more ?? 0) + /** @type {number} */ (more) };
1388
1390
  const data = {
1389
1391
  ...without(m.item.data, 'blocked'),
1390
1392
  status: 'ready',
@@ -1789,9 +1791,13 @@ const SKIP_GATES = { skip: true, wait: false, project: undefined };
1789
1791
  * The operator's choice of an item's gates (docs/Autonomy-Plan.md, B): `skip` puts its verdict,
1790
1792
  * decision and question gates on their second value, `wait` holds them, `project` takes the
1791
1793
  * field off and the project's `gates:` hold. Commit `gcf(item)`, key `gates`.
1794
+ * @param {string} projectDir
1795
+ * @param {string} id
1796
+ * @param {{gates?: string, commit?: boolean}} [opts]
1792
1797
  */
1793
1798
  async function setGatesUnlocked(projectDir, id, { gates, commit = true } = {}) {
1794
- if (!(gates in SKIP_GATES)) throw new Error(`gates is ${Object.keys(SKIP_GATES).join(' | ')}`);
1799
+ if (gates === undefined || !(gates in SKIP_GATES))
1800
+ throw new Error(`gates is ${Object.keys(SKIP_GATES).join(' | ')}`);
1795
1801
  const ledger = await buildLedger(projectDir);
1796
1802
  const item = ledger.item(id);
1797
1803
  if (!item) throw new Error(`${id} is not a work item`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.29.0",
3
+ "version": "0.29.1",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -133,6 +133,8 @@ gcf_forbidden:
133
133
  - do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
134
134
  - do not run `ai-factory gcf phase next`: the phase moves on the human's word only
135
135
  - do not change what agent runs may do: `ai-factory gcf permissions`, its deny groups and the board's YOLO belong to the human
136
+ - a run blocked with `needs permission` goes on once the human allows that one rule for its next run: the board's **Allow <rule> for one run**
137
+ - its console form is `ai-factory gcf unblock <id>`, then `ai-factory gcf-harness run <id> --allow "<rule>"`, the rule as the refusal card names it
136
138
  - do not change a setting of `gcf/config.yml` or the `language` of `.ai-factory/config.yaml`: `ai-factory gcf config set` belongs to the human
137
139
  - do not reuse an ended id: rework gets a new id with `reopens: <old id>`
138
140
  - do not commit past the gate with `--no-verify`: a refused commit names what to fix