feat: bootstrap PolicyWeave privacy policy workspace

.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+concurrency:
+  group: policyweave-ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres@sha256:d3e1620b530c944afa6e887d22eb899824da68e19c52024bf98f5220c88a65b2 # 18.6-alpine3.24
+        env:
+          POSTGRES_DB: policyweave_test
+          POSTGRES_USER: policyweave_ci
+          POSTGRES_PASSWORD: policyweave_ci_password
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U policyweave_ci -d policyweave_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - name: Generate exact-head dependency SBOM
+        run: |
+          mkdir -p dependency-evidence
+          npm sbom --sbom-format cyclonedx > dependency-evidence/policyweave-dependency-sbom.cdx.json
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+      - name: Verify PostgreSQL policy revision migration
+        env:
+          PGHOST: 127.0.0.1
+          PGPORT: 5432
+          PGUSER: policyweave_ci
+          PGDATABASE: policyweave_test
+          PGPASSWORD: policyweave_ci_password
+        run: sh db/tests/policy_revision_runtime.sh
+      - name: Verify PostgreSQL concurrent policy writers
+        env:
+          PGHOST: 127.0.0.1
+          PGPORT: 5432
+          PGUSER: policyweave_ci
+          PGDATABASE: policyweave_test
+          PGPASSWORD: policyweave_ci_password
+        run: sh db/tests/policy_revision_concurrency.sh
+      - name: Verify PostgreSQL policy revision restore
+        env:
+          PGHOST: 127.0.0.1
+          PGPORT: 5432
+          PGUSER: policyweave_ci
+          PGDATABASE: policyweave_test
+          PGPASSWORD: policyweave_ci_password
+        run: sh db/tests/policy_revision_restore.sh
+      - run: npx playwright install --with-deps chromium
+      - run: npm run test:e2e
+      - name: Upload exact-head browser evidence
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: policyweave-browser-evidence
+          path: test-results
+          if-no-files-found: warn
+      - name: Upload exact-head dependency SBOM
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: policyweave-dependency-sbom
+          path: dependency-evidence/policyweave-dependency-sbom.cdx.json
+          if-no-files-found: error

.gitignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+.env
+coverage
+playwright-report
+test-results/
+*.tsbuildinfo
+.codegraph/

AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+## Product responsibility
+PolicyWeave is a local-first privacy-policy fact-authoring workspace. It structures facts supplied by a service operator, detects missing or contradictory inputs, and renders a review draft. It does not provide legal advice, certify compliance, or infer facts that the operator has not established.
+
+## Development contract
+- Treat structured policy facts as the source of truth; rendered policy prose is a deterministic projection.
+- Preserve the seven authoring steps in `docs/PRD.md`: service information, collection items, purposes, retention, third-party transfer, international transfer, and privacy contact.
+- Behavior changes require regression or edge-case tests first. Do not resolve a review finding until the exact current head proves the finding obsolete or fixed.
+- Re-fetch the PR head before every commit/push. Never force-push or weaken branch/ruleset protections to merge.
+- Keep `ARCHITECTURE.md`, `docs/TRD.md`, ADRs, `docs/research-traceability.md`, `CHANGELOG.md`, and `docs/product-technical-gap-baseline.md` aligned with implementation.
+- Do not encode legal conclusions from memory. Every legal/rule/template decision needs an authoritative source, effective date, source revision, and implementation/test trace.
+- Do not commit identifying customer, individual, or real operational-organization data in tests, examples, fixtures, or product documentation. Publicly documented legal authorities, official document titles, standards bodies, source publishers, and the repository owner may be named when required for accurate provenance and citation. Production must not consume synthetic demo data.
+- Keep persistence objects semantically named with at least two words and `snake_case` unless a framework contract requires another convention. Avoid generic named persistence objects such as a standalone `id` table/collection.
+- Hosted persistence/publication must be introduced only behind explicit tenant, authorization, audit, encryption, immutable revision, and supersession contracts. CI PostgreSQL restart and dump/restore evidence lives in `db/tests/policy_revision_restore.sh` and does not enable a hosted adapter. Seed `retention_status = applies` only in the same transaction as its `retention_rule`; autocommit fails the deferred fact contract.
+- GitHub Actions dependencies stay SHA pinned and checkout credentials must not persist.
+- Direct npm dependencies stay pinned to their reviewed lock resolutions. Compiler and bundler packages belong in `devDependencies`, and exact-head CI publishes a CycloneDX dependency SBOM without treating license metadata as legal approval.
+
+## 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`.

ARCHITECTURE.md

