--- name: development-workflow description: Use when making repository changes, debugging, handling review feedback, verifying work, conducting final review, recovering CI, deciding the next development lifecycle step, or handling a missing or weaker final_review_protocol attestation or coordinator clean-iteration minimum. --- # Development workflow When selecting a delegated agent's model or reasoning effort, read [model-routing](../model-routing/SKILL.md) before spawning. It is the canonical task-local routing policy; agent definitions do not choose a model. Use `workspace-reader.status` before choosing a workflow. Outside Git, without configuration, or with invalid configuration, inspection remains available but the plugin cannot provide configured workflow guidance. This advisory state does not deny ordinary host mutation capabilities. ## Workflow explanation checklist Strongly recommend the [architecture and decision-history practices](../engineering-standards/references/architecture-policy.md) for project adoption. First inspect the project's current architecture and local policy. Existing conventions and explicit user choices take precedence; installation or setup alone does not adopt these recommendations. Record the accepted subset, any overrides, document paths and prospective adoption boundary in project-owned guidance. Do not add requirements or block delivery solely because an unadopted recommendation is absent. For adopted rules, check the actual candidate and resulting trunk commits, including squash delivery. Use only the corresponding checker rules and retain semantic review evidence separately from mechanical receipts. Offer unadopted practices as recommendations, not findings of noncompliance. When explaining implementation increments, final review, or terminal-review remediation, cover these points explicitly; do not replace them with a generic reference to gates: - Before planning review, use a fresh independent broad risk scout that assesses security and human/physical safety separately, even when overall risk is low. - Filter findings deterministically before stronger risk-selected lens review; reserve strong batched verification for blocking, disputed, or materially uncertain findings. - Causal repair, with the recorded RED causal claim when applicable, immediate focused tests and lightweight review; comprehensive suites belong in CI, without a duplicate local comprehensive exact-commit gate. - Installed Lefthook commit/push gates without manual duplication, signed commits, exact commit/message/signature verification, and authorized delivery. - Record the delivered identity together with its required exact-SHA CI runs. A completed required failure activates the existing **Tiber recovery hold**. - Each publication increment must have a verified local checkpoint before proportional independent publication review; trunk push follows that review. All planned increments and acceptance checks precede final feature review. Explain the complete remediation checkpoint. - PR branch pushes and draft creation may precede review, but ready/non-draft publication, auto-merge enablement and merge-queue entry require passing current local multi-lens review. Before updating **any** ready PR, FIRST return it to draft and confirm that succeeded, regardless of whether auto-merge is enabled. Only then disable auto-merge and confirm it is off before pushing; stop if either safeguard fails. Auto-merge being off does not narrow the draft safeguard. Renew affected review before restoring ready status, auto-merge or queue entry. - Independent delta assessment renews affected behavior/dependencies while preserving proven peer receipts and all recorded responsibilities/sample floors. Full renewal requires material whole-scope impact or unisolatable provenance. ## Carried rejection evidence recovery If an old `final_review.advance` was rejected after a carried independently rejected finding's source dependencies changed, read the authoritative session with `final_review.resume_latest` after updating and restarting the runtime. Preserve the original baseline and all completed `lens_results` exactly. When the fingerprint and reviewed source still match, retry the saved advance unchanged. The corrected host observes changed dependency identities and returns `verifier_required`; use that exact returned assignment in a fresh independent verifier context. Do not invent a new reviewer allegation, alter completed clean results, fabricate `resolution_reopen` evidence or replace state. After the verifier finishes and closes, resubmit the same review request with its genuine `verifier_result` and the caller's actual assigned-model, fresh-context and post-close lifecycle attestation. A rejection refreshes source-bound evidence only with all actually checked current dependency blobs, which the host independently observes. A confirmed or uncertain verdict leaves the finding open. A genuinely finding-free submitted round can retain normal clean credit after successful adjudication; a newly submitted allegation still remains visible even after rejection. V3 can retain valid coverage after genuine independent adjudication; v2 keeps its recorded complete clean rounds until explicit migration. If source or fingerprint changed, reconcile the authoritative pending assignment and required delta review before resubmitting. ## Proportional and interruptible execution Before expanding active scope for advisory or non-blocking feedback, run the proportionality checkpoint in `workflow-rules.md` against the original goal, acceptance criteria, trust boundaries, and completion claim. A review finding does not authorize broader implementation. Keep materially required causal work and mechanical gates fail-closed. Report distinct improvements and offer the user a choice; worthwhile distinct work may enter the backlog without expanding or delaying the active goal, while implementation requires the user to explicitly expand the goal. V3 can preserve valid coverage after genuine independent rejection or proper report-only disposition. Confirmed blockers remain required work. In every checkpoint result, explicitly name all four boundaries and the outcome for each; never substitute a bare reference to "the proportionality checkpoint." In every status update or answer about long-running work, explicitly report four fields for each gate: (1) command or gate identity, (2) why it is required, (3) progress or last-known state, and (4) cancellation path. Apply a user's scope correction immediately to every subsequent action, promptly stop optional work, report what stopped, preserve completed valid evidence, and do not implicitly restart cancelled work. Reuse evidence only item by item when its covered source or behavior, scope, baseline, configuration, environment, inputs, and freshness contract are unchanged; record that decision and rerun affected checks plus every required post-mutation or post-commit gate. Deduplication never bypasses an acceptance criterion, final-review reset, exact-revision gate, or CI-recovery hold. ## Per-edit durable checkpoints After every individual implementation-file or test-file edit, stop and run the smallest relevant test immediately. Bind the exact worktree snapshot and test receipt to exactly one durable state, plus its next permitted action. Before the first edit, commit, or push, resolve the full ticket-start commit OID and persist it in this record; carry that immutable baseline through every later checkpoint and into terminal review: The authoritative persistence owner is always the validated local record; the unavailable native workflow scheduler and a generic remote note API are never the owner. Store the latest record at `$(git rev-parse --git-common-dir)/development-system/checkpoints/.latest` in every delivery mode. Use the active task ID as `checkpoint-id` when one exists. Otherwise derive it as lowercase hexadecimal SHA-256 of the exact byte sequence `baseline_oid`, one NUL byte, and the original user-request text encoded as UTF-8 after replacing every CRLF or lone CR line ending with LF. Do not trim whitespace, normalize Unicode, interpolate variables, or append a newline. Record that ID in every handoff. Use the bundled `/scripts/transition-local-checkpoint.sh CHECKPOINT_ID OPERATION_ID OPERATION INPUT_FILE` with the [typed operation contract](references/checkpoint-operations.md). Supply operation-specific evidence plus the expected successor generation and predecessor digest; never manually construct a successor for an ordinary transition. Keep input and retained evidence outside the worktree. Choose and retain one stable operation ID before the call; use `read` with `{}` or retry the exact request after interruption, without repeating an external action. The helper derives the successor from the validated authoritative predecessor under the writer's exclusive task-scoped lock, and retains a durable operation receipt. Reusing an ID with different input is rejected. After an interrupted publication, the writer reconciles the prepared receipt against authoritative bytes before any new transition. The compatibility `write-local-checkpoint.sh` still accepts a complete outside-worktree proposal and uses the same validation, lock, and publication path. The helper creates the owner-only parent, then validates a private same-directory candidate. It reads the current complete record and requires the candidate's `generation` to equal the current generation plus one and its `predecessor_sha256` to equal SHA-256 of the exact current `checkpoint-v1` line; the bootstrap record uses generation zero and a null predecessor. It also requires the candidate to perform the predecessor's exact `next_action`, so a schema-valid record cannot skip or reorder an edit, test, review, gate, verification, delivery, CI-monitoring, recovery, or terminal-review transition. Reject a missing, stale, or action-incompatible predecessor without replacing the current record. The helper flushes the private candidate, recomputes the complete worktree identity and rejects publication if it changed since validation, atomically renames the stable record over the target, flushes the directory, and releases the lock; never synthesize a second writer or append in place. Keep this local file untracked and out of the content snapshot. After every transition, persist exactly one authoritative local record before the next action. When task-board remote publication is independently authorized, append that successfully validated transition to the active Tiber task with `tiber.note.add` (CLI: `tiber note add`) as an optional mirror. Mirror failure does not replace or invalidate the authoritative local transition; retain the publication failure for handoff and retry it only while remote mutation remains authorized. The canonical wire form is the literal prefix `checkpoint-v1 ` followed by one compact JSON object (no Markdown) with these required keys: `generation`, `predecessor_sha256`, `baseline_oid`, `snapshot`, `state`, `test`, `gates`, `delivery`, `ci`, and `next_action`. `generation` is a non-negative integer and `predecessor_sha256` is a SHA-256 string except on the generation-zero bootstrap, where it is `null`. Use strings for other scalar values and `null` only where the following exact shapes permit it. `snapshot` is exactly `{"head_oid":string,"tracked_sha256":string,"untracked_sha256":string}`. `test` is either `null` or exactly `{"command":string,"receipt_ref":string,"outcome":"pass"|"fail","failure_kind":string|null}`. It records the immediate test or, when a pending gate fails, that gate's actual command and bounded failure evidence. A failed pre-commit hook uses `failure_kind:"pre-commit-hook"`; a lightweight review requiring remediation uses `failure_kind:"lightweight-review"`. These are truthful failed gate receipts, not claims that the preceding focused test failed. `gates` has these required fields (legacy records may omit terminal review): `{"lightweight_review_receipt":string|null,"fast_gate_receipt":string|null,"exact_identity_verification_receipt":{"receipt_ref":string,"outcome":"pass"|"fail"}|null}`. `gates.increment_review_receipt` and `gates.terminal_review_receipt`, when present, each use `{"receipt_ref":string,"head_oid":string,"baseline_oid":string,"source_sha256":string}`. `increment-review-pass` records independent review of the declared publication increment, bound to the exact verified source and immutable task baseline, and permits trunk `push`. It does not certify final acceptance. Missing legacy evidence earns no publication credit; a legacy committed `terminal-review` checkpoint must explicitly use `increment-review-pass`. The final receipt additionally carries `scope:"final-acceptance"`; legacy unscoped receipts never earn new final acceptance credit. Legacy ready-to-push records explicitly renew increment review before publication. `terminal-review-pass` records scope-complete final acceptance only after delivery and required exact-SHA CI success. Successful CI after increment publication leads to `terminal-review`, or use `begin-edit` to continue the next increment. `begin-edit` clears both review receipts while preserving the original task baseline and CI history for cumulative final review. `delivery` is either `null` or exactly `{"mode":"local-only"|"direct-to-trunk"|"pull-request","commit_oid":string|null,"pushed_oid":string|null,"local_snapshot":string|null}`. `ci` is exactly `{"runs":[{"provider":string,"run_id":string,"commit_oid":string,"status":"queued"|"running"|"success"|"failure"}],"terminal_success_run_id":string|null}`; `runs` is append-ordered by observation and every successor must retain the predecessor's complete array as an exact prefix. A non-null `terminal_success_run_id` must name the final array entry. Every command, receipt, provider, run ID, and local-snapshot string used as evidence must contain at least one non-whitespace character. The snapshot hashes are defined as follows: - `tracked_sha256` is SHA-256 of the exact byte stream from `git diff --binary --full-index HEAD --`. - `untracked_sha256` is SHA-256 of the byte stream produced by iterating `git ls-files --others --exclude-standard -z` in its emitted order and, for each path, appending its Git mode token (`100755` for an executable regular file, `100644` for another regular file, or `120000` for a symlink), one NUL byte, the path bytes, one NUL byte, the file's `git hash-object -- ` OID, and one newline byte. An unsupported file type is a recovery hold. The empty stream has the standard SHA-256 empty digest. State-specific absent values remain `null` or empty arrays; never omit or rename keys. JSON escaping is the only escaping. Before the first edit on a clean task-start worktree, bootstrap the first record as `pushed-or-delivery-mode-equivalent`: use the ticket-start OID for `snapshot.head_oid`, set `test` to `null`, describe the already-authorized starting identity in `delivery` (a pushed OID for a remote mode or `local_snapshot` for local-only), and make the first planned causal edit the sole `next_action`. This is the only delivered-state gate exception: all three gate receipts are `null`, and CI may be empty, only when `baseline_oid` equals `snapshot.head_oid`, both snapshot hashes prove the clean starting worktree, and `delivery` identifies that same pre-existing baseline. A dirty, non-baseline, or unreconciled starting worktree is a recovery hold, not a bootstrap shortcut. Store bounded references rather than raw logs or secrets. At session start, restart, or handoff, always read the authoritative local `.latest` file regardless of repository delivery mode. Select its latest `checkpoint-v1` record, verify its generation/predecessor chain when history is available, and reconcile every identity with current Git and forge state before acting. When task publication was authorized, use `tiber.show` only to compare the optional mirror and recover any retained publication failure; a missing or behind mirror does not override valid local authority. A malformed, missing, non-atomic or stale local, or mismatched authoritative record is a fail-closed recovery hold: do not edit, commit, push, or infer progress until the same task record is reconciled. This note protocol records evidence only; it does not claim to enforce harness capabilities. For upgrade compatibility, a pre-6.2 `checkpoint-v1` record whose only noncanonical field is a free-form `next_action` remains readable evidence, but its action is never executable authority. Under the same task lock, derive the canonical action from its state and receipts, append the next generation through the bundled writer, and reconcile that successor before acting. Any other schema, identity, or lineage mismatch remains a recovery hold. ### Failed pending gates and stranded-checkpoint recovery When `next_action` is `commit-through-pre-commit-hook` and the actual Git operation fails in pre-commit without creating a commit, publish a `failing` successor before any repair. Likewise, a `lightweight-review` finding requiring remediation first publishes a `failing` successor. Record `test.outcome:"fail"`, the matching failure kind above, the failed command or review identity, and a bounded reference to the actual failure evidence. Keep HEAD unchanged, retain the immutable baseline and CI history, clear every gate receipt, set `delivery` to `null`, and use `causal-edit: ` as the sole next action. Never fabricate a commit, a passing hook receipt, or a passing review. Commit and push remain prohibited while failing. After the causal repair, run fresh focused testing immediately, then fresh lightweight review, then a new normal commit attempt through the installed pre-commit hook. Exact identity verification, authorized delivery, exact-SHA CI, and terminal review remain required; failed or pre-repair receipts cannot satisfy the repaired snapshot. For records already stranded at either pending gate, use the bundled `/scripts/record-checkpoint-failure.sh CHECKPOINT_ID EXPECTED_GENERATION EXPECTED_PREDECESSOR FAILURE_KIND COMMAND RECEIPT_FILE CAUSAL_REPAIR`. Load the authoritative predecessor, use its generation plus one and its exact SHA-256 digest, and supply a readable, nonempty retained failure-evidence file outside the worktree. This helper copies the predecessor, records the evidence path and digest, computes the current canonical snapshot, and publishes only through `write-local-checkpoint.sh`. It preserves staged, unstaged, and untracked work, including previously untracked files now staged; it never changes the index, edits source, runs the failed action, or writes `.latest` directly. A stale caller or changed HEAD is rejected without publication. First reconcile Git and the failed action's actual evidence. Staging can change the tracked/untracked snapshot partition without changing source; hook-made changes must be identified and included in the actual failing snapshot. An unexplained source change, missing evidence, malformed predecessor, or commit already created is still a recovery hold. Do not restore an old snapshot or discard staged work to make hashes match. If failure evidence is unavailable, recover it from the blocked session; otherwise the still-pending normal commit action may be retried with captured output, recording its actual success or failure. A commit that succeeds follows the normal committed transition and cannot be relabeled as a failed pre-commit attempt. Recovery records evidence; the helper cannot attest that a caller's supplied failure report is truthful. - `failing`: commit and push are prohibited. Permit only the next causal edit needed to address that failure, reject unrelated or convenience changes, and immediately test again. `test` is required and `delivery` is `null`. Every gate receipt is `null`; CI entries may only describe already-delivered earlier commits and cannot satisfy a gate for this snapshot. A newly written test that passes unexpectedly is still `failing`: preserve the truthful `outcome:"pass"`, set `failure_kind:"invalid-test"`, and record only `rewrite-invalid-test: ` as `next_action`; do not represent the execution as a failed test or introduce a fifth state. Other failing records use `causal-edit: ` so the exact RED evidence, diagnosis, and next edit survive interruption. - `passing-awaiting-gates-or-review`: freeze further implementation and test edits. Run the bounded lightweight review; any required remediation must first enter the failed-gate transition above, then permit its causal edit and another immediate focused test. `test` is required and `delivery` is `null`. Then create the authorized signed commit. Git must trigger the Lefthook pre-commit gate during that operation; do not run the gate separately. Record the hook receipt and commit together, using `lightweight-review` and then `commit-through-pre-commit-hook` as the exact successive `next_action` values. exact-identity verification remains `null` until a commit or reviewed local-only snapshot exists. - `committed`: record the signed commit OID and whether the next action is the delivery-mode checkpoint or a locally complete checkpoint; `delivery` is required and its commit OID must equal `snapshot.head_oid`. Lightweight-review and the pre-commit hook receipt are required. Immediately after commit creation, `exact_identity_verification_receipt` may be `null` only while `next_action` is `verify-exact-commit`; append the next committed checkpoint after verification. Exact-identity verification checks source identity, message, and signature; it never reruns repository verification already owned by Lefthook. A failed verification stays `committed`, records the bounded `outcome:"fail"` receipt, sets `next_action` to `repair-exact-identity-verification`, prohibits delivery, and permits only the causal repair action followed by another exact verification. Push or local completion requires a successful exact-identity verification receipt; then use `increment-review` for direct-to-trunk, `push` for a draft PR branch, or `record-local-delivery` for local-only. A verified local committed checkpoint may use `begin-edit` to continue the next increment as the exact `next_action`. CI for this new commit may still have no runs before remote delivery. - `pushed-or-delivery-mode-equivalent`: record the exact pushed OID and CI runs, or the exact local-only terminal snapshot and the fact that remote mutation is unauthorized; `delivery` is required and must identify the exact state-appropriate commit or snapshot, and all three gate receipts remain required, with exact-identity `outcome:"pass"`, except for the exact clean bootstrap above. For a local-only no-commit checkpoint, exact-identity verification binds the reviewed local snapshot; it never implies commit authority or fabricates a commit receipt. Immediately after a successful remote push, `ci.runs` may be empty only while `next_action` is `register-exact-sha-ci-monitor`; append the next checkpoint as soon as the run reference exists. Otherwise direct-to-trunk and pull-request records require at least one CI run for the exact pushed OID. Use `monitor-exact-sha-ci` while all runs are queued/running without terminal success, `enter-ci-recovery` as the sole action when an exact-SHA run fails and no replacement has reached terminal success, and `terminal-review` after the named terminal success. Increment publication review never implies feature completion. Use `complete` only with retained final acceptance, which must be the final append-ordered CI observation. Retained CI history may contain earlier failures. Local-only requires no remote run and uses `terminal-review`. A remote push must trigger the Lefthook pre-push gate; do not run its verification commands separately. Set `terminal_success_run_id` only when it names an included exact-OID success run; queued, running, older-OID, or failed runs never satisfy readiness. When Tiber's opt-in final-review policy requires reviewed source and verification paths in a commit tree, the local equivalent is a required local commit; if commit authority is explicitly withheld, completion blocks without authorizing a push. Every interruption or handoff must preserve the ticket-start baseline, state, exact snapshot, test receipt, completed gates, and sole next permitted action. Never infer progress from an unbound green test or a clean worktree alone. When a test and its implementation cannot independently pass, declare one bounded RED-to-GREEN pair before the implementation edit. Persist the expected RED result and causal claim, allow only the paired implementation edit, test immediately, and enter `passing-awaiting-gates-or-review` at GREEN. This is not permission to bundle another behavior. The pair is not a fifth durable state: its RED snapshot remains canonical `failing` with the paired implementation as the sole next action until the immediate retest reaches GREEN. Apply proportional checkpoints outside implementation and test files. Documentation, configuration, and formatting-only changes run the smallest relevant formatter, parser, validation, or executable example before their lightweight review and delivery checkpoint. Generated output and mechanically required metadata may accompany only the causal source snapshot that produces or requires them. Never batch already-passing unrelated work for convenience. Commit small, coherent passing increments extremely frequently in every delivery mode; do not wait for a feature, vertical slice, or final MVP to be complete. Direct-to-trunk pushes go to origin’s configured trunk; PR/MR pushes go to the selected branch; local-only commits stay local. An explicit no-commit instruction takes precedence and uses the reviewed snapshot route. Each commit runs the configured pre-commit checks at minimum, preserves signing and exact source/message/signature verification, and receives proportional independent review before trunk publication. Review the actual increment and its affected dependencies; unfinished acceptance criteria for later increments are not publication blockers unless the current increment breaks an existing contract. Keep required CI gates and record the exact pushed SHA. Supporting commits are progress toward a slice, not delivered user value. Continue completing usable vertical slices regularly and perform scope-complete final review and acceptance before claiming feature or MVP completion. In direct-to-trunk mode, use one checkout on the configured trunk branch and push directly to origin’s trunk. Do not create a branch, linked worktree, or parallel source checkout unless the user explicitly authorizes a different approach. Serialize mutable work in that checkout, including CI repair; read-only reviewers may inspect it. Use affected independent review for each increment rather than accumulating a completed local batch for one eventual publication review. Keep the immutable task-start baseline for final acceptance while recording each increment’s reviewed scope and exact identity separately. For direct-to-trunk final acceptance, publish the final verified increment after its independent increment review before starting cumulative final review. A still-local checkpoint takes that publication route first; full feature acceptance never blocks incremental publication. Review the delivered final identity against the immutable ticket-start baseline. Required CI may run alongside independent final review; completion requires both clean final review and terminal-success CI for that exact SHA. Local-only final review uses the recorded local identity without publication; PR/MR branch publication may precede final readiness review. In PR/MR mode, authorized branch pushes and draft creation may precede full local review. Before updating any ready PR/MR, first return it to draft and confirm success, then disable auto-merge and confirm it is off. Stop if either safeguard fails. Current local multi-lens review is required before restoring readiness, enabling auto-merge, or entering the merge queue. Local-only work remains local and uses the authorized commit or no-commit evidence route. In all modes, source, dependency, baseline, scope, or conflict-resolution changes invalidate affected evidence; metadata-only changes require exact identity verification. Required remote CI follows push, and a failure preempts unrelated work through CI recovery. Neither passing CI nor forge approval substitutes for required independent review. Any terminal-review finding remediation must leave review and complete the normal immediate-test and lightweight-review checkpoint. Then use a signed additive commit plus exact verification, renewed affected review before trunk push (or PR readiness), and authorized push for remote modes, or the same frequent signed local commits for local-only. An explicit no-commit restriction instead uses a new exact reviewed snapshot. Submit the diff-bound independent delta assessment and obtain fresh affected-behavior/dependency review under v3, preserving proven peer receipts and every recorded responsibility and sample floor. An ordinary delta cannot omit an obligation or lower its sample count. Full renewal requires whole-scope impact or unisolatable provenance; v2 retains its recorded full-reset contract. Comprehensive, slow, integration, mutation, and pipeline-scale suites remain in CI rather than being duplicated in a local exact-commit gate. A completed exact-SHA CI failure immediately preempts review or other work through the existing Tiber-owned recovery hold. Keep checkpoint CI bounded per ref while continuing increments. Use existing provider or repository coalescing/cancellation for superseded non-terminal runs when available and authorized; otherwise wait for capacity before another push would add obsolete queued work. Never cancel the current terminal candidate's exact-SHA run, and never accept a successful older run as its readiness evidence. `register-exact-sha-ci-monitor`, `monitor-exact-sha-ci`, and `enter-ci-recovery` are delivery-readiness actions, not a serialization barrier for local causal work: after the next increment's immediate focused test, the successor may enter `failing` or the initial `passing-awaiting-gates-or-review` stage while retaining the complete CI observation history. ## Final-review protocol preflight For every final-review path, complete this checklist before creating any risk or review state: 1. Call `workspace-reader.status` through the same connected MCP that would run final review. 2. Require one `final_review_protocol` object with `contract_version >= 3`, `minimum_clean_iterations: 1`, `scoped_coverage: true`, `explicit_policy_migration: true`, and `durable_pending_assignment_recovery: true`. 3. Missing or mismatched capability accepts zero enforced credit and blocks terminal delivery, PR/MR publication, merge, and readiness. Preserve separately authorized causal checkpoint work under its ordinary gates. Do not bypass the coordinator with manual claims or caller-edited state. 4. Update the plugin and version-matched current-host binaries, restart the harness, and repeat `workspace-reader.status` through the same connected MCP. A local build, configured path, plan call, or installation alone does not prove adoption by that connected process. 5. Read the recorded session policy. V2 sessions retain their existing three-round requirements; use explicit independently assessed `final_review.migrate_policy` to change an active contract. Preserve baseline, history, blockers, holds, and original evidence. Missing historical dependency/freshness/lifecycle bindings cannot become invented narrow reusable credit. Read the [proportional review policy](../../components/development-discipline/skills/final-review/references/proportional-review-policy.md) for v3 requirements, source/behavior/scope/freshness invalidation, visual continuity, legacy compatibility, and exact recovery operations. Never waive a gate because of elapsed time, budget, pressure, tool failure, or a stuck task. For every workflow question, load [workflow rules](references/workflow-rules.md). Before editing, classify artifact impact relations and RED applicability. Keep diagnosis causal, bind readiness claims to post-mutation exact-revision evidence, select review lenses from changed system boundaries, and use the configured delivery mode. Load the retained specialist contract only when its intent matches: - Change classification or preflight: [change preflight](../../components/development-discipline/skills/change-preflight/SKILL.md). - Causal debugging: [systematic debugging](../../components/development-discipline/skills/systematic-debugging/SKILL.md). - RED-GREEN-refactor behavior: [test-driven development](../../components/development-discipline/skills/test-driven-development/SKILL.md). - Exact-revision evidence: [verification before completion](../../components/development-discipline/skills/verification-before-completion/SKILL.md). - Final-review scope, findings, or verifier flow: [final review](../../components/development-discipline/skills/final-review/SKILL.md). - Worker or reviewer selection: [model routing](../model-routing/SKILL.md). - Failed pushed CI: [CI failure follow-up](../../components/development-discipline/skills/ci-failure-follow-up/SKILL.md). - Lifecycle-aware delivery: [delivery workflow](../../components/development-discipline/skills/delivery-workflow/SKILL.md). - Commit-message rationale: [rationale commit messages](../../components/development-discipline/skills/rationale-commit-messages/SKILL.md). - Authoring or reviewing a skill: [writing skills](../../components/development-discipline/skills/writing-skills/SKILL.md). For every final-review path, keep these fail-closed invariants visible in the working context rather than relying on a later summary. When asked how to run or complete final review, state every applicable invariant before adjacent delivery detail: - Honor every explicit baseline, path scope, and read-only boundary. Otherwise, review the pinned baseline plus every unexcluded staged, unstaged, committed, renamed, mode-changed, and untracked byte. A review-only request reports findings and never edits; remediate valid findings only when remediation was requested. - With no explicit base, use the immutable full ticket-start OID—never a newly resolved `origin/main`. For both base and explicitly uncommitted review, use the one-revision `git diff --find-renames --find-copies --end-of-options --` content surface plus separately NUL-parse `git status --short -z --untracked-files=all` as exact path bytes without display unquoting. Read in-scope untracked content, including newline-containing paths. Write the deduplicated inventory to a temporary NUL-delimited file, pass it with the full OID to `scripts/final-review-scope-hash.sh`, use exact helper stdout for plan `diff_hash` and every advance `current_diff_hash`, and delete the temporary file after each call. Reject triple-dot, index-only, bare-worktree, symbolic-baseline, and caller-invented hashes. - Use a genuine fresh-context reviewer for every applicable assigned responsibility. One complete risk-selected round is the v3 default. Additional 2–10 samples require explicit consequential high/exceptional risk, residual uncertainty, affected scope, and count rationale; exceptional dimensions need at least two. - Select production-risk-footguns for concrete deployment/resource/data-access consequences. Keep model/document, instruction, visual, tooling, and production code obligations distinct. Actual security/safety boundaries still select scrutiny. - Submit source-bound inspected dependencies and real model-role, fresh-context, post-close lifecycle attestations. Missing/forged/stale/reused evidence earns no credit. Execute the exact returned fresh pending assignments. - Freshly verify and review repaired behavior, callers, contracts, consumers, and dependencies. Retain proven unaffected receipts with original identities and current applicability proofs. Whole renewal needs concrete whole-scope impact or unisolatable shared provenance. Independent rejection/report-only disposition can retain coverage; caller defense never substitutes for adjudication. - When Tiber's opt-in final-review policy applies, explicitly require every fresh independent clean review and every substantive finding to be recorded through the durable `tiber.review.record` surface. Prose instructions, coordinator state, or an unrecorded reviewer result are not completion or delivery evidence. - For pushed work, the most recently completed in-scope build must be green. A queued or running build is only waiting, never replacement evidence, and a completed failed required job creates the CI-recovery hold. - When exceptional risk is at issue, explicitly return this complete checklist; never summarize an item away: 1. Reject an empty, unknown, or invented exceptional trigger. The only supported IDs are `destructive-or-irreversible-operation`, `authentication-or-authorization-boundary`, `sensitive-data-migration`, `cryptographic-behavior`, and `safety-critical-behavior`. 2. Require both a supported trigger and an explicitly exceptional dimension for an exceptional overall profile. 3. Keep supported triggers recorded on a lower profile when concrete mitigations keep risk below exceptional. 4. Require at least two samples for exceptional dimensions; other extra samples require explicit consequential high residual risk and justified scope/count. 5. Validate every later delta with the same supported-trigger and explicitly-exceptional-dimension rules. 6. Preserve trigger/history evidence, independently reassess affected behavior and dependencies, invalidate their receipts, and retain proven unaffected coverage. Whole-scope renewal requires concrete whole-scope impact. ## Review recovery and evidence operations For timer, completed-session, rejected-finding, or review-yield questions, read the [final-review protocol](../../components/development-discipline/skills/final-review/references/mcp-protocol.md) before choosing or explaining a recovery. Name the supported operation and its required evidence; a generic instruction to continue or start over is insufficient. When explaining a completed-session reopen, explicitly name preservation of the baseline, history, and unresolved obligations as well as the clean-credit reset. When a yield question supplies no scope or evidence references, label its counts provisional and request the actual report and evidence; never invent identifiers or source-change facts to complete a report. - After a 75-minute checkpoint, use `final_review.continue_review` with the authoritative `state_ref`, a stable `operation_id`, and concrete progress rationale. Retry the exact request after a lost response. It preserves the original start, unresolved blockers, recorded coverage obligations, and failure holds. Resolve a legacy escalation with its concrete recovery reference. A locked signer blocks signing; continue independent authorized work and never bypass its signature gate. Elapsed time alone needs no human permission. - For a required source change after completion, use `final_review.reopen` with the authoritative `state_ref`, stable `operation_id`, reason, current scope hash, complete changed-file inventory, and fresh bound test evidence. Preserve baseline, history, and unresolved obligations; suspend completion, obtain independent delta assessment, and renew affected coverage while retaining proven peers. V2 keeps its recorded full-reset policy until migration. - For independent adjudication of a new ordinary disputed finding, include `verification_requests` with its exact `finding_id` and `lens` on the initial `final_review.advance`. Run the returned fresh verifier and preserve its frozen targets on a full resubmission; compact restart recovery uses retained targets. Unknown or reused-rejection targets cannot bypass evidence-backed reopening. - Give reviewers retained rejection rationale, concrete evidence, verifier provenance, and reviewed scope. Match exact finding/lens identity rather than wording. An unsupported repeat is a non-clean duplicate without renewed escalation. A challenge needs `resolution_reopen`, new contradictory evidence, relevant source change, or a demonstrated verification gap, plus an explicit explanation of why the prior resolution fails and independent adjudication. Unrelated documentation changes preserve source-bound evidence. Reopened allegations also remain non-clean. - Use `final_review.yield_report` and inspect its references with `final_review.evidence`. Separate actual completed rounds from iteration and delta/reset bookkeeping, and raw allegations from confirmed, duplicate, rejected, reopened, and verified-repair outcomes. Bind every count to its reviewed scope and whether source changed between rounds. Missing evidence is unavailable, not zero; request the evidence rather than inventing counts. Clean rounds supply required scrutiny and never lower review policy. When a `final_review.plan` handoff is truncated, recover it instead of replanning. Call `final_review.pending_assignments` with the retained `state_ref`; its compact summary is authoritative for every pending lens, verifier, or delta-risk assignment, including the exact `subagent_key`, exact `model_role`, phase metadata, close policy, result-schema version, and the phase-specific assignment identity and evidence references. Pass one exact `subagent_key` back to that tool to retrieve only that assignment's original durable prompt and schema. An incomplete `final_review.resume_latest` returns the same compact summary. Supply `work_item_id` when the original review was ticket-bound, and never mix a session, project root, work item, or fingerprint from different handoffs. These retrievals are read-only and idempotent: they append no event, change no revision, fingerprint, scope, or hash, and never reassign a lens or role. If a pre-upgrade pending verifier or delta-risk record lacks recoverable assignment facts, follow its explicit `recovery=restart_final_review` guidance; never reconstruct it from partial projection state. A missing or invalid lifecycle/model attestation earns no credit. Execute the actual returned fresh pending scope; never repair or re-credit an invalid assignment. V3 retains independent valid peers and replaces malformed adjudication over frozen targets. Shared provenance compromise invalidates all dependent coverage. V2 retains its original reset rules until explicit migration. The pinned ticket-start Git baseline plus in-repository paths, contents, modes, and untracked inventory define reviewed source scope. Coordinator events, snapshots, state files, and projections are bookkeeping outside that hash. After terminal source review, a content-identical commit does not reopen review merely because HEAD, staging partition, signature, or commit metadata changed. Real path, content, mode, untracked-content, pinned-baseline, or requested-scope changes do reopen it. The terminal sequence is verified local checkpoint, proportional independent increment review before trunk push, or full review before PR readiness, then exact-SHA post-push readiness evidence. A clean unchanged review adds review evidence only. Pushed readiness requires terminal-success CI for the exact final-reviewed SHA; pending CI is `review-complete-awaiting-exact-sha-ci`. Source-changing remediation creates a new mode-specific checkpoint and resets review as described above. Load `delivery-workflow` before the first implementation or test increment so the configured delivery mode and green-increment preservation cadence are known before even a standalone test edit, commit, or push. After final review, recheck it only to confirm that the reviewed identity is published only as authorized and has the required exact-SHA CI or local readiness evidence; a clean unchanged review creates no additional commit. ## Structured lifecycle The plugin exposes structured `final_review.*` coordination. Use ordinary host tools for authorized repository changes and verification, and follow the RED-GREEN-refactor, exact-evidence, review, and delivery guidance in the specialist contracts above. Do not claim that plugin instructions, hooks, or final-review records enforce harness capabilities or authorize external actions. Installed Tiber task transitions enforce the separate opt-in `[final_review].minimum_clean_reviews` completion and trailer-delivery policy. They do not enforce editing, execution, or the host's development lifecycle. Before a new task, inspect forge CI. Require a successful completed run for the candidate revision; queued/running is not terminal evidence, and any completed failed required job activates a repository-wide hold. Use Tiber's single CI-recovery owner and record SHA, run, checks, and terminal status. Development Discipline reads that Tiber hold when gating delivery; it does not own one. For direct-to-trunk CI failure with WIP, use the [trunk recovery protocol](../../components/development-discipline/skills/ci-failure-follow-up/references/trunk-wip-recovery.md). Keep one serialized trunk checkout, retain the exact stash OID and recovery record, account for unpublished commits separately, and verify staged/untracked restoration before dropping the matching stash. Conflict resolution renews focused tests and affected review; it does not earn automatic passing credit.