gcf-aif-ext 0.29.0 → 0.29.2

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.
Files changed (50) hide show
  1. package/commands/gcf.js +114 -57
  2. package/extension.json +1 -1
  3. package/hooks/pre-commit.js +2 -0
  4. package/lib/agent-permissions.js +7 -4
  5. package/lib/audit-core.js +28 -18
  6. package/lib/board.js +1 -1
  7. package/lib/build-queue.js +5 -2
  8. package/lib/changes.js +1 -0
  9. package/lib/commit-files.js +2 -1
  10. package/lib/commit-move.js +114 -0
  11. package/lib/config-doc.js +22 -0
  12. package/lib/config-set.js +34 -39
  13. package/lib/design-check.js +8 -3
  14. package/lib/design-parts.js +123 -74
  15. package/lib/devices.js +5 -9
  16. package/lib/edits.js +7 -3
  17. package/lib/frozen.js +24 -0
  18. package/lib/gate.js +1 -1
  19. package/lib/gates.js +2 -1
  20. package/lib/gcf-paths.js +13 -10
  21. package/lib/git.js +19 -5
  22. package/lib/handoff.js +6 -1
  23. package/lib/history.js +1 -1
  24. package/lib/inbox-categories.js +37 -35
  25. package/lib/inbox.js +65 -34
  26. package/lib/integrate.js +7 -12
  27. package/lib/ledger.js +1 -1
  28. package/lib/lessons.js +4 -1
  29. package/lib/metrics.js +1 -0
  30. package/lib/migrate.js +1 -1
  31. package/lib/milestone-state.js +1 -1
  32. package/lib/phase.js +1 -1
  33. package/lib/pillars.js +1 -1
  34. package/lib/play-notes.js +4 -0
  35. package/lib/play-on.js +2 -1
  36. package/lib/play.js +36 -9
  37. package/lib/playtest-list.js +1 -1
  38. package/lib/push.js +9 -5
  39. package/lib/questions.js +4 -2
  40. package/lib/session-mark.js +21 -2
  41. package/lib/shelf.js +1 -0
  42. package/lib/systems-doc.js +31 -20
  43. package/lib/unit-ops.js +31 -109
  44. package/lib/validate-item.js +1 -2
  45. package/lib/verdict-fs.js +2 -1
  46. package/lib/verify-stamp.js +6 -1
  47. package/lib/verify.js +6 -2
  48. package/lib/work-ops.js +126 -86
  49. package/package.json +1 -1
  50. package/templates/agents-block.md +3 -0
package/lib/work-ops.js CHANGED
@@ -15,7 +15,8 @@ import { atomicWrite, resolveInside } from './safe-path.js';
15
15
  import { allowedFrom, decisionFits, FEATURE_ONLY, fromOf } from './transitions.js';
16
16
  import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
17
17
  import { deriveId, isValidId } from './id.js';
18
- import { commitMove, addConstraints, onWorkBranch } from './unit-ops.js';
18
+ import { addConstraints } from './unit-ops.js';
19
+ import { commitMove, onWorkBranch } from './commit-move.js';
19
20
  import { blocksNamed, blocksOf, openSystemDoc, replaceBlock, upsertBlock } from './systems-doc.js';
20
21
  import { blockOrder } from './design.js';
