@mrciphersmith/keryx 0.3.83 → 0.3.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.83",
+  "version": "0.3.85",
   "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/rules/core/model-selection.mdc

@@ -326,6 +326,12 @@ recording them is one copy rather than four decisions.
   remove.
 - **Do not ask the operator which model to use per dispatch.** Asking every time
   is what made adaptive selection impossible.
+- **An interactive review round shows the computed plan once.** It is the third
+  start question of `review-orchestrator` (`model_strategy: ask`, the
+  interactive default): the complexity the round's signals give, each role's tier
+  and the model it resolves to here. The operator accepts it, takes every role to
+  `deep`, or sets it — for that round. An unattended round dispatches the
+  computed plan without asking (`adaptive`).
 - Never write a concrete model name into a skill, a rule, a dispatch template, or
   the resolution code.
 - Take the candidate set from runtime detection. Never from a literal list of

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

@@ -433,14 +433,14 @@ Before accepting implementation:
 1. Run focused tests for touched scope.
 2. Run `code-verifier`.
 3. Run `keryx health run` when Code Health is enabled.
-4. Check the bounds, then run `review-orchestrator` with relevant domains.
-
+4. Check the bounds, then run `review-orchestrator` with relevant domains — in this session,
+   never handed whole to one subagent: one without a dispatch tool returns `STATUS: BLOCKED`.
    ```bash
    keryx review budget --spent <usd-so-far> --outstanding <subagents you already have in flight>
    ```
-
    A non-zero exit means the spend ceiling (3 USD by default) has been reached:
-   **stop and ask the user** rather than dispatching another fan-out.
+   **stop and ask the user** rather than dispatching another fan-out — never shrink the fan-out to fit.
+   Dispatch prompts point at sources (files, SHAs, the PR) and never paraphrase a contract.
 
    `--outstanding` is the part that matters here. `review-orchestrator`
    dispatches reviewers in parallel and runs *nested* under this skill, and

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

@@ -368,3 +368,138 @@ inside) the findings they annotate — same separation the finding schema
 itself draws between a reviewer's claim (`severity`, `problem`, …) and what
 became of it (`disposition`), which a reviewer never states and this pass
 does not either.
