---
name: release-completion-workflows
description: Complete bounded implementation sprints through acceptance evidence, local commits, and explicitly scoped publication actions.
---

# Release Completion Workflows

## Trigger
Use for a user-authorized bounded sprint or release where the terminal condition is a working, verified local artifact and often a local commit, push, or deploy decision.

## Core operating rule
A user’s terminal completion condition remains active across worker failures, partial test successes, reviews, and interim status updates. Treat those as internal events, not terminal outcomes. Do not send a final response that merely lists next steps while the task is still actionable.

For transactional financial-source releases, also load `transactional-data-release-engineering`, especially `references/financial-source-onboarding-and-zero-row-guards.md`. It contains the source-truth/saldenketten contract, private manifest and backup rules, runtime dependency-closure gate, and productive read-only Preview → hard Confirm-stop evidence.

For sensitive extracted-candidate Preview → Confirm workflows, use `references/controlled-sensitive-candidate-review-release.md`. It requires mandatory worker-side preview-digest recomputation (missing is rejected, not optional), allowlisted nested preview/provenance projections, explicit source/date/unit/operator/qualitative/duplicate semantics, adversarial bypass tests, and frozen-base reproduction before touching unrelated legacy regression tests.

For browser Preview → Confirm actions with a dedicated mutation-domain CSRF contract, use `references/preview-confirm-csrf-release-gate.md`. It covers authenticated CSRF acquisition, non-consuming preview, frozen payload/revision/token state, mutation invalidation, consuming confirm, and browser evidence that executes the real preview request while proving DB and queue remain unchanged.

For historical annual actuals and deterministic current-year comparisons, follow `references/prior-year-actuals-and-deterministic-forecast.md`. It covers absence-versus-explicit-zero storage, batch Preview → Confirm → Audit, complete-total comparison semantics, reproducible rounded forecast operands, API nullability, stale-request protection, and focused financial/browser probes.

When the sprint is defined as one complete vertical PR, follow `references/vertical-fullstack-sprint-delivery.md`: backend, API/UI, release gates, responsive UAT, one final review, documentation, commit, push, and remote verification are internal phases—not separate user approval stops.

## Sensitive post-action preflight
When a release begins by validating a user-completed queued action on productive sensitive data, follow `references/sensitive-post-action-readonly-preflight.md`. It defines fail-fast read-only database/audit/queue/worker checks, correct cross-table audit binding, narrow semantic normalization, projection sequencing, and aggregate-only failure reporting. Any duplicate, queue residue, or structured-contract inconsistency stops all later implementation and release phases.

## Fresh-session closeout mode
When the user asks to finish an existing uncommitted release in a fresh session, treat the working tree as the implementation source of truth. Do not reset, stash, redesign, re-analyze the repository, restart the sprint, or repeat already-green work. Start with only `git status`, `git diff --check`, and an expected-path check; then run exactly the requested changed/new tests and static checks once. On failure, diagnose one concrete cause, make one targeted correction, and rerun only the invalidated check. Preserve the remaining runway for migration, backup, reconciliation, commit, push, deployment, and one read-only smoke. If the user prescribes final report fields, return only those fields and stop—do not append a retrospective or propose the next sprint.

For a strict one-commit closeout, keep publication verification commands causally separated: a successful `git push` remains successful even if a later fetch/check in the same shell fails. Keep temporary Askpass credentials available through any authenticated fetch used for remote verification, remove them afterward, and verify local `HEAD`, the tracking ref, and clean status without exposing the secret. Before creating that sole commit, stage the exact runtime candidate and run the private-route readiness smoke against the real listener/proxy topology—not only loopback or a synthetic server. Include browser bootstrap concurrency (`response >= 400`, `console.error`, `pageerror`), actual Serve/reverse-proxy target and port, service interpreter, and protected fallback hash. Static catalog endpoints that are serially green may still fail under parallel first-load requests; deduplicate identical browser requests or prove bounded concurrent success before publication. This pre-publication smoke prevents a post-push amend/force-update merely to repair runtime routing or bootstrap races.

## Visual-only dashboard release mode
When a sprint explicitly freezes database, medical, and data-source contracts, enforce that boundary through an expected changed-path set and a short added-lines diff scan for SQL DDL/DML, canonical medical writes, external URLs, and disallowed chart loaders. Verify the deployed base by comparing runtime files with Git blobs before deciding whether a base redeploy is needed; do not rerun the previous sprint merely because the next presentation sprint starts.

For generated browser fixtures, align the rendered `today` with the fixture anchor before the one focused browser run. A date mismatch can put every valid series outside the active period and falsely present as broken charts. For an ECharts-only contract, verify actual ECharts instances, `window.Chart` absence, resource-level Chart.js absence, genuine gaps, exact metric-ID drill-down, 390 px overflow/touch targets, and reduced-motion behavior. Personal baseline bands may use only observed baseline values; laboratory bands still require observation-specific verified references.

