Skip to content

docs: reconcile ARCHITECTURE/CLAUDE.md with the code (provisioner, ADR tree, unit docs) - #2244

Draft
thinmintdev wants to merge 5 commits into
mainfrom
docs/drift-pass
Draft

docs: reconcile ARCHITECTURE/CLAUDE.md with the code (provisioner, ADR tree, unit docs)#2244
thinmintdev wants to merge 5 commits into
mainfrom
docs/drift-pass

Conversation

@thinmintdev

@thinmintdev thinmintdev commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Summary

Documentation drift pass (study 0.8; H16): reconciles ARCHITECTURE.md,
CONTRIBUTING.md, CHANGELOG.md, one systemd unit, and one docstring with
the code they describe, and fixes the "hal0 keeps no ADR tree" claim that
was flatly wrong (docs/adr/ exists). Every claim below was verified
against source before writing, and a haiku docs-verifier fact-check pass
confirmed all of them.

  • Hermes provisioner (ARCHITECTURE.md "Bundled agents (v0.3)"):
    described a 15-phase, checkpointed provisioner. The code
    (src/hal0/agents/hermes_provision.py) is a 12-step, deliberately
    uncheckpointed converging pipeline (_INSTALL_STEPS,
    hermes_provision.py:6582) — the old provision.json/PHASES
    checkpoint machinery is gone per the module's own docstring. Rewrote the
    section from _INSTALL_STEPS and the real CLI verb (hal0 agent install hermes, not agent provision).
  • BUNDLED_AGENTS: was quoted as ("pi-coder", "hermes"); the real
    value (src/hal0/agents/manager.py:117) is ("hermes", "pi").
  • hal0-agent@.service Documentation=: pointed at
    docs/agents/hermes/SERVICE.md, which has never existed. Repointed at
    the real, tracked docs/guides/run-agents.mdx.
  • Byte-identical memory-provider pair
    (installer/agents/hermes/plugins/hal0-memory/provider.py and
    src/hal0/agents/hermes/plugins/memory_hindsight/provider.py): a guard
    test (tests/agents/hermes_plugins/test_seed_parity.py) already exists
    on main and already establishes src/ as the canonical owner with
    installer/ as its byte-identical seed — this was already done, just
    not documented correctly. Fixed an inverted comment in
    hermes_provision.py that called the installer copy "canonical."
  • ADR tree: CLAUDE.md says docs/adr/ holds the decision records;
    ARCHITECTURE.md and CONTRIBUTING.md both said hal0 keeps no
    separate ADR tree. Neither was the full picture — most ADR-00NN
    citations in source comments resolve to docs/internal/adr/, a second,
    gitignored ADR tree (#638) with independent numbering, the same
    local-only pattern this repo already uses for docs/.devdocs/ and
    docs/superpowers/. Fixed the false claims and added a "Decision
    records" section to ARCHITECTURE.md explaining both trees. Reconstructed
    5 of the missing ADRs (0004, 0012, 0013, 0020, 0023) from git
    history (docs/internal/adr/*.md was tracked before #638, so its
    blobs are still retrievable) and current-code verification, with lab
    topology/hostnames scrubbed. Declined to reconstruct 0008/0009/0010/
    0022 — they describe the Lemonade-fronted inference runtime that the
    container-switchover epic (#687) removed entirely; republishing them
    as current would be a ghost architecture, so ARCHITECTURE.md notes
    this instead. Fixed a mislabeled ADR-0004→0005 link in
    docs/concepts/memory.mdx.
  • Stale voice/ module-tree entry: ARCHITECTURE.md's module layout
    listed src/hal0/voice/ as "emptied in providers: retire vestigial voice providers (Moonshine/Kokoro) + document lemond-only dispatch (PR-10) #620"; the directory was fully
    deleted in that commit (2db4c682) and doesn't exist on disk. Removed
    the entry (the correct "deleted" explanation already exists elsewhere in
    the same file).

No behavior change — docs, one systemd metadata field, and one docstring.

Risk grade

  • low — docs only, internal refactor, or behaviour-preserving fix

Touched surfaces

  • Installer (installer/, systemd units) — Documentation= field only
  • Docs (docs/, CONTRIBUTING.md)

§14.1 high-risk surfaces

None apply.

Rollback

Rollback: revert this PR; no runtime behavior depends on any of these
files.

Test tiers run

  • α unit (uv run pytest tests/ -q -n 8 — 12761 passed, 3 pre-existing
    failures per CONTRIBUTING.md/program notes: test_pressure_evict_noop_when_probe_fails,
    the two test_moonshine_server.py ffmpeg-dependent tests; unrelated
    to this diff)
  • β integration (covered by the same full run above)
  • γ release-gate — not required (docs-only, low risk)

Also ran: uv run ruff check/format (clean), python3 scripts/check_sunset.py
(green, 193 <= baseline 193), uv run mypy src/hal0/agents/hermes_provision.py
(pre-existing errors only, none on touched lines), and a docs-verifier
fact-check pass over all 23 claims in the diff (all verified).

🤖 Generated with Claude Code

https://claude.ai/code/session_014BA2Lma4WErDwZXTAgJr1C

thinmintdev and others added 5 commits September 5, 2026 12:52
@thinmintdev @claude
docs(architecture): reconcile Hermes provisioner + agent-roster claim…
014b334 
…s with code

The "Bundled agents (v0.3)" section described a 15-phase, checkpointed
Hermes provisioner. `src/hal0/agents/hermes_provision.py`'s own module
docstring says the old `provision.json`/`PHASES`/`PhaseContext` checkpoint
machinery is gone: it is now a 12-step, deliberately uncheckpointed
converging pipeline (`_INSTALL_STEPS`, hermes_provision.py:6582), and the
brain/persona/memory-identity phases that used to run inside it now run
from the hal0-api boot lifespan instead. Rewrote the "Install & lifecycle"
and "Surfaces > Provision" sections from the actual `_INSTALL_STEPS` tuple
and CLI verb (`hal0 agent install hermes`, not the nonexistent `agent
provision`).

`BUNDLED_AGENTS` was quoted as `("pi-coder", "hermes")`; the real value in
`src/hal0/agents/manager.py:117` is `("hermes", "pi")`.

The module-tree listed `src/hal0/voice/` as "emptied in #620" — the
directory was fully deleted in that commit (2db4c68), not merely
emptied, and no longer exists on disk. Dropped the stale tree entry (the
correct "deleted in #620" explanation already exists a few lines below,
in the Key boundaries section).

Added forward references to the ADR-tree reconciliation landing in the
next commit (the front-matter callout, the "Standing decisions" line, and
a new "Decision records" section), so this file stops asserting hal0
keeps no ADR tree.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014BA2Lma4WErDwZXTAgJr1C
Signed-off-by: thinmintdev <alexander@awideweb.com>
@thinmintdev @claude
fix(systemd): point hal0-agent@ Documentation= at a real tracked doc
d482028 
Documentation= named docs/agents/hermes/SERVICE.md, which has never
existed in this tree (installer/systemd is the real location of the
unit itself; there is no docs/agents/ directory at all). Point it at
docs/guides/run-agents.mdx, the actual operator-facing doc for
installing and running the bundled Hermes agent this unit serves.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014BA2Lma4WErDwZXTAgJr1C
Signed-off-by: thinmintdev <alexander@awideweb.com>
@thinmintdev @claude
docs(agents): fix inverted memory-plugin ownership comment
84841bb 
_phase_install's docstring called installer/agents/hermes/plugins/hal0-memory/
"the canonical, shipped MemoryProvider source". It is the opposite: the
canonical source is src/hal0/agents/hermes/plugins/memory_hindsight/, and
the installer path is a byte-identical seed mirrored from it (already
locked together by tests/agents/hermes_plugins/test_seed_parity.py's own
docstring: "The installer seed MUST be a byte-identical copy of the
canonical source"). Fixed the comment to point at the real owner instead
of re-establishing one — the two files are already byte-identical
(verified sha256) and the guard test already exists and passes, so the
anti-scar "one owner per fact" requirement for this pair is satisfied by
the existing test; only the stale comment needed fixing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014BA2Lma4WErDwZXTAgJr1C
Signed-off-by: thinmintdev <alexander@awideweb.com>
@thinmintdev @claude
docs(adr): reconcile the ADR-tree claim and reconstruct 5 missing ADRs
39a4315 
CLAUDE.md says docs/adr/ holds the accepted decision records; ARCHITECTURE.md
and CONTRIBUTING.md both said hal0 keeps no separate ADR tree at all — while
docs/adr/ demonstrably exists with 5 tracked files. Neither claim was the
full picture: source comments cite dozens of ADR-00NN numbers with no file
in docs/adr/, most of which resolve to docs/internal/adr/, a second,
gitignored ADR tree (closed out of git tracking by #638, for decisions that
carry lab topology/IP data) with its own, independent numbering — the same
local-only pattern this repo already uses for docs/.devdocs/ and
docs/superpowers/. That tree's history is retrievable from git blobs for
files that were tracked before #638 (93e1848^:docs/internal/adr/*.md);
numbers assigned after that commit (e.g. 0023) were never tracked at all.

Fixed the false "no ADR tree" claims in ARCHITECTURE.md (done in the prior
commit) and CONTRIBUTING.md's anti-scar rule 9, and the CHANGELOG.md intro's
"kept internal" claim (public docs/adr/ existed too). Fixed a mislabeled
citation in docs/concepts/memory.mdx: the shared/private namespace grammar
is ADR-0005, not ADR-0004 as the link text claimed (the href already pointed
at 0005-memory-namespace-shared-private.md).

Reconstructed 5 ADRs from git history (docs/internal/adr/*.md, tracked
before #638) and current-code verification, condensed to a page each per
this repo's existing docs/adr/0002 and 0005 convention, with lab
topology/hostnames scrubbed:

- 0004 bundled agents — rewritten against the current v0.3+ state (the
  v0.2 draft named pi-coder/Hermes-Agent and Cognee memory, all since
  superseded)
- 0012 remove auth and Caddy entirely — still current, verified against
  ARCHITECTURE.md, mcp_mount.py, docs/operate/auth.mdx
- 0013 per-agent MCP client allow-list — verified against the current
  ToolPolicy/MCPServerConfig/AgentConfig schema and mcp_client.py
- 0020 localhost-callback-only OAuth PKCE (OpenRouter) — verified against
  the current _loopback.py guard and the still-501 auth.py scaffold
- 0023 canonical LLM roles (agent/utility) + Hindsight-native memory
  extraction — never tracked in git (post-#638 number); reconstructed
  from source comments + the CHANGELOG v0.8.0-beta.3 entry alone, since
  it is the single most-cited missing ADR number in the tree

Declined to reconstruct 0008/0009/0010/0022: all four describe the
Lemonade-fronted inference runtime (lemond, LemonadeProvider,
WrappedServer dispatch), which the container-switchover epic (#687)
removed entirely. Republishing them as current, accepted ADRs would
describe a runtime that no longer exists; ARCHITECTURE.md's new
"Decision records" section (previous commit) notes this instead of
leaving a numbered gap that looks like an oversight.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014BA2Lma4WErDwZXTAgJr1C
Signed-off-by: thinmintdev <alexander@awideweb.com>
@thinmintdev @claude
docs(changelog): add Unreleased entry for the drift pass (#2244)
2c3aba8 
Per CONTRIBUTING.md rule 4: every PR adds a CHANGELOG entry.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014BA2Lma4WErDwZXTAgJr1C
Signed-off-by: thinmintdev <alexander@awideweb.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@thinmintdev