+
+## Start questions (Step 5) — once per round, after the context pack
+
+The round asks its operator three questions, once, in one interaction, after
+Step 1 (context pack) and Step 3 (scope) — never before them: the counterpart
+question cannot be answered well until the context pack has looked for the
+other side. On Claude Code that is one `AskUserQuestion` call carrying the
+three questions; on any other host, the lettered prompt below. An unattended
+round (job pipeline, trigger, schedule) asks nothing, applies the defaults and
+records them under `### How this review was run`.
+
+1. **Reviewers** — default `--all`: every reviewer the engine detects plus every
+   project and convention reviewer its gates admit. Narrowing is an explicit
+   choice (tests only, one domain, a custom list). Flags the caller passed
+   answer this question and skip it. Convention reviewers are part of this
+   question; the job setting `convention_reviewers` still answers it in a
+   `job-orchestrator` pipeline.
+2. **Counterpart** — the other side of every contract the diff consumes or
+   mirrors: the backend for a frontend change, the frontend and other consumers
+   for a backend change. Before asking, the context pack looks for it:
+   endpoints, DTOs and rules the diff calls or mirrors, a paired PR
+   (`gh pr list --repo <counterpart> --search <branch-or-feature>`), the
+   producer at a freshly fetched SHA. The question shows what was found —
+   "no link found" included — and one checkbox, **verify the counterpart**, ON
+   by default even when nothing was found. Verification is not limited to a
+   paired PR: the other side's contracts and logic are re-read at a pinned SHA
+   every round. When the round cannot locate that code itself (repository,
+   handler, validator), it asks the operator where it is; it never records
+   `state: unavailable` on its own. Skipping verification takes a reason, and
+   the reason goes in the report.
+3. **Models** — the complexity the round already holds signals for (changed
+   files and lines, the risk class from Depth floor below, domains, scope B),
+   the per-role tier `keryx review tier` prints for each planned dispatch, and
+   the model each tier resolves to on this host. Choices: accept the plan (the
+   default), all `deep`, or custom. The plan is shown once per round, never per
+   dispatch (`rules/core/model-selection.mdc`). Skills, rules and this file name
+   tiers only; model ids appear in the rendered question and the report.
+
+```text
+Context: <PR or branch>, <N> files / <N> lines, <domains>; risk: <class>
+
+1) Reviewers     A) --all (default)  B) tests only  C) <domain> only  D) choose
+2) Counterpart   found: <endpoints, rules, paired PR — or "no link found">
+                 A) verify <backend|frontend> (default)  B) skip — give a reason
+3) Models        complexity: <low|medium|high>; <role>: <tier> → <model>, …
+                 A) accept (default)  B) all deep  C) custom
+
+> answers (default: 1A 2A 3A)
+```
+
+## Depth floor — a gating round does not degrade
+
+A round is **gating** when its verdict lets a change move: the review step of a
+flow (`flow-orchestrator` Phase 3), a pre-merge or pre-ship review, a
+re-request after fixes. A gating round runs the composition the start questions
+selected.
+
+- **No dispatch tool, no review.** A host that cannot dispatch subagents — this
+  engine running inside a subagent is the usual case — returns
+  `STATUS: BLOCKED` with reason `nested_dispatch_unavailable` and no verdict.
+  It does not review the diff alone and call that a round. Measured (flow 405):
+  a single-agent round on a 150-line frontend PR wrote "did not dispatch any
+  sub-reviewers", approved it with two cosmetic minors, and the next human round
+  filed six real findings, every one reachable from the diff and the backend at
+  a pinned SHA.
+- **Size never lowers depth below the risk class.** The budget table sizes the
+  context, not the depth.
+- **High-risk includes a client-side mirror of a server rule** — validation,
+  limits, permissions, uniqueness, reserved names — beside the triggers the main
+  file lists.
+
+## Counterpart verification — the contract is enumerated, not summarised
+
+For an **input rule** the diff mirrors or depends on (what the server accepts
+for a name, a value, a role), the `cross_repo` entry records the producer's
+complete check set in `checks` and how that set was found in
+`enumeration_method` (`review-context.schema.json`):
+
+- every check the producer runs on that input: validators, restriction
+  utilities, uniqueness queries, reserved-name registries, and the storage bound
+  (column width, index, a downstream identifier);
+- for each check: its `source` (`file:line` at the pinned SHA), whether it is
+  case-sensitive, and the `paths` it runs on (create, update, rename, copy,
+  import, move, …).
+
+Put these rules in every reviewer dispatch:
+
+- **The facts are a starting point, not a boundary.** A reviewer may read the
+  producer itself and file what the entry missed.
+- **"The producer has no limit" is a question, not a fact.** Find what bounds
+  the value — that is where an over-long or unexpected value fails, usually as a
+  server error.
+- **Build the surfaces × checks matrix**: every surface that sends the input
+  against every check, each cell `same`, `missing`, `stricter` or `looser`.
+  `missing` is a refusal the user meets late; `stricter` blocks legal input; a
+  check the producer lacks but storage enforces is a producer defect — filed as
+  pre-existing, or fixed by a paired change.
+- **Every refusal the producer can return is shown where the user can act on
+  it** — next to the field, not as a generic toast.
+
+## Round obligations — always on, never asked
+
+These apply to every round without a question:
+
+1. **Enumerate before concluding.** Every caller and surface of a changed value
+   is found with `keryx ctx rg` or gdgraph, and the query is recorded — never
+   taken from the diff's own list.
+2. **Quantified claims are checked.** "Every", "all", "only" and "never" in the
+   PR body or the commits are compared with that enumeration; an over-claim is a
+   `minor` finding, the same class as the description-versus-diff rule.
+3. **A verified-clean line names its sites.** Each line of the `Verified clean`
+   lane names the files, sites or commands it rests on; "the frontend does the
+   same" without them is not verified.
+4. **A pre-existing defect gets a disposition.** Every pre-existing defect the
+   round finds in the contract the change touches is recorded with one: fixed in
+   the change (small, same contract), named out of scope in the PR body, or a
+   recommended issue. Found and dropped is the failure this rule exists for.
+5. **Red on the parent, per test.** Every added test fails with the parent
+   commit's production files restored; the run is the evidence.
+6. **A threaded value is pinned per site.** A parameter, key or prop passed at
+   several render sites is asserted at each site, or centralised so there is
+   one.
+7. **One rule, one implementation.** The same check implemented twice is a
+   finding, even while both copies agree.
+8. **"Do not re-raise" needs a record.** A dispatch may exclude an item only by
+   citing the PR comment, issue or decision that settled it — never a whole
+   surface ("X has no test; covered elsewhere").
+
+### Runtime research-completion ledger
+
+New managed packages carry `research.json`, initially pending. Before closing a round, enumerate unresolved observations from raw reviewers and the changed-file/consumer census, assign stable obligation IDs, and investigate them. Run the probe or inspect the relevant source and assertions: merely proposing a check does not resolve it. An unexecuted probe is not a verified claim.
+
+Supply the ledger using `keryx review ingest --research <ledger.json>` alongside the report and findings. Format: `version: 1`, `scopeReviewed: true`, `rawReconciled: true`, `obligations: [...]`. Each obligation requires `id`, `source`, `question`, `status`, `evidence`, `reason`. Status `finding` additionally requires `finding` pointing to exactly one canonical finding ID or global ID. Other terminal statuses are `refuted` and `out-of-scope`, both requiring evidence and reason. Preserve distinct scenarios when deduplicating. Assert census/reconciliation flags only after performing those checks; an empty obligations array is valid only if the actual census found no open observations.
+
+Open, deferred and unverifiable obligations block completion. If context, runtime or budget prevents resolution, retain the obligation and report incomplete; do not relabel it refuted or out-of-scope. Completion and the flow gate re-read the ledger even when the manifest says closed. Legacy packages without this artifact remain compatible, not proven complete. This gate validates the declared ledger, not the truth or exhaustiveness of its census; independent source/raw audits remain necessary.

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

