@gavin-hu/my-pi-agent 0.16.0 → 0.17.0

package/lib/web/runtime.ts

@@ -10,10 +10,16 @@
 /** localStorage key for the browser's explicit light/dark choice, shared by both surfaces. */
 export const WEB_THEME_STORAGE_KEY = "pi-web-theme";
 
+/**
+ * Where both routers serve {@link THEME_JS}. `docHead` emits the same path, so
+ * the script tag and the route cannot drift apart.
+ */
+export const THEME_JS_PATH = "/theme.js";
+
 /**
  * A tiny head script that applies the saved theme before the body is painted,
- * so an explicit choice does not flash the system theme on load. Served as
- * `/theme.js` and shared by both pages.
+ * so an explicit choice does not flash the system theme on load. Served at
+ * {@link THEME_JS_PATH} and shared by both pages.
  */
 export const THEME_JS = `(function(){try{var t=localStorage.getItem("${WEB_THEME_STORAGE_KEY}");if(t==="light"||t==="dark")document.documentElement.setAttribute("data-theme",t);}catch(e){}})();`;
 
@@ -67,52 +73,124 @@ export const THEME_TOGGLE_JS = String.raw`(function () {
   }
 })();`;
 
+/** Options for {@link dialogScript}. */
+export interface DialogOptions {
+	/** Id of the dialog root: the element carrying `.bf-dialog` and `hidden`. */
+	dialogId: string;
+	/** Id of the dialog's own close button, when the markup has one. */
+	closeId?: string;
+	/** Id of the page's trigger button, when the dialog opens from one. */
+	triggerId?: string;
+	/** Property to expose on `window`, so the page can open and close it. */
+	globalName?: string;
+}
+
+/** Everything inside a dialog that can take focus, in DOM order. */
+const FOCUSABLE =
+	'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+
 /**
- * The `?` keyboard sheet's wiring, shared by both clients.
- *
- * It owns the sheet's pointer behavior — the page's trigger button, the sheet's
- * own close button, and a click on the backdrop — and nothing else: each page
- * keeps its own keyboard policy in its keydown handler, because the two differ
- * (the review peels `Esc` through a composer first), and calls in through
- * `window.bfKeys`.
+ * The wiring every modal in the kit shares: open and close, the backdrop, the
+ * `Tab` trap, `Esc`, and focus returning to whatever opened it.
  *
- * `triggerId` is the page's own shortcut button, since browse opens the sheet
- * from `#keys-open` and review from `#shortcuts`. The sheet's ids are the fixed
- * contract in `keysSheet` (`lib/web/markup.ts`).
+ * A dialog is modal before this script runs too — `aria-modal` and `hidden` are
+ * in the markup — so a page without JavaScript still shows it closed rather
+ * than half-open.
  *
- * Value-only: the open state is the dialog's own `hidden` attribute, so this
- * module holds nothing.
+ * Value-only: the open state is the dialog's own `hidden` attribute, and the
+ * element that opened it lives in this script's closure.
  */
