From 6078dc15651aba197411217d372b88aedca83602 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 3 Oct 2026 22:38:37 +1000 Subject: [PATCH] docs: constitution review edits; state the wiring rule without naming a file --- CLAUDE.md | 123 ++++++++++++++++++++++++++---------------------------- 1 file changed, 59 insertions(+), 64 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4601f281a..268c79971 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,15 +5,16 @@ here changes a decision. If a rule stops changing decisions, delete it. ## What this is -**archie-core** is event-driven agentic automation. An event (a forge issue, -a webhook capture, a schedule, a chat message) is matched to a workflow, -the workflow runs an agent in an isolated container, and the result lands -somewhere a human reviews it. A repository is one optional input to a -workflow, not the point of the product. +**archie-core** is event-driven agentic automation. An event (an issue, PR, +webhook, schedule, chat message) is matched to a workflow, the workflow runs an +agent or tool in an isolated container, and the result lands somewhere for +review or action. A repository is an optional input to a workflow, not the point +of the product. -The product is unfinished. Many features are half-built, and the codebase -carries far more code, binaries, docs and tooling than it delivers. The job -right now is to finish features and shrink the codebase, not to extend it. + The product is +unfinished. Many features are half-built, and the codebase carries far more +code, binaries, docs and tooling than it delivers. The job right now is to +finish features and shrink the codebase, not to extend it. ## Authority @@ -23,49 +24,44 @@ When sources disagree, the higher one wins: 2. This file. 3. The code as it is in the tree. 4. Beads issues (`bd show `): the plan for a piece of work. -5. Everything else (memories, comments, old docs) is a hint. Verify it - against the code before acting on it. - -There are no PRDs, architecture docs or repo skills. Old ones live outside -the repo and are not guidance. Do not recreate them. +5. Everything else (memories, comments, old docs) is a hint. Verify it against + the code before acting on it. ## How to decide -- **Broken beats new.** A bug that blocks work gets fixed now, with the - smallest change that unblocks it. No design doc, no new mechanism. -- **Cheapest option first.** Before building anything, name the smallest - change that solves the problem, including changing configuration or - deleting something. If your plan adds a new mechanism (RPC, process, - binary, abstraction, config field, tool) or grows past about 100 lines, - stop and present the cheap option to the maintainer first. -- **Delete before adding.** Unused code, dead paths, fallbacks nobody takes - and features nobody runs get removed, not maintained. Solo project, single - user: breaking changes need no compatibility shims. -- **Finish before starting.** Prefer completing a half-built feature end to - end over starting a new one. -- **No new binaries.** A new command is a subcommand of an existing binary. - A binary exists only for a real process boundary (separate deploy, - scaling, security or failure domain). +- **Broken beats new.** A bug that blocks work gets fixed now, with the smallest + change that unblocks it. No design docs and no new mechanism. +- **Cheapest option first.** Before building, name the smallest change that + solves the problem, including changing configuration or deleting something. If + your plan adds a new mechanism (RPC, process, binary, abstraction, config + field, tool) or grows past about 100 lines, stop and assess whether you're + taking the path of least resistance. +- **Delete before adding.** Unused code, dead paths, fallbacks nobody takes and + features nobody runs get removed, not maintained. Solo project, single user: + breaking changes need no compatibility shims. +- **Finish before starting.** Prefer completing a half-built feature end to end + over starting a new one. +- **No new binaries.** A new command is a subcommand of an existing binary. A + binary exists only for a real process boundary (separate deploy, scaling, + security or failure domain). - **No compensating tools.** Do not write a linter, checker or generator to enforce something a simpler design would make unnecessary. Fix the design. - **A setting must work end to end.** A config field that parses but has no consumer is a bug. Settings are edited through the control plane (API and dashboard), never by requiring a server login. - **Ask only for real decisions.** Product direction and trade-offs the - maintainer owns are questions. Everything with a conventional answer is - not: decide, do it, say what you chose. + maintainer owns are questions. Everything with a conventional answer is not: + decide, do it, say what you chose. ## Code - Idiomatic Go. Small functions, explicit errors, no package-level mutable - state, no god objects. `internal/app/archied/bootstrap.go` is the - counter-example: never add to it. New wiring belongs to the feature that - needs it. + state, no god objects. Each feature wires itself; a composition root only + calls those constructors in order. - Dependencies point inward: `cmd → app → {domain, infrastructure}`, `infrastructure` implements `domain` interfaces, `domain` imports neither. `cmd/` parses flags and calls `app`, nothing else. -- Fix invalid state where it is produced, not with checks where it is - consumed. +- Fix invalid state where it is produced, not with checks where it is consumed. - If a fix fails twice, throw the block away and rewrite it simply. - Comments say why, briefly. No migration history, phase names or issue narration in code. @@ -76,19 +72,18 @@ the repo and are not guidance. Do not recreate them. The default for a change is no new test. Write one only when: -- something actually broke: write the test that reproduces it, see it fail - on the assertion, then fix; or -- the change alters one of these seams: State Store SQL semantics - (transition guards, idempotent dispatch, cancellation), security - boundaries (HMAC, grants, path confinement, egress, secrets), the workflow - step contract, or the import-boundary rules. +- something actually broke: write the test that reproduces it, see it fail on + the assertion, then fix; or +- the change alters one of these seams: State Store SQL semantics (transition + guards, idempotent dispatch, cancellation), security boundaries (HMAC, grants, + path confinement, egress, secrets), the workflow step contract, or the + import-boundary rules. -A test that exists must catch a real regression, survive refactoring, run -fast, and be cheap to keep. Never test wiring, constants, defaults, struct -shapes, fakes, or call order. One table-driven test per behaviour; extend -the table instead of adding a second test. Prefer making an invalid state -unrepresentable to testing that it is rejected. Test helpers live in -`_test.go` files only. +A test that exists must catch a real regression, survive refactoring, run fast, +and be cheap to keep. Never test wiring, constants, defaults, struct shapes, +fakes, or call order. One table-driven test per behaviour; extend the table +instead of adding a second test. Prefer making an invalid state unrepresentable +to testing that it is rejected. Test helpers live in `_test.go` files only. ## Invariants @@ -113,17 +108,17 @@ task ui # dashboard into ui/dist task check # the gate ``` -Requires Go 1.27, Task, golangci-lint, Node/npm and Docker. -Adopt `task fmt` and `go fix` output as-is. +Requires Go 1.27, Task, golangci-lint, Node/npm and Docker. Adopt `task fmt` and +`go fix` output as-is. -- `task check` gates the commit: `task check && git commit ...`. Never claim - a gate result you did not just produce on that exact tree; if the gate - could not run, say what you did verify. -- Commit finished work without asking. Stage only your own paths and commit - in the same command. Conventional Commits scoped by package, short - messages. Push only when told. -- Never commit binaries, build output, scratch files or `.references/`. - Scratch goes in `/tmp`. +- `task check` gates the commit: `task check && git commit ...`. Never claim a + gate result you did not just produce on that exact tree; if the gate could not + run, say what you did verify. +- Commit finished work without asking. Stage only your own paths and commit in + the same command. Conventional Commits scoped by package, short messages. Push + only when told. +- Never commit binaries, build output, scratch files or `.references/`. Scratch + goes in `/tmp`. - Runtime config lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. Nothing in the working tree is read at runtime. Systemd is optional. - Releases: `RELEASING.md`. @@ -136,16 +131,16 @@ Work is tracked in `bd`, never in Markdown TODO files. bd ready | bd show | bd update --claim | bd close ``` -- An issue is the plan: what is wrong or wanted, and how you know it is - done. Keep it to that. -- Bead state syncs through Dolt (`bd dolt push/pull`, only when told), not - git. Never commit `.beads/` exports. +- An issue is the plan: what is wrong or wanted, and how you know it is done. + Keep it to that. +- Bead state syncs through Dolt (`bd dolt push/pull`, only when told), not git. + Never commit `.beads/` exports. - No host names, IPs, paths, PIDs or credentials in any bead: they are published. - File follow-up work you find as a bead. Do not fix it in passing. ## Changing this file -A rule is added only after a real failure it would have prevented, and it -must say which decision it changes. Remove rules that no longer change -decisions. Keep it short enough to read in full every session. +A rule is added only after a real failure it would have prevented, and it must +say which decision it changes. Remove rules that no longer change decisions. +Keep it short enough to read in full every session.