Draft: rewrite the architecture (docs/Architecture.md) #83

2026-09-30T15:50:25Z

dev-agent commented

2026-09-30 15:50:25 +00:00

The architecture rewrite we outlined, for review with inline comments. Nothing else changes yet:

docs/Architecture-Build-Spec.md stays until this is agreed;
the Development Plan (build order, service status) and updating the code's section references come after.

The new section letters (P, L, D, O, X, Q) don't clash with the old A–H citations in the code meanwhile.

Structure

Part P, principles:
- what Nisse is (conversational collaborators);
- the threat model (mistakes, injection, crashes; not a malicious model);
- actions by their effects (no side effects / contained / dangerous);
- three layers of control (hard walls, fast path, classifier);
- reversibility first; structural, not model judgment;
- local first, frontier on call.
Part L, nisse-core: the work model, the agent loop, authority (approvals as scoped permissions, pre-approved vs needs-discussion milestones, the trust dial), the action classifier, conversation, context and memory (five layers, plus how memory is written and used), the canonical log, durability and recovery, models and roles, the knowledge store, prompt injection, secrets/identity/logging.
Part D, nisse-dev: documents as the workflow, the workspace (fresh at use, toolchain preflight), git and PR hygiene, review and merge, action classes, deployment.
Part O, nisse-ops: approved step sequences (kept) as its scope source, action classes, interfaces, tickets and duties, deployment.
Part X, deployment (all agents), Part Q, open questions, and an appendix of what changed from the Build Spec.

Decisions from our discussion, as written:

The local model drives every step, with a prompt that encourages calling for help, plus observable escalation triggers (P7, L9).
Architecture documents and build plans are always discussed; milestones are marked pre-approved or needs discussion; PR review is a sanity check on an operator-set trust dial (L3, D2, D5).
Agent memory is in the architecture (L6), scheduled later in the Development Plan.

Points I decided that we didn't explicitly discuss — please check these:

Role names: driver, helper (delegation), expert (ask_expert) and classifier, replacing executor/planner/delegate/consultant (L9).
Repairing the environment is in scope for nisse-dev: cleaning caches, reinstalling project dependencies. Installing system software stays class 3 (D3, D6).
Build plans specify rather than implement: behaviour and tests as acceptance criteria, with code only where it's the clearest specification (D2). This settles the plan-style part of #82 in favour of option B.
The dev plan record lives in the Gitea issue as now, alongside the documents in the repo (D2).
Agent memory lives in the agent's private Outline space, one note per fact with an index (L6, L10).
Merging by the agent, when the trust dial allows, requires branch protection that demands an operator approval the agent's account can't give (D5, #65).
The phase policy "planning always escalates" is dropped, per your answer (appendix).

🤖 Generated with Claude Code

https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

The architecture rewrite we outlined, for review with inline comments. **Nothing else changes yet:** - `docs/Architecture-Build-Spec.md` stays until this is agreed; - the Development Plan (build order, service status) and updating the code's section references come after. The new section letters (P, L, D, O, X, Q) don't clash with the old A–H citations in the code meanwhile. **Structure** - **Part P, principles:** - what Nisse is (conversational collaborators); - the threat model (mistakes, injection, crashes; not a malicious model); - **actions by their effects** (no side effects / contained / dangerous); - three layers of control (hard walls, fast path, classifier); - reversibility first; structural, not model judgment; - **local first, frontier on call**. - **Part L, `nisse-core`:** the work model, **the agent loop**, **authority** (approvals as scoped permissions, pre-approved vs needs-discussion milestones, the trust dial), **the action classifier**, conversation, **context and memory** (five layers, plus how memory is written and used), the canonical log, durability and recovery, models and roles, the knowledge store, prompt injection, secrets/identity/logging. - **Part D, `nisse-dev`:** documents as the workflow, the workspace (fresh at `use`, toolchain preflight), git and PR hygiene, review and merge, action classes, deployment. - **Part O, `nisse-ops`:** approved step sequences (kept) as its scope source, action classes, interfaces, tickets and duties, deployment. - **Part X, deployment** (all agents), **Part Q, open questions**, and **an appendix of what changed** from the Build Spec. **Decisions from our discussion, as written:** - The local model drives every step, with a prompt that encourages calling for help, plus observable escalation triggers (P7, L9). - Architecture documents and build plans are always discussed; milestones are marked pre-approved or needs discussion; PR review is a sanity check on an operator-set trust dial (L3, D2, D5). - Agent memory is in the architecture (L6), scheduled later in the Development Plan. **Points I decided that we didn't explicitly discuss — please check these:** 1. **Role names:** `driver`, `helper` (delegation), `expert` (ask_expert) and `classifier`, replacing executor/planner/delegate/consultant (L9). 2. **Repairing the environment is in scope for `nisse-dev`:** cleaning caches, reinstalling project dependencies. Installing system software stays class 3 (D3, D6). 3. **Build plans specify rather than implement:** behaviour and tests as acceptance criteria, with code only where it's the clearest specification (D2). This settles the plan-style part of #82 in favour of option B. 4. **The dev plan record lives in the Gitea issue** as now, alongside the documents in the repo (D2). 5. **Agent memory lives in the agent's private Outline space,** one note per fact with an index (L6, L10). 6. **Merging by the agent,** when the trust dial allows, requires branch protection that demands an operator approval the agent's account can't give (D5, #65). 7. **The phase policy "planning always escalates" is dropped,** per your answer (appendix). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

dev-agent added 1 commit 2026-09-30 15:50:25 +00:00

Draft: rewrite the architecture as docs/Architecture.md

CI / checks (push) Skipped

CI / checks (pull_request) Successful in 1m18s

Details

a18294fa0c

A full rewrite of the architecture, following the outline agreed with the
operator: a threat model of mistakes, injection and crashes rather than a
malicious model; actions classed by their effects; hard walls, a
deterministic fast path and an action classifier; a conversational loop
driven by a local model with frontier helpers; approvals as scoped
permissions with pre-approved milestones and a trust dial; context and
memory, including agent memory; documents as nisse-dev's workflow.

Added beside docs/Architecture-Build-Spec.md, which stays until this is
agreed; the Development Plan and reference updates come after. New
section letters (P, L, D, O, X, Q) avoid clashing with the old A-H
references in the code meanwhile.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

dongar approved these changes

2026-09-30 19:40:18 +00:00

dongar merged commit 73a035dfcc into main

2026-09-30 19:40:21 +00:00

dongar deleted branch architecture-rewrite

2026-09-30 19:40:21 +00:00

dev-agent referenced this pull request

2026-09-30 19:40:49 +00:00

Discussion: architecture as a project document, separate build plans, and how detailed plans should be #82

Sign in to join this conversation.