From 4303d6eecd8d3e5717823968ee565fd060365bf0 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Mon, 31 Aug 2026 23:19:44 +0900 Subject: [PATCH] fix: enforce review finding convergence --- .agents/skills/recipe-front-review/SKILL.md | 2 +- .agents/skills/recipe-review/SKILL.md | 2 +- .agents/skills/reviewee-judgment/SKILL.md | 11 +++++++---- .../skills/subagents-orchestration-guide/SKILL.md | 2 +- .../references/review-resolution.md | 14 ++------------ package.json | 2 +- 6 files changed, 13 insertions(+), 20 deletions(-) diff --git a/.agents/skills/recipe-front-review/SKILL.md b/.agents/skills/recipe-front-review/SKILL.md index 2ccc92b..ff35957 100644 --- a/.agents/skills/recipe-front-review/SKILL.md +++ b/.agents/skills/recipe-front-review/SKILL.md @@ -77,7 +77,7 @@ Proposed corrections: d) Design-side update ``` -Apply Review Resolution before presenting results. Recommend a correction route only for findings classified `apply` or `user_decision_required`: +Apply Review Resolution before presenting results. Recommend a correction route only for findings classified `apply` or `user decision required`: - Use `d` when implementation intent matches the requirement but the Design Doc is stale or too narrow. - Use `c` when the required correction changes implementation. diff --git a/.agents/skills/recipe-review/SKILL.md b/.agents/skills/recipe-review/SKILL.md index f2d7576..f4323d1 100644 --- a/.agents/skills/recipe-review/SKILL.md +++ b/.agents/skills/recipe-review/SKILL.md @@ -80,7 +80,7 @@ Proposed corrections: d) Design-side update ``` -Apply Review Resolution before presenting results. Recommend a correction route only for findings classified `apply` or `user_decision_required`: +Apply Review Resolution before presenting results. Recommend a correction route only for findings classified `apply` or `user decision required`: - Use `d` when implementation intent matches the requirement but the Design Doc is stale or too narrow. - Use `c` when the required correction changes implementation. diff --git a/.agents/skills/reviewee-judgment/SKILL.md b/.agents/skills/reviewee-judgment/SKILL.md index eed000d..0fa5f2c 100644 --- a/.agents/skills/reviewee-judgment/SKILL.md +++ b/.agents/skills/reviewee-judgment/SKILL.md @@ -64,10 +64,10 @@ Evaluate candidates through these gates in order. A later gate cannot compensate Establish causal sufficiency before cost can favor a response. A required correction remains required regardless of cost; cost ranks its sufficient responses. Once a discretionary response passes the causal, durable-quality, and verification gates, low cost favors applying it when its observable benefit is positive and its maintenance, verification, and execution risk remain immaterial. When the best structural response lacks adequate verification, retain it as the preferred target, state the exact proof needed to make it safe, and explain the debt carried by any executable interim response. -These gates constrain the decision, not the route used to reach it. They require no fixed number of alternatives, separate decision artifact, or edit for every finding. - ## Resolution Method +Before starting, add steps 1–5 to `update_plan` in order; add step 6 only when execution is authorized. Complete each step before starting the next. + ### 1. Normalize the Findings Separate these elements before accepting any proposed fix, consolidating repeated evidence across findings: @@ -102,6 +102,7 @@ Before selecting a response, test it against applicable causal alternatives that The resulting comparison must make clear: +- whether the reviewed change or mechanism is necessary at all; - which cause it resolves; - which concepts, responsibilities, or constraints it adds or removes; - what same-problem instances remain; @@ -120,6 +121,8 @@ Assign one disposition to each problem group: - **evidence required**: a material unknown could change finding validity, ownership, response selection, or verification. Pause changes for that problem group, continue independent groups, and report the exact evidence needed, its source when known, the decision it controls, and the condition for resuming; - **user decision required**: the preferred response changes an approved outcome, architecture, compatibility promise, or scope boundary. +Return `evidence required` and `user decision required` to the skill caller. The caller resolves them when it owns the required evidence or decision and otherwise routes them to the responsible authority. + If an interim patch is the only safely executable response, label it as interim, describe the retained structural problem, and present the enabling work for the preferred response. The user decides whether that tradeoff is worth taking. ### 6. Execute and Verify @@ -136,7 +139,7 @@ Findings grouped: - : confirmed | unsupported | unresolved Evidence: observed | inferred | unknown Cause and owner: -Decision-changing alternatives considered: +Reviewed change or mechanism necessity and decision-changing alternatives considered: Recommendation and disposition: Authority: recommend only | execute selected response Why it wins in the decision order: @@ -145,7 +148,7 @@ Required evidence and resume condition, if any: User decision, if any: ``` -Keep the report proportional. Omit fields that have no material content, but always preserve the problem/fix separation, the causal owner, the alternatives that could change the decision, and any user-owned tradeoff. +Keep the report proportional. Omit fields that have no material content, but always preserve the problem/fix separation, the causal owner, whether the reviewed change or mechanism is necessary, the alternatives that could change the decision, and any user-owned tradeoff. ## Completion Check diff --git a/.agents/skills/subagents-orchestration-guide/SKILL.md b/.agents/skills/subagents-orchestration-guide/SKILL.md index 5c79c8e..1c5d28d 100644 --- a/.agents/skills/subagents-orchestration-guide/SKILL.md +++ b/.agents/skills/subagents-orchestration-guide/SKILL.md @@ -120,7 +120,7 @@ Use agent statuses as routing signals, not as a parser contract. Interpret the r ### Review Resolution -Use [references/review-resolution.md](references/review-resolution.md) for reviewer findings and verifier discrepancies. The orchestrator decides which findings to apply, decline, or return for a genuine user-owned decision; authors and downstream reviewers receive only resolved evidence relevant to their action. +The orchestrator loads and applies `reviewee-judgment` through disposition selection before reviewer findings or verifier discrepancies generate author or implementation work. Use [references/review-resolution.md](references/review-resolution.md) to delegate `apply` dispositions and route reruns and handoff. Resolve returned evidence or decision requests through Orchestrator Escalation Resolution. ### Orchestrator Escalation Resolution [MANDATORY] diff --git a/.agents/skills/subagents-orchestration-guide/references/review-resolution.md b/.agents/skills/subagents-orchestration-guide/references/review-resolution.md index 9ca1e57..0f2337c 100644 --- a/.agents/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/.agents/skills/subagents-orchestration-guide/references/review-resolution.md @@ -4,15 +4,7 @@ Use this procedure for reviewer findings and verifier discrepancies before they ## 1. Assess Findings -The orchestrator classifies each finding or discrepancy from its cited evidence. For an unsupported or overbroad document claim, first test whether removing or narrowing the claim preserves the confirmed requirements and accepted decisions; use that reduction instead of creating implementation work. - -| Decision | Use when | -|---|---| -| `apply` | The current artifact or implementation contradicts an approved requirement, selected ADR decision, repository rule, or observed contract; would remain incorrect, non-executable, or non-verifiable; or commits downstream work to an unsupported addition that can be removed or narrowed without changing confirmed requirements. | -| `decline` | The finding adds scope, reverses a recorded exclusion, requests optional hardening or external operation, duplicates existing proof, or costs more than its observable effect justifies. | -| `user_decision_required` | Resolution changes the product outcome, a confirmed requirement or exclusion, or a major approved design decision. | - -For `apply`, pass the complete finding or discrepancy unchanged with its disposition. For `decline`, give the originating reviewer or verifier the governing source or observed evidence and the concrete scope mismatch or cost-to-effect mismatch. Keep the dispositions in the active workflow context as the complete resolution record. +Apply `reviewee-judgment` to the current findings and keep its problem groups, dispositions, reasons, and evidence in the active workflow context. ## 2. Revise and Reconsider @@ -24,9 +16,7 @@ The reviewer withdraws a declined finding when the reason is consistent with gov Each rerun applies the reviewer's or verifier's stated rerun boundary to the current artifact or implementation and may report newly observed evidence-backed findings within that boundary. The orchestrator reassesses the current findings through Section 1. -Continue revision and reconsideration while an applied correction or new evidence materially changes the artifact, implementation, evidence, or finding disposition. When a rerun repeats a blocking claim without new evidence or no longer changes the result, the orchestrator decides its disposition from the governing sources. Route a remaining unusable artifact or implementation through Orchestrator Escalation Resolution instead of starting the same Review Resolution again. - -Return to the user only for `user_decision_required`, unavailable user-held authority, or an unauthorized irreversible action. Preserve completed work and unaffected findings when that happens. +Continue revision and reconsideration while an applied correction or new evidence materially changes the artifact, implementation, evidence, or finding disposition. When a rerun repeats a blocking claim without new evidence or no longer changes the result, the orchestrator reassesses the remaining claim through Section 1. Route a remaining unusable artifact or implementation through Orchestrator Escalation Resolution instead of starting the same Review Resolution again. ## Handoff diff --git a/package.json b/package.json index 1e91eaf..974510b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "codex-workflows", - "version": "1.3.1", + "version": "1.3.2", "description": "Codex CLI workflows that keep larger software changes within the approved scope, from planning through review", "license": "MIT", "author": "Shinsuke Kagawa",