@mrciphersmith/keryx 0.3.82 → 0.3.83

package/dist/cli.js

@@ -17288,7 +17288,7 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-jev-scenarios": 187,
     "review/review-layout": 238,
     "review/review-logic": 377,
-    "review/review-orchestrator": 1723,
+    "review/review-orchestrator": 1712,
     "review/review-performance": 374,
     "review/review-pr-feedback": 895,
     "review/review-regression": 216,
@@ -21098,7 +21098,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@mrciphersmith/keryx",
-    version: "0.3.82",
+    version: "0.3.83",
     description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
     private: false,
     publishConfig: {

package/dist/core.js

@@ -10853,7 +10853,7 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-jev-scenarios": 187,
     "review/review-layout": 238,
     "review/review-logic": 377,
-    "review/review-orchestrator": 1723,
+    "review/review-orchestrator": 1712,
     "review/review-performance": 374,
     "review/review-pr-feedback": 895,
     "review/review-regression": 216,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.82",
+  "version": "0.3.83",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -1203,25 +1203,25 @@ Ask unless automation settings explicitly set `publish_pr_review_report`:
 ```text
 Publish the review report to the PR?
 
-  A) Concise PR comment only
-  B) Concise PR comment + detailed AI markdown artifact (recommended for follow-up fixes)
+  A) Concise PR review only
+  B) Concise PR review + detailed AI markdown artifact (recommended for follow-up fixes)
   C) Do not publish
 
 > pick a letter (default: C)
 ```
 
 **Rules:**
-- The PR comment and AI artifact must be written in English only, regardless of the chat language or reviewer output language.
+- The PR review and AI artifact must be written in English only, regardless of the chat language or reviewer output language.
 - Default is C. Never publish to a PR without explicit user confirmation or `publish_pr_review_report: comment`, `publish_pr_review_report: comment-and-ai-artifact`.
-- If the user chooses A, delegate concise comment formatting to `review-orchestrator`'s PR Review Report Publication contract.
+- If the user chooses A, delegate concise review formatting to `review-orchestrator`'s PR Review Report Publication contract.
 - If the user chooses B, also generate `.metaproject/jobs/<job-name>/review-ai-report.md` using `review-orchestrator`'s Detailed AI Markdown Artifact contract, and include in the comment's `Meta` section both an `AI artifact` path and an `AI artifact description` row explaining that the file carries detailed findings, fix guidance, patch guidance, regression coverage, validation plan, and follow-up agent context.
 - **If no PR exists yet**, do not ask now and do not stash a pending decision — nothing persists one. Ask this question again after the PR step (2.10) creates the PR, when the answer can actually be acted on.
 - The decision is acted on immediately or not at all. There is no `publication_plan` field in `state.json`; what was published is stated in the 2.9 report.
 
 **Automation values:**
 - `publish_pr_review_report: ask` -> ask the question above.
-- `publish_pr_review_report: comment` -> publish the concise PR comment only.
-- `publish_pr_review_report: comment-and-ai-artifact` -> publish the concise PR comment and create the detailed AI markdown artifact.
+- `publish_pr_review_report: comment` -> publish the concise PR review only.
+- `publish_pr_review_report: comment-and-ai-artifact` -> publish the concise PR review and create the detailed AI markdown artifact.
 - `publish_pr_review_report: none` -> do not publish.
 
 #### 2.6.3 Post-Review Checkpoint

package/src/gdskills/bundled/skills/review/review-orchestrator/SKILL.md

@@ -1564,15 +1564,18 @@ in `templates/review-report.md`: `Changes requested` or `No blockers, merge-read
 Render the human report from that file. Do not invent a second skeleton here.
 
 ```markdown
-**Changes requested — 1 Blocker, 2 Major, 4 Minor, 1 question.** Reviewed `<head>` against `<base>` (round N). <what holds, and where the risk is.>
+<!-- slot:pre-verdict -->
+**Changes requested — 1 Blocker, 2 Major, 4 Minor, 1 question.** <what holds, and where the risk is.>
+Reviewed `<head>` against `<base>` · round N · <files> files, +<add>/−<del> · CI <state>.
+<!-- slot:after-verdict -->
 
 ### Blocker
-**F-001. <one-sentence claim>.** `path/to/file.ts:line`, in the diff.
+**F-001. <one-sentence claim>.** [`path/to/file.ts:line`](<blob link at head>), in the diff.
 <proof: traced path, probe, or failing scenario>
 Fix: <concrete>
 
 ### Major
-**F-002. <one-sentence claim>.** `path/to/file.ts:line`, pre-existing — render under Pre-existing instead when location_class says so.
+**F-002. <one-sentence claim>.** [`path/to/file.ts:line`](<blob link at head>), in the diff.
 
 ### Minor
 - **F-010. <claim>.** `path:line`, in the diff — <proof and fix, one to three sentences>.
@@ -1580,21 +1583,7 @@ Fix: <concrete>
 ### Questions
 1. <an info finding that needs an author answer; other info is not published>
 
-### Pre-existing (not blocking)
-- **F-020. <claim>.** `path:line` — <why it is out of this diff>
-
-### Verified clean
-- <what was checked> — <how>
-
-### How this review was run
-- **Workflow:** `review-orchestrator`
-- **Scope:** `<base>..<head>`, round N, PR #N
-- **Models:** <actual models and reviewers, or not recorded>
-- **Tools:** <tools actually invoked, or not recorded>
-- **Skills:** <skills actually used, or not recorded>
-- **Subagents:** <dispatched reviewers and models, or none when confirmed; otherwise not recorded>
-- **Not run:** <reviewer — reason>
-- **Verification:** <mode>; confirmed N, refuted N, unverifiable N, unverified N
+<details> Pre-existing (not blocking) · Verified clean <!-- slot:verified-clean --> · How this review was run — **Workflow:**, **Scope:**, **Models:**, **Tools:**, **Skills:**, **Subagents:**, **Not run:**, **Verification:** <!-- slot:how-run --> </details>
 ```
 
 Pick the domain file the same way reviewers are picked: frontend scope, or a
@@ -1650,8 +1639,8 @@ the report exists, unless `publish_pr_review_report` is already set:
 ```text
 Publish this review report to the PR?
 
-  A) PR comment only
-  B) PR comment + follow-up file (recommended when a fix round will follow)
+  A) PR review only
+  B) PR review + follow-up file (recommended when a fix round will follow)
   C) Do not publish
 
 > pick a letter (default: C)
