Add design specs for the provider architecture and permission model epic

docs/superpowers/specs/2026-06-11-datadome-server-side-protection-design.md

@@ -1,5 +1,16 @@
 # DataDome Server-Side Protection API Integration
 
+> **Supersession note (PR #986):** the response-effects portions of this
+> document — in particular "DataDome headers/cookies apply last and win"
+> and any post-finalization ordering — are **superseded** by the
+> response-header hook spec's §4a security-channel contract
+> (`2026-07-30-integration-response-header-hook-design.md`): one global
+> order applies (core finalization → ordinary mutators → security
+> effects → final cache/privacy invariant pass, unconditionally last),
+> with typed cookie/header operations, enumerated allowlists
+> (`datadome-header-allowlist.md`), and owner-only identifier
+> boundaries. Where this document conflicts, the hook spec governs.
+
 **Issue:** #317
 **Date:** 2026-06-11
 **Status:** In Progress

docs/superpowers/specs/datadome-header-allowlist.md

@@ -0,0 +1,26 @@
+# DataDome header allowlist (normative, checked-in — request and response directions)
+
+The complete set of response-named header pointers the security channel
+(hook spec §4a) may copy into the owner-scoped publisher-upstream
+overlay. Every `X-DataDome-*` name not listed here is rejected. Adding a
+name is a reviewed commit to this file and a spec change.
+
+| Header                | Direction                   | Scope                                                                                                |
+| --------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `X-DataDome-ClientID` | response → upstream overlay | Owner-scoped overlay only; never the shared request view; vendor egress governed by sign-off item 23 |
+
+## Response-direction allowlist (browser-response pointers)
+
+Headers a DataDome decision may set on the outgoing response, beyond
+the typed security cookie (hook spec §4a). Empty rows below the base
+set mean: nothing else is accepted until a reviewed commit adds it.
+
+| Header                    | Decision                     | Semantics                                   |
+| ------------------------- | ---------------------------- | ------------------------------------------- |
+| `Location`                | Respond (3xx) only           | replace                                     |
+| `Content-Type`            | Respond only (owns its body) | replace                                     |
+| `Cache-Control`, `Pragma` | Respond only                 | restricted merge; invariant pass still last |
+
+Note: the vendor's `X-Set-Cookie` response field is **not** a
+forwardable header — it lowers into the typed `datadome` cookie
+operation (hook spec §4a) and never reaches the browser as a header.

docs/superpowers/specs/decisions/README.md

@@ -0,0 +1,6 @@
+# PR #986 product-decision records
+
+One file per open row of the migration spec §8 sign-off table
+(`NN-title.md`), recording the decision, the deciders, and the date. The
+table links each record as its row closes; a row without a record here is
+open, and implementation is blocked while any row is open.

docs/superpowers/specs/gpp-registry-snapshot.md

@@ -0,0 +1,38 @@
+# GPP registry snapshot (normative, vendored)
+
+The pinned per-section accepted versions for the permission spec's §4.5
+map. This file is the single reproducible authority; updating it is a
+reviewed spec change. A mapped section presenting a version not listed
+here is treated as malformed-present (permission spec §4.4).
+
+| GPP section ID | Section                                             | Accepted version(s) |
+| -------------- | --------------------------------------------------- | ------------------- |
+| 6              | US Privacy string (uspv1, carried as a GPP section) | 1                   |
+| 7              | usnat                                               | 1                   |
+| 8              | usca                                                | 1                   |
+| 9              | usva                                                | 1                   |
+| 10             | usco                                                | 1                   |
+| 11             | usut                                                | 1                   |
+| 12             | usct                                                | 1                   |
+| 13             | usfl                                                | 1                   |
+| 14             | usmt                                                | 1                   |
+| 15             | usor                                                | 1                   |
+| 16             | ustx                                                | 1                   |
+| 17             | usde                                                | 1                   |
+| 18             | usia                                                | 1                   |
+| 19             | usne                                                | 1                   |
+| 20             | usnh                                                | 1                   |
+| 21             | usnj                                                | 1                   |
+| 22             | ustn                                                | 1                   |
+| 23             | usmn                                                | 1                   |
+| 24             | usmd                                                | 1                   |
+| 25             | usin                                                | 1                   |
+| 26             | usky                                                | 1                   |
+| 27             | usri                                                | 1                   |
+
+Version values for sections 6–23 were captured from the IAB registry at
+the time of writing and are re-verified against the official registry as
+part of ratification review. Sections 24–27 have assigned IDs but no
+reproducibly published binary layouts in the official sources as of this
+snapshot; they are reserved and inert until an official layout can be
+vendored here. Any change is a reviewed change to this file.