gcf-harness-aif-ext 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleg (VirtualMaestro)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# gcf-harness-aif-ext
+
+Claude-Code-specific orchestration for the [Game Context Framework](../gcf-aif-ext). Optional: GCF works without it, by hand.
+
+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.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
+- Claude Code 2.1.270+ (hooks, dynamic workflows)
+- AI Factory 2.x, Node.js ≥ 22.14
+
+## Install
+
+```bash
+ai-factory extension add <path-to>/packages/gcf-harness-aif-ext
+ai-factory gcf-harness install   # registers the readset-guard hook
+```
+
+## 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.
+
+## Docs
+
+[Harness-PRD](https://github.com/VirtualMaestro/GCF/blob/main/docs/Harness-PRD.md) is the spec: pipeline stages, gates, execution surfaces, the guard's contract.
+
+## License
+
+MIT

package/commands/harness.js

@@ -0,0 +1,67 @@
+// `ai-factory gcf-harness install` — 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';
+import { existsSync } from 'node:fs';
+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';
+
+/**
+ * The harness holds no code of the core: it calls `ai-factory gcf …` and writes gcf/.
+ * That contract is invisible to npm, so the check happens here, at install time — and
+ * inside the action, because extensions register in an order nobody controls.
+ * An unreadable command list means the CLI shape is unknown, not that the core is absent.
+ */
+function coreMissing(program) {
+  if (!Array.isArray(program?.commands)) return false;
+  return !program.commands.some((c) => (typeof c?.name === 'function' ? c.name() : c?.name) === 'gcf');
+}
+
+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)')
+    .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 already = JSON.stringify(settings.hooks.PreToolUse).includes(MARKER);
+      if (!already) {
+        settings.hooks.PreToolUse.push({
+          matcher: 'Read|Grep|Glob',
+          hooks: [{ type: 'command', command: `node "${guard}" # ${MARKER}` }],
+        });
+        await mkdir(path.dirname(settingsFile), { recursive: true });
+        await writeFile(settingsFile, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+        console.log(`readset-guard registered → ${settingsFile}`);
+      } else {
+        console.log('readset-guard already registered');
+      }
+
+      const gitignore = path.join(projectDir, '.gitignore');
+      const line = '.gcf-session/';
+      const has = existsSync(gitignore) && (await readFile(gitignore, 'utf8')).includes(line);
+      if (!has) await appendFile(gitignore, `\n${line}\n`, 'utf8');
+    });
+}

package/extension.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
+  "name": "gcf-harness-aif-ext",
+  "version": "0.1.1",
+  "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
+  "skills": [
+    "skills/gcf-run",
+    "skills/gcf-run-ingest"
+  ],
+  "commands": [
+    { "name": "gcf-harness", "description": "GCF harness setup", "module": "commands/harness.js" }
+  ]
+}

