chore: fix CLAUDE.md to flow and remove contradictions.
This commit is contained in:
1 parent
ec5e83a995
commit
7e819d85ef
1 file changed
+201
-585
@@ -1,627 +1,243 @@
|
||||
# CLAUDE.md
|
||||
# AGENTS.md
|
||||
|
||||
Guidance for any coding agent working in this repository.
|
||||
|
||||
`AGENTS.md` is a symlink to this file, so Claude, Codex, Pi, Tau and anything
|
||||
else reading either name get the same instructions. **Keep every rule here
|
||||
harness-agnostic**: name the behaviour required, not the tool that provides it.
|
||||
"Spawn a fresh reviewer that did not write the code" is a rule; "run
|
||||
`/code-review`" is one harness's way of satisfying it. The single exception is
|
||||
the memory note under Issue Tracking, which is explicitly Claude-scoped.
|
||||
Keep every rule here harness-agnostic: name the required behaviour, not the tool
|
||||
that provides it (e.g. "spawn a fresh reviewer that did not write the code", not
|
||||
a specific sub-command).
|
||||
|
||||
## Code Quality & Refactoring Standards
|
||||
|
||||
- **Zero Patch Stacking:** Never apply more than two sequential fixes to the
|
||||
same logic block. If a solution fails twice, scrap the block and rewrite it
|
||||
cleanly.
|
||||
- **Root-Cause Fixes:** Fix invalid state at the producer, not via defensive
|
||||
checks at the consumer.
|
||||
- **Architectural Simplicity:** Prefer a complete 20-line rewrite over a 5-line
|
||||
band-aid that adds conditional complexity or obscures intent.
|
||||
- **Revert on Flail:** If an implementation becomes convoluted to satisfy edge
|
||||
cases, discard the approach and select a simpler design.
|
||||
|
||||
## What this is
|
||||
|
||||
**archied** is a resident daemon that polls a forge (GitHub, Gitea planned) for
|
||||
issues assigned/labelled to it, works each one in an isolated git worktree
|
||||
through a routed workflow (bootstrap / implement / TDD / feasibility), and opens
|
||||
pull requests for human review. See `ARCHITECTURE.md` for the full package map,
|
||||
workflow engine design, task lifecycle, and key design decisions — read it
|
||||
before making non-trivial changes, since several invariants (env-enforced gates,
|
||||
model never runs git, agent execution as a data boundary) aren't obvious from
|
||||
the code alone.
|
||||
**archied** is a resident daemon that polls a forge (GitHub, Gitea) for issues
|
||||
assigned/labelled to it, works each one in an isolated git worktree through a
|
||||
routed workflow (bootstrap / implement / TDD / feasibility), and opens pull
|
||||
requests for human review.
|
||||
|
||||
## Scope discipline (read this before planning anything)
|
||||
See `ARCHITECTURE.md` for the package map, workflow engine design, task
|
||||
lifecycle, and key design decisions. Read it before making non-trivial changes.
|
||||
Key invariants: env-enforced gates, model never runs git, and agent execution
|
||||
functions as a strict data boundary.
|
||||
|
||||
`docs/architecture/` is authoritative for everything it covers: implement
|
||||
against it, don't re-litigate it, don't restate it in a new document.
|
||||
## Scope Discipline
|
||||
|
||||
It does not cover everything, and this section used to claim it did — it
|
||||
called the design "complete" and banned design documents outright. That was
|
||||
wrong on its face: this repo is mid-migration to a domain-oriented structure,
|
||||
and `docs/architecture/migration-decisions.md` is an **open decision
|
||||
register** whose entire job is holding design that is not settled yet. A rule
|
||||
asserting the design is finished, in a tree that ships a list of what remains
|
||||
to be decided, pushed every genuinely new capability through a prohibition
|
||||
aimed only at sprawl. The ban was a proxy: what it meant to stop was prose
|
||||
substituting for a diff, not thinking before building something new.
|
||||
`docs/architecture/` is authoritative for settled design.
|
||||
`docs/architecture/migration-decisions.md` is the open decision register for the
|
||||
domain migration.
|
||||
|
||||
So the test is **is there a settled design for this**, never **is this a
|
||||
document**:
|
||||
- **Settled design exists** → Implement it immediately with a diff. Do not
|
||||
produce design prose. If a small detail is missing, ask the maintainer
|
||||
directly.
|
||||
- **No settled design exists (or open in `migration-decisions.md`)** → Write a
|
||||
decisive, 1-page design doc before coding. Land new capabilities in
|
||||
`docs/prds/` and migration questions in
|
||||
`docs/architecture/migration-decisions.md`. Promote to `docs/architecture/`
|
||||
only after implementation lands.
|
||||
- **Strictly Prohibited:** Ownership ledgers, field-level inventories,
|
||||
current-state traces, parity matrices for their own sake, and
|
||||
planning/refactor tracking issues.
|
||||
- **Solo Project Context:** Prefer the smallest workable change over extensive
|
||||
defensive scaffolding.
|
||||
|
||||
- **Settled design exists** → implement it. Producing prose instead of a diff
|
||||
is the failure. If one detail is missing, ask the maintainer in a sentence;
|
||||
don't write a document to resolve a sentence-sized question.
|
||||
- **No settled design exists** — genuinely new capability, or an open item in
|
||||
`migration-decisions.md` → design first, briefly and decisively. This is
|
||||
required, not merely tolerated. Accreting diffs toward a new architecture
|
||||
without deciding its shape is how the flat `internal/` layout happened, and
|
||||
undoing that is measured in weeks.
|
||||
## Deployment Model
|
||||
|
||||
A design artifact earns its place by being short, decisive, and followed by
|
||||
code:
|
||||
- **Systemd is optional:** `deployments/` holds supported profiles
|
||||
(`single-forge-github.toml`, `multi-forge-github-gitea.toml`,
|
||||
`local-ollama-standalone.toml`, `docker-nats-stack.toml`,
|
||||
`systemd-user-service.md`). Never assume a systemd unit exists.
|
||||
- **Chat filesystem confinement:** Builtin tools default to workspace jail via
|
||||
`SetPathConfinement(!unrestricted)`. Unrestricted access requires
|
||||
`[chat] unrestricted_filesystem = true`.
|
||||
- **NATS endpoint immutability:** The daemon passes agent containers its startup
|
||||
connection URL (`d.ConnectedNATS.URL`). Containers and daemon must resolve
|
||||
this address. Embedded mode binds to the Docker bridge gateway. A SIGHUP
|
||||
reload of `nats.url` logs an error requiring restart to prevent split-brain
|
||||
delivery.
|
||||
- **Container pull policy:** `containers.pull_policy` must be `"missing"`
|
||||
(default) or `"always"`. Private registries return 401 on `"always"` because
|
||||
no auth is sent. Refresh explicitly via `docker compose pull agent`.
|
||||
- **Docker Compose:** `docker-compose.yml` carries optional external NATS and
|
||||
the `agent` build stanza. The agent uses a `build` profile so `up -d nats`
|
||||
never starts it as a persistent service.
|
||||
- **Config path:** Runtime configuration lives at
|
||||
`${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. Nothing in the working
|
||||
tree is load-bearing at runtime.
|
||||
|
||||
- One page, and it **decides**. It does not survey options, inventory fields,
|
||||
or trace current state — the code is the current state, so a document
|
||||
restating it is stale on arrival.
|
||||
- It lands in a named home: `docs/prds/` for new capability, an entry in
|
||||
`docs/architecture/migration-decisions.md` for an open migration question.
|
||||
Promote it into `docs/architecture/` only once it is built and true.
|
||||
- It is not finished until a diff follows it. Design with no implementation is
|
||||
the same sprawl in better clothes.
|
||||
- Failure test: cut anything a reader could have learned by reading the code.
|
||||
## Release Process
|
||||
|
||||
Still prohibited, and none of these were ever design:
|
||||
|
||||
- Ownership ledgers, field-level inventories, current-state traces, parity
|
||||
matrices written for their own sake, and review campaigns.
|
||||
- Planning, review, or refactor **issues**. Open issues only for concrete bugs
|
||||
and user-facing features.
|
||||
|
||||
This is a **solo project**. There is no review board, no handoff to a
|
||||
zero-context engineer, no compliance requirement. Prefer the smallest change
|
||||
that works over the most defensible one.
|
||||
|
||||
Issues are tracked in GitHub Issues; grouped issues can be linked under an
|
||||
epic, with subtasks linked to the epic.
|
||||
|
||||
## Deployment model
|
||||
|
||||
**archied supports several deployment shapes; systemd is not required.**
|
||||
`deployments/` holds the supported profiles — `single-forge-github.toml`,
|
||||
`multi-forge-github-gitea.toml`, `local-ollama-standalone.toml`,
|
||||
`docker-nats-stack.toml`, and `systemd-user-service.md` as one operational
|
||||
runbook among them. Do not write code or docs that assume a systemd unit exists.
|
||||
|
||||
**The chat agent's file tools are workspace-confined by default.** `builtin`
|
||||
tool construction calls `SetPathConfinement(!unrestricted)`, so read, write,
|
||||
edit, find and grep are jailed to the configured workspace unless
|
||||
`[chat] unrestricted_filesystem = true` lifts it
|
||||
(`internal/config/config.go`, `internal/tools/provider/builtin/provider.go`).
|
||||
That setting is commented out in `config.example.toml` — an operator opt-in, not
|
||||
the default, and not an architectural requirement. Where the daemon runs and
|
||||
whether the jail is lifted together determine which filesystem those tools can
|
||||
reach; neither is something the code should assume. `archied` and embedded NATS
|
||||
run in the native daemon; per-task `archie-agent` workers run in Docker.
|
||||
|
||||
**The daemon hands agent containers the NATS endpoint its own client connected with at startup** — see
|
||||
`containerEnv` in `internal/daemon/daemon.go`, which appends `NATS_URL=` from
|
||||
`d.ConnectedNATS.URL`, captured at construction. That endpoint must therefore
|
||||
be reachable from wherever the daemon runs *and* from inside the containers.
|
||||
Embedded mode resolves the selected Docker bridge first and binds its
|
||||
authenticated listener to that bridge's host gateway. External mode needs an
|
||||
operator-supplied URL reachable from both; for the optional Compose broker that
|
||||
is the pinned `172.19.0.1` gateway, not the service name and not localhost.
|
||||
|
||||
The two URLs are the same today and deliberately *not* the same after a
|
||||
SIGHUP reload of `nats.url`: the daemon's own client is startup-built, so a
|
||||
reload that pointed new containers at the new URL would launch them on a
|
||||
server the daemon is not publishing on, and every task would park with
|
||||
`ErrNoResponders`. Freezing the connected endpoint makes that divergence
|
||||
impossible regardless of what the config says or who reloads it; a reloaded
|
||||
`nats.url` is logged as a change that requires a restart.
|
||||
|
||||
**`containers.pull_policy` can only be `"missing"`** (the default) or
|
||||
`"always"`. `"always"` against a private registry answers 401, because the
|
||||
daemon sends no credentials to the Docker API. Refresh the agent image
|
||||
explicitly instead: `docker compose pull agent`.
|
||||
|
||||
**`docker-compose.yml`** is optional in the default embedded deployment. It
|
||||
carries an external NATS service plus the agent build stanza. The agent has a
|
||||
`build` profile so `up -d nats` never starts it as a service — without the
|
||||
profile, Compose creates a container that exits 0 immediately and reports
|
||||
"Started", which reads as a crash loop. `docker compose build agent` and
|
||||
`docker compose pull agent` work by name without activating the profile.
|
||||
|
||||
**Config lives outside the repo**, at
|
||||
`${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. Nothing in the repo working
|
||||
tree is load-bearing at runtime. Reference templates are in `deployments/`;
|
||||
`config.example.toml` is the annotated schema.
|
||||
|
||||
## Release process
|
||||
|
||||
See `RELEASING.md` for the full process and the standing rule on when to
|
||||
version each component — most sessions only touch `archied`, so most releases
|
||||
are gateway-only (`RUNTIME=skip`) by default. Don't ask whether to skip an
|
||||
untouched component; skip it and say so in the handoff.
|
||||
See `RELEASING.md`. Most sessions touch only `archied`, making releases
|
||||
gateway-only (`RUNTIME=skip`) by default. Skip untouched components
|
||||
automatically and note it in the handoff.
|
||||
|
||||
## Build & Test
|
||||
|
||||
Commands are defined in `Taskfile.yml` (uses [Task](https://taskfile.dev)); run
|
||||
`task --list` to see everything.
|
||||
|
||||
**Prerequisites:** Go 1.26.5 (matched exactly by `go.mod`), [Task], `gofumpt`,
|
||||
`golangci-lint`, and **Node/npm** — `task check` runs the dashboard suite too, so
|
||||
a Go-only toolchain cannot complete the gate.
|
||||
|
||||
[Task]: https://taskfile.dev
|
||||
Commands are defined in `Taskfile.yml` (requires Go 1.26.5,
|
||||
[Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, and Node/npm).
|
||||
|
||||
```bash
|
||||
task build # build archied and archie-agent binaries into bin/
|
||||
task test # go test ./... -count=1
|
||||
task test:ui # dashboard node tests (DOM-building primitives)
|
||||
task ui # build the dashboard into ui/dist (committed — see below)
|
||||
task ui # build dashboard into ui/dist (LAW asset)
|
||||
task fmt # gofumpt -w . && go fix ./...
|
||||
task vet # go vet ./...
|
||||
task lint # golangci-lint run ./...
|
||||
task check # fmt + go fix + vet + build + test + test:ui
|
||||
task dev # archied live-reload + Vite HMR together, on :5173
|
||||
task check # fmt + go fix + vet + build + test + test:ui (The Definitive Gate)
|
||||
task dev # archied live-reload + Vite HMR together on :5173
|
||||
```
|
||||
|
||||
`task check` is the gate, and it includes `test:ui` deliberately: nothing else
|
||||
runs the dashboard suite, so left out it rots silently and a broken DOM
|
||||
primitive ships. Note that `task fmt` **rewrites files**, so `check` is not a
|
||||
read-only verification step.
|
||||
|
||||
Run a single test: `go test ./internal/domain/workflow/... -run TestName -v`.
|
||||
|
||||
Docker helpers: `task docker-build` builds the agent image locally;
|
||||
`task docker-up`, `task docker-down`, and `task docker-logs` manage the optional
|
||||
external NATS service.
|
||||
|
||||
## Repository hygiene
|
||||
|
||||
- **`ui/dist` is committed on purpose.** The Go build embeds it, so building
|
||||
`archied` must never require a Node toolchain. If you change anything under
|
||||
`ui/src`, run `task ui` and commit the rebuilt `ui/dist` in the same change.
|
||||
Never add it to `.gitignore`.
|
||||
- **Do not commit** build artefacts or local state: `/archied`, `/archie-agent`,
|
||||
`/bin/`, `*.db`, `*.png` working screenshots, `.references/`,
|
||||
`config.production.toml`, `.env`, or the docs site's `node_modules/` and
|
||||
`.vitepress/{cache,dist}/`. `.gitignore` already covers these; the point is not
|
||||
to defeat it.
|
||||
- **Scratch files go outside the repo**, in the OS temp directory or your
|
||||
harness's scratch area — not in the working tree, where `worktree.CommitAll`
|
||||
will sweep them up (see the `WriteTaskJSON` trap below).
|
||||
- Commits follow **Conventional Commits** scoped by package:
|
||||
`feat(webui): ...`, `fix(build): ...`, `ci: ...`, `chore(release): ...`.
|
||||
- Commit finished, gate-clean work (passing `task check`, adversarial review
|
||||
clean) without stopping to ask first. Only push when asked.
|
||||
|
||||
## Organisation (strict)
|
||||
|
||||
`docs/architecture/organisation.md` is authoritative and approved. This section
|
||||
is the enforcement summary — read that doc before any structural change, and
|
||||
change the doc first if the rule itself needs to change.
|
||||
|
||||
**Archie is domain-driven, not flat.** `internal/` currently holds ~35 packages
|
||||
side by side. That is a migration in progress, not the target. Do **not** infer
|
||||
the structure from what is there: adding a sibling package next to
|
||||
`internal/gateway/` because that is where similar code lives today is how the
|
||||
flat layout keeps regrowing, and undoing it is measured in weeks.
|
||||
|
||||
### The layers, and what each owns
|
||||
|
||||
- **`internal/domain/<area>/`** — one cohesive job Archie performs. Owns that
|
||||
job's language, state, rules, operations, commands, events, policy
|
||||
implementations, runtime settings, and the _contracts_ it needs from the
|
||||
outside world. A domain declares the interface it needs; it never names who
|
||||
implements it.
|
||||
- **`internal/infrastructure/<service>/`** — implementations of those contracts:
|
||||
configuration, persistence, forge clients, event-bus transports, anything that
|
||||
talks to something external.
|
||||
- **`internal/app/<application>/`** — composition. Constructs domains and
|
||||
infrastructure, translates external configuration into domain settings,
|
||||
connects commands and events, starts services in dependency order, owns health
|
||||
aggregation and shutdown ordering. It is the only layer that knows about both
|
||||
of the two above.
|
||||
- **`cmd/<binary>/`** — process-level input only: flags, environment, signals.
|
||||
It MUST NOT contain substantive wiring and MUST NOT act as a service locator.
|
||||
|
||||
These stay under `internal/`. That is a compiler-enforced visibility boundary,
|
||||
not a naming convention: moving a layer to the repository root would make
|
||||
Archie's domain types importable by any module that depends on this one, and
|
||||
silently commit us to API stability on exactly the code that most needs to keep
|
||||
changing.
|
||||
|
||||
### Dependency direction is the invariant
|
||||
|
||||
`cmd → app → {domain, infrastructure}`, and `infrastructure → domain` to
|
||||
implement its contracts. Nothing points back up: a domain importing
|
||||
infrastructure, or infrastructure importing app, is a defect regardless of how
|
||||
convenient it is. If a domain needs something an infrastructure package has, the
|
||||
domain declares an interface and app wires the implementation in.
|
||||
|
||||
### Cross-cutting packages
|
||||
|
||||
Some packages are neither domain nor infrastructure because they serve both —
|
||||
`logging`, `events`, `eventbus`, `policy`, `taskstate`. They sit as named
|
||||
top-level packages under `internal/`, each named for what it provides.
|
||||
|
||||
The defining property is checkable, and it is the whole rule: **a cross-cutting
|
||||
package may be imported by any layer, and imports none of them.** Zero
|
||||
dependencies on domain, infrastructure or app. That is what lets it sit outside
|
||||
the dependency direction safely — it is a sink, never a source, so it cannot
|
||||
create a cycle or smuggle a dependency inward.
|
||||
|
||||
It is also the failure test: the moment such a package imports a domain type it
|
||||
has stopped being cross-cutting and become domain code that has been misfiled.
|
||||
|
||||
There is deliberately **no `shared/` directory**. "Shared" is a category, not a
|
||||
name, and a directory named for a category becomes the place things go when
|
||||
nobody can say what they are. `utils`, `helpers`, `common` and `misc` are
|
||||
prohibited for the same reason: if a package cannot be named for what it
|
||||
provides, it is misplaced, not shared.
|
||||
|
||||
Cross-cutting utilities exist precisely to keep the code DRY — a function owned
|
||||
by no single package and used by many. Do not wait for a second consumer to
|
||||
justify one, and do not copy a helper into two domains to avoid creating one.
|
||||
(The "second consumer" rule below is about feature code, not this.)
|
||||
|
||||
### Within a package: organise by concern, never by layer or type
|
||||
|
||||
- One file per API area, named for it: `api_tasks.go`, `api_logs.go`,
|
||||
`api_skills.go`. A new endpoint group is a new file. Cross-cutting wiring gets
|
||||
its own file too: `server.go` (routes and construction only), `auth.go`,
|
||||
`sse.go`.
|
||||
- **A package owns its own format end to end.** `internal/logging` defines the
|
||||
on-disk log format _and_ reads it (`reader.go`); `internal/webui/api_logs.go`
|
||||
is transport and parses nothing. If two packages both know a format, one of
|
||||
them is wrong.
|
||||
- Empty or ceremonial `entities`, `repositories` or `services` layers are
|
||||
prohibited. Code that changes together lives together.
|
||||
- No grab-bag file. If you cannot name a file after the single thing it does, it
|
||||
is doing more than one thing.
|
||||
|
||||
### Frontend
|
||||
|
||||
- One folder per feature under `ui/src/<feature>/`, holding its own `.js` and
|
||||
`.css`, with the JS importing its own CSS. Changing logs cannot disturb tasks.
|
||||
- Shared primitives live in `ui/src/base/` and `ui/src/css/`, one file per
|
||||
primitive (`button.css`, `card.css`, `pill.css`, `table.css`).
|
||||
- Extract a feature's code into a shared primitive on the **second** real
|
||||
consumer, never in anticipation of one.
|
||||
|
||||
### When to split
|
||||
|
||||
Split on concern, not line count. The triggers are: you scroll past unrelated
|
||||
code to change one thing, or two people editing different features collide in
|
||||
one file. Renaming a file to something vaguer to make new code fit is the
|
||||
failure this rule exists to prevent — add a file.
|
||||
|
||||
### Why
|
||||
|
||||
A domain that declares its own contracts can be tested, reviewed, replaced and
|
||||
reasoned about without the rest of the system. Once the direction of dependency
|
||||
inverts anywhere, that stops being true everywhere downstream. It also has an
|
||||
immediate cost with parallel sessions: `cmd/archied/main.go` had to be split
|
||||
hunk-by-hunk three times in one day because two sessions were editing it at once
|
||||
— a symptom of wiring living where it should not.
|
||||
|
||||
## Architecture
|
||||
|
||||
Full details live in `ARCHITECTURE.md` — do not duplicate it here; skim it
|
||||
whenever touching the daemon, workflow engine, or forge/worktree/store
|
||||
boundaries. Summary of what's evolved since that doc was last fully accurate:
|
||||
|
||||
- **The domain migration has begun.** `internal/domain/` (curator, workflow,
|
||||
workintake) and `internal/infrastructure/` (configuration, eventbus,
|
||||
modelcatalog, terminalprompt) both exist. The tree is authoritative over any
|
||||
package table; see `docs/architecture/migration-decisions.md` for the recorded
|
||||
position and what was agreed next.
|
||||
- The daemon has grown an RPC split (`internal/forgerpc`, `internal/storerpc`,
|
||||
`internal/worktreerpc`, `internal/natsrpc`) used by the task-scoped
|
||||
`archie-agent` worker. Autonomous workflows cross one full-task core-NATS
|
||||
handoff; the daemon has no local workflow runner. The eventbus transport is
|
||||
`internal/infrastructure/eventbus/`. Check those plus `docker-compose.yml` for
|
||||
the current split between `archied` and sandboxed workers.
|
||||
- `internal/gate/` — quality gate execution (the "environmental constraints over
|
||||
prompt rules" mechanism).
|
||||
- `internal/skill/`, `internal/skillscript/`, `internal/yaegiutil/` — SKILL.md
|
||||
support (listed as "Planned" in ARCHITECTURE.md; now has real implementation —
|
||||
check these packages for current state before assuming it's unbuilt).
|
||||
- `internal/channels/` — inbound chat/notification channels (e.g. Telegram — see
|
||||
`internal/channels/telegram/`, `internal/channels/email/`); channel-agnostic
|
||||
interface in `internal/channels/channel.go`.
|
||||
- `internal/memory/`, `internal/gateway/`,
|
||||
`internal/container/`, `internal/plugin/`, `internal/tools/`,
|
||||
`internal/taskrun/` — not documented in ARCHITECTURE.md; read the package
|
||||
before modifying, its doc comment and tests are the source of truth.
|
||||
|
||||
### Per-package traps (things an agent will break if it doesn't check first)
|
||||
|
||||
- **`internal/channels/telegram/`** — the long-polling branch calls
|
||||
`dropPendingUpdates(ctx, b)` before `go b.Start(ctx)`. This clears Telegram's
|
||||
24h undelivered-update queue so a reboot doesn't answer hours-old messages. It
|
||||
also runs on `/restart`. The webhook branch already passes
|
||||
`DropPendingUpdates: true` in `SetWebhookParams`; both paths must stay
|
||||
consistent.
|
||||
- **Telegram command menus resolve by SCOPE SPECIFICITY, not recency.** Order,
|
||||
most specific first: `chat_member` > `chat` > `chat_administrators` >
|
||||
`all_chat_administrators` > `all_group_chats` > `all_private_chats` >
|
||||
`default`. So `SetMyCommands` on `default` alone is **invisible in DMs** if
|
||||
anything was ever registered on `all_private_chats`. Hit when migrating a bot
|
||||
token between applications: our 8 commands landed on `default` and logged
|
||||
success while the menu still showed ~60 stale commands from the previous app.
|
||||
Menus are server-side state owned by Telegram and keyed to the **bot token** —
|
||||
they survive redeploys, rewrites and whole-application migrations. Inheriting a
|
||||
token means inheriting its menu, webhook config and other bot-level settings,
|
||||
so audit `getMyCommands` per scope and `getWebhookInfo` when taking one over.
|
||||
`commands.go` publishes to `default` + `all_private_chats` + `all_group_chats`
|
||||
so leftovers are overwritten rather than shadowing.
|
||||
- **`ai-sdk` streaming: `FullStream` is authoritative and MUST be drained until
|
||||
close.** Its writes are *synchronous*, so an unread `FullStream` stalls the
|
||||
producer and deadlocks the turn. `TextStream` is best-effort and silently
|
||||
DROPS deltas when not drained — consuming it deadlocked every streamed reply
|
||||
in production. Range `FullStream` and collect `core.StreamPartTextDelta`. See
|
||||
the doc comment on `core/stream_impl.go`. Related: check the pinned
|
||||
`go-telegram/bot` version against latest before hand-rolling anything — a
|
||||
Markdown→HTML converter was written while 4 releases behind, and
|
||||
`SendRichMessage` with `models.InputRichMessage{Markdown}` had made it
|
||||
obsolete. `EscapeMarkdown` does the *inverse* of formatting, and
|
||||
`ParseModeMarkdown == "MarkdownV2"` while `ParseModeMarkdownV1 == "Markdown"`
|
||||
— the names disagree with the values.
|
||||
- **NATS, three behaviours that have each caused a real defect:**
|
||||
(1) *Work-queue retention forbids overlapping consumers.* `ARCHIE_TASKS` uses
|
||||
`jetstream.WorkQueuePolicy`, so two consumers with overlapping `FilterSubjects`
|
||||
conflict and the later one silently receives nothing. `nats.Client.Subscribe`
|
||||
creates a NEW consumer, so calling it on subjects the client's own durable
|
||||
consumer already filters will never deliver — drain the existing consumer with
|
||||
`Fetch` instead. `internal/app/agentworker` deliberately uses core NATS only;
|
||||
restoring a worker JetStream consumer would also restore the deleted
|
||||
single-stage execution topology.
|
||||
(2) *Reply inboxes are not stream subjects.* Answering a request must use core
|
||||
NATS: the request message's reply address is an ephemeral `_INBOX.*` belonging
|
||||
to one waiting caller and part of no stream, so a durable publish to it fails.
|
||||
Full-task and RPC responders use core `msg.Respond`; never route their replies
|
||||
through `eventbus.Publisher`.
|
||||
(3) *Subscribe does not mean reachable.* `nc.Subscribe` only queues the SUB
|
||||
frame client-side, so code that registers a responder and immediately issues a
|
||||
request can beat its own subscription and get `ErrNoResponders` from a
|
||||
responder that is, by then, listening. `natsrpc.RegisterAll` now flushes before
|
||||
returning — this was the cause of the long-standing
|
||||
`TestRunTaskExecutesBootstrapWorkflowEndToEnd` CI flake that passed in
|
||||
isolation and failed under full-suite load.
|
||||
- **`internal/gateway/` chat prompt** — `BuildSystemPrompt` renders
|
||||
`templates/archie.md.tpl`. The `<tools>` block is built from the **same**
|
||||
`core.ToolSet` passed to the model, so the prompt cannot claim a tool the model
|
||||
cannot call; never source the tool list from anywhere else. An empty toolset
|
||||
deliberately renders "no tools are available" rather than an empty block,
|
||||
because an empty block reads as "you have tools" and the model invents them.
|
||||
Personas are the STYLE layer only — instruction precedence, core rules and the
|
||||
`<tools>`/`<env>` blocks live in the template, so selecting a persona can never
|
||||
strip rules or tool inventory. Do not move rules into persona strings.
|
||||
`internal/tools/provider/contract_test.go` asserts the literal wiring strings
|
||||
`chatGenerateOptions(nil, toolReg` and `toolSummaries(options.Tools)` in
|
||||
`cmd/archied/main.go` — refactoring that call site fails that test **by
|
||||
design**.
|
||||
- **`internal/container/pool.go` `WriteTaskJSON`** — the per-task boot brief
|
||||
goes to `<worktree>/.git/task.json`, not the worktree root.
|
||||
`worktree.CommitAll` stages via go-git `Add{All:true}`, which ignores
|
||||
`.gitignore` and `.git/info/exclude`, so anything in the worktree root is
|
||||
pushed onto the task branch. Nothing under `.git` can be tracked;
|
||||
`worktree.go:41-46` documents this reasoning for the prepared sentinel. If you
|
||||
change the path, update `internal/infrastructure/agentboot/task.go` `TaskID`
|
||||
(the reader) in lockstep.
|
||||
- **MCP providers are registered by the daemon as _optional_**
|
||||
(`cmd/archied/ main.go`, `providerRegistry.RegisterOptional`). One that cannot
|
||||
start is logged at error level, excluded from the running set, and reported
|
||||
through `Registry.Health` as degraded — it does not roll back the other
|
||||
providers or stop the daemon. That was previously a hard failure, so one
|
||||
broken npm package unregistered every builtin tool and crash-looped archied
|
||||
under `Restart=on-failure`, taking Telegram with it. Providers the daemon
|
||||
genuinely requires still use `Register` and keep atomic rollback; check
|
||||
`providerRegistry.Skipped()` when tools are mysteriously missing. No
|
||||
npx-launched servers are configured in production anyway — the builtin tools
|
||||
(read, write, edit, find, grep, shell) and `web_fetch`. There is no `test`
|
||||
tool; gates run test commands, the model does not.
|
||||
|
||||
**Task lifecycle** (from ARCHITECTURE.md, still current):
|
||||
`queued → running(workflow:stage) → pr_open → merged|rejected`, with
|
||||
`waiting_human` and `parked` side states. Crash recovery re-queues anything left
|
||||
`running`. A park records its reason on the task, which the dashboard and
|
||||
`/api/tasks` surface; it no longer comments on the forge issue. Retries are an
|
||||
explicit operator action (dashboard or chat), capped by `max_retries`, not a
|
||||
label a human removes.
|
||||
|
||||
**Config** is daemon-level TOML (see `config.example.toml`), not per-repo files
|
||||
in this repo. Multi-identity deployments run more than one identity from a
|
||||
single daemon, each with a distinct `bot_user`; see
|
||||
`deployments/multi-forge-github-gitea.toml` and `docs/architecture/identity.md`
|
||||
before changing multi-identity or dispatch behaviour. Details of any particular
|
||||
operator's hosts belong in that operator's own notes, not here.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Go 1.26.5, module `github.com/samcharles93/archie-core`.
|
||||
- `ai-sdk/runtime`, `ai-sdk/agentloop`, `ai-sdk/core` are external other
|
||||
projects, not vendored copies. Changes affect other repos.
|
||||
- **Commit the meaning, not just the change.** When a change alters what
|
||||
something MEANS rather than what it does, say so explicitly in the commit body
|
||||
and in the code comment: "X used to mean A; it now means B, because C." Update
|
||||
the doc comment in the same commit — a comment that contradicts its code is
|
||||
worse than no comment, because the next reader trusts it. This is not
|
||||
ceremony: over 2026-08-04/05, three consecutive rounds of fixes each introduced
|
||||
a regression the next round caught, and **every one passed `task check` with
|
||||
tests written for it** (a summary that sorted to the end of history; a cache
|
||||
slot claimed before the store write; a degraded container pool that silently
|
||||
ran agent loops in-process with the daemon's own authority, removing the
|
||||
isolation boundary `[containers]` exists to provide). Tests catch behaviour
|
||||
that breaks; they do not catch behaviour that quietly starts meaning something
|
||||
else. Roughly half of what adversarial reviewers found, they found by noticing
|
||||
a doc comment or commit message that no longer matched the code.
|
||||
- **Lifting code from tau requires a provenance header** on every copied file,
|
||||
naming the tau source path, the tau commit it came from, and the deliberate
|
||||
mutations. This turns copy-paste drift into a diff instead of archaeology.
|
||||
(Reuse strategy is copy-and-mutate, never extraction into shared libraries.)
|
||||
- Non-interactive shell commands only: some environments alias `cp`/`mv`/`rm` to
|
||||
`-i`. Use `cp -f`, `mv -f`, `rm -f`/`rm -rf`, `scp -o BatchMode=yes`,
|
||||
`ssh -o BatchMode=yes`, `apt-get -y`.
|
||||
- Environmental enforcement over prompt rules: gates, test-file protection, and
|
||||
diff caps are code-level checks the agent cannot talk its way around — follow
|
||||
this pattern for any new safety constraint rather than adding it to a system
|
||||
prompt.
|
||||
- **Plugin engine rule (strict):** “engine” means a typed, lifecycle-managed
|
||||
capability family with an owning registry or manager; it never means another
|
||||
method on the generic plugin interface. Keep `plugin.Plugin` metadata-only,
|
||||
give plugins narrow typed registrars instead of daemon access, and apply the
|
||||
lifecycle and trust-boundary requirements in
|
||||
[ARCHITECTURE.md#plugin-engine-rule-strict](ARCHITECTURE.md#plugin-engine-rule-strict).
|
||||
Its mechanically testable structure is enforced by
|
||||
`internal/plugin/architecture_test.go`; reviewers enforce its lifecycle,
|
||||
access, and trust semantics.
|
||||
- The model/agent never runs git directly — worktree operations
|
||||
(`internal/worktree/`) are deterministic daemon-owned steps, not agent tools.
|
||||
|
||||
## Development Protocol (mandatory)
|
||||
|
||||
This is not optional style guidance — every code change in this repo follows
|
||||
this sequence. It's the same discipline archied enforces on _itself_ via the
|
||||
TDD workflow in `ARCHITECTURE.md`.
|
||||
|
||||
**`task check` is the definitive quality gate.** `task check` = `fmt` +
|
||||
`go fix ./...` + `vet` + `build` + `test`, and it is the one command that must
|
||||
pass, clean, before any change is considered done — it's the literal analogue of
|
||||
the `[[repos.gate]]` archied runs against every PR it opens. Don't hand-pick a
|
||||
subset of `go test`/`go vet`/`go build` and call it good; run `task check` (or
|
||||
the scoped equivalent, e.g. `go test ./internal/foo/... -count=1` +
|
||||
`golangci-lint run ./internal/foo/...` for a single package) and confirm it's
|
||||
clean.
|
||||
|
||||
**Red-then-green, definitively:**
|
||||
|
||||
1. **Red** — write the failing test(s) first, against the _intended_ behavior,
|
||||
before any implementation code exists. Run them and confirm they fail for the
|
||||
right reason (not a compile error).
|
||||
2. **Green** — write the minimum implementation to make those tests pass. No
|
||||
implementation code is written before its test exists and fails.
|
||||
3. Confirm via `task check` (or scoped `go test .../... -count=1`) that the
|
||||
suite is green, `golangci-lint run` reports zero findings, and `gofumpt -w .`
|
||||
reports no unformatted files.
|
||||
4. No hardcoded values in tests (use parameterized test tables), no hardcoded
|
||||
identity/config values in implementation code, and every error path gets a
|
||||
test.
|
||||
|
||||
**Adversarial verification is mandatory, and it runs as a separate pass from a
|
||||
fresh reviewer — never self-certified by the implementer.** After red-then-green
|
||||
is green:
|
||||
|
||||
- Run the review from a context with no memory of how the code was written, and
|
||||
instruct it to assume every line is wrong until proven correct. Any mechanism
|
||||
that achieves this is fine — a fresh subagent, a separate session, a review
|
||||
command your harness provides.
|
||||
- The checklist: all tests pass, lint is zero-findings, formatting is clean,
|
||||
then a manual read of every non-test file in the changed package for — dead
|
||||
code paths, unchecked error returns, hardcoded values that should be
|
||||
parameters/constants, interface satisfaction, nil-pointer risk, goroutine
|
||||
leaks, and races on shared mutable state.
|
||||
- Findings are **reported**, not silently fixed by the same pass that wrote the
|
||||
code — a finding that survives blocks closing the work, it doesn't get waved
|
||||
through. (If your harness has a structured findings mechanism, use it;
|
||||
otherwise a plain list is fine.)
|
||||
- Only close out the issue once the adversarial pass reports zero surviving
|
||||
findings.
|
||||
|
||||
**Lint-driven changes are behaviour-bearing. Review them; never trust them.**
|
||||
Two confirmed regressions, one from each shape lint work takes:
|
||||
|
||||
1. **Autofix.** A `golangci-lint --fix` batch across 8 files had its `errorlint`
|
||||
fix in `internal/tools/builtin/grep.go` rewrite
|
||||
`if exitErr, ok := err.(*exec.ExitError); ok && exitErr.ExitCode() == 1` into
|
||||
`errors.As(err, &exitErr)` **without the exit-code check**. ripgrep exit 1
|
||||
means no matches; exit 2 means the search never ran. So every failure was
|
||||
reported to the model as "no matches found", and the agent would state a file
|
||||
contains nothing on the strength of a search that never happened. The fix kept
|
||||
`errors.As` **and** restored the predicate — errorlint reports 0 issues on
|
||||
that form, so satisfying the linter never required dropping it. *Pattern:*
|
||||
fixers rewrite the error-matching part of a compound condition and can widen
|
||||
or narrow the predicate around it. Any autofix touching a condition needs its
|
||||
pre-fix behaviour checked.
|
||||
2. **Structural extraction** — the riskier shape. Clearing a `nestif` finding
|
||||
extracted a helper that took a slice **by pointer** and appended every
|
||||
surviving field to it; the caller's own loop then appended the same fields
|
||||
again. Every model name doubled (`/model gpt-5.6` asked the router for
|
||||
`gpt-5.6 gpt-5.6`), and an index loop becoming a range loop meant a
|
||||
space-separated `--provider openai` value was no longer consumed with its
|
||||
flag. Telegram model switching broke outright and nobody noticed. *Pattern:*
|
||||
when a `gocognit`/`nestif`/`cyclop` extraction hands a collection to a helper
|
||||
by pointer, or turns an index loop into a range loop, check the accumulation
|
||||
and skip semantics. The compiler catches neither.
|
||||
|
||||
**Verification discipline:** confirm a regression test actually fails against the
|
||||
buggy version before trusting it. The grep bug returned
|
||||
`Content: "no matches found", IsError: false`, which a naive test asserting only
|
||||
"no error" would have passed. For the doubled model name, assert **field count**
|
||||
rather than string equality, so a future re-extraction cannot pass by doubling a
|
||||
different part of the string.
|
||||
|
||||
## Issue Tracking
|
||||
|
||||
This project uses **GitHub Issues** (`samcharles93/archie-core`) via `gh` for
|
||||
issue tracking. Epics are parent issues; their work items are linked as native
|
||||
GitHub sub-issues. Labels: `task`, `feature`/`enhancement`, `bug`, `epic`,
|
||||
plus `in-progress` for active work.
|
||||
|
||||
*Claude-specific:* project memory lives in
|
||||
`~/.claude/projects/-work-apps-archie-core/memory/`. Other harnesses should use
|
||||
their own equivalent — nothing in this repo depends on it.
|
||||
|
||||
|
||||
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:46cd31e7 -->
|
||||
## Beads Issue Tracker
|
||||
|
||||
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
|
||||
|
||||
### Quick Reference
|
||||
Single package/test runs:
|
||||
|
||||
```bash
|
||||
bd ready # Find available work
|
||||
bd show <id> # View issue details
|
||||
bd update <id> --claim # Claim work
|
||||
bd close <id> # Complete work
|
||||
go test ./internal/domain/workflow/... -run TestName -v -count=1
|
||||
```
|
||||
|
||||
### Rules
|
||||
## Repository Hygiene
|
||||
|
||||
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
|
||||
- Run `bd prime` for detailed command reference and session close protocol
|
||||
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
|
||||
- **Generated assets are LAW:** Never modify, revert, or ignore generated files
|
||||
in `ui/dist/` or schema outputs. Incorporate them into relevant commits.
|
||||
- **Ignored paths:** Never commit build artifacts, binaries (`/bin/`,
|
||||
`/archied`), DB files, working screenshots, `.references/`, or
|
||||
`node_modules/`.
|
||||
- **Scratch files:** Place scratch files strictly in `/tmp` or the harness
|
||||
scratch space. Never put scratch files in the working tree
|
||||
(`worktree.CommitAll` will stage them).
|
||||
- **Conventional Commits:** Scope by package: `feat(webui): ...`,
|
||||
`fix(build): ...`, `chore(release): ...`.
|
||||
- **Commit policy:** Commit finished, gate-clean changes (`task check` passing +
|
||||
clean adversarial review) without asking. Push only when instructed.
|
||||
|
||||
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
|
||||
## Organisation (Strict Domain-Driven Architecture)
|
||||
|
||||
## Agent Context Profiles
|
||||
`docs/architecture/organisation.md` is authoritative. Do not follow flat
|
||||
structures found in legacy packages.
|
||||
|
||||
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
|
||||
### Layers and Ownership
|
||||
|
||||
- **Default**: Use `bd` for task tracking. Commit finished, gate-clean work
|
||||
(passing `task check`, adversarial review clean) without stopping to ask
|
||||
first, scoping `git add` to the files the change actually touches.
|
||||
Do not push or run Dolt remote sync unless explicitly asked. At handoff,
|
||||
report changed files, validation, and issue status.
|
||||
- `internal/domain/<area>/`: Domain logic, entities, state machines, commands,
|
||||
events, and required contracts (interfaces). Never imports infrastructure or
|
||||
app.
|
||||
- `internal/infrastructure/<service>/`: Implementations of domain contracts
|
||||
(persistence, forge clients, external transports, config loading).
|
||||
- `internal/app/<application>/`: Dependency injection, wiring domain to
|
||||
infrastructure, lifecycle management, and shutdown ordering.
|
||||
- `cmd/<binary>/`: CLI flag parsing, OS signal traps, and entry point routing
|
||||
only. No domain wiring.
|
||||
|
||||
## Session Completion
|
||||
### Invariants
|
||||
|
||||
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
|
||||
- **Dependency Flow:** `cmd → app → {domain, infrastructure}`, with
|
||||
`infrastructure → domain` implementing contracts. Downward/inward dependencies
|
||||
only.
|
||||
- **Cross-Cutting Packages:** `logging`, `events`, `eventbus`, `policy`,
|
||||
`taskstate` sit directly under `internal/`. They may be imported by any layer,
|
||||
but **must import zero internal packages**. No `shared/`, `utils/`, or
|
||||
`common/` catch-alls.
|
||||
- **File Layout:** One file per API concern (`api_tasks.go`, `api_logs.go`). A
|
||||
package owns its on-disk format end-to-end (e.g. `internal/logging` defines
|
||||
and reads its format; transport layers do not parse).
|
||||
- **Frontend:** Features live in `ui/src/<feature>/` with colocated `.js` and
|
||||
`.css`. Extract to `ui/src/base/` only on the second distinct consumer.
|
||||
|
||||
## Per-Package Invariants & Traps
|
||||
|
||||
- **`internal/channels/telegram/`:**
|
||||
- The long-polling worker must call `dropPendingUpdates(ctx, b)` before
|
||||
`b.Start(ctx)` and on `/restart`.
|
||||
- Always publish command menus to `default`, `all_private_chats`, and
|
||||
`all_group_chats` simultaneously via `commands.go` to avoid scope shadowing
|
||||
from legacy registrations.
|
||||
|
||||
- **`ai-sdk` Streaming:** `FullStream` writes synchronously and MUST be drained
|
||||
completely to prevent producer deadlocks. Do not rely on `TextStream` (drops
|
||||
deltas).
|
||||
- **NATS Invariants:**
|
||||
- `ARCHIE_TASKS` uses `jetstream.WorkQueuePolicy`. Do not bind overlapping
|
||||
consumer filters; use `Fetch` on existing durables instead of new `Subscribe`
|
||||
calls.
|
||||
- RPC and task responses must use core NATS `msg.Respond` to write to ephemeral
|
||||
`_INBOX.*` subjects, not `eventbus.Publisher`.
|
||||
- Always flush connections (`nc.Flush()`) immediately after registering
|
||||
responders to avoid race conditions on initial requests.
|
||||
|
||||
- **`internal/gateway/` Chat Prompt:** System prompt `<tools>` blocks are
|
||||
rendered strictly from the active `core.ToolSet`. Never decouple prompt tool
|
||||
definitions from passed runtime tools.
|
||||
- **`internal/container/pool.go` (`WriteTaskJSON`):** Write task briefs to
|
||||
`<worktree>/.git/task.json`. Never place them in the worktree root (`go-git`
|
||||
`Add{All:true}` ignores `.gitignore` and leaks root files into branch
|
||||
commits).
|
||||
- **MCP Providers:** Daemon registers providers as optional via
|
||||
`providerRegistry.RegisterOptional`. Missing or failed providers log warnings
|
||||
and degrade health without terminating the process.
|
||||
|
||||
## Development Protocol
|
||||
|
||||
1. **Red (Failing Test):** Write failing test cases first using table-driven
|
||||
tests against target behaviour. Verify the failure originates from test
|
||||
assertions, not compilation errors.
|
||||
2. **Green (Implementation):** Implement minimal code to satisfy the failing
|
||||
tests.
|
||||
3. **Quality Gate:** Run `task check`.
|
||||
4. **Formatting is LAW:** Adopt all formatting and simplification changes from
|
||||
`task fmt` (`gofumpt` + `go fix`) verbatim. Never revert or fight canonical
|
||||
linter/formatter diffs.
|
||||
5. **Adversarial Verification:** Run a verification pass using an isolated
|
||||
reviewer context assuming all changes are incorrect until verified. Check:
|
||||
dead code, unchecked errors, hardcoded constants, missing error paths, nil
|
||||
pointers, goroutine leaks, and race conditions.
|
||||
6. **Linter Guard:**
|
||||
|
||||
- When using `errorlint` fixes, ensure boolean predicates (e.g.
|
||||
`exitErr.ExitCode() == 1`) are retained alongside `errors.As`.
|
||||
- When extracting loops/conditionals, verify slice mutations and pointer
|
||||
semantics do not duplicate elements.
|
||||
|
||||
## Issue Tracking (Beads)
|
||||
|
||||
All task management is tracked via **bd (beads)**. Do not write local Markdown
|
||||
TODO lists or use non-Beads trackers.
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
bd ready # List unclaimed work
|
||||
bd show <id> # View issue details
|
||||
bd update <id> --claim # Claim an issue
|
||||
bd close <id> # Mark issue complete
|
||||
bd remember # Persist cross-session architectural facts
|
||||
```
|
||||
|
||||
- Run `bd prime` to inspect full engine context.
|
||||
- Use `bd remember` for knowledge retention. Do not write to root `MEMORY.md`
|
||||
files.
|
||||
- Issues live in a local Dolt DB; `.beads/issues.jsonl` is an export.
|
||||
|
||||
## Session Completion Protocol
|
||||
|
||||
1. **Log remaining work:** File new items via `bd` for identified debt or
|
||||
follow-up tasks.
|
||||
2. **Run gate:** Verify `task check` passes completely clean.
|
||||
3. **Update tracker:** Close finished issues via `bd close <id>`.
|
||||
4. **Commit:**
|
||||
|
||||
1. **File issues for remaining work** - Create beads for anything that needs follow-up
|
||||
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
||||
3. **Update issue status** - Close finished work, update in-progress items
|
||||
4. **Commit, then handle push/sync**:
|
||||
```bash
|
||||
# Default: commit finished, gate-clean work directly.
|
||||
git add <files the change touches>
|
||||
git commit -m "..."
|
||||
git status
|
||||
|
||||
# Push/sync only when explicitly asked:
|
||||
git pull --rebase
|
||||
bd dolt push
|
||||
git push
|
||||
git status
|
||||
git add <scoped-files>
|
||||
git commit -m "feat(scope): description"
|
||||
```
|
||||
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/push step
|
||||
|
||||
**Critical rules:**
|
||||
- Explicit user or orchestrator instructions override this Beads block.
|
||||
- Do not push or run Dolt remote sync without explicit authority.
|
||||
- If a required sync or push is blocked, stop and report the exact command and error.
|
||||
<!-- END BEADS INTEGRATION -->
|
||||
5. **Sync & Push Policy:** Do not push to git remotes or run `bd dolt push`
|
||||
unless explicitly instructed.
|
||||
6. **Handoff:** Report changed files, gate verification results, and active
|
||||
issue states.
|
||||
Reference in new issue
Block a user