feat: integrate review suite into epic execution

CHANGELOG.md

@@ -6,7 +6,9 @@ summary: Chronological history of repository and skill changes.
 
 ## 2026-07-19 — Epic workflow and review contract cleanup
 
+- feat: integrate repository-owned review into epic execution
 - feat: compose repository-owned code review
+  (556fea80b6970b97c31e819693f43c251b7b3796)
 - feat: add local code simplicity review
   (d6ed890f6924a2ae7ae4b04fa95072ee853c9b97)
 - feat: add whole-solution simplicity review

README.md

@@ -14,7 +14,8 @@ Current skills:
 - `skills/review-code-change` — orchestrate the repository-owned review lenses
   into one evidence-bound, deduplicated verdict
 - `skills/implement-epic-sequence` — execute GitHub or Linear epics through
-  dependency-aware implementation, review, merge, cleanup, and closeout
+  dependency-aware implementation, repository-owned review, remote gates, merge,
+  cleanup, and closeout
 - `skills/prepare-changesets` — decompose a large, review-ready branch into a
   deterministic chain of smaller, reviewable changesets and GitHub PRs
 - `skills/review-correctness` — find material behavioral, security,

skills/implement-epic-sequence/SKILL.md

@@ -42,6 +42,12 @@ Before changing code, resolve:
   deletion, and deployment;
 - named architecture, design, contract, or rollout documents.
 
+For a merge-inclusive run, verify before implementation that
+`review-code-change` is available and readable. It is the single local
+adversarial-review dependency. If it is unavailable, stop with an explicit
+missing-dependency result; do not substitute a third-party skill, a generic
+reviewer, or an unreviewed merge path.
+
 Unless the user or repository contract states otherwise, apply this authority
 matrix:
 
@@ -188,39 +194,27 @@ same files.
 
 Follow `references/review-and-merge-gates.md`.
 
-- Implement directly in the primary execution context.
-- After local validation, require one fresh, read-only adversarial
-  `code-review-pro` pass in a separate review-only subagent or equivalent
-  isolated context unless the user explicitly waives it or independent review
-  tooling is unavailable.
-- Use a fresh or minimally inherited context. Give the reviewer only raw task
-  artifacts: repository instructions, the live ticket, named specifications, the
-  complete `base...HEAD` diff for the captured head/base SHA pair, and
-  validation evidence. Do not provide the implementation transcript, intended
-  answer, prior conclusions, or suspected findings.
-- Before review, require every intended ticket change to be committed and the
-  implementation worktree to be clean. If unrelated user artifacts prevent a
-  clean state, classify and preserve them and prove they are irrelevant to the
-  candidate.
-- Before delegation, capture HEAD, commit history, and tracked, untracked, and
-  ignored worktree state. After review, verify that all remain unchanged. Treat
-  any reviewer mutation as an integrity failure and inspect it without
-  discarding user work.
-- Review correctness, acceptance criteria, regressions, failure paths, security,
-  authorization, architecture, public surface area, tests, documentation, and
-  scope.
-- Apply only material, tractable, in-scope findings.
-- Re-run affected and required validation after fixes.
-- Run a fresh pass after material fixes and invalidate prior remote review
-  signals after every head or base change.
-- Use at most three adversarial passes by default. If the final pass still has a
-  material finding, do not merge; report the unresolved finding and request
-  direction.
-
-Do not silently count an unavailable independent reviewer as a passed gate.
-Record the limitation, perform a fresh adversarial self-review, and proceed only
-when repository policy does not require independence and the user has accepted
-or already authorized the unavailable-tool fallback.
+- Implement and apply fixes only in the primary execution context.
+- Commit and validate a clean candidate, then invoke `review-code-change` in a
+  fresh or minimally inherited read-only context with raw ticket, repository,
+  diff, validation, and worktree artifacts.
+- Exclude the implementation transcript, intended solution, prior conclusions,
+  and suspected findings.
+- Consume the suite's validated aggregate verdict, findings, dispositions,
+  limitations, and next action without reproducing its lens rubrics or ordering.
+- Apply only blocking and strong-recommendation findings that are material,
+  tractable, and ticket-scoped. Preserve deferred findings without expanding the
+  PR.
+- After fixes, run affected and required validation, commit, push, build a new
+  head-bound evidence packet, and invoke the suite according to its re-review
+  instructions.
+- Use at most three full fix/re-review cycles by default. Keep the PR open and
+  report unresolved material findings after the final cycle.
+
+Treat a missing dependency, malformed result, `blocked` verdict, reviewer
+mutation, or unavailable required evidence as a failed local review gate. The
+review suite remains read-only; this workflow owns every code and GitHub
+mutation.
 
 Create a follow-up ticket only when ticket management is authorized and the gap
 is real, evidenced, and intentionally outside the current PR. Otherwise report a
