Skip to content

DOCS-011: docs housekeeping sweep — archive obsolete entries, dead links, stale comments and counts #683

Description

@mlorentedev

Source: docs audit 2026-07-07 (docs/audits/docs-audit-2026-07-07.md) — findings D12, D13, D14, D15, D17, D18, D19, D22, D23, D27 (CONFIRMED).

Mechanical sweep, one PR:

  • Archive: docs/troubleshooting/setup-windows-session-hook-path.md (resolved; about a retired script) → troubleshooting/archive/; docs/runbooks/guide-gemini-cli-recovery.md (self-declared obsolete; sunset 2026-06-18 passed) → new runbooks/archive/ or frontmatter status: archived (pick one convention — audit Q6).
  • Dead links (3): adr-026pattern-knowledge-placement (vault note linked as repo path); hive-mcp-rejection-disconnect.mdclaude-mem-broken-marketplace.md (moved to archive/); archive/claude-mem-broken-marketplace.mdai-tools.md (missing ../). Durable guard for this class = GUARD-002: CI guard against env-mapping.conf resurrection and dead docs refs #669 scope.
  • Broken alias: .zsh/aliases.zsh:32 clchangelog-gen.sh (deleted; changelog is release-please) — remove.
  • Symlink-vs-copy drift: tmux.conf:2 header, guide-tmux.md §deploy, arch-map row all say symlink; deploy is deploy_file copy (ADR-012).
  • Retired-script mentions in config comments: env-contract.json _comment + DOTFILES_DIR description, session-start-config.json doctor_drift comment (cite doctor.{sh,ps1}).
  • specs/README.md counts (~26 active/~44 archived → 57/75) — reword to avoid rot.
  • docs/README.md: index architecture.md + secrets-inventory.md + audits/; add a small task-routing table.
  • docs/lessons.md: add a TOC/topic index at top (keep append-only body).
  • docs/architecture.md:27: .zsh/ "(aliases, completions)" → actual contents (aliases, functions, nvm).
  • docs/secrets-inventory.md: add historical banner (2026-06 snapshot; secrets/registry.yaml is SSOT) + one reader-facing paragraph on the GUARD-002: CI guard against env-mapping.conf resurrection and dead docs refs #669 env-mapping split-brain — final disposition per audit Q3.
  • AGENTS.md:31 "37 universal patterns" → 72 (or unpinned wording).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions