@mrciphersmith/keryx 0.3.119 → 0.3.120

package/dist/core.js

@@ -9635,11 +9635,11 @@ var init_skill_length_ceilings = __esm(() => {
     "orchestration/context-collector": 671,
     "orchestration/feature-analyzer": 447,
     "orchestration/feature-dev": 177,
-    "orchestration/flow-orchestrator": 694,
+    "orchestration/flow-orchestrator": 691,
     "orchestration/issue-analyzer": 373,
     "orchestration/job-documenter": 414,
     "orchestration/job-orchestrator": 2235,
-    "orchestration/task-implementer": 668,
+    "orchestration/task-implementer": 662,
     "planning/autodoc-analyst": 180,
     "planning/autodoc-architect": 179,
     "planning/autodoc-assembler": 145,
@@ -9689,8 +9689,8 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-clean-code": 543,
     "review/review-core-boundaries": 163,
     "review/review-flow-graph": 188,
-    "review/review-frontend": 616,
-    "review/review-frontend-conventions": 213,
+    "review/review-frontend": 612,
+    "review/review-frontend-conventions": 211,
     "review/review-highload": 548,
     "review/review-jev-comments": 184,
     "review/review-jev-contract": 193,
@@ -9700,7 +9700,7 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-jev-scenarios": 187,
     "review/review-layout": 238,
     "review/review-logic": 370,
-    "review/review-orchestrator": 1615,
+    "review/review-orchestrator": 1582,
     "review/review-performance": 359,
     "review/review-pr-contract": 191,
     "review/review-pr-feedback": 895,
@@ -27431,6 +27431,12 @@ import { existsSync as existsSync8 } from "fs";
 import { readFile as readFile23 } from "fs/promises";
 import path50 from "path";
 
+// src/review/round-record.ts
+init_fs();
+var NOT_REVIEW_PACKAGES = [".", ":(exclude).metaproject/reviews", ":(exclude,glob).metaproject/flows/*/reviews/**"];
+var REVIEWED_STATUSES = new Set(["reviewed", "decided", "learned", "closed"]);
+var COMPLETED_STATUSES = new Set(["decided", "learned", "closed"]);
+
 // src/review/stack.ts
 init_skill_frontmatter();
 var STACK_TAGS = ["nestjs", "react", "mobx", "prisma", "playwright", "sql", "http-server"];
@@ -28302,6 +28308,41 @@ async function unresolvedReferences(projectRoot, content) {
 
 // src/review/reviewers.ts
 init_skill_frontmatter();
+function overlapFields(content) {
+  const list = (key) => {
+    const nested = metadataList(content, key);
+    return nested.length > 0 ? nested : frontmatterList(content, key);
+  };
+  const scalar = (key) => {
+    const value = (frontmatterScalar(content, key, "metadata") ?? frontmatterScalar(content, key))?.trim();
+    return value === undefined || value === "" ? undefined : value;
+  };
+  const supersedes = [...new Set(list("supersedes").map((name) => name.trim()).filter(Boolean))];
+  const overlapGroup = scalar("overlap_group");
+  const rank = scalar("overlap_rank");
+  return {
+    ...supersedes.length > 0 ? { supersedes } : {},
+    ...overlapGroup !== undefined ? { overlapGroup } : {},
+    ...rank === "generic" || rank === "specific" ? { overlapRank: rank } : {}
+  };
+}
+function overlapGroupsOf(inventory) {
+  const tier = (source, rank) => source === "project-skill" ? 0 : rank === "generic" ? 2 : 1;
+  const members = new Map;
+  for (const reviewer of [...inventory.project, ...inventory.bundled]) {
+    if (reviewer.overlapGroup === undefined)
+      continue;
+    const list = members.get(reviewer.overlapGroup) ?? [];
+    if (!list.some((entry) => entry.name === reviewer.name))
+      list.push({ name: reviewer.name, tier: tier(reviewer.source, reviewer.overlapRank) });
+    members.set(reviewer.overlapGroup, list);
+  }
+  const groups = {};
+  for (const [group, list] of [...members].sort(([a], [b]) => a.localeCompare(b))) {
+    groups[group] = list.sort((a, b) => a.tier - b.tier || a.name.localeCompare(b.name)).map((entry) => entry.name);
+  }
+  return groups;
+}
 function metadataLine(content, label) {
   const match = content.match(new RegExp(`^${escapeRegexLiteral(label)}:\\s*(.+)$`, "m"));
   return match?.[1]?.trim();
@@ -28339,7 +28380,8 @@ async function bundledReviewerFromFile(name, skillMdPath, projectRelativePath) {
     source: "bundled",
     path: projectRelativePath,
     ...engine !== undefined ? { engine } : {},
-    ...description !== undefined ? { description } : {}
+    ...description !== undefined ? { description } : {},
+    ...content !== undefined ? overlapFields(content) : {}
   };
 }
 async function projectInstalledReviewers(bundledRoot) {
@@ -28394,7 +28436,8 @@ async function collectReviewers(projectRoot, deps = {}) {
       ...origin ? { origin } : {},
       ...originHash ? { originHash } : {},
       ...importedAt ? { importedAt } : {},
-      drift: await driftFor(projectRoot, origin, originHash)
+      drift: await driftFor(projectRoot, origin, originHash),
+      ...overlapFields(content)
     });
   }
   const family = familyFlagsByReviewer(new Map(project.map((reviewer) => [reviewer.name, reviewer.flags])));
@@ -28404,6 +28447,22 @@ async function collectReviewers(projectRoot, deps = {}) {
   return { bundled, bundledSource, project };
 }
 
+// src/review/cost.ts
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+// src/review/jev-select.ts
+var CORE_MANDATORY_REVIEWER_IDS = [
+  "review-logic",
+  "review-architecture",
+  "review-security-code",
+  "review-highload"
+];
+
+// src/review/coverage.ts
+init_contained_path();
+
 // src/review/run-profile.ts
 init_fs();
 import { existsSync as existsSync6, readFileSync as readFileSync10 } from "fs";
@@ -28988,6 +29047,17 @@ var LIGHT_MAX_FILES = 5;
 var LIGHT_MAX_CHANGED_LINES = 300;
 var LIGHT_FIXED_REVIEWERS = ["review-logic", "review-testing-practices"];
 var LIGHT_CONVENTIONS_PREFERENCE = ["review-frontend-conventions", "review-backend", "review-clean-code"];
+var NEVER_SUPERSEDED = new Set([...CORE_MANDATORY_REVIEWER_IDS, "review-regression"]);
+function overlayChangedByRound(reviewer, context) {
+  if (reviewer.source !== "project-skill" || reviewer.path === undefined)
+    return;
+  if (context.files === undefined)
+    return `${reviewer.name} is a project overlay and the round's changed files are not recorded, so it cannot be ruled out that this branch wrote it`;
+  const absolute = path50.isAbsolute(reviewer.path) ? reviewer.path : path50.resolve(context.root ?? process.cwd(), reviewer.path);
+  const dir = path50.relative(context.root ?? process.cwd(), path50.dirname(absolute)).split(path50.sep).join("/");
+  const changed = context.files.find((file) => file === dir || file.startsWith(`${dir}/`));
+  return changed === undefined ? undefined : `${reviewer.name} is a project overlay this round changes (${changed})`;
+}
 var NOT_ROSTER = new Set([
   "review-orchestrator",
   "review-verifier",
@@ -29129,6 +29199,83 @@ var PR_CONTRACT = "review-pr-contract";
 function dispatchKnowsRole(dispatch, role) {
   return Array.isArray(dispatch.roles) && dispatch.roles.includes(role);
 }
+function applySupersedes(required, inventory, excluded, context = {}, notes = []) {
+  const kept = new Set(required);
+  for (const reviewer of [...inventory.project, ...inventory.bundled]) {
+    if (!kept.has(reviewer.name))
+      continue;
+    const targets = (reviewer.supersedes ?? []).filter((target) => target !== reviewer.name && kept.has(target));
+    if (targets.length === 0)
+      continue;
+    const core = targets.filter((target) => NEVER_SUPERSEDED.has(target));
+    if (core.length > 0)
+      notes.push(`${reviewer.name} supersedes ${core.join(", ")}: ignored, ${core.length === 1 ? "it is a core role" : "they are core roles"} that always run`);
+    const rest = targets.filter((target) => !NEVER_SUPERSEDED.has(target));
+    if (rest.length === 0)
+      continue;
+    const changed = overlayChangedByRound(reviewer, context);
+    if (changed !== undefined) {
+      notes.push(`${reviewer.name} supersedes ${rest.join(", ")}: ignored, ${changed}`);
+      continue;
+    }
+    for (const target of rest) {
+      kept.delete(target);
+      excluded.push({ reviewer: target, reason: `superseded by ${reviewer.name}` });
+    }
+  }
+  return required.filter((name) => kept.has(name));
+}
+function applyOverlapGroups(required, inventory, files, excluded, context = {}, notes = []) {
+  const kept = new Set(required);
+  const byName = new Map([...inventory.project, ...inventory.bundled].map((reviewer) => [reviewer.name, reviewer]));
+  const projectGates = new Map(inventory.project.filter((r) => r.pathsSource !== "none" && r.paths.length > 0).map((r) => [r.name, r.paths.map(globToRegExp2)]));
+  const gateOf = (name) => {
+    const bundled = BUNDLED_PATH_GATES[name];
+    if (bundled !== undefined)
+      return bundled;
+    const patterns = projectGates.get(name);
+    return patterns === undefined ? undefined : (file) => patterns.some((p) => p.test(file));
+  };
+  const covers = (winner, loser) => {
+    const wide = gateOf(winner);
+    if (wide === undefined)
+      return true;
+    if (files === undefined)
+      return false;
+    const narrow = gateOf(loser);
+    return files.filter((file) => narrow === undefined || narrow(file)).every((file) => wide(file));
+  };
+  for (const [group, members] of Object.entries(overlapGroupsOf(inventory))) {
+    const present = members.filter((member) => kept.has(member));
+    const winner = present[0];
+    if (winner === undefined)
+      continue;
+    const winnerReviewer = byName.get(winner);
+    const changed = winnerReviewer === undefined ? undefined : overlayChangedByRound(winnerReviewer, { ...context, files });
+    for (const member of present.slice(1)) {
+      if (!covers(winner, member))
+        continue;
+      if (NEVER_SUPERSEDED.has(member)) {
+        notes.push(`overlap group ${group}: ${member} kept beside ${winner}, it is a core role that always runs`);
+        continue;
+      }
+      if (changed !== undefined) {
+        notes.push(`overlap group ${group}: ${member} kept beside ${winner}, ${changed}`);
+        continue;
+      }
+      kept.delete(member);
+      excluded.push({ reviewer: member, reason: `overlap group ${group}: ${winner} reads the same lines` });
+    }
+  }
+  return required.filter((name) => kept.has(name));
+}
+function lightConventionsReviewer(roster, inventory) {
+  const pick = LIGHT_CONVENTIONS_PREFERENCE.find((name) => roster.includes(name));
+  if (pick === undefined)
+    return;
+  const group = Object.values(overlapGroupsOf(inventory)).find((members) => members.includes(pick));
+  return group?.find((member) => roster.includes(member)) ?? pick;
+}
 async function requiredReviewers(root, mode, files, options = {}) {
   const inventory = await collectReviewers(root);
   const stack = await detectProjectStack(root);
@@ -29153,7 +29300,7 @@ async function requiredReviewers(root, mode, files, options = {}) {
   }
   const filesKnown = files !== undefined;
   if (options.depth === "light") {
-    const conventions = LIGHT_CONVENTIONS_PREFERENCE.find((name) => roster.includes(name));
+    const conventions = lightConventionsReviewer(roster, inventory);
     const keep = new Set([...LIGHT_FIXED_REVIEWERS, ...conventions === undefined ? [] : [conventions]]);
     const light = roster.filter((name) => keep.has(name));
     for (const name of roster)
@@ -29162,7 +29309,9 @@ async function requiredReviewers(root, mode, files, options = {}) {
     for (const name of [REGRESSION, PR_CONTRACT])
       if (inventory.bundled.some((r) => r.name === name))
         excluded.push({ reviewer: name, reason: "light round: not part of the light set" });
-    return { mode, depth: "light", required: light.sort(), excluded, filesKnown };
+    const notes = [];
+    const kept = applySupersedes(light, inventory, excluded, { root, files }, notes).sort();
+    return { mode, depth: "light", required: kept, excluded, filesKnown, ...notes.length === 0 ? {} : { notes } };
   }
   const gated = (name) => {
     if (!filesKnown)
@@ -29202,13 +29351,15 @@ async function requiredReviewers(root, mode, files, options = {}) {
     else
       excluded.push({ reviewer: PR_CONTRACT, reason: "no pr-context.md in the package: there is no PR body checklist to compare with the diff" });
   }
-  return { mode, depth: "full", required: required.sort(), excluded, filesKnown };
+  const notes = [];
+  const collapsed = applyOverlapGroups(applySupersedes(required, inventory, excluded, { root, files }, notes), inventory, files, excluded, { root }, notes).sort();
+  return { mode, depth: "full", required: collapsed, excluded, filesKnown, ...notes.length === 0 ? {} : { notes } };
 }
 async function gitDiffStats(root, target) {
   try {
     assertGitRevision(target.ref);
     assertGitRevision(target.head);
-    const proc = Bun.spawn(["git", "diff", "--no-color", "-U20", "--end-of-options", `${target.ref}...${target.head}`], { cwd: root, stdout: "pipe", stderr: "pipe", timeout: 15000, killSignal: "SIGKILL", maxBuffer: 8 * 1024 * 1024 });
+    const proc = Bun.spawn(["git", "diff", "--no-color", "-U20", "--end-of-options", `${target.ref}...${target.head}`, "--", ...NOT_REVIEW_PACKAGES], { cwd: root, stdout: "pipe", stderr: "pipe", timeout: 15000, killSignal: "SIGKILL", maxBuffer: 8 * 1024 * 1024 });
     const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
     if (exitCode !== 0 || proc.signalCode !== null)
       return;
@@ -29345,13 +29496,50 @@ async function reviewerSetErrors(dispatch, options, effective) {
     depth: effective?.depth ?? "full"
   });
   const selected = new Set(Array.isArray(record.selected) ? record.selected.filter(text) : []);
+  const skips = dispatchSkips(record).filter((skip) => need.required.includes(skip.reviewer) && !selected.has(skip.reviewer));
+  const decided = await skipDecision(options.packageDir, skips.map((skip) => skip.reviewer));
+  if (decided.ok)
+    for (const skip of skips)
+      selected.add(skip.reviewer);
   const missing = need.required.filter((name) => !selected.has(name));
   if (!missing.length)
     return [];
+  if (!decided.ok)
+    return [`dispatch.skipped is not accepted: ${decided.refusal}`];
   return [
     `dispatch covers ${need.required.length - missing.length} of ${need.required.length} reviewers that mode ${record.mode} requires; missing: ${missing.join(", ")}. ` + "Dispatch them, or record an operator override {operatorQuote, reason}; `keryx review required` prints the set" + (effective?.refused === undefined ? "" : `. The dispatch says depth light, but the full set applies: ${effective.refused}`)
   ];
 }
+async function skipDecision(packageDir, skipped) {
+  if (skipped.length === 0)
+    return { ok: true };
+  const writers = decisionWriters("reviewer-override", packageDir === undefined ? "<review-dir>" : path50.relative(process.cwd(), packageDir) || ".");
+  if (packageDir === undefined)
+    return { ok: false, refusal: `skipping ${skipped.join(", ")} needs the operator's decision recorded in the package: ${writers}` };
+  const { required } = await reviewersLeftOut(packageDir, undefined);
+  const outside = skipped.filter((name) => !required.includes(name));
+  if (outside.length > 0)
+    return { ok: false, refusal: `${outside.join(", ")} cannot be skipped: no operator decision can name ${outside.length === 1 ? "it" : "them"} (not in the mode-all required set ${required.join(", ") || "none"}); run ${outside.length === 1 ? "it" : "them"}` };
+  const skip = new Set(skipped);
+  const now = await operatorDecisionSubject(packageDir, "reviewer-override", required.filter((name) => !skip.has(name)));
+  if (await confirmedDecision(packageDir, "reviewer-override", now) !== undefined)
+    return { ok: true };
+  return { ok: false, refusal: `skipping ${skipped.join(", ")} narrows the reviewer set and needs the operator's decision for head ${now.head ?? "unknown"} leaving out ${now.items.join(", ") || "nothing"}: ${writers} with --selected naming every other required reviewer` };
+}
+function dispatchSkips(dispatch) {
+  const record = dispatch && typeof dispatch === "object" && !Array.isArray(dispatch) ? dispatch : undefined;
+  if (record === undefined || !Array.isArray(record.skipped))
+    return [];
+  const out = [];
+  for (const entry of record.skipped) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      continue;
+    const { reviewer, reason } = entry;
+    if (typeof reviewer === "string" && reviewer.trim() !== "" && typeof reason === "string" && reason.trim() !== "")
+      out.push({ reviewer: reviewer.trim(), reason: reason.trim() });
+  }
+  return out;
+}
 async function packageScopeFiles(packageDir) {
   try {
     const parsed = JSON.parse(await readFile23(path50.join(packageDir, "scope-files.json"), "utf8"));
@@ -29361,22 +29549,15 @@ async function packageScopeFiles(packageDir) {
   }
 }
 function projectRootOfPackage(packageDir) {
-  return path50.resolve(packageDir, "..", "..", "..");
-}
-
-// src/review/cost.ts
-function estimateTokens(text) {
-  return Math.ceil(text.length / 4);
+  const resolved = path50.resolve(packageDir);
+  const parts = resolved.split(path50.sep);
+  const at = parts.lastIndexOf(".metaproject");
+  if (at > 0)
+    return parts.slice(0, at).join(path50.sep) || path50.sep;
+  const found = resolveProjectRoot(resolved);
+  return found !== resolved ? found : path50.resolve(resolved, "..", "..", "..");
 }
 
-// src/review/jev-select.ts
-var CORE_MANDATORY_REVIEWER_IDS = [
-  "review-logic",
-  "review-architecture",
-  "review-security-code",
-  "review-highload"
-];
-
 // src/review/conform-state.ts
 init_redact();
 
@@ -29662,6 +29843,11 @@ function coveredSliceIds(dispatch, retry) {
       if (typeof id === "string")
         ids.add(id);
   }
+  if (Array.isArray(dispatch?.fixSlicesCovered)) {
+    for (const id of dispatch.fixSlicesCovered)
+      if (typeof id === "string")
+        ids.add(id);
+  }
   const reviewers = record(record(retry)?.reviewers);
   for (const entry of Object.values(reviewers ?? {})) {
     const covered = record(entry)?.covered;
@@ -29980,6 +30166,7 @@ function normalizeText(value) {
 init_fs();
 import { readFile as readFile25 } from "fs/promises";
 import path54 from "path";
+var SEVERITY_SET = new Set(["blocker", "major", "minor", "info"]);
 var KNOWN_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED", "PENDING"]);
 var PR_COMMENT_STATE_VERSION = 1;
 function prCommentsStatePath(cwd, repo, number) {

package/package.json

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

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

@@ -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). 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,27 +243,26 @@ 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.
+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.
+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.
+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:
+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
@@ -389,11 +387,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 +409,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 +428,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 +437,15 @@ 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.
+   - **`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,10 +532,8 @@ 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 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.
 
@@ -691,4 +685,7 @@ 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). |
+| "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.md

@@ -1125,12 +1125,12 @@ 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> }
 ```
 
@@ -1298,11 +1298,11 @@ 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>

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>"