codex-orchestrator 2.0.1 → 2.0.3

package/internal-workflow/docs/agents/confidence-rubric.md

@@ -0,0 +1,65 @@
+# Confidence Rubric
+
+Use this rubric for coding skills that report findings, diagnose root causes, review specs, or decide whether an auto-fix is safe.
+
+Do not use fake numeric precision unless a skill has a concrete scoring reason. Prefer `high`, `medium`, and `low` with evidence.
+
+## High Confidence
+
+High confidence means the finding or diagnosis has direct evidence.
+
+Requires:
+
+- a concrete trigger path, code path, failing signal, or tool output
+- a clear explanation of why existing guards do not prevent the issue
+- no unresolved assumption that changes the conclusion
+
+Allowed actions:
+
+- report as a finding
+- block execution when the issue is safety-critical or spec-critical
+- auto-fix only when the fix is narrow, low-risk, local-patterned, and verifiable
+
+## Medium Confidence
+
+Medium confidence means the issue is likely but one explicit assumption remains.
+
+Requires:
+
+- strong local evidence
+- exactly what assumption remains
+- what evidence would promote or demote the finding
+
+Allowed actions:
+
+- report as a likely issue, risk, or execution concern
+- ask a targeted question when the unresolved assumption changes the fix
+- do not auto-fix unless new evidence raises confidence to high
+
+## Low Confidence
+
+Low confidence means the concern is plausible but not proven.
+
+Requires:
+
+- a clear label as uncertainty
+- the missing evidence or verification gap
+
+Allowed actions:
+
+- present as a question, risk, or verification gap
+- do not report as a proven bug
+- do not auto-fix
+
+## Auto-Fix Gate
+
+Auto-fix is allowed only when all are true:
+
+- confidence is high
+- root cause is clear
+- fix is narrow and low-risk
+- fix matches local project patterns
+- verification is available, or the edit is syntax-checkable and obviously safe
+- the change does not require a product decision
+
+If any condition is missing, report the issue with evidence and stop before editing.

package/internal-workflow/docs/agents/contract-test-ledger.md

@@ -0,0 +1,60 @@
+# Contract Test Ledger
+
+Use this shared ledger for behavior-changing work where a passing happy-path test could still miss a contract defect. The ledger turns review-class risks into testable obligations before implementation.
+
+## When Required
+
+Create or update a contract test ledger when the task changes any of these:
+
+- API, DTO, schema, serialization, persistence, or externally visible response shape
+- ordering, lifecycle events, state transitions, retries, idempotency, timeout, cancellation, or background jobs
+- cache keys, invalidation, state merge precedence, fallback behavior, profile/global/mobile overrides, defaults, or feature flags
+- evidence, trace, snapshot, audit, summary, aggregation, score, winner, or generated artifacts
+- shared behavior read by multiple callers, tenants, users, groups, children, or projections
+
+For narrow UI copy, docs-only, formatting, tests-only, or isolated styling changes, the ledger is not required.
+
+## Required Shape
+
+Keep the ledger compact. Use one row per invariant:
+
+```markdown
+## Contract Test Ledger
+
+| Invariant | Risk It Prevents | First Test / Proof | Status |
+| --- | --- | --- | --- |
+| <observable rule> | <real failure mode> | <exact test name/command or manual proof> | planned / red / green / blocked |
+```
+
+Rules:
+
+- The invariant must be observable through the public interface or the same seam real callers use.
+- The risk must name the concrete bug class, not a vague "edge case".
+- The first test/proof must fail before the fix unless the ledger records why a RED signal is impossible.
+- `blocked` requires the missing seam, fixture, service, or decision that prevents proof.
+- Keep the ledger current as implementation proceeds; do not backfill it only at the end.
+
+## Invariant Prompts
+
+Ask the relevant subset before the first RED test:
+
+- **Ordering:** What must happen before/after terminal events, snapshots, persistence writes, notifications, or cleanup?
+- **Precedence:** Which source wins among user input, profile, mobile, global, server, cache, AI, fallback, default, `null`, `false`, `0`, and empty objects?
+- **Threading:** Does each new field survive construction, normalization, cloning, retry, persistence reload, serialization, and every visible consumer?
+- **Runtime contract:** Do validation, internal types, persistence schema, API response, and consumers agree on names, units, nullability, enum values, and date/object formats?
+- **Retry/idempotency:** What changes on retry, and which snapshots, counters, streams, timestamps, writes, or side effects must be rebuilt instead of reused?
+- **Determinism:** When sort keys, timestamps, scores, priorities, or winners tie, what stable tie-breaker makes output repeatable?
+- **Evidence:** Which trace, audit, snapshot, Fresh-Context, summary, or generated artifact proves the behavior actually happened?
+- **Partial failure:** If a dependency times out, throws, returns stale data, or fails after a side effect, what durable state remains and who repairs it?
+- **Scope/cardinality:** Is data global, per-tenant, per-group, per-child, per-step, or per-item, and can one top-level field collapse multiple meaningful results?
+
+## Review Feedback Loop
+
+When code review finds a real contract defect, add or update one ledger row before fixing it:
+
+- `Invariant`: the rule the implementation violated
+- `Risk It Prevents`: the observed review finding
+- `First Test / Proof`: the regression test or proof that would have caught it
+- `Status`: `red` before the fix, then `green` after verification
+
+If no correct public seam exists for the regression test, record that as `blocked` and name the architecture/testability gap. Do not replace a missing seam with an implementation-detail test unless the task explicitly approves that tradeoff.