## Workflow
1. **Freeze the agreed scope.** Record explicit exclusions, protected surfaces, and API/data contracts. Do not broaden the task because a worker stalled.
2. **Secure current work.** Inspect status/diff before further edits. Preserve previously green contract coverage; only rerun tests whose covered files or assumptions changed. Keep focused releases reviewable: do not run a whole-file formatter across large legacy modules merely because a few sections changed. Format new files and touched regions where tooling permits, inspect `git diff --stat` before final review, and reduce accidental formatting churn before tests/commit rather than carrying thousands of unrelated line changes into the release. If semantic work must be transplanted back onto the original formatting, compare parsed function/assignment bodies and rerun every affected gate afterward.

   **Pre-commit candidate completeness:** `git diff --stat` and `git diff --check` omit untracked files. Build the candidate set from tracked changes plus `git ls-files --others --exclude-standard`, compare that exact set with the approved paths, and inspect a combined full diff that includes every untracked file. After staging only those exact paths, run `git diff --cached --check` and inspect `git diff --cached --stat`/`--name-status` before committing. A green unstaged `git diff --check` is not sufficient evidence for a candidate containing new files.
3. **Use workers as optional accelerators, but consume their gates.** When a worker fails or reaches limits, inspect/retain any changes, then continue in the primary agent. Do not repeatedly resume an exhausted session. Respect a user instruction to stop delegating. If a worker was assigned a release-gating review, read its complete result before claiming that review passed, committing, pushing, or deploying. Never replace a still-outstanding delegated verdict with an informal primary-agent assumption; if the result arrives after a commit, remediate in a separate fix commit and invalidate/re-run affected final gates.

   **Keep final reviewers verdict-oriented and time-bounded.** When full suites and aggregate gates already ran on the exact immutable candidate, tell reviewers not to rerun them. Give each reviewer a narrow list of known findings/counterexamples, permit only focused probes, and require a concise P0/P1/P2 verdict well before the worker timeout. A timeout trace is evidence, not a verdict: inspect it completely, consume any reproduced finding, fix it separately, and dispatch one narrower re-review rather than treating timeout as PASS or launching another broad release audit.

   **Maintain an asynchronous review supersession ledger.** Record each review's dispatch tree/generation, returned findings, the exact repair that consumed each finding, and the focused evidence for that repair. Delayed verdicts are evidence about the tree that existed at dispatch time, not automatic verdicts on the current candidate. When older results arrive after newer repairs or a newer exact-tree `0/0/0`, map every old finding to its repair/test before marking it superseded; do not reopen fixed findings merely because their notification arrived late, and do not ignore an old finding without that trace. Only a verdict explicitly bound to the latest immutable candidate can serve as the release gate.

   **Close every dispatched review before declaring or publishing the release.** A newer `0/0/0` does not cancel an older still-running review unless every issue that older review was assigned to inspect is represented in the supersession ledger with direct code/test evidence. Before commit/merge, inventory all dispatch IDs from the session and require each to be terminal (`completed`, explicitly cancelled, or timed out with its full transcript consumed). Do not treat a timeout without a summary as empty evidence: inspect the transcript for reproduced counterexamples and unfinished findings. If a delayed review arrives after deployment, verify each finding against the exact merged SHA and the actual schema/API contract rather than against the review's age or stated base. A real latent defect requires a normal follow-up branch, focused regression, full affected suite, independent review, CI, merge, exact-SHA redeploy, and a repeated no-write sentinel; never patch the deployed worktree directly.

   **Bind verdicts to the actual dirty candidate, not only `HEAD`.** When review happens before commit, `HEAD` identifies only the base and can make a correct verdict look bound to the wrong tree. Record the base SHA plus an exact candidate manifest covering tracked modifications and untracked files, and a deterministic digest of the reviewed content/diffs (or review the staged index and record its tree hash). Before committing, prove the staged candidate matches that reviewed identity; after commit, prove the commit contains the same candidate. A reviewer statement such as `HEAD=<base>` is insufficient release evidence unless paired with this dirty-tree identity.

   **Schema-check derived SQL in read models.** For new or heavily changed read-model SQL, compare every selected column with the canonical migration/runtime schema (for SQLite, `PRAGMA table_info`) and add an adversarial fixture that actually activates each conditional query branch. A broad green suite can miss a nonexistent column when ordinary fixtures return before that branch. When deriving base-currency values, use stored original value/currency/FX columns and test both same-currency and foreign-currency paths; do not assume a convenience column exists because a service object exposes an equivalent computed property.
