gcf-harness-aif-ext 0.5.1 → 0.6.1

package/README.md

@@ -11,7 +11,7 @@ The harness turns policy-as-text into an executable pipeline. It has **no memory
 
 ## Requirements
 
-- [`gcf-aif-ext`](../gcf-aif-ext) `^0.4.1` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
+- [`gcf-aif-ext`](../gcf-aif-ext) `^0.5.3` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
 - Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
 - AI Factory 2.x, Node.js ≥ 22.14
 
@@ -47,6 +47,10 @@ Updating keeps the hook entry valid — it points into the extension's install d
 
 0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
 
+0.6.1 is a fix release, to update together with core 0.5.3. The run lock `.gcf-session/runs/<id>.lock` is created exclusively, and a lock left by a dead run is taken over; while it is live, the gate refuses the item to another run and the core refuses any move on it, `/gcf-run` on main included. A session whose log cannot open ends as an error and releases its claim.
+
+0.6.0 adds `ai-factory gcf-harness run` (a batch at once, a worktree and an agent session per item, then the integrator) and the `--worktree` mode of `/gcf-run`, whose session ritual now integrates the verified branches a dead run left. It requires `gcf-aif-ext` 0.5.0 (`gcf worktree`, `gcf integrate`, `gcf verify`) — update both together and run `ai-factory gcf init`. The DoD of `/gcf-run` is `ai-factory gcf verify <id>`, and the item's `live:` delta is written before it.
+
 0.4.1 is a patch release. `/gcf-run` now commits the implementation first, then flips the card to `built` in a second commit, with `built_at` set to the implementation commit's hash. Update the core to 0.3.1 together with the harness: without it, an audit run before a verdict makes the pre-commit gate refuse that verdict.
 
 To remove the extension:
@@ -59,10 +63,12 @@ Removal does not touch `.claude/settings.json`: delete the `PreToolUse` entry wh
 
 ## What it adds
 
