gcf-harness-aif-ext 0.3.2 → 0.3.4

package/README.md

@@ -2,17 +2,24 @@
 
 Claude-Code-specific orchestration for the [Game Context Framework](../gcf-aif-ext). Optional: GCF works without it, by hand.
 
+> **Claude Code only.** Codex and the other AI Factory runtimes are not supported: the harness is built on Claude Code
+> dynamic workflows and `PreToolUse` hooks, which they do not have. AI Factory still copies the `gcf-run` skills into
+> every runtime the project is configured for, where they do not work — on a project without Claude Code, do not
+> install the harness. GCF itself keeps working on any runtime.
+
 The harness turns policy-as-text into an executable pipeline. It has **no memory of its own** — everything it knows between two agent calls is on disk in `gcf/`, so a run killed at any point restarts and reaches the same state.
 
 ## Requirements
 
-- [`gcf-aif-ext`](../gcf-aif-ext) `^0.2.2` 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)
+- [`gcf-aif-ext`](../gcf-aif-ext) `^0.2.7` 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
 
 ## Install
 
-Install into a project that already has the core, from npm or a local checkout:
+The shortest way is from the core: `ai-factory gcf init` asks whether to install the harness too, and on yes runs both steps below. It asks only in a terminal and only when the project has the Claude Code agent; `gcf init --harness` installs it without asking, `--no-harness` skips the question.
+
+By hand, into a project that already has the core, from npm or a local checkout:
 
 ```bash
 ai-factory extension add gcf-aif-ext                                # the core, if not yet installed
@@ -48,6 +55,8 @@ Removal does not touch `.claude/settings.json`: delete the `PreToolUse` entry wh
 
 **`/gcf-run <card-id…>`** — drives a card from the backlog to `built`, with every gate checked *before* the tokens are spent: the audit ritual, collapsed dependencies, the tune limit, the WIP cap, the context budget. It stops at `built` and prints the playtest list — the verdict belongs to the human, and there is no stage past the build.
 
+**`ai-factory gcf-harness gate <card-id…>`** — the `/gcf-run` gate as code. It reads one `gcf audit --json` report and exits 1 with a one-line reason when the cards may not go: a `schema:` other than 1, a card that is not `proposed` or `tuning`, an unplayed dependency, the tune limit, no WIP room for the whole batch (`built` count + batch size over `wip_built_limit`), or two cards of the batch touching the same system. The skill runs it and stops on a non-zero exit — no model compares the numbers.
+
 **`/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

@@ -1,13 +1,108 @@
 // `ai-factory gcf-harness init` — registers the readset-guard PreToolUse hook in the
 // project's .claude/settings.json (the AIF manifest cannot install Claude Code hooks —
 // same decision as gcf hooks-install for git hooks). Idempotent by marker comment.
