chore(docs): decouple code/docs references from plans/ ahead of going private

The <= rc12 upgrade guide ships in the v0.10.0 release notes (paste-ready
block added to the #616 PR body); plans/ is heading to a private location.
Every reference from public, durable surfaces is now self-contained:

- CLAUDE.md pitfall 16 + troubleshooting.md: full fix inline, pointer to the
  release notes instead of plans/volume-permission-hardening.md
- flows/lib.sh: stale-binary pitfall described inline (was citing the
  deleted v1337 buy report)
- agent_contract_integration_test.go: drops the deleted sell-agent-perf.md
  citation (the reasoning survives in the comment)
- cmd/obol/sell_agent.go: demo-label TODO self-contained (was citing
  openapi-402-followups.md)
- docs/observability.md: deleted QA reports referenced via git history

Remaining plans/ mentions are intentional: the CLAUDE.md conventions line,
observability's explicit git-history pointer, and the SKILL.md path table.

Author: bussyjd

.agents/skills/obol-stack-dev/references/troubleshooting.md

@@ -41,7 +41,7 @@ state.db / config.yaml; x402-buyer exits `load state:` at startup, killing
 every `paid/<model>` route. Fix: recreate the cluster (`stack down` →
 `purge -f` → `init` → `up`; back up agent wallets first), or for k3d chown
 the PV backing dirs to 1000:1000 from inside the node and restart the pods.
-See plans/volume-permission-hardening.md "Upgrading from <= v0.10.0-rc12".
+Full steps: v0.10.0 release notes, "Breaking changes".
 
 ### k3d port 80 privileged on macOS
 

CLAUDE.md

@@ -389,7 +389,7 @@ A registry digest pin instead of `:latest` on the verifier means your dev rewrit
 14. **First-request flake on freshly-deployed verifier** — the first request after `x402-verifier` becomes Ready can return an empty body / Bad Gateway from Traefik because the HTTPRoute is wired but the verifier's serviceoffer-source watcher has not loaded the route yet. `flows/flow-07-sell-verify.sh` and `flows/flow-08-buy.sh` wrap the 402-body fetch in a 12x5s retry loop. Do not extend retry loops elsewhere to mask intermittents — this one is a real first-request race.
 
 15. **"0 spent" is not proof no money moved** — an error response (>= 400) carrying `X-PAYMENT-RESPONSE` with a tx hash means the facilitator settled on-chain and THEN failed; the buyer marks that auth consumed, buy.py prints a settled-on-chain warning. Chain is canonical; see `docs/observability.md` ("Verify settlement against the chain").
-16. **Clusters created on <= v0.10.0-rc12 keep hostPath-typed PVs** — kubelet ignores `fsGroup` there, and v0.10.0's non-root pods (UID 1000, no chown inits) cannot read the legacy 10000-owned data. Supported path: recreate the cluster (wallet backup/restore). See `plans/volume-permission-hardening.md` "Upgrading from <= v0.10.0-rc12".
+16. **Clusters created on <= v0.10.0-rc12 keep hostPath-typed PVs** — kubelet ignores `fsGroup` there, and v0.10.0's non-root pods (UID 1000, no chown inits) cannot read the legacy 10000-owned data. Supported path: recreate the cluster (wallet backup/restore); full steps in the v0.10.0 release notes (Breaking changes).
 
 For a fuller debug catalog with symptom->fix mapping, see `.agents/skills/obol-stack-dev/references/release-smoke-debugging.md`.
 

cmd/obol/sell_agent.go

@@ -426,8 +426,9 @@ func runAgentBackedDemo(
 			// "demo" from offer.namespace alone. The obol.org/demo
 			// label is the explicit signal — keep it set here so quant
 			// and friends show up under "Demo services" on the
-			// storefront. Drop this once we relax the cross-namespace
-			// guard (see plans/openapi-402-followups.md).
+			// storefront. Drop this once the catalog renderer's
+			// cross-namespace guard is relaxed to infer demo offers
+			// from their namespace.
 			"labels": map[string]any{"obol.org/demo": "true"},
 		},
 		"spec": specMap,

docs/observability.md

@@ -418,9 +418,9 @@ contributors: if you write a guarded division, the epsilon is `1e-9`.
 
 ### Reports
 
-- The OBOL parity integration test report — see `plans/` for the most recent
-  `release-smoke-hardening-*.md` and `post-490-integration-*.md` entries that
-  reference the metric audits behind PRs #527 / #530 / #531.
+- The OBOL parity integration test reports (metric audits behind PRs #527 /
+  #530 / #531) lived in `plans/release-smoke-hardening-*.md` and
+  `plans/post-490-integration-*.md`; retrieve them from git history.
 
 ---
 

flows/lib.sh

@@ -531,8 +531,8 @@ bootstrap_flow_workspace() {
     # Pick the freshest of the caller-supplied binary and the workspace binary.
     # During iteration on embedded skill content (e.g. buy-x402/scripts/buy.py)
     # it is easy to rebuild one and forget the other; copying the stale one
-    # silently bakes pre-fix files into the cluster PVC. See pitfall in
-    # plans/inference-v1337-buy-report-20260514.md (v1337 attempt 5).
+    # silently bakes pre-fix files into the cluster PVC (root-caused during
+    # the 2026-05-14 v1337 live-buy QA session).
     if [ -f "$obol_bin" ] && [ -f "$workspace_bin" ] && [ "$obol_bin" != "$workspace_bin" ]; then
         picked_mtime=$(stat -c %Y "$obol_bin" 2>/dev/null || stat -f %m "$obol_bin" 2>/dev/null || echo 0)
         other_mtime=$(stat -c %Y "$workspace_bin" 2>/dev/null || stat -f %m "$workspace_bin" 2>/dev/null || echo 0)

internal/agentcrd/agent_contract_integration_test.go

@@ -270,9 +270,9 @@ func containsListItem(yamlBody, item string) bool {
 // skills" / "no-bundled-skills" line: that string is owned by the external
 // nousresearch/hermes-agent image, is not referenced anywhere in this repo, and
 // could change wording or log level across image bumps without our knowledge —
-// grepping for it would be a brittle, unverifiable contract. The plan
-// (plans/sell-agent-perf.md, Verification) only ever treated the log line as an
-// eyeball aid, not an assertion.
+// grepping for it would be a brittle, unverifiable contract. Earlier
+// verification notes only ever treated the log line as an eyeball aid, not
+// an assertion.
 //
 // The reliable, image-version-independent signal is the pod's on-disk skills
 // layout: when the marker is honored, Hermes seeds NONE of its ~80 bundled