-**`/gcf-run <item-id…>`** — drives work items through plan, implementation and DoD, with every gate checked *before* the tokens are spent: the audit ritual, the gate below, the context budget. The plan is written by `aif-plan`, then improved in passes, each by a fresh subagent that reads only the plan and the readset and records every default it picks; `ai-factory gcf plan check <id>` runs after each pass, and a pass that changes no task ends the loop. A plan still changing after `plan_passes` passes, or a question only the human can answer (a save format, a public API, a new dependency, a pillar conflict), blocks the item before any code is written. The DoD is the project's `dod.test` and `dod.build` commands from `gcf/config.yml` plus a review by a fresh subagent, up to `dod_attempts` attempts. Every item ends in a state the core records: `gcf submit` (gate `verdict` or `decision` — waits for the human), `gcf close` (gate `auto` — done, or a soft unit closed as `unplayed`) or `gcf block` with the reason. The verdict and the decision belong to the human: the pipeline stops at `submit` and prints the playtest list.
+**`/gcf-run <item-id…>`** — drives work items through plan, implementation and DoD, with every gate checked *before* the tokens are spent: the audit ritual, the gate below, the context budget. The plan is written by `aif-plan`, then improved in passes, each by a fresh subagent that reads only the plan and the readset and records every default it picks; `ai-factory gcf plan check <id>` runs after each pass, and a pass that changes no task ends the loop. A plan still changing after `plan_passes` passes, or a question only the human can answer (a save format, a public API, a new dependency, a pillar conflict), blocks the item before any code is written. The DoD is `ai-factory gcf verify <id>` — the gate's checks, the item's `live:` delta, and the project's `dod.build` and `dod.test` commands from `gcf/config.yml` — plus a review by a fresh subagent, up to `dod_attempts` attempts. Every item ends in a state the core records: `gcf submit` (gate `verdict` or `decision` — waits for the human), `gcf close` (gate `auto` — done, or a soft unit closed as `unplayed`) or `gcf block` with the reason. The verdict and the decision belong to the human: the pipeline stops at `submit` and prints the playtest list.
 
 **`ai-factory gcf-harness gate <item-id…>`** — the `/gcf-run` gate as code. It reads one `gcf audit --json` report and exits 1 with a one-line reason when the items may not go: a core older than 0.4.0, a `schema:` other than 1 in `gcf/config.yml`, an id with no work item, a feature (run its children; the feature closes when they are finished), an item that is not `ready`, an unplayed dependency, no WIP room for the batch (items awaiting a verdict + the batch's `gate: verdict` items over `wip_built_limit`), or two items of the batch touching the same system unless both say `parallel: ok`. The tune limit is not a gate rule: `verdict tune` itself refuses at the limit, and an item tuned up to it still gets its last build. The skill runs it and stops on a non-zero exit — no model compares the numbers.
 
+**`ai-factory gcf-harness run <item-id…> [--agent "<cmd>"]`** — runs a batch at once, each item in its own worktree (`gcf worktree <id>`) with its own agent session: `claude -p "/gcf-run <id> --worktree"` by default, or the command in `--agent` / `GCF_RUN_AGENT`. The sessions run unattended, so set the agent's permissions for print mode first. A session ends with a commit and `gcf verify <id> --mark` (the `GCF-Verified` trailer); a question for the human goes into `.gcf-session/outcome.json` in its worktree, and `run` records the block on main. Then `gcf integrate` merges the verified branches and records each move, and `run` prints the playtest session. Its first step, like `/gcf-run`'s, integrates the verified branches a dead run left. A session that ended with no result leaves its item `ready`; the next `run` resumes its worktree. Logs: `.gcf-session/runs/<id>.log`. One run drives an item at a time (`.gcf-session/runs/<id>.lock`), and a resumed worktree first gets main merged in, so the answer from an `unblock` reaches the session. A worktree sees only what is committed: keep `.ai-factory.json`, the installed extensions and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`.
+
 **`/gcf-run-ingest <gdd.md>`** — imports a design document as a fan-out workflow: parallel aspect extraction, provenance verified by code rather than by an agent (a quote either is a verbatim substring of its section or it is not), completeness lenses per candidate, and an interaction matrix computed from the candidates that write the same state.
 
 **readset-guard** — a `PreToolUse` hook on Read/Grep/Glob. While a run manifest exists at `.gcf-session/readset.json`, a path inside `gcf/` that is not in the readset is denied, and so is a Grep from the project root (no `path`, or a `path` above `gcf/`) unless its `glob` starts with a literal directory other than `gcf` (`src/**`, not `**/*.md`), because such a content search would read the whole tree past the gate. Glob and Greps scoped to the game code are never restricted. No manifest means no restriction: manual work is never gated. An honest limit — `cat` through Bash still bypasses it. This is a discipline tool, not a security perimeter.

package/commands/harness.js

@@ -7,6 +7,7 @@ import { existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { run, cliCore, DEFAULT_AGENT } from './run.js';
 
 const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const MARKER = 'gcf-readset-guard';
@@ -26,6 +27,8 @@ function itemProblem(id, item, report) {
     return `${id} is ${item.status} — only ready items are driven`;
   }
 
+  if (item.running) return `${id} is driven by another harness run — wait until it ends`;
+
   // A child of a feature paused after a death does not start: the decision may kill it.
   const parent = item.parent ? report.items.find((p) => p.id === item.parent) : null;
   if (parent?.status === 'awaiting-decision') {
@@ -237,4 +240,49 @@ export function register(program) {
     .description('Gate work items before the paid stages of /gcf-run: exit 1 with the reason')
     .option('--json', 'machine output: {pass, reason}')
     .action(runGate);
+
+  harness
+    .command('run <ids...>')
+    .description('Run items at once, each in its worktree with its own agent, then integrate')
+    .option(
+      '--agent <command>',
+      'the agent command; it gets "/gcf-run <id> --worktree"',
+      process.env.GCF_RUN_AGENT ?? DEFAULT_AGENT,
+    )
+    .option('--json', 'machine output')
+    .action(runItems);
+}
+
+/** The run report a human reads, then the playtest sheet of what now waits for play. */
+function printRun(r) {
+  for (const o of r.orphans)
+    console.log(`orphan ${o.id}: ${o.move ?? o.conflict ?? o.error ?? o.skipped}`);
+  if (r.gate) console.error(`gcf gate: ${r.gate}`);
+  for (const i of r.items) {
+    const why = i.reason ?? i.conflict ?? i.error ?? i.skipped;
+    console.log(`${i.id}: ${i.result}${why ? ` — ${why}` : ''}`);
+  }
+
+  if (!r.gate) console.log(`\n${cliCore(process.cwd())(['playtest', 'session']).out.trim()}`);
+}
+
+const failed = (r) =>
+  Boolean(r.gate) ||
+  r.items.some((i) => ['conflict', 'error'].includes(i.result)) ||
+  r.orphans.some((o) => o.conflict || o.error);
+
+async function runItems(ids, opts) {
+  try {
+    const r = await run(process.cwd(), [...new Set(ids)], {
+      agent: opts.agent,
+      gate: (batch) => gate(auditReport(), batch),
+    });
+    if (opts.json) console.log(JSON.stringify(r, null, 2));
+    else printRun(r);
+    if (failed(r)) process.exitCode = 1;
+  } catch (e) {
+    // A refusal of the core (main not clean, no core) ends the run with its one line.
+    console.error(`gcf-harness run: ${e.message}`);
+    process.exitCode = 1;
+  }
 }

package/commands/run.js

@@ -0,0 +1,241 @@
+// `ai-factory gcf-harness run <ids…>` (Methodology §7): every item runs in its own worktree with
+// its own agent session, all at once; the integrator ends the run. The first step picks up the
+// verified branches a dead run left; an agent that needs the human leaves `outcome.json` in its
+// worktree, and the block is recorded on main — a worktree never writes gcf/ status.
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEFAULT_AGENT = 'claude -p';
+
+/** The core CLI: the same ai-factory that runs this command, in the project. */
+export function cliCore(projectDir) {
+  return (args) => {
+    const res = spawnSync(process.execPath, [process.argv[1], 'gcf', ...args], {
+      cwd: projectDir,
+      encoding: 'utf8',
+    });
+
+    return { ok: res.status === 0, out: res.stdout ?? '', err: res.stderr ?? '' };
+  };
+}
+
+function json(res, what) {
+  try {
+    return JSON.parse(res.out);
+  } catch (e) {
+    throw new Error(`ai-factory gcf ${what} gave no report: ${(res.err || res.out).trim()}`, {
+      cause: e,
+    });
+  }
+}
+
+/** One agent session in the item's worktree; resolves with its exit code. */
+function startAgent(agent, id, dir, fd) {
+  return new Promise((resolve) => {
+    const child = spawn(`${agent} "/gcf-run ${id} --worktree"`, {
+      cwd: dir,
+      shell: true,
+      stdio: ['ignore', fd, fd],
+    });
+    child.on('error', () => resolve(-1));
+    child.on('exit', (code) => resolve(code ?? -1));
+  });
+}
+
+/** What the agent left for the main checkout: `{block: <reason>}`, or null. */
+async function outcomeOf(dir) {
+  const file = path.join(dir, '.gcf-session', 'outcome.json');
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch {
+    return { block: `the run left an unreadable ${file}` };
+  } finally {
+    await rm(file, { force: true });
+  }
+}
+
+/** Whether a pid is a live process; EPERM is alive under another user. */
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+/**
+ * One harness run per item at a time: `.gcf-session/runs/<id>.lock` holds the pid of the run
+ * that drives it, created exclusively. A lock whose process is gone is taken over; the core
+ * refuses moves on the item while the lock is live. Returns the release, or null.
+ */
+async function claim(logs, id) {
+  const file = path.join(logs, `${id}.lock`);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    if (await create(file)) return () => rm(file, { force: true });
+    const text = await readFile(file, 'utf8').catch(() => null);
+    if (text === null) continue; // released meanwhile
+    const pid = Number(text.trim());
+    if (pid === process.pid) return () => rm(file, { force: true });
+    if (!(await dead(file, pid))) return null;
+    await clearDead(file, text);
+  }
+
+  return null;
+}
+
+/** Create the lock with this pid, or false when it exists. */
+async function create(file) {
+  try {
+    await writeFile(file, `${process.pid}\n`, { flag: 'wx' });
+
+    return true;
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+
+    return false;
+  }
+}
+
+/** A lock whose pid is gone, or that never got one and is old: its creator died writing it. */
+async function dead(file, pid) {
+  if (Number.isInteger(pid) && pid > 0) return !alive(pid);
+  const age = await stat(file).then(
+    (s) => Date.now() - s.mtimeMs,
+    () => 0,
+  );
+
+  return age > 10000;
+}
+
+/**
+ * Remove a dead lock under `<lock>.break`, as the core's main lock does: two runs that judged
+ * the same lock dead cannot both remove it, so neither deletes the other's fresh lock.
+ */
+async function clearDead(file, text) {
+  const breaker = `${file}.break`;
+  if (!(await create(breaker))) return;
+  try {
+    if ((await readFile(file, 'utf8').catch(() => null)) === text) await rm(file, { force: true });
+  } finally {
+    await rm(breaker, { force: true });
+  }
+}
+
+/** Whether the tip of the worktree's branch carries `GCF-Verified: <id>`. */
+function verified(dir, id) {
+  const res = spawnSync('git', ['log', '-1', '--format=%(trailers:key=GCF-Verified,valueonly)'], {
+    cwd: dir,
+    encoding: 'utf8',
+  });
+
+  return (res.stdout ?? '').split('\n').some((v) => v.trim() === id);
+}
+
+/** The worktree of each item, claimed for this run; an item that cannot start is an error. */
+async function prepare(ids, core, logs) {
+  const ready = [];
+  const failed = [];
+  for (const id of ids) {
+    const release = await claim(logs, id);
+    if (!release) {
+      failed.push({ id, result: 'error', error: `${id} is already running in another run` });
+      continue;
+    }
+
+    try {
+      const wt = json(await core(['worktree', id, '--json']), `worktree ${id}`);
+      if (wt.sync) throw new Error(wt.sync);
+      ready.push({ id, dir: wt.path, release });
+    } catch (e) {
+      await release();
+      failed.push({ id, result: 'error', error: e.message });
+    }
+  }
+
+  return { ready, failed };
+}
+
+/** One session per item, its output in `.gcf-session/runs/<id>.log`. */
+async function session(r, agent, logs) {
+  let log = null;
+  try {
+    log = await open(path.join(logs, `${r.id}.log`), 'a');
+
+    return { ...r, code: await startAgent(agent, r.id, r.dir, log.fd) };
+  } catch (e) {
+    return { ...r, code: null, error: e.message };
+  } finally {
+    await log?.close();
+    await r.release();
+  }
+}
+
+/**
+ * A run that asked to block is recorded on main. Asked after its branch was verified, the
+ * block wins: an empty commit takes the trailer off the tip, so no integrate merges it.
+ */
+async function recordBlock(r, outcome, core) {
+  const reason = String(outcome.block);
+  if (verified(r.dir, r.id))
+    spawnSync('git', ['commit', '--allow-empty', '-m', `gcf(unverified): ${r.id}`], { cwd: r.dir });
+  const b = await core(['block', r.id, '--reason', reason]);
+
+  return {
+    id: r.id,
+    result: b.ok ? 'block' : 'error',
+    reason,
+    ...(b.ok ? {} : { error: (b.err || b.out).trim() }),
+  };
+}
+
+/** The result line of an item the integrator handled, or why it has none. */
+function resultOf(run, integrated) {
+  const done = integrated.find((x) => x.id === run.id);
+  if (!done && run.error) return { id: run.id, result: 'error', error: run.error };
+  if (!done)
+    return {
+      id: run.id,
+      result:
+        `no result (agent exit ${run.code}): ${run.id} stays ready, a rerun resumes its ` +
+        'worktree',
+    };
+
+  return {
+    ...done,
+    result: done.move ?? (done.conflict ? 'conflict' : done.error ? 'error' : 'skipped'),
+  };
+}
+
+/**
+ * Pick up orphans, gate the batch, run every item in its worktree at once, record each block
+ * on main, integrate the verified branches. `gate(ids)` answers `{pass, reason}`.
+ */
+export async function run(
+  projectDir,
+  ids,
+  { core = cliCore(projectDir), agent = DEFAULT_AGENT, gate },
+) {
+  const orphans = json(await core(['integrate', '--json']), 'integrate');
+  const passed = gate(ids);
+  if (!passed.pass) return { orphans, gate: passed.reason, items: [] };
+
+  const logs = path.join(path.resolve(projectDir), '.gcf-session', 'runs');
+  await mkdir(logs, { recursive: true });
+  const { ready, failed } = await prepare(ids, core, logs);
+  const runs = await Promise.all(ready.map((r) => session(r, agent, logs)));
+  const items = [...failed];
+  for (const r of runs) {
+    const outcome = await outcomeOf(r.dir);
+    if (outcome?.block) items.push(await recordBlock(r, outcome, core));
+  }
+
+  const integrated = json(await core(['integrate', '--json']), 'integrate');
+  for (const r of runs) if (!items.some((i) => i.id === r.id)) items.push(resultOf(r, integrated));
+
+  return { orphans, items };
+}

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-harness-aif-ext",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-harness-aif-ext",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "prepack": "node -e \"const p=require('./package.json'),e=require('./extension.json');if(p.version!==e.version)throw new Error('version mismatch: package.json '+p.version+' vs extension.json '+e.version)\""
   },
   "peerDependencies": {
-    "gcf-aif-ext": "^0.4.1"
+    "gcf-aif-ext": "^0.5.3"
   },
   "files": [
     "extension.json",

package/skills/gcf-run/SKILL.md

@@ -11,6 +11,7 @@ purpose:
 
 inputs:
 - 1 or more work item or design unit ids; a batch shares one build and one playtest list
+- `--worktree` when `ai-factory gcf-harness run` started this session inside the item's worktree
 
 preconditions:
 - `gcf/` exists and `ai-factory gcf audit` runs (the gcf-aif-ext extension provides it)
@@ -24,7 +25,7 @@ forbidden_behaviors:
 - do not edit `status:` or `gcf/LIVE.md` by hand: `submit`, `close` and `block` own them
 
 workflow:
-1. session ritual: delete a `.gcf-session/readset.json` left by a killed run; run `ai-factory gcf audit --json`; read `gcf/INDEX.md`; report the audit first line to the human
+1. session ritual: delete a `.gcf-session/readset.json` left by a killed run; run `ai-factory gcf integrate` to merge the verified branches a dead run left; run `ai-factory gcf audit --json`; read `gcf/INDEX.md`; report the audit first line
 2. for a unit still in `gcf/design/`: take it with the gcf-card skill first
 3. for a feature id: replace it with its `ready` children from the audit report's `items` (`parent` names the feature) that are not in `open_depends`; a feature in `awaiting-decision` starts none of them
 4. of those children, keep one per subsystem unless every child sharing it says `parallel: ok`; the rest wait for the next run; an empty list: report "nothing to run" and stop
@@ -36,14 +37,18 @@ workflow:
 10. after each pass run `ai-factory gcf plan check <id>`; a failure blocks the item with its reason; a pass that changes no task ends the loop - the plan converged
 11. passes <= `plan_passes` from `gcf/config.yml` (5 by default); a plan still changing after the last pass: run `ai-factory gcf block <id> --reason "plan did not converge"` and stop
 12. a question only the human can answer - a save format, a public API, a new dependency, a pillar conflict: run `ai-factory gcf block <id> --reason "<question>"` and stop
-13. implement with aif-implement, then verify: the project's `dod.test` and `dod.build` commands from `gcf/config.yml`, plus the item's negative constraints; attempts <= `dod_attempts`, each with a diagnosis
-14. review the diff with a fresh subagent; fix what it finds before the commit; DoD still red after the attempts: commit nothing, run `ai-factory gcf block <id> --reason "<diagnosis>"`
+13. implement with aif-implement, write the item's `live:` delta, then run `ai-factory gcf verify <id>` and check the item's negative constraints; a non-zero exit is a red DoD; attempts <= `dod_attempts`, each with a diagnosis
+14. review the diff with a fresh subagent; fix what it finds before the commit; DoD still red after the attempts: commit no code, run `ai-factory gcf block <id> --reason "<diagnosis>"` - its commit carries the item file with its delta
 15. the reviewer also answers the `review_question` of each pillar in `gcf/PILLARS.md` over the diff: an answer that breaks the pillar is a finding
-16. commit the implementation via aif-commit; write the item's `live:` delta
+16. commit the implementation and the `live:` delta via aif-commit
 17. gate `verdict` or `decision`: run `ai-factory gcf submit <id>`; gate `auto`: run `ai-factory gcf close <id>` - a soft unit closes unplayed
 18. a dependency still waiting for its verdict refuses the close: run `ai-factory gcf block <id> --reason "waits for <dep>"`
-19. close the run: delete `.gcf-session/readset.json`, run `ai-factory gcf playtest` and hand the list to the human, with one report row per plan pass: pass, tasks changed, result
+19. close the run: delete `.gcf-session/readset.json`, run `ai-factory gcf playtest session` and hand its checklist to the human, with one report row per plan pass: pass, tasks changed, result
 20. after a tune verdict or an unblock, re-enter this pipeline at step 5: the gates re-run because the counters moved
+21. with `--worktree`: skip the integrate of step 1, steps 2-4 and the playtest of step 19, and change no `gcf/` file but the item's `live:`
+22. with `--worktree`, every stop - a failed gate, an over budget readset, a failed plan check, steps 11, 12, 14, 18 - writes `{"block": "<reason>"}` to `.gcf-session/outcome.json` and ends the session
+23. with `--worktree`, run no `ai-factory gcf block`, `submit` or `close`: the core refuses them on a `work/` branch, and the harness records the move on main
+24. with `--worktree`, step 17 is: commit everything but `gcf/.metrics`, then run `ai-factory gcf verify <id> --mark`; the harness merges the branch
 
 invocation:
 - run when the user names a work item or a unit to drive; batches share steps 1 and 19