docs(docs): close audit findings — ADR gap rule, audits lifecycle, agent files

[Skords-01]

Summary

Closes the quick-win findings of the 2026-05-02 doc-hygiene audit:

• ADR gap detection. New rule Claude/review project structure l2 ke1 #6 in scripts/docs/check-adr-graph.mjs (findNumberingGaps() + KNOWN_NUMBERING_GAPS allowlist) — any new sequential gap fails CI. 0029 is whitelisted with a comment pointing at the README explainer; future undocumented skips will be caught.
• ADR README. Refreshes header, replaces the stale «наступний номер 0031» line with a proper «Note on missing 0029» blockquote and clarifies that the next ADR is 0032.
• Audits index. Adds a Status column + a Lifecycle section (Active / Closed / Archived) to docs/audits/README.md and assigns a status per row.
• UX 2025 audit archived. Physically moved docs/audits/ux-audit-2025.md → docs/audits/archive/ux-audit-2025.md, flipped Status: Active → Archived, added an archival blockquote pointing at the canonical design system + UX-IMPROVEMENT-PLAN. freshness-config.json and the example in docs/governance/doc-freshness.md were updated to the new path so coverage stays green.
• Agent files unified. CLAUDE.md / DEVIN.md are now parallel thin pointers to AGENTS.md with a single-source-of-truth callout; redundant «Канонічні посилання» clones removed, only agent-specific bullets kept.
• Audit doc itself committed as docs/audits/2026-05-02-doc-hygiene-audit.md (Status: Active) so the findings + fixes are auditable later.
• Tests. scripts/docs/__tests__/check-adr-graph.test.mjs gets 10 new tests for findNumberingGaps, the validator integration, and a guard pinning 0029 membership in the allowlist.

No runtime / app code touched; this is doc + governance-script-only.

Governing Skill

• Primary skill: n/a (doc-hygiene cleanup; followed audit checklist)
• Secondary skill (if truly needed): n/a

Playbook

• Primary playbook: n/a
• Why this playbook: n/a
• If no playbook matched, why: doc-hygiene fixes spanning ADR registry / audits index / agent files don't match a single playbook surface. Each touched area still respects its own conventions (ADR rules, freshness-config schema, hard rule Claude/review project structure l2 ke1 #15).

Verification

node scripts/docs/check-adr-graph.mjs
# → [check-adr-graph] OK — 30 ADR(s) checked, graph is consistent.

node --test scripts/docs/__tests__/check-adr-graph.test.mjs
# → 34 pass / 0 fail (10 new gap-rule tests included)

pnpm lint
# → all suites pass; tech-debt freshness OK; openapi snapshot fresh

node scripts/docs/check-freshness.mjs --check-coverage
# → All tracked markdown files have a freshness header.

Additional checks:

• check-adr-graph CI gate passes locally
• freshness coverage check passes after the archive/ rename
• commitlint + lint-staged hooks ran (no --no-verify); prettier + bump-last-validated auto-applied

Docs and Governance

• I updated docs that changed with the behavior, contract, workflow, or rollout.
• I checked whether AGENTS.md needed an update. (No — Hard Rules untouched; CLAUDE/DEVIN now point at it more explicitly.)
• I checked whether a playbook or skill needed an update. (No — none reference the renamed ux-audit-2025 path.)
• I checked whether governance docs or review docs needed an update. (Yes — doc-freshness.md example path bumped.)

Updated docs:

• docs/adr/README.md — gap explainer + freshness bump
• docs/audits/README.md — Status column + Lifecycle section
• docs/audits/archive/ux-audit-2025.md — flipped to Archived (renamed)
• docs/audits/2026-05-02-doc-hygiene-audit.md — new historical record
• docs/governance/doc-freshness.md — example path
• CLAUDE.md, DEVIN.md — thin-pointer rewrite

Risk and Rollout

• User-visible risk: none. No app/runtime/CI workflow code changed; only doc content + a new validator rule.
• Rollout / deploy order: merge anytime. The new check-adr-graph rule activates immediately on next CI run; current tree is already compliant (validator passes locally).
• Backout plan: revert the PR. The ADR file rename (ux-audit-2025.md → archive/) is the only path-sensitive change — tracked via git mv, fully reversible. KNOWN_NUMBERING_GAPS allowlist is data-only; removing it would re-fail CI until 0029 is filed or re-whitelisted.

