project-spec 0.11.1 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,9 +22,11 @@ npx project-spec install --claude # or --codex
22
22
 
23
23
  ```text
24
24
  Use the project-knowledge skill to build a knowledge vault for this repository.
25
+ Put it in project-spec/.
25
26
 
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.
27
+ First take the inventory: every app and package, and every way into each one:
28
+ what a person can open, what another system can call, what runs on its own and
29
+ what the product sends out. Write it to the inventory file before any page.
28
30
 
29
31
  Then go one feature at a time and finish each before the next. Describe only
30
32
  what the code does: one page per feature with numbered business rules, and
@@ -46,7 +48,7 @@ A big repository takes more than one session. To go on where the last one stoppe
46
48
  Use the project-knowledge skill and continue the map from the inventory file.
47
49
  ```
48
50
 
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).
51
+ The agent writes only Markdown in that folder. Name any other folder in the prompt (`docs/spec`, `knowledge/shop`): the commands find the spec wherever it is, and `npx project-spec move --to DIR` moves it later without breaking its links. 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
52
 
51
53
  ### What to ask next
52
54
 
@@ -134,6 +136,7 @@ npx project-spec serve # read the spec in the browser
134
136
  npx project-spec coverage # what the code has that no page mentions yet
135
137
  npx project-spec build --out FILE # the viewer as one file, to show on a server
136
138
  npx project-spec instructions # the block that asks agents to keep the spec current
139
+ npx project-spec move --to DIR # move the spec to another folder of the repository
137
140
  npx project-spec status # where the skill is installed and whether it is current
138
141
  npx project-spec update # refresh the installed copies
