leos-agent 6.3.0 → 7.0.0

package/skills/brainstorming/SKILL.md

@@ -7,7 +7,9 @@ description: >
   wide blast radius, hard to reverse, or that introduce new surface need
   genuine, viable alternatives with trade-offs weighed before any code gets
   written. Produces the chosen approach and its trade-offs, sized to the gate,
-  handed off to leo:writing-plans.
+  handed off to leo:writing-plans. Use when choosing an approach before
+  non-trivial code. Do not use for contained reversible tweaks, investigation,
+  or writing the plan itself.
 when_to_use: >
   Before starting non-trivial code: a new feature, a new integration surface,
   a schema or data-model change, anything that's expensive or awkward to

package/skills/debugging/SKILL.md

@@ -5,7 +5,9 @@ description: >
   behavior. Five named phases — Reproduce, Localize, Hypothesize, Prove, Fix —
   each with an exit criterion, so a fix never lands before the cause is
   pinned to file:line. Diagnosis is read-only judge work (investigator); the
-  fix happens separately, at the routed tier.
+  fix happens separately, at the routed tier. Use when a bug, failure, crash,
+  or surprising behavior needs diagnosis. Do not use for planned features,
+  reviewing a diff, or post-fix completion verification.
 when_to_use: >
   Any bug report, failing test, crash, stack trace, or "why does X happen"
   before proposing a fix — used by the investigator agent and by the main
@@ -61,7 +63,7 @@ you, and go again.
 
 After two failures on the same cause (two hypotheses tried and reverted, still
 no Prove), step up one tier rather than retrying at the same one — investigator
-haiku-assist steps to full investigator, investigator itself steps to a
+explore findings feed a full investigator, and investigator itself steps to a
 second, more evidence-fed pass, capped at Opus. A genuine deadlock, or two
 Opus verdicts on the same cause that disagree → `expert`, announced in one
 line ("escalating to expert: <question>") before it's invoked, never silent.

package/skills/delegation/SKILL.md

@@ -4,7 +4,8 @@ description: >
   Operational mechanics for dispatching subagents — a single spawn or a large
   fan-out — the companion to the policy's "Delegate the labor" section.
   Covers brief construction, model/effort pinning, the four-state return
-  contract, and ledger-backed progress tracking for long multi-agent runs.
+  contract, and ledger-backed progress tracking for long multi-agent runs. Use
+  when dispatching any subagent or fan-out. Do not use to choose a task's tier.
 when_to_use: >
   Any time work is routed to a subagent (explore, investigator, executor,
   implementer, reviewer, expert) rather than done inline — single dispatch or
@@ -36,8 +37,8 @@ version needs no follow-up question; the first invites three.
 ## Pin model and effort
 
 Every dispatch pins **model AND effort** from the routing table — opus for
-judges (reviewer, investigator), sonnet for execution (implementer, executor
-on normal work), haiku for mechanical work (executor on boilerplate). expert
+judges (reviewer, investigator), sonnet for normal implementation
+(implementer), haiku for mechanical work (executor). expert
 never appears in a fan-out — one at a time, never fanned. An unpinned call
 silently inherits the session's tier: in an opus session that means every
 executor spawn quietly runs at opus, and a ten-item fan-out burns
@@ -53,7 +54,7 @@ a report that hedges across two of them.
 |---|---|---|
 | `done` | Work finished, matches the brief | Verify against artifacts — see leo:verification — never take the self-report at face value |
 | `concerns` | Finished, but flags something worth a second look | Read the concerns before accepting; they're often the real finding |
-| `needs-context` | Blocked on missing information you can supply | Send the missing piece to the same agent (`SendMessage` on Claude Code — elsewhere see the *Follow-up to a live agent* row of your mapping, and where none is established, cold re-dispatch with the context restated is the whole mechanism) so it keeps the context it already built. Either way **once** — a second needs-context on the same gap means the brief itself is broken, escalate the tier |
+| `needs-context` | Blocked on missing information you can supply | Send the missing piece to the same agent (`SendMessage` on Claude Code, `followup_task` on Codex — elsewhere see the *Follow-up to a live agent* row of your mapping, and where none is established, cold re-dispatch with the context restated is the whole mechanism) so it keeps the context it already built. Either way **once** — a second needs-context on the same gap means the brief itself is broken, escalate the tier |
 | `blocked` | Blocked on something you can't hand over inline | Resolve the blocker, or escalate per the ladder — never a silent same-tier retry |
 
 `needs-context` and `blocked` look similar; the test is whether the missing
