Files
archie/docs/archive/decisions.md
T
sam cc53e5258d fix(telegram): compact tool output and drop turn caps
Render completed ToolCallEvents as Telegram-safe streaming blocks
with compact name/status and a short cleaned preview. Summarize
file contents and listings instead of dumping source or quoted
JSON. Collapse repeated legacy turn-budget failures.

Remove max_tokens turn gating and the 200000 turn_budget_chars
default so absent or commented config cannot restore an aggregate
cap. Keep per-result max_result_chars and spill.

Confine find/grep discovery to the active workspace/worktree.

Refs #604
2026-08-23 16:40:16 +00:00

220 lines
8.8 KiB
Markdown

# Archie Design Decisions
Record of architectural choices, reversals, and lessons learned during
development. Each entry has a date, a decision, the reasoning, and the
context that led to it. This document is the first thing to read before
changing anything that contradicts a prior decision.
---
## 2026-08-24 -- Turn continuation is never output-volume or token gated
**Decision**: A turn is never stopped because an aggregate token count or
aggregate tool-result character count was reached. `max_tokens` and
`turn_budget_chars` are not runtime continuation controls. Tool output is
bounded only per invocation with `max_result_chars`; oversized individual
results are spilled when a workspace-readable spill directory is configured,
or explicitly truncated otherwise.
**Reasoning**: Aggregate caps discard useful work and caused the model to emit
repeated `turn budget exceeded (200000 chars)` tool failures instead of
finishing. Model context/output accounting and tool-result volume are distinct:
provider output limits may describe one model response, but they must never be
used to terminate the multi-step turn.
**Context**: GitHub #604 showed full file and module listings followed by four
identical read failures and a shell failure at the old 200,000-character cap.
The renderer now summarizes those legacy events for replay, while current
dispatch never creates them. Find and grep are confined to the active
workspace/worktree; the Go module cache remains readable only by explicit
path, not by discovery.
---
## 2026-07-23 -- Forge-agnostic issue creation via CreateIssue
**Decision**: Add `CreateIssue(ctx, owner, repo, title, body, labels)
(int, error)` to the `forge.Forge` interface. Every forge backend
(Gitea, GitHub, future beads) implements it.
**Reasoning**: Agents discover out-of-scope findings during planning
and building. These should be filed as tickets immediately rather than
lost. Making `CreateIssue` part of the Forge interface means the agent
calls one method regardless of the underlying ticketing system.
**Future**: A `beads` forge backend will implement `CreateIssue` by
calling `bd create`. This makes beads the internal/default issue tracker
while Gitea/GitHub are external forges. The agent doesn't know which
it's talking to -- the daemon resolves the forge from repo config.
---
## 2026-07-23 -- Dolt and Beads for agent-native issue tracking
**Decision**: Install dolt (version-controlled SQL) and beads (`bd`,
a graph-based issue tracker for AI agents) as the foundation for
multi-repo scaling and multi-agent coordination.
**Reasoning**: Beads provides persistent memory across sessions, first-
class dependency tracking, JSON output for programmatic use, and hash-
based IDs that prevent merge conflicts in multi-agent workflows. It's
built on Dolt which gives cell-level merge, native branching, and
remote sync -- the same primitives git gives code but applied to issues.
**Context**: Gas Town (`~/gt/`) is cloned for reference -- it implements
a multi-agent workspace on top of beads. The archie-core scaling
strategy will follow a similar model: a coordinator daemon with per-repo
agents, all sharing a beads-backed task graph.
**Current state**: dolt 2.2.2, beads 1.1.0 installed. Beads initialized
in archie-core (`.beads/`). Six issues seeded for the scaling roadmap.
---
## 2026-07-23 -- Token budgets must be generous, not predictive
> **Superseded by the 2026-08-24 decision above.** There is no configured
> aggregate token cap; model token usage remains accounting only.
**Decision**: Set `max_tokens` to 100,000,000 (100M). Do not attempt to
predict what a task needs without data. Lower limits later based on
actual per-workflow/per-repo metrics.
**Reasoning**: An agent killed mid-task at 1M tokens wastes every token
it already consumed. There is no compaction or checkpointing yet, so a
killed agent is a total loss. Long-running agents regularly use 160+ steps and
hundreds of thousands of tokens per request. Large repositories need
proportionally more.
**Context**: The planner burned 357K tokens just to discover a fix
already existed. The builder hit 1M at step 25 of 90. Neither task was
unreasonable -- they were just exploring a large codebase.
**Future**: Track actual token consumption per workflow/stage/repo. Use
that data to set informed limits. Build compaction or checkpointing so
a killed agent can resume rather than restart.
---
## 2026-07-23 -- baseline-fix: auto-repair pre-existing gate failures
**Decision**: When `StageBaselineGate` detects a red gate (gofumpt, go
vet, etc. failing on clean main), launch the builder to fix the
failures via TDD rather than parking. Only park if the builder cannot
fix them.
**Reasoning**: A red baseline means the repo was broken before archie
touched it. Parking creates an infinite loop -- the next retry hits the
same failure. The agent should fix pre-existing issues, not fail on them.
**Implementation**: `StageBaselineGate` now calls `tc.Agent.Run()` with
a TDD mission when the gate fails. Uses the same builder agent. Note:
this required wiring `tc.Agent` (the runner) through the stage context.
---
## 2026-07-23 -- No hardcoded MaxSteps in workflow stages
**Decision**: Remove all hardcoded `MaxSteps` values from workflow
stages. Every stage inherits from `[budgets].max_steps` in the config.
**Reasoning**: Hardcoded values (15 for plan, 15 for TDD analyse, 15
for feasibility assess, 20 for PRD) were arbitrary and broke on large
repos. The config should be the single source of truth.
**Files affected**: `implement.go`, `tdd.go`, `feasibility.go`.
---
## 2026-07-23 -- No-op detection: close issues when build has 0 changes
**Decision**: When the builder completes with `StatusPassed` and 0 file
changes, close the issue with a comment rather than parking on "worktree
has no changes to commit".
**Reasoning**: A builder that passes with 0 changes means the fix
already exists or the issue is a no-op. The old behavior parked in an
infinite loop (commit-push fails because nothing changed, task re-queues,
builder runs again, same result).
**Implementation**: `TaskContext.BuildNoChanges` is set in the build
stage's `OnResult` when `Status == Passed && len(Changes) == 0`.
`StageCommitPush` checks this flag and calls `Forge.CloseIssue()` +
sets `Outcome = Merged` to stop the workflow.
**Test**: `TestStageCommitPushClosesIssueWhenBuildNoChanges` in
`implement_test.go`.
---
## 2026-07-23 -- assignee trigger over label trigger
**Decision**: Default to `trigger = "assignee"` instead of `trigger =
"label"`. The daemon only claims issues explicitly assigned to the bot
user.
**Reasoning**: Codex created 80+ issues with the `archie` label, and
the daemon auto-claimed every one. Label-based triggering is too
promiscuous for repos shared between humans and agents.
---
## 2026-07-23 -- DeepSeek v4 Pro as primary model
**Decision**: Use `deepseek/deepseek-v4-pro` as the planner and builder
model. Qwythos-9B (local llama.cpp) is the fallback for offline/cheap
tasks.
**Reasoning**: Qwythos couldn't complete a representative large-repository
plan stage before timing out. DeepSeek completed it in 21 iterations. Large
repositories need a larger model.
**Provider setup**: `class = "deepseek"`, API key via `DEEPSEEK_API_KEY`
env var from Bitwarden Secrets Manager (bws).
---
## 2026-07-22 -- v1.0.0 tagged
**Decision**: Tagged `v1.0.0` at commit incorporating the daemon/agent
split, NATS JetStream, Docker sandbox, Yaegi plugins, agentskills.io
skills, and Gitea forge support.
---
## 2026-07-22 -- Docker Compose stack with NATS + containers
**Decision**: The production deployment uses `docker-compose.yml` with
NATS, archied, and archie-agent containers. Config at `config.docker.toml`.
**Key fixes**:
- NATS healthcheck uses `wget localhost:8222/healthz` (not `nats-server check`)
- `host.docker.internal:host-gateway` extra_hosts for Linux
- Config mount path: `config.docker.toml` → `/etc/archie/config.toml`
- No stale `image:` tag on archied service (forces local build)
---
## 2026-07-22 -- Worktree Prepare before Container Acquire
**Decision**: Clone the worktree (`Trees.Prepare()`) before acquiring
a Docker container. Made `Prepare()` idempotent -- skips if `.git`
already exists.
**Reasoning**: Docker bind-mounts fail with "bind source path does not
exist" if the worktree hasn't been cloned yet. The old code acquired
the container first, then the prepare stage cloned into a path that
didn't exist on the host.
---
## 2026-07-22 -- Gofumpt and Go tools must be on PATH
**Decision**: The daemon's `exec.Command` for gate checks inherits the
process PATH. `~/go/bin` (where `gofumpt`, `golangci-lint`, etc. live)
must be in the PATH before starting the daemon.
**Symptom**: `baseline red -- gofumpt -w . fails` but manual run passes.
Root cause: `which gofumpt` returns nothing because `~/go/bin` isn't on
PATH in external agent sessions.