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>
4.8 KiB
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.
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.