@@ -89,10 +90,11 @@ between "agent finished" and "ledger written" is exactly the gap this
 exists to close.
 
 `${CLAUDE_PLUGIN_ROOT}` above is the Claude Code spelling of the plugin root,
-and it is substituted into this text only there. On another harness, read the
-plugin-root form from that harness's appendix in the injected policy (Codex
-uses a real `$PLUGIN_ROOT` env var, Cursor `$CURSOR_PLUGIN_ROOT`) — the path
-after the root is identical everywhere.
+and it is substituted into this text only there. Codex exposes `$PLUGIN_ROOT`
+and Cursor `$CURSOR_PLUGIN_ROOT`. Hermes and OpenCode expose no root variable;
+their injected policy substitutes an absolute payload path into the `state.py`
+and `memory.py` commands, which is the discoverable source to reuse. Do not
+invent an environment variable where the harness exposes none.
 
 For a batch of independent, well-scoped fixes, don't hand-roll this loop —
 the reusable workflow at `${CLAUDE_PLUGIN_ROOT}/workflows/cost-tiered-fix.js`

package/skills/doctor/SKILL.md

@@ -6,7 +6,9 @@ description: >
   machine-local state and the memory store live, and which skills shipped
   versus which this session can actually invoke. Disk facts come from a
   helper script; the context facts only the running session can answer, and
-  a disagreement between the two columns is the diagnosis.
+  a disagreement between the two columns is the diagnosis. Use when Leo asks
+  about Leo's loading, routing, or skill wiring. Do not use for project health
+  checks, project-code debugging, or unprompted inspection.
 when_to_use: >
   Leo asks whether the policy loaded, why routing or a skill is misbehaving,
   or invokes doctor by name after installing, updating, or switching harness.
@@ -37,14 +39,22 @@ argument, not a fault.
 
 `${CLAUDE_PLUGIN_ROOT}` is the Claude Code spelling. Codex exports
 `$PLUGIN_ROOT` and Cursor `$CURSOR_PLUGIN_ROOT`. On Hermes and OpenCode no
-plugin-root variable exists at all — but the policy already in your context had
-its placeholders substituted before injection, so the absolute path appears in
-its machine-local state paragraph. Read it from there. Being unable to locate
+plugin-root variable exists at all — the injected policy instead substitutes an
+absolute payload path into its `state.py` and `memory.py` commands. Read that
+command path from the policy as the discoverable source. Being unable to locate
 the payload at all is itself the first finding: the harness is not looking where
 the plugin was installed.
 
 Add `--json` when you want the same facts as data.
 
+Doctor validates the bootstrap that actually belongs to the named harness:
+the session hook and manifest for Claude, Codex, and Cursor;
+`config.instructions` in OpenCode's plugin; and Hermes registration plus its
+first-tool-result fallback. It also reports the running Python version against
+the supported 3.9+ floor. Codex hook trust is not provable from disk: review
+the plugin in `/hooks` and confirm it is trusted before treating the on-disk
+hook as active.
+
 ## Then answer the three it cannot
 
 A script can prove the hook is installed and that the policy renders. It cannot
@@ -56,13 +66,17 @@ prove the policy arrived. Only you can see your own context.
    then points at models that do not exist here.
 2. **Which skills are actually invocable?** Compare your own skill list against
    the script's shipped roster. Mind the naming rule: most harnesses namespace
