From ea30067dfa4a2ff9aa2d069bf89146b1d63cb093 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 9 Sep 2026 14:13:03 +0900 Subject: [PATCH 1/2] docs: record side-chain landing plus merge know-how --- AGENTS.md | 4 ++++ CLAUDE.md | 4 ++++ docs/product-technical-gap-baseline.md | 4 ++-- 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 90bf5a7..e4f5bde 100644 --- a/AGENTS.md +++ b/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`. diff --git a/CLAUDE.md b/CLAUDE.md index 60e4e51..fe1893f 100644 --- a/CLAUDE.md +++ b/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 ` first, re-confirm CLEAN/MERGEABLE plus exact-head verify GREEN, then `gh pr merge --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. diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index cb73159..70021f4 100644 --- a/docs/product-technical-gap-baseline.md +++ b/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` (pins now in `develop`, so `dependency-review` is expected to flip; CodeQL-compat failures go through the central owner path); 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. From 852c6bad42ac6b8f738d874a66e3afb684860301 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 9 Sep 2026 14:22:54 +0900 Subject: [PATCH 2/2] docs: record PR1 exact-head failures on pinned develop tip --- docs/product-technical-gap-baseline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 70021f4..43d0925 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -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. Re-verify PR #1 on the post-successor `develop` head `e1c588f` (pins now in `develop`, so `dependency-review` is expected to flip; CodeQL-compat failures go through the central owner path); 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. +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.