gcf-aif-ext 0.20.2 → 0.22.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 +19 -0
- package/commands/gcf.js +92 -6
- 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/changes.js +643 -0
- package/lib/config-set.js +19 -1
- package/lib/design-check.js +47 -18
- package/lib/design-parts.js +27 -17
- package/lib/design.js +24 -3
- package/lib/domain.js +4 -2
- package/lib/edits.js +2 -13
- package/lib/gate.js +13 -1
- package/lib/gcf-paths.js +10 -0
- package/lib/git.js +22 -2
- package/lib/index-gen.js +5 -4
- package/lib/linter.js +5 -3
- package/lib/plan-check.js +52 -2
- package/lib/tree-file.js +107 -0
- 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 +7 -2
- package/templates/config.yml +4 -0
- package/templates/game.md +3 -0
- package/templates/glossary.md +5 -5
package/lib/tree-file.js
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
// Reading a file of a checkout for a view (`gcf edits diff`, `gcf changes`): only a regular file
|
|
2
|
+
// that lies inside the tree. A link named `x.png` would read a file outside the project.
|
|
3
|
+
import {
|
|
4
|
+
closeSync,
|
|
5
|
+
constants,
|
|
6
|
+
existsSync,
|
|
7
|
+
fstatSync,
|
|
8
|
+
lstatSync,
|
|
9
|
+
openSync,
|
|
10
|
+
readSync,
|
|
11
|
+
realpathSync,
|
|
12
|
+
} from 'node:fs';
|
|
13
|
+
import path from 'node:path';
|
|
14
|
+
|
|
15
|
+
const listed = (why) => ({ kind: 'listed', why });
|
|
16
|
+
|
|
17
|
+
/** Whether `file` really lies under `root`: git walks through a Windows junction as a folder. */
|
|
18
|
+
function inside(root, file) {
|
|
19
|
+
try {
|
|
20
|
+
const rel = path.relative(realpathSync.native(root), realpathSync.native(file));
|
|
21
|
+
|
|
22
|
+
return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
|
|
23
|
+
} catch {
|
|
24
|
+
return false;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* What `rel` (from `root`, `/` allowed at its end: git names an untracked nested repository so)
|
|
30
|
+
* is on disk, with no byte read: `{kind: 'file', size}`, `{kind: 'gone'}`, or `{kind: 'listed',
|
|
31
|
+
* why}` for what is never opened.
|
|
32
|
+
* @param {string} root
|
|
33
|
+
* @param {string} rel
|
|
34
|
+
*/
|
|
35
|
+
export function fileState(root, rel) {
|
|
36
|
+
const file = path.join(root, rel.replace(/\/$/, ''));
|
|
37
|
+
let st;
|
|
38
|
+
try {
|
|
39
|
+
st = lstatSync(file);
|
|
40
|
+
} catch {
|
|
41
|
+
return { kind: 'gone' };
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
if (st.isSymbolicLink()) return listed('link');
|
|
45
|
+
if (st.isDirectory())
|
|
46
|
+
return listed(existsSync(path.join(file, '.git')) ? 'nested repository' : 'not a regular file');
|
|
47
|
+
if (!st.isFile()) return listed('not a regular file');
|
|
48
|
+
// The file itself is regular, a folder on its way may be a link.
|
|
49
|
+
if (!inside(root, file)) return listed('link');
|
|
50
|
+
|
|
51
|
+
return { kind: 'file', size: st.size };
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* The first `max` bytes of `rel` when it is a regular file inside `root`: `{kind: 'file', size,
|
|
56
|
+
* bytes}`, or what fileState says. Windows has no O_NOFOLLOW: there a file swapped for a link
|
|
57
|
+
* between the check and the open is read; this reads the operator's own disk for the operator.
|
|
58
|
+
* @param {string} root
|
|
59
|
+
* @param {string} rel
|
|
60
|
+
* @param {number} max
|
|
61
|
+
*/
|
|
62
|
+
export function readHead(root, rel, max) {
|
|
63
|
+
const state = fileState(root, rel);
|
|
64
|
+
if (state.kind !== 'file') return state;
|
|
65
|
+
try {
|
|
66
|
+
const fd = openSync(path.join(root, rel), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
|
|
67
|
+
try {
|
|
68
|
+
const st = fstatSync(fd);
|
|
69
|
+
if (!st.isFile()) return listed('not a regular file');
|
|
70
|
+
const bytes = Buffer.alloc(Math.min(st.size, max));
|
|
71
|
+
const n = readSync(fd, bytes, 0, bytes.length, 0);
|
|
72
|
+
|
|
73
|
+
return { kind: 'file', size: st.size, bytes: bytes.subarray(0, n) };
|
|
74
|
+
} finally {
|
|
75
|
+
closeSync(fd);
|
|
76
|
+
}
|
|
77
|
+
} catch (e) {
|
|
78
|
+
// ELOOP: it became a link just now. Else the editor holds it, or the rights say no.
|
|
79
|
+
return listed(e.code === 'ELOOP' ? 'link' : 'not readable');
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// A new file the edits dialog shows whole: past this it is cut, never read into memory.
|
|
84
|
+
const NEW_FILE_MAX = 16 * 1024 * 1024;
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* A file git does not know yet as a diff of its own: each line added.
|
|
88
|
+
* @param {string} root
|
|
89
|
+
* @param {string} rel
|
|
90
|
+
* @param {number} [max]
|
|
91
|
+
*/
|
|
92
|
+
export function newFileDiff(root, rel, max = NEW_FILE_MAX) {
|
|
93
|
+
const head = readHead(root, rel, max);
|
|
94
|
+
if (head.kind === 'gone') return '';
|
|
95
|
+
if (head.kind === 'listed') return `new file ${rel}: ${head.why}\n`;
|
|
96
|
+
if (head.bytes.includes(0)) return `new file ${rel}: binary\n`;
|
|
97
|
+
const whole = head.size <= head.bytes.length;
|
|
98
|
+
const text = head.bytes.toString('utf8');
|
|
99
|
+
// Cut: the last line may have lost its end, a letter's bytes too.
|
|
100
|
+
const kept = whole ? text : text.slice(0, Math.max(0, text.lastIndexOf('\n')));
|
|
101
|
+
// An empty file has no line to add.
|
|
102
|
+
const lines = kept ? kept.replace(/\n$/, '').split('\n') : [];
|
|
103
|
+
const end = whole ? '' : `… first ${head.bytes.length} of ${head.size} bytes\n`;
|
|
104
|
+
const added = lines.map((l) => `+${l}\n`).join('');
|
|
105
|
+
|
|
106
|
+
return `new file ${rel}\n--- /dev/null\n+++ b/${rel}\n${added}${end}`;
|
|
107
|
+
}
|
|
@@ -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.22.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)
|
package/profiles/glossary.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: glossary
|
|
3
|
-
description: The CNL-P profile of
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
25
|
-
note:
|
|
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
|
|
33
|
+
- none: a project fills this from the vocabulary its own glossary already uses
|
|
34
34
|
|
|
35
35
|
enforcement:
|
|
36
|
-
- `
|
|
37
|
-
-
|
|
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
|
package/profiles/plan.md
ADDED
|
@@ -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 `
|
|
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
|
|
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
|
|
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 `
|
|
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:
|
package/skills/gcf-init/SKILL.md
CHANGED
|
@@ -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
|
|
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
|