docs: record side-chain landing plus merge know-how

AGENTS.md

@@ -18,3 +18,7 @@ PolicyWeave is a local-first privacy-policy fact-authoring workspace. It structu
 
 ## Verification
 The minimum exact-head gate is `npm run lint`, `npm test`, and `npm run build`, plus every live organization-required workflow, independent approval, and resolved review thread. Queued, skipped, predecessor-head, or stale results are not passing evidence.
+
+## Know-how
+- Draft PRs cannot merge through the API: mark ready (`gh pr ready`), re-confirm exact-head CLEAN/MERGEABLE/verify GREEN with zero unresolved threads, then ordinary `--merge` without branch deletion or force-push.
+- Slow local executors flake Vitest's default 5s per-test timeout on full-workflow UI tests while exact-head CI stays GREEN. Use `npx vitest run --testTimeout=60000` for the local signal; CI `verify` is authoritative. Detail: `CLAUDE.md`.

CLAUDE.md

@@ -7,3 +7,7 @@ Before changing code, read `docs/PRD.md`, `ARCHITECTURE.md`, the applicable ADRs
 For behavior changes, add or strengthen tests before production code. Reconcile documentation and the product-gap ledger on the same branch. Use the exact current PR head for reviews, checks, and merge decisions, and never bypass governance to compensate for a failing or unassigned check.
 
 Deferred `policy_revision` fact triggers evaluate the final commit state. CI restore seeds `retention_status = applies` and `retention_rule` in one transaction; the owner runbook is `db/tests/policy_revision_restore.sh`.
+
+## Know-how (2026-09-09, exact-head `e1c588f` verified)
+- Draft PRs cannot merge through the API (`Pull Request is still a draft`): run `gh pr ready <n>` first, re-confirm CLEAN/MERGEABLE plus exact-head verify GREEN, then `gh pr merge <n> --merge`. Never delete stacked branches on merge; successors restack with ordinary non-force merge commits.
+- Local Vitest defaults to a 5s per-test timeout and flakes on slow executors (full `App` workflow tests exceed it under load while CI verify stays GREEN). Use `npx vitest run --testTimeout=60000` for the local full-suite signal; do not retune production or timeouts to mask executor slowness. CI `verify` on the exact head remains the authoritative verdict.

docs/product-technical-gap-baseline.md

@@ -73,7 +73,7 @@ The final URL-boundary follow-up found that WHATWG `URL.search` and `URL.hash` a
 
 The dependency-governance pass found that every direct npm declaration was either `latest` or a mutable caret range and that TypeScript, Vite, and the React Vite plugin were incorrectly classified as production dependencies. Test-only head `80b69d6a640194997906ec23ca0140f28fd95908` produced exact RED CI `34244619215`: clean install and lint passed, 73 predecessor tests passed, and only the two new pin/classification contracts failed. Minimal implementation `cd9144f4a8a78427457bb58ee4b0a5f75a1ca750` pins all 21 direct packages to their existing reviewed lock resolutions, moves the three build packages to `devDependencies`, and uses npm to regenerate development-scope metadata without changing any resolved package version. A second test-only head `f6bbf9d6e5621ac26e3d1905556c192c2c8613c7` produced exact RED CI `34245711353`: 75 tests passed and only the missing CycloneDX publication contract failed. Workflow repair `a3592da89c75be87564e1d4ec8d9e685e9e3093e` generates a CycloneDX 1.5 SBOM from the exact installed lock graph and uploads it through the existing SHA-pinned artifact action. A final storage review found that placing the SBOM below `test-results` duplicated it in both browser and dependency artifacts. Test-only head `3c8ac646c7ccd0140976f3fcefc914fc4b9a7d80` produced exact RED CI `34246822467` with 75 passing tests and only the new artifact-isolation contract failing; minimal repair `00b89fb6c986b22e2453a58f4b6dc61ba7ff1dff` writes the SBOM once below `dependency-evidence` and uploads only that path as the dependency artifact. Current review follow-up independently checks runtime and development declarations, asserts both artifact destinations, and names all three runtime packages consistently. The lock/license and SBOM evidence support security and legal review but do not themselves approve dependency licenses or replace organization vulnerability gates.
 
-The successor merge below lands this side chain in `develop` order: the above export evidence plus the dependency-governance delta arrive together, preserving both histories without force-push.
+The successor landed this side chain in `develop` order via PR #18 (successor head `828ecf1`, parents `8178ba6` + `83fb9f8`, verify `34313155294` GREEN, zero review threads, merged 05:06:01Z): the above export evidence plus the dependency-governance delta arrived together, preserving both histories without force-push. Predecessor merges in this turn: PR #10 (export, head `cef8c0b`, verify `34301731941` GREEN, 7/7 threads resolved, merged 04:32:57Z after `gh pr ready` lifted the draft merge block) and PR #11 (readiness plus pins, head `77bf3c2` after the scope-sentence correction, verify `34311980712` GREEN, 1/1 thread resolved, merged 04:54:21Z). `develop` is now `e1c588f` with zero `latest` declarations; merged-tree local gates are lint GREEN, build GREEN, and 76/76 Vitest GREEN. No PR was closed to reach this state.
 
 ## Current baseline
 
@@ -104,7 +104,7 @@ The Proposed aggregate root is the minimal `policy_revision` boundary. The no-co
 A publishable release requires complete fact-to-warning navigation, deterministic rendering of captured source facts, no inferred customer operational facts, truthful first-responsibility startup/progress, explicit unresolved-review blocking across the seven authoring responsibilities, an explicit no-collection path that does not infer unrelated processing facts, independent explicit retention status, immutable reviewed publication revisions, accessible responsive interaction, authoritative source/version traceability for legal rules, hosted security/privacy evidence, and exact-head CI/security/independent review. Buyer-facing wording describes assistance and reviewability, never a compliance guarantee or an internal implementation boundary.
 
 ## Active commercialization order
-1. Verify the restacked side chain (PR #10 export delta, PR #11 readiness docs plus SBOM/license evidence) with exact-head CI/security/SAST and independent approval; deliver pins down-chain and clear PR #1's CodeQL-compat failures through the central owner path (sole-maintainer approval is the structural blocker); merge PR #1 only through ordinary protection. The full writer-stack tip already landed in `develop` via PR #16.
+1. Re-verify PR #1 on the post-successor `develop` head `e1c588f`: `verify` is GREEN on the exact head, but `dependency-review` still FAILs even with zero `latest` declarations in `develop`, and both CodeQL compatibility analyses still FAIL. Central-workflow logs live in the organization central repository (leaf-repo API returns 404), so the `dependency-review` reason is not inspectable from this repo; route both through the central owner path rather than leaf-side churn. Secure independent approval (sole-maintainer approval is the structural blocker); merge PR #1 only through ordinary protection. The full writer-stack tip landed in `develop` via PR #16 and the export plus dependency-governance side chain via PRs #10/#11/#18.
 2. Extend the exact-head responsive/accessibility evidence with screen-reader checks, native browser-zoom automation when the harness supports it, and manual records; CSS focus contrast, logical step-focus transfer, focused-heading viewport visibility, retention transitions, effective 200% browser-zoom reflow, and current desktop/tablet/mobile screenshots are already verified.
 3. Preserve exact-head PostgreSQL 18 migration, domain-error, two-session lock, restart, and dump/restore evidence, then prove tenant authorization, immutable audit, and encryption before enabling any hosted adapter.
 4. Implement secure review/publication with immutable releases and explicit supersession.