docs: constitution review edits; state the wiring rule without naming a file

This commit is contained in:
sam committed 2026-10-03 22:38:44 +10:00
1 parent 75988204d5
commit 6078dc1565
1 file changed
+59 -64
+59 -64
View File
@@ -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.
<temporary - this statement must be removed on 2026-10-10"> 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. </temporary>
## 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 <id>`): 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 <id> | bd update <id> --claim | bd close <id>
```
- 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.