@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/prompts/review.md

@@ -1,192 +1,161 @@
 # Code Review Prompt
 
-This document is the review **policy**: which level a change is reviewed at, how many rounds a review
-runs, and what happens to a finding after the cap. Two other documents hold the rest, and this file
-points to them rather than restating them:
+Review policy: the level, the round count, and what happens to a finding after the cap. Elsewhere:
 
-- The **rubric** the reviewer applies — the severity tests, the nine categories, the output format and
-  the stop conditions — is `prompts/review-rubric.md`, handed to `/code-review` by
-  `pnpm josh review:brief`.
-- The **orchestration** around a review — how the gate runs beside it, when the pull request opens, how
-  the merge is issued — is `.claude/skills/workflow-commands/chain-rule.md` → "Orchestration facts
-  single-sourced here".
+- Rubric (severity tests, nine categories, output format, stop conditions): `prompts/review-rubric.md`,
+  handed to `/code-review` by `pnpm josh review:brief`.
+- Orchestration (gate beside the review, when the PR opens, the merge):
+  `.claude/skills/workflow-commands/chain-rule.md` → "Orchestration facts single-sourced here".
 
 ---
 
 ## When to run
 
-When a review runs is `CLAUDE.md` → "Pre-commit Self-Review"; inside a workflow, round 1 runs before
-the commit and round 2 beside CI (`.claude/skills/workflow-commands/chain-rule.md`). Pass the
-`reviewer` profile's model and effort that `pnpm josh review:brief` prints to the review subagent;
-do not substitute the review level for effort.
+When: `CLAUDE.md` → "Pre-commit Self-Review"; inside a workflow, round 1 runs before the commit and
+round 2 beside CI (`.claude/skills/workflow-commands/chain-rule.md`). Pass the review subagent the
+`reviewer` profile's model and effort that `pnpm josh review:brief` prints; never substitute the review
+level for effort.
 
-Re-run after applying fixes until **no high or medium findings remain — or until the round cap below is
-reached, the first review included — whichever comes first.** The cap below is not optional. The second round
-is a verification pass over the fixes, not the first review again
+Re-run after fixes until **no high or medium findings remain or the round cap below is reached** (the
+first review counts), whichever comes first. Round 2 is a verification pass over the fixes
 (`prompts/review-rubric.md` → "The second round is a verification pass, not a second full review").
 
 ---
 
 ## Before round 1 — the implementer's self-check
 
-**Answer these five over your own diff before the scoped pair that precedes round 1.** A round-1
-High/Medium makes round 2 due, and most of them are of a kind the implementer clears more cheaply
-than a reviewer finds: in a sample of 135 round-1 High/Medium findings, about two in three fell under one of these questions. Fix what an answer turns up; the review, its
-severity tests and the round cap are unchanged.
-
-1. **Tests pin the change** — for each condition, branch or call you added or changed, name the test
-   that turns red when it is deleted or inverted, and check its fixture actually reaches that branch
-   (no assert on a string the code never draws, no comparison against a literal copy).
-2. **Prose matches the code** — grep the docs, prompts and comments for the old wording of every
-   behavior, constant, command and heading you changed, moved or removed, `"the table above"` and
-   rewritten sentences included.
-3. **Failure is not a negative answer** — every timeout, non-zero exit or `gh` failure on a path you
-   touched returns something a caller can tell apart from `false`, `undefined` or "nothing found".
-4. **Every caller moved with it** — grep every reference to a function, list or command you changed,
-   and update each sibling path (the other CLI, the registry, the consumer side) in the same change.
+Answer these five over your own diff before the scoped pair that precedes round 1, and fix what an
+answer turns up (about two in three of 135 sampled round-1 High/Medium findings fell under one). The
+review, its severity tests and the round cap are unchanged.
+
+1. **Tests pin the change** — for each condition, branch or call added or changed, name the test that
+   turns red when it is deleted or inverted, and check its fixture reaches that branch (no assert on a
+   string the code never draws, no comparison against a literal copy).
+2. **Prose matches the code** — grep docs, prompts and comments for the old wording of every behavior,
+   constant, command and heading you changed, moved or removed, `"the table above"` and rewritten
+   sentences included.
+3. **Failure is not a negative answer** — every timeout, non-zero exit or `gh` failure on a touched
+   path returns something a caller can tell apart from `false`, `undefined` or "nothing found".
+4. **Every caller moved with it** — grep every reference to a changed function, list or command, and
+   update each sibling path (the other CLI, the registry, the consumer side) in the same change.
 5. **The Issue is met on HEAD** — the premises you relied on hold on the current tree, and each
