Eight approved decisions existed only as beads memories and were lost when
the tracker was removed. Recovered from a backup taken six minutes before
8bf0f6b and folded into the docs that own them, rather than a new document.
- migration-decisions: recorded position as of 2026-07-29, the deferred
private-input-DTO compromise, and the agreed internal/app/{archied,
agentworker} next step
- configuration: missing credential degrades a capability, only invalid
config is fatal; config generation moves from install.sh to archied setup
- identity: the three-layer invariants/SOUL/representation model, and why
a curator may only propose SOUL changes
- agent-system: the curator isolation invariant (curators are peers, never
on a chat turn's critical path)
- messaging-and-work-intake: semantic search over messages is an explicit
non-goal, with the measurements behind it
- safe-change-and-recovery: the /restart deadlock and lockout constraints
- plugins-and-extensions: dates the surprisal deferral
Also replaces the dead `**Beads issue:** archie-core-5d7` frontmatter across
all 12 documents with the GitHub issue it migrated to (#73), and rewrites
every other beads identifier to its issue number.
2.8 KiB
Domain and Feature Review Procedure
Status: Active
Date: 2026-07-28
Tracking issue: #73
Purpose
Architecture work proceeds one domain or feature at a time. Before any design question, the selected area is researched across its complete live implementation, consumers, tests, state, configuration, and runtime wiring.
Existing packages are evidence, not the unit that drives the interview. Placement follows behaviour and ownership, not the existing directory name.
No restructuring implementation begins until the relevant package decisions are agreed and recorded in the focused domain or requirement document.
Required research
Before design questions, the current-state report MUST identify:
- entry points and runtime composition;
- state, persistence, and lifecycle;
- public and internal contracts;
- commands, events, and policy enforcement;
- configuration and defaults;
- all consumers and cross-domain interactions;
- process and infrastructure boundaries;
- tests, failure behaviour, and known invariants;
- duplicated or conflicting implementations;
- documentation that disagrees with live code.
Discoverable facts MUST be investigated rather than presented to the user as design questions.
Required decisions
Each package review records:
| Decision | Required result |
|---|---|
| Owned behaviour | The cohesive job the code performs |
| Domain ownership | The owner of the behaviour and vocabulary |
| Final location | Its target path |
| Public contracts | The smallest interfaces, commands, and events exposed |
| Required services | Domain-defined interfaces implemented by infrastructure |
| State ownership | The owner of each mutable record and transition |
| Dependencies | Allowed imports and dependencies to remove |
| Duplication | Code to consolidate, delete, or keep separate |
| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |
| Process boundary | In-process, or the concrete reason for isolation |
| Configuration | Settings owned by the domain or plugin |
| Policy | Definitions, evaluators, consequences, and shared mechanics used |
| Documentation | Authoritative definitions and generated reference |
| Migration constraints | Behaviour and data that must remain correct |
Interview method
For every selected domain or feature:
- Declare the single area under review.
- Complete the current-state research.
- Explain actual behaviour in plain technical language.
- Separate facts from design decisions and concerns.
- Resolve obvious consequences directly and ask only questions whose answer materially changes behaviour or structure.
- Record each confirmed decision in its focused document.
- Complete that area's handoff before selecting another.
- Keep unrelated domains outside the implementation scope.