@@ -18,15 +18,11 @@ metadata:
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
-
 # Review Orchestrator
-
 Entry point for the entire review domain. This skill is a thin router: it detects scope,
 dispatches specialized reviewers in parallel, then consolidates their findings into one
 unified report sorted by severity. It does not perform any review logic itself.
-
 ---
-
 ## Workflow
 
 ```
@@ -38,7 +34,7 @@ Review Orchestrator Progress:
 - [ ] Step 3: Build the bounded scope with `keryx review scope` — never by hand
 - [ ] Step 3b: On a deep round, compute scope B with `keryx review blast-radius` — never by browsing — and KEEP the `--json` file; `review ingest --blast-radius <file>` is refused without it
 - [ ] Step 4: Parse flags / auto-detect domain from scope
-- [ ] Step 5: Ask user to confirm optional convention reviewers (legacy/profile reviewers are flag-only, never prompted)
+- [ ] Step 5: Start questions, once, after Steps 1 and 3 — reviewers (default `--all`), counterpart verification (default on), model plan; unattended takes the defaults (SKILL.detail.md § "Start questions"; legacy/profile reviewers stay flag-only)
 - [ ] Step 5c: When `review.jev.select` is on, run `keryx review jev-select` over the finalized candidate set and drop its `skip` decisions from Wave A/B — see "Reviewer selection with Jev"
 - [ ] Step 6: Plan sub-agent dispatch and token budgets, and compute each dispatch's model with `keryx review tier` — never by hand
 - [ ] Step 7: Stage 1 gate - spec compliance check (if issue/task provided)
@@ -144,7 +140,7 @@ which of its inputs were recovered and which were never written down.
 | `context_doc` | string | no | Path to job context document (e.g., `.metaproject/jobs/<job>/ai/context.md`). |
 | `context_mode` | string | no | `none`, `light`, or `full`. Default: `light` for PR review, `none` for small path reviews. `full` may call `context-collector` before dispatch. |
 | `token_budget` | object | no | Optional budget controls: `{total, per_reviewer, diff_max_chars, file_max_chars}`. |
-| `model_strategy` | string | no | `ask` or `adaptive`. Default: `adaptive`; the model per dispatch is computed by `keryx review tier`, never chosen by hand (see Step 6). |
+| `model_strategy` | string | no | `ask` or `adaptive`. Default: `ask` in an interactive round (shown once as Start question 3), `adaptive` unattended; the model per dispatch is computed by `keryx review tier`, never chosen by hand (see Step 6). |
 | `managed_review` | object | no | Optional managed review mode: `{mode, target, target_ref, flow_id, reviewers}` where mode is `lightweight`, `attach-review`, `review-flow`, or `ingest`. |
 | `verification_mode` | string | no | `off`, `annotate`, or `filter`. Default `annotate` — verdicts are recorded and nothing is removed. See Wave C. |
 | `pr_comments` | object | no | `{enabled, max_replies_total, max_sentences_per_reply}`. Defaults: enabled when a PR exists, `30`, `2`. Collect every round, reply once at the end. See External PR comments. |
@@ -522,9 +518,9 @@ The rule that follows for reviewers, and that belongs in the dispatch prompt:
 > producer disproves, and a defect missed because the producer's actual default was
 > assumed rather than read.
 
-If the other repository is not available to you, record it as
-`state: unavailable` in `cross_repo` and leave the dependent findings at `info`.
-An unavailable producer is a result. Assuming one is not.
+If you cannot locate the producer, ask the operator where it is (Start question 2); record `state: unavailable` only when it cannot be read, and leave the dependent findings at `info`.
+An unavailable producer is a result. Assuming one is not. An input rule records the producer's full check set and is verified every round,
+paired PR or not — SKILL.detail.md § "Counterpart verification".
 
 A finding whose evidence lives in the producer sets `repo` on the finding itself.
 `file` and `line` alone name a path in the repository under review, so without
@@ -600,8 +596,8 @@ Context modes:
 - `full`: for large/high-risk PRs or user request. Invoke `context-collector` first, then pass the resulting context path and summary to reviewers.
 
 High-risk triggers for `full` recommendation:
-- Auth, permissions, API contracts, migrations, shared core, state management, graph/flow, security, performance-critical paths.
-- More than 20 changed source files or more than 2,000 changed lines.
+- Auth, permissions, API contracts, a client-side mirror of a server rule (validation, limit, permission, uniqueness, reserved names), migrations, shared core, state management, graph/flow, security, performance-critical paths.
+- More than 20 changed source files or more than 2,000 changed lines. Size never lowers depth below the risk class (SKILL.detail.md § "Depth floor").
 - Missing or ambiguous linked requirements.
 
 If `full` context would be useful but was not explicitly requested, ask once:
@@ -655,8 +651,8 @@ whether it is computed:
 
 | `model_strategy` | Behavior |
 |---|---|
-| `ask` | Present the `keryx review tier` model plan once before dispatch. |
-| `adaptive` (default) | Dispatch on the computed model directly; record the chosen model per reviewer in the final report metadata. |
+| `ask` (default, interactive) | Present the `keryx review tier` model plan once before dispatch — Start question 3; the operator may accept it, take all `deep`, or set it. |
+| `adaptive` (default, unattended) | Dispatch on the computed model directly; record the chosen model per reviewer in the final report metadata. |
 
 Rules:
 - Never write a model id into a dispatch by hand — paste the `model` block `keryx review tier` printed.
@@ -1052,30 +1048,30 @@ what to do with it: `SKILL.detail.md` beside this file, section "Project-local
 reviewers". A description saying another entry point dispatches it is its
 author's routing note, not a restriction.
 
-### Convention Reviewer Confirmation
+### Start questions (Step 5)
 
-When convention reviewers are auto-detected and the user did not explicitly pass
-`--project-conventions`, `--frontend-conventions`, `--testing-practices`, `--core-boundaries`,
-`--flow-graph`, or `--all`, ask before dispatch:
+Ask once, after the context pack (Step 1) and the scope (Step 3), in one interaction — one
+`AskUserQuestion` call on Claude Code, the lettered prompt in SKILL.detail.md elsewhere:
 
-```text
-I found local convention reviewers that match this review scope:
+1. **Reviewers** — default `--all`; detected convention reviewers are included. Narrowing
+   (tests only, one domain, custom) is the operator's explicit choice. Passed flags answer it.
+   Legacy/profile reviewers stay flag-only and are never prompted.
+2. **Counterpart** — show what the context pack found for the other side of the contract
+   (endpoints, mirrored rules, a paired PR, or "no link found") and a checkbox to verify it,
+   ON by default even with no link. If the round cannot locate that code, it asks where it is.
+   Verification is not limited to a paired PR: contracts and logic are re-read every round.
+3. **Models** — complexity, the per-role tier from `keryx review tier`, the model each tier
+   resolves to on this host; accept (default), all `deep`, or custom. Once per round.
 
-  A) Include all detected convention reviewers (recommended)
-  B) Choose individually
-  C) Skip convention reviewers for this run
+Unattended rounds ask nothing: `--all`, counterpart verified, computed models — recorded in
+`### How this review was run`. In a `job-orchestrator` pipeline the job setting
+`convention_reviewers` still answers question 1 (unresolved: include all detected reviewers
+and record that choice in the review scope).
 
-Detected:
-  - review-frontend-conventions: <why detected, or omit if not detected>
-  - review-testing-practices: <why detected, or omit if not detected>
-  - review-core-boundaries: <why detected, or omit if not detected>
-  - review-flow-graph: <why detected, or omit if not detected>
-```
-
-If the user chooses B, list only detected reviewers and ask for names to include/exclude.
-If the user does not answer and the review is part of an automated `job-orchestrator` pipeline,
-use the job setting `convention_reviewers` (default: `"ask"`; if still unresolved, include all
-detected reviewers and record that choice in the review scope).
+A gating round runs what these answers selected; a host that cannot dispatch subagents
+returns `STATUS: BLOCKED` (`nested_dispatch_unavailable`) instead of reviewing alone. Every
+round also carries the always-on obligations — SKILL.detail.md § "Depth floor",
+§ "Counterpart verification", § "Round obligations".
 
 ### Reviewer selection with Jev (`jev-select`) — advisory, before dispatch (Step 5c)
 
@@ -1185,7 +1181,11 @@ whoever reads the merge commit a year later reads the body. When `review.jev.con
 
 ## Dispatching Reviewers
 