package/internal-workflow/docs/agents/implementation-review-loop.md

@@ -0,0 +1,302 @@
+# Implementation Review Loop
+
+Use this policy for every approved implementation-spec execution. This
+target-specific Module owns implementation authority, durable Review State,
+checkpoint/final topology, validation reuse, gate ordering, audit epochs, and
+implementation outcome mapping. It applies
+[`review-protocol.md`](review-protocol.md) for context transfer, Full/Closure
+mechanics, defect lifecycle, no-progress, and the common result envelope.
+`spec-implementer`, `cleanup-review`, and `code-review` are callers or Adapters;
+they must not reproduce either Module. Deterministic tickets-orchestrator work
+using its issue as authority remains outside this Module and uses direct TDD
+plus repo review gates.
+
+This policy does not replace tests, architecture checks, smoke tests, or Git
+checkpoints. Those proofs remain independent evidence.
+
+## Interface
+
+Conceptually, the executor uses:
+
+```text
+review_implementation(
+  authority_artifact_kind,
+  authority_artifact_path,
+  review_profile,
+  current_revision,
+  checkpoint,
+  review_focus,
+  defect_ledger
+) -> review_outcome
+```
+
+The outcome records:
+
+- `outcome`: `Approved | Blocked | Waived`
+- `authority_artifact_kind`: `approved-spec`
+- `authority_artifact_path`: the sole artifact that stores review state
+- `review_profile`: `simple | medium | high`
+- completed review passes and pending launches
+- review mode, reviewer/session identity, target revision, and assigned lenses
+- stable defect IDs and their current status
+- logical skill activations and their open/closed state
+- mandatory final coverage still required
+
+## Authority
+
+An approved implementation spec stores the sole `## Implementation Review
+State`. Architecture RFCs, product PRDs, tickets, `ready-for-approval`
+artifacts, inferred approval, and ordinary direct-ticket waves are ineligible.
+Persist `authority_artifact_kind` and `authority_artifact_path` and never create
+a second ledger in an upstream artifact, caller, ticket, or Adapter.
+
+Lifecycle and proof updates to the selected artifact do not change its approved
+status or substantive design. A substantive authority change requires the
+normal artifact revision/review path before implementation continues.
+
+## Profile And Review Shape
+
+Prefer the selected authority artifact's `review_profile`. If it is absent, use the same
+evidence-based classification and hard escalators as
+[`artifact-review-loop.md`](artifact-review-loop.md). Actual implementation
+evidence may raise the profile but must not lower it.
+
+Review profile selects mandatory lenses and independence. Protocol pass-count
+semantics apply; parallel reviewer results remain separate passes even when they
+reduce wall-clock time.
+
+Select the reviewer role from the profile: `simple` uses `reviewer_fast`,
+`medium` uses `reviewer_standard`, and `high` uses `reviewer_deep`. Root always
+launches reviewer children; it never performs an implementation review inline.
+An Adapter runs inline only inside its already assigned reviewer child.
+
+A reviewer that fails before returning a usable result is recorded as failed
+and closed, not as completed coverage. Escalation preserves completed coverage
+and the stable Defect Ledger. A user pause, context compaction, slice commit,
+worker replacement, or new turn also preserves them; none restarts the review
+topology automatically.
+
+Stop early when mandatory coverage and protocol clear-state requirements hold.
+
+## Review Planning
+
+Before the first implementation reviewer, root creates a short Review Plan:
+
+- current profile and required independent lenses
+- only stable intermediate checkpoints and their required lenses; move an unstable checkpoint to final coverage when later slices touch the same files, owners, or contracts
+- any separate cleanup requirement, which must name a concrete evidenced reason that cannot fit the final spec/standards lens
+- final code-review lenses and minimum independent coverage
+- reviewer lineages that own affected-lens Closure
+
+Create one durable activation record for each logical skill invocation. Record
+`activation_id`, skill, owner, opened/closed state, and resume rule. Review Full
+and lineage-preserving Closure passes stay inside that review skill's activation;
+TDD repair cycles stay inside the active TDD activation. Cleanup, code review,
+TDD, and debugger activations never share an ID, and a continuation resumes an
+ID only for the same skill and authorized flow.
+
+## Durable Review State
+
+Do not create durable review state during implementation preflight. Immediately
+before the first actual reviewer launch, persist the short Review Plan and
+pending launch in the selected authority artifact under
+`## Implementation Review State`. From that point onward this is the execution
+ledger for review state; do not keep the authoritative history only in chat
+context or a subagent summary.
+
+Record at least:
+
+- profile, completed pass count, and required coverage still outstanding
+- current checkpoint/gate, review timing baseline, gate-local consecutive
+  Closure-wave count, and latest Closure wave ID
+- planned mandatory final reviews and their lenses
+- authority artifact kind/path and logical skill activation records
+- each lineage ID, origin Full session, active session generation, Closure count,
+  rotation reason, live/timeout state, and `conclude_requested_at`
+- any convergence audit epoch: trigger, triggering pass/wave/revision,
+  completion, dispositions, selected sessions, resume reason, and pass/wave/time
+  baselines used for its next rearm
+- pending reviewer launches with launch ID, mode, lineage/session identity,
+  activation ID, target revision, checkpoint/gate, Closure wave ID when
+  applicable, assigned lenses, and start timestamp
+- every completed review's mode, lineage/session identity, target revision,
+  checkpoint/gate, Closure wave ID, assigned lenses, start/end timestamps, and
+  outcome
+- the stable Defect Ledger with transition history, reopen count, fixed revision,
+  verifying review, and any explicit risk acceptance
+
+Write a pending launch before starting its reviewer. After the launch returns,
+replace the pending record with either its usable completed result or a failed,
+closed session record; only a usable result increments `review_passes`. A context
+compaction, new turn, resumed task, or different root agent must reconcile every
+pending launch with its recorded session before starting a replacement.
+
+Update this section after each launch, usable reviewer result, repair batch,
+closure, waiver, acceptance, reopen, or terminal outcome. A resumed executor
+reconstructs accounting and lifecycle history from this persisted state. If the
+state is missing or internally inconsistent after reviews began, return
+`Blocked` until it is reconciled from available thread/session evidence; never
+assume zero completed passes or silently replace an in-flight reviewer.
+
+Plan mandatory final coverage before launching an intermediate review. Launch a
+checkpoint only when its target is settled and later slices will not invalidate
+the reviewed files, owners, or contracts. Otherwise move its lenses to final
+coverage. Do not replace a required final lens with another fresh checkpoint
+reviewer or a repeat broad audit.
+
+The default shapes are:
+
+- `simple`: validation only when policy does not require review; otherwise one
+  final Full review and affected-lens Closure only after repairs.
+- `medium`: an explicit intermediate checkpoint may provide one required lens;
+  the final integrator covers every remaining lens, includes bounded cleanup in
+  spec/standards, and verifies its defects without a separate cleanup pass.
+- `high`: use parallel independent tracks only for disjoint mandatory lenses;
+  the spec/standards track includes bounded cleanup, and affected-lens Closure
+  follows only after consolidated repairs. There is no separate cleanup pass by
+  default.
+
+`code-review` uses one final reviewer covering both correctness and
+spec/standards for `simple` and `medium`. For `high`, it uses two disjoint final
+tracks unless earlier independent coverage already covered both axes and one
+fresh final integrator receives their compact handoffs.
+
+Before launching a fresh final reviewer, reconcile coverage on the settled
+revision. If the latest usable Full or Closure covered every mandatory final
+lens and left no open defect, mark final review complete and stop. Count cleanup
+Closure only for the lenses explicitly assigned in the Review Plan; a
+`cleanup-only` pass does not satisfy correctness or spec/standards coverage.
+
+## Review Capsule
+
+Use the protocol capsule with these implementation fields:
+
+- the unanswered implementation question and any prior coverage it invalidates
+- authority artifact kind/path, profile, current revision, checkpoint, and exact diff command
+- changed paths and assigned `Review Focus` lenses
+- source-of-truth docs and relevant Contract Test Ledger rows
+- compact validation results and known verification gaps
+
+For Closure, map changed paths and tests into the protocol Revision Map.
+
+## Review Modes
+
+Use protocol Full and Closure without redefining them. Implementation Closure
+maps `affected_targets` to paths, tests, runtime contracts, and Review Focus
+lenses. An already planned Full reviewer may verify a repair when its assigned
+lenses cover it.
+
+## Defect Lifecycle
+
+Use the canonical protocol ledger and lifecycle without local aliases.
+
+Implementation proof-only gaps may use `planned-final-verification` only when an
+already scheduled code-review lens owns the proof; they remain open until
+independently verified and never re-enter cleanup. Artifact proof-contract gaps
+reopen artifact review. A pre-existing adjacent issue is non-blocking only as an
+`improvement` with `follow-up-improvement`.
+
+## Validation Evidence Reuse
+
+Persist command/config identity, failure signature, target revision and changed
+path/contract impact basis, secret-safe environment fingerprint, transitive
+ownership/contract impact, and result. Reuse a known unrelated suite failure
+only when every field matches; unknown environment or transitive impact fails
+closed. Focused tests and every required check for a repair always rerun.
+
+## Gate Ordering
+
+1. Implement the slice and pass its tests/exit gate.
+2. At an explicit intermediate checkpoint, run the required targeted
+   `code-review` directly under the Review Plan.
+3. Repair one consolidated finding batch and use protocol Closure for the
+   affected lineages. An already planned Full reviewer may verify the repair when
+   its assigned lenses cover it.
+   At one gate, collect the usable results from all already-launched reviewers
+   before repairing, unless an immediate blocker invalidates the remaining
+   work. Do not turn individual findings into serial repair, validation, and
+   Closure micro-cycles. Repair compatible findings once, rerun each affected
+   validation once on the resulting revision, then launch one affected-lens
+   Closure wave.
+4. Continue implementation only when checkpoint blockers are verified or the
+   Review Plan explicitly assigns their verification to an already planned reviewer
+   without violating the checkpoint's safety purpose.
+5. After all implementation slices and validations settle, run one final code
+   review wave. `simple` and `medium` use one reviewer; `high` launches two
+   disjoint reviewer tracks in parallel. The spec/standards lens owns bounded
+   cleanup.
+
+Intermediate code-review checkpoints do not run cleanup-review. A separate
+cleanup pass is exceptional: run it only when the user, approved source, or repo
+policy names a concrete evidenced simplification risk that cannot fit the final
+spec/standards lens. `large` or `high` alone is not a reason. If an approved spec
+names an intermediate cleanup checkpoint, return `Blocked` for spec revision.
+
+Cleanup review runs at most once as a Full review for the whole spec. After its
+findings are repaired, either use protocol Closure or give the final code
+reviewer those stable defect IDs for verification. Never launch another Full
+cleanup review over the repaired whole diff.
+
+## Convergence And Stop Rules
+
+Apply protocol repair, no-progress, stop, and waiver semantics. The following
+audit is implementation-specific.
+
+Before launching more reviewers, run one non-terminal convergence audit after
+two consecutive Closure waves in one gate, ten total implementation review
+passes, or 90 minutes when timing is available. One coordinated launch over all
+affected lineages is one wave regardless of parallel pass count.
+
+Persist one audit epoch with trigger, triggering pass/wave/revision,
+completion, dispositions, selected sessions, and resume reason. It survives
+resume. After a material repair/evidence change proves progress, rearm by
+recording the current total pass count, current gate-local Closure-wave count,
+and current timestamp as new baselines. The next audit opens only after a
+post-rearm delta reaches two Closure waves in that gate, ten implementation
+review passes, or 90 minutes; already-consumed counts or time cannot reopen it
+immediately. Without progress do not rearm and use the existing stop rules.
+Thresholds never approve, waive, downgrade, or block by themselves, and
+distinct failure mechanics remain distinct even when they protect one
+invariant.
+
+Return `Approved` for the final settled revision only when protocol state is
+`clear` and:
+
+- every mandatory lens has independent coverage
+- final validation and required cleanup/code-review gates ran
+
+Map protocol `stopped` to `Blocked`. Implementation-specific blockers also
+include:
+
+- a defect reopens repeatedly and exposes a source-of-truth or repair-design
+  contradiction that root cannot resolve from current evidence
+- an execution risk remains open without an explicit user decision to accept it
+
+Do not mark implementation `Blocked` merely because review has run several
+times. Resolve the repair, evidence, or decision problem first.
+
+Map protocol `waived` to `Waived` and preserve skipped coverage and open risks.
+It remains non-approval; target authority or downstream policy may still block
+delivery.
+
+## Required Handoff
+
+Use the protocol result envelope and add:
+
+```text
+Implementation Review Profile: <simple | medium | high>
+Review Outcome: <Approved | Blocked | Waived>
+Authority Artifact: <approved spec path>
+Implementation Checkpoint: <checkpoint or final>
+```
+
+## Contract Test Ledger
+
+| Invariant | Risk It Prevents | First Test / Proof | Status |
+| --- | --- | --- | --- |
+| Review pass counts are audit metrics, while one durable Review Plan and Defect Ledger span the entire spec. | Each slice silently recreates a new loop or a repairable spec blocks on an arbitrary count. | Manual eval scenario 15 | planned |
+| Intermediate checkpoints never trigger cleanup; final review is one settled profile-selected wave, and separate cleanup is exceptional. | Per-slice hygiene or size-driven cleanup adds latency and restarts review over unstable work. | Manual eval scenario 17 | planned |
+| Audit epochs persist across resume and rearm only after material progress. | Thresholds repeatedly trigger audits or become terminal limits. | Manual eval scenario 12 | planned |
+
+Keep these rows `planned` until the corresponding operator eval is run and its
+result is saved.