-   acceptance criterion is checked off one by one against the diff.
+   acceptance criterion is checked against the diff.
 
 ---
 
 ## Review level (decided by `pnpm josh review:brief --level-only`, never by judgement)
 
-**Run `pnpm josh review:brief --level-only` and use what it prints** — `low` or `medium`, from the
-changed paths and nothing else, never "this one is small". `--staged` classifies the staged diff,
-`--json` adds the reason; inside a workflow `pnpm josh review:brief` prints the same level on its first
-line. A `low` change gets 1 round, a `medium` one up to 2 (the cap below). How the answer is derived —
-the inert paths, documentation at `medium`: `docs/maintainers/review-history.md` → "The level is
-decided from the changed paths".
+Run `pnpm josh review:brief --level-only` and use what it prints — `low` or `medium`, from the changed
+paths only, never "this one is small". `--staged` classifies the staged diff, `--json` adds the reason;
+inside a workflow `pnpm josh review:brief` prints the level on its first line. `low` gets 1 round,
+`medium` up to 2. A diff that touches documentation is not inert: it stays at `medium`.
 
 ```bash
 pnpm josh review:brief --level-only            # the branch diff
 pnpm josh review:brief --level-only --staged   # the staged diff
 ```
 
-**A confirmed High blocks regardless of round count**, and the round cap below does not change that.
+**A confirmed High blocks regardless of round count**, whatever the cap.
 
 ---
 
 ## Review round cap (2 rounds)
 
-The severity rule in the rubric is not a stopping condition on its own: every fix creates new surface a
-further round would find something in.
-
-**Two rounds is the ceiling, not the schedule.** Whether the second one is due at all is
-`pnpm josh review:round2`'s answer — "When round 2 is skipped entirely, and when it is not" below is
-the single source of that condition.
+Two rounds is the ceiling, not the schedule: every fix creates new surface a further round would find
+something in. Whether round 2 is due is `pnpm josh review:round2`'s answer (below).
 
 ### A merge-conflict resolution review is not one of the two
 
-**When `pnpm josh followup` reports `PR checks failed (merge conflict)`, the child resolves the conflict
-in its own lane and reviews the resolution — and that round does not count against the cap**. The cap bounds re-reading _the change under review_; a resolution review reads
-a different subject — not the change, but what merging a moved `main` into it did.
-`.claude/skills/workflow-commands/backlogrun-recovery.md` → "Conflicts are not predicted" is the single source of
-the procedure and of the four conditions under which the run steps back instead of resolving.
-`pnpm josh review:attest --check` must answer `ok` before the merge is re-issued, and a confirmed High
-parks the child rather than buying it a further round.
+When `pnpm josh followup` reports `PR checks failed (merge conflict)`, the child resolves the conflict
+in its own lane and reviews the resolution — **that round does not count against the cap**, since it
+reads what merging a moved `main` did, not the change. Procedure and the four step-back conditions:
+`.claude/skills/workflow-commands/backlogrun-recovery.md` → "Conflicts are not predicted".
+`pnpm josh review:attest --check` must answer `ok` before the merge is re-issued; a confirmed High parks
+the child rather than buying a further round.
 
 ### When round 2 is skipped entirely, and when it is not
 
-**Two rounds is the ceiling; whether the second round runs at all is a command's answer, not a reading
-of a list**:
-
 ```bash
 pnpm josh review:round2 --round-1-closed   # → required | skip ; the reason on stderr
 ```
 
