feat: docs-adapters ROI audit — adapters, src/ refold, CI/supply-chain, harden passes

.agents/README.md

@@ -24,11 +24,7 @@ Source of truth for AI agent configuration. Cursor consumes via symlinks in `.cu
 
 ## Inventory
 
-9 rules + 18 skills. Discover on disk via `ls` + the frontmatter audit in [`agents-tier-system`](rules/agents-tier-system.md) — no hardcoded name lists.
-
-**Rules** — 7 Tier-1 (always-on): `agents-first-convention`, `tracer-bullets`, `no-bypass-hooks`, `verify-after-each-step`, `authoring-discipline`, `concise-reporting`, `architecture-priming`; plus `lessons.md`. 2 Tier-2 (globs): `agents-tier-system`, `docs-governance-priming`.
-
-**Skills** — `writing-great-skills` (meta vocabulary), `grilling` + `grill-me` + `grill-with-docs` (design stress-test), `teach` (multi-session learning), `ask-agents` (user-only router), `improve-codebase-architecture` (seam/boundary plans), `domain-modeling` (ubiquitous language), `docs-governance` + `docs-lifecycle-sweep` (docs lifecycle), `agents-tier-system` (tier assignments), `authoring-discipline` (prose depth), `verify-after-each-step` (per-file checks), `writing-agents-config` (persist deltas), `harden-pr` (branch-to-pristine), `diagnosing-bugs` (hard-bug loop), `tdd` (red-green-refactor), `pr-comment-fact-check` (reviewer/bot triage).
+Discover on disk via `ls` + the frontmatter audit in [`agents-tier-system`](rules/agents-tier-system.md) — no hardcoded name lists.
 
 ## Conventions
 

.agents/rules/agents-tier-system.md

@@ -12,7 +12,7 @@ alwaysApply: false
 
 Three attachment modes: **always-on** (`alwaysApply: true`), **auto-attached** (`globs:`), **intent** (`description:` only).
 
-**Tier 1 budget:** owner-set; currently 7 always-on rules + `lessons.md` (≤250 lines total). The frontmatter audit is the source of truth — **no hardcoded Tier 1 name lists** in rule, skill, or README. Audit:
+**Tier 1 budget:** owner-set; currently 8 always-on rules + `lessons.md` (≤250 lines total). The frontmatter audit is the source of truth — **no hardcoded Tier 1 name lists** in rule, skill, or README. Audit:
 
 ```bash
 for f in .agents/rules/*.md .agents/lessons.md; do

.agents/rules/codemap.md

@@ -0,0 +1,25 @@
+---
+alwaysApply: true
+---
+
+<!-- codemap-init:managed -->
+
+# Codemap
+
+This project is indexed by **Codemap** — a local SQLite index of structure (symbols, imports, exports, components, dependencies, markers, scopes, references, bindings, call graphs, CSS variables, coverage).
+
+**Before** answering structural questions (where is X defined, who imports Y, what does Z export, list components / hooks / deprecated symbols, trace dependency or call graphs), query the index — don't grep:
+
+```bash
+codemap query --json "<SQL>"     # or `codemap query --recipe <id>` for prebuilt patterns
+```
+
+Full rule (today's version, served by the installed binary):
+
+- **CLI:** `codemap rule`
+- **MCP:** read resource `codemap://rule`
+- **HTTP:** `GET /resources/{encoded-uri}` against `codemap serve`
+
+If `codemap` prints a pointer-protocol warning on startup, re-run `codemap agents init --force` to refresh this template.
+
+<!-- codemap-pointer-version: 1 -->

.agents/skills/authoring-discipline/PROSE.md

@@ -8,9 +8,11 @@ Companion to always-on [`.agents/rules/authoring-discipline.md`](../../rules/aut
 
 **Keep:** why (not what), non-obvious constraints, cross-cutting context, pointers when a relationship isn't obvious, sentinels/magic values, the rejected alternative, storage/runtime quirks (sync-vs-async read path, `instanceof Promise` gating, cross-tab identity compare).
 
-**Cut:** file inventories, pasted signatures, restating the next line, generic library practice, duplicate facts across README/architecture/glossary.
+**Cut:** file inventories, pasted signatures, restating the next line, generic library practice, duplicate facts across README/architecture/glossary, tallied counts of re-derivable items ("16 subpaths", "158 tests") — the number goes stale the moment it changes and turns into errored info; the items (a table, a folder) carry the story, the number doesn't.
 
-**Comments/JSDoc:** 0 lines when self-explanatory; 1 line default; 2–3 only for irreducible gotchas; `>3 lines` → lift to `docs/` with one-line pointer. The shipped `.d.mts` should read well in hovers — `@param` / `@returns` / `@default` / `@example` carry the meaning; types stay, narrating them does not.
+**Comments/JSDoc:** 0 lines when self-explanatory; 1 line default; 2–3 only for irreducible gotchas; `>3 lines` → lift to `docs/` with one-line pointer. The shipped `.d.mts` should read well in hovers — `@param` / `@returns` / `@default` / `@example` (with real, resolving imports) carry the meaning when usage isn't obvious; types stay, narrating them does not.
+
+**Historical traces** in committed prose — "hydrated on …", "following up on …", changelog-edit residue, stale rosters — earn no ROI once the moment passes; write as if fresh, cut the trace. Source comments: the rule's "update if outdated" covers them.
 
 **Doc slimming:** full checklists in [`docs-governance`](../docs-governance/SKILL.md) (anchor preservation, existence test, anti-bloat).
 

.agents/skills/codemap/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: codemap
+description: Query codebase structure via SQLite instead of scanning files. Use when exploring code, finding where symbols are defined, tracing who imports what, listing components / hooks / CSS variables / deprecated symbols, walking dependency or call graphs, or auditing structural changes on a PR.
+---
+
+<!-- codemap-init:managed -->
+
+# Codemap skill
+
+Full content is served live by the installed `codemap` CLI, so version bumps carry today's reference automatically — no `agents init` re-run needed.
+
+- **CLI:** `codemap skill` → full markdown
+- **MCP:** read resource `codemap://skill`
+- **HTTP:** `GET /resources/{encoded-uri}` against `codemap serve`
+
+If `codemap` prints a pointer-protocol warning on startup, re-run `codemap agents init --force` to refresh this template.
+
+<!-- codemap-pointer-version: 1 -->

.agents/skills/harden-pr/LEDGER.md

@@ -11,7 +11,7 @@ By-design or false-positive findings — do not re-raise.
 ```
 
 <!-- Example:
-- **[correctness]** `src/persist-core.ts:147` — sync-first read path: by-design — sync backends settle pre-paint; async rides the same getItem Promise branch.
+- **[correctness]** `src/core/persist-core.ts:147` — sync-first read path: by-design — sync backends settle pre-paint; async rides the same getItem Promise branch.
 -->
 
 ## Deferred
@@ -21,3 +21,5 @@ Capped or out-of-scope-for-now — reconcile re-vets; remove lines when fixed.
 ```markdown
 - **[severity]** `file:line` — finding (deferred: out of scope | cap | blocked)
 ```
+
+- **[info]** `package.json` peerDependencies — `./frameworks/svelte` declares `svelte >=5.7.0` in source/README but `package.json` has `svelte >=3.0.0` shared with `./frameworks/svelte-store` (deferred: out of bounds — peer deps are package-level, not subpath-level; can't fix without splitting the svelte subpath into a separate package).

.agents/skills/improve-codebase-architecture/LANGUAGE.md

@@ -8,8 +8,8 @@ Shared vocabulary for every suggestion this skill makes. Use these terms exactly
 
 **Module**
 Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, a class, a file with a public surface, or a subpath entry.
-_Avoid_: unit, component, service. ("Component" conflicts with React component; use "Module" even when the module is `use-hydrated.ts`.)
-_Examples in this repo_: a single factory (`createStorage`); a subpath entry (`persist-idb.ts`); the core entry (`persist-core.ts` + `hydration.ts` behind `src/index.ts`); a codec (`persist-seroval.ts`).
+_Avoid_: unit, component, service. ("Component" conflicts with React component; use "Module" even when the module is `src/adapters/frameworks/react.ts`.)
+_Examples in this repo_: a single factory (`createStorage`); a subpath entry (`src/adapters/backends/idb.ts`); the core entry (`src/core/persist-core.ts` + `src/core/hydration.ts` behind `src/core/index.ts`); a codec (`src/adapters/codecs/seroval.ts`).
 
 **Interface**
 Everything a caller must know to use the module correctly. Includes the type signature, but also: invariants, ordering constraints, error modes, required configuration, the wire-type contract it depends on, the `HydrationSignal` observation contract.
@@ -31,7 +31,7 @@ _Examples in this repo_: the three seams in `docs/architecture.md` — **backend
 
 **Adapter**
 A concrete thing that satisfies an interface at a seam. Describes _role_ (what slot it fills), not substance (what's inside).
-_Examples in this repo_: each backend (`localStorage` adapter, `idb-keyval` adapter) is an adapter at the `StateStorage<TRaw>` seam; each codec (`persist-seroval`, a JSON passthrough) is an adapter at the `StorageCodec` seam; `useHydrated` is the React adapter at the `HydrationSignal` seam. Two adapters per seam = real seam (sync backend + async backend); one adapter = hypothetical.
+_Examples in this repo_: each backend (`localStorage` adapter, `idb-keyval` adapter) is an adapter at the `StateStorage<TRaw>` seam; each codec (`seroval`, a JSON passthrough) is an adapter at the `StorageCodec` seam; `useHydrated` is the React adapter at the `HydrationSignal` seam. Two adapters per seam = real seam (sync backend + async backend); one adapter = hypothetical.
 
 **Leverage**
 What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.

.agents/skills/improve-codebase-architecture/REFERENCE.md

@@ -10,13 +10,13 @@ When assessing a candidate for deepening, classify its dependencies:
 
 Pure computation, in-memory state, no I/O. Always deepenable — just merge the modules and test directly.
 
-> **Examples in this repo.** Most of `persist-core.ts`: the hydration gate, the write/throttle loop, the registry, the `migrate`/`buster`/`maxAge` helpers. Codec `encode` / `decode` (pure transforms between `StorageValue` and `TRaw`). `hydration.ts` (`HydrationSignal` construction).
+> **Examples in this repo.** Most of `src/core/persist-core.ts`: the hydration gate, the write/throttle loop, the registry, the `migrate`/`buster`/`maxAge` helpers. Codec `encode` / `decode` (pure transforms between `StorageValue` and `TRaw`). `src/core/hydration.ts` (`HydrationSignal` construction).
 
 ### 2. Local-substitutable
 
 Dependencies that have local test stand-ins. Deepenable if the test substitute exists. The deepened module is tested with the local stand-in running in the test suite.
 
-> **Examples in this repo.** An in-memory `StateStorage` map doubles for `localStorage` / `idb-keyval` in `bun:test` (no DOM, no real storage). A hand-rolled `PersistableSource` (a plain object with `getState` / `setState` / `subscribe`) doubles for a TanStack Store — `persist-core.test.ts` exercises the whole middleware without `@tanstack/store`. The `HydrationSignal` is observed from outside the store, so framework adapters test against a synthetic signal, not a real React tree (the `tests-dom` suite covers the React rerender path separately).
+> **Examples in this repo.** An in-memory `StateStorage` map doubles for `localStorage` / `idb-keyval` in `bun:test` (no DOM, no real storage). A hand-rolled `PersistableSource` (a plain object with `getState` / `setState` / `subscribe`) doubles for a TanStack Store — `src/core/persist-core.test.ts` exercises the whole middleware without `@tanstack/store`. The `HydrationSignal` is observed from outside the store, so framework adapters test against a synthetic signal, not a real React tree (the `tests-dom` suite covers the React rerender path separately).
 
 ### 3. Remote but owned (Ports & Adapters)
 
@@ -30,7 +30,7 @@ Recommendation shape: "Define a `StateStorage<TRaw>` port (already the seam), im
 
 Third-party services you don't control (`idb-keyval`, `seroval`, `react`, `@tanstack/store`). Mock at the boundary. The deepened module takes the external dependency as an injected port, and tests provide a mock / stand-in.
 
-> **Examples in this repo.** `idb-keyval` (the `persist-idb` subpath is the adapter; tests use the in-memory `StateStorage`); `seroval` (the `persist-seroval` codec is the adapter; tests use a JSON passthrough codec); `react` (`use-hydrated.ts` is the adapter; `tests-dom` is the only place a real React renderer runs); `@tanstack/store` (`persist-tanstack.ts` is the adapter; core tests use a synthetic source).
+> **Examples in this repo.** `idb-keyval` (the `./backends/idb` subpath is the adapter; tests use the in-memory `StateStorage`); `seroval` (the `./codecs/seroval` codec is the adapter; tests use a JSON passthrough codec); `react` (`src/adapters/frameworks/react.ts` is the adapter; `tests-dom` is the only place a real React renderer runs); `@tanstack/store` (`src/adapters/sources/tanstack-store.ts` is the adapter; core tests use a synthetic source).
 
 ## Seam discipline
 
@@ -64,7 +64,7 @@ This repo runs **oxlint only** (no ESLint, no `eslint-plugin-boundaries`). Archi
 oxlint resolves the **nearest** `.oxlintrc.json` for each file and **does not auto-merge with parents**. That has three concrete consequences:
 
 1. **Always set `extends`.** Every nested config must extend a parent config that ultimately reaches the repo-root `.oxlintrc.json`, otherwise baseline plugins/rules silently disappear for the files it owns.
-2. **The `!` negation in `files` does not work** in oxlint. A `files: ["**", "!persist-idb/**"]` override matches `persist-idb` files too, which silently shadows any `persist-idb`-specific rule defined in another override.
+2. **The `!` negation in `files` does not work** in oxlint. A `files: ["**", "!backends/idb/**"]` override matches `backends/idb` files too, which silently shadows any `backends/idb`-specific rule defined in another override.
 3. **Same rule key in two `overrides[]` matching the same file → later replaces earlier.** Patterns do not merge across overrides. Combine all applicable patterns into a single `no-restricted-imports` rule per scope.
 
 Because of (2) and (3), the cleanest pattern is **one config file per scope** — the repo-root config plus a deeper config for any `src/` subfolder that needs different rules. Each leaf `extends` its parent and re-declares any rules it wants to carry alongside its own.
@@ -74,7 +74,7 @@ Canonical example layout (if `src/` ever grows a subfolder needing its own rule)
 ```text
 .oxlintrc.json                 ← baseline only
 src/.oxlintrc.json             ← extends root, core zero-dep value-import ban
-src/persist-idb/.oxlintrc.json ← extends ../, idb subpath-specific rules
+src/adapters/backends/.oxlintrc.json ← extends ../, backends-seam-specific rules
 ```
 
 Example leaf for a directional rule (keep `persist-core` / `hydration` free of peer-dep value imports — the zero-dep gate):
@@ -89,13 +89,7 @@ Example leaf for a directional rule (keep `persist-core` / `hydration` free of p
       {
         "patterns": [
           {
-            "group": [
-              "seroval",
-              "idb-keyval",
-              "@tanstack/store",
-              "react",
-              "react-dom"
-            ],
+            "group": ["seroval", "idb-keyval", "@tanstack/store", "react"],
             "message": "Zero-dep core: peer deps are subpath opt-in, not core imports. Use the matching subpath entry."
           }
         ]
@@ -173,6 +167,6 @@ Which category from `REFERENCE.md` applies and how dependencies are handled:
 - **File naming**: don't add a `-plan` suffix — the `plans/` folder provides context. `docs/plans/<short-kebab-name>.md`.
 - **Roadmap link format**: `[<title>](./plans/<file>.md)` under the appropriate section in `docs/roadmap.md`.
 - **Boundary candidates that need lint enforcement** should propose the exact `.oxlintrc.json` block in the same plan — see [Boundary enforcement](./REFERENCE.md#boundary-enforcement-oxlint) above.
-- **Public-surface changes**: when the candidate touches the package public API (an `exports` map entry, a shipped `.d.mts`, the root `README.md`), the plan must include the migration path for **every** consumer-reachable import (and a changeset entry). The published typings are the public surface — don't guess; enumerate via `package.json` `exports` + `src/index.ts` re-exports.
+- **Public-surface changes**: when the candidate touches the package public API (an `exports` map entry, a shipped `.d.mts`, the root `README.md`), the plan must include the migration path for **every** consumer-reachable import (and a changeset entry). The published typings are the public surface — don't guess; enumerate via `package.json` `exports` + `src/core/index.ts` re-exports.
 - **Pure dead-code removal is not a plan candidate.** Those go directly into `docs/roadmap.md`. This skill is for plans that need design discussion.
 - **Glossary cross-reference**: when the proposal renames or introduces a domain term, link to (and on the same PR, update) [`docs/glossary.md`](../../../docs/glossary.md). If there's no entry yet and the term is genuinely domain-bearing, recommend [`domain-modeling`](../domain-modeling/SKILL.md) first.

.agents/skills/pr-comment-fact-check/SKILL.md

@@ -19,7 +19,7 @@ description: STOP and fact-check PR review comments before applying or dismissin
 
 Common LLM-reviewer patterns on this repo:
 
-1. **"This isn't tested" without checking siblings** — `persist-core` contracts are pinned across `persist-core.test.ts`, `persist-seroval.test.ts`, `persist-idb.test.ts`, `persist-tanstack.test.ts`; `useHydrated` spans `src/use-hydrated.test.ts` (bun, SSR/snapshot) **and** `tests-dom/**/*.test.tsx` (vitest, rerender/detach). Verify coverage before accepting.
+1. **"This isn't tested" without checking siblings** — `persist-core` contracts are pinned across `src/core/persist-core.test.ts`, `src/adapters/codecs/seroval.test.ts`, `src/adapters/backends/idb.test.ts`, `src/adapters/sources/tanstack-store.test.ts`; `useHydrated` spans `src/adapters/frameworks/react.test.ts` (bun, SSR/snapshot) **and** `tests-dom/**/*.test.tsx` (vitest, rerender/detach). Verify coverage before accepting.
 2. **Type-safety alarms** — if `bun run typecheck` (tsgo) passes, the claim is almost always wrong, or about runtime behavior the type system can't see (then the reviewer must justify with the runtime case).
 3. **Generic "best practice" claims unsupported by our rules** — "always destructure", "prefer interfaces over types", "add `useMemo`/`useCallback`" — stylistic; we either have a rule or we don't. Grep `.agents/` for the convention.
 4. **Convention citations that don't exist** — "this breaks the library's API conventions" — grep `.agents/` + `docs/architecture.md`. If not codified, it's preference, not rule.