-   them as `leo:<name>`, while OpenCode registers the directory by path and
-   names each skill from its own frontmatter, so they appear bare there. A
-   skill that looks missing on OpenCode may simply be listed without a prefix.
+   them as `leo:<name>`, while OpenCode has no namespace and requires a
+   skill's frontmatter name to match its directory, so the plugin registers a
+   generated shadow copy with every skill renamed `leo-<name>`. A skill that
+   looks missing on OpenCode may simply be listed as `leo-<name>` rather than
+   `leo:<name>`.
 3. **Is memory present and delivered?** The script reports whether the store
    exists and whether each native surface received its generated copy. Whether
    those facts are in front of you right now is something only you can confirm.
-   Report the two separately; they disagree more often than expected.
+   Report the two separately; they disagree more often than expected. Hermes's
+   projection is opt-in, so doctor reports it explicitly as disabled rather
+   than silently omitting it.
 
 ## Reading the report
 
@@ -72,10 +86,13 @@ three: **healthy**, **degraded**, or **not loaded**. Never free prose. `not
 loaded` outranks everything else: if the policy did not arrive, nothing else in
 the report describes how this session will actually behave.
 
-**Breadcrumb logs are history, not a verdict.** They carry no timestamps, and
-the test suite drives the failure paths deliberately, so entries accumulate on
-any machine where the tests have ever run. Quote the newest line if it is
-useful, but never conclude "the hook failed this session" from it.
+**Most breadcrumb logs are history, not a verdict.** Some older logs carry no
+timestamps, and the test suite drives failure paths deliberately, so entries
+can accumulate on a development machine. Quote the newest line if useful, but
+never conclude "the hook failed this session" from history alone. The one
+capability exception is `opencode-skills.log`: its presence means namespaced
+OpenCode skill registration degraded and doctor reports that state until the
+breadcrumb is cleared after the underlying problem is understood.
 
 ## Failure modes
 
@@ -83,9 +100,11 @@ useful, but never conclude "the hook failed this session" from it.
 |---|---|---|
 | Policy absent, bootstrap installed | the hook fired and failed open | read the newest breadcrumb, then confirm it describes this session before believing it |
 | Policy present, mapping names another harness | detection resolved wrong, usually a stray plugin-root variable exported in an unrelated shell | unset it, restart the session |
-| Harness reported as `unknown` | no `--harness`, and this harness exports no plugin-root variable | re-run with `--harness <name>` read off your mapping heading |
+| Harness reported as `unknown` | no `--harness`, and this harness exports no plugin-root variable | degraded until re-run with `--harness <name>` read off your mapping heading; a still-unknown explicit run is invalid wiring |
+| Codex hook is on disk but policy is absent | the new or changed hook may not be trusted | open `/hooks`, review the hook, and explicitly trust it |
+| OpenCode reports `opencode-skills.log` | the namespaced shadow tree failed and no bare-name fallback was registered | inspect the newest breadcrumb, fix the path/permission failure, and restart OpenCode |
 | Shipped roster exceeds what you can invoke | the harness cached an older payload, or the skills directory is not registered | update the plugin; on OpenCode check `opencode debug skill` for each skill's `location` |
-| Skills listed without the `leo:` prefix | OpenCode, working as designed | invoke them bare; not a fault |
+| Skills listed as `leo-<name>` instead of `leo:<name>` | OpenCode, working as designed | invoke them as `leo-<name>`; not a fault |
 | Tier names resolve to models this harness cannot run | mapping and harness disagree | same as row 2 |
 | Machine-local state not writable | the path override points somewhere unwritable | fix or unset it |
 | A skill is genuinely absent from disk | it was never added | see leo:writing-skills |

package/skills/executing-plans/SKILL.md

@@ -5,7 +5,8 @@ description: >
   with a check at every batch boundary, plan-intent-wins-on-architecture /
   reality-wins-on-mechanics arbitration, and one fix-then-re-review cycle
   before stopping to report. Used by the implementer agent, or the main loop
-  when it executes a plan directly.
+  when it executes a plan directly. Use when a written plan is about to become
+  code. Do not use for open-ended work without a plan or for reviewing a diff.
 when_to_use: >
   A written plan (from planner, an issue, or Leo's own outline) is about to
   be turned into code. NOT for open-ended implementation with no plan

package/skills/finishing-a-branch/SKILL.md

@@ -6,7 +6,9 @@ description: >
   a closed set of next steps — merge / PR / keep / discard — routes the
   chosen path through the right ordering (land the work before removing the
   worktree, remove the worktree before deleting the branch), and leaves the
-  repo clean.
+  repo clean. Use when reviewed implementation on a branch/worktree needs a
+  terminal disposition. Do not use to manage a worktree mid-task or replace
+  the review cycle.
 when_to_use: >
   A branch or worktree has reached "implementation done" and Leo needs to
   decide what happens to it. Fires after execute-then-review completes, or
@@ -71,7 +73,7 @@ Per option:
 | Option | Sequence |
 |---|---|
 | merge | merge locally or `gh pr merge` → remove worktree (`leo:worktrees`) → delete local branch |
-| PR | push branch → open PR → **stop** (worktree and branch stay; nothing is unmerged yet) |
+| PR | push branch → open PR → **stop** (worktree and branch stay; nothing is merged yet.) |
 | keep | do nothing destructive; leave worktree and branch as-is |
 | discard | typed confirmation (below) → remove worktree (`leo:worktrees`) → force-delete branch |
 

package/skills/freshness/SKILL.md

@@ -6,7 +6,9 @@ description: >
   committed to, its shape is confirmed against a source that reflects the
   version this project actually runs — the installed package, the lockfile
   pin, or documentation fetched this turn. Each check is recorded by symbol
-  and source in the report.
+  and source in the report. Use when writing, reviewing, or asserting a
+  third-party surface. Do not use for first-party code, pinned standard
+  libraries, or as a substitute for verification.
 when_to_use: >
   About to write, review, or assert the shape of a third-party surface — an
   import path, an argument list, a config key, an HTTP field, an auth
@@ -46,14 +48,25 @@ Outside these five, write the code.
 
 ## What counts as a source
 
-Ranked by closeness to the bytes that will actually execute.
+Two different questions — which to reach for, and which one wins.
 
-| Rank | Source | Why it counts |
-|---|---|---|
-| 1 | The installed package read on disk — `node_modules`, `site-packages`, `vendor` | It is the version this project runs; it cannot be out of date |
-| 2 | The lockfile pin plus that version's changelog or docs, fetched this turn | Right version, second-hand text |
-| 3 | Official documentation fetched this turn, version confirmed against the pin | Fetching without checking which version the page describes buys nothing |
-| 4 | A documentation tool the harness exposes for that vendor | Vendor-maintained, still confirm which version answered |
+**Lookup order.** Cheapest first; stop at the first that answers.
+
+1. A documentation tool the harness exposes for that vendor (Context7 and
+   the like) — one call, cheap.
+2. Official documentation fetched this turn — cheap.
+3. The lockfile pin plus that version's changelog — a narrow read.
+4. The installed package read on disk — `node_modules`, `site-packages`,
+   `vendor` — expensive; grep for the specific symbol, never read whole
+   files.
+
+Rungs 1 and 2 answer for whichever version they happen to describe, which is
+not always yours. Note the version each one reports and compare it to the pin;
+a cheap answer that cannot say which version it describes has not answered.
+
+**Authority.** When two sources disagree, the installed package wins — it
+is the version that will execute. A cheap source that contradicts it is
+wrong.
 
 Not sources: your recollection; an older file in this repo calling the same API,
 which may be the stale thing you are about to copy; a blog post; a search
@@ -97,8 +110,8 @@ to the lockfile without rerunning anything.
   case where they do not is the entire reason for the step.
 - "Another file here calls it this way" — that file may be what you are about
   to propagate.
-- "The typechecker will catch it" — a typechecker reads installed stubs, which
-  is a rank-1 source. Say so and cite it, rather than skipping and hoping.
+- "The typechecker will catch it" — a typechecker reads installed stubs, the
+  authority source. Say so and cite it, rather than skipping and hoping.
 - "It's one argument" — argument names are exactly what moves between majors.
 
 ## Reviewable finding

package/skills/memory/SKILL.md

@@ -5,7 +5,9 @@ description: >
   session and every plugin update. Covers what earns a place in the store,
   how a fact is written and revised, how to read one before acting on it,
   and when to throw one away. The store is canonical; each harness's own
-  memory surface receives a generated copy of the global facts.
+  memory surface receives a generated copy of the global facts. Use when a
+  durable preference, repo rule, decision, or machine quirk surfaces. Do not
+  use for current-task state or facts already recorded in the repository.
 when_to_use: >
   A fact surfaces that will still be true next month — a stated preference,
   a repo rule the code does not spell out, a settled decision, a machine
@@ -98,7 +100,15 @@ python3 "${CLAUDE_PLUGIN_ROOT}/scripts/memory.py" write repo convention "Generat
 ```
 
 Writing the same title again revises that file in place and keeps its original
-creation date. `list` shows what is stored; `read <ref>` returns one fact whole.
+creation date only when both title and type match exactly. A slug collision with
+a different title or type receives the next `-N` suffix; a corrupt occupied
+slot is never overwritten. `list` shows what is stored; `read <ref>` returns
+one fact whole.
+
+Leo-owned memory directories use mode `0700`; fact files and the generated
+`index.json` and `MEMORY.md` use `0600`. A newly generated projection is also
+private, while an existing user-owned projection target retains the mode the
+user chose.
 
 ## Read path
 

package/skills/resolve-ticket/SKILL.md

@@ -5,7 +5,8 @@ description: >
   context (Confluence, Slack, GitHub), investigate and plan at Opus tier, get
   Leo's explicit sign-off, implement on a worktree branch with sonnet/haiku
   executors, Opus-review the diff, then push and open a DRAFT pull request in
-  the browser.
+  the browser. Use when Leo names a tracked ticket to fix or implement. Do not
+  use for ad-hoc fixes without a ticket or independent-item batches.
 when_to_use: >
   Leo asks to fix or implement a specific tracked ticket by ID ("fix ENG-123",
   "/resolve-ticket PLAT-42"). NOT for ad-hoc fixes with no ticket (normal
@@ -23,6 +24,7 @@ allowed-tools:
   - Bash(git fetch *)
   - Bash(git rev-parse *)
   - Bash(git merge-base *)
+  - Bash(git check-ignore *)
   - Bash(git checkout *)
   - Bash(git switch *)
   - Bash(git add *)
@@ -137,8 +139,8 @@ Collect URLs from the ticket body, comments, attachments, and (Jira)
   tell Leo explicitly** that Slack must be configured independently in the
   current harness, then continue without it.
 - **GitHub PR/issue/commit** → `gh` view commands.
-- **Anything else** → whatever fetch tool this harness offers, one attempt;
-  `curl` is the fallback.
+- **Anything else** → use an available connector or fetch tool once. If none
+  is connected, report that context gap to Leo; do not use a shell HTTP fallback.
 
 Every failure or skip goes into a **context-gaps list** shown at the sign-off
 gate — Leo sees exactly what wasn't read before approving.
@@ -182,7 +184,8 @@ Only after Approve: `git fetch origin`, then create branch
 `fix/<TICKET-ID>-<slug>` off `origin/<defaultBranch>` in a worktree. Where the
 harness has a native worktree tool (see the *Worktrees* row of your mapping),
 use it and pair every enter with an exit. Otherwise, and on every harness that
-does not: `git worktree add -b fix/<id>-<slug> ../<repo>-fix-<id>
+does not: first prove `git check-ignore .claude/worktrees/fix-<id>` succeeds,
+then `git worktree add -b fix/<id>-<slug> .claude/worktrees/fix-<id>
 origin/<default>` and work by absolute paths.
 
 Executors in Step 6 must **NOT** be given their own worktree — this is one
@@ -202,8 +205,9 @@ Per plan step:
   specs, so the executor contract (do exactly this, stop on ambiguity) fits
   better than implementer's wider latitude. Anywhere the plan is thinner than
   that, use `implementer` as the policy says.
-- Steps touching disjoint files run as parallel spawns; dependent steps
-  sequential. Executors commit as they go.
+- Parallel spawns are read-only investigation only. All edits, test writes,
+  staging, commits, and other mutations are strictly sequential in the one
+  canonical `.claude/worktrees/fix-<id>` worktree. Executors commit as they go.
 - This loop implements directly only for trivial diffs (< ~10 lines) where
   writing the spec would cost more than the change.
 - Escalate, don't struggle: an executor reporting ambiguity or failing twice →
@@ -248,9 +252,11 @@ ticket, the approved plan, and the diff scope
    Same voice rules as /review-pr: no filler, no emoji, no self-praise.
    If a PR already exists for the branch, open that one instead and say so.
 3. `gh pr view --web` to open it in the browser.
-4. Leave the worktree (native tool where there is one, otherwise `git worktree
-   remove` once the branch is pushed). Do **not** write back to the ticket (no comment, no status
-   transition) — deliberate non-action; Leo asks separately if he wants it.
+4. Retain the worktree through PR merge. After merge, hand cleanup to
+   `leo:finishing-a-branch` / `leo:worktrees`; do not remove it merely because
+   the draft PR was opened. Do **not** write back to the ticket (no comment,
+   no status transition) — deliberate non-action; Leo asks separately if he
+   wants it.
 5. Final report: branch, PR URL, worktree path (left in place for follow-ups),
    checks run, review rounds used, remaining non-blocking notes.
 

package/skills/review-pr/SKILL.md

@@ -6,11 +6,12 @@ description: >
   submitted. Handles Leo's existing reviews: a stale pending review is
   replaced; posted threads are left, resolved, or get a staged reply.
   Reports the staged comments and a merge verdict in chat. Requires gh,
-  installed and authenticated.
+  installed and authenticated. Use when Leo asks to review a GitHub PR. Do not
+  use for a local working diff or to submit a review.
 when_to_use: >
   Leo asks to review a pull request by number ("review PR 42", "/review-pr 42")
   or "review the PR for this branch". NOT for reviewing the local working diff
-  (that is /code-review or the reviewer subagent) and NOT for submitting a
+  (that is the local reviewer subagent) and NOT for submitting a
   review — this only stages draft comments.
 argument-hint: "[pr-number]"
 allowed-tools:
@@ -26,6 +27,7 @@ allowed-tools:
   - Bash(git merge-base *)
   - Bash(git status *)
   - Bash(python3 */ghreview.py *)
+  - Bash(python3 "*/ghreview.py" *)
   - Agent
 ---
 
@@ -39,8 +41,8 @@ Run this at the **Opus tier** — it ends in a merge verdict, which is judge
 work. Tier map: Sonnet reads (the lens agents), Opus judges (this main loop).
 Your harness mapping names the concrete model for each, and says whether a
 per-spawn model override exists here at all; where it does not, the lenses run
-at whatever their registered agent runs. The staged
-review is created by `${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py` in ONE API call
+at whatever their registered agent runs. The staged review is created by
+`"${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py"` in ONE API call
 with no `event` field — that is what keeps it PENDING. Never use `gh pr review`
 (it always submits) and never set an `event` value.
 
@@ -97,7 +99,7 @@ Two kinds of prior review state, handled differently:
 it carries the script's own marker (it embeds one in everything it stages):
 
 ```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py clear-pending -R OWNER/REPO -n N
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py" clear-pending -R OWNER/REPO -n N
 ```
 
 If it exits 0, note what was deleted in the final report. If it exits 3, it
@@ -110,13 +112,17 @@ stage step, `--replace-pending --force`) once he confirms. Still pass
 **Posted (submitted) review threads of mine** — fetch them:
 
 ```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py threads -R OWNER/REPO -n N
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py" threads -R OWNER/REPO -n N
 ```
 
 Returns unresolved threads whose root comment is mine (threads from pending
-reviews are excluded automatically; `line` is null for file-level threads).
+reviews are excluded automatically). A true file-level thread has both
+`line: null` and `original_line: null`; report it as `path:file-level`. An
+outdated line thread can have `line: null`, `original_line: <N>`, and
+`is_outdated: true`; report it at `path:<N>` with an `outdated` label, not as
+file-level.
 For each thread, judge the original comment against the **current** diff
