Policy for how agents source authoritative knowledge and translate it to boma:
- Facts (version-specific syntax/options) → consult version-matched official docs,
cite, and stamp `verified: subject · tool ver · source · date`. Training memory
is the draft, never the authority.
- Judgments (best practices) → evidence to translate through boma's principles
(extends ADR-013); never adopted because the docs/a blog say so.
- Consultation is risk-based (security / unfamiliar-or-fast-moving / can't quote a
flag with confidence), with a "from memory, unverified" transparency backstop.
- Sources: context7 → WebFetch upstream → claude-code-guide → deep-research; match
the PINNED version, not "latest".
- Graceful degradation: the plugin accelerators may be absent on a fresh checkout,
so the policy commits to the principle and falls back to WebFetch/WebSearch.
CLAUDE.md gains a concise operating rule + pointer. TODO 10.4 decided. New TODO
10.7 tracks making the plugin/MCP toolchain reproducible from the repo (it is not
synced by account nor carried by git) — surfaced by a portability check this run.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ADR-013 sets how boma draws on AnsibleBaobabV4 without inheriting it:
translate-don't-transplant — V4 is evidence, never authority. It is a legitimate
source only of operational gotchas and working config snippets (re-derived on
boma's terms); never requirements, domain values, structure, or conventions.
Provenance stays transient (commits/conversation), durable docs stay clean. AI
consultation guardrails included. Resolves TODO 3.3 and 10.1.
Also bring ADR-011 (update management, Proposed draft) under version control:
- fix its "reuse V4's ntfy topics" line to "boma defines its own" (ADR-013)
- track its 6 open questions in TODO 16, plus a 7th: reconcile its tags-not-digests
pinning with the digest-pinning the security work now mandates (R1 / checklist /
15.6) — they currently conflict.
CLAUDE.md gains a V4 guardrail + ADR-013 pointer.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Revise ADR-004 to a service-role standard: every service is its own
self-contained role with a required file set including SECURITY.md, uniform
deploy mechanics, and a deferred shared-engine option (with revisit trigger)
recorded in the ADR.
Add the per-service security record:
- docs/security/service-security-template.md — canonical SECURITY.md template
(exposure, checklist status, service-specific hardening, residual risks)
- roles/<service>/SECURITY.md is where each service records how it meets the bar;
/security-review aggregates roles/*/SECURITY.md and cross-checks against config
- service-checklist.md noted as the generic bar the record answers
Wire-up: new-role runbook step writes SECURITY.md from the template; ADR-002
governance bullet points at it; CLAUDE.md role conventions require it and mandate
one-role-per-service; STATUS records the convention as defined-not-yet-applied.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a managerial security frame on top of the host baseline: explicit threat
model (opportunistic external, lateral movement/blast radius, operator/agent
error; supply chain accepted-lower-priority), security principles, and four
governance mechanisms that ADR-002 establishes and links out to:
- docs/security/service-checklist.md — per-service security bar (referenced
from the new-role runbook)
- docs/security/accepted-risks.md — living accepted-risk register (R1-R4)
- planned /security-review skill (TODO 8.5)
- agent guardrails in CLAUDE.md "what Claude must not do"
STATUS.md records the frame as present (manual enforcement) and /security-review
as planned-not-built.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ADR-010: API tokens as least-privilege managed secrets, declarative-first (no
click-ops), automation boundary, planned trunk-based CI. CLAUDE.md/AGENTS.md:
check 'rbw unlocked' before vault-dependent tasks (incl. commits) rather than
failing partway.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
R6/R7: ADR-003 & ADR-008 CI pipelines rewritten trunk-based (push to main ->
test -> staging -> [manual gate] production); CLAUDE.md no longer forbids pushing
to main. R8: STATUS/roles-README/site.yml now say base & docker_host are not built
(not in git), so a clean clone errors. R15/R16: ADR-001 table flagged as intended
design; dropped the unbuilt 'monitoring agent' from the baseline.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
First /review-repo run on boma. Hardened repo-scan.py (no TODO.md/prose false
positives). Applied 7 safe fixes (DNS staleness x2, STATUS factual correction,
hosts.yml path generalisation, trunk-based wording x2, scripts/README). Recorded
the run and 17 open findings in docs/reviews/2026-05-30-*.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
New on-demand repo audit: scripts/repo-scan.py does the cheap deterministic
checks (markers, broken refs, unencrypted vaults) and inventory; the command
fans out judgement reviewers across four dimensions, applies only safe/obvious
fixes, and writes a tracked report to docs/reviews/. Cron + email deferred.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Master vault password is fetched from Vaultwarden via the rbw agent
(scripts/vault-pass-client.sh, wired as vault_password_file) instead of a
plaintext .vault_pass. Vault secrets use a nested vault.<service>.<key> map.
Encrypted vault.yml files are excluded from lint. Includes the host rename in
Makefile and STATUS.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
