project-spec 0.10.0 → 0.11.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/README.md +51 -13
- package/bin/project-spec.mjs +88 -3
- package/package.json +1 -1
- package/skills/project-knowledge/SKILL.md +21 -5
- package/skills/project-knowledge/references/agents.md +30 -0
- package/skills/project-knowledge/references/format.md +2 -2
- package/skills/project-knowledge/references/gaps.md +3 -2
- package/skills/project-knowledge/references/sync.md +1 -1
- package/skills/project-knowledge/scripts/coverage.py +7 -3
- package/skills/project-knowledge/scripts/knowledge.py +42 -2
- package/viewer/viewer.html +189 -38
- package/skills/spec-change/LICENSE +0 -21
- package/skills/spec-change/SKILL.md +0 -63
- package/skills/spec-change/agents/openai.yaml +0 -4
- package/skills/spec-change/references/gaps.md +0 -163
- /package/skills/{spec-change → project-knowledge}/references/plan.md +0 -0
package/README.md
CHANGED
|
@@ -8,29 +8,59 @@ This is an early project. It has been used on a few real repositories; [VALIDATI
|
|
|
8
8
|
|
|
9
9
|

|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Setup
|
|
12
12
|
|
|
13
13
|
You need an agent that can read your repository (Claude Code or Codex), Python 3.10+, Git, and Node 18+ for the `npx` commands.
|
|
14
14
|
|
|
15
|
+
**1. Install the skill** (once per machine):
|
|
16
|
+
|
|
15
17
|
```sh
|
|
16
18
|
npx project-spec install --claude # or --codex
|
|
17
19
|
```
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
**2. Open your agent in the project and paste this:**
|
|
20
22
|
|
|
21
23
|
```text
|
|
22
24
|
Use the project-knowledge skill to build a knowledge vault for this repository.
|
|
23
|
-
|
|
24
|
-
|
|
25
|
+
|
|
26
|
+
First take the inventory: every app and package, every screen, API endpoint,
|
|
27
|
+
job and email. Write it to the inventory file before any page.
|
|
28
|
+
|
|
29
|
+
Then go one feature at a time and finish each before the next. Describe only
|
|
30
|
+
what the code does: one page per feature with numbered business rules, and
|
|
31
|
+
every doubt as its own gap.
|
|
32
|
+
|
|
33
|
+
If you run out of time, stop at the end of a feature and tell me how many
|
|
34
|
+
features are finished, in progress and not started.
|
|
25
35
|
```
|
|
26
36
|
|
|
27
|
-
|
|
37
|
+
**3. Read what it wrote:**
|
|
28
38
|
|
|
29
39
|
```sh
|
|
30
40
|
npx project-spec serve
|
|
31
41
|
```
|
|
32
42
|
|
|
33
|
-
|
|
43
|
+
A big repository takes more than one session. To go on where the last one stopped:
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
Use the project-knowledge skill and continue the map from the inventory file.
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The agent writes only Markdown under `knowledge/<project>/`. It does not change application code, commit or push. There is also a Claude Code plugin, a manual install and a way to pin one version for a team: see [Install and update](docs/install.md).
|
|
50
|
+
|
|
51
|
+
### What to ask next
|
|
52
|
+
|
|
53
|
+
| When | Prompt |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| A page looks thin | `Use project-knowledge to explore <feature> until it is finished.` |
|
|
56
|
+
| You want the gaps checked | `Use project-knowledge in gaps mode: recheck the high-priority gaps against the code.` |
|
|
57
|
+
| You changed the code | `Use project-knowledge to record this change in the spec.` |
|
|
58
|
+
| Others changed the code | `Use project-knowledge to record what changed last week.` or, for everything since the last review, `... to sync the vault.` |
|
|
59
|
+
| A gap is accepted | `Use project-knowledge to plan the gap <name>. Plan only.` |
|
|
60
|
+
| You have one question | `Use project-knowledge to investigate: <question>.` |
|
|
61
|
+
| A document says how it should work | `Use project-knowledge to audit <document> against the code.` |
|
|
62
|
+
|
|
63
|
+
More in [Working with the skills](docs/workflows.md#example-prompts).
|
|
34
64
|
|
|
35
65
|
## What you get
|
|
36
66
|
|
|
@@ -74,12 +104,19 @@ One local page, read from the files on disk. Nothing is built or uploaded. It co
|
|
|
74
104
|
|
|
75
105
|
[The viewer](docs/viewer.md) describes every screen, and how to show the spec on a development server for the rest of the team.
|
|
76
106
|
|
|
77
|
-
## The
|
|
107
|
+
## The skill
|
|
78
108
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
109
|
+
[project-knowledge](skills/project-knowledge/SKILL.md) writes and maintains the spec and the gap queue. It also audits written requirements against the code, answers one question, re-checks one gap, plans a gap you accepted and follows Git history. It never changes application code.
|
|
110
|
+
|
|
111
|
+
## Keep it current
|
|
112
|
+
|
|
113
|
+
A spec is only worth reading while it is true. The cheap way to keep it true is to let whoever changes the code correct the spec in the same task, as an edit the size of the change: a changed validation message is one row of one table, not a new review of the project.
|
|
114
|
+
|
|
115
|
+
```sh
|
|
116
|
+
npx project-spec instructions --file AGENTS.md # or CLAUDE.md, GEMINI.md, .cursor/rules/project-spec.mdc
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
This writes a short block into the file your agent reads at the start of a session (Codex, Cursor, Claude Code, Gemini CLI, GitHub Copilot). It asks the agent to read a feature's page before changing it and to correct the changed rules afterwards. Run it again after an update and it replaces the block and leaves the rest of the file alone.
|
|
83
120
|
|
|
84
121
|
## Commands
|
|
85
122
|
|
|
@@ -87,8 +124,9 @@ One local page, read from the files on disk. Nothing is built or uploaded. It co
|
|
|
87
124
|
npx project-spec serve # read the spec in the browser
|
|
88
125
|
npx project-spec coverage # what the code has that no page mentions yet
|
|
89
126
|
npx project-spec build --out FILE # the viewer as one file, to show on a server
|
|
90
|
-
npx project-spec
|
|
91
|
-
npx project-spec
|
|
127
|
+
npx project-spec instructions # the block that asks agents to keep the spec current
|
|
128
|
+
npx project-spec status # where the skill is installed and whether it is current
|
|
129
|
+
npx project-spec update # refresh the installed copies
|
|
92
130
|
```
|
|
93
131
|
|
|
94
132
|
## Read more
|
package/bin/project-spec.mjs
CHANGED
|
@@ -21,8 +21,10 @@ const SKIP = new Set(['__pycache__', '.DS_Store', MARKER]);
|
|
|
21
21
|
const KNOWLEDGE = new Set(['serve', 'build', 'check', 'snapshot']);
|
|
22
22
|
const MAINTAIN = new Set(['scan', 'receipt', 'finish']);
|
|
23
23
|
const COVERAGE = 'coverage'; // its own helper, which takes no command word
|
|
24
|
-
// Skills earlier versions shipped; project-knowledge
|
|
25
|
-
|
|
24
|
+
// Skills earlier versions shipped; project-knowledge took over what they did. spec-change (changing the product from
|
|
25
|
+
// an edited spec) was dropped: its planning guide is part of project-knowledge, and the spec is kept current by the
|
|
26
|
+
// agent that changes the code (see `project-spec instructions`).
|
|
27
|
+
const RETIRED = ['spec-audit', 'spec-change', 'spec-investigation', 'spec-plan'];
|
|
26
28
|
// Folders inside a project where a copy of the skills may live.
|
|
27
29
|
const PROJECT_PLACES = ['knowledge/tooling', '.claude/skills', '.codex/skills', '.agents/skills'];
|
|
28
30
|
|
|
@@ -51,7 +53,13 @@ Keep the skills current
|
|
|
51
53
|
Refresh every copy that status lists and remove retired skills. Nothing new is added.
|
|
52
54
|
|
|
53
55
|
A copy you edited by hand is never replaced unless you pass --force; the old files
|
|
54
|
-
are kept under ~/.project-spec/backups first
|
|
56
|
+
are kept under ~/.project-spec/backups first.
|
|
57
|
+
|
|
58
|
+
Keep the spec current
|
|
59
|
+
project-spec instructions [--file FILE]... [--vault DIR] [--remove]
|
|
60
|
+
A short block for AGENTS.md, CLAUDE.md and the like. It asks whoever changes the code to
|
|
61
|
+
correct the spec in the same task, as an edit the size of the change. Printed, or written
|
|
62
|
+
into each FILE you name; run again, it replaces the block and leaves the rest of the file.`;
|
|
55
63
|
|
|
56
64
|
class Problem extends Error {}
|
|
57
65
|
|
|
@@ -279,6 +287,82 @@ function update(args) {
|
|
|
279
287
|
return ok ? 0 : 1;
|
|
280
288
|
}
|
|
281
289
|
|
|
290
|
+
// The block lives in the skill, so an agent without this command can copy it by hand.
|
|
291
|
+
const BLOCK_FILE = path.join(SKILLS, 'project-knowledge', 'references', 'agents.md');
|
|
292
|
+
const BLOCK_START = '<!-- project-spec:start -->';
|
|
293
|
+
const BLOCK_END = '<!-- project-spec:end -->';
|
|
294
|
+
|
|
295
|
+
// As the helpers do: the single vault under knowledge/.
|
|
296
|
+
function findVault(repo) {
|
|
297
|
+
const base = path.join(repo, 'knowledge');
|
|
298
|
+
const found = [];
|
|
299
|
+
if (fs.existsSync(path.join(base, '00-index.md'))) found.push(base);
|
|
300
|
+
else if (fs.existsSync(base)) {
|
|
301
|
+
for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
|
|
302
|
+
if (entry.isDirectory() && fs.existsSync(path.join(base, entry.name, '00-index.md'))) found.push(path.join(base, entry.name));
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
if (found.length !== 1) throw new Problem(`${found.length ? 'several vaults' : 'no vault'} found under knowledge/; name the vault with --vault DIR`);
|
|
306
|
+
return found[0];
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
function instructions(args) {
|
|
310
|
+
const repo = path.resolve(take(args, '--repo').pop() || '.');
|
|
311
|
+
const named = take(args, '--vault').pop();
|
|
312
|
+
const files = take(args, '--file');
|
|
313
|
+
const remove = flag(args, '--remove');
|
|
314
|
+
done(args);
|
|
315
|
+
if (remove && !files.length) throw new Problem('--remove needs --file FILE');
|
|
316
|
+
let block = '';
|
|
317
|
+
if (!remove) {
|
|
318
|
+
const text = fs.readFileSync(BLOCK_FILE, 'utf8');
|
|
319
|
+
const from = text.indexOf(BLOCK_START);
|
|
320
|
+
const to = text.indexOf(BLOCK_END);
|
|
321
|
+
const vault = named ? path.resolve(named) : findVault(repo);
|
|
322
|
+
if (!fs.existsSync(path.join(vault, '00-index.md'))) throw new Problem(`${vault} is not a vault: it has no 00-index.md`);
|
|
323
|
+
const rel = path.relative(repo, vault).split(path.sep).join('/');
|
|
324
|
+
if (!rel || rel.startsWith('..')) throw new Problem('the vault must be a folder inside the repository');
|
|
325
|
+
block = text.slice(from, to + BLOCK_END.length).replaceAll('{vault}', rel);
|
|
326
|
+
}
|
|
327
|
+
if (!files.length) return console.log(block), 0;
|
|
328
|
+
for (const name of files) {
|
|
329
|
+
const file = path.resolve(name);
|
|
330
|
+
const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
|
|
331
|
+
const from = before === null ? -1 : before.indexOf(BLOCK_START);
|
|
332
|
+
const to = before === null ? -1 : before.indexOf(BLOCK_END);
|
|
333
|
+
const has = from >= 0 && to > from;
|
|
334
|
+
let after = before;
|
|
335
|
+
let what;
|
|
336
|
+
if (remove) {
|
|
337
|
+
if (!has) what = 'no project-spec block there';
|
|
338
|
+
else {
|
|
339
|
+
const head = before.slice(0, from).replace(/\s+$/, '');
|
|
340
|
+
const tail = before.slice(to + BLOCK_END.length).trim();
|
|
341
|
+
after = [head, tail].filter(Boolean).join('\n\n') + (head || tail ? '\n' : '');
|
|
342
|
+
what = after ? 'block removed' : 'removed (the file held nothing else)';
|
|
343
|
+
}
|
|
344
|
+
} else if (before === null) {
|
|
345
|
+
// A Cursor rule file needs its own header to be applied in every session.
|
|
346
|
+
after = (file.endsWith('.mdc') ? '---\ndescription: Keep the project spec current\nalwaysApply: true\n---\n\n' : '') + block + '\n';
|
|
347
|
+
what = 'written';
|
|
348
|
+
} else if (has) {
|
|
349
|
+
after = before.slice(0, from) + block + before.slice(to + BLOCK_END.length);
|
|
350
|
+
what = after === before ? 'already current' : 'block updated';
|
|
351
|
+
} else {
|
|
352
|
+
after = before.replace(/\s*$/, '') + (before.trim() ? '\n\n' : '') + block + '\n';
|
|
353
|
+
what = 'block added';
|
|
354
|
+
}
|
|
355
|
+
if (after !== before) {
|
|
356
|
+
if (after) {
|
|
357
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
358
|
+
fs.writeFileSync(file, after);
|
|
359
|
+
} else fs.rmSync(file);
|
|
360
|
+
}
|
|
361
|
+
console.log(` ${path.relative(process.cwd(), file) || file}: ${what}`);
|
|
362
|
+
}
|
|
363
|
+
return 0;
|
|
364
|
+
}
|
|
365
|
+
|
|
282
366
|
function python(script, command, args) {
|
|
283
367
|
if (!args.includes('--repo')) args.push('--repo', '.');
|
|
284
368
|
if (command === 'serve') {
|
|
@@ -299,6 +383,7 @@ function main(argv) {
|
|
|
299
383
|
if (command === 'status') return status(args) || 0;
|
|
300
384
|
if (command === 'install') return install(args);
|
|
301
385
|
if (command === 'update') return update(args);
|
|
386
|
+
if (command === 'instructions') return instructions(args);
|
|
302
387
|
if (KNOWLEDGE.has(command)) return python('knowledge.py', command, args);
|
|
303
388
|
if (MAINTAIN.has(command)) return python('maintain.py', command, args);
|
|
304
389
|
if (command === COVERAGE) return python('coverage.py', command, args);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "project-spec",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Agent skills that read a repository and keep a spec people can read: one page per feature, every business rule numbered. Local viewer and one command to install and update the skills.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent-skills",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: project-knowledge
|
|
3
|
-
description: Understand a repository and keep that understanding true. Builds and maintains an as-built specification derived only from source, in an Obsidian-compatible Markdown vault, plus a separate queue of individually tracked gaps that people re-check and decide. Also audits written requirements against the code and investigates one question or re-checks one gap. Use for project memory, linked architecture notes, syncing the spec with commits, comparing a spec with the implementation, answering why the code behaves as it does, or working through open gaps.
|
|
3
|
+
description: Understand a repository and keep that understanding true. Builds and maintains an as-built specification derived only from source, in an Obsidian-compatible Markdown vault, plus a separate queue of individually tracked gaps that people re-check and decide. Also audits written requirements against the code and investigates one question or re-checks one gap. Use for project memory, linked architecture notes, syncing the spec with commits, comparing a spec with the implementation, answering why the code behaves as it does, or working through open gaps. Also records a code change in the spec as a small edit, and plans an accepted gap. It never changes application code.
|
|
4
4
|
license: MIT
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -27,7 +27,7 @@ Everything else that is a question about the product becomes a gap (`gaps/`), **
|
|
|
27
27
|
|
|
28
28
|
Who writes what:
|
|
29
29
|
|
|
30
|
-
- An agent creates gaps with `decision: "open"
|
|
30
|
+
- An agent creates gaps with `decision: "open"`, `recheck: "not-checked"` and `created` set to today. The pass that found a gap is not its recheck.
|
|
31
31
|
- A person decides: `accepted`, `rejected` or `deferred`, recorded with their name and date. An agent records such a decision only when the person said it, and never infers one from a plan, a task or silence. This keeps the vault an honest record of choices people made, not of what an agent guessed they wanted.
|
|
32
32
|
- An agent may set `duplicate` (bookkeeping) and `done` (it read the current code and the question is closed). Reading the code is a recheck, so it also records `recheck: "not-reproduced"`, `rechecked_by: "agent"`, today's date and a dated `Recheck` entry, and says where the code does it in `Decision`.
|
|
33
33
|
- Rechecks are recorded by whoever ran them; an agent writes `rechecked_by: "agent"`, never its product name, and only for a check it executed.
|
|
@@ -40,17 +40,19 @@ Natural-language requests are fine; these are modes, not a required CLI.
|
|
|
40
40
|
|
|
41
41
|
- **map** (a new vault): take the inventory of what the product has, then go through its features one at a time and finish each before starting the next ([Research before writing](#research-before-writing)). A first map is measured by how many features are finished, not by how many pages exist: thirty finished features and a list of forty not started is a better first map than seventy thin pages. The inventory is kept in a file in the vault ([The inventory file](#the-inventory-file)), which is also where a pass that was interrupted continues. A pass that runs out of time leaves that file saying which features are finished, which one is in progress and which were not started, and never calls itself full.
|
|
42
42
|
- **update**: revisit claims affected since the previous run, preserve manually written knowledge, add discoveries, and fill in what the pages you touch are missing (see [Leave each page better](#leave-each-page-better)).
|
|
43
|
+
- **record <change>**: after a code change, bring only the rules it changed up to date, as an edit the size of the change ([Record a change](#record-a-change)). This is what the agent that changed the code does at the end of its task, and what a person asks for a commit or a pull request.
|
|
43
44
|
- **sync**: reconcile changes from all contributors since the last reviewed Git checkpoint. Read [the sync workflow](references/sync.md); a sync with work you cannot accept yet (for example another contributor's uncommitted files) uses `deferred` and ends as a partial finish with exit status 3 and the checkpoint unmoved.
|
|
44
45
|
- **merge**: reconcile two contributors' vault updates from their common Git base. Read [the merge workflow](references/merge.md).
|
|
45
46
|
- **explore <area or question>**: deepen a bounded area and link the result into the vault. Deepening an area means its feature notes first: what each one is for and every rule a person would look up, with its values, until [the feature is finished](#when-a-feature-is-finished). Then the lists the code keeps in one place, such as its background jobs. A request to "fill in", "complete", "backfill" or "go deeper" means this mode, and so does a reader saying a page is thin.
|
|
46
47
|
- **gaps**: work the queue. List gaps by state; re-verify open gaps against the current code; every kind of gap is rechecked, proposals and questions about unexplained behavior included, because the recheck asks only whether the page's `Current behavior` still describes the code (`confirmed (still holds)` or `not reproduced (no longer holds)`) and never whether a proposal is worth doing, which is the person's decision. For a proposal that usually means confirming the capability is absent. Record each result in the gap's `Recheck` section with `recheck`, `rechecked_by` (`agent` for checks you ran), `rechecked_on`; set `recheck: "outdated"` on a gap whose cited source changed since its recorded recheck (keeping the other two fields); set `done` where the code now closes the question, recording that reading as a `not-reproduced` recheck by `agent`, and make sure the feature's page states the answer as a numbered rule that the gap's `Decision` names ([closing a gap as done](references/gaps.md#closing-a-gap-as-done)); mark duplicates. Then hand the `needs-decision` gaps to people with the options you found in `Discussion`. Never decide one yourself. When a person decides in the conversation, record it with their name; if you do not know their name, ask rather than writing `agent`.
|
|
47
48
|
- **audit <document or feature>**: compare written requirements with the code, keeping what the code satisfies apart from what needs action. Read [the audit guide](references/audit.md). In a vault each finding that needs action becomes its own gap; without a vault the audit is a report.
|
|
48
49
|
- **investigate <question>** or **recheck <gap>**: answer one question about behavior from repository and runtime evidence, or re-check a single gap and write the result into it. Read [the investigation guide](references/investigate.md). It works without a vault too.
|
|
50
|
+
- **plan <gap>**: write the plan for a gap a person accepted, and no code. Read [the planning guide](references/plan.md).
|
|
49
51
|
- **remove <page>**: delete a page the person calls noise. Delete the file, remove or reword every link to it on other pages, run `check`, and say what you removed. Do this only on the person's word, and do not put another page in its place. A real question the person disagrees with is not noise: record their decision as `rejected` so the answer is kept.
|
|
50
52
|
- **check**: validate structure and source freshness without changing researched claims.
|
|
51
53
|
- **migrate**: bring a vault written before the spec/gap split to the current format. Read [the migration guide](references/migrate.md).
|
|
52
54
|
|
|
53
|
-
Run these when the user asks. Creating a vault does not authorize a timer, a hook
|
|
55
|
+
Run these when the user asks. Creating a vault does not authorize a timer, a hook or an automatic commit; those are separate requests the user must make through their host. The one standing instruction this skill offers is [a short block for the repository's instruction file](references/agents.md) (`AGENTS.md`, `CLAUDE.md` and the like), which asks whoever changes the code to record the change in the spec. Offer it when you hand over a vault, and add it only when the person agrees. Teammates receive changes through the normal Git workflow.
|
|
54
56
|
|
|
55
57
|
Write vault content in English unless the user asks for another language, whatever language the chat uses. Keep filenames and IDs as stable ASCII slugs. Reuse an existing vault's conventions and do not migrate unrelated personal notes. The helpers support this format, not arbitrary Obsidian vaults.
|
|
56
58
|
|
|
@@ -64,6 +66,20 @@ Write vault content in English unless the user asks for another language, whatev
|
|
|
64
66
|
6. **Read each client.** When the product has more than one client, read the feature in each of them. Two clients calling the same server procedure does not make them the same: one may lack a screen, a check or a confirmation. Write what differs on the feature's page ([Write the spec](#write-the-spec)); a difference that looks unintended is also a gap.
|
|
65
67
|
7. Track what was read, merely discovered, excluded or changing in the inventory file, as you go and not from memory at the end. Discovery is not review, and a note count is not completeness. When the session will not cover everything, stop at the end of a feature, not in the middle of all of them.
|
|
66
68
|
|
|
69
|
+
### Record a change
|
|
70
|
+
|
|
71
|
+
The cheapest moment to correct the spec is the task that changed the code, while the diff is in front of you. This is an edit, not a research pass, and its size follows the size of the diff: a changed validation message is one row of one table.
|
|
72
|
+
|
|
73
|
+
1. Take the diff: your own change, or `git diff A..B` for the commit, branch, pull request or period the person names ("what changed last week" is the diff from the last commit before that day to `HEAD`). List what a person using the product would notice: a rule that changed, appeared or went away, a new screen, endpoint, job or email, a removed one. A change nobody could notice (a refactor, a rename, a test, styling, a comment) needs no spec edit: say so and stop.
|
|
74
|
+
2. Find the pages: the notes whose `sources` name a changed file (`check` lists them as "changed source"), and the feature the change belongs to when no page cites the file yet.
|
|
75
|
+
3. Edit only what the diff changed. A changed limit, message, condition or permission: correct that rule's row, which keeps its number. A new rule: a new row with the next free number. A behavior that is gone: delete its row and never reuse the number. A new screen, endpoint or job of an existing feature: add it to that feature's page and to [the inventory file](#the-inventory-file). A new feature: a page of its own written from the files in the diff, a line in its area's list and an entry in the inventory; give it `status: "partial"` with what was not read when the diff does not show the whole feature. A file that now holds a rule goes into `sources`. Set `updated` on the pages you edit.
|
|
76
|
+
4. Stay inside the diff. Read other code only as far as stating a rule correctly needs, do not rewrite or reorder the page, and do not fill in what the page was already missing: [Leave each page better](#leave-each-page-better) does not apply to this mode. If the change shows that the page is wrong or thin in other ways, say so in your report; that is an **explore**, and the person decides when to spend it.
|
|
77
|
+
5. Gaps: when the change is about an open gap, record what you read as a recheck on it ([gaps.md](references/gaps.md)); deciding stays with the person. When the change raises a question about the product (the web now refuses what the mobile app allows), write one gap. Nothing else in the queue is touched.
|
|
78
|
+
6. Run `check`. Run `snapshot --notes` for a page you edited, or re-read against the diff and found right as it is, only when every changed source `check` names for it is a file in this diff. A page with a changed source from someone else's work keeps its warning for a **sync**.
|
|
79
|
+
7. No run page, no receipt, and the review checkpoint stays where it is. Report in two or three lines: which rules changed on which pages, or that the spec needed no change.
|
|
80
|
+
|
|
81
|
+
A later **sync** still lists these commits, and it is cheap for them: a note whose sources carry no freshness warning was reviewed when its change was recorded.
|
|
82
|
+
|
|
67
83
|
### The inventory file
|
|
68
84
|
|
|
69
85
|
`$VAULT/.knowledge/inventory.md` is the checklist of the whole map and the place a later session continues from ([format](references/format.md#the-inventory-file)). No helper writes or reads it: keeping it true is your job, and it is what stops a large map from losing a feature or being started again from nothing.
|
|
@@ -93,7 +109,7 @@ Delegate only when the user or repository instructions allow it; give each helpe
|
|
|
93
109
|
Write for the person who asks "what does this do, and what are its rules", not for the person who wrote the code. A page that lists validation without saying what the screen is for has the detail and misses the point.
|
|
94
110
|
|
|
95
111
|
- **Area** pages are maps: what the area covers and where it stops, its feature notes and then its reference notes, each with one line saying what it covers (not how it works), related areas, and what was read, merely discovered or left out. Name the lists the area has that no note holds yet ("Not listed yet: the email templates"), so the next pass knows what to fill in and a reader knows the list is not complete. That line is for what a pass could not finish, with the reason; a map or explore pass that leaves out a list it had the code for is not finished. Give each area a one-line `summary`; the viewer shows it.
|
|
96
|
-
- **New behavior goes into a new note, never into the area page.** An area page describes no behavior itself: no screens, steps, walk-throughs or tables. When you document how a feature works, write a note for it and add a line for it to the area's list, even when the area page looks like the quicker place. A feature
|
|
112
|
+
- **New behavior goes into a new note, never into the area page.** An area page describes no behavior itself: no screens, steps, walk-throughs or tables. When you document how a feature works, write a note for it and add a line for it to the area's list, even when the area page looks like the quicker place. A feature too big for one page gets a note per part ("A feature with parts", below); a feature that fits one page stays one note, whatever number of screens, tabs or steps it has. Link whole notes: if you want to link a heading inside a note, that part is a note of its own. `check` rejects a table, or a link to part of a note, on an area page.
|
|
97
113
|
- **A feature note is the one page for one screen, feature, flow or rule**, and every feature note has the same shape, so a reader knows where to look:
|
|
98
114
|
1. The opening, with no heading: what the feature is for, who uses it and where they find it. One short paragraph, before any rule. "Profile is where a person sets the name and time zone that teammates and emails show for them. Everyone signed in has one, under Settings."
|
|
99
115
|
2. `## How it works`: what a person does and what happens, in the order it happens. Leave it out when there is no flow to tell.
|
|
@@ -109,7 +125,7 @@ Write for the person who asks "what does this do, and what are its rules", not f
|
|
|
109
125
|
- **Say it in the product's words.** "Saving is refused", "the list reloads", "only owners see it", not "the mutation rejects", "refetches", "the RPC requires a nonempty team ID". Name a constant, a job or a route in code formatting when someone would search for it; keep the rest of the code's vocabulary out.
|
|
110
126
|
- **The summary says what the feature is for**, in one or two plain sentences, as a person who never opens the code would say it: no file names, symbols, status codes or words like "verified", and not a rule picked from the page ("The form accepts 1-120 characters" is a rule, not a summary). The viewer shows it under the title and in every list. It is still a claim about the code: it says no more than the page proves. Do not infer design rationale; cite a comment or ADR in the source, or say it is unknown.
|
|
111
127
|
- **A reference note** is a list of things the code registers in one place and that belong to no single feature: the background jobs, the emails and notifications, the routes, the roles and what each may do, the plan limits, the flags, the states of a record. It is one table, one row per item, every item, with the count and where the list comes from ("all 7 jobs registered in `worker/index.ts`"), so a later sync can tell when one is added; put that place in `sources`. A cell holds a value in a few words, two short sentences at most; an item that needs more has a feature note, and the row links to it. Do not write a list note for form fields or for the actions on a screen (they are in the feature's note), for a kind the area has only one or two of, or for a kind it does not have. Each rule is written once: in the feature's note when it belongs to a feature, in the list when it does not.
|
|
112
|
-
- **Cite the few files that decide the behavior.** `sources` holds the files where the
|
|
128
|
+
- **Cite the few files that decide the behavior.** `sources` holds the files where the page's rules are written (the schema, the service, the component): every file a rule on the page was read from, and no others. That is often one to five; it is not a limit, and a rule read from a sixth file makes that file a source. A page that needs many more is usually a feature that should have parts. Every source is a tripwire: when it changes, the page is marked for re-reading. So leave out shared plumbing (the router, a layout, the base client), files that merely sit on the path, and tests unless a test is what the claim rests on. In the text, name the symbol a rule comes from (`INVITE_TTL_DAYS`) and link a file where it helps, without line numbers: a line number points at the wrong line after the next edit, a name still finds the place. When files are renamed or split, `check` reports the missing path; point `sources` at where the rule lives now and re-read the page.
|
|
113
129
|
- **What you ran goes on the run page**, not in the note: commands, PASS, FAIL or NOT RUN, the revision. A note has no "Verification" section and no line naming its area (the frontmatter has it and the viewer shows it). Reading a test does not mean it passes today, so do not write that it does.
|
|
114
130
|
- Link related spec pages with `[[notes/example|label]]` in the sentence that needs them, and say how they relate (depends on, constrains, produces, supersedes). A note belongs to one area; give it a second only when both areas' readers would look for it there. Every substantive page needs an area and a path from the index. Add cross-area links for a reason, not for graph density.
|
|
115
131
|
- A requirements document or ticket is documented intent. It can be quoted in a gap's `Evidence`; it is not a source for what the code does, so never list it in a spec page's `sources` or describe its labels in spec text.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# A standing instruction for the project's agents
|
|
2
|
+
|
|
3
|
+
A spec stays true most cheaply when whoever changes the code corrects the spec in the same task, while the change is still in front of them. The block below asks for exactly that, in a few lines, from any agent that works in the repository, whether or not it has this skill. It goes into the file the agent reads at the start of a session:
|
|
4
|
+
|
|
5
|
+
| Agent | File |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| Codex, Cursor, Gemini CLI, GitHub Copilot and others that read it | `AGENTS.md` |
|
|
8
|
+
| Claude Code | `CLAUDE.md` |
|
|
9
|
+
| Gemini CLI, by default | `GEMINI.md` |
|
|
10
|
+
| Cursor rules | `.cursor/rules/project-spec.mdc` |
|
|
11
|
+
| GitHub Copilot | `.github/copilot-instructions.md` |
|
|
12
|
+
|
|
13
|
+
Add it only when the person agrees: it is a rule for everyone who works in the repository. `npx project-spec instructions --file AGENTS.md` writes it with the vault's path filled in, and replaces the block when run again; by hand, copy the text between the two marker lines, markers included, and put the vault's path where it says `{vault}`. Keep the block as short as it is: it is read at the start of every session.
|
|
14
|
+
|
|
15
|
+
<!-- project-spec:start -->
|
|
16
|
+
## Project spec
|
|
17
|
+
|
|
18
|
+
`{vault}/` is this project's as-built spec. `notes/` has one page per feature with its numbered business rules (`BR-CHAT-03`), `gaps/` has the open questions, `00-index.md` is the way in. It says what the code does now.
|
|
19
|
+
|
|
20
|
+
- Before you change a feature, read its page.
|
|
21
|
+
- When your change alters what the product does, correct the spec in the same task, and keep the edit as small as the change:
|
|
22
|
+
- a changed limit, message, condition or permission: correct that rule's row; the rule keeps its number
|
|
23
|
+
- a new rule: a new row with the next free number; a rule that is gone: delete its row and never reuse the number
|
|
24
|
+
- a new screen, endpoint or job: add it to its feature's page; a new feature gets a page of its own, linked from its area's page
|
|
25
|
+
- Edit only the pages of features you changed. Do not re-read other code, rewrite a page or start a review of the whole spec. A refactor, a rename, a test or a styling change needs no spec edit.
|
|
26
|
+
- Then run `npx project-spec check --vault {vault}`. Run `npx project-spec snapshot --vault {vault} --notes <ids of the pages you edited>` when `check` names no changed source for those pages other than files you changed.
|
|
27
|
+
- A doubt about the product is not written into a page: tell the person. Do not decide or close a gap.
|
|
28
|
+
|
|
29
|
+
With the project-knowledge skill installed, follow its "Record a change" section, which has the full rules.
|
|
30
|
+
<!-- project-spec:end -->
|
|
@@ -233,14 +233,14 @@ Rules the validator applies beyond the basics: `decided_by: "agent"` is rejected
|
|
|
233
233
|
"sources": ["src/service.ts"], "summary": "", "updated": "2026-11-14", "stale": false,
|
|
234
234
|
"kind": "", "recheck": "", "recheckedBy": "", "recheckedOn": "",
|
|
235
235
|
"decision": "", "decidedBy": "", "decidedOn": "", "state": "",
|
|
236
|
-
"gap": "", "layer": "spec", "recheckOutdated": false, "priority": "", "confidence": "", "duplicateOf": ""
|
|
236
|
+
"gap": "", "layer": "spec", "recheckOutdated": false, "priority": "", "confidence": "", "duplicateOf": "", "added": ""
|
|
237
237
|
}],
|
|
238
238
|
"edges": [{"source": "collections", "target": "collection-periods"}],
|
|
239
239
|
"warnings": []
|
|
240
240
|
}
|
|
241
241
|
```
|
|
242
242
|
|
|
243
|
-
The added fields are empty strings when they do not apply. `recheckOutdated` is true when `recheck` is `outdated` or the automatic marker applies. `priority`, `confidence` and `duplicateOf` are gap properties, empty when absent. `layer` is `spec` for areas and notes, `gap` for gaps and plans, `nav` for index and run pages. For a gap node `status` is `""` and `gap` stays empty; for a plan node `gap` holds the gap id. The viewer treats missing fields as empty, so older data still opens.
|
|
243
|
+
The added fields are empty strings when they do not apply. `recheckOutdated` is true when `recheck` is `outdated` or the automatic marker applies. `priority`, `confidence` and `duplicateOf` are gap properties, empty when absent. `added` is the day a gap appeared: its `created` property, else the day its page was first committed, else empty (a page not committed yet, or no Git history); it is empty for every other page. `layer` is `spec` for areas and notes, `gap` for gaps and plans, `nav` for index and run pages. For a gap node `status` is `""` and `gap` stays empty; for a plan node `gap` holds the gap id. The viewer treats missing fields as empty, so older data still opens.
|
|
244
244
|
|
|
245
245
|
Extract prose wikilinks, excluding inline and fenced code examples. Resolve full vault paths and unique basenames; reject missing or ambiguous notes. Strip aliases and heading or block fragments when checking file existence; headings are not validated. Area membership also adds navigation edges. Label the result as a knowledge and coverage map, not a runtime dependency graph.
|
|
246
246
|
|
|
@@ -27,7 +27,8 @@ A gap must not have `status`; its progress is carried by `recheck` and `decision
|
|
|
27
27
|
| `decided_by` | when `decision` is `accepted`, `rejected` or `deferred` | a person's name; the value `agent` is an error |
|
|
28
28
|
| `decided_on` | when `decision` is `accepted`, `rejected` or `deferred` | `YYYY-MM-DD` |
|
|
29
29
|
| `duplicate_of` | when `decision` is `duplicate` | id of another existing gap (not itself) |
|
|
30
|
-
| `
|
|
30
|
+
| `created` | optional, gap pages only | `YYYY-MM-DD`: the day the gap was written. Set it when you create the gap and never change it. The viewer shows it on the gap and can list the newest gaps first; for a page without it, the viewer uses the day the page was first committed. |
|
|
31
|
+
| `priority`, `confidence` | optional, gap and plan pages only | short strings, e.g. `"high"`. Use `high`, `medium` or `low` for `priority` (or `P0` to `P4`): the viewer lists the most urgent gap of each state first, can show one priority only, and can list the newest gaps first instead. |
|
|
31
32
|
|
|
32
33
|
`decided_by` and `decided_on` are also allowed on `done` and `duplicate` but not required. With `outdated`, `rechecked_by` and `rechecked_on` stay in place as the record of the last recheck actually done. A fresh recheck replaces all three fields and adds a new dated entry to the `Recheck` section; keep the older entries.
|
|
33
34
|
|
|
@@ -81,7 +82,7 @@ Use `agent` as the name for entries you write yourself. Layout of options, objec
|
|
|
81
82
|
|
|
82
83
|
| Field | Who |
|
|
83
84
|
| --- | --- |
|
|
84
|
-
| New gap: `kind`, `recheck: "not-checked"`, `decision: "open"`, optional `priority`/`confidence` | The agent that found it |
|
|
85
|
+
| New gap: `kind`, `recheck: "not-checked"`, `decision: "open"`, `created` (today), optional `priority`/`confidence` | The agent that found it |
|
|
85
86
|
| `recheck`, `rechecked_by`, `rechecked_on`, `Recheck` text | Whoever actually performed the check; an agent writes `agent` only for a check it ran itself, with its commands and results. An agent may also set `recheck: "outdated"` when a cited source changed since the recorded recheck, keeping the other two fields |
|
|
86
87
|
| `decision: accepted`, `rejected`, `deferred` with `decided_by`, `decided_on` | A person only. An agent writes it only when a person said so in the conversation, and records that person's name |
|
|
87
88
|
| `decision: done` | An agent may set it after reading current code that closes the question; it cites where in `Decision` and records that reading as a recheck (see below). A person closing a gap as done records the decision in `decided_by`/`Decision`; their name goes in `rechecked_by` only if they read or ran the current code themselves, otherwise the recheck fields stay as they are |
|
|
@@ -34,7 +34,7 @@ Existing clones reuse the shared checkpoint.
|
|
|
34
34
|
|
|
35
35
|
Follow the repository's task coordination for substantive writes, and respect other people's claims on specific notes and source areas.
|
|
36
36
|
|
|
37
|
-
**Spec notes.**
|
|
37
|
+
**Spec notes.** A note the scan lists as affected whose sources carry no freshness warning was already reviewed after the change, usually by the task that made it ([Record a change](../SKILL.md#record-a-change)): give it `unchanged` with the reason "recorded with the change" and read it again only when the diff shows something its page lacks. For the rest, read each relevant diff in its execution context. Inspect the mapped notes, connected rules and uncovered files; a new route or service may need a new area or note. Classify every pending path as reviewed, excluded with a concrete reason, or deferred. A generated asset may be excluded; an unknown behavior may not be excluded just to empty the queue. Credential files are not evidence and their contents never enter the vault. Update claims from the code, keep manual text and stable IDs, and resolve deleted or renamed sources by investigation. A changed registration point (a new job, route, email, role or flag) updates the reference note that lists that kind of thing; a changed form or screen updates its feature note. A note you re-read gets what it is missing, what the feature is for and its rules with their values, and loses what a reader does not need; see "Leave each page better" in the skill. For a renamed or split file, point `sources` at where the rule lives now and re-read the page. If evidence is truly gone, keep the note as `stale` or `superseded` with a line saying what could not be found; open a gap only if a question about the product remains. a missing note is not evidence of missing functionality.
|
|
38
38
|
|
|
39
39
|
**Gaps.** List the gaps whose `sources` include a changed path, and any gap whose described behavior the diff touches. For each, re-read the current code:
|
|
40
40
|
|
|
@@ -34,6 +34,8 @@ LOG_LINE = re.compile(r'\b(console|logger|log|logging|Sentry|debug)\s*\.\s*\w+\s
|
|
|
34
34
|
NOT_PROSE = re.compile(r'[{}<>;=\\]|\$\(|^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|WITH)\b|https?://|\w+\.\w+\(|\w/\w+/\w')
|
|
35
35
|
# A named number: MAX_ATTACHMENTS = 10, TTL_MS: number = 60 * 60 * 1000
|
|
36
36
|
LIMIT = re.compile(r'\b([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\s*(?::[^=\n]{1,40})?=\s*([-+]?\d[\d_.]*(?:\s*[*/+-]\s*\d[\d_.]*)*)\s*[;,]?\s*(?:(?://|#).*)?$', re.M)
|
|
37
|
+
# A docstring describes the code to its reader; nobody using the product sees it.
|
|
38
|
+
DOCSTRING = re.compile(r'''^[ \t]*[rRuU]?("""|\'\'\')[\s\S]*?\1''', re.M)
|
|
37
39
|
PUNCTUATION = str.maketrans({'‘': "'", '’': "'", '“': '"', '”': '"', '–': '-', '—': '-', ' ': ' '})
|
|
38
40
|
|
|
39
41
|
|
|
@@ -53,7 +55,7 @@ def is_sentence(text):
|
|
|
53
55
|
|
|
54
56
|
def sentences_in(text):
|
|
55
57
|
found = []
|
|
56
|
-
for line in text.split('\n'):
|
|
58
|
+
for line in DOCSTRING.sub('', text).split('\n'):
|
|
57
59
|
if LOG_LINE.search(line):
|
|
58
60
|
continue
|
|
59
61
|
for _, inner in QUOTED.findall(line):
|
|
@@ -184,13 +186,15 @@ def main(argv=None):
|
|
|
184
186
|
if prefixes:
|
|
185
187
|
items = [(name, 'says', s) for name, f in files.items() for s in f['unquoted']]
|
|
186
188
|
items += [(name, 'sets', f'{n} = {v}') for name, f in files.items() for n, v in f['unnamed']]
|
|
187
|
-
print(f'\n{len(items)} things under {", ".join(prefixes)} that no page mentions:'
|
|
189
|
+
print(f'\n{len(items)} things under {", ".join(prefixes)} that no page mentions:' if items
|
|
190
|
+
else f'\nNothing under {", ".join(prefixes)} is missing from the pages.')
|
|
188
191
|
for name, verb, what in (items if args.all else items[:60]):
|
|
189
192
|
print(f' {name} {verb}: {what}')
|
|
190
193
|
if not args.all and len(items) > 60:
|
|
191
194
|
print(f' ... and {len(items) - 60} more (--all prints them)')
|
|
192
195
|
uncited = sorted((f['lines'], name) for name, f in files.items() if not f['cited'])
|
|
193
|
-
print(f'\n{len(uncited)} of {len(files)} files there are cited by no page; the largest:'
|
|
196
|
+
print(f'\n{len(uncited)} of {len(files)} files there are cited by no page; the largest:' if uncited
|
|
197
|
+
else f'\nEvery one of the {len(files)} files there is cited by a page.')
|
|
194
198
|
for lines, name in reversed(uncited[-(len(uncited) if args.all else 15):]):
|
|
195
199
|
print(f' {name} ({lines} lines)')
|
|
196
200
|
return 0
|
|
@@ -23,7 +23,7 @@ RECHECKS = ('not-checked', 'confirmed', 'not-reproduced', 'outdated')
|
|
|
23
23
|
DECISIONS = ('open', 'accepted', 'rejected', 'deferred', 'done', 'duplicate')
|
|
24
24
|
DECIDED = ('accepted', 'rejected', 'deferred')
|
|
25
25
|
STATE_ORDER = ('needs-recheck', 'needs-decision', 'accepted', 'deferred', 'rejected', 'done', 'duplicate')
|
|
26
|
-
GAP_ONLY = ('kind', 'recheck', 'rechecked_by', 'rechecked_on', 'decision', 'decided_by', 'decided_on', 'duplicate_of')
|
|
26
|
+
GAP_ONLY = ('kind', 'recheck', 'rechecked_by', 'rechecked_on', 'decision', 'decided_by', 'decided_on', 'duplicate_of', 'created')
|
|
27
27
|
GAP_SECTIONS = ('Current behavior', 'Gap', 'Evidence', 'Recheck', 'Discussion', 'Decision')
|
|
28
28
|
LAYERS = {'area': 'spec', 'note': 'spec', 'gap': 'gap', 'plan': 'gap', 'index': 'nav', 'run': 'nav'}
|
|
29
29
|
UNCOUNTED = ' (uncommitted change, not counted)' # suffix of a freshness warning that --ignore-dirty does not count
|
|
@@ -253,6 +253,8 @@ def validate_gap(meta):
|
|
|
253
253
|
raise ValueError("decided_by must be a person's name: an agent may not decide, only record what a person decided")
|
|
254
254
|
if 'decided_on' in meta:
|
|
255
255
|
check_date('decided_on', meta['decided_on'])
|
|
256
|
+
if 'created' in meta:
|
|
257
|
+
check_date('created', meta['created'])
|
|
256
258
|
if meta['decision'] == 'duplicate':
|
|
257
259
|
if not meta.get('duplicate_of', '').strip():
|
|
258
260
|
raise ValueError("duplicate_of is required when decision is 'duplicate': give the id of the other gap")
|
|
@@ -819,6 +821,40 @@ def vault_history(repo, vault):
|
|
|
819
821
|
return commits
|
|
820
822
|
|
|
821
823
|
|
|
824
|
+
_added_cache = {}
|
|
825
|
+
|
|
826
|
+
|
|
827
|
+
def added_dates(repo, vault):
|
|
828
|
+
"""The day each vault page was first committed, by its path in the vault. Empty outside a Git work tree.
|
|
829
|
+
|
|
830
|
+
A gap's own `created` property wins over this; the history only answers for pages written before that property
|
|
831
|
+
existed. A renamed page counts from the rename. Cached per HEAD, because every page load asks for it.
|
|
832
|
+
"""
|
|
833
|
+
spec, prefix = page_pathspec(repo, vault)
|
|
834
|
+
head = run_git(repo, ['rev-parse', 'HEAD']) if spec else None
|
|
835
|
+
if spec is None or head.returncode:
|
|
836
|
+
return {}
|
|
837
|
+
key = (str(repo), str(vault), head.stdout.strip())
|
|
838
|
+
if key not in _added_cache:
|
|
839
|
+
top = run_git(repo, ['rev-parse', '--show-prefix']).stdout.decode(errors='replace').strip()
|
|
840
|
+
try:
|
|
841
|
+
log = run_git(repo, ['-c', 'core.quotepath=off', 'log', '--date=short', '--no-color', '--no-renames', '--diff-filter=A',
|
|
842
|
+
'--name-only', '--format=%x01%H%x02%ad', '--', *spec], timeout=20)
|
|
843
|
+
except subprocess.TimeoutExpired:
|
|
844
|
+
return {}
|
|
845
|
+
found, boundary = {}, shallow_commits(repo)
|
|
846
|
+
for chunk in (log.stdout.decode('utf-8', errors='replace').split('\x01')[1:] if not log.returncode else []):
|
|
847
|
+
header, _, names = chunk.partition('\n')
|
|
848
|
+
sha, _, date = header.partition('\x02')
|
|
849
|
+
if sha in boundary: # its parents were not fetched, so every page looks added there
|
|
850
|
+
continue
|
|
851
|
+
for name in names.split('\n'):
|
|
852
|
+
if name.startswith(top + prefix):
|
|
853
|
+
found[name[len(top + prefix):]] = date.strip() # newest first, so the oldest commit has the last word
|
|
854
|
+
_added_cache[key] = found
|
|
855
|
+
return _added_cache[key]
|
|
856
|
+
|
|
857
|
+
|
|
822
858
|
def vault_pending(repo, vault):
|
|
823
859
|
"""Vault pages with uncommitted changes: [{path, status}], empty outside Git."""
|
|
824
860
|
spec, prefix = page_pathspec(repo, vault)
|
|
@@ -842,7 +878,11 @@ def vault_pending(repo, vault):
|
|
|
842
878
|
|
|
843
879
|
def page_payload(repo, vault, notes, edges, warnings, sources=True):
|
|
844
880
|
files = cited_files(repo, vault, notes)[0] if sources else {}
|
|
845
|
-
|
|
881
|
+
graph, first = graph_of(notes, edges, warnings), added_dates(repo, vault)
|
|
882
|
+
for node, note in zip(graph['nodes'], notes):
|
|
883
|
+
# When a gap appeared: the day its page says, else the day the page was first committed, else unknown (a new page).
|
|
884
|
+
node['added'] = note['meta'].get('created', '') or first.get(note['path'], '') if note['meta']['type'] == 'gap' else ''
|
|
885
|
+
return graph | {
|
|
846
886
|
'vaultPath': Path(os.path.relpath(vault, repo)).as_posix(), 'files': files,
|
|
847
887
|
'history': vault_history(repo, vault), 'pending': vault_pending(repo, vault)}
|
|
848
888
|
|
package/viewer/viewer.html
CHANGED
|
@@ -417,6 +417,54 @@
|
|
|
417
417
|
.map-head .pillrow {
|
|
418
418
|
gap: 6px;
|
|
419
419
|
}
|
|
420
|
+
/* The queue's states are tabs, plain words with a count, so the row of filters under them stays quiet. */
|
|
421
|
+
.tabrow {
|
|
422
|
+
display: flex;
|
|
423
|
+
flex-wrap: wrap;
|
|
424
|
+
gap: 0 22px;
|
|
425
|
+
border-bottom: 1px solid var(--line);
|
|
426
|
+
}
|
|
427
|
+
.tab {
|
|
428
|
+
display: inline-flex;
|
|
429
|
+
align-items: baseline;
|
|
430
|
+
gap: 6px;
|
|
431
|
+
min-height: 36px;
|
|
432
|
+
padding: 0 1px;
|
|
433
|
+
margin-bottom: -1px;
|
|
434
|
+
border: 0;
|
|
435
|
+
border-bottom: 2px solid transparent;
|
|
436
|
+
background: none;
|
|
437
|
+
color: var(--muted);
|
|
438
|
+
font: 600 14px/1 var(--sans);
|
|
439
|
+
}
|
|
440
|
+
.tab:hover {
|
|
441
|
+
color: var(--ink);
|
|
442
|
+
}
|
|
443
|
+
.tab[aria-pressed="true"] {
|
|
444
|
+
color: var(--ink);
|
|
445
|
+
border-bottom-color: var(--ink);
|
|
446
|
+
}
|
|
447
|
+
.tab .n {
|
|
448
|
+
font: 12px var(--mono);
|
|
449
|
+
opacity: 0.75;
|
|
450
|
+
}
|
|
451
|
+
.filters {
|
|
452
|
+
display: flex;
|
|
453
|
+
flex-wrap: wrap;
|
|
454
|
+
align-items: center;
|
|
455
|
+
gap: 8px;
|
|
456
|
+
}
|
|
457
|
+
.filters select {
|
|
458
|
+
max-width: 220px;
|
|
459
|
+
}
|
|
460
|
+
.filters .push {
|
|
461
|
+
margin-left: auto;
|
|
462
|
+
}
|
|
463
|
+
@media (pointer: coarse) {
|
|
464
|
+
.tab {
|
|
465
|
+
min-height: 44px;
|
|
466
|
+
}
|
|
467
|
+
}
|
|
420
468
|
.view:has(> .compact) {
|
|
421
469
|
padding-top: 18px;
|
|
422
470
|
}
|
|
@@ -1295,14 +1343,17 @@
|
|
|
1295
1343
|
padding: 20px;
|
|
1296
1344
|
overflow: hidden;
|
|
1297
1345
|
}
|
|
1346
|
+
/* One size whatever is chosen, so picking another request moves nothing: the list of requests, the
|
|
1347
|
+
fields for the chosen one and the text that gets copied each keep their place and scroll by themselves. */
|
|
1298
1348
|
.copy-card {
|
|
1299
|
-
width: min(
|
|
1300
|
-
|
|
1349
|
+
width: min(1080px, 100%);
|
|
1350
|
+
height: min(640px, calc(100vh - 40px));
|
|
1301
1351
|
padding: 22px 24px 24px;
|
|
1302
1352
|
display: grid;
|
|
1303
|
-
grid-template-columns: minmax(0, 1fr) minmax(0,
|
|
1304
|
-
|
|
1305
|
-
|
|
1353
|
+
grid-template-columns: 188px minmax(0, 1fr) minmax(0, 1.15fr);
|
|
1354
|
+
grid-template-rows: auto minmax(0, 1fr);
|
|
1355
|
+
gap: 16px 24px;
|
|
1356
|
+
overflow: hidden;
|
|
1306
1357
|
}
|
|
1307
1358
|
.copy-card > .stack {
|
|
1308
1359
|
grid-column: 1 / -1;
|
|
@@ -1310,18 +1361,53 @@
|
|
|
1310
1361
|
}
|
|
1311
1362
|
.copy-card > .stack .h2 {
|
|
1312
1363
|
font-size: 18px;
|
|
1364
|
+
overflow: hidden;
|
|
1365
|
+
text-overflow: ellipsis;
|
|
1366
|
+
white-space: nowrap;
|
|
1313
1367
|
}
|
|
1368
|
+
.copy-menu,
|
|
1314
1369
|
.copy-controls,
|
|
1315
1370
|
.copy-side {
|
|
1316
1371
|
display: flex;
|
|
1317
1372
|
flex-direction: column;
|
|
1318
1373
|
gap: 14px;
|
|
1319
1374
|
min-width: 0;
|
|
1375
|
+
min-height: 0;
|
|
1320
1376
|
}
|
|
1321
|
-
.copy-
|
|
1322
|
-
|
|
1323
|
-
|
|
1324
|
-
|
|
1377
|
+
.copy-menu,
|
|
1378
|
+
.copy-controls {
|
|
1379
|
+
overflow-y: auto;
|
|
1380
|
+
}
|
|
1381
|
+
.copy-controls {
|
|
1382
|
+
padding: 0 2px 2px;
|
|
1383
|
+
}
|
|
1384
|
+
/* The requests are a list to pick from, one under another. */
|
|
1385
|
+
.copy-card .menu {
|
|
1386
|
+
flex-direction: column;
|
|
1387
|
+
flex-wrap: nowrap;
|
|
1388
|
+
gap: 2px;
|
|
1389
|
+
}
|
|
1390
|
+
.copy-card .menu .pill {
|
|
1391
|
+
width: 100%;
|
|
1392
|
+
height: 36px;
|
|
1393
|
+
justify-content: flex-start;
|
|
1394
|
+
padding: 0 12px;
|
|
1395
|
+
border-color: transparent;
|
|
1396
|
+
border-radius: 12px;
|
|
1397
|
+
background: none;
|
|
1398
|
+
font-size: 14px;
|
|
1399
|
+
text-align: left;
|
|
1400
|
+
}
|
|
1401
|
+
.copy-card .menu .pill:hover {
|
|
1402
|
+
background: var(--soft);
|
|
1403
|
+
}
|
|
1404
|
+
.copy-card .menu .pill[aria-pressed="true"] {
|
|
1405
|
+
background: var(--ink);
|
|
1406
|
+
color: #ffffff;
|
|
1407
|
+
}
|
|
1408
|
+
/* Room for the longest explanation, so a shorter one does not pull the fields up. */
|
|
1409
|
+
#copy-hint {
|
|
1410
|
+
min-height: 5.8em;
|
|
1325
1411
|
}
|
|
1326
1412
|
.copy-card .pillrow {
|
|
1327
1413
|
gap: 6px;
|
|
@@ -1346,12 +1432,43 @@
|
|
|
1346
1432
|
.copy-card .btn {
|
|
1347
1433
|
height: 36px;
|
|
1348
1434
|
}
|
|
1349
|
-
|
|
1435
|
+
.copy-side .night {
|
|
1436
|
+
flex: 1;
|
|
1437
|
+
min-height: 0;
|
|
1438
|
+
}
|
|
1439
|
+
.copy-side .night pre {
|
|
1440
|
+
flex: 1;
|
|
1441
|
+
min-height: 0;
|
|
1442
|
+
max-height: none;
|
|
1443
|
+
}
|
|
1444
|
+
@media (max-width: 880px) {
|
|
1350
1445
|
.copy-card {
|
|
1446
|
+
height: auto;
|
|
1447
|
+
max-height: calc(100vh - 40px);
|
|
1351
1448
|
grid-template-columns: minmax(0, 1fr);
|
|
1449
|
+
grid-template-rows: auto;
|
|
1450
|
+
overflow: auto;
|
|
1352
1451
|
}
|
|
1353
|
-
.copy-
|
|
1354
|
-
|
|
1452
|
+
.copy-menu,
|
|
1453
|
+
.copy-controls {
|
|
1454
|
+
overflow: visible;
|
|
1455
|
+
}
|
|
1456
|
+
.copy-card .menu {
|
|
1457
|
+
flex-direction: row;
|
|
1458
|
+
flex-wrap: wrap;
|
|
1459
|
+
gap: 6px;
|
|
1460
|
+
}
|
|
1461
|
+
.copy-card .menu .pill {
|
|
1462
|
+
width: auto;
|
|
1463
|
+
height: 32px;
|
|
1464
|
+
border-color: var(--line-strong);
|
|
1465
|
+
border-radius: 999px;
|
|
1466
|
+
}
|
|
1467
|
+
#copy-hint {
|
|
1468
|
+
min-height: 0;
|
|
1469
|
+
}
|
|
1470
|
+
.copy-side .night pre {
|
|
1471
|
+
max-height: 40vh;
|
|
1355
1472
|
}
|
|
1356
1473
|
}
|
|
1357
1474
|
.copy-card fieldset {
|
|
@@ -1390,10 +1507,6 @@
|
|
|
1390
1507
|
padding: 16px 18px;
|
|
1391
1508
|
border-radius: 16px;
|
|
1392
1509
|
}
|
|
1393
|
-
/* Tall enough to read, short enough that the dialog itself never needs a second scrollbar. */
|
|
1394
|
-
.copy-card .night pre {
|
|
1395
|
-
max-height: max(160px, calc(100vh - 380px));
|
|
1396
|
-
}
|
|
1397
1510
|
.check {
|
|
1398
1511
|
display: flex;
|
|
1399
1512
|
align-items: center;
|
|
@@ -1745,6 +1858,9 @@
|
|
|
1745
1858
|
// The day a gap was closed, as far as the page says: the decision, else the recheck that closed it.
|
|
1746
1859
|
const closedOn = (n) => str(n.decidedOn) || str(n.recheckedOn) || str(n.updated);
|
|
1747
1860
|
const byClosed = (a, b) => closedOn(b).localeCompare(closedOn(a)) || byTitle(a, b);
|
|
1861
|
+
// The day a gap appeared. A gap without one is a page not committed yet, so it is the newest.
|
|
1862
|
+
const addedOn = (n) => str(n.added);
|
|
1863
|
+
const byAdded = (a, b) => (addedOn(b) || "9999").localeCompare(addedOn(a) || "9999") || byGapOrder(a, b);
|
|
1748
1864
|
const recheckOutdated = (n) =>
|
|
1749
1865
|
isGap(n) && (n.recheckOutdated === true || n.recheck === "outdated");
|
|
1750
1866
|
const stateRank = (n) => {
|
|
@@ -2341,6 +2457,7 @@
|
|
|
2341
2457
|
);
|
|
2342
2458
|
if (str(n.priority)) row("Priority", n.priority);
|
|
2343
2459
|
if (str(n.confidence)) row("Confidence", n.confidence);
|
|
2460
|
+
if (addedOn(n)) row("Added", addedOn(n));
|
|
2344
2461
|
box.append(dl);
|
|
2345
2462
|
return box;
|
|
2346
2463
|
}
|
|
@@ -2577,6 +2694,13 @@
|
|
|
2577
2694
|
});
|
|
2578
2695
|
return row;
|
|
2579
2696
|
};
|
|
2697
|
+
// The same choice as pills, drawn as tabs: for the one choice a page is organised by.
|
|
2698
|
+
const tabs = (label, options, current, pick) => {
|
|
2699
|
+
const row = pills(label, options, current, pick);
|
|
2700
|
+
row.className = "tabrow";
|
|
2701
|
+
Array.from(row.children).forEach((b) => (b.className = "tab"));
|
|
2702
|
+
return row;
|
|
2703
|
+
};
|
|
2580
2704
|
function featureList(features) {
|
|
2581
2705
|
const box = el("div");
|
|
2582
2706
|
features.forEach((f) => {
|
|
@@ -2613,7 +2737,7 @@
|
|
|
2613
2737
|
const row = el("div", null, "row"),
|
|
2614
2738
|
grow = el("div", null, "grow");
|
|
2615
2739
|
grow.append(button(g.title, "rowlink", () => openNode(g)));
|
|
2616
|
-
const facts = [kindLabels[g.kind] || str(g.kind), factsLine(g)].filter(Boolean).join(" · ");
|
|
2740
|
+
const facts = [kindLabels[g.kind] || str(g.kind), factsLine(g), addedOn(g) && "Added " + addedOn(g)].filter(Boolean).join(" · ");
|
|
2617
2741
|
if (facts) grow.append(el("span", facts, "muted small"));
|
|
2618
2742
|
row.append(grow, stateBadge(g));
|
|
2619
2743
|
if (recheckOutdated(g)) row.append(outdatedBadge());
|
|
@@ -2844,6 +2968,7 @@
|
|
|
2844
2968
|
const GAP_PORTION = 40;
|
|
2845
2969
|
let gapState = "open", // "open", one of the open states, or "history"
|
|
2846
2970
|
gapShown = GAP_PORTION,
|
|
2971
|
+
gapSort = "urgent", // "urgent" (state, then priority) or "newest" (the day the gap appeared)
|
|
2847
2972
|
gapArea = "",
|
|
2848
2973
|
gapKind = "",
|
|
2849
2974
|
gapPriority = ""; // "" for all, "none" for gaps without one, otherwise the value
|
|
@@ -2863,7 +2988,8 @@
|
|
|
2863
2988
|
// The queue is a work list: one row of title and filters, then the gaps.
|
|
2864
2989
|
function viewGaps(view) {
|
|
2865
2990
|
const box = el("div", null, "stack compact"),
|
|
2866
|
-
head = el("div", null, "map-head")
|
|
2991
|
+
head = el("div", null, "map-head"),
|
|
2992
|
+
filters = el("div", null, "filters");
|
|
2867
2993
|
head.append(el("h1", "Gaps"));
|
|
2868
2994
|
head.title = "Questions about what is missing, unverified or could be added. Each one is rechecked and then decided by a person.";
|
|
2869
2995
|
box.append(head);
|
|
@@ -2879,8 +3005,8 @@
|
|
|
2879
3005
|
show();
|
|
2880
3006
|
},
|
|
2881
3007
|
history = pool.filter(isClosed).length;
|
|
2882
|
-
|
|
2883
|
-
|
|
3008
|
+
box.append(
|
|
3009
|
+
tabs(
|
|
2884
3010
|
"State",
|
|
2885
3011
|
// The queue is the open work; what is closed is one step away, under History. A state with
|
|
2886
3012
|
// no gaps under the current filters is left out, unless it is the one selected.
|
|
@@ -2896,12 +3022,13 @@
|
|
|
2896
3022
|
},
|
|
2897
3023
|
),
|
|
2898
3024
|
);
|
|
3025
|
+
box.append(filters);
|
|
2899
3026
|
if (stateHints[gapState]) box.append(el("p", stateHints[gapState], "muted small"));
|
|
2900
3027
|
const kinds = Object.keys(kindLabels);
|
|
2901
3028
|
nodes.forEach((n) => {
|
|
2902
3029
|
if (isGap(n) && str(n.kind) && !kinds.includes(n.kind)) kinds.push(n.kind);
|
|
2903
3030
|
});
|
|
2904
|
-
|
|
3031
|
+
filters.append(
|
|
2905
3032
|
selectOf("Area", areaOptions(), gapArea, (v) => {
|
|
2906
3033
|
gapArea = v;
|
|
2907
3034
|
again();
|
|
@@ -2916,7 +3043,7 @@
|
|
|
2916
3043
|
(a, b) => priorityRank({ priority: a }) - priorityRank({ priority: b }) || a.localeCompare(b),
|
|
2917
3044
|
);
|
|
2918
3045
|
if (priorities.length || gapPriority)
|
|
2919
|
-
|
|
3046
|
+
filters.append(
|
|
2920
3047
|
selectOf(
|
|
2921
3048
|
"Priority",
|
|
2922
3049
|
[
|
|
@@ -2931,9 +3058,23 @@
|
|
|
2931
3058
|
},
|
|
2932
3059
|
),
|
|
2933
3060
|
);
|
|
3061
|
+
const order = selectOf(
|
|
3062
|
+
"Order",
|
|
3063
|
+
[
|
|
3064
|
+
["urgent", gapState === "history" ? "Last closed first" : "Most urgent first"],
|
|
3065
|
+
["newest", "Newest first"],
|
|
3066
|
+
],
|
|
3067
|
+
gapSort,
|
|
3068
|
+
(v) => {
|
|
3069
|
+
gapSort = v;
|
|
3070
|
+
again();
|
|
3071
|
+
},
|
|
3072
|
+
);
|
|
3073
|
+
order.className = "push";
|
|
3074
|
+
filters.append(order);
|
|
2934
3075
|
const shown = pool
|
|
2935
3076
|
.filter((g) => (gapState === "open" ? !isClosed(g) : gapState === "history" ? isClosed(g) : stateOf(g) === gapState))
|
|
2936
|
-
.sort(gapState === "history" ? byClosed : byGapOrder);
|
|
3077
|
+
.sort(gapSort === "newest" ? byAdded : gapState === "history" ? byClosed : byGapOrder);
|
|
2937
3078
|
if (shown.length) {
|
|
2938
3079
|
// A long queue comes in portions: the most urgent are in the first one, the rest one press away.
|
|
2939
3080
|
const card = el("section", null, "card"),
|
|
@@ -3196,15 +3337,15 @@
|
|
|
3196
3337
|
hint: "The agent writes a plan for an accepted gap: steps, checks, what must be decided first. No code is changed.",
|
|
3197
3338
|
ask: "Limits or wishes for the plan (optional)",
|
|
3198
3339
|
text: (c) =>
|
|
3199
|
-
"Use the
|
|
3340
|
+
"Use the project-knowledge skill to plan this gap. Plan only, do not build it, and only if its decision is accepted; otherwise tell me what is missing." +
|
|
3200
3341
|
(c.note ? "\n\nKeep in mind: " + c.note : ""),
|
|
3201
3342
|
},
|
|
3202
3343
|
change: {
|
|
3203
3344
|
label: "Change the behavior",
|
|
3204
|
-
hint: "You want the product to work differently. The agent asks its questions first, then
|
|
3345
|
+
hint: "You want the product to work differently. The agent asks its questions first, changes the code, then corrects this page so it says what the code does now.",
|
|
3205
3346
|
ask: "What should be different, and for whom",
|
|
3206
3347
|
text: (c) =>
|
|
3207
|
-
"
|
|
3348
|
+
"I want to change the behavior this page describes. Ask your questions first, then change the code and check it. When the code is done, record the change in the spec as the project-knowledge skill describes (Record a change): correct only the rules that changed, and keep their numbers." +
|
|
3208
3349
|
"\n\nWhat I want: " + (c.note || "[describe the change]"),
|
|
3209
3350
|
},
|
|
3210
3351
|
question: {
|
|
@@ -3304,17 +3445,19 @@
|
|
|
3304
3445
|
meta.append(isGap(n) ? stateBadge(n) : statusBadge(n), el("span", repoPath(n), "path"));
|
|
3305
3446
|
top.append(el("div", "Copy for AI", "eyebrow"), el("h2", n.title, "h2"), meta);
|
|
3306
3447
|
|
|
3307
|
-
const want = el("fieldset")
|
|
3308
|
-
|
|
3309
|
-
el("legend", "What should the agent do?"),
|
|
3310
|
-
pills("What should the agent do?", intentsFor(n).map((k) => [k, INTENTS[k].label]), copyState.intent, (v) => {
|
|
3448
|
+
const want = el("fieldset"),
|
|
3449
|
+
menu = pills("What should the agent do?", intentsFor(n).map((k) => [k, INTENTS[k].label]), copyState.intent, (v) => {
|
|
3311
3450
|
copyState.intent = v;
|
|
3451
|
+
copyState.refocus = true;
|
|
3312
3452
|
renderCopy();
|
|
3313
|
-
})
|
|
3314
|
-
|
|
3315
|
-
|
|
3453
|
+
});
|
|
3454
|
+
menu.className = "pillrow menu";
|
|
3455
|
+
want.append(el("legend", "What should the agent do?"), menu);
|
|
3456
|
+
const hint = el("p", intent.hint, "muted small"),
|
|
3457
|
+
chosen = el("div", null, "stack");
|
|
3316
3458
|
hint.id = "copy-hint";
|
|
3317
|
-
|
|
3459
|
+
chosen.style.gap = "10px";
|
|
3460
|
+
chosen.append(hint);
|
|
3318
3461
|
if (intent.choices) {
|
|
3319
3462
|
const [key, options] = intent.choices,
|
|
3320
3463
|
sub = pills(intent.label, options, copyState[key], (v) => {
|
|
@@ -3322,7 +3465,7 @@
|
|
|
3322
3465
|
renderCopy();
|
|
3323
3466
|
});
|
|
3324
3467
|
sub.id = "copy-choice";
|
|
3325
|
-
|
|
3468
|
+
chosen.append(sub);
|
|
3326
3469
|
}
|
|
3327
3470
|
|
|
3328
3471
|
// Typing updates the preview in place, so the field keeps the cursor.
|
|
@@ -3374,11 +3517,19 @@
|
|
|
3374
3517
|
actions.append(copy, button("Close", "btn", closeCopy), el("span", "Nothing is sent. It goes to your clipboard.", "muted small"));
|
|
3375
3518
|
const preview = el("div", null, "night");
|
|
3376
3519
|
preview.append(el("div", "What gets copied", "eyebrow"), pre);
|
|
3377
|
-
const
|
|
3520
|
+
const list = el("div", null, "copy-menu"),
|
|
3521
|
+
controls = el("div", null, "copy-controls"),
|
|
3378
3522
|
side = el("div", null, "copy-side");
|
|
3379
|
-
|
|
3523
|
+
list.append(want);
|
|
3524
|
+
controls.append(chosen, words, include);
|
|
3380
3525
|
side.append(preview, actions);
|
|
3381
|
-
card.append(top, controls, side);
|
|
3526
|
+
card.append(top, list, controls, side);
|
|
3527
|
+
// The card was drawn again, so hand the keyboard back to the request that was picked.
|
|
3528
|
+
if (copyState.refocus) {
|
|
3529
|
+
copyState.refocus = false;
|
|
3530
|
+
const now = Array.from(menu.children).find((b) => b.getAttribute("aria-pressed") === "true");
|
|
3531
|
+
if (now && now.focus) now.focus();
|
|
3532
|
+
}
|
|
3382
3533
|
}
|
|
3383
3534
|
$("#copydlg").addEventListener("click", (e) => {
|
|
3384
3535
|
if (e.target === $("#copydlg")) closeCopy();
|
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 WorldStoryCm
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: spec-change
|
|
3
|
-
description: Change the product, starting from the specification. A person edits the spec text on a branch and the diff is the change request; use to review that diff for contradictions, ambiguity and missing cases before any code is written, then implement it and check every changed statement against the code. Also use to plan a change without building it, with scope, ordered steps, decision gates and observable acceptance criteria. Works on a project-knowledge vault or on any specification kept as Markdown in Git.
|
|
4
|
-
license: MIT
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Spec Change
|
|
8
|
-
|
|
9
|
-
The person describes what they want by editing the specification, not by describing code. Your job is to make the code say what the edited spec says, and to tell them where their text cannot be built as written. They follow the work by reading the spec and your questions, so write for a reader who does not open the source.
|
|
10
|
-
|
|
11
|
-
This skill changes application code. It is the only one in this bundle that does; a plan-only request changes none. Read the repository's instructions first, work on the branch that holds the spec edits, and leave committing, pushing and merging to the person unless they ask.
|
|
12
|
-
|
|
13
|
-
## Plan only
|
|
14
|
-
|
|
15
|
-
When the person asks for a plan and no code, or wants to plan a gap they accepted, follow [the planning guide](references/plan.md) and stop there. The deliverable is the plan; nothing below this section applies until they ask for the change itself.
|
|
16
|
-
|
|
17
|
-
## Read the change request
|
|
18
|
-
|
|
19
|
-
- Find the base the person branched from (ask if it is not obvious) and read the spec diff against it: committed and uncommitted edits to the spec pages. In a project-knowledge vault these are `areas/` and `notes/`; ignore `.knowledge/`.
|
|
20
|
-
- The base spec must describe the base code. If it is behind (a pending sync, freshness warnings), the diff mixes the person's intent with ordinary drift; say so and separate the two before going on.
|
|
21
|
-
- Restate every changed statement as one line in plain language: what happens today, what should happen instead. A removed sentence is a change too. Edits that only reword a page without changing behavior are listed as such and need no code.
|
|
22
|
-
- Do not treat anything outside the diff as a request. An idea in a chat message or a gap page becomes part of the change only when the person puts it into the spec text.
|
|
23
|
-
|
|
24
|
-
## Ask before writing code
|
|
25
|
-
|
|
26
|
-
Review the change as a careful colleague would review a requirement, against both the rest of the spec and the code.
|
|
27
|
-
|
|
28
|
-
- **Contradictions.** Read the pages linked from the changed ones, the rest of their area and the pages that cite the same sources. Name each statement elsewhere that the edit now contradicts.
|
|
29
|
-
- **Ambiguity.** For each changed statement, say who triggers it, when, and what they observe. If two reasonable readings lead to different code, that is a question.
|
|
30
|
-
- **Missing cases.** Check what the edit leaves unsaid: failure and denial, permissions, empty and boundary values, existing stored data, concurrent use, and what other features that call the same code will now do.
|
|
31
|
-
- **Cost surprises.** Trace the current code path far enough to see what the change touches. Tell the person when a one-line edit implies a migration, a contract change for other callers or a new dependency.
|
|
32
|
-
|
|
33
|
-
Sort the findings into two lists. **Questions** need the person's answer because the answer changes behavior; give each a number, the options and the one you would pick. **Assumptions** are choices you can make and reverse cheaply; state them and proceed. Keep the lists short and written in the language of the spec, not of the code.
|
|
34
|
-
|
|
35
|
-
Stop and wait for answers while any question is open. Each answer goes into the spec text, written by the person or by you in their words, so that the spec, not the conversation, holds the decision. If the person cannot answer now, take that statement out of this round: restore its as-built wording and, in a vault, record the open choice as a gap following [gaps.md](references/gaps.md).
|
|
36
|
-
|
|
37
|
-
## Implement
|
|
38
|
-
|
|
39
|
-
- For more than a small change, lay out the ordered steps first, as [the planning guide](references/plan.md) describes: shared contracts before their callers, each step with the check that verifies it.
|
|
40
|
-
- Every changed statement gets a check that would fail on the old behavior, at the boundary the statement describes. Follow the project's conventions and keep the change inside the scope of the diff. If you find something else wrong on the way, report it; do not fix it silently.
|
|
41
|
-
- If the code shows that a statement cannot hold as written, stop and return to the person with the reason and options. Do not reword their spec to match what was easy to build.
|
|
42
|
-
|
|
43
|
-
## Check the code against the spec
|
|
44
|
-
|
|
45
|
-
When the code is done, read it again as if you had not written it and compare it with each changed page, statement by statement.
|
|
46
|
-
|
|
47
|
-
- A statement that holds: note the file and symbol that implement it and the check that ran. Reading a test is not running it; mark checks you did not run `NOT RUN`.
|
|
48
|
-
- A statement that does not hold: fix the code, or bring it to the person. The spec changes only on their word.
|
|
49
|
-
- In a vault, update each changed page's `sources` to the files it now rests on, then run `check` and `snapshot --notes` for the pages you re-read, as the project-knowledge skill describes. No spec page may be left describing behavior the branch does not implement: before the work is called done, such text goes back to its as-built wording and the intent moves to a gap.
|
|
50
|
-
|
|
51
|
-
## Report
|
|
52
|
-
|
|
53
|
-
```text
|
|
54
|
-
# Spec change: <title>
|
|
55
|
-
## What changed one line per statement: before, after
|
|
56
|
-
## Answered questions the question, the answer, where the spec now says it
|
|
57
|
-
## Assumptions choices made without asking, and how to reverse them
|
|
58
|
-
## Evidence statement -> file and symbol -> check, PASS / FAIL / NOT RUN
|
|
59
|
-
## Not done statements taken out of this round, with their gaps
|
|
60
|
-
## Spec text I edited every wording change made by the agent, so the person can review it
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
Keep the report in the person's language and in terms of behavior. Code references belong in the Evidence section only.
|
|
@@ -1,4 +0,0 @@
|
|
|
1
|
-
interface:
|
|
2
|
-
display_name: "Spec Change"
|
|
3
|
-
short_description: "Plan a change, or build it from an edited spec"
|
|
4
|
-
default_prompt: "Use $spec-change to take my edits to the specification as the change request. Review the diff and ask your questions before writing code, then implement it and check every changed statement against the code."
|
|
@@ -1,163 +0,0 @@
|
|
|
1
|
-
# Writing gap and plan pages
|
|
2
|
-
|
|
3
|
-
This page is self-contained: it is enough to create, update or close a gap page, or to write a plan page, in a project-knowledge vault. Nothing else needs to be read first.
|
|
4
|
-
|
|
5
|
-
## Why gaps are separate from the spec
|
|
6
|
-
|
|
7
|
-
A vault has two layers. Spec pages (`areas/`, `notes/`) say what the code does today, nothing more. Gap pages (`gaps/`) hold every doubt, missing piece, contradiction or idea, one question per page. Plan pages (`plans/`) say how to build one accepted gap. The layers stay apart so a reader can trust the spec without wondering which sentences are proposals, and so a person can look at each gap on its own and decide it. An agent proposes; a person decides.
|
|
8
|
-
|
|
9
|
-
Gap and plan pages link to spec notes with wikilinks. Spec pages never link back to gaps or plans (the validator rejects it).
|
|
10
|
-
|
|
11
|
-
## Files and properties
|
|
12
|
-
|
|
13
|
-
A gap lives in `gaps/<slug>.md`; a plan in `plans/<gap-id>.md`. Frontmatter is one property per line with a JSON value (strings in double quotes, arrays on one line).
|
|
14
|
-
|
|
15
|
-
Every page: `id` (unique ASCII slug), `title`, `type`, `areas` (at least one existing area id), `sources` (repository-relative files read; may be empty for gaps and plans), `updated` (`YYYY-MM-DD`, last substantive edit).
|
|
16
|
-
|
|
17
|
-
A gap must not have `status`; its progress is carried by `recheck` and `decision`.
|
|
18
|
-
|
|
19
|
-
| Property | When | Values |
|
|
20
|
-
| --- | --- | --- |
|
|
21
|
-
| `type` | always | `"gap"` |
|
|
22
|
-
| `kind` | always | one of `product-gap` (accepted requirement missing or unmet), `verification-gap` (behavior exists but evidence is missing), `product-plan` (a proposal or open product choice), `conflict` (credible sources disagree), `knowledge-gap` (a specific behavior is unexplained or undocumented; never the vault's own research backlog) |
|
|
23
|
-
| `recheck` | always | `not-checked`, `confirmed` (still holds), `not-reproduced` (no longer holds), `outdated` (the cited sources changed after the last recorded recheck); see [What a recheck means](#what-a-recheck-means) |
|
|
24
|
-
| `rechecked_by` | when `recheck` is not `not-checked` | a person's name, or `agent`; an agent always writes `agent`, and a person's name appears only when that person ran the check and said so |
|
|
25
|
-
| `rechecked_on` | when `recheck` is not `not-checked` | `YYYY-MM-DD` |
|
|
26
|
-
| `decision` | always | `open`, `accepted`, `rejected`, `deferred`, `done`, `duplicate` |
|
|
27
|
-
| `decided_by` | when `decision` is `accepted`, `rejected` or `deferred` | a person's name; the value `agent` is an error |
|
|
28
|
-
| `decided_on` | when `decision` is `accepted`, `rejected` or `deferred` | `YYYY-MM-DD` |
|
|
29
|
-
| `duplicate_of` | when `decision` is `duplicate` | id of another existing gap (not itself) |
|
|
30
|
-
| `priority`, `confidence` | optional, gap and plan pages only | short strings, e.g. `"high"`. Use `high`, `medium` or `low` for `priority` (or `P0` to `P4`): the viewer lists the most urgent gap of each state first and can show one priority only. |
|
|
31
|
-
|
|
32
|
-
`decided_by` and `decided_on` are also allowed on `done` and `duplicate` but not required. With `outdated`, `rechecked_by` and `rechecked_on` stay in place as the record of the last recheck actually done. A fresh recheck replaces all three fields and adds a new dated entry to the `Recheck` section; keep the older entries.
|
|
33
|
-
|
|
34
|
-
The `rechecked_*` fields must be absent only while `recheck` is `not-checked`; `decided_*` absent while `decision` is `open`; `duplicate_of` absent for any other decision. Optional `tags`, `aliases`, `task_ids`, `summary` and `verification` work as on other pages.
|
|
35
|
-
|
|
36
|
-
A plan page has `type: "plan"`, a `status` (`current`, `partial`, `planned`, `stale` or `superseded`; use `planned` until the work is done) and `gap`: the id of an existing gap whose `decision` is `accepted` or `done`.
|
|
37
|
-
|
|
38
|
-
## The six sections
|
|
39
|
-
|
|
40
|
-
Every gap has exactly these `##` headings, once each (order does not matter). A missing or repeated heading is a validation error.
|
|
41
|
-
|
|
42
|
-
- `## Current behavior`: what the code does today in this area, as plain fact, linking the relevant spec notes. No opinion about what it should do.
|
|
43
|
-
- `## Gap`: the one question this page asks, phrased so a person can answer it. If the finding has a second aspect with a different next step or owner, make it a second page.
|
|
44
|
-
- `## Evidence`: what supports the question: files and symbols read, commands run with results, `NOT RUN` for anything only read. Label documented intent, static reading and observed execution separately.
|
|
45
|
-
- `## Recheck`: while `not-checked`, write "Not checked yet." Otherwise: who re-verified, how, when, and what they found, newest entry last. When you set `outdated`, add a dated line saying which source changed. The pass that raised the gap is not a recheck.
|
|
46
|
-
- `## Discussion`: append-only log, see below.
|
|
47
|
-
- `## Decision`: while `open`, write "Open." Otherwise the decision and its reason, in the words of the person who decided. For `done`, say where in the code the question is now closed. For `duplicate`, name the surviving gap.
|
|
48
|
-
|
|
49
|
-
When `recheck` is not `not-checked`, the Recheck section must have text; when `decision` is not `open`, so must Decision.
|
|
50
|
-
|
|
51
|
-
## What a recheck means
|
|
52
|
-
|
|
53
|
-
A recheck asks one question of every gap, whatever its kind: **does the page's `Current behavior` section still describe the code?** It is not a verdict on the gap's worth. The reason to ask is that a person decides on the gap only after someone has confirmed the page still describes reality, and that needs to be possible for proposals and questions about unexplained behavior too, not only for defects.
|
|
54
|
-
|
|
55
|
-
- `confirmed` ("confirmed (still holds)"): yes. What `Current behavior` says, including what it says is absent, is what the code does now.
|
|
56
|
-
- `not-reproduced` ("not reproduced (no longer holds)"): no. The code no longer matches the description: the capability exists, the defect is gone, the sources stopped disagreeing. The usual next step is `decision: "done"`, or rewriting the gap around what is true now.
|
|
57
|
-
|
|
58
|
-
What that means for each kind:
|
|
59
|
-
|
|
60
|
-
| Kind | `confirmed` (still holds) | `not-reproduced` (no longer holds) |
|
|
61
|
-
| --- | --- | --- |
|
|
62
|
-
| `product-gap` | The requirement is still unmet: the code does not do what it asks for. | The code now meets the requirement, or the defect cannot be reproduced. |
|
|
63
|
-
| `verification-gap` | The behavior is as described and the evidence is still missing. | Evidence now exists (a test, a run, a log), or the behavior differs from the description. |
|
|
64
|
-
| `product-plan` | The proposed capability is still absent and nothing already implements it. | Something in the code now does what was proposed. |
|
|
65
|
-
| `conflict` | Both sources still say what the page says, and they still disagree. | One source changed or the claims no longer clash. |
|
|
66
|
-
| `knowledge-gap` | The thing is still unexplained or undocumented: no code, comment or document answers it. | The code or a source now answers the question. |
|
|
67
|
-
|
|
68
|
-
A recheck never judges whether a proposal is worth doing, whether a requirement is right or which side of a conflict should win. That is the person's decision, made afterwards. For a proposal or a question about unexplained behavior the recheck is usually quick, for example reading the code to confirm the capability is absent, and it is still required: without it the gap stays in `needs-recheck` and cannot reach `needs-decision`. Write what you read in `Recheck` so the person can see the page was checked, not assumed.
|
|
69
|
-
|
|
70
|
-
## Discussion entries
|
|
71
|
-
|
|
72
|
-
One bullet per entry, oldest first, never edited or removed afterwards:
|
|
73
|
-
|
|
74
|
-
```text
|
|
75
|
-
- 2026-11-15 · Name: what was said, proposed or learned.
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
Use `agent` as the name for entries you write yourself. Layout of options, objections and questions belongs here, not in `Decision`, which records only the outcome.
|
|
79
|
-
|
|
80
|
-
## Who sets which field
|
|
81
|
-
|
|
82
|
-
| Field | Who |
|
|
83
|
-
| --- | --- |
|
|
84
|
-
| New gap: `kind`, `recheck: "not-checked"`, `decision: "open"`, optional `priority`/`confidence` | The agent that found it |
|
|
85
|
-
| `recheck`, `rechecked_by`, `rechecked_on`, `Recheck` text | Whoever actually performed the check; an agent writes `agent` only for a check it ran itself, with its commands and results. An agent may also set `recheck: "outdated"` when a cited source changed since the recorded recheck, keeping the other two fields |
|
|
86
|
-
| `decision: accepted`, `rejected`, `deferred` with `decided_by`, `decided_on` | A person only. An agent writes it only when a person said so in the conversation, and records that person's name |
|
|
87
|
-
| `decision: done` | An agent may set it after reading current code that closes the question; it cites where in `Decision` and records that reading as a recheck (see below). A person closing a gap as done records the decision in `decided_by`/`Decision`; their name goes in `rechecked_by` only if they read or ran the current code themselves, otherwise the recheck fields stay as they are |
|
|
88
|
-
| `decision: duplicate`, `duplicate_of` | Agent or person (bookkeeping) |
|
|
89
|
-
| `Discussion` | Anyone, by appending |
|
|
90
|
-
|
|
91
|
-
Never guess a decision from silence, from a plan existing, or from a task being created. If it is unclear whether a person decided, leave `open` and ask in `Discussion`.
|
|
92
|
-
|
|
93
|
-
## Closing a gap as done
|
|
94
|
-
|
|
95
|
-
When an agent sets `decision: "done"` because it read (or ran) the current code and the gap no longer holds, that reading is itself a recheck, and the page should say so. In the same edit record `recheck: "not-reproduced"`, `rechecked_by: "agent"`, today's `rechecked_on`, and add a dated entry to `Recheck` saying what was read or run. In `Decision`, say where in the code the question is now closed. The two sections answer different questions: `Recheck` is how you know it no longer holds, `Decision` is where the code does it. Without the recheck fields a closed gap looks as if nobody ever looked at the code. When a person closes a gap as done, they record the decision in `decided_by` and `Decision`. Their name goes in `rechecked_by` (not `agent`) only if they read or ran the current code themselves and add a `Recheck` entry saying what they did; if they decided without doing so, leave the recheck fields as they are. If you are not sure the question is closed, leave it open.
|
|
96
|
-
|
|
97
|
-
Closing a gap is also the moment its answer becomes part of the spec. Before you set `done`, open the page of the feature the gap is about and make sure it states what is true now as a numbered rule, read from the current code: add the rule, or correct the one that was there. Then name that rule in the gap's `Decision` ("Closed by BR-USERS-07") next to the place in the code. The same goes for `rejected`: the behavior stays as it is, so the feature's page should already state it as a rule, and `Decision` names that rule beside the person's reason. The link goes one way, from the gap to the spec page; a spec page still never mentions a gap.
|
|
98
|
-
|
|
99
|
-
A closed gap is not deleted. The spec says what the code does; the closed gap is the only place that says why, who decided and what was checked. The viewer takes closed gaps (`done`, `rejected`, `duplicate`) out of the queue, lists them under History with the most recently closed first, and shows them on the feature's page as closed questions, folded under the text. Delete a gap only when a person calls the page noise.
|
|
100
|
-
|
|
101
|
-
## Derived state
|
|
102
|
-
|
|
103
|
-
Computed by the helper, never written into Markdown:
|
|
104
|
-
|
|
105
|
-
| `decision` | `recheck` | State |
|
|
106
|
-
| --- | --- | --- |
|
|
107
|
-
| `open` | `not-checked` or `outdated` | `needs-recheck` |
|
|
108
|
-
| `open` | `confirmed` or `not-reproduced` | `needs-decision` |
|
|
109
|
-
| anything else | any | the `decision` value |
|
|
110
|
-
|
|
111
|
-
Every open gap passes through a recheck before `needs-decision`, including proposals (`product-plan`) and questions about unexplained behavior (`knowledge-gap`). Rechecking a proposal means confirming the capability is still absent, not judging the proposal.
|
|
112
|
-
|
|
113
|
-
## Example gap page (illustrative)
|
|
114
|
-
|
|
115
|
-
````markdown
|
|
116
|
-
---
|
|
117
|
-
id: "invoice-retry-limit"
|
|
118
|
-
title: "Should failed invoice emails retry more than once?"
|
|
119
|
-
type: "gap"
|
|
120
|
-
kind: "product-plan"
|
|
121
|
-
areas: ["billing"]
|
|
122
|
-
sources: ["src/billing/mailer.py"]
|
|
123
|
-
recheck: "confirmed"
|
|
124
|
-
rechecked_by: "Dana Ruiz"
|
|
125
|
-
rechecked_on: "2026-11-15"
|
|
126
|
-
decision: "open"
|
|
127
|
-
priority: "medium"
|
|
128
|
-
updated: "2026-11-15"
|
|
129
|
-
---
|
|
130
|
-
|
|
131
|
-
# Should failed invoice emails retry more than once?
|
|
132
|
-
|
|
133
|
-
## Current behavior
|
|
134
|
-
|
|
135
|
-
`send_invoice` makes one delivery attempt and logs a failure; it does not schedule another. See [[notes/invoice-delivery|Invoice delivery]].
|
|
136
|
-
|
|
137
|
-
## Gap
|
|
138
|
-
|
|
139
|
-
Customers with a temporary mail outage never receive the invoice. Should the mailer retry, and if so how many times and over what period?
|
|
140
|
-
|
|
141
|
-
## Evidence
|
|
142
|
-
|
|
143
|
-
- Static: `send_invoice` in `src/billing/mailer.py` has no retry loop or queue call.
|
|
144
|
-
- Documented intent: none found; no requirement mentions retries.
|
|
145
|
-
- No test covers a failed first attempt (NOT RUN, nothing to run).
|
|
146
|
-
|
|
147
|
-
## Recheck
|
|
148
|
-
|
|
149
|
-
2026-11-15, Dana Ruiz: re-read `send_invoice` and ran it against a stubbed transport that raises on the first call; the invoice stays unsent, one error is logged and nothing schedules a second attempt. No queue or retry code exists elsewhere in `src/billing/`. Confirmed (still holds): the capability is absent. Whether to add it is the open question below.
|
|
150
|
-
|
|
151
|
-
## Discussion
|
|
152
|
-
|
|
153
|
-
- 2026-11-15 · agent: Options are (a) fixed three retries within an hour, (b) hand the email to the existing job queue, (c) leave as is and show a "resend" button.
|
|
154
|
-
- 2026-11-16 · Dana Ruiz: Leaning to (b); need to check queue limits first.
|
|
155
|
-
|
|
156
|
-
## Decision
|
|
157
|
-
|
|
158
|
-
Open.
|
|
159
|
-
````
|
|
160
|
-
|
|
161
|
-
## Writing a plan page
|
|
162
|
-
|
|
163
|
-
Create one only for a gap whose `decision` is `accepted`. Name it `plans/<gap-id>.md`, give it its own `id` (for example `<gap-id>-plan`), set `gap` to the gap's id and use the gap's areas. The body states the goal and what exists today (with links to spec notes), the ordered steps with the files they touch, observable acceptance checks, what is out of scope, and which checks have not been run. A plan records intent for one decision; it does not add facts to the spec. When the work lands, an agent that reads the code may set the gap to `done`, and the spec notes are then updated from the code.
|
|
File without changes
|