project-spec 0.9.2 → 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 CHANGED
@@ -8,29 +8,59 @@ This is an early project. It has been used on a few real repositories; [VALIDATI
8
8
 
9
9
  ![A feature page in the viewer: what the feature is for, how it works, and its business rules as numbered rows](docs/images/viewer-page.png)
10
10
 
11
- ## Start
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
- Ask your agent:
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
- Describe only what the code does: one page per feature with its business rules,
24
- and every doubt as its own gap.
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
- Then read what it wrote:
37
+ **3. Read what it wrote:**
28
38
 
29
39
  ```sh
30
40
  npx project-spec serve
31
41
  ```
32
42
 
33
- 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).
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
 
@@ -59,7 +89,7 @@ A rule keeps its number for good, so a reviewer, a tester or a support person ca
59
89
 
60
90
  ## The viewer
61
91
 
62
- One local page, read from the files on disk. Nothing is built or uploaded.
92
+ One local page, read from the files on disk. Nothing is built or uploaded. It comes with the npm package and is not copied into your project; the vault also opens in Obsidian, so the viewer is optional.
63
93
 
64
94
  1. **Read** a feature page: its purpose, its flow, its rules.
65
95
  2. **Find** anything with search, including a rule number.
@@ -74,12 +104,19 @@ One local page, read from the files on disk. Nothing is built or uploaded.
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 two skills
107
+ ## The skill
78
108
 
79
- | Skill | What it does |
80
- | --- | --- |
81
- | [project-knowledge](skills/project-knowledge/SKILL.md) | Writes and maintains the spec and the gap queue. Audits written requirements against the code, answers one question, re-checks one gap, follows Git history. It never changes application code. |
82
- | [spec-change](skills/spec-change/SKILL.md) (experimental) | Changes the product starting from the spec: you edit the spec on a branch, the agent asks its questions, then implements the change and checks each changed statement against the code. |
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.
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 status # where the skills are installed and whether they are current
91
- npx project-spec update # refresh the installed skills
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
@@ -10,14 +10,21 @@ import { fileURLToPath } from 'node:url';
10
10
 
11
11
  const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
12
12
  const SKILLS = path.join(ROOT, 'skills');
13
+ // The viewer is not part of a skill: a skill holds only what writing a spec needs. It lives in the package, and a
14
+ // copy of the skill gets it only when asked (--with-viewer) or when it already had one.
15
+ const VIEWER = path.join(ROOT, 'viewer', 'viewer.html');
16
+ const VIEWER_SKILL = 'project-knowledge';
17
+ const VIEWER_REL = 'assets/viewer.html';
13
18
  const PACKAGE = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
14
19
  const MARKER = '.project-spec.json'; // written into every copy: which version it is and what its files looked like
15
20
  const SKIP = new Set(['__pycache__', '.DS_Store', MARKER]);
16
21
  const KNOWLEDGE = new Set(['serve', 'build', 'check', 'snapshot']);
17
22
  const MAINTAIN = new Set(['scan', 'receipt', 'finish']);
18
23
  const COVERAGE = 'coverage'; // its own helper, which takes no command word
19
- // Skills earlier versions shipped; project-knowledge and spec-change took over what they did.
20
- const RETIRED = ['spec-audit', 'spec-investigation', 'spec-plan'];
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'];
21
28
  // Folders inside a project where a copy of the skills may live.
22
29
  const PROJECT_PLACES = ['knowledge/tooling', '.claude/skills', '.codex/skills', '.agents/skills'];
23
30
 
@@ -38,13 +45,21 @@ Read the spec
38
45
  Keep the skills current
39
46
  project-spec status
40
47
  Where copies of the skills are and whether they match this version.
41
- project-spec install [--claude] [--codex] [--dir DIR]... [--skills a,b] [--force]
48
+ project-spec install [--claude] [--codex] [--dir DIR]... [--skills a,b] [--with-viewer | --no-viewer] [--force]
42
49
  Copy the skills into ~/.claude/skills, ~/.codex/skills or a folder you name.
50
+ A copy holds the instructions and the helpers. --with-viewer adds the viewer page to it, for a
51
+ place without Node; --no-viewer takes it out of a copy that has it.
43
52
  project-spec update [--force]
44
53
  Refresh every copy that status lists and remove retired skills. Nothing new is added.
45
54
 
46
55
  A copy you edited by hand is never replaced unless you pass --force; the old files