package/hooks/readset-guard.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Readset guard (Harness-PRD §7): a PreToolUse hook for Read/Grep/Glob. While a run
+// manifest exists at .gcf-session/readset.json, paths inside gcf/ that are not in the
+// readset are denied (exit 2, reason on stderr — Claude Code shows it to the agent).
+// No manifest → silent allow (manual work is never restricted). Paths outside gcf/
+// are never touched, and neither is a search that cannot reach gcf/ — the project's own
+// code stays freely greppable. Honest limit: Bash `cat` bypasses this; it is a discipline
+// tool for a solo developer, not a security perimeter.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+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 };
+    return {
+      allow: false,
+      reason: 'an unscoped Grep reads the contents of all of gcf/ — pass `path:` or a `glob:` that scopes the search.',
+    };
+  }
+
+  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';
+  // `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 {
+    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 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);
+  if (!verdict.allow) {
+    console.error(`gcf readset-guard: ${verdict.reason}`);
+    process.exit(2);
+  }
+  process.exit(0);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "gcf-harness-aif-ext",
+  "version": "0.1.1",
+  "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
+  "type": "module",
+  "license": "MIT",
+  "author": "Oleg (VirtualMaestro)",
+  "aiFactoryCompatibility": ">=2.0.0 <3.0.0",
+  "keywords": [
+    "ai-factory",
+    "gcf",
+    "harness",
+    "extension"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VirtualMaestro/GCF.git"
+  },
+  "homepage": "https://github.com/VirtualMaestro/GCF#readme",
+  "bugs": {
+    "url": "https://github.com/VirtualMaestro/GCF/issues"
+  },
+  "engines": {
+    "node": ">=22.14"
+  },
+  "scripts": {
+    "test": "node --test",
+    "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"
+  },
+  "files": [
+    "extension.json",
+    "skills",
+    "commands",
+    "hooks",
+    "workflows",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/skills/gcf-run/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: gcf-run
+description: Drive one or more GCF cards from backlog to built in a single run - gates before tokens, readset discipline, playtest list at the end. Use when the user says "прогони карточку" / "run the card".
+---
+
+mode: pipeline
+
+purpose:
+- drive a card through gate, readset, plan, implement and build with the stop rules checked before each paid stage
+
+inputs:
+- 1 or more cand-NNN or card-NNN ids; a batch shares one build and one playtest list
+
+preconditions:
+- `gcf/` exists and `ai-factory gcf audit` runs (the gcf-aif-ext extension provides it)
+
+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 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
+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
+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
+7. build the project; flip the card frontmatter to `status: built` with `built_at:` set to the implementation commit hash, commit via aif-commit
+8. close the run: delete `.gcf-session/readset.json`, run `ai-factory gcf playtest` and hand the list to the human
+9. after a tune verdict, re-enter this pipeline at step 3: the gates re-run because the counters moved
+
+invocation:
+- run when the user names a card or candidate to drive; batches share steps 1 and 8

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

@@ -0,0 +1,32 @@
+---
+name: gcf-run-ingest
+description: Fan-out GDD import on Claude Code dynamic workflows - parallel extraction and lenses, one output package. Use for a large GDD or when the user says "запусти импорт воркфлоу".
+---
+
+mode: orchestrated import
+
+purpose:
+- run the gcf-ingest pipeline as a dynamic workflow: minutes of fan-out instead of hours of one agent
+
+inputs:
+- a path to the GDD (markdown); the sequential `/gcf-ingest` skill stays the correctness reference
+
+preconditions:
+- `gcf/` exists; the user has opted into multi-agent orchestration (the Workflow tool requires it)
+
+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
+
+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)
+
+invocation:
+- run when the user asks for the workflow import on a GDD

package/workflows/ingest.js

@@ -0,0 +1,167 @@
+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: '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 }
+// 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).
+
+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
+const gddText = sections.map((s) => `[${s.anchor}] ${s.heading ?? '(preamble)'}\n${s.body}`).join('\n\n')
+
+const UNITS = {
+  type: 'object',
+  properties: {
+    units: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          anchor: { type: 'string' },
+          quote: { type: 'string', description: 'verbatim substring of the source section' },
+          detail: { type: 'string' },
+        },
+        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 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 ?? [] })),
+  // 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) {
+      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 = Object.fromEntries(extracted.filter(Boolean).map((r) => [r.aspect, r.cited]))
+const inferred = extracted.filter(Boolean).flatMap((r) => r.inferred)
+const candidates = byAspect.features ?? []
+const subsystems = byAspect.subsystems ?? []
+log(`${candidates.length} candidates, ${inferred.length} inferred units diverted to questions`)
+
+// Numbers → envelopes: value ± spread, assumed. Deterministic transformation.
+const envelopes = (byAspect.numbers ?? []).map((u) => {
+  const m = (u.detail ?? u.quote).match(/(\d+(?:[.,]\d+)?)\s*([a-zA-Zа-яё%]*)/)
+  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 }
+})
+
+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' },
+  },
+  required: ['gaps', 'systems', 'state_written'],
+}
+const perCandidate = 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 ?? ''}`,
+    { label: `lens:${c.name}`, phase: 'Lenses', schema: CAND_LENS },
+  ).then((r) => r && { ...c, ...r }),
+)
+
+const enriched = perCandidate.filter(Boolean)
+const FINDINGS = {
+  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'],
+      },
+    },
+  },
+  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']
+// 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}`,
+  { label: `lens:${lens.split(':')[0]}`, phase: 'Lenses', schema: FINDINGS },
+)))).filter(Boolean).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`)
+const conflicts = (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)
+
+// 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' }))]
+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(', ')}` : ''}`,
+    crossings: pairs.filter((p) => p.a === c || p.b === c).length,
+  })),
+  envelopes,
+  d1: questions.filter((q) => q.class === 'D1'),
+  d2: questions.filter((q) => q.class === 'D2'),
+  constraints: byAspect.constraints ?? [],
+}