gcf-harness-aif-ext 0.2.0 → 0.3.2

package/README.md

@@ -6,24 +6,51 @@ The harness turns policy-as-text into an executable pipeline. It has **no memory
 
 ## Requirements
 
-- [`gcf-aif-ext`](../gcf-aif-ext) `^0.2.0` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness install` refuses when the `gcf` command is not registered
+- [`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)
 - AI Factory 2.x, Node.js ≥ 22.14
 
 ## Install
 
+Install 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
+ai-factory extension add gcf-harness-aif-ext                        # npm
+# ai-factory extension add ../GCF/packages/gcf-harness-aif-ext      # local checkout
+```
+
+This installs the `gcf-run` and `gcf-run-ingest` skills and registers the `gcf-harness` command. Then initialize the harness in the project — like `gcf init`, once per project:
+
+```bash
+ai-factory gcf-harness init    # per project: .claude/settings.json + .gitignore
+```
+
+It is **per project**, not global — run it again in every game repository: it adds the readset-guard `PreToolUse` entry to the project's `.claude/settings.json` (never `~/.claude`) and `.gcf-session/` to `.gitignore`. It is idempotent — a re-run after moving or cloning the project repoints the hook at the new path — refuses when the `gcf` command is not registered, and refuses to rewrite a `settings.json` it cannot parse. It is a separate step for the same reason as `gcf hooks-install`: an AI Factory manifest cannot install Claude Code hooks.
+
+## Upgrade
+
+```bash
+ai-factory extension update gcf-harness-aif-ext
+```
+
+Updating keeps the hook entry valid — it points into the extension's install directory, which an update refreshes in place.
+
+To remove the extension:
+
 ```bash
-ai-factory extension add <path-to>/packages/gcf-harness-aif-ext
-ai-factory gcf-harness install   # registers the readset-guard hook
+ai-factory extension remove gcf-harness-aif-ext
 ```
 
+Removal does not touch `.claude/settings.json`: delete the `PreToolUse` entry whose command ends in `# gcf-readset-guard` by hand, or every Read, Grep and Glob will report a hook error.
+
 ## What it adds
 
 **`/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.
 
 **`/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 an unscoped Grep or Glob is denied too, because a search from the project root would read the whole tree past the gate. 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.
+**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.
 
 ## Docs
 

package/commands/harness.js

@@ -1,4 +1,4 @@
-// `ai-factory gcf-harness install` — registers the readset-guard PreToolUse hook in the
+// `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.
 import { readFile, writeFile, mkdir, appendFile } from 'node:fs/promises';
@@ -23,8 +23,8 @@ function coreMissing(program) {
 export function register(program) {
   const harness = program.command('gcf-harness').description('GCF harness setup');
 
-  harness.command('install')
-    .description('Register the readset-guard hook in .claude/settings.json (idempotent)')
+  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');
@@ -46,22 +46,33 @@ export function register(program) {
       }
       settings.hooks ??= {};
       settings.hooks.PreToolUse ??= [];
-      const already = JSON.stringify(settings.hooks.PreToolUse).includes(MARKER);
-      if (!already) {
+      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: `node "${guard}" # ${MARKER}` }],
+          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 registered → ${settingsFile}`);
+        console.log(`readset-guard ${ours.length ? 'repointed' : 'registered'} → ${settingsFile}`);
       } else {
         console.log('readset-guard already registered');
       }
 
+      // 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')).includes(line);
+      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');
     });
 }

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

package/hooks/readset-guard.js

@@ -17,30 +17,39 @@ function readStdin() {
   }
 }
 
+/**
+ * Whether a Grep `glob:` keeps a search away from `gcfDir`, the first path segment leading
+ * from the search root to gcf/. Globs are gitignore-style: one without a slash matches at
+ * any depth, and a wildcard, brace or negation in the first segment can still match gcf/.
+ * 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('/');
+  return parts.length > 1 && !/[*?[\]{}!]/.test(parts[0]) && parts[0] !== gcfDir;
+}
+
 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.
   if (!manifest || !input) return { allow: true };
 
-  const candidate = input.tool_input?.file_path ?? input.tool_input?.path ?? null;
-  if (!candidate) {
-    // Without `path`, a search runs from the project root. Only a CONTENT search is a leak:
-    // Glob returns paths, and gcf/ paths are already public in INDEX.md. A Grep whose `glob:`
-    // points away from gcf/ cannot reach it either. What is left is the real hole.
-    if (input.tool_name !== 'Grep') return { allow: true };
-    const scope = (input.tool_input?.glob ?? '').replaceAll('\\', '/');
-    if (scope && !scope.startsWith('gcf')) return { allow: true };
+  // Without `path`, a search runs from the project root.
+  const candidate = input.tool_input?.file_path ?? input.tool_input?.path ?? '.';
+  const abs = path.resolve(projectDir, candidate);
+  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:` that scopes the search.',
+      reason: 'an unscoped Grep reads the contents of all of gcf/ — pass `path:` or a `glob:` anchored outside gcf/ (e.g. `src/**`).',
     };
   }
 