-**Ask it once round 1's fixes are in and before the commit.** Pass `--round-1-closed` only where every
-round-1 High/Medium finding actually closed — by a fix in this working tree, or as a verified false
-positive — and none was filed or deferred. **Without the flag the answer is `required`**, which is also
-what the command answers to every uncertainty it meets, a missing round-1 snapshot included.
+Ask once round 1's fixes are in, before the commit. Pass `--round-1-closed` only when every round-1
+High/Medium closed — fixed in this working tree or verified false positive — and none was filed or
+deferred. Without the flag, and on any uncertainty (a missing round-1 snapshot included), the answer is
+`required`.
+
+`skip` has exactly two arms, and the reason line names which fired:
+
+- **A** — the fix delta is empty.
+- **B** — every path in the fix delta is inert by the review-level classification above:
+  `docs/**/*.md`, the root `README.md`, under `prompts/`, or a `.ts` / `.js` / `.svelte` file outside
+  `.claude/` changed only in comments (a lint, type-check, coverage or bundler directive comment counts
+  as code).
 
-**`skip` has exactly two arms** — **A** (no fix code: the fix delta is empty) and **B** (a fix that
-leaves what executes unchanged: every path in the fix delta is inert by the review-level classification
-above, `docs/**/*.md`, the root `README.md`, under `prompts/`, or a `.ts` / `.js` / `.svelte` file
-outside `.claude/` whose only change is in comments, a directive comment — lint, type-check, coverage
-or bundler — counting as code); the reason line names which fired. **One path
-outside that set makes the round `required`** — `.claude/**`, `CLAUDE.md`, a test, configuration, a
-code line, or a source file whose comment-free text cannot be read. Why neither arm weakens the
-standard: `docs/maintainers/review-history.md` → "The two skip arms".
+One path outside that set makes it `required` — `.claude/**`, `CLAUDE.md`, a test, configuration, a
+code line, or a source file whose comment-free text cannot be read.
 
-**A skipped round is recorded on the Issue**, so the condition stays auditable and can be withdrawn if
-a defect is later traced to a skipped delta:
+Record a skipped round on the Issue:
 
 1. Label the Issue `review-round2-skipped`, created once per repository:
    `gh api repos/{owner}/{repo}/labels -f name=review-round2-skipped -f color=c5def5 -f description="Review round 2 was skipped under the condition in prompts/review.md" --silent 2>/dev/null || true`,
    then `gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=review-round2-skipped'`.
-2. Post an Issue comment under the heading `## Round 2 skipped`, naming **which arm fired** and quoting
-   **the reason line the command printed**, verbatim.
+2. Comment under `## Round 2 skipped`, naming which arm fired and quoting the command's reason line
+   verbatim.
 
 ### Three-way disposition after the cap
 