4. **Make the smallest vertical repair.** Work from a reproducible failing acceptance test. For browser features, validate the complete synthetic path: fixture, generated view, server, browser session, API, and interaction. Before implementing UI filters or deep-link restoration, determine whether the existing bounded API can satisfy the behavior truthfully. If pre-limit API semantics must change and the sprint requires advance notice, report that boundary before editing rather than silently filtering only page 1 or widening scope.
5. **Avoid test-only false confidence.** A test change may fix a stale expectation, but must not downgrade a stated visible acceptance criterion. Verify the product behavior independently before accepting it.
6. **Bound repeated repairs causally.** Count attempts against the same diagnosed cause, not every failed rerun. A selector correction and a later product-state fix are different causes. After two unsuccessful cause-directed repairs of the same concrete behavior, stop and report the file, test, exact failure, both causal attempts, and the minimal remaining path.
7. **Run acceptance in order.** Run focused contract/security/browser tests while implementation is changing. Before the one-shot browser matrix, verify that every spec is assigned to the complete generated feature profile it asserts; a partial subflag is not a valid host for a full-preview spec. Do not run the one-shot full suites until no further product or test changes are expected. Then run exactly one full Python suite and one full browser suite, followed by the requested static syntax/lint/diff and review gates.

   **Require terminal test evidence, not process disappearance.** A test process no longer appearing in `ps` is not a green result. For every full gate, retain the command exit status and require the framework's terminal summary (for example `N passed` plus elapsed time). A progress-only log that stops at `54%`, `68%`, or any other partial point without a traceback or summary is an abnormally incomplete gate: classify it as release-blocking but not yet as a product regression. If output is piped through `tee`, use `set -o pipefail` and preserve the shell's final status; do not infer that later chained typecheck/build commands ran merely because the wrapper disappeared. One clean replacement run is appropriate after verifying the candidate is no longer changing; if that also lacks terminal evidence, stop rerunning and report the gate as incomplete with the last observed progress.

   **Separate contract readiness from release readiness.** In acceptance matrices, a focused regression may mark an individual business contract `PASS`, while full suites, browser UAT, hosted CI, exact-SHA deployment, or productive no-write/idempotency sentinels remain pending. Report these as separate release blockers rather than downgrading proven contract behavior or overpromoting the overall candidate. Bind the matrix to a final status/diff/untracked-file reread because a concurrent workflow/test-collection edit invalidates an earlier frozen-candidate claim.

   If the release contract also requires an aggregate command such as `make verify` that repeats those heavy suites, run that aggregate command by itself rather than beside CPU-intensive lint/scans; parallel resource contention can create misleading frontend-hook or worker timeouts. If code or tests change after a full suite *before* the final review, the release is no longer backed by that suite; avoid entering that state by stabilizing first. When the governing sprint contract explicitly requires exactly one final review after the full suites, a narrow review/UAT fix may instead be verified with the affected focused tests plus all relevant release gates; do not rerun every full suite unless the finding crosses broader contracts or the user requires it. Record this ordering truthfully. If a broad legacy suite has one apparently unrelated failure, reproduce that exact test at the frozen base SHA in a temporary detached worktree. A base-SHA reproduction proves only that the regression is pre-existing: report it separately, keep the current suite truthfully non-green, and proceed only when the agreed release contract permits focused gates despite that inherited failure. Never silently edit the stale test or count the broad suite as passed.

   **SQLite and time-isolation trap:** Verify that helpers receiving the literal `":memory:"` pass it directly to `sqlite3.connect`; converting it through `Path` creates a real file named `:memory:` and lets state leak across test connections or runs. Before trusting a local/CI discrepancy, check for that artifact and prove two literal in-memory connections are isolated. Also ensure tests that query records created at runtime do not use a fixed `data_cutoff` that has moved into the past. Use a monkeypatched clock or an explicit future test cutoff, while keeping product as-of dates fixed. After correcting either isolation contract, rerun the formerly failing focused test and the full suite because previously green results may have depended on leaked state.

   **Split-branch baseline repairs:** Before creating independent feature and test-baseline branches from a common parent, run the full suite on that exact parent and freeze the complete failing-test manifest. Do not infer the parent’s failure count from a feature branch whose test edits may already mask failures. If the requested repair count, branch ancestry, non-overlap requirement, and green-suite terminal condition cannot all hold simultaneously, make no repair edits until the branch topology is clarified. Offer explicit alternatives: keep branches independent with inherited failures, make the repair branch depend on the feature commit, or accept overlapping fixes. Once topology is resolved as baseline-first, preserve the original feature commit under an explicit backup ref, commit a green test-only baseline, then rebuild the feature branch from that baseline with a no-auto-commit three-way transfer. Prove that incidental baseline repairs are absent from feature-v2 at the hunk/signature level; shared file paths alone do not imply duplicated PR content.

   See `references/test-baseline-feature-restacking.md` for the full backup-ref, exact-base reproduction, deterministic test repair, no-commit transfer, hunk-ownership, blob-comparison, audit-correction, and verification recipe.
