Condense the architecture; move mechanism detail to the Development Plan
CI / checks (push) Skipped
CI / checks (pull_request) Successful in 1m18s

Each rule is stated once in its home section and referred to by ID
elsewhere. No decision added or removed; implementation detail moved to
Development-Plan.md section 6, keyed by architecture section. P8 folded
into P1, P5 and X1; the Appendix about the old spec dropped. Section
IDs are unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE
This commit is contained in:
dongarandClaude Opus 5.5 committed 2026-10-02 18:43:16 +00:00
1 parent d77c142488
commit 6e4dca040c
2 files changed
+686 -1052

No files matched your search

+54
View File
@@ -309,3 +309,57 @@ All 19 open issues, as of 2026-09-30:
| #79 ending projects and milestones | **Superseded** | M2.5 |
| #80 build artifacts in PRs | Milestone | M1.4 |
| #81 no-change milestones | **Superseded** | M2.5 |
## 6. Implementation notes
Mechanism detail moved out of `docs/Architecture.md` in PR #90, which keeps only
decisions and their reasons. Keyed by the architecture section each note
implements; a milestone touching that section uses the note, and changes it here
if the implementation differs.
- **L1 switching:** the grace period before switching away from an item waiting
on the operator defaults to 10 minutes. When the driver chooses the next ready
item and the choice fails or is invalid, fall back to the oldest.
- **L3 revision stamping:** in Matrix, a reply is stamped with the revision whose
message had been sent when it arrived; on a Gitea issue or a Vikunja ticket,
with the latest proposal comment older than the reply.
- **L5 transport:** the `Transport` interface is send, ask and receive. Intake
backoff is exponential, capped at a few minutes.
- **L6 fitting order:** first shorten old tool results to their first and last
lines, then drop the oldest events with a note saying so; never the system
prompt, the current plan or the most recent turns. View labels:
`[orchestrator]`, `[operator, Matrix]`, `[operator, comment on PR #N]`,
`[helper report]`, `[executor]` narration.
- **L7 rendering:** content is stored as bytes or local paths and uploaded or
inlined at render time, never as provider handles. Token budgeting and
prompt-cache breakpoints are render-time concerns, never stored. Compaction
summaries are first-class events so a model change never inherits opaquely
compacted history. A reasoning "session" is a delegation, including one resumed
after a crash.
- **L8 state store:** SQLite in WAL mode, each change committed and fsynced before
the loop continues. A delegation's cut is clean when its last event is a
completed result, its branch is at the expected commit, its caps are unbreached
and external truth matches the log. "Anything else" offers continue, re-plan or
abandon.
- **L9 local models:** request `tool_choice` only of models whose server declares
it can enforce it; otherwise the loop enforces the contract (an explicit
`finish`, prose treated as a violation). Briefings use the capability profile,
never a model name or "weaker model".
- **L10 vault:** atomic writes are write-then-rename. Obsidian's settings folder
(and `.git`, if history is kept) are not synced. A failed write is retried, or
recorded and reconciled later.
- **L12:** secrets reach a command by environment or stdin. Headless agents get an
Authelia single-factor exception scoped by source address, group and target.
Logs are shipped to the host journal, not kept in containers.
- **D3 preflight:** a project's needs are read from its files (`Cargo.toml`,
`pyproject.toml`, `package.json`) or a declaration in the repository.
- **D4 publishing:** standard excludes are configured in each clone, and only what
the work produced is committed. A push hands the key over stdin to a
short-lived `ssh-agent` on the build VM, for that one push.
- **D7:** test services use ports 18000–18099, so opening access later is a
firewall change. The inference host is behind LiteLLM, so it is not a second
egress exception.
- **X4:** the agent host's state dataset is ZFS, snapshotted on a schedule and on
each approval. Tool VM templates use Terraform's `bpg/proxmox` provider with
cloud-init. Containers restart unless stopped.
- **X5:** the local inference host is llama-swap on an RTX 4090 machine.