Secrets Documentation Audit — 2026-07-02
Auditor: Claude Code (p24-infra session)
Scope: All secrets, credentials, and rotation documentation in docs/ and .claude/
Trigger: User request — review rotation playbooks, identify overlaps and navigation issues for /role-secret-manager
Status: Complete — P0+P1 remediation applied same session
Documents audited (12 files)
| File | Lines | Role |
|---|---|---|
CLAUDE.md §Secrets | ~35 | Governance overview |
docs/secrets-management.md | 241 | General SOPS guide (pre-role-system era) |
docs/secrets-sops-age.md | 161 | CI/CD + automation perspective |
docs/playbooks/secret-manager.md | 271 | Master playbook (single source of truth) |
docs/playbooks/secret-rotation-access-matrix.md | 249 | Tier 1/2/3 classification (75 keys) |
docs/playbooks/static-api-key-incident-rotation.md | 383 | Exposure incident response |
docs/playbooks/sops-windows-crlf.md | 235 | CRLF/BOM corruption recovery |
docs/playbooks/sops-edit-operations.md | 178 | SOPS edit bugs + patterns |
docs/playbooks/credential-rotation-180d.md | 100+ | Scheduled rotation procedures |
docs/playbooks/credential-rotation-policy.md | 270 | Policy, SLAs, decision trees |
.claude/task-playbooks/credential-rotation.md | 41 | Session entry point (task detection) |
docs/playbooks/credential-rotation-manual-static.md | 80+ | Manual rotation procedures |
Additionally: 55+ per-service rotation playbooks confirmed to exist in docs/playbooks/.
Findings
CRITICAL (P0) — Fixed
F1: CLAUDE.md §Secrets points to deprecated file
CLAUDE.md line 112 said Full playbook: docs/secrets-management.md.
docs/secrets-management.md is a pre-role-system document with only 5 SOPS files listed (current is 9).
docs/playbooks/secret-manager.md is the actual single source of truth (last updated 2026-07-01).
Fix applied: Changed CLAUDE.md §Secrets pointer to docs/playbooks/secret-manager.md.
HIGH (P1) — Fixed
F2: No navigation map in secret-manager.md
A session loading secret-manager.md had no guidance on which of the 12 documents to load next.
Without a navigation map, sessions defaulted to reading everything or guessing.
Fix applied: Added ## Navigation — what to load for each task section to secret-manager.md immediately after the startup sequence.
F3: credential-rotation.md task-playbook was a quick checklist, not a dispatcher
The entry-point task playbook attempted to be a self-contained checklist instead of routing to the right document. It also had a stale reference to docs/secrets-management.md.
Fix applied: Rewrote .claude/task-playbooks/credential-rotation.md as a 3-step dispatcher (identify scenario → check tier → execute via secret-manager.md).
MEDIUM (P2) — Open
F4: Windows SOPS write pattern duplicated in 5 places
[System.IO.File]::WriteAllText pattern with UTF8Encoding($false) appears in:
docs/playbooks/secret-manager.mddocs/playbooks/sops-windows-crlf.mddocs/playbooks/sops-edit-operations.mddocs/playbooks/static-api-key-incident-rotation.mdCLAUDE.md §Secrets
No contradictions found. Risk: future update applied to only one location.
Recommended fix: Extract to docs/playbooks/sops-windows-patterns.md, replace inline copies with one-line references. (Not applied this session — low urgency, no active bug.)
F5: docs/password-rotation-procedures.md — FINDING INCORRECT (closed)
Post-audit grep confirmed the file EXISTS at docs/password-rotation-procedures.md.
Initial scan missed it. No action needed — finding closed.
Gap-monitoring check in worker-secret-manager.md §Gap Monitoring will correctly find the file on workers and skip issue creation.
LOW (P3) — Not actioned
F6: Tier decision tree in 4 places
Appears in secret-manager.md, secret-rotation-access-matrix.md, credential-rotation-policy.md, .claude/task-playbooks/credential-rotation.md.
No contradictions. Intentional redundancy for self-contained documents.
Future risk: drift on tier reclassification.
What was NOT found
- Zero contradictions between any documents on tier classifications, SLAs, or procedures
- Zero cases where a general rule in
secrets-management.mdoverrides a specific playbook docs/secrets-management.mdalready had a primary-reference banner pointing tosecret-manager.mdat the top of the file (added previously) — only CLAUDE.md was still pointing to the wrong file
Changes made this session
| File | Change |
|---|---|
CLAUDE.md | §Secrets: changed Full playbook pointer from docs/secrets-management.md to docs/playbooks/secret-manager.md |
docs/playbooks/secret-manager.md | Added ## Navigation section (reading map) after startup sequence |
.claude/task-playbooks/credential-rotation.md | Rewritten as 3-step dispatcher, removed stale reference |
docs/audits/INDEX.md | Created (new audits index) |
docs/audits/2026-07-02-secrets-documentation-audit.md | Created (this file) |
.claude/agent-prompts/worker-secret-manager.md | Created (new worker role for queue-based secret operations) |
New capability added: worker-secret-manager
A dedicated autonomous worker role was created at .claude/agent-prompts/worker-secret-manager.md.
Capabilities:
- Add / rotate / remove secrets in SOPS autonomously (Tier 1 only)
- Authorization check: validates that the requester has scope to request the specific SOPS file
- Gap monitoring: detects missing playbooks, missing log entries, stale secrets
- Self-healing: creates GH issues for gaps, pushes missing GH Secrets from SOPS, creates missing stubs
Queue job type: secret-manager
Primary server: bms-4
Next audit recommendation
Next review: 2026-10-02 (90 days) Trigger: Earlier if a Tier classification changes or a new SOPS file is added. Scope to cover next time: Per-service playbooks consistency check (55+ files not audited this session).