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/GLOSSARY.md +26 -0
- package/README.md +13 -0
- package/commands/gcf.js +36 -11
- package/extension.json +6 -1
- package/injections/improve-plan.md +7 -0
- package/injections/plan-context.md +10 -1
- package/lib/bundle.js +4 -5
- package/lib/design-check.js +47 -18
- package/lib/design-parts.js +27 -17
- package/lib/design.js +24 -3
- package/lib/domain.js +12 -4
- package/lib/edits.js +37 -4
- package/lib/git.js +59 -8
- package/lib/index-gen.js +5 -4
- package/lib/plan-check.js +52 -2
- package/node_modules/cnlp-kit/CHANGELOG.md +23 -0
- package/node_modules/cnlp-kit/README.md +27 -1
- package/node_modules/cnlp-kit/bin/cnlp.js +1 -1
- package/node_modules/cnlp-kit/cnlp-format.md +13 -0
- package/node_modules/cnlp-kit/package.json +1 -1
- package/node_modules/cnlp-kit/profiles/glossary.md +38 -0
- package/node_modules/cnlp-kit/skills/cnlp-glossary/SKILL.md +50 -0
- package/node_modules/cnlp-kit/src/cnlp.js +10 -5
- package/node_modules/cnlp-kit/src/config.js +40 -3
- package/package.json +3 -2
- package/profiles/game.md +6 -0
- package/profiles/glossary.md +15 -14
- package/profiles/plan.md +52 -0
- package/skills/gcf-adopt/SKILL.md +1 -1
- package/skills/gcf-ingest/SKILL.md +4 -4
- package/skills/gcf-init/SKILL.md +1 -1
- package/skills/gcf-vision/SKILL.md +1 -1
- package/templates/agents-block.md +5 -2
- package/templates/game.md +3 -0
- package/templates/glossary.md +5 -5
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 =
|
|
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
|
-
(
|
|
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
|
-
|
|
230
|
-
|
|
231
|
-
|
|
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
|
-
|
|
263
|
-
|
|
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
|
|
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
|
|
17
|
-
['glossary', '
|
|
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)))
|
|
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.
|
|
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
|
-
//
|
|
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.
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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)
|