8. **Reserve the release runway and freeze migrations.** Before late-stage polishing, preserve enough execution budget for final review → copy-first migration on the frozen schema → commit → push → deploy/restart → controlled pipeline → read-only smoke → runtime/fallback hashes → clean status. Batch independent checks and stop nonessential exploration when it threatens that runway. Set an explicit final-quarter cutoff: once reached, permit only release-blocking fixes and their invalidated gates; do not add speculative features or launch another broad review loop. When the runtime exposes a hard tool-iteration cap, count the remaining release side effects before dispatching any reviewer: reserve calls for commit, push, PR/CI, merge, exact-SHA deploy, service/DB smoke, and final evidence. If a review transcript truncates its verdict, request at most one concise verdict-only re-review; consume it before editing further, and checkpoint into a fresh session before the cap rather than starting successive review loops. If the remaining execution/tool budget cannot cover the terminal gates, create a precise continuation checkpoint and continue in a fresh session before the hard cap forces a non-terminal final response. Never launch an aggregate/full-suite process while a worker, reviewer, or primary edit can still change its worktree; evidence from a moving tree is invalid even when the process exits green. Never treat `CREATE TABLE IF NOT EXISTS` as an upgrade: if a private database was migrated before the schema/worker/CHECK contracts froze, add an explicit idempotent in-place upgrade, take a fresh backup, and rerun copy/idempotency/integrity/FK/restore gates before release.
9. **Keep generated runtime evidence fresh.** After renderer, fixture, JS, CSS, schema, or feature-profile changes, regenerate the synthetic HTML/DB as applicable, recopy runtime assets, and restart the isolated server before browser evidence. An updated API behind stale copied assets is a fixture/runtime freshness failure, not proof that the current UI is broken.
10. **Keep executing through the terminal state and require blocker provenance.** When the user explicitly requests uninterrupted execution, a progress message is never a handoff or stopping point. Continue tool work in the same task until verified completion or the specified reproducible blocker condition. Never infer a timeout from elapsed wall-clock time, unfinished work, context pressure, or ordinary test failures. A technical blocker requires an actual tool/provider/gateway/runtime timeout, cancel, exception, or error event with a concrete cause. If timeout provenance is disputed, inspect the persisted session event sequence and relevant gateway log/code: a normal `assistant` message following successful tool calls means the model chose to stop, not that the runtime timed out. Distinguish gateway inactivity timeouts from wall-clock limits, and do not recommend changing timeout configuration without both the resolved active value and a matching timeout event.
11. **Create evidence and commit.** Record only non-sensitive commands/results, changed paths, synthetic screenshots if required, deferred scope, and privacy confirmation. Distinguish automated tests from review-only conclusions. Before freezing the candidate, inspect CI workflow assertions for hard-pinned test counts or names. Exact equality such as `667 passed` is fragile because the next legitimate test addition forces another workflow edit. Preserve the test process exit code as the primary failure gate; if deletion protection is required, parse the summary and enforce a stable minimum such as `passed_count >= frozen_floor`, failing when the count cannot be parsed. Never weaken the floor or skip tests merely to make CI pass. Treat any workflow edit as part of the reviewed release candidate. Verify clean status after a local commit. Push/deploy only under the latest explicit authorization; a later “do not deploy” overrides an earlier deploy approval. **For a coupled exactly-one-commit → push → deploy release, prove write permission to the exact remote before creating the sole release commit** (for example an authenticated repository-permission query or a no-op/dry-run push against the intended branch). Read access, an unrelated generic PAT, or a token-looking environment variable is not write evidence. If write permission is unavailable, stop before the commit so the release can resume without violating the one-commit contract. **When the release also adds or changes `.github/workflows/*`, ordinary repository write access is insufficient:** preflight workflow-file authorization separately before finalizing the integration commit. Repository `admin`/`push` metadata, an empty `X-OAuth-Scopes` header, and a content-blind `git push --dry-run` are all inconclusive; the behavioral probe must actually attempt an authorized workflow-file write against the exact repository. Perform that probe before coupling all implementation work into an exactly-one-commit release. If automatic PR-CI is mandatory and GitHub rejects that workflow push, preserve the local branch/commit and stop; do not remove or relocate CI merely to publish a partial branch. Treat legacy `without workflow scope` wording as a possible credential-source mismatch before concluding that a canonical fine-grained PAT lacks permission: inspect repository/user/system helpers, embedded remote credentials, `gh auth`, and token-variable names without exposing values; compare `git credential fill` with the canonical token only as a boolean equality; then make at most one helper-bypassed push using a temporary mode-`0700` Askpass that reads a short-lived variable loaded from the canonical mode-`0600` file. Fine-grained **Workflows: Read and write** is sufficient even when GitHub uses classic-scope wording. Preserve owner-only recovery material (for example a `git bundle` plus SHA-256, mode `0600`) when a credential blocker strands local release commits. A committed evidence file cannot self-contain its own literal commit SHA; use an honest symbolic `git:HEAD-after-release-commit` marker and verify/report the literal SHA after commit and push. For confirmation-gated service operations, keep build/staging, stop/migrate, and restart as distinct phases, state the exact service action, and obtain direct consent immediately before it; do not bury `systemctl restart` or `systemctl start` inside a long compound deployment-and-healthcheck command. Run the confirmation-gated service action in its own tool call, then perform healthchecks separately. If a frontend unit is a Vite/static preview reading the build directory in place, stop it before `npm run build` or runtime asset replacement; rebuilding the live `dist` can fail the unit or briefly expose a partial asset set. A process supervisor may report the npm wrapper exited while its shell/node child still owns the listener. After every temporary-server stop, verify both the bound port and descendant process tree are gone before rebuilding or reusing the port; terminate the authorized tracked process group rather than trusting wrapper status alone. Build after stop, verify the output, then restart. A listener probe issued immediately after `systemctl start` can race process readiness, and a trailing `grep` exit can make an otherwise successful compound command look failed; inspect unit state and startup logs before diagnosing the deployment. Private-IP/Tailscale HTTP probes may independently require network approval, so keep them outside the service-action command. Run consent-sensitive probes one per tool call: do not combine loopback health, private-IP/Tailscale UI, or authenticated business smokes in one shell command, because a block on one probe can obscure which earlier checks actually ran and invalidate otherwise useful evidence. If the execution layer returns an explicit blocked/no-consent verdict, do not retry or route around it even when an earlier broad deploy authorization exists; report the exact blocked probe and the independently verified database/code/service state, then pause all remaining merge/deploy side effects. A later background-process completion notification (for example green CI) is release evidence, not renewed consent: consume its terminal result, but require a direct user reply before resuming the blocked side effects.
12. **Handle explicit release exceptions truthfully.** If a user knowingly accepts a narrow non-security/non-medical blocker after the normal stop threshold, ask for an explicit choice, preserve the failed test/review and both repair attempts in evidence, mark it `failed_exception_accepted`, and identify earlier full-suite results as belonging to the previous candidate. Do not relabel the gate as passed. Make a separate fix commit rather than amending an earlier reviewed commit, then publish/deploy only the exact accepted scope. Authentication, privacy, data-trust, and medical-safety failures remain blockers unless the governing policy itself is explicitly changed.

