gcf-aif-ext 0.2.7 → 0.3.0

package/lib/validate-card.js

@@ -3,35 +3,45 @@
 const FIELDS = [
   'schema',
   'id',
-  'slug',
+  'type',
+  'title',
   'status',
-  'route',
   'system',
   'depends',
+  'pillars',
   'source',
+  'reopens',
   'tune_count',
   'built_at',
   'created',
 ];
-const REQUIRED = FIELDS.filter((f) => f !== 'built_at');
+const OPTIONAL = ['title', 'reopens', 'built_at'];
+const REQUIRED = FIELDS.filter((f) => !OPTIONAL.includes(f));
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const slugList = (v) => Array.isArray(v) && v.every((s) => SLUG.test(s));
+const text = (v) => (typeof v === 'string' && v.length > 0) || 'must be a non-empty string';
 
 const RULES = {
-  schema: (v) => v === 1 || 'schema must be 1',
-  id: (v) => /^card-\d{3}$/.test(v) || 'id must match card-NNN',
-  slug: (v) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(v) || 'slug must be a lowercase hyphen slug',
+  // Schema 1 cards (`card-NNN` ids, `slug`, `route`) predate the Design Model: say how to move.
+  schema: (v) =>
+    v === 2 ||
+    (v === 1
+      ? 'schema 1 card: rename the file to cards/<slug>.md, set id: <slug>, drop slug and route, ' +
+        'add type: mechanic and pillars: [], set schema: 2'
+      : 'schema must be 2'),
+  id: (v) => SLUG.test(v) || 'id must be a lowercase hyphen slug',
+  type: (v) =>
+    ['mechanic', 'resource'].includes(v) ||
+    'type must be mechanic or resource (a hard unit never becomes a card)',
+  title: (v) => text(v) === true || `title ${text(v)}`,
   status: (v) =>
     ['proposed', 'built', 'tuning'].includes(v) ||
     `status "${v}" is not storable (П1: terminal statuses never live in a file)`,
-  route: (v) => ['soft', 'hard'].includes(v) || 'route must be soft or hard',
-  system: (v) =>
-    (Array.isArray(v) && v.length >= 1 && v.every((s) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(s))) ||
-    'system must list >=1 subsystem slugs',
-  depends: (v) =>
-    (Array.isArray(v) && v.every((d) => /^card-\d{3}$/.test(d))) ||
-    'depends must list card-NNN ids',
-  source: (v) =>
-    /^(GDD#[A-Za-z0-9_-]+|manual|inferred)$/.test(v) ||
-    'source must be GDD#<id>, manual or inferred',
+  system: (v) => (slugList(v) && v.length >= 1) || 'system must list >=1 subsystem slugs',
+  depends: (v) => slugList(v) || 'depends must list unit ids',
+  pillars: (v) => slugList(v) || 'pillars must list pillar ids',
+  source: (v) => /^(GDD#[A-Za-z0-9_-]+|manual)$/.test(v) || 'source must be GDD#<id> or manual',
+  reopens: (v) => text(v) === true || `reopens ${text(v)}`,
   tune_count: (v) => (Number.isInteger(v) && v >= 0) || 'tune_count must be an integer >= 0',
   built_at: (v) =>
     v === null ||
@@ -43,11 +53,12 @@ const RULES = {
 
 const dateStr = (v) => (v instanceof Date ? v.toISOString().slice(0, 10) : String(v));
 
-const UNTIL_OK = /^\[until:\s*(verdict\(card-\d{3}\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]$/;
+const UNTIL_OK = /^\[until:\s*(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]$/;
 
 /** Validate card frontmatter. Returns a list of one-line errors (empty = valid). */
 export function validateCard(data) {
   const errors = [];
+  if (data.schema !== undefined && data.schema !== 2) return [RULES.schema(data.schema)];
   for (const key of REQUIRED) if (!(key in data)) errors.push(`missing field: ${key}`);
   for (const key of Object.keys(data)) {
     if (!FIELDS.includes(key))
@@ -73,7 +84,7 @@ export function validateUntil(body) {
       if (!UNTIL_OK.test(m[0]))
         errors.push(
           `line ${i + 1}: bad until annotation ${m[0]} ` +
-            '(use verdict(card-NNN), retune(system) or manual(text))',
+            '(use verdict(<id>), retune(system) or manual(text))',
         );
     }
   });

package/lib/verdict-fs.js

@@ -1,79 +1,66 @@
 import { readFile, unlink } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { parse, serialize } from './frontmatter.js';
+import { parseBlocks, itemsOf, readRecords } from 'cnlp-kit';
+import { serialize } from './frontmatter.js';
 import { listCards } from './gcf-paths.js';
 import { atomicWrite, resolveInside, withFileRollback } from './safe-path.js';
 import { writeIndex } from './index-gen.js';
 import { isLegal } from './transitions.js';
+import { operationInProgress, commitPaths, dirtyPaths } from './git.js';
+import { blockLines, upsertBlock, openSystemDoc } from './systems-doc.js';
 
-// Slot → systems-doc section map (GCF-PRD §8.2). Deterministic merge: lines are
-// carried verbatim and deduplicated; the LLM compression of `behavior` happens in the
-// card BEFORE the verdict (the skill edits the card), not here.
-const MERGE_MAP = [
-  ['behavior', 'behavior'],
-  ['contract', 'code'],
-  ['feel', 'feel'],
-  ['constraints', 'constraints'],
-];
+const ENVELOPE = /^\S+\.\.\S+ /;
+const real = (lines) => lines.filter((l) => !/^- none\b/.test(l));
 
-function blockLines(body, key) {
-  const m = String(body).match(new RegExp(`^${key}:\\s*\\n((?:- .*\\n?)*)`, 'm'));
+function recordsOf(body, key) {
+  const { lines, sections } = parseBlocks(body);
+  const at = sections.find((s) => s.key === key && !s.value);
 
-  return m ? m[1].split('\n').filter((l) => l.startsWith('- ')) : [];
+  return at ? readRecords(itemsOf(lines, at.line)).records.map((r) => r.values) : [];
 }
 
-function upsertBlock(body, key, addLines) {
-  if (!addLines.length) return body;
-  const existing = new Set(blockLines(body, key));
-  const fresh = addLines.filter((l) => !existing.has(l));
-  if (!fresh.length) return body;
-  const re = new RegExp(`(^${key}:\\s*\\n(?:- .*\\n?)*)`, 'm');
-  if (re.test(body))
-    return body.replace(
-      re,
-      (blk) => `${blk.endsWith('\n') ? blk : `${blk}\n`}${fresh.join('\n')}\n`,
-    );
-
-  return `${body.trimEnd()}\n\n${key}:\n${fresh.join('\n')}\n`;
+const scalar = (body, key) => parseBlocks(body).sections.find((s) => s.key === key)?.value ?? '';
+
+/** A resource rate: an envelope is a range of intent (feel), a comparison is exact (constraint). */
+function rateLines(body, out) {
+  for (const [key, word] of [
+    ['sources', 'source'],
+    ['sinks', 'sink'],
+  ]) {
+    for (const r of recordsOf(body, key)) {
+      out.behavior.push(`- ${word} ${r.name}`);
+      if (ENVELOPE.test(`${r.rate} `)) out.feel.push(`- ${r.name} rate ${r.rate}`);
+      else out.constraints.push(`- ${r.rate}`);
+    }
+  }
 }
 
-// `git commit --only <paths>` is a partial commit, which git refuses outright while a merge
-// or a sequencer operation is in progress. Detect it up front so the failure has a reason.
-const IN_PROGRESS = [
-  'MERGE_HEAD',
-  'CHERRY_PICK_HEAD',
-  'REVERT_HEAD',
-  'rebase-merge',
-  'rebase-apply',
-];
-function operationInProgress(projectDir) {
-  const gitDir = spawnSync('git', ['rev-parse', '--git-dir'], {
-    cwd: projectDir,
-    encoding: 'utf8',
-  });
-  if (gitDir.status !== 0) return null;
-  const dir = path.resolve(projectDir, gitDir.stdout.trim());
-
-  return IN_PROGRESS.find((name) => existsSync(path.join(dir, name))) ?? null;
-}
+/**
+ * Card → systems-doc lines by the fixed map (GCF-PRD §8.2). Deterministic: a record becomes
+ * one line, a bullet stays itself, `- none:` placeholders carry nothing. A line keeps its
+ * `[until: …]` and stays in its own section, where the reader who needs it looks.
+ */
+export function collapseLines(body) {
+  /** @type {Record<string, string[]>} */
+  const out = { purpose: [], code: [], behavior: [], feel: [], constraints: [] };
+  out.purpose.push(...real(blockLines(body, 'intent')));
+  for (const r of recordsOf(body, 'behavior')) {
+    out.behavior.push(`- ${r.input} -> ${r.state} -> ${r.feedback}`);
+  }
 
-function gitCommit(projectDir, message, addPaths) {
-  // Stage and commit exactly the files this verdict touched: `git add -- gcf/` would stage a
-  // user's unrelated edits under gcf/, and rollback only restores what it snapshotted.
-  for (const p of addPaths)
-    spawnSync('git', ['add', '--', p], { cwd: projectDir, stdio: 'ignore' });
-  const res = spawnSync('git', ['commit', '-m', message, '--only', '--', ...addPaths], {
-    cwd: projectDir,
-    encoding: 'utf8',
-  });
-  if (res.status !== 0) throw new Error(`verdict commit failed: ${res.stderr || res.stdout}`);
-
-  return spawnSync('git', ['rev-parse', 'HEAD'], {
-    cwd: projectDir,
-    encoding: 'utf8',
-  }).stdout.trim();
+  out.behavior.push(...real(blockLines(body, 'refusal')), ...real(blockLines(body, 'boundaries')));
+  const persistence = scalar(body, 'persistence');
+  if (persistence && !/^none\b/.test(persistence)) out.behavior.push(`- persists: ${persistence}`);
+  rateLines(body, out);
+  const like = scalar(body, 'feel_like');
+  if (like) out.feel.push(`- ${like}`);
+  for (const r of recordsOf(body, 'feel')) out.feel.push(`- ${r.name} ${r.envelope}`);
+  out.code.push(...real(blockLines(body, 'contract')));
+  out.constraints.push(...real(blockLines(body, 'constraints')));
+  out.constraints.push(...real(blockLines(body, 'interactions')));
+
+  return out;
 }
 
 /** Find the card and refuse an unknown verdict or a transition the lifecycle forbids. */
@@ -95,51 +82,69 @@ async function findVerdictCard(root, cardId, verdict) {
 function planTune({ card, note }) {
   return async () => {
     const data = { ...card.data, status: 'tuning', tune_count: (card.data.tune_count ?? 0) + 1 };
-    const body = note ? upsertBlock(card.body, 'feel', [`- retune: ${note}`]) : card.body;
+    // The remark goes to `tuning:`, the block the agent reads before the rebuild.
+    const body = note ? upsertBlock(card.body, 'tuning', [`- ${note}`]) : card.body;
     await atomicWrite(card.file, serialize(data, body));
   };
 }
 
-function planKill({ root, card, cardId, note, tags, systems, touched }) {
+/** The graveyard line of a killed or dropped unit: `- <id> | <reason> | tags: <tags>`. */
+export async function buryLine(root, id, reason, tags) {
   const gyFile = path.join(root, 'graveyard.md');
-  touched.push(gyFile);
+  const existing = existsSync(gyFile) ? await readFile(gyFile, 'utf8') : '';
+  const line = `- ${id} | ${reason || 'no reason recorded'} | tags: ${tags.join(', ')}\n`;
+  await atomicWrite(gyFile, existing + line);
+}
+
+export const HISTORY_HEAD =
+  '# History — `- <id> | done|collapsed | <date>`, one line per unit built (gcf done) or ' +
+  'card kept by a verdict; the move writes it in the commit that ends the life\n';
+
+/**
+ * The history line of a unit built (`done`) or a card kept (`collapsed`). It goes in id order,
+ * not at the end: branches recording different ids touch different places of the file and merge
+ * cleanly, and a revert of the move takes out exactly its line.
+ */
+export async function recordLine(root, id, event, date = new Date().toISOString().slice(0, 10)) {
+  const file = path.join(root, 'history.md');
+  const old = existsSync(file) ? await readFile(file, 'utf8') : '';
+  // A file kept with CRLF stays CRLF; an empty one starts from the header.
+  const eol = old.includes('\r\n') ? '\r\n' : '\n';
+  const lines = (old.trim() ? old : HISTORY_HEAD).replace(/\s+$/, '').split(/\r?\n/);
+  const at = lines.findIndex((l) => (l.match(/^- (\S+) \|/)?.[1] ?? '') > id);
+  lines.splice(at < 0 ? lines.length : at, 0, `- ${id} | ${event} | ${date}`);
+  await atomicWrite(file, `${lines.join(eol)}${eol}`);
+}
+
+function planKill({ root, card, cardId, note, tags, systems, touched }) {
+  touched.push(path.join(root, 'graveyard.md'));
 
   return async () => {
-    const reason = note || 'no reason recorded';
-    const tagStr = (tags.length ? tags : systems).join(', ');
-    const line = `- ${cardId} | ${card.data.slug} | ${reason} | tags: ${tagStr}\n`;
-    const existing = existsSync(gyFile) ? await readFile(gyFile, 'utf8') : '';
-    await atomicWrite(gyFile, existing + line);
+    await buryLine(root, cardId, note, tags.length ? tags : systems);
     await unlink(card.file);
   };
 }
 
-async function mergeIntoSystem(sysFile, system, card, cardId) {
-  let doc = existsSync(sysFile)
-    ? parse(await readFile(sysFile, 'utf8'))
-    : { data: { system }, body: 'purpose:\n- (fill in)\n' };
+/** Merge the card into one systems doc; a new doc starts from design/'s purpose. */
+async function mergeIntoSystem(root, system, card, cardId) {
+  const doc = await openSystemDoc(root, system);
   let body = doc.body;
-  for (const [slot, section] of MERGE_MAP) {
-    body = upsertBlock(body, section, blockLines(card.body, slot));
+  for (const [section, lines] of Object.entries(collapseLines(card.body))) {
+    body = upsertBlock(body, section, lines);
   }
 
-  // Lines with a live until: move to `open` (GCF-PRD §8.2.5).
-  const openLines = blockLines(card.body, 'interactions').filter((l) => l.includes('[until:'));
-  body = upsertBlock(body, 'open', openLines);
-  await atomicWrite(sysFile, serialize({ ...doc.data, updated_by: cardId }, body));
+  await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: cardId }, body));
 }
 
 function planKeep({ root, card, cardId, systems, touched }) {
   // `system:` names files, and the pre-commit gate validates it only after they are written:
   // `../../x` would already have overwritten a file outside gcf/.
   const sysFiles = systems.map((s) => resolveInside(path.join(root, 'systems'), `${s}.md`));
-  touched.push(...sysFiles);
+  touched.push(...sysFiles, path.join(root, 'history.md'));
 
   return async () => {
-    for (const [i, sysFile] of sysFiles.entries()) {
-      await mergeIntoSystem(sysFile, systems[i], card, cardId);
-    }
-
+    for (const s of systems) await mergeIntoSystem(root, s, card, cardId);
+    await recordLine(root, cardId, 'collapsed');
     await unlink(card.file);
   };
 }
@@ -149,8 +154,9 @@ const PLANS = { tune: planTune, kill: planKill, keep: planKeep };
 /**
  * The one operation that collapses a card (GCF-PRD §8). Atomic: file changes roll back
  * on failure; the verdict commit has the fixed greppable format. `keep` merges into every
- * touched systems doc; `kill` writes the graveyard line; `tune` bumps the counter and
- * appends the human note to the feel slot.
+ * touched systems doc and writes the history line; `kill` writes the graveyard line; `tune`
+ * bumps the counter and
+ * appends the human note to the `tuning` block.
  *
  * The commit runs INSIDE the rollback: it fires the pre-commit gate, which can reject the
  * merged systems doc, and a card unlinked by a commit that never landed is a lost card.
@@ -175,8 +181,16 @@ export async function applyVerdict(
   const touched = [card.file, path.join(root, 'INDEX.md')];
   const systems = card.data.system ?? [];
   const mutate = PLANS[verdict]({ root, card, cardId, note, tags, systems, touched });
+  // The commit takes whole files: a user's own uncommitted edit in a systems doc or the
+  // graveyard would ride along unseen. The card is the verdict's input and may be dirty.
+  const others = touched.filter((f) => f !== card.file && path.basename(f) !== 'INDEX.md');
+  const dirty = commit ? dirtyPaths(projectDir, others) : [];
+  if (dirty.length)
+    throw new Error(
+      `commit or stash these first, the verdict would carry them: ${dirty.join('; ')}`,
+    );
 
-  const message = `gcf(verdict): ${verdict} ${cardId} ${card.data.slug} → ${systems.join(',')}`;
+  const message = `gcf(verdict): ${verdict} ${cardId} → ${systems.join(',')}`;
   /** @type {string | null} */
   let hash = null;
   await withFileRollback(
@@ -184,7 +198,7 @@ export async function applyVerdict(
     async () => {
       await mutate();
       await writeIndex(root);
-      if (commit) hash = gitCommit(projectDir, message, touched);
+      if (commit) hash = commitPaths(projectDir, message, touched);
     },
     { gitCwd: commit ? path.resolve(projectDir) : null },
   );

package/package.json

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

package/profiles/game.md

@@ -0,0 +1,68 @@
+---
+name: game
+description: The CNL-P profile of gcf/game.md — the vision, the scope and the milestones the design units are planned against.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat and the document is named by its fixed path
+
+frontmatter_fields:
+- none: the file is a singleton at a fixed path and carries no machine fields
+
+lexicon_exempt:
+- none: nothing is exempt in the document that bounds the scope
+
+sections:
+- key: logline
+  form: scalar
+  required: yes
+  note: the game in one line
+
+- key: platforms
+  form: bullet-list
+  required: yes
+  note: platform and input, one per line
+
+- key: audience
+  form: bullet-list
+  required: yes
+  note: who plays, one group per line
+
+- key: references
+  form: bullet-list
+  required: no
+  note: "like X, not like Y", one reference per line
+
+- key: scope_in
+  form: bullet-list
+  required: yes
+  note: what the game holds
+
+- key: scope_out
+  form: bullet-list
+  required: yes
+  note: what the game does not hold, or not in this version
+
+- key: milestones
+  form: record-list
+  required: yes
+  record_keys: name, goal
+  optional_record_keys: content
+  note: the closed vocabulary of a unit's milestone field; content is a volume written as a comparison
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor when the file came from a GDD
+
+custom_sections:
+- none: a block that is not listed above belongs to a unit or to PILLARS.md
+
+enforcement:
+- `ai-factory gcf design check` resolves every unit's milestone against this file

package/profiles/glossary.md

@@ -0,0 +1,37 @@
+---
+name: glossary
+description: The CNL-P profile of gcf/glossary.md — one word per concept, the synonyms it forbids, and the project's own units of measure.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat and the document is named by its fixed path
+
+frontmatter_fields:
+- none: the file is a singleton at a fixed path and carries no machine fields
+
+lexicon_exempt:
+- none: the glossary is the lexicon of the project
+
+sections:
+- key: terms
+  form: record-list
+  required: yes
+  record_keys: term, means
+  optional_record_keys: not
+  note: a term the human confirmed, what it means, and the words that may not name it
+
+- key: units
+  form: bullet-list
+  required: no
+  note: units of measure the project adds to the closed list, one per line as "<unit>: <what it measures>"
+
+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)
+- quoted text is data: a GDD quote keeps the designer's own word

package/profiles/pillars.md

@@ -21,7 +21,8 @@ sections:
   form: record-list
   required: yes
   record_keys: statement, invariant, review_question
-  note: pillar count <= 7 and the token budget are enforced by the gcf audit core, not the checker
+  optional_record_keys: id
+  note: pillar count <= 7 and the token budget are enforced by the gcf audit core; id is the slug a design unit cites in pillars:
 
 custom_sections:
 - none: a pillar that needs more than its three keys is not a pillar yet

package/profiles/unit-constraint.md

@@ -0,0 +1,42 @@
+---
+name: unit-constraint
+description: The CNL-P profile of a GCF design unit of type constraint — a platform, performance or size threshold, accepted by a measurement.
+---
+
+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
+
+frontmatter_fields:
+- none: a constraint never becomes a card, so its header lives above the blocks in design/
+
+lexicon_exempt:
+- none: every block is read when the constraint is planned and measured
+
+sections:
+- key: threshold
+  form: bullet-list
+  required: yes
+  note: one comparison per line, "<subject> <op> <value> <unit>"
+
+- key: measure
+  form: bullet-list
+  required: yes
+  note: how the threshold is measured and on what - device, build, scene
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+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/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-entity.md

@@ -0,0 +1,38 @@
+---
+name: unit-entity
+description: The CNL-P profile of a GCF design unit of type entity — the shape of a data noun before code holds it.
+---
+
+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
+
+frontmatter_fields:
+- none: an entity never becomes a card, so its header lives above the blocks in design/
+
+lexicon_exempt:
+- none: every block is read when the entity is planned and coded
+
+sections:
+- key: fields
+  form: record-list
+  required: yes
+  record_keys: name, holds
+  note: one record per field - what it holds, never its allowed values, which belong to a rule
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+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/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-mechanic.md

@@ -0,0 +1,106 @@
+---
+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.
+---
+
+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
+
+frontmatter_fields:
+- schema
+- id
+- type
+- title
+- status
+- system
+- depends
+- pillars
+- source
+- reopens
+- tune_count
+- built_at
+- created
+
+lexicon_exempt:
+- none: every block is read when the unit is planned, built or played
+
+sections:
+- key: intent
+  form: bullet-list
+  required: yes
+  note: why the mechanic exists, in the designer's words
+
+- key: behavior
+  form: record-list
+  required: yes
+  record_keys: input, state, feedback
+  note: one record per chain - player input, the state it changes, the feedback the player sees
+
+- key: refusal
+  form: bullet-list
+  required: yes
+  note: what happens when the action is not allowed - no resource, invalid target, already active
+
+- key: boundaries
+  form: bullet-list
+  required: yes
+  note: zero, maximum, overflow, simultaneity; an exact limit is a comparison at the end of its line
+
+- key: persistence
+  form: scalar
+  required: yes
+  note: what survives a reload, a session or a match
+
+- key: feel_like
+  form: scalar
+  required: yes
+  note: the comparison "like X, not like Y"
+
+- key: feel
+  form: record-list
+  required: yes
+  record_keys: name, envelope
+  note: one record per tunable value; an envelope "a..b <unit>" is the only legal range of intent
+
+- 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
+
+- key: interactions
+  form: bullet-list
+  required: yes
+  note: card stage, absent in design/ - "<other id>: how the two cross", one line per crossing
+
+- key: constraints
+  form: bullet-list
+  required: yes
+  note: negative constraints, one prohibition per line, checkable by an analyzer or a reviewer
+
+- key: miss_criterion
+  form: scalar
+  required: yes
+  note: the one question the game in hand answers; the human answers it at the verdict
+
+- key: tuning
+  form: bullet-list
+  required: no
+  note: card stage only - one verdict remark per tune, read before the rebuild
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+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/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding