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.
71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
# Domain and Feature Review Procedure
|
|
|
|
**Status:** Active
|
|
**Date:** 2026-07-28
|
|
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/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:
|
|
|
|
1. Declare the single area under review.
|
|
2. Complete the current-state research.
|
|
3. Explain actual behaviour in plain technical language.
|
|
4. Separate facts from design decisions and concerns.
|
|
5. Resolve obvious consequences directly and ask only questions whose answer
|
|
materially changes behaviour or structure.
|
|
6. Record each confirmed decision in its focused document.
|
|
7. Complete that area's handoff before selecting another.
|
|
8. Keep unrelated domains outside the implementation scope.
|