Skip to content

docs: reconcile audited design and implementation drift - #2629

Open
codeforester wants to merge 2 commits into
mainfrom
documentation/2628-20261021-reconcile-audited-documentation-drift
Open

codeforester wants to merge 2 commits into
mainfrom
documentation/2628-20261021-reconcile-audited-documentation-drift

Conversation

@codeforester

@codeforester codeforester commented Oct 21, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Several maintained guides describe older behavior even though the corresponding runtime changes are implemented and tested. Reconcile the audited contracts across design, user/reference docs, contributor guidance, and AI context without changing runtime code.

  • Include test.requirements in the project-runtime decision table and make IDE mutation consent explicit.
  • Specify the accepted earlier-BOM/tag release recovery path from fix: recover a tagged release after publication tooling changes #2551, and document uninstall's confirmed retention contract: project run bundles are removed, Base-level history remains.
  • Document workspace deadlines/cancellation, current review policy, and all 18 Python package responsibilities.
  • Repair the registry and technical-overview examples, including the overview's required release repository field; distinguish static package inspection from explicit runtime verification.
  • Add the missing unreleased activation-repair note. Upgrade guidance and its notes are handled separately under docs: document the Base upgrade contract across Homebrew and source installs #2597.

Issue

Fixes #2628

Refs #1611 and #1613 for broader runtime separation and the future input schema; neither is implemented or closed by this PR.

Validation

  • 209 pytest cases and 38 subtests passed across the existing documentation checks, contract hardening, command-reference flags, version docs, and focused routing, IDE consent, uninstall, release/readiness/publication, and workspace setup/test/process tests.
  • After the final AI command-context correction, reran command-reference flags, contract hardening, and repository documentation links: 16 passed. After adding the registry evidence map, reran contract hardening and documentation links: 15 passed.
  • Extracted both corrected YAML blocks and passed them to the production manifest/registry parsers. Disposable probes reconfirmed requirements-triggered routing, static unverified readiness, and the documented uninstall retention split.
  • Checked all 11 local heading links in changed documents and matched the ownership table against all 18 tracked Python packages.
  • git diff --check passed. No real install, release publication, or uninstall was performed.

Design Impact

Reconciles descriptions of implemented behavior. Release recovery follows the accepted #2551 contract. Uninstall explicitly retains the existing removal/retention behavior and describes its verification limits. No new runtime behavior or documentation-governance gate is introduced.

Docs Impact

Canonical runtime, IDE, release, workspace, ownership, and review documents now agree with the implementation. A dedicated uninstall guide is linked from the index, command reference, stability contract, cache layout, and adopter guide. Contributor guidance distinguishes Base-owned Python packages from the external framework and the legacy CI search-path entry. The contract registry maps reconciled behavior to implementation/tests and states the remaining semantic-coverage limits.

AI Context Impact

Update ARCHITECTURE, COMMANDS, and STATUS for runtime triggers, isolated wrapper execution, and static versus explicitly executing requirements inspection.

Release Notes

Unreleased now records the activation discovery repair from #2611. Documentation corrections do not change published release contents. The two missing upgrade notes belong to #2597's PR.

Demo Impact

None. This PR changes documentation only and preserves existing runtime/demo behavior.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Documentation improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: reconcile audited design and implementation drift

1 participant