@@ -1659,15 +1648,15 @@ Publish this review report to the PR?
 
 Automation values, names unchanged:
 
-- `comment` or legacy `true` -> the PR comment only.
-- `comment-and-ai-artifact` -> the PR comment plus the follow-up file.
+- `comment` or legacy `true` -> the PR review only.
+- `comment-and-ai-artifact` -> the PR review plus the follow-up file.
 - `none` or legacy `false` -> do not publish.
 
 Default is do not publish. No resolvable PR number means skip and say so.
 
-The comment is the report rendered from `templates/review-report.md`, English, with the domain file chosen above (`templates/pr-comment-frontend.md` / `templates/pr-comment-backend.md`) — never a summary written freehand. It does not use a tool heading, a finding table, or a meta table. It does not carry a co-author line, a `Generated with` trailer, or any sentence that names a vendor or a product as the author. Name the workflow and reviewers that actually ran, with models, tools, skills and subagents. Never identify the operator from `gh auth status`, git config or a credential; do not sign the comment as a person, reviewer or model.
+The review body is the report rendered from `templates/review-report.md`, English, with the domain file chosen above (`templates/pr-comment-frontend.md` / `templates/pr-comment-backend.md`) — never a summary written freehand. It does not use a tool heading, a finding table, or a meta table. It does not carry a co-author line, a `Generated with` trailer, or any sentence that names a vendor or a product as the author. Name the workflow and reviewers that actually ran, with models, tools, skills and subagents. Never identify the operator from `gh auth status`, git config or a credential; do not sign the review as a person, reviewer or model. A project overlay adds content only through the template's overlay slots.
 