47
- 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.`;
48
63
 
49
64
  class Problem extends Error {}
50
65
 
@@ -62,6 +77,15 @@ const skillNames = () =>
62
77
  .map(e => e.name)
63
78
  .sort();
64
79
 
80
+ const sha = file => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
81
+ const hasViewer = dir => fs.existsSync(path.join(dir, VIEWER_REL));
82
+ // The files a copy of a skill should have: the skill's own, and the viewer when this copy carries it.
83
+ function freshFiles(name, viewer) {
84
+ const fresh = filesOf(path.join(SKILLS, name));
85
+ if (viewer && name === VIEWER_SKILL) fresh[VIEWER_REL] = sha(VIEWER);
86
+ return fresh;
87
+ }
88
+
65
89
  function filesOf(dir, base = dir, out = {}) {
66
90
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
67
91
  if (SKIP.has(entry.name) || entry.name.endsWith('.pyc')) continue;
@@ -82,9 +106,10 @@ function readMarker(dir) {
82
106
  }
83
107
 
84
108
  // What a copy is, compared with this package: current, older, modified by hand, unknown, or absent.
85
- function inspect(dir, name) {
109
+ // `viewer` says whether the copy should carry the viewer; left out, a copy keeps what it has.
110
+ function inspect(dir, name, viewer = hasViewer(dir)) {
86
111
  if (!fs.existsSync(path.join(dir, 'SKILL.md'))) return { state: 'absent' };
87
- const fresh = filesOf(path.join(SKILLS, name));
112
+ const fresh = freshFiles(name, viewer);
88
113
  const now = filesOf(dir);
89
114
  const same = (a, b) => Object.keys(a).length === Object.keys(b).length && Object.keys(a).every(k => a[k] === b[k]);
90
115
  const marker = readMarker(dir);
@@ -114,24 +139,32 @@ function backup(dir, name) {
114
139
 
115
140
  // Copies one skill into place. Files an earlier install put there and this version no longer has are removed;
116
141
  // files nobody recorded (yours) are left alone.
117
- function place(dir, name) {
142
+ function place(dir, name, viewer) {
118
143
  const source = path.join(SKILLS, name);
119
- const fresh = filesOf(source);
144
+ const fresh = freshFiles(name, viewer);
120
145
  const marker = readMarker(dir);
121
146
  for (const old of Object.keys(marker ? marker.files : {})) {
122
147
  if (fresh[old] === undefined) fs.rmSync(path.join(dir, old), { force: true });
123
148
  }
149
+ if (name === VIEWER_SKILL && !viewer) {
150
+ fs.rmSync(path.join(dir, VIEWER_REL), { force: true });
151
+ try {
152
+ fs.rmdirSync(path.dirname(path.join(dir, VIEWER_REL))); // only when nothing else is in it
153
+ } catch {}
154
+ }
124
155
  for (const rel of Object.keys(fresh)) {
125
156
  const to = path.join(dir, rel);
126
157
  fs.mkdirSync(path.dirname(to), { recursive: true });
127
- fs.copyFileSync(path.join(source, rel), to);
158
+ fs.copyFileSync(rel === VIEWER_REL && name === VIEWER_SKILL ? VIEWER : path.join(source, rel), to);
128
159
  }
129
160
  fs.writeFileSync(path.join(dir, MARKER), JSON.stringify({ package: PACKAGE.name, version: PACKAGE.version, commit: commit(), files: fresh }, null, 2) + '\n');
130
161
  }
131
162
 
132
- function apply(root, name, force, lines) {
163
+ // `viewer`: true adds the viewer to the copy, false takes it out, undefined keeps what the copy has (none when new).
164
+ function apply(root, name, force, lines, viewer) {
133
165
  const dir = path.join(root, name);
134
- const found = inspect(dir, name);
166
+ const carries = name === VIEWER_SKILL && (viewer === undefined ? hasViewer(dir) : viewer);
167
+ const found = inspect(dir, name, carries);
135
168
  const label = `${shorten(dir)}`;
136
169
  if (found.state === 'current' && !found.adopt) return lines.push(` ${label}: already current`);
137
170
  if (found.state === 'modified' && !force) {
@@ -140,8 +173,8 @@ function apply(root, name, force, lines) {
140
173
  }
141
174
  let kept = '';
142
175
  if (found.state === 'modified' || found.state === 'unknown') kept = `; the old copy is in ${shorten(backup(dir, name))}`;
143
- place(dir, name);
144
- lines.push(` ${label}: ${found.state === 'absent' ? 'installed' : found.adopt ? 'recorded as current' : 'updated'} to ${PACKAGE.version}${kept}`);
176
+ place(dir, name, carries);
177
+ lines.push(` ${label}: ${found.state === 'absent' ? 'installed' : found.adopt ? 'recorded as current' : 'updated'} to ${PACKAGE.version}${carries ? ', with the viewer' : ''}${kept}`);
145
178
  }
146
179
 
147
180
  const shorten = p => (p.startsWith(os.homedir() + path.sep) ? '~' + p.slice(os.homedir().length) : p);
@@ -195,7 +228,7 @@ function status(args) {
195
228
  for (const name of names) {
196
229
  const found = inspect(path.join(root, name), name);
197
230
  if (found.state !== 'current' && found.state !== 'absent') behind++;
198
- console.log(` ${name}: ${STATE_TEXT[found.state](found)}`);
231
+ console.log(` ${name}: ${STATE_TEXT[found.state](found)}${name === VIEWER_SKILL && hasViewer(path.join(root, name)) ? ', with the viewer' : ''}`);
199
232
  }
200
233
  for (const name of retiredIn(root)) {
201
234
  behind++;
@@ -212,7 +245,11 @@ function install(args) {
212
245
  if (flag(args, '--codex')) roots.push(homes()[1]);
213
246
  roots.push(...take(args, '--dir').map(d => path.resolve(d)));
214
247
  const only = take(args, '--skills').flatMap(v => v.split(',')).map(v => v.trim()).filter(Boolean);
248
+ const withViewer = flag(args, '--with-viewer');
249
+ const noViewer = flag(args, '--no-viewer');
215
250
  done(args);
251
+ if (withViewer && noViewer) throw new Problem('--with-viewer and --no-viewer cannot be used together');
252
+ const viewer = withViewer ? true : noViewer ? false : undefined;
216
253
  if (!roots.length) throw new Problem('say where to install: --claude, --codex or --dir DIR');
217
254
  const names = skillNames();
218
255
  const unknown = only.filter(n => !names.includes(n));
@@ -220,7 +257,7 @@ function install(args) {
220
257
  let ok = true;
221
258
  for (const root of roots) {
222
259
  const lines = [];
223
- for (const name of only.length ? only : names) if (apply(root, name, force, lines) === false) ok = false;
260
+ for (const name of only.length ? only : names) if (apply(root, name, force, lines, viewer) === false) ok = false;
224
261
  console.log(lines.join('\n'));
225
262
  }
226
263
  return ok ? 0 : 1;
@@ -250,6 +287,82 @@ function update(args) {
250
287
  return ok ? 0 : 1;
251
288
  }
252
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
+
253
366
  function python(script, command, args) {
254
367
  if (!args.includes('--repo')) args.push('--repo', '.');
255
368
  if (command === 'serve') {
@@ -270,6 +383,7 @@ function main(argv) {
270
383
  if (command === 'status') return status(args) || 0;
271
384
  if (command === 'install') return install(args);
272
385
  if (command === 'update') return update(args);
386
+ if (command === 'instructions') return instructions(args);
273
387
  if (KNOWLEDGE.has(command)) return python('knowledge.py', command, args);
274
388
  if (MAINTAIN.has(command)) return python('maintain.py', command, args);
275
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.9.2",
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",
@@ -28,6 +28,7 @@
28
28
  "files": [
29
29
  "bin",
30
30
  "skills",
31
+ "viewer",
31
32
  "!**/__pycache__",
32
33
  "!**/*.pyc",
33
34
  "LICENSE",
@@ -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. It never changes application code; use spec-change for that.
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"` and `recheck: "not-checked"`. The pass that found a gap is not its recheck.
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
- - **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` ([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
+ - **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, an automatic commit or a mandatory task-end rule in the repository's instruction files; those are separate requests the user must make through their host. Teammates receive changes through the normal Git workflow.
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 with several parts (screens, tabs, steps) gets a note per part, plus one note that ties them together only when the parts share a flow worth describing. 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.
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 rule is written (the schema, the service, the component), usually one to five. A page that needs many more to back its rules 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.
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.
@@ -151,7 +167,7 @@ python3 "$SKILL_DIR/scripts/knowledge.py" snapshot --repo "$REPO" --vault "$VAUL
151
167
 
152
168
  `check` validates structure and freshness; it cannot judge prose or coverage. `coverage.py` lists what the code has that no page mentions ([When a feature is finished](#when-a-feature-is-finished)). `--strict` turns freshness warnings into a failing exit status, for CI. In a working tree shared with someone else's uncommitted work, `--strict --ignore-dirty` still prints warnings for sources with uncommitted changes but does not fail on them when the accepted fingerprint equals the file at `HEAD` (the only drift is uncommitted); committed drift still fails, and it is not for CI ([details](references/format.md)). `serve` shows the vault in a browser and writes nothing. `snapshot` accepts source fingerprints as reviewed; run it only for pages you actually re-read against their sources, never to clear a warning. An initial reviewed pass may use `--all`.
153
169
 
154
- To read the result, run `python3 <skill>/scripts/knowledge.py serve --repo <repository> --open` (add `--vault` when the repository has several vaults under `knowledge/`), or open the folder as an Obsidian vault. The command is long, so when you hand over offer to give it a short name in the project: a `spec` script in `package.json` (`project-spec serve` when the project has the `project-spec-skills` package, otherwise the full command), a `spec` target in a `Makefile`, or a shell alias. That file is outside the vault, so add it only when the person agrees. The viewer is one page on `127.0.0.1`; it reads the vault and the files the pages cite from disk on every page load, so it needs no build and shows the current state after a reload. It shows a note as written, under its title and summary, with the source files folded away at the end; an area page shows its notes with their summaries. So the first paragraph and the summary are what most readers see. Its **Copy for AI** turns a page and the reader's own words into a request for an agent that names the page file. It only copies text, so an agent that receives one still follows the skill it names, and a recheck or decision the reader states there is recorded under the reader's name, never as the agent's. If the vault has errors the page lists them instead. When the person wants the spec on a server for people without the repository, `knowledge.py build --repo <repository> --out <file outside the vault>` writes that same viewer as one file ([options](references/format.md)); run it only when asked, never commit the file into the vault, and leave `--with-sources` out unless the person says everyone who can open the page may read the code.
170
+ To read the result, run `npx project-spec serve` in the repository (add `--vault` when it has several vaults under `knowledge/`), or open the folder as an Obsidian vault. The viewer is not part of this skill, which holds only what writing a spec needs: it comes with the `project-spec` npm package. Where this copy of the skill has `assets/viewer.html`, or sits in a clone of the skills repository, `python3 <skill>/scripts/knowledge.py serve --repo <repository> --open` shows the same page without Node; without the viewer that command says so and names the other ways. When you hand over, offer to give the command a short name in the project: a `spec` script in `package.json` (`project-spec serve`), a `spec` target in a `Makefile`, or a shell alias. That file is outside the vault, so add it only when the person agrees. The viewer is one page on `127.0.0.1`; it reads the vault and the files the pages cite from disk on every page load, so it needs no build and shows the current state after a reload. It shows a note as written, under its title and summary, with the source files folded away at the end; an area page shows its notes with their summaries. So the first paragraph and the summary are what most readers see. Its **Copy for AI** turns a page and the reader's own words into a request for an agent that names the page file. It only copies text, so an agent that receives one still follows the skill it names, and a recheck or decision the reader states there is recorded under the reader's name, never as the agent's. If the vault has errors the page lists them instead. When the person wants the spec on a server for people without the repository, `npx project-spec build --out <file outside the vault>` (or `knowledge.py build` in a copy that has the viewer) writes that same viewer as one file ([options](references/format.md)); run it only when asked, never commit the file into the vault, and leave `--with-sources` out unless the person says everyone who can open the page may read the code.
155
171
 
156
172
  Before handing over, read what you wrote as the person who will use it, not as its author. Open one area page and two of the notes you wrote or changed, and ask:
157
173
 
@@ -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
 
@@ -250,7 +250,9 @@ Canonical Markdown must not contain raw merge conflicts. Validation rejects comp
250
250
 
251
251
  `build` writes the same viewer as one file, for a server that shows the spec to people who do not have the repository: `knowledge.py build --repo REPO [--vault VAULT] --out FILE [--source-url URL] [--with-sources]`. `--out` must be a file outside the vault. The command stops with the `check` errors when the vault has any, and writes nothing then; freshness warnings do not stop it. The page data is the graph plus `built: true`, `commit` (the full `HEAD`, empty outside Git), `sourceUrl`, `vaultPath`, `history`, `pending` and `files`. `files` is empty unless `--with-sources` is given, because the text of cited files is source code. `--source-url` must be an `http(s)` address; `{commit}` in it is replaced by `HEAD`, and it is an error to name `{commit}` outside a Git work tree. `--allow-missing-sources` is for a build that sees only part of the repository (a Docker build context): a cited path where nothing exists is not an error and does not mark its page as changed, and the command lists those files; `check` and `snapshot` never accept it. On a built page a cited file whose text is not included is a link to `sourceUrl/<repository path>` (with `#L10-L20` when lines are named) in a new tab, or plain text when there is no `sourceUrl`; it is never a relative link, which would lead into the site that hosts the page. In a shallow clone the commit whose parents were not fetched is left out of `history` (by `serve` too), since Git would show every page as added there, and `build` says that the history is short.