package/internal-workflow/docs/agents/review-gates.md

@@ -0,0 +1,49 @@
+# Review Gates
+
+This file owns applicability only. Approved-spec execution follows
+[`implementation-review-loop.md`](implementation-review-loop.md), which owns
+checkpoint order, Full/Closure topology, durable state, and final coverage.
+Direct work uses the gates below without manufacturing Module state.
+
+## Cleanup Review
+
+Do not launch a separate `$cleanup-review` from size or risk classification
+alone. The final `$code-review` spec/standards lens owns bounded cleanup for
+simple, medium, large, and high-risk changes; high runs that lens in its own
+parallel reviewer track.
+
+Use separate `$cleanup-review` only when the user, approved source, or repo
+policy names a concrete evidenced simplification risk that cannot fit the
+bounded spec/standards lens. It runs before final `$code-review`; approved-spec
+execution lets the shared Module schedule it.
+
+Treat a change as large only when it contains several independently verifiable
+runtime workflows or material cross-owner, cross-repo, release-sequencing, or
+rollback coordination. File count, module count, or a broad mechanical diff is
+not enough. Default a coherent feature with one behavior and one validation
+path to medium even when it touches several files.
+
+Cleanup is not a correctness review. Its skill owns the detailed lens,
+confidence handling, repair integration, and output contract.
+
+## Final Code Review
+
+Run final `$code-review` when implementation changes include any of:
+
+- a medium/large feature or shared multi-module business behavior;
+- API/DTO/schema, migration, persistence, auth, permission, payment, cache,
+  concurrency, background-job, or shared-state contracts;
+- shared UI/navigation/middleware/core flows;
+- runtime logic across three or more files when the change is behavioral rather
+  than mechanical and crosses one owner or validation seam.
+
+Do not invoke it automatically for documentation/copy/comments, tests-only or
+styling-only changes, formatting/renames, mechanical refactors, or isolated
+one-file fixes with low regression risk.
+
+`$code-review` owns reviewer topology, confidence, auto-fix, and output rules.
+Its spec/standards reviewer owns the bounded cleanup lens for every profile; do
+not launch `$cleanup-review` for the same settled diff without an explicit
+concrete reason beyond size or risk labels.
+For approved specs, required final coverage remains part of the shared
+Implementation Review State.