@@ -0,0 +1,46 @@
+# Architecture
+
+## Product boundary
+PolicyWeave owns the authoring and review of structured privacy-processing facts and the deterministic generation of a review draft. It does not own legal advice, identity-provider data, payment processing, or a customer's source systems. Hosted publication and durable storage are future supporting capabilities, not authority to invent or reinterpret processing facts.
+
+## Domain-driven design
+The core subdomain is **Policy Fact Authoring**. Supporting subdomains are **Review & Publication** and **Legal Source Registry**. Browser/storage frameworks, authentication infrastructure, observability, and deployment are generic subdomains.
+
+### Bounded contexts
+- **Policy Fact Authoring**: captures `service_profile`, collection presence/no-collection attestation, `collection_item`, `processing_purpose`, `retention_rule`, `third_party_transfer`, `international_transfer`, and `privacy_contact` facts.
+- **Review & Publication**: derives `review_finding`, controls `policy_revision` review state, and will create immutable `publication_revision` artifacts only after explicit authorization.
+- **Legal Source Registry**: versions authoritative sources, effective dates, rule/template revisions, and citations. It is an anti-corruption layer between changing external law/guidance and already-published revisions.
+
+### Context map
+`Policy Fact Authoring -> Review & Publication` is a customer/supplier relationship through a versioned policy-fact contract. `Legal Source Registry -> Review & Publication` supplies versioned rule evidence; source updates cannot silently mutate historical policy revisions. External customer systems remain behind adapters and must not be queried or mutated through hidden coupling.
+
+## Ubiquitous language and model
+A future `policy_revision` is the minimal aggregate root and transaction boundary. `service_profile`, collection presence/no-collection attestation, `collection_item`, `processing_purpose`, `retention_rule`, `third_party_transfer`, `international_transfer`, and `privacy_contact` are revision-owned facts/value objects unless later evidence requires independent lifecycles. `review_finding` is derived evidence. `publication_revision` is an immutable release receipt, not a mutable policy row. Rendered prose is a projection and never the source of truth.
+
+Core invariants:
+1. A fresh workspace contains no inferred customer operational facts; blank means unresolved rather than `none`.
+2. Collection presence is established by either at least one selected collection item or an explicit no-collection attestation. Empty selection alone remains unresolved. The no-collection attestation and selected items are mutually exclusive; contradictory state fails closed.
+3. Turning on the no-collection attestation invalidates all selected-item collection mode, processing purpose, and collection-path evidence. Turning the attestation off cannot revive those stale facts.
+4. Selecting a collection item without confirming its collection mode, processing purpose, or collection-path evidence creates independent blocking review findings.
+5. Service identity, retention, third-party provision status, international-transfer status, and privacy contact remain blocking authoring responsibilities until explicitly established; service URL and contact-email syntax checks prove only usable field shape, not endpoint/mailbox ownership.
+6. Third-party provision and international transfer distinguish unresolved, yes, and no. A `yes` status requires dependent facts; a transition away from yes invalidates dependent details so stale facts cannot revive silently.
+7. Disabling a collection item invalidates its dependent collection-mode, processing-purpose, and collection-path evidence; re-enabling requires renewed confirmation.
+8. Review findings navigate to the fact that caused them.
+9. Publication must never upgrade an unreviewed or incomplete draft to a reviewed/authoritative state.
+10. A published revision remains reproducible from its policy facts plus rule/template/source versions.
+11. External legal-source updates produce explicit re-evaluation, not silent rewriting.
+
+## Current implementation
+The active MVP is a React/Vite browser workspace. State is in memory and there is no production persistence or publication backend. The browser can download a deterministic versioned JSON draft containing normalized operator-authored facts and readiness finding codes; this local portability projection is not publication, persistence, or legal approval. The seven PRD steps are routed to distinct editing surfaces. The collection taxonomy is metadata only. `src/policy.ts` owns deterministic collection-selection/no-collection/mode/purpose/path and non-collection authoring-completeness findings; `src/App.tsx` owns browser orchestration, explicit no-collection and transfer-status capture, warning-to-source navigation, stale dependent-fact invalidation, and deterministic preview rendering. `src/AuthoringFocusController.tsx` is a browser interaction adapter: after explicit rail, previous/next, or review-warning navigation changes the active editing surface, it moves programmatic focus to that surface's heading without changing domain state, intercepting ordinary field interaction, or overriding the separate preview-focus shortcut.
+
+Authoring completeness is deliberately separate from legal sufficiency. Current readiness rules prove that product-defined fact responsibilities were explicitly addressed; they do not assert that a policy complies with law. Source/effective-date-bound legal validation belongs to the Legal Source Registry -> Review & Publication boundary.
+
+## Persistence boundary (Proposed schema; CI-only runtime)
+ADR-0003 and `db/migrations/0001_policy_revision.sql` propose the first PostgreSQL contract. The 3NF write model uses `policy_revision` as aggregate root; `service_profile`, `collection_item`, `processing_purpose`, and `retention_rule` are revision-owned facts. `(tenant_account_id, revision_number)` identifies a version, while `(policy_revision_id, collection_item_key)` is the item-level UPSERT/idempotency key. Deferred database constraints lock the owning revision row, reject collection items under explicit no-collection, and reject retention-rule/status contradictions at transaction commit.
+
+Exact-head CI executes that migration against digest-pinned PostgreSQL 18, including rollback, two-session locks with NULL-safe complete-value assertions, process restart, and custom-format dump/restore of complete collection-item plus independent collection and retention facts. This is not an active datastore, released API, or hosted adapter. Hosted tenant authorization, immutable audit events, encryption, deletion, operational backup/restore, and production-scale contention remain open. Publication remains append-only/immutable with explicit supersession; writes across unrelated aggregates must not share a transaction merely for convenience. Named database/schema/persistence objects use at least two semantic words and `snake_case`, for example `policy_revision`, `collection_item`, `processing_purpose`, `review_finding`, `publication_revision`, and `legal_source_revision`.
+
+Separate write-side draft commands from read-side rendered/review projections once hosted traffic justifies it. Account for revision hot spots and optimistic/constrained writes before adding collaborative editing. Keep source/customer integrations behind ACLs; do not form a shared kernel with unrelated ContextualWisdomLab products without demonstrated reuse.
+
+## Deployment and operability direction
+The browser-only MVP needs no service mesh. A hosted backend should be compose-deployable across Docker/Podman/Colima before Kubernetes migration, expose asynchronous/non-blocking request handling, and add realistic k6 evidence for network surfaces before latency claims. No code may depend on an optional `close_connection` instance attribute existing unless the adapter contract guarantees it.