## Browser-specific checklist
- Feature flag default state is testable and explicit.
- New scripts/assets load only in the intended scope; legacy UI and its fallback remain untouched.
- Locally vendored assets are tested under the actual CSP after initialization: zero external requests is not enough. Fail on `console.error`/`pageerror`, inspect injected CSS/fonts/data URIs, and compute integrity metadata only after the final deterministic transformation.
- Browser-delivered HTML, JavaScript, URLs, logs, cookies, and persistent storage contain no reusable bearer/basic credential. Transport-level HTTP authentication may be used for a private sensitive preview, but configure it through the browser context (for example Playwright `httpCredentials`), verify unauthenticated `401` and authenticated `200`, and never put credentials in the URL or generated page. If a temporary human-friendly browser password is requested, keep it in a separate owner-only file and preserve the strong bearer/API token; never weaken the bearer token merely to simplify the Basic-Auth dialog.
- Synthetic server fixtures use private runtime files and non-production data.
- Browser UI tests navigate to the actual parent tab/view before interacting with child controls.
- Generated dashboards may retain hidden dialog controls in the DOM. For capture/open-close smokes, first activate the visible launcher, then scope child selectors to `:visible`; never click the first global `[data-*]` match merely because it exists. Open the form, close without submit, and bracket the probe with production-DB and action-queue sentinels.
- Treat locator-derived evidence as page-bound. Capture counts and labels before navigating to another route; querying the same locator after V4 or another page loads can return a misleading zero. Emit only aggregate results, and when diagnosing selectors inspect role names or attribute names without dumping all visible labels from a sensitive production page.
- When dialogs/drawers use Vue `Teleport`, component-wrapper queries may falsely report missing UI even though it rendered under `document.body`. Mount with a real document target or query the teleported DOM directly; click the real semantic button carrying the test selector, not a non-semantic table row/card wrapper. Preserve keyboard/focus behavior rather than restoring wrapper click handlers merely to satisfy stale tests.
- For read-only production UAT, bracket page loads and preview-only probes with both a material business digest and strict side-effect sentinels (`updated_at` hashes plus ingestion/snapshot counts). Validate the changed deep section at desktop/tablet/mobile widths; no horizontal overflow does not excuse unreadable per-digit card wrapping. Measure `scrollWidth - clientWidth` at each viewport and, on failure, enumerate only the overflowing elements' tags/test IDs/classes and bounding boxes—never their sensitive text. For Chromium CDP responsive checks, prefer an exact CSS viewport width with touch emulation enabled separately; `mobile=true` can alter the layout viewport and produce misleading dimensions. Grid/flex cards containing long financial labels commonly need `min-w-0` on both the grid container/item and `w-full` on the item. Wait for an explicit ready state before screenshots, verify console evaluation still targets the intended URL, and delete sensitive production screenshots after extracting aggregate evidence.
- A production UAT finding after a green merge is a new release candidate, not permission to patch production directly. Make the smallest branch commit, rerun the affected full suite/static gates, publish through a follow-up PR and full CI, merge normally, deploy the new exact remote-main SHA, and repeat the complete responsive UAT. Report both PRs and the final deployed merge SHA.
- Time-window fixtures use server-authoritative or fixed fixture dates; do not accidentally rely on the browser’s wall clock.
- When an API response works but the UI is hidden, inspect selector multiplicity, parent visibility, `hidden` state, and the feature-flag state before changing contracts.