-The follow-up file path and the metadata rules (real model names, Run vs Not run, no `adaptive` in the model slot) live in that same template. Write the body to a temp file and post with `gh pr comment <n> --body-file <file>`.
+The follow-up file path and the metadata rules (real model names, Run vs Not run, no `adaptive` in the model slot) live in that same template. Write the body to a temp file and post it as one formal review whose state follows *Where it is posted* in the template: `gh pr review <n> --request-changes|--approve|--comment --body-file <file>`. On a merged or closed PR, post it as `gh pr comment <n> --body-file <file>` instead.
 
 **No GitHub write without an approved draft.** Before ANY write — the comment, a thread reply, `keryx review comments reply`, a review — show the user the rendered body and wait for explicit approval of that body.
 Picking A or B above chooses *whether* to publish, not *what*; a comment is public and cannot be unsent. With no user to answer (a dispatched run), do not write: hand the rendered body back to the caller.

package/src/gdskills/bundled/skills/review/review-orchestrator/templates/review-report.md

@@ -1,15 +1,56 @@
 # Review report (render)
 
 The shape of the report a human reads at the end of a round, and of the PR
-comment when one is published. Machine contracts are unchanged: severity stays
+review when one is published. Machine contracts are unchanged: severity stays
 `blocker | major | minor | info`, the output verdict stays
 `APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES`, and the `keryx:findings`
-block still rides after the prose. This file says how that record is *shown*.
+block still rides after the prose in the ingested copy. This file says how that
+record is *shown*.
 
 Read `templates/pr-comment-frontend.md` or `templates/pr-comment-backend.md`
-for the domain checklist. This file is the skeleton both share.
+for the domain checklist. This file is the skeleton both share, and the slots a
+project overlay may fill.
 
-## How the visible verdict is chosen
+## Where it is posted
+
+On a pull request the report is the **body of one formal review**, so it
+counts as a review and not as a comment stream:
+
+| Machine `verdict` | Review state |
+|---|---|
+| `REQUEST_CHANGES` | Request changes, if the reviewer may; on the reviewer's own PR GitHub rejects it, so Comment |
+| `APPROVE` / `APPROVE_WITH_SUGGESTIONS` | Approve, if the reviewer may approve; else Comment |
+| PR already merged or closed | a plain PR comment — a review state no longer gates anything |
+
+One report per round, posted once. The `keryx:findings` block is never posted;
+it lives in the copy `keryx review ingest` reads. If the body would exceed
+GitHub's 65,536-character limit, post the visible part and link the follow-up
+file for the rest.
+
+## The skeleton
+
+Sections in this order. Omit a heading that has no content. The visible part is
+what a reader must act on; everything else is folded.
+
+```markdown
+<!-- slot:pre-verdict -->
+**Changes requested — 1 Blocker, 2 Major, 4 Minor, 1 question.** <what holds, and where the risk is — one sentence.>
+Reviewed `<head>` against `<base>` · round N · <files> files, +<add>/−<del> · CI <green | red: check names>.
+<!-- slot:after-verdict -->
+
+### Prior findings            (fix rounds only)
+### Blocker
+### Major
+### Minor
+### Questions
+
+<details><summary><b>Pre-existing (not blocking)</b></summary> … </details>
+<details><summary><b>Scope</b></summary> … </details>          (only when a pr-process note exists)
+<details><summary><b>Verified clean</b></summary> … <!-- slot:verified-clean --> </details>
+<details><summary><b>How this review was run</b></summary> … <!-- slot:how-run --> </details>
+```
+
+### The verdict line
 
 Map the machine verdict, do not invent a fourth one:
 
@@ -19,60 +60,71 @@ Map the machine verdict, do not invent a fourth one:
 | `APPROVE` | `**No blockers, merge-ready.**` |
 | `APPROVE_WITH_SUGGESTIONS` | `**No blockers, merge-ready — N Minor, N questions.**` |
 
-`N` is the count of findings **in the changed code** at that severity. A
-`location_class: pre-existing` finding is not in that count and does not flip
-the verdict. Omit a zero Blocker count. A question is an `info` finding that
-needs an author answer, rendered under Questions, not as a finding.
-
-Then one sentence: what holds, and where the risk is. Name the commits
-reviewed: `Reviewed <head> against <base> (round N).` If head moved during the
-round, name the commits not checked.
+`N` counts findings **in the changed code** at that severity. A
+`location_class: pre-existing` finding is not counted and does not flip the
+verdict. Omit a zero count. A question is an `info` finding that needs an
+author answer, rendered under Questions, not as a finding.
 
