# Exact-tree health-dashboard release review

Use for final read-only QA/security approval of an uncommitted health-dashboard tree after late fixes.

## Runtime-to-tree identity before repository review

When the task declares an already-running synthetic runtime, treat that direct runtime as the first source of truth even if the session's injected working directory appears unrelated.

1. Prove which process owns the declared port, then inspect only non-sensitive process metadata: executable, command line, current working directory, and allowlisted test/runtime environment variables.
2. Require an explicit synthetic identity header or equivalent sentinel and verify that queue/database/output targets point only to the declared disposable fixture area.
3. Use the owning process's working directory to identify the exact source tree, then run Git status/diff gates there. Do not silently review the session default repository merely because it was supplied as the initial cwd.
4. Confirm the product route explicitly; a root redirect or fallback route can serve a different dashboard generation while still returning HTTP 200. Verify route, title/bundle sentinel, and served synthetic instance before browser assertions.
5. If process identity, synthetic identity, route, and tree cannot be reconciled, stop with a scope/identity blocker rather than approving evidence from mixed repositories or runtimes.

## Freeze the release candidate before independent review

Independent approval is meaningful only for an immutable candidate.

1. Finish local fixes and focused tests first, stage the complete candidate, then capture `HEAD`, `git status --short`, staged path list, and a digest of the staged diff.
2. Dispatch reviewers only after that freeze. Do not continue opportunistic implementation or hardening while they review; otherwise findings and approvals can refer to different trees.
3. If any file changes after dispatch, mark all affected verdicts stale. Integrate the change, rerun the smallest proving tests, freeze a new digest, and request a narrow re-review of the changed contract before using `APPROVE` in release evidence.
4. Consume all reviewer outputs, combine their findings into one fix batch where possible, then re-freeze. Avoid a review/edit/review loop where each worker races a moving worktree.
5. Documentation-only evidence updates may follow approval only when they cannot affect runtime contracts; still run JSON/example and diff checks before commit.
6. Include nonignored untracked files in candidate identity. A digest of `git diff` alone does not cover new tests or source files; pair it with stable content hashes for every `git ls-files --others --exclude-standard` path.
7. Before treating the candidate as frozen, confirm that no test/build process is still rewriting tracked screenshots or evidence. Capture status and the complete digest twice after those processes exit. Transient zero-blob/raw-diff entries, a changing path count, or historical screenshots appearing and disappearing from status mean the candidate is moving and no approval can attach to it.

## Gate sequence