-**After the second round, place every remaining non-High finding in exactly one of three exits, decided
-from what the finding is rather than from the filer's discretion**. **The
-default exit is branch 3, and branch 2 has to be earned**. Read them in order — branch 1 where the fix is
-trivial and local, branch 2 only where the finding clears the bar it names, branch 3 for everything
-left, which is most of them. "It might matter later" is branch 3.
-
-1. **Fix it in place.** The finding closes in a few lines inside a file the diff already touches, with
-   no design judgement — a stale comment, a name, an unused export. **A fix-in-place never starts a new
-   review round**: the fix widens the diff, so a naive re-review would re-open the loop the cap just
-   closed. The fix must stay **inside a file the diff already changed** and carry **no design decision**;
-   a finding that cannot close under both limits is filed, not fixed in place.
-2. **File it as an Issue.** The finding is a **confirmed defect that reaches a runtime code path** —
-   both halves, and neither on its own. Confirmed means the failure scenario is stated in concrete
-   inputs and state. **Reaching is read exactly as the rubric's Severity test 1 reads it** — a runtime
-   code path, a distributed artifact a consumer reads, or the verification that guards either — so in a
-   repository whose product is its distributed documents, a defect in one of those is a branch-2 finding
-   like any other. **The reaching half is not a judgement**: `pnpm josh disposition <path>` answers
-   `runtime` / `non-runtime` from the finding's paths, sharing the same inert set the review level uses,
-   so only "is the defect confirmed" is left to decide. **"It needs a decision" is no longer a branch-2
-   condition on its own**: a design question with no defect under it takes branch 3.
-3. **Drop it with a one-line note in the PR body.** **This is the default, and it takes everything the
-   other two branches did not**: a Low that does not reach the user, and every remaining finding that is
-   neither closable in place nor a confirmed runtime defect — a design preference or an unproven
-   suspicion included. **The note is not optional**: one line naming the finding and why it was dropped
-   is what keeps a dropped finding auditable rather than invisible.
-
-**Findings that reduce to one root judgement are filed as one Issue, not several** — a single follow-up
-Issue with a section per symptom (`## 現象 1` / `## 現象 2`).
-
-Only branch 2 files an Issue. What follows applies to that branch.
-
-- **A finding routed to branch 2 is filed as a follow-up Issue referencing the current one, and the
-  current Issue completes.** (A confirmed High is not a branch-2 finding: it blocks the merge rather
-  than being deferred — see below.)
-- **Filing does not end at the Issue.** `epic:next` only ever offers a child the task list of an epic
-  names, so an Issue in no epic is never handed to a running `backlogrun` — the deferred finding is parked
-  forever, which reads the same from the backlog. **The steps run inside the CI wait, not before
-  the commit.** Where the run opens a pull request — `fullrun`, `backlogrun` — they go after
-  `pnpm josh git -y` and before `pnpm josh followup`; where it does not — `halfrun`, or a standalone
-  pre-commit self-review — they run as soon as the disposition is decided. **The chain may run in a
-  delegated unit** — `pnpm josh delegate followup-filing`.
-- **A second follow-up from one round folds into the first by default.** Several findings from one
-  review fold into one Issue — the filing-time counterpart to the split assessment, reading the same
-  two questions (`.claude/skills/workflow-commands/split-assessment.md` → "The same two questions
-  decide the filing-time fold"). `pnpm josh issue:file` asks the fold question itself on the run's
-  second filing and holds a `fold`; the first filing asks nothing.
-
-  1. File the follow-up Issue referencing the current one, tagged `route:review-cap` — **before the current Issue closes.**
-     `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route review-cap`.
-     The command lints the body, applies the classification labels it declares, runs the duplicate scan
-     and then `epic:bundle` on the new Issue (`docs/josh-commands-backlog.md` → `josh issue:file`). The
-     `epic:bundle` candidate search reads open issues only, so once the parent has closed it answers
-     `none` permanently.
-  2. Act on the `epic:bundle` answer it prints. **`epic:bundle` recommends and writes nothing**, so acting means running the
-     write command yourself — never a hand edit of the epic body, which leaves the task list and the
-     `blocked-by` relations disagreeing and `epic:next` returning `error`.
-
-  | Answer                                                                                            | Do                                                                                                                                                                                                                                                                                                       | Tier                    |
-  | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-  | `add_to_epic`                                                                                     | `pnpm josh epic --add <E> <new>` — add `--before <M>` / `--after <M>` when the relation carries an order                                                                                                                                                                                                 | **A — no confirmation** |
-  | `create_epic`                                                                                     | `pnpm josh epic "<title>" <new> <other> [--ordered]`                                                                                                                                                                                                                                                     | **A — no confirmation** |
-  | `ask` — candidates spread across two or more epics                                                | **Choose the epic you recommend, run its write command, and record the decision** — what was taken, what was rejected, why — on both the new Issue and that epic's `## Decisions`. This does not stop a run and does not park a child; stop only where the two epics are genuinely too close to separate | **A — no confirmation** |
-  | `none`                                                                                            | Nothing                                                                                                                                                                                                                                                                                                  | —                       |
-  | **The command could not answer** — non-zero exit, or **any** ⚠ warning above `Nothing to bundle.` | Stop and report, naming what it said. **A `none` printed after such a warning is not "nothing to bundle"** — the search was incomplete                                                                                                                                                                   | —                       |
-
-- **A confirmed High is never deferred.** A real defect does not ship because a round counter ran out,
-  so a standing High blocks the merge — never fixed-in-place, filed, or dropped as one of the three
-  exits. If a High is still standing after the second round, do not start a third: stop, send a
-  `confirmation` Telegram, and put the scope back to the user, where splitting the Issue is usually the
-  answer.
+After round 2, place every remaining non-High finding in exactly one exit, decided by what the finding
+is. **The default exit is branch 3, and branch 2 has to be earned**. "It might matter later" is branch 3.
+
+1. **Fix it in place** — it closes in a few lines inside a file the diff already changed, with no
+   design decision (a stale comment, a name, an unused export). A fix-in-place never starts a new
+   review round. A finding that cannot close under both limits is filed, not fixed in place.
+2. **File it as an Issue** — a **confirmed defect that reaches a runtime code path** — both halves, and neither on its own.
+   Confirmed: the failure scenario is stated in concrete inputs and state.
+   **Reaching is read exactly as the rubric's Severity test 1 reads it** (a runtime code path, a
+   distributed artifact a consumer reads, or the verification that guards either), so a defect in a
+   distributed document is branch 2. `pnpm josh disposition <path>` answers `runtime` / `non-runtime`
+   from the finding's paths (the review level's inert set). **"It needs a decision" is no longer a branch-2 condition on its own**:
+   a design question with no defect under it takes branch 3.
+3. **Drop it with a one-line note in the PR body** — **This is the default, and it takes everything the other two branches did not**:
+   a Low that does not reach the user, a design preference, an unproven suspicion. **The note is not optional**:
+   one line naming the finding and why it was dropped.
+
+Findings that reduce to one root judgement are filed as one Issue with a section per symptom
+(`## 現象 1` / `## 現象 2`).
+
+Branch 2 only:
+
+- File a follow-up Issue whose `parent: #N` line names the current one — a mention in its background
+  is not read by `epic:bundle`; the current Issue completes.
+- An Issue in no epic is never offered by `epic:next`, so filing continues to the epic. Run these steps
+  inside the CI wait: in `fullrun` / `backlogrun` after `pnpm josh git -y` and before
+  `pnpm josh followup`; in `halfrun` or a standalone pre-commit self-review as soon as the disposition
+  is decided. They may run delegated — `pnpm josh delegate followup-filing`.
+- A second follow-up from one round folds into the first by default
+  (`.claude/skills/workflow-commands/split-assessment.md` → "The same two questions decide the
+  filing-time fold"). `pnpm josh issue:file` asks the fold question on the run's second filing and holds
+  a `fold`; the first filing asks nothing.
+
+  1. Before the current Issue closes, file it tagged `route:review-cap`:
+     `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route review-cap`. It lints
+     the body, applies the declared labels, runs the duplicate scan and `epic:bundle`
+     (`docs/josh-commands-backlog.md` → `josh issue:file`). `epic:bundle` reads open issues only, so
+     after the parent closes it answers `none` permanently.
+  2. Act on the printed `epic:bundle` answer by running the write command yourself — `epic:bundle`
+     writes nothing, and a hand edit of the epic body leaves the task list and `blocked-by` relations
+     disagreeing (`epic:next` returns `error`). Tier A, no confirmation:
+     - `add_to_epic` → `pnpm josh epic --add <E> <new>`, with `--before <M>` / `--after <M>` when the
+       relation carries an order.
+     - `create_epic` → `pnpm josh epic "<title>" <new> <other> [--ordered]`.
+     - `ask` (candidates across two or more epics) → run the recommended epic's write command and record
+       what was taken, what was rejected and why on the new Issue and that epic's `## Decisions`. Stop
+       only where the two epics are genuinely too close to separate.
+     - `none` → nothing.
+     - Non-zero exit, or any ⚠ warning above `Nothing to bundle.` → stop and report what it said; a
+       `none` after such a warning is not "nothing to bundle".
+
+**A confirmed High is never deferred** — it blocks the merge, never fixed-in-place, filed or dropped.
+If one still stands after round 2, do not start a third: stop, send a `confirmation` Telegram, and put
+the scope back to the user (usually: split the Issue).

package/prompts/sonar-hotspot-handling.md

@@ -2,50 +2,26 @@
 
 <!-- cspell:words hotspot Hotspot hotspots Hotspots NOSONAR -->
 
-This guide extends the collaboration workflow with a project-local procedure for handling SonarCloud Security Hotspots. It is kept out of the upstream-synced `prompts/collaboration-workflow/` topics so those stay identical across the projects that consume them.
-
-AI tools cannot perform OAuth browser login to SonarCloud, so this guide assumes public-API and config-based actions as the primary path.
+Project-local procedure for SonarCloud Security Hotspots, kept out of the upstream-synced `prompts/collaboration-workflow/`. AI tools cannot do SonarCloud's OAuth browser login, so the primary path is the public API and config.
 
 ## Quality Gate enforcement (CI blocks PRs)
 
-The distributed `.github/workflows/sonar-qube.yml` runs the SonarCloud scan with
-`-Dsonar.qualitygate.wait=true`, so the `SonarQube` job — a required PR check — fails when the
-Quality Gate is red. **The gate alone is not enough**: `Sonar way` judges ratings and ratios, so a
-few MINOR code smells keep the maintainability rating at A and a small copied block stays under the
-duplication threshold. On a pull request the job therefore ends with `pnpm josh sonar:new-code <PR>`,
-which **fails on a single new issue of any type or severity, or a single new duplicated block**
-(joshuafolkken/kit#3045). An issue resolved in SonarCloud as accepted or a false positive is not
-counted — that resolution is the route for a deliberate exception. This job is the single enforcement point:
-`josh followup` does **not** scan SonarCloud findings (it only scans CodeRabbit / Claude Review
-comments), but it **does** wait on the required `SonarQube` CI check, so a red gate also blocks the
-`followup` merge. Consumers pick the workflow up verbatim via `josh sync`; do not re-implement the
-gate per consumer.
-
-**A run that cannot see `SONAR_TOKEN` skips the scan and passes**, printing one line that names the
-missing token (joshuafolkken/kit#2815) — a consumer that does not use SonarCloud is never blocked by
-it. The same holds for any run GitHub withholds secrets from (a fork pull request, or a Dependabot
-run without the secret in the Dependabot store), so a repository that relies on this gate keeps
-`SONAR_TOKEN` in both secret stores.
+The distributed `.github/workflows/sonar-qube.yml` scans with `-Dsonar.qualitygate.wait=true`, so the required `SonarQube` PR check fails on a red Quality Gate. On a pull request the job then runs `pnpm josh sonar:new-code <PR>`, which **fails on a single new issue of any type or severity, or a single new duplicated block** (joshuafolkken/kit#3045) — `Sonar way` judges ratings and ratios, so a few MINOR smells or a small copied block would otherwise pass. An issue resolved in SonarCloud as accepted or a false positive is not counted; that resolution is the route for a deliberate exception.
+
+This job is the single enforcement point: `josh followup` does not scan SonarCloud findings but waits on the required `SonarQube` check, so a red gate blocks its merge too. Consumers get the workflow verbatim via `josh sync`; do not re-implement the gate per consumer.
+
+A run that cannot see `SONAR_TOKEN` skips the scan and passes, printing one line naming the missing token (joshuafolkken/kit#2815). GitHub withholds secrets from fork pull requests and from Dependabot runs without the secret in the Dependabot store, so a repository relying on this gate keeps `SONAR_TOKEN` in both secret stores.
 
 ### New Code vs Overall Code semantics
 
-The scan passes `package.json`'s `version` as `sonar.projectVersion`, so New Code — "since the
-previous version" — restarts at every `josh bump` that reaches main instead of growing from the
-first analysis on.
+The scan passes `package.json`'s `version` as `sonar.projectVersion`, so New Code ("since the previous version") restarts at every `josh bump` that reaches main.
 
-SonarCloud's default **Sonar way** Quality Gate evaluates **New Code only** — conditions
-(new bugs, new code smells above the Maintainability rating, new coverage/duplication) apply to
-lines changed in the PR's New Code period, not the whole codebase. Consequences:
+The default Sonar way gate evaluates New Code only — lines changed in the PR's New Code period:
 
-- A PR is blocked when it **introduces or modifies** code that trips a condition — this is what
-  catches the recurring Maintainability `0 -> 1` regression that motivated this gate.
-- Pre-existing Overall-Code findings on untouched files do **not** fail an unrelated PR. To make
-  the gate enforce Overall Code as well, add Overall conditions to the gate in the SonarCloud
-  project settings (Quality Gates UI) — that is a SonarCloud-side configuration, not a repo file.
+- A PR that introduces or modifies code tripping a condition is blocked (e.g. a Maintainability `0 -> 1` regression).
+- Pre-existing Overall-Code findings on untouched files do not fail an unrelated PR. Enforcing Overall Code needs Overall conditions added in the SonarCloud Quality Gates UI, not a repo file.
 
-When triaging a red gate, confirm via the PR analysis whether the failing condition is a **New
-Code** condition (caused by this PR — fix it) or an **Overall** condition (pre-existing — handle
-per the table below, and do not let it silently block an unrelated change).
+Red gate → check in the PR analysis: a New Code condition is this PR's (fix it); an Overall one is pre-existing (handle per the table below, never silently blocking an unrelated change).
 
 ## Step A / Step B: fetch the hotspots and read each one's disposition
 
@@ -53,11 +29,7 @@ per the table below, and do not let it silently block an unrelated change).
 pnpm josh sonar:hotspots <PR>
 ```
 
-The command fetches the hotspots on the pull request from SonarCloud's public API (no auth), reading
-the project key from `sonar-project.properties`, and prints per hotspot its `status`, `component`,
-`line`, `ruleKey` and the Step B branch it falls into. The one branch key that used to be walked by
-eye — "is this path upstream-synced?" — is answered by calling `josh sync:scope`'s own detection, so
-no distribution path list is duplicated. The four branches:
+Reads the PR's hotspots from SonarCloud's public API (no auth; project key from `sonar-project.properties`) and prints each one's `status`, `component`, `line`, `ruleKey` and Step B branch; upstream-synced paths come from `josh sync:scope`'s detection.
 
 | Branch     | Meaning                                                                                                    |
 | ---------- | ---------------------------------------------------------------------------------------------------------- |
@@ -66,15 +38,15 @@ no distribution path list is duplicated. The four branches:
 | `fix`      | A reviewed-and-fixed hotspot — the real issue was fixed                                                    |
 | `defer`    | A reviewed hotspot set aside — out of scope for this PR                                                    |
 
-A read that failed (rate-limit, network) prints `unreadable: <reason>`, told apart from a success
-that found no hotspots. `pnpm josh oracle:list` carries the same vocabulary. **The only judgement
-left to you is whether a `TO_REVIEW` hotspot is really a false positive** — if it is, apply its
-`excluded` / `local` branch; if it is instead a real issue fix the code and add a regression test,
-and if it is out of scope mention it in the completion comment and open a follow-up Issue.
+A failed read (rate-limit, network) prints `unreadable: <reason>`, distinct from finding none. `pnpm josh oracle:list` uses the same vocabulary. **Your only judgement: is a `TO_REVIEW` hotspot really a false positive?**
+
+- False positive → apply its `excluded` / `local` branch.
+- Real issue → fix the code and add a regression test.
+- Out of scope → mention it in the completion comment and open a follow-up Issue.
 
 ## Step C: optional — mark SAFE via API if a token is available
 
-If `SONAR_TOKEN` is exported (SonarCloud user token with write scope):
+With `SONAR_TOKEN` exported (SonarCloud user token with write scope):
 
 ```bash
 curl -sS -u "$SONAR_TOKEN:" -X POST \
@@ -82,10 +54,10 @@ curl -sS -u "$SONAR_TOKEN:" -X POST \
   -d "hotspot=<hotspot-key>&status=REVIEWED&resolution=SAFE&comment=<reason>"
 ```
 
-Without a token, prefer Step B's config-based approach — that change is reviewable in the PR diff, whereas API-side state changes are not.
+Without a token, prefer Step B's config-based approach — it is reviewable in the PR diff; API-side state changes are not.
 
 ## Reporting rules
 
-- List every outstanding hotspot in the completion comment (never hide a failing SonarCloud analysis).
-- State which action you took (excluded / marked SAFE / fixed / deferred) and why.
-- If you deferred, include a link to the follow-up Issue.
+- List every outstanding hotspot in the completion comment; never hide a failing SonarCloud analysis.
+- State the action taken (excluded / marked SAFE / fixed / deferred) and why.
+- Link the follow-up Issue for a deferral.