21
22
  import {
@@ -58,6 +59,7 @@ import { appendQuestions, questionsFile } from './questions.js';
58
59
  import { refusal } from './refusal.js';
59
60
  import { releaseBuild } from './play.js';
60
61
  import { playNotesCheck, playNotesOf, withoutPlayNotes } from './play-notes.js';
62
+ import { frozenHash, legacyFrozen, matchesFrozen } from './frozen.js';
61
63
 
62
64
  /**
63
65
  * Options of a committed move; each move reads the ones it needs.
@@ -71,6 +73,7 @@ import { playNotesCheck, playNotesOf, withoutPlayNotes } from './play-notes.js';
71
73
  * @property {string[]} [assume] the agent's assumptions: D2 records in the move's commit
72
74
  * @property {boolean} [dropOutcome] the integrator's: the plan's `## Outcome` leaves in the commit
73
75
  * @property {string} [said] the agent's word for the human, into the commit's subject
76
+ * @property {string[]} [playedOn] a verdict's: where the operator played it
74
77
  */
75
78
 
76
79
  const SOFT = ['mechanic', 'resource'];
@@ -80,7 +83,11 @@ const gcfOf = (projectDir) => path.join(path.resolve(projectDir), 'gcf');
80
83
 
81
84
  /** HEAD's hash, null outside a repository or before the first commit. */
82
85
  function headHash(projectDir) {
83
- const res = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: projectDir, encoding: 'utf8' });
86
+ const res = spawnSync('git', ['rev-parse', 'HEAD'], {
87
+ windowsHide: true,
88
+ cwd: projectDir,
89
+ encoding: 'utf8',
90
+ });
84
91
 
85
92
  return res.status === 0 ? res.stdout.trim() : null;
86
93
  }
@@ -123,27 +130,6 @@ export function openDepends(ledger, depends = [], { waiting = false } = {}) {
123
130
  });
124
131
  }
125
132
 
126
- /**
127
- * The hash an unplayed item is frozen at (Methodology §5.4): its body and its `live:` delta —
128
- * the two things a tune or a kill takes back out of systems/ and LIVE.md.
129
- */
130
- export const frozenHash = (item) =>
131
- createHash('sha1')
132
- .update(String(item.body).replace(/\r\n/g, '\n').trim())
133
- .update(`\nlive: ${JSON.stringify(item.data.live ?? null)}`)
134
- .digest('hex');
135
-
136
- /** The 0.4.0 `frozen:`: the sha1 of the body alone, without the `live:` delta. */
137
- const legacyFrozen = (item) =>
138
- createHash('sha1').update(String(item.body).replace(/\r\n/g, '\n').trim()).digest('hex');
139
-
140
- /**
141
- * Whether an unplayed item still matches its `frozen:`. An item closed by 0.4.0 holds the
142
- * legacy form, which guards the body only, until `gcf init` restamps it (restampFrozen).
143
- */
144
- export const matchesFrozen = (item) =>
145
- item.data.frozen === frozenHash(item) || item.data.frozen === legacyFrozen(item);
146
-
147
133
  /** Whether the item's `live:` is the one its unplayed close committed. */