Hard Rule #15

• I read AGENTS.md before coding.
• Internal docs I touched are in Ukrainian.
• I did not use --no-verify.

Reviewer Notes

Worth a closer look:

1. Historical claim about ADR-0029 in docs/adr/README.md and KNOWN_NUMBERING_GAPS comment: «0029-кандидат (per-source AI-memory ingestion gating) був згорнутий в ADR-0028 під час рев'ю». This was reconstructed from git log of the 2026-05-02 parallel sessions — please sanity-check the framing matches your recollection. If it doesn't, the README blockquote and the KNOWN_NUMBERING_GAPS inline comment are the two places to adjust.
2. Lifecycle assignments in the new docs/audits/README.md Status column are inferred from filename + content (Closed for one-shot assessments, Active for trackers / templates). If any of 2026-04-26-sergeant-audit-devin.md, 2026-04-28-sergeant-comprehensive-audit.md, or UX-UI-AUDIT-2026.md is still actively driving work, flip its row from Closed → Active.
3. findNumberingGaps() window semantics: it scans between min(numbers) and max(numbers) of the present ADRs. If the very first ADR (0001) is ever deleted, the window silently shifts; the rule still catches new gaps but won't notice a missing prefix. Acceptable for the intended use-case (catching parallel-session collisions at the front of the list) but worth flagging.
4. Auto-bumped freshness signatures: the bump-last-validated lint-staged hook re-attributed all touched freshness headers to @Skords-01 (the committer). This is the hook's intended behavior but might look surprising in the diff for files where the audit text mentions @claude.
5. No code surface touched — apps/*, packages/*, workflows, runtime configs are all untouched. Diff is concentrated in docs/, scripts/docs/, plus the two root agent files.

Link to Devin session: https://app.devin.ai/sessions/fc46ff4a13544e01a3dc6aebe8ddbc34

---

Summary by cubic

Adds a CI rule to catch gaps in ADR numbering and cleans up docs per the 2026‑05‑02 doc‑hygiene audit. Also refreshes the audits index, archives the 2025 UX audit, and makes AGENTS.md the clear source of truth for agent docs.

• New Features

  • Added findNumberingGaps() and a new gap rule in scripts/docs/check-adr-graph.mjs; 0029 whitelisted in KNOWN_NUMBERING_GAPS with docs.
  • Added tests in scripts/docs/__tests__/check-adr-graph.test.mjs, including a guard for 0029.
  • Updated docs/adr/README.md with “Note on missing 0029” and clarified the next ADR is 0032.
  • Added a Status column and lifecycle to docs/audits/README.md; moved docs/audits/ux-audit-2025.md to docs/audits/archive/ (Archived) and updated paths in scripts/docs/freshness-config.json and docs/governance/doc-freshness.md; added docs/audits/2026-05-02-doc-hygiene-audit.md.
  • Rewrote CLAUDE.md and DEVIN.md as thin pointers to AGENTS.md with agent-specific notes only; no runtime/app code changed.

• Migration

  • No action needed. The new ADR rule runs in CI and the repo already passes.

^{Written for commit 8c84c84. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation

  • Added comprehensive doc-hygiene audit documentation capturing repository documentation state and improvements.
  • Reorganized audit lifecycle with active, closed, and archived audit categories.
  • Archived 2025 UX audit documentation with pointers to current design resources.
  • Updated documentation governance and freshness tracking policies.

• Chores

  • Enhanced repository documentation validation for consistency.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sergeant	Ready	Preview, Comment	May 2, 2026 9:33pm

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Documentation audit identifying and enforcing ADR numbering consistency, refactoring agent-specific guidance documents as thin pointers to a central authority, archiving stale audit records, and extending ADR graph validation with a configurable known-gaps allowlist.

Changes

Documentation Hygiene and ADR Numbering

Layer / File(s)	Summary
ADR Numbering Constants scripts/docs/check-adr-graph.mjs	Introduces KNOWN_NUMBERING_GAPS set containing whitelisted ADR numbers (e.g., "0029") and exports findNumberingGaps() to compute missing 4-digit ADR numbers between observed min/max.
Graph Validation Logic scripts/docs/check-adr-graph.mjs	validateGraph() now enforces sequential ADR numbering by reporting gaps not present in KNOWN_NUMBERING_GAPS, with corresponding documentation required in docs/adr/README.md.
Governance Pointer Documents CLAUDE.md, DEVIN.md	Both files refactored as thin pointers to AGENTS.md as the single source of truth; updated startup flow steps to reference playbooks under docs/playbooks/ as canonical recipes and clarified production surface paths (governance, skills, playbooks).
ADR and Audit Metadata docs/adr/README.md, docs/audits/README.md	ADR README documents the known 0029 gap and corrects next ADR number to 0032; audits README adds ## Lifecycle section (Active/Closed/Archived) and restructures table with Status column.
Audit Lifecycle Management docs/audits/archive/ux-audit-2025.md, scripts/docs/freshness-config.json	Moves ux-audit-2025.md to archive folder with updated metadata (Status: Archived); freshness config path updated to reflect new location.
Comprehensive Audit Document docs/audits/2026-05-02-doc-hygiene-audit.md	New audit documenting repo-wide doc hygiene state, ADR gap fixes, audit lifecycle changes, thin-pointer migrations, freshness header policy, stale claims inventory, CI/workflow overview, and pickup tasks (quick wins resolved, medium/larger follow-ups noted).
Freshness Tracking Updates docs/governance/doc-freshness.md	Refreshes validation metadata and updates cadence override path from docs/audits/ux-audit-2025.md to docs/audits/archive/ux-audit-2025.md.
ADR Validation Tests scripts/docs/__tests__/check-adr-graph.test.mjs	Adds unit tests for findNumberingGaps() (empty input, contiguous ranges, single/multiple gaps, allowlisting, 4-digit padding, null handling) and validateGraph() (undocumented gaps flagged, whitelisted 0029 passes).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• PR #1200: Extended ADR graph validator with KNOWN_NUMBERING_GAPS allowlist and findNumberingGaps() function to detect and document numbering gaps in the ADR registry.
• PR #711: Proposes creation of centralized AGENTS.md and playbook templates, which directly informs the thin-pointer refactoring of CLAUDE.md and DEVIN.md in this PR.
• PR #1150: Modifies governance and playbook documentation (notably CLAUDE.md and playbook cleanup) to update pre-flight steps and centralize references, overlapping with governance rewrites in this PR.

Poem

A rabbit hops through docs so bright,
Gaps in numbers brought to light—
ADR 0029 found its place,
Governance simplified with grace.
From chaos springs a cleaner trace. 🐰📚✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the three main change themes: ADR gap rule enforcement, audits lifecycle restructuring, and agent files consolidation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch devin/1777756978-doc-hygiene-audit-fixes

---

_{Review rate limit: 3/10 reviews remaining, refill in 36 minutes and 9 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

⏱️ CI Pipeline Duration Report

Based on the last 50 successful runs on the default branch.

Overall Pipeline

Metric	Value
p50	6m 26s
p95	7m 55s
p99	9m 3s
Current run	6m 16s
vs p95	-20.8%

Trend (last 20 runs): ▃▃▁▂▃▃▃▂▃▃▂▂▄▃▃▆▅▄█▆

Per-Job Breakdown

Job	p50	p95	p99	Current	vs p95
Accessibility (axe-core)	2m 5s	2m 21s	2m 23s	0s	-100.0%
Commit messages (commitlint)	0s	0s	0s	35s	N/A
Critical-flow E2E (Playwright)	1m 36s	1m 44s	1m 44s	6m 5s	+251.0%
Migration lint (AGENTS rule	0s	0s	0s	8s	N/A
Pipeline duration (p95 trend)	26s	27s	27s	—	—
Secret scan (gitleaks)	8s	11s	11s	7s	-36.4%
Smoke E2E (Playwright)	1m 26s	1m 40s	1m 40s	—	—
Test coverage (vitest)	2m 4s	2m 33s	2m 33s	3m 21s	+31.4%
Workflow lint (actionlint)	7s	7s	7s	5s	-28.6%
check	4m 12s	4m 54s	5m 6s	53s	-82.0%
tsconfig strict guard (PR-1.A)	5s	14s	14s	8s	-42.9%