@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, serve, subagent, job, watch, web-access, file-browse, file-open, file-read, check, memory, context, session-bus, board, team, wechat, and bytefly.",
   "keywords": [
     "pi-package",
@@ -84,6 +84,11 @@
     "lib/**",
     "skills/**",
     "themes/**",
+    "assets/screens/board.png",
+    "assets/screens/chrome.png",
+    "assets/screens/file-browse.png",
+    "assets/screens/plan-review.png",
+    "assets/screens/plan.png",
     "!**/*.test.ts"
   ],
   "publishConfig": {

package/skills/init/SKILL.md

@@ -13,7 +13,7 @@ cannot show; the repository supplies every command, path, and convention that ca
 be verified. Plan mode is the review gate: no write happens before approval.
 
 `/skill:init` loads this skill. If plan mode is not active, call
-`enter_plan_mode` and wait for confirmation. Keep the interview and the plan
+`plan` with action `enter` and wait for confirmation. Keep the interview and the plan
 review in that order; do not write the file early to save a step. A declined plan
 mode ends the skill: stop and explain, rather than writing directly.
 
@@ -29,7 +29,7 @@ mode ends the skill: stop and explain, rather than writing directly.
         └─> draft: new file, exact edits, or an honest no-op
         └─> quality gate
         └─> plan outline with ## Steps and ## Verification
-        └─> write_plan ──> exit_plan_mode
+        └─> plan · write ──> plan · exit
                              ├─ not approved ──> refine the same plan
                              └─ approved ──────> write/edit the target
                                                  └─ read back + quality gate
@@ -147,7 +147,7 @@ evidence, not as a replacement for reading the repository.
 
 ## 5. Plan and review
 
-- Save the proposal with `write_plan` in the documented outline. The plan must
+- Save the proposal with `plan` action `write` in the documented outline. The plan must
   include:
   - `## Goal` — the outcome for the instruction file;
   - `## Context` — the sourced evidence sheet, the effective-file finding, and the
@@ -162,9 +162,9 @@ evidence, not as a replacement for reading the repository.
   - `## Verification` — the project's own check when it declares one (`run_check`,
     or the narrower docs or structure test that guards the instruction file), then
     reading the written file back against the checklist.
-- Call `exit_plan_mode` with the returned path.
+- Call `plan` action `exit` with the returned path.
 - If the user refines or rejects the plan, stay in plan mode, rewrite the same
-  plan file with `write_plan` (`plan_path`), and present it again.
+  plan file with `plan` action `write` (`plan_path`), and present it again.
 - No write to the target may happen before approval.
 
 ## 6. Apply and verify

package/skills/next/SKILL.md

@@ -15,11 +15,9 @@ project wins.
 The conversation decides where the candidates come from (section 3); the request
 decides only what to ask and where to look.
 
-Two sibling skills, where they are installed, own a narrower question: an audit
-of *where to refactor* is `refactor`, and *whether a document still tells the
-truth* — the changelog, the roadmap, the front door — is `project-docs`. When the
-request is already scoped to one of those, name the skill that answers it and
-hand over, instead of returning a generic list.
+A sibling skill, where it is installed, owns a narrower question: an audit of
+*where to refactor* is `refactor`. When the request is already scoped to it, name
+that skill and hand over, instead of returning a generic list.
 
 A next-steps block that the host draws itself is not this skill's output: that is
 the reply's suggested follow-up, a turn-level hint. This skill inspects state, so

package/extensions/board/seat.ts

@@ -1,28 +0,0 @@
-/**
- * The seat: the name the page serves as, and the actor it is shown as.
- *
- * A page outlives the session that opened it — a `/resume`, a rename, or a fresh
- * session taking the page over would otherwise change who the page says it is. So the
- * page is a *seat* rather than a session: one fixed name, one fixed id derived from it,
- * and the same identity however many sessions have served it.
- *
- * The page writes nothing, so the id decides no ownership: it is what the page's own
- * roster and the `you` chip are read against, and it keeps a page's reads the same
- * across a handover. The board's tools write as the session — which is why the label is
- * shared with the session serving the page and the ids are not.
- */
-
-import type { Actor } from "../../lib/board/rules.ts";
-import { normalizeLabel } from "../../lib/session-label.ts";
-
-/** The name a repository's page always serves under, so the lead is a role and not a session. */
-export const DEFAULT_SEAT = "team-lead";
-
-/** The prefix of a page's actor id, so one is never mistaken for a session id. */
-export const SEAT_ID_PREFIX = "board:";
-
-/** The actor a page reads as: the seat, and an id derived from it. */
-export function pageActor(label: string = DEFAULT_SEAT): Actor {
-	const seat = normalizeLabel(label, DEFAULT_SEAT);
-	return { id: `${SEAT_ID_PREFIX}${seat.toLowerCase()}`, label: seat };
-}

