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/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,19 @@ 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
|
+
|
|
62
|
+
### 0.20.2
|
|
63
|
+
|
|
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).
|
|
65
|
+
|
|
53
66
|
### 0.20.1
|
|
54
67
|
|
|
55
68
|
- `edits diff|commit|discard` on a path with no change left ends its error with `gcf-refusal: {"code":"clean","paths":[…],"left":[…]}`: the clean paths, and the named ones still edited. A board whose refusal list went stale (another card's Commit took the files) knows nothing is left to fix.
|
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')
|
|
@@ -753,13 +755,17 @@ function registerEdits(gcf) {
|
|
|
753
755
|
"(the human's)",
|
|
754
756
|
);
|
|
755
757
|
const PATH = 'a path from the project, as the refusal lists it (repeatable)';
|
|
758
|
+
const PATH_FILE = 'the paths from a file, one a line, - for stdin: past the command line';
|
|
759
|
+
// A refusal of many paths runs past Windows' 32K command line: a board sends them on stdin.
|
|
760
|
+
const pathsOf = (o) => [...o.path, ...(o.pathFile === undefined ? [] : linesOf(o.pathFile))];
|
|
756
761
|
group
|
|
757
762
|
.command('diff')
|
|
758
763
|
.description('The edits of these paths: the staged part and the part not staged')
|
|
759
|
-
.
|
|
764
|
+
.option('--path <path>', PATH, repeated, [])
|
|
765
|
+
.option('--path-file <path>', PATH_FILE)
|
|
760
766
|
.option('--json', '{files, staged, unstaged}')
|
|
761
767
|
.action(async (o) => {
|
|
762
|
-
const r = (await edits()).editsDiff(process.cwd(), o
|
|
768
|
+
const r = (await edits()).editsDiff(process.cwd(), pathsOf(o));
|
|
763
769
|
if (o.json) return out(true, r);
|
|
764
770
|
if (r.staged) console.log(`staged:\n${r.staged}`);
|
|
765
771
|
if (r.unstaged) console.log(`not staged:\n${r.unstaged}`);
|
|
@@ -767,10 +773,11 @@ function registerEdits(gcf) {
|
|
|
767
773
|
group
|
|
768
774
|
.command('commit')
|
|
769
775
|
.description('Commit the hand edits of these paths as they are: gcf(edit), through the gate')
|
|
770
|
-
.
|
|
776
|
+
.option('--path <path>', PATH, repeated, [])
|
|
777
|
+
.option('--path-file <path>', PATH_FILE)
|
|
771
778
|
.action(async (o) => {
|
|
772
779
|
await operatorOnly('edits commit');
|
|
773
|
-
const r = await (await edits()).editsCommit(process.cwd(), o
|
|
780
|
+
const r = await (await edits()).editsCommit(process.cwd(), pathsOf(o));
|
|
774
781
|
console.log(`committed ${r.files.join(', ')}${shortHash(r.hash)}`);
|
|
775
782
|
});
|
|
776
783
|
group
|
|
@@ -779,10 +786,11 @@ function registerEdits(gcf) {
|
|
|
779
786
|
'Put these paths back as the last commit has them, the index too; a new file goes. ' +
|
|
780
787
|
'It cannot be undone: look at edits diff first',
|
|
781
788
|
)
|
|
782
|
-
.
|
|
789
|
+
.option('--path <path>', PATH, repeated, [])
|
|
790
|
+
.option('--path-file <path>', PATH_FILE)
|
|
783
791
|
.action(async (o) => {
|
|
784
792
|
await operatorOnly('edits discard');
|
|
785
|
-
const r = await (await edits()).editsDiscard(process.cwd(), o
|
|
793
|
+
const r = await (await edits()).editsDiscard(process.cwd(), pathsOf(o));
|
|
786
794
|
console.log(`discarded ${r.files.join(', ')}`);
|
|
787
795
|
});
|
|
788
796
|
}
|
|
@@ -1354,6 +1362,12 @@ function entryText(arg, o) {
|
|
|
1354
1362
|
return readTextFile(o.textFile);
|
|
1355
1363
|
}
|
|
1356
1364
|
|
|
1365
|
+
/** A file's lines, `-` for stdin: none empty, a CRLF's CR gone. */
|
|
1366
|
+
const linesOf = (file) =>
|
|
1367
|
+
readTextFile(file)
|
|
1368
|
+
.split(/\r?\n/)
|
|
1369
|
+
.filter((l) => l !== '');
|
|
1370
|
+
|
|
1357
1371
|
/** A text file's text, `-` for stdin. */
|
|
1358
1372
|
function readTextFile(file) {
|
|
1359
1373
|
const text = readFileSync(file === '-' ? 0 : file, 'utf8');
|
|
@@ -1529,17 +1543,28 @@ function registerPlan(gcf) {
|
|
|
1529
1543
|
.command('plan')
|
|
1530
1544
|
.description('The plan of a work item')
|
|
1531
1545
|
.command('check <id>')
|
|
1532
|
-
.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
|
+
)
|
|
1533
1550
|
.option('--json', 'machine output')
|
|
1534
1551
|
.action(async (id, o) => {
|
|
1535
1552
|
await touchSession(id);
|
|
1536
1553
|
const r = await (await lib('plan-check')).planCheck(process.cwd(), id);
|
|
1537
|
-
// 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.
|
|
1538
1555
|
await (
|
|
1539
1556
|
await lib('metrics')
|
|
1540
|
-
).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
|
+
]);
|
|
1541
1563
|
out(o.json, r, (x) =>
|
|
1542
|
-
|
|
1564
|
+
[
|
|
1565
|
+
...(x.ok ? [`${x.plan}: ${x.done}/${x.tasks} tasks done`] : x.problems),
|
|
1566
|
+
...x.format.map((f) => `format: ${f}`),
|
|
1567
|
+
].join('\n'),
|
|
1543
1568
|
);
|
|
1544
1569
|
if (!r.ok) process.exitCode = 1;
|
|
1545
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': {
|
|
@@ -603,8 +603,16 @@ const DETAIL = {
|
|
|
603
603
|
help: 'One lowercase word after the category: asset, static-analysis, framework',
|
|
604
604
|
};
|
|
605
605
|
|
|
606
|
-
// The paths of a `dirty` refusal: `--path=<path>` each
|
|
607
|
-
|
|
606
|
+
// The paths of a `dirty` refusal: `--path=<path>` each, or one a line on stdin (`lines`:
|
|
607
|
+
// `--path-file -`, core 0.20.2), past Windows' 32K command line.
|
|
608
|
+
const EDIT_PATHS = {
|
|
609
|
+
key: 'paths',
|
|
610
|
+
flag: 'path',
|
|
611
|
+
label: 'Paths',
|
|
612
|
+
kind: 'list',
|
|
613
|
+
hidden: true,
|
|
614
|
+
lines: true,
|
|
615
|
+
};
|
|
608
616
|
|
|
609
617
|
// The moves of the domain's blocks: the phase, the inbox, the questions, the run order.
|
|
610
618
|
const BLOCK_SPECS = {
|