gcf-aif-ext 0.5.0 → 0.5.1

package/README.md

@@ -50,6 +50,12 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
 
 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.5.1
+
+- A provenance record `assumed: q-NNN` must name a record still in `gcf/open-questions.md` (M9). A D2 record lives until its `until:` fires; once the human confirms the value, cite `answer: q-NNN` instead and remove it. After updating, run `ai-factory gcf design check`: every citation of a removed question blocks the commit gate until it is rewritten.
+- An unplayed item's body is frozen, so a word added to the glossary or a removed question is reported there, not blocked.
+- The `AGENTS.md` block has no `##` heading any more: a CNL-P guide is flat. A project that checks `AGENTS.md` with `cnlp check` adds `gcf_context`, `gcf_work`, `gcf_forbidden` and `gcf_skills` to `custom_sections` of its guide profile.
+
 ### 0.5.0
 
 The run layer of the methodology. Update both extensions together — `gcf-harness-aif-ext` 0.6.0 requires this core — and run `ai-factory gcf init` to refresh the agent block in `AGENTS.md`. New commands:

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/lib/design-check.js

@@ -121,12 +121,14 @@ function itemsIn(text, key) {
 export const recordsIn = (text, key) =>
   readRecords(itemsIn(text, key)).records.map((r) => r.values);
 
-/** `blocks:` of open-questions.md: every reference, and the D1 ones per blocked id. */
+/** open-questions.md: every record id, every `blocks:` reference, the D1 ones per blocked id. */
 export function questionBlocks(text) {
   /** @type {Map<string, string[]>} */
   const d1 = new Map();
   const refs = [];
-  for (const rec of String(text ?? '').split(/\n(?=- id:)/)) {
+  const src = String(text ?? '');
+  const qids = new Set([...src.matchAll(/^\s*- id:\s*(\S+)/gm)].map((m) => m[1]));
+  for (const rec of src.split(/\n(?=- id:)/)) {
     const qid = rec.match(/^- id:\s*(\S+)/)?.[1];
     const ids = listOf(rec.match(/^\s+blocks:\s*(.+)$/m)?.[1] ?? '');
     if (!qid || ids === 'TBD' || !ids.length) continue;
@@ -135,7 +137,7 @@ export function questionBlocks(text) {
     for (const id of ids) d1.set(id, [...(d1.get(id) ?? []), qid]);
   }
 
-  return { d1, refs };
+  return { d1, refs, qids };
 }
 
 /** Everything outside a unit that its references resolve against. */
@@ -296,7 +298,15 @@ function recordProblem(r, ctx) {
   }
 
   if (r.answer) return /^(q-\d+|manual)$/.test(r.answer) ? null : 'answer is q-NNN or manual';
-  if (r.assumed) return /^q-\d+$/.test(r.assumed) ? null : 'assumed is q-NNN';
+  if (r.assumed) {
+    if (!/^q-\d+$/.test(r.assumed)) return 'assumed is q-NNN';
+
+    // The D2 record is what the readset and the human's skim list see: it outlives its citation.
+    return ctx.questions.qids.has(r.assumed)
+      ? null
+      : `assumed: ${r.assumed} is not in open-questions.md - a D2 record stays until its ` +
+          `until: fires; once the human confirms the value, cite answer: ${r.assumed} instead`;
+  }
 
   return 'a record carries src + quote, answer, or assumed';
 }
@@ -326,6 +336,9 @@ function uncovered(values, records) {
 export const isDrift = (problem) =>
   /^(quote is not verbatim|GDD#\S+ is not an anchor)/.test(problem ?? '');
 
+/** The D2 record an `assumed:` cites left open-questions.md. */
+const isGone = (problem) => /^assumed: q-\d+ is not in open-questions/.test(problem ?? '');
+
 /** M9: provenance records are well formed, quotes verbatim, every GDD-sourced slot backed. */
 function provenanceIssues(u, values, ctx) {
   const records = provenanceOf(u.body);
@@ -446,11 +459,16 @@ async function checkItem(item, ctx, ledger) {
   const values = slotValues(item.body, profile).filter((v) => !OPERATOR_BLOCKS.includes(v.block));
   for (const v of values.filter((x) => isTbd(x.value)))
     add('M1', v.line, `a unit in work carries no TBD: ${v.block}`);
-  for (const [c, line, m] of valueIssues(values, ctx)) add(c, line, m);
+  // An unplayed body is frozen (§5.4): a later glossary word or unit, or a gone question, cannot
+  // be fixed there, only reported until a tune or a kill takes the item back.
+  const frozen = item.data.status === 'unplayed' ? 'report' : 'block';
+  for (const [c, line, m] of valueIssues(values, ctx)) add(c, line, m, frozen);
   for (const r of provenanceOf(item.body)) {
     const problem = recordProblem(r, ctx);
     // An item's quotes go stale when the GDD moves on: that is a D1 for the human, not a gate.
-    if (problem) add('M9', r.line, problem, isDrift(problem) ? 'report' : 'block');
+    // A gone question is outside the frozen body too; a malformed record was malformed at close.
+    const sev = isDrift(problem) ? 'report' : isGone(problem) ? frozen : 'block';
+    if (problem) add('M9', r.line, problem, sev);
   }
 
   return issues;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",

package/profiles/glossary.md

@@ -33,5 +33,5 @@ custom_sections:
 - none: a block that is not listed above belongs to a unit
 
 enforcement:
-- `ai-factory gcf design check` refuses a forbidden synonym in gcf/design/ and in a card (M4)
+- `ai-factory gcf design check` refuses a forbidden synonym in gcf/design/ and in a work item (M4); an unplayed item's frozen body only reports it
 - quoted text is data: a GDD quote keeps the designer's own word

package/profiles/system.md

@@ -41,7 +41,7 @@ sections:
 - key: constraints
   form: bullet-list
   required: yes
-  note: negative constraints and invariants accumulated from cards and hard implementations
+  note: negative constraints and invariants accumulated from work items and hard implementations
 
 - key: open
   form: bullet-list
@@ -49,7 +49,7 @@ sections:
   note: lines carrying a live "[until: ...]" annotation, moved here by collapse
 
 custom_sections:
-- none: a fact that fits no block above belongs to code or to a card, not here
+- none: a fact that fits no block above belongs to code or to a work item, not here
 
 enforcement:
 - `npx --yes cnlp-kit check`, over the files a `cnlp.config.json` corpus entry maps to this profile

package/profiles/unit-constraint.md

@@ -8,10 +8,10 @@ format: cnlp-format.md
 mood: declarative
 
 headings:
-- none: the body is flat; the `## <id>` line and the header fields above the blocks name the unit
+- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in work/ the frontmatter does
 
 frontmatter_fields:
-- none: a constraint never becomes a card, so its header lives above the blocks in design/
+- none: in design/ the header lives above the blocks; in work/ the work item schema holds the frontmatter
 
 lexicon_exempt:
 - none: every block is read when the constraint is planned and measured
@@ -48,5 +48,5 @@ custom_sections:
 - none: a block that is not listed above is prose looking for a home
 
 enforcement:
-- `ai-factory gcf design check`, over the units in gcf/design/
+- `ai-factory gcf design check`, over the units in gcf/design/ and the items in gcf/work/
 - the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-entity.md

@@ -8,10 +8,10 @@ format: cnlp-format.md
 mood: declarative
 
 headings:
-- none: the body is flat; the `## <id>` line and the header fields above the blocks name the unit
+- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in work/ the frontmatter does
 
 frontmatter_fields:
-- none: an entity never becomes a card, so its header lives above the blocks in design/
+- none: in design/ the header lives above the blocks; in work/ the work item schema holds the frontmatter
 
 lexicon_exempt:
 - none: every block is read when the entity is planned and coded
@@ -44,5 +44,5 @@ custom_sections:
 - none: a block that is not listed above is prose looking for a home
 
 enforcement:
-- `ai-factory gcf design check`, over the units in gcf/design/
+- `ai-factory gcf design check`, over the units in gcf/design/ and the items in gcf/work/
 - the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-mechanic.md

@@ -1,6 +1,6 @@
 ---
 name: unit-mechanic
-description: The CNL-P profile of a GCF design unit of type mechanic — one body for its section in design/<system>.md and for its card in cards/<id>.md.
+description: The CNL-P profile of a GCF design unit of type mechanic — one body for its section in design/<system>.md and for its work item in work/<id>.md.
 ---
 
 format: cnlp-format.md
@@ -8,22 +8,10 @@ format: cnlp-format.md
 mood: declarative
 
 headings:
-- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in cards/ the frontmatter does
+- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in work/ the frontmatter does
 
 frontmatter_fields:
-- schema
-- id
-- type
-- title
-- status
-- system
-- depends
-- pillars
-- source
-- reopens
-- tune_count
-- built_at
-- created
+- none: in design/ the header lives above the blocks; in work/ the work item schema holds the frontmatter
 
 lexicon_exempt:
 - none: every block is read when the unit is planned, built or played
@@ -69,12 +57,12 @@ sections:
 - key: contract
   form: bullet-list
   required: yes
-  note: card stage, absent in design/ - paths and entry points, never member lists or values; an architecture rule is a constraint
+  note: work stage, absent in design/ - paths and entry points, never member lists or values; an architecture rule is a constraint
 
 - key: interactions
   form: bullet-list
   required: yes
-  note: card stage, absent in design/ - "<other id>: how the two cross", one line per crossing
+  note: work stage, absent in design/ - "<other id>: how the two cross", one line per crossing
 
 - key: constraints
   form: bullet-list
@@ -107,5 +95,5 @@ custom_sections:
 - none: a block that is not listed above is prose looking for a home
 
 enforcement:
-- `ai-factory gcf design check`, over the units in gcf/design/ and the cards in gcf/cards/
+- `ai-factory gcf design check`, over the units in gcf/design/ and the items in gcf/work/
 - the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-resource.md

@@ -1,6 +1,6 @@
 ---
 name: unit-resource
-description: The CNL-P profile of a GCF design unit of type resource — an economy resource with its sources and sinks, in design/<system>.md and as a card.
+description: The CNL-P profile of a GCF design unit of type resource — an economy resource with its sources and sinks, in design/<system>.md and as a work item.
 ---
 
 format: cnlp-format.md
@@ -8,22 +8,10 @@ format: cnlp-format.md
 mood: declarative
 
 headings:
-- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in cards/ the frontmatter does
+- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in work/ the frontmatter does
 
 frontmatter_fields:
-- schema
-- id
-- type
-- title
-- status
-- system
-- depends
-- pillars
-- source
-- reopens
-- tune_count
-- built_at
-- created
+- none: in design/ the header lives above the blocks; in work/ the work item schema holds the frontmatter
 
 lexicon_exempt:
 - none: every block is read when the unit is planned, built or played
@@ -49,12 +37,12 @@ sections:
 - key: contract
   form: bullet-list
   required: yes
-  note: card stage, absent in design/ - paths and entry points, never member lists or values
+  note: work stage, absent in design/ - paths and entry points, never member lists or values
 
 - key: interactions
   form: bullet-list
   required: yes
-  note: card stage, absent in design/ - "<other id>: how the two cross", one line per crossing
+  note: work stage, absent in design/ - "<other id>: how the two cross", one line per crossing
 
 - key: constraints
   form: bullet-list
@@ -87,5 +75,5 @@ custom_sections:
 - none: a block that is not listed above is prose looking for a home
 
 enforcement:
-- `ai-factory gcf design check`, over the units in gcf/design/ and the cards in gcf/cards/
+- `ai-factory gcf design check`, over the units in gcf/design/ and the items in gcf/work/
 - the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-rule.md

@@ -8,10 +8,10 @@ format: cnlp-format.md
 mood: declarative
 
 headings:
-- none: the body is flat; the `## <id>` line and the header fields above the blocks name the unit
+- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in work/ the frontmatter does
 
 frontmatter_fields:
-- none: a rule never becomes a card, so its header lives above the blocks in design/
+- none: in design/ the header lives above the blocks; in work/ the work item schema holds the frontmatter
 
 lexicon_exempt:
 - none: every block is read when the rule is planned and tested
@@ -48,5 +48,5 @@ custom_sections:
 - none: a block that is not listed above is prose looking for a home
 
 enforcement:
-- `ai-factory gcf design check`, over the units in gcf/design/
+- `ai-factory gcf design check`, over the units in gcf/design/ and the items in gcf/work/
 - the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/skills/gcf-card/SKILL.md

@@ -23,10 +23,11 @@ forbidden_behaviors:
 - do not put `until:` in the frontmatter: it is a line annotation inside slots
 - do not move a section, edit the backlog or write `status:` by hand: `ai-factory gcf take`, `item new`, `done`, `drop` and the item moves own those
 - do not reuse an id: an ended id stays ended; rework gets a new id with `reopens: <old id>`
+- do not remove a D2 record cited as `assumed: q-NNN`: it stays in `gcf/open-questions.md` until its `until:` fires; when the human confirms the value earlier, rewrite each citation to `answer: q-NNN` first
 
 outputs:
 - each answered slot gets a provenance record `- slot: <block>` with `answer: manual`, or `answer: q-NNN` when it closes a question
-- a design-unit item body carries every block of its type plus `contract:` (paths and entry points) and `interactions:` (`<other id>: how the two cross`, or `- none: <why>`)
+- a design-unit item body carries every block of its type; a mechanic or resource item adds `contract:` (paths and entry points) and `interactions:` (`<other id>: how the two cross`, or `- none: <why>`)
 - every item carries a `live:` delta before it ends: what it adds, modifies or removes in `gcf/LIVE.md`, or `none: <why>`
 
 workflow:
@@ -44,7 +45,7 @@ workflow:
 12. write each answer into the unit in place, with its `answer:` provenance record
 13. run `ai-factory gcf design check --json` until the unit's entry in `units` reads `ready: true`, then commit the answered unit
 14. run `ai-factory gcf take <id>` for one unit, or `ai-factory gcf take <id> <id> --feature <feature-id>` to group several under a feature; it writes `gcf/work/<id>.md` and removes the sections and backlog lines in one step
-15. in each design-unit item write `contract:` from the code tree and `interactions:` from the units and items that write the same state; a soft unit whose human wants no playtest gets `gate: auto` - it will close as unplayed
+15. in each mechanic or resource item write `contract:` from the code tree and `interactions:` from the units and items that write the same state; a soft unit whose human wants no playtest gets `gate: auto` - it will close as unplayed
 16. write the item's `live:` delta (a feature's children keep `none: parent`; the feature writes the capability), run `ai-factory gcf design check`, and commit
 17. report the item paths, each item's gate, and for a verdict item the one question the playtest will answer
 

package/templates/agents-block.md

@@ -1,5 +1,3 @@
-## Game Context Framework (from gcf-aif-ext)
-
 gcf_context:
 - the game's design and its work live in `gcf/`, and the `ai-factory gcf` commands and the gcf skills change them
 - read `gcf/INDEX.md` before anything else under `gcf/`: it lists every subsystem, design unit and work item
@@ -16,6 +14,7 @@ gcf_work:
 - work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
 - in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:`, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
 - a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
+- a word added to a `not:` of `gcf/glossary.md` leaves `gcf/design/` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit as M4
 - the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --source playtest "<note>"`
 - a release item carries `version:` and `channel:` (`item new <id> --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
 - `item new` and `take` refuse a type the current phase does not take: run `ai-factory gcf phase` and bring the refusal to the human