gcf-harness-aif-ext 0.5.0 → 0.6.0

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.0` 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.0` 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
 
@@ -45,6 +45,10 @@ Updating keeps the hook entry valid — it points into the extension's install d
 
 0.5.0 drives work items (`gcf/work/<id>.md`, schema 3) instead of cards and requires `gcf-aif-ext` 0.4.0 — update both together; against an older core the gate refuses with `gcf-aif-ext >= 0.4.0 is required`. A project still holding schema 2 cards in `gcf/cards/` re-creates them first (see the core's "Upgrading from 0.3.x"). What changes for you: `/gcf-run` takes ids of items in `ready`; it no longer stops at `built` but ends each item with `submit`, `close` or `block`; the plan is improved in passes until it converges; the WIP cap counts only items that end waiting for a verdict.
 
+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.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:
@@ -57,10 +61,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';
@@ -237,4 +238,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,186 @@
+// `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, 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 });
+  }
+}
+
+/**
+ * One harness run per item at a time: `.gcf-session/runs/<id>.lock` holds the pid of the run
+ * that drives it. A lock whose process is gone is taken over. Returns the release, or null.
+ */
+async function claim(logs, id) {
+  const file = path.join(logs, `${id}.lock`);
+  try {
+    const pid = Number((await readFile(file, 'utf8')).trim());
+    process.kill(pid, 0);
+    if (pid !== process.pid) return null;
+  } catch {
+    // no lock, or its process is gone
+  }
+
+  await writeFile(file, `${process.pid}\n`);
+
+  return () => rm(file, { 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) {
+  const log = await open(path.join(logs, `${r.id}.log`), 'a');
+  try {
+    return { ...r, code: await startAgent(agent, r.id, r.dir, log.fd) };
+  } 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)
+    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.0",
+  "version": "0.6.0",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/hooks/readset-guard.js

@@ -49,22 +49,32 @@ function outsideVerdict(input, abs, gcfRoot) {
   return { allow: false, reason: UNSCOPED_GREP };
 }
 
-/** The paths a manifest allows, plus the two every stage may always read. */
-function allowedPaths(manifest) {
+/**
+ * The files a manifest allows, plus the two every stage may always read: the index, and the
+ * config whose DoD commands and limits the run reads at its plan and DoD steps.
+ */
+function allowedFiles(manifest) {
   // `gcf context --json` emits files as {path, tokens_est}; accept that shape as well as
   // the projected string list, so a manifest written either way still gates correctly.
   const files = (manifest.files ?? []).map((f) => (typeof f === 'string' ? f : f?.path));
 
-  return new Set([...files.filter(Boolean), 'gcf/INDEX.md', 'gcf']);
+  return new Set([...files.filter(Boolean), 'gcf/INDEX.md', 'gcf/config.yml']);
 }
 
-/** A path inside gcf/ passes only through the readset. */
-function insideVerdict(rel, manifest) {
-  const allowed = allowedPaths(manifest);
+/**
+ * A path inside gcf/ passes only through the readset. A Grep reads every file under a
+ * directory, so it gets exact files only; Glob and Read may name a directory holding one.
+ */
+function insideVerdict(rel, manifest, tool) {
+  const allowed = allowedFiles(manifest);
   if (allowed.has(rel)) return { allow: true };
-  // ponytail: a directory path passes when any allowed file lives under it, so Grep over
-  // gcf/systems can still see sibling files' content; per-file grep scoping if it leaks.
-  if ([...allowed].some((f) => f.startsWith(`${rel}/`))) return { allow: true };
+  const holds = [...allowed].some((f) => f.startsWith(`${rel}/`));
+  if (holds && tool !== 'Grep') return { allow: true };
+  if (holds)
+    return {
+      allow: false,
+      reason: `a Grep over ${rel} reads files outside the readset — Grep a readset file by path.`,
+    };
 
   return {
     allow: false,
@@ -94,7 +104,7 @@ export function decide(input, projectDir, manifest) {
   // The gcf root itself relativizes to '' — unguarded it becomes 'gcf/' and matches nothing.
   const relPosix = relFromGcf.replaceAll('\\', '/');
 
-  return insideVerdict(relPosix ? `gcf/${relPosix}` : 'gcf', manifest);
+  return insideVerdict(relPosix ? `gcf/${relPosix}` : 'gcf', manifest, input.tool_name);
 }
 
 function readManifest(projectDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-harness-aif-ext",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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.0"
+    "gcf-aif-ext": "^0.5.0"
   },
   "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
@@ -32,16 +33,22 @@ workflow:
 6. readset: run `ai-factory gcf context <item-id> --json`; write `{"item":"<id>","files": ctx.files.map(f => f.path)}` to `.gcf-session/readset.json` - paths, not objects; `over_budget: true` stops the run with a D1 question naming the subsystem
 7. plan: run aif-plan full for the item into its `plan:` path, by default `.ai-factory/plans/<id>.md`, reading only the readset files; an existing plan (the item came back after a tune, an unblock or a continue) is kept, not rewritten
 8. improve the plan in passes, each pass a fresh subagent that reads only the plan and the readset and applies aif-improve without questions, writing each default it picks into the plan
-9. 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
-10. 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
-11. 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
-12. 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
-13. 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>"`
-14. commit the implementation via aif-commit; write the item's `live:` delta
-15. gate `verdict` or `decision`: run `ai-factory gcf submit <id>`; gate `auto`: run `ai-factory gcf close <id>` - a soft unit closes unplayed
-16. a dependency still waiting for its verdict refuses the close: run `ai-factory gcf block <id> --reason "waits for <dep>"`
-17. 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
-18. after a tune verdict or an unblock, re-enter this pipeline at step 5: the gates re-run because the counters moved
+9. each pass also checks every task against the `invariant` of each pillar in `gcf/PILLARS.md`: the pass reworks a task that breaks one, and a conflict no rework removes is a pillar conflict of step 12
+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, 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 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 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 17
+- run when the user names a work item or a unit to drive; batches share steps 1 and 19

package/workflows/ingest.js

@@ -140,12 +140,13 @@ const COHERENCE = [
 const sectionText = (s) => `[${s.anchor}] ${s.heading ?? '(preamble)'}\n${s.body}`;
 
 /**
- * GCF-PRD §11.7: a large GDD is cut into segments, each agent sees one. A section is never
- * split — quotes are verified against whole sections. ponytail: chars, not tokens.
+ * GCF-PRD §11.7: a large GDD is cut into segments, each agent sees one. A section longer than
+ * a segment is cut at paragraphs, each part keeps the section's anchor: quotes are verified
+ * against the whole section (bodyOf). ponytail: chars, not tokens.
  */
 function packSegments(sections, limit) {
   const segments = [];
-  for (const s of sections) {
+  for (const s of sections.flatMap((x) => sectionParts(x, limit))) {
     const last = segments[segments.length - 1];
     const text = sectionText(s);
     if (last && last.size + text.length <= limit) {
@@ -159,6 +160,62 @@ function packSegments(sections, limit) {
   return segments;
 }
 
+/** A section as parts that fit `limit`: whole paragraphs, a paragraph too long cut by length. */
+function sectionParts(s, limit) {
+  if (sectionText(s).length <= limit) return [s];
+  // 24: room for the ` (part N of M)` the heading gains. A floor of 500: a segment_chars at or
+  // below the heading would otherwise cut the body into one part per character.
+  const room = Math.max(500, limit - sectionText({ ...s, body: '' }).length - 24);
+  const paras = s.body
+    .split(/\n\s*\n/)
+    .flatMap((p) =>
+      Array.from({ length: Math.ceil(p.length / room) || 1 }, (_, i) =>
+        p.slice(i * room, (i + 1) * room),
+      ),
+    );
+  const bodies = [];
+  for (const p of paras) {
+    const last = bodies.length - 1;
+    if (last >= 0 && bodies[last].length + 2 + p.length <= room) bodies[last] += `\n\n${p}`;
+    else bodies.push(p);
+  }
+
+  return bodies.map((body, i) => ({
+    ...s,
+    heading: `${s.heading ?? '(preamble)'} (part ${i + 1} of ${bodies.length})`,
+    body,
+  }));
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * The part of a section an agent judging one unit needs: the whole body when it fits `limit`,
+ * else a window of `limit` chars centred on the quote, its edges pulled in to paragraph breaks
+ * that keep the quote. The quote matches across any whitespace, as provenance does, so one
+ * spanning two paragraphs is found too; a quote absent from the body yields its head.
+ */
+function around(body, quote, rawLimit) {
+  const limit = Math.max(500, rawLimit);
+  if (body.length <= limit) return body;
+  const words = String(quote ?? '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  const m = words.length ? new RegExp(words.map(escapeRe).join('\\s+')).exec(body) : null;
+  if (!m) return body.slice(0, limit);
+  const qEnd = m.index + m[0].length;
+  let start = Math.max(0, m.index - Math.max(0, Math.floor((limit - m[0].length) / 2)));
+  let end = Math.min(body.length, start + limit);
+  start = Math.max(0, Math.min(start, end - limit));
+  const from = body.indexOf('\n\n', start);
+  if (start > 0 && from >= 0 && from + 2 <= m.index) start = from + 2;
+  const to = body.lastIndexOf('\n\n', end);
+  if (end < body.length && to >= qEnd) end = to;
+
+  return body.slice(start, end);
+}
+
 // A line wrap in the GDD is not an edit: whitespace runs compare equal, as in `gcf quotes`.
 const ws = (t) => String(t).replace(/\s+/g, ' ').trim();
 
@@ -212,6 +269,30 @@ function crossingPairs(cands) {
   return pairs;
 }
 
+/**
+ * Drop the edge that closes each cycle of `deps` (id → ids it depends on), in place, and return
+ * each dropped edge with its cycle: which of the two really comes first is the designer's call.
+ */
+function breakCycles(deps) {
+  const broken = [];
+  const state = new Map();
+  const visit = (id, trail) => {
+    state.set(id, 'open');
+    for (const d of [...deps[id]]) {
+      if (state.get(d) === 'open') {
+        deps[id] = deps[id].filter((x) => x !== d);
+        broken.push({ id, dep: d, cycle: [...trail.slice(trail.indexOf(d)), id, d] });
+      } else if (!state.has(d)) visit(d, [...trail, id]);
+    }
+
+    state.set(id, 'done');
+  };
+
+  for (const id of Object.keys(deps)) if (!state.has(id)) visit(id, []);
+
+  return broken;
+}
+
 /** An id no unit has used yet: the agent's slug, suffixed -2, -3… on a collision. */
 function freeId(wanted, taken) {
   const base = /^[a-z0-9]+(-[a-z0-9]+)*$/.test(wanted ?? '') ? wanted : 'unit';
@@ -342,7 +423,8 @@ const spread = args.spread ?? 0.3;
 // Every id the project has used (`ai-factory gcf where --json`): a dropped or done unit's id
 // is never minted again, or the new unit would collide with the old one's history.
 const taken = new Set(Array.isArray(args.taken) ? args.taken : []);
-const segments = packSegments(sections, Number(args.segment_chars) || 60000);
+const segmentChars = Number(args.segment_chars) || 60000;
+const segments = packSegments(sections, segmentChars);
 const bodyOf = new Map(sections.map((s) => [s.anchor, s.body]));
 const multi = segments.length > 1;
 
@@ -370,7 +452,7 @@ log(`${inferred.length} inferred units diverted to questions`);
 
 phase('Lenses');
 const enriched = await pipeline(candidates, (c) =>
-  ask(lensPrompt(c, subsystemNames, bodyOf.get(c.anchor) ?? ''), {
+  ask(lensPrompt(c, subsystemNames, around(bodyOf.get(c.anchor) ?? '', c.quote, segmentChars)), {
     label: `lens:${c.name}`,
     phase: 'Lenses',
     schema: CAND_LENS,
@@ -396,10 +478,19 @@ const coherence = coherenceResults.flatMap((r) => r.findings);
 phase('Conflicts');
 const pairs = crossingPairs(cands);
 log(`${pairs.length} crossing pair(s) from the interaction matrix`);
-const pairSections = ({ a, b }) =>
-  [...new Set([a.anchor, b.anchor])].map((anchor) =>
-    sectionText(sections.find((s) => s.anchor === anchor) ?? { anchor, body: '' }),
-  );
+// Two units share the prompt, so each section gets half of a segment around its own quote.
+const pairSections = ({ a, b }) => {
+  const units = a.anchor === b.anchor ? [a] : [a, b];
+
+  return units.map((u) => {
+    const s = sections.find((x) => x.anchor === u.anchor) ?? { anchor: u.anchor, body: '' };
+    const quotes = a.anchor === b.anchor ? [a.quote, b.quote] : [u.quote];
+    const body = quotes.map((q) => around(s.body, q, segmentChars / units.length / quotes.length));
+
+    return sectionText({ ...s, body: [...new Set(body)].join('\n\n[…]\n\n') });
+  });
+};
+
 const conflictResults = await pipeline(pairs, (p) =>
   ask(conflictPrompt(p, pairSections(p)), {
     label: `conflict:${p.a.name}×${p.b.name}`,
@@ -415,6 +506,16 @@ for (const { order, pair } of conflictResults) {
   if (order === 'b_first') deps[pair.a.id].push(pair.b.id);
 }
 
+// Each pair agent decided alone: their orders may close a cycle the gate would never open.
+const anchorOf = new Map(cands.map((c) => [c.id, c.anchor]));
+const cycleQuestions = breakCycles(deps).map(({ id, dep, cycle }) => ({
+  lens: 'depends',
+  anchors: [...new Set(cycle.map((x) => anchorOf.get(x)))],
+  class: 'D1',
+  question: `the pair orders close a cycle ${cycle.join(' -> ')}: which comes first?`,
+  proposed: `${id} does not depend on ${dep}`,
+}));
+
 // ─── Package: deterministic code — an agent never writes the final report ────────────
 
 const provenanceQuestions = inferred.map((u) => ({
@@ -448,6 +549,7 @@ const questions = [
   ...gddQuestions,
   ...coherence,
   ...conflicts,
+  ...cycleQuestions,
   ...provenanceQuestions,
   ...envelopeQuestions,
 ];