+// `ai-factory gcf-harness gate <ids…>` — the /gcf-run gate as code (Harness-PRD §4.3).
 import { readFile, writeFile, mkdir, appendFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const MARKER = 'gcf-readset-guard';
+const SCHEMA = 1; // the only gcf/config.yml schema this harness drives
+const SESSION_RULE = /^(\/|\*\*\/)?\.gcf-session\/?$/;
+
+// ─── gate ────────────────────────────────────────────────────────────────────────────
+
+/** Why one card may not go, or null. */
+function cardProblem(id, card, report) {
+  if (!card) return `${id} has no card file — materialize the candidate first`;
+  if (!['proposed', 'tuning'].includes(card.status)) {
+    return `${id} is ${card.status} — only proposed and tuning cards are driven`;
+  }
+
+  // A dependency inside the same batch lands here too: the dependent waits for its verdict.
+  const open = report.open_depends.find((o) => o.id === id);
+  if (open) return `${id} depends on unplayed ${open.depends.join(', ')} — playtest them first`;
+  if (report.tune_limit.some((t) => t.id === id)) {
+    return `${id} is at the tune limit — kill or redesign it`;
+  }
+
+  return null;
+}
+
+/** Why the batch as a whole may not go, or null. */
+function batchProblem(cards, wip) {
+  // `wip.over` is false at count === limit, and this run adds every card of the batch.
+  if (wip.count + cards.length > wip.limit) {
+    return (
+      `WIP: ${wip.count} built + ${cards.length} in this run exceeds the limit of ${wip.limit}` +
+      ' — playtest first'
+    );
+  }
+
+  for (let i = 0; i < cards.length; i++) {
+    for (const other of cards.slice(i + 1)) {
+      const shared = cards[i].system.filter((s) => other.system.includes(s));
+      if (shared.length) {
+        const pair = `${cards[i].id} and ${other.id}`;
+
+        return `${pair} both touch ${shared.join(', ')} — run them separately`;
+      }
+    }
+  }
+
+  return null;
+}
+
+const verdict = (reason) => ({ pass: !reason, reason: reason ?? '' });
+
+/**
+ * Decides whether the cards may enter the paid stages, from one `gcf audit --json` report.
+ * Pure: the report is the whole input, so every rule has a test and no model compares numbers.
+ */
+export function gate(report, ids) {
+  if (!Array.isArray(report?.cards)) {
+    return verdict('the audit report has no card summary — gcf-aif-ext >= 0.2.6 is required');
+  }
+
+  if (report.schema !== SCHEMA) {
+    const drives = `this harness drives schema ${SCHEMA} only`;
+
+    return verdict(`gcf/config.yml has schema: ${report.schema}; ${drives}`);
+  }
+
+  const byId = new Map(report.cards.map((c) => [c.id, c]));
+  for (const id of ids) {
+    const problem = cardProblem(id, byId.get(id), report);
+    if (problem) return verdict(problem);
+  }
+
+  return verdict(
+    batchProblem(
+      ids.map((id) => byId.get(id)),
+      report.wip,
+    ),
+  );
+}
+
+/** `gcf audit` exits 1 on any finding, so the report is read from stdout whatever the code. */
+function auditReport() {
+  // Re-enter the same ai-factory CLI that is running this command: no PATH or .cmd lookup.
+  const args = [process.argv[1], 'gcf', 'audit', '--json'];
+  const res = spawnSync(process.execPath, args, { encoding: 'utf8' });
+  try {
+    return JSON.parse(res.stdout);
+  } catch (err) {
+    const output = (res.stderr || res.stdout || '').trim();
+    throw new Error(`\`ai-factory gcf audit --json\` produced no report: ${output}`, {
+      cause: err,
+    });
+  }
+}
+
+// ─── init ────────────────────────────────────────────────────────────────────────────
 
 /**
  * The harness holds no code of the core: it calls `ai-factory gcf …` and writes gcf/.
@@ -17,62 +112,111 @@ const MARKER = 'gcf-readset-guard';
  */
 function coreMissing(program) {
   if (!Array.isArray(program?.commands)) return false;
-  return !program.commands.some((c) => (typeof c?.name === 'function' ? c.name() : c?.name) === 'gcf');
+  const nameOf = (c) => (typeof c?.name === 'function' ? c.name() : c?.name);
+
+  return !program.commands.some((c) => nameOf(c) === 'gcf');
+}
+
+/**
+ * Refuse on malformed settings rather than rewriting the file from {} — the user's
+ * existing hooks are worth more than this one registration.
+ */
+async function readSettings(settingsFile) {
+  if (!existsSync(settingsFile)) return {};
+  // Outside the try: an unreadable file is its own error, not "invalid JSON".
+  const raw = await readFile(settingsFile, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${settingsFile} is not valid JSON (${err.message}) — fix it, then re-run`, {
+      cause: err,
+    });
+  }
+}
+
+/**
+ * Adds the guard entry, or repoints an existing one: a moved or cloned project keeps the old
+ * absolute path under the marker, and the registered hook would keep launching a missing file.
+ * Returns what happened, or null when the settings already hold the right command.
+ */
+function registerGuard(settings, command) {
+  settings.hooks ??= {};
+  settings.hooks.PreToolUse ??= [];
+  const ours = settings.hooks.PreToolUse.flatMap((e) => e?.hooks ?? []).filter(
+    (h) => typeof h?.command === 'string' && h.command.includes(MARKER),
+  );
+  if (!ours.length) {
+    settings.hooks.PreToolUse.push({
+      matcher: 'Read|Grep|Glob',
+      hooks: [{ type: 'command', command }],
+    });
+
+    return 'registered';
+  }
+
+  const stale = ours.filter((h) => h.command !== command);
+  for (const h of stale) h.command = command;
+
+  return stale.length ? 'repointed' : null;
+}
+
+/**
+ * Only an active rule ignoring the root .gcf-session/ counts — not a comment or a pattern
+ * for some other directory that happens to contain the name.
+ */
+async function ignoreSession(projectDir) {
+  const gitignore = path.join(projectDir, '.gitignore');
+  const lines = existsSync(gitignore) ? (await readFile(gitignore, 'utf8')).split('\n') : [];
+  if (!lines.some((l) => SESSION_RULE.test(l.trim()))) {
+    await appendFile(gitignore, '\n.gcf-session/\n', 'utf8');
+  }
+}
+
+async function init(program) {
+  if (coreMissing(program)) {
+    throw new Error(
+      'gcf-aif-ext is not installed: the harness drives `ai-factory gcf …` — ' +
+        'run `ai-factory extension add gcf-aif-ext` first',
+    );
+  }
+
+  const projectDir = process.cwd();
+  const settingsFile = path.join(projectDir, '.claude', 'settings.json');
+  const guard = path.join(EXT_ROOT, 'hooks', 'readset-guard.js').replaceAll('\\', '/');
+  const settings = await readSettings(settingsFile);
+  const change = registerGuard(settings, `node "${guard}" # ${MARKER}`);
+  if (change) {
+    await mkdir(path.dirname(settingsFile), { recursive: true });
+    await writeFile(settingsFile, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+    console.log(`readset-guard ${change} → ${settingsFile}`);
+  } else {
+    console.log('readset-guard already registered');
+  }
+
+  await ignoreSession(projectDir);
+}
+
+function runGate(ids, opts) {
+  const result = gate(auditReport(), [...new Set(ids)]);
+  if (opts.json) console.log(JSON.stringify(result));
+  else if (result.pass) console.log('gate: pass');
+  if (!result.pass) {
+    console.error(`gcf gate: ${result.reason}`);
+    process.exitCode = 1;
+  }
 }
 
 export function register(program) {
   const harness = program.command('gcf-harness').description('GCF harness setup');
 
-  harness.command('init')
-    .description('Initialize the harness in this project: readset-guard hook in .claude/settings.json (idempotent)')
-    .action(async () => {
-      if (coreMissing(program)) {
-        throw new Error('gcf-aif-ext is not installed: the harness drives `ai-factory gcf …` — run `ai-factory extension add gcf-aif-ext` first');
-      }
-      const projectDir = process.cwd();
-      const settingsFile = path.join(projectDir, '.claude', 'settings.json');
-      const guard = path.join(EXT_ROOT, 'hooks', 'readset-guard.js').replaceAll('\\', '/');
-
-      // Refuse on malformed settings rather than rewriting the file from {} — the user's
-      // existing hooks are worth more than this one registration.
-      let settings = {};
-      if (existsSync(settingsFile)) {
-        const raw = await readFile(settingsFile, 'utf8');
-        try {
-          settings = JSON.parse(raw);
-        } catch (err) {
-          throw new Error(`${settingsFile} is not valid JSON (${err.message}) — fix it, then re-run`);
-        }
-      }
-      settings.hooks ??= {};
-      settings.hooks.PreToolUse ??= [];
-      const command = `node "${guard}" # ${MARKER}`;
-      // A moved or cloned project keeps the old absolute path under the marker: repoint it,
-      // or the registered hook keeps launching a file that is gone.
-      const ours = settings.hooks.PreToolUse.flatMap((e) => e?.hooks ?? [])
-        .filter((h) => typeof h?.command === 'string' && h.command.includes(MARKER));
-      const stale = ours.filter((h) => h.command !== command);
-      if (!ours.length) {
-        settings.hooks.PreToolUse.push({
-          matcher: 'Read|Grep|Glob',
-          hooks: [{ type: 'command', command }],
-        });
-      }
-      for (const h of stale) h.command = command;
-      if (!ours.length || stale.length) {
-        await mkdir(path.dirname(settingsFile), { recursive: true });
-        await writeFile(settingsFile, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
-        console.log(`readset-guard ${ours.length ? 'repointed' : 'registered'} → ${settingsFile}`);
-      } else {
-        console.log('readset-guard already registered');
-      }
+  harness
+    .command('init')
+    .description('Initialize the harness in this project: readset-guard hook (idempotent)')
+    .action(() => init(program));
 
-      // Only an active rule ignoring the root .gcf-session/ counts — not a comment or a
-      // pattern for some other directory that happens to contain the name.
-      const gitignore = path.join(projectDir, '.gitignore');
-      const line = '.gcf-session/';
-      const has = existsSync(gitignore) && (await readFile(gitignore, 'utf8')).split('\n')
-        .some((l) => /^(\/|\*\*\/)?\.gcf-session\/?$/.test(l.trim()));
-      if (!has) await appendFile(gitignore, `\n${line}\n`, 'utf8');
-    });
+  harness
+    .command('gate <ids...>')
+    .description('Gate cards before the paid stages of /gcf-run: exit 1 with the reason')
+    .option('--json', 'machine output: {pass, reason}')
+    .action(runGate);
 }

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.3.2",
+  "version": "0.3.4",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/hooks/readset-guard.js

@@ -24,10 +24,59 @@ function readStdin() {
  * Only a literal first segment that is not gcfDir proves the search cannot get there.
  */
 function globAvoids(glob, gcfDir) {
-  const parts = (glob ?? '').replaceAll('\\', '/').replace(/^\.?\//, '').split('/');
+  const parts = (glob ?? '')
+    .replaceAll('\\', '/')
+    .replace(/^\.?\//, '')
+    .split('/');
+
   return parts.length > 1 && !/[*?[\]{}!]/.test(parts[0]) && parts[0] !== gcfDir;
 }
 
+const UNSCOPED_GREP =
+  'an unscoped Grep reads the contents of all of gcf/ — ' +
+  'pass `path:` or a `glob:` anchored outside gcf/ (e.g. `src/**`).';
+
+/**
+ * A path outside gcf/: only a CONTENT search from a directory above gcf/ still reaches it.
+ * Glob returns paths, and gcf/ paths are already public in INDEX.md.
+ */
+function outsideVerdict(input, abs, gcfRoot) {
+  const toGcf = path.relative(abs, gcfRoot).replaceAll('\\', '/');
+  const above = !toGcf.startsWith('..') && !path.isAbsolute(toGcf);
+  if (input.tool_name !== 'Grep' || !above) return { allow: true };
+  if (globAvoids(input.tool_input?.glob, toGcf.split('/')[0])) return { allow: true };
+
+  return { allow: false, reason: UNSCOPED_GREP };
+}
+
+/** The paths a manifest allows, plus the two every stage may always read. */
+function allowedPaths(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']);
+}
+
+/** A path inside gcf/ passes only through the readset. */
+function insideVerdict(rel, manifest) {
+  const allowed = allowedPaths(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 };
+
+  return {
+    allow: false,
+    // No "delete the manifest" hint: that is the human's lever for lifting the guard, and an
+    // agent told about it on every denial will reach for it and turn a leak into a bypass.
+    reason:
+      `${rel} is outside the current readset (.gcf-session/readset.json). ` +
+      'Extend it via `ai-factory gcf context <card>`, ' +
+      'or work from the files already in the readset.',
+  };
+}
+
 export function decide(input, projectDir, manifest) {
   // No manifest, or no input to judge at all: never restrict. A hook that hard-blocks every
   // read because stdin hiccuped is worse than the leak it guards.
@@ -39,55 +88,33 @@ export function decide(input, projectDir, manifest) {
   const gcfRoot = path.join(path.resolve(projectDir), 'gcf');
   const relFromGcf = path.relative(gcfRoot, abs);
   if (relFromGcf.startsWith('..') || path.isAbsolute(relFromGcf)) {
-    // Outside gcf/. Only a CONTENT search from a directory above gcf/ still reaches it: Glob
-    // returns paths, and gcf/ paths are already public in INDEX.md.
-    const toGcf = path.relative(abs, gcfRoot).replaceAll('\\', '/');
-    const above = !toGcf.startsWith('..') && !path.isAbsolute(toGcf);
-    if (input.tool_name !== 'Grep' || !above || globAvoids(input.tool_input?.glob, toGcf.split('/')[0])) return { allow: true };
-    return {
-      allow: false,
-      reason: 'an unscoped Grep reads the contents of all of gcf/ — pass `path:` or a `glob:` anchored outside gcf/ (e.g. `src/**`).',
-    };
+    return outsideVerdict(input, abs, gcfRoot);
   }
 
   // The gcf root itself relativizes to '' — unguarded it becomes 'gcf/' and matches nothing.
   const relPosix = relFromGcf.replaceAll('\\', '/');
-  const rel = relPosix ? `gcf/${relPosix}` : 'gcf';
-  // `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 allowed = new Set([
-    ...(manifest.files ?? []).map((f) => (typeof f === 'string' ? f : f?.path)).filter(Boolean),
-    'gcf/INDEX.md',
-    'gcf',
-  ]);
-  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.
-  for (const f of allowed) {
-    if (f.startsWith(`${rel}/`)) return { allow: true };
+
+  return insideVerdict(relPosix ? `gcf/${relPosix}` : 'gcf', manifest);
+}
+
+function readManifest(projectDir) {
+  try {
+    return JSON.parse(readFileSync(path.join(projectDir, '.gcf-session', 'readset.json'), 'utf8'));
+  } catch {
+    return null;
   }
-  return {
-    allow: false,
-    // No "delete the manifest" hint: that is the human's lever for lifting the guard, and an
-    // agent told about it on every denial will reach for it and turn a leak into a bypass.
-    reason: `${rel} is outside the current readset (.gcf-session/readset.json). Extend it via \`ai-factory gcf context <card>\`, or work from the files already in the readset.`,
-  };
 }
 
 // Hook entry: only runs when executed directly, so tests can import decide().
-if (import.meta.url === `file://${process.argv[1]?.replaceAll('\\', '/')}` || process.argv[1]?.endsWith('readset-guard.js')) {
+const entry = process.argv[1]?.replaceAll('\\', '/');
+if (import.meta.url === `file://${entry}` || entry?.endsWith('readset-guard.js')) {
   const input = readStdin();
   const projectDir = input?.cwd ?? process.cwd();
-  let manifest = null;
-  try {
-    manifest = JSON.parse(readFileSync(path.join(projectDir, '.gcf-session', 'readset.json'), 'utf8'));
-  } catch {
-    manifest = null;
-  }
-  const verdict = decide(input, projectDir, manifest);
+  const verdict = decide(input, projectDir, readManifest(projectDir));
   if (!verdict.allow) {
     console.error(`gcf readset-guard: ${verdict.reason}`);
     process.exit(2);
   }
+
   process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-harness-aif-ext",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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.2.2"
+    "gcf-aif-ext": "^0.2.7"
   },
   "files": [
     "extension.json",

package/skills/gcf-run/SKILL.md

@@ -13,18 +13,17 @@ inputs:
 
 preconditions:
 - `gcf/` exists and `ai-factory gcf audit` runs (the gcf-aif-ext extension provides it)
-- `schema:` in `gcf/config.yml` is 1, the only schema this harness drives: any other value refuses the run at start
 
 forbidden_behaviors:
 - do not go past `built`: the verdict belongs to the human, this pipeline has no stage after the build
 - do not read a `gcf/` file outside the readset from `ai-factory gcf context`
 - do not continue past a failed gate: report the one-line reason, delete `.gcf-session/readset.json`, and stop - a stop is a normal outcome
-- do not batch cards whose `system:` lists intersect, unless `depends:` orders them
+- do not compare the audit numbers yourself: the gate command is the only judge of whether a card may go
 
 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`; stale built cards with live dependents mean stop - print the playtest list instead of building
 2. for a cand-NNN input: materialize it with the gcf-card skill; a hard route leaves the pipeline for the normal AIF cycle here
-3. gate, per card, on a fresh `ai-factory gcf audit --json` - step 2 and a tune verdict move the counters: absent from `open_depends` and `tune_limit`; `wip.count` plus the number of cards in the batch is at most `wip.limit`
+3. gate: run `ai-factory gcf-harness gate <card-ids...>` over the whole batch; a non-zero exit is a failed gate, its stderr line is the reason
 4. readset: run `ai-factory gcf context <card-id> --json`; write `{"card":"<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
 5. plan with aif-plan, shaped by the card slots, reading only the readset files
 6. implement with aif-implement, then verify: autotests plus the card's negative constraints; retries <= 2 with a diagnosis each, then stop

package/skills/gcf-run-ingest/SKILL.md

@@ -22,13 +22,15 @@ forbidden_behaviors:
 
 workflow:
 1. run `ai-factory gcf anchor <file> --json` and keep the sections list
-2. on a re-import the output carries `delta`: keep only the sections whose anchor is in `delta.added`, skip the workflow when none are left, and apply the other delta classes as step 9 of the gcf-ingest skill does
+2. on a re-import the output carries `delta`: keep only the sections whose anchor is in `delta.added`, skip the workflow when none are left, and apply the other delta classes as step 11 of the gcf-ingest skill does
 3. read `envelope_default_spread` from `gcf/config.yml`
 4. read the highest NNN across `gcf/backlog.md` and `gcf/cards/`; invoke the Workflow tool with scriptPath `.ai-factory/extensions/gcf-harness-aif-ext/workflows/ingest.js` and args `{sections, spread, start_num}`, start_num = NNN + 1
-5. write the results: candidate lines appended to `gcf/backlog.md` keeping the ids the workflow minted; D1 and D2 records appended to `gcf/open-questions.md`; then run `ai-factory gcf index`
-6. mark a candidate whose nouns match the `purpose` or the `code` paths of an existing systems doc with `impl?` in its line, the same rule the sequential `/gcf-ingest` applies
-7. report the package in the GCF order: D1 questions first, pillar candidates, backlog summary with the top crossing candidates, D2 envelope assumptions
-8. verify equivalence on the first real GDD: compare this package against a sequential `/gcf-ingest` pass and report any divergence as a harness bug (Harness-PRD H3)
+5. write the results: candidate lines appended to `gcf/backlog.md` keeping the minted ids; fold each `exact` number into the description of the line citing its anchor
+6. append the D1 and D2 records to `gcf/open-questions.md` in the record form the gcf-ingest skill states under outputs, a D2 with its `assumed:` and `until:`
+7. run `ai-factory gcf quotes` and move each flagged line to a D1 with lens `provenance`, then run `ai-factory gcf index`
+8. mark a candidate whose nouns match the `purpose` or the `code` paths of an existing systems doc with `impl?`; with `gcf/systems/` empty on a codebase, report the marks as blind
+9. report the package in the GCF order: D1 questions first, pillar candidates, backlog summary with the top crossing candidates, D2 envelope assumptions
+10. verify equivalence on the first real GDD: compare this package against a sequential `/gcf-ingest` pass and report any divergence as a harness bug
 
 invocation:
 - run when the user asks for the workflow import on a GDD

package/workflows/ingest.js

@@ -1,42 +1,22 @@
 export const meta = {
   name: 'gcf-ingest',
-  description: 'Fan-out GDD import: parallel aspect extraction, code-verified provenance, lenses, one package',
+  description:
+    'Fan-out GDD import: parallel aspect extraction, code-verified provenance, lenses, one package',
   phases: [
     { title: 'Extract', detail: 'one agent per aspect per segment of the anchored sections' },
     { title: 'Lenses', detail: 'completeness per candidate, coherence over the whole set' },
     { title: 'Conflicts', detail: 'pairwise checks where the interaction matrix crosses' },
   ],
-}
-// args: { sections: [{anchor, heading, body}], spread: number, start_num: number, segment_chars?: number }
+};
+
+// args: { sections: [{anchor, heading, body}], spread, start_num, segment_chars? }
 // The main thread runs `ai-factory gcf anchor --json` BEFORE this workflow and writes
 // the outputs AFTER it — the script has no filesystem, by design (Harness-PRD §6.1).
+// Layout: schemas, then pure helpers, then the three phases, then package assembly.
 
-const sections = args.sections
-const spread = args.spread ?? 0.3
-// Candidate ids continue the existing backlog numbering: minting from the array index
-// makes every re-ingest emit cand-001 again, colliding with what is already filed.
-const startNum = Number(args.start_num) || 1 // args come from a model-composed call: "5" would concatenate
-// 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.
-const segmentChars = Number(args.segment_chars) || 60000
-const sectionText = (s) => `[${s.anchor}] ${s.heading ?? '(preamble)'}\n${s.body}`
-const segments = []
-for (const s of sections) {
-  const last = segments[segments.length - 1]
-  const text = sectionText(s)
-  if (last && last.size + text.length <= segmentChars) {
-    last.texts.push(text)
-    last.size += text.length
-  } else segments.push({ texts: [text], size: text.length })
-}
+// ─── Schemas: what each agent must return ────────────────────────────────────────────
 
-// A dead agent must stop the import, not shrink it: an empty extraction reads as "the GDD
-// has nothing here", and a re-import skips unchanged sections, so the loss would stick.
-const ask = async (prompt, opts) => {
-  const r = await agent(prompt, opts)
-  if (!r) throw new Error(`${opts.label} returned no result — import stopped, nothing to write; re-run the workflow`)
-  return r
-}
+const strings = (description) => ({ type: 'array', items: { type: 'string' }, description });
 
 const UNITS = {
   type: 'object',
@@ -50,79 +30,37 @@ const UNITS = {
           anchor: { type: 'string' },
           quote: { type: 'string', description: 'verbatim substring of the source section' },
           detail: { type: 'string' },
+          kind: {
+            enum: ['tunable', 'count', 'limit', 'threshold'],
+            description:
+              'numbers only: tunable = a feel value to balance; count = how many of a thing; ' +
+              'limit = a hard bound; threshold = a performance target',
+          },
         },
         required: ['name', 'anchor', 'quote'],
       },
     },
   },
   required: ['units'],
-}
-
-const ASPECTS = [
-  { key: 'pillars', prompt: 'pillar candidates: statements about what the game IS and is NOT' },
-  { key: 'subsystems', prompt: 'subsystems: the nouns — movement, combat, economy; lowercase slug in name' },
-  { key: 'features', prompt: 'feature candidates: the player verbs — things the player does; one unit per mechanic' },
-  { key: 'numbers', prompt: 'exact numbers and progressions: durations, costs, curves; detail carries the value and unit' },
-  { key: 'constraints', prompt: 'platform, audience, monetization and scope constraints' },
-]
+};
 
-phase('Extract')
-const byAnchor = new Map(sections.map((s) => [s.anchor, s.body]))
-const extracted = await pipeline(
-  ASPECTS.flatMap((a) => segments.map((seg, i) => ({ a, seg, i }))),
-  ({ a, seg, i }) => ask(
-    `Extract ${a.prompt} from this GDD${segments.length > 1 ? ` (part ${i + 1} of ${segments.length})` : ''}. Every unit MUST carry a verbatim quote copied exactly from its section and the section anchor.\n\n${seg.texts.join('\n\n')}`,
-    { label: `extract:${a.key}${segments.length > 1 ? `:${i + 1}` : ''}`, phase: 'Extract', schema: UNITS },
-  ).then((r) => ({ aspect: a.key, units: r.units ?? [] })),
-  // Provenance is CODE, not an agent: a quote either is a substring of its section or it is not.
-  (r) => {
-    const cited = []
-    const inferred = []
-    for (const u of r.units) {
-      const body = byAnchor.get(u.anchor) ?? ''
-      if (u.quote && body.includes(u.quote)) cited.push(u)
-      else inferred.push({ ...u, aspect: r.aspect })
-    }
-    return { aspect: r.aspect, cited, inferred }
-  },
-)
-
-const byAspect = {}
-for (const r of extracted) byAspect[r.aspect] = [...(byAspect[r.aspect] ?? []), ...r.cited]
-const inferred = extracted.flatMap((r) => r.inferred)
-const candidates = byAspect.features ?? []
-const subsystems = byAspect.subsystems ?? []
-log(`${candidates.length} candidates over ${segments.length} segment(s), ${inferred.length} inferred units diverted to questions`)
-
-// Numbers → envelopes: value ± spread, assumed. Deterministic transformation. The sign and a
-// compound unit (m/s2) are part of the value; a hyphen glued to a word (level-5) is not a minus.
-const envelopes = (byAspect.numbers ?? []).map((u) => {
-  const m = (u.detail ?? u.quote).match(/((?<![\p{L}\p{N}])[-−])?(\d+(?:[.,]\d+)?)\s*([\p{L}%°][\p{L}\p{N}%°/^²³·]*)?/u)
-  if (!m) return { ...u, envelope: null }
-  const v = (m[1] ? -1 : 1) * parseFloat(m[2].replace(',', '.'))
-  const a = +(v * (1 - spread)).toFixed(3)
-  const b = +(v * (1 + spread)).toFixed(3)
-  return { ...u, envelope: `${Math.min(a, b)}..${Math.max(a, b)} ${m[3] ?? ''}`.trim(), assumed: true }
-})
-
-phase('Lenses')
 const CAND_LENS = {
   type: 'object',
   properties: {
-    gaps: { type: 'array', items: { type: 'string' }, description: 'missing answers: state, input, feedback, refusal, boundaries, persistence' },
-    systems: { type: 'array', items: { type: 'string' }, description: 'subsystem slugs this candidate touches' },
-    state_written: { type: 'array', items: { type: 'string' }, description: 'named state this mechanic writes' },
+    gaps: strings('missing answers: state, input, feedback, refusal, boundaries, persistence'),
+    systems: strings('subsystem slugs this candidate touches'),
+    state_written: strings('named state this mechanic writes'),
+    route: {
+      enum: ['soft', 'hard'],
+      description:
+        'hard when an agent can verify acceptance alone (data format, protocol, ' +
+        'structural invariant, numeric performance threshold); ' +
+        'soft when acceptance is a playtest; doubt → soft',
+    },
+    route_why: { type: 'string', description: 'the reason for the route, one short clause' },
   },
-  required: ['gaps', 'systems', 'state_written'],
-}
-const enriched = await pipeline(
-  candidates,
-  (c) => ask(
-    `Completeness lenses over one feature candidate. Candidate: ${c.name} (${c.anchor}: "${c.quote}").\nKnown subsystems: ${subsystems.map((s) => s.name).join(', ') || 'none yet'}.\nSection:\n${byAnchor.get(c.anchor) ?? ''}`,
-    { label: `lens:${c.name}`, phase: 'Lenses', schema: CAND_LENS },
-  ).then((r) => ({ ...c, ...r })),
-)
-const idOf = new Map(enriched.map((c, i) => [c, `cand-${String(startNum + i).padStart(3, '0')}`]))
+  required: ['gaps', 'systems', 'state_written', 'route', 'route_why'],
+};
 
 const FINDING = {
   type: 'object',
@@ -134,70 +72,361 @@ const FINDING = {
     proposed: { type: 'string' },
   },
   required: ['lens', 'anchors', 'class', 'question', 'proposed'],
-}
-const FINDINGS = { type: 'object', properties: { findings: { type: 'array', items: FINDING } }, required: ['findings'] }
-const COHERENCE = ['loop closure: every produced resource has a sink and every sink a source',
-  'progression pressure: what moves the player forward and brings them back',
-  'economy balance: do the numbers converge over time',
-  'dictionary: exactly one word per concept across the document']
-// A segmented GDD does not fit one agent: the whole-set lenses read the cited units instead.
-const wholeDoc = segments.length === 1
-  ? segments[0].texts.join('\n\n')
-  : `Cited units (the GDD is too large to attach):\n${JSON.stringify(Object.fromEntries(Object.entries(byAspect).map(([k, us]) => [k, us.map((u) => ({ name: u.name, anchor: u.anchor, quote: u.quote, detail: u.detail }))])))}`
-// Barrier is correct here: coherence lenses need the WHOLE candidate set at once.
-const coherence = (await parallel(COHERENCE.map((lens) => () => ask(
-  `Coherence lens over the whole GDD: ${lens}.\nCandidates: ${JSON.stringify(enriched.map((c) => ({ name: c.name, anchor: c.anchor, state_written: c.state_written })))}\n\n${wholeDoc}`,
-  { label: `lens:${lens.split(':')[0]}`, phase: 'Lenses', schema: FINDINGS },
-)))).flatMap((r) => r.findings)
-
-phase('Conflicts')
-// Interaction matrix from code: pairs writing the same named state.
-const pairs = []
-for (let i = 0; i < enriched.length; i++) {
-  for (let j = i + 1; j < enriched.length; j++) {
-    const shared = enriched[i].state_written.filter((s) => enriched[j].state_written.includes(s))
-    if (shared.length) pairs.push({ a: enriched[i], b: enriched[j], shared })
-  }
-}
-log(`${pairs.length} crossing pair(s) from the interaction matrix`)
-// `deps` is the matrix's by-product (GCF-PRD §11.4): the pair check also says which mechanic
-// has to be played first.
+};
+
+const FINDINGS = {
+  type: 'object',
+  properties: { findings: { type: 'array', items: FINDING } },
+  required: ['findings'],
+};
+
+// `deps` is the matrix's by-product (GCF-PRD §11.4): the pair check also says which
+// mechanic has to be played first.
 const CONFLICT = {
   type: 'object',
   properties: {
     findings: FINDINGS.properties.findings,
-    order: { enum: ['a_first', 'b_first', 'none'], description: 'a_first: B cannot be built or played without A already in the game' },
+    order: {
+      enum: ['a_first', 'b_first', 'none'],
+      description: 'a_first: B cannot be built or played without A already in the game',
+    },
   },
   required: ['findings', 'order'],
+};
+
+const ASPECTS = [
+  { key: 'pillars', prompt: 'pillar candidates: statements about what the game IS and is NOT' },
+  {
+    key: 'subsystems',
+    prompt: 'subsystems: the nouns — movement, combat, economy; lowercase slug in name',
+  },
+  {
+    key: 'features',
+    prompt: 'feature candidates: the player verbs — things the player does; one unit per mechanic',
+  },
+  {
+    key: 'numbers',
+    prompt:
+      'exact numbers and progressions: durations, costs, curves; detail carries the value and ' +
+      'unit, kind says whether it is tunable, a count, a hard limit or a performance threshold',
+  },
+  { key: 'constraints', prompt: 'platform, audience, monetization and scope constraints' },
+  {
+    key: 'questions',
+    prompt:
+      'questions the document itself leaves open: its open-questions section, TBD, TODO; ' +
+      'name carries the question, detail the answer the text leans to, if any',
+  },
+];
+
+const COHERENCE = [
+  'loop closure: every produced resource has a sink and every sink a source',
+  'progression pressure: what moves the player forward and brings them back',
+  'economy balance: do the numbers converge over time',
+  'dictionary: exactly one word per concept across the document',
+];
+
+// ─── Helpers: pure functions, no agents ──────────────────────────────────────────────
+
+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.
+ */
+function packSegments(sections, limit) {
+  const segments = [];
+  for (const s of sections) {
+    const last = segments[segments.length - 1];
+    const text = sectionText(s);
+    if (last && last.size + text.length <= limit) {
+      last.texts.push(text);
+      last.size += text.length;
+    } else {
+      segments.push({ texts: [text], size: text.length });
+    }
+  }
+
+  return segments;
 }
-const conflictResults = await pipeline(
-  pairs,
-  (p) => ask(
-    `Two mechanics write the same state (${p.shared.join(', ')}): A "${p.a.name}" (${p.a.anchor}) and B "${p.b.name}" (${p.b.anchor}). Does the document define their interaction? If not, report the gap as a D1 finding. Also say whether one has to exist before the other.\n\n${[...new Set([p.a.anchor, p.b.anchor])].map((anchor) => sectionText(sections.find((s) => s.anchor === anchor) ?? { anchor, body: '' })).join('\n\n')}`,
-    { label: `conflict:${p.a.name}×${p.b.name}`, phase: 'Conflicts', schema: CONFLICT },
-  ).then((r) => ({ ...r, pair: p })),
-)
-const conflicts = conflictResults.flatMap((r) => r.findings)
-const deps = new Map(enriched.map((c) => [c, []]))
+
+// 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();
+
+/** Provenance is CODE, not an agent: a quote either is a substring of its section or not. */
+function splitByProvenance({ aspect, units }, bodyOf) {
+  const cited = [];
+  const inferred = [];
+  for (const u of units) {
+    const body = ws(bodyOf.get(u.anchor) ?? '');
+    if (u.quote && body.includes(ws(u.quote))) cited.push(u);
+    else inferred.push({ ...u, aspect });
+  }
+
+  return { aspect, cited, inferred };
+}
+
+// The sign and a compound unit (m/s2) are part of the value; a hyphen glued to a word
+// (level-5) is not a minus.
+const NUMBER = /((?<![\p{L}\p{N}])[-−])?(\d+(?:[.,]\d+)?)\s*([\p{L}%°][\p{L}\p{N}%°/^²³·]*)?/u;
+
+/**
+ * Number → envelope: value ± spread, assumed. Deterministic transformation. Only a tunable
+ * value gets one: a count (50 levels), a hard limit or a performance threshold stays exact.
+ * An integer keeps integer bounds, widened outward — 2 hp is 1..3, never 1.4..2.6.
+ */
+function toEnvelope(unit, spread) {
+  const m = (unit.detail ?? unit.quote).match(NUMBER);
+  if (!m || (unit.kind && unit.kind !== 'tunable')) return { ...unit, envelope: null };
+  const value = (m[1] ? -1 : 1) * parseFloat(m[2].replace(',', '.'));
+  const scaled = [value * (1 - spread), value * (1 + spread)].map((x) => +x.toFixed(3));
+  let lo = Math.min(...scaled);
+  let hi = Math.max(...scaled);
+  if (/^\d+$/.test(m[2])) {
+    lo = Math.min(Math.floor(lo), value - 1);
+    hi = Math.max(Math.ceil(hi), value + 1);
+  }
+
+  return { ...unit, envelope: `${lo}..${hi} ${m[3] ?? ''}`.trim(), assumed: true };
+}
+
+/** Interaction matrix from code: pairs of candidates writing the same named state. */
+function crossingPairs(cands) {
+  const pairs = [];
+  for (let i = 0; i < cands.length; i++) {
+    for (let j = i + 1; j < cands.length; j++) {
+      const shared = cands[i].state_written.filter((s) => cands[j].state_written.includes(s));
+      if (shared.length) pairs.push({ a: cands[i], b: cands[j], shared });
+    }
+  }
+
+  return pairs;
+}
+
+/** The backlog line grammar `gcf index` parses (GCF-PRD §5.2). */
+function candidateLine(c, deps) {
+  const fields = [
+    `- ${c.id}`,
+    c.name,
+    `route: ${c.route === 'hard' ? 'hard' : 'soft'} (${c.route_why || 'acceptance is a playtest'})`,
+    `sys: ${c.systems[0] ?? 'unassigned'}`,
+    `deps: ${deps.join(', ') || '-'}`,
+    `src: ${c.anchor}`,
+    `q: "${c.quote}"`,
+  ];
+  if (c.gaps.length) fields.push(`gaps: ${c.gaps.join(', ')}`);
+  fields.push(c.detail || c.name);
+
+  return fields.join(' | ');
+}
+
+// ─── Prompts ─────────────────────────────────────────────────────────────────────────
+
+function extractPrompt(aspect, segment, part, parts) {
+  return [
+    `Extract ${aspect.prompt} from this GDD${parts > 1 ? ` (part ${part} of ${parts})` : ''}.`,
+    'Every unit MUST carry a verbatim quote copied exactly from its section',
+    'and the section anchor.',
+    '',
+    segment.texts.join('\n\n'),
+  ].join('\n');
+}
+
+function lensPrompt(c, subsystemNames, sectionBody) {
+  return [
+    'Completeness lenses over one feature candidate, and its route with the reason.',
+    `Candidate: ${c.name} (${c.anchor}: "${c.quote}").`,
+    `Known subsystems: ${subsystemNames.join(', ') || 'none yet'}.`,
+    'Section:',
+    sectionBody,
+  ].join('\n');
+}
+
+function coherencePrompt(lens, cands, document) {
+  const summary = cands.map((c) => ({
+    name: c.name,
+    anchor: c.anchor,
+    state_written: c.state_written,
+  }));
+
+  return [
+    `Coherence lens over the whole GDD: ${lens}.`,
+    `Candidates: ${JSON.stringify(summary)}`,
+    '',
+    document,
+  ].join('\n');
+}
+
+function conflictPrompt({ a, b, shared }, sectionTexts) {
+  return [
+    `Two mechanics write the same state (${shared.join(', ')}):`,
+    `A "${a.name}" (${a.anchor}) and B "${b.name}" (${b.anchor}).`,
+    'Does the document define their interaction? If not, report the gap as a D1 finding.',
+    'Also say whether one has to exist before the other.',
+    '',
+    sectionTexts.join('\n\n'),
+  ].join('\n');
+}
+
+/** A segmented GDD does not fit one agent: the whole-set lenses read the cited units instead. */
+function citedDigest(byAspect) {
+  const digest = Object.fromEntries(
+    Object.entries(byAspect).map(([aspect, units]) => [
+      aspect,
+      units.map(({ name, anchor, quote, detail }) => ({ name, anchor, quote, detail })),
+    ]),
+  );
+
+  return `Cited units (the GDD is too large to attach):\n${JSON.stringify(digest)}`;
+}
+
+// A dead agent must stop the import, not shrink it: an empty extraction reads as "the GDD
+// has nothing here", and a re-import skips unchanged sections, so the loss would stick.
+async function ask(prompt, opts) {
+  const result = await agent(prompt, opts);
+  if (!result) {
+    throw new Error(`${opts.label} returned no result — import stopped, nothing to write`);
+  }
+
+  return result;
+}
+
+// ─── Run ─────────────────────────────────────────────────────────────────────────────
+
+const sections = args.sections;
+const spread = args.spread ?? 0.3;
+// Candidate ids continue the existing backlog numbering: minting from the array index
+// makes every re-ingest emit cand-001 again. Number(): args come from a model-composed
+// call, and "5" would concatenate.
+const startNum = Number(args.start_num) || 1;
+const segments = packSegments(sections, Number(args.segment_chars) || 60000);
+const bodyOf = new Map(sections.map((s) => [s.anchor, s.body]));
+const multi = segments.length > 1;
+
+phase('Extract');
+const jobs = ASPECTS.flatMap((aspect) => segments.map((segment, i) => ({ aspect, segment, i })));
+const extracted = await pipeline(
+  jobs,
+  ({ aspect, segment, i }) =>
+    ask(extractPrompt(aspect, segment, i + 1, segments.length), {
+      label: `extract:${aspect.key}${multi ? `:${i + 1}` : ''}`,
+      phase: 'Extract',
+      schema: UNITS,
+    }).then((r) => ({ aspect: aspect.key, units: r.units ?? [] })),
+  (r) => splitByProvenance(r, bodyOf),
+);
+
+const byAspect = {};
+for (const r of extracted) byAspect[r.aspect] = [...(byAspect[r.aspect] ?? []), ...r.cited];
+const inferred = extracted.flatMap((r) => r.inferred);
+const candidates = byAspect.features ?? [];
+const subsystemNames = (byAspect.subsystems ?? []).map((s) => s.name);
+const envelopes = (byAspect.numbers ?? []).map((u) => toEnvelope(u, spread));
+log(`${candidates.length} candidates over ${segments.length} segment(s)`);
+log(`${inferred.length} inferred units diverted to questions`);
+
+phase('Lenses');
+const enriched = await pipeline(candidates, (c) =>
+  ask(lensPrompt(c, subsystemNames, bodyOf.get(c.anchor) ?? ''), {
+    label: `lens:${c.name}`,
+    phase: 'Lenses',
+    schema: CAND_LENS,
+  }).then((r) => ({ ...c, ...r })),
+);
+const cands = enriched.map((c, i) => ({
+  ...c,
+  id: `cand-${String(startNum + i).padStart(3, '0')}`,
+}));
+
+// No sections at all also takes the digest path: there is no segment to attach.
+const wholeDoc = segments.length === 1 ? segments[0].texts.join('\n\n') : citedDigest(byAspect);
+// Barrier is correct here: coherence lenses need the WHOLE candidate set at once.
+const coherenceResults = await parallel(
+  COHERENCE.map(
+    (lens) => () =>
+      ask(coherencePrompt(lens, cands, wholeDoc), {
+        label: `lens:${lens.split(':')[0]}`,
+        phase: 'Lenses',
+        schema: FINDINGS,
+      }),
+  ),
+);
+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: '' }),
+  );
+const conflictResults = await pipeline(pairs, (p) =>
+  ask(conflictPrompt(p, pairSections(p)), {
+    label: `conflict:${p.a.name}×${p.b.name}`,
+    phase: 'Conflicts',
+    schema: CONFLICT,
+  }).then((r) => ({ ...r, pair: p })),
+);
+const conflicts = conflictResults.flatMap((r) => r.findings);
+/** @type {Record<string, string[]>} */
+const deps = Object.fromEntries(cands.map((c) => [c.id, []]));
 for (const { order, pair } of conflictResults) {
-  if (order === 'a_first') deps.get(pair.b).push(idOf.get(pair.a))
-  if (order === 'b_first') deps.get(pair.a).push(idOf.get(pair.b))
+  if (order === 'a_first') deps[pair.b.id].push(pair.a.id);
+  if (order === 'b_first') deps[pair.a.id].push(pair.b.id);
 }
 