1. Capture `git status --short --branch`, changed paths, untracked nonignored files, `git diff --check`, HEAD, and branch before testing.
2. Review the complete changed surface, including untracked tests/docs. Scan untracked content separately because ordinary `git diff` omits it.
3. Prove frozen fallback surfaces (for example v4) by changed-path and worktree-vs-HEAD hash checks; do not rely only on filenames containing `v4` because shared server/assets may use generic names.
4. Run the full suite and a focused safety/contract subset with bytecode disabled or isolated. Run lint on changed files when the repository has known unrelated baseline debt, and disclose the broader baseline separately rather than calling the whole repository clean.
5. Run AST/source parsing, JavaScript syntax, whitespace checks, added-line security scans, secret-like filename scans, binary/artifact scans, and tracked/nonignored artifact checks. In a read-only review, do not use plain `python -m py_compile` inside the repository because it writes or refreshes `__pycache__`; use `ast.parse`, set `PYTHONDONTWRITEBYTECODE=1` where applicable, or direct bytecode output to a disposable `PYTHONPYCACHEPREFIX` outside the tree.
6. Reproduce the synthetic database and rendered HTML twice from explicit dates/timestamps. Require byte equality and report checksums.
7. Start browser QA on a newly selected isolated port using the just-generated synthetic fixture. Verify readiness and the synthetic sentinel before Playwright. Redirect Playwright output, traces, screenshots, and reports to a disposable directory outside the repository even when the normal paths are ignored; remove that directory after recording aggregate results. Afterward, inspect ignored status too: Playwright may still create a repository-local `test-results/.last-run.json` even when `--output` points elsewhere, so remove only review-created residue and prove final status matches the initial capture.
8. Never accept a green browser run merely because the requested port responded. An already-running stale or foreign server can satisfy readiness and produce misleading evidence. Confirm the new server process owns the selected port and, where practical, compare the served HTML body/checksum or fixture marker with the just-generated artifact.
8a. For any write-capable same-origin endpoint, pair the successful native-browser POST with an adversarial exact-origin probe using a fresh synthetic CSRF token/cookie. Change only the Origin scheme (for example, request over `http://host:port` with `Origin: https://host:port`) and require rejection before queue mutation. Comparing only `urlparse(origin).netloc` to `Host` is not an exact-origin check: it accepts a scheme mismatch despite a green real-browser happy path. Remove the synthetic sentinel action after recording the result.
9. If a preferred port is occupied, leave the foreign process untouched, choose another port, and rerun the complete browser suite against the controlled server. Do not kill processes you did not start.
10. Stop only the review-owned server, remove disposable `/tmp` fixtures, then rerun focused tests, `git diff --check`, and final status immediately before reporting. Compare the final status to the initial capture so the review itself cannot silently add artifacts.
11. If a broad regression run fails because inherited synthetic-test environment variables activate a stricter fixture guard, classify the run as contaminated rather than a product failure. Re-run once with only the contaminating test-instance variables removed, preserve both results, and report the clean replacement as evidence only when it covers the identical test selection.

## Route, history, and compatibility contracts

1. A new sub-view must have a reload-stable URL/state discriminator. Do not reuse the reviewed-detail route for an unreviewed preview or other mode whose backend policy differs; direct load, reload, back, and forward must resolve to the same viewer and endpoint.
2. Treat response enum literals as contracts. Adding a clearer field is usually safe; silently replacing an established literal such as `searchable` with a renamed value is a breaking change unless the endpoint is versioned or a documented migration/compatibility period exists.
3. When implementation intentionally supersedes an older safety or availability policy, update or explicitly obsolete the versioned contract and machine-readable evidence in the same candidate. A frontend that accepts both old and new values does not make the server response backward compatible.
4. Browser tests for a new viewer/action must include reload and history restoration, not only the initial successful click. For navigation controls that call both `replaceState` and `pushState`, verify that one Back returns to the prior semantic view rather than a duplicate URL entry.
5. If the sprint has no versioned scope/evidence artifact, state that exact-scope and evidence-plan reconciliation are unverified; do not infer them from filenames or green tests.
6. In master-detail refactors, do not restore an opaque document or preview by searching only the current paginated list response. A direct `document=<opaque>` or preview route must resolve through its dedicated detail endpoint, independent of list sort, filters, and the first-page limit; test an item deliberately absent from page one across direct load, reload, Back, and Forward.
7. Treat client-only filters over a bounded server page as a data-contract failure, not merely a UX limitation. If a control claims to filter the document collection, apply it in SQL before pagination or explicitly scope its label to the current page; coverage counts and empty states must use the same filter scope.
8. For post-action redirects into a filtered review workspace, trace the submitted opaque key through receipt classification, filter membership, selection fallback, and URL replacement. The just-queued item must remain the selected receipt target (or show a dedicated receipt state); an `open` filter must not exclude it and silently select another editable row.
9. Do not project unrestricted queue `reason`/note text into browser bundles merely because it is length-bounded. Use an enum/code allowlist or the same path/URL/Drive-token-safe metadata sanitizer as other sensitive surfaces. Never infer medically meaningful product classes such as simple versus composite from unconstrained reason keywords with a fail-open default; unknown classification remains unknown and requires review.

## Adversarial read-API integrity probes

For catalog/read-API release candidates, green happy-path tests are not enough. Add small disposable synthetic counterexamples that cross-check contracts across layers:

