## Design > Derived from: `{brief path}` @ sha256 `{first 12 hex of the brief's sha256}` · ceremony: architectural ### Architecture The modules this change adds or alters, and what each one owns. Judge each by the deletion test: if deleting the module would only move its complexity into its callers, it earns its place; a deep module hides much behind a small interface. Name the seams where behaviour can be tested or swapped. ### Data Flow How data enters, moves through and leaves the changed modules — one path per use case in the brief, in order. ### Interfaces Every boundary this plan creates or changes: signature, inputs, outputs, errors. Steps cite these in `Interface in:` / `Interface out:`. ### Data Models Types, schemas, files and their fields. Mark what is new and what changes shape. ### Error Handling Each failure mode, what the system does about it, and what the user sees. Unreadable input, a missing dependency and a partial failure are always listed. ### Module Map Dependencies point one way. The validator rejects a cycle. ```mermaid graph TD cli[src/cli] --> core[src/core] core --> store[src/store] ``` ### Architecture Rules Each rule names what enforces it. **checked by ``** — a command the target repo already has (its own dependency-cruiser, import-linter, linter or a test); `lib/verification/arch-rules.mjs` runs dependency-cruiser and import-linter when the repo configures them, and installs nothing. **advisory — `.claude/rules/.md`** — guidance Claude Code loads in the target repo; a plan step writes that file. A checked rule is accepted only once it has been seen to pass, fail on a planted violation, and pass again: the Proof column names the step that shows it (`arch-rules.mjs --prove --rule --plant =` does it in one command for the two supported tools; the planted run must trip that rule). | Rule | Enforced by | Proof | |------|-------------|-------| | {core never imports cli} | checked by `{node_modules/.bin/depcruise --config .dependency-cruiser.cjs src}` | Step {N} | | {prefer pure functions in core} | advisory — `.claude/rules/{core}.md` | — | ### Requirements Check Conflicts and gaps between the brief's requirements, each asked once as a two-choice question with the recommendation first: **keep** (the requirement as written) or **change like this** (a concrete proposal). Record the answer here. An answer that changes the brief's Intent, Goal or Success Criteria stops the plan: the brief is re-run through `/trekbrief`, never edited by the planner. | # | Finding | Question | Answer | |---|---------|----------|--------| | 1 | {two requirements that cannot both hold / a case no requirement covers} | Keep, or change like this: {proposal}? | {keep / change} | *If there is nothing to ask, write "No conflicts or gaps found" and say what was compared.* ### Decisions (ADR) *Optional.* Only for a decision that is hard to reverse, surprising without context, AND the result of a real trade-off. One paragraph each: context, decision, alternatives rejected and why. ### Gotchas *Optional.* Each place two constraints collide, the risky call made there, and who decided it.