gcf-harness-aif-ext 0.3.4 → 0.4.0

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.2.7` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
+- [`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
 - Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
 - AI Factory 2.x, Node.js ≥ 22.14
 

package/commands/harness.js

@@ -17,7 +17,7 @@ const SESSION_RULE = /^(\/|\*\*\/)?\.gcf-session\/?$/;
 
 /** Why one card may not go, or null. */
 function cardProblem(id, card, report) {
-  if (!card) return `${id} has no card file — materialize the candidate first`;
+  if (!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`;
   }

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-harness-aif-ext",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/package.json

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

package/skills/gcf-run/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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".
+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".
 ---
 
 mode: pipeline
@@ -9,7 +9,7 @@ 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
+- 1 or more unit or card 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)
@@ -22,7 +22,7 @@ forbidden_behaviors:
 
 workflow:
 1. session ritual: delete a `.gcf-session/readset.json` left by a killed run; run `ai-factory gcf audit --json`; read `gcf/INDEX.md`; stale built cards with live dependents mean stop - print the playtest list instead of building
-2. for a cand-NNN input: materialize it with the gcf-card skill; a hard route leaves the pipeline for the normal AIF cycle here
+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
@@ -32,4 +32,4 @@ workflow:
 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
+- run when the user names a card or a unit to drive; batches share steps 1 and 8

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

@@ -1,6 +1,6 @@
 ---
 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 "запусти импорт воркфлоу".
+description: Fan-out GDD import on Claude Code dynamic workflows - parallel extraction and lenses, design units in one package. Use for a large GDD or when the user says "запусти импорт воркфлоу".
 ---
 
 mode: orchestrated import
@@ -15,22 +15,24 @@ 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 create card files: the package holds design units, a card 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
 
 workflow:
 1. run `ai-factory gcf anchor <file> --json` and keep the sections list
-2. on a re-import the output carries `delta`: keep only the sections whose anchor is in `delta.added`, skip the workflow when none are left, and apply the other delta classes as step 11 of the gcf-ingest skill does
+2. on a re-import the output carries `delta`: keep only the sections whose anchor is in `delta.added`, skip the workflow when none are left, and apply the other delta classes as step 17 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 minted ids; fold each `exact` number into the description of the line citing its anchor
-6. append the D1 and D2 records to `gcf/open-questions.md` in the record form the gcf-ingest skill states under outputs, a D2 with its `assumed:` and `until:`
-7. run `ai-factory gcf quotes` and move each flagged line to a D1 with lens `provenance`, then run `ai-factory gcf index`
-8. mark a candidate whose nouns match the `purpose` or the `code` paths of an existing systems doc with `impl?`; with `gcf/systems/` empty on a codebase, report the marks as blind
-9. report the package in the GCF order: D1 questions first, pillar candidates, backlog summary with the top crossing candidates, D2 envelope assumptions
-10. verify equivalence on the first real GDD: compare this package against a sequential `/gcf-ingest` pass and report any divergence as a harness bug
+4. run `ai-factory gcf where --json` and keep every listed id as `taken`: an import never mints an id the project has used
+5. invoke the Workflow tool with scriptPath `.ai-factory/extensions/gcf-harness-aif-ext/workflows/ingest.js` and args `{sections, spread, taken}`
+6. append each unit's `section` to `gcf/design/<system>.md`; start a missing file with `# <system>` and `purpose: TBD`; append `- <id>` per unit to `gcf/backlog.md`
+7. write each envelope into a `feel` record of the unit citing its anchor, with `assumed: q-NNN` beside its quote; write each `exact` number as a closing comparison into that unit
+8. append the D1 and D2 records to `gcf/open-questions.md` in the record form the gcf-ingest skill states under outputs, a D2 with its `assumed:` and `until:`
+9. run `ai-factory gcf design check` and fix every blocking finding: a digit in prose becomes a comparison or words, a misquote becomes a D1 with lens `provenance`
+10. mark a unit whose nouns match the `purpose` or the `code` paths of an existing systems doc with `flags: impl?`; with `gcf/systems/` empty on a codebase, report the marks as blind
+11. report the package in the GCF order: D1 questions first, pillar candidates, the design summary per subsystem with the top crossing units, D2 envelope assumptions
+12. verify equivalence on the first real GDD: compare this package against a sequential `/gcf-ingest` pass and report any divergence as a harness bug
 
 invocation:
 - run when the user asks for the workflow import on a GDD

package/workflows/ingest.js

@@ -4,12 +4,12 @@ export const meta = {
     'Fan-out GDD import: parallel aspect extraction, code-verified provenance, lenses, one package',
   phases: [
     { title: 'Extract', detail: 'one agent per aspect per segment of the anchored sections' },
-    { title: 'Lenses', detail: 'completeness per candidate, coherence over the whole set' },
+    { title: 'Lenses', detail: 'route and id per unit, coherence over the whole set' },
     { title: 'Conflicts', detail: 'pairwise checks where the interaction matrix crosses' },
   ],
 };
 
-// args: { sections: [{anchor, heading, body}], spread, start_num, segment_chars? }
+// args: { sections: [{anchor, heading, body}], spread, taken?: string[], segment_chars? }
 // The main thread runs `ai-factory gcf anchor --json` BEFORE this workflow and writes
 // the outputs AFTER it — the script has no filesystem, by design (Harness-PRD §6.1).
 // Layout: schemas, then pure helpers, then the three phases, then package assembly.
@@ -47,8 +47,17 @@ const UNITS = {
 const CAND_LENS = {
   type: 'object',
   properties: {
-    gaps: strings('missing answers: state, input, feedback, refusal, boundaries, persistence'),
-    systems: strings('subsystem slugs this candidate touches'),
+    id: {
+      type: 'string',
+      pattern: '^[a-z0-9]+(-[a-z0-9]+)*$',
+      description:
+        'the unit id: a short lowercase latin hyphen slug of its name, frozen once written',
+    },
+    systems: {
+      type: 'array',
+      items: { type: 'string', pattern: '^[a-z0-9]+(-[a-z0-9]+)*$' },
+      description: 'subsystem slugs this unit touches, the one it lives in first',
+    },
     state_written: strings('named state this mechanic writes'),
     route: {
       enum: ['soft', 'hard'],
@@ -59,7 +68,7 @@ const CAND_LENS = {
     },
     route_why: { type: 'string', description: 'the reason for the route, one short clause' },
   },
-  required: ['gaps', 'systems', 'state_written', 'route', 'route_why'],
+  required: ['id', 'systems', 'state_written', 'route', 'route_why'],
 };
 
 const FINDING = {
@@ -203,21 +212,56 @@ function crossingPairs(cands) {
   return pairs;
 }
 
-/** The backlog line grammar `gcf index` parses (GCF-PRD §5.2). */
-function candidateLine(c, deps) {
-  const fields = [
-    `- ${c.id}`,
-    c.name,
-    `route: ${c.route === 'hard' ? 'hard' : 'soft'} (${c.route_why || 'acceptance is a playtest'})`,
-    `sys: ${c.systems[0] ?? 'unassigned'}`,
-    `deps: ${deps.join(', ') || '-'}`,
-    `src: ${c.anchor}`,
-    `q: "${c.quote}"`,
-  ];
-  if (c.gaps.length) fields.push(`gaps: ${c.gaps.join(', ')}`);
-  fields.push(c.detail || c.name);
-
-  return fields.join(' | ');
+/** 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';
+  let id = base;
+  for (let n = 2; taken.has(id); n++) id = `${base}-${n}`;
+  taken.add(id);
+
+  return id;
+}
+
+// Every slot the GDD did not answer reads TBD: the questions come when /gcf-card takes the unit.
+const SOFT_SLOTS = ['behavior', 'refusal', 'boundaries', 'persistence', 'feel_like', 'feel'];
+
+/**
+ * The `## <id>` section of a unit in gcf/design/<system>.md (GCF-PRD §5.7): a player verb is
+ * a soft mechanic, an acceptance an autotest gives is a hard rule. Only the quote is the GDD's.
+ */
+function unitSection(c, depends) {
+  const hard = c.route === 'hard';
+  const why = c.route_why || (hard ? 'an autotest accepts it' : 'acceptance is a playtest');
+  const slot = hard ? 'statement' : 'intent';
+  const body = hard
+    ? ['statement:', `- ${c.detail || c.name}`, '', 'check: TBD']
+    : [
+        'intent:',
+        `- ${c.detail || c.name}`,
+        ...SOFT_SLOTS.map((s) => `\n${s}: TBD`),
+        '\nconstraints: TBD',
+        '\nmiss_criterion: TBD',
+      ];
+
+  return [
+    `## ${c.id}`,
+    '',
+    `type: ${hard ? 'rule' : 'mechanic'}`,
+    `title: ${c.name}`,
+    `route: ${hard ? 'hard' : 'soft'} (${why})`,
+    `system: [${(c.systems.length ? c.systems : ['unassigned']).join(', ')}]`,
+    'milestone: TBD',
+    'pillars: TBD',
+    `depends: ${depends.length ? `[${depends.join(', ')}]` : 'none'}`,
+    `source: ${c.anchor}`,
+    '',
+    ...body,
+    '',
+    'provenance:',
+    `- slot: ${slot}`,
+    `  src: ${c.anchor}`,
+    `  quote: "${c.quote}"`,
+  ].join('\n');
 }
 
 // ─── Prompts ─────────────────────────────────────────────────────────────────────────
@@ -234,8 +278,8 @@ function extractPrompt(aspect, segment, part, parts) {
 
 function lensPrompt(c, subsystemNames, sectionBody) {
   return [
-    'Completeness lenses over one feature candidate, and its route with the reason.',
-    `Candidate: ${c.name} (${c.anchor}: "${c.quote}").`,
+    'One feature unit: its route with the reason, its subsystems, the state it writes, its id.',
+    `Unit: ${c.name} (${c.anchor}: "${c.quote}").`,
     `Known subsystems: ${subsystemNames.join(', ') || 'none yet'}.`,
     'Section:',
     sectionBody,
@@ -295,10 +339,9 @@ async function ask(prompt, opts) {
 
 const sections = args.sections;
 const spread = args.spread ?? 0.3;
-// Candidate ids continue the existing backlog numbering: minting from the array index
-// makes every re-ingest emit cand-001 again. Number(): args come from a model-composed
-// call, and "5" would concatenate.
-const startNum = Number(args.start_num) || 1;
+// 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 bodyOf = new Map(sections.map((s) => [s.anchor, s.body]));
 const multi = segments.length > 1;
@@ -333,10 +376,7 @@ const enriched = await pipeline(candidates, (c) =>
     schema: CAND_LENS,
   }).then((r) => ({ ...c, ...r })),
 );
-const cands = enriched.map((c, i) => ({
-  ...c,
-  id: `cand-${String(startNum + i).padStart(3, '0')}`,
-}));
+const cands = enriched.map((c) => ({ ...c, id: freeId(c.id, taken) }));
 
 // No sections at all also takes the digest path: there is no segment to attach.
 const wholeDoc = segments.length === 1 ? segments[0].texts.join('\n\n') : citedDigest(byAspect);
@@ -394,7 +434,7 @@ const envelopeQuestions = envelopes
     question: `"${e.name}": "${e.quote}" taken as the envelope ${e.envelope}`,
     proposed: e.envelope,
     assumed: `±${Math.round(spread * 100)}% around the cited number`,
-    until: `manual(materialization of the candidate citing ${e.anchor})`,
+    until: `manual(materialization of the unit citing ${e.anchor})`,
   }));
 // GCF-PRD §11.2: the GDD's own open questions are the designer's gaps, said out loud.
 const gddQuestions = (byAspect.questions ?? []).map((u) => ({
@@ -415,13 +455,15 @@ const questions = [
 const result = {
   pillar_candidates: byAspect.pillars ?? [],
   subsystems: subsystemNames,
-  candidates: cands.map((c) => ({
-    line: candidateLine(c, deps[c.id]),
+  units: cands.map((c) => ({
+    id: c.id,
+    system: c.systems[0] ?? 'unassigned',
+    section: unitSection(c, deps[c.id]),
     crossings: pairs.filter((p) => p.a === c || p.b === c).length,
   })),
   envelopes: envelopes.filter((e) => e.envelope),
-  // Counts, hard limits and thresholds stay exact: the write step folds each into the
-  // description of the candidate citing the same anchor.
+  // Counts, hard limits and thresholds stay exact: the write step writes each as a closing
+  // comparison into the unit citing the same anchor.
   exact: envelopes.filter((e) => !e.envelope),
   d1: questions.filter((q) => q.class === 'D1'),
   d2: questions.filter((q) => q.class === 'D2'),