-Dispatch selected reviewers in parallel when independent. Use waves when token budget is tight or when one reviewer needs another result:
+**Dispatch integrity is a completion prerequisite.** Use one distinct execution per selected reviewer role; do not combine multiple roles in one child or count sections of one response as independent runs. When budgets are tight, use sequential waves, not role batching. Resolve every project-rule anchor before dispatch; missing rules require context recovery or a blocked result, never silently skipped checks. A read-only pass cannot discharge executable obligations: dispatch a capable execution pass and retain its evidence. Partial scope and NEEDS_CONTEXT remain incomplete until rerun over the outstanding scope.
+
+New managed packages declare `reviewerDispatch: "research.json"`. Alongside the research ledger, provide `dispatch: { version: 1, selected: [...], unresolvedRules: [], runs: [...] }`. Preserve the actual computed reviewer inventory. Each run has `reviewer`, unique `executionId`, `status: "complete"`, `scopeComplete: true`, `rawEvidence`, nonempty `ruleEvidence`, and boolean `executionRequired`. Required execution needs nonempty `executionEvidence` (command/output references); a source-only scope requires `executionReason`. Do not fabricate IDs or mark truncated responses complete. Runtime validates these declarations at closure and the flow gate, not their truth: independently audit evidence and inventory before freezing. Legacy artifact absence is compatibility, not proof of a correct launch. Research closure is mandatory: see [Runtime research-completion ledger](SKILL.detail.md#runtime-research-completion-ledger).
+
+Dispatch selected reviewers in parallel when independent — this engine dispatches them itself; a host without a dispatch tool returns `STATUS: BLOCKED` (`nested_dispatch_unavailable`) and never reviews alone. Use waves when token budget is tight or when one reviewer needs another result:
 
 1. Wave A - core correctness/risk reviewers: logic, architecture, security/highload when selected.
 2. Wave B - domain reviewers: frontend/backend/testing/convention reviewers filtered to relevant files. `review-jev-rules` (flow 330), `review-jev-risk`/`review-jev-scenarios` (flow 332), `review-jev-docs`/`review-jev-comments` (flow 333), `review-jev-contract` (flow 335) also run here, CLI-engine not sub-agent, `"engine": "jev"` in `keryx review reviewers --json`, gated on their own opt-in and a resolvable Jev/OpenRouter credential — measured verdicts per reviewer (keep off by default, experimental, etc.) in `SKILL.detail.md` § "CLI-engine reviewers".

package/src/gdskills/bundled/skills/review/review-orchestrator/review-context.schema.json

@@ -205,6 +205,51 @@
               "null"
             ],
             "description": "The last round the producer was re-read. An entry with `state: open` that was pinned in round 1 and never revalidated is stale by round 3: a parallel pull request is precisely the thing that moves between rounds."
