gcf-aif-ext 0.7.8 → 0.7.9

package/README.md

@@ -50,6 +50,11 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
 
 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.
 
+### 0.7.9
+
+- `gcf done`, `gcf drop` (a design unit), `gcf pillar rename|retire`, `gcf phase next` and `gcf question answer` hold the main lock from their first read to their commit, as the work item moves do. Before, two at once could both pass their checks and write over each other: an answer lost, a unit in the history twice.
+- `gcf claim` says the mark lives 2 hours without a gcf command, as it does (it said 30 minutes).
+
 ### 0.7.8
 
 - An open question's field written as a YAML block (`assumed: |` or `>`, and the lines under it) reads as its text: before, `gcf board --json` gave the block sign `|`. Every reader of `gcf/open-questions.md` (the board, `design check`, the audit, `context`, the index) reads the fields the same way:

package/commands/gcf.js

@@ -33,7 +33,7 @@ function registerSession(gcf) {
     .command('claim <id>')
     .description(
       'An agent session starts working the item on main: the board shows it running until a ' +
-        'move ends it, release, or 30 minutes without a gcf command on it',
+        'move ends it, release, or 2 hours without a gcf command on it',
     )
     .action(async (id) => {
       const { buildLedger } = await lib('ledger');
@@ -977,6 +977,10 @@ function registerBoard(gcf) {
         ].join('\n'),
       );
     });