1. **Filter before limit:** Populate more than the source limit with rows that will be filtered out, followed by one valid row. Require either the valid row or an explicit limit error. A SQL `LIMIT` applied before an in-Python semantic filter can silently hide valid medication administrations, verified observations, or events.
2. **Calendar boundaries:** Probe syntactically valid extreme ISO dates such as `0001-01-01` and `9999-12-31`. Date-padding logic (`start - 1 day`, `end + 1 day`) must not leak `OverflowError` or drop the HTTP connection; require a deterministic bounded JSON 4xx response with privacy headers.
3. **Catalog-versus-series availability:** For every released source class, insert one valid synthetic observation and assert that catalog availability reports it while the corresponding series returns it. This catches catalog branches omitted for a source even though its provider works.
4. **Raw-row ceilings:** Inspect each source adapter, not only the final response length. Require SQL/cursor-level bounds and fail-closed overflow behavior before materializing or aggregating rows; post-aggregation point limits do not bound memory or source work.
5. **All endpoints twice:** Serialize every endpoint twice with sorted compact JSON and require byte equality. Pair this with unknown and duplicate scalar-query probes per endpoint, including endpoints that allow no query parameters.
6. **Examples as contracts:** Check that documentation covers every public endpoint and that command examples either use their declared token variable or are explicitly labeled non-executable/redacted. Compare selected documented fields against actual synthetic responses.
7. **Redaction delimiters and path classes:** Probe sensitive paths embedded after whitespace and punctuation (`prefix /var/...`, `prefix=/var/...`, `x|/tmp/...`), traversal (`../../...`), URL/file schemes, Windows/UNC paths, and Drive-ID-like tokens through the real events/search response—not only the helper. Redaction regexes that recognize only a few delimiters are incomplete.
8. **Finite numeric contracts:** Probe very long digit strings that match a numeric regex but convert to infinity. Apply `math.isfinite` to both observations and reference bounds, and serialize JSON with non-finite values forbidden.
9. **Document-namespace isolation:** API document metadata IDs must be opaque and non-numeric, must not be directly transformable into legacy numeric document routes, and must fail when passed to the legacy route. Cross-database ID reuse is a disclosure risk even when both lookups are individually read-only.
10. **Error-envelope closure:** Force provider exceptions and non-serializable responses, then require bounded JSON `500` responses with `no-store`. Probe unknown methods in both origin-form and absolute-form request targets, including an invalid Host, so framework-level `send_error` paths cannot escape the API envelope.

Treat silent omission of valid health observations, catalog/series availability contradictions, uncaught boundary-date exceptions, unbounded raw-source reads, cross-namespace document IDs, non-finite JSON, or redaction bypasses as Important release blockers even when the committed test suite is green.

## Sensitive-tree discipline

- Do not open production databases, reports, exports, logs, or credential files during a source review. Prove their absence from the changed/untracked surface using names, Git metadata, and allowlisted extensions only.
- Read untracked source/docs/tests because ordinary diff output omits them, but classify suspicious filenames before opening anything that could be a credential or medical artifact.
- Keep every dynamic probe on a newly generated synthetic DB and HTML. Production service status or integrity checks belong to a separately authorized deployment gate, not an uncommitted-diff review.
- For frozen fallback scope, hash named fallback files against `HEAD` and separately reason about shared generic files (server, worker, assets, units) that can still change fallback behavior.

## Approval wording

Return `APPROVE` only when no Important/Critical issue remains. Separate:

- regression evidence;
- browser evidence;
- deterministic reproduction checksums;
- security/secrets/artifact/v4 evidence;
- nonblocking pre-existing baseline debt;
- confirmation that review probes did not modify the source tree or access production data.

A broad linter failure in untouched legacy files is not a new regression, but it must not be misreported as repository-wide lint success. State exactly which changed-file gate passed and which pre-existing baseline remains.