gcf-harness-aif-ext 0.4.0 → 0.5.1

package/README.md

@@ -11,7 +11,7 @@ The harness turns policy-as-text into an executable pipeline. It has **no memory
 
 ## Requirements
 
-- [`gcf-aif-ext`](../gcf-aif-ext) `^0.3.0` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
+- [`gcf-aif-ext`](../gcf-aif-ext) `^0.4.1` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
 - Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
 - AI Factory 2.x, Node.js ≥ 22.14
 
@@ -43,6 +43,12 @@ 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.
 
+0.5.0 drives work items (`gcf/work/<id>.md`, schema 3) instead of cards and requires `gcf-aif-ext` 0.4.0 — update both together; against an older core the gate refuses with `gcf-aif-ext >= 0.4.0 is required`. A project still holding schema 2 cards in `gcf/cards/` re-creates them first (see the core's "Upgrading from 0.3.x"). What changes for you: `/gcf-run` takes ids of items in `ready`; it no longer stops at `built` but ends each item with `submit`, `close` or `block`; the plan is improved in passes until it converges; the WIP cap counts only items that end waiting for a verdict.
+
+0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
+
+0.4.1 is a patch release. `/gcf-run` now commits the implementation first, then flips the card to `built` in a second commit, with `built_at` set to the implementation commit's hash. Update the core to 0.3.1 together with the harness: without it, an audit run before a verdict makes the pre-commit gate refuse that verdict.
+
 To remove the extension:
 
 ```bash
@@ -53,9 +59,9 @@ Removal does not touch `.claude/settings.json`: delete the `PreToolUse` entry wh
 
 ## 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 <item-id…>`** — drives work items through plan, implementation and DoD, with every gate checked *before* the tokens are spent: the audit ritual, the gate below, the context budget. The plan is written by `aif-plan`, then improved in passes, each by a fresh subagent that reads only the plan and the readset and records every default it picks; `ai-factory gcf plan check <id>` runs after each pass, and a pass that changes no task ends the loop. A plan still changing after `plan_passes` passes, or a question only the human can answer (a save format, a public API, a new dependency, a pillar conflict), blocks the item before any code is written. The DoD is the project's `dod.test` and `dod.build` commands from `gcf/config.yml` plus a review by a fresh subagent, up to `dod_attempts` attempts. Every item ends in a state the core records: `gcf submit` (gate `verdict` or `decision` — waits for the human), `gcf close` (gate `auto` — done, or a soft unit closed as `unplayed`) or `gcf block` with the reason. The verdict and the decision belong to the human: the pipeline stops at `submit` and prints the playtest list.
 
-**`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.
+**`ai-factory gcf-harness gate <item-id…>`** — the `/gcf-run` gate as code. It reads one `gcf audit --json` report and exits 1 with a one-line reason when the items may not go: a core older than 0.4.0, a `schema:` other than 1 in `gcf/config.yml`, an id with no work item, a feature (run its children; the feature closes when they are finished), an item that is not `ready`, an unplayed dependency, no WIP room for the batch (items awaiting a verdict + the batch's `gate: verdict` items over `wip_built_limit`), or two items of the batch touching the same system unless both say `parallel: ok`. The tune limit is not a gate rule: `verdict tune` itself refuses at the limit, and an item tuned up to it still gets its last build. The skill runs it and stops on a non-zero exit — no model compares the numbers.
 
 **`/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.
 

package/commands/harness.js

@@ -15,38 +15,56 @@ 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 — take the unit into work first (/gcf-card)`;
-  if (!['proposed', 'tuning'].includes(card.status)) {
-    return `${id} is ${card.status} — only proposed and tuning cards are driven`;
+/** Why one work item may not go, or null. */
+function itemProblem(id, item, report) {
+  if (!item) return `${id} has no work item — take the unit or create the item first (/gcf-card)`;
+  if (item.type === 'feature') {
+    return `${id} is a feature — run its children, the feature closes when they are finished`;
   }
 
-  // A dependency inside the same batch lands here too: the dependent waits for its verdict.
+  if (item.status !== 'ready') {
+    return `${id} is ${item.status} — only ready items are driven`;
+  }
+
+  // A child of a feature paused after a death does not start: the decision may kill it.
+  const parent = item.parent ? report.items.find((p) => p.id === item.parent) : null;
+  if (parent?.status === 'awaiting-decision') {
+    return `${id}: its feature ${parent.id} awaits a decision — decide it first`;
+  }
+
+  // A dependency inside the same batch lands here too: the dependent waits for it.
   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`;
+  if (open) {
+    return (
+      `${id} depends on unplayed ${open.depends.join(', ')} — playtest them first; ` +
+      'a killed one never plays: take it out of depends, or drop'
+    );
   }
 
+  // The tune limit is held by `verdict tune` itself: an item tuned up to the limit is still
+  // built once more, and refusing that run would leave it stuck in ready.
   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) {
+function batchProblem(items, wip) {
+  // Only an item that ends waiting for a verdict takes a WIP place; `wip.over` is false at
+  // count === limit, and this run adds every such item of the batch.
+  const waiting = items.filter((i) => i.gate === 'verdict').length;
+  if (waiting && wip.count + waiting > wip.limit) {
     return (
-      `WIP: ${wip.count} built + ${cards.length} in this run exceeds the limit of ${wip.limit}` +
-      ' — playtest first'
+      `WIP: ${wip.count} awaiting a verdict + ${waiting} 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}`;
+  for (let i = 0; i < items.length; i++) {
+    for (const other of items.slice(i + 1)) {
+      const shared = items[i].system.filter((s) => other.system.includes(s));
+      // `parallel: ok` on both is the operator's explicit permission (Methodology §7).
+      const allowed = items[i].parallel === 'ok' && other.parallel === 'ok';
+      if (shared.length && !allowed) {
+        const pair = `${items[i].id} and ${other.id}`;
 
         return `${pair} both touch ${shared.join(', ')} — run them separately`;
       }
@@ -59,12 +77,12 @@ function batchProblem(cards, wip) {
 const verdict = (reason) => ({ pass: !reason, reason: reason ?? '' });
 
 /**
- * Decides whether the cards may enter the paid stages, from one `gcf audit --json` report.
+ * Decides whether the work items 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 (!Array.isArray(report?.items)) {
+    return verdict('the audit report has no work item summary — gcf-aif-ext >= 0.4.0 is required');
   }
 
   if (report.schema !== SCHEMA) {
@@ -73,9 +91,9 @@ export function gate(report, ids) {
     return verdict(`gcf/config.yml has schema: ${report.schema}; ${drives}`);
   }
 
-  const byId = new Map(report.cards.map((c) => [c.id, c]));
+  const byId = new Map(report.items.map((c) => [c.id, c]));
   for (const id of ids) {
-    const problem = cardProblem(id, byId.get(id), report);
+    const problem = itemProblem(id, byId.get(id), report);
     if (problem) return verdict(problem);
   }
 
@@ -216,7 +234,7 @@ export function register(program) {
 
   harness
     .command('gate <ids...>')
-    .description('Gate cards before the paid stages of /gcf-run: exit 1 with the reason')
+    .description('Gate work items 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.4.0",
+  "version": "0.5.1",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/hooks/readset-guard.js

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

package/package.json

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

package/skills/gcf-run/SKILL.md

@@ -1,35 +1,49 @@
 ---
 name: gcf-run
-description: Drive one or more GCF units from the 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".
+description: Drive one or more GCF work items through plan, implement and DoD in a single run - gates before tokens, a converging plan, readset discipline, then submit, close or block. Use when the user says "прогони задачу" / "прогони карточку" / "run the item".
 ---
 
 mode: pipeline
 
 purpose:
-- drive a card through gate, readset, plan, implement and build with the stop rules checked before each paid stage
+- drive a work item through gate, readset, plan, implement and its DoD with the stop rules checked before each paid stage
+- end every item in a state the core records: `submit` (waits for the human), `close` (gate auto, done) or `block` (needs the human)
 
 inputs:
-- 1 or more unit or card ids; a batch shares one build and one playtest list
+- 1 or more work item or design unit 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 give a verdict or a decision: `verdict` and `decide` belong to the human, this pipeline stops at `submit`
 - 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 compare the audit numbers yourself: the gate command is the only judge of whether a card may go
+- do not compare the audit numbers yourself: the gate command is the only judge of whether an item may go
+- do not ask the human about a reversible choice during planning: pick the safe default and write it into the plan
+- do not edit `status:` or `gcf/LIVE.md` by hand: `submit`, `close` and `block` own them
 
 workflow:
-1. session ritual: delete a `.gcf-session/readset.json` left by a killed run; run `ai-factory gcf audit --json`; read `gcf/INDEX.md`; stale built cards with live dependents mean stop - print the playtest list instead of building
-2. for a unit still in `gcf/design/`: take it with the gcf-card skill; a hard unit leaves the pipeline for the normal AIF cycle here
-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
-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
+1. session ritual: delete a `.gcf-session/readset.json` left by a killed run; run `ai-factory gcf audit --json`; read `gcf/INDEX.md`; report the audit first line to the human
+2. for a unit still in `gcf/design/`: take it with the gcf-card skill first
+3. for a feature id: replace it with its `ready` children from the audit report's `items` (`parent` names the feature) that are not in `open_depends`; a feature in `awaiting-decision` starts none of them
+4. of those children, keep one per subsystem unless every child sharing it says `parallel: ok`; the rest wait for the next run; an empty list: report "nothing to run" and stop
+5. gate: run `ai-factory gcf-harness gate <item-ids...>` over the whole batch; a non-zero exit is a failed gate, its stderr line is the reason
+6. readset: run `ai-factory gcf context <item-id> --json`; write `{"item":"<id>","files": ctx.files.map(f => f.path)}` to `.gcf-session/readset.json` - paths, not objects; `over_budget: true` stops the run with a D1 question naming the subsystem
+7. plan: run aif-plan full for the item into its `plan:` path, by default `.ai-factory/plans/<id>.md`, reading only the readset files; an existing plan (the item came back after a tune, an unblock or a continue) is kept, not rewritten
+8. improve the plan in passes, each pass a fresh subagent that reads only the plan and the readset and applies aif-improve without questions, writing each default it picks into the plan
+9. each pass also checks every task against the `invariant` of each pillar in `gcf/PILLARS.md`: the pass reworks a task that breaks one, and a conflict no rework removes is a pillar conflict of step 12
+10. after each pass run `ai-factory gcf plan check <id>`; a failure blocks the item with its reason; a pass that changes no task ends the loop - the plan converged
+11. passes <= `plan_passes` from `gcf/config.yml` (5 by default); a plan still changing after the last pass: run `ai-factory gcf block <id> --reason "plan did not converge"` and stop
+12. a question only the human can answer - a save format, a public API, a new dependency, a pillar conflict: run `ai-factory gcf block <id> --reason "<question>"` and stop
+13. implement with aif-implement, then verify: the project's `dod.test` and `dod.build` commands from `gcf/config.yml`, plus the item's negative constraints; attempts <= `dod_attempts`, each with a diagnosis
+14. review the diff with a fresh subagent; fix what it finds before the commit; DoD still red after the attempts: commit nothing, run `ai-factory gcf block <id> --reason "<diagnosis>"`
+15. the reviewer also answers the `review_question` of each pillar in `gcf/PILLARS.md` over the diff: an answer that breaks the pillar is a finding
+16. commit the implementation via aif-commit; write the item's `live:` delta
+17. gate `verdict` or `decision`: run `ai-factory gcf submit <id>`; gate `auto`: run `ai-factory gcf close <id>` - a soft unit closes unplayed
+18. a dependency still waiting for its verdict refuses the close: run `ai-factory gcf block <id> --reason "waits for <dep>"`
+19. close the run: delete `.gcf-session/readset.json`, run `ai-factory gcf playtest` and hand the list to the human, with one report row per plan pass: pass, tasks changed, result
+20. after a tune verdict or an unblock, re-enter this pipeline at step 5: the gates re-run because the counters moved
 
 invocation:
-- run when the user names a card or a unit to drive; batches share steps 1 and 8
+- run when the user names a work item or a unit to drive; batches share steps 1 and 19

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

@@ -15,7 +15,7 @@ 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 design units, a card exists only when `/gcf-card` takes one
+- do not create work items: the package holds design units, a work item exists only when `/gcf-card` takes one
 - 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

package/workflows/ingest.js

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