Commit Graph
60 Commits
Author SHA1 Message Date
sam 0d35e753b5 refactor: format markdown files using prettier, fix spelling concerns, reduce Taskfile bloat 2026-09-25 01:10:28 +10:00
sam f36e17796c chore(staterpc): remove deprecated unary capture RPCs and Binding.secret
ListCaptures and ListUndispatchedCaptures had no callers once the client
moved to the streaming RPCs; they were kept only for mixed-version rollouts.
Binding.secret was unused since signing moved to Source; its number and
name are reserved.
2026-09-25 00:00:16 +10:00
sam c971348a86 docs(development): organise the guides by area
One page per area: frontend UI, agent, workflows, daemon (task lifecycle and
event automation together), State Store, control plane and settings, and
processes and wiring, with merging work kept separate.
2026-09-24 21:05:29 +10:00
sam 21e4d47907 docs(development): checklists for every kind of change
docs/development/ holds one page per kind of change (settings, State Store
and persistence, task lifecycle, workflows and steps, event automation,
dashboard, agent execution and containers, processes and wiring, merging
work), each naming every layer the change must reach and pointing at the
document that owns the design. The docs build puts them in the development
set; docs/index.md and CLAUDE.md link them.

Also adds the container-profile case to the validator agreement test, the
check the profiles work skipped.
2026-09-24 21:03:34 +10:00
sam 9864766804 docs: describe the PostgreSQL-only stores, state_dir and the import-only db_path
Architecture, deployment, installer, skill and PRD text now name the Postgres
State Store, the offline recovery commands on database_url, state_dir for host
state, and db_path as the legacy-file locator for archie-state-store import.
Finalised PRDs, CHANGELOG, docs/news and docs/archive are unchanged records.
2026-09-24 14:51:48 +10:00
sam c620e00396 feat(postgres): pool that refuses servers before PG 18, goose migrations under an advisory lock, testcontainers harness
internal/infrastructure/postgres opens a pgx pool, checks server_version_num >= 180000, and applies goose migrations with a Postgres session advisory lock so processes starting together apply each migration once. internal/infrastructure/postgres/pgtest starts postgres:18 through testcontainers per test binary and gives each test its own database. Adds jackc/pgx/v5 v5.11.0, pressly/goose/v3 v3.28.0 and testcontainers-go v0.44.0. The database URL config, sqlc, the Compose service and the ownership lock move to archie-core-7r0x.2, where they have consumers.
2026-09-24 01:03:08 +10:00
sam f4d20cfe0a fix(build): task check runs in ~27s cold, ~12s warm
task test runs -short with the test cache on; task test:full keeps the
uncached run. The 50s keepalive proof skips under -short (the deploy
workflow's full go test still runs it). Sleep-bound archied watch tests
run in parallel, and the read-only gate steps run concurrently after fmt
and proto:check. ui:deps is run: once so the parallel UI steps install once.
2026-09-24 00:29:07 +10:00
sam a65eae2458 docs(agents): a bead never carries production instance detail
Beads sync to a Dolt remote, so anything written into one is published.
Two beads filed earlier today named an operator host, its internal
address and its filesystem paths -- the tracker was treated as a private
store, which it is not.

The rule is stated where the tracker is described, next to the existing
one about .beads/ never reaching a commit, because it is the same class:
the tracker is not a private store. Host-specific facts belong in the
operator's memos instance, which a bead may point at.
2026-09-23 12:29:29 +10:00
sam e95a77c2f7 docs: delete ARCHITECTURE.md, move its normative content into docs/architecture
ARCHITECTURE.md duplicated the docs/architecture tree and had drifted badly
against it: "internal/ holds ~36" against 112 packages, two of the seven
binaries listed, a Forge table listing `RepliesAfter` (deleted from the tree),
and a stated invariant ("No daemon-internal cron") contradicted by the
scheduling engine that internal/app/archied/scheduling.go composes and
main.go starts.

It was also the sole home of three pieces of still-authoritative content, so
those move rather than disappear:

- plugin engine rule (strict), the memory engine family, and the
  internal/plugin/architecture_test.go enforcement note ->
  docs/architecture/plugins-and-extensions.md
- intake provenance: forge poll/webhook dedup through
  TaskEnvelope.IdempotencyKey, binding-stamped chat/playbook enqueue, and the
  single-identity webhook-intake rejection ->
  docs/architecture/messaging-and-work-intake.md

Live references are repointed from CLAUDE.md (AGENTS.md is a symlink to it),
docs/architecture, docs/guides, seven PRDs, and four .agents skills. The
heading "## Plugin engine rule (strict)" is preserved in its new home so the
existing #plugin-engine-rule-strict citations keep resolving. Generated docs
artifacts regenerated.
2026-09-22 23:49:53 +10:00
sam c74ebfab2d docs(agents): make the gate gate the commit
Two rules added to the quality-gate step, both learned by getting them wrong
tonight.

The gate must gate the commit: one conditional chain, so its exit status is what
decides whether the commit runs. Written as separate statements on one command
line it is decorative, because nothing reads its status but the operator -- the
failure is discovered after it has already been pushed.

And never assert a gate result that was not just produced on that exact tree. A
commit message outlives the tree it describes and is read by people who were not
there; if the tree has moved, describe the change and let the run speak.

AGENTS.md is a symlink to this file, so the edit belongs here.
2026-09-22 15:19:59 +10:00
sam a092e2198e test(eda): pin playbook dispatch ledger docs and regression gaps 2026-09-22 04:51:17 +10:00
sam c9765d9afd fix(eda): wire playbook dispatch ledger and validate its key 2026-09-22 04:36:28 +10:00
sam 2c4c03728a docs(skills): fold the config-wiring trap into the ledger
The rule belongs in CLAUDE.md, the inventory belongs in the config skill. The
skill already carried a decoded-but-unwired ledger and defines its status terms
exactly, so the entry now points at it instead of duplicating it, and the ledger
gains the live instance from 2026-09-22 (per-identity forge intake) plus the
three shapes an unwired field can take - not-consumed, not-projected, and
deliberately-not-projected, the last being UpdateCheckCommand/UpdateInstallCommand
read from base by design.
2026-09-22 03:39:23 +10:00
sam af3552c6e2 docs: record the config-field trap (a field that parses is not a field that works)
Three defects in one session landed the same way: a map field the file overlay
dropped (xrux), a field missing from the control-plane projection
(parallel_tool_calls), and per-identity forge.intake - accepted TOML that no
consumer reads, and which is not even validated. The entry names the shape,
gives the live example with file:line, and points at
docs/architecture/configuration.md as the config authority.
2026-09-22 03:21:27 +10:00
sam 93500976b0 docs: qualify the red step and require verifying handed-over input
Red-green stays the default, but a test that cannot fail for an interesting
reason is noise in the gate rather than evidence. Tests that restate an
assignment or a constant were being written to satisfy the protocol literally.

An empty handed-over export cost a whole autonomous run this session: the tree
was reconstructed from instead, on a 131-file change with no context. An
unreadable input is a blocking fact, not a gap to fill by inference.
2026-09-21 11:30:48 +10:00
sam 02720c8e81 feat(controlplane): runtime administration over the State Store's gRPC server
The Web UI and messaging channels now read and write Archie's runtime
settings through one versioned, audited control-plane API hosted on the
State Store's existing gRPC server: catalog, query, command, watch. Each
feature owns its resource, validation and commands; storage only writes
versions and audit records.

Workflows move with it. Definitions become portable YAML compiled through
a closed, typed step registry and stored as a control-plane resource, so
the yaegi interpretation paths (internal/gate, wfeval, wfextract,
gateeval, gateextract, skillbuild) are deleted rather than carried.

The UI process reads definitions as data: the JSON projection lives in
internal/domain/workflow/task so a dashboard decodes the stored
collection without linking the workflow engine, which cmd/archie-ui's
deletion gate forbids. Shipped definitions ride the catalog descriptor
rather than a bespoke REST route, keeping the API to its four operations.

archie-messaging gains -state-store-target/-state-store-token and reads
channel settings from the database, failing closed when the State Store
is unreachable: the database is authoritative for those settings.
2026-09-21 08:17:42 +10:00
sam 450a2d785a feat(webui): make attempts a pager above the tabs
The attempt selector becomes an icon-ended pager from the registry
pagination primitive: chevrons walk run history, numbers land on an
attempt, and the active page is the attempt on screen. It sits top-right
above the tab card, and the meta line loses the attempt text fact since
the control now carries it.
2026-09-21 00:25:54 +10:00
sam 0efd812387 fix(build): make formatting and CI converge (#901) 2026-09-20 00:38:51 +10:00
sam 4b51722440 fix(build): pin gofumpt and golangci-lint as one matched pair
`task fmt` formats with the standalone gofumpt and `task lint` re-checks that
formatting with the gofumpt golangci-lint vendors. `task check` runs `fmt`
then `lint` without diffing the tree, so `lint` is the only hard failure for
formatting -- and when the two versions differ, any construct they disagree on
makes the gate unsatisfiable: the standalone formatter rewrites a file one way
and lint rejects it, with nothing a contributor can run to satisfy both.

The surfaces had drifted onto three different pairs. This machine ran gofumpt
v0.7.0 against golangci-lint 2.13.2 (vendors v0.11.0), the image pinned
golangci-lint 2.12.2 (vendors v0.9.2) next to gofumpt v0.11.0, and CI
installed gofumpt@latest. `any((Trees)(nil))` in changes_test.go is the
construct that surfaced it: gofumpt <= v0.9.2 keeps the redundant parens,
>= v0.10.0 removes them.

- Dockerfile: golangci-lint 2.13.2, whose vendored gofumpt v0.11.0 now equals
  the pinned GOFUMPT_VERSION, so the image's two formatters agree.
- Dockerfile: fail the build if the pins ever diverge, rather than ship an
  image whose gate cannot pass.
- deploy.yml: gofumpt@v0.11.0 instead of @latest, which drifts ahead of
  whatever golangci-lint vendors.
- Record the invariant where an agent will meet it: AGENTS.md (CLAUDE.md) and
  the build-and-env skill, whose snapshots now name the pinned pair instead of
  calling both unpinned.
2026-09-19 18:52:10 +10:00
sam 3773856c70 feat(workintake): authorize review reactions by owned PR 2026-09-19 10:46:18 +10:00
sam 8c71df24e2 docs: correct the withdrawn State Store topology and the authority revision
Two of the three findings from review. The third had already been fixed by the
version of the service-registry PRD that landed on main.

1. docs/prds/state-store-contract.md §10 still prescribed the topology that was
   deleted when the State Store was extracted. It said an empty `Target` opens a
   local `*store.Store` adapter, and that the daemon's base path is that local
   store "already opened by openProductionTaskStore". Neither holds: the
   standalone archie-state-store process exclusively owns archie.db, and both
   archied and archie-gateway reject an empty target (bootstrap.go,
   state_store_client.go: "services.state.target is required").
   openProductionTaskStore still exists, but only inside that standalone process.
   Following the ratified section would have reinstated the deleted in-process
   ownership path. The config.example.toml bullet (which still advised adding the
   section with a COMMENTED target -- impossible to boot) and the "opposite
   default (local, not remote)" blockquote are corrected with it; the section is
   already present with the target uncommented and marked REQUIRED.

2. CLAUDE.md named the State Store authority rev. 2c while the contract itself is
   ratified at rev. 2d. AGENTS.md is a symlink to CLAUDE.md, so one edit covers
   both guides.

Not changed: the typo-visibility finding is already addressed by the PRD on main.
Its tracking name, unregisteredServiceKeys, is unimplemented in Go, so the runtime
diagnostic is still missing -- filed as archie-core-jp4g.
2026-09-19 03:07:38 +10:00
sam 52aa774afc feat(build): gate generated contract data in task check
Closes #855 (archie-core-5gzx).

The check mode added in the preceding commit had no caller, so it prevented nothing: a
stale contracts.json still passed every gate. This wires it in and makes
drift fail the build.

- `task docs:generate` writes the committed artifact.
- `task docs:check` verifies it, non-destructively.
- `task check` runs `docs:check`, right after `proto:check`, so both
  generated-artifact surfaces are judged the same way in the same place.

The check cannot be satisfied by rewriting: it generates into a temporary
directory, so a failing gate leaves the artifact exactly as it found it and
the author applies the regenerated bytes. That keeps the regenerated diff
reviewable in the same commit as the code change that caused it, which is
what Step 9 of the architecture document requires and what a CI auto-update
would quietly bypass.

Documents that called this gap open are updated rather than left to
contradict the code:

- `generated-documentation.md` Step 8 (no `docs:*` task exists -> both exist),
  Step 9 (drift is gated locally, not in CI), and the hook/CI policy (rule 3
  is now enforced by the gate; rules 1, 2, and 4 still rely on the author,
  since nothing observes a commit).
- `contract-conformance-audit.md` gap 1, now closed.
- `config-example-drift.md` item 3, which asked for exactly this wiring.
- `CLAUDE.md`, whose `task check` description listed neither `docs:check`
  nor `test:tools`.
- The build, docs, and diagnostics skills, plus a re-baselined diagnostics
  snapshot: the `task_docs` delivery surface went 0 -> 6 and the `tools`
  module 4 -> 7 now that the tasks exist.

Verified with `task check` (green), including the new `docs:check` step.
2026-09-18 12:46:40 +10:00
sam 853aef4eee chore(docs): correct the required Go version to 1.27.0
go.mod requires go 1.27.0; the guidance file still said 1.26.5.
2026-09-14 23:38:15 +10:00
sam fdf73243a0 docs(architecture): promote the shipped review stage, reconcile CLAUDE.md
Closes archie-core-h019.7. Three parts:

- Promote docs/prds/adversarial-self-review.md into
  docs/architecture/adversarial-review.md, describing the stage as shipped
  (subagent executor, .git-free snapshot, ReviewReport contract, fail-closed
  park, models.reviewer budget, operator-triggered review_pr) and mark the PRD
  as promoted.
- Add the review stage to ARCHITECTURE.md's task lifecycle.
- Reconcile CLAUDE.md's Development Protocol: distinguish the contributor's
  opt-in manual pass from archied's automatic pre-PR review.

Note: the h019.7 text said the review diverts to waiting_human, but the
shipped stage (h019.1/h019.4) parks to StatusParked, not waiting_human. This
change documents the shipped behaviour (parked), not the stale wording.
2026-09-10 01:31:50 +10:00
sam 242e51b3e1 feat(staterpc): carry the dashboard's configuration snapshot
archie-core-ymut decided the configuration page reads a projection the daemon
publishes rather than reaching into a shared config.Holder. This is the
carrier: a single-row store surface plus PutConfigSnapshot/GetConfigSnapshot,
taking the contract to 42 RPCs.

The document is opaque here. Its shape belongs to the daemon that builds it
and the page that renders it, so the store neither parses nor validates it,
and schema names the projection so a reader can refuse one it does not
understand. It is secret-free where it is built: the projection carries an API
key's environment variable name and whether it resolved, never a value.

Both RPCs are administrative. authorizesTaskScopedCall is deny-by-default, so
a container's task-scoped grant can neither rewrite what an operator reads nor
read a projection of the deployment it runs inside; a test pins both.

Nothing publishes or reads it yet -- the daemon's publisher and the UI's
read path land with the rest of the cutover.
2026-09-09 23:35:41 +10:00
sam fc18892324 docs(agents): list every step task check actually runs
The gate also runs proto:lint, proto:check and lint (Taskfile.yml:187-200);
the summary line omitted all three. A session that reads this line and
assembles go vet + go build + go test + gofumpt as an equivalent stand-in
misses golangci-lint entirely, which is how main last went red.
2026-09-09 00:26:54 +10:00
sam 89c1c53ed6 docs(agents): correct AGENTS.md's State Store section for the standalone process + task-grant reality
The in-process-multiplexed-server and daemon.StateStoreTokens bullets
described the pre-.4.6 design; neither boot.startStateStoreServer nor
daemon.StateStoreTokens exist in the codebase anymore. Replaced with
what's actually true: the standalone archie-state-store process,
staterpc.GrantIssuer/TaskGrants task-scoped credentials, and
archie-agent's single (no longer dual-path) gRPC Store.

Surfaced while reconciling beads .4.2-.4.6 against main -- all five
verified against the code and closed as genuinely done.
2026-09-07 17:34:16 +10:00
sam 576e22b554 feat(state-store): generalize storerpc as the State Store gRPC contract (archie-core-8cda.4.2) (#770)
* feat(state-store): generalize storerpc as the State Store gRPC contract

Implements archie-core-8cda.4.2 against docs/prds/state-store-contract.md
rev. 2c: generate protobuf/gRPC client and server adapters for every
ratified store contract (proto/state/v1/state.proto, 40 RPCs, one
StateStoreService), add internal/infrastructure/staterpc with a bufconn
conformance suite exercising both local and remote adapters, serve the
service in-process (bridge address + mandatory per-task bearer token when
agent containers exist, loopback-only otherwise), and flip archie-agent's
workflow.Store to a long-lived gRPC client when the daemon injects
STATE_STORE_URL/STATE_STORE_TOKEN (falling back to the legacy NATS
storerpc path otherwise -- one agent process is never both).

Also drops the *sql.Tx parameter from store.BindingDispatcher.RecordDispatch
(a required wire-blocker fix: a transaction cannot cross a gRPC boundary,
and production always passed nil).

fix(store): drop RecordDispatch's unusable *sql.Tx parameter
feat(config): add services.state contract-adapter selector

* fix(state-store): apply no-mistakes review decisions

- Drop StreamTokenInterceptor (unused; the State Store service has no
  streaming RPCs and nothing calls it).
- Make StateStoreTokens.Validate compare tokens in constant time
  (crypto/subtle) per the auto-fix hardening.ing finding.
- Amend config.example.toml / config.Services.State doc text so it frames
  [services.state].target as the ratified surface consumed by the upcoming
  standalone archie-state-store binary (.4.3), not active today.
2026-09-07 03:01:33 +10:00
sam 6affe0eea3 chore(curator): add embedding client and sampler interface prerequisites (#752)
* feat(curator): add embedding client and sampler wave-1 prerequisites

Bead archie-core-1786637500752-415-434e5bb9 (GitHub #436) was closed with
no linked PR/commits, and the surprisal-sampling bead
archie-core-1786637500776-416-600a66e5 (GitHub #437) found none of its
stated prerequisites -- an embedding client, a Sampler interface, or the
four wave-1 cheap sampling strategies -- actually exist. This builds them:

- internal/domain/embedding + internal/infrastructure/embedding: a narrow
  typed embedding client, config-driven via a providers table + a role in
  [models], mirroring the existing chat model role convention. Degrades to
  capability-unavailable (never fails startup or a call) for a missing
  role, unknown provider, unsupported class, or unresolved credential.
  Wired as an optional capability in bootstrap.go's setupEmbeddings.
- internal/domain/sampling: the Sampler interface plus recency, random,
  all, and staleness-proxy strategies, per docs/prds/curator-sampler-wave1.md.
  Deterministic given fixed inputs, matching GitHub #437's stated
  acceptance criterion for the embedding-backed strategy it will add
  behind this same interface (not part of this change).

Table-driven tests throughout; httptest for the embedding client, no live
service. No curator wiring yet -- nothing consumes either capability in
this change.

* no-mistakes(document): docs(architecture): mark curator sampling prereqs as landed
2026-09-05 22:53:08 +10:00
sam 659e914cf1 chore(beads): stop tracking issues.jsonl/interactions.jsonl in git
Dolt is the source of truth and already syncs via its own git+ remote
(bd dolt push/pull). Committing the JSONL export separately produced a
steady stream of no-op "chore(beads)" commits that skewed commit counts
without adding information. Untrack the export files, disable
export.auto/git-add, and drop the beads-commit step from CLAUDE.md's
Session Completion Protocol.
2026-09-05 20:37:45 +10:00
sam d640b6b915 docs: reconcile plugins-and-extensions.md and ARCHITECTURE.md with shipped webhook intake
ARCHITECTURE.md described forge intake as polling-only and listed Gitea
as still "planned" despite internal/forge/gitea.go fully implementing
it -- both stale since 7d5u.4/.2/.3 shipped forge webhook intake.
Corrected the opening description, package map, Provenance-by-origin
paragraph, [forge] config bullet, and Implemented/Planned lists; added
a "Webhook intake" subsection documenting internal/forge/webhook as a
separate HTTP receiver reusing the poller's TaskEnvelope/PublishTask
path.

CLAUDE.md gains the internal/forge/webhook/ trap: HMAC verification
must precede payload parsing, and the webhook-built TaskEnvelope must
keep its poll-compatible owner/repo/number idempotency key or
poll/webhook double-dispatch returns.

plugins-and-extensions.md gains a section cross-referencing 7d5u.1's
decision (in-process typed families, no amendment needed) and naming
the Module action position as the shipped instance -- Channel/Forge
positions are correctly left as open investigation (t2db.19), not
claimed as shipped.

Closes archie-core-7d5u.6.
2026-09-03 06:48:02 +10:00
sam 6cedc0213e docs: drop the standing adversarial-review pass from the dev protocol
Sticking with red-green TDD plus task check as the gate for now,
rather than a fresh-context reviewer pass on every change by default.
Adversarial review stays available, just opt-in per request.
2026-09-02 21:40:57 +10:00
sam 3129422a79 fix(plugin): add missing CLAUDE.md reference to plugin engine rule
Test TestPluginEngineRuleIsCanonicalAndSharedByAgentInstructions was
missing entirely, letting CLAUDE.md drift out of sync with
ARCHITECTURE.md#plugin-engine-rule-strict. Added the test and the
missing reference.
2026-08-31 21:25:20 +10:00
sam 7e819d85ef chore: fix CLAUDE.md to flow and remove contradictions. 2026-08-28 23:06:17 +10:00
sam 972fb5b8e1 feat(deployment): default to managed NATS workers
Autonomous workflows now always hand a complete task to a scoped archie-agent container. Embedded NATS is the default and external NATS changes only broker placement; legacy agent and containers.enabled inputs decode for migration but cannot select an execution path. The daemon flushes task-event subscriptions before a worker can publish, and runtime updates snapshot and restore the configured worker image.
2026-08-24 14:56:57 +10:00
sam 5d00ec7b0c refactor(agentexec): remove legacy execution paths
Autonomous workflows now have exactly one production boundary: a task-scoped archie-agent receives a full-task core-NATS request and runs the worker-local stage loop. The legacy [agent] section remains decode-only for migration; it no longer selects runtime behavior.
2026-08-24 14:56:57 +10:00
sam e736910ab3 docs: add RELEASING.md, stop asking whether to skip an untouched component
Every release session asked the same question and got the same
answer: archie-agent has no unreleased changes touching its own
package closure, so skip it. Codify the rule instead of asking each
time -- only version a component with actual unreleased commits in
its closure, don't bundle an unrelated backlog into an unrelated
release just because it's "due", and don't ask when the answer is
mechanically decided by tools/release.sh's own dependency check.

CLAUDE.md's Release process section pointed to duplicated instructions;
replaced with a pointer to RELEASING.md so there's one source of truth.
2026-08-23 23:40:45 +10:00
sam 212f04a86b docs: remove commit-permission gating from CLAUDE.md, keep push gated
Every "do not commit without asking" line (the repository-hygiene bullet
and the Beads-managed Conservative/Minimal/Team-maintainer profile split)
required stopping mid-task for approval on finished, gate-clean work --
friction with no benefit on a solo project. Pushing and Dolt remote sync
still require explicit ask; only the commit gate is removed.
2026-08-22 19:23:16 +10:00
sam f4438843fe docs: let scope discipline permit design where none is settled (#533)
The Scope discipline section used to open by declaring the architecture
documentation "complete and authoritative ... not a draft to extend", and
then banned producing "new architecture documents, migration plans ...
decision records" outright.

That was already false in this tree. docs/architecture/migration-decisions.md
is titled "Active migration inventory" and exists to record "what remains to
be decided before Archie's current implementation can be migrated into the
approved domain-oriented structure". The Architecture section of this same
file points agents at it for "the recorded position and what was agreed next".
docs/prds/ holds an active PRD and docs/archive/prds/ shows PRDs are a normal
artifact here. So the rule asserted the design was finished while the repo
shipped an open decision register, and banned the exact artifact type that
register is made of.

What changed in MEANING: the gate used to be "is this a document" and is now
"is there a settled design for this". Where a settled design exists, nothing
changes -- implement it, and prose instead of a diff is still the failure.
Where none exists (new capability, or an open item in migration-decisions.md)
designing first is now REQUIRED rather than prohibited.

The old ban was a proxy. What it meant to stop was prose substituting for a
diff, and it stopped that by banning the artifact instead of the behaviour.
Proxy rules hold right up until the work is genuinely new -- which is when
this one broke, and when designing first matters most: accreting diffs toward
a new architecture without deciding its shape is how the flat internal/ layout
happened, and CLAUDE.md already says undoing that is measured in weeks.

The anti-sprawl teeth are kept and made checkable rather than categorical: one
page, it decides rather than surveys, it lands in a named home (docs/prds/ or
migration-decisions.md), it is unfinished until a diff follows, and anything a
reader could have learned from the code gets cut. Ownership ledgers,
inventories, current-state traces, review campaigns and planning/refactor
issues stay prohibited -- none of those were ever design.

AGENTS.md is a symlink to this file, so every harness picks this up.
2026-08-21 22:20:48 +10:00
sam 6c9d446742 docs: add Beads tracker guidance to CLAUDE.md 2026-08-15 14:12:08 +10:00
sam 45345cdfb6 refactor(agent): move worker runtime into application layer
cmd/archie-agent used to own worker construction, NATS lifecycle, task execution, MCP setup, and workflow wiring. It now owns process input only and invokes internal/app/agentworker, while transport-specific NATS, boot-brief, and git-safety mechanics live under infrastructure.
2026-08-15 00:43:12 +10:00
sam f544dd0978 feat(config): SIGHUP-triggered reload with requires-restart warnings
The daemon can now re-read its configuration on SIGHUP (or on a
future in-process trigger) and republish it through the Holder,
closing the first half of issue #348: 'config can change at runtime,
safely, and can't brick the daemon.'

Reload path:
- cmd/archied/reload.go: ReloadController re-runs loader.Resolve on
  the same paths main.go passed at startup (Resolve is pure -- no
  reload state added to the loader). apply is called only with a
  Document that passed validation; a failed reload records the error
  and its timestamp and leaves the running config untouched. That
  Set-not-called-on-error property is the safety core and is pinned
  by TestReloadValidationFailureDoesNotApply.
- SIGHUP listener in main.go runs reloadLoop(ctx, ch, controller, log);
  the loop is extracted as a testable seam (syscall.SIGHUP is Unix-only,
  fine given the Linux target).

PollInterval is genuinely reloadable now, not just re-read:
the three ticker sites (Run, per-identity goroutine, shared
maintenance loop) re-read the interval each tick and Reset the ticker
on change. A reloaded poll_interval takes effect on the next cycle.

Diff-and-warn so an operator never has to read the source to know
whether an edit took effect: changedNonReloadableFields compares the
old and new snapshots against an allowlist of re-read fields
(PollInterval, Repos, DiffCapLines, Budgets, Dispatch, and the
Containers sub-fields VolumeTTL + MaxConcurrency). Anything else that
changed logs Warn 'requires a restart'; a fully-applied reload logs
Info. The allowlist is deliberate: a field added to Config later
defaults to requires-restart, the safe direction.

NATS split-brain closed: containerEnv now hands containers the
endpoint the daemon's own client connected with at startup
(Daemon.ConnectedNATS, captured at construction) instead of the live
config, so a reloaded nats.url cannot point new containers at a
server the daemon is not publishing on. A nats change is therefore
classified requires-restart, and CLAUDE.md's 'hands its own nats.url
verbatim' note is updated to the meaning it now has (same today,
deliberately different after a reload).

Validation guard: poll_interval <= 0 is rejected in validate.go
beside the VolumeTTL guard. applyDefaults fills zero with 60s, so
this fires on an explicit negative -- which would panic
time.NewTicker/Reset at boot and, after the per-iteration reset,
on a SIGHUP mid-run.

Observability: config.ReloadStatus (last_error, last_error_at,
last_reload_at) is recorded by the controller and surfaced in
/api/config via Server.LastReload, so a stale running config is
visible in the dashboard, not just the logs. Rendering waits for the
UI step.

Recovery hatch: --no-config-overlay flag plus ARCHIE_SKIP_CONFIG_OVERLAY=1
(configuration.SkipOverlay), logged at startup. No overlay source
exists yet; the flag is the documented escape hatch the DB overlay
(step 3 of #348) will consult.

webui.Server.ConfigProvenance becomes atomic.Pointer so a reload can
swap it via SetProvenance independently of Cfg; the accepted skew
(new config alongside old provenance) is documented on the field.

Verified: task check clean; -race on daemon, webui, cmd/archied,
config, infrastructure/configuration.
2026-08-10 00:19:46 +10:00
sam 61b4b7b0cf refactor(store): replace legacy persistence with SQLite
Task and event persistence now uses a dedicated SQLite sidecar derived from the configured state prefix, matching the independently persisted conversation store. The configured path now means a state-path prefix rather than a database file so fresh SQLite state never attempts to interpret the previous storage format.

Remove the retired implementation and dependency completely, strengthen SQLite migrations and concurrency behavior, restore backend-neutral coverage, and align configuration, operational guidance, UI labels, and deployment documentation with the new storage and host-daemon topology.
2026-08-09 22:27:25 +10:00
sam 95f6a3fae7 docs: correct CLAUDE.md and ARCHITECTURE.md against the current tree
Both documents had drifted far enough to mislead a new session on its first
read. CLAUDE.md is symlinked as AGENTS.md, so its rules now name required
behaviour rather than one harness's command for it.

Corrections verified against the tree:

- internal/workflow moved to internal/domain/workflow; the single-test
  example pointed at a package that no longer exists
- there is no internal/nats package; the eventbus transport is
  internal/infrastructure/eventbus
- task check also runs test:ui, so the gate needs Node, and task fmt
  rewrites files rather than only verifying
- Gitea is implemented, not planned
- the nats.url passthrough is containerEnv, not a line number that moved
- ARCHITECTURE.md claimed every park comments on the forge issue; the code
  records park_reason on the task and requeue clears it
- the opening sentence described a single-forge, label-only daemon

Deployment no longer presents systemd as the model: deployments/ carries
five profiles and systemd is one runbook among them. The chat agent's file
tools are workspace-confined by default and unrestricted_filesystem is an
operator opt-in, which had been written as an architectural constraint.
Host-specific operator details are removed, along with a pointer to a
memory that never existed.

Adds what every session needs and nothing recorded: toolchain
prerequisites, Conventional Commits, and that ui/dist is committed so the
Go build never requires a Node toolchain.

Folds in seven traps recovered from the pre-migration tracker: the three
NATS behaviours, Telegram scope-specificity menus, the ai-sdk FullStream
deadlock, the chat prompt's tools-block invariant, the two lint-autofix
regression shapes, and commit-the-meaning.
2026-08-09 18:10:12 +10:00
sam 7c01532394 docs: update issue tracking to GitHub Issues 2026-08-09 01:28:57 +10:00
sam e10cbbc92c refactor: pre-cleanup. 2026-08-06 01:40:15 +10:00
sam 58f3d40683 docs: state the organisation rule as an enforceable invariant
The layering was written down in docs/architecture/organisation.md and
approved, but nothing an agent reads first pointed at it. Reading
internal/ cold shows ~35 packages side by side, so the obvious move is
to add a thirty-sixth -- which is how the flat layout kept regrowing,
and untangling it cost a week.

The section states the four layers and their ownership, names the
dependency direction as the invariant, and explains why the layers stay
under internal/: it is a compiler-enforced visibility boundary, so
hoisting one to the repository root would make Archie's domain types
importable by any dependent module and commit us to API stability on
exactly the code that most needs to keep changing.

Cross-cutting packages get a checkable definition rather than a vibe: a
package that may be imported by any layer and imports none of them.
logging, events, eventbus and taskstate each have zero inward imports
today, which is what lets them sit outside the dependency direction --
they are sinks, never sources. It doubles as the failure test: the
moment one imports a domain type it has become misfiled domain code.

Deliberately no shared/ directory. A directory named for a category
becomes where things go when nobody can say what they are.

Refs archie-core-5d7
2026-08-05 11:37:34 +10:00
sam 170fe0250b fix: close the duplicate-work loop and the dead paths around it
Applies the four-reviewer pass over the forge/dashboard-actions work.
The through-line is that several capabilities were wired but inert, and
one of them could cost real work.

DUPLICATE WORK. "Closes #N" was dropped from PR bodies in favour of
LinkBranch, which is sidebar linkage on Gitea and a no-op stub on
GitHub -- neither closes anything, and nothing else did either. So a
merged task left its issue open, labelled and assigned; the next poll
re-enqueued it, and once the dashboard's Clear removed the task row that
became a second implementation and a second PR for work already merged.
reconcilePRs now closes the issue on merge, and a rejected task closes
its issue too. A PR closed without merging deliberately leaves the issue
open: that usually means "try again".

MAX RETRIES. Configured, defaulted and reported by /api/config, and
enforced nowhere -- markDead was unreachable and EffectiveMaxRetries had
no callers, so the dashboard's retry incremented retry_count forever.
The retry action now retires a task to dead at the cap.

DEAD ON ARRIVAL. Tasks() never selected plan or source, so the
"Decision required" panel could not render and chat tasks -- whose issue
number is synthetic -- linked to forge issues that do not exist.

COSMETIC FAILURE, FATAL RESULT. OpenPR failed the whole stage when
LinkBranch errored, so the pull request was never opened and the task
parked; a retry re-links the same branch, which Gitea answers with a
conflict, so every retry parked again. It is best-effort now.

INVISIBLE ACTIONS. Approve/retry/reject wrote store rows and nothing
else, so the timeline and activity stream never showed that a human had
intervened. They emit events now.

Also: store write failures answer 500 rather than 409; the dashboard
surfaces the server's actual reason instead of "409 Conflict"; action
buttons stop propagation (acting on a task no longer also expands it),
disable in flight, keep per-task errors instead of one shared string,
and confirm before rejecting.

Removed: the maybeRetryParked shim and markDead with their now-vacuous
tests, WaitingTasks (no consumers; its tests were rewritten to assert
the same routing through TaskByID), write-only Daemon.Runtime, and
dir/dirs response bloat from /api/skills. skillSource checked workDir
before sharedDir, mislabelling every shared skill when the two are equal.
DefaultRoots now dedupes roots differing only by a trailing separator.

The air build rule claiming to keep ui/dist current never ran -- it
required one file to satisfy include_dir and include_file together, and
ui/ is excluded from the walk. Deleted with the comment that promised it.
task test:ui joins task check and CI; it ran nowhere before, so the
dashboard suite could rot silently.

Docs corrected where they described behaviour that no longer exists:
parks no longer comment on the issue, state labels no longer drive
retries, and forgerpc's doc claimed four proxied methods while listing
three of five.
2026-08-05 03:54:25 +10:00
sam a2b2dc9ef2 fix(tools): let an optional provider fail without taking the daemon down
provider.Registry.Start was atomic for every provider: one failure
unregistered every other provider including the builtins, returned an
error up through the capability host, and exited archied. Under
Restart=on-failure that is a crash loop. Observed on carina 2026-07-30 --
mcp.desktop-commander could not start because the runtime image was
missing unzip, and the daemon restarted continuously, losing chat, the
gateway and every builtin tool over one third-party npm package.

Atomicity is right for a provider archied requires. It is wrong for an
external MCP server pulled from a registry at runtime, which is exactly
the category allowed to be absent -- the same reasoning already applied
to the forge, and to containers.

RegisterOptional marks a provider the daemon can run without. Its
failure to start, discover or index stops only itself and excludes it;
Register keeps today's rollback. Required/optional is a deployment fact
rather than a property of the code, so the registrar states it instead
of the engine declaring it in its own manifest -- which also keeps
plugin.Manifest metadata-only, per the plugin engine rule.

A skipped provider's dependents cannot run either: an optional dependent
is skipped with the reason, a required one is a hard failure, since it
declared it cannot work without something now absent.

Degradation is reported, not silent -- Health goes degraded naming each
provider and cause, Skipped() exposes the set, and the daemon logs one
error line per exclusion. Silence is how this went unnoticed until the
crash loop. A provider that half-started before failing is still
stopped, so no child process is left behind.

The regression test drives the real capability host, the path main.go
calls: with desktop-commander registered as required it fails with the
verbatim carina error, and as optional the daemon starts with its
builtins intact.

Closes archie-core-ky6
2026-08-04 23:32:47 +10:00
sam 82b420520a chore: trim CLAUDE.md to what an agent actually needs
Three per-package traps (telegram polling, task.json path, MCP hard-fail).
Five deployment facts (host daemon, gateway NATS, pull_policy, agent
profile, config location). Release process. Dropped the history notes,
binary-extraction recipe, .dockerignore and GOTMPDIR bullets.
2026-07-31 02:11:03 +10:00