package/internal-workflow/docs/agents/review-protocol.md

@@ -0,0 +1,170 @@
+# Review Protocol
+
+This Module owns review mechanics shared by artifact and implementation review:
+capsules, Full/Closure, reviewer lineage, the canonical Defect Ledger, no-progress,
+stop/waiver semantics, and the result envelope. Target Modules own authority,
+risk/profile selection, topology, durable orchestration, gate order, and final
+outcome mapping. Callers select a target Module and never copy this protocol.
+
+## Interface
+
+```text
+apply_review_protocol(
+  review_capsule,
+  reviewer_lineages
+) -> protocol_result
+```
+
+`review_capsule` is the normalized Full/Closure capsule defined below. The result
+contains `state: clear | repair-required | stopped | waived`, pass
+mode/revision/lineage/session/lenses, mandatory coverage, ledger transitions, and any
+stop or waiver record. The capsule's canonical Defect Ledger is the only ledger
+input. `clear` requires assigned-scope coverage and every non-superseded blocker
+or execution risk to be `verified`, except an explicitly `accepted-risk`
+execution risk. A superseded record counts as resolved only when `superseded_by`
+resolves through an acyclic chain of distinct same-ledger IDs to one
+non-superseded canonical replacement; that terminal replacement controls
+clearance. A missing, self-referential, or cyclic replacement chain prevents
+`clear`. The target Module decides whether `clear` is enough for `Approved`. A
+reviewer lineage binds one activation, profile/lenses, Full coverage, and defect
+IDs; physical sessions may rotate without creating a new activation or Full.
+
+## Review Capsule
+
+Every fresh reviewer receives a bounded self-contained capsule:
+
+- target kind/path, pinned revision, profile, mode, and assigned lenses
+- one review question and why existing valid coverage does not answer it
+- goal, authority, approved scope, and relevant source references
+- required Evidence Index entries, compact validation, and verification gaps
+- canonical Defect Ledger
+- for Closure: repair diff, affected contracts, and Revision Map
+  `changed target -> defect IDs -> affected invariants/contracts`
+
+Exclude raw parent history, old targets, prior reviewer prose, repeated logs,
+unrelated output, and broad inventories. Reviewers may inspect extra evidence
+needed for a finding. Reuse unchanged evidence; invalidate only entries affected
+by changed targets/contracts or stale external sources. External evidence keeps
+its direct source and retrieval date.
+
+Before launch, reuse clear coverage for the same target revision, question, and
+lenses. Do not launch a reviewer whose question is already answered; a changed
+target or a distinct artifact-versus-implementation question is new coverage.
+
+## Review Modes
+
+**Full:** read the complete pinned target required by assigned lenses and return
+all visible evidence-backed blockers/execution risks as one batch.
+
+**Closure:** use only affected reviewer lineages to verify repaired IDs, the
+repair diff, and contract fan-out. Do not re-audit unchanged areas. The first
+Closure normally reuses the Full session. If it reopens a defect and another
+repair follows, run the next Closure in a fresh session of the same lineage.
+Before a Closure launch, rotate earlier after compaction/interruption or when
+observable context usage reaches 40%. The fresh session receives the bounded
+capsule, remains Closure, and preserves Full coverage and defect authority. One
+coordinated launch over affected lineages is one Closure wave.
+
+Closure admits a new defect only when it names the repair target/contract that
+introduced or materially widened the trigger, or a high-confidence
+`blocker`/`execution-risk` violates a source-required invariant in the assigned
+lens. Each newly admitted blocker or execution risk starts as `status: open`
+and `disposition: repair-now`, then moves `open -> fixed -> verified` only
+through repair and independent affected-lens verification. Pre-existing
+adjacent issues are improvements. Verification stays with an affected session
+or an already planned covering Full reviewer. Start a new Full only when the
+repair invalidated mandatory-lens coverage.
+
+## Canonical Defect Ledger
+
+Root assigns stable IDs and deduplicates only when invariant and failure
+mechanics both match. Wording changes do not create defects.
+
+```yaml
+id: REVIEW-CONC-003
+class: blocker | execution-risk | improvement
+disposition: repair-now | planned-final-verification | follow-up-improvement | accepted-risk
+status: open | fixed | verified | blocked | reopened | accepted-risk | superseded
+severity: critical | high | medium | low
+confidence: high | medium | low
+invariant: "<observable rule>"
+failure: "<concrete failure mechanics>"
+evidence: ["<target/repo/source reference>"]
+repair: "<smallest sufficient change>"
+affected_targets: ["<path, section, contract, or lens>"]
+introduced_in_review: 2
+transition_history: []
+reopen_count: 0
+acceptance: null | { authority, reason, scope, target_revision }
+superseded_by: null | "<canonical replacement defect ID>"
+fixed_in_revision: null
+verified_in_review: null
+```
+
+Reviewers reuse supplied IDs; new candidates use `NEW-<LENS>-NN` until root
+deduplicates them. Root may mark a duplicate `superseded` only after recording
+its canonical replacement in `superseded_by`. The chain must be acyclic and end
+at a distinct non-superseded record; a superseded record never hides the
+terminal replacement's lifecycle. Disposition and lifecycle are separate.
+`fixed` requires a later affected-lens Closure or planned Full to become
+`verified`; tests alone do not independently verify review findings.
+
+Improvements use `follow-up-improvement` and do not block. Only an execution
+risk may become `accepted-risk`, after explicit authority, reason, scope, and
+target revision are recorded. A blocker cannot be accepted or downgraded.
+Target Modules decide where `planned-final-verification` is legal; it remains
+open until the scheduled lens verifies it.
+
+## Repair, Stop, And Waiver
+
+Root repairs compatible findings in one batch. Before another Closure, target
+revision/strategy, relevant evidence, defect state, or source decision must
+change materially. Otherwise root must change the repair, prove the finding
+invalid, or surface the decision preventing convergence.
+
+Pass counts and elapsed time are audit signals, never approval, waiver,
+downgrade, or blocking conditions. Target Modules may define audit epochs while
+preserving this rule.
+
+A bounded poll timeout while the reviewer session remains live is non-terminal:
+report that the reviewer has not completed within the polling window, not that
+it is stuck, failed, or unavailable. Root may send at most one conclude request
+for that reviewer turn. Further empty polls neither authorize another conclude
+request nor replacement/cancellation. Replace or cancel only after the reviewer
+session or transport explicitly reports `failed`, `lost`, or unavailable; a
+late usable result from the original live session remains authoritative. Persist
+session `live|timed-out` state and `conclude_requested_at` so resume preserves
+the limit.
+
+Return `stopped` without another review when repair needs a product/scope/owner
+decision, mandatory evidence or reviewer is unavailable, no substantive repair
+exists, or the same defect repeats without progress.
+
+Return `waived` only after explicit user instruction. Record skipped coverage
+and open defects. Waiver never means approval, verifies/accepts no defect, and
+skips no separate downstream gate. The target Module maps it to `Waived` or
+`Blocked` using its authority rules.
+
+## Result Envelope
+
+```text
+Review Passes: <total; Full; Closure; fresh sessions when tracked>
+Mandatory Coverage: <covered lenses or gaps>
+Verified Defects: <IDs or None>
+Accepted Risks: <IDs, authority, and reason or None>
+Open Defects: <IDs or None>
+```
+
+Target Modules add profile, mapped outcome, authority, Adapter verdict,
+checkpoint, status, or performance fields without redefining common fields.
+
+## Contract Test Ledger
+
+| Invariant | Risk It Prevents | First Test / Proof | Status |
+| --- | --- | --- | --- |
+| Full/Closure stay causal and affected-lens-only within reviewer lineage | Broad review restarts, stale context, or lost defect authority | Evals 11, 16 | green |
+| Every launch answers an uncovered question on its pinned target | Duplicate reviewers repeat valid coverage without new evidence | Eval 23 | green |
+| Both consumers use one defect schema and lifecycle | Artifact and implementation defects drift | Eval 12 | green |
+| No-progress requires material change | Unchanged Closure repeats or numeric limits become terminal | Eval 12 | green |
+| A live reviewer poll timeout stays non-terminal and permits at most one conclude request | Root falsely reports a hang, cancels useful work, or launches a duplicate reviewer | Eval 12 | green |
+| Waiver skips coverage without accepting defects | Skipped review is reported as approval or risk acceptance | Eval 12 | green |