Documentation remediation — 2026-10-24

The remediation program covers 8 workstreams, 318 documents and 253 finding groups in a private registry. These are baseline coverage counts, not completed repairs or live acceptance results. This entry is a public-safe progress summary; raw audit evidence and peer-review rationales remain private.

First repair: source work, not live acceptance

The first repair is limited to REC-001 / INC-002 / OPS-043 on branch fix/docs-audit-recovery-contract in PR #469. Registry navigation: repository README. Validation commands and results are recorded in the PR and private session evidence. No production deployment, application recovery drill, cutover or backup cleanup is claimed.

Initial local validation completed 109 focused tests with one Bash-version class skip. Linux CI then exposed two test-environment assumptions; the follow-up records the failure and fixture corrections. A fresh isolated Python environment with a local Bash 5 test runtime passed all 115 focused tests without skips. Markdown lint and strict build passed for all 208 site pages. A real restic 0.17.3 probe also passed six file-contract assertions using only synthetic local data. None of these is application recovery acceptance; check the corrected PR head's CI, and retain separate systemd, offsite and production gates.

The recovery contract now distinguishes:

• Production of snapshots: one restic invocation contains all declared job paths and adds homelab-path-set-v1. The tag is not an application-consistency guarantee, and older split snapshots remain unchanged.
• Selection: reviewed explicit IDs for recovery; repeat --snapshot only for disjoint same-host legacy snapshots exactly covering the manifest. Their cross-snapshot consistency still requires operator review.
• Planning and staging: default metadata/preflight JSON; explicit --restore creates a new private target with existing non-symlink parents. The helper performs no cutover, promotion or cleanup and preserves failed staging.
• Scheduled verification: the weekly wrapper uses the helper, unique private staging and preserved failure evidence. The role installs host python3-yaml before timer configuration. --latest requires the newest snapshot itself to be complete; it never falls back to an older complete snapshot or automatically mixes paths.
• Acceptance: root-path completeness is not backup validity. Every staged dataset and the application recovery set must validate before any stop, deletion or live copy. Remaining application-specific recovery defects are not certified or fixed by this path-set repair.

Restic's default host,paths retention grouping keeps legacy split groups separate from new all-path snapshots. No automatic deletion or retention-group change is authorized. Storage checks and separately approved cleanup follow verified backups and application restores, not merely the creation of a tagged snapshot.

Phase status and responsibility

Phase	Status	Agent responsibility	Owner/operator responsibility and remaining gate
Baseline and tracking	Registered privately	Maintain the scoped evidence and progress record without publishing raw findings	Prioritize remaining workstreams; baseline counts are not closure counts
First repair	Source changes under review in PR #469	Align producer/helper/weekly contract, guarded runbooks and source validation	Review and approve the exact revision; no merge or live acceptance asserted here
Rollout preparation	Pending	Document prerequisites and safe rollback without deleting backups	Confirm credentials, storage headroom, host dependencies, target mounts and maintenance window
Deployment	Not performed by this repair	No operational execution in this documentation task	Deploy the approved revision and verify effective units and dependencies
Recovery verification	Real drill not performed	Keep source tests distinct from restore evidence	Inspect new local/offsite snapshots, stage reviewed IDs, validate all paths and isolated application recovery; check weekly failure evidence
Acceptance and legacy cleanup	Gated	Preserve historical facts and report limits; do not close unrelated findings	Record live results, approve any cutover separately, retain legacy groups until verified recovery and explicit cleanup approval

flowchart TD
    Baseline[Private baseline registered] --> Source[Agent source repair and validation]
    Source --> Review[Owner reviews PR 469]
    Review --> Prepare[Owner confirms dependencies and storage]
    Prepare --> Deploy[Owner approves rollout]
    Deploy --> Stage[Operator stages reviewed snapshot IDs]
    Stage --> Validate[Validate all paths and application recovery]
    Validate --> Accept[Owner records live acceptance]
    Accept --> Retain[Retain legacy backups unless cleanup separately approved]

Updated operating guidance

• Per-service restore: shared prerequisites, explicit-ID staging, legacy split selection, and validation before live operations.
• Rebuild from zero: recovery ordering with guarded external/offsite staging and separate application acceptance gates.
• Public edge recovery: staging before writer stops or data transfers; dated tabletop evidence remains historical.
• OneUptime recovery: stage both logical backup roots and validate their matching recovery set; historical split IDs retained.
• Runner observability: stage both monitoring roots before reviewing application recovery.

Private operating guidance remains in the repository; use the parent README for repository navigation. The existing documentation-validation journal and earlier drill/tabletop facts are not rewritten as evidence for this repair. Other workstreams and unrelated backlogs retain their existing status. Remaining gates are owner review, rollout, verified local/offsite recovery sets, isolated application drills and separately approved production recovery or cleanup; a docs build cannot satisfy those gates.