-## Section order
-
-1. Verdict line.
-2. Blocker, then Major. Omit a heading that has no findings.
-3. Minor.
-4. Questions.
-5. Pre-existing (not blocking). Omit if empty.
-6. Scope — only when a process note exists (`location_class: pr-process`).
-7. Verified clean. Required. Not a list of compliments.
-8. How this review was run.
-9. The `keryx:findings` fence, after the prose, unchanged.
-
-No `## AI Review Report`, `# AI Review Report`, `## AI Summary`, `## Positive
-Notes`, or any heading that names the tool instead of the subject. No
-`Generated with`, no bot signature, no co-author trailer. A model name appears
-only in **How this review was run**, as the model that ran, never as an author.
+The second line is the context line: head, base, round, size, CI. If head moved
+during the round, add `· unchecked: <commits>`.
 
 ## One finding
 
-Blocker and Major, as a paragraph:
+Blocker and Major as a paragraph, visible:
 
 ```markdown
-**F-012. The guard is not called on the save path.** `src/store.ts:88`, in the diff.
-`save()` awaits `api.put` and then writes the form with no `runInAction`. A response that lands after unmount still mutates the store.
+**F-012. The guard is not called on the save path.** [`src/store.ts:88`](https://github.com/<owner>/<repo>/blob/<head>/src/store.ts#L88), in the diff.
+`save()` awaits `api.put` and then writes the form with no `runInAction`. A response that lands after unmount still mutates the store. Probe: <what was run, and what it printed>.
+Also at: `src/other.ts:12`, `src/third.ts:40`.
 Fix: wrap the write in `runInAction`, and ignore the response when `disposed` is set.
 ```
 
-Minor, as one list item, proof and fix in one to three sentences:
+Minor as one list item, proof and fix in one to three sentences:
 
 ```markdown
-- **F-019. Icon button has no accessible name.** `src/Toolbar.tsx:14`, in the diff — the control is an icon with no `aria-label`, so a screen reader announces nothing. Fix: add an `aria-label` from `t()`.
+- **F-019. Icon button has no accessible name.** [`src/Toolbar.tsx:14`](…), in the diff — the control is an icon with no `aria-label`, so a screen reader announces nothing. Fix: add an `aria-label` from `t()`.
 ```
 
 Rules:
 
 - Bold first line is the claim, one sentence. Then `file:line` and the location
   class: `in the diff`, `pre-existing`, or `pr-process`.
-- Proof is a traced path, a probe that was run, or a concrete failing scenario.
-  Not "this looks wrong".
+- `file:line` links to the blob at the **reviewed head SHA**, not to a branch,
+  so the link still points at the reviewed line after the author pushes.
+- Proof is a traced path, a probe that was run (with what it printed), or a
+  concrete failing scenario. Not "this looks wrong".
+- A class with several sites is one finding with an `Also at:` line, never one
+  finding per site.
 - `Fix:` is concrete. A suggested fix is unchecked code: do not publish a fix
-  you have not checked the same way you checked the finding.
+  you have not checked the same way you checked the finding. A GitHub
+  `suggestion` block is allowed only for a fix that was checked.
+- Finding ids (`F-NNN`) are stable across rounds: a re-raised finding keeps its
+  id, a new one takes the next free number.
 - No finding table. A table is allowed only for short cells: ids, `file:line`,
   counts, statuses, before/after, pass/fail. A cell longer than about ten words
   is not a table cell.
 
+When there are more than five Minor findings, wrap the Minor list in
+`<details open><summary><b>Minor (N)</b></summary>` so the page stays scannable.
+
+## Prior findings (fix rounds)
+
+On a round with `is_fix_round: true`, the disposition of every prior finding
+comes before the new ones, as a short table:
+
+```markdown
+### Prior findings
+| Id | Finding | Status | Evidence |
+|---|---|---|---|
+| F-003 | Delete frame dropped on cache miss | closed | probe at `<head>`: handler fires |
+| F-007 | Pending key built by hand | partial | 2 of 4 sites |
+```
+
+Statuses: `closed`, `open`, `partial`, `regressed`, `withdrawn`. A withdrawn
+finding names what made it wrong, in one sentence, and is listed first. A defect
+a fix introduced is a new finding, rendered under its severity with
+`regressed from F-NNN`.
+
 ## Questions and pre-existing
 
 `info` is not published as a finding. If it needs an author answer, render it