@@ -235,18 +229,21 @@ Follow both bundled gate references. Merge only when:
   irrelevant;
 - required local validation passed;
 - required CI passed or the repository explicitly has no such checks;
-- every applicable required adversarial, human, and connector review has a clean
-  or approving verdict explicitly tied to the exact current head and base SHA
-  pair;
+- the repository-owned local review has a clean result bound to the current head
+  and an explicit disposition for any later base drift;
+- every applicable required human and connector review has a current approving
+  or clean verdict under repository policy;
 - no undispositioned actionable conversation comment, formal review, connector
   feedback, or review thread remains;
 - the PR still matches its ticket and base;
 - no other PR superseded it.
 
-Treat every head change, including a push, rebase, conflict resolution, or
-update-branch operation, and every base-branch advance as invalidating older
-merge-candidate evidence. Rebuild and revalidate the current head/base candidate
-before merge.
+Treat every head-changing edit, push, rebase, conflict resolution, or
+update-branch operation as invalidating head-bound evidence. When only the base
+advances, inspect the current merge candidate and record why each gate was
+retained or invalidated. Retain evidence only when the effective diff and
+resulting tree are unchanged, no conflict or relevant overlap exists, and
+repository policy permits retention. Otherwise rerun every affected gate.
 
 After merge, verify the remote state and base-branch result before cleanup.
 

skills/implement-epic-sequence/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Implement Epic Sequence"
-  short_description: "Execute epics safely from ticket to merge"
-  default_prompt: "Use $implement-epic-sequence to implement the remaining ready children of this epic through review, merge, cleanup, and closeout."
+  short_description: "Execute epics through safe reviewed merges"
+  default_prompt: "Use $implement-epic-sequence to implement the remaining ready children of this epic through repository-owned review, merge, cleanup, and closeout."

skills/implement-epic-sequence/evals/cases.json

