feat: transparency manifest — attested 'what this tool read' section

[gkanitz]

Context

Slice G of the v0.2 "Meaning" wave — the org-comfort slice. Shared design
context: docs/superpowers/specs/2026-07-04-impact-roadmap-design.md
(PR #47).

The known adoption bottleneck is org-admin approval. Today the
data-minimization story is "trust us + read the source". This slice turns it
into a verifiable claim inside the attested report: a machine-readable
manifest of every API route class the run called (with counts) plus an
explicit "never requested" declaration, rendered as a plain-language
"What this tool read" section.

Goal (vertical slice)

Counting middleware in both provider adapters → access_manifest schema
block → rendered section, end to end — with a structural guarantee that the
manifest can never silently go stale.

In scope

• HTTP middleware wrapping each adapter's client: every outgoing request must
  resolve to a registered route class (REST route template like
  rest:list_pulls, or GraphQL query name like graphql:pr_diff_shape).
  An unresolvable request is an error in tests — this is the honesty
  invariant that keeps the manifest complete as the codebase evolves.
• Route classes are static template names. Never URLs: no owner, repo,
  username, or PR number may appear in a class string.
• Schema (additive): access_manifest {endpoints [{class, count}], never_requested [], notes}. Present in every report, local and CI.
• never_requested is a static per-adapter declaration, minimum: file
  contents, diffs/patches, branch names, colleague profiles, commit
  contents. Rendered verbatim.
• Render: "What this tool read" section — plain-language summary (route
  classes with counts, in reader terms) + the never-requested list, phrased
  for an org admin and a recruiter, not an engineer.
• Docs: employer one-pager (docs/employer-onepager.md) gains a short
  paragraph pointing at the manifest as the verifiable data-minimization
  claim.

Out of scope

• Org policy files (v0.4), any new metrics, changing what the tool fetches.

Design constraints

• Privacy safeguards catalog (spec): GitHub Action wrapper with Sigstore attestation and pinned-version verification #6 prohibited-strings extended to the
  new section; class strings are covered by the no-identifier rule above.
• Adapters must construct their HTTP/GraphQL clients only through the
  counting wrapper — QA verifies no direct client construction remains.

Acceptance criteria — TDD

Success (write these tests first; all must pass)

1. Integration test: a full pipeline run against the recorded fixture
   servers produces a manifest whose per-class counts exactly equal the
   fixture servers' request logs (both providers).
2. Unregistered-route enforcement: a test that makes one request to an
   unregistered path fails through the middleware with a distinct error —
   proving new endpoints cannot ship without a manifest entry.
3. Class-string hygiene: no class string contains /, an owner/repo name,
   a username, or a number derived from fixtures (property-checked against
   the registered set).
4. GraphQL calls (from feat: GraphQL diff-shape fetch — per-PR file stats without patch content (GitHub + GitLab) #49) appear under their own query-name classes with
   correct counts.
5. never_requested list is static per adapter and rendered verbatim in
   HTML (golden); the report JSON carries the same list (round-trip +
   Validate; pre-v0.2 sample JSON still validates).
6. Manifest present in local unverified runs too (golden on the sparse
   fixture).
7. Rendered "What this tool read" golden: plain-language section with
   counts and the never-requested list; prohibited-strings test passes.
8. Cache interaction: requests served from the existing API cache still
   count once per actual HTTP request, not per logical lookup (test pins
   the semantics: the manifest reports wire traffic).

Failure — QA red flags (any one observed → reject the PR)

• Any count that can drift from actual wire traffic (e.g. counters
  incremented in call sites instead of middleware).
• A way to make requests that bypasses the middleware (direct
  http.Client/GraphQL client construction in adapters).
• URLs, repo names, usernames, or PR numbers in class strings or the
  rendered section.
• Manifest absent from any report mode.
• never_requested generated dynamically (it is a reviewed, static
  declaration — that is what makes it an auditable claim).

Parallel-work contract

• Territory: provider/ middleware + registration tables,
  render/templates/sections/ (new numbered partial), goldens,
  docs/employer-onepager.md.
• Shared, additive-only: report/report.go (new block only),
  provider/provider.go, render/render.go, layout.tmpl (include line).
• Depends on: feat: GraphQL diff-shape fetch — per-PR file stats without patch content (GitHub + GitLab) #49 (GraphQL classes must exist). Merge order: last in
  the milestone — after feat: banded context layer — cited typical ranges under every KPI #48, feat: verified share card — attested card.svg/card.png artifact #50, feat: PR-size stats + size-normalized review depth (implements #26) #52, feat: verified tech-stack fingerprint — language mix from merged-PR diff lines #53, feat: narrative front page + interviewer kit (render-only, rule-derived) #54 — so the registered-route
  table and manifest reflect the wave's final access surface. Starting work
  earlier is fine; final rebase must re-run the integration counts.

Definition of done

TDD skill followed; all success criteria green; go test ./... passes;
PR references this issue.