## Isolated browser-suite matrix
When historical browser specs require incompatible generated pages, flags, queues, or auth setup, a monolithic run against one server is invalid evidence. Classify each failure first as wrong fixture/server mode, stale test contract, or product regression. Then run a small sequential matrix where every group gets a fresh private temp directory, fixture DB, random loopback port, token/queue files, process-local environment, `--workers=1` when state is shared, and reliable teardown. Typical groups are standard UI, capture queue, feature prototype, auth/session, and the current flagged feature. Aggregate the independently green groups as the full browser acceptance.

Do not reintroduce an obsolete authentication path merely to satisfy a historical spec. Update the spec to the approved current contract and explicitly verify absence of credentials in HTML, JavaScript, URLs, and browser storage.

## Gated API-feature ownership
For server-gated browser features, make the renderer authoritative: the explicit generator flag must emit the enabled DOM marker and feature-only assets. The disabled page must omit those assets and make zero session/API requests; do not keep a query-string bypass as the normal activation route. Assign browser-session bootstrap to exactly one client component and acceptance-test one bootstrap per load across repeated sequential loads.

For interactive async views, protect against stale responses with a monotonically increasing refresh generation. Also remember that a microtask queued by a target listener may run before an ancestor bubble listener has finalized shared ARIA/state; prefer a single state owner or defer beyond the complete event dispatch. Verify the resulting chart contract, not just button state.

Medical chart bands require a separate contract: a global band is valid only when every observed point has the same verified `(min,max,source)` range; changing ranges need observation-bounded segments, and `missing_reference` must never create a band. Personal baselines remain distinct from laboratory reference intervals.

See `references/read-only-production-uat-and-responsive-evidence.md` for production-safe preview-only probes, MagicDNS/Tailscale checks, material plus strict no-write sentinels, async-ready responsive evidence, truthful visual findings, and sensitive-screenshot cleanup.

See `references/webdriver-http-responsive-production-uat.md` for a dependency-free Chromium/ChromeDriver W3C-HTTP fallback, privacy-safe responsive evidence, all-table SQLite no-write bracketing, and interpretation pitfalls for internal table overflow, query-bearing routes, CSS viewport dimensions, and heuristic touch-target findings.

See `references/responsive-cdp-overflow-and-followup-pr.md` for exact CSS-viewport CDP checks, privacy-safe overflow localization, grid/flex shrink fixes, and the mandatory follow-up PR/CI/redeploy loop for defects discovered after the first merge.

See `references/release-runway-schema-freeze-and-runtime-freshness.md` for preserving terminal-step execution budget, freezing additive schemas before private migration, upgrading already-created intermediate tables safely, and invalidating stale generated browser runtimes after renderer/asset changes.

See `references/read-only-preflight-and-schema-capacity-gate.md` when a sensitive workflow needs durable corrections or state separation but migrations require a prior stop-and-report. It covers sentinel-bracketed synthetic UI probes, semantic-capacity inventory, anti-shortcut rules, and the minimal additive proposal/approval gate.

See `references/sqlite-production-guarded-release.md` for fail-closed `/tmp` test/UAT isolation before collection, accidental-migration diagnosis and one-time rollback discipline, DB-touching service probes, copy-first SQLite deployment, localhost-gated Tailscale proxy topology, and logical post-start evidence.

See `references/review-driven-financial-hotfix-release.md` for immutable-import read-model hotfixes, local-date/cutoff semantics, post-snapshot holdings-and-cash replay, complete iterative review consumption, GitHub workflow-run API fallback, coherent online SQLite backup/restore evidence, exact-SHA deployment, and route-discovered UAT.

See `references/sequential-financial-dashboard-provider-release.md` for ordered multi-PR financial releases, exact merge-tree deployment, dedicated loopback-only provider dry-runs under write-disabled UAT, hash-proven no-write evidence, market-operation mutexes, and truthful mutation-versus-reload outcomes.

See `references/stacked-branch-integration-gate.md` for linear ancestry proof, exact-tip integration branches, mandatory GitHub workflow authorization, one-PR CI, history-preserving merge, and deployment of the verified remote-main commit.

See `references/workflow-authorization-and-sensitive-release-artifacts.md` for behavioral workflow-scope preflight, hard-pinned CI-count audits, owner-only Git-bundle recovery, isolated aggregate gates, and the private-runtime-versus-tracked-evidence split.

