gcf-harness-aif-ext 0.5.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.4.0` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
+- [`gcf-aif-ext`](../gcf-aif-ext) `^0.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
 
@@ -45,6 +45,8 @@ Updating keeps the hook entry valid — it points into the extension's install d
 
 0.5.0 drives work items (`gcf/work/<id>.md`, schema 3) instead of cards and requires `gcf-aif-ext` 0.4.0 — update both together; against an older core the gate refuses with `gcf-aif-ext >= 0.4.0 is required`. A project still holding schema 2 cards in `gcf/cards/` re-creates them first (see the core's "Upgrading from 0.3.x"). What changes for you: `/gcf-run` takes ids of items in `ready`; it no longer stops at `built` but ends each item with `submit`, `close` or `block`; the plan is improved in passes until it converges; the WIP cap counts only items that end waiting for a verdict.
 
+0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
+
 0.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:

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-harness-aif-ext",
-  "version": "0.5.0",
+  "version": "0.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,
@@ -94,7 +104,7 @@ export function decide(input, projectDir, manifest) {
   // The gcf root itself relativizes to '' — unguarded it becomes 'gcf/' and matches nothing.
   const relPosix = relFromGcf.replaceAll('\\', '/');
 
-  return insideVerdict(relPosix ? `gcf/${relPosix}` : 'gcf', manifest);
+  return insideVerdict(relPosix ? `gcf/${relPosix}` : 'gcf', manifest, input.tool_name);
 }
 
 function readManifest(projectDir) {

package/package.json

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

package/skills/gcf-run/SKILL.md

@@ -32,16 +32,18 @@ workflow:
 6. readset: run `ai-factory gcf context <item-id> --json`; write `{"item":"<id>","files": ctx.files.map(f => f.path)}` to `.gcf-session/readset.json` - paths, not objects; `over_budget: true` stops the run with a D1 question naming the subsystem
 7. plan: run aif-plan full for the item into its `plan:` path, by default `.ai-factory/plans/<id>.md`, reading only the readset files; an existing plan (the item came back after a tune, an unblock or a continue) is kept, not rewritten
 8. improve the plan in passes, each pass a fresh subagent that reads only the plan and the readset and applies aif-improve without questions, writing each default it picks into the plan
-9. after each pass run `ai-factory gcf plan check <id>`; a failure blocks the item with its reason; a pass that changes no task ends the loop - the plan converged
-10. passes <= `plan_passes` from `gcf/config.yml` (5 by default); a plan still changing after the last pass: run `ai-factory gcf block <id> --reason "plan did not converge"` and stop
-11. a question only the human can answer - a save format, a public API, a new dependency, a pillar conflict: run `ai-factory gcf block <id> --reason "<question>"` and stop
-12. implement with aif-implement, then verify: the project's `dod.test` and `dod.build` commands from `gcf/config.yml`, plus the item's negative constraints; attempts <= `dod_attempts`, each with a diagnosis
-13. review the diff with a fresh subagent; fix what it finds before the commit; DoD still red after the attempts: commit nothing, run `ai-factory gcf block <id> --reason "<diagnosis>"`
-14. commit the implementation via aif-commit; write the item's `live:` delta
-15. gate `verdict` or `decision`: run `ai-factory gcf submit <id>`; gate `auto`: run `ai-factory gcf close <id>` - a soft unit closes unplayed
-16. a dependency still waiting for its verdict refuses the close: run `ai-factory gcf block <id> --reason "waits for <dep>"`
-17. close the run: delete `.gcf-session/readset.json`, run `ai-factory gcf playtest` and hand the list to the human, with one report row per plan pass: pass, tasks changed, result
-18. after a tune verdict or an unblock, re-enter this pipeline at step 5: the gates re-run because the counters moved
+9. each pass also checks every task against the `invariant` of each pillar in `gcf/PILLARS.md`: the pass reworks a task that breaks one, and a conflict no rework removes is a pillar conflict of step 12
+10. after each pass run `ai-factory gcf plan check <id>`; a failure blocks the item with its reason; a pass that changes no task ends the loop - the plan converged
+11. passes <= `plan_passes` from `gcf/config.yml` (5 by default); a plan still changing after the last pass: run `ai-factory gcf block <id> --reason "plan did not converge"` and stop
+12. a question only the human can answer - a save format, a public API, a new dependency, a pillar conflict: run `ai-factory gcf block <id> --reason "<question>"` and stop
+13. implement with aif-implement, 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 work item or a unit to drive; batches share steps 1 and 17
+- run when the user names a work item or a unit to drive; batches share steps 1 and 19

package/workflows/ingest.js

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