148
134
  function liveAsClosed(projectDir, item) {
149
135
  const close = unplayedCloseCommit(projectDir, item.data.id);
@@ -418,6 +404,7 @@ const dropKnownIssue = (m, id) =>
418
404
  /** True when git tracks `file`: an ignored or new plan stays out of the move's commit. */
419
405
  function tracked(projectDir, file) {
420
406
  const res = spawnSync('git', ['ls-files', '--error-unmatch', '--', file], {
407
+ windowsHide: true,
421
408
  cwd: projectDir,
422
409
  stdio: 'ignore',
423
410
  });
@@ -711,6 +698,7 @@ const playChanges = (item) =>
711
698
  /**
712
699
  * A4 in one write: gate verdict, awaiting-verdict, and why (`gate_why`) — status alone would
713
700
  * break "awaiting-verdict needs gate: verdict".
701
+ * @param {string | null} [why]
714
702
  */
715
703
  function awaitVerdict(m, why = null) {
716
704
  const data = {
@@ -926,6 +914,9 @@ const newCycle = (data) => ({
926
914
  plan_cycle: Number(data.plan_cycle ?? 0) + 1,
927
915
  });
928
916
 
917
+ // Where the operator played it: a note for the history, never a condition (Plan, C).
918
+ const playedNote = (playedOn) => (playedOn?.length ? ` (played on: ${playedOn.join('; ')})` : '');
919
+
929
920
  /** keep | tune | kill on an item waiting for its verdict or unplayed (Methodology §5.4).
930
921
  * @param {MoveOpts} [opts]
931
922
  */
@@ -938,9 +929,7 @@ async function verdictItemUnlocked(projectDir, id, verdict, opts = {}) {
938
929
  if (verdict === 'keep') await keep(m, constraints);
939
930
  else if (verdict === 'tune') await tune(m, note);
940
931
  else removal = endToGraveyard(m, m.item, { reason: note, tags, removal: remove ?? true });
941
- // Where the operator played it: a note for the history, never a condition (Plan, C).
942
- const played = opts.playedOn?.length ? ` (played on: ${opts.playedOn.join('; ')})` : '';
943
- const tail = `${verdict} ${id} → ${systems.join(',')}${played}`;
932
+ const tail = `${verdict} ${id} → ${systems.join(',')}${playedNote(opts.playedOn)}`;
944
933
  const hash = await finish(m, `verdict:${verdict}`, tail, commit);
945
934
 
946
935
  return { verdict, id, systems, hash, removal, ...buildLeft(m) };
@@ -955,11 +944,12 @@ function changedIn(projectDir) {
955
944
  const res = spawnSync(
956
945
  'git',
957
946
  ['-c', 'core.quotePath=false', 'status', '--porcelain', '-uall', '--', ...KEEP_SCOPE],
958
- { cwd: projectDir, encoding: 'utf8' },
947
+ { windowsHide: true, cwd: projectDir, encoding: 'utf8' },
959
948
  );
960
949
  if (res.status !== 0) throw new Error(`git status failed: ${res.stderr.trim()}`);
961
950
  // Porcelain paths are the repository's: a project inside a bigger repository is a prefix in.
962
951
  const prefix = spawnSync('git', ['rev-parse', '--show-prefix'], {
952
+ windowsHide: true,
963
953
  cwd: projectDir,
964
954
  encoding: 'utf8',
965
955
  }).stdout.trim();
@@ -1000,17 +990,8 @@ function keepOrder(pack) {
1000
990
  return order;
1001
991
  }
1002
992
 
1003
- /**
1004
- * keep of a whole milestone (docs/Autonomy-Plan.md, C): every unplayed and awaiting-verdict item
1005
- * of it, one commit, all or nothing. Every check comes before the first write: a frozen body
1006
- * edited, a dependency outside the milestone not played yet, a cycle inside it. The items
1007
- * inside keep in dependency order, each seeing the ones before it ended. gcf/ and the plans
1008
- * must be clean but for the pack's own item files (their compress edits ride along); a failure
1009
- * on the way restores them all.
1010
- * @param {MoveOpts & {playedOn?: string[]}} [opts]
1011
- */
1012
- async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
1013
- const { note = '', playedOn = [], commit = true } = opts;
993
+ /** The milestone's items that wait for its play, each checked before the first write. */
994
+ async function keepPack(projectDir, name) {
1014
995
  const root = gcfOf(projectDir);
1015
996
  const milestones = (await gameMilestones(root)) ?? [];
1016
997
  if (!milestones.some((m) => m.name === name))
@@ -1034,8 +1015,11 @@ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
1034
1015
  );
1035
1016
  }
1036
1017
 
1037
- const order = keepOrder(pack);
1038
- const own = new Set(pack.map((i) => path.relative(projectDir, i.file).replaceAll('\\', '/')));
1018
+ return pack;
1019
+ }
1020
+
1021
+ /** Refuse a milestone keep that would carry changes of gcf/ or the plans but the pack's own. */
1022
+ function refuseLoose(projectDir, name, own) {
1039
1023
  const loose = changedIn(projectDir).filter((c) => !own.has(c.file));
1040
1024
  if (loose.length) {
1041
1025
  // The board's Commit clears only gcf/'s edits: a loose plan gets the words alone.
@@ -1046,11 +1030,64 @@ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
1046
1030
  loose.map((c) => c.file).join(', '),
1047
1031
  );
1048
1032
  }
1033
+ }
1049
1034
 
1035
+ function refuseKeepBusy(projectDir, name, commit) {
1050
1036
  if (commit && onWorkBranch(projectDir))
1051
1037
  throw new Error('keep --milestone records on main: a work/ branch records no move');
1052
1038
  const busy = commit ? operationInProgress(projectDir) : null;
1053
1039
  if (busy) throw new Error(`cannot keep milestone ${name} while ${busy} is in progress`);
1040
+ }
1041
+
1042
+ /** The pack's keeps in `order`, and the one commit of them. */
1043
+ async function keepAll(projectDir, name, order, { note, playedOn, commit }) {
1044
+ for (const id of order)
1045
+ await verdictItemUnlocked(projectDir, id, 'keep', { note, playedOn, commit: false });
1046
+ if (!commit) return { milestone: name, ids: order, hash: null };
1047
+ const files = changedIn(projectDir).map((c) => path.join(projectDir, c.file));
1048
+ const message = `gcf(verdict): keep ${name} → ${order.join(', ')}${playedNote(playedOn)}`;
1049
+ const hash = commitPaths(projectDir, message, files, { key: 'verdict:keep', items: order });
1050
+ for (const id of order) clearCard(projectDir, id);
1051
+ const left = order.map((id) => releaseBuild(projectDir, id)).filter(Boolean);
1052
+
1053
+ return { milestone: name, ids: order, hash, ...(left.length ? { build_left: left } : {}) };
1054
+ }
1055
+
1056
+ function undoKeep(projectDir, own, saved, index) {
1057
+ // Nothing kept: what the keep wrote back to HEAD (staged or not); the pack's own files keep
1058
+ // the operator's edits on disk and in the index as they were.
1059
+ const mine = changedIn(projectDir)
1060
+ .map((c) => c.file)
1061
+ .filter((f) => !own.has(f));
1062
+ if (mine.length)
1063
+ spawnSync('git', ['reset', '-q', '--', ...mine], { windowsHide: true, cwd: projectDir });
1064
+ for (const c of changedIn(projectDir)) {
1065
+ if (own.has(c.file)) continue;
1066
+ if (c.untracked) rmSync(path.join(projectDir, c.file), { force: true });
1067
+ else
1068
+ spawnSync('git', ['checkout', 'HEAD', '--', c.file], { windowsHide: true, cwd: projectDir });
1069
+ }
1070
+
1071
+ for (const [file, text] of saved) writeFileSync(file, text);
1072
+ if (index) restoreIndex(index);
1073
+ }
1074
+
1075
+ /**
1076
+ * keep of a whole milestone (docs/Autonomy-Plan.md, C): every unplayed and awaiting-verdict item
1077
+ * of it, one commit, all or nothing. Every check comes before the first write: a frozen body
1078
+ * edited, a dependency outside the milestone not played yet, a cycle inside it. The items
1079
+ * inside keep in dependency order, each seeing the ones before it ended. gcf/ and the plans
1080
+ * must be clean but for the pack's own item files (their compress edits ride along); a failure
1081
+ * on the way restores them all.
1082
+ * @param {MoveOpts & {playedOn?: string[]}} [opts]
1083
+ */
1084
+ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
1085
+ const { note = '', playedOn = [], commit = true } = opts;
1086
+ const pack = await keepPack(projectDir, name);
1087
+ const order = keepOrder(pack);
1088
+ const own = new Set(pack.map((i) => path.relative(projectDir, i.file).replaceAll('\\', '/')));
1089
+ refuseLoose(projectDir, name, own);
1090
+ refuseKeepBusy(projectDir, name, commit);
1054
1091
 
1055
1092
  const saved = pack.map((i) => [i.file, readFileSync(i.file)]);
1056
1093
  // Their index as the operator left it: a staged compress edit stays staged after a rollback.
@@ -1058,33 +1095,10 @@ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
1058
1095
  projectDir,
1059
1096
  pack.map((i) => i.file),
1060
1097
  );
1061
- const played = playedOn.length ? ` (played on: ${playedOn.join('; ')})` : '';
1062
1098
  try {
1063
- for (const id of order)
1064
- await verdictItemUnlocked(projectDir, id, 'keep', { note, playedOn, commit: false });
1065
- if (!commit) return { milestone: name, ids: order, hash: null };
1066
- const files = changedIn(projectDir).map((c) => path.join(projectDir, c.file));
1067
- const message = `gcf(verdict): keep ${name} → ${order.join(', ')}${played}`;
1068
- const hash = commitPaths(projectDir, message, files, { key: 'verdict:keep', items: order });
1069
- for (const id of order) clearCard(projectDir, id);
1070
- const left = order.map((id) => releaseBuild(projectDir, id)).filter(Boolean);
1071
-
1072
- return { milestone: name, ids: order, hash, ...(left.length ? { build_left: left } : {}) };
1099
+ return await keepAll(projectDir, name, order, { note, playedOn, commit });
1073
1100
  } catch (e) {
1074
- // Nothing kept: what the keep wrote back to HEAD (staged or not); the pack's own files keep
1075
- // the operator's edits on disk and in the index as they were.
1076
- const mine = changedIn(projectDir)
1077
- .map((c) => c.file)
1078
- .filter((f) => !own.has(f));
1079
- if (mine.length) spawnSync('git', ['reset', '-q', '--', ...mine], { cwd: projectDir });
1080
- for (const c of changedIn(projectDir)) {
1081
- if (own.has(c.file)) continue;
1082
- if (c.untracked) rmSync(path.join(projectDir, c.file), { force: true });
1083
- else spawnSync('git', ['checkout', 'HEAD', '--', c.file], { cwd: projectDir });
1084
- }
1085
-
1086
- for (const [file, text] of saved) writeFileSync(file, text);
1087
- if (index) restoreIndex(index);
1101
+ undoKeep(projectDir, own, saved, index);
1088
1102
  throw new Error(`keep --milestone ${name}: nothing kept — ${e.message}`, { cause: e });
1089
1103
  }
1090
1104
  }
@@ -1377,14 +1391,14 @@ async function stallItemUnlocked(projectDir, id, { passes, reason = '', commit =
1377
1391
  */
1378
1392
  async function answerStallUnlocked(projectDir, id, { more, accept = false, commit = true }) {
1379
1393
  const move = accept ? 'plan_accept' : 'plan_more';
1380
- if (!accept && !(Number.isInteger(more) && more >= 1))
1394
+ if (!accept && !(more !== undefined && Number.isInteger(more) && more >= 1))
1381
1395
  throw new Error('more passes: a number, 1 or more');
1382
1396
  const m = await begin(projectDir, id, move);
1383
1397
  const stall = m.item.data.stall;
1384
1398
  if (!stall) throw new Error(`${id} is not stalled in planning: nothing to answer`);
1385
1399
  const answered = accept
1386
1400
  ? { ...stall, accepted: true }
1387
- : { ...stall, more: Number(stall.more ?? 0) + more };
1401
+ : { ...stall, more: Number(stall.more ?? 0) + /** @type {number} */ (more) };
1388
1402
  const data = {
1389
1403
  ...without(m.item.data, 'blocked'),
1390
1404
  status: 'ready',
@@ -1535,9 +1549,20 @@ function checkDepends(ledger, id, depends, { added = depends, parent = null } =
1535
1549
  }
1536
1550
  }
1537
1551
 
1552
+ /** The gate a new item of `type` gets, refused when it is none or its type forbids it. */
1553
+ function gateOfNew({ type, gate, severity }) {
1554
+ const g = gate ?? DEFAULT_GATE[type];
1555
+ if (!GATES.includes(g)) throw new Error(`gate must be ${GATES.join(' | ')}`);
1556
+ if (type === 'feature' && g !== 'auto') throw new Error('a feature always has gate auto');
1557
+ if (type === 'bug' && !SEVERITIES.includes(severity))
1558
+ throw new Error(`a bug needs --severity ${SEVERITIES.join('|')}`);
1559
+
1560
+ return g;
1561
+ }
1562
+
1538
1563
  /** Refuse a spec `item new` cannot honour; returns the gate the item gets. */
1539
1564
  function checkNew(ledger, spec) {
1540
- const { id, type, gate, severity } = spec;
1565
+ const { id, type } = spec;
1541
1566
  if (!isValidId(id)) throw new Error(`${id} is not a lowercase hyphen slug`);
1542
1567
  if (spec.parent && !isValidId(spec.parent))
1543
1568
  throw new Error(`--parent is one feature item, not ${spec.parent}`);
@@ -1545,11 +1570,7 @@ function checkNew(ledger, spec) {
1545
1570
  if (!ITEM_TYPES.includes(type)) throw new Error(`type must be ${ITEM_TYPES.join(' | ')}`);
1546
1571
  if (UNIT_ITEM_TYPES.includes(type))
1547
1572
  throw new Error(`a ${type} is a design unit: write it in gcf/design/, then gcf take ${id}`);
1548
- const g = gate ?? DEFAULT_GATE[type];
1549
- if (!GATES.includes(g)) throw new Error(`gate must be ${GATES.join(' | ')}`);
1550
- if (type === 'feature' && g !== 'auto') throw new Error('a feature always has gate auto');
1551
- if (type === 'bug' && !SEVERITIES.includes(severity))
1552
- throw new Error(`a bug needs --severity ${SEVERITIES.join('|')}`);
1573
+ const g = gateOfNew(spec);
1553
1574
  checkRelease(spec);
1554
1575
  checkDepends(ledger, id, spec.depends ?? [], { parent: spec.parent });
1555
1576
 
@@ -1789,9 +1810,13 @@ const SKIP_GATES = { skip: true, wait: false, project: undefined };
1789
1810
  * The operator's choice of an item's gates (docs/Autonomy-Plan.md, B): `skip` puts its verdict,
1790
1811
  * decision and question gates on their second value, `wait` holds them, `project` takes the
1791
1812
  * field off and the project's `gates:` hold. Commit `gcf(item)`, key `gates`.
1813
+ * @param {string} projectDir
1814
+ * @param {string} id
1815
+ * @param {{gates?: string, commit?: boolean}} [opts]
1792
1816
  */
1793
1817
  async function setGatesUnlocked(projectDir, id, { gates, commit = true } = {}) {
1794
- if (!(gates in SKIP_GATES)) throw new Error(`gates is ${Object.keys(SKIP_GATES).join(' | ')}`);
1818
+ if (gates === undefined || !(gates in SKIP_GATES))
1819
+ throw new Error(`gates is ${Object.keys(SKIP_GATES).join(' | ')}`);
1795
1820
  const ledger = await buildLedger(projectDir);
1796
1821
  const item = ledger.item(id);
1797
1822
  if (!item) throw new Error(`${id} is not a work item`);
@@ -1854,7 +1879,10 @@ function lstatOr(file) {
1854
1879
  }
1855
1880
  }
1856
1881
 
1857
- /** @type {typeof setGatesUnlocked} */
1882
+ /**
1883
+ * @type {typeof setGatesUnlocked}
1884
+ * @public gcf.js imports lib modules by name at run time, out of knip's sight.
1885
+ */
1858
1886
  export const setGates = (projectDir, id, opts = {}) =>
1859
1887
  locked(projectDir, opts.commit ?? true, () => setGatesUnlocked(projectDir, id, opts));
1860
1888
  /** @type {typeof attachItemUnlocked} */
@@ -1890,14 +1918,8 @@ async function titleForId(root, spec) {
1890
1918
  return title;
1891
1919
  }
1892
1920
 
1893
- async function newItemUnlocked(projectDir, given) {
1894
- const root = gcfOf(projectDir);
1895
- const ledger = await buildLedger(projectDir);
1896
- // The system's id, made under the lock that writes it: two moves never take one id.
1897
- const spec = given.id
1898
- ? given
1899
- : { ...given, id: deriveId(await titleForId(root, given), ledger.known, given.type) };
1900
- const gate = checkNew(ledger, spec);
1921
+ /** Refuse a new item's milestone that game.md does not list, or a feature without one. */
1922
+ async function checkNewMilestone(root, spec) {
1901
1923
  const feature = spec.type === 'feature';
1902
1924
  const milestones = spec.milestone || feature ? await gameMilestones(root) : null;
1903
1925
  if (spec.milestone && milestones && !milestones.some((m) => m.name === spec.milestone))
@@ -1911,9 +1933,10 @@ async function newItemUnlocked(projectDir, given) {
1911
1933
  `a feature is played with its milestone: --milestone ` +
1912
1934
  `<${milestones.map((m) => m.name).join(' | ')}>`,
1913
1935
  );
1914
- if (spec.proposal !== undefined && !/^[\w-]+\/[\w-]+$/.test(spec.proposal))
1915
- throw new Error(`--proposal is <thread>/<proposal id>, not ${spec.proposal}`);
1916
- if (spec.dryRun) return { id: spec.id, item: `gcf/work/${spec.id}.md`, hash: null };
1936
+ }
1937
+
1938
+ /** The new item's file, refused where the phase, its reopens, the file or its note forbid it. */
1939
+ async function checkNewWrite(projectDir, root, ledger, spec) {
1917
1940
  await refuseByPhase(projectDir, spec.type, spec.reopens);
1918
1941
  if (spec.reopens && !ledger.where(spec.reopens).terminal.length)
1919
1942
  throw new Error(`reopens names ${spec.reopens}, which has not ended`);
@@ -1921,6 +1944,23 @@ async function newItemUnlocked(projectDir, given) {
1921
1944
  if (existsSync(file)) throw new Error(`gcf/work/${spec.id}.md already exists`);
1922
1945
  if (spec.note !== undefined && spec.note.length > NOTE_MAX)
1923
1946
  throw new Error(`the note is ${spec.note.length} characters: up to ${NOTE_MAX}`);
1947
+
1948
+ return file;
1949
+ }
1950
+
1951
+ async function newItemUnlocked(projectDir, given) {
1952
+ const root = gcfOf(projectDir);
1953
+ const ledger = await buildLedger(projectDir);
1954
+ // The system's id, made under the lock that writes it: two moves never take one id.
1955
+ const spec = given.id
1956
+ ? given
1957
+ : { ...given, id: deriveId(await titleForId(root, given), ledger.known, given.type) };
1958
+ const gate = checkNew(ledger, spec);
1959
+ await checkNewMilestone(root, spec);
1960
+ if (spec.proposal !== undefined && !/^[\w-]+\/[\w-]+$/.test(spec.proposal))
1961
+ throw new Error(`--proposal is <thread>/<proposal id>, not ${spec.proposal}`);
1962
+ if (spec.dryRun) return { id: spec.id, item: `gcf/work/${spec.id}.md`, hash: null };
1963
+ const file = await checkNewWrite(projectDir, root, ledger, spec);
1924
1964
  const take = await takeEntry(projectDir, root, spec);
1925
1965
  // A note given goes over what the entry says: a board's form shows that text and sends it back,
1926
1966
  // and a human's edit of it is the note.
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.2",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -133,6 +133,9 @@ 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
138
+ - do not name or guess the rule that refused a call (`Edit(.claude/settings.json)` is a guess): you do not know it; name the refused call and point the human to that Allow button on the item's card
136
139
  - 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
140
  - do not reuse an ended id: rework gets a new id with `reopens: <old id>`
138
141
  - do not commit past the gate with `--no-verify`: a refused commit names what to fix