See `references/aggregate-gate-and-pinned-toolchain.md` for reproducing exact CI-pinned lint versions, inspecting hard-coded Makefile executables, running repeated aggregate gates in isolation, and preserving truthful status when the execution layer explicitly blocks a required command.

See `references/tracked-release-gate-inventory.md` for read-only inventories of tracked Make/package/CI/test/restart gates, truthful collected-versus-executed test counts, stale floor detection, untracked-candidate checks, and separating restart scripts from real deployment automation.

See `references/runtime-listener-identity-and-supervisor-deployment.md` before exact-SHA production deployment on multi-application hosts. It covers listener ownership, systemd/container discovery, deployment-worktree identity, misleading health responses from unrelated listeners, supervisor auto-restarts, bind/CORS/proxy topology, and identity-aware post-deploy proof.

See `references/feature-flags-session-and-chart-contracts.md` for the concrete activation, race, session, and reference-band acceptance pattern.

See `references/visual-dashboard-design-release.md` for presentation-only scope guards, contextual headers, Today/Cockpit acceptance, ECharts-only checks, fixture-date alignment, responsive/reduced-motion gates, and authenticated private visual smokes.

See `references/read-only-record-pagination-and-streaming.md` for FTS document-level keysets, NOCASE cursor symmetry, chronological comparisons, paginated viewers, history/race control, nonblocking descriptor streaming, and honest test-vs-review evidence.

See `references/strict-csp-vendored-browser-assets.md` for runtime-injected CSS/font/data-URI detection, CSP-clean browser gates, deterministic post-processing, integrity metadata ordering, and published-commit follow-up discipline.

See `references/private-media-runtime-release-gates.md` for exact service-interpreter/dependency preflights, fail-closed local media validation, copy-first private migrations, canonical medical diffs, protected fallback hashes, and read-only synthetic/live smoke discipline.

See `references/parallel-production-preview-deployment.md` for two-commit preview releases, regeneration-profile symmetry, SQLite-safe rollback backups, atomic runtime installation, fallback checksum invariants, token-file-backed Git publication, authenticated private smokes, aggregate-only real-data probes, and approval-gated service operations.

See `references/unified-state-and-private-smoke-recovery.md` for metadata-only live API reproduction, single-owner browser state, route-parser namespace isolation, server-day synchronization, profile-aligned browser matrices, and safe private-smoke accounting.

See `references/navigation-record-and-runtime-smoke.md` for exact metric-ID drill-down, history-entry normalization and duplicate-push prevention, per-tab filter allowlists, real-endpoint document acceptance, readable calendar events, readiness-aware private deployment, and screenshot-artifact cleanup.

See `references/master-detail-state-and-bounded-review-lists.md` for durable mobile/list routes, exact queued-action identity, independently rendered single-item editors, out-of-page deep-link resolution, fail-closed classification, and truthful page-local filtering under frozen API semantics.

See `references/temporary-private-preview-basic-auth.md` for separating a temporary human-friendly Basic password from the strong bearer token, owner-only configuration and rollback, browser-session verification, and truthful live-vs-synthetic privileged-action smokes.

See `references/final-remediation-verification-review.md` for read-only re-review of previously reported findings using exact-tree inspection, end-to-end contract tracing, dimension-by-dimension provenance probes, authoritative cutoff checks, nullable/stale aggregate semantics, empty-set regressions, and concise blocking verdicts.

See `references/period-bound-financial-readiness-release.md` for separating current value, freshness, reconciliation, performance readiness, and policy; enforcing exact selected-period boundaries; runtime/OpenAPI response contracts; source-specific freshness; null-safe monetary UI; exact-tree re-review; and read-only sentinel-backed deployment evidence.

See `references/frontend-api-contract-release-review.md` for independent frontend/API contract reviews covering visible-label-to-database semantics, enum matrices, KPI provider truth, direct-load URL persistence, runtime-DOM privacy probes, and dependency-free responsive Selenium evidence. When the UI exposes scheduler/provider/run health, pair it with `references/operational-status-projection-review.md`: keep latest-attempt, latest-success, and scheduler/source epochs separate; require coherent counters, all-state probes, explicit status-fetch failures, timezone checks, responsive browser evidence, and proof that ordinary dashboard loads do not invoke providers.

For an independent, snapshot-bound acceptance and P0/P1/P2 risk matrix while implementation is still evolving, follow `references/independent-acceptance-risk-matrix.md`. It covers golden-case mapping, legacy-vs-new evidence separation, preview/confirm schema tracing, transaction ownership, deduplication lineage, migration digests, sensitive-data boundaries, and package-relative frontend test invocation.