-// Package assembly is deterministic code — an agent never writes the final report.
-const questions = [...coherence, ...conflicts,
-  ...inferred.map((u) => ({ lens: 'provenance', anchors: [u.anchor], class: 'D1', question: `"${u.name}" (${u.aspect}) has no verbatim quote — said or invented?`, proposed: 'drop it' })),
-  // GCF-PRD §11.3: an envelope is a D2 assumption — the number is cited, the spread is not.
-  ...envelopes.filter((e) => e.envelope).map((e) => ({ lens: 'envelope', anchors: [e.anchor], class: 'D2', question: `"${e.name}": "${e.quote}" taken as the envelope ${e.envelope} — assumed: ±${Math.round(spread * 100)}%`, proposed: e.envelope }))]
-return {
+// ─── Package: deterministic code — an agent never writes the final report ────────────
+
+const provenanceQuestions = inferred.map((u) => ({
+  lens: 'provenance',
+  anchors: [u.anchor],
+  class: 'D1',
+  question: `"${u.name}" (${u.aspect}) has no verbatim quote — said or invented?`,
+  proposed: 'drop it',
+}));
+// GCF-PRD §11.3: an envelope is a D2 assumption — the number is cited, the spread is not.
+const envelopeQuestions = envelopes
+  .filter((e) => e.envelope)
+  .map((e) => ({
+    lens: 'envelope',
+    anchors: [e.anchor],
+    class: 'D2',
+    question: `"${e.name}": "${e.quote}" taken as the envelope ${e.envelope}`,
+    proposed: e.envelope,
+    assumed: `±${Math.round(spread * 100)}% around the cited number`,
+    until: `manual(materialization of the candidate citing ${e.anchor})`,
+  }));
+// GCF-PRD §11.2: the GDD's own open questions are the designer's gaps, said out loud.
+const gddQuestions = (byAspect.questions ?? []).map((u) => ({
+  lens: 'gdd-open',
+  anchors: [u.anchor],
+  class: 'D1',
+  question: u.name,
+  proposed: u.detail || 'ask the designer',
+}));
+const questions = [
+  ...gddQuestions,
+  ...coherence,
+  ...conflicts,
+  ...provenanceQuestions,
+  ...envelopeQuestions,
+];
+
+const result = {
   pillar_candidates: byAspect.pillars ?? [],
-  subsystems: subsystems.map((s) => s.name),
-  candidates: enriched.map((c) => ({
-    line: `- ${idOf.get(c)} | ${c.name} | route: soft | sys: ${c.systems[0] ?? 'unassigned'} | deps: ${deps.get(c).join(', ') || '-'} | src: ${c.anchor}${c.gaps.length ? ` | gaps: ${c.gaps.join(', ')}` : ''}`,
+  subsystems: subsystemNames,
+  candidates: cands.map((c) => ({
+    line: candidateLine(c, deps[c.id]),
     crossings: pairs.filter((p) => p.a === c || p.b === c).length,
   })),
-  envelopes,
+  envelopes: envelopes.filter((e) => e.envelope),
+  // Counts, hard limits and thresholds stay exact: the write step folds each into the
+  // description of the candidate citing the same anchor.
+  exact: envelopes.filter((e) => !e.envelope),
   d1: questions.filter((q) => q.class === 'D1'),
   d2: questions.filter((q) => q.class === 'D2'),
   constraints: byAspect.constraints ?? [],
-}
+};
+
+// @ts-expect-error -- the Workflow runtime runs this file as a function body: return is its API
+return result;