gcf-harness-aif-ext 0.4.0 → 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.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.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 — 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.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.4.0",
+  "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.3.0"
+    "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 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. 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 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 17

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