gcf-harness-aif-ext 0.3.4 → 0.5.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.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
 - Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
 - AI Factory 2.x, Node.js ≥ 22.14
 
@@ -43,6 +43,10 @@ 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.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 +57,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 — materialize the candidate first`;
-  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.3.4",
+  "version": "0.5.0",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/hooks/readset-guard.js

@@ -72,7 +72,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.',
   };
 }

package/package.json

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

package/skills/gcf-run/SKILL.md

@@ -1,35 +1,47 @@
 ---
 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 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 cand-NNN or card-NNN 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 cand-NNN input: materialize it with the gcf-card skill; a hard route 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. 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
 
 invocation:
-- run when the user names a card or candidate 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 17

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 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
 
 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'),