project-spec 0.8.0 → 0.9.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
@@ -1,156 +1,45 @@
1
1
  # Project Spec Skills
2
2
 
3
- **Turn a repository into knowledge you can navigate, question, and maintain.**
3
+ **Turn a repository into a spec people can read: one page per feature, every business rule numbered.**
4
4
 
5
- Two agent skills: one to understand existing software and keep that understanding true, one to change it starting from the spec. Start with the code you already have. Keep explanations in English Markdown with links to the evidence.
5
+ Agent skills for the moment after you built fast with AI and now need to know what the product really does. The agent reads the code you already have and writes down how it works. You read the result in a local viewer, question it, and change the product starting from it.
6
6
 
7
- The knowledge skill produces an **Obsidian-compatible vault** with two clearly separated layers:
8
-
9
- - an **as-built spec**: exactly how the code is implemented now, derived only from source. Each feature has one page: what it is for, how it works, its fields and its business rules, every rule with a number you can quote. What people or agents agreed in chats is not part of it.
10
- - a **gap queue**: the agent's guesses about what is missing, doubtful or worth adding, one question per page. People re-check each gap and decide it, with a separate discussion and decision for every item.
11
-
12
- To read it there is a small **local viewer**: one command opens the spec as a plain document in your browser, straight from the files on disk, and turns what you read into a request for your agent. [See how it works](#read-the-spec-then-work-from-it). Obsidian works too and is optional. The other skills work with ordinary repository files, with or without a vault.
7
+ This is an early project. It has been used on a few real repositories; [VALIDATION.md](VALIDATION.md) says what was checked and what was not.
13
8
 
14
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)
15
10
 
