gcf-aif-ext 0.20.2 → 0.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/GLOSSARY.md +26 -0
- package/README.md +9 -0
- package/commands/gcf.js +18 -5
- 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 +2 -2
- package/lib/git.js +4 -1
- 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/GLOSSARY.md
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
purpose:
|
|
2
|
+
- GCF's method: the words its skills, templates and agent block use for a game's design and its work
|
|
3
|
+
|
|
4
|
+
terms:
|
|
5
|
+
- term: work item
|
|
6
|
+
means: one piece of work in `gcf/work/<id>.md`: a feature, a bug, a tech task, a spike or a release
|
|
7
|
+
avoid: ticket, user story, epic
|
|
8
|
+
|
|
9
|
+
- term: design unit
|
|
10
|
+
means: one designed thing (a mechanic, rule, entity, resource or constraint) in `gcf/design/` until it goes into work
|
|
11
|
+
avoid: feature spec
|
|
12
|
+
|
|
13
|
+
- term: verdict
|
|
14
|
+
means: the human's keep, tune or kill of an item they played
|
|
15
|
+
avoid: rating, grade
|
|
16
|
+
|
|
17
|
+
- term: playtest
|
|
18
|
+
means: the human playing a built milestone or item and saying how it felt
|
|
19
|
+
avoid: test session
|
|
20
|
+
|
|
21
|
+
- term: milestone
|
|
22
|
+
means: a slice of the game the human plays as one, in the order `gcf/game.md` gives
|
|
23
|
+
avoid: sprint
|
|
24
|
+
|
|
25
|
+
- term: pillar
|
|
26
|
+
means: a quality the game must keep, in `gcf/PILLARS.md`, changed only on the human's word
|
package/README.md
CHANGED
|
@@ -50,6 +50,15 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
|
|
|
50
50
|
|
|
51
51
|
On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
|
|
52
52
|
|
|
53
|
+
### 0.21.0
|
|
54
|
+
|
|
55
|
+
- Bundles `cnlp-kit` 3.10. Its project glossary is GCF's glossary now: **`GLOSSARY.md` at the project root**, beside `cnlp.config.json`, in cnlp's own shape — a `purpose:` block and `terms:` records of `term`, `means` and an optional `avoid` (a comma list). `npx --yes cnlp-kit check` finds it by name and rejects every word it avoids in the systems docs and `PILLARS.md`; `ai-factory gcf design check` (the commit gate) rejects them in design units and work items (M4). An `avoid:` is the project's deny list everywhere: list only a word wrong in every document, and prefer a phrase ("tile hand") to a bare word with other uses.
|
|
56
|
+
- GCF ships no `glossary` profile of its own any more: one by that name took cnlp's place, and a `GLOSSARY.md` the `cnlp-glossary` skill writes failed the check. The units of measure a project adds move to an optional `units:` block of `gcf/game.md`.
|
|
57
|
+
- The commit gate and the `dirty` refusal of a move cover `GLOSSARY.md` as they cover `gcf/`: a commit of the glossary alone runs the design check.
|
|
58
|
+
- `GLOSSARY.md` in this package lists GCF's own words (work item, design unit, verdict, playtest, milestone, pillar) and what each replaces; the tests hold GCF's skills to it. It is not copied into a project.
|
|
59
|
+
- **The plan form** (CNL-P profile `plan`): a work item's plan is written in blocks, one idea a line — `context:` (facts found in the code), `decisions:` (records `id`, `pick`, `why`, optional `rejects` and `cost`), `tasks:` (`- [ ] t1 <action> (d1)` under `### Phase N:` lines, as aif-implement ticks them), `pillar_check:`, `verification:`. aif-plan learns it from the injection, aif-improve keeps it from a new injection. `gcf plan check` lists the plan's form problems (a line over 250 characters, an unquantified comparative, a word the glossary avoids) as `format:` lines that never fail it, and `plan-log.csv` counts them in a 4th column. A plan already in work (a ticked task) is not asked to change its form; `## Settings`, `## Handoff` and `## Outcome` stay sections.
|
|
60
|
+
- **Upgrading a project that has `gcf/glossary.md`**: `design check` reports it (not a block) until it moves, and until then its words hold nowhere. Move it by hand: `git mv gcf/glossary.md GLOSSARY.md`; add a `purpose:` block (what the game is, in 1 line); turn each `not:` into `avoid:`, keeping only words wrong in every document (run `npx --yes cnlp-kit check` and `ai-factory gcf design check` to see where a word is used); move a `units:` block into `gcf/game.md`; commit.
|
|
61
|
+
|
|
53
62
|
### 0.20.2
|
|
54
63
|
|
|
55
64
|
- `edits diff|commit|discard` also take the paths from `--path-file <file|->`, one a line: a board sends a refusal's paths on stdin. Hundreds of them no longer run past Windows' 32K command line, neither in the command nor in the git calls of a move's commit: `git diff` and `git ls-files` go in parts, `git commit` takes a long list from `--pathspec-from-file` (git 2.25+; a move's few paths stay arguments).
|
package/commands/gcf.js
CHANGED
|
@@ -620,7 +620,9 @@ function registerDesign(gcf) {
|
|
|
620
620
|
});
|
|
621
621
|
design
|
|
622
622
|
.command('export')
|
|
623
|
-
.description(
|
|
623
|
+
.description(
|
|
624
|
+
'Glue game.md, GLOSSARY.md, PILLARS.md and the units into one bundle a designer edits',
|
|
625
|
+
)
|
|
624
626
|
.option('--system <name>', 'only this subsystem')
|
|
625
627
|
.option('--milestone <name>', 'only the units of this milestone')
|
|
626
628
|
.option('--out <file>', 'write the bundle here instead of stdout')
|
|
@@ -1541,17 +1543,28 @@ function registerPlan(gcf) {
|
|
|
1541
1543
|
.command('plan')
|
|
1542
1544
|
.description('The plan of a work item')
|
|
1543
1545
|
.command('check <id>')
|
|
1544
|
-
.description(
|
|
1546
|
+
.description(
|
|
1547
|
+
'Deterministic plan check: it exists, has task checkboxes, readset in budget; ' +
|
|
1548
|
+
'its form against the plan profile as format lines, which never fail it',
|
|
1549
|
+
)
|
|
1545
1550
|
.option('--json', 'machine output')
|
|
1546
1551
|
.action(async (id, o) => {
|
|
1547
1552
|
await touchSession(id);
|
|
1548
1553
|
const r = await (await lib('plan-check')).planCheck(process.cwd(), id);
|
|
1549
|
-
// Harness-PRD §11: the checks a plan took to converge.
|
|
1554
|
+
// Harness-PRD §11: the checks a plan took to converge; the last column, its format lines.
|
|
1550
1555
|
await (
|
|
1551
1556
|
await lib('metrics')
|
|
1552
|
-
).logMetric(process.cwd(), 'plan-log.csv', [
|
|
1557
|
+
).logMetric(process.cwd(), 'plan-log.csv', [
|
|
1558
|
+
id,
|
|
1559
|
+
r.ok ? 1 : 0,
|
|
1560
|
+
r.problems?.length ?? 0,
|
|
1561
|
+
r.format.length,
|
|
1562
|
+
]);
|
|
1553
1563
|
out(o.json, r, (x) =>
|
|
1554
|
-
|
|
1564
|
+
[
|
|
1565
|
+
...(x.ok ? [`${x.plan}: ${x.done}/${x.tasks} tasks done`] : x.problems),
|
|
1566
|
+
...x.format.map((f) => `format: ${f}`),
|
|
1567
|
+
].join('\n'),
|
|
1555
1568
|
);
|
|
1556
1569
|
if (!r.ok) process.exitCode = 1;
|
|
1557
1570
|
});
|
package/extension.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
|
|
3
3
|
"name": "gcf-aif-ext",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.21.0",
|
|
5
5
|
"description": "Game Context Framework for AI Factory",
|
|
6
6
|
"skills": [
|
|
7
7
|
"skills/gcf-init",
|
|
@@ -28,6 +28,11 @@
|
|
|
28
28
|
"position": "append",
|
|
29
29
|
"file": "./injections/plan-context.md"
|
|
30
30
|
},
|
|
31
|
+
{
|
|
32
|
+
"target": "aif-improve",
|
|
33
|
+
"position": "append",
|
|
34
|
+
"file": "./injections/improve-plan.md"
|
|
35
|
+
},
|
|
31
36
|
{
|
|
32
37
|
"target": "aif-review",
|
|
33
38
|
"position": "append",
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
## GCF: keep the plan's form (from gcf-aif-ext)
|
|
2
|
+
|
|
3
|
+
gcf_improve:
|
|
4
|
+
- when `gcf/` exists and the plan belongs to a work item, keep it in the plan form: blocks `context:`, `decisions:`, `tasks:`, `pillar_check:`, `verification:`, one idea a line
|
|
5
|
+
- move detail out of a task into the decision it cites, and do not say a fact twice
|
|
6
|
+
- keep every tick and every `### Phase` line: a ticked task is done work
|
|
7
|
+
- after the pass, run `ai-factory gcf plan check <item-id>` and fix each `format:` line; a format line is polish and never blocks
|
|
@@ -8,6 +8,15 @@ gcf_gate:
|
|
|
8
8
|
- an id in `depends:` that lives in `gcf/design/`, or as an item in any status but unplayed, parked or awaiting-verdict, is not played: do not plan on top of it, stop
|
|
9
9
|
- a dependency awaiting its verdict is planned on: the close of this item then waits for that verdict (`ai-factory gcf block <id> --reason "waits for <dep>"`)
|
|
10
10
|
- write the plan to the item's `plan:` path, by default `.ai-factory/plans/<item-id>.md`, with task checkboxes
|
|
11
|
+
- write it in the plan form below, not in TASK-FORMAT.md's Context, Decisions and Tasks: keep `## Settings`, leave out Commit Plan and Roadmap Linkage
|
|
11
12
|
- a design-unit item: shape the plan by its slots — intent, behavior, refusal, boundaries, persistence, feel envelopes, contract, interactions, constraints, miss criterion; a hard unit plans its tests from `statement`, `threshold` or `fields`
|
|
12
13
|
- a bug item: the first task writes the test that reproduces `repro:`, the fix comes after it
|
|
13
|
-
- after the plan, run `ai-factory gcf plan check <item-id>`: a failure is fixed in the plan before implementation
|
|
14
|
+
- after the plan, run `ai-factory gcf plan check <item-id>`: a failure is fixed in the plan before implementation; fix each `format:` line too, which never blocks
|
|
15
|
+
|
|
16
|
+
gcf_plan_form:
|
|
17
|
+
- one idea a line, 150 characters as the target and 250 the limit; a fact is said once, and a task cites the decision it follows
|
|
18
|
+
- `context:` bullets of facts found in the code and the readset; the item's own text is not restated
|
|
19
|
+
- `decisions:` records `- id: d1` with `pick:` and `why:`, and `rejects:` or `cost:` when there is one
|
|
20
|
+
- `tasks:` lines `- [ ] t1 <action> (d1, d2)`, grouped under `### Phase N: <name>` lines
|
|
21
|
+
- `pillar_check:` one `<pillar>: <effect>` line per pillar the work touches, and at most one `untouched: <pillars>` line
|
|
22
|
+
- `verification:` the commands that prove it, then what the human checks by hand
|
package/lib/bundle.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// The structured entry (GCF-PRD §11.10): `design export` glues game.md,
|
|
1
|
+
// The structured entry (GCF-PRD §11.10): `design export` glues game.md, GLOSSARY.md, PILLARS.md
|
|
2
2
|
// and the units into one bundle a designer edits; `design import` brings it back without a
|
|
3
3
|
// model. A board's form saves one part the same way (`design save`, lib/design-parts.js).
|
|
4
4
|
// Each part carries the hash it was exported with, so an import tells a designer's edit from
|
|
@@ -8,14 +8,13 @@ import { existsSync } from 'node:fs';
|
|
|
8
8
|
import { createHash } from 'node:crypto';
|
|
9
9
|
import path from 'node:path';
|
|
10
10
|
import { bodyIssues } from 'cnlp-kit';
|
|
11
|
-
import { readDesign, loadDocProfile, PILLARS_MAX, SLUG_RE } from './design.js';
|
|
11
|
+
import { readDesign, loadDocProfile, PILLARS_MAX, SLUG_RE, DOC_FILES, docPath } from './design.js';
|
|
12
12
|
import { buildLedger } from './ledger.js';
|
|
13
13
|
import { designCheck, recordsIn } from './design-check.js';
|
|
14
14
|
import { atomicWrite, withFileRollback, resolveInside } from './safe-path.js';
|
|
15
15
|
import { writeIndex } from './index-gen.js';
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
export const DOC_FILES = { game: 'game.md', glossary: 'glossary.md', pillars: 'PILLARS.md' };
|
|
17
|
+
export { DOC_FILES, docPath };
|
|
19
18
|
const DOCS = Object.keys(DOC_FILES);
|
|
20
19
|
// A part opens with a marker comment, not with a heading: a `# notes` line inside game.md or a
|
|
21
20
|
// purpose is content, and a heading boundary would cut the document there.
|
|
@@ -227,7 +226,7 @@ const NOTES = {
|
|
|
227
226
|
/** The file each write touches. */
|
|
228
227
|
function fileOf(root, w) {
|
|
229
228
|
// validName already holds a doc to DOCS; resolveInside is the second lock on the path.
|
|
230
|
-
if (w.kind === 'doc') return resolveInside(root,
|
|
229
|
+
if (w.kind === 'doc') return resolveInside(path.dirname(root), docPath(w.name));
|
|
231
230
|
|
|
232
231
|
return resolveInside(path.join(root, 'design'), `${w.kind === 'system' ? w.name : w.system}.md`);
|
|
233
232
|
}
|
package/lib/design-check.js
CHANGED
|
@@ -5,6 +5,7 @@ import { readFile } from 'node:fs/promises';
|
|
|
5
5
|
import { existsSync } from 'node:fs';
|
|
6
6
|
import path from 'node:path';
|
|
7
7
|
import { bodyIssues, lexiconIssues, parseBlocks, itemsOf, readRecords } from 'cnlp-kit';
|
|
8
|
+
import { glossaryAvoids } from 'cnlp-kit/config';
|
|
8
9
|
import {
|
|
9
10
|
SLUG_RE,
|
|
10
11
|
UNIT_TYPES,
|
|
@@ -12,6 +13,8 @@ import {
|
|
|
12
13
|
AGENT_SLOTS,
|
|
13
14
|
listOf,
|
|
14
15
|
loadDocProfile,
|
|
16
|
+
DOC_FILES,
|
|
17
|
+
docPath,
|
|
15
18
|
slotValues,
|
|
16
19
|
provenanceOf,
|
|
17
20
|
isTbd,
|
|
@@ -22,7 +25,7 @@ import { collapseLines } from './verdict-fs.js';
|
|
|
22
25
|
import { fieldOf } from './question-fields.js';
|
|
23
26
|
import { blocksOf } from './systems-doc.js';
|
|
24
27
|
|
|
25
|
-
// Units a number may carry. A project adds its own in the `units:` block of
|
|
28
|
+
// Units a number may carry. A project adds its own in the `units:` block of game.md.
|
|
26
29
|
// Bare `px` is absent on purpose: its size depends on the screen density.
|
|
27
30
|
export const UNITS = [
|
|
28
31
|
...['s', 'ms', 'min', 'h', '%', 'fps', 'KB', 'MB', 'GB', 'deg', 'm'],
|
|
@@ -49,7 +52,6 @@ export const REQUIRED_HEADER = [
|
|
|
49
52
|
'source',
|
|
50
53
|
];
|
|
51
54
|
const ws = (t) => String(t).replace(/\s+/g, ' ').trim();
|
|
52
|
-
const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
53
55
|
|
|
54
56
|
/**
|
|
55
57
|
* @typedef {object} Issue
|
|
@@ -112,9 +114,6 @@ export const closingComparison = (line) => {
|
|
|
112
114
|
return Boolean(cmp) && !/\d/.test(namesOut(v.slice(0, cmp?.index ?? 0)));
|
|
113
115
|
};
|
|
114
116
|
|
|
115
|
-
/** A whole-word, case-insensitive match that also works for Cyrillic (`\b` is ASCII-only). */
|
|
116
|
-
const wordRe = (w) => new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRe(w)}(?![\\p{L}\\p{N}_])`, 'iu');
|
|
117
|
-
|
|
118
117
|
async function readIf(file) {
|
|
119
118
|
return existsSync(file) ? readFile(file, 'utf8') : null;
|
|
120
119
|
}
|
|
@@ -173,24 +172,26 @@ export function questionBlocks(text) {
|
|
|
173
172
|
|
|
174
173
|
/** Everything outside a unit that its references resolve against. */
|
|
175
174
|
async function loadContext(root) {
|
|
176
|
-
const glossary = await readIf(path.join(root,
|
|
175
|
+
const glossary = await readIf(path.join(root, DOC_FILES.glossary));
|
|
176
|
+
const game = await readIf(path.join(root, 'game.md'));
|
|
177
|
+
// A glossary not moved yet (before core 0.21) still lends its units: M5 does not block a
|
|
178
|
+
// number its project counted in them while the move waits (the review).
|
|
179
|
+
const old = await readIf(path.join(root, 'glossary.md'));
|
|
177
180
|
const milestones = await gameMilestones(root);
|
|
178
181
|
const pillars = await readIf(path.join(root, 'PILLARS.md'));
|
|
179
|
-
const forbidden = recordsIn(glossary, 'terms').flatMap((t) => {
|
|
180
|
-
const not = listOf(t.not ?? '');
|
|
181
|
-
|
|
182
|
-
return not === 'TBD' ? [] : not;
|
|
183
|
-
});
|
|
184
182
|
|
|
185
183
|
return {
|
|
186
184
|
milestones: milestones?.map((m) => m.name) ?? null,
|
|
187
185
|
pillarIds: recordsIn(pillars, 'pillars')
|
|
188
186
|
.map((p) => p.id)
|
|
189
187
|
.filter(Boolean),
|
|
190
|
-
|
|
188
|
+
// The words GLOSSARY.md avoids (cnlp's own reading); a draft's `avoid: TBD` bans no word.
|
|
189
|
+
forbidden: glossary === null ? [] : glossaryAvoids(glossary).filter((f) => f.word !== 'TBD'),
|
|
191
190
|
units: [
|
|
192
191
|
...UNITS,
|
|
193
|
-
...itemsIn(
|
|
192
|
+
...[...itemsIn(game, 'units'), ...itemsIn(old, 'units')].map((i) =>
|
|
193
|
+
i.text.replace(/^- /, '').split(':')[0].trim(),
|
|
194
|
+
),
|
|
194
195
|
],
|
|
195
196
|
questions: questionBlocks(await readIf(path.join(root, 'open-questions.md'))),
|
|
196
197
|
sources: await sourceBodies(path.join(root, 'source')),
|
|
@@ -333,7 +334,8 @@ function valueIssues(values, ctx) {
|
|
|
333
334
|
for (const v of values) {
|
|
334
335
|
const text = judged(v.value, true);
|
|
335
336
|
const hit = ctx.forbidden.find((f) => f.re.test(text));
|
|
336
|
-
if (hit)
|
|
337
|
+
if (hit)
|
|
338
|
+
out.push(['M4', v.line, `"${hit.word}" is a word GLOSSARY.md avoids — write "${hit.term}"`]);
|
|
337
339
|
// `contract` names code — paths and types like Rigidbody2D — not quantities.
|
|
338
340
|
const num = v.block === 'contract' ? null : numberProblem(v.block, v.value, ctx.units);
|
|
339
341
|
if (num) out.push(['M5', v.line, `${num}: ${v.value}`]);
|
|
@@ -446,9 +448,9 @@ async function checkUnit(u, ctx, ledger) {
|
|
|
446
448
|
return { issues, values };
|
|
447
449
|
}
|
|
448
450
|
|
|
449
|
-
/** M1 and M5 over a singleton document (game.md,
|
|
451
|
+
/** M1 and M5 over a singleton document (game.md, GLOSSARY.md), `key: TBD` accepted. */
|
|
450
452
|
async function checkDoc(root, name, ctx) {
|
|
451
|
-
const text = await readIf(path.join(root,
|
|
453
|
+
const text = await readIf(path.join(root, DOC_FILES[name]));
|
|
452
454
|
if (text === null) return [];
|
|
453
455
|
const profile = await loadDocProfile(name);
|
|
454
456
|
const tbdLines = new Set(
|
|
@@ -459,7 +461,10 @@ async function checkDoc(root, name, ctx) {
|
|
|
459
461
|
const shape = bodyIssues(text, profile).filter(
|
|
460
462
|
(i) => !(tbdLines.has(i.line) && i.message.includes('carries a value on the key line')),
|
|
461
463
|
);
|
|
462
|
-
|
|
464
|
+
// The glossary is cnlp's document: a number in a term's meaning ("one of the 3 rows") is no
|
|
465
|
+
// quantity a design slot holds, and cnlp's own check passes it (the review).
|
|
466
|
+
const values = name === 'glossary' ? [] : slotValues(text, profile);
|
|
467
|
+
const nums = values.flatMap((v) => {
|
|
463
468
|
const p = numberProblem(v.block, v.value, ctx.units);
|
|
464
469
|
|
|
465
470
|
return p ? [{ line: v.line, message: `${p}: ${v.value}`, check: 'M5' }] : [];
|
|
@@ -468,13 +473,36 @@ async function checkDoc(root, name, ctx) {
|
|
|
468
473
|
return [...shape.map((i) => ({ ...i, check: 'M1' })), ...nums].map((i) => ({
|
|
469
474
|
check: i.check,
|
|
470
475
|
severity: 'block',
|
|
471
|
-
|
|
476
|
+
// From gcf/, as the other findings are; the glossary by its own name, at the root.
|
|
477
|
+
file: DOC_FILES[name].replace(/^\.\.\//, ''),
|
|
472
478
|
line: i.line,
|
|
473
479
|
id: null,
|
|
474
480
|
message: i.message,
|
|
475
481
|
}));
|
|
476
482
|
}
|
|
477
483
|
|
|
484
|
+
/**
|
|
485
|
+
* A glossary left at gcf/glossary.md, where GCF kept it before core 0.21: nothing reads it any
|
|
486
|
+
* more, so its avoided words hold nowhere until it moves (a report, not a block).
|
|
487
|
+
*/
|
|
488
|
+
async function oldGlossary(root) {
|
|
489
|
+
if (!existsSync(path.join(root, 'glossary.md'))) return [];
|
|
490
|
+
|
|
491
|
+
return [
|
|
492
|
+
{
|
|
493
|
+
check: 'M1',
|
|
494
|
+
severity: 'report',
|
|
495
|
+
file: 'glossary.md',
|
|
496
|
+
line: 1,
|
|
497
|
+
id: null,
|
|
498
|
+
message:
|
|
499
|
+
`gcf/glossary.md is read no more: move it to ${docPath('glossary')} (git mv), give it a ` +
|
|
500
|
+
'`purpose:` block, turn each `not:` into `avoid:` (a word wrong in every document), and ' +
|
|
501
|
+
'move `units:` into gcf/game.md',
|
|
502
|
+
},
|
|
503
|
+
];
|
|
504
|
+
}
|
|
505
|
+
|
|
478
506
|
/** Each design file opens with the subsystem's `purpose:` (`TBD` until someone writes it). */
|
|
479
507
|
function preambleIssues(design) {
|
|
480
508
|
return design
|
|
@@ -822,6 +850,7 @@ export async function designCheck(projectDir, { ledger: built = null } = {}) {
|
|
|
822
850
|
for (const c of ledger.items) issues.push(...(await checkItem(c, ctx, ledger)));
|
|
823
851
|
issues.push(...(await unplayedIssues(root, ledger)));
|
|
824
852
|
for (const doc of ['game', 'glossary']) issues.push(...(await checkDoc(root, doc, ctx)));
|
|
853
|
+
issues.push(...(await oldGlossary(root)));
|
|
825
854
|
issues.push(...preambleIssues(ledger.design));
|
|
826
855
|
issues.push(...ledgerIssues(ledger), ...dependsCycles(ledger), ...questionIssues(ctx, ledger));
|
|
827
856
|
if (ledger.design.length) {
|
package/lib/design-parts.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// The design as parts a board edits field by field (Board-PRD §5.24): PILLARS.md, game.md,
|
|
2
|
-
//
|
|
2
|
+
// the project's GLOSSARY.md, a subsystem's purpose, a unit. A part reads as the fields its CNL-P profile
|
|
3
3
|
// declares; a save writes the edited fields back into the part's text and brings it in as a
|
|
4
4
|
// one-part bundle (lib/bundle.js), so a form edit passes the same three-way check and the same
|
|
5
5
|
// design check a designer's import does. The board writes no file of gcf/ itself.
|
|
@@ -7,7 +7,6 @@ import { readFile, readdir } from 'node:fs/promises';
|
|
|
7
7
|
import { existsSync } from 'node:fs';
|
|
8
8
|
import { spawnSync } from 'node:child_process';
|
|
9
9
|
import path from 'node:path';
|
|
10
|
-
import { fileURLToPath } from 'node:url';
|
|
11
10
|
import { parseBlocks, itemsOf, readRecords } from 'cnlp-kit';
|
|
12
11
|
import {
|
|
13
12
|
HEADER_KEYS,
|
|
@@ -15,13 +14,22 @@ import {
|
|
|
15
14
|
UNIT_TYPES,
|
|
16
15
|
CARD_TYPES,
|
|
17
16
|
loadDocProfile,
|
|
17
|
+
profileFile,
|
|
18
18
|
parseDesign,
|
|
19
19
|
provenanceOf,
|
|
20
20
|
readDesign,
|
|
21
21
|
slotValues,
|
|
22
22
|
listOf,
|
|
23
23
|
} from './design.js';
|
|
24
|
-
import {
|
|
24
|
+
import {
|
|
25
|
+
DOC_FILES,
|
|
26
|
+
docPath,
|
|
27
|
+
hashOf,
|
|
28
|
+
importBundle,
|
|
29
|
+
parseBundle,
|
|
30
|
+
purposeOf,
|
|
31
|
+
unitText,
|
|
32
|
+
} from './bundle.js';
|
|
25
33
|
import {
|
|
26
34
|
REQUIRED_HEADER,
|
|
27
35
|
designCheck,
|
|
@@ -37,7 +45,6 @@ import { renamePillar } from './pillars.js';
|
|
|
37
45
|
import { dirtyPaths, restoreFromHead } from './git.js';
|
|
38
46
|
import { blocksOf, putBlock } from './systems-doc.js';
|
|
39
47
|
|
|
40
|
-
const PROFILES_DIR = fileURLToPath(new URL('../profiles/', import.meta.url));
|
|
41
48
|
// The work stage writes these blocks: a unit in design/ has not reached them.
|
|
42
49
|
const WORK_ONLY = ['contract', 'interactions', 'tuning', 'notes'];
|
|
43
50
|
// What a unit's header field takes, for the form's help.
|
|
@@ -67,7 +74,7 @@ const lf = (t) => String(t ?? '').replace(/\r\n/g, '\n');
|
|
|
67
74
|
|
|
68
75
|
/** The `note:` of each section a profile declares: the help a form shows beside its field. */
|
|
69
76
|
async function notesOf(name) {
|
|
70
|
-
const raw = await readFile(
|
|
77
|
+
const raw = await readFile(profileFile(name), 'utf8');
|
|
71
78
|
|
|
72
79
|
return new Map(recordsIn(raw, 'sections').map((r) => [r.key, r.note ?? null]));
|
|
73
80
|
}
|
|
@@ -187,7 +194,7 @@ async function locate(root, kind, name, type) {
|
|
|
187
194
|
throw new Error(`${name} is not a design doc: ${Object.keys(DOC_FILES).join(', ')}`);
|
|
188
195
|
const text = await readIf(path.join(root, DOC_FILES[name]));
|
|
189
196
|
|
|
190
|
-
return { file:
|
|
197
|
+
return { file: docPath(name), text: text === null ? null : text.trim() };
|
|
191
198
|
}
|
|
192
199
|
|
|
193
200
|
const design = await readDesign(root);
|
|
@@ -561,14 +568,13 @@ async function bundleMove(
|
|
|
561
568
|
|
|
562
569
|
// What the design is made of: what `design commit` records and the board counts as unrecorded.
|
|
563
570
|
const DESIGN_PATHS = [
|
|
564
|
-
'PILLARS.md',
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
'
|
|
568
|
-
|
|
569
|
-
'
|
|
570
|
-
|
|
571
|
-
].map((p) => `gcf/${p}`);
|
|
571
|
+
...['PILLARS.md', 'game.md', 'backlog.md', 'open-questions.md', 'design', 'source'].map(
|
|
572
|
+
(p) => `gcf/${p}`,
|
|
573
|
+
),
|
|
574
|
+
docPath('glossary'),
|
|
575
|
+
// Where the glossary lived before core 0.21: its move to the root is design too (the review).
|
|
576
|
+
'gcf/glossary.md',
|
|
577
|
+
];
|
|
572
578
|
|
|
573
579
|
/**
|
|
574
580
|
* The design files with changes git has not recorded, project-relative. An import's held map
|
|
@@ -614,7 +620,9 @@ export const commitDesign = (projectDir, opts = {}) =>
|
|
|
614
620
|
locked(projectDir, opts.commit ?? true, () => commitUnlocked(projectDir, opts));
|
|
615
621
|
|
|
616
622
|
async function commitUnlocked(projectDir, { message = null, commit = true } = {}) {
|
|
617
|
-
|
|
623
|
+
// A rename takes its old path along (`git mv gcf/glossary.md GLOSSARY.md`): left out, the
|
|
624
|
+
// hook saw the deletion outside the commit and refused it.
|
|
625
|
+
const files = unrecordedDesign(projectDir, { renamed: true });
|
|
618
626
|
if (!files.length) return { files, hash: null };
|
|
619
627
|
const blocking = (await designCheck(projectDir)).issues.filter((i) => i.severity === 'block');
|
|
620
628
|
if (blocking.length) {
|
|
@@ -639,7 +647,7 @@ async function commitUnlocked(projectDir, { message = null, commit = true } = {}
|
|
|
639
647
|
|
|
640
648
|
// What an agent's draft writes (decision 35), and so what `design discard` may take back: not an
|
|
641
649
|
// uploaded GDD, the backlog or the questions, which an import writes.
|
|
642
|
-
const DRAFT_PATHS = ['gcf/PILLARS.md', 'gcf/game.md', '
|
|
650
|
+
const DRAFT_PATHS = ['gcf/PILLARS.md', 'gcf/game.md', docPath('glossary')];
|
|
643
651
|
const isDraftPath = (f) => DRAFT_PATHS.includes(f) || f.startsWith('gcf/design/');
|
|
644
652
|
|
|
645
653
|
/**
|
|
@@ -690,7 +698,7 @@ const isDesignQuestion = (q, units) =>
|
|
|
690
698
|
export async function designState(projectDir, { report, questions, items }) {
|
|
691
699
|
const root = path.join(path.resolve(projectDir), 'gcf');
|
|
692
700
|
const pillarsText = await readIf(path.join(root, 'PILLARS.md'));
|
|
693
|
-
const glossaryText = await readIf(path.join(root,
|
|
701
|
+
const glossaryText = await readIf(path.join(root, DOC_FILES.glossary));
|
|
694
702
|
const game = existsSync(path.join(root, 'game.md'));
|
|
695
703
|
const units = new Set(report.units.map((u) => u.id));
|
|
696
704
|
const sources = await sourcesOf(root);
|
|
@@ -710,6 +718,8 @@ export async function designState(projectDir, { report, questions, items }) {
|
|
|
710
718
|
// The new item form's milestone choices; null without game.md (a free field then).
|
|
711
719
|
milestones: await gameMilestones(root),
|
|
712
720
|
glossary: glossaryText === null ? null : recordsIn(glossaryText, 'terms').length,
|
|
721
|
+
// A glossary left where a core before 0.21 kept it: read no more until it moves.
|
|
722
|
+
glossary_old: existsSync(path.join(root, 'glossary.md')),
|
|
713
723
|
systems: report.systems,
|
|
714
724
|
sources,
|
|
715
725
|
questions: asked.map((q) => q.id),
|
package/lib/design.js
CHANGED
|
@@ -5,7 +5,8 @@ import { readFile, readdir } from 'node:fs/promises';
|
|
|
5
5
|
import { existsSync } from 'node:fs';
|
|
6
6
|
import path from 'node:path';
|
|
7
7
|
import { fileURLToPath } from 'node:url';
|
|
8
|
-
import { parseBlocks, itemsOf, readRecords
|
|
8
|
+
import { parseBlocks, itemsOf, readRecords } from 'cnlp-kit';
|
|
9
|
+
import { profileFor } from 'cnlp-kit/config';
|
|
9
10
|
|
|
10
11
|
export const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
|
|
11
12
|
export const UNIT_TYPES = ['mechanic', 'resource', 'rule', 'constraint', 'entity'];
|
|
@@ -30,8 +31,28 @@ export const AGENT_SLOTS = ['check', 'measure', 'contract', 'interactions'];
|
|
|
30
31
|
|
|
31
32
|
const PROFILES_DIR = fileURLToPath(new URL('../profiles/', import.meta.url));
|
|
32
33
|
|
|
33
|
-
|
|
34
|
-
|
|
34
|
+
// The singleton design documents, each with its file from gcf/: the glossary is the project's
|
|
35
|
+
// GLOSSARY.md beside cnlp.config.json, where cnlp finds it (cnlp-kit 3.10).
|
|
36
|
+
export const DOC_FILES = { game: 'game.md', glossary: '../GLOSSARY.md', pillars: 'PILLARS.md' };
|
|
37
|
+
|
|
38
|
+
/** A doc's file from the project, with `/`: `gcf/game.md`, `GLOSSARY.md`. */
|
|
39
|
+
export const docPath = (name) => path.posix.normalize(`gcf/${DOC_FILES[name]}`);
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The CNL-P profile of a document kind: GCF's own in profiles/ (`unit-mechanic`, `game`, …),
|
|
43
|
+
* else cnlp-kit's (`glossary`: the project glossary is cnlp's document, not GCF's).
|
|
44
|
+
*/
|
|
45
|
+
export const loadDocProfile = (name) => profileFor(name, PROFILES_DIR);
|
|
46
|
+
|
|
47
|
+
// cnlp-kit's own profiles, beside its src/.
|
|
48
|
+
const CNLP_PROFILES = fileURLToPath(new URL('../profiles/', import.meta.resolve('cnlp-kit')));
|
|
49
|
+
|
|
50
|
+
/** The file of the profile loadDocProfile loads: GCF's own, else cnlp-kit's. */
|
|
51
|
+
export function profileFile(name) {
|
|
52
|
+
const own = path.join(PROFILES_DIR, `${name}.md`);
|
|
53
|
+
|
|
54
|
+
return existsSync(own) ? own : path.join(CNLP_PROFILES, `${name}.md`);
|
|
55
|
+
}
|
|
35
56
|
|
|
36
57
|
/** A doc profile's block keys in the order M1 holds a body to. */
|
|
37
58
|
export const blockOrder = async (name) => (await loadDocProfile(name)).sections.map((s) => s.key);
|
package/lib/domain.js
CHANGED
|
@@ -420,7 +420,7 @@ const DESIGN_SPECS = {
|
|
|
420
420
|
// files its agent writes without a permission card; everything else still asks.
|
|
421
421
|
const DESIGN_EDITS = [
|
|
422
422
|
'gcf/game.md',
|
|
423
|
-
'
|
|
423
|
+
'GLOSSARY.md',
|
|
424
424
|
'gcf/backlog.md',
|
|
425
425
|
'gcf/open-questions.md',
|
|
426
426
|
'gcf/INDEX.md',
|
|
@@ -496,7 +496,7 @@ const STARTS = {
|
|
|
496
496
|
label: 'Draft with agent',
|
|
497
497
|
help: 'A draft of the glossary from the vision and the units: you record it, edit or discard it',
|
|
498
498
|
skill: 'gcf-vision',
|
|
499
|
-
say: 'Draft
|
|
499
|
+
say: 'Draft GLOSSARY.md from the vision and the design units. Write it, do not record it.',
|
|
500
500
|
edits: DESIGN_EDITS,
|
|
501
501
|
},
|
|
502
502
|
'draft-system': {
|
package/lib/git.js
CHANGED
|
@@ -95,6 +95,9 @@ export function dirtyPaths(projectDir, paths) {
|
|
|
95
95
|
*/
|
|
96
96
|
export const GATE_SCOPE = [
|
|
97
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',
|
|
98
101
|
':(exclude)gcf/.metrics',
|
|
99
102
|
':(exclude,glob)gcf/source/*.import.json',
|
|
100
103
|
];
|
|
@@ -132,7 +135,7 @@ export function dirtyGcf(projectDir, skip = []) {
|
|
|
132
135
|
if (!/[RC]/.test(xy)) continue;
|
|
133
136
|
i++;
|
|
134
137
|
const old = ours(recs[i] ?? '');
|
|
135
|
-
if (xy.includes('R') && old.startsWith('gcf/')) paths.push(old);
|
|
138
|
+
if (xy.includes('R') && (old.startsWith('gcf/') || old === 'GLOSSARY.md')) paths.push(old);
|
|
136
139
|
}
|
|
137
140
|
|
|
138
141
|
const off = new Set([...skip].map((p) => relOf(projectDir, p)));
|
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
|
}
|