gcf-aif-ext 0.5.0 → 0.5.2

package/node_modules/cnlp-kit/src/config.js

@@ -4,9 +4,9 @@
 // inside a file the next upgrade overwrote.
 
 import { existsSync } from 'node:fs';
-import { glob, readdir, readFile } from 'node:fs/promises';
+import { glob, readdir, readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
-import { bodyIssues, loadProfileAt, pageRefs, resolveDoc } from './cnlp.js';
+import { bodyIssues, lexiconApplies, loadProfileAt, pageRefs, parseBlocks, resolveDoc } from './cnlp.js';
 
 export const CONFIG_NAME = 'cnlp.config.json';
 
@@ -124,24 +124,48 @@ export function readingOrder(sets) {
   return out;
 }
 
+/** `pageIdOf`, with the set renamed when the caller named it apart from its directory. */
+const renamedIdOf = (rel, docsets, rename) => {
+  const id = pageIdOf(rel, docsets);
+  return id && { ...id, docset: rename[id.docset] ?? id.docset };
+};
+
 /**
  * §9 reference conformance across a corpus, which is the 1 check no single document can make.
  * `docs` is every file already read, so this adds no read of its own.
+ *
+ * `context` holds the pages of companion sets as `{ set, page, raw }`: they resolve references and
+ * are never checked. Their id comes with them rather than from a path, because a companion may sit
+ * outside the root, in a folder named by a version rather than by its set.
  */
-export function linkIssues(docs, docsets) {
+export function linkIssues(docs, docsets, { context = [], rename = {} } = {}) {
   const pages = new Map();
   const sets = new Set();
   for (const { rel } of docs) {
-    const id = pageIdOf(rel, docsets);
+    const id = renamedIdOf(rel, docsets, rename);
     if (!id) continue;
     pages.set(`${id.docset}:${id.page}`, rel);
     sets.add(id.docset);
   }
+  const known = new Set(pages.keys());
+  for (const { set, page } of context) {
+    known.add(`${set}:${page}`);
+    sets.add(set);
+  }
 
   const issues = [];
   const reached = new Set();
+  // A companion's references are not this run's to report, but they count toward reach: a page of
+  // an integration set is reached only from the companion that overrides it.
+  for (const { set, page, raw } of context) {
+    for (const ref of pageRefs(raw)) {
+      if (ref.key === 'docset') continue;
+      const qualified = ref.target.includes(':') ? ref.target : `${set}:${ref.target}`;
+      if (qualified !== `${set}:${page}`) reached.add(qualified);
+    }
+  }
   for (const { rel, raw } of docs) {
-    const from = pageIdOf(rel, docsets);
+    const from = renamedIdOf(rel, docsets, rename);
     if (!from) continue;
     const self = `${from.docset}:${from.page}`;
     for (const ref of pageRefs(raw)) {
@@ -157,7 +181,7 @@ export function linkIssues(docs, docsets) {
       if (ref.key === 'by' && ref.target.includes(':')) {
         issues.push({ file: rel, line: ref.line, message: `"by: ${ref.target}" carries a document set prefix — a "by:" value names a page of this set` });
       }
-      if (!pages.has(qualified)) {
+      if (!known.has(qualified)) {
         issues.push({ file: rel, line: ref.line, message: `page "${qualified}" does not resolve to a file under ${docsets}/` });
       } else if (qualified !== self) {
         reached.add(qualified);
@@ -217,6 +241,85 @@ export async function skillDrift(root, agents, version) {
   return out;
 }
 
+/**
+ * The standing rules `cnlp init` hands an operator to paste into the file their agent reads. 1
+ * value and not a string inside the command, because `cnlp check` reads it too: a pasted copy is a
+ * copy that goes stale, and nothing else in the project records that it was taken.
+ */
+export const AGENT_BLOCK = [
+  '- the CNL-P standard is the authority on document form: read it with `npx cnlp print format`',
+  '- run `npx cnlp check` before a commit that touches a document the corpus names',
+  "- load a library's documentation with `npx cnlp docs`, which writes every set's index in reading order",
+];
+
+// The 2 files an agent reads by convention, which are the 2 the corpus proposal below already
+// knows. The block is pasted by hand, so nothing records which file took it.
+const AGENT_FILES = ['AGENTS.md', 'CLAUDE.md'];
+
+/**
+ * The agent files carrying a copy of `AGENT_BLOCK` from an earlier version. A bullet naming
+ * `npx cnlp print format` is the block's own opener and is what finds the copy.
+ * ponytail: that phrase is the anchor — a version that stops naming it loses the watch on every
+ * copy already pasted, and the answer then is markers written into the file.
+ */
+export async function agentBlockDrift(root) {
+  const out = [];
+  for (const name of AGENT_FILES) {
+    const at = path.join(root, name);
+    if (!existsSync(at)) continue;
+    const lines = (await readFile(at, 'utf8')).split(/\r?\n/).map((l) => l.trimEnd());
+    const start = lines.findIndex((l) => /^-\s.*`npx cnlp print format`/.test(l));
+    if (start < 0) continue; // the project never took the block
+    if (lines.slice(start, start + AGENT_BLOCK.length).join('\n') !== AGENT_BLOCK.join('\n')) out.push(name);
+  }
+  return out;
+}
+
+/**
+ * The local profiles a packaged profile of the same name has outgrown. A project copies a packaged
+ * profile to fill its own `custom_sections`, and `profileFor` reads the copy from then on: an
+ * upgrade moves the original underneath it, and the check reports a conformant corpus against a
+ * declaration this package has since changed. What a copy adds is the vocabulary it was copied for
+ * and is never drift; what the packaged profile declares and the copy does not is.
+ */
+export async function profileDrift(config) {
+  const out = [];
+  if (!config.profilesDir) return out;
+  for (const name of [...new Set(config.corpus.map((e) => e.profile))].sort()) {
+    const local = path.join(config.profilesDir, `${name}.md`);
+    const packagedAt = resolveDoc(name);
+    if (!existsSync(local) || !existsSync(packagedAt) || path.resolve(packagedAt) === path.resolve(local)) continue;
+    const packaged = await loadProfileAt(packagedAt);
+    const mine = await loadProfileAt(local);
+    const byKey = new Map(mine.sections.map((s) => [s.key, s]));
+    const missing = [];
+    for (const want of packaged.sections) {
+      const has = byKey.get(want.key);
+      if (!has) {
+        missing.push(`section "${want.key}"`);
+        continue;
+      }
+      if (has.form !== want.form) missing.push(`section "${want.key}" as a ${want.form}`);
+      if (want.required && !has.required) missing.push(`section "${want.key}" as required`);
+      for (const k of want.recordKeys) {
+        if (!has.recordKeys.includes(k)) missing.push(`record key "${want.key}.${k}"`);
+      }
+    }
+    for (const h of packaged.headings) {
+      if (!mine.headings.includes(h)) missing.push(`heading "${h}"`);
+    }
+    for (const f of packaged.frontmatterFields) {
+      if (!mine.frontmatterFields.includes(f)) missing.push(`frontmatter field "${f}"`);
+    }
+    if (packaged.mood && packaged.mood !== mine.mood) missing.push(`mood "${packaged.mood}"`);
+    // Forward slashes, like every other path this reports: the checker names a file the same way
+    // on every platform.
+    const rel = path.relative(config.root, local).split(path.sep).join('/');
+    if (missing.length) out.push({ profile: name, file: rel, missing });
+  }
+  return out;
+}
+
 // The layouts a corpus entry is usually written for. `cnlp init` keeps the ones that match a file,
 // so a project adopting the format starts from its own layout rather than from an example of one.
 // ponytail: path convention only, never content — a decision record filed under docs/references
@@ -272,21 +375,69 @@ export async function proposeCorpus(root) {
  * An entry matching no file is dropped here, which a written config is right to refuse: a glob a
  * project typed and no file answers is a mistake, and a glob this function guessed is a folder the
  * set does not have yet.
+ *
+ * 1 set checked alone still resolves its crossings: `companions` names the sets it crosses into,
+ * each `{ name, dir }`, and the sets beside it join as companions named by their directories. A
+ * companion is read to resolve a reference and never checked. `name` names the checked set when
+ * its directory does not, as in a layout of `<set>/<version>/`.
  */
-export async function configForPath(dir) {
-  const abs = path.resolve(dir);
-  if (!existsSync(abs)) throw new Error(`no such directory: ${dir}`);
+export async function configForPath(dir, { name, companions: named = [] } = {}) {
+  if (!existsSync(path.resolve(dir))) throw new Error(`no such directory: ${dir}`);
+  // The spelling on disk, not the one typed: on a case-insensitive disk `DragonECS-Unity` would
+  // otherwise miss its own directory among the siblings and read itself as a companion.
+  const abs = await realpath(path.resolve(dir));
+  if (!Array.isArray(named)) throw new Error(`companions is a list of { name, dir }, found ${JSON.stringify(named)}`);
   let root;
   let docsets = null;
   let corpus;
-  if (existsSync(path.join(abs, 'index.md'))) {
+  const oneSet = existsSync(path.join(abs, 'index.md'));
+  // A root check already reads every set under it, and a project has no single set to name.
+  if (!oneSet && (name !== undefined || named.length)) {
+    throw new Error(`${abs} is not 1 document set — a name and companions apply to a directory holding an index.md`);
+  }
+  const base = path.basename(abs);
+  const setName = name ?? base;
+  const companions = [];
+  if (oneSet) {
+    if (name !== undefined) checkSetName(name, 'the checked set');
+    for (const c of named) {
+      checkSetName(c.name, 'a companion');
+      if (!c.dir) throw new Error(`companion "${c.name}" names no dir — give the directory of 1 document set`);
+      if (!existsSync(path.resolve(c.dir))) throw new Error(`companion "${c.name}": no such directory: ${path.resolve(c.dir)}`);
+      const at = await realpath(path.resolve(c.dir));
+      // The checked set read again under another name would reach its own pages through the copy.
+      if (at === abs) throw new Error(`companion "${c.name}" is the checked set itself — name another set`);
+      if (!existsSync(path.join(at, 'index.md'))) {
+        throw new Error(`companion "${c.name}": ${at} holds no index.md — name the directory of 1 document set`);
+      }
+      if (c.name === setName) throw new Error(`companion "${c.name}" carries the name of the checked set — name it apart`);
+      if (companions.some((o) => o.name === c.name)) throw new Error(`companion "${c.name}" is named twice — name each set once`);
+      companions.push({ name: c.name, dir: at });
+    }
+    // A set is present because a project vendors it, so the sets beside it are its companions.
+    // A name apart from the directory means no flat layout: the siblings there are other versions
+    // of the same set, and reading them as sets would resolve nothing.
+    // ponytail: a sibling's name is its directory's and is not held to `checkSetName`; a directory
+    // carrying ":" is possible only off Windows, and it would print as a set nobody can reference.
+    if (setName === base) {
+      const parent = path.dirname(abs);
+      for (const entry of (await readdir(parent, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        const at = path.join(parent, entry.name);
+        if (!entry.isDirectory() || entry.name === base || !existsSync(path.join(at, 'index.md'))) continue;
+        // An explicit companion wins, by name or by directory: 1 set is read once.
+        if (companions.some((o) => o.name === entry.name || o.dir === at)) continue;
+        companions.push({ name: entry.name, dir: at });
+      }
+    }
+  }
+  if (oneSet) {
     root = path.dirname(path.dirname(abs));
     docsets = path.basename(path.dirname(abs));
-    corpus = docsetCorpus(`${docsets}/${path.basename(abs)}`);
+    corpus = docsetCorpus(`${globLiteral(docsets)}/${globLiteral(base)}`);
   } else if (await holdsASet(abs)) {
     root = path.dirname(abs);
     docsets = path.basename(abs);
-    corpus = docsetCorpus(`${docsets}/*`);
+    corpus = docsetCorpus(`${globLiteral(docsets)}/*`);
   } else {
     // Neither shape: fall back to the layouts `cnlp init` already knows, so pointing at a project
     // reads the same as pointing at a set.
@@ -301,7 +452,29 @@ export async function configForPath(dir) {
   if (kept.length === 0) {
     throw new Error(`${abs} holds no document this kit knows the layout of — a document set is an index.md beside concepts, api and tasks`);
   }
-  return { path: null, root, profilesDir: null, docsets, corpus: kept, agents: [] };
+  // `companions` is always present, `[]` included: a caller tells a kit that ignores the option
+  // from a set that failed by this field's absence.
+  const rename = setName === base ? {} : { [base]: setName };
+  return { path: null, root, profilesDir: null, docsets, corpus: kept, agents: [], companions, rename };
+}
+
+/** A set name keys every page id, and `:` separates `<set>:<name>`, so a name carrying it reads as a page. */
+function checkSetName(name, whose) {
+  if (typeof name !== 'string' || name === '' || /[:/\\]/.test(name)) {
+    throw new Error(`${JSON.stringify(name)} is no name for ${whose} — a set name is not empty and carries no ":", "/" or "\\"`);
+  }
+}
+
+/**
+ * A directory name as a glob that matches only itself. The corpus is a glob, and a set in
+ * `2.0.0-[rc]` otherwise reads as a character class that matches no directory, which reports
+ * the set as holding no document. A class of 1 character is the escape `fs.glob` honours: it
+ * reads `\` as a separator on Windows.
+ * ponytail: a `{` still opens a brace set, which no escape reaches through `fs.glob`; a set
+ * directory named with braces needs a config instead of a path.
+ */
+function globLiteral(name) {
+  return name.replace(/[[*?]/g, (c) => `[${c}]`);
 }
 
 /** Whether an immediate subdirectory carries an index.md, which is what makes a directory a root. */
@@ -329,10 +502,40 @@ export async function filesFor(entry, root) {
  * Run every corpus entry. Returns the files checked and the issues found, each carrying the
  * project-relative path it came from. Severity is the caller's: an issue is an issue here.
  */
+/**
+ * The bytes a document set costs a reader, split by when they are paid. The index is loaded to
+ * answer any question and a page is loaded to answer 1, so the 2 numbers are different kinds of
+ * cost, and an author trimming the wrong one saves a reader nothing.
+ *
+ * Computed from the documents the caller has already read, so this adds no read of its own.
+ */
+export function setSizes(docs, docsets, rename = {}) {
+  const sets = new Map();
+  for (const { rel, raw } of docs) {
+    const id = renamedIdOf(rel, docsets, rename);
+    if (!id) continue;
+    const set = sets.get(id.docset) ?? { name: id.docset, indexBytes: 0, pages: 0, pageBytes: 0 };
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    if (id.page === 'index') set.indexBytes += bytes;
+    else {
+      set.pages += 1;
+      set.pageBytes += bytes;
+    }
+    sets.set(id.docset, set);
+  }
+  return [...sets.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
 export async function checkProject(config) {
   const issues = [];
   const checked = [];
   const docs = [];
+  // A document the §5 word lists never reach. It is not an issue — nothing in it is wrong — but a
+  // run that says nothing about it reports a conformant corpus over rules that never ran.
+  const foreign = [];
+  // §3: a marked region the file's profile did not shape. Reported for the same reason: a run that
+  // names no exemption reads as a check of every line, and a region is an exemption anybody can write.
+  const regions = [];
   for (const entry of config.corpus) {
     const files = await filesFor(entry, config.root);
     if (files.length === 0) {
@@ -343,10 +546,25 @@ export async function checkProject(config) {
       const raw = await readFile(path.join(config.root, rel), 'utf8');
       checked.push(rel);
       docs.push({ rel, raw });
+      if (!lexiconApplies(raw)) foreign.push(rel);
+      for (const r of parseBlocks(raw).regions) regions.push({ file: rel, ...r });
       for (const issue of bodyIssues(raw, profile)) issues.push({ file: rel, ...issue });
     }
   }
+  // A config from `readConfig` carries neither field: it already reads every set under its root.
+  const rename = config.rename ?? {};
+  // A companion's pages resolve references and are counted nowhere: the run reports on the set it
+  // was pointed at. `docsetCorpus` is the 1 place the shape of a set is written, so it is read here too.
+  const context = [];
+  for (const { name, dir } of config.companions ?? []) {
+    for (const entry of docsetCorpus('.')) {
+      for (const rel of await filesFor(entry, dir)) {
+        const page = rel.split(path.sep).join('/').slice(0, -3);
+        context.push({ set: name, page, raw: await readFile(path.join(dir, rel), 'utf8') });
+      }
+    }
+  }
   // §9 is the 1 rule that needs the whole corpus, so it runs once over the files already read.
-  if (config.docsets) issues.push(...linkIssues(docs, config.docsets));
-  return { checked, issues };
+  if (config.docsets) issues.push(...linkIssues(docs, config.docsets, { context, rename }));
+  return { checked, issues, foreign, regions, sets: config.docsets ? setSizes(docs, config.docsets, rename) : [] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
     "README.md"
   ],
   "dependencies": {
-    "cnlp-kit": "^3.1.3",
+    "cnlp-kit": "^3.9.1",
     "yaml": "^2.5.1"
   },
   "bundleDependencies": [

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