16
- ## Pick a skill
17
-
18
- | For | Skill | What you get |
19
- | --- | --- | --- |
20
- | Understand | [project-knowledge](skills/project-knowledge/SKILL.md) | An as-built spec of capabilities and behavior and a separate queue of individually tracked gaps. It also audits written requirements against the code, answers one question or re-checks one gap, keeps the spec in step with Git history and reconciles concurrent vault updates. It never changes application code. |
21
- | Change (experimental) | [spec-change](skills/spec-change/SKILL.md) | A source-grounded plan with decision gates and observable acceptance criteria, or the change itself: you edit the spec on a branch, the agent reviews the diff and asks its questions before any code, then implements it and checks each changed statement against the code. |
22
-
23
- Each skill is independently usable. A useful sequence is:
24
-
25
- ```mermaid
26
- flowchart LR
27
- A[Map the project] --> B[Read it in the viewer]
28
- B --> C[Audit a spec or re-check a gap]
29
- C --> D[A person decides, then plan]
30
- B --> E[Edit the spec: spec-change]
31
- D --> F[Implement and verify]
32
- E --> F
33
- F --> A
34
- ```
35
-
36
- `project-knowledge` never changes application code; `spec-change` is the one that does, and only after it has asked its questions. Reading a test establishes what it expects; only running it produces a test result.
37
-
38
- ## Read the spec, then work from it
39
-
40
- The vault is plain Markdown: easy for an agent to write, tiring for a person to read file by file. The viewer is the reading side. It is one local page that reads the vault from disk every time it loads, so there is nothing to build first.
41
-
42
- It is made for one loop:
43
-
44
- 1. **Read.** A tree lists the areas and the features in each. A feature page says in plain words what the feature is for and how it works, then lists its fields and its numbered business rules; the source files and the properties are folded away. A breadcrumb, Back and Forward and a "You are here" card say where you are, and the related pages are listed beside the text.
45
- 2. **Find.** Search (Cmd/Ctrl+K) covers pages, gaps and the text of the files the pages cite. A rule number such as `BR-CANCEL-02` finds its page.
46
- 3. **Ask.** "Copy for AI" on any page turns the page and your own words into a request for your agent that names the page file. For a gap: recheck it, record a check you did yourself, record your decision, lay out the options, plan it. For any page: change the behavior, ask a question, or remove a page that is only noise. Each choice says what will happen, and you see the exact text before you copy it.
47
- 4. **Let the agent work.** Paste the brief into your agent. With `spec-change` it asks its questions first, edits the spec on a branch, builds the change and checks every changed statement against the code.
48
- 5. **See what moved.** Recent changes lists the pages whose cited sources changed since the last review, the pages not committed yet, and the vault's Git history with what each summary said before and after.
49
-
50
- | Search | Copy for AI |
51
- | --- | --- |
52
- | ![Search results grouped into features, gaps and files](docs/images/viewer-search.png) | ![The Copy for AI dialog with the exact text that will be copied](docs/images/viewer-copy.png) |
53
- | **Recent changes** | **Gap queue** |
54
- | ![The vault's Git history, one line per commit](docs/images/viewer-changes.png) | ![The gap queue filtered by state, kind and area](docs/images/viewer-gaps.png) |
55
-
56
- ![The map of pages, one frame per area](docs/images/viewer-map.png)
11
+ ## Start
57
12
 
58
- The screenshots show the fictional [Parcel Desk](examples/parcel-desk/README.md) example. The viewer only reads: it listens on `127.0.0.1`, makes no network requests and writes nothing to the repository. "Copy for AI" puts text on your clipboard; the only thing it keeps in your browser is the name you sign a check or a decision with. A link to a file in the repository opens inside the viewer, Markdown rendered and code with the cited lines marked.
59
-
60
- ### Open it with one command
61
-
62
- With the [package](#with-npm) installed in your project, add a script to `package.json`:
63
-
64
- ```json
65
- {
66
- "scripts": {
67
- "spec": "project-spec serve"
68
- }
69
- }
70
- ```
71
-
72
- `npm run spec` then opens the viewer for that project. Without the package, the command is the helper itself, where `<skill>` is the `project-knowledge` folder (`~/.claude/skills/project-knowledge`, `~/.codex/skills/project-knowledge`, or a copy kept inside the repository):
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.
73
14
 
74
15
  ```sh
75
- python3 <skill>/scripts/knowledge.py serve --repo . --open
16
+ npx project-spec install --claude # or --codex
76
17
  ```
77
18
 
78
- Give that a short name once, as a `Makefile` target (the second line starts with a tab) or a shell alias:
79
-
80
- ```make
81
- spec:
82
- python3 <skill>/scripts/knowledge.py serve --repo . --open
83
- ```
19
+ Ask your agent:
84
20
 
85
- ```sh
86
- alias spec='python3 ~/.claude/skills/project-knowledge/scripts/knowledge.py serve --open --repo'
21
+ ```text
22
+ 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.
87
25
  ```
88
26
 
89
- The vault is found by itself when the repository has one under `knowledge/`; otherwise add `--vault PATH`. The page is served on port 8757, or another free port when that one is taken; `--port N` picks one. `project-spec serve` opens the browser unless you add `--no-open`; the helper opens it only with `--open`. If the vault has errors, the page lists them.
90
-
91
- ### Show it on a server
92
-
93
- `serve` is for your own machine. To let the rest of the team read the spec on a development or staging server, write the viewer as one file and let your application return it:
27
+ Then read what it wrote:
94
28
 
95
29
  ```sh
96
- project-spec build --out build/spec.html \
97
- --source-url 'https://github.com/OWNER/REPO/blob/{commit}'
30
+ npx project-spec serve
98
31
  ```
99
32
 
100
- Without the package the command is `python3 <skill>/scripts/knowledge.py build --repo . --out build/spec.html`. The file is the whole viewer: the pages, the search, the map, the gap queue and the history, with no other files and no network requests. It is a copy of the vault at the moment of the build, so build it again on every deploy.
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).
101
34
 
102
- | Option | What it does |
103
- | --- | --- |
104
- | `--out FILE` | Where to write the page. It must be outside the vault: nothing is generated into the vault. |
105
- | `--source-url URL` | Where a cited file can be read. The file's path in the repository is added to this address, and `{commit}` becomes the commit the page was built from. Without it, cited files are shown as names. |
106
- | `--with-sources` | Put the text of the cited files into the page, as `serve` does, so they open inside the viewer. Leave it out when people who may not read the repository can open the page. |
107
-
108
- The spec describes how the product works inside, and with `--with-sources` it carries source code. So treat the file like the repository:
109
-
110
- - Keep it out of folders the web server publishes by itself (`public/`, `static/`). Return it from a route that checks who is asking.
111
- - Build it only for the environments that should have it, and make the route answer 404 everywhere else.
112
- - If your application sets a `Content-Security-Policy`, the page needs inline scripts and styles and nothing else.
113
-
114
- For example, a route in a Next.js application (a sketch: put your own sign-in check where `signedIn()` is):
115
-
116
- ```ts
117
- // src/app/development/spec/route.ts
118
- import { readFile } from "node:fs/promises";
119
- import path from "node:path";
120
-
121
- export const dynamic = "force-dynamic";
122
-
123
- export async function GET() {
124
- if (process.env.SPEC_PAGE !== "on" || !(await signedIn())) {
125
- return new Response("Not found", { status: 404 });
126
- }
127
- const page = await readFile(path.join(process.cwd(), "build/spec.html"));
128
- return new Response(page, {
129
- headers: {
130
- "Content-Type": "text/html; charset=utf-8",
131
- "Cache-Control": "no-store",
132
- "X-Robots-Tag": "noindex",
133
- "Content-Security-Policy":
134
- "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'",
135
- },
136
- });
137
- }
138
- ```
35
+ ## What you get
139
36
 
140
- The build needs Python and Git, so run it where the application is built (a CI job or a build stage), not inside a running container that has neither. The **Recent changes** page comes from the Git history: in a shallow clone it starts at the first commit that was fetched in full, and the command says so. In GitHub Actions, `fetch-depth: 0` on the checkout step gives it the whole history.
37
+ A folder of plain Markdown in your repository (it also opens in Obsidian) with two layers that stay apart:
141
38
 
142
- ## What a feature page says
39
+ - **The as-built spec.** How the code works now, taken only from the source. Each feature has one page: what it is for, how it works, its fields and its numbered rules. What people agreed in chats is not part of it.
40
+ - **The gap queue.** The agent's questions about what is missing, doubtful or worth adding, one per page. People re-check each one and decide it. The agent never records a decision nobody made.
143
41
 
144
- Every feature, screen or flow has one page, and all of them have the same sections in the same order. A section the feature does not have is left out.
145
-
146
- | Section | What it holds |
147
- | --- | --- |
148
- | Opening | What the feature is for, who uses it and where it is found. |
149
- | `How it works` | What happens, step by step, in the product's words. |
150
- | `Fields` | One row per input: whether it is required, its rule, the message when it is refused. |
151
- | `Business rules` | One numbered row per rule, with the values from the code. |
152
-
153
- This is the page in the screenshot above, as the agent wrote it:
42
+ A page looks like this:
154
43
 
155
44
  ```markdown
156
45
  # Only requested pickups are currently cancellable
@@ -158,11 +47,6 @@ This is the page in the screenshot above, as the agent wrote it:
158
47
  A customer who no longer needs a pickup cancels it, and the service lets that
159
48
  happen only before anyone has started work on it.
160
49
 
161
- ## How it works
162
-
163
- `cancel_pickup` in the service first runs the ownership check, then looks at the
164
- pickup's state. A pickup that passes both is set to `cancelled` and returned.
165
-
166
50
  ## Business rules
167
51
 
168
52
  | ID | Rule |
@@ -171,206 +55,59 @@ pickup's state. A pickup that passes both is set to `cancelled` and returned.
171
55
  | BR-CANCEL-02 | In any other state the cancellation is refused with "Only requested pickups can be cancelled" and nothing is changed. |
172
56
  ```
173
57
 
174
- A rule's number is its name. It stays the same when the rule's text changes, a new rule gets the next free number, and a removed rule's number is never used again, so a number quoted in a ticket, a test or a chat keeps pointing at one rule. `check` fails when a number appears twice in the vault.
175
-
176
- Things the code registers in one place and no single feature owns (background jobs, emails, routes, roles, plan limits) are listed in reference pages: one table with every item. A page cites the one to five files that decide its behavior. When one of them changes, the page is marked "Code changed since the last check" until someone re-reads it.
177
-
178
- ## Why use this?
179
-
180
- - **Onboarding:** follow a workflow across UI, API, policy, persistence and tests without rediscovering the same paths every session.
181
- - **Change planning:** see which rules and related areas a change can affect before writing code.
182
- - **Rules you can point at:** a reviewer, a tester or a support person can say "BR-CANCEL-02 is wrong" instead of describing a screen.
183
- - **Useful gap reports:** each doubt is its own page, typed as a missing capability, outdated documentation, an unverified scenario, a conflict or an undecided product proposal, and carries who re-checked it and who decided it.
184
- - **Team memory:** commit the notes with the project. A manual sync reviews changes from all contributors since the last reviewed commit, including older commits and merges.
185
-
186
- The graph records relationships between explanations. It does not infer a complete runtime dependency graph or prove that the deployed application works. The agent never records a decision nobody made: accepting, rejecting or deferring a gap is a person's act.
187
-
188
- ## Install and run
189
-
190
- These are [Agent Skills](https://agentskills.io/specification): each folder has a `SKILL.md` entry point. They require an agent that can read your repository. The knowledge helpers need **Python 3.10+** and **Git**; they have no package dependencies. No MCP server, cloud service, paid API or Obsidian plugin is required by the bundle.
191
-
192
- ### With npm
193
-
194
- The package is [`project-spec`](https://www.npmjs.com/package/project-spec) on the npm registry, with one command of the same name. It needs Node 18+ in addition to Python. Nothing has to be installed first:
195
-
196
- ```sh
197
- npx project-spec install --claude # or --codex, or --dir knowledge/tooling
198
- npx project-spec serve # the viewer for the project in the current folder
199
- npx project-spec build --out FILE # the same viewer as one file, to show on a server
200
- ```
201
-
202
- Then ask your agent to use the `project-knowledge` skill ([example prompts](#example-prompts)).
203
-
204
- To pin one version for everyone on a project, add it as a development dependency:
205
-
206
- ```sh
207
- npm install --save-dev project-spec
208
- ```
209
-
210
- The lockfile then pins the version, and `npm update project-spec` moves it forward. The command keeps every copy of the skills in step with that version:
211
-
212
- ```sh
213
- npx project-spec status # where the copies are and whether each is current
214
- npx project-spec update # refresh every copy that status lists
215
- ```
216
-
217
- `status` and `update` look in `~/.claude/skills`, `~/.codex/skills` and the usual folders of the current project (`knowledge/tooling`, `.claude/skills`, `.codex/skills`, `.agents/skills`). `update` refreshes what is there and adds nothing new; `install` adds. A copy you edited by hand is not replaced unless you pass `--force`, and the old files are kept under `~/.project-spec/backups` first. `--skills project-knowledge` limits an install to the skills you name.
58
+ A rule keeps its number for good, so a reviewer, a tester or a support person can say "BR-CANCEL-02 is wrong" instead of describing a screen. When a file a page relies on changes, the page is marked for re-reading.
218
59
 
219
- To run the unreleased version from this repository, use `npx github:WorldStoryCm/project-spec-skills status` in place of `npx project-spec status`.
60
+ ## The viewer
220
61
 
221
- ### Claude Code plugin
62
+ One local page, read from the files on disk. Nothing is built or uploaded.
222
63
 
223
- The repository is also a plugin marketplace for Claude Code. Inside Claude Code:
64
+ 1. **Read** a feature page: its purpose, its flow, its rules.
65
+ 2. **Find** anything with search, including a rule number.
66
+ 3. **Ask**: "Copy for AI" turns the page and your own words into a request for your agent.
67
+ 4. **See what moved**: the pages whose code changed since they were last checked.
224
68
 
225
- ```text
226
- /plugin marketplace add WorldStoryCm/project-spec-skills
227
- /plugin install project-spec@project-spec-skills
228
- ```
229
-
230
- The two skills then appear as `/project-spec:project-knowledge` and `/project-spec:spec-change`, and Claude Code updates them with the plugin. The plugin does not add the `project-spec` command; ask the agent to open the viewer, or use `npx project-spec serve`.
231
-
232
- ### Codex
233
-
234
- Ask the built-in skill installer:
235
-
236
- ```text
237
- Install these skills from WorldStoryCm/project-spec-skills:
238
- skills/project-knowledge
239
- skills/spec-change
240
- ```
241
-
242
- If you already have a skill with the same name, compare versions before replacing it. The installer in Codex handles its own destination. In Codex you can name a skill with `$name`, for example `$spec-change`.
243
-
244
- ### Claude Code, by hand
245
-
246
- Copy the whole skill folder (it contains the references and helper scripts) to one of:
247
-
248
- - `~/.claude/skills/<name>/` to use it in all your projects, or
249
- - `.claude/skills/<name>/` inside one project.
250
-
251
- ```sh
252
- git clone https://github.com/WorldStoryCm/project-spec-skills.git
253
- mkdir -p ~/.claude/skills
254
- cp -R project-spec-skills/skills/project-knowledge ~/.claude/skills/
255
- cp -R project-spec-skills/skills/spec-change ~/.claude/skills/
256
- ```
257
-
258
- Then ask in plain language, or invoke a skill by name with `/<name>`, for example `/spec-change`. Claude Code finds a skill from its description, so an ordinary request often picks the right one.
259
-
260
- ### Example prompts
261
-
262
- These work in any host; use `$name` or `/name` where your host supports it, or just say which skill you mean.
263
-
264
- ```text
265
- Use the project-knowledge skill to build an English knowledge vault for this repository.
266
- Describe only what the code does: one page per feature with its business rules,
267
- each claim linked to source, and every doubt as its own gap.
268
- ```
269
-
270
- ```text
271
- Use the project-knowledge skill to audit docs/checkout.md against the checkout implementation.
272
- Prioritize real mismatches; record each as a separate open gap.
273
- ```
274
-
275
- ```text
276
- Use the project-knowledge skill to re-check the gap "cancelled order still reserves stock".
277
- Read the call path and relevant tests, write the result into the gap's Recheck
278
- section, and leave the decision to me.
279
- ```
280
-
281
- ```text
282
- Use the spec-change skill to plan the accepted gap "reservation-release".
283
- Include affected modules, concurrency checks and acceptance criteria. Plan only.
284
- ```
285
-
286
- ```text
287
- Use the spec-change skill. I edited the spec on this branch; the diff against main
288
- is the change request. Ask your questions first, then implement it and show me
289
- which statement is covered by which check.
290
- ```
291
-
292
- ### Any agent with repository access
293
-
294
- Clone this repository, then ask the agent to read the chosen `skills/<name>/SKILL.md` and follow it in your target project. Keep that skill's directory intact so its references and scripts resolve. Use your host's documented installation mechanism if it supports skills. Hosts other than Codex and Claude Code have not been integration-tested, and the format change described in [VALIDATION.md](VALIDATION.md) has not yet been tested with an agent on any host.
69
+ | Search | Copy for AI |
70
+ | --- | --- |
71
+ | ![Search results grouped into features, gaps and files](docs/images/viewer-search.png) | ![The Copy for AI dialog with the exact text that will be copied](docs/images/viewer-copy.png) |
72
+ | **Recent changes** | **Gap queue** |
73
+ | ![The vault's Git history, one line per commit](docs/images/viewer-changes.png) | ![The gap queue filtered by state, kind and area, the most urgent first](docs/images/viewer-gaps.png) |
295
74
 
296
- ## Try the example first
75
+ [The viewer](docs/viewer.md) describes every screen, and how to show the spec on a development server for the rest of the team.
297
76
 
298
- [Parcel Desk](examples/parcel-desk/README.md) is a small, fictional pickup service with a real spec/code disagreement and a ready-made knowledge vault. The vault shows three gaps at different points of the lifecycle (needs recheck, needs decision, accepted with a plan). It includes example audit, investigation and plan outputs.
77
+ ## The two skills
299
78
 
300
- ```sh
301
- git clone https://github.com/WorldStoryCm/project-spec-skills.git
302
- cd project-spec-skills
303
- python3 scripts/verify.py
304
- ```
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. |
305
83
 
306
- Start the viewer on the example:
84
+ ## Commands
307
85
 
308
86
  ```sh
309
- python3 skills/project-knowledge/scripts/knowledge.py serve --repo examples/parcel-desk --open
310
- ```
311
-
312
- Search for **cancellation**, open a gap, follow its links and try "Copy for AI" on it. [Read the spec, then work from it](#read-the-spec-then-work-from-it) describes every screen.
313
-
314
- To use Obsidian, choose **Open folder as vault** and select `examples/parcel-desk/knowledge/parcel-desk`. Open `00-index`, then **Graph view: Open graph view** from the command palette (Cmd/Ctrl+G). In graph settings, **Existing files only** hides unresolved source links outside the vault. Pages cluster around their area because each page links to it; run pages carry no links, so they do not pull the clusters together. To see the spec alone, put `-path:gaps -path:plans -path:runs` in the graph's search filter, and add a color group per folder (`path:areas`, `path:notes`, `path:gaps`) under **Groups**. **Open local graph** shows only the neighbours of the page you are reading. Gap properties are searchable, for example `[decision:open]` or `[kind:verification-gap]`. See [Obsidian's graph guide](https://help.obsidian.md/plugins/graph).
315
-
316
- Source links point outside the vault into the repository. Some hosts do not open these paths; the note's `sources` property gives the repository-relative path for your editor. All example application data is invented.
317
-
318
- ## Keep knowledge current
319
-
320
- ```text
321
- Use the project-knowledge skill to sync: review all integrated changes since the last
322
- reviewed checkpoint, update the affected spec notes, and revisit gaps whose
323
- sources changed.
324
- ```
325
-
326
- Or narrow the work:
327
-
328
- ```text
329
- Ask project-knowledge to explore permissions and deepen the access-control notes.
330
- Ask project-knowledge to work the gaps: re-verify open ones against the current code
331
- and list which are waiting for my decision.
332
- Ask project-knowledge to check links and source freshness.
333
- ```
334
-
335
- The agent researches and writes the claims. The Python helpers validate structure, track source fingerprints and render views; running a helper alone does not understand your code. A scan identifies candidate changes, and fingerprints are accepted and the Git checkpoint advanced only after review. See the [sync workflow](skills/project-knowledge/references/sync.md). If part of the range cannot be accepted yet, for example because another contributor has uncommitted edits to a file, mark it `deferred`: the rest is accepted, the checkpoint stays where it is and the helper exits with status 3 (not 0, and not 2, which is a usage error).
336
-
337
- If `check` fails on a vault written before the spec/gap split, follow the [migration guide](skills/project-knowledge/references/migrate.md). The same guide has the regroup pass for a vault whose feature pages lack the sections above, or whose rules were spread over separate table pages per kind.
338
-
339
- Everything is manual and nothing is published: the bundle installs no schedule or hooks, and does not commit, push or synchronize other clones. Share the Markdown, reviewed state and chosen skill version through your normal Git workflow. Personal Obsidian settings and local scan reports should stay ignored.
340
-
341
- ### Gaps are decided by people
342
-
343
- A gap starts open. Anyone can re-check it (ask `project-knowledge` to recheck it) and the result is written into the gap with who did it and when. Then a person accepts, rejects or defers it, or the agent finds the code already closes it and marks it done. Only an accepted gap gets a plan. Each gap page has its own `Discussion` and `Decision` sections, and the viewer lists the queue by state. A recheck means the same thing for every kind of gap, proposals included: it asks only whether the page's description of current behavior still holds in the code ("confirmed (still holds)" or "not reproduced (no longer holds)"), never whether the proposal is a good idea. Details are in [gaps.md](skills/project-knowledge/references/gaps.md).
344
-
345
- ### When two people update the vault
346
-
347
- ```text
348
- Use the project-knowledge skill to merge our knowledge updates from main
349
- and teammate/knowledge. Preserve both contributors' useful pages and stable IDs,
350
- check overlapping claims against source, and report unresolved conflicts.
351
- ```
352
-
353
- The agent compares the common base and both versions, combines supported changes, and retains unresolved claims with their provenance. If two people recorded different decisions on the same gap, it reopens that gap, keeps both positions in its discussion and reports it. A read-only inspector finds changed paths, overlaps and ID collisions. Reviewed fingerprints and Git checkpoints need explicit reconciliation; they are never made current by picking the newest JSON. Derived views are rebuilt from the resolved pages. See the [merge workflow](skills/project-knowledge/references/merge.md).
354
-
355
- Use separate branches or worktrees, or one writer per page, for concurrent work. The local finish lock protects bookkeeping, not simultaneous editing across computers. Merge is an agent workflow, not an automatic Git merge driver.
356
-
357
- ## What the files mean
358
-
359
- ```text
360
- knowledge/<project>/
361
- 00-index.md start here
362
- areas/ maps of related capabilities (spec)
363
- notes/ one page per feature, plus reference lists (spec)
364
- gaps/ one question per page (gap)
365
- plans/ one plan per accepted gap (gap)
366
- runs/ review history and evidence limits
367
- .knowledge/ sources.json (reviewed fingerprints), review.json (reviewed Git checkpoint)
87
+ npx project-spec serve # read the spec in the browser
88
+ npx project-spec coverage # what the code has that no page mentions yet
89
+ 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
368
92
  ```
369
93
 
370
- Spec pages never link to gaps; a gap links to the spec notes it is about. A gap that needs attention is a reason to look, not a defect list: it can mean unverified behavior, an unmet requirement or an undecided proposal. The [format contract](skills/project-knowledge/references/format.md) explains the page types, properties and evidence model. Helpers support this format; they are not a general Obsidian vault importer.
371
-
372
- ## Contributing and verification
94
+ ## Read more
373
95
 
374
- See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks, skill boundaries and expectations for examples. [VALIDATION.md](VALIDATION.md) records the actual release checks and limitations. Small, evidence-backed improvements are welcome, especially reproducible cases where a skill confuses intended behavior, implemented behavior and runtime evidence.
375
-
376
- The shipped skills and examples are original work, licensed under [MIT](LICENSE). This is an independent project; Obsidian and the agent hosts are not its sponsors. No third-party skill collection is bundled.
96
+ | Page | What is in it |
97
+ | --- | --- |
98
+ | [Install and update](docs/install.md) | npm, the Claude Code plugin, Codex, a manual copy, keeping copies current. |
99
+ | [The viewer](docs/viewer.md) | Every screen, a short command to open it, and the spec on a server. |
100
+ | [What the spec contains](docs/spec.md) | The sections of a feature page, big features and several apps, how deep the first map goes, the coverage report, the files in the vault. |
101
+ | [Working with the skills](docs/workflows.md) | Example prompts, the example project, keeping the spec current, deciding gaps, two people updating the vault. |
102
+ | [Parcel Desk](examples/parcel-desk/README.md) | A small fictional project with a ready-made vault to try the viewer on. |
103
+ | [VALIDATION.md](VALIDATION.md) | What was actually checked for each release, and the limits. |
104
+ | [CONTRIBUTING.md](CONTRIBUTING.md) | Checks, skill boundaries and how releases are made. |
105
+
106
+ ## What it does not do
107
+
108
+ - The agent writes the claims. The helpers check structure and track which files changed; a helper alone does not understand your code.
109
+ - The spec says what the code does. It does not prove that the deployed application works.
110
+ - Nothing runs by itself: no schedule, no hooks, no commits or pushes. You share the Markdown through your normal Git workflow.
111
+ - No MCP server, cloud service, paid API or Obsidian plugin is needed.
112
+
113
+ The skills and examples are original work under the [MIT license](LICENSE). This is an independent project; Obsidian and the agent hosts are not its sponsors.
@@ -15,6 +15,7 @@ const MARKER = '.project-spec.json'; // written into every copy: which version i
15
15
  const SKIP = new Set(['__pycache__', '.DS_Store', MARKER]);
16
16
  const KNOWLEDGE = new Set(['serve', 'build', 'check', 'snapshot']);
17
17
  const MAINTAIN = new Set(['scan', 'receipt', 'finish']);
18
+ const COVERAGE = 'coverage'; // its own helper, which takes no command word
18
19
  // Skills earlier versions shipped; project-knowledge and spec-change took over what they did.
19
20
  const RETIRED = ['spec-audit', 'spec-investigation', 'spec-plan'];
20
21
  // Folders inside a project where a copy of the skills may live.
@@ -25,10 +26,12 @@ const USAGE = `project-spec ${PACKAGE.version}
25
26
  Read the spec
26
27
  project-spec serve [--repo DIR] [--vault DIR] [--port N] [--no-open]
27
28
  Open the viewer for the repository (default: the current folder).
28
- project-spec build --out FILE [--source-url URL] [--with-sources] [--repo DIR] [--vault DIR]
29
+ project-spec build --out FILE [--source-url URL] [--with-sources] [--allow-missing-sources]
29
30
  Write the viewer as one HTML file, to show the spec on a server.
30
31
  project-spec check | snapshot [options]
31
32
  The knowledge helper; --repo defaults to the current folder.
33
+ project-spec coverage [--path FOLDER]... [--all]
34
+ What the code has that no spec page mentions yet: folders, messages and limits.
32
35
  project-spec scan | receipt | finish [options]
33
36
  The sync helper; --repo defaults to the current folder.
34
37
 
@@ -253,7 +256,7 @@ function python(script, command, args) {
253
256
  if (!flag(args, '--no-open') && !args.includes('--open')) args.push('--open');
254
257
  }
255
258
  const exe = process.env.PROJECT_SPEC_PYTHON || (process.platform === 'win32' ? 'python' : 'python3');
256
- const full = [path.join(SKILLS, 'project-knowledge', 'scripts', script), command, ...args];
259
+ const full = [path.join(SKILLS, 'project-knowledge', 'scripts', script), ...(command === COVERAGE ? [] : [command]), ...args];
257
260
  if (process.env.PROJECT_SPEC_DRY_RUN) return console.log([exe, ...full].join(' ')), 0;
258
261
  const run = spawnSync(exe, full, { stdio: 'inherit' });
259
262
  if (run.error) throw new Problem(`could not start ${exe}: ${run.error.message}. The helpers need Python 3.10 or newer; set PROJECT_SPEC_PYTHON to its path.`);
@@ -269,6 +272,7 @@ function main(argv) {
269
272
  if (command === 'update') return update(args);
270
273
  if (KNOWLEDGE.has(command)) return python('knowledge.py', command, args);
271
274
  if (MAINTAIN.has(command)) return python('maintain.py', command, args);
275
+ if (command === COVERAGE) return python('coverage.py', command, args);
272
276
  throw new Problem(`unknown command: ${command}\n\n${USAGE}`);
273
277
  }
274
278
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "project-spec",
3
- "version": "0.8.0",
3
+ "version": "0.9.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",
@@ -38,11 +38,11 @@ The full property list, section layout and example are in [gaps.md](references/g
38
38
 
39
39
  Natural-language requests are fine; these are modes, not a required CLI.
40
40
 
41
- - **map** (a new vault): discover areas, research the code, write a note for each feature with its rules, the few lists the code keeps in one place, any gaps found, and the index. A first map that only follows a few paths through each area is a draft: say so on the area pages and in the run page.
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. A pass that runs out of time says on the run page which features are finished, which are partial 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
43
  - **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
44
  - **merge**: reconcile two contributors' vault updates from their common Git base. Read [the merge workflow](references/merge.md).
45
- - **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. Then the lists the code keeps in one place, such as its background jobs. A request to "fill in", "complete" or "backfill" an area means this mode.
45
+ - **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
46
  - **gaps**: work the queue. List gaps by state; re-verify open gaps against the current code; every kind of gap is rechecked, proposals and questions about unexplained behavior included, because the recheck asks only whether the page's `Current behavior` still describes the code (`confirmed (still holds)` or `not reproduced (no longer holds)`) and never whether a proposal is worth doing, which is the person's decision. For a proposal that usually means confirming the capability is absent. Record each result in the gap's `Recheck` section with `recheck`, `rechecked_by` (`agent` for checks you ran), `rechecked_on`; set `recheck: "outdated"` on a gap whose cited source changed since its recorded recheck (keeping the other two fields); set `done` where the code now closes the question, recording that reading as a `not-reproduced` recheck by `agent` ([closing a gap as done](references/gaps.md#closing-a-gap-as-done)); mark duplicates. Then hand the `needs-decision` gaps to people with the options you found in `Discussion`. Never decide one yourself. When a person decides in the conversation, record it with their name; if you do not know their name, ask rather than writing `agent`.
47
47
  - **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
48
  - **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.
@@ -58,9 +58,23 @@ Write vault content in English unless the user asks for another language, whatev
58
58
 
59
59
  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
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.
61
- 3. Cluster capabilities and follow representative vertical paths (UI, API, policy or service, persistence, tests). A directory name establishes neither a domain boundary nor a behavior.
62
- 4. Then make each area complete where a person will look things up. A representative path shows how an area works; it does not tell anyone which jobs exist or how long a name may be. For each feature, 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. 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, not a sample.
63
- 5. Track what was read, merely discovered, excluded or changing in each area. Discovery is not review, and a note count is not completeness. For large projects finish a broad map, then deepen area by area and save a checkpoint.
61
+ 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 on the run page with each feature's size: its entry points, its folders, its lines. This list is the plan and the ledger 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
+ 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
+ 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
+ 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
+ 7. Track what was read, merely discovered, excluded or changing in each area. 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
+
67
+ ### When a feature is finished
68
+
69
+ A feature is finished when nothing is left on its list, not when its page looks complete. Run the report for its folders:
70
+
71
+ ```sh
72
+ python3 "$SKILL_DIR/scripts/coverage.py" --repo "$REPO" --vault "$VAULT" --path src/features/chat --path mobile/src/chat
73
+ ```
74
+
75
+ It prints the files there that no page cites, and each sentence a person can see and each named number (`CHAT_MAX_MEDIA = 10`) that no page mentions. Go through that list. Each item is one of three things: a rule that belongs on the page (add it, quoting the message or naming the number), something the spec leaves out on purpose (a control that only opens or closes, a label, a log line), or code you have not read (read it). Run it again until what is left is only the second kind. Without `--path` the report ranks every folder of the repository by how much it has that no page mentions, which is how you find the features nobody wrote down at all.
76
+
77
+ The report is a list of places to read, not a score, and it cannot see a rule that has no message and no named number, so it does not replace reading the entry points. A page whose feature is not finished has `status: "partial"` and ends with a line saying what is left ("Not read yet: the support chat screens, the mobile app"); `current` means the whole feature was read. Put the report's first lines for each finished feature on the run page.
64
78
 
65
79
  Delegate only when the user or repository instructions allow it; give each helper a disjoint area and integrate their evidence before accepting a claim.
66
80
 
@@ -76,13 +90,16 @@ Write for the person who asks "what does this do, and what are its rules", not f
76
90
  3. `## Fields`, when the feature has a form: a table with one row per field (`Field`, `Required`, `Rule`, `Message when refused`).
77
91
  4. `## Business rules`: a table with one numbered rule per row (`ID`, `Rule`): who may do it, when an action is available, disabled or hidden, limits and defaults, what is kept, sent or deleted, and when. One or two sentences per rule, with the value. A field's rule is in `Fields` and is not repeated here.
78
92
 
93
+ 5. `## Where the apps differ`, when the product has several clients: a table with one row per difference (`What`, then one column per client, such as `Web` and `Mobile`). Say what each client does, in a few words; "same" is not a row. When the clients were compared and nothing differs, write that one sentence instead of the table, and say which clients were compared.
94
+
79
95
  Use these headings as written and in this order, and leave out a section the feature does not have. Links to the notes it depends on go in the sentence or rule where they matter. Everything about the feature is on this page: do not move its fields, its actions or who may use them to another page, because a reader of Profile should not need four pages to learn what Profile does. A note is as long as its rules need; split a long note by feature or flow, never by kind of fact.
96
+ - **A feature with parts.** The vault has three levels and no more: an area, its features, and the parts of a feature that is too big for one page. A part is a feature note with `parent: "<id of the feature note>"`, in the same area, about one flow or one kind of use: "Group chats", "Support chats", "Sending a message". The feature's own note stays short: what the feature is for, how its parts fit together, the rules that hold in every part, and `## Parts`, a list with a link to each part and one line saying what it covers. Each rule is written once, in the part it belongs to, with the part's own rule word (`BR-GROUPCHAT-01`). The area page lists the feature, not its parts. Split when the page would pass about twenty rules or the feature has several kinds of user or flow; do not split a feature that fits one page, and never make a part of a part. `check` rejects a part whose feature does not link to it.
80
97
  - **A rule's number is its name.** Write it `BR-<FEATURE>-<NN>`, for example `BR-PROFILE-01`: a short upper-case word for the feature, the same in all rules of the note and used by no other note, then a number counting up from 01. People quote these numbers in tickets, tests and conversations, so a rule keeps its number when its text changes, a new rule gets the next free number, and the number of a rule that no longer exists is never used again. Never renumber to close a hole or to reorder. `check` rejects a number that appears twice.
81
98
  - **Write down the business rules, with their values.** The concrete rule is the content and a description of the mechanism is not enough: "a name is required and at most 60 characters, and longer input is refused with 'Name is too long'", not "the form validates the name". For every form, action and job say what is required, the limits (length, range, count, size, format, uniqueness), defaults, rounding and time zones, when an action is available, disabled or hidden ("Send is disabled while the list is empty"), what an empty list shows, what needs a confirmation, which error the person sees, and who may do it. Leave out controls that only open, close, go somewhere or try again: an action is worth a line when it changes something or has a condition. When the browser and the server check different things, write both; when they disagree, open a `conflict` gap. A note that says "validates input" or "uses a worker" without the rules it applies is not finished.
82
99
  - **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.
83
100
  - **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.
84
101
  - **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.
85
- - **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. 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.
102
+ - **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.
86
103
  - **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.
87
104
  - 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.
88
105
  - 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.
@@ -122,7 +139,7 @@ python3 "$SKILL_DIR/scripts/knowledge.py" check --repo "$REPO" --vault "$VAULT"
122
139
  python3 "$SKILL_DIR/scripts/knowledge.py" snapshot --repo "$REPO" --vault "$VAULT" --notes note-id area-id
123
140
  ```
124
141
 
125
- `check` validates structure and freshness; it cannot judge prose or coverage. `--strict` turns freshness warnings into a failing exit status, for CI. In a working tree shared with someone else's uncommitted work, `--strict --ignore-dirty` still prints warnings for sources with uncommitted changes but does not fail on them when the accepted fingerprint equals the file at `HEAD` (the only drift is uncommitted); committed drift still fails, and it is not for CI ([details](references/format.md)). `serve` shows the vault in a browser and writes nothing. `snapshot` accepts source fingerprints as reviewed; run it only for pages you actually re-read against their sources, never to clear a warning. An initial reviewed pass may use `--all`.
142
+ `check` validates structure and freshness; it cannot judge prose or coverage. `coverage.py` lists what the code has that no page mentions ([When a feature is finished](#when-a-feature-is-finished)). `--strict` turns freshness warnings into a failing exit status, for CI. In a working tree shared with someone else's uncommitted work, `--strict --ignore-dirty` still prints warnings for sources with uncommitted changes but does not fail on them when the accepted fingerprint equals the file at `HEAD` (the only drift is uncommitted); committed drift still fails, and it is not for CI ([details](references/format.md)). `serve` shows the vault in a browser and writes nothing. `snapshot` accepts source fingerprints as reviewed; run it only for pages you actually re-read against their sources, never to clear a warning. An initial reviewed pass may use `--all`.
126
143
 
127
144
  To read the result, run `python3 <skill>/scripts/knowledge.py serve --repo <repository> --open` (add `--vault` when the repository has several vaults under `knowledge/`), or open the folder as an Obsidian vault. The command is long, so when you hand over offer to give it a short name in the project: a `spec` script in `package.json` (`project-spec serve` when the project has the `project-spec-skills` package, otherwise the full command), a `spec` target in a `Makefile`, or a shell alias. That file is outside the vault, so add it only when the person agrees. The viewer is one page on `127.0.0.1`; it reads the vault and the files the pages cite from disk on every page load, so it needs no build and shows the current state after a reload. It shows a note as written, under its title and summary, with the source files folded away at the end; an area page shows its notes with their summaries. So the first paragraph and the summary are what most readers see. Its **Copy for AI** turns a page and the reader's own words into a request for an agent that names the page file. It only copies text, so an agent that receives one still follows the skill it names, and a recheck or decision the reader states there is recorded under the reader's name, never as the agent's. If the vault has errors the page lists them instead. When the person wants the spec on a server for people without the repository, `knowledge.py build --repo <repository> --out <file outside the vault>` writes that same viewer as one file ([options](references/format.md)); run it only when asked, never commit the file into the vault, and leave `--with-sources` out unless the person says everyone who can open the page may read the code.
128
145
 
@@ -131,9 +148,11 @@ Before handing over, read what you wrote as the person who will use it, not as i
131
148
  - Does the note start by saying what the feature is for and who uses it, before any rule?
132
149
  - Is each rule one numbered row a person could quote, with its value, and did every rule that was already there keep its number?
133
150
  - Could someone answer "how long may a name be", "when is this button disabled" or "which jobs run at night" from the page without opening the code? If the answer is in the code you read but not on the page, add it.
151
+ - Did `coverage --path` for the feature's folders end with only things the spec leaves out on purpose? Is every page whose feature is not finished marked `partial`, with what is left?
152
+ - Does a feature with more than about twenty rules have parts, and does a product with several clients say on each feature page where they differ?
134
153
  - Is everything about one feature on its own page, or does the reader have to collect it from several?
135
154
  - Would a person who never opens the code understand every sentence? Would the page survive a file being renamed?
136
155
  - Does the area page only map, with its missing lists named?
137
156
  - Is every doubt a gap about the product, and nothing in the queue a to-do of the vault itself?
138
157
 
139
- Then validate and, when tools allow, open the viewer. Report real counts, coverage limits, the checks you ran and how to open the result. Keep structural validation, application tests and GUI checks separate. Committing and pushing are left to the user.
158
+ Then validate and, when tools allow, open the viewer. Report real counts: how many features of the inventory are finished, partial and not started, 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.