gcf-aif-ext 0.20.2 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,6 +4,29 @@ The format has its own version from here on. It used to be stamped with the rele
4
4
  an ADR extension, which made a breaking change to the format invisible inside that project's
5
5
  patch release.
6
6
 
7
+ ## 3.10.0
8
+
9
+ §5 held every project to 1 shared language and gave none of them a place for its own. A term used
10
+ across documents was defined on 1 page or on none, and nothing stopped a second word for it.
11
+
12
+ ### Added
13
+
14
+ - **§5: a project glossary extends the lexicon.** `GLOSSARY.md` beside `cnlp.config.json` holds a
15
+ project's own terms. `cnlp check` finds it by name, with no corpus entry and no config key, and holds
16
+ it to the new `glossary` profile. A directory checked by path reads no glossary.
17
+ - **`avoid:` is the project's deny list.** Every word a `terms:` record lists under it is rejected in
18
+ every document the corpus names, quoted text excepted, and the glossary itself is not checked for
19
+ it. A word matches as written, in any script: inflection is a rule of 1 language.
20
+ - **`profiles/glossary.md`**: a `purpose:` block and a `terms:` record-list of `term`, `means` and an
21
+ optional `avoid`.
22
+ - **The `cnlp-glossary` skill**, which `cnlp init` installs beside the other 2: it asks which thing a
23
+ vague word names, tests a term against edge cases and the code, and records it the moment the
24
+ operator agrees, creating the file at the first term.
25
+ - **A 4th line in the agent block**: name each thing by the term `GLOSSARY.md` defines. A project
26
+ holding the 3-line block gets the drift report until it pastes the new one.
27
+ - **`bodyIssues(raw, profile, { avoid })`** and `lexiconIssues(lines, mood, avoid)` take the words,
28
+ for a project calling the checker directly; `glossaryAvoids(raw)` in `./config` reads them.
29
+
7
30
  ## 3.9.1
8
31
 
9
32
  ### Added
@@ -76,7 +76,7 @@ must not overwrite. What the copy adds is the vocabulary it was copied for, and
76
76
  reported.
77
77
 
78
78
  `cnlp init` also prints the block to paste into `AGENTS.md`, `CLAUDE.md` or whatever file your
79
- agent reads. Three lines, and they are the rules no skill announces: an installed skill states
79
+ agent reads. Four lines, and they are the rules no skill announces: an installed skill states
80
80
  its own task in its description, and a standing rule answers to no task description. It prints
81
81
  rather than writes: your agent file is yours.
82
82
 
@@ -94,6 +94,31 @@ before a single body moves. Then, per document, it lists the source's rules, rew
94
94
  each rule against the result, and names anything in the result that has no origin in the source.
95
95
  A contradiction it finds in the prose is reported, never resolved silently — that decision is yours.
96
96
 
97
+ ### Keep a project glossary
98
+
99
+ The standard's §5 lexicon is the language every project shares. The words your project names its
100
+ own things by are yours, and they live in `GLOSSARY.md` beside `cnlp.config.json`:
101
+
102
+ ```
103
+ purpose:
104
+ - name the things a shop sells and who buys them
105
+
106
+ terms:
107
+ - term: Customer
108
+ means: a person or a company that places an Order
109
+ avoid: client, buyer
110
+ ```
111
+
112
+ - **Writing the file is the whole of adopting it.** No corpus entry, no config key: `cnlp check`
113
+ finds it by name and holds it to the `glossary` profile.
114
+ - **`avoid:` is your own deny list.** Every word it lists is rejected in every document the corpus
115
+ names — `AGENTS.md:3: "client" is a word the glossary avoids — write "Customer"`. Quoted text is
116
+ data and passes, and the glossary itself is not checked for the words it names.
117
+ - It matches a word as written, in any script, so list every form you mean: `client, clients`.
118
+ - **The `cnlp-glossary` skill builds it with you.** It asks which thing a vague word names, tests a
119
+ term against edge cases and the code, writes the term the moment you agree, and creates the file
120
+ at the first one. The agent block `cnlp init` prints tells your agent to speak in those terms.
121
+
97
122
  ### Document a library or a framework
98
123
 
99
124
  Run the `cnlp-docset` skill against whatever you found, and name a directory to write into. The
@@ -184,6 +209,7 @@ meant a three-way merge. A package boundary is what makes upgrading a version bu
184
209
  | `adr` | an architecture decision record |
185
210
  | `guide` | a repository guide such as `AGENTS.md` |
186
211
  | `reference` | a checklist or protocol a skill loads by path |
212
+ | `glossary` | a project's `GLOSSARY.md` — its own terms, and the words each one replaces |
187
213
  | `docset` | the index of a library's documentation — one whole working program, and the closed list of what the library offers |
188
214
  | `concept` | one model the API pages of that library rest on |
189
215
  | `api` | one capability: its symbols, its contract, and one example |