252
252
 
253
- `assets/viewer.html` has exactly one `__KNOWLEDGE_DATA__` placeholder for script-safe JSON. Treat contents as untrusted text: no raw Markdown HTML execution, unsafe URL schemes, external scripts, fonts, analytics or fetches. Render readable basic Markdown, pipe tables and wikilinks; leave unsupported syntax as text. The viewer has a tree of areas with their notes (a note is listed under its first area; superseded notes are not listed), a search over pages, gaps and the cited files, and five places: the overview, a page, the gap queue, the map and recent changes. A note shows its title, `summary`, the page text and the gaps about it that are not closed, then its source files folded; an area shows its notes with their summaries and folds its own text. The pages linked to or from the page are a short list beside it. Navigation keeps a trail for Back and Forward and writes the place into the address (`#/page/notes/example`, `#/gaps`), so a reload or a copied link returns to it. The map draws one frame per primary area (the area page, or the first entry of `areas`) with its pages inside; an edge between a page and its primary area is not drawn because the frame says it, links inside one area are solid and links across areas dashed; `nav` pages are not drawn. Recent changes reads `history`, `pending` and the "changed source" lines of `warnings`. "Copy for AI" only composes text from the page, a choice of what the agent should do and the reader's own words, and copies it to the clipboard. The reader's name, the recently viewed pages and the last commit seen are kept in the browser's `localStorage`, and the viewer works without it.
253
+ `serve` and `build` need the viewer page, which is not part of the skill folder. They look for `assets/viewer.html` in this copy of the skill (`project-spec install --with-viewer` puts it there), then for `viewer/viewer.html` in the package or clone the skill sits in, and stop with a message naming `npx project-spec serve` when there is neither; every other command works without it. `--viewer FILE` shows the vault with a page of your own instead: any HTML file with the placeholder once, which receives the data described above.
254
+
255
+ The viewer page has exactly one `__KNOWLEDGE_DATA__` placeholder for script-safe JSON. Treat contents as untrusted text: no raw Markdown HTML execution, unsafe URL schemes, external scripts, fonts, analytics or fetches. Render readable basic Markdown, pipe tables and wikilinks; leave unsupported syntax as text. The viewer has a tree of areas with their notes (a note is listed under its first area; superseded notes are not listed), a search over pages, gaps and the cited files, and five places: the overview, a page, the gap queue, the map and recent changes. A note shows its title, `summary`, the page text and the gaps about it that are not closed, then its source files folded; an area shows its notes with their summaries and folds its own text. The pages linked to or from the page are a short list beside it. Navigation keeps a trail for Back and Forward and writes the place into the address (`#/page/notes/example`, `#/gaps`), so a reload or a copied link returns to it. The map draws one frame per primary area (the area page, or the first entry of `areas`) with its pages inside; an edge between a page and its primary area is not drawn because the frame says it, links inside one area are solid and links across areas dashed; `nav` pages are not drawn. Recent changes reads `history`, `pending` and the "changed source" lines of `warnings`. "Copy for AI" only composes text from the page, a choice of what the agent should do and the reader's own words, and copies it to the clipboard. The reader's name, the recently viewed pages and the last commit seen are kept in the browser's `localStorage`, and the viewer works without it.
254
256
 
255
257
  ## Format references
256
258
 
@@ -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
- | `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. |
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 |
@@ -94,6 +95,10 @@ Never guess a decision from silence, from a plan existing, or from a task being
94
95
 
95
96
  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
 
98
+ 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.
99
+
100
+ 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.
101
+
97
102
  ## Derived state
98
103
 
99
104
  Computed by the helper, never written into Markdown: