docs: propose documentation maintenance and drift prevention strategy #2631

Goal

Propose a Base-native documentation maintenance strategy after the known drift corrections, with a concrete path from accepted design to enforceable PR evidence.

Background

The October audit found contradictions and missing behavioral detail despite passing contract checks. Correction PRs #2629 and #2630 reconcile the known drift. The remaining G01-G03 gaps concern impact analysis, design acceptance before implementation, and executable traceability. Existing #2570/#2572 check PR shape and #2573 concerns structured agent assignment; none alone establishes semantic documentation ownership.

Scope

Write a clearly proposed strategy covering documentation layers/authority, design and affected-user-document drafts before implementation, proportionate restoration-fix handling, structured impact dispositions, executable examples and contract mapping, release-note handling, and staged enforcement. Relate the proposal to existing backlog instead of duplicating implementation issues.

Acceptance Criteria

• Proposal distinguishes PRD, HLD, detailed contracts, decisions, user/reference/operational docs, and derived agent/consumer material.
• Material behavior changes require accepted design and affected document drafts before dependent code; final docs accompany implementation before merge.
• Proposed PR impact record covers design, user docs, interfaces, operations/security, release notes, and derived consumers, with evidence for no-impact dispositions.
• Automation's limits, negative canaries, trusted execution, current-head evaluation, trial period, and required-check promotion criteria are explicit.
• Existing related issues and the remaining manifest-schema gap are linked; policy implementation remains separate.
• Proposal states maintainer decisions still needed and does not present unimplemented enforcement as active policy.

Validation

Review against the live correction PRs, existing contract registry and PR workflow, related backlog, and primary-source industry practices. Run repository documentation-link checks and git diff --check. No GitHub enforcement settings or runtime behavior changes.

Non-Goals

Implementing a new CI gate, changing required reviewers or rulesets, rewriting all historical plans, mandating a third-party skill, or implementing #1613's schema.

Project Fields

• Status: In Progress
• Priority: P1
• Size: S
• Area: Docs
• Initiative: Contract Hardening
• Milestone: v1.11.0

Agent Assignment

Codex authors the proposed design in a dedicated issue-backed worktree. codeforester owns design acceptance. Open a draft PR for review; do not merge or activate policy implicitly.