Skip to content

docs: validate and fix all public documentation against source code audit#71

Merged
kolkov merged 1 commit into
mainfrom
docs/audit-validation-fixes
Feb 9, 2026
Merged

docs: validate and fix all public documentation against source code audit#71
kolkov merged 1 commit into
mainfrom
docs/audit-validation-fixes

Conversation

@kolkov
Copy link
Copy Markdown
Contributor

@kolkov kolkov commented Feb 9, 2026

Summary

Validate and fix all public documentation against the 4-agent source code audit (2026-02-09).

8 files changed, 709 additions, 495 deletions.

Key corrections

  • PMS_COMPLIANCE.md: ~80% compliance → ~60%/51% (validated), helper count 214→160, eclass count 14→12, fix wrong file path loader.gointegration.go, add Known Bugs section (6 tracked), add Fundamental Limitation and Community Audit sections
  • ROADMAP.md: full rewrite — update from outdated v0.9.3 to v0.10.0 phase with wave structure, add Known Limitations table, v1.0.0 release criteria with target vs current metrics
  • ARCHITECTURE.md: fix interpreter strategy to correct approach (configurable backend, not hybrid)
  • README.md: add Known Limitations section, update roadmap header to v0.10.0 phase
  • CONTRIBUTING.md: expand architecture from 8 to 19 internal packages, add useful references
  • CLI_REFERENCE.md: mark exit codes 2-6 as planned conventions (currently most errors return 1)
  • INSTALL.md: update version to 0.9.4, add daemon scaffolding note
  • UPSTREAM.md: update grknight feedback to configurable backend

Interpreter strategy (all files)

Replaced "hybrid bash" with correct approach:

  1. Fix mvdan/sh upstream (contribute PRs)
  2. Write custom Go interpreter optimized for ebuilds
  3. Configurable backend — users can enable real /bin/bash via settings

Test plan

  • Verify all markdown renders correctly on GitHub
  • Verify internal links (#known-bugs, #fundamental-limitation) resolve
  • No broken external links

…udit

- PMS_COMPLIANCE.md: correct ~80% to ~60%/~51%, fix helper count 214→~160,
  eclass count 14→12, fix loader.go→integration.go path, add Known Bugs
  and Fundamental Limitation sections, add Community Audit table
- ROADMAP.md: full rewrite from v0.9.3 to v0.10.0 phase, add wave structure,
  known limitations table, v1.0.0 release criteria, remove outdated sections
- ARCHITECTURE.md: fix interpreter strategy (configurable backend, not hybrid)
- README.md: add Known Limitations section, update roadmap header to v0.10.0
- CONTRIBUTING.md: expand architecture from 8 to 19 packages, add references
- CLI_REFERENCE.md: mark exit codes 2-6 as planned conventions
- INSTALL.md: update version to 0.9.4, add daemon scaffolding note
- UPSTREAM.md: fix grknight feedback to configurable backend
- All files: replace hybrid bash with correct strategy (fix mvdan/sh upstream
  or custom interpreter + configurable real /bin/bash backend via settings)
@kolkov kolkov merged commit 50a115e into main Feb 9, 2026
3 checks passed
@kolkov kolkov deleted the docs/audit-validation-fixes branch February 9, 2026 22:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant