gcf-aif-ext 0.3.0 → 0.4.1

package/README.md

@@ -2,7 +2,9 @@
 
 The Game Context Framework as an [AI Factory](https://github.com/lee-to/ai-factory) extension: a documentary layer for building games with an AI agent, where the documents hold **state instead of history**.
 
-A Design Model: the design lives in `gcf/design/<system>.md` as units with typed slots — what the GDD says, quoted and anchored, and `TBD` for everything it does not. A soft unit taken into work becomes a feature card with the same body; the card collapses into its subsystem's document on a human playtest verdict and then ceases to exist. A hard unit leaves through its tests. A graveyard keeps the reasons things were killed. Read rules keep the token cost of a task flat as the project ages.
+A Design Model: the design lives in `gcf/design/<system>.md` as units with typed slots — what the GDD says, quoted and anchored, and `TBD` for everything it does not. Every piece of work — a mechanic, a bug, tech, an asset, a spike, a release — is a work item `gcf/work/<id>.md` with a `type` and a `gate`: who closes it, the human after play (`verdict`), a check (`auto`), or the human without a build (`decision`). A unit taken into work moves into its item with the same body; a soft unit collapses into its subsystem's document on a human playtest verdict and the item ceases to exist. `gcf/LIVE.md` is a short snapshot of what the game is now — capabilities and known issues. `gcf/inbox.md` holds raw input waiting for triage. A history and a graveyard keep how each id ended and why things were killed. Read rules keep the token cost of a task flat as the project ages.
+
+The methodology is [Methodology.md](https://github.com/VirtualMaestro/GCF/blob/main/docs/Methodology.md) (RU).
 
 Runtime-agnostic — everything here works on any AI Factory runtime. The Claude-Code-specific orchestration lives in [`gcf-harness-aif-ext`](../gcf-harness-aif-ext), which is optional.
 
@@ -22,20 +24,20 @@ ai-factory extension add gcf-aif-ext                        # npm
 # ai-factory extension add ../GCF/packages/gcf-aif-ext      # local checkout
 ```
 
-This installs the 8 skills into each configured runtime, registers the `gcf` command and appends the injections to `aif-plan`, `aif-review` and `aif-commit`. Then set up the project — two steps, run once:
+This installs the 9 skills into each configured runtime, registers the `gcf` command and appends the injections to `aif-plan`, `aif-review` and `aif-commit`. Then set up the project — two steps, run once:
 
 ```bash
-ai-factory gcf init            # seeds gcf/ and cnlp.config.json (PILLARS.md is written by /gcf-init)
+ai-factory gcf init            # seeds gcf/, cnlp.config.json and .gitattributes (PILLARS.md is written by /gcf-init)
 ai-factory gcf hooks-install   # arms the pre-commit gate
 ```
 
-`gcf init` is idempotent: it creates what is missing and overwrites nothing.
+`gcf init` is idempotent: it creates what is missing and overwrites nothing. Among what it seeds: `gcf/work/` for the work items, `gcf/inbox.md` for raw input, `gcf/LIVE.md` for the project snapshot, `gcf/history.md` and `gcf/graveyard.md` — the two files that record how an id's life ended — and three lines in `.gitattributes` (`gcf/history.md merge=union`, `gcf/graveyard.md merge=union`, `gcf/inbox.md merge=union`) so that two branches appending different lines to those files never conflict there.
 
 It then offers the optional [harness](../gcf-harness-aif-ext) — orchestration and a readset guard for **Claude Code only** — and on yes runs `ai-factory extension add gcf-harness-aif-ext` and `ai-factory gcf-harness init`. It asks only in a terminal and only when `.ai-factory.json` lists the Claude Code agent; an agent or CI run is never asked and installs nothing. `--harness` installs it without asking, `--no-harness` skips the question.
 
 `hooks-install` is a separate step because an AI Factory manifest can declare skills, commands and injections but cannot install a git hook — and because arming a gate that can break your commits is your call, not the extension's. It needs a git repository, and it will not overwrite a `pre-commit` it did not write: if husky or lefthook already owns the hook, it prints the one line to chain from it instead. Without the hook GCF still works; nothing enforces it at commit time.
 
-Then `/gcf-vision` for a brand-new game, `/gcf-adopt` for a project that already has code, `/gcf-ingest <gdd.md>` for an existing design doc, or `/gcf-card` to start a feature by hand.
+Then `/gcf-vision` for a brand-new game, `/gcf-adopt` for a project that already has code, `/gcf-ingest <gdd.md>` for an existing design doc, or `/gcf-card` to start work by hand.
 
 ## Upgrade
 
@@ -44,7 +46,50 @@ ai-factory extension update gcf-aif-ext     # pulls the new version
 ai-factory extension update --force         # refresh even if the version is unchanged
 ```
 
-Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook.
+Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-factory gcf init` again after an update: it adds only what a newer version seeds and the project lacks.
+
+On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
+
+### 0.4.1
+
+A fix release over 0.4.0; update in place. What you may notice:
+
+- An unplayed item's `frozen:` now covers its `live:` delta as well as its body. Items closed by 0.4.0 keep working. `tune`, `kill` and `drop` refuse an unplayed item edited since its close: restore the file first.
+- With `PILLARS.md` present, a mechanic or resource with `pillars: TBD` is not ready to `take`. `gcf pillar rename` and `gcf pillar retire` revise a pillar where units and items cite it.
+- `design check` blocks a `depends:` cycle and an id with two terminal lines (a merge of branches).
+- The commit gate refuses a `LIVE.md` ref into `gcf/` that names no file.
+- `gcf init` writes an agent instructions block into `AGENTS.md` (and into a `CLAUDE.md` that does not import it), between `<!-- gcf:start -->` and `<!-- gcf:end -->`. Any agent session then knows where work lives and which commands own it. Run `gcf init` again after an update to refresh it.
+
+### Upgrading from 0.3.x
+
+0.4.0 replaces the cards with work items and does **not migrate** them. A schema 2 card in `gcf/cards/` is no longer read: while any is left there, the pre-commit gate refuses every commit that touches `gcf/`, and `gcf audit` reports it first. In order:
+
+1. Update both extensions together — `gcf-harness-aif-ext` 0.5.0 requires this core — and run `ai-factory gcf init`: it seeds `gcf/work/`, `gcf/inbox.md`, `gcf/LIVE.md` and the `gcf/inbox.md merge=union` line. Your `config.yml` is kept; the new keys `unplayed_warn_after`, `plan_passes` and `dod_attempts` take their defaults, and `dod.test` / `dod.build` (the project's test and build commands) are yours to fill in.
+2. Re-create each card. A 0.3 card is a mechanic or a resource, which `item new` does not create: put its body back as a `## <id>` section in `gcf/design/<system>.md` with a `- <id>` line in `backlog.md`, commit, and run `ai-factory gcf take <id>`. A card that was `built` then goes `ai-factory gcf submit <id>` (its code is in main already); `tune_count` starts at 0 unless you carry it over by hand.
+3. Delete `gcf/cards/` and commit it with the new items.
+
+What else changes: statuses are `ready`, `awaiting-verdict`, `awaiting-decision`, `blocked`, `parked` and `unplayed` (`proposed` and `tuning` are `ready`, `built` is `awaiting-verdict`); `built_at` is `since`; `submit` replaces the hand flip to `built`; `reopens:` names an ended id and rework gets a new id; a kill or drop of code already in main creates a `remove-<id>` item; graveyard lines carry the type (0.3 lines without it still read); history gains the `decided` event; every item needs a `live:` delta before it ends.
+
+### Upgrading from 0.3.0
+
+0.3.1 is a patch release with no migration step. It changes behavior in these ways:
+
+- the pre-commit gate ignores `gcf/.metrics/`: a `gcf audit` or `gcf context` run no longer makes the next verdict, `take`, `done` or `drop` fail with `gcf/ has changes outside the index`
+- `ai-factory gcf verdict <id> tune` refuses a card at `tune_limit` (`gcf/config.yml`, 3 by default): kill it, or redesign the envelope and reset `tune_count`
+- `gcf audit` reports open questions older than `question_stale_after_commits` (`stale_questions`) and a `PILLARS.md` with more than 7 pillars
+- a card with an unquoted numeric `id:` (YAML reads `id: 2024` as a number) is refused: quote the slug
+- `built_at` is recorded in a follow-up commit after the implementation commit, with that commit's hash
+- the form check is `npx --yes cnlp-kit check`; `npx cnlp check` fails on a machine without a global cnlp-kit, because no npm package is named `cnlp`
+- a GDD with `#` lines inside closed code fences reports a one-time delta on its next re-import: those lines were wrongly read as headings before
+
+### Upgrading from 0.2.x
+
+0.3.0 replaces the candidate backlog with the Design Model: a card is schema 2 (`cards/<id>.md` with a slug id, `type`, `pillars`, no `slug` and no `route`; the gate names the steps for a schema 1 card), and the design lives in `gcf/design/`. In order:
+
+1. `ai-factory extension update` and `ai-factory gcf init` (adds `history.md` and the `.gitattributes` lines).
+2. `ai-factory gcf design migrate` — deterministic, no commit. Each `cand-NNN | …` backlog line becomes a unit: the quote goes to provenance, every slot the line did not carry reads `TBD`, every gap note survives as a `TBD`, the backlog keeps its order, and `cand-NNN` references in `open-questions.md` and `graveyard.md` are rewritten. The keeps and dones of old commit messages are copied into `gcf/history.md` once.
+3. Candidates you already turned into units by hand: `--skip cand-012=tile-placement` drops the line and sends dependencies on it to that unit; `--skip cand-014=take-back+undo-and-clear` does the same for a candidate you split in two. The command prints the dependencies it could not map, the units that look like duplicates of hand-written ones, and the gap notes of skipped candidates to check in their units.
+4. `ai-factory gcf design check`, fix what it reports — typically a digit in a description — and commit.
 
 To remove the extension:
 
@@ -56,15 +101,22 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
 
 ## What it adds
 
-**Skills** — `gcf-init`, `gcf-adopt`, `gcf-card`, `gcf-verdict`, `gcf-audit`, `gcf-vision`, `gcf-debate`, `gcf-ingest`.
+**Skills** — `gcf-init`, `gcf-adopt`, `gcf-card` (put work into `gcf/work/`: take units, group them under a feature, or create a non-design item), `gcf-verdict` (verdicts and decisions), `gcf-triage` (inbox entries into items, tunes, units or nothing, with the human approving each), `gcf-audit`, `gcf-vision`, `gcf-debate`, `gcf-ingest`.
+
+**A deterministic core** behind `ai-factory gcf …`:
+
+- work items — `take <ids...> [--feature <id>]`, `item new <id> --type <type>`, `submit`, `close`, `verdict <id> keep|tune|kill`, `decide <id> go|no|wontfix|known|close|continue|kill`, `block`, `unblock`, `drop`, `done`, `where`
+- inbox and snapshot — `inbox [add <text> | drop <in-id>]`, `live`, `live check`
+- runs and play — `context`, `plan check <id>`, `playtest`, `audit`
+- design and sources — `design check`, `design export`, `design import`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
+- setup — `init`, `index`, `hooks-install`
 
-**A deterministic core** behind `ai-factory gcf …` — `init`, `index`, `context`, `audit`, `playtest`, `verdict`, `anchor`, `section`, `quotes`, `lint`, `design check`, `where`, `take`, `done`, `drop`, `hooks-install`. These are plain Node scripts with no LLM in the loop: the same functions the skills call, the pre-commit gate runs, and the harness gates against.
+Every move of an item makes one commit `gcf(<move>): <id>` with every file it touched — the item, history or graveyard, `LIVE.md`, the systems documents, the parent feature, a removal item, the archived plan. `take`, `item new` and `inbox` do not commit. These are plain Node scripts with no LLM in the loop: the same functions the skills call, the pre-commit gate runs, and the harness gates against.
 
-**A pre-commit gate** that breaks the commit on a terminal status stored in a card file, a malformed `[until:]` annotation, a card built on an unplayed dependency, a dependency that names no known id, a П2 linter finding in a subsystem document, or a blocking design-check finding: a malformed unit or card, a digit in prose, a forbidden synonym, a quote that is not verbatim in its GDD section, an id living in two places, a backlog out of step with `gcf/design/`. An unfinished unit (`TBD`) never breaks a commit. The gate regenerates `gcf/INDEX.md` and stages it for you.
+**A pre-commit gate** that breaks the commit on a schema 2 card left in `gcf/cards/`, an invalid item (an unknown field, a status that is not stored or does not fit its gate or type, a file name that is not its id), a malformed `[until:]` annotation, an edited body of an `unplayed` item, a malformed `gcf/LIVE.md`, a П2 linter finding in a subsystem document, or a blocking design-check finding: a malformed unit or item, a digit in prose, a forbidden synonym, a quote that is not verbatim in its GDD section, a dependency that names no known id, an id living in two places, a backlog out of step with `gcf/design/`. An unfinished unit (`TBD`) never breaks a commit. A unit or item that leaves `gcf/design/` or `gcf/work/` without a move only draws a warning — its reason is lost, but an item still depending on it fails in that same commit. The gate regenerates `gcf/INDEX.md` and stages it for you.
 
-**CNLP profiles and a card schema** for the documents the agent reads — one profile per unit type, shared by a unit and its card — plus injections into `aif-plan`, `aif-review` and `aif-commit`.
+**CNLP profiles and a work item schema** for the documents the agent reads — one profile per unit type, shared by a unit and its item — plus injections into `aif-plan`, `aif-review` and `aif-commit`.
 
-**Upgrading from 0.2.x:** a card is schema 2 now — `cards/<id>.md` with a slug id, `type`, `pillars`, no `slug` and no `route`; the gate names the steps for a schema 1 card. Backlog candidate lines (`cand-NNN | …`) become units in `gcf/design/` with `ai-factory gcf design migrate` (deterministic, no commit): it keeps the backlog order, writes the quote as provenance and every slot the line did not carry as `TBD`, rewrites `cand-NNN` references in `open-questions.md` and `graveyard.md`, and copies the keeps and dones of old commit messages into `gcf/history.md` once — the ledger reads that file, not the log. Then run `ai-factory gcf design check`, fix what it reports — typically a digit in a description — and commit.
 
 ## Docs
 

package/commands/gcf.js

@@ -70,12 +70,17 @@ function aif(args) {
 
 const today = () => new Date().toISOString().slice(0, 10);
 
-const UNION = ['gcf/history.md merge=union', 'gcf/graveyard.md merge=union'];
+const UNION = [
+  'gcf/history.md merge=union',
+  'gcf/graveyard.md merge=union',
+  'gcf/inbox.md merge=union',
+];
 
 /**
- * Two branches that end different lives may add their lines at the same spot of history.md or
- * graveyard.md: a union merge keeps both instead of a conflict whose "ours" loses one. Adds the
- * missing rules to `<dir>/.gitattributes`; a project that ran an older init gets them on re-run.
+ * Two branches that end different lives may add their lines at the same spot of history.md,
+ * graveyard.md or inbox.md: a union merge keeps both instead of a conflict whose "ours" loses
+ * one. Adds the missing rules to `<dir>/.gitattributes`; a project that ran an older init gets
+ * them on re-run.
  */
 export async function unionAttributes(dir) {
   const file = path.join(dir, '.gitattributes');
@@ -87,7 +92,7 @@ export async function unionAttributes(dir) {
 }
 
 async function seedSkeleton(root) {
-  for (const dir of ['design', 'cards', 'systems', 'source', '.metrics']) {
+  for (const dir of ['design', 'work', 'systems', 'source', '.metrics']) {
     await mkdir(path.join(root, dir), { recursive: true });
   }
 
@@ -102,14 +107,14 @@ async function seedSkeleton(root) {
     if (!existsSync(target)) await copyFile(path.join(EXT_ROOT, 'templates', tpl), target);
   }
 
-  const { HISTORY_HEAD } = await lib('verdict-fs');
+  const { HISTORY_HEAD, GRAVEYARD_HEAD } = await lib('verdict-fs');
+  const { INBOX_HEAD } = await lib('inbox');
+  const { serializeLive } = await lib('live');
   for (const [name, header] of [
     ['history.md', HISTORY_HEAD],
-    [
-      'graveyard.md',
-      '# Graveyard — `- <id> | <reason> | tags: <tags>`, one line per idea killed by a verdict ' +
-        'or dropped before work\n',
-    ],
+    ['graveyard.md', GRAVEYARD_HEAD],
+    ['inbox.md', INBOX_HEAD],
+    ['LIVE.md', serializeLive({ capabilities: [], knownIssues: [] })],
     [
       'open-questions.md',
       '# Open questions — records with id/lens/sections/sys/class/question/proposed, ' +
@@ -146,7 +151,8 @@ function registerInit(gcf, program) {
   gcf
     .command('init')
     .description(
-      'Create the gcf/ skeleton from templates (idempotent, never overwrites); offers the harness',
+      'Create the gcf/ skeleton from templates (idempotent, never overwrites) and the agent ' +
+        'instructions block in AGENTS.md (replaced in place); offers the harness',
     )
     .option('--harness', `also install ${HARNESS} and run gcf-harness init (Claude Code only)`)
     .option('--no-harness', 'do not offer the harness')
@@ -155,6 +161,10 @@ function registerInit(gcf, program) {
       await seedSkeleton(root);
       const { writeIndex } = await lib('index-gen');
       await writeIndex(root);
+      // Re-run on every update: the block is replaced in place, so it follows the extension.
+      const block = await readFile(path.join(EXT_ROOT, 'templates', 'agents-block.md'), 'utf8');
+      const agents = await (await lib('agents-block')).writeAgentsBlock(process.cwd(), block);
+      if (agents.length) console.log(`agent instructions written: ${agents.join(', ')}`);
       console.log(
         'gcf/ ready. Write PILLARS.md through /gcf-init, then import a GDD with /gcf-ingest ' +
           'or start the design with /gcf-vision.',
@@ -177,19 +187,19 @@ function registerIndex(gcf) {
 
 function registerContext(gcf) {
   gcf
-    .command('context <card-id>')
-    .description('Assemble the readset for a card (GCF-PRD §9.1)')
+    .command('context <item-id>')
+    .description('Assemble the readset for a work item (GCF-PRD §9.1)')
     .option('--json', 'machine output')
-    .action(async (cardId, opts) => {
+    .action(async (itemId, opts) => {
       const { buildContext } = await lib('context');
-      const ctx = await buildContext(process.cwd(), cardId);
+      const ctx = await buildContext(process.cwd(), itemId);
       // Metric 1 (GCF-PRD §14): readset size over time, one csv line per call.
       const { appendFile, mkdir } = await import('node:fs/promises');
       const metricsDir = path.join(process.cwd(), 'gcf', '.metrics');
       await mkdir(metricsDir, { recursive: true });
       await appendFile(
         path.join(metricsDir, 'context-log.csv'),
-        `${today()},${cardId},${ctx.files.length},${ctx.total_tokens_est}\n`,
+        `${today()},${itemId},${ctx.files.length},${ctx.total_tokens_est}\n`,
         'utf8',
       );
       out(opts.json, ctx, (c) =>
@@ -213,9 +223,10 @@ function registerAudit(gcf) {
       const report = await audit(process.cwd());
       // Metric 2 (GCF-PRD §14): findings per audit run.
       const findings =
-        report.stale_built.length +
+        report.stale_waiting.length +
         report.tune_limit.length +
         report.until.filter((u) => u.status === 'stale').length +
+        report.stale_questions.length +
         Object.keys(report.linter).length;
       const { appendFile, mkdir } = await import('node:fs/promises');
       const metricsDir = path.join(process.cwd(), 'gcf', '.metrics');
@@ -236,7 +247,7 @@ function registerAudit(gcf) {
 function registerPlaytest(gcf) {
   gcf
     .command('playtest')
-    .description('List built cards with their miss-criterion questions')
+    .description('List items awaiting a verdict and unplayed ones, with their questions')
     .option('--json', 'machine output')
     .action(async (opts) => {
       const { gcfRoot } = await lib('gcf-paths');
@@ -244,29 +255,60 @@ function registerPlaytest(gcf) {
       const list = await playtestList(gcfRoot());
       out(opts.json, list, (l) =>
         l.length
-          ? l.map((c) => `${c.id} [${c.system.join(',')}]: ${c.question}`).join('\n')
-          : 'nothing in built — nothing to playtest',
+          ? l.map((c) => `${c.id} (${c.status}) [${c.system.join(',')}]: ${c.question}`).join('\n')
+          : 'nothing waits for a playtest',
       );
     });
 }
 
+const shortHash = (h) => (h ? ` (${h.slice(0, 7)})` : '');
+const removalLine = (r) => (r.removal ? `\nremoval item: gcf/work/${r.removal}.md` : '');
+
+/** `--remove` / `--no-remove` / neither (the move's default) for a move that may bury code. */
+const removeOptions = (cmd) =>
+  cmd
+    .option('--remove', 'also create a removal item: the code is in main')
+    .option('--no-remove', 'no removal item: the code never reached main');
+
 function registerVerdict(gcf) {
-  gcf
-    .command('verdict <card-id> <verdict>')
-    .description('Apply a human verdict: keep | tune | kill (GCF-PRD §8)')
-    .option('--note <text>', 'tune remark or kill reason')
+  removeOptions(
+    gcf
+      .command('verdict <item-id> <verdict>')
+      .description('Apply a human verdict: keep | tune | kill (Methodology §4.1)')
+      .option('--note <text>', 'tune remark or kill reason')
+      .option('--tags <list>', 'graveyard tags on kill, comma-separated (default: its systems)')
+      .option(
+        '--constraint <line>',
+        'keep of a hard unit: a line every reader of the subsystem must remember',
+        (v, p) => [...p, v],
+        [],
+      ),
+  )
     .option('--no-commit', 'skip the verdict commit (tests only)')
-    .action(async (cardId, verdict, opts) => {
-      const { applyVerdict } = await lib('verdict-fs');
-      const res = await applyVerdict(process.cwd(), cardId, verdict, {
+    .action(async (itemId, verdict, opts) => {
+      const { verdictItem } = await lib('work-ops');
+      const res = await verdictItem(process.cwd(), itemId, verdict, {
         note: opts.note ?? '',
+        tags: splitList(opts.tags),
+        remove: opts.remove,
+        constraints: opts.constraint,
         commit: opts.commit,
       });
-      const hash = res.hash ? ` (${res.hash.slice(0, 7)})` : '';
-      console.log(`${res.verdict} ${res.card} → ${res.systems.join(',')}${hash}`);
+      console.log(
+        `${res.verdict} ${res.id} → ${res.systems.join(',')}${shortHash(res.hash)}` +
+          removalLine(res),
+      );
     });
 }
 
+const splitList = (v) =>
+  v
+    ? String(v)
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+
 function anchorDeltaLine(r) {
   if (r.delta) {
     const { added, changed, removed, renamed } = r.delta;
@@ -368,7 +410,9 @@ function registerDesign(gcf) {
   const design = gcf.command('design').description('Design Model: units in gcf/design/');
   design
     .command('check')
-    .description('Mechanical checks over gcf/design/ and the cards; exit 1 on a blocking finding')
+    .description(
+      'Mechanical checks over gcf/design/ and the work items; exit 1 on a blocking finding',
+    )
     .option('--json', 'machine output')
     .action(async (opts) => {
       const { designCheck } = await lib('design-check');
@@ -438,7 +482,9 @@ const placeLines = (x) => [...x.live.map((p) => `${p.state} gcf/${p.file}`), ...
 function registerWhere(gcf) {
   gcf
     .command('where [id]')
-    .description('Where an id lives: a design section, a card, a terminal event; no id lists all')
+    .description(
+      'Where an id lives: a design section, a work item, a terminal event; no id lists all',
+    )
     .option('--json', 'machine output')
     .action(async (id, opts) => {
       const { buildLedger } = await lib('ledger');
@@ -458,9 +504,13 @@ function registerWhere(gcf) {
 function registerMoves(gcf) {
   const ops = () => lib('unit-ops');
   gcf
-    .command('take <id>')
-    .description('Move a ready soft unit from gcf/design/ into cards/<id>.md (no commit)')
-    .action(async (id) => console.log((await (await ops()).takeUnit(process.cwd(), id)).card));
+    .command('take <ids...>')
+    .description('Move ready units from gcf/design/ into work items gcf/work/<id>.md (no commit)')
+    .option('--feature <id>', 'group them under this feature item, new or live')
+    .action(async (ids, o) => {
+      const r = await (await ops()).takeUnits(process.cwd(), ids, { feature: o.feature ?? null });
+      console.log(r.items.join('\n'));
+    });
   gcf
     .command('done <id>')
     .description('A hard unit is built and tested: it leaves gcf/design/ (commit gcf(done))')
@@ -477,20 +527,214 @@ function registerMoves(gcf) {
       ).doneUnit(process.cwd(), id, { constraints: o.constraint, commit: o.commit });
       console.log(`done ${r.id}${r.hash ? ` (${r.hash.slice(0, 7)})` : ''}`);
     });
+  removeOptions(
+    gcf
+      .command('drop <id>')
+      .description(
+        'Drop a unit or a work item: a graveyard line keeps the reason (commit gcf(drop))',
+      )
+      .requiredOption('--reason <text>', 'why it dies')
+      .option('--tags <list>', 'graveyard tags, comma-separated (default: its systems)'),
+  )
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, o) => {
+      const tags = splitList(o.tags);
+      const { buildLedger } = await lib('ledger');
+      const isItem = (await buildLedger(process.cwd())).item(id);
+      const r = isItem
+        ? await (
+            await lib('work-ops')
+          ).dropItem(process.cwd(), id, {
+            reason: o.reason,
+            tags,
+            remove: o.remove,
+            commit: o.commit,
+          })
+        : await (
+            await ops()
+          ).dropUnit(process.cwd(), id, { reason: o.reason, tags, commit: o.commit });
+      console.log(`dropped ${r.id}${shortHash(r.hash)}${removalLine(r)}`);
+    });
+}
+
+function registerItem(gcf) {
+  const item = gcf.command('item').description('Work items in gcf/work/ (Methodology §3)');
+  item
+    .command('new <id>')
+    .description('Create a work item in ready (or blocked), no commit; a design unit uses take')
+    .requiredOption(
+      '--type <type>',
+      'feature | tech | bug | spike | asset | content | perf | release',
+    )
+    .option('--gate <gate>', 'verdict | auto | decision (default: by type)')
+    .option('--title <text>', 'one line: what the item gives')
+    .option('--parent <feature>', 'a live feature item this one belongs to')
+    .option('--system <list>', 'subsystems it touches, comma-separated')
+    .option('--depends <list>', 'ids it waits for, comma-separated')
+    .option('--severity <level>', 'a bug: critical | high | medium | low')
+    .option('--blocked <why>', 'start blocked, e.g. "file needed" for an asset')
+    .option('--from <in-id>', 'the inbox entry it comes from: erased')
+    .option('--reopens <id>', 'the ended id this item reworks')
+    .action(async (id, o) => {
+      const { newItem } = await lib('work-ops');
+      const r = await newItem(process.cwd(), {
+        id,
+        type: o.type,
+        gate: o.gate,
+        title: o.title,
+        parent: o.parent,
+        system: splitList(o.system),
+        depends: splitList(o.depends),
+        severity: o.severity,
+        blocked: o.blocked,
+        from: o.from,
+        reopens: o.reopens,
+      });
+      console.log(r.item);
+    });
+}
+
+function registerItemMoves(gcf) {
+  const ops = () => lib('work-ops');
   gcf
-    .command('drop <id>')
-    .description(
-      'Drop a unit before any work: a graveyard line keeps the reason (commit gcf(drop))',
+    .command('submit <id>')
+    .description('ready → awaiting-verdict / awaiting-decision (commit gcf(submit))')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, o) => {
+      const r = await (await ops()).submitItem(process.cwd(), id, { commit: o.commit });
+      console.log(`${r.id} → ${r.status}${shortHash(r.hash)}`);
+    });
+  gcf
+    .command('close <id>')
+    .description('A gate-auto item passed its DoD: it ends, or a soft unit goes unplayed')
+    .option(
+      '--constraint <line>',
+      'a hard unit: a line every reader of the subsystem must remember',
+      (v, p) => [...p, v],
+      [],
     )
-    .requiredOption('--reason <text>', 'why the idea dies')
-    .option('--tags <list>', 'graveyard tags, comma-separated (default: its systems)')
     .option('--no-commit', 'skip the commit (tests only)')
     .action(async (id, o) => {
-      const tags = o.tags ? o.tags.split(',').map((t) => t.trim()) : [];
       const r = await (
         await ops()
-      ).dropUnit(process.cwd(), id, { reason: o.reason, tags, commit: o.commit });
-      console.log(`dropped ${r.id}${r.hash ? ` (${r.hash.slice(0, 7)})` : ''}`);
+      ).closeItem(process.cwd(), id, { constraints: o.constraint, commit: o.commit });
+      console.log(`closed ${r.id}${r.unplayed ? ' → unplayed' : ''}${shortHash(r.hash)}`);
+    });
+}
+
+function registerDecide(gcf) {
+  const ops = () => lib('work-ops');
+  removeOptions(
+    gcf
+      .command('decide <id> <choice>')
+      .description('go | no | wontfix | known | close | continue | kill (Methodology §4.1)')
+      .option('--reason <text>', 'why: the graveyard keeps it'),
+  )
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, choice, o) => {
+      const r = await (
+        await ops()
+      ).decideItem(process.cwd(), id, choice, {
+        reason: o.reason ?? '',
+        remove: o.remove,
+        commit: o.commit,
+      });
+      console.log(`${r.choice} ${r.id}${shortHash(r.hash)}${removalLine(r)}`);
+    });
+  gcf
+    .command('block <id>')
+    .description('ready → blocked, with the reason or the question (commit gcf(block))')
+    .requiredOption('--reason <text>', 'why it cannot go on, or the question for you')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, o) => {
+      const r = await (
+        await ops()
+      ).blockItem(process.cwd(), id, { reason: o.reason, commit: o.commit });
+      console.log(`blocked ${r.id}${shortHash(r.hash)}`);
+    });
+  gcf
+    .command('unblock <id>')
+    .description('blocked | parked → ready (commit gcf(unblock))')
+    .option('--note <text>', 'the answer, or "file: <path>" for an asset')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, o) => {
+      const r = await (
+        await ops()
+      ).unblockItem(process.cwd(), id, { note: o.note ?? '', commit: o.commit });
+      console.log(`unblocked ${r.id}${shortHash(r.hash)}`);
+    });
+}
+
+function registerInbox(gcf) {
+  const inbox = gcf
+    .command('inbox')
+    .description('Raw input waiting for triage (gcf/inbox.md); no commit')
+    .option('--json', 'machine output')
+    .action(async (o) => {
+      const { gcfRoot } = await lib('gcf-paths');
+      const list = await (await lib('inbox')).listInbox(gcfRoot());
+      out(o.json, list, (l) =>
+        l.length ? l.map((e) => `${e.id} [${e.source}] ${e.text}`).join('\n') : 'inbox empty',
+      );
+    });
+  inbox
+    .command('add <text>')
+    .description('Append an entry')
+    .option('--source <source>', 'playtest | ci | agent | operator', 'operator')
+    .action(async (text, o) => {
+      const { gcfRoot } = await lib('gcf-paths');
+      const e = await (await lib('inbox')).addInbox(gcfRoot(), text, o.source);
+      console.log(e.id);
+    });
+  inbox
+    .command('drop <in-id>')
+    .description('Erase an entry: triaged as noise, a duplicate, or turned into an item')
+    .action(async (id) => {
+      const { gcfRoot } = await lib('gcf-paths');
+      await (await lib('inbox')).dropInbox(gcfRoot(), id);
+      console.log(`erased ${id}`);
+    });
+}
+
+function registerLive(gcf) {
+  const live = gcf
+    .command('live')
+    .description('What the game is now: gcf/LIVE.md')
+    .option('--json', 'machine output')
+    .action(async (o) => {
+      const { gcfRoot } = await lib('gcf-paths');
+      const l = await (await lib('live')).readLive(gcfRoot());
+      const rows = (list) => list.map((r) => `  ${r.id}: ${r.summary}`);
+      out(o.json, l, (x) =>
+        ['capabilities:', ...rows(x.capabilities), 'known-issues:', ...rows(x.knownIssues)].join(
+          '\n',
+        ),
+      );
+    });
+  live
+    .command('check')
+    .description('Record form, refs that name no file, known issues against parked bugs')
+    .option('--json', 'machine output')
+    .action(async (o) => {
+      const r = await (await lib('live')).checkLive(process.cwd());
+      out(o.json, r.issues, (l) => (l.length ? l.join('\n') : 'clean'));
+      if (r.issues.length) process.exitCode = 1;
+    });
+}
+
+function registerPlan(gcf) {
+  gcf
+    .command('plan')
+    .description('The plan of a work item')
+    .command('check <id>')
+    .description('Deterministic plan check: it exists, has task checkboxes, readset in budget')
+    .option('--json', 'machine output')
+    .action(async (id, o) => {
+      const r = await (await lib('plan-check')).planCheck(process.cwd(), id);
+      out(o.json, r, (x) =>
+        x.ok ? `${x.plan}: ${x.done}/${x.tasks} tasks done` : x.problems.join('\n'),
+      );
+      if (!r.ok) process.exitCode = 1;
     });
 }
 
@@ -541,8 +785,36 @@ function registerLint(gcf) {
     });
 }
 
+function registerPillar(gcf) {
+  const pillar = gcf
+    .command('pillar')
+    .description('Revise PILLARS.md where units and items cite it (the human decides)');
+  pillar
+    .command('rename <from> <to>')
+    .description('Rename a pillar id in PILLARS.md, units and items (commit gcf(pillar))')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (from, to, o) => {
+      const r = await (await lib('pillars')).renamePillar(process.cwd(), from, to, o);
+      console.log(`renamed ${from} → ${to}${shortHash(r.hash)}`);
+    });
+  pillar
+    .command('retire <id>')
+    .description('Take a pillar out; units left with none read pillars: TBD (commit gcf(pillar))')
+    .requiredOption('--reason <text>', 'why the game no longer holds it')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, o) => {
+      const r = await (await lib('pillars')).retirePillar(process.cwd(), id, o);
+      console.log(`retired ${id}${shortHash(r.hash)}`);
+      if (r.bare.length)
+        console.log(
+          `items now citing no pillar — give each one or accept it: ${r.bare.join(', ')}`,
+        );
+    });
+}
+
 export function register(program) {
   const gcf = program.command('gcf').description('Game Context Framework core');
+  registerPillar(gcf);
   registerInit(gcf, program);
   registerIndex(gcf);
   registerContext(gcf);
@@ -555,6 +827,12 @@ export function register(program) {
   registerDesign(gcf);
   registerWhere(gcf);
   registerMoves(gcf);
+  registerItem(gcf);
+  registerItemMoves(gcf);
+  registerDecide(gcf);
+  registerInbox(gcf);
+  registerLive(gcf);
+  registerPlan(gcf);
   registerHooksInstall(gcf);
   registerLint(gcf);
 }