-(`ghreview.py extract` for that path — `is_outdated` means the nearby code
+(`ghreview.py extract` for that path — `is_outdated: true` means the nearby code
 changed, which is a hint, not a verdict) and pick one action, defaulting to
 *leave* when torn:
 
@@ -132,7 +138,7 @@ adjudication is complete.
 ## Step 2 — Map the diff and pick a route
 
 ```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py map -R OWNER/REPO -n N
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py" map -R OWNER/REPO -n N
 ```
 
 Returns per-file addressable-line ranges, `generated` flags (lockfiles, dist,
@@ -149,7 +155,7 @@ the post-exclusion size:
 
 Spawn three subagents at once using this harness's spawn mechanism — leo:delegation
 and the *Subagent spawn* row of your mapping name it. Use the read-only
-**explore** role, never a general-purpose agent: a lens is the agent that
+**review-lens** role, never a general-purpose agent: a lens is the agent that
 actually ingests the attacker-authored diff, and a general-purpose agent
 carries the full tool set including Write, Edit, and unrestricted Bash. This
 skill's `allowed-tools` govern this loop's turn, not the agents it spawns, so
@@ -166,7 +172,7 @@ sharded review that hits the agent cap.
 Do NOT ingest the full diff in this main loop on the standard
 path — the lenses read, you judge. Each lens gets: PR number, `OWNER/REPO`,
 title/body, its file list, and instructions to fetch its own diff slice via
-`gh pr diff N` or `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py extract -R OWNER/REPO -n N <paths…>`
+`gh pr diff N` or `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py" extract -R OWNER/REPO -n N <paths…>`
 (resolve the plugin root and pass the absolute path into the prompt — a
 subagent does not inherit your placeholder).
 
@@ -185,8 +191,10 @@ Charters:
    behavior, dead code, misleading names, genuine style nits worth a human's
    comment.
 
-Each lens returns findings as JSON only:
-`[{path, line, side: "RIGHT"|"LEFT", severity: "blocking"|"major"|"minor"|"nit", confidence: 0-100, note, fix?}]`
+Each lens returns JSON only:
+`{"status":"done"|"needs-context","findings":[{path, line, side:
+"RIGHT"|"LEFT", severity: "blocking"|"major"|"minor"|"nit", confidence:
+0-100, note, fix?}]}`
 with `line` as the absolute new-file line (RIGHT) it verified against the
 patch, and an instruction to cite the exact diff line — unverifiable findings
 get dropped in Step 4, so guessing wastes the lens's own work.
@@ -234,7 +242,7 @@ resolutions are public and go last, only once staging has succeeded):
    (`{"comments": [{path, line, side, body, start_line?, start_side?}]}`), then:
 
    ```
-   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py stage -R OWNER/REPO -n N \
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py" stage -R OWNER/REPO -n N \
      --commit <headRefOid> --input comments.json --replace-pending
    ```
 
@@ -255,7 +263,7 @@ resolutions are public and go last, only once staging has succeeded):
    scratchpad file:
 
    ```
-   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py reply -R OWNER/REPO -n N \
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py" reply -R OWNER/REPO -n N \
      --thread-id PRRT_… --body-file reply.txt
    ```
 
@@ -266,7 +274,7 @@ resolutions are public and go last, only once staging has succeeded):
 3. **Resolve stale threads** — one call per Step 1 resolve action:
 
    ```
-   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py resolve-thread -R OWNER/REPO -n N \
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ghreview.py" resolve-thread -R OWNER/REPO -n N \
      --thread-id PRRT_…
    ```
 
@@ -283,6 +291,8 @@ error.
 
 1. Staged comments as a table: `path:line — comment`.
 2. Existing threads as a table: `path:line — left / resolved / reply staged`
+   (use `path:file-level` only when both anchors are null; otherwise use
+   `path:original_line` with an `outdated` label when the current line is null)
    (+ what was said in staged replies; note if a stale pending review was
    replaced, and that resolutions are already live).
 3. Unstaged findings (dropped anchors, overflow past the cap) — clearly marked.