@@ -88,7 +140,6 @@ One line per check that was actually run and held: what was checked, and how.
 Do not list a checklist item that was not checked. Do not praise.
 
 ```markdown
-### Verified clean
 - MobX write after `await` — every `await` in the diff is followed by `runInAction` or an early return on `disposed`.
 - i18n — `t()` appears only in render; no `defaultValue`.
 ```
@@ -101,7 +152,6 @@ git config, a credential or a PR author. Use `not recorded` when evidence for
 a tool, skill or model is unavailable; use `none` only when the run proves none.
 
 ```markdown
-### How this review was run
 - **Workflow:** `review-orchestrator`; severity and lanes per the repository review rules, else the canonical rubric in this skill.
 - **Scope:** `<base>..<head>`, round N, PR #N. Unchecked commits: <list or none>.
 - **Models:** <actual model names and the reviewers that ran on each; or not recorded>.
@@ -118,7 +168,7 @@ a tool, skill or model is unavailable; use `none` only when the run proves none.
 - **Reviewed at:** <UTC timestamp>
 ```
 
-Model rules, unchanged from the old metadata table:
+Model rules:
 
 - Name the model that actually ran. Never write `adaptive`, `inherit`,
   `unsupported`, or `current-session` in the model slot.
@@ -128,17 +178,50 @@ Model rules, unchanged from the old metadata table:
 - Keep **Run** complete. If Not run is long, group it with counts and notable
   names; the full list belongs in the follow-up file.
 
+## Formatting rules
+
+- Lead with the conclusion. Nothing above the verdict except a `pre-verdict`
+  slot an overlay fills.
+- Visible part: verdict, context line, prior findings, Blocker, Major, Minor,
+  Questions. Everything else is inside `<details>`.
+- Leave a blank line after every `<summary>…</summary>` and before
+  `</details>`; GitHub renders the Markdown inside only then.
+- Code, paths, flags and identifiers in backticks. No screenshots of code.
+- No `## AI Review Report`, `# AI Review Report`, `## AI Summary`,
+  `## Positive Notes`, or any heading that names the tool instead of the
+  subject. No `Generated with`, no bot signature, no co-author trailer. A model
+  name appears only in **How this review was run**, as the model that ran,
+  never as an author.
+
+## Overlay slots
+
+A project overlay (for example a repository facade over this engine) extends the
+report **only** by filling these slots. It may not reorder, rename or remove a
+base section, add a severity level, or change the verdict mapping.
+
+| Slot | Where | Typical content |
+|---|---|---|
+| `pre-verdict` | above the verdict line | a scope verdict that comes before severity, e.g. "Mis-scoped: split" |
+| `after-verdict` | right after the context line | round status, round cap, review-state rationale, a table of other reviewers' open items |
+| `verified-clean` | end of Verified clean | the project's mandatory checks, each with how it was checked |
+| `how-run` | end of How this review was run | project orchestrator name, overlays selected and skipped, project packages applied, rule files read |
+
+An overlay may also map the review state more strictly (for example "any Major
+→ Request changes"), never more loosely than the table in *Where it is posted*.
+An empty slot leaves no trace in the output. The `<!-- slot:… -->` markers are
+rendering guides and are not posted.
+
 ## Follow-up file
 
 When publication is `comment-and-ai-artifact`, write the long form beside the
-job, not into the PR comment:
+job, not into the PR review:
 
 ```text
 jobs/reviews/pr-<number>/review-report.md
 .metaproject/jobs/<job-name>/ai/review-report.md
 ```
 
-Same section order as the comment. YAML front matter may keep the machine
+Same section order as the review. YAML front matter may keep the machine
 verdict (`APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES`) because ingest
 reads it. The visible title is the subject of the change, never a tool name.
 No co-author line in the file either.