139
142
  ```
@@ -18,7 +18,7 @@ const VIEWER_REL = 'assets/viewer.html';
18
18
  const PACKAGE = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
19
19
  const MARKER = '.project-spec.json'; // written into every copy: which version it is and what its files looked like
20
20
  const SKIP = new Set(['__pycache__', '.DS_Store', MARKER]);
21
- const KNOWLEDGE = new Set(['serve', 'build', 'check', 'snapshot']);
21
+ const KNOWLEDGE = new Set(['serve', 'build', 'check', 'snapshot', 'move']);
22
22
  const MAINTAIN = new Set(['scan', 'receipt', 'finish']);
23
23
  const COVERAGE = 'coverage'; // its own helper, which takes no command word
24
24
  // Skills earlier versions shipped; project-knowledge took over what they did. spec-change (changing the product from
@@ -37,6 +37,8 @@ Read the spec
37
37
  Write the viewer as one HTML file, to show the spec on a server.
38
38
  project-spec check | snapshot [options]
39
39
  The knowledge helper; --repo defaults to the current folder.
40
+ project-spec move --to DIR
41
+ Move the spec to another folder of the repository; links from its pages to your files are repointed.
40
42
  project-spec coverage [--path FOLDER]... [--all]
41
43
  What the code has that no spec page mentions yet: folders, messages and limits.
42
44
  project-spec scan | receipt | finish [options]
@@ -292,17 +294,28 @@ const BLOCK_FILE = path.join(SKILLS, 'project-knowledge', 'references', 'agents.
292
294
  const BLOCK_START = '<!-- project-spec:start -->';
293
295
  const BLOCK_END = '<!-- project-spec:end -->';
294
296
 
295
- // As the helpers do: the single vault under knowledge/.
297
+ // As the helpers do: the one folder that holds 00-index.md, at most three folders deep, outside hidden folders,
298
+ // dependencies and build output.
299
+ const NOT_A_VAULT_PLACE = new Set(['node_modules', 'vendor', 'dist', 'build', 'out', 'target', 'coverage', '__pycache__', 'venv', 'Pods']);
296
300
  function findVault(repo) {
297
- const base = path.join(repo, 'knowledge');
298
301
  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));
302
+ const look = (folder, depth) => {
303
+ let entries = [];
304
+ try {
305
+ entries = fs.readdirSync(folder, { withFileTypes: true }).filter(e => e.isDirectory() && !e.name.startsWith('.') && !NOT_A_VAULT_PLACE.has(e.name));
306
+ } catch {
307
+ return;
308
+ }
309
+ for (const entry of entries.sort((x, y) => (x.name < y.name ? -1 : 1))) {
310
+ const dir = path.join(folder, entry.name);
311
+ if (fs.existsSync(path.join(dir, '00-index.md'))) found.push(dir);
312
+ else if (depth < 3) look(dir, depth + 1);
303
313
  }
314
+ };
315
+ look(repo, 1);
316
+ if (found.length !== 1) {
317
+ throw new Problem(`${found.length ? 'several vaults found (' + found.map(f => path.relative(repo, f)).join(', ') + ')' : 'no vault found: no folder with 00-index.md up to three folders deep'}; name the vault with --vault DIR`);
304
318
  }
305
- if (found.length !== 1) throw new Problem(`${found.length ? 'several vaults' : 'no vault'} found under knowledge/; name the vault with --vault DIR`);
306
319
  return found[0];
307
320
  }
308
321
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "project-spec",
3
- "version": "0.11.1",
3
+ "version": "0.12.0",
4
4
  "description": "Agent skills that read a repository and keep a spec people can read: one page per feature, every business rule numbered. Local viewer and one command to install and update the skills.",
5
5
  "keywords": [
6
6
  "agent-skills",
@@ -17,7 +17,7 @@ Read [the format contract](references/format.md) before writing pages or running
17
17
 
18
18
  - `$SKILL_DIR`: the directory containing this `SKILL.md`; the helpers are in `$SKILL_DIR/scripts/`.
19
19
  - `$REPO`: the root of the repository being documented.
20
- - `$VAULT`: its vault. Reuse an existing one; otherwise create `knowledge/<project-slug>/` inside `$REPO` and say so.
20
+ - `$VAULT`: its vault, a folder inside `$REPO`. Reuse an existing one, wherever it is. For a new one use the folder the person names; when they name none, create `project-spec/` at the root of `$REPO` (`project-spec/<product>/` when the repository holds several products that each need a spec) and say so. The helpers find the vault without being told when the repository has exactly one, up to three folders deep; otherwise pass `--vault`. To move a vault later, use `knowledge.py move --to <folder>`, which repoints the links from pages to repository files; never move the folder by hand.
21
21
 
22
22
  ## Keeping the layers apart
23
23
 
@@ -60,7 +60,7 @@ Write vault content in English unless the user asks for another language, whatev
60
60
 
61
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.
62
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.
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.
63
+ 3. **Take the inventory before writing a page.** List every way into the product from the places that register them, every item and not a sample. There are four kinds, and what they are called depends on the product: what a person can open (the pages or screens of every client: web, mobile, admin; the commands of a command-line tool), what another system can call (API procedures, endpoints, webhooks, the public functions of a library), what runs on its own (jobs, schedules, queue consumers, triggers) and what the product sends out (emails, notifications, exports, calls to other services). These names are examples, not the list: if this product has a kind of its own (a bot command, a report, a device message), it belongs in the inventory too. 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.
64
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)).
65
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.
66
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.
@@ -167,7 +167,7 @@ python3 "$SKILL_DIR/scripts/knowledge.py" snapshot --repo "$REPO" --vault "$VAUL
167
167
 
168
168
  `check` validates structure and freshness; it cannot judge prose or coverage. `coverage.py` lists what the code has that no page mentions ([When a feature is finished](#when-a-feature-is-finished)). `--strict` turns freshness warnings into a failing exit status, for CI. In a working tree shared with someone else's uncommitted work, `--strict --ignore-dirty` still prints warnings for sources with uncommitted changes but does not fail on them when the accepted fingerprint equals the file at `HEAD` (the only drift is uncommitted); committed drift still fails, and it is not for CI ([details](references/format.md)). `serve` shows the vault in a browser and writes nothing. `snapshot` accepts source fingerprints as reviewed; run it only for pages you actually re-read against their sources, never to clear a warning. An initial reviewed pass may use `--all`.
169
169
 
170
- To read the result, run `npx project-spec serve` in the repository (add `--vault` when it has several vaults under `knowledge/`), or open the folder as an Obsidian vault. The viewer is not part of this skill, which holds only what writing a spec needs: it comes with the `project-spec` npm package. Where this copy of the skill has `assets/viewer.html`, or sits in a clone of the skills repository, `python3 <skill>/scripts/knowledge.py serve --repo <repository> --open` shows the same page without Node; without the viewer that command says so and names the other ways. When you hand over, offer to give the command a short name in the project: a `spec` script in `package.json` (`project-spec serve`), a `spec` target in a `Makefile`, or a shell alias. That file is outside the vault, so add it only when the person agrees. The viewer is one page on `127.0.0.1`; it reads the vault and the files the pages cite from disk on every page load, so it needs no build and shows the current state after a reload. It shows a note as written, under its title and summary, with the source files folded away at the end; an area page shows its notes with their summaries. So the first paragraph and the summary are what most readers see. Its **Copy for AI** turns a page and the reader's own words into a request for an agent that names the page file. It only copies text, so an agent that receives one still follows the skill it names, and a recheck or decision the reader states there is recorded under the reader's name, never as the agent's. If the vault has errors the page lists them instead. When the person wants the spec on a server for people without the repository, `npx project-spec build --out <file outside the vault>` (or `knowledge.py build` in a copy that has the viewer) writes that same viewer as one file ([options](references/format.md)); run it only when asked, never commit the file into the vault, and leave `--with-sources` out unless the person says everyone who can open the page may read the code.
170
+ To read the result, run `npx project-spec serve` in the repository (add `--vault` when it has several vaults), or open the folder as an Obsidian vault. The viewer is not part of this skill, which holds only what writing a spec needs: it comes with the `project-spec` npm package. Where this copy of the skill has `assets/viewer.html`, or sits in a clone of the skills repository, `python3 <skill>/scripts/knowledge.py serve --repo <repository> --open` shows the same page without Node; without the viewer that command says so and names the other ways. When you hand over, offer to give the command a short name in the project: a `spec` script in `package.json` (`project-spec serve`), a `spec` target in a `Makefile`, or a shell alias. That file is outside the vault, so add it only when the person agrees. The viewer is one page on `127.0.0.1`; it reads the vault and the files the pages cite from disk on every page load, so it needs no build and shows the current state after a reload. It shows a note as written, under its title and summary, with the source files folded away at the end; an area page shows its notes with their summaries. So the first paragraph and the summary are what most readers see. Its **Copy for AI** turns a page and the reader's own words into a request for an agent that names the page file. It only copies text, so an agent that receives one still follows the skill it names, and a recheck or decision the reader states there is recorded under the reader's name, never as the agent's. If the vault has errors the page lists them instead. When the person wants the spec on a server for people without the repository, `npx project-spec build --out <file outside the vault>` (or `knowledge.py build` in a copy that has the viewer) writes that same viewer as one file ([options](references/format.md)); run it only when asked, never commit the file into the vault, and leave `--with-sources` out unless the person says everyone who can open the page may read the code.
171
171
 
172
172
  Before handing over, read what you wrote as the person who will use it, not as its author. Open one area page and two of the notes you wrote or changed, and ask:
173
173
 
@@ -7,7 +7,7 @@ Plain Markdown, wikilinks and flat YAML properties. Use **JSON values inside YAM
7
7
  ## Layout
8
8
 
9
9
  ```text
