@mrciphersmith/keryx 0.3.120 → 0.3.122

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

@@ -0,0 +1,180 @@
+---
+name: review-premise
+model_tier: deep
+description: |
+  Use when: findings exist and someone is about to act on them — after the verifier in a
+  review round (Wave D), or before a fix loop implements a finding that came from a
+  follow-up issue or an external review comment. Judges whether each finding is a defect
+  at all, on intent, accepted practice, consistency and fix soundness, and returns
+  upheld | downgraded | challenged | owner-decision. It can only lower a severity or hold a
+  finding for the operator; it never adds a finding, raises a severity or edits its text.
+  NOT for: first-pass review (run domain reviewers first); checking whether a finding
+  reproduces (review-verifier); dismissing a finding, which only the operator does.
+triggers:
+  - "judge the premise of these findings"
+  - "review --premise"
+  - "is this standard practice"
+  - "is this finding a real defect"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+  origin: "authored"
+license: "MIT"
+---
+
+# Review — Premise
+
+Wave D. A finding can reproduce and still be wrong. The verifier asks whether the fact a
+finding names is there; this judge asks whether that fact is a defect. It reads each
+finding on a clean context, judges it, and emits one premise claim per finding. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs.
+
+## The case this exists for
+
+A final review reported: *the playback timeline is pinned LTR — two components hard-code
+`dir="ltr"`, so the timeline does not mirror in RTL.* The fact was true and reproduced.
+The finding was still wrong. Platform guidance says media playback controls and their
+progress indicator do not mirror (Material Design, Bidirectionality; Apple HIG, Right to
+left), and the code carried three signals of a deliberate choice: the explicit override,
+a lint exemption naming that area a physical-LTR island, and a sibling media control
+forcing the same direction. The finding was implemented; two reviews of the fix checked
+only the implementation. Asked "is this standard practice?", a model refuted it in one turn.
+
+## Workflow
+
+```
+review-premise Progress:
+- [ ] Step 1: Drop every finding below `minor`
+- [ ] Step 2: Per finding, read only its bare claim (title, file, quote) and the code there; form a view
+- [ ] Step 3: Collect intent signals at and around the site (see question 1)
+- [ ] Step 4: Answer the four questions
+- [ ] Step 5: Only now read the reviewer's problem, impact, evidence and suggested_fix; revise if they show something you missed
+- [ ] Step 6: Emit one premise claim per finding judged, and nothing else
+```
+
+The order of steps 2 and 5 is the point. A reviewer's argument read first anchors the
+judgement on it; the claim and the code read first let you see what the reviewer did not.
+
+## Input Contract
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `findings` | array | yes | Canonical findings (`review-finding.schema.json`), each with its display `id`, unique in the package (the caller renumbers a collision, a new finding sharing a carried one's id included, in the saved reviewer results before you run): your claim's `finding_id` (a claim may name an id the duplicate merge absorbed; it then targets the surviving finding). A display `id` holds no `#`, the global_id separator (`<reviewId>#<id>`): ingest refuses one, so the caller names a finding of several waves `<raw stem>:<id>` (`review-logic-w1:F-001`), never `review-logic-w1#F-001`. Several judge dispatches each return one claims file; `review ingest --premises` takes them all. Only a finding carried from an earlier round also has a `global_id` (ingest mints the rest after you run); a claim may name a carried finding by it. Each has `reviewer`, `severity`, `source` (`external` marks a PR comment), `file`, `quote`, `problem`, `suggested_fix`. In a delta round, only findings with no carried premise. |
+| `judge` | string | yes | Your own name. Recorded on the claims file. |
+| `source` | string | no | `round` (default), `follow-up-issue` or `external-comment`: where the findings came from. The last two have no review package: each finding is the issue or comment text as `problem`, its `file:line` refs as `file`/`line` with the code there as `quote`, the comment's `C-NNN` (review-pr-feedback) or the issue's number as `id` with its URL as `url`, its author as `reviewer` and the severity it states (else `minor`). The caller saves your claims beside its own record (a flow: `<flow-dir>/premise/<n>.json`) and journals the operator's answer; no `ingest` or `decide-premise` runs, so the caller applies every refusal of the merge (`PREMISE_REJECTION_REASONS`, `src/review/premise.ts`) by hand. For one finding those are: any claim on a finding below `minor` (`below-minor`); an uncited `challenged` or `downgraded`; a `downgraded` with no `severity`, or with the finding's own severity (`not-a-downgrade`) or a higher one (`raise-severity`); a `severity` on any other verdict (`severity-without-downgrade`); a downgrade of an external or `review-security-code` finding, of a `minor`, or below `minor`; a hold without a `question`; an `owner-decision` with fewer than two options; a judge that raised the finding. |
+| `branch` / `base_sha` | string | no | So `git log` and `git blame` read the change under review, where your host gives you git; on keryx shell the caller passes their output in `context_files`. |
+
+## The four questions
+
+1. **Intent.** Is the thing called a defect a deliberate choice? Look for an explicit
+   override (`dir="ltr"`, `!important`, a pinned version, a forced flag), a suppression or
+   exemption (a lint disable, a `@ts-expect-error` with a reason, an allowlist entry), a
+   comment or commit message giving a reason (`git log -L <start>,<end>:<file>`, `git blame`, `git show <sha>`
+   where your host gives you git; on keryx shell, the history excerpts the caller passes in `context_files`), and
+   sibling code doing the same. A signal does not prove the choice right; it proves someone chose, so the finding has to show their reason wrong.
+   A signal the branch under review itself introduces (in `git log <base>..<head>`, or in lines
+   the diff adds) is not evidence of a prior deliberate choice: the change cannot ratify itself.
+2. **Accepted practice.** What do platform guidelines (Material Design, Apple HIG, WCAG,
+   the framework's own docs), the language's idioms, clean-code principles and common
+   patterns say? Then the project's own rules, with their known exceptions. A project rule
+   applied where accepted practice makes an exception is not a defect.
+3. **Consistency.** Would the suggested fix make the system more consistent or less? A fix
+   that makes one site differ from siblings doing the same thing is evidence against the
+   premise, not a follow-up.
+4. **Fix soundness.** Would a senior reviewer reject the suggested fix? A fix that is wrong
+   for the platform usually means the premise is wrong too.
+
+## Verdicts
+
+| Verdict | Meaning | Must carry |
+|---|---|---|
+| `upheld` | The premise stands; the finding goes on unchanged. | — |
+| `downgraded` | A defect, but intent or practice shows it is smaller than reported. Never for a `minor`, an external or a `review-security-code` finding: hold those with `challenged` or `owner-decision` instead. | `severity`, strictly lower and never below `minor`, and ≥1 `intent_signals` or `practice_sources` |
+| `challenged` | Evidence says it is not a defect. | ≥1 `intent_signals` or `practice_sources`, and a `question` |
+| `owner-decision` | A product choice the code cannot settle either way. | a `question` and ≥2 `options` |
+
+`challenged` and `owner-decision` **hold** the finding: it does not count as an open
+blocker or major, it is not sent to a fixer, and the verdict lists it as awaiting the
+operator, who answers with `keryx review decide-premise` (`uphold` or `dismiss`). You never
+dismiss. `upheld` is the normal answer: a finding with a trigger, an outcome, no intent
+signal and no practice source against it is upheld.
+
+## Iron Laws
+
+| Rule | Why |
+|------|-----|
+| **You can only lower or hold.** No new finding, no raised severity, no edit to a finding's text. | The merge builds the record from the original finding and takes only your verdict; a claim carrying more is rejected (`unknown-property`), an entry that is no object too (`malformed-claim`). |
+| **Never judge your own finding.** | The merge rejects a judge equal to the reporter (`self-judgement`). |
+| **Claim first, argument second.** | The case passed two reviews that read the fix's argument and never the premise. |
+| **`challenged` cites.** Each intent signal names its `ref` (`file:line` or a SHA) and what it says; each practice source names the guideline and section precisely enough to look up. | An uncited challenge is rejected and the finding stays as reported. Never invent a quote. |
+| **Never re-grade by the rubric.** Severity is the reviewer's and the verifier's call; a test gap or a surviving mutant stays as reported unless intent or practice shrinks it, and a minor is upheld or challenged, never downgraded. | An uncited downgrade is rejected (`downgrade-without-evidence`). Minors matter: a finding you weaken is one nobody fixes. |
+| **Read-only.** Read files; run nothing but `git log`, `git blame` and `git show`, and those only where your host gives a read-only child git. On keryx shell you have no shell and no git tool: read the history excerpts in `context_files`, or say the history was not read. | Executing is the verifier's job; this judgement is about meaning. |
+| **An external finding, and a `review-security-code` finding, is held or upheld, never dismissed or downgraded.** | A human asked; the operator answers them. Severity of a security finding measures exposure, which intent does not lower. The merge rejects the downgrade (`external-downgrade`, `security-downgrade`). |
+
+## Output Contract
+
+```
+STATUS: DONE | NEEDS_CONTEXT | BLOCKED
+```
+
+- `DONE` — every finding given was judged or explicitly left alone (below `minor`).
+- `NEEDS_CONTEXT` — the code at a finding's site cannot be read; say which.
+- `BLOCKED` — the findings input is unreadable or carries no ids.
+
+Then one premise claims object. The orchestrator saves it unchanged as the file
+`keryx review ingest --premises <file>` reads:
+
+````text
+```json keryx:premises
+{
+  "judge": "review-premise",
+  "model": "<model id>",
+  "premises": [
+    {
+      "finding_id": "LY-003",
+      "verdict": "challenged",
+      "intent_signals": [
+        { "ref": "src/player/TimelineSlider.tsx:150", "says": "explicit dir=\"ltr\" on the timeline root" },
+        { "ref": "eslint.config.js:42", "says": "exemption names this area a physical-LTR scroll/pixel island" },
+        { "ref": "src/player/MediaControls.tsx:81", "says": "sibling media control forces the same direction" }
+      ],
+      "practice_sources": [
+        { "name": "Material Design — Bidirectionality", "says": "media playback controls and progress do not mirror" },
+        { "name": "Apple HIG — Right to left", "says": "video controls and timeline indicators keep their direction" }
+      ],
+      "reasoning": "The fact reproduces, but LTR is the platform practice for playback and the code chose it three times.",
+      "question": "The timeline is LTR on purpose, as platforms do. Keep it, or mirror it anyway?",
+      "options": ["dismiss — keep LTR, as platforms do", "uphold — mirror the timeline"]
+    },
+    { "finding_id": "LG-002", "verdict": "downgraded", "severity": "minor", "intent_signals": [{ "ref": "src/a.ts:12", "says": "comment: legacy fallback kept until v3, read-only" }], "reasoning": "A real defect in a path the code marks as legacy and read-only." },
+    { "finding_id": "LG-004", "verdict": "upheld", "reasoning": "No signal of intent; the null path is reachable from the form reset." }
+  ]
+}
+```
+````
+
+Then a short markdown summary: counts per verdict, and for each held finding its id, the
+question, and the signals or sources behind it.
+
+## Scope Boundaries
+
+| Concern | This skill | Use instead |
+|---------|------------|-------------|
+| Whether a finding is a defect at all | YES | — |
+| Lowering a severity, holding a finding for the operator | YES | — |
+| Whether a finding reproduces | NO | `review-verifier` |
+| Adding a finding, raising a severity, editing one | **NO** | a domain reviewer in a new round |
+| Dismissing a finding | NO | the operator: `keryx review decide-premise --answer dismiss` |
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|----------------|-----------------|
+| "The fact reproduces, so the finding is right." | Reproducing proves the fact, not the defect. The case reproduced. |
+| "The reviewer's argument is convincing." | That is why you read it last. |
+| "A sibling does the same; that is a follow-up." | A sibling doing the same is a signal of intent, against the premise. |
+| "The project rule says X, so any deviation is a defect." | Check the rule against platform practice and its known exceptions first. |
+| "It is clearly wrong; I will mark it dismissed." | You cannot dismiss. Hold it with a question; the operator decides. |
+| "Challenge anything ambiguous, to be safe." | A held finding costs the operator a question. Without a cited signal or source it is upheld. |
+| "I will run the tests to be sure." | Read-only. Running something is the verifier's method, not yours. |

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

@@ -22,15 +22,14 @@ license: "MIT"
 # Review: Regression
 
 You are reviewing **scope B** of a deep round. The files you are given are not
-under review. They are under **regression check**. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`.
+under review. They are under **regression check**. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`, except the read-only `git log`, `git blame` and `git show` where its host gives a read-only child git (keryx shell does not: there the payload supplies the history).
 
 ## The one question
 
 > Does this change break an existing behaviour here?
 
 Not "is this code good". Not "would I have written it this way". The blast-radius
-set is code that already worked; your job is to find where the change stops it
-working.
+set is code that already worked; your job is to find where the change stops it working.
 
 This is enforced, not requested. `keryx review ingest` runs
 `screenBlastRadiusFindings` over the findings this scope returns and refuses
@@ -171,6 +170,7 @@ Severity comes from **Severity (canonical)** in `review-orchestrator/SKILL.md`;
 1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot name the input, call, or condition that reaches the code, you have an observation, not a finding. Report it as `info` and say what would settle it.
 2. **Never flag the theoretical.** The path you describe must exist in the code under review. Do not report a safe API because it could be misused, or a pattern because it is often wrong elsewhere.
 3. **One finding per class, not one per occurrence.** When the same shape appears at several sites, report it once and list every site. Ten findings that are one finding hide the other nine problems.
+4. **A deliberate choice is not a defect until its reason is read and shown wrong.** An explicit override, suppression or exemption, a comment or commit giving a reason, or a sibling doing the same is a decision: read its reason (the comment, `git log -L` or `git blame`, the sibling) before you report it, and report it only when you can show that reason wrong. A project rule is checked against accepted platform practice and its known exceptions before a deviation from it is reported.
 
 Severity levels are defined once, in `review-orchestrator/SKILL.md` → **Severity (canonical)**. This reviewer does not restate them: `blocker` is the four merge-blocking shapes named there and nothing else, and the `major`/`minor` boundary is the trigger-and-outcome test.
 

package/src/gdskills/bundled/skills/review/review-security-code/SKILL.md

@@ -23,7 +23,7 @@ license: "MIT"
 
 ## Purpose
 
-Finds exploitable security vulnerabilities introduced in the changed code of the current branch. Covers injection, auth/authz gaps, IDOR, secrets, insecure crypto, CSRF, path traversal, and framework-specific patterns (NestJS, React). Produces findings with explicit attack vectors and concrete fixes. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`.
+Finds exploitable security vulnerabilities introduced in the changed code of the current branch. Covers injection, auth/authz gaps, IDOR, secrets, insecure crypto, CSRF, path traversal, and framework-specific patterns (NestJS, React). Produces findings with explicit attack vectors and concrete fixes. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`, except the read-only `git log`, `git blame` and `git show` where its host gives a read-only child git (keryx shell does not: there the payload supplies the history).
 
 This skill covers **code-level security only**. It does NOT audit npm/bun dependency trees, Docker configurations, or deployment surfaces — use `security-audit` for those.
 
@@ -67,7 +67,7 @@ See shared script: `.metaproject/skills/gdskills/shared/git-merge-base.md`
 
 Run the script from that file to determine `MERGE_BASE` (`BASE_SHA`) and `SCOPE` before proceeding.
 
-**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text: a read-only child has no shell, so run no git command and never rebuild the diff. Only with none supplied, collect it:
+**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text and never rebuild the diff. A choice's history (law 4) is read with `git log`, `git blame` and `git show` only where the host gives a read-only child git; on keryx shell a read-only child has no shell and no git tool, so read the `git log -L`/`git blame` excerpts the payload supplies, or say the history was not read. Only with none supplied, collect it:
 ```bash
 git diff --name-status "${BASE_SHA}" && git diff "${BASE_SHA}" && git ls-files --others --exclude-standard
 # explicit range: <FROM_SHA>..<TO_SHA> in place of "${BASE_SHA}"
@@ -201,15 +201,10 @@ Attack vector template: _"Attacker sends `filename=../../etc/passwd`, reading ar
 
 ### Shared laws (every reviewer)
 
-1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
-   name the input, call, or condition that reaches the code, you have an
-   observation, not a finding. Report it as `info` and say what would settle it.
-2. **Never flag the theoretical.** The path you describe must exist in the code
-   under review. Do not report a safe API because it could be misused, or a
-   pattern because it is often wrong elsewhere.
-3. **One finding per class, not one per occurrence.** When the same shape appears
-   at several sites, report it once and list every site. Ten findings that are one
-   finding hide the other nine problems.
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot name the input, call, or condition that reaches the code, you have an observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code under review. Do not report a safe API because it could be misused, or a pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears at several sites, report it once and list every site. Ten findings that are one finding hide the other nine problems.
+4. **A deliberate choice is not a defect until its reason is read and shown wrong.** An explicit override, suppression or exemption, a comment or commit giving a reason, or a sibling doing the same is a decision: read its reason (the comment, `git log -L` or `git blame`, the sibling) before you report it, and report it only when you can show that reason wrong. A project rule is checked against accepted platform practice and its known exceptions before a deviation from it is reported.
 
 Severity levels are defined once, in `review-orchestrator/SKILL.md` →
 **Severity (canonical)**. This reviewer does not restate them: `blocker` is the

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

@@ -25,7 +25,7 @@ license: "MIT"
 
 Focused style reviewer. Covers naming conventions, dead code, readability, DRY violations,
 import organization, comment quality, file length, cyclomatic complexity, and console noise.
-Never touches logic correctness, architecture, security, or performance. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`.
+Never touches logic correctness, architecture, security, or performance. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`, except the read-only `git log`, `git blame` and `git show` where its host gives a read-only child git (keryx shell does not: there the payload supplies the history).
 
 ---
 
@@ -66,7 +66,7 @@ Run that script to determine `BASE_SHA` before collecting the diff.
 
 Only review code changed in scope. Do not flag style issues in lines outside the diff.
 
-**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text: a read-only child has no shell, so run no git command and never rebuild the diff. Only with none supplied, collect it:
+**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text and never rebuild the diff. A choice's history (law 4) is read with `git log`, `git blame` and `git show` only where the host gives a read-only child git; on keryx shell a read-only child has no shell and no git tool, so read the `git log -L`/`git blame` excerpts the payload supplies, or say the history was not read. Only with none supplied, collect it:
 ```bash
 git diff --name-status "${BASE_SHA}" && git diff "${BASE_SHA}" && git ls-files --others --exclude-standard
 # explicit range: <FROM_SHA>..<TO_SHA> in place of "${BASE_SHA}"
@@ -195,15 +195,10 @@ Do not flag DRY violations for code outside the diff even if legacy duplication
 
 ### Shared laws (every reviewer)
 
-1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
-   name the input, call, or condition that reaches the code, you have an
-   observation, not a finding. Report it as `info` and say what would settle it.
-2. **Never flag the theoretical.** The path you describe must exist in the code
-   under review. Do not report a safe API because it could be misused, or a
-   pattern because it is often wrong elsewhere.
-3. **One finding per class, not one per occurrence.** When the same shape appears
-   at several sites, report it once and list every site. Ten findings that are one
-   finding hide the other nine problems.
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot name the input, call, or condition that reaches the code, you have an observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code under review. Do not report a safe API because it could be misused, or a pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears at several sites, report it once and list every site. Ten findings that are one finding hide the other nine problems.
+4. **A deliberate choice is not a defect until its reason is read and shown wrong.** An explicit override, suppression or exemption, a comment or commit giving a reason, or a sibling doing the same is a decision: read its reason (the comment, `git log -L` or `git blame`, the sibling) before you report it, and report it only when you can show that reason wrong. A project rule is checked against accepted platform practice and its known exceptions before a deviation from it is reported.
 
 Severity levels are defined once, in `review-orchestrator/SKILL.md` →
 **Severity (canonical)**. This reviewer does not restate them: `blocker` is the

package/src/gdskills/bundled/skills/review/review-testing-practices/SKILL.md

@@ -28,8 +28,7 @@ license: "MIT"
 
 # Review — Testing Practices
 
-Reviewer for local testing discipline. Read project test guides first when present, then apply
-the neutral baseline below. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs the tests only when its payload's `allowed_tools` says `run-tests`, within `exec_budget_s`; otherwise it runs no command.
+Reviewer for local testing discipline. Read project test guides first when present, then apply the neutral baseline below. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs the tests only when its payload's `allowed_tools` says `run-tests`, within `exec_budget_s`; otherwise it runs no command, except the read-only `git log`, `git blame` and `git show` where its host gives a read-only child git (keryx shell does not: there the payload supplies the history).
 
 ---
 
@@ -195,6 +194,7 @@ pass, then work the checklist.
 1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot name the input, call, or condition that reaches the code, you have an observation, not a finding. Report it as `info` and say what would settle it.
 2. **Never flag the theoretical.** The path you describe must exist in the code under review. Do not report a safe API because it could be misused, or a pattern because it is often wrong elsewhere.
 3. **One finding per class, not one per occurrence.** When the same shape appears at several sites, report it once and list every site. Ten findings that are one finding hide the other nine problems.
+4. **A deliberate choice is not a defect until its reason is read and shown wrong.** An explicit override, suppression or exemption, a comment or commit giving a reason, or a sibling doing the same is a decision: read its reason (the comment, `git log -L` or `git blame`, the sibling) before you report it, and report it only when you can show that reason wrong. A project rule is checked against accepted platform practice and its known exceptions before a deviation from it is reported.
 
 Severity levels are defined once, in `review-orchestrator/SKILL.md` → **Severity (canonical)**. This reviewer does not restate them: `blocker` is the four merge-blocking shapes named there and nothing else, and the `major`/`minor` boundary is the trigger-and-outcome test.
 

package/src/gdskills/contracts/review-finding.schema.json

@@ -115,6 +115,69 @@
         "description": "Reasoning alone produces no new evidence, so it can never reach `confirmed` (AC7). It cannot reach `refuted` either, and that extension is deliberate: `refuted` is the only verdict with a destructive consequence, so granting it to the weakest method would reinstate review-strict with the sign flipped. Anything checkable is `site-check` or `execution`; `reasoning` is what is left when nothing was run."
       }
     },
