docs: reconcile audited design and implementation drift #2628

Goal

Reconcile confirmed documentation drift from the 18 October design/code audit against current main, without changing runtime behavior.

Background

The audit found inconsistent descriptions across canonical design, user guidance, examples, ownership documentation, and AI context. Current main still contains these discrepancies. Passing existing contract tests does not establish that the prose is accurate.

Scope

• D01: document test.requirements as a project Python runtime trigger.
• D02: make IDE mutation consent explicit in setup and removal procedures.
• D03: document the narrowly accepted tagged-release recovery contract from fix: recover a tagged release after publication tooling changes #2551/fix: recover tagged releases after tooling advances main #2552, preserving strict first-time publication.
• D04: reconcile uninstall retention wording and publish a precise removal/retention matrix with the maintainer-confirmed current behavior: project run bundles are removed and Base-level history is retained.
• D05: replace obsolete review-policy availability guidance.
• D06: repair the technical-overview and artifact-registry examples using production parsers.
• D07: document current workspace execution deadlines, cancellation boundaries, and partial outcomes, including the changes from fix(workspace): fail closed and report delegated test execution state #2613.
• D09: complete the current Python package ownership map and remove obsolete Base-local lib/python references in affected contributor/design guidance.
• D10: correct derived AI architecture guidance for isolated Base execution and static versus explicit runtime verification.
• D11: add the missing unreleased activation note; upgrade-related notes and D08 are owned by docs: document the Base upgrade contract across Homebrew and source installs #2597.

Acceptance Criteria

• Each listed finding has a concrete documentation correction or an explicit maintainer decision recorded in the PR.
• Runtime ownership and consent procedures agree across affected canonical and derived documents.
• Release recovery describes prerequisites, original BOM/tag authority, failure boundaries, and idempotent resume without weakening the first-time provenance contract.
• Uninstall docs distinguish selected resource removal, retained state, checkout identity, verification limits, and partial failures.
• The two current YAML examples pass the production parsers.
• Ownership covers every tracked Python package and names the actual provider boundary.
• Workspace docs distinguish setup/test process-group handling from update subprocess handling.
• Existing relevant documentation/contract checks and git diff --check pass.

Validation

Compare the documentation against current implementation and regression tests. Run the existing relevant documentation tests, focused routing/IDE/release/uninstall/workspace tests, and the production parsers against the corrected fenced YAML blocks. No real install, release publication, or uninstall is required.

Non-Goals

• Runtime behavior changes, a new manifest schema (Publish a tested JSON Schema for base_manifest.yaml #1613), or implementation of future documentation-impact CI.
• Replacing the accepted Base workflow or making a third-party skill mandatory.
• Duplicating the upgrade contract tracked in docs: document the Base upgrade contract across Homebrew and source installs #2597.

Project Fields

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

Agent Assignment

Owner: Codex, with codeforester as accountable maintainer. Use one dedicated issue-backed documentation worktree. Validate and open a reviewable PR; do not merge without authorization. Preserve unrelated worktrees and the primary checkout.