10
- knowledge/<project>/
10
+ project-spec/ or the folder the person chose; older vaults are in knowledge/<project>/
11
11
  00-index.md start here
12
12
  areas/ maps of related capabilities (spec)
13
13
  notes/ source-backed behaviors and rules (spec)
@@ -166,6 +166,10 @@ The validator enforces these body rules:
166
166
  5. A gap has six `##` sections with exactly these headings, each once: `Current behavior`, `Gap`, `Evidence`, `Recheck`, `Discussion`, `Decision`. Headings inside code fences do not count.
167
167
  6. When `decision` is not `open`, `Decision` needs text; when `recheck` is not `not-checked`, `Recheck` needs text.
168
168
 
169
+ ## Where the vault is
170
+
171
+ A vault is a folder of the repository that holds `00-index.md`. The person may put it anywhere; a new one goes to `project-spec/` at the root unless they name another folder. Nothing inside a page depends on that place except Markdown links from a page to a file of the repository, which are relative to the page. So a vault is moved with the helper, not by hand: `knowledge.py move --repo REPO --to FOLDER` moves the folder, repoints those links, writes `created` into each gap that lacks it (Git will show the page as new in its new place), removes the folder it left when nothing else is in it, and runs the checks. Page ids, wikilinks, `sources` and the reviewed fingerprints stay as they are. After a move, anything outside the vault that names the old folder is yours to update: a `--vault` in a script, the block in an agent instruction file.
172
+
169
173
  ## The inventory file
170
174
 
