Kjell Tore Guttormsen
f5ca220bc0
Wave 1, order 3 (P3 plan mode as the start, P2 design as its own part, P9
plan side). Contracts K3-K6 for the later merges.
- plan_version 1.8 (1.7 plans stay valid): Test first on every step, one
End-to-end ("run the thing") step, optional Interface in / Interface out /
Review focus fields, a ceremony class in the header (absent =
architectural), and for architectural plans a ## Design part: module map
without cycles, architecture rules that name their enforcer and the step
that proves them, a requirements check asked as keep / change.
- K3 lib/validators/plan-gate.mjs: the critic verdict is recorded INSIDE the
plan (Claude Code's plan approval hands a hook only the plan file's text),
bound to the hash taken before the reviewers read it; 0 go / 1 stop / 2
could not run; at most 3 critic rounds, then stop and ask.
- K5 lib/verification/arch-rules.mjs: runs the target repo's own
dependency-cruiser or import-linter (installs nothing; 2 = not measured,
never green); --prove --rule shows pass -> fail on a planted violation of
that rule -> pass. Verified against dependency-cruiser 18.5.0 and
import-linter 2.15; madge 8.0.0 left out (missed a planted .mjs cycle).
- K6 lib/verification/plan-scope-sweep.mjs: changed files no step names.
- /trekplan Phases 8-10: design part, bounded critic loop, the gate before
"execute", a plan-mode path through ExitPlanMode (not yet run end to end
inside plan mode). plan-critic 10 -> 12 dimensions; scope-guardian checks
the ceremony.
- Fixed on the way: plan-validator and plan-review-dedup used the
file://argv[1] main guard (no-op under a symlink or a space); CRLF plans
failed every manifest; the dedup dropped finding severity.
Borrowed, credited in place: obra/superpowers, Kiro (docs), addyosmani/
agent-skills, mattpocock/skills, GitHub Spec Kit, bashebr/ai-native-sdlc,
Boris Cherny's public threads.
Suite 1497 (1495 / 0 / 2), 86 new tests.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
114 lines
4.8 KiB
Markdown
114 lines
4.8 KiB
Markdown
<!--
|
|
The design part of a plan (plan_version 1.8). /trekplan Phase 8 writes it as
|
|
the plan's `## Design` section, between `## Context` and
|
|
`## Implementation Plan`, ONLY when the brief's `ceremony:` is
|
|
`architectural` (an absent field means architectural: heaviest on doubt).
|
|
`small` and `bounded` plans omit it.
|
|
|
|
The design lives in the PLAN, never in the brief: the brief format is a public
|
|
contract (Handover 1), the plan contract is Voyage's own (Handover 4).
|
|
|
|
`plan-validator --strict` checks, for an architectural 1.8 plan: the eight
|
|
`###` subsections below exist, the module map is a mermaid graph with no
|
|
cycle, every architecture rule names its enforcer, a checked rule names the
|
|
step that proves it, and an advisory rule names its `.claude/rules/` file.
|
|
`### Decisions (ADR)` and `### Gotchas` are optional.
|
|
|
|
Borrowed, with credit:
|
|
- Section list: Kiro's design.md (architecture, data flow, interfaces, data
|
|
models, error handling, test strategy), and its requirements analysis asked
|
|
as two-choice questions. Kiro's SMT engine is not borrowed.
|
|
- Design questions: obra/superpowers@8ca22db brainstorming (MIT, © 2025 Jesse
|
|
Vincent).
|
|
- Module map with one dependency direction and no cycles, and "use the
|
|
de-facto tool" (e.g. dependency-cruiser): addyosmani/agent-skills@9d0c60d
|
|
(MIT, © 2025 Addy Osmani).
|
|
- Vocabulary (deep module, seam, deletion test), the three-condition ADR bar,
|
|
and pass → fail → pass: mattpocock/skills@c55ee46 (MIT, © 2026 Matt Pocock).
|
|
- Rules that must pass: GitHub Spec Kit's constitution (MIT), changed so each
|
|
rule names what enforces it; in Spec Kit the model ticks the boxes itself.
|
|
- Gotchas and "Derived from <hash>": bashebr/ai-native-sdlc@11fb8d7 (MIT).
|
|
-->
|
|
|
|
## 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 `<command>`** — 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/<file>.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 <name> --plant
|
|
<file>=<dest>` 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.
|