v1.5.0 documentation and contribution audit¶
Audited 2026-09-14 against the release candidate based on c55ea47ed3239d471132b414dc2f0d8a43cceeb0.
Canonical ledger record: task_cc032b780f404f88bf19f4898b429b64.
Scope and evidence limits¶
The inventory below records a source anchor and changed/not-changed decision for every current document enumerated before this release pass. Generated references and executable book contracts are verified by the documentation gate. Operational runbooks were compared with their implementation and existing dated receipts; this audit does not claim to have re-executed every deployment, recovery drill, provider integration or native desktop workflow. Historical measurements remain historical, and proposed ADRs remain proposals. The release wheel and fleet cutover have separate acceptance requirements.
Corrections cover PostgreSQL-only storage, explicit migrations, independent crash-observer Python, Hermes-specific gateway checks, current CLI verbs, the actual desktop bridge boundary, and validation before publication.
Open contribution disposition¶
| PR | Release decision | Evidence |
|---|---|---|
| #788 | Superseded by this release change | Replay now requires the historical starvation state; arbitrary setup exceptions do not count as reproductions. |
| #773 | Superseded by this release change | Candidate ARM64 smoke builds locally, eliminating the published-tag race and its proposed wait loop. |
| #683 | Already satisfied | Its prohibited identity strings are absent from both affected current files; the docs identity gate verifies the tree. |
| #839 | Deferred at candidate freeze | Late verifier-resource propagation change; hosted sanity was still running. The release does not activate this profile on fleet workers. |
| #814 | Deferred | SoulGraph feature branch conflicts with main; unfinished feature is not included. |
| #782 | Deferred | Automatic machine-hold release changes operational policy and has a failing sanity check. |
| #677 | Deferred | Mission Control feature branch conflicts with main and lacks completed manual hub validation. |
Current-document decisions¶
Paths link to the candidate files. Source anchors identify the contract reviewed; the implementation remains authoritative. Proposed documents are retained as design records rather than promoted to release capabilities.
| Document | Decision | Source anchor | Audit finding |
|---|---|---|---|
docs/activation-probe/calibration-spec.md (removed 2026-09-30 with the probe) |
Not changed | src/mac/activation_probe/calibration.py |
Retain the documented contract and stated limitations against the source anchor. |
docs/activation-probe/classifier-spec.md (removed 2026-09-30 with the probe) |
Not changed | src/mac/activation_probe/classifier.py |
Retain the documented contract and stated limitations against the source anchor. |
docs/activation-probe/integration-guide.md (removed 2026-09-30 with the probe) |
Not changed | src/mac/activation_probe/runtime.py |
Retain the documented contract and stated limitations against the source anchor. |
docs/activation-probe/prototype-report.md (removed 2026-09-30 with the probe) |
Not changed | src/mac/activation_probe/classifier.py |
Retain the documented contract and stated limitations against the source anchor. |
docs/activation-probe/runtime-selection.md (removed 2026-09-30 with the probe) |
Not changed | src/mac/activation_probe/runtime.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/adr/0001-unify-hermes-runtime-into-mac.md | Not changed | deploy/fleet-node-install.sh |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0002-memory-store-at-scale.md | Not changed | src/mac/vector_writer_service.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0003-tokenhub-core-into-mac.md | Not changed | src/mac/secrets_service.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0004-task-ledger-vs-hermes-kanban.md | Changed | src/mac/store.py |
Clarify PostgreSQL authority; retain the original ledger decision and historical context. |
| docs/adr/0005-elastic-executor-tier-vs-static-fleet.md | Not changed | deploy/deploy-mac-fleet.sh |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0006-acp-support.md | Not changed | src/mac/task_executor.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0007-hermes-boundary-mood-nap-soul-memory.md | Not changed | src/mac/services.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0008-openshell-docker-engine-runtime.md | Not changed | deploy/openshell/bootstrap-openshell.sh |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0009-minimal-base-on-demand-layered-provisioning.md | Not changed | src/mac/executor_sandbox.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0010-fleet-ide-cutover-parity-matrix.md | Not changed | ide/src/App.tsx |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0011-hub-review-verification-scope.md | Changed | scripts/run-sanity-tests.sh |
Move full-suite verification from scheduled runs to candidate CI. |
| docs/adr/0012-hybrid-native-steward-containerized-execution.md | Not changed | src/mac/executor_sandbox.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0013-authoritative-hub-allocator.md | Not changed | src/mac/allocator.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0014-visibility-is-not-a-dispatch-gate.md | Not changed | src/mac/allocator.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0015-macos-nodes-are-host-installs.md | Not changed | deploy/openshell/bootstrap-openshell.sh |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0016-agent-initiated-review.md | Not changed | src/mac/services.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0017-token-spend-is-metered-at-the-router.md | Not changed | src/mac/scientific_optimizer.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0018-task-graph-progressive-disclosure.md | Not changed | observe/src/lib/api.ts |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0019-privilege-is-an-acl-on-a-resource-tree.md | Not changed | src/mac/acl.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0020-a-running-task-is-not-editable.md | Changed | tests/test_task_stop_start.py |
Mark the implemented stop/start boundary without claiming the entire proposal shipped. |
| docs/adr/0021-schema-changes-need-versioned-migrations.md | Not changed | src/mac/schema_migrations.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0022-a-gate-returns-a-named-decision-not-a-boolean.md | Not changed | src/mac/acl.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0023-one-skill-source-many-harness-plugins.md | Not changed | src/mac/agentbus_broadcast.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0024-the-dashboard-streams-the-bus-not-just-its-counts.md | Not changed | observe/tests/readonly.test.ts |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0025-the-hub-ui-is-the-observability-console.md | Not changed | tests/ui/test_hub_ui_is_one_tree.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0026-first-class-operations-emit-bus-events.md | Not changed | src/mac/services.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0027-upgrades-are-versioned-and-fail-closed.md | Not changed | src/mac/fleet_upgrade_service.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0028-installation-is-a-package-not-a-push.md | Not changed | deploy/deploy-mac-fleet.sh |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0029-the-route-search-path-is-a-fleet-contract.md | Not changed | src/mac/route_ladder.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0030-langchain-extracts-before-qdrant.md | Not changed | src/mac/vector_writer_service.py |
Retain dated decision and context; proposal is not a shipped capability. |
| docs/adr/0032-cli-session-hooks-not-tmux.md | Not changed | src/mac/cli_session.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/adr/0033-local-continuation-hub-supervision.md | Not changed | src/mac/worker.py |
Retain dated decision and context; implementation boundary checked against source. |
| docs/agent-lifecycle-proof.md | Changed | src/mac/task_lifecycle.py |
Label May receipts historical; require fresh canaries. |
| docs/audit.md | Not changed | src/mac/task_lifecycle.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/authority-boundary.md | Not changed | tests/api/test_authority_boundary.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/book/01-system.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/02-local-start.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/03-projects-and-tasks.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/04-machines-and-agents.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/05-evidence-review-completion.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/06-hermes-and-ide.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/07-repository-contracts.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/08-plans-and-dags.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/09-fleet-onboarding.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/10-identity-and-secrets.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/11-publication-and-refs.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/12-operations.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/13-deployment-topologies.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/14-images-and-cutover.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/15-sandboxed-runtimes.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/16-apis-and-integrations.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/17-learning-evals-scaling.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/book/18-capstone.md | Not changed | scripts/test-docs.py |
Executable tutorial contract; verify examples through the book gate. |
| docs/break-glass-host-recovery.md | Not changed | src/mac/worker_subprocess.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/c26-certifier-phase-profile-example.md | Changed | deploy/certifier/harness_manifest.py |
Retain the certifier fixture while marking its former project retired. |
| docs/client-bootstrap-contract.md | Not changed | src/mac/client_login.py |
Retain the documented contract and stated limitations against the source anchor. |
docs/coding-cli-credentials.md (removed 2026-10-02 with the other coding CLIs) |
Not changed | src/mac/coding_agent.py |
Retain the documented contract and stated limitations against the source anchor. |
docs/coding-route-ladder.md (removed 2026-10-02 with the route ladder) |
Not changed | src/mac/route_ladder.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/crash-diagnosis-and-repair.md | Changed | deploy/fleet-node-install.sh |
Correct the independent crash-observer interpreter. |
| docs/dashboard-connection.md | Changed | ide/src/api/mac.ts |
Remove obsolete renderer configuration and unwired bridge claims. |
docs/deploy-prerequisite-vs-phase1-audit.md (removed 2026-10-01 with the deploy script) |
Not changed | deploy/deploy-mac-fleet.sh |
Phase-one staging still precedes prerequisite validation; preserve the open finding. |
| docs/dispatch-priority-bias-audit.md | Not changed | src/mac/store.py |
Retain the documented contract and stated limitations against the source anchor. |
docs/dream-repair-slack-lineage.md (removed 2026-09-30 with dreaming) |
Not changed | src/mac/nap_consolidator.py |
Retain the documented contract and stated limitations against the source anchor. |
docs/dreaming-rewrite.md (removed 2026-09-30 with dreaming) |
Not changed | src/mac/dreaming/__init__.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/env-config-reference.md | Not changed | scripts/generate-env-config-registry.py |
Generated surface or source integration inventory; verify freshness and links. |
| docs/fleet-cutover-transaction-protocol.md (since deleted) | Not changed | deploy/deploy-mac-fleet.sh |
Keep transactional cutover and fault-matrix gates; artifact release does not satisfy them. |
| docs/fleet-directives.md | Changed | src/mac/directive_service.py |
Use a neutral repository example. |
docs/fleet-node-onboarding-checklist.md (removed 2026-10-01 with the deploy script) |
Changed | deploy/reviewed-tool-assets.sh |
Use PostgreSQL and runtime-specific gateway readiness. |
| docs/fleet-operational-learning.md | Not changed | src/mac/fleet_learning.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/fleet-registry-schema.md | Not changed | scripts/setup-fleet.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/getting-started.md | Not changed | scripts/start-test-postgres.sh |
Retain the documented contract and stated limitations against the source anchor. |
| docs/guide/01-architecture.md | Not changed | src/mac/models.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/guide/02-getting-started.md | Not changed | scripts/start-test-postgres.sh |
Retain the documented contract and stated limitations against the source anchor. |
| docs/guide/03-advanced.md | Not changed | src/mac/task_lifecycle.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/guide/04-ui.md | Not changed | tests/ui/test_hub_ui_is_one_tree.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/guide/05-developer-guide.md | Not changed | scripts/resolve-impacted-tests.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/guide/06-trust-workflow.md | Not changed | src/mac/task_outcomes.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/guide/README.md | Not changed | scripts/generate-docs-reference.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/hermes-boundary.md | Changed | src/mac/hermes_adapter.py |
Remove obsolete direct-SQLite wording. |
| docs/hermes-integration.md | Changed | src/mac/hermes_adapter.py |
Remove obsolete direct-SQLite wording. |
| docs/hermes-vendor-fate.md | Changed | deploy/openshell/mac-hermes.Containerfile |
Distinguish the historical gateway choice from the current Hermes option. |
docs/hgx-elastic-capacity.md (deleted 2026-10-01) |
Not changed | src/mac/hgx_elastic_capacity.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/home-consolidation.md | Changed | deploy/fleet-node-install.sh |
Mark consolidation as a historical proposal; current deployment preserves the selected Hermes profile. |
| docs/hub-availability.md | Changed | src/mac/pg_backup.py |
Remove the retired live SQLite tier. |
| docs/hub-host-saturation-remediation.md | Changed | deploy/fleet-node-install.sh |
Date the incident scope and direct operators to the live registry. |
| docs/image-publication-and-qualification.md | Changed | .github/workflows/ci.yml |
Document candidate validation before qualification. |
| docs/in-flight-agent-messages.md | Changed | src/mac/agentbus_broadcast.py |
Correct administered AgentBus commands. |
| docs/index.md | Not changed | scripts/generate-docs-reference.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/integration-authority-contract.md | Changed | src/mac/services.py |
Use the authenticated hub CLI rather than a private SQLite path. |
| docs/investigations/dependency-drift.md | Not changed | scripts/fault-replay.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/investigations/hermes-deployment-readiness.md | Not changed | deploy/fleet-node-install.sh |
Profile and supervisor behavior matches deployed recovery investigation; chat proof remains distinct from task proof. |
| docs/macos-shared-services.md | Not changed | deploy/install-qdrant-service.sh |
Retain the documented contract and stated limitations against the source anchor. |
docs/memory-tier-schema.md (removed 2026-09-30 with the memory tier) |
Not changed | src/mac/models.py |
Retain the documented contract and stated limitations against the source anchor. |
docs/memory-tier-verification.md (removed 2026-09-30 with the memory tier) |
Not changed | tests/test_vector_writer_service.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/notifier-configuration-guide.md | Changed | src/mac/notifier_service.py |
Correct secret verb, required actor and file-based input. |
| docs/oneshot-isolation-gate-verification.md | Not changed | scripts/run-contract-tests.sh |
Explicitly historical verification of a removed vendor tree. |
| docs/openshell-nemo-relay-e2e.md | Not changed | tests/test_openshell_sandbox.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/openshell-nemo-relay-integration.md | Not changed | src/mac/task_executor.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/openshell-sandbox.md | Changed | src/mac/task_executor.py |
Separate native gateways from Linux sandboxed execution. |
| docs/presentations/agentfabric-overview/README.md | Not changed | src/mac/models.py |
Retain historical authoring material and its stated evidence limits; the new pinned deck supersedes it for this release. |
| docs/presentations/agentfabric-overview/SKILL.md | Not changed | src/mac/models.py |
Retain historical authoring material and its stated evidence limits; the new pinned deck supersedes it for this release. |
| docs/presentations/agentfabric-overview/current-deliverables.md | Not changed | src/mac/models.py |
Retain historical authoring material and its stated evidence limits; the new pinned deck supersedes it for this release. |
| docs/presentations/agentfabric-overview/deck-specification.md | Not changed | src/mac/models.py |
Retain historical authoring material and its stated evidence limits; the new pinned deck supersedes it for this release. |
| docs/presentations/agentfabric-overview/narrative-specification.md | Not changed | src/mac/models.py |
Retain historical authoring material and its stated evidence limits; the new pinned deck supersedes it for this release. |
| docs/presentations/agentfabric-overview/prompts/deck-authoring-prompt.md | Not changed | src/mac/models.py |
Retain historical authoring material and its stated evidence limits; the new pinned deck supersedes it for this release. |
| docs/presentations/agentfabric-overview/prompts/image-prompts.md | Not changed | src/mac/models.py |
Retain historical authoring material and its stated evidence limits; the new pinned deck supersedes it for this release. |
| docs/presentations/agentfabric-overview/qa-ledger.md | Not changed | src/mac/models.py |
Retain historical authoring material and its stated evidence limits; the new pinned deck supersedes it for this release. |
| docs/presentations/agentfabric-overview/source-notes.md | Not changed | src/mac/models.py |
Retain historical authoring material and its stated evidence limits; the new pinned deck supersedes it for this release. |
| docs/problems.md | Not changed | deploy/deploy-mac-fleet.sh |
Retain the dated incident snapshot; it is not live fleet status. |
| docs/production-deployment.md | Changed | deploy/k8s/README.md |
Correct storage, schema migration, backup and upgrade instructions. |
| docs/python-baseline.md | Not changed | deploy/hermes/python314-source.json |
Keep focused Hermes compatibility evidence and upstream-suite limitations explicit. |
| docs/reference/cli.md | Not changed | src/mac/cli.py |
Generated surface or source integration inventory; verify freshness and links. |
| docs/reference/documentation-inventory.md | Changed | scripts/generate-docs-reference.py |
Generated surface or source integration inventory; verify freshness and links. |
| docs/reference/openapi.md | Not changed | src/mac/api.py |
Generated surface or source integration inventory; verify freshness and links. |
| docs/reference/staged-module-integration-audit.md | Not changed | src/mac/data/test_impact_map.json |
Generated surface or source integration inventory; verify freshness and links. |
docs/repository-cicd-monitor.md (removed 2026-09-30 with the monitor) |
Changed | src/mac/cicd_monitor.py |
Separate the generic CI monitor from mandatory MAC release gates; date inbox observations. |
| docs/repository-ref-hygiene.md | Not changed | src/mac/repository_ref_reconciler.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/repository-runtime-contract.md | Changed | src/mac/project_repository_service.py |
Use the actual repository-owned contract gate and Linux verification boundary. |
docs/review-strategy-experiments.md (removed 2026-09-30 with review experiments) |
Changed | src/mac/review_experiments.py |
Make semantic-review opt-in explicit. |
| docs/review-tick-stall-diagnosis.md | Not changed | tests/test_review_tick_stall_diagnosis.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/roadmap.md | Not changed | src/mac/task_outcomes.py |
Roadmap and historical receipts do not certify all unchecked work as delivered. |
docs/scientific-optimizer.md (removed 2026-09-30 with the optimizer) |
Not changed | src/mac/scientific_optimizer.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/secrets-management-guide.md | Not changed | src/mac/secrets_service.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/soul-preservation-runbook.md | Not changed | tests/test_soul_preservation.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/structured-task-bodies.md | Not changed | src/mac/workflow_models.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/synchronized-fleet-cutover.md (since deleted) | Not changed | tests/test_deploy_fleet_parallel_staging.py |
Keep independent cutover acceptance requirements; no fleet deployment claimed here. |
| docs/task-dependency-semantics.md | Not changed | src/mac/task_lifecycle.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/task-throughput-observability.md | Not changed | src/mac/task_flow_analytics.py |
Retain the documented contract and stated limitations against the source anchor. |
| docs/testing-strategy.md | Changed | src/mac/data/test_impact_map.json |
Move every deferred validation tier into candidate CI. |
The new release audit itself is an added current document, anchored to the workflow changes in .github/workflows/ci.yml and .github/workflows/docs.yml, the source paths above, and the linked contribution records. Its reachability and formatting are covered by the same documentation gate.