+}
+
+/** The human's settings a board edits through the core: config keys and agent deny rules. */
+function registerSettings(gcf) {
   const config = gcf
     .command('config')
     .description("The human's settings of gcf/config.yml: list them, or set one (commit)")
@@ -1189,6 +1193,7 @@ export function register(program) {
   registerVerify(gcf);
   registerIntegrate(gcf);
   registerBoard(gcf);
+  registerSettings(gcf);
   registerPhase(gcf);
   registerHooksInstall(gcf);
   registerLint(gcf);

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/lib/agent-permissions.js

@@ -7,10 +7,12 @@
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import YAML from 'yaml';
 import { commitMove } from './unit-ops.js';
 import { atomicWrite } from './safe-path.js';
 import { gcfRoot } from './gcf-paths.js';
+import { configDoc, ensureMap } from './config-set.js';
+
+const GROUPS_SHAPE = 'gcf/config.yml: agent.groups must map a group id to true or false';
 
 // A shell command pattern turns into a rule for both shell tools: on Windows the agent runs
 // commands through PowerShell, which Bash rules do not cover.
@@ -75,7 +77,8 @@ export const DENY_GROUPS = [
   {
     id: 'human-moves',
     label:
-      "the human's GCF moves: verdict, decide, answer, unblock, phase, pillars, settings, permissions, setup",
+      "the human's GCF moves: verdict, decide, answer, unblock, phase, pillars, settings, " +
+      'permissions, setup',
     on: true,
     rules: shell(
       'ai-factory gcf verdict*',
@@ -159,12 +162,12 @@ function rules(agent, key) {
  */
 function choices(agent) {
   const g = agent.groups ?? {};
-  if (typeof g !== 'object' || Array.isArray(g))
-    throw new Error('gcf/config.yml: agent.groups must map a group id to true or false');
+  if (typeof g !== 'object' || Array.isArray(g)) throw new Error(GROUPS_SHAPE);
   for (const [id, on] of Object.entries(g))
     if (!known(id) || typeof on !== 'boolean')
       throw new Error(
-        `gcf/config.yml: agent.groups.${id} must be true or false, for one of ${GROUP_IDS.join(' | ')}`,
+        `gcf/config.yml: agent.groups.${id} must be true or false, ` +
+          `for one of ${GROUP_IDS.join(' | ')}`,
       );
 
   return g;
@@ -214,18 +217,9 @@ export async function setPermissions(projectDir, change, { commit = true } = {})
   const hash = await commitMove(projectDir, 'gcf(permissions): agent deny rules', {
     files: [file],
     mutate: async () => {
-      const doc = YAML.parseDocument(existsSync(file) ? await readFile(file, 'utf8') : '');
-      if (doc.errors.length) throw new Error(`gcf/config.yml: ${doc.errors[0].message}`);
-      if (!YAML.isMap(doc.contents)) doc.contents = doc.createNode({});
-      // A blank `agent:` (or one holding only comments) is no map yet.
-      const agent = doc.get('agent', true);
-      if (agent != null && !YAML.isMap(agent) && !(YAML.isScalar(agent) && agent.value == null))
-        throw new Error('gcf/config.yml: agent must be a mapping');
-      if (!YAML.isMap(agent)) doc.set('agent', doc.createNode({}));
-      const groups = doc.getIn(['agent', 'groups'], true);
-      if (groups != null && !YAML.isMap(groups) && !(YAML.isScalar(groups) && groups.value == null))
-        throw new Error('gcf/config.yml: agent.groups must map a group id to true or false');
-      if (!YAML.isMap(groups)) doc.setIn(['agent', 'groups'], doc.createNode({}));
+      const doc = configDoc(existsSync(file) ? await readFile(file, 'utf8') : '');
+      ensureMap(doc, ['agent'], 'gcf/config.yml: agent must be a mapping');
+      ensureMap(doc, ['agent', 'groups'], GROUPS_SHAPE);
       const current = agentOf({ agent: doc.toJS().agent });
       checkChange(change, current);
       for (const id of change.on ?? []) doc.setIn(['agent', 'groups', id], true);

package/lib/board.js

@@ -231,7 +231,7 @@ export async function board(projectDir) {
   return {
     schema: BOARD_SCHEMA,
     run_mode: config.run_mode,
-    // What the harness hands its agent runs (Harness-PRD §7): the deny rules and the context limits.
+    // What the harness hands its agent runs (Harness-PRD §7): deny rules and the context limits.
     agent: agentOf(config),
     // The human's settings of config.yml, each with its value and default (`gcf config set`).
     settings: settingsOf(await readRawConfig(root)),

package/lib/config-set.js

@@ -16,13 +16,31 @@ import { configOf, DEFAULT_CONFIG, gcfRoot, RUN_MODES } from './gcf-paths.js';
 // Thrown inside the move to leave without a write or a commit.
 const NO_CHANGE = new Error('no change');
 
+/** gcf/config.yml as a YAML document with a map on top: an edit keeps its comments. */
+export function configDoc(text) {
+  const doc = YAML.parseDocument(text);
+  if (doc.errors.length) throw new Error(`gcf/config.yml: ${doc.errors[0].message}`);
+  if (!YAML.isMap(doc.contents)) doc.contents = /** @type {any} */ (doc.createNode({}));
+
+  return doc;
+}
+
+/** Make `keys` a map. A blank key (`dod:` with nothing or only comments under it) is none yet. */
+export function ensureMap(doc, keys, error) {
+  const node = doc.getIn(keys, true);
+  if (YAML.isMap(node)) return;
+  if (node != null && !(YAML.isScalar(node) && node.value == null)) throw new Error(error);
+  doc.setIn(keys, doc.createNode({}));
+}
+
 /** @type {{ key: string, kind: Kind, label: string }[]} */
 export const SETTINGS = [
   {
     key: 'run_mode',
     kind: 'mode',
     label:
-      'how a run drives an item: worktree (several at once) or main (one at a time in the project folder)',
+      'how a run drives an item: worktree (several at once) or main (one at a time in the ' +
+      'project folder)',
   },
   { key: 'dod.test', kind: 'command', label: "the project's test command for the DoD, or none" },
   { key: 'dod.build', kind: 'command', label: "the project's build command for the DoD, or none" },
@@ -132,21 +150,9 @@ export async function setConfig(projectDir, key, text, { commit = true } = {}) {
     files: [file],
     mutate: async () => {
       const text = existsSync(file) ? await readFile(file, 'utf8') : '';
-      const doc = YAML.parseDocument(text);
-      if (doc.errors.length) throw new Error(`gcf/config.yml: ${doc.errors[0].message}`);
-      if (!YAML.isMap(doc.contents)) doc.contents = doc.createNode({});
-      // A blank parent (`dod:` with nothing under it) is no map yet.
-      if (keys.length > 1) {
-        const parent = doc.get(keys[0], true);
-        if (
-          parent != null &&
-          !YAML.isMap(parent) &&
-          !(YAML.isScalar(parent) && parent.value == null)
-        )
-          throw new Error(`gcf/config.yml: ${keys[0]} must map its keys`);
-        if (!YAML.isMap(parent)) doc.set(keys[0], doc.createNode({}));
-      }
-
+      const doc = configDoc(text);
+      if (keys.length > 1)
+        ensureMap(doc, [keys[0]], `gcf/config.yml: ${keys[0]} must map its keys`);
       if (value === null) doc.deleteIn(keys);
       else doc.setIn(keys, value);
       raw = doc.toJS();

package/lib/gcf-paths.js

@@ -68,6 +68,7 @@ export function configOf(parsed) {
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
     throw new Error('gcf/config.yml must be a key: value mapping');
   // A blank `key:` parses as null and means "not set", like an absent key.
+  /** @type {Record<string, any>} */
   const config = {
     ...DEFAULT_CONFIG,
     ...Object.fromEntries(Object.entries(parsed).filter(([, v]) => v !== null)),

package/lib/main-lock.js

@@ -140,3 +140,14 @@ export async function withMainLock(projectDir, fn, { waitMs = 60000 } = {}) {
     if (text.includes(token)) await unlink(file).catch(() => {});
   }
 }
+
+/**
+ * A committed move holds the main lock from its first read to its commit (Methodology §7): one
+ * that read the ledger before taking it would write over a move committed meanwhile.
+ * @template T
+ * @param {string} projectDir
+ * @param {boolean} commit
+ * @param {() => Promise<T>} move
+ */
+export const locked = (projectDir, commit, move) =>
+  commit ? withMainLock(projectDir, move) : move();

package/lib/phase.js

@@ -8,6 +8,7 @@ import { readLiveStrict, writeLive, liveFile } from './live.js';
 import { buildLedger } from './ledger.js';
 import { ITEM_TYPES } from './validate-item.js';
 import { commitMove } from './unit-ops.js';
+import { locked } from './main-lock.js';
 
 const ALL = ITEM_TYPES;
 const SOFT = ['mechanic', 'resource'];
@@ -206,8 +207,12 @@ export async function phaseStatus(projectDir) {
  * The operator moves the phase on, commit `gcf(phase): <from> → <to>`. An unmet criterion needs
  * `reason`, which the commit carries; the move itself is the operator's word on one that only
  * the operator can check.
+ * @type {typeof nextPhaseUnlocked}
  */
-export async function nextPhase(projectDir, { reason = '', commit = true } = {}) {
+export const nextPhase = (projectDir, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => nextPhaseUnlocked(projectDir, opts));
+
+async function nextPhaseUnlocked(projectDir, { reason = '', commit = true } = {}) {
   const status = await phaseStatus(projectDir);
   if (!status.next) throw new Error(`${status.phase} is the last phase`);
   const unmet = status.criteria.filter((c) => c.met === false);

package/lib/pillars.js

@@ -10,6 +10,7 @@ import { recordsIn } from './design-check.js';
 import { buildLedger } from './ledger.js';
 import { atomicWrite } from './safe-path.js';
 import { commitMove } from './unit-ops.js';
+import { locked } from './main-lock.js';
 
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
@@ -73,7 +74,7 @@ async function revise(projectDir, id, { edit, editPillars, tail, commit }) {
 }
 
 /** `pillar rename <from> <to>`: the id changes in PILLARS.md and every unit and item citing it. */
-export async function renamePillar(projectDir, from, to, { commit = true } = {}) {
+async function renamePillarUnlocked(projectDir, from, to, { commit = true } = {}) {
   if (!SLUG_RE.test(to)) throw new Error(`${to}: a pillar id is a lowercase hyphen slug`);
   const text = await readFile(path.join(projectDir, 'gcf', 'PILLARS.md'), 'utf8').catch(() => '');
   if (recordsIn(text, 'pillars').some((p) => p.id === to))
@@ -92,7 +93,7 @@ export async function renamePillar(projectDir, from, to, { commit = true } = {})
  * unit left citing no pillar reads `pillars: TBD` again — it is not ready until the human gives
  * it one, or decides it is out of scope. The reason is kept in the commit.
  */
-export async function retirePillar(projectDir, id, { reason, commit = true }) {
+async function retirePillarUnlocked(projectDir, id, { reason, commit = true }) {
   const why = String(reason ?? '')
     .replace(/\s+/g, ' ')
     .trim();
@@ -111,3 +112,11 @@ export async function retirePillar(projectDir, id, { reason, commit = true }) {
     commit,
   });
 }
+
+// PILLARS.md and the citing files are read for the edit: the lock holds from that read on.
+/** @type {typeof renamePillarUnlocked} */
+export const renamePillar = (projectDir, from, to, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => renamePillarUnlocked(projectDir, from, to, opts));
+/** @type {typeof retirePillarUnlocked} */
+export const retirePillar = (projectDir, id, opts) =>
+  locked(projectDir, opts.commit ?? true, () => retirePillarUnlocked(projectDir, id, opts));

package/lib/question-fields.js

@@ -26,6 +26,7 @@ const BLOCK = /^([|>])[-+]?\d?[-+]?(\s+#.*)?$/;
  */
 function folded(lines) {
   let text = '';
+  /** @type {'text' | 'more' | null} */
   let prev = null;
   let blanks = 0;
   for (const l of lines) {

package/lib/questions.js

@@ -7,6 +7,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { atomicWrite } from './safe-path.js';
 import { commitMove } from './unit-ops.js';
+import { locked } from './main-lock.js';
 import { blockEnd, fieldOf, indentOf } from './question-fields.js';
 
 // A D2 carries its assumption and the trigger that brings it back; `lens`, `sections` and `sys`
@@ -93,8 +94,12 @@ function withAnswer(record, answer) {
 /**
  * The human answers question `qid` (`gcf question answer`): the answer goes into its record, one
  * line, and commits as `gcf(answer): <qid>`. Refuses an id the file does not hold.
+ * @type {typeof answerUnlocked}
  */
-export async function answerQuestion(projectDir, qid, answer, { commit = true } = {}) {
+export const answerQuestion = (projectDir, qid, answer, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => answerUnlocked(projectDir, qid, answer, opts));
+
+async function answerUnlocked(projectDir, qid, answer, { commit = true } = {}) {
   const text = String(answer ?? '')
     .replace(/\s+/g, ' ')
     .trim();

package/lib/unit-ops.js

@@ -16,7 +16,7 @@ import { upsertBlock, openSystemDoc } from './systems-doc.js';
 import { buryLine, recordLine } from './verdict-fs.js';
 import { DEFAULT_GATE } from './validate-item.js';
 import { refuseByPhase } from './phase.js';
-import { withMainLock } from './main-lock.js';
+import { locked, withMainLock } from './main-lock.js';
 
 /** A design file's text without the `## <id>` section. */
 export function removeUnit(text, id) {
@@ -265,8 +265,12 @@ async function record(projectDir, message, { files, mutate, commit, inputs = []
 /**
  * A hard unit is built and its tests are green: it leaves design/ without a work item. A line
  * every future reader of the subsystem must remember goes to the systems doc's `constraints:`.
+ * @type {typeof doneUnitUnlocked}
  */
-export async function doneUnit(projectDir, id, { constraints = [], commit = true } = {}) {
+export const doneUnit = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => doneUnitUnlocked(projectDir, id, opts));
+
+async function doneUnitUnlocked(projectDir, id, { constraints = [], commit = true } = {}) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const unit = await designUnit(projectDir, id);
   if (CARD_TYPES.includes(unit.header.type))
@@ -300,8 +304,14 @@ export async function addConstraints(doc, id, constraints) {
   await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: id }, body));
 }
 
-/** A unit is dropped before any work: a graveyard line keeps the reason (Methodology §9). */
-export async function dropUnit(projectDir, id, { reason, tags = [], commit = true }) {
+/**
+ * A unit is dropped before any work: a graveyard line keeps the reason (Methodology §9).
+ * @type {typeof dropUnitUnlocked}
+ */
+export const dropUnit = (projectDir, id, opts) =>
+  locked(projectDir, opts.commit ?? true, () => dropUnitUnlocked(projectDir, id, opts));
+
+async function dropUnitUnlocked(projectDir, id, { reason, tags = [], commit = true }) {
   if (!String(reason ?? '').trim())
     throw new Error('a drop needs a reason: the graveyard keeps it');
   const root = path.join(path.resolve(projectDir), 'gcf');

package/lib/verify.js

@@ -20,7 +20,8 @@ export function runDod(projectDir, config, key, stdio) {
       ok: false,
       problems: [`dod.${key} is not set in gcf/config.yml — the project's command, or none`],
     };
-  // shortcut: no timeout, a command that waits for input hangs the run; add one when it bites.
+  // shortcut: no timeout; stdin is closed, but a command that never ends (a watch mode, a
+  // server) hangs `gcf verify`, and a harness run until its own timeout; add one when it bites.
   const res = spawnSync(cmd, { cwd: projectDir, shell: true, stdio });
   const ok = res.status === 0;
   const why = res.error ? res.error.message : `exit ${res.status ?? res.signal}`;

package/lib/work-ops.js

@@ -37,7 +37,7 @@ import {
 } from './live.js';
 import { dropInbox } from './inbox.js';
 import { refuseByPhase } from './phase.js';
-import { runHolder, withMainLock } from './main-lock.js';
+import { locked, runHolder } from './main-lock.js';
 import { dropAgentSession, releaseSession, sessionActive } from './session-mark.js';
 
 /**
@@ -954,16 +954,6 @@ async function newItemUnlocked(projectDir, spec) {
   return { item: `gcf/work/${spec.id}.md`, hash };
 }
 
-/**
- * A committed move holds the main lock from its first read to its commit (Methodology §7): one
- * that read the ledger before taking it would write over a move committed meanwhile.
- * @template T
- * @param {string} projectDir
- * @param {boolean} commit
- * @param {() => Promise<T>} move
- */
-const locked = (projectDir, commit, move) => (commit ? withMainLock(projectDir, move) : move());
-
 /** @type {typeof submitItemUnlocked} */
 export const submitItem = (projectDir, id, opts = {}) =>
   locked(projectDir, opts.commit ?? true, () => submitItemUnlocked(projectDir, id, opts));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",