docs: remediate documentation audit findings and add automated docs:maintain pipeline

Merged
BI
1mo ago
+2299-911

Summary

  • Resolves all 21 documentation & ownership audit findings across setup/contributor instructions, skills, codebase-index, design system contracts, operations/deployment runbooks, governance checklists, living plans, and organisation manifests.
  • Reduces AGENTS.md from 23,977 bytes to 21,189 bytes (2,811 bytes spare under the 24,000-byte ceiling) and aligns PROJECT-INSTRUCTIONS-CONTINUATION.md with docs/agents/native-startup/*.md delegation.
  • Adds the unified automated documentation and file-organisation maintenance pipeline (scripts/maintain-docs-system.mjs, tests/maintain-docs-system.test.ts, npm run docs:maintain, npm run docs:maintain:check, and --classify).
  • Hardens documentation & organisation gates (scripts/generate-hazard-register-snapshot.mjs --check, scripts/check-docs-links.mjs, scripts/check-docs-script-refs.mjs, scripts/organisation/check-retired-rules.mjs, scripts/generate-repo-awareness-snapshot.ts, and scripts/list-database-skills.mjs).

RAG impact: none (documentation, organisation manifests, and offline documentation/organisation maintenance scripts only; no retrieval, ranking, or answer-generation behavior changed).

Clinical Governance Preflight

  • Clinical behavior / safety impact: None (documentation, runbook accuracy, and offline maintenance tooling only).
  • Source governance / provenance impact: None.

Verification

  • Checks run during implementation:
    • npm run docs:maintain:check -> organisation: exit 0 (pass) — working tree: 9956 files: 9951 placed, 4 shared, 1 ignored, 0 not yet placed, 0 unplaced
    • node scripts/check-gate-manifest.mjs -> Gate-manifest OK: all 45 verify:full gates are enforced in CI (static-pr + mapped jobs), the 42 static gates are documented consistently, and 13 operating docs pass the cheap≠static composition pin.
    • npx vitest run tests/maintain-docs-system.test.ts tests/check-docs-links.test.ts tests/instruction-continuation-guards.test.ts tests/organisation-instruction-guards.test.ts tests/repo-awareness-generator.test.ts -> Test Files 5 passed (5) | Tests 100 passed (100)
  • Full verify:pr-local and hosted GitHub Actions CI checks: unrun at bare-PR publication time by request (GitHub is the verification surface).

Risk and rollout

  • Risk: Low (documentation, organisation manifests, snapshots, and offline doc-maintenance scripts only).
  • Rollback: Revert PR commit cleanly.
  • Provider or production effects: None.

Summary by cubic

Remediates the 21 documentation and documentation-ownership audit findings across docs, skills, and organisation manifests, and adds an automated documentation maintenance pipeline. AGENTS.md is trimmed below the byte ceiling, PROJECT-INSTRUCTIONS-CONTINUATION.md is aligned with native-startup delegation, and snapshots, archives, and organisation maps are regenerated to match. No RAG or clinical behavior changes; this touches only documentation, organisation manifests, and offline maintenance tooling.

New Features

  • npm run docs:maintain auto-places unplaced files into the matching docs/organisation/systems/*.json manifest and regenerates snapshots; --classify prints the target area for a path.
  • npm run docs:maintain:check runs the pipeline in check-only mode for CI.

Bug Fixes / Hardening

  • Corrects stale references across runbooks, design-system contracts, prompts, archives, and .env.example, including the renamed Railway project, retired arbiter/check:docling-lab scripts, restored privacy attestation expiry, corrected CME route count, and updated type-scale aliases and crisis-number counts.
  • States precisely what the crisis-contact tests pin (an https:// prefix per source URL) and documents the five real push-guard overrides, dropping the nonexistent browser guard.
  • Clarifies that design-system adoption passed proof statuses are recorded declarations backed by manifest evidence, not re-run browser proofs.
  • Hardens documentation, organisation, and gate checks to fail on misplaced files, dangling links, script-ref drift, and retired rules.
  • Makes hazard snapshot gates deterministic with expiry-independent tests and atomic snapshot writes, and bounds rmSync retries so CI does not flake.

Summary by Gitar

  • Policy gates:
    • Changed missing Clinical Governance Preflight and RAG impact: checks in scripts/pr-policy.mjs from blocking errors to advisory warnings
  • Scripts and packages:
    • Removed the differentials:import script from package.json
    • Added check:hazard-register-snapshot to detect stale hazard snapshots
    • Switched outstanding-issues IDs to ULID-backed #XXXXXX Crockford Base32 allocated by scripts/outstanding-issues.mjs
  • Deployment config:
    • Documented the new railway.worker.json health check and pre-deploy migration command
  • Playwright cadence:
    • Restated non-Chromium and iPhone/tablet projects as release-matrix only
    • Documented verify:ui contention exiting 75 (DATABASE_HEAVY_RUN_ADMISSION_BUSY) rather than 1
  • Organisation checks:
    • Made scripts/check-organisation.mjs include non-ignored untracked files so new files are placed before being staged

This will update automatically on new commits.