@gavin-hu/my-pi-agent 0.18.0 → 0.19.0

package/skills/project-docs/references/audit.md

@@ -0,0 +1,131 @@
+# Audit
+
+Read-only. The audit answers one question per claim: is this still true, and if not,
+which mode fixes it? It never edits — not even a typo, not even "while we are here".
+If the user asks for the fixes, finish the report first, then enter the mode it names.
+
+Read [`discovery.md`](./discovery.md) first and open the report with the profile. The
+five faces below are a reading order, not a checklist: a face with no evidence
+produces no findings.
+
+## 1. The tree against the docs
+
+The claims a reader acts on: a catalog row, a limit stated in a package README, a
+default in a configuration table, a roadmap item, a non-goal, a "supported format"
+list. For each, find the code that does it — the registration, the branch, the config
+default — and name where it disagrees.
+
+| Where the claim lives | What falsifies it |
+|---|---|
+| A catalog row or feature bullet | The tool, command, flag, or route no longer registers |
+| A limitations section | The gap was closed, or widened, and the text did not move |
+| A configuration default | The loader's default differs from the table |
+| A roadmap item | The tree already does it (see face 4) |
+| A non-goal | The changelog records the thing being shipped anyway |
+
+## 2. The docs against each other
+
+- **Counts** — a number a doc states about the code (modules, tools, extensions,
+  screens) belongs to the tree. A project that derives it in a test has the count; one
+  that does not is a finding, and the fix is a guard, not a number.
+- **Catalog rows** — every row names a thing that exists; every existing thing the
+  catalog claims to cover has a row. Both directions.
+- **Cross-reference ids** — the same feature named in a front-door row, a roadmap item,
+  and a changelog entry. Report a mismatch; never rename one side to match.
+- **The version** — the source of truth, the newest dated changelog heading, the tag,
+  and any badge, badge-adjacent prose, or install instruction that repeats it.
+- **The mirror** — a translated README carries the original's sections, table rows, and
+  links. A row that exists in one and not the other is a finding even when the prose is
+  deliberately translated.
+- **The contributor path** — the commands `CONTRIBUTING.md` tells a newcomer to run,
+  against the manifest's `scripts` and the CI workflow's steps. A command the docs promise
+  and the manifest does not define is the one stale claim a new contributor hits first,
+  and a step CI runs that the docs never mention is the one they skip.
+
+## 3. The changelog's commit window
+
+Run `scripts/state.ts` (see the skill's *Start here*). It gives the file, the last tag,
+the commits since it, the `[Unreleased]` categories, and the scopes in use.
+
+When discovery says a tool generates the file, the window's entries live in that tool's
+input — the changeset queue, the commit-message convention — so audit those, and report
+a missing fragment rather than a missing bullet.
+
+Read every commit it lists: `git show <sha>` for the diff, or the pull request when the
+repository squashes. A subject line is not enough — `fix bug` and `wip` hide
+user-visible changes, and `feat: rewrite the config loader` is often invisible to users.
+For each commit, decide whether a user can observe it, which bullet covers it, whether
+that bullet's scope is right, and whether a reader of the bullet alone would know what
+changed for them.
+
+| Commit | User-visible | Evidence | Existing entry | Action |
+|---|---|---|---|---|
+| `3f19a02` | yes | `src/load.ts:42` now rejects an unknown key | — | add |
+| `b81c4de` | no | test-only | — | leave |
+| `0ad9f12` | yes | retry limit 3 → 5 | `Changed`: "`api`: retries are now bounded" | update: the bullet never names the limit |
+| `77e0a1e` | unclear | touches the public `--json` shape | — | ask |
+
+`Action` is one of **add** (user-visible, no bullet), **update** (a bullet exists and is
+wrong, unscopeable, or too vague to act on), **leave** (covered, internal, or recorded
+under an older release), or **ask** (the outcome depends on intent the diff cannot show).
+
+Report separately:
+
+- Duplicate `##` or `###` headings — some tools render the second as its own section,
+  and a reader sees half the entries.
+- An empty category heading, or a heading a release guard rejects.
+- An `[Unreleased]` section that is missing or empty while the window contains
+  user-visible changes.
+- An entry for something already shipped under a dated heading: the same outcome twice,
+  which reads as a second change.
+- A stale link reference pointing at an older tag than the newest dated heading — where
+  the file uses link references at all. A generated or non-Keep-a-Changelog file may have
+  none, and the state script reports that absence as a missing reference without it being
+  a defect.
+
+## 4. The roadmap's own ids and caps
+
+Re-derive the window before judging an item: `git log --oneline <last-tag>..HEAD` plus
+the changelog's newest dated heading. A roadmap describes the tree, so work that landed
+but has not shipped is already part of what it should describe.
+
+- An item the tree already does is a deletion, with its reason recorded where the item
+  was.
+- An id used twice, skipped in a sequence, or cited from nowhere the file defines.
+- A bucket over the cap the file states; a bucket that keeps growing stops being a
+  priority.
+- A ledger row whose items all closed, or an open item with no ledger row.
+- A relative link or a `path:line` citation that no longer resolves.
+
+## 5. The front door's examples
+
+- The quickstart command, run as written. A command that no longer exists is a stale
+  promise, and it is the most expensive one because it is the reader's first step.
+- An example that imports, configures, or calls something the code no longer accepts.
+- A screenshot or a recording that shows a surface that has since changed.
+- A link to a guide that moved, a section anchor that was renamed, or a badge whose
+  target is gone.
+
+## Report
+
+Open with the profile, then the four sections from the skill: **Stale**, **Missing**,
+**Suggested edit**, **Needs a decision**. Every stale finding carries the document,
+`path:line`, the evidence in the tree, and the mode that fixes it. Group by the mode
+when there are more than a handful, so the user can act one mode at a time.
+
+Nothing found is a valid result for the whole audit or for any face. Say what was
+checked — the files read, the commands run, the commits examined — and stop. An audit
+that invents findings to look thorough is worse than one that reports none.
+
+## What the audit cannot see
+
+Name these in a closing line instead of guessing:
+
+- Whether a change is user-visible to someone the diff does not show — a default that
+  only matters on one platform, a behavior the docs promised and the tests never
+  covered.
+- Whether a commit message describes what the code does; only the diff does.
+- Whether an item shipped: a merged change to a document is not a release, and only the
+  maintainer knows whether the front door's promise is meant to hold today or next
+  version.
+- Whether a roadmap priority is still right, and whether a non-goal still stands.

package/skills/project-docs/references/changelog.md

@@ -0,0 +1,105 @@
+# Record one bullet
+
+This mode writes one thing: a bullet in the changelog for a change that just landed.
+It does not decide whether something shipped, and it does not curate a release — that
+is the `release` mode, and only for a version the user named.
+
+Read [`discovery.md`](./discovery.md) first for the file, the categories, their order,
+the scope spelling, and whether the entry ships with the change. Where a tool owns the
+file — `semantic-release`, `changesets`, `git-cliff`, or a step in the release workflow —
+this mode does not write it: the entry belongs upstream, in the commit message's
+convention, a changeset fragment, or the generator's config.
+
+## Where the bullet goes
+
+- Re-read the changelog before editing: another session, another contributor, or the
+  user may have written since the state script ran.
+- Under `[Unreleased]`, in the category the project uses for this kind of change, in
+  the file's own order and spelling. Never create a second heading for a category that
+  already exists in the section.
+- When the file keeps no `[Unreleased]` section, ask where the change is recorded — the
+  preamble decides, and a project that writes entries only at release has a different
+  procedure.
+- Insert without disturbing any other bullet, keep the file's wrap column, and write it
+  in the same commit as the change it describes.
+
+## Does it qualify
+
+It qualifies when a user can observe it: behavior, a CLI or tool or command surface, a
+config default, packaging and dependencies a user installs, security, or a documented
+promise that is now true or false.
+
+It does not qualify when only the implementation moved: an internal refactor, a rename
+with no behavior change, a test, formatting, a comment, a dependency bump with no
+behavior change, or a typo fixed in the changelog itself.
+
+When a change is both — a refactor that also fixes a rounding bug — the bullet is the
+rounding bug, and the refactor is not mentioned.
+
+## One outcome, one bullet
+
+- A feature and the bug it fixed before release are one bullet: users never saw the
+  broken version.
+- Two observable changes are two bullets, even in one commit.
+- Two commits that produce one outcome are one bullet, written where the outcome became
+  true.
+- A breaking change is its own bullet with the required action; do not bury it in a
+  feature's sentence.
+
+When the outcome is unclear, ask. Reading the diff tells you what changed; only the
+author knows what a user will notice.
+
+## The shape
+
+Follow the file's newest released section. Where the project states nothing, the shape
+is one bullet that leads with the scope in backticks, a colon, then what the user can
+now do:
+
+```text
+- `billing`: invoices show tax as a separate line. Amounts that used to be bundled
+  into `total` are summed on the printed total, so an invoice stored by an older
+  release still reconciles.
+- `cli`: `--legacy-auth` is no longer read; run `mytool migrate auth` first.
+```
+
+- **Scope**: the area a user would name — an extension, package, module, or subsystem,
+  in the project's own spelling. Never a file path, a function, or a ticket number. A
+  bullet with no scope is a defect where the project uses scopes, and noise where it
+  does not.
+- **Outcome first**: what is different for the user, then the mechanism if it matters,
+  then any action they must take.
+- **Length**: a bullet may run to several sentences when the outcome needs them — what
+  the user sees, what it replaced, what to do about it. Brevity is not the goal;
+  vagueness is the defect.
+- **Voice**: match the file. Most changelogs are present tense and third person; do not
+  switch to marketing, and do not add praise for the change.
+- **Wrap**: match the file's column, usually near 80, and let one bullet be one
+  paragraph.
+
+## What does not belong
+
+File names and paths, internal helper names, test counts and coverage, commit hashes
+and pull-request numbers as the subject (a link at the end is fine where the file does
+it), and empty words such as "various", "improvements", "cleanup", "refactor", "misc".
+A reader who cannot tell from the bullet whether the change affects them has been told
+nothing.
+
+## The two failure modes
+
+```text
+- `billing`: refactored invoice rendering and added tests.
+- `misc`: improvements.
+```
+
+The first names no outcome and reports the implementation. The second names no scope,
+no outcome, and would fit any release.
+
+```text
+- `api`: `POST /v2/charge` now refuses an amount with more than two decimals
+  instead of truncating it, so a client that relied on the old rounding sees a
+  `422` with `code: "amount_precision"`. Truncation moved to `POST /v2/charge/draft`,
+  which is what the old behavior should have been.
+```
+
+Three sentences, one outcome, one scope, and the migration named. Long is fine when
+each sentence tells the reader something they must know.

package/skills/project-docs/references/discovery.md

@@ -0,0 +1,127 @@
+# Discover the project's documents
+
+A document is a convention before it is a file: which documents exist, what each one
+promises, how a version is spelled, and when an entry is written are all things a
+project chose. Read what it chose. Do not import a template where the project says
+something else, and do not average two sources — when they disagree, ask.
+
+Find these five things, in this order. The first one locates the rest.
+
+## 1. The document set
+
+The documents this skill looks for, in the order it looks, and where a project keeps
+them. A project that has only some of them is normal: the skill maintains what exists,
+and whether to adopt a missing one is the maintainer's decision rather than an edit.
+
+- **The front door** — `README.md` first, then `README.rst`, `README`, or `docs/README.md`.
+  A mirror (`README.zh-CN.md`, `README.ja.md`) is part of the front door, not a
+  separate document: it carries the same sections, table rows, and links.
+- **The plan of record** — `ROADMAP.md`, then `ROADMAP`, `docs/roadmap.md`, a
+  `ROADMAP` section in the front door, or an issue tracker label the project's docs
+  name. A project with none is maintained from the changelog and the tree alone; say so.
+- **The record of what shipped** — `CHANGELOG.md`, then `CHANGELOG`, `CHANGES.md`,
+  `HISTORY.md`, `NEWS.md`, `docs/CHANGELOG.md`, `docs/changelog.md`. The bundled script
+  takes the first name in that order. Several changelogs belonging to several packages
+  are a scope question, not a choice: ask which package is in scope, and never treat one
+  package's file as a copy of another's.
+- **The contributor path** — `CONTRIBUTING.md`, then `.github/CONTRIBUTING.md`,
+  `docs/contributing.md`, and the instruction file the project's agent reads
+  (`AGENTS.md`, `CLAUDE.md`), which usually states the rules the other three obey.
+
+Deep guides (`docs/`, `documentation/`) are where detail belongs. Their existence is
+the reason the front door can stay short: it summarizes and links, and the skill must
+not move a guide's content up into it, or copy the front door's catalog down.
+
+These rules are written in Markdown's vocabulary because most projects write their docs
+in it. Read the format the project actually uses — reStructuredText, AsciiDoc, plain
+text — and fix it in that format: a heading anchor, a link reference, and a fenced
+example are spelled differently in each, and converting a document is not this skill's
+job.
+
+## 2. The version's single source
+
+One file decides the version: `package.json`, `pyproject.toml`, `Cargo.toml`, a
+`VERSION` file, or a `version` module. Everything else repeats it — the newest dated
+changelog heading, a tag, a badge, a lockfile. Read the source and the repeats
+together; a version that disagrees in one place is the most common stale claim a
+release leaves behind.
+
+## 3. The changelog's local conventions
+
+- **Who writes the file** — a preamble that says "generated", a `.changeset/` or
+  `.changes/` directory, a release workflow step that writes the changelog, or a
+  generator named in the manifest or its config: `semantic-release`, `release-please`,
+  `changesets`, `git-cliff`, `goreleaser`, `cargo-release`, `standard-version`. Where a
+  tool owns the file, the entry is written upstream — in the commit message's
+  convention, in a changeset fragment, or in the generator's config — and never by hand.
+- **The preamble** — whether it names Keep a Changelog, Semantic Versioning, a
+  different convention, and whether unreleased entries are kept in the file at all.
+- **The category names and their order** — Keep a Changelog's set is `Added`,
+  `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`, in that order, and a
+  project may use a subset, add its own, or reorder them. Copy the spelling exactly:
+  `Fix` is not `Fixed`.
+- **The bullet's shape** — read the newest *released* section, not the first one. Note
+  the scope prefix (`- \`core\`: …`, `- [core] …`, or none), whether a bullet may run
+  several sentences, the wrap column, and whether backticks or bold carry the scope.
+- **Whether the entry ships with the change** — `CONTRIBUTING.md`, the instruction
+  file, and a pull-request template say it in one line. Silence is not permission to
+  defer: ask, because a changelog maintained per release is a different procedure.
+- **The release procedure** — a release document outranks everything here:
+  `docs/release.md`, `RELEASING.md`, `CONTRIBUTING.md`'s release section, a
+  `publish.yml` job, or a `release` script in the manifest. Read it for the link-ref
+  update, the tag format, and the push and publish order.
+
+## 4. The roadmap's rules
+
+- **The item form** — how an item is written and whether it carries an id: `**P1 — …**`,
+  `- [ ] …`, `R1: …`, a bare heading. Ids are what a citation elsewhere points at.
+- **The buckets and their caps** — horizon names (`Now` / `Next` / `Later`, or
+  quarters), and any limit the file states on how many items a bucket holds.
+- **The ledger, if there is one** — the table tying a promise in the front door to the
+  items that keep it; a row is open while any of its items are.
+- **What happens to a shipped item** — the stated rule, usually one line: delete it and
+  record the reason, or renumber the rest. Never tick it and leave it, unless the file
+  says to.
+- **The non-goals** — the "deliberately left thin" or "won't do" list, with the reason
+  each carries. Reversing one is a decision, not an edit.
+
+## 5. The check and the guards
+
+The project's check command (`bun run check`, `npm test`, `make check`, a CI workflow)
+is the finish line for any edit. Find the guards on these documents by name, because a
+guard states the rule better than a summary of it: `release.test.ts`,
+`changelog.test.ts`, `docs-parity.test.ts`, `roadmap.test.ts`, a link checker, or a CI
+step that compares a count in the docs with the tree.
+
+Quote a guard's name and what it holds; do not restate its rule. Run the guard
+directly while iterating — a failing guard names the rule you just broke.
+
+## State the profile
+
+Before editing, write one short paragraph: the documents found, the version's source,
+the changelog's categories and scope spelling, the roadmap's item form and caps, the
+check command, and the guards. It is how the user catches a misread in one line
+instead of in a diff. Do not invent a rule the project never stated; ask instead.
+
+## A worked example
+
+When you are in this repository, the answers are already written down:
+
+- `README.md` and `README.zh-CN.md` — the front door and its mirror; `test/docs-parity.test.ts`
+  holds the two to the same headings, table rows, and links.
+- `CHANGELOG.md` — Keep a Changelog preamble, categories in the standard order,
+  `[Unreleased]` kept in the file, scope in backticks followed by a colon.
+- `ROADMAP.md` — items as `**P1 — …**`, `Now` and `Next` capped at ten, a promise
+  ledger, and the rule that a shipped item is deleted with its reason;
+  `test/roadmap.test.ts` pins the ids, links, and caps, and cannot see that an item
+  has shipped.
+- `CONTRIBUTING.md` and `AGENTS.md` — the entry lands in the same commit as the
+  change, and a behavior change also updates the catalog table in both entry READMEs
+  and the relevant guide.
+- `docs/development.md` — the normative release procedure.
+- `test/release.test.ts` — the guard on subsection names, order, emptiness, and the
+  version pin against the newest tag.
+- `bun run check` — the finish line; `bun test test/roadmap.test.ts` for one guard alone.
+
+The paths are named, not linked: a skill is installed into projects that do not
+contain them, so a link would point nowhere from the place it is read.

package/skills/project-docs/references/readme.md

@@ -0,0 +1,80 @@
+# Readme
+
+The front door is the only document a reader is guaranteed to see, so it carries two
+burdens at once: it must be *enough* on its own, and it must not become the manual. This
+mode keeps it true to the tree without letting it grow.
+
+Read [`discovery.md`](./discovery.md) first for the file, its mirror, and the guides it
+links to.
+
+## What belongs on the front door
+
+- What the thing is, in one or two sentences a stranger can act on.
+- Install, and the first command that proves the install worked.
+- The catalog: one row per capability, grouped by what the reader is trying to do.
+- Configuration that a reader must choose before the first run, and where the rest
+  lives.
+- Links onward to the guides, and the license.
+
+What does not belong: a tool's parameter table, an exhaustive options list, an internal
+architecture, or a tutorial. When a row needs three sentences of mechanism, the
+mechanism belongs in a guide and the row links to it — do not copy the guide up, and do
+not let the row become a summary of a summary.
+
+## Rows and counts belong to the tree
+
+Where the project has a catalog of capabilities, each row follows the tree:
+- Every row names something that exists and is spelled the way the code spells it: the
+  tool, the command, the flag, the file. A renamed tool with an unchanged row is a
+  broken promise to the reader who types it.
+- Every count the page states — extensions, tools, skills, themes, formats — is read
+  from the tree. A project with a guard that derives it has the number already: change
+  the tree, or the guard, never the number in the prose.
+- A capability with no row is invisible; a row with no capability is a lie. Both
+  directions, in the same pass.
+
+## Examples must run
+
+Run the quickstart as written, in a clean directory, before editing anything else on the
+page. The first command is the most expensive promise on the page: a broken one costs
+the reader the whole document. Then check the worked example — an import, a
+configuration snippet, a call — against the current surface, and prefer the shortest
+form that still runs.
+
+## The mirror, where the project has one
+
+A translated front door is the same document in another language: the same sections,
+the same table rows in the same order, the same relative links. Prose is translated;
+structure is not. A project with one language has no mirror to check, and adding one is
+not this mode's job. A row added to one and not the other is a finding, and the count on
+both sides is the tree's.
+
+## Screenshots and assets
+
+An image is a claim about a surface. Recapture it when the surface changed — and only
+then, because a stale frame is worse than no frame and a fresh frame is expensive to
+produce. Check that the alt text describes what the frame now shows, that the image is
+referenced by a relative path, and that an image whose feature was removed is deleted
+rather than left unreferenced.
+
+## Report
+
+Say which rows, counts, examples, and images moved, and which claims you could not check
+without running the product. A front door that matches the tree already is a valid
+result; say what you verified — the command you ran, the counts you derived — and stop.
+
+## In this repository
+
+- `README.md` is the front door and `README.zh-CN.md` mirrors it section for section;
+  `test/docs-parity.test.ts` holds the two to the same headings, table rows, and links,
+  and derives the catalog's counts from the tree.
+- `test/extension-load.test.ts` pins every count the pages state — extensions, tools,
+  skills, themes — against what actually loads and ships, and requires a row in both
+  entry READMEs for every packaged skill.
+- `assets/` holds the frames the pages show; `bun run screenshots` recaptures one, and a
+  frame is only recaptured when its surface changed.
+- Deep detail lives in `docs/extensions/<name>.md`, `lib/README.md`, and `docs/`; the
+  front door links there and does not restate them.
+
+The paths are named, not linked: a skill is installed into projects that do not
+contain them, so a link would point nowhere from the place it is read.

package/skills/project-docs/references/release.md

@@ -0,0 +1,84 @@
+# Release
+
+Only when the user asked for a specific version. A release is a promise: a tag, a
+published artifact, and a section of the changelog that says what is in it. The
+project's release document owns the whole procedure; this file adds the changelog
+steps and the order they fit into, not a competing one.
+
+## Before touching the file
+
+1. Read the project's release document — `docs/release.md`, `RELEASING.md`,
+   `CONTRIBUTING.md`'s release section, `.github/workflows/publish.yml`. It decides
+   the files to bump, the tag format, and the push and publish order.
+2. Confirm the version and the reason with the user. Say the reason in SemVer's
+   terms: a fix with no surface change is a patch, an additive surface is a minor, a
+   breaking change is a major — and ask when a project in `0.x` treats minors as the
+   breaking channel, because many do. Never infer a version from the size of the
+   diff and never raise the version in the release without the user's word for it.
+
+## Move the entries
+
+A project that keeps no changelog file — only GitHub or GitLab releases, or release
+notes a tool generates — has nothing to move: say so and stop, and do not create the
+file as part of a release. The rest of this section assumes one exists.
+
+A file a tool generates is moved by that tool, not here: `changeset version`,
+`git-cliff --tag`, `release-please`, `semantic-release`, or whatever the project's
+release document names. In that case this mode's job is to check the result — the
+version, the dated heading, the category order, the link refs — and to report the step
+that is still owed, never to edit the generated file.
+
+- Read `[Unreleased]` and check it is what the release contains: everything since
+  the last tag, nothing that already shipped.
+- Move every entry under `## [X.Y.Z] - YYYY-MM-DD`, categories in the file's own
+  order and spelling, creating only the categories that hold an entry. Keep each
+  bullet's text; a release is a move, not a rewrite.
+- Leave `[Unreleased]` present and empty, unless the file's preamble says it is
+  removed between releases. An empty heading is how the next change knows where to
+  land.
+- Update the link references: `[Unreleased]` now compares from the new tag, and the
+  new version gets a reference in the file's existing style (`compare/vOLD...vNEW`
+  or `releases/tag/vNEW`).
+- Bump the version where the project keeps it — usually one manifest, sometimes a
+  lockfile, a version file, and an install pin. The build manifest and the newest
+  dated heading must agree, or a consistency guard fails.
+- The release commit holds the changelog move, the version bump, and the link refs.
+  No behavior, no new entries, no unrelated docs: a release commit that also changes
+  code cannot be diffed as a release.
+
+## Finish
+
+- Run the project's release guard (often `release.test.ts` or a `changelog` check),
+  then the project's full check. The guard is the one test that names a version, so
+  run it directly while iterating.
+- Then, in the project's order and only with explicit approval for that push: commit,
+  tag (`vX.Y.Z`, annotated where the project does that), push the tag together with
+  the branch — a branch push that lands before its tag races the checkout that
+  asserts they agree — and publish through the project's pipeline, not a local
+  publish.
+- The release body is that section verbatim, heading included. Do not add a summary,
+  a thank-you, or a rewrite of the bullets a reader already has.
+
+## Verify a release you did not cut
+
+A release is a chain of steps, and the last one can sit for hours waiting on a
+pipeline's approval, so checking a tagged version is its own job. It touches no file:
+open the tag, read each of these, and report the line.
+
+- The tag's own manifest — `git show vX.Y.Z:package.json`, or the equivalent — because
+  the publish job proves that before it publishes, not the branch's.
+- The newest dated heading, and the project's release guard where it has one.
+- The link refs: `[Unreleased]` compares from the new tag, and `X.Y.Z` points at it.
+- Whatever the release document bumps in the same commit — an install pin, a version
+  stamped in a guide, a captured image.
+- The release body against the section the project's own tooling prints, never against
+  memory.
+- The publish run itself: a workflow that checks out `vX.Y.Z` publishes the tagged tree
+  whatever ref the dispatch named, so what remains is its environment approval and the
+  registry version after it.
+
+## After
+
+If a shipped change turns out to have no bullet, do not edit the released section.
+Record the gap to the user and add a bullet to `[Unreleased]` for the next release,
+naming the fix; a released section is a record of what was published, not a draft.

