project-spec 0.10.0 → 0.11.1

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
 
@@ -74,12 +104,28 @@ 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 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.
120
+
121
+ ## Upgrading
122
+
123
+ ```sh
124
+ npx project-spec@latest update # refresh every installed copy of the skill
125
+ npx project-spec@latest check # an older spec still passes; this lists anything to fix
126
+ ```
127
+
128
+ Your spec needs no conversion: every release since 0.7.0 only added optional things to it. Two releases changed what is installed. 0.11.0 removed the `spec-change` skill; `update` deletes its copies and keeps a backup, and a request that named it now names `project-knowledge`. 0.10.0 stopped copying the viewer into your project; open it with `npx project-spec serve`. [Upgrading from an earlier version](docs/install.md#upgrading-from-an-earlier-version) has the steps for each release.
83
129
 
84
130
  ## Commands
85
131
 
@@ -87,8 +133,9 @@ One local page, read from the files on disk. Nothing is built or uploaded. It co
87
133
  npx project-spec serve # read the spec in the browser
88
134
  npx project-spec coverage # what the code has that no page mentions yet
89
135
  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
136
+ npx project-spec instructions # the block that asks agents to keep the spec current
137
+ npx project-spec status # where the skill is installed and whether it is current
138
+ npx project-spec update # refresh the installed copies
92
139
  ```
93
140
 
94
141
  ## Read more
@@ -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 and spec-change took over what they did.
25
- 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'];
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.10.0",
3
+ "version": "0.11.1",
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. 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,30 +40,46 @@ 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, 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
 
57
59
  ## Research before writing
58
60
 
59
61
  1. Read the repository's instructions and any task coordination they require. Preserve existing edits. Record the exact revision and whether you read uncommitted files. Application source is read-only: this skill writes only inside the vault.
60
- 2. Inspect manifests, entrypoints, routes, schema and migrations, services and tests. Skip dependencies, build output, credential files, raw logs and customer data. Never use the vault itself as evidence about the application.
62
+ 2. Inspect manifests, entrypoints, routes, schema and migrations, services and tests. **Read the tests; do not run them.** The spec is read from the code, and a test file is one more thing to read: what it expects is evidence, whether it passes today is not something a spec page states. So a map, an explore, a sync or a recorded change runs nothing but this skill's helpers: no test suite, no build, no application. Running them for every feature costs time and money and adds nothing to a page. Run a check of the application only when the person asks for it, or in **investigate** and **recheck** when reading cannot settle the question, and then the smallest one that does. Skip dependencies, build output, credential files, raw logs and customer data. Never use the vault itself as evidence about the application.
61
63
  3. **Take the inventory before writing a page.** List what the product has from the places that register it, every item and not a sample: the pages or screens of every client (web, mobile, admin), the API procedures or endpoints, the jobs, the emails. Count them. Run `coverage` (below) for the size of each folder. Group the items into features and write that list into [the inventory file](#the-inventory-file) with each feature's size: its entry points, its folders, its lines. This list is the plan and the checklist of the whole map. A directory name establishes neither a feature nor a behavior, so check a group against what its entry points do.
62
64
  4. **Split a big feature before writing it.** One page holds what a person reads in one sitting: about twenty rules. A feature with more than about eight entry points, more than about 2,000 lines of its own code, or several kinds of user or flow (direct, group and support chats) will not fit, and squeezing it into one page is how fifty rules become thirteen. Give it a feature note and one note per part ("A feature with parts" under [Write the spec](#write-the-spec)).
63
65
  5. **Go deep before going wide.** Take one feature and finish it before starting the next. Read every one of its entry points on every client and follow each to the file that decides the behavior (the schema, the service, the policy, the component). Read its rules off the code: a `max(60)` in a schema, a `disabled={items.length === 0}` on a button, a `CHECK` constraint, a default value, a permission check, every `throw` and every refusal. Read the words a person sees too, the labels, the error messages and what an empty list says, and quote them. For the things the code registers in one place (the queue and cron registrations, the route table, the email templates, the roles, the flags), enumerate from that place, every item.
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,8 +125,8 @@ 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.
113
- - **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.
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.
129
+ - **What you ran goes on the run page**, not in the note: commands, PASS, FAIL or NOT RUN, the revision. For most passes that is the helpers only, and `NOT RUN` beside the application's tests is the expected entry, not a hole to fill. 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.
116
132
 
@@ -166,4 +182,4 @@ Before handing over, read what you wrote as the person who will use it, not as i
166
182
  - Does the area page only map, with its missing lists named?
167
183
  - Is every doubt a gap about the product, and nothing in the queue a to-do of the vault itself?
168
184
 
169
- Then validate and, when tools allow, open the viewer. Report real counts: how many features of the inventory file are finished, in progress and not started, what is under "Left out", the first lines of the `coverage` report for the whole repository, the checks you ran and how to open the result. Do not describe a map as full or complete while the inventory has features that are not finished. Keep structural validation, application tests and GUI checks separate. Committing and pushing are left to the user.
185
+ Then validate and, when tools allow, open the viewer. Report real counts: how many features of the inventory file are finished, in progress and not started, what is under "Left out", the first lines of the `coverage` report for the whole repository, the helper checks you ran and how to open the result. Do not describe a map as full or complete while the inventory has features that are not finished. Keep structural validation, application tests and GUI checks separate. Committing and pushing are left to the user.
@@ -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
- | `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 |
@@ -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.** 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.
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
- return graph_of(notes, edges, warnings) | {
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
 
@@ -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(1040px, 100%);
1300
- max-height: calc(100vh - 40px);
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, 1fr);
1304
- gap: 16px 28px;
1305
- overflow: auto;
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-side {
1322
- align-self: start;
1323
- position: sticky;
1324
- top: 0;
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
- @media (max-width: 820px) {
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-side {
1354
- position: static;
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
- head.append(
2883
- pills(
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
- head.append(
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
- head.append(
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 spec-change skill to plan this gap. Plan only, do not build it, and only if its decision is accepted; otherwise tell me what is missing." +
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 edits the spec on a branch, builds the change and checks it.",
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
- "Use the spec-change skill. I want to change the behavior this page describes. Ask your questions first, then edit the spec on a branch, build it and check every changed statement against the code." +
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
- want.append(
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
- const hint = el("p", intent.hint, "muted small");
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
- want.append(hint);
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
- want.append(sub);
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 controls = el("div", null, "copy-controls"),
3520
+ const list = el("div", null, "copy-menu"),
3521
+ controls = el("div", null, "copy-controls"),
3378
3522
  side = el("div", null, "copy-side");
3379
- controls.append(want, words, include);
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.