-  const abs = path.resolve(projectDir, candidate);
-  const gcfRoot = path.join(path.resolve(projectDir), 'gcf');
-  const relFromGcf = path.relative(gcfRoot, abs);
-  if (relFromGcf.startsWith('..') || path.isAbsolute(relFromGcf)) return { allow: true }; // outside gcf/
-
   // The gcf root itself relativizes to '' — unguarded it becomes 'gcf/' and matches nothing.
   const relPosix = relFromGcf.replaceAll('\\', '/');
   const rel = relPosix ? `gcf/${relPosix}` : 'gcf';

package/package.json

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

package/skills/gcf-run/SKILL.md

@@ -13,17 +13,18 @@ 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 and stop - a stop is a normal outcome
+- 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
 
 workflow:
-1. session ritual: 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
+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: depends all collapsed, tune_count < limit, WIP under `wip_built_limit` - the audit report from step 1 carries each answer
+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`
 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

@@ -18,15 +18,17 @@ forbidden_behaviors:
 - do not create card files: the package holds backlog lines, a card materializes only at pull
 - do not let an agent write gcf files from inside the workflow: the script returns data, this skill writes
 - do not paste the package into PILLARS.md: pillar candidates go to the human as D1
+- do not write anything from a failed workflow: a dead agent fails it on purpose, so report its label and stop
 
 workflow:
 1. run `ai-factory gcf anchor <file> --json` and keep the sections list
-2. read `envelope_default_spread` from `gcf/config.yml`
-3. 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
-4. 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`
-5. 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
-6. report the package in the GCF order: D1 questions first, pillar candidates, backlog summary with the top crossing candidates, D2 envelope assumptions
-7. 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)
+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
+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)
 
 invocation:
 - run when the user asks for the workflow import on a GDD

package/workflows/ingest.js

@@ -2,12 +2,12 @@ export const meta = {
   name: 'gcf-ingest',
   description: 'Fan-out GDD import: parallel aspect extraction, code-verified provenance, lenses, one package',
   phases: [
-    { title: 'Extract', detail: 'one agent per aspect over the anchored sections' },
+    { 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 }
+// args: { sections: [{anchor, heading, body}], spread: number, start_num: number, segment_chars?: number }
 // 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).
 
@@ -16,7 +16,27 @@ 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
-const gddText = sections.map((s) => `[${s.anchor}] ${s.heading ?? '(preamble)'}\n${s.body}`).join('\n\n')
+// 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 })
+}
+
+// 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 UNITS = {
   type: 'object',
@@ -47,15 +67,15 @@ const ASPECTS = [
 ]
 
 phase('Extract')
+const byAnchor = new Map(sections.map((s) => [s.anchor, s.body]))
 const extracted = await pipeline(
-  ASPECTS,
-  (a) => agent(
-    `Extract ${a.prompt} from this GDD. Every unit MUST carry a verbatim quote copied exactly from its section and the section anchor.\n\n${gddText}`,
-    { label: `extract:${a.key}`, phase: 'Extract', schema: UNITS },
-  ).then((r) => ({ aspect: a.key, units: r?.units ?? [] })),
+  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 byAnchor = new Map(sections.map((s) => [s.anchor, s.body]))
     const cited = []
     const inferred = []
     for (const u of r.units) {
@@ -67,20 +87,22 @@ const extracted = await pipeline(
   },
 )
 
-const byAspect = Object.fromEntries(extracted.filter(Boolean).map((r) => [r.aspect, r.cited]))
-const inferred = extracted.filter(Boolean).flatMap((r) => r.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, ${inferred.length} inferred units diverted to questions`)
+log(`${candidates.length} candidates over ${segments.length} segment(s), ${inferred.length} inferred units diverted to questions`)
 
-// Numbers → envelopes: value ± spread, assumed. Deterministic transformation.
+// 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(/(\d+(?:[.,]\d+)?)\s*([a-zA-Zа-яё%]*)/)
+  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 = parseFloat(m[1].replace(',', '.'))
-  const lo = +(v * (1 - spread)).toFixed(3)
-  const hi = +(v * (1 + spread)).toFixed(3)
-  return { ...u, envelope: `${lo}..${hi} ${m[2]}`.trim(), assumed: true }
+  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')
@@ -93,44 +115,40 @@ const CAND_LENS = {
   },
   required: ['gaps', 'systems', 'state_written'],
 }
-const perCandidate = await pipeline(
+const enriched = await pipeline(
   candidates,
-  (c) => agent(
-    `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${sections.find((s) => s.anchor === c.anchor)?.body ?? ''}`,
+  (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) => r && { ...c, ...r }),
+  ).then((r) => ({ ...c, ...r })),
 )
+const idOf = new Map(enriched.map((c, i) => [c, `cand-${String(startNum + i).padStart(3, '0')}`]))
 
-const enriched = perCandidate.filter(Boolean)
-const FINDINGS = {
+const FINDING = {
   type: 'object',
   properties: {
-    findings: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          lens: { type: 'string' },
-          anchors: { type: 'array', items: { type: 'string' } },
-          class: { enum: ['D1', 'D2'] },
-          question: { type: 'string' },
-          proposed: { type: 'string' },
-        },
-        required: ['lens', 'anchors', 'class', 'question', 'proposed'],
-      },
-    },
+    lens: { type: 'string' },
+    anchors: { type: 'array', items: { type: 'string' } },
+    class: { enum: ['D1', 'D2'] },
+    question: { type: 'string' },
+    proposed: { type: 'string' },
   },
-  required: ['findings'],
+  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) => () => agent(
-  `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${gddText}`,
+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 },
-)))).filter(Boolean).flatMap((r) => r.findings)
+)))).flatMap((r) => r.findings)
 
 phase('Conflicts')
 // Interaction matrix from code: pairs writing the same named state.
@@ -142,22 +160,40 @@ for (let i = 0; i < enriched.length; i++) {
   }
 }
 log(`${pairs.length} crossing pair(s) from the interaction matrix`)
-const conflicts = (await pipeline(
+// `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' },
+  },
+  required: ['findings', 'order'],
+}
+const conflictResults = await pipeline(
   pairs,
-  (p) => agent(
-    `Two mechanics write the same state (${p.shared.join(', ')}): "${p.a.name}" (${p.a.anchor}) and "${p.b.name}" (${p.b.anchor}). Does the document define their interaction? If not, report the gap as a D1 finding.`,
-    { label: `conflict:${p.a.name}×${p.b.name}`, phase: 'Conflicts', schema: FINDINGS },
-  ),
-)).filter(Boolean).flatMap((r) => r.findings)
+  (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, []]))
+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))
+}
 
 // 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' }))]
+  ...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 {
   pillar_candidates: byAspect.pillars ?? [],
   subsystems: subsystems.map((s) => s.name),
-  candidates: enriched.map((c, i) => ({
-    line: `- cand-${String(startNum + i).padStart(3, '0')} | ${c.name} | route: soft | sys: ${c.systems[0] ?? 'unassigned'} | deps: - | src: ${c.anchor}${c.gaps.length ? ` | gaps: ${c.gaps.join(', ')}` : ''}`,
+  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(', ')}` : ''}`,
     crossings: pairs.filter((p) => p.a === c || p.b === c).length,
   })),
   envelopes,