+    "premise": {
+      "title": "What the premise judge found when it asked whether this finding's request is right",
+      "description": "Flow 459. Declared HERE and deliberately NOT in the bundled reviewer-finding.schema.json, on the same basis as `verification`: the reviewer that raised a finding is the one actor that may not judge its premise. The verifier asks whether the facts hold; the premise judge asks whether the request is right (an explicit override, an exemption, a sibling doing the same and accepted platform practice are all evidence that a flagged shape is a deliberate choice). `challenged` and `owner-decision` HOLD the finding: it is not an open blocker or major and is not passed to a fixer until the operator answers. The judge is delete-only: it never adds a finding, never raises a severity and never edits the finding's text; `downgraded` carries a strictly lower `severity` (`major` or `minor`: a downgrade stops at the fix-loop threshold), which is then also the finding's own. One source of truth each: the finding's own `severity` wins over a `premise.severity` that disagrees (ingest aligns them), and the operator's answer is the `premise-question` decision in the package's operator-decisions.json; `premise.operator` is only its audit trail on the record, and ingest strips it from any finding it receives. The schema states the per-verdict fields below; that a downgrade is STRICTLY lower than the original is checked in code (src/review/premise.ts). Absent means nobody judged.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["verdict", "judge"],
+      "properties": {
+        "verdict": { "type": "string", "enum": ["upheld", "downgraded", "challenged", "owner-decision"] },
+        "judge": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 },
+        "severity": { "type": "string", "enum": ["major", "minor"], "description": "`downgraded` only: the lower severity, also the finding's own. Never `info`: a downgrade stops at `minor`, the fix-loop threshold." },
+        "original_severity": { "type": "string", "enum": ["blocker", "major"], "description": "`downgraded` only: what the reviewer reported." },
+        "intent_signals": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["ref", "says"],
+            "properties": { "ref": { "type": "string", "minLength": 1 }, "says": { "type": "string", "minLength": 1 } }
+          }
+        },
+        "practice_sources": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "says"],
+            "properties": { "name": { "type": "string", "minLength": 1 }, "says": { "type": "string", "minLength": 1 } }
+          }
+        },
+        "reasoning": { "type": "string" },
+        "question": { "type": "string", "minLength": 1, "description": "`challenged` and `owner-decision`: what the operator is asked." },
+        "options": { "type": "array", "minItems": 2, "items": { "type": "string", "minLength": 1 } },
+        "operator": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["answer", "reason", "at", "actor"],
+          "description": "The operator's answer once applied to the record (`keryx review decide-premise`, the `review_decide_premise` card). An audit trail: the answer counts only from the package's operator-decisions.json, and ingest strips this field from input findings.",
+          "properties": {
+            "answer": { "type": "string", "enum": ["uphold", "dismiss"] },
+            "reason": { "type": "string", "minLength": 1 },
+            "quote": { "type": "string", "minLength": 1, "description": "The operator's own words: what they typed at the terminal, or the card text they said yes to." },
+            "at": { "type": "string", "minLength": 1 },
+            "actor": { "type": "string", "minLength": 1 },
+            "confirmedVia": { "type": "string", "enum": ["tui-card", "remote-card", "terminal"] }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "required": ["verdict"], "properties": { "verdict": { "const": "downgraded" } } },
+          "then": { "required": ["severity", "original_severity"] }
+        },
+        {
+          "if": { "required": ["verdict"], "properties": { "verdict": { "enum": ["challenged", "owner-decision"] } } },
+          "then": { "required": ["question"] }
+        },
+        {
+          "if": { "required": ["verdict"], "properties": { "verdict": { "const": "owner-decision" } } },
+          "then": { "required": ["options"] }
+        }
+      ]
+    },
     "severity": { "type": "string", "enum": ["blocker", "major", "minor", "info"] },
     "repo": {
       "type": ["string", "null"],
@@ -129,7 +192,7 @@
     },
     "quote": {
       "title": "The code this finding is about, copied verbatim out of `file`",
-      "description": "What replaces asking the model for a line number: a model is poor at counting lines and good at repeating text it has just read. The quote is matched against `file` at the round's head — exactly first, then with whitespace collapsed, then not at all. A quote that matches in more than one place is `unlocatable` rather than anchored to the first hit, because choosing among them would be a guess wearing a line number. Absent for a finding that is about the round rather than a site.",
+      "description": "What replaces asking the model for a line number: a model is poor at counting lines and good at repeating text it has just read. The quote is matched against `file` at the round's head — exactly first, then with whitespace collapsed, then (a one-line quote of at least 12 characters, MIN_SUBSTRING_QUOTE_CHARS) as an exact substring of exactly one line, then not at all; a shorter fragment must be a whole line. A quote that matches in more than one place is `unlocatable` rather than anchored to the first hit, because choosing among them would be a guess wearing a line number. Absent for a finding that is about the round rather than a site.",
       "type": ["string", "null"]
     },
     "locator": {
@@ -140,7 +203,7 @@
       "required": ["state"],
       "properties": {
         "state": { "type": "string", "enum": ["derived", "unlocatable"] },
-        "method": { "type": "string", "enum": ["exact", "whitespace-normalised"] },
+        "method": { "type": "string", "enum": ["exact", "whitespace-normalised", "substring"] },
         "reason": { "type": ["string", "null"] },
         "reported_line": { "type": ["integer", "null"], "minimum": 1 }
       },
@@ -159,6 +222,18 @@
       "type": "boolean",
       "description": "Written, as true, only by `review ingest` when `file` does not exist at the round's reviewed head (a cat-file existence check of `<head>:<file>`). The finding is kept, never dropped, and is listed in scope.md: a finding that cites a path nobody can open is the reviewer's claim, not a located site."
     },
+    "quote_unlocated": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reason"],
+      "description": "Written only by `review ingest` when `quote` was checked against `file` at the round's reviewed head and is absent from it (`absent`) or matches more than one place (`ambiguous`, with the matched lines in `candidate_lines`, bounded by the scan). The finding is kept with `line` null, never relocated by similarity or proximity, listed in scope.md and by readiness item `quotes-located`; the round is recorded rather than refused. It is the machine-readable outcome of the same check that writes `locator` (`state: unlocatable`, its `reason` the prose of it): ingest writes both from one result and recomputes both on every ingest, so they never disagree. Gates and readers branch on this flag; `locator` is the record of how the line was or was not derived.",
+      "properties": {
+        "reason": { "type": "string", "enum": ["absent", "ambiguous"] },
+        "candidate_lines": { "type": "array", "maxItems": 50000, "items": { "type": "integer", "minimum": 1 } }
+      },
+      "if": { "properties": { "reason": { "const": "absent" } }, "required": ["reason"] },
+      "then": { "not": { "required": ["candidate_lines"] } }
+    },
     "symbol": { "type": ["string", "null"] },
     "problem": { "type": "string" },
     "impact": { "type": "string" },