package/skills/project-docs/references/roadmap.md

@@ -0,0 +1,93 @@
+# Roadmap
+
+The roadmap is the one document that describes the tree rather than the last release,
+so it goes stale two ways: it keeps what already shipped, and it promises what the
+tree already does differently. This mode re-derives it and deletes what is done. It
+never decides what matters.
+
+Read [`discovery.md`](./discovery.md) first for the file, the item form, the buckets
+and their caps, the ledger, and the stated rule for a shipped item. A file with no ids
+and no buckets is not a defect to fix: it gets the deletion pass below, and no invented
+id scheme.
+
+## Re-derive before editing
+
+```bash
+git log --oneline <last-tag>..HEAD
+```
+
+Use `HEAD`, or the branch the project documents as its default — a project's branch is
+not always `main`. Read the changelog's newest dated heading beside it: the window is
+everything that landed, and the release is what a reader has. A project with no tags has
+no window at all: re-derive from the newest dated heading and the tree instead, and say
+that is what you did. An item is not "shipped" because a branch merged — the tree
+decides whether the promise is met, the maintainer decides whether it shipped.
+
+Then, for every item in the file, open the code it names. Three outcomes:
+
+- **The tree does it.** Delete the item, and record the reason where it was — one line
+  is enough, and it is what stops the same item being re-added next review. A file with
+  its own history or "previous `Now`" section gets the note there instead.
+- **The tree does part of it.** Rewrite the item down to the part still missing. A
+  condensed item is a finding; a deleted one that was not done is a lost promise.
+- **The tree contradicts it** — the approach changed, or the problem was solved another
+  way. Delete it with that reason. Parking it as "still available" describes a tree
+  that no longer exists.
+
+Never tick an item and leave it. A checklist with finished rows is a changelog written
+in the wrong file, and it is what the project's own rule usually forbids.
+
+## Renumber and fix every citation
+
+After a deletion, ids break in four places, and all four move in the same edit:
+
+- The item headings, so a prefix's numbers stay contiguous.
+- Every reference elsewhere in the file — a ledger row, a "if only two things ship"
+  list, a `P1–P3` range whose endpoints both still resolve.
+- Every mention in the guides, the front door, and the instruction file, which is what
+  a stale id breaks first because nothing validates it.
+- The relative links and `path:line` citations the items carry.
+
+Change an id only when a deletion forces it. Renumbering for tidiness loses the
+citations the file's readers already have.
+
+## Keep the buckets honest
+
+- A bucket over the cap the file states is a priority list that stopped being one:
+  demote an item rather than widening the cap.
+- A horizon whose exit condition has been met gets rewritten, not left as decoration.
+- A ledger row whose items have all closed is closed; an open item with no ledger row
+  gets one, or it is not part of a promise.
+
+## Numbers belong to the tree
+
+Any count the file states about the code — modules, extensions, tools, screens — is
+read from the tree, not adjusted by hand. A project that derives it in a guard has the
+count already: run the guard, and change the tree or the guard, never the number. A
+project that does not is a finding for the audit, and the fix is a guard.
+
+## Non-goals are decisions
+
+The non-goal list carries a reason per entry. When the changelog, a discussion, or the
+audit contradicts one, that is a decision for the maintainer: list it, with the
+evidence, and ask. Reversing a documented non-goal is not a roadmap edit, and an item
+that needs one reversed says so in the item.
+
+## Report
+
+Every edit named by the item it touched: deleted, rewritten, renumbered, or cited.
+Then the items that need a decision, one line each. A roadmap whose window changed and
+whose items are all still true is a valid result — say so instead of finding work to
+look thorough.
+
+## In this repository
+
+- `ROADMAP.md` states its own rules under *How items are ordered*: an item is deleted
+  when it ships, never ticked, and `Now` and `Next` hold at most ten.
+- `test/roadmap.test.ts` pins the mechanical half — id uniqueness and contiguity, the
+  links, the citations, and the caps — and cannot tell that an item has shipped, which
+  is why the file states that rule in prose.
+- `AGENTS.md` requires the deletion or renumbering in the same commit as the change.
+
+The paths are named, not linked: a skill is installed into projects that do not
+contain them, so a link would point nowhere from the place it is read.