gcf-aif-ext 0.20.1 → 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.
package/lib/edits.js CHANGED
@@ -4,7 +4,7 @@
4
4
  import { readFileSync, existsSync } from 'node:fs';
5
5
  import { spawnSync } from 'node:child_process';
6
6
  import path from 'node:path';
7
- import { dirtyGcf, literal, restoreFromHead } from './git.js';
7
+ import { dirtyGcf, inParts, literal, restoreFromHead } from './git.js';
8
8
  import { locked } from './main-lock.js';
9
9
  import { refusal } from './refusal.js';
10
10
  import { commitMove } from './unit-ops.js';
@@ -56,6 +56,40 @@ function newFileDiff(projectDir, f) {
56
56
  /** Literal pathspecs: a `[` in a name is no glob that takes its siblings along. */
57
57
  const lits = (projectDir, files) => files.map((f) => literal(projectDir, f));
58
58
 
59
+ // The form a board cuts the diff by, whatever the user's git config says (diff.noprefix,
60
+ // diff.mnemonicPrefix, color.ui=always, an external diff): heads `a/<path> b/<path>` from the
61
+ // project, as dirtyGcf names the paths, not from the repository a project may sit in.
62
+ const DIFF_FORM = [
63
+ '--no-color',
64
+ '--no-ext-diff',
65
+ '--no-textconv',
66
+ '--relative',
67
+ '--src-prefix=a/',
68
+ '--dst-prefix=b/',
69
+ ];
70
+
71
+ /**
72
+ * `git diff <opts>` of `files`; it takes no pathspec file: a long list in parts (inParts). A
73
+ * working-tree diff refreshes the index under index.lock even with GIT_OPTIONAL_LOCKS=0 (a
74
+ * file with a new time and the index's content): autoRefreshIndex off, a run's commit beside
75
+ * the open dialog finds no lock.
76
+ */
77
+ const diffOf = (projectDir, opts, files) =>
78
+ inParts(lits(projectDir, files))
79
+ .map((part) =>
80
+ git(
81
+ projectDir,
82
+ '-c',
83
+ 'diff.autoRefreshIndex=false',
84
+ 'diff',
85
+ ...DIFF_FORM,
86
+ ...opts,
87
+ '--',
88
+ ...part,
89
+ ),
90
+ )
91
+ .join('');
92
+
59
93
  const tracked = (projectDir, f) =>
60
94
  spawnSync('git', ['ls-files', '--error-unmatch', '--', literal(projectDir, f)], {
61
95
  cwd: projectDir,
@@ -72,12 +106,11 @@ const tracked = (projectDir, f) =>
72
106
  */
73
107
  export function editsDiff(projectDir, paths) {
74
108
  const files = changed(projectDir, paths, 'diff');
75
- const staged = git(projectDir, 'diff', '--cached', '--', ...lits(projectDir, files));
109
+ const staged = diffOf(projectDir, ['--cached'], files);
76
110
  const known = files.filter((f) => tracked(projectDir, f));
77
111
  const fresh = files.filter((f) => !known.includes(f));
78
112
  const unstaged =
79
- (known.length ? git(projectDir, 'diff', '--', ...lits(projectDir, known)) : '') +
80
- fresh.map((f) => newFileDiff(projectDir, f)).join('');
113
+ diffOf(projectDir, [], known) + fresh.map((f) => newFileDiff(projectDir, f)).join('');
81
114
 
82
115
  return { files, staged, unstaged };
83
116
  }
package/lib/git.js CHANGED
@@ -3,6 +3,34 @@ import { existsSync, rmSync } from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { refusal } from './refusal.js';
5
5
 
6
+ // A read (`git status`, `git diff`) refreshes the index under index.lock when it can: a board's
7
+ // read then failed a run's integrate commit in main ("index.lock: File exists"). Every git of
8
+ // this process reads without that lock; a write takes its own lock as ever.
9
+ process.env.GIT_OPTIONAL_LOCKS ??= '0';
10
+
11
+ // Windows' command line holds 32K characters: a longer list of paths (a refusal's hundreds of
12
+ // hand edits) goes in parts, or to `git commit` from a file.
13
+ const ARGS_MAX = 8000;
14
+
15
+ /** `specs` in parts, each short enough for one command line. */
16
+ export function inParts(specs) {
17
+ const parts = [];
18
+ let part = [];
19
+ let n = 0;
20
+ for (const s of specs) {
21
+ if (part.length && n + s.length + 1 > ARGS_MAX) {
22
+ parts.push(part);
23
+ part = [];
24
+ n = 0;
25
+ }
26
+ part.push(s);
27
+ n += s.length + 1;
28
+ }
29
+ if (part.length) parts.push(part);
30
+
31
+ return parts;
32
+ }
33
+
6
34
  // `git commit --only <paths>` is a partial commit, which git refuses outright while a merge
7
35
  // or a sequencer operation is in progress. Detect it up front so the failure has a reason.
8
36
  const IN_PROGRESS = [
@@ -67,6 +95,9 @@ export function dirtyPaths(projectDir, paths) {
67
95
  */
68
96
  export const GATE_SCOPE = [
69
97
  'gcf',
98
+ // The project's glossary sits beside cnlp.config.json, where cnlp finds it (cnlp-kit 3.10):
99
+ // its avoided words hold over gcf/, so a change to it is checked with gcf/.
100
+ 'GLOSSARY.md',
70
101
  ':(exclude)gcf/.metrics',
71
102
  ':(exclude,glob)gcf/source/*.import.json',
72
103
  ];
@@ -104,7 +135,7 @@ export function dirtyGcf(projectDir, skip = []) {
104
135
  if (!/[RC]/.test(xy)) continue;
105
136
  i++;
106
137
  const old = ours(recs[i] ?? '');
107
- if (xy.includes('R') && old.startsWith('gcf/')) paths.push(old);
138
+ if (xy.includes('R') && (old.startsWith('gcf/') || old === 'GLOSSARY.md')) paths.push(old);
108
139
  }
109
140
 
110
141
  const off = new Set([...skip].map((p) => relOf(projectDir, p)));
@@ -226,10 +257,22 @@ export function commitPaths(projectDir, message, paths, move = {}) {
226
257
  const real = paths.filter((p) => existsSync(p) || inHead(projectDir, p));
227
258
  const msg = ['-m', message, ...moveTrailers(move)];
228
259
  const only = real.map((p) => literal(projectDir, p));
229
- const res = spawnSync('git', ['commit', ...msg, '--only', '--', ...only], {
230
- cwd: projectDir,
231
- encoding: 'utf8',
232
- });
260
+ // A list past one command line goes on stdin (git 2.25+); a move's few paths as arguments.
261
+ const long = inParts(only).length > 1;
262
+ const res = spawnSync(
263
+ 'git',
264
+ [
265
+ 'commit',
266
+ ...msg,
267
+ '--only',
268
+ ...(long ? ['--pathspec-from-file=-', '--pathspec-file-nul'] : ['--', ...only]),
269
+ ],
270
+ {
271
+ cwd: projectDir,
272
+ encoding: 'utf8',
273
+ ...(long && { input: only.map((p) => `${p}\0`).join('') }),
274
+ },
275
+ );
233
276
  const out = res.stderr || res.stdout;
234
277
  // The gate reads the whole gcf/ tree: another file's edit stops the move, in the Operator's
235
278
  // words. Its paths from git: the move's own staged files ride along and stop nothing.
@@ -259,15 +302,23 @@ export function commitPaths(projectDir, message, paths, move = {}) {
259
302
  export function snapshotIndex(cwd, files) {
260
303
  const rels = files.map((f) => path.relative(cwd, f).replaceAll('\\', '/'));
261
304
  // -z: no C-quoting of non-ASCII paths, so the output is the path itself.
262
- const res = spawnSync('git', ['ls-files', '-s', '-z', '--', ...rels], { cwd, encoding: 'utf8' });
263
- if (res.status !== 0) return null;
305
+ // ls-files takes no pathspec file: a long list in parts.
306
+ let stdout = '';
307
+ for (const part of inParts(rels)) {
308
+ const res = spawnSync('git', ['ls-files', '-s', '-z', '--', ...part], {
309
+ cwd,
310
+ encoding: 'utf8',
311
+ });
312
+ if (res.status !== 0) return null;
313
+ stdout += res.stdout;
314
+ }
264
315
  const prefix = spawnSync('git', ['rev-parse', '--show-prefix'], {
265
316
  cwd,
266
317
  encoding: 'utf8',
267
318
  }).stdout.trim();
268
319
  const entries = new Map();
269
320
  const conflicted = new Set();
270
- for (const rec of res.stdout.split('\0').filter(Boolean)) {
321
+ for (const rec of stdout.split('\0').filter(Boolean)) {
271
322
  const m = rec.match(/^(\d+) ([0-9a-f]+) (\d)\t(.+)$/s);
272
323
  if (!m) continue;
273
324
  if (m[3] === '0') entries.set(m[4], { mode: m[1], blob: m[2] });
package/lib/index-gen.js CHANGED
@@ -11,10 +11,11 @@ import { readDesign, slotValues, loadDocProfile, isTbd, UNIT_TYPES } from './des
11
11
  * INDEX.md is a deterministic function of gcf/ contents (GCF-PRD §5.1): generated,
12
12
  * never hand-written. The pre-commit hook regenerates it and stages the result.
13
13
  */
14
+ // Each with its file from the project: the glossary is the project's, beside cnlp.config.json.
14
15
  const SINGLETONS = [
15
- ['pillars', 'PILLARS.md', 'pillars and negative invariants'],
16
- ['game', 'game.md', 'vision, scope and milestones'],
17
- ['glossary', 'glossary.md', 'terms and forbidden synonyms'],
16
+ ['pillars', 'gcf/PILLARS.md', 'pillars and negative invariants'],
17
+ ['game', 'gcf/game.md', 'vision, scope, milestones and units of measure'],
18
+ ['glossary', 'GLOSSARY.md', 'terms and the words they avoid'],
18
19
  ];
19
20
 
20
21
  export async function generate(root) {
@@ -23,7 +24,7 @@ export async function generate(root) {
23
24
  lines.push(`${type} | gcf/${file} | ${status} | ${system} | ${descr}`);
24
25
 
25
26
  for (const [type, file, descr] of SINGLETONS) {
26
- if (existsSync(path.join(root, file))) row([type, file, '-', '-', descr]);
27
+ if (existsSync(path.join(root, '..', file))) lines.push(`${type} | ${file} | - | - | ${descr}`);
27
28
  }
28
29
 
29
30
  const backlog = await readIfExists(root, 'backlog.md');
package/lib/plan-check.js CHANGED
@@ -1,10 +1,15 @@
1
1
  // `gcf plan check <id>` (Methodology §5.2.1): the deterministic check after each improve pass —
2
2
  // the plan exists, it holds task checkboxes, and the item's readset fits the context budget.
3
- // Whether the plan is any good is the improve passes' job; this only says it is usable.
3
+ // Whether the plan is any good is the improve passes' job; this only says it is usable. Its
4
+ // form against the `plan` profile (CNL-P: blocks, one idea a line, no fact twice) is reported
5
+ // as `format` lines, never a problem: a long line must not cost the item its paid passes.
4
6
  import { existsSync, readFileSync } from 'node:fs';
5
7
  import path from 'node:path';
8
+ import { bodyIssues } from 'cnlp-kit';
9
+ import { glossaryAvoids, GLOSSARY_NAME } from 'cnlp-kit/config';
6
10
  import { buildLedger } from './ledger.js';
7
11
  import { buildContext } from './context.js';
12
+ import { loadDocProfile } from './design.js';
8
13
 
9
14
  /**
10
15
  * An item's plan and its task checkboxes: `{plan, tasks, done}`, `tasks` null when there is no
@@ -23,6 +28,47 @@ export function planTicks(projectDir, data) {
23
28
  };
24
29
  }
25
30
 
31
+ /**
32
+ * The plan as the profile reads it, line numbers kept: a `##` section aif-plan or GCF adds
33
+ * (Settings, Original Request, Handoff, Outcome) is blanked to the next block of the profile,
34
+ * and a `### Phase` line is blank (a bullet-list takes only `- ` items; a blank line is fine).
35
+ */
36
+ export function profiledText(text, keys) {
37
+ const block = new RegExp(`^(${keys.join('|')}):`);
38
+ let section = false;
39
+
40
+ return text
41
+ .split(/\r?\n/)
42
+ .map((l) => {
43
+ if (/^## /.test(l)) section = true;
44
+ else if (block.test(l)) section = false;
45
+ if (section || /^### /.test(l)) return '';
46
+
47
+ // A subtask is a task: aif-plan nests them, the form does not refuse them.
48
+ return /^\s+- \[[ xX]\] /.test(l) ? l.trimStart() : l;
49
+ })
50
+ .join('\n');
51
+ }
52
+
53
+ /**
54
+ * The plan's form against the `plan` profile, as `<line>: <message>` lines; the project
55
+ * glossary's avoided words count. None once a task is ticked: work in flight is not asked to
56
+ * change its form. A plan in no block of the profile (aif-plan's own layout) gets one line.
57
+ */
58
+ export async function planFormat(projectDir, text) {
59
+ if (/^\s*- \[[xX]\] /m.test(text)) return [];
60
+ const profile = await loadDocProfile('plan');
61
+ const keys = profile.sections.map((s) => s.key);
62
+ if (!new RegExp(`^(${keys.join('|')}):`, 'm').test(text))
63
+ return [`the plan is not in the plan profile: blocks ${keys.join(', ')}`];
64
+ const glossary = path.join(path.resolve(projectDir), GLOSSARY_NAME);
65
+ const avoid = existsSync(glossary) ? glossaryAvoids(readFileSync(glossary, 'utf8')) : [];
66
+
67
+ return bodyIssues(profiledText(text, keys), profile, { avoid }).map(
68
+ (i) => `${i.line}: ${i.message}`,
69
+ );
70
+ }
71
+
26
72
  export async function planCheck(projectDir, id) {
27
73
  const item = (await buildLedger(projectDir)).item(id);
28
74
  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
@@ -35,6 +81,10 @@ export async function planCheck(projectDir, id) {
35
81
  const ctx = await buildContext(projectDir, id);
36
82
  if (ctx.over_budget)
37
83
  problems.push(`readset ~${ctx.total_tokens_est} tokens is over the budget ${ctx.budget}`);
84
+ const format =
85
+ found === null
86
+ ? []
87
+ : await planFormat(projectDir, readFileSync(path.resolve(projectDir, plan), 'utf8'));
38
88
 
39
- return { id, plan, tasks, done, problems, ok: problems.length === 0 };
89
+ return { id, plan, tasks, done, problems, format, ok: problems.length === 0 };
40
90
  }
@@ -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.1",
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)