-export function keysDialogScript(triggerId: string): string {
+export function dialogScript(options: DialogOptions): string {
+	const trigger = options.triggerId ? `document.getElementById("${options.triggerId}")` : "null";
+	const closer = options.closeId ? `document.getElementById("${options.closeId}")` : "null";
+	const expose = options.globalName
+		? `window.${options.globalName} = {
+    open: function () { toggle(true); },
+    toggle: toggle,
+    close: function () { toggle(false); },
+    isOpen: isOpen
+  };`
+		: "";
 	return `(function () {
   "use strict";
-  var dialog = document.getElementById("keys-dialog");
+  var dialog = document.getElementById("${options.dialogId}");
   if (!dialog) return;
+  var opener = null;
 
   function isOpen() {
     return !dialog.hidden;
   }
+  // A button inside a closed dialog has no boxes, so the rects are the test that
+  // survives a hidden attribute, a collapsed panel, and a stylesheet swap alike.
+  function focusables() {
+    return Array.prototype.filter.call(dialog.querySelectorAll('${FOCUSABLE}'), function (node) {
+      return node.getClientRects && node.getClientRects().length > 0;
+    });
+  }
   function toggle(force) {
     var open = force === undefined ? dialog.hidden : force;
+    if (open === isOpen()) return;
     dialog.hidden = !open;
     if (open) {
-      var close = document.getElementById("keys-close");
-      if (close && close.focus) close.focus();
+      opener = document.activeElement;
+      var first = focusables()[0];
+      if (first) first.focus();
+    } else if (opener && opener.focus) {
+      opener.focus();
+      opener = null;
     }
   }
 
-  var trigger = document.getElementById("${triggerId}");
+  var trigger = ${trigger};
   if (trigger) trigger.addEventListener("click", function () { toggle(); });
-  var closer = document.getElementById("keys-close");
+  var closer = ${closer};
   if (closer) closer.addEventListener("click", function () { toggle(false); });
   dialog.addEventListener("click", function (event) {
     if (event.target === dialog) toggle(false);
   });
 
-  window.bfKeys = {
-    toggle: toggle,
-    close: function () { toggle(false); },
-    isOpen: isOpen
-  };
+  // Tab cycles inside the dialog: leaving it would put focus behind the scrim,
+  // where the page looks inert but is not.
+  dialog.addEventListener("keydown", function (event) {
+    if (event.key !== "Tab") return;
+    var nodes = focusables();
+    if (nodes.length === 0) { event.preventDefault(); return; }
+    var first = nodes[0];
+    var last = nodes[nodes.length - 1];
+    if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  });
+
+  // Capture, so Esc closes the dialog before a page handler peels another layer.
+  document.addEventListener("keydown", function (event) {
+    if (event.key !== "Escape" || !isOpen()) return;
+    toggle(false);
+    event.preventDefault();
+    event.stopPropagation();
+  }, true);
+
+  ${expose}
 })();`;
 }
+
+/**
+ * The `?` keyboard sheet's wiring, shared by both clients.
+ *
+ * `triggerId` is the page's own shortcut button, since browse opens the sheet
+ * from `#keys-open` and review from `#shortcuts`. The sheet's ids are the fixed
+ * contract in `keysSheet` (`lib/web/markup.ts`), and the page's keydown handler
+ * calls in through `window.bfKeys`.
+ */
+export function keysDialogScript(triggerId: string): string {
+	return dialogScript({
+		dialogId: "keys-dialog",
+		closeId: "keys-close",
+		triggerId,
+		globalName: "bfKeys",
+	});
+}

package/lib/web/tokens.ts

@@ -21,12 +21,11 @@ interface ThemeJson {
 const DARK = darkTheme as unknown as ThemeJson;
 const LIGHT = lightTheme as unknown as ThemeJson;
 
-/** Web custom property -> Bytefly theme var. `--accent-soft` is derived. */
+/** Web custom property -> Bytefly theme var. `--accent-soft`, `--on-accent`, `--scrim`,
+ * and `--shadow` are derived, so no appearance-only colour enters the kit. */
 const VAR_TOKENS: ReadonlyArray<readonly [string, string]> = [
 	["--canvas", "canvas"],
 	["--surface", "canvasSubtle"],
-	["--surface-raised", "selectionBg"],
-	["--selected", "selectionBg"],
 	["--border", "borderMuted"],
 	["--border-strong", "border"],
 	["--text", "text"],
@@ -90,19 +89,34 @@ function rgba(hex: string, alpha: number): string {
 	return `rgba(${r},${g},${b},${alpha})`;
 }
 
+/**
+ * Overlays are not palette entries: a scrim dims what is behind it and a shadow
+ * lifts a panel off it, so each appearance needs its own alpha rather than the
+ * theme's colours.
+ */
+const OVERLAYS: Record<"dark" | "light", { scrim: string; shadow: string }> = {
+	dark: { scrim: "rgba(0,0,0,.5)", shadow: "0 8px 24px rgba(0,0,0,.4)" },
+	light: { scrim: "rgba(15,23,42,.3)", shadow: "0 8px 24px rgba(15,23,42,.14)" },
+};
+
 /** The full custom-property set for one appearance. */
-function paletteOf(theme: ThemeJson, accentAlpha: number): Record<string, string> {
+function paletteOf(theme: ThemeJson, appearance: "dark" | "light", accentAlpha: number): Record<string, string> {
 	const palette: Record<string, string> = {};
 	for (const [token, name] of VAR_TOKENS) palette[token] = theme.vars[name];
 	palette["--accent-soft"] = rgba(palette["--accent"] ?? "#000000", accentAlpha);
+	// A label on the accent fill is the canvas colour: a light blue button takes dark
+	// text, and the same derivation gives white on the light theme's darker blue.
+	palette["--on-accent"] = palette["--canvas"];
+	palette["--scrim"] = OVERLAYS[appearance].scrim;
+	palette["--shadow"] = OVERLAYS[appearance].shadow;
 	for (const [token, name] of SYNTAX_TOKENS) palette[token] = resolve(theme, theme.colors[name] ?? "");
 	return palette;
 }
 
 /** Every token value per appearance, for tests and for building the CSS. */
 export const WEB_THEME_TOKENS: { dark: Record<string, string>; light: Record<string, string> } = {
-	dark: paletteOf(DARK, 0.15),
-	light: paletteOf(LIGHT, 0.1),
+	dark: paletteOf(DARK, "dark", 0.15),
+	light: paletteOf(LIGHT, "light", 0.1),
 };
 
 /** `a{color:var(--tok-keyword)}…` for each syntax token. */
@@ -125,4 +139,6 @@ export const WEB_THEME_CSS = `:root{${declarations(WEB_THEME_TOKENS.dark)};${SCA
 :root[data-theme="light"]{${declarations(WEB_THEME_TOKENS.light)};color-scheme:light}
 :root[data-theme="dark"]{color-scheme:dark}
 @media (prefers-color-scheme:light){:root:not([data-theme]){${declarations(WEB_THEME_TOKENS.light)};color-scheme:light}}
-${SYNTAX_RULES}`;
+${SYNTAX_RULES}
+/* Paper is white: print the light palette whatever the screen is showing. */
+@media print{:root{${declarations(WEB_THEME_TOKENS.light)};color-scheme:light}}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, file-read, check, memory, context, wechat, and bytefly.",
   "keywords": [
     "pi-package",
@@ -127,6 +127,7 @@
     "compat:versions": "bun run scripts/peer-versions.ts",
     "bench:render": "bun run scripts/render-bench.ts",
     "screenshot:file-browse": "bun run scripts/file-browse-shot.ts",
+    "screenshot:plan-flow": "bun run scripts/plan-flow-shot.ts",
     "screenshot:plan": "bun run scripts/plan-review-shot.ts",
     "screenshot:tools": "bun run scripts/tool-renderings.ts gallery assets/tool-renderings.png",
     "screenshot:tool-pngs": "bun run scripts/tool-renderings.ts tools assets/tools",
@@ -158,6 +159,7 @@
     "@types/bun": "latest",
     "@types/qrcode": "^1.5.5",
     "get-east-asian-width": "^1.6.0",
+    "playwright-core": "^1.64.1",
     "typebox": "^1.3.27",
     "typescript": "^5.6.0"
   }

package/skills/changelog/SKILL.md

@@ -1,48 +1,37 @@
 ---
 name: changelog
-description: "Maintain a Keep a Changelog file: draft the candidate bullet before implementation, record one user-visible bullet in the same commit, audit commits since the last tag for missing or weak entries, and curate a release section from the project's own rules. Use when planning, writing, or auditing a changelog or preparing a release, not for ordinary code edits."
+description: "Maintain a Keep a Changelog file: record one user-visible bullet in the same commit, audit commits since the last tag for missing or weak entries, and curate a release section from the project's own rules. Use when writing, auditing, or releasing a changelog, not for ordinary code edits."
 ---
 
 # Maintain the changelog
 
 This is a procedure, not a second policy. Read the project's instructions first;
-where they disagree with this skill, the project wins. There are four modes:
-**draft** (before the code exists), **record** (the default once it does),
-**audit**, and **release**. `/skill:changelog draft`, `... audit`, and
-`... release` name the others; with no mode, infer draft versus record from
-whether the behavior already exists.
+where they disagree with this skill, the project wins. There are three modes:
+**record** (the default), **audit**, and **release**. `/skill:changelog` records;
+`... audit` and `... release` name the others.
 
 ## 1. Read the project profile
 
-Before editing, find:
+In this package the profile is written down; read it rather than rediscover it:
 
-- the changelog file and its preamble;
-- the category spelling and order;
-- the scope prefix, and whether one bullet per extension or module is required;
-- whether the entry belongs in the same commit as the change;
-- the release document, version bump, link refs, and tag/push/publish order;
-- the check command and any release-consistency test.
+- [`../../CHANGELOG.md`](../../CHANGELOG.md) — the preamble, the scope prefixes,
+  and the bullet shape in use;
+- [`../../AGENTS.md`](../../AGENTS.md) — the entry lands in the same commit as the
+  change, and a behavior change also updates the two entry READMEs and `docs/`;
+- [`../../docs/development.md#release`](../../docs/development.md#release) — the
+  normative release procedure: version bump, link refs, tag and push order;
+- [`../../test/release.test.ts`](../../test/release.test.ts) — the guard on
+  subsection names, order, emptiness, and the version pin.
+
+Everywhere else, find the same six things: the changelog and its preamble, the
+category spelling and order, the scope prefix and one-bullet-per-unit rule,
+whether the entry ships with the change, the release document with its bump and
+push order, and the check command with any release-consistency test.
 
 State the profile in one short paragraph. Do not invent a rule the project never
 stated; ask instead.
 
-## 2. Draft before implementing
-
-For a new feature, draft the bullet in the plan or a scratchpad, not in
-`CHANGELOG.md`.
-
-- Write one line in the project's shape: ``- `scope`: <what the user can now do>``.
-- If you cannot state the outcome, or need several unrelated bullets, the feature
-  is not scoped yet; split it or ask before coding.
-- Name the intended category and any migration, breaking change, or required
-  action now, while the scope is still open.
-- Use the draft as the acceptance criterion: implementation is done when the
-  behavior it describes is true and tested.
-- Keep it out of the changelog until the code lands; a draft is not a shipped
-  claim. Update it when the outcome changes, then move it into `[Unreleased]` in
-  the same commit as the code (**Record**).
-
-## 3. Classify the change
+## 2. Classify the change
 
 It qualifies when a user can observe it: behavior, a CLI/tool/command surface, a
 config default, packaging, security, or a documented promise that is now true or
@@ -57,7 +46,7 @@ be one bullet if users see one outcome; two observable changes are two bullets.
 Ask when the outcome is unclear. Never invent an entry to make an audit look
 complete.
 
-## 4. Record
+## 3. Record
 
 - Write the entry in the same commit as the change. If the change is already
   pushed without one, add a follow-up commit rather than rewriting history.
@@ -68,24 +57,40 @@ complete.
 - Exclude file names, internal helpers, test counts, commit hashes, and vague
   words such as "various" or "improvements".
 - Match the file's voice and tense. Do not add marketing.
+- A behavior change also updates its row in the catalog tables of
+  [`../../README.md`](../../README.md) and
+  [`../../README.zh-CN.md`](../../README.zh-CN.md) plus the `docs/` guide it
+  belongs to; the changelog is this skill's subject, not its only file. A skill's
+  change updates its `SKILL.md` and its README row together.
 - Re-read immediately before editing, append within the category, and preserve
   other bullets and concurrent edits. Never create a second category heading.
 
+Shape: one blank-line-separated bullet per outcome, wrapped near 80 columns, the
+scope in backticks followed by a colon. The scope is the extension or module name,
+spelled as this package spells it — `bytefly`, `plan`, `wechat`, `todo` — or
+`lib`, `docs`, `test`, `ci`, `skills`. A bullet with no scope, or with a name the
+package does not use, is a defect. A bullet may run several sentences — say what
+the user sees, what it replaced, and any required action. Brevity is not the
+goal; vagueness is the defect.
+
 Good:
 
 ```text
-- `billing`: invoices now show the tax line separately.
-- `config`: `oldKey` is no longer read; run `bun run config:migrate`.
+- `config`: the report now says what its percentages are shares of. A
+  `Composition · 11k estimate` header sits above the rows, and a disabled
+  compaction no longer prints a headroom figure for a threshold that will never
+  fire.
+- `cli`: `oldKey` is no longer read; run `bun run config:migrate`.
 ```
 
 Bad:
 
 ```text
-- `billing`: refactored invoice rendering and added tests.
+- `config`: refactored invoice rendering and added tests.
 - `misc`: improvements.
 ```
 
-## 5. Audit (read-only)
+## 4. Audit (read-only)
 
 1. Find the last tag: `git describe --tags --abbrev=0`, or the project's
    equivalent.
@@ -107,29 +112,36 @@ since the tag contain user-visible changes.
 Do not edit during the audit unless the user asks. If they do, return to
 **Record** and make only the entries the evidence supports.
 
-## 6. Release (only when asked)
+## 5. Release (only when asked)
 
-Follow the project's release document; it is normative. This is a checklist, not
-a replacement:
+The project's release document is normative — in this package
+[`../../docs/development.md#release`](../../docs/development.md#release), guarded
+by [`../../test/release.test.ts`](../../test/release.test.ts). This is a
+checklist, not a replacement:
 
 - Confirm the version and the SemVer reason with the user.
 - Move every `[Unreleased]` entry under `## [X.Y.Z] - YYYY-MM-DD`; leave an empty
   `[Unreleased]` heading.
-- Bump every manifest and update the compare and release link refs.
-- Run the project's release checks.
-- Tag, push, and publish only with explicit approval, in the project's order.
+- Bump every manifest and update the compare and release link refs, in the same
+  commit as the movable part; the version in the manifest and the newest dated
+  heading must agree or the release test fails.
+- Run the project's release checks, then `bun test test/release.test.ts` for the
+  version and subsection rules.
+- Tag, push, and publish only with explicit approval, in the project's order. The
+  order matters: push the tag with `main`, never after it.
 - Keep the release commit mechanical: no behavior, code, or unrelated docs.
-- Use that section as the release body; do not add extra prose.
+- Use that section as the release body (`bun run release:notes X.Y.Z` prints it);
+  do not add extra prose.
 
-## 7. Quality gate
+## 6. Quality gate
 
 - One bullet per user-visible change; every bullet starts with a scope and a user
-  outcome.
+  outcome, and may take several sentences to state it.
 - No internal-only or duplicate entries, and no empty category headings.
 - No entry for a change that shipped before its heading.
 - Links and versions agree; the project check passes.
 
-## 8. Report and stop
+## 7. Report and stop
 
 Say what was recorded, what the audit found, or what the release moved. List what
 was deliberately left out and why. When nothing qualifies, say so. Stop before

package/skills/next/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: next
+description: "Decide what to do next from a project's real state, or from the current conversation: loose work in the tree, commits since the last tag, unreleased changelog entries, roadmap or plan items still open, and the project's check command. Returns a short ranked list with the evidence for each item and the command that starts it; read-only, it never edits, commits, or begins the work. Use when asked what to do next, where to pick up, what is left, or what to work on now."
+---
+
+# Decide what to do next
+
+This is a triage, not a work session. The deliverable is a short ranked list with
+evidence; do not edit, commit, tag, or start the top item. The skill is
+model-invoked when a request matches the description; `/skill:next` is the
+explicit fallback. Read the project's own instructions first; where they disagree
+with this skill, the project wins.
+
+Two sibling skills own a narrower question: an audit of *where to refactor* is
+`refactor`, and *what the last tag owes the changelog* is `changelog`. 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 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
+its list survives the conversation that produced it.
+
+## 1. Read the request
+
+The host appends the text after the command to these instructions as the request.
+It is `<prompt>` in `/skill:next <prompt>`, it comes before any reading, and it
+carries up to three parts:
+
+```text
+/skill:next [session] [what you want] [@path ...]
+```
+
+- **`session`, first word** — session mode (section 3). The rest of the prompt
+  keeps its own meaning: `/skill:next session what is left?` is session mode with
+  a filter, not a filter of `session`.
+- **What you want** — a question, a goal, or a topic: "what is left before
+  0.17?", "plan file outline". It chooses what the shortlist is about and keeps
+  only the sources that can answer it; say which ones you kept. A named release,
+  file, or feature is the filter.
+- **One or more paths** — `@src`, `src`, `packages/api`, or one inside the
+  sentence. Resolve each from the working directory, and take the evidence from
+  there: that path's diffs, plan steps, roadmap items, and changelog scope. A path
+  that does not exist is reported and asked about, never guessed.
+- **Both** — the usual case. `/skill:next plan file outline @extensions/plan/`
+  asks what to do next about the plan file outline, with `@extensions/plan/` as
+  the evidence, so a roadmap item, a plan step, or a changelog entry outside that
+  path is not a candidate.
+- **An imperative** — "fix the failing test" names one piece of work, and the
+  prompt is not approval for it. Answer with that item alone — evidence, starting
+  command, effort — and ask before starting, instead of producing a list.
+- **No prompt** — triage of the current project.
+- **Anything unreadable** — triage anyway, and say in one clause how you read the
+  prompt, so a misreading is visible in the report rather than silently narrowing
+  the list.
+
+## 2. Read the project profile
+
+With the request read, find:
+
+- the instruction files, and whether they require isolation (a worktree, a
+  branch) or a specific check;
+- the check command — the one that proves the tree is green; the triage quotes it
+  and never runs it (section 4);
+- where work is tracked: a roadmap, an issue tracker, `TODO` docs, a plans
+  directory, a changelog;
+- the release path: what a tag, a version bump, or an unreleased entry owes;
+- the VCS, its branch model, and the last tag if there is one.
+
+State the profile in one or two lines. Do not invent a source the project does
+not have; a project with no roadmap is triaged from git and the check alone.
+
+## 3. Choose the mode
+
+- **Triage** — what the tree says. Use git, the changelog, the roadmap or issues,
+  and the plans directory. This is the default.
+- **Session** — what this conversation left open. Read the conversation's own
+  record: the todo list, the goal, the approved plan and its ticked steps, what
+  subagents and jobs returned, and the diff this session produced. Then list the
+  loose ends it left: uncommitted files, an unapproved plan, a claim that was
+  never run, a documented behavior that changed without a doc or changelog edit.
+- When both apply, run triage and read the session for context; the tree wins,
+  because it is where the work actually is.
+
+Mode and scope are independent: session mode still honours a path, and triage
+with a path reads the whole tree's evidence before narrowing. State the mode, the
+scope, and the prompt as read, at the top of the report.
+
+## 4. Gather evidence
+
+Read only; nothing in this stage writes. Follow the project's own tool
+discipline, and say what you could not read.
+
+| Source | What it proves |
+|---|---|
+| `git status --short`, `git diff --stat` | Work in flight, and whose it is |
+| `git log --oneline <last-tag>..HEAD` | What has landed unreleased |
+| `git worktree list`, `git branch --no-merged` | An isolated tree left behind, a branch never merged |
+| The changelog's `[Unreleased]` | Whether a landed change is recorded, and whether the window is empty |
+| The roadmap, issue tracker, or `TODO` docs | The project's stated priorities, and which are already done |
+| The plans directory (`.pi/plans` or the project's equivalent) | An approved plan whose steps remain |
+| The todo list, the goal, job and subagent results | What the session promised and did not finish |
+| The check command | Whether the tree is green — cite the last known result, and make running it the item's starting command rather than running it here |
+
+A roadmap, a changelog, and a plan all lag the tree. Verify a candidate against
+the code before recommending it, and drop one that is already done.
+
+## 5. Verify and filter
+
+A candidate is not a suggestion until it has one concrete artifact: a path with
+line numbers, a command's output, a diff hunk, or a failing test name. If you
+cannot point at it, drop it.
+
+- Reject anything already done, already documented as a deliberate non-goal, or
+  blocked on a decision the user has not made — say which, and ask if it matters.
+- Keep a bug separate from a preference, and a refactor separate from a fix.
+- Prefer the candidate with a fast verification command.
+- Never invent work to fill the list. An empty list is a valid answer.
+
+## 6. Rank by cost of loss
+
+Order by what it would cost to lose, cheapest loss first:
+
+- **Loose work** — a dirty tree, an unapproved plan, a check that has not been
+  run, an unmerged branch, a worktree left behind, a stopped job.
+- **A broken promise** — a README, roadmap, or doc claim the code no longer
+  meets, a released behavior with no test.
+- **An unfinished promise** — a stated roadmap item, the remaining steps of an
+  approved plan, a documented limitation with no item, an unreleased change with
+  no changelog entry.
+- **New reach** — a capability nobody has asked for comes last, and only when the
+  three above are empty.
+
+Label each item with the ceremony it needs. The label is not a second ordering:
+cost of loss decides the order, and the label says how much work the item takes.
+
+- **Do next** — cheap, safe, and unblocks the rest.
+- **Worth planning** — high value, but it spans files, changes a public surface,
+  or needs a decision first.
+- **Later** — real, but not now.
+
+Cap the list at three to five items, and let a tier be empty. A roadmap restated
+as ten suggestions is not a triage. Do not invent a numeric score; the reason
+must be readable.
+
+## 7. Report
+
+- **State** — one paragraph: the mode, the scope and how the prompt was read,
+  the branch or worktree, what is dirty, what is unreleased, and whether the
+  check passes. Name anything you could not read.
+- **The shortlist** — each item with its label, the action, the evidence at
+  `path:line` or the command output that proves it, the command that starts it,
+  and effort (S/M/L). Link the file the item lives in.
+- **Rejected or stale** — one line each, with the reason the roadmap, changelog,
+  or plan entry no longer applies.
+- **Next step** — ask which item to start. Do not start it, and do not open with
+  an edit.
+
+If the host expects a closing next-steps block, keep it to the top two or three
+choices as one line each; the evidence stays in the list above, never repeated
+there.
+
+## 8. Handoff
+
+When the user picks an item, the audit is over:
+
+- Restate the chosen item as a task with its acceptance test.
+- Enter plan mode when the host provides it and the item spans files, changes a
+  public surface, or has an unknown step list. Track a small one in a todo list.
+- Run the project's check first for a baseline, and finish with the full check.
+- Do not commit unless the user asks.
+
+## 9. Stop conditions
+
+- Nothing worth doing: say so, with what was checked, instead of inventing work.
+- The tree is mid-rebase, mid-merge, mid-bisect, or has a conflict: reconciling it
+  is the only next item; nothing else is safe to suggest.
+- The project has no work tracking: say the list is derived from git and the check
+  only, and suggest recording the plan or roadmap the project is missing.
+- A candidate needs a destructive command (a branch delete, a worktree prune, a
+  history rewrite) to start: name it as a decision for the user, not as a step.
+
+The triage is done when the mode is stated, every item has evidence and a
+starting command, the list is capped, rejected candidates are explained, and no
+file was modified.