For financial inbox releases that replace classification-group actions with single-item duplicate decisions, credit-card settlements, or confirmed-transaction category corrections, also follow `references/single-item-financial-correction-review.md`. It adds sibling-row non-mutation probes, complete item capability binding, durable duplicate/reopen and settlement semantics, canonical aggregate tracing, explicit previous-schema migration gates, CI count-floor audits, and browser-backed 1440/820/390 acceptance.

For readiness metrics and grouped review actions, also follow `references/readiness-and-bounded-bulk-decision-review.md`. It covers server-side business-readiness enforcement, displayed-versus-mutated cluster bounds, acceptance-test inversions, embedded private business rules, and synthetic preview-only counterprobes.

For findings-only final reviews of an uncommitted working tree against a named base, follow `references/exact-tree-read-only-diff-review.md`. It adds untracked-file scope, producer-to-UI contract tracing, deterministic counterexamples for date-only freshness and contradictory readiness, selected-period versus lifetime-coverage checks, and a mandatory final re-read when the tree changes during review. For append-only market observations, refresh no-op guarantees, correction lineage, and truthful wealth dates/counts, also use `references/exact-tree-market-observation-adversarial-probes.md`; it explains how to keep reviewing the requested immutable tree if the staged index moves concurrently. For UX-heavy acceptance gates involving confirmation wording, preview-field separation, bounded examples/days, or isolated browser-matrix wiring, also follow `references/exact-tree-ux-acceptance-review.md`.

For release-/migration-/data-safety reviews of financial import work, also follow `references/release-migration-data-safety-review-probes.md`. It adds adversarial synthetic probes for lossy fuzzy deduplication, source/account-role mismatches, transaction-specific real-data leakage, no-DDL versus operational onboarding, and lockfile/runtime-engine compatibility.

For Preview → Confirm workflows, deterministic run IDs, immutable daily snapshots, or retryable multi-day jobs, follow `references/transactional-preview-idempotency-and-immutable-snapshot-probes.md`. It covers SQLite `INSERT OR REPLACE` bypasses of apparent immutability, fingerprints that omit consumed price/FX inputs, confirmation-ID payload mismatch, false success over partial child runs, and semantic drift under predictable stable IDs. When Preview displays prior cash, deltas, or aggregate wealth, bind the normalized effective projection—not merely the latest anchor row: include authoritative post-anchor movements and every canonical component that can change the displayed total, then recompute under the Confirm lock.

For current-day market-data recovery, one-shot valuation writers, source activation gates, and operator status projections, also follow `references/current-market-data-source-integrity-review.md`. It covers WAL-safe read-only dry-runs, exact provider-ID/currency validation, concurrent activation idempotency, cross-source scheduler isolation, canonical writer-to-reader identity, same-day replay drift, activation-before-existing-run ordering, run-consistent status provenance, and separation of snapshot defects from still-missing runtime evidence. For stale-only refresh, trace selected identities through the actual provider request and persistence loop: a stale-count gate followed by a full-inventory one-shot is not stale-only, and a same-day idempotency shortcut must not report success while stale prices remain. Pair that review guide with `references/controlled-market-data-recovery-release.md` for the end-to-end diagnosis → write-free live dry-run → production-copy replay → backup → two idempotent one-shots → source-isolated timer activation and expected-mutation audit sequence.

For releases that add daily financial valuations or extend an already-installed scheduler, also follow `references/daily-valuation-release-and-scheduler-safety.md`. It covers full canonical reader identity across accounts, explicit supersession lineage, post-partial backfill drift binding, pre-existing timer-state inspection, fail-closed unit installation, and all-table no-write deployment sentinels.

For exact-commit financial data-truth reviews, follow `references/financial-data-truth-release-review.md`. It traces one canonical actionable-review predicate through counts, filters, rendering, and confirmation; requires snapshot-bound keyset pagination and truthful error/global/filtered-empty states; and verifies expense/income/refund/transfer/card-settlement/receipt-detail/duplicate effects by exercising the real writer into the canonical reader rather than relying on idealized direct-SQL fixtures.

For shared cash projections feeding multiple backend surfaces, use `references/shared-financial-read-model-adversarial-probes.md`. It defines the exact anchor + authoritative budget import + duplicate canonical import + additive manual-adjustment counterexample, malformed-date and provider-source fail-closed probes, oldest-component freshness semantics, independent runtime checks across every consumer, and repository-pinned lint verification.

## Evidence discipline
Never include credentials, raw production records, token values, or sensitive screenshots in evidence. For financial, medical, or similarly sensitive releases, keep instrument-/record-level diagnosis matrices outside Git as owner-only runtime artifacts (`0600`); tracked documentation should contain only aggregate technical findings, contracts, and sanitized reason classes. Keep the evidence compact and versioned; do not turn a sprint closeout into a new architecture document. If the first full test run is invalidated by proven environment contamination, record that fact, clean the environment, and permit one replacement run; do not weaken fail-closed product checks.

## Reference
See `references/worker-and-browser-acceptance.md` for failure handling, browser diagnostics, and isolated synthetic-suite matrix guidance.