@@ -385,7 +385,7 @@ if (command === 'init') {
385
385
  console.log('A project documenting no library deletes "docsets" and that directory.');
386
386
  // Printed and not written: an agent file is a file the project owns, and its content is a
387
387
  // decision about how that project's agent works. The operator pastes it where their agent reads.
388
- // 3 lines and not 5: an installed skill announces its own task through its description, so the
388
+ // 4 lines and not 6: an installed skill announces its own task through its description, so the
389
389
  // block states only what a skill cannot — a standing rule answers to no task description.
390
390
  console.log(`\nPaste this into AGENTS.md, CLAUDE.md, or whatever file your agent reads:\n`);
391
391
  console.log(AGENT_BLOCK.join('\n'));
@@ -317,6 +317,19 @@ domain term — an entity handle, a file handle — that a word-level pattern ca
317
317
  verb, so the verb is left to review. That is the same enforced-versus-reviewed split the
318
318
  passive rule states for irregular participles.
319
319
 
320
+ **A project glossary extends the lexicon.** Every rule above belongs to this format and names no
321
+ project. A project's own terms live in `GLOSSARY.md` beside its `cnlp.config.json`, held to the
322
+ `glossary` profile: it is where `define a specialized term once` happens for a term more than 1
323
+ document uses, and it is the one list in this section the project writes rather than this file.
324
+
325
+ - a `terms:` record names 1 thing by 1 `term`, and its `avoid:` lists the words that name the same thing.
326
+ - a word an `avoid:` lists is rejected in every document the corpus names, the way a deny-list word is:
327
+ quoted text is still data, and the glossary itself, which names the word, is not checked for it.
328
+ - a word matches as written, in any script: the project writes the glossary in its own language, so
329
+ inflection is not this file's to know, and a form the glossary does not list is not rejected.
330
+ - a document set checked by path reads no glossary: it is written for another project, whose glossary
331
+ is not the one sitting above it.
332
+
320
333
  ## 6. No section restates another
321
334
 
322
335
  Each fact appears once, in the block that owns it.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cnlp-kit",
3
- "version": "3.9.1",
3
+ "version": "3.10.0",
4
4
  "description": "CNL-P — a format for documents an agent has to read precisely. The standard, its profiles, and the checker that holds them.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: glossary
3
+ description: The CNL-P profile of a project glossary — the terms a project's documents and its agent name things by, each with the words it replaces.
4
+ ---
5
+
6
+ format: cnlp-format.md
7
+
8
+ mood: declarative
9
+
10
+ headings:
11
+ - none: a glossary is one flat run of blocks, and its fixed file name carries the title
12
+
13
+ frontmatter_fields:
14
+ - none: a glossary is found by its fixed name at the project root, so nothing routes on a field
15
+
16
+ lexicon_exempt:
17
+ - none: a glossary has no frontmatter, so nothing is exempt
18
+
19
+ sections:
20
+ - key: purpose
21
+ form: bullet-list
22
+ required: yes
23
+ note: what the project is, and which part of it these terms name, in 1 or 2 lines
24
+
25
+ - key: terms
26
+ form: record-list
27
+ required: yes
28
+ record_keys: term, means
29
+ optional_record_keys: avoid
30
+ note: term is the 1 word every document uses; means says what the thing is in 1 or 2 sentences, not how code works with it; avoid is a comma list
31
+
32
+ custom_sections:
33
+ - none: a project fills this from the vocabulary its own glossary already uses
34
+
35
+ enforcement:
36
+ - `npx cnlp check` holds `GLOSSARY.md` beside `cnlp.config.json` to this profile, and needs no corpus entry for it
37
+ - `npx cnlp check` reports every word an `avoid:` value lists, in every other document the corpus names
38
+ - any issue is an error: a word the glossary avoids is a second name for a thing that has 1
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: cnlp-glossary
3
+ description: Build and keep the project glossary, GLOSSARY.md — challenge a term the operator uses two ways, pin a vague word to one term, test it against edge cases and the code, and record it the moment it is agreed. Use when discussing project terminology, naming a new concept, or editing GLOSSARY.md.
4
+ ---
5
+
6
+ mode: cnlp_glossary
7
+
8
+ purpose:
9
+ - keep 1 glossary per project, `GLOSSARY.md` beside `cnlp.config.json`, so the operator, the agent and every document name a thing by 1 word
10
+ - record a term in the turn the operator agrees to it, not in a batch at the end of the session
11
+ - turn each word a term replaces into an `avoid:` value, which `npx cnlp check` then rejects in every document the corpus names
12
+
13
+ inputs:
14
+ - none: the skill reads the conversation, `GLOSSARY.md` when it exists, and the code the operator names
15
+
16
+ preconditions:
17
+ - `cnlp.config.json` sits at the project root: the check reads `GLOSSARY.md` beside it, and finds no glossary anywhere else
18
+
19
+ scope:
20
+ - act on `GLOSSARY.md` only; rewrite another document that uses an avoided word only when the operator agrees to it
21
+ - hold the glossary to the terms of this project: the §5 lexicon of the standard already governs the common words
22
+
23
+ forbidden_behaviors:
24
+ - do not record a term the operator has not agreed to: the check enforces every `avoid:` value, so a guess there becomes a rule
25
+ - do not write an implementation detail into `means:`: the glossary says what a thing is, and the code says how it works
26
+ - do not add a general programming term: a timeout or an error type means what it means in every project
27
+ - do not create `GLOSSARY.md` before the operator agrees to the first term: a glossary holding no term carries nothing to enforce
28
+ - do not resolve a contradiction between what the operator says and what the code does: report it, because the operator decides which 1 is right
29
+ - do not list a word under `avoid:` that names a different thing: it rejects a correct line in every document
30
+
31
+ outputs:
32
+ - `GLOSSARY.md` at the project root, holding 1 record per agreed term
33
+ - per session: the terms added or changed, and the document lines the check names for an avoided word
34
+
35
+ workflow:
36
+ 1. read `GLOSSARY.md` when it exists, and read its shape with `npx cnlp print glossary`
37
+ 2. compare each word the operator uses against `terms:`, and ask which thing is meant when it conflicts with a `means:` or appears in an `avoid:`
38
+ 3. ask which thing a vague or overloaded word names, and present 1 term for it with the words it replaces
39
+ 4. present a concrete case at the boundary between 2 terms, and ask which term owns it
40
+ 5. compare what the operator states against the code, and report each place the code does otherwise
41
+ 6. write the agreed term into `terms:` in the same turn: `term`, `means` in 1 or 2 sentences, and `avoid` with the words it replaces
42
+ 7. write `GLOSSARY.md` with a `purpose:` block and the first record when the file does not exist yet
43
+ 8. run `npx cnlp check` and fix what it reports in `GLOSSARY.md`
44
+ 9. report every line of another document the check names for an avoided word, and rewrite those lines when the operator agrees
45
+ 10. name a decision record to the operator only when the choice is hard to reverse, surprising without context, and the result of a real trade-off
46
+
47
+ invocation:
48
+ - Claude Code: `/cnlp-glossary`, once this folder sits in `.claude/skills/`
49
+ - Codex: `$cnlp-glossary`, once this folder sits in its skills directory
50
+ - any other agent: read `skills/cnlp-glossary/SKILL.md` and follow it; the body is the instruction
@@ -236,9 +236,10 @@ export async function loadProfile(name, opts) {
236
236
  /**
237
237
  * Body conformance with the profile and with the shared lexicon. Returns [{ line, message }]
238
238
  * sorted by line; the caller decides the severity. A line number of 0 means the issue is
239
- * about the document as a whole.
239
+ * about the document as a whole. `avoid` is a project glossary's words, as `glossaryAvoids` in
240
+ * `config.js` reads them: the project's own deny list, run beside the one this file carries.
240
241
  */
241
- export function bodyIssues(raw, profile) {
242
+ export function bodyIssues(raw, profile, { avoid = [] } = {}) {
242
243
  const { lines, prose, sections, headings, fences } = parseBlocks(raw);
243
244
  const issues = [];
244
245
  const at = (line, message) => issues.push({ line, message });
@@ -309,7 +310,7 @@ export function bodyIssues(raw, profile) {
309
310
  }
310
311
 
311
312
  // A region is exempt from the file's shape, not from the language: the lexicon reads it.
312
- issues.push(...lexiconIssues(prose, profile.mood));
313
+ issues.push(...lexiconIssues(prose, profile.mood, avoid));
313
314
  return issues.sort((a, b) => a.line - b.line);
314
315
  }
315
316
 
@@ -525,9 +526,10 @@ const UNCLOSED = [
525
526
  /**
526
527
  * §5 lexicon. One rule set for every profile, except the active voice: `mood` decides whether the
527
528
  * document has an actor to name, so a caller reaching this directly passes the profile's mood or
528
- * gets every rule that holds whatever the register is.
529
+ * gets every rule that holds whatever the register is. `avoid` is `[{ word, term, re }]`, the
530
+ * words a project glossary replaces: unlike the lists above it is the project's, so any script.
529
531
  */
530
- export function lexiconIssues(lines, mood = '') {
532
+ export function lexiconIssues(lines, mood = '', avoid = []) {
531
533
  const issues = [];
532
534
  lines.forEach((l, i) => {
533
535
  const line = i + 1;
@@ -551,6 +553,9 @@ export function lexiconIssues(lines, mood = '') {
551
553
  }
552
554
  const deny = text.match(DENY);
553
555
  if (deny) issues.push({ line, message: `deny-list word "${deny[0]}"` });
556
+ for (const { word, term, re } of avoid) {
557
+ if (re.test(text)) issues.push({ line, message: `"${word}" is a word the glossary avoids — write "${term}"` });
558
+ }
554
559
  const spelled = text.match(SPELLED_THRESHOLD);
555
560
  if (spelled) issues.push({ line, message: `"${spelled[0]}" — a threshold is a digit` });
556
561
  const limit = text.match(AMBIGUOUS_LIMIT);
@@ -6,10 +6,35 @@
6
6
  import { existsSync } from 'node:fs';
7
7
  import { glob, readdir, readFile, realpath } from 'node:fs/promises';
8
8
  import path from 'node:path';
9
- import { bodyIssues, lexiconApplies, loadProfileAt, pageRefs, parseBlocks, resolveDoc } from './cnlp.js';
9
+ import { bodyIssues, itemsOf, lexiconApplies, loadProfileAt, pageRefs, parseBlocks, readRecords, resolveDoc } from './cnlp.js';
10
10
 
11
11
  export const CONFIG_NAME = 'cnlp.config.json';
12
12
 
13
+ // §5: a project's own terms. A fixed name beside the config, so writing the file is the whole of
14
+ // adopting it: no key to add, and the skill that writes the first term edits no config.
15
+ export const GLOSSARY_NAME = 'GLOSSARY.md';
16
+
17
+ /**
18
+ * The words a glossary's `terms:` records list under `avoid:`, each with the term that replaces it.
19
+ * The pattern bounds a word by any script's letters, not by `\b`, which reads only ASCII: a glossary
20
+ * is the project's, and the project writes it in its own language.
21
+ * ponytail: a word matches as written, so `client` does not catch `clients` — the glossary lists
22
+ * every form it means to reject, because inflection is a rule of 1 language and this reads any.
23
+ */
24
+ export function glossaryAvoids(raw) {
25
+ const { lines, sections } = parseBlocks(raw);
26
+ const at = sections.find((s) => s.key === 'terms');
27
+ if (!at) return [];
28
+ const out = [];
29
+ for (const { values } of readRecords(itemsOf(lines, at.line)).records) {
30
+ for (const word of (values.avoid ?? '').split(',').map((w) => w.trim().replace(/^[`"']|[`"']$/g, '')).filter(Boolean)) {
31
+ const body = word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
32
+ out.push({ word, term: values.term, re: new RegExp(`(?<![\\p{L}\\p{N}_])${body}(?![\\p{L}\\p{N}_])`, 'iu') });
33
+ }
34
+ }
35
+ return out;
36
+ }
37
+
13
38
  /** Nearest `cnlp.config.json` at or above a directory, or null. */
14
39
  export function findConfig(from = process.cwd()) {
15
40
  let dir = path.resolve(from);
@@ -250,6 +275,7 @@ export const AGENT_BLOCK = [
250
275
  '- the CNL-P standard is the authority on document form: read it with `npx cnlp print format`',
251
276
  '- run `npx cnlp check` before a commit that touches a document the corpus names',
252
277
  "- load a library's documentation with `npx cnlp docs`, which writes every set's index in reading order",
278
+ '- name each thing by the term `GLOSSARY.md` defines for it, and do not use a word its `avoid:` lists',
253
279
  ];
254
280
 
255
281
  // The 2 files an agent reads by convention, which are the 2 the corpus proposal below already
@@ -536,19 +562,30 @@ export async function checkProject(config) {
536
562
  // §3: a marked region the file's profile did not shape. Reported for the same reason: a run that
537
563
  // names no exemption reads as a check of every line, and a region is an exemption anybody can write.
538
564
  const regions = [];
539
- for (const entry of config.corpus) {
565
+ // §5: the glossary joins the corpus by being present. A written config only: a directory checked
566
+ // by path is a set produced for another project, and the directory above it is not that project.
567
+ const glossaryAt = config.path ? path.join(config.root, GLOSSARY_NAME) : null;
568
+ const avoid = glossaryAt && existsSync(glossaryAt) ? glossaryAvoids(await readFile(glossaryAt, 'utf8')) : [];
569
+ const corpus = glossaryAt && existsSync(glossaryAt)
570
+ ? [...config.corpus, { profile: 'glossary', glob: GLOSSARY_NAME, implicit: true }]
571
+ : config.corpus;
572
+ for (const entry of corpus) {
540
573
  const files = await filesFor(entry, config.root);
541
574
  if (files.length === 0) {
542
575
  throw new Error(`corpus entry ${JSON.stringify(entry.glob)} matches no file under ${config.root}`);
543
576
  }
544
577
  const profile = await profileFor(entry.profile, config.profilesDir);
545
578
  for (const rel of files) {
579
+ // A corpus entry the project wrote over the glossary already read it, with the profile it named.
580
+ if (entry.implicit && checked.includes(rel)) continue;
546
581
  const raw = await readFile(path.join(config.root, rel), 'utf8');
547
582
  checked.push(rel);
548
583
  docs.push({ rel, raw });
549
584
  if (!lexiconApplies(raw)) foreign.push(rel);
550
585
  for (const r of parseBlocks(raw).regions) regions.push({ file: rel, ...r });
551
- for (const issue of bodyIssues(raw, profile)) issues.push({ file: rel, ...issue });
586
+ // The glossary is where an avoided word is named, so it is the 1 file the words do not reach.
587
+ const words = rel === GLOSSARY_NAME ? [] : avoid;
588
+ for (const issue of bodyIssues(raw, profile, { avoid: words })) issues.push({ file: rel, ...issue });
552
589
  }
553
590
  }
554
591
  // A config from `readConfig` carries neither field: it already reads every set under its root.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.20.2",
3
+ "version": "0.21.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -38,11 +38,12 @@
38
38
  "schemas",
39
39
  "profiles",
40
40
  "hooks",
41
+ "GLOSSARY.md",
41
42
  "LICENSE",
42
43
  "README.md"
43
44
  ],
44
45
  "dependencies": {
45
- "cnlp-kit": "^3.9.1",
46
+ "cnlp-kit": "^3.10.0",
46
47
  "yaml": "^2.5.1"
47
48
  },
48
49
  "bundleDependencies": [
package/profiles/game.md CHANGED
@@ -54,6 +54,11 @@ sections:
54
54
  optional_record_keys: content, play
55
55
  note: the closed vocabulary of a unit's and a work item's milestone field, in build order; each is the smallest slice of the game that can be played; play is the question its play answers; content is a volume written as a comparison
56
56
 
57
+ - key: units
58
+ form: bullet-list
59
+ required: no
60
+ note: units of measure the project adds to the closed list, one per line as "<unit>: <what it measures>"
61
+
57
62
  - key: provenance
58
63
  form: record-list
59
64
  required: no
@@ -66,3 +71,4 @@ custom_sections:
66
71
 
67
72
  enforcement:
68
73
  - `ai-factory gcf design check` resolves every unit's and work item's milestone against this file
74
+ - a number in a unit carries a unit of the closed list or of `units:` (M5)
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: glossary
3
- 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.
3
+ description: The CNL-P profile of a project glossary — the terms a project's documents and its agent name things by, each with the words it replaces.
4
4
  ---
5
5
 
6
6
  format: cnlp-format.md
@@ -8,30 +8,31 @@ format: cnlp-format.md
8
8
  mood: declarative
9
9
 
10
10
  headings:
11
- - none: the body is flat and the document is named by its fixed path
11
+ - none: a glossary is one flat run of blocks, and its fixed file name carries the title
12
12
 
13
13
  frontmatter_fields:
14
- - none: the file is a singleton at a fixed path and carries no machine fields
14
+ - none: a glossary is found by its fixed name at the project root, so nothing routes on a field
15
15
 
16
16
  lexicon_exempt:
17
- - none: the glossary is the lexicon of the project
17
+ - none: a glossary has no frontmatter, so nothing is exempt
18
18
 
19
19
  sections:
20
+ - key: purpose
21
+ form: bullet-list
22
+ required: yes
23
+ note: what the project is, and which part of it these terms name, in 1 or 2 lines
24
+
20
25
  - key: terms
21
26
  form: record-list
22
27
  required: yes
23
28
  record_keys: term, means
24
- optional_record_keys: not
25
- note: a term the human confirmed, what it means, and the words that may not name it
26
-
27
- - key: units
28
- form: bullet-list
29
- required: no
30
- note: units of measure the project adds to the closed list, one per line as "<unit>: <what it measures>"
29
+ optional_record_keys: avoid
30
+ note: term is the 1 word every document uses; means says what the thing is in 1 or 2 sentences, not how code works with it; avoid is a comma list
31
31
 
32
32
  custom_sections:
33
- - none: a block that is not listed above belongs to a unit
33
+ - none: a project fills this from the vocabulary its own glossary already uses
34
34
 
35
35
  enforcement:
36
- - `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
37
- - quoted text is data: a GDD quote keeps the designer's own word
36
+ - `npx cnlp check` holds `GLOSSARY.md` beside `cnlp.config.json` to this profile, and needs no corpus entry for it
37
+ - `npx cnlp check` reports every word an `avoid:` value lists, in every other document the corpus names
38
+ - any issue is an error: a word the glossary avoids is a second name for a thing that has 1
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: plan
3
+ description: The CNL-P profile of a work item's plan — what the code holds, what was chosen and why, the tasks, the pillars it touches, how it is checked; each fact said once.
4
+ ---
5
+
6
+ format: cnlp-format.md
7
+
8
+ mood: declarative
9
+
10
+ headings:
11
+ - none: the blocks carry the structure; a `#` title and the `##` sections aif-plan or GCF add (Settings, Handoff, Outcome) are read past, not shaped
12
+
13
+ frontmatter_fields:
14
+ - none: the plan is found by the item's `plan:` path and carries no machine fields
15
+
16
+ lexicon_exempt:
17
+ - none: nothing is exempt in a plan an agent implements from
18
+
19
+ sections:
20
+ - key: context
21
+ form: bullet-list
22
+ required: yes
23
+ note: facts found in the code and the readset, one per line; the item's own text is not restated
24
+
25
+ - key: decisions
26
+ form: record-list
27
+ required: yes
28
+ record_keys: id, pick, why
29
+ optional_record_keys: rejects, cost
30
+ note: one choice per record, `id` as d1, d2…; `rejects` names the option not taken and why; `cost` the accepted price; a task cites a decision by its id and does not repeat it
31
+
32
+ - key: tasks
33
+ form: bullet-list
34
+ required: yes
35
+ note: one task per line as `- [ ] t1 <action> (d2, d3)`, grouped under `### Phase N: <name>` lines; aif-implement ticks each
36
+
37
+ - key: pillar_check
38
+ form: bullet-list
39
+ required: yes
40
+ note: one line per pillar the work touches, as `<pillar>: <effect>`; `untouched: <pillars>` lines <= 1
41
+
42
+ - key: verification
43
+ form: bullet-list
44
+ required: yes
45
+ note: the commands that prove it, then what the human checks by hand
46
+
47
+ custom_sections:
48
+ - none: a fact that fits no block belongs to the item or to a decision
49
+
50
+ enforcement:
51
+ - `ai-factory gcf plan check` lists every form problem as a `format:` line, and never blocks on one: a format line is polish an improve pass applies
52
+ - a plan already in work (a ticked task) is not asked to change its form
@@ -33,7 +33,7 @@ workflow:
33
33
  7. fill `behavior:` and `constraints:` with 1 placeholder each, annotated `[until: manual(first verdict touching <name>)]`: the profile requires both blocks, and a `manual(...)` trigger is not an audit finding
34
34
  8. write a constraint the human states out loud into `constraints:`, and do not interview subsystem by subsystem for more: unanswered questions on adoption day are the staleness this framework exists to remove
35
35
  9. draft `PILLARS.md` by the interview in the `gcf-init` skill, steps 4..8, and do not restate that interview here
36
- 10. run `npx --yes cnlp-kit check` (it covers the systems docs and PILLARS of `cnlp.config.json`, not design units), then `ai-factory gcf lint` over each new systems doc, then `ai-factory gcf index`
36
+ 10. run `npx --yes cnlp-kit check` (it covers the systems docs and PILLARS of `cnlp.config.json` and `GLOSSARY.md`, not design units), then `ai-factory gcf lint` over each new systems doc, then `ai-factory gcf index`
37
37
  11. ask the human to run `ai-factory gcf hooks-install`; when it refuses over a foreign pre-commit, hand them the chain line it prints
38
38
  12. state the next step: an old design document goes through `/gcf-ingest` into `gcf/design/`, new work starts at `/gcf-card`
39
39
 
@@ -36,7 +36,7 @@ outputs:
36
36
  - `gcf/backlog.md`: one `- <id>` line per new unit, appended at the end
37
37
  - a question record in `gcf/open-questions.md`: `- id: q-NNN`, then `lens:`, `sections:`, `sys:`, `class: D1|D2`, `question:`, `proposed:`, and `blocks: <ids>` when the answer gates units
38
38
  - a D2 record adds `assumed:` (what the agent took as given) and `until:` (when it expires, in the `verdict(<id>)`, `retune(system)` or `manual(text)` form)
39
- - `gcf/game.md` and `gcf/glossary.md` proposals in the forms of `templates/game.md` and `templates/glossary.md`, written only after the human confirms them
39
+ - `gcf/game.md` and `GLOSSARY.md` proposals in the forms of `templates/game.md` and `templates/glossary.md`, written only after the human confirms them
40
40
 
41
41
  workflow:
42
42
  1. when `gcf/systems/` is empty and the repository already holds game code, tell the human `impl?` marks are blind without `/gcf-adopt`, and offer to run it first
@@ -50,18 +50,18 @@ workflow:
50
50
  9. classify each number before an envelope: a tunable value (duration, speed, damage, cost, rate) gets value ± `envelope_default_spread` from `gcf/config.yml`, rounded outward for an integer
51
51
  10. write that envelope into the slot and a D2 record for it, and cite the record as `assumed: q-NNN` beside the quote
52
52
  11. keep counts, hard limits and performance thresholds exact as comparisons
53
- 12. ask about a unit of measure outside the closed list (bare `px`, a currency): it becomes a question, or a `units:` entry of the glossary the human confirms
53
+ 12. ask about a unit of measure outside the closed list (bare `px`, a currency): it becomes a question, or a `units:` entry of `gcf/game.md` the human confirms
54
54
  13. run the completeness lenses per unit - input, state, feedback, refusal, boundaries, persistence - and leave each unanswered lens as `TBD` in its slot: the questions come when `/gcf-card` takes the unit
55
55
  14. run the coherence lenses over the set and send their findings to questions now: interaction matrix, loop closure, economy, progression, dictionary
56
56
  15. record `depends:` between units from the interaction matrix: units that write the same state
57
- 16. propose the glossary from the dictionary lens: one term per concept and its forbidden synonyms; keep the GDD's own words in unit text until the human confirms a term
57
+ 16. propose the glossary from the dictionary lens: one term per concept, and under `avoid:` only a word wrong in every document; keep the GDD's own words in unit text until the human confirms a term
58
58
  17. on a re-import run `ai-factory gcf design check`: a unit whose quote is no longer verbatim gets `flags: src-changed`, a unit whose anchor the GDD removed gets `flags: orphan`; `gcf anchor` already rewrote renamed anchors
59
59
  18. on a re-import, raise a D1 for a work item or a collapsed system that cites a changed anchor, and run steps 3..16 over the text no quote covers any more
60
60
  19. mark a unit whose nouns match the `purpose` or the `code` paths of an existing systems doc with `flags: impl?`: the mechanic may already ship, and the human drops it with `ai-factory gcf drop`
61
61
  20. append the new ids to `gcf/backlog.md`, run `ai-factory gcf design check`, fix every blocking finding, then run `ai-factory gcf anchor <file> --done`: until then a rerun gets the same delta
62
62
  21. record the import with `ai-factory gcf design commit -m "import <file>"`
63
63
  22. report the package, ordered: D1 questions (the main product), pillar candidates, glossary conflicts, the design summary per subsystem, D2 assumptions; say when `impl?` was blind
64
- 23. write `gcf/game.md` and `gcf/glossary.md` as the human confirms them, and record them with `ai-factory gcf design commit`
64
+ 23. write `gcf/game.md` and `GLOSSARY.md` as the human confirms them, and record them with `ai-factory gcf design commit`
65
65
  24. state the next step: answer the D1s, confirm pillars and glossary, then take the first unit with `/gcf-card <id>`
66
66
 
67
67
  invocation:
@@ -26,7 +26,7 @@ workflow:
26
26
  4. otherwise start from the pillar candidates an import left in `gcf/open-questions.md`; with none and `gcf/PILLARS.md` empty, draw candidates from `gcf/game.md` and the units of `gcf/design/`
27
27
  5. ask the human for the game's core promise, then for 2..7 pillars: each a name of 2..4 words, a statement, a negative invariant and a review question; its id, which units cite, is the name in Latin lowercase joined by hyphens
28
28
  6. write `gcf/PILLARS.md` with the confirmed pillars, word for word, in the record-list form of `.ai-factory/extensions/gcf-aif-ext/templates/PILLARS.md`: the human decides each pillar, you only write it down
29
- 7. run `npx --yes cnlp-kit check` and fix form issues it reports; it checks only the systems docs and PILLARS of `cnlp.config.json`: units go through `ai-factory gcf design check`, the tree through `ai-factory gcf audit`
29
+ 7. run `npx --yes cnlp-kit check` and fix the form issues it reports in the systems docs, PILLARS and `GLOSSARY.md`: units go through `ai-factory gcf design check`, the tree through `ai-factory gcf audit`
30
30
  8. record the pillars with `ai-factory gcf design commit -m "pillars"`
31
31
  9. ask the human to run `ai-factory gcf hooks-install`: the commit gate is theirs to arm
32
32
  10. state the next step: import a GDD with `/gcf-ingest`, or start the design with `/gcf-vision` when there is none
@@ -41,7 +41,7 @@ workflow:
41
41
  8. state the next step: `/gcf-init` for the pillars interview, `/gcf-debate` to stress the design, then `/gcf-card <id>` for the first unit
42
42
  9. to change the vision, scope or milestones later, read `gcf/game.md`, ask what changes, write only the blocks that change, and read them back to the human
43
43
  10. a milestone renamed while units cite it fails the design check: change the `milestone:` of each citing unit too, then run `ai-factory gcf design check` and `ai-factory gcf design commit -m "<what changed>"`
44
- 11. a draft of the glossary (the board's Draft with agent): from `gcf/game.md` and the units, write `gcf/glossary.md` in the form of `templates/glossary.md`; do not record it: the human records, edits or discards it
44
+ 11. a draft of the glossary (the board's Draft with agent): from `gcf/game.md` and the units, write `GLOSSARY.md` as `templates/glossary.md`, no `avoid: TBD`; do not record it: the human records, edits or discards it
45
45
  12. a draft of a subsystem's purpose: read its units in `gcf/design/<system>.md` and `gcf/game.md`, write its `purpose:` block, change nothing else, and do not record it
46
46
 
47
47
  invocation:
@@ -11,6 +11,8 @@ gcf_work:
11
11
  - an agent names the category: `ai-factory gcf inbox categories` lists them and who may file each; yours are `request` (what only a person can give: a file, an asset, an access), `bug`, `finding` (a remark about the code or the project: a risk, debt, an analyzer's warning), `idea`, and `playtest` for the human's words in a playtest session; a remark about the code is a `finding`, never a failure, which only a CI job files
12
12
  - a text of several lines (its first line becomes the title) goes through stdin: `ai-factory gcf inbox add --text-file - <<'EOF'`, the lines, then `EOF`
13
13
  - before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
14
+ - an item's plan is in the plan form: blocks `context:`, `decisions:` (records `id`, `pick`, `why`), `tasks:` (`- [ ] t1 <action> (d1)`), `pillar_check:`, `verification:`, one idea a line
15
+ - `ai-factory gcf plan check <id>` lists the plan's form problems as `format:` lines: fix them, they never block
14
16
  - drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext and the agent is Claude Code (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
15
17
  - a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) is answered by `ai-factory gcf-harness metrics`
16
18
  - a question about past runs (an item's results, what it ran on, its cost, the part of its log a run wrote) is answered by `ai-factory gcf-harness runs [--item <id>] --json`; `ai-factory gcf-harness run <ids...> --model <m> --effort <e>` runs items on another model for that run only, the item unchanged
@@ -22,7 +24,8 @@ gcf_work:
22
24
  - work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
23
25
  - in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:` and new inbox entries, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
24
26
  - a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
25
- - 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
27
+ - name each thing by the term `GLOSSARY.md` defines for it; a word added to an `avoid:` there leaves `gcf/design/`, `gcf/systems/`, `gcf/PILLARS.md` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit in design and items as M4, `npx --yes cnlp-kit check` the rest
28
+ - an `avoid:` lists only a word wrong in every document: a word with another use stays out, a phrase ("tile hand") beats a bare word
26
29
  - the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --category playtest "<note>"`, in the human's words
27
30
  - a release item carries `version:` and `channel:` (`item new --title "<title>" --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
28
31
  - `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
@@ -38,7 +41,7 @@ gcf_work:
38
41
  - what happened to an item before (who submitted, blocked, tuned or reranked it, and when) is `ai-factory gcf item history <id>`: its moves from git, an ended item's too
39
42
  - a picture or file the human gives an item goes to `ai-factory gcf item attach <id> --file <path>` (its `gcf/work/<id>/attachments/`, committed); read an item's attachments before you plan it
40
43
  - write what the human reads (a question, an assumption, a block reason, an inbox entry, a lesson, a report, an item's `title:`) in `language.ui` of `.ai-factory/config.yaml`, and the body of an item that is not a design unit in its `language.artifacts`
41
- - write in English whatever lands in a checked document: `gcf/design/`, `gcf/systems/`, `gcf/glossary.md`, `gcf/PILLARS.md`, `gcf/LIVE.md`, the body of a design unit's item but its `tuning:` and `notes:`, an item's `live:` summary; an answer that moves into a unit's slot goes there in English
44
+ - write in English whatever lands in a checked document: `gcf/design/`, `gcf/systems/`, `GLOSSARY.md`, `gcf/PILLARS.md`, `gcf/LIVE.md`, the body of a design unit's item but its `tuning:` and `notes:`, an item's `live:` summary; an answer that moves into a unit's slot goes there in English
42
45
  - never translate keys, statuses, ids, commands, `TBD`, `answer: q-NNN`, `## Handoff`, a `quote:` (it is verbatim from the GDD) or the fixed start of a block reason (`needs permission:`, `plan did not converge:`, `waits for`)
43
46
  - a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
44
47
  - a pillar changes only on the human's word; its short `name:` is what the human knows it by, and its id comes from the name: a new name saved with `design save` renames the id wherever it is cited; `ai-factory gcf pillar retire <id> --reason "<why>"` takes one out
package/templates/game.md CHANGED
@@ -22,3 +22,6 @@ milestones:
22
22
 
23
23
  - name: steam
24
24
  goal: a long campaign once the web version proves the puzzle keeps players
25
+
26
+ units:
27
+ - coins: the soft currency
@@ -1,11 +1,11 @@
1
+ purpose:
2
+ - a short-session puzzle about placing tiles on a small board: the names of its pieces and places
3
+
1
4
  terms:
2
5
  - term: tile tray
3
6
  means: the supply of unplaced tiles the player picks from
4
- not: hand, table
7
+ avoid: tile hand
5
8
 
6
9
  - term: void cell
7
10
  means: a cell a shaped board leaves out
8
- not: blocked cell
9
-
10
- units:
11
- - coins: the soft currency
11
+ avoid: blocked cell