+          },
+          "checks": {
+            "type": "array",
+            "minItems": 1,
+            "description": "For an input rule the diff mirrors or depends on (what the producer accepts for a name, a value, a role): the producer's COMPLETE check set, not a summary of it. Flow 405: a dispatch that carried only the producer's regex let two rounds approve a change that missed a case-sensitive prefix check, a case-sensitive uniqueness check and a column-width bound. The set is a starting point for reviewers, never a boundary.",
+            "items": {
+              "type": "object",
+              "required": [
+                "check",
+                "source",
+                "paths"
+              ],
+              "properties": {
+                "check": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "What the producer refuses, in one line — including a storage bound such as a column width."
+                },
+                "source": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "`file:line` at the pinned ref."
+                },
+                "case_sensitive": {
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "paths": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "The producer paths this check runs on — create, update, rename, copy, import, move, …"
+                }
+              },
+              "additionalProperties": true
+            }
+          },
+          "enumeration_method": {
+            "type": "string",
+            "minLength": 1,
+            "description": "How `checks` was found to be complete — the producer entry points read and the searches run. Required whenever `checks` is present."
           }
         },
         "allOf": [
@@ -241,6 +286,18 @@
                 "pr"
               ]
             }
+          },
+          {
+            "if": {
+              "required": [
+                "checks"
+              ]
+            },
+            "then": {
+              "required": [
+                "enumeration_method"
+              ]
+            }
           }
         ],
         "additionalProperties": true

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

@@ -160,7 +160,7 @@ a tool, skill or model is unavailable; use `none` only when the run proves none.
 - **Subagents:** <dispatched subagents, their reviewer roles and actual models; or none when confirmed, otherwise not recorded>.
 - **Fallback:** <reviewer> via `general-purpose` because <native agent type unavailable | no bundled agent>. Or `none`.
 - **Not run:** <reviewer> — <short reason>. Or `none`.
-- **Selection:** <auto-detected scope | explicit flags | optional groups the user picked>
+- **Selection:** <explicit flags | start questions: reviewers <`--all` | narrowed to …>, counterpart <verified at <sha> | skipped: reason>, models <accepted | all deep | custom> | defaults (unattended)>
 - **Verification:** <mode>. Confirmed N, refuted N, unverifiable N, unverified N. Removed N (always 0 outside `filter`).
 - **Stage counts:** pre-filter dropped <files>/<blocks>/<lines> (or `not recorded`). Retained N.
 - **Context:** <job/context path, or none>