171
175
  `.knowledge/inventory.md` is the checklist of a map: what the product has, and how far the spec has got with it. The agent writes it before the first page and keeps it true afterwards ([the rules](../SKILL.md#the-inventory-file)); no helper reads it, and like everything under `.knowledge/` it is not a page of the vault. It is committed with the vault, which is how a second session, or a second person, continues where the first one stopped.
@@ -200,7 +204,7 @@ Folders: web-app/src/features/reviews
200
204
  ```
201
205
 
202
206
  - A feature's heading is its name and one of three states: `not started`, `in progress`, `finished`. A feature with parts is still one heading; its parts are among its pages.
203
- - One checkbox per entry point: the client or kind (`web`, `mobile`, `admin`, `api`, `job`, `email`) and the name the code registers it under. A box is ticked when the entry point was followed to the code that decides its behavior, not when it was seen.
207
+ - One checkbox per entry point: the client or kind and the name the code registers it under. Use the product's own kinds; `web`, `mobile`, `admin`, `api`, `job`, `email`, `webhook` and `command` are common ones, not a fixed list. A box is ticked when the entry point was followed to the code that decides its behavior, not when it was seen.
204
208
  - `Pages` names the feature's pages by path. `Left` says in words what is not read yet, and is the same thing the `partial` page says in its last line. A `finished` feature has every box ticked and no `Left` line.
205
209
  - "Left out" holds what was looked at and is not part of the product, each with its reason.
206
210
 
@@ -246,7 +250,7 @@ Extract prose wikilinks, excluding inline and fenced code examples. Resolve full
246
250
 
247
251
  Canonical Markdown must not contain raw merge conflicts. Validation rejects complete Git groups with a labeled opening marker, matching marker widths (including configured widths), and an optional diff3 base section, even inside code fences. Unlabeled or custom conflict formats are outside this detector; also inspect unresolved Git index entries. A `conflict` gap that records attributed claims and a next check is valid; it does not resolve them. See [concurrent merges](merge.md).
248
252
 
249
- `serve` shows the vault in a browser: `knowledge.py serve --repo REPO [--vault VAULT] [--port N] [--open]`. Without `--vault`, this and every other command use the single vault under `knowledge/` (`knowledge/00-index.md` or `knowledge/*/00-index.md`) and stop with a message when there is none or several. It listens on `127.0.0.1` only (port 8757, or a free one when that is taken), answers only `/` and only when addressed as this machine, never writes, and builds the page again from disk on every request, so a reload shows the current files. When the vault has errors the page lists them. The page data is the graph above plus `live: true`, `vaultPath` (the vault's path relative to the repository), `history`, `pending` and `files`. `history` is the last 30 commits that touched vault pages (not `.knowledge/`), newest first, each `{"sha", "date", "subject", "pages", "more"}`; a page entry is `{"path", "status"}` with `status` `added`, `changed` or `removed`, plus `was` and `now` when the commit changed the page's `summary` (or, failing that, its `title`); at most 80 pages are listed per commit and `more` counts the rest. `pending` lists vault pages with uncommitted changes in the same `{"path", "status"}` shape. Both are empty outside a Git work tree. `files` is the text of the repository files that pages cite in `sources` or link to, keyed by repository-relative path, each `{"text", "truncated"}`. A file is included only when it is inside the repository and outside the vault, is not a credential path, and is UTF-8 text; one file is cut at 300,000 characters and all files together at 4,000,000, after which the rest stay ordinary links. The viewer opens a link to an included file in place: Markdown rendered, anything else as numbered lines, with the lines of a `#L10` or `#L10-L20` fragment marked.
253
+ `serve` shows the vault in a browser: `knowledge.py serve --repo REPO [--vault VAULT] [--port N] [--open]`. Without `--vault`, this and every other command use the repository's single vault: the one folder that holds `00-index.md`, looked for up to three folders deep and not inside hidden folders, dependencies or build output. They stop with a message when there is none or several. It listens on `127.0.0.1` only (port 8757, or a free one when that is taken), answers only `/` and only when addressed as this machine, never writes, and builds the page again from disk on every request, so a reload shows the current files. When the vault has errors the page lists them. The page data is the graph above plus `live: true`, `vaultPath` (the vault's path relative to the repository), `history`, `pending` and `files`. `history` is the last 30 commits that touched vault pages (not `.knowledge/`), newest first, each `{"sha", "date", "subject", "pages", "more"}`; a page entry is `{"path", "status"}` with `status` `added`, `changed` or `removed`, plus `was` and `now` when the commit changed the page's `summary` (or, failing that, its `title`); at most 80 pages are listed per commit and `more` counts the rest. `pending` lists vault pages with uncommitted changes in the same `{"path", "status"}` shape. Both are empty outside a Git work tree. `files` is the text of the repository files that pages cite in `sources` or link to, keyed by repository-relative path, each `{"text", "truncated"}`. A file is included only when it is inside the repository and outside the vault, is not a credential path, and is UTF-8 text; one file is cut at 300,000 characters and all files together at 4,000,000, after which the rest stay ordinary links. The viewer opens a link to an included file in place: Markdown rendered, anything else as numbered lines, with the lines of a `#L10` or `#L10-L20` fragment marked.
250
254
 
251
255
  `build` writes the same viewer as one file, for a server that shows the spec to people who do not have the repository: `knowledge.py build --repo REPO [--vault VAULT] --out FILE [--source-url URL] [--with-sources]`. `--out` must be a file outside the vault. The command stops with the `check` errors when the vault has any, and writes nothing then; freshness warnings do not stop it. The page data is the graph plus `built: true`, `commit` (the full `HEAD`, empty outside Git), `sourceUrl`, `vaultPath`, `history`, `pending` and `files`. `files` is empty unless `--with-sources` is given, because the text of cited files is source code. `--source-url` must be an `http(s)` address; `{commit}` in it is replaced by `HEAD`, and it is an error to name `{commit}` outside a Git work tree. `--allow-missing-sources` is for a build that sees only part of the repository (a Docker build context): a cited path where nothing exists is not an error and does not mark its page as changed, and the command lists those files; `check` and `snapshot` never accept it. On a built page a cited file whose text is not included is a link to `sourceUrl/<repository path>` (with `#L10-L20` when lines are named) in a new tab, or plain text when there is no `sourceUrl`; it is never a relative link, which would lead into the site that hosts the page. In a shallow clone the commit whose parents were not fetched is left out of `history` (by `serve` too), since Git would show every page as added there, and `build` says that the history is short.
252
256
 
@@ -146,7 +146,7 @@ def folders(files, prefixes=()):
146
146
  def main(argv=None):
147
147
  parser = argparse.ArgumentParser(description=__doc__.split('\n')[0])
148
148
  parser.add_argument('--repo', required=True, type=Path)
149
- parser.add_argument('--vault', type=Path, help='default: the single vault under knowledge/ in the repository')
149
+ parser.add_argument('--vault', type=Path, help='default: the single vault in the repository, a folder with 00-index.md')
150
150
  parser.add_argument('--path', action='append', default=[], metavar='FOLDER',
151
151
  help='only this folder or file of the repository, and list each sentence and limit no page mentions; repeatable')
152
152
  parser.add_argument('--all', action='store_true', help='print every line instead of the first 40 folders or 60 items')
@@ -12,7 +12,7 @@ import sys
12
12
  import subprocess
13
13
  import tempfile
14
14
  import unicodedata
15
- from urllib.parse import unquote, urlsplit
15
+ from urllib.parse import quote, unquote, urlsplit
16
16
  from pathlib import Path, PurePosixPath
17
17
 
18
18
  TYPES = {'index', 'area', 'note', 'gap', 'plan', 'run'}
@@ -711,17 +711,138 @@ def viewer_html(payload):
711
711
  return template.replace('__KNOWLEDGE_DATA__', serialized)
712
712
 
713
713
 
714
+ VAULT_DEPTH = 3 # project-spec/, knowledge/<product>/ and docs/<product>/spec/ are all within reach
715
+ NOT_A_VAULT_PLACE = {'node_modules', 'vendor', 'dist', 'build', 'out', 'target', 'coverage', '__pycache__', 'venv', 'Pods'}
716
+
717
+
714
718
  def find_vault(repo):
715
- """The vault of a repository when there is exactly one in the usual place."""
716
- found = sorted(p.parent for p in repo.glob('knowledge/*/00-index.md'))
717
- if (repo / 'knowledge/00-index.md').is_file():
718
- found.append(repo / 'knowledge')
719
+ """The repository's vault when it has exactly one: a folder that holds `00-index.md`, wherever the person put it.
720
+
721
+ Looks at most three folders deep and not inside hidden folders, dependencies or build output, so a vault that
722
+ belongs to something nested deeper (an example project, a package's own docs) is not taken for the repository's.
723
+ """
724
+ found = []
725
+
726
+ def look(folder, depth):
727
+ try:
728
+ entries = sorted(e for e in folder.iterdir()
729
+ if e.is_dir() and not e.is_symlink() and not e.name.startswith('.') and e.name not in NOT_A_VAULT_PLACE)
730
+ except OSError:
731
+ return
732
+ for entry in entries:
733
+ if (entry / '00-index.md').is_file():
734
+ found.append(entry) # nothing inside a vault is another vault
735
+ elif depth < VAULT_DEPTH:
736
+ look(entry, depth + 1)
737
+
738
+ look(repo, 1)
719
739
  if len(found) != 1:
720
- raise ValueError(('no vault found under knowledge/' if not found else
740
+ raise ValueError(('no vault found: no folder with 00-index.md up to three folders deep' if not found else
721
741
  'several vaults found (' + ', '.join(p.relative_to(repo).as_posix() for p in found) + ')') + '; pass --vault')
722
742
  return found[0]
723
743
 
724
744
 
745
+ def repoint(text, old_dir, new_dir, old_vault):
746
+ """`text` of a page that sat in `old_dir` and now sits in `new_dir`, with the links that leave the vault repointed.
747
+
748
+ All three are absolute POSIX paths. A link to another page of the vault is relative to something that moved with
749
+ it, so it stays as written; a link to a file of the repository is rewritten so it names the same file from the
750
+ new place. Links in code are left alone. Returns (text, how many links changed).
751
+ """
752
+ changed = 0
753
+
754
+ def target(match):
755
+ nonlocal changed
756
+ raw = match.group(1)
757
+ angle = raw.startswith('<')
758
+ inner = raw[1:-1] if angle else raw
759
+ cut = re.search(r'[?#]', inner)
760
+ path, tail = (inner[:cut.start()], inner[cut.start():]) if cut else (inner, '')
761
+ where = unquote(path)
762
+ if not where or where.startswith('/') or SCHEME.match(where):
763
+ return match.group(0)
764
+ absolute = posixpath.normpath(posixpath.join(old_dir, where))
765
+ if absolute == old_vault or absolute.startswith(old_vault + '/'):
766
+ return match.group(0)
767
+ fresh = posixpath.relpath(absolute, new_dir)
768
+ fresh = fresh if angle else quote(fresh, safe="/-._~!$&'()*+,;=:@")
769
+ if fresh == path:
770
+ return match.group(0)
771
+ changed += 1
772
+ return match.group(0)[:match.start(1) - match.start(0)] + (f'<{fresh}{tail}>' if angle else fresh + tail)
773
+
774
+ lines = []
775
+ for line, in_code in lines_with_code(text):
776
+ if not in_code:
777
+ # an inline code span is not a link either
778
+ pieces = re.split(r'(`+.*?`+)', line)
779
+ line = ''.join(piece if i % 2 else MD_REF.sub(target, MD_LINK.sub(target, piece)) for i, piece in enumerate(pieces))
780
+ lines.append(line)
781
+ return '\n'.join(lines), changed
782
+
783
+
784
+ def move_vault(repo, vault, dest):
785
+ """Move the vault to `dest`, another folder of the same repository, and keep it true: links from pages to files
786
+ of the repository are repointed, and each gap keeps the day it appeared. Returns a list of lines to print.
787
+
788
+ Page ids, wikilinks, `sources` and the reviewed fingerprints do not depend on where the vault is, so nothing
789
+ else changes. Raises ValueError with the reason when the move cannot be made; nothing is touched then.
790
+ """
791
+ import shutil
792
+ dest = Path(os.path.abspath(dest))
793
+ if dest == vault:
794
+ raise ValueError('the vault is already there')
795
+ if not dest.is_relative_to(repo) or dest == repo:
796
+ raise ValueError('--to must be a folder inside the repository')
797
+ if dest.is_relative_to(vault):
798
+ raise ValueError('--to must not be inside the vault it moves')
799
+ if dest.exists() and (not dest.is_dir() or any(dest.iterdir())):
800
+ raise ValueError(f'{dest.relative_to(repo).as_posix()} already exists and is not empty')
801
+ first = added_dates(repo, vault)
802
+ edits, links, pages, dated = {}, 0, 0, 0
803
+ for file in sorted(vault.rglob('*.md')):
804
+ rel = file.relative_to(vault)
805
+ if any(part in {'.obsidian', '.trash'} for part in rel.parts) or file.is_symlink():
806
+ continue
807
+ try:
808
+ before = file.read_bytes().decode('utf-8')
809
+ except (OSError, UnicodeDecodeError):
810
+ continue
811
+ after, count = repoint(before.replace('\r\n', '\n'), (vault / rel).parent.as_posix(), (dest / rel).parent.as_posix(), vault.as_posix())
812
+ # Git will show the page as new in its new place, so a gap that has no `created` gets the day it first appeared.
813
+ head = re.match(r'---\n(.*?)\n---\n', after, re.S)
814
+ day = first.get(rel.as_posix())
815
+ if head and day and re.search(r'^type:\s*"gap"\s*$', head.group(1), re.M) and not re.search(r'^created:', head.group(1), re.M):
816
+ after = re.sub(r'^(type:\s*"gap"\s*)$', lambda m: m.group(1) + f'\ncreated: "{day}"', after, count=1, flags=re.M)
817
+ dated += 1
818
+ if count:
819
+ links, pages = links + count, pages + 1
820
+ if after != before.replace('\r\n', '\n'):
821
+ edits[rel] = after
822
+ dest.parent.mkdir(parents=True, exist_ok=True)
823
+ if dest.exists():
824
+ dest.rmdir()
825
+ shutil.move(str(vault), str(dest))
826
+ for rel, text in edits.items():
827
+ atomic_write(dest / rel, text)
828
+ old, new = vault.relative_to(repo).as_posix(), dest.relative_to(repo).as_posix()
829
+ lines = [f'move: {old} -> {new}; {links} links to repository files repointed on {pages} pages'
830
+ + (f'; {dated} gaps given the day they first appeared' if dated else '')]
831
+ _, _, errors, warnings, _ = load_vault(repo, dest)
832
+ lines.append(f'move: check finds {len(errors)} errors and {len(warnings)} warnings in the new place')
833
+ lines += [f' {error}' for error in errors[:20]]
834
+ left = vault.parent
835
+ if left != repo and left.is_dir() and left != dest.parent:
836
+ rest = sorted(p.name for p in left.iterdir())
837
+ if rest:
838
+ lines.append(f'move: {left.relative_to(repo).as_posix()}/ still holds {", ".join(rest)}')
839
+ else:
840
+ left.rmdir() # nothing of anyone's is left in it
841
+ lines.append(f'move: now update what names the old folder: a `--vault {old}` in your scripts, and the block in AGENTS.md or CLAUDE.md '
842
+ '(`project-spec instructions --file ...` writes it again)')
843
+ return lines
844
+
845
+
725
846
  HISTORY_COMMITS = 30 # commits shown under Recent changes
726
847
  HISTORY_PAGES = 80 # pages listed for one commit
727
848
  _history_cache = {}
@@ -954,13 +1075,14 @@ def make_server(repo, vault, port):
954
1075
 
955
1076
  def main(argv=None):
956
1077
  parser = argparse.ArgumentParser()
957
- parser.add_argument('command', choices=['check', 'snapshot', 'serve', 'build'])
1078
+ parser.add_argument('command', choices=['check', 'snapshot', 'serve', 'build', 'move'])
958
1079
  parser.add_argument('--repo', required=True, type=Path)
959
- parser.add_argument('--vault', type=Path, help='default: the single vault under knowledge/ in the repository')
1080
+ parser.add_argument('--vault', type=Path, help='default: the single vault in the repository, a folder with 00-index.md')
960
1081
  parser.add_argument('--strict', action='store_true', help='fail check when freshness warnings exist')
961
1082
  parser.add_argument('--port', type=int, default=8757, help='serve: port on 127.0.0.1 (another free port is used if it is taken)')
962
1083
  parser.add_argument('--open', action='store_true', help='serve: open the page in the default browser')
963
1084
  parser.add_argument('--out', type=Path, help='build: the HTML file to write, outside the vault')
1085
+ parser.add_argument('--to', type=Path, metavar='DIR', help='move: the folder of the repository the vault moves to')
964
1086
  parser.add_argument('--viewer', type=Path, metavar='FILE',
965
1087
  help='serve, build: a page of your own instead of the viewer; it gets the data where it says __KNOWLEDGE_DATA__')
966
1088
  parser.add_argument('--with-sources', action='store_true', help='build: include the text of the repository files the pages cite')
@@ -995,6 +1117,14 @@ def main(argv=None):
995
1117
  parser.error('repo and vault must be existing directories')
996
1118
  if args.viewer and args.command not in ('serve', 'build'):
997
1119
  parser.error('--viewer is only for serve and build')
1120
+ if (args.command == 'move') != bool(args.to):
1121
+ parser.error('move requires --to DIR' if args.command == 'move' else '--to is only for move')
1122
+ if args.command == 'move':
1123
+ try:
1124
+ print('\n'.join(move_vault(repo, vault, args.to if args.to.is_absolute() else repo / args.to)))
1125
+ except (OSError, ValueError) as exc:
1126
+ parser.error(str(exc))
1127
+ return 0
998
1128
  if args.command in ('serve', 'build'):
999
1129
  global VIEWER
1000
1130
  VIEWER = args.viewer.resolve() if args.viewer else None
@@ -53,18 +53,23 @@ def jsonbytes(value):
53
53
  return (json.dumps(value, ensure_ascii=True, indent=2, sort_keys=True) + '\n').encode()
54
54
 
55
55
 
56
- def relevant(path, vault_rel):
57
- p = Path(path)
58
- parts = p.parts
59
- bundle_metadata = vault_rel.startswith('knowledge/') and path in {'knowledge/README.md', 'knowledge/.gitignore'}
60
- return bool(parts) and not bundle_metadata and not knowledge.credential_path(path) and not (path == vault_rel or path.startswith(vault_rel + '/')) and not (path == 'knowledge/tooling/project-knowledge' or path.startswith('knowledge/tooling/project-knowledge/')) and not any(knowledge.fold(x) in {'.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '__pycache__'} for x in parts)
56
+ # Where a copy of this skill may sit inside the repository: updating it is not a change of the application.
57
+ SKILL_COPIES = tuple(base + '/project-knowledge' for base in ('knowledge/tooling', '.claude/skills', '.codex/skills', '.agents/skills'))
61
58
 
62
59
 
63
60
  def housekeeping(path, vault_rel):
64
- """Paths a sync never queues because they are the vault, the portable skill copy or their wrapper files."""
61
+ """Paths a sync never queues because they are the vault, a copy of the skill or their wrapper files."""
65
62
  if vault_rel.startswith('knowledge/') and path in {'knowledge/README.md', 'knowledge/.gitignore'}:
66
63
  return True
67
- return any(path == base or path.startswith(base + '/') for base in (vault_rel, 'knowledge/tooling/project-knowledge'))
64
+ return any(path == base or path.startswith(base + '/') for base in (vault_rel, *SKILL_COPIES))
65
+
66
+
67
+ def relevant(path, vault_rel):
68
+ parts = Path(path).parts
69
+ return (bool(parts) and not knowledge.credential_path(path) and not housekeeping(path, vault_rel)
70
+ and not any(knowledge.fold(x) in {'.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '__pycache__'} for x in parts))
71
+
72
+
68
73
 
69
74
 
70
75
  def retarget_hint(repo, vault, target):
@@ -512,16 +517,20 @@ def main():
512
517
  parser = argparse.ArgumentParser()
513
518
  subs = parser.add_subparsers(dest='command', required=True)
514
519
  rp = subs.add_parser('receipt')
515
- rp.add_argument('--repo', required=True, type=Path); rp.add_argument('--vault', required=True, type=Path)
520
+ rp.add_argument('--repo', required=True, type=Path); rp.add_argument('--vault', type=Path)
516
521
  rp.add_argument('--plan', required=True, type=Path); rp.add_argument('--out', required=True, type=Path)
517
522
  rp.add_argument('--run', type=Path)
518
523
  for name in ('scan', 'finish'):
519
- p = subs.add_parser(name); p.add_argument('--repo', required=True, type=Path); p.add_argument('--vault', required=True, type=Path)
524
+ p = subs.add_parser(name); p.add_argument('--repo', required=True, type=Path); p.add_argument('--vault', type=Path)
520
525
  if name == 'scan':
521
526
  p.add_argument('--target'); p.add_argument('--write-status', action='store_true'); p.add_argument('--json', action='store_true')
522
527
  else:
523
528
  p.add_argument('--plan', required=True, type=Path); p.add_argument('--review', required=True, type=Path)
524
- args = parser.parse_args(); repo = args.repo.resolve(); vault = args.vault.resolve()
529
+ args = parser.parse_args(); repo = args.repo.resolve()
530
+ try:
531
+ vault = args.vault.resolve() if args.vault else knowledge.find_vault(repo)
532
+ except ValueError as exc:
533
+ parser.error(str(exc))
525
534
  if args.command == 'receipt':
526
535
  print(receipt(repo, vault, args.plan, args.out, args.run))
527
536
  elif args.command == 'scan':