package/extensions/todo/tui.ts

@@ -1,212 +0,0 @@
-/**
- * Terminal rendering for the todo list.
- *
- * `todoRow` is the shared item layout used by the persistent widget and the
- * `/todos` screen. Two tiny components wrap it: a non-interactive widget for
- * `ctx.ui.setWidget()`, and a scrollable, dismissible list for `ctx.ui.custom()`.
- */
-
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
-import { clampScroll, fitRows, formatRange, isCloseKey, navigateScroll, wheelDelta } from "../../lib/tui/cursor.ts";
-import { dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
-import { clip } from "../../lib/tui/columns.ts";
-import { emptyState, listRow } from "../../lib/tui/rows.ts";
-import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { RenderCache } from "../../lib/tui/render-cache.ts";
-import { titleRule } from "../../lib/tui/rules.ts";
-import { paint } from "../../lib/tui/tokens.ts";
-import {
-	progressCount,
-	progressSummary,
-	todoGlyphChar,
-	todoGlyphRole,
-	todoLabel,
-	todoLabelRole,
-	todoLabelText,
-	todoRailLines,
-	type TodoRailInput,
-} from "./format.ts";
-import { currentTodo } from "./state.ts";
-import type { Todo } from "./types.ts";
-
-/** Widget key used with `ctx.ui.setWidget()`. */
-export const WIDGET_KEY = "todo-widget";
-
-/** Items the `/todos` screen shows when the terminal height is unknown. */
-const SCREEN_DEFAULT_ITEMS = 12;
-
-/** One indented item line, clipped to `width`. */
-function todoRow(todo: Todo, theme: Theme, width: number): string {
-	return listRow(theme, width, {
-		glyph: todoGlyphChar(todo),
-		glyphRole: todoGlyphRole(todo),
-		label: todoLabelText(todo),
-		labelRole: todoLabelRole(todo),
-	});
-}
-
-/**
- * One-line widget summary: progress plus the current item, or a completion note
- * when nothing is open. Label-first and glyph-free, matching the `goal` and
- * `jobs` widgets. Callers clip it to the available width.
- */
-function todoLine(todos: Todo[], theme: Theme): string {
-	const head = `${paint(theme, "accent", "Todos")}${paint(theme, "faint", SEPARATORS.item)}${paint(theme, "faint", progressCount(todos))}`;
-	const current = currentTodo(todos);
-	if (!current) return `${head} ${paint(theme, "faint", "completed")}`;
-	return `${head}${paint(theme, "faint", SEPARATORS.item)}${todoLabel(current, theme)}`;
-}
-
-/**
- * Transcript result block: the indented glyph rail, wrapping at the render width.
- *
- * `render` runs on every frame Pi draws, for every block in the transcript, so the
- * rail is memoized on the width (`RenderCache`) and rebuilt only when
- * `setInput` hands over a new list or `invalidate` says the theme moved. The
- * caller must go through `setInput`: mutating a list in place would leave the
- * block showing what it drew last.
- */
-export class TodoResult implements Component {
-	private input: TodoRailInput;
-	private theme: Theme;
-	private readonly cache = new RenderCache();
-
-	constructor(input: TodoRailInput, theme: Theme) {
-		this.input = input;
-		this.theme = theme;
-	}
-
-	/** Update in place so the transcript can reuse this component across renders. */
-	setInput(input: TodoRailInput, theme: Theme): void {
-		this.input = input;
-		this.theme = theme;
-		this.cache.invalidate();
-	}
-
-	invalidate(): void {
-		this.cache.invalidate();
-	}
-
-	render(width: number): string[] {
-		const w = Math.max(1, width);
-		return this.cache.lines(w, undefined, () => this.build(w));
-	}
-
-	private build(w: number): string[] {
-		// The leading blank line separates the rail from the call header, matching
-		// the built-ins' header/output gap.
-		return ["", ...todoRailLines(this.input, this.theme, w)];
-	}
-}
-
-/** Persistent one-line widget shown above the editor while the list has work. */
-export class TodoWidget implements Component {
-	constructor(
-		private readonly todos: Todo[],
-		private readonly theme: Theme,
-	) {}
-
-	invalidate(): void {}
-
-	render(width: number): string[] {
-		if (this.todos.length === 0) return [];
-		return [truncateToWidth(todoLine(this.todos, this.theme), Math.max(1, width), "…")];
-	}
-}
-
-/** Dismissible, scrollable list opened by `/todos`; reads the live list on each render. */
-export class TodoListComponent implements Component {
-	private scrollTop = 0;
-	/** Rows shown at once; recomputed from the terminal height on every render. */
-	private visible = SCREEN_DEFAULT_ITEMS;
-
-	constructor(
-		private readonly getTodos: () => Todo[],
-		private readonly theme: Theme,
-		private readonly onClose: () => void,
-		private readonly requestRender: () => void,
-		private readonly viewportRowsSource?: ViewportRowsSource,
-	) {}
-
-	/** The live list; re-read on each render so an open screen follows changes. */
-	private get todos(): Todo[] {
-		return this.getTodos();
-	}
-
-	private get maxScroll(): number {
-		return Math.max(0, this.todos.length - this.visible);
-	}
-
-	private setScroll(next: number): void {
-		const clamped = clampScroll(next, this.todos.length, this.visible);
-		if (clamped === this.scrollTop) return;
-		this.scrollTop = clamped;
-		this.requestRender();
-	}
-
-	handleInput(data: string): void {
-		if (isCloseKey(data)) {
-			this.onClose();
-			return;
-		}
-		// `g`/`G` jump to the ends, matching the `/jobs` and plan screens.
-		if (data === "g") {
-			this.setScroll(0);
-			return;
-		}
-		if (data === "G") {
-			this.setScroll(this.maxScroll);
-			return;
-		}
-		const next = navigateScroll(data, this.scrollTop, this.todos.length, this.visible);
-		if (next !== undefined) this.setScroll(next);
-	}
-
-	/** Wheel scrolling moves the list, matching the other list screens. */
-	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
-		const delta = wheelDelta(event);
-		if (delta === undefined) return undefined;
-		this.setScroll(this.scrollTop + delta);
-		return { handled: true };
-	}
-
-	invalidate(): void {}
-
-	render(width: number): string[] {
-		const w = Math.max(1, width);
-		const header = titleRule(this.theme, w, "Todos");
-
-		if (this.todos.length === 0) {
-			return dockListFrame({
-				theme: this.theme,
-				width: w,
-				header,
-				body: emptyState(this.theme, w, { label: "No todos yet. Ask the agent to plan some work." }),
-				hint: screenHint(this.theme, w, ["Esc close"]),
-			});
-		}
-
-		// header, summary, blank, blank-after-list, hint, closing rule
-		const chrome = 6;
-		this.visible = fitRows(this.viewportRowsSource, this.todos.length, chrome, SCREEN_DEFAULT_ITEMS);
-		this.scrollTop = clampScroll(this.scrollTop, this.todos.length, this.visible);
-
-		const end = Math.min(this.todos.length, this.scrollTop + this.visible);
-		const body: string[] = [];
-		for (let i = this.scrollTop; i < end; i++) body.push(todoRow(this.todos[i], this.theme, w));
-
-		return dockListFrame({
-			theme: this.theme,
-			width: w,
-			header,
-			summary: clip(`  ${paint(this.theme, "meta", progressSummary(this.todos))}`, w),
-			body,
-			range:
-				this.scrollTop > 0 || end < this.todos.length
-					? formatRange(this.theme, w, { start: this.scrollTop, end, total: this.todos.length })
-					: undefined,
-			hint: screenHint(this.theme, w, ["Esc close", "↑/↓ or k/j scroll", "PgUp/PgDn", "g/G or Home/End"]),
-		});
-	}
-}

