@mrciphersmith/keryx 0.3.119 → 0.3.121

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.119",
+  "version": "0.3.121",
   "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/install-manifest.json

@@ -455,7 +455,7 @@
     },
     "review-core-skills": {
       "kind": "skill",
-      "description": "Generic (non-stack-specific) review skills: orchestrator, logic, architecture, security, performance, clean-code, highload, regression, core-boundaries, flow-graph, layout, style, testing-practices, verifier, pr-feedback, and the legacy AI/learned/style review profiles.",
+      "description": "Generic (non-stack-specific) review skills: orchestrator, logic, architecture, security, performance, clean-code, highload, regression, core-boundaries, flow-graph, layout, style, testing-practices, verifier, premise, pr-feedback, and the legacy AI/learned/style review profiles.",
       "paths": [
         "src/gdskills/bundled/skills/review/review-orchestrator/**",
         "src/gdskills/bundled/skills/review/review-logic/**",
@@ -472,6 +472,7 @@
         "src/gdskills/bundled/skills/review/review-style/**",
         "src/gdskills/bundled/skills/review/review-testing-practices/**",
         "src/gdskills/bundled/skills/review/review-verifier/**",
+        "src/gdskills/bundled/skills/review/review-premise/**",
         "src/gdskills/bundled/skills/review/review-pr-feedback/**",
         "src/gdskills/bundled/skills/review/code-ai-review/**",
         "src/gdskills/bundled/skills/review/code-learned-review/**",

package/src/gdskills/bundled/rules/core/session-plan-bridge.mdc

@@ -36,7 +36,7 @@ in progress, so it never makes the agent continue on its own, which is what make
 |---|---|---|
 | `job-orchestrator` | the step ids `keryx job status <name> --json` reports — `analyze`, `context`, `prepare`, `tests-creator`, `implement`, `sanity-check`, `verify`, `review`, `security`, `fix`, `verify-post-fix`, `perf-check`, `report`, `pr`, `deploy` | `keryx job status <name>` (read it, never retype it) |
 | `flow-orchestrator` | the Flow's task ids `T1..Tn` | `keryx flow status <id>` / the Flow's `tasks.md` |
-| `review-orchestrator` | `step-0` … `step-14`, from its own numbered checklist | its Workflow section |
+| `review-orchestrator` | `step-0` … `step-14` and `step-10b`, from its own numbered checklist | its Workflow section |
 
 An id that exists only in the session plan is drift by construction: the operator
 cannot reconcile it with the CLI, and a resumed run cannot match it. If a

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.md

@@ -39,7 +39,7 @@ End-to-end feature development workflow from idea to merge-ready PR.
 
 ### Phase 1: REQUIREMENTS + SPEC
 
-1. Parse input (description or GitHub issue via `gh issue view`)
+1. Parse input (description or GitHub issue via `gh issue view`). An issue filed from a review finding, or an external review comment, is a premise to check: dispatch `review-premise` on it first, shaped and recorded as `flow-orchestrator` Phase 1 says ("A flow sourced from a finding": no `decide-premise`; claims in `<flow-dir>/premise/<n>.json` if a flow exists; with none, its claims object goes into the Implementation Spec under **Premise**), and on `challenged` or `owner-decision` ask the operator its question with its options and journal their answer before writing the spec
 2. Clarify ambiguities — ask the user up to 3 questions max
 3. Produce the **Implementation Spec** (per `implementation-doc-mandate.mdc`):
    - **What**: feature description in 2-3 sentences
@@ -48,8 +48,8 @@ End-to-end feature development workflow from idea to merge-ready PR.
    - **Acceptance criteria**: testable bullet points
    - **Approach**: which files will change, key design decisions
    - **Test strategy**: framework, which scenarios will be covered
-4. **Save spec** to `.feature-spec.md` in project root (add to .gitignore if not already)
-5. **Get user confirmation before proceeding**
+   - **Premise** (only for an input sourced from a finding, with no flow): the review-premise claims object and the operator's answer, in their words
+4. **Save spec** to `.feature-spec.md` in project root (add to .gitignore if not already), then **get user confirmation before proceeding**
 
 ### Phase 2: DESIGN
 
@@ -113,7 +113,7 @@ Input:  codebase_path=<project_root>, scope=changed, base_branch=<base>
    - `git diff main...HEAD` — review the full diff
    - Check for: TODOs left behind, console.logs, hardcoded values
    - Verify all acceptance criteria from Phase 1 spec
-3. Fix any findings (max 2 review-fix cycles)
+3. Fix any findings (max 2 review-fix cycles), never one `review-premise` holds: a held finding is neither fixable nor clean and blocks the cycle until answered; ask the operator about it as `review-orchestrator` "Wave D" says, and only an upheld one is fixed, carrying `premise_verdict` and `premise_answer` as task-implementer's `FIX_CONTEXT` defines them (unattended: stop and report the held list). Each next round is `keryx review start` or `keryx review plan` on the new head: the round comes from `round.json`; no own range, no whole-branch re-review (the `git diff main...HEAD` above is round 1 only).
 4. Re-run `code-verifier` after any fixes
 
 ### Phase 8: DELIVER + CHANGE REPORT

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

@@ -77,11 +77,12 @@ flowchart TD
   C --> D["flow-init context enrichment"]
   D --> E["freeze AC + start flow"]
   E --> F["dispatch tests-creator / task-implementer"]
-  F --> G["code-verifier + review-orchestrator"]
+  F --> FG{"first green: ask operator - open PR or harden first"}
+  FG --> G["code-verifier + review-orchestrator"]
   G --> H{"All tasks, checks, review OK?"}
   H -- "no" --> F
   H -- "yes" --> I{"Ask user how to finish"}
-  I -- "create PR" --> J["create PR and run review/fix loop"]
+  I -- "create PR" --> J["create PR; each round = review start on the new head (delta)"]
   J --> K{"review clean, PR mergeable?"}
   K -- "no, attempts < 5" --> J
   K -- "no, attempts = 5 or repetition detected" --> R["enrich context and change fix strategy"]
@@ -177,9 +178,7 @@ Record attempts as they happen, not only on resume:
 keryx flow task attempt <id> <Tn> --outcome started|failed|blocked [--detail "<what happened>"]
 ```
 
-`attempts.count` is append-only and lives in `flow.json`. A counter that lives
-only in the orchestrator's context resets to zero exactly when the loop bound
-matters most, which makes it not a counter.
+`attempts.count` is append-only and lives in `flow.json`. A counter that lives only in the orchestrator's context resets to zero exactly when the loop bound matters most, which makes it not a counter.
 
 ### 0.1 Route
 
@@ -244,39 +243,29 @@ Write or update:
 - `tasks.md` - task definitions grouped by context, test, implement, review, docs;
 - `acceptance-criteria.md` - verifiable `ACn` criteria, each ending in one marker: [verify: exec `<command>`] or [verify: invariant `<command>`] (a backticked command), [verify: judged] (a human checks: live run, operator decision, text quality), or [verify: none — <reason>]. If a kind is unclear, ask the operator ONE question listing the criteria with proposed kinds, before `flow freeze`. Behaviour with an external dependency or a failure path gets its own failure-scenario criterion with an observable result (saved, error visible, retry creates no duplicate); a check claimed to catch a regression carries `· sensitive: revert|mutation|failure-scenario` and the confirm note carries `evidence: <ref>` (revert/mutation run or failure-scenario reference).
 
+### UI or state scope: a state × event matrix in plan.md
+
+When the scope touches UI, a store, or other code that holds state across events, `plan.md` carries a state × event matrix before `flow freeze`. Rows are the states the surface can be in (for example loading, loaded, empty, missing, first-load failed, refresh failed); columns are the events that reach it (for example the user switches selection, unmount, workspace or context change, retry). Each cell is one line: what the user sees and which state survives, citing the project's styling/UX rules where they decide it. Every non-trivial cell gets an `ACn` row, or one AC per group of cells with the same result; a cell that is genuinely "no change" needs none. List only the states and events the change reaches:
+
+| state \ event | user switches selection | unmount | retry |
+|---|---|---|---|
+| loading | drop the stale response; loading shows for the new one | no state write after unmount | — |
+| refresh failed | keep loaded data; the error does not follow to the new selection | — | re-fetch; error stays inline until success |
+
+It does not apply when the scope holds no UI or state (CLI output, pure functions, docs, build config): write `State × event matrix: not applicable — <why>` in `plan.md`. The matrix is what workers and fix rounds check behavior against; a choice no cell decides is a `behavior_changes` entry for the operator (Phase 2).
+
 ### A verification step in the plan is a task, not a sentence
 
-Every check the plan says must happen before the work is accepted - run the
-thing end to end, confirm two components agree, exercise the path no test
-covers - is added with `keryx flow task add` and closed with
-`keryx flow task done`. Prose in `plan.md` blocks nothing, and an
-orchestrator that wrote the step is the same one deciding whether to run it.
-
-The failure this prevents is specific and has happened: a plan listed
-"confirm both components agree on the same input" as step 5, the
-implementation shipped without it, and review found that the two did not
-agree at all - the change could not work in production. The check had been
-identified correctly and then skipped, because nothing made skipping it
-visible.
-
-Tasks are the mechanism for this. `keryx flow complete` runs a `tasks` gate
-over them, so an unrun verification step keeps the flow open instead of being
-quietly dropped.
-
-Know the gate's exact scope, because for years this file claimed a gate that
-did not exist and 24 completed flows shipped with an open task:
-
-- the gate is **opt-in per flow package**, keyed on `gates.tasks` in
-  `flow.json`, which `keryx flow init` writes for every flow it creates. A
-  package created before the gate landed does not carry the flag, and for it
-  the gate reports `skipped` and blocks nothing;
-- a task fails the gate when its status is not `done`; when its disposition is
-  `failed`; when its disposition is `blocked` (terminal, but the work did not
-  happen — and the harness emits this disposition on its own for a run that
-  ended blocked); when its disposition is `skipped` with no recorded reason; or
-  when its disposition is a value this build does not recognise. An
-  unrecognised disposition FAILS rather than falling through: a gate whose
-  default for the unknown case is "pass" is not a gate;
+Every check the plan says must happen before the work is accepted - run the thing end to end, confirm two components agree, exercise the path no test covers - is added with `keryx flow task add` and closed with `keryx flow task done`. Prose in `plan.md` blocks nothing, and an orchestrator that wrote the step is the same one deciding whether to run it.
+
+The failure this prevents is specific and has happened: a plan listed "confirm both components agree on the same input" as step 5, the implementation shipped without it, and review found that the two did not agree at all - the change could not work in production. The check had been identified correctly and then skipped, because nothing made skipping it visible.
+
+Tasks are the mechanism for this. `keryx flow complete` runs a `tasks` gate over them, so an unrun verification step keeps the flow open instead of being quietly dropped.
+
+Know the gate's exact scope, because for years this file claimed a gate that did not exist and 24 completed flows shipped with an open task:
+
+- the gate is **opt-in per flow package**, keyed on `gates.tasks` in `flow.json`, which `keryx flow init` writes for every flow it creates. A package created before the gate landed does not carry the flag, and for it the gate reports `skipped` and blocks nothing;
+- a task fails the gate when its status is not `done`; when its disposition is `failed`; when its disposition is `blocked` (terminal, but the work did not happen — and the harness emits this disposition on its own for a run that ended blocked); when its disposition is `skipped` with no recorded reason; or when its disposition is a value this build does not recognise. An unrecognised disposition FAILS rather than falling through: a gate whose default for the unknown case is "pass" is not a gate;
 - to close a task as deliberately not needed, record why:
 
   ```bash
@@ -285,6 +274,8 @@ did not exist and 24 completed flows shipped with an open task:
 
 Read the `tasks` line in the `flow complete` output. If it says `skipped`, the gate did not run and the task list is yours to verify by hand.
 
+**A flow sourced from a finding: check its premise before freeze.** A follow-up issue filed from a review, or an external review comment, is a premise to check, not a settled requirement. Before `flow freeze`, dispatch `review-premise` with `source: follow-up-issue` or `external-comment` and the finding shaped as its Input Contract `source` row says (the issue number or the comment's `C-NNN` as `id`, its URL as `url`). Skip it when the dispatch says the premise is already recorded (`review-pr-feedback` rule 7 sends a `premise:` constraint). No review package exists, so no `ingest` or `decide-premise` runs: save its claims as `<flow-dir>/premise/<n>.json`, and apply every refusal of the merge by hand, as that `source` row lists them (`PREMISE_REJECTION_REASONS`, `src/review/premise.ts`): a refused claim leaves the finding upheld. On `challenged` or `owner-decision` ask the operator its question with its options (`ask_user` in keryx shell, the host's question tool elsewhere), journal their answer, and plan only what the operator upholds.
+
 Then freeze and start (`--yes`: the operator already answered the kinds question, so the freeze must not prompt):
 
 ```bash
@@ -389,11 +380,7 @@ fi
 keryx flow task done <id> <Tn>
 ```
 
-Why each path is checked on its own: `git status --porcelain --` with no path
-lists the whole tree, `git add` fails on a path that is neither on disk nor
-tracked, and `git commit` with nothing staged exits 1. The trailing
-`-- "${PENDING[@]}"` commits only these paths, so a file another lane staged is
-not swept into this commit.
+Why each path is checked on its own: `git status --porcelain --` with no path lists the whole tree, `git add` fails on a path that is neither on disk nor tracked, and `git commit` with nothing staged exits 1. The trailing `-- "${PENDING[@]}"` commits only these paths, so a file another lane staged is not swept into this commit.
 
 If new work is discovered:
 
@@ -415,6 +402,8 @@ properly formatted `subagent-result`.
 | `BLOCKED` | `keryx flow block <id> --reason "<worker reason>"`; resolve or escalate one concise question, then `flow unblock` and re-dispatch. |
 | `FAILED` | Emitted by harness **child** workers (`src/harness/child/contract.ts`), never by skill workers — `task-implementer` maps its own `failed` onto `BLOCKED`. Retry once with the same dispatch. If it fails again, block the flow and surface the error to the user. |
 
+**A `behavior_changes` entry with `needs_operator: true` is a question, not a concern to journal.** task-implementer lists every user-visible tradeoff it made (message wording, error placement, state reset) there. Before accepting that result, ask the operator with the question tool — one question per entry, the implemented choice and each of its `alternatives` as options — and record the answer in `journal.md`. An answer other than the implemented one is a fix task on the same `Tn` before the boundary commit, not a review finding later.
+
 Carry `run_id`/`dispatch_id` across retries so the flow journal stays traceable,
 and record every dispatch against the task's persisted counter so a session
 restart does not reset the budget:
@@ -432,7 +421,8 @@ 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 — in this session,
+4. **First-green gate, once per flow.** The first time every implement/test task is `done` and steps 1–3 pass, ask the operator one question (question tool, options) before any review round: `issue AC met — open the PR with the standard review`, or `harden first` with each extra matrix cell or failure path you would add as its own option. Record the answer in `journal.md`; picked hardening becomes `keryx flow task add` tasks (plus `keryx flow ac update` when it adds criteria) before review. A dispatched run has no operator: it takes the standard review and journals that the dispatch answered the gate.
+5. 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> --full --outstanding <subagents still running, 0 if none>
@@ -440,16 +430,16 @@ Before accepting implementation:
    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 — never shrink the fan-out to fit.
    Dispatch prompts point at sources (files, SHAs, the PR) and never paraphrase a contract.
+   Every round opens with `keryx review start` on the current head, never a hand-built range (Phase 4 loop, step 1).
 
-   `--outstanding` is the part that matters here. `review-orchestrator` runs inline
-   in this session and dispatches reviewers in parallel; keryx cannot observe other
-   subagents. Passing the count still running is the only thing that makes the
-   concurrency cap mean anything; omit it and the cap bounds the reviewer fan-out
-   alone, which the review record then states plainly. Add `--full` for `--all`.
+   `--outstanding` is the part that matters here. `review-orchestrator` runs inline in this session and dispatches reviewers in parallel; keryx cannot observe other subagents. Passing the count still running is the only thing that makes the concurrency cap mean anything; omit it and the cap bounds the reviewer fan-out alone, which the review record then states plainly. Add `--full` for `--all`.
 
-5. If findings require code changes, dispatch fix work through `task-implementer`
-   and record the fix task in the flow.
-6. Close the skill-learning loop (see `rules/core/skill-lifecycle.mdc`). Collect
+6. If findings require code changes, run a fix round through `task-implementer`, recorded as a flow fix task:
+   - **Scope freeze.** A fix round fixes the round's findings and nothing else. Hardening, refactors or new cells a fix suggests go to the operator as a question (as in step 4); never grow scope inside a fix round.
+   - **Red probes → ONE implementer.** When reviewers left red probes (failing tests or commands on the findings), pass them as `test_case_specs` to one `task-implementer` dispatch — no separate `tests-creator` task. `tests-creator` runs only for a new contract no probe covers.
+   - **A held finding is not fixed.** A finding `review-premise` held (`challenged` or `owner-decision`) is neither fixable nor clean: it never goes into `fix_context.review_feedback` and it blocks the loop until answered. Ask the operator about it as `review-orchestrator` "Wave D" says (the card in keryx shell; elsewhere the question tool, then the exact `keryx review decide-premise` command for them to run in their terminal) and journal the recorded answer; only an upheld finding enters a fix round, carrying `premise_verdict` and `premise_answer` as task-implementer's `FIX_CONTEXT` defines them. A dispatched run leaves it held and journals it.
+   - **`suggested_fix` is a hypothesis.** Pass each finding's `id` and `suggested_fix` in `fix_context.review_feedback`; the implementer reproduces the finding (red), checks the suggestion against the state × event matrix, then fixes (task-implementer 1.3). Journal every `suggested_fix diverged` / `did not reproduce` note it returns.
+7. Close the skill-learning loop (see `rules/core/skill-lifecycle.mdc`). Collect
    the `skill_drift` fields from task-implementer results and the
    `## Skill Learning` block from review-orchestrator. For each flagged
    project-skill, dispatch a subagent — on a cheaper / non-flagship model if one
@@ -536,18 +526,12 @@ the bound plus an escalation — never an unbounded loop.
 
 ### PR review/fix loop
 
-1. Run the relevant `review-orchestrator` checks against the PR and current
-   branch state.
-2. If findings or required check failures remain, create or update a flow fix
-   task, dispatch `task-implementer`, push the fix, and run review again.
+1. Each round — the first and every one after a fix — is `keryx review start` on the PR's current head, then `review-orchestrator` from that package. `review start` finds the previous round itself (local package, git history, the PR's round block, the flow package) and, when the previous reviewed head is an ancestor, reviews the delta: fix changes with a small roster (logic, regression, the findings' authors, the verifier) and the prior findings attached, new changes as round 1, unchanged code carried with its dispositions. Never pass a whole-branch range or `--all` per round; `<package>/round.json` records the round, its source and its mode.
+2. If findings (held ones aside: Phase 3 step 6) or required check failures remain, run a fix round under Phase 3 step 6 (flow fix task, `task-implementer`), push the fix, and run the next round as in step 1.
 
    **A required check failure is not automatically a fix task.** When `review.jev.ci_triage` is on, run `keryx review ci-triage --run <id> --json` on each failed run first: `top: flaky` (or a `deterministic` override) → rerun once (`gh run rerun --failed <id>`), record it in `journal.md`, and treat a second failure as `real-regression` regardless; `top: real-regression` → investigate and fix as usual; `top: infra` → report it in the completion notes and leave the code alone. The verdict is advisory only — never the sole reason to skip a fix task.
 
-   **The threshold is `minor`.** The loop exits when the round reports zero
-   findings at `blocker`, `major` or `minor`; `info` does not hold it. State the
-   remaining `info` findings in the completion report rather than fixing them
-   under a loop that was not opened for them. A caller may lower the threshold in
-   `constraints`; it cannot raise it to merge over a `minor`.
+   **The threshold is `minor`.** The loop exits when the round reports zero findings at `blocker`, `major` or `minor` that are not held, and no held finding awaits the operator; `info` does not hold it. A held finding counts as neither fixable nor clean: while one is unanswered, run no fix round for it and stop to ask (unattended: stop and report the held list). State the remaining `info` findings in the completion report rather than fixing them under a loop that was not opened for them. A caller may lower the threshold in `constraints`; it cannot raise it to merge over a `minor`.
 3. Allow at most **five** review/fix attempts for the current approach. Count
    an attempt when review/check results are available, including a clean result,
    and record it with `keryx flow task attempt <id> <Tn> --outcome ...` so the
@@ -691,4 +675,8 @@ Stop and re-read this skill if you are thinking:
 | "The worker returned BLOCKED twice — faster if I implement this task myself." | The implementer never self-accepts and the orchestrator never implements. Block the flow, escalate one concise question, then unblock and re-dispatch. Doing the work here erases the boundary the whole flow model rests on. |
 | "Verification is described in the plan, so it will happen." | A verification step in the plan is a task, not a sentence. If it is not a task with a status, nothing records whether it ran, and the flow reaches `implemented` with an unrun gate. |
 | "The review fan-out is cheap, so the budget check can wait." | `keryx review budget --spent … --outstanding …` gates the fan-out, and `review-orchestrator` runs inline in this same main session, where keryx cannot see the in-flight subagents; declare them with `--outstanding`. Skipping the check means the cap bounds nothing. |
+| "The reviewer wrote the fix; applying it is the fastest close." | A `suggested_fix` is a hypothesis. Most majors in a long fix loop are introduced by fixes: reproduce the finding red, check the suggestion against the state × event matrix, then fix (Phase 3 step 6). |
+| "The finding came from a review, so its premise is settled." | A finding can reproduce and still not be a defect. Never pass a held finding in `fix_context.review_feedback`; ask the operator as `review-orchestrator` "Wave D" says (Phase 3 step 6); a flow sourced from a finding runs `review-premise` before freeze (Phase 1). |
+| "While I'm in this code, the fix round can also harden the empty state." | Scope freeze: a fix round fixes findings. New hardening is an operator decision at the first-green gate or as an explicit question, never silent growth. |
+| "The implementer journaled its UX choice, so it is decided." | A `behavior_changes` entry with `needs_operator: true` is decided by the operator, asked with options before the result is accepted (Phase 2). A journal line decides nothing. |
 | "I'll set the verification kind later." | An `unclassified` criterion cannot become data afterwards without a recorded rewrite: `keryx flow ac update <id> --criterion ACn --text "…" --reason "<why>"`. Put the `[verify: …]` marker on every criterion before `flow freeze`. |

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

@@ -0,0 +1,70 @@
+# Job Orchestrator - Reference Detail
+
+Reference material moved out of `SKILL.md` to keep it within its length ceiling:
+rationale, evidence and long examples. Nothing here is an instruction the agent must
+follow at a step; each section is linked from the spot in `SKILL.md` that used it.
+
+## Dry-run plan output example
+
+```
+Dry-run plan for: issue-4141--pipeline-validation
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Step 1: analyze          [issue-analyzer]           → input: issue #4141
+Step 2: context          [context-collector]        → input: analysis result, project_dir
+Step 3: prepare          [orchestrator]             → creates: feature/pipeline-validation worktree
+Step 4: tests-creator    [tests-creator × 3]        → RED stubs, one per task
+Step 5: implement        [task-implementer × 3]     → wave-parallel, 3 tasks
+Step 6: sanity-check     [orchestrator]             → verifies commits exist
+Step 7: verify           [code-verifier]            → lint + type-check + test + imports
+Step 8: review           [review-orchestrator]      → managed round, ingested
+Step 9: security         [security-audit]           → conditional: auth/API/DB/env files
+Step 10: fix             [task-implementer]         → conditional: if NEEDS_FIX
+Step 11: verify-post-fix [code-verifier]            → conditional: after fix
+Step 12: perf-check      [perf-check]               → conditional: frontend/bundle files
+Step 13: report          [orchestrator]             → aggregates all results
+Step 14: pr              [orchestrator + gh CLI]    → conditional: if create_pr
+Step 15: deploy          [deploy]                   → conditional: if user asks
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Estimated sub-agent calls: 11-14 (varies with tasks and review findings)
+No changes will be made. Use without --dry-run to execute.
+```
+
+## Post-mortem document template
+
+```markdown
+# Post-Mortem: <job-name>
+
+## Timeline
+(from .metaproject/jobs/<job-name>/journal.md — every line as recorded)
+- <ISO timestamp> - created
+- <ISO timestamp> - step: implement in-progress (retries 0)
+- <ISO timestamp> - step: implement in-progress (retries 1)
+- <ISO timestamp> - step: implement failed (retries 1) — <reason>
+
+## What Went Wrong
+- <Step name> failed with: <error class> — <error message>
+- Recorded retries: <metrics.steps[].retries>
+- Root cause hypothesis: <analysis>
+
+## What Worked
+- <N> tasks completed successfully
+- Context collection was accurate
+
+## Recommendations for Retry
+- Fix <specific issue> before re-running
+- Consider splitting task-3 into smaller subtasks
+```
+
+## Metrics table in the report
+
+**Aggregated in the report:**
+```markdown
+## Metrics
+| Step | Duration | Retries |
+|------|----------|---------|
+| Analyze | 45s | 0 |
+| Context | 30s | 0 |
+| Implement | 5m 22s | 1 |
+| Review | 1m 10s | 0 |
+| **Total** | **7m 47s** | **1** |
+```

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

@@ -989,7 +989,7 @@ transcript and nothing else, which is precisely the failure the managed pipeline
 replaced.
 
 A pull request driven by this orchestrator has to pass the completion gate shipped in
-0.2.71. Its five conditions are what 2.6 and 2.7 are built to satisfy:
+0.2.71. Its conditions are what 2.6 and 2.7 are built to satisfy:
 
 | Gate condition | Satisfied by |
 |---|---|
@@ -998,6 +998,7 @@ A pull request driven by this orchestrator has to pass the completion gate shipp
 | scope B is recorded when a scope-B reviewer ran | `keryx review blast-radius --json` → `review ingest --blast-radius` (2.6.1) |
 | no inbound PR comment is unanswered | `keryx review comments collect` every round, `… reply --final` once (2.6.2) |
 | verification stats exist | `review-verifier` dispatched, passed as `--verifications` (2.6.1) |
+| no held finding lacks an operator decision | `review-premise` (Wave D) claims passed as `--premises`; each held finding asked as `review-orchestrator` "Wave D" says (2.6.1) |
 
 #### 2.6.0 Review Scope Selection
 
@@ -1125,24 +1126,26 @@ runs on the session model. That is a correct answer, not a failure.
 
 ```
 flags:             <selected flags, e.g. --backend --security --testing-practices>
-commit_range:      <BASE_SHA>..HEAD
+commit_range:      <BASE_SHA>..HEAD   # round 1 only; a later round takes its range from round.json
 issue_url:         <issue URL, when the job has one — enables the Stage 1 spec gate>
 context_doc:       <JOBS_ROOT>/<job-name>/ai/context.md
 verification_mode: annotate
 managed_review:    { mode: "review-flow", target: "branch", target_ref: "<feature-branch>" }
-is_fix_round:      <true on any round after the first>
+is_fix_round:      <true on any round after the first; the round, its range and prior_findings come from `review start`/`review plan`, never from your own range>
 pr_comments:       { enabled: <true when a PR exists> }
 ```
 
-It emits the unified report AND the fenced ```json keryx:findings``` block, and runs
-`review-verifier` (Wave C) over the consolidated findings, returning its verification
-claims as a file path.
+It emits the unified report AND the fenced ```json keryx:findings``` block, runs
+`review-verifier` (Wave C) and then `review-premise` (Wave D) over the consolidated
+findings, and returns the verification claims and the premise claims as file paths.
 
-**Step 7 — verification is part of the round, not an extra.** `review-orchestrator`
-dispatches `review-verifier` in Wave C over the consolidated findings. The verifier
-**runs something** and can only delete — it never raises a severity, adds a finding,
-or rewrites one, and it never verifies a finding raised by the same reviewer. Its
-claims are merged by the CLI, not by hand.
+**Step 7 — verification and the premise check are part of the round, not extras.**
+`review-orchestrator` dispatches `review-verifier` in Wave C over the consolidated
+findings. The verifier **runs something** and can only delete — it never raises a
+severity, adds a finding, or rewrites one, and it never verifies a finding raised by the
+same reviewer. After it, `review-premise` (Wave D) judges whether each finding is a
+defect at all: it can lower a severity or hold a finding for the operator, never add
+one. Both claim sets are merged by the CLI, not by hand.
 
 **Step 8 — ingest the round.** This is what makes it citable.
 
@@ -1152,13 +1155,14 @@ keryx review ingest --report <path/to/review-report.md> --ref <feature-branch> \
   --scope <JOBS_ROOT>/<job-name>/scope.json \
   --blast-radius <JOBS_ROOT>/<job-name>/blast-radius.json \
   --verifications <path/to/verifications.json> --verification-mode annotate \
-  --refuted <path/to/refuted.json> \
+  --premises <path/to/premises.json> --refuted <path/to/refuted.json> \
   --spent <usd-so-far> --outstanding <subagents in flight>
 ```
 
 An unrecognised option is **refused, not ignored** — a silently dropped flag writes
 nothing and still reports success. `--refuted` carries findings this round raised and
 then dismissed; without it the package keeps only the survivors of an unlogged triage.
+A first ingest without `--premises` holds nothing; a re-ingest carries earlier holds.
 
 **Findings are the canonical shape.** One vocabulary, everywhere in this skill:
 
@@ -1174,9 +1178,18 @@ then dismissed; without it the package keeps only the survivors of an unlogged t
 
 **Classify:**
 ```
-NEEDS_FIX = count(blocker) > 0 OR count(major) > 0
+HELD      = findings review-premise holds (challenged / owner-decision) with no operator decision
+OPEN      = blocker + major findings not in HELD
+NEEDS_FIX = count(OPEN) > 0
 ```
 
+A HELD finding is neither fixable nor clean: it never enters a fix prompt, and it blocks
+the job until answered. Ask the operator about each one as `review-orchestrator` "Wave
+D" says; an upheld one rejoins OPEN at its severity (carrying `premise_verdict` and
+`premise_answer` as task-implementer's `FIX_CONTEXT` defines them), a dismissed one
+carries `dismissed-incorrect` from the operator's decision. Unattended: stop and report
+the HELD list; never let the loop end reading clean while HELD is non-empty.
+
 **Document:** record the report in the job package too, so the job and the review
 record point at each other:
 
@@ -1276,7 +1289,7 @@ still reported — so a finding the next reviewer simply did not look at was rec
 fixed. That is absence-as-evidence, and the completion gate refuses it.
 
 ```
-UNRESOLVED_FINDINGS = all blocker + major findings from step 2.6
+UNRESOLVED_FINDINGS = OPEN from step 2.6          # never a HELD finding (Classify, 2.6.1)
 PREVIOUS_REVIEW_OUTPUT = <the ingested report from step 2.6>
 
 FOR iteration in [1, 2, 3]:
@@ -1298,15 +1311,15 @@ FOR iteration in [1, 2, 3]:
   4. Run the sanity check (step 2.5.2 logic) — verify commits were made
   5. Run the next managed round — the FULL 2.6.1 sequence, not a bare re-dispatch:
        keryx review budget  --spent <usd> --outstanding <n>
-       keryx review start   --target branch --ref <feature-branch> --head <new-head>
+       keryx review plan    --target branch --ref <feature-branch> --head <new-head>
+                            # start + scope + blast-radius + slice + required + estimate on the new head;
+                            # round.json names the delta, scope.json and blast-radius.json land in the package
        keryx review comments collect --repo <r> --pr <n> --sha <new-head> --round <N+1> --out <file>
-       keryx review scope        --ref "$BASE_SHA" --json > scope.json
-       keryx review blast-radius --ref "$BASE_SHA" --previous blast-radius.json --json > blast-radius.json
-       <run review-orchestrator inline, in this session, with is_fix_round: true>
+       <run review-orchestrator inline, in this session; it takes the round from round.json>
        keryx review ingest  --report <new-report> --ref <feature-branch> --head <new-head> \
                             --scope scope.json --blast-radius blast-radius.json \
-                            --verifications <file> --refuted <file> --outstanding <n>
-  6. Recompute NEEDS_FIX from the ingested findings
+                            --verifications <file> --premises <file> --refuted <file> --outstanding <n>
+  6. Recompute HELD, OPEN and NEEDS_FIX from the ingested findings; a new HELD finding is asked about as in Classify
   7. Record what became of each finding raised in the PREVIOUS round — every one of
      them, before the next iteration starts:
 
@@ -1320,9 +1333,8 @@ FOR iteration in [1, 2, 3]:
      must cite where the outcome is written down. A recorded state and its citation
      cannot be overwritten by a later close — record a correction as a new round.
      Closing with no dispositions leaves every finding reading `unknown`, which means
-     "nobody wrote down what happened".
-  8. UNRESOLVED_FINDINGS = the blocker + major findings of the NEW round that are
-     still without a terminal disposition
+     "nobody wrote down what happened". A HELD finding gets no disposition here: it waits for the operator.
+  8. UNRESOLVED_FINDINGS = the OPEN findings of the NEW round still without a terminal disposition
 
   9. STUCK CHECK — runs before the next iteration and ignores the budget:
      IF any finding identity is in UNRESOLVED_FINDINGS for the SECOND iteration
@@ -1351,6 +1363,8 @@ IF still NEEDS_FIX after max iterations, or the stuck check broke the loop:
   steps. Give every surviving finding a disposition (dismissed-wont-fix or
   dismissed-deprioritised, with evidence) rather than leaving it `unknown`
   → continue to VERIFY (2.8)
+
+IF HELD is non-empty when the loop ends: ask the operator (Classify); unattended, stop and report the HELD list
 ```
 
 `comments reply` **refuses without `--final`**: replying per round turns one review
@@ -1936,28 +1950,8 @@ When `dry_run: true` is set (or `--dry-run` is passed):
 3. **Phase 2 is skipped entirely** — no sub-agents dispatched, no git operations
 4. **Output:** Full plan tree with agent names, input data shapes, dependencies:
 
-```
-Dry-run plan for: issue-4141--pipeline-validation
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Step 1: analyze          [issue-analyzer]           → input: issue #4141
-Step 2: context          [context-collector]        → input: analysis result, project_dir
-Step 3: prepare          [orchestrator]             → creates: feature/pipeline-validation worktree
-Step 4: tests-creator    [tests-creator × 3]        → RED stubs, one per task
-Step 5: implement        [task-implementer × 3]     → wave-parallel, 3 tasks
-Step 6: sanity-check     [orchestrator]             → verifies commits exist
-Step 7: verify           [code-verifier]            → lint + type-check + test + imports
-Step 8: review           [review-orchestrator]      → managed round, ingested
-Step 9: security         [security-audit]           → conditional: auth/API/DB/env files
-Step 10: fix             [task-implementer]         → conditional: if NEEDS_FIX
-Step 11: verify-post-fix [code-verifier]            → conditional: after fix
-Step 12: perf-check      [perf-check]               → conditional: frontend/bundle files
-Step 13: report          [orchestrator]             → aggregates all results
-Step 14: pr              [orchestrator + gh CLI]    → conditional: if create_pr
-Step 15: deploy          [deploy]                   → conditional: if user asks
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Estimated sub-agent calls: 11-14 (varies with tasks and review findings)
-No changes will be made. Use without --dry-run to execute.
-```
+The full plan tree (agent names, input shapes, dependencies, no changes made):
+`SKILL.detail.md`, "Dry-run plan output example".
 
 5. Ask user: "Execute this plan? (yes / adjust / abort)"
 
@@ -2158,29 +2152,7 @@ When a job ends with a step recorded `failed`, or with unresolved blocker findin
    off `journal.md`, which `keryx job` timestamped as the job ran, and the retry counts
    come from `keryx job status <job-name> --json`:
 
-```markdown
-# Post-Mortem: <job-name>
-
-## Timeline
-(from .metaproject/jobs/<job-name>/journal.md — every line as recorded)
-- <ISO timestamp> - created
-- <ISO timestamp> - step: implement in-progress (retries 0)
-- <ISO timestamp> - step: implement in-progress (retries 1)
-- <ISO timestamp> - step: implement failed (retries 1) — <reason>
-
-## What Went Wrong
-- <Step name> failed with: <error class> — <error message>
-- Recorded retries: <metrics.steps[].retries>
-- Root cause hypothesis: <analysis>
-
-## What Worked
-- <N> tasks completed successfully
-- Context collection was accurate
-
-## Recommendations for Retry
-- Fix <specific issue> before re-running
-- Consider splitting task-3 into smaller subtasks
-```
+Use the template in `SKILL.detail.md`, "Post-mortem document template".
 
 2. Save to `.metaproject/jobs/<job-name>/post-mortem.md`
 3. Include in final user message: "Post-mortem saved to `.metaproject/jobs/<job-name>/post-mortem.md`"
@@ -2220,16 +2192,7 @@ terminal disposition.
 keryx job status <job-name> --json     # `retries` per step, plus phase and next_step
 ```
 
-**Aggregated in the report:**
-```markdown
-## Metrics
-| Step | Duration | Retries |
-|------|----------|---------|
-| Analyze | 45s | 0 |
-| Context | 30s | 0 |
-| Implement | 5m 22s | 1 |
-| Review | 1m 10s | 0 |
-| **Total** | **7m 47s** | **1** |
-```
+**Aggregated in the report:** a per-step Duration/Retries table with a total row
+(`SKILL.detail.md`, "Metrics table in the report").
 
 This data identifies which steps are bottlenecks and which ones needed a second attempt.

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

@@ -179,7 +179,7 @@ If `blocker` or `major` findings exist:
 1. Group by file
 2. Launch task-implementer (`task_type: "fix"`) with the findings
 3. Run the sanity check — verify commits were made
-4. Run the NEXT managed round (the whole REVIEW sequence above, `is_fix_round: true`)
+4. Run the NEXT managed round: `keryx review plan --target branch --ref <feature-branch> --head <new-head>` (or `review start`) on the new head, then review-orchestrator. The round, range and prior findings come from `round.json`: no own range, no `--all` per round, no whole-branch re-review.
 5. Disposition every finding of the previous round:
    ```bash
    keryx review complete <review-id> --finding F-001 --disposition acted-on --evidence "<commit>"