@@ -0,0 +1,150 @@
+[
+  {
+    "id": "correctness-fix-and-rereview",
+    "request": "Implement and merge the ready child after all required gates pass.",
+    "ticket": {
+      "goal": "Stop retry scheduling at the configured maximum.",
+      "acceptance_criteria": ["No retry is scheduled when retry_count equals max_retries."],
+      "non_goals": ["Redesign the queue."],
+      "preserved_behaviors": ["Retries below the maximum still schedule normally."]
+    },
+    "candidate": {
+      "head_sha": "1111111111111111111111111111111111111111",
+      "comparison_base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "diff_summary": "The retry branch still schedules when retry_count equals max_retries.",
+      "validation": ["focused passed", "full passed"]
+    },
+    "review_dependency_available": true,
+    "suite_result": {
+      "schema_version": "1.0", "lens": "aggregate",
+      "candidate": {"head_sha": "1111111111111111111111111111111111111111", "comparison_base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},
+      "verdict": "changes_required",
+      "findings": [{
+        "id": "correctness.retry-bound", "lens": "correctness", "severity": "blocking", "confidence": "high",
+        "rule": "Retries must stop at max_retries.",
+        "evidence": [{"location": "worker retry branch", "detail": "Equality still reaches schedule_retry."}],
+        "concern": "The maximum does not stop retry scheduling.", "impact": "Work can exceed the configured retry budget.",
+        "proposed_change": "Return before scheduling when retry_count is at least max_retries.", "expected_effect": "Bound retries at the configured maximum."
+      }],
+      "blocking_reasons": [],
+      "next_action": "Apply the correctness fix, validate, commit and push a new head, then rerun correctness and affected downstream lenses."
+    },
+    "followup_suite_result": {
+      "schema_version": "1.0", "lens": "aggregate",
+      "candidate": {"head_sha": "1212121212121212121212121212121212121212", "comparison_base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},
+      "verdict": "clean", "findings": [], "blocking_reasons": [],
+      "next_action": "No further local review action is required."
+    },
+    "remote_policy": {"ci": "passed", "human": "not_required", "connector": "not_configured"}
+  },
+  {
+    "id": "solution-redesign-early-exit",
+    "request": "Implement and merge the ready child after all required gates pass.",
+    "ticket": {
+      "goal": "Persist one local audit record.",
+      "acceptance_criteria": ["One local record is written."],
+      "non_goals": ["Support remote storage providers."],
+      "preserved_behaviors": ["Existing local writes remain atomic."]
+    },
+    "candidate": {
+      "head_sha": "2222222222222222222222222222222222222222",
+      "comparison_base_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "diff_summary": "Adds a provider registry, dispatch layer, and remote-provider configuration for one local write.",
+      "validation": ["focused passed", "full passed"]
+    },
+    "review_dependency_available": true,
+    "suite_result": {
+      "schema_version": "1.0", "lens": "aggregate",
+      "candidate": {"head_sha": "2222222222222222222222222222222222222222", "comparison_base_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"},
+      "verdict": "changes_required",
+      "findings": [{
+        "id": "solution-simplicity.remove-provider-platform", "lens": "solution_simplicity", "severity": "blocking", "confidence": "high",
+        "rule": "Remote providers are outside scope.",
+        "evidence": [{"location": "candidate diff", "detail": "Provider configuration and dispatch exist for one local write."}],
+        "concern": "The implementation strategy exceeds the ticket.", "impact": "It adds unsupported ownership and failure modes.",
+        "proposed_change": "Replace the provider platform with one direct local write.", "expected_effect": "Remove provider configuration, dispatch, and remote failure modes."
+      }],
+      "blocking_reasons": [],
+      "next_action": "Redesign the implementation, capture a new head, and restart the full review sequence."
+    },
+    "remote_policy": {"ci": "required", "human": "not_required", "connector": "not_configured"}
+  },
+  {
+    "id": "code-simplicity-targeted-correctness",
+    "request": "Implement and merge the ready child after all required gates pass.",
+    "ticket": {
+      "goal": "Authorize two new admin actions.",
+      "acceptance_criteria": ["Only active admins may invoke either action."],
+      "non_goals": ["Create another authorization framework."],
+      "preserved_behaviors": ["The shared active-admin policy remains authoritative."]
+    },
+    "candidate": {
+      "head_sha": "3333333333333333333333333333333333333333",
+      "comparison_base_sha": "cccccccccccccccccccccccccccccccccccccccc",
+      "diff_summary": "Both actions repeat the existing active-admin policy instead of calling its helper.",
+      "validation": ["focused passed", "full passed"]
+    },
+    "review_dependency_available": true,
+    "suite_result": {
+      "schema_version": "1.0", "lens": "aggregate",
+      "candidate": {"head_sha": "3333333333333333333333333333333333333333", "comparison_base_sha": "cccccccccccccccccccccccccccccccccccccccc"},
+      "verdict": "changes_required",
+      "findings": [{
+        "id": "code-simplicity.reuse-admin-policy", "lens": "code_simplicity", "severity": "strong_recommendation", "confidence": "high",
+        "rule": "Reuse the repository authorization helper.",
+        "evidence": [{"location": "two new actions", "detail": "Both repeat require_active_admin logic."}],
+        "concern": "Authorization policy has three owners.", "impact": "The repeated checks can drift.",
+        "proposed_change": "Call require_active_admin from each action.", "expected_effect": "Restore one authorization-policy owner."
+      }],
+      "blocking_reasons": [],
+      "next_action": "Apply the code-simplicity fix on a new head, rerun code simplicity, then run targeted correctness."
+    },
+    "remote_policy": {"ci": "required", "human": "not_required", "connector": "not_configured"}
+  },
+  {
+    "id": "unrelated-base-drift-retained",
+    "request": "Merge the clean reviewed child when all current gates pass.",
+    "ticket": {"goal": "Add a parser boundary test.", "acceptance_criteria": ["The boundary is covered."], "non_goals": [], "preserved_behaviors": ["Parser behavior is unchanged."]},
+    "candidate": {
+      "head_sha": "4444444444444444444444444444444444444444",
+      "comparison_base_sha": "dddddddddddddddddddddddddddddddddddddddd",
+      "diff_summary": "Adds one parser test.", "validation": ["focused passed", "full passed"]
+    },
+    "review_dependency_available": true,
+    "suite_result": {"schema_version": "1.0", "lens": "aggregate", "candidate": {"head_sha": "4444444444444444444444444444444444444444", "comparison_base_sha": "dddddddddddddddddddddddddddddddddddddddd"}, "verdict": "clean", "findings": [], "blocking_reasons": []},
+    "base_drift": {"new_base_sha": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "effective_diff_changed": false, "resulting_tree_changed": false, "conflict": false, "relevant_overlap": false, "repository_requires_reset": false},
+    "remote_policy": {"ci": "passed", "human": "not_required", "connector": "not_configured"}
+  },
+  {
+    "id": "relevant-base-drift-restarts-gates",
+    "request": "Merge the clean reviewed child when all current gates pass.",
+    "ticket": {"goal": "Change retry classification.", "acceptance_criteria": ["Permanent errors do not retry."], "non_goals": [], "preserved_behaviors": ["Transient errors retry."]},
+    "candidate": {
+      "head_sha": "5555555555555555555555555555555555555555",
+      "comparison_base_sha": "ffffffffffffffffffffffffffffffffffffffff",
+      "diff_summary": "Changes the retry classifier.", "validation": ["focused passed", "full passed"]
+    },
+    "review_dependency_available": true,
+    "suite_result": {"schema_version": "1.0", "lens": "aggregate", "candidate": {"head_sha": "5555555555555555555555555555555555555555", "comparison_base_sha": "ffffffffffffffffffffffffffffffffffffffff"}, "verdict": "clean", "findings": [], "blocking_reasons": []},
+    "base_drift": {"new_base_sha": "abababababababababababababababababababab", "effective_diff_changed": true, "resulting_tree_changed": true, "conflict": true, "relevant_overlap": true, "repository_requires_reset": false},
+    "remote_policy": {"ci": "required", "human": "required", "connector": "required"}
+  },
+  {
+    "id": "missing-review-dependency",
+    "request": "Implement and merge the ready child after all required gates pass.",
+    "ticket": {"goal": "Add one command.", "acceptance_criteria": ["The command runs."], "non_goals": [], "preserved_behaviors": []},
+    "candidate": {"head_sha": "6666666666666666666666666666666666666666", "comparison_base_sha": "1212121212121212121212121212121212121212", "diff_summary": "Adds one command.", "validation": ["focused passed", "full passed"]},
+    "review_dependency_available": false,
+    "suite_result": {"schema_version": "1.0", "lens": "aggregate", "candidate": {"head_sha": "6666666666666666666666666666666666666666", "comparison_base_sha": "1212121212121212121212121212121212121212"}, "verdict": "blocked", "findings": [], "blocking_reasons": ["Required review skill review-code-change is unavailable."], "next_action": "Make review-code-change available before continuing the merge-inclusive run."},
+    "remote_policy": {"ci": "required", "human": "not_required", "connector": "not_configured"}
+  },
+  {
+    "id": "clean-local-review-remote-policy-pending",
+    "request": "Merge the clean reviewed child when all current gates pass.",
+    "ticket": {"goal": "Expose one read-only status field.", "acceptance_criteria": ["The field is returned."], "non_goals": [], "preserved_behaviors": ["Existing fields are unchanged."]},
+    "candidate": {"head_sha": "7777777777777777777777777777777777777777", "comparison_base_sha": "3434343434343434343434343434343434343434", "diff_summary": "Adds one read-only field and test.", "validation": ["focused passed", "full passed"]},
+    "review_dependency_available": true,
+    "suite_result": {"schema_version": "1.0", "lens": "aggregate", "candidate": {"head_sha": "7777777777777777777777777777777777777777", "comparison_base_sha": "3434343434343434343434343434343434343434"}, "verdict": "clean", "findings": [], "blocking_reasons": []},
+    "remote_policy": {"ci": "passed", "human": "required_pending", "connector": "required_pending", "unresolved_threads": 0}
+  }
+]