chore(docs): codify known_issues/ resolved-sweep convention and apply it to the backlog

[cristim]

Summary

Project-wide hygiene gap surfaced during the #41 / #42 audit: every known_issues/*.md doc carries a header like

> **Audit status (2026-04-22):** `1 needs triage · 0 resolved (new file)`

When the underlying issue closes (e.g., #41 was closed in PR #67, #42 in the same PR, #43 in PR #64), the corresponding doc is left in place with 0 resolved unchanged. There's no documented sweep convention and no archive/resolved subdirectory. As of today (2026-04-27), known_issues/25_*.md, 26_*.md, 27_*.md (and probably more) all show stale "needs triage" status for issues that have shipped.

This makes the directory progressively less useful: a reader can't tell which docs are open work vs. historical context, and the audit-status counts are wrong.

Current state

$ ls known_issues/ | wc -l
30+
$ for f in known_issues/2[567]*.md; do
    head -3 "$f" | grep "Audit status"
  done
> **Audit status (2026-04-22):** `1 needs triage · 0 resolved (new file)`
> **Audit status (2026-04-22):** `1 needs triage · 0 resolved (new file)`
> **Audit status (2026-04-22):** `1 needs triage · 0 resolved (new file)`

…even though #41, #42, #43 are all closed.

Proposed fix

Pick one of three conventions and apply it consistently:

1. Archive on resolve: move resolved docs to known_issues/resolved/ (keeps the audit trail, surfaces only open work in the top-level directory).
2. Update audit-status header on resolve: bump the M resolved count and add the closing PR ref. Doc stays in place.
3. Delete on resolve: rely on git history for the audit trail. Cleanest filesystem state, but loses the "context that prompted the issue" once the entry is gone.

My read: option 1 (archive) is the best balance — preserves searchability of why a fix was made (a developer 6 months from now grepping known_issues/ for "federation source-identity" still finds context) without polluting the active triage queue.

Whichever option lands, codify it as a one-paragraph entry in CLAUDE.md (project-level) so the next "fix and forget" round doesn't accumulate again.

Scope of the cleanup sweep

Audit every doc in known_issues/, cross-reference against the closing-PR list, and apply the chosen convention. As of 2026-04-27, at least these docs are stale (their referenced issues are CLOSED):

• 25_federation_azure_gcp_source_identity_failloud.md (closed via fix(api): extend federation source-identity fail-loud guard to Azure and GCP deployments #41 → PR fix(api): pre-flight validation for federation IaC bundles (target/source + Azure/GCP source-identity) #67)
• 26_federation_target_source_consistency.md (closed via fix(api): reject impossible federation target/source combinations with HTTP 400 #42 → PR fix(api): pre-flight validation for federation IaC bundles (target/source + Azure/GCP source-identity) #67)
• 27_federation_old_bundle_redownload_notice.md (closed via docs(release-notes): tell customers with pre-zero-touch federation bundles to re-download #43 → PR docs(release-notes): tell pre-zero-touch federation bundle customers to re-download #64)
• Likely more — full sweep needed.

Effort

Medium — 30–60 min for the audit + apply + add the convention paragraph to CLAUDE.md. Not blocking any feature work; suitable as a low-priority chore.

References

• Audit note that surfaced this: fix(api): extend federation source-identity fail-loud guard to Azure and GCP deployments #41 (comment) ("Notes" section)