package/lib/tui/index.ts

@@ -1,34 +0,0 @@
-/**
- * The Bytefly terminal design system: one kit for every interactive surface.
- *
- * Import from `lib/tui/index.ts` rather than a leaf module so the surface reads
- * as one system. The leaves: `tokens.ts` (semantic role -> theme token),
- * `glyphs.ts` (the shared glyph, separator, and status-key vocabulary),
- * `chrome.ts` (screen frame, hints, viewport, overlay), `cursor.ts` (list
- * scroll and navigation), `columns.ts` (width math), `rules.ts` (the rule
- * grammar), `rows.ts` (list rows, checkboxes, chips, empty states), `gauge.ts`
- * (the context gauge), `indent.ts` (the transcript block indent), and
- * `line-pane.ts` (the scrollable log/match pane), and
- * (the shared tool-transcript kit: call title, width-safe call line,
- * sanitized error, and the running timer), and `render-cache.ts` (the
- * per-instance line memo a derived component renders through).
- *
- * Value-only, like every `lib/` module: pure functions, constants, and classes,
- * with no module-level state.
- */
-
-export * from "./chrome.ts";
-export * from "./columns.ts";
-export * from "./confirm.ts";
-export * from "./cursor.ts";
-export * from "./dock-screen.ts";
-export * from "./gauge.ts";
-export * from "./glyphs.ts";
-export * from "./line-pane.ts";
-export * from "./indent.ts";
-export * from "./render-cache.ts";
-export * from "./rows.ts";
-export * from "./rules.ts";
-export * from "./status-controller.ts";
-export * from "./tokens.ts";
-export * from "./tool.ts";

package/skills/project-docs/SKILL.md

@@ -1,133 +0,0 @@
----
-name: project-docs
-description: "Keep a project's documents true to its tree: a read-only audit of the front door, the roadmap, the contributor path, and the changelog against the code and against each other, then one mode per act that writes — record a changelog bullet in the same commit as the change, curate a release section from the project's own rules, delete a shipped roadmap item and renumber, and sync the README front door. Use when a doc claim looks stale, before a release, or when a change lands owing an entry; prioritisation stays with `next` and structure with `refactor`."
-compatibility: "Bun for scripts/state.ts; git for the roadmap and the audit."
----
-
-# Keep the docs true to the tree
-
-Goal: the documents a reader trusts — the front door, the plan of record, the record
-of what shipped, and the contributor path — so a claim the tree no longer meets is
-found, and each act that needs writing has one owner. This is a procedure, not a
-second policy: the project's instructions and release document win, and where they
-are silent this file says ask.
-
-A bare `/skill:project-docs` reads and reports. Nothing is written until a mode is
-named.
-
-## Pick the mode
-
-| The words after `/skill:project-docs` | Mode | Owns | Writes | Follow |
-|---|---|---|---|---|
-| nothing | audit | every document, read-only | no | [`references/audit.md`](./references/audit.md) |
-| `changelog` | changelog | the unreleased window of the changelog | yes | [`references/changelog.md`](./references/changelog.md) |
-| `release <version>` | release | one version's section and link refs | yes | [`references/release.md`](./references/release.md) |
-| `roadmap` | roadmap | items, ids, and buckets | yes | [`references/roadmap.md`](./references/roadmap.md) |
-| `readme` | readme | the front door and its mirror | yes | [`references/readme.md`](./references/readme.md) |
-| anything else | refuse, and name the five | — | no | — |
-
-Audit is the default because the skill spans four documents: a bare invocation that
-writes would edit a document nobody asked about.
-
-## Start here
-
-Read [`references/discovery.md`](./references/discovery.md) first, in every mode. It
-finds the project's documents, the version's single source, the changelog's local
-conventions, the roadmap's rules, the check command, and the guards by name. State
-that profile in one paragraph before writing anything; it is how a misread is caught
-in a line instead of in a diff.
-
-For the changelog's mechanical half, run the state script, resolved against this
-skill's own directory:
-
-```bash
-bun <skill>/scripts/state.ts <project-root>
-```
-
-It prints the changelog file it found, the last tag and the commits since it, the
-`[Unreleased]` categories with counts and line numbers, the empty and duplicate
-headings, the scope prefixes in use, and the link refs. That is the state; read the
-diffs for judgement, not for counting. When it finds no changelog, no repository, or no
-Bun to run it with, say so and fall back to discovery by hand. The git commands these
-references give are git's; use the project's VCS where it differs.
-
-## Non-negotiables
-
-1. **Discover, don't impose.** The project's document set, category spelling, scope
-   prefix, bullet shape, item ids, bucket caps, and release procedure are the rules.
-   State the profile in one paragraph, and ask when two sources disagree.
-2. **One bullet per user-visible outcome**, in the same commit as the change. A
-   feature and the bug it fixed before release are one bullet; two observable
-   changes are two.
-3. **A shipped item is deleted here, with its reason, never ticked.** A roadmap that
-   keeps what already landed describes a tree that no longer exists.
-4. **One id per thing, across every document.** A README row, a roadmap item, and a
-   changelog entry that name the same feature use the same name. A mismatch is
-   reported, never renamed.
-5. **A judgement is not a finding.** Positioning, priority, dates, non-goals, and
-   contribution policy are the maintainer's: list them and ask.
-6. **One owner per artefact.** The changelog belongs here; what to do next belongs to
-   the `next` skill; structure belongs to `refactor`.
-
-## Modes
-
-- **Audit** — read-only, five faces: the tree against the docs, the docs against each
-  other, the changelog's commit window, the roadmap's own ids and caps, and the front
-  door's examples. Every finding names the mode that fixes it.
-- **Changelog** — one bullet under the project's category for one user-visible
-  outcome, re-reading the file first. It never decides whether something has already
-  shipped.
-- **Release** — only for a version the user named, and only after the project's
-  release document has been read; everything after moving the entries follows it.
-- **Roadmap** — re-derived from the commits since the last tag rather than from the
-  last tag: shipped items deleted, ids renumbered, every citation and link fixed.
-- **Readme** — the front door's catalog rows, counts, examples, and mirror, kept equal
-  to the tree; deep detail stays in the project's own guides.
-
-## Handover
-
-- **A changelog entry, an audit, or a release** is this skill: do not look for
-  another one.
-- **What to do next** is `next`, where it is installed: it triages loose work and
-  broken promises across the project, and its candidates are not a doc audit's findings.
-- **A structural change to the docs or the code** is `refactor`, where it is installed.
-- **Who may contribute, and how** is a decision for the maintainer: ask, and edit
-  nothing until it is answered.
-
-## Report
-
-Open with the profile in one paragraph, then:
-
-- **Stale** — the claim, `path:line`, the evidence in the tree, and the mode that
-  fixes it.
-- **Missing** — a document, a row, an entry, or an item the project's own rules call
-  for and the tree does not have.
-- **Suggested edit** — the diff or the exact replacement, for the mechanical items
-  only, and never applied until the user says so.
-- **Needs a decision** — one line each: the question, and what it changes.
-
-Nothing found is a valid result, and the whole report may be empty. Say what was
-checked and stop; an audit that invents four entries to look thorough is worse than
-one that finds nothing.
-
-## Quality gate
-
-- The project's own check passes, including any guard on the release window, the
-  documentation's parity, or the roadmap's ids.
-- Every edit names the document and the line, and every bullet names a scope in the
-  project's spelling and a user outcome.
-- No judgement is smuggled into a diff, and the changelog entry is in the change's
-  own commit.
-
-## Stop conditions
-
-- The project has only a README, no roadmap, and no changelog: say so. Whether to
-  adopt one is the maintainer's decision, not an edit.
-- The changelog is generated — by `semantic-release`, `changesets`, `git-cliff`, or a
-  step in the release workflow: the entry lands upstream, in the commit message, a
-  changeset fragment, or the generator's config. Never hand-edit the file.
-- Two sources disagree — two changelogs, a version in two places, a roadmap item the
-  changelog contradicts: ask instead of averaging them.
-- The change would reverse a documented non-goal: it is a decision, and the item is
-  listed rather than written.
-- The request is really triage or a refactor: name the sibling skill and stop.

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

@@ -1,131 +0,0 @@
-# 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.