Retire the old build spec, and point every reference at the architecture (M0.1)
CI / checks (push) Skipped
CI / checks (pull_request) Successful in 1m22s
CI / checks (push) Skipped
CI / checks (pull_request) Successful in 1m22s
Development Plan M0.1. Every section reference in code, tests, specs/, the example config, the tuning guide, and the CLAUDE.md and README files now cites docs/Architecture.md (P, L, D, O, X, Q) instead of the old spec's A-H, and docs/Architecture-Build-Spec.md is deleted (git keeps it). The plan's old-to-new table goes with it. Mostly mechanical, with a per-site choice where one old section split: A4 became L2 where it meant stop/abandon/the loop and L3 where it meant approvals; A10 became L6 in the context-budget code and L7 elsewhere; B2 became D4 for outbound Gitea and publishing and D5 for review intake; 'A3 step N' became the matching step of L8's boot sequence. Comments describing behaviour the architecture drops (planning always escalating, thresholds tuned at an old build step) now describe the current code and point at the Development Plan. docs/Architecture.md gains one line the rewrite missed: intake outages delay but never fail work (old B2), now in L5, where the poller and Matrix code cite it. Comments and docs only; no behaviour change. 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:
1 parent
890708594b
commit
1ad0b2147d
73 files changed
+259
-1786
No files matched your search
File diff suppressed because it is too large.
Load diff
+10
-5
@@ -1,10 +1,8 @@
|
||||
# Nisse — Architecture
|
||||
|
||||
**Status: agreed (PR #83).** How and in what order it gets built is in
|
||||
`docs/Development-Plan.md`. Until that plan's first milestone retires
|
||||
`docs/Architecture-Build-Spec.md`, code comments still cite the old spec's section
|
||||
numbers (A1–A18, B, C, F). This document uses different letters (P, L, D, O, X, Q)
|
||||
so the two can't be confused meanwhile.
|
||||
`docs/Development-Plan.md`. It replaced `docs/Architecture-Build-Spec.md`, which
|
||||
remains in git history; its section letters (A–H) are not reused here.
|
||||
|
||||
This document says what Nisse is, how its parts fit together, and why. It records
|
||||
decisions and the reasons for them. It doesn't record status or sequencing.
|
||||
@@ -360,6 +358,12 @@ comments) carry work and records. They are polled or received as structured JSON
|
||||
Comments from allowlisted operators are instructions or approvals; comments from
|
||||
anyone else are data (L11).
|
||||
|
||||
**Intake outages delay, never fail.** When Matrix, Gitea or Vikunja is
|
||||
unreachable, intake backs off exponentially (capped at a few minutes), retries
|
||||
indefinitely, and logs the outage. An outage delays a reaction; it never fails
|
||||
work or forces a change of state. Outbound effects interrupted by an outage are
|
||||
covered by intents (L8).
|
||||
|
||||
### L6. Context and memory
|
||||
|
||||
What each model sees, what persists, and how memory is written and used.
|
||||
@@ -980,7 +984,8 @@ it uses; nothing is shared between agents.
|
||||
|
||||
## Appendix — What changed from the Build Specification
|
||||
|
||||
For reviewing this rewrite against `docs/Architecture-Build-Spec.md`:
|
||||
For readers who knew the former `docs/Architecture-Build-Spec.md` (in git
|
||||
history):
|
||||
|
||||
- **Threat model and control model (P2–P4).** Checks are built around mistakes,
|
||||
injection and crashes, in three layers with an action classifier, rather than a
|
||||
|
||||
@@ -93,10 +93,11 @@ test Matrix room, a budget-capped LiteLLM key; configuration in `~/nisse-e2e/`.
|
||||
|
||||
### Phase 0 — Housekeeping
|
||||
|
||||
**M0.1 Retire the old spec.** *Pre-approved.*
|
||||
**M0.1 Retire the old spec.** *Pre-approved.* **Done.**
|
||||
- Update every section reference in code, tests, `specs/` and the `CLAUDE.md` and
|
||||
`README.md` files from the old spec's A–H to the new letters (table in §6).
|
||||
- Delete `docs/Architecture-Build-Spec.md` (git keeps it); drop §6 from this plan.
|
||||
`README.md` files from the old spec's A–H to the new letters.
|
||||
- Delete `docs/Architecture-Build-Spec.md` (git keeps it), and the old-to-new
|
||||
section table this plan carried for the purpose.
|
||||
- Acceptance: `grep` finds no reference to the old spec or its section numbers.
|
||||
|
||||
**M0.2 A bring-up script, and an unprivileged agent user on this box.** *Pre-approved.*
|
||||
@@ -302,32 +303,3 @@ 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. Old section numbers → new (for M0.1, then removed)
|
||||
|
||||
| Old (`Architecture-Build-Spec.md`) | New (`Architecture.md`) |
|
||||
|---|---|
|
||||
| 0 Naming | Naming |
|
||||
| 0.1 What we're building, guiding principles | P1, P3–P8 |
|
||||
| 0.2 Work model | L1 |
|
||||
| A1 Transport | L5 |
|
||||
| A2 State store, A3 Boot reconciliation | L8 |
|
||||
| A4 Control loop and gating | L2 (loop, `stop`, `abandon`), L3 (approvals) |
|
||||
| A5 LLM access | L9 |
|
||||
| A6 Browser tool | D7, O4 |
|
||||
| A7 Secrets, A8 SSO identity, A9 Logging | L12 |
|
||||
| A10 Canonical transcript | L7 (schema), L6 (context) |
|
||||
| A11 Roles, A12 Escalation, A13 Delegation, A14 `ask_expert`, A15 Local accommodations, A16 Eval capture | L9 |
|
||||
| A17 Knowledge store | L10 (store), L6 (memory) |
|
||||
| A18 Prompt injection | L11 |
|
||||
| B1 Workflow | L2, D2 |
|
||||
| B2 Requirements | D2, D4, D5 |
|
||||
| B3 Deployment | D7 |
|
||||
| C1–C5 Sysadmin Agent | O1–O6 (C2 → O2, C3 → O4, C4 → O5, C5 → O6) |
|
||||
| D Knowledge (Outline) | L10 |
|
||||
| E Supporting services | X5, and §2 here |
|
||||
| F1–F4 Deployment model | X1–X4 |
|
||||
| G Build order | This plan |
|
||||
| H Open decisions | Q |
|
||||
@@ -67,7 +67,7 @@ relying on them.)
|
||||
Two consequences:
|
||||
|
||||
- **Context length is a memory decision, not a free setting.** The spec's
|
||||
estimate (Part H) was about 5 GB left for KV cache beside a 4-bit 32B model.
|
||||
estimate (the original build spec) was about 5 GB left for KV cache beside a 4-bit 32B model.
|
||||
At 16-bit, that's only about 20k tokens of context for Qwen3-32B.
|
||||
- **KV-cache quantization** stores keys and values in 8 bits (or 4). At 8
|
||||
bits it halves the cache and is close to lossless. At 4 bits it is
|
||||
@@ -170,7 +170,7 @@ How many model calls one milestone may make before the executor stops with
|
||||
### `tuning.executor.failure_limit` — default 2
|
||||
|
||||
How many consecutive failed `run_command` calls trigger escalation: the
|
||||
sub-task is handed to a frontier model as a delegation (spec A12). A
|
||||
sub-task is handed to a frontier model as a delegation (architecture L9). A
|
||||
successful command resets the count. Failed file reads don't count, since
|
||||
reading is looking around, not doing the work.
|
||||
|
||||
@@ -192,12 +192,12 @@ reading is looking around, not doing the work.
|
||||
|
||||
How many `ask_expert` calls one milestone may make. `ask_expert` is a single
|
||||
stateless question to a stronger model, with no access to the repository
|
||||
(spec A14), for things like "is this API deprecated?".
|
||||
(architecture L9), for things like "is this API deprecated?".
|
||||
|
||||
- **Too low:** the executor can't get unstuck on a knowledge question it
|
||||
can't answer from the code.
|
||||
- **Too high:** a confused executor asks variations of the same question
|
||||
instead of doing the work or failing. That's the circling A12 warns about.
|
||||
instead of doing the work or failing. That's the circling L9 warns about.
|
||||
- **Deciding:** count consults per milestone, and check whether the answers
|
||||
changed what the executor did next. If it regularly exhausts the budget
|
||||
without progress, the budget is fine and the model or the plan is the
|
||||
@@ -206,7 +206,7 @@ stateless question to a stronger model, with no access to the repository
|
||||
### `tuning.delegation` — hard caps on one delegation
|
||||
|
||||
A delegation is a frontier model working a sub-task with full tool access
|
||||
(spec A13). When a cap is hit, the delegation **fails**, and its branch and
|
||||
(architecture L9). When a cap is hit, the delegation **fails**, and its branch and
|
||||
work are discarded, because resuming on a half-edited tree isn't safe.
|
||||
|
||||
| Knob | Default | Caps |
|
||||
@@ -216,7 +216,7 @@ work are discarded, because resuming on a half-edited tree isn't safe.
|
||||
| `wall_clock_s` | 900 | elapsed time |
|
||||
|
||||
- **`max_tokens` is a scope limit, not the money limit.** Spending limits live
|
||||
on the LiteLLM key (spec A5). This cap stops one delegation from growing
|
||||
on the LiteLLM key (architecture L9). This cap stops one delegation from growing
|
||||
without bound. An unbounded one could still exhaust a daily budget and take
|
||||
every frontier model away until it resets.
|
||||
- **Too low:** delegations fail just short of finishing and their work is
|
||||
@@ -225,7 +225,7 @@ work are discarded, because resuming on a half-edited tree isn't safe.
|
||||
- **Too high:** a stuck delegation burns tokens and time before failing.
|
||||
- **Deciding:** every delegation records the tokens it used and how long it
|
||||
ran (the `delegation_completed` event, captured for evaluation per spec
|
||||
A16). Set each cap above what successful delegations actually use, with
|
||||
L9). Set each cap above what successful delegations actually use, with
|
||||
room to spare.
|
||||
|
||||
### `tuning.tools.command_timeout_s` — default 120
|
||||
|
||||
Reference in new issue
Block a user