Commit Graph
155 Commits
Author SHA1 Message Date
sam 0064da1d2b feat(workintake): authorize review reactions by owned PR 2026-09-19 10:46:18 +10:00
sam 73f019ea9f 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 2385e81066 Merge pull request #878 from samcharles93/feat/attempt-attribution
Feat/attempt attribution
2026-09-19 02:48:25 +10:00
sam 987573443c fix(config): enforce the service context at registration
ServiceSpec.Context documented which addresses a service must end up with, but
nothing read it, so a typo'd context was accepted and meant nothing. Review
caught it as scaffolding that looked load-bearing.

RegisterService now validates it: an unknown context, or a hosted (server/both)
service registered with no default listen address, panics. Registrations come
from this repository's own init(), never from operator input, so an invalid one
is a programming error with no caller positioned to handle an error return, and
failing at process start beats a service binding where nobody dials.

Services.RequireTarget replaces the same check and message hand-written in
composeStateStoreClient and composeChatContract. An empty registered default
target is what declares a target operator-supplied, so the requirement belongs
to the registry rather than to each consumer. It stays a lazy check at
composition time rather than becoming load-time validation: a process that
never dials a service must still load a configuration that omits it.

The review's stated failure mode does not occur. A hosted service with an empty
listen does not reach net.Listen as an ephemeral port; resolveServiceListen
returns "no listen address" and archied refuses to start. The defect was the
inert field, not a silent bind.

Refs: archie-core-u23g
2026-09-19 01:50:25 +10:00
sam 37231d56bb docs(prds): pin review remediation identity to the resolved task 2026-09-19 01:48:53 +10:00
sam 280c97de7c docs(prds): ratify PR review remediation with amendments
Status moves to Decided. Six amendments, all found by measuring the draft
against the tree and against what PR #859 produced from it:

- Sequencing gains the reaction stream as step 1. The parent decision already
  requires ARCHIE_REACTIONS under LimitsPolicy and 7d5u.2 parameterised
  Retention for it, but no stream exists, so every publish to archie.reaction.*
  fails against no matching stream.
- The owned-task guard becomes its own step. The (owner, repo, pr_number)
  lookup it depends on does not exist: pr_number is written and never read in
  a WHERE clause, so it needs a store method, a StateStoreService RPC and an
  index.
- The producers move to the end. A producer built before its consumer and its
  guard publishes into nothing, and becomes an unguarded intake the moment a
  stream appears.
- Idempotency keys gain the reaction kind. Review IDs and review-comment IDs
  are independent forge sequences, so the bare id let the two collide.
- A review is the unit of remediation, never a comment. One review with eight
  inline comments would otherwise mean eight builder runs, eight gates and
  eight pushes to answer one review. Runs also serialise per task regardless
  of allow_concurrent.
- Only archie's own comments are excluded, not all bots'. The external review
  bot is the main source of findings on an archie-opened PR. Because that
  makes bot comments actionable, the exchange can run away between two bots
  with no human involved, so remediation rounds are capped by max_retries.

Withdraws the RepliesAfter citation: no such mechanism exists in the tree.
2026-09-19 01:11:01 +10:00
sam 678539e390 fix(workflow): require a workflow from triage when a code change is needed
The selection criteria alone left workflow optional and defaulted an omitted
or unrecognised value to implement, so a decide call could still skip the
decision and send an unsettled capability straight to the builder.

Omission is now a retryable rejection: CaptureTool gains RequiredWhenTrue, a
conditional requirement a flat RequiredFields entry cannot express, because
the close-without-change branch has no workflow to name and must not be made
to invent one. A rejected call is not recorded, so it does not consume
MaxCalls and the model retries with the field.

A value outside the enum now fails the stage rather than degrading to
implement: reaching OnResult with one means the model ignored its own schema.

Splits validateCaptureArgs into per-constraint checks (cyclop) and carries
the regenerated contracts.json.
2026-09-19 00:33:39 +10:00
sam da4547e27c feat(config): key services by name through a registry
Services was a struct with one field per service, so each service's name was
stated three times: the field, the loader's defaulting branch, and every
consumer's field access. Adding one meant editing all three, and nothing
stopped them disagreeing. The drift was already there: stateStoreResolvedToken
and gatewayResolvedToken were identical apart from the env var each hard-coded.

Services becomes map[string]ServiceConnection, and RegisterService declares a
service once with the five fields it has. Everything that differs between
services is now an argument rather than a branch elsewhere: an empty registered
target means the operator must supply one, which is how services.state.target
stays required while the gateway's is defaulted, and the registered token env
var replaces the two copied resolvers with Services.ResolvedToken.

Defaulting iterates the registry, so a new service needs no loader edit.
Consumers read Services.Get(name).

Keeping a typo'd section reported took explicit work. [services.gatway] used to
land in toml.MetaData.Undecoded() because the struct had no such field; a map
decodes any section, so it would have loaded silently and left the daemon
dialing the default. unregisteredServiceKeys asks the registry which names are
real, and the test for it fails with an empty UnknownKeys when that check is
removed.

The TOML shape is unchanged, so no deployment profile, config.example.toml or
install.sh edit is needed.

Refs: archie-core-u23g
2026-09-18 23:32:36 +10:00
sam e31d189f81 docs(prds): design the service registry and revise the state store contract
A service is already one Go type (config.ServiceConnection); what is duplicated
is its name, across the struct fields in internal/config/services.go, the
default branches in infrastructure/configuration/defaults.go, and every
consumer's field access. The drift that permits is already in the tree: the two
token resolvers are identical apart from their env var name, and gateway.Target
is defaulted while state.Target is a startup error with nothing stating that
asymmetry in one place.

Key services by name and carry the asymmetry as registration data, so a new
service is one RegisterService line rather than an edit in three layers. An
empty target default means the operator must supply one, which replaces the
required/defaulted split without a branch. The TOML shape is unchanged.

state-store-contract.md section 10 mandated the opposite, so it is revised to
rev. 2d in the same change rather than left contradicting the design; its own
summary already described the seam as [services.<name>].

Also records the open [chat.*] section naming question in the migration
decision register, where it is blocked on a decision rather than on evidence.
2026-09-18 23:23:35 +10:00
sam b09be5515d feat(config): let the State Store and Gateway listen addresses be configured
Both gRPC listeners took their bind address from a -listen flag default alone,
with no config key. The port a service binds and the port its clients dial were
therefore two separate facts -- the flag default, and [services.<name>].target --
with nothing keeping them in step.

On a host that already owned the default the effect read as a code fault rather
than a port collision: the store died with "bind: address already in use" while
every client reported "state store: connection error ... error reading server
preface: EOF". Cockpit binds 9090 by default, so this is not hypothetical.
Verifying the dashboard on such a host needed a hand-written overlay plus a
matching -listen, two things to keep in step by hand.

- [services.state].listen and [services.gateway].listen now name the bind
  address. Precedence is -listen, then config, then a default applied by the
  loader. An empty result is a startup ERROR, never a fallback: net.Listen reads
  "" as "any free port", so defaulting there would bind the service somewhere no
  client looks and still report success.
- Both flag defaults become "" so configuration can win, mirroring how archie-ui
  already prefers [web].listen over its flag.
- Gateway listen defaults to the same constant as the gateway target, so a
  default deployment's client and server cannot drift onto different ports.
  [services.state].target still has no default: an empty target stays a startup
  error in the daemon and gateway, which no longer serve a local store.
- ServiceConnection gains the field. Its doc now says clients read only Target
  and TargetToken, and Listen belongs to the process that owns the service --
  the previous wording claimed the struct starts no listeners while carrying one.
- deployments/dev.toml states each port once, beside the target it must match, so
  `task dev` is retargetable on a host that owns 9090 by editing one overlay.

Tests. Unit: config defaults, explicit values, and precedence. Process: the
existing real-process smoke test now takes its listen from configuration instead
of -listen, so the end-to-end wiring is proven by the test that already starts
the binary, with no extra process. Both were verified load-bearing by mutation --
inverting the precedence fails the unit test, and making the app layer ignore
config fails the process test with "state: no listen address".

Verified: task check exit 0. Also documented in config.example.toml, the
configuration architecture table, and the `task dev` summary.
2026-09-18 19:15:02 +10:00
sam 7414713d61 feat(webui): add the per-run task detail page
A per-task page at #/tasks/{id} with tabs for the attempt's stages and log, changed
files, configuration and a raw debug view. Reachable from the task list, deep
linkable via ?tab= and ?attempt=, and reload safe. Existing URLs (#/tasks?task=N
and #/tasks?status=...) are unchanged.

- A stage rail per attempt: name, duration, terminal status and error text, with
  unattributed events surfaced and the agent's own verdict shown separately.
- No pass/fail badge and no exit code anywhere: the backend has neither, and a stage
  that returned nil after producing a poor diff is a success. Status word, duration
  and error text are shown instead.
- The log pane filters by attempt, stage and level, states the coverage caveat for
  stage filters (agent and tool output records no stage), and keeps the three read
  outcomes distinct: no log reader in this deployment, no file for this attempt, and
  no entries matching the filter.
- Retry is labelled as a new run and its confirm says the previous attempt's commits
  are discarded, because it hard-resets the branch onto the base.
- An absent capture reads "not captured for this run" rather than implying nothing
  changed, and no elapsed-run figure is shown since only per-stage durations exist.
- The events cache is invalidated on retry (it previously kept the ended attempt's
  events) and the log cache is keyed by attempt, so two attempts cannot be conflated.
- ui/dist is rebuilt and committed: the gate runs the node tests but never rebuilds
  the bundle, so a stale one would otherwise ship behind a green gate.
- docs/prds/task-run-detail.md records the surface and its limits, and
  docs/architecture/observability.md describes it alongside the read endpoints.

Both new vocabularies are pinned by tests on each side (config schema, change
statuses) so a one-sided rename fails a test instead of silently degrading the page.
2026-09-18 18:33:03 +10:00
sam 40851baa90 docs(prds): design the code graph as an MCP surface
Supersedes symbol-reference-index.md, which scoped only the data layer and
left the interface unstated. Deleted rather than archived: it was written
today, never implemented, and keeping both would leave two documents claiming
authority over one capability.

Three things the narrower doc did not settle.

The interface is MCP. archied consumes MCP and serves none, so exposing the
graph that way reaches Claude Code, pi, codex and Archie's own agents through
one surface with no coupling to the daemon. Diagrams are deliberately not a
tool: a model handed an accurate subgraph writes its own Mermaid, and the
valuable half was never the rendering.

Every answer declares what it could not see. RTA over-approximates interface
dispatch and reflection is invisible, so the *extract yaegi tables make
symbols look reachable regardless. An agent trusting a confident wrong graph
is worse off than one that greps.

A code graph does not power a documentation chatbot. It answers structural
questions about Go symbols; answering "how do I configure a second identity"
means retrieving prose from markdown. I had previously implied one substrate
served both. It does not, and building it that way would serve neither well.
2026-09-18 13:42:33 +10:00
sam a533810546 docs(site): close the excluded-PRD link chain and reconcile the CI section
Two fixes to the published site, both about not shipping something false.

exclude_docs held back prds/ but let ui-service-boundary.md through, because
architecture/migration-decisions.md links to it three times. That PRD in turn
links to service-decomposition.md and config-schema.md, so the exclusion was
still producing two dead links on the published site. Letting those two
through closes the chain: the build now reports no excluded-link references
at all.

generated-documentation.md's "Step 9: CI" said no workflow builds, checks or
publishes documentation. Adding .github/workflows/docs.yml made the first
clause false. Restated to say what that workflow does and, more importantly,
what it deliberately does not: it does not run docsgen, regenerate
contracts.json, or publish. Generated-artifact drift is still gated locally by
task check, which is the split that section exists to protect, since a CI job
that regenerated output could paper over uncommitted differences rather than
fail on them.
2026-09-18 13:17:02 +10:00
sam dcaa98cc44 docs(site): make docs/ buildable as a documentation site
Adds an mkdocs.yml, a landing page, and `task docs:site` / `task docs:serve`.
Deliberately hosting-agnostic: MkDocs is the same input Backstage TechDocs
consumes, so choosing where this lands later costs nothing.

exclude_docs holds back four subtrees, since everything under docs/ would
otherwise be published. archive/ is superseded design and would compete with
the current architecture for a reader's attention; inspiration/ discusses
other products by name; prds/ are open decisions rather than settled design;
github-token.md is credential setup. One PRD is let back through because
architecture/migration-decisions.md links to it three times, and a page
excluded out from under a live link is just a 404 with extra steps.

No nav block. MkDocs derives it from the directory layout, so a new page
under docs/architecture/ publishes without a second edit, and there is no
hand-maintained tree to drift against the repository.

Builds --strict, so a dead internal link fails rather than ships.
2026-09-18 13:16:09 +10:00
sam 38c0e485bc chore(tools): make unreachable-code analysis runnable from the Taskfile
Add `task deadcode` (whole-program RTA from ./cmd/...) and `task reachaudit`
(the existing classifier on top of it). Neither joins `task check`: both
report a standing backlog, so gating on them fails every run until that
backlog is zero, same as `task vuln`.

`task deadcode` shells to `go run ...@latest` rather than a local binary on
purpose. A deadcode built against an older Go than this module exits non-zero
and prints nothing, which reads as "no dead code" instead of "analysis
failed" -- the locally installed copy was built against 1.26 against a 1.27
module and had been silently reporting an empty tree.

reachaudit had two traps that made it answer confidently from nothing:
its --repo default pointed at a path that does not exist on either machine,
and it reused /tmp/reachaudit-deadcode.txt with no staleness check, so it
would serve a previous tree's analysis indefinitely. Key the cache on HEAD
and refuse it outright when the tree is dirty.

Also lands the design for tools/symbolrefs, the type-resolved reference
index that covers what reachability cannot: RTA treats every address-taken
function as live, so every reflect.ValueOf entry in the *extract tables
launders a dead symbol into a reachable-looking one, and deadcode reports
functions only, leaving dead package vars unrepresentable.
2026-09-18 13:15:26 +10:00
sam 641c80f7d9 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 541bd0299d docs(skills): re-verify every .agents skill against the current tree
All ten `archie-*` skills carried claims that no longer matched the
checkout. Re-verified each against code, git history, and the shipped
configuration, then corrected the drift.

Structural changes the skills had not caught up with:

- Composition root moved: `cmd/archied/main.go` is a ~30-line dispatcher
  into `internal/app/archied.Run()` with wiring in `bootstrap.go`. The
  skills still described `cmd/archied` as the wiring site, which also
  silently zeroed the diagnostics delivery snapshot.
- Config decoding moved out of `internal/config` into
  `internal/infrastructure/configuration`. `config.Load` / `config.LoadDir`
  no longer exist; the loader is `configuration.New` + `Loader.Resolve`.
- Task contract moved to `internal/domain/storecontract`, with
  `internal/store/interface.go` holding aliases only. The task type is
  `internal/domain/workflow/task.Task`.
- `internal/workflow` became `internal/domain/workflow`; `internal/storerpc`
  became gRPC `internal/infrastructure/staterpc`; `internal/policy` does not
  exist.
- `Store.Transition` now guards on `from` and writes status plus history in
  one transaction. Three skills still described the old non-atomic behavior
  as current and open.
- `internal/domain/{messaging,workflow,workintake}`, `internal/eventbus`,
  `internal/app`, and `internal/infrastructure` now exist.
  `internal/domain/{agent,identity}` and `internal/policy` remain target-only.

Tooling and environment facts:

- Go 1.27.0 (root and tools modules), golangci-lint 2.13.2, staticcheck
  2026.2.1; snapshot dates and HEAD moved to 2026-09-18 / 0ee2d27e.
- Re-ran the bundled diagnostics and re-baselined its snapshot table.
  Confirmed 78.6% store coverage, a clean race run, and zero dupl findings.
- Corrected the claim that no `.dockerignore` exists; it does.
- Replaced skill script paths that pointed at the untracked `.claude/skills`
  symlink with the canonical tracked `.agents/skills` location.
- Fixed the delivery-snapshot comment's wrong commit hash for the Gitea
  workflow removal (dd9bddc2, not e539048).

Findings the verification closed:

- The VitePress site and `.github/workflows/docs.yml` were removed
  (de150f20); the Gitea workflow was dropped (dd9bddc2).
- The changelog `vX.Y.Z`-vs-`X.Y.Z` contradiction is settled, not open: both
  changelogs and the CI gate agree on `## [<version>]`.
- Tracked `docs/node_modules` and the skill-script test regression are
  settled, not current.
- The six unmerged `origin/fix/*` and `origin/feat/*` candidate branches no
  longer exist.

Also regenerates `docs/data/generated/contracts.json`, which the
verification found stale since a825db28: docsgen emits 11 schemas now, and
`MediaAttachment.raw` plus an `AgentExecutionResult.required` field were
missing. `cmp` passes after regeneration.

Verified with `task check` (green).
2026-09-18 12:37:51 +10:00
sam 0ee2d27ebc fix(workflow): record a parked run's reason in its own log
The agent-side half of the same gap. A stage failure already logged
"stage failed -- parking" before parking, but a run whose OUTCOME was parked
(a review that could not run, a workflow that ended with no outcome) reached
the timeline as a KindParked event and the store as park_reason and never
the log an operator downloads.

park is the one place a park's reason is final, so it is now the one place
that logs it; the stage-failure branch no longer logs its own near-copy, and
the stage names itself inside the reason. The entry carries the stage as a
field so nothing is lost by dropping the duplicate line.

observability.md's "Implemented design" section documented the container's
system-log path as though it were the only source of task-log content; it
now records the daemon's and the workflow's own park writers, including why
the entry follows the transition rather than preceding it.
2026-09-18 01:49:56 +10:00
sam 3cb3cf7e62 feat(ui): download a task attempt's log, and stop blaming a setting for it
The attempt-log panel offered no way to get a log out of the dashboard, and
its failure copy asserted that task logging was not enabled for the run. The
first is the feature: the panel now links to the download route for the attempt
it is showing, so the browser owns the filename the server sets and streams the
body to disk rather than the client holding a whole log in memory.

The second is the honesty fix. "No log recorded for this attempt" is a fact
about the attempt; "this dashboard cannot read task logs" is a fact about the
deployment, and only the second is worth sending an operator to a setting for.
The panel renders them differently off the response's found/disabled markers.

Rebuilds ui/dist, which is a committed asset.
2026-09-17 12:12:47 +00:00
sam 676fd92574 docs(prds): land the memory engine unification decision
Approved for implementation, dated 2026-09-16, previously untracked.
Settles four open items in docs/architecture/migration-decisions.md#5 and
supersedes the memory-turn-context.md draft.

Section 8's deletion list no longer names config.Memory.SessionTTL: the
council carried that deletion standalone and af3a8a2 removed the field,
so listing it here would schedule work already done. Provider and
ProviderConfig are unchanged, both still present.
2026-09-17 00:34:01 +10:00
sam af3a8a2a61 refactor(config): delete the two decoded-but-unread policy fields
MemoryConfig.SessionTTL and ToolPolicy.ParallelExecution were decoded by
config loading and read nowhere, so setting either silently did nothing.
Removing them routes both keys into the unknown-key detector, which names
them in a boot warning instead. A live-looking knob wired to nothing is
the worse state, and the sibling memory.provider already earned a loud
load-time rejection for exactly this.

Also drops the config.example.toml line that shipped session_ttl into
every first-run config.toml via configtemplate.go, and the commented-out
dir_test.go assertions that would have re-created both fields under that
file's "make these pass without modifying them" header.
2026-09-17 00:32:02 +10:00
sam 07e39144e2 docs(architecture): record the NATS scaffolds as deliberate deferrals
servicediscovery/nats and gatewayrpc.StoreClient are implemented and fully
tested, but neither has a production caller and no config surface exposes
either. Both were previously unrecorded, which made them indistinguishable
from oversight. The register now names them: StoreClient under the session
migration that will consume it, service discovery under shared mechanics,
alongside the runtime boundary that pins container addressing by injected NATS
URL instead. Kept rather than deleted because re-deriving tested wire code
later is pure cost.
2026-09-15 16:54:12 +10:00
sam 639cd7f8b7 docs(architecture): record the embeddings client as deliberately inert
setupEmbeddings constructs a client at boot and holds it on b.embeddings, but
no production code reads that field yet, so a resolved models.embedding role
currently produces a client whose only observable effect is a boot log line.
The document already notes that no curator consumes a Sampler yet; it now says
the same of the embeddings client, so the inert state is stated rather than
implied. Both are prerequisites waiting on #437, not unwired defects.
2026-09-15 16:54:12 +10:00
sam 6fd76ae550 fix(tools): stop testing on the text of other files, and ungate contractaudit
Six tests asserted on the wording and formatting of source and config files
rather than on behaviour: four injected text into fixtures and checked that a
regex noticed, and two asserted on api.jsx's contents. They break on an extra
space, a newline, a rename, or a comment that merely mentions the token -- the
single-fetch check had already false-positived on a comment, and I patched it
with a comment-stripper instead of deleting it. A test that cannot tell "the
code is wrong" from "the file is formatted differently" tests the wrong thing,
and the maintenance cost is permanent.

Deleted: tools/contractaudit/negative_test.go in full, and the source-scanning
"api.jsx holds exactly one fetch call" check with its stripComments helper. The
dashboard suite still asserts the browser mutation contract behaviourally, per
method, by inspecting the request each one makes -- which is where the real
defect was found. 142 UI tests pass; the 45 methods remain fully covered by the
two inventories and the completeness check.

The tool's own decoding is now testable without a file: parseDeclarations takes
an io.Reader, so its rules are exercised with in-memory input, and only the
absent-file branch still touches a path (which is never created).

contractaudit is no longer part of task check. Its surfaces are discovered by
scanning source text, so a rename or reformat elsewhere can change its output
with nothing actually wrong -- it reported 16 live routes as unconsumed once,
when the dashboard's request helper was renamed. A check that can fail for
reasons unrelated to what it measures must not be able to break a build. It now
matches tools/reachaudit: advisory, run by hand, --strict available on request.

Also removes five unused indirect requires from tools/go.mod (go mod tidy).
They were residue from the reflection-based first implementation of the RPC
scan, which was replaced by text scanning without tidying. -mod=readonly cannot
catch a superfluous require, so nothing would ever have found them.

Rewrites docs/prds/contract-conformance-audit.md, which claimed RPC coverage was
derived by reflection over the exported client type -- it never was -- listed
surface sizes of 43/12/52 against real counts of 45/21/49, described three
classification classes where the code has four, invented a five-surface Shape
with files that were never written, and blamed raw fetch calls for a 401 defect
that did not exist. Each false claim is now recorded in an errata section rather
than quietly dropped, and the document states plainly that the audit has found
nothing actionable: the 415 refusals and the duplicated client plumbing were
both found by reading the handler and reproducing the request.

Testing rule added to the document, since this is the second time: assert on the
observable effect, never on the content or formatting of generated or
hand-authored text and config files.
2026-09-15 14:17:53 +10:00
sam dacec700a6 fix(tools): stop contractaudit crediting dead paths as live consumers
Renaming the dashboard's request helper from req( to request( broke the
consumer extractor: it matched the call by name, so 16 live routes were
reported unconsumed. The extractor now keys on the call argument instead,
which survives a rename.

The first attempt at that fix was worse than the bug, and is recorded here
because the direction of the error is the whole point. Crediting any quoted
/api/... literal meant a comment, a retired-route array, or a display label
counted as proof a route was reachable -- so deleting every real request
still reported the surface as healthy. A false "unconsumed" is a loud,
fixable failure; a false "consumed" is a silent hole in the gate, which is
worse than having no gate at all.

A path now counts as a consumer only when it is the first argument of a call
in code. That excludes bare constants, dead arrays, object properties, and
commented-out calls, while still accepting any function name. Both halves are
pinned by tests: TestScanFileCreditsAnyCallSignature and
TestScanFileIgnoresNonCallLiterals, plus a surface-level
TestNegativeCommentedOutCallIsStillReported that the vacuous version fails.
Re-injecting either half of the bug fails the suite.

Requiring a call lost no real consumer: internal/webui still reads 49/49.
The remaining limits (path must be the first argument; template
interpolations unseen; routes credited per path rather than per verb) are
declared in docs/contract-declarations.json and the PRD rather than left
implicit.

Also corrects a measurement I had quoted inconsistently: proto/state/v1
declares 45 RPCs, not 43 or 46.
2026-09-15 13:49:47 +10:00
sam 778d33f89c refactor(tools): delete unreachable dispatch/gating engine
DispatchSequential, DispatchConcurrent, ClassifyEntry and their
supporting types (dispatch.go) have zero non-test callers; the live
tool path is agentexec/toolset.go's BuildToolSetFrom. Removes the
dead engine and its tests, and updates the PRD status table that
referenced it (tools-core-1).
2026-09-15 10:19:39 +10:00
sam 1957d0ab39 feat(tools): add contractaudit for standing contract-conformance reporting
Reachability (tools/reachaudit, epic archie-core-06ag) answers "is this code
in a shipped binary?". It cannot answer the complementary question: "does
every declared contract surface have a consumer, or a declaration that it
has none?". ratelimit was in the binary closure and called by nothing, which
reachability could not see.

tools/contractaudit classifies each subject of each declared surface as
CONSUMED, DECLARED-UNCONSUMED, UNDECLARED-UNCONSUMED, or STALE-DECLARATION,
and only the last two are findings. The declaration allowlist must match
reality exactly: a missing entry fails and so does an entry that outlived
its subject, because a stale allowlist is how a gate quietly stops checking
anything.

Surfaces: the two gRPC services, whose consumption is derived by scanning
adapter bodies for calls through the generated client, and the dashboard
HTTP API, matched between the registerXRoutes call sites and the path
literals the bundled client calls.

Findings on the current tree, all deliberate and now declared:
ListCaptures and ListUndispatchedCaptures are superseded by their streaming
variants -- staterpc's client calls StreamCaptures -- so no production
client reaches the unary RPCs.

Three bugs this tool found in itself, each recorded because each is the
class of error that makes a conformance check worse than none:

- Joining RPCs to adapter methods by name silently reported live RPCs as
  unconsumed, because adapters do not map one-to-one: StoreClient.Get calls
  GetSession, List calls ListSessions.
- Reflecting over the client value rather than the pointer reported zero
  methods, hence the whole surface unconsumed.
- Treating the asset mount and the health probes as dashboard API routes
  reported four healthy routes as undeclared; they have different consumers
  and are out of scope for this surface.

The consumer extractor fails loudly on a call shape it cannot parse rather
than under-reporting, and every check is negative-tested: a route, an RPC,
and a removed consumer are each injected, confirmed to fail for the right
reason, and reverted. The declaration staleness rule is tested too.

Advisory when run directly; task check runs it -strict. See
docs/prds/contract-conformance-audit.md.
2026-09-15 09:41:20 +10:00
sam c9970bb5de docs(prds): decide example-config drift is gated, not generated
Records why config.example.toml and deployments/*.toml should not be generated:
the example documents 137 keys (active and commented) and its hand-written
comments are the file's purpose, TOML round-tripping does not preserve them, and
docs/prds/config-schema.md forbids building on config.Config because that struct
is scheduled for dissolution. generated-documentation.md:225 additionally
prohibits adding a hardcoded type list to docsgen. The deployment profiles are
curated complete-configs setting 3-46 keys, not projections of the example.

What the check did find is worth more: decodeTOML
(internal/infrastructure/configuration/decode.go:27) discards the TOML metadata,
so unknown config keys are silently ignored -- a misspelled key parses,
validates, and does nothing. That is fixed by reporting Undecoded() across every
target a file feeds, as a warning rather than a fatal error, because
configuration.md's settled startup policy is that a missing credential degrades
and only an invalid config stops the daemon.

Also withdraws a premise this session used: a measurement claiming 17 keys were
set by a profile but documented nowhere was an artifact of an extractor that
stripped comment markers. providers.<name>.api_key_env is a real documented
field (internal/config/config.go:180) and [[identities]] is documented. The
decision does not rest on it, and the withdrawal is recorded in the document so
the premise is not reused.

Filed with it: config-5 (unknown keys ignored, P1) and docs-and-tools-1
(generated-documentation.md documents a four-subcommand docsgen that
tools/docsgen/main.go does not implement, including the `check` mode the same
document names as the remedy for its own admitted "drift is ungated" gap).
2026-09-15 02:52:24 +10:00
sam 8301a949ee Merge pull request #827 from samcharles93/fix/webui-config-projection-chat-setup
fix(webui): count every chat front-end in the published projection
2026-09-15 00:26:55 +10:00
sam b894951e62 Merge pull request #826 from samcharles93/feat/deep-research-design
docs(research): design a deep-research fan-out capability
2026-09-15 00:26:51 +10:00
sam 73aa86181e fix(webui): count every chat front-end in the published projection
GitHub #821 reported two dashboard behaviours degrading in the extracted UI
process because webui.Server.Cfg is nil there. Half of it was already closed:
03afd2e ("take configuration off the dashboard server", on main since
2026-09-12) moved the daemon's ConfigView renderer off webui.Server, gave
ConfigView a chat section carrying show_tool_calls, the operator name and a
channel flag, and pointed chatShowToolCalls and handleSetup at the projection.
The chat page and the checklist do read published values now.

The channel flag was still wrong. It was derived from telegram and the webhook
gateway only, while the daemon's own channel status manager lists three
front-ends and counts the inbound mail gateway as one. An email-only
deployment therefore read as configured on /api/channels and unconfigured on
the setup checklist at the same time, and the checklist told the operator to
connect a channel they already had.

Fix at the producer: config.ChatConfig gains FrontEnds, the single definition
of "this front-end is configured", enumerating telegram, email and the webhook
gateway. Both the published projection (ChannelConfigured) and the daemon's
channel descriptors (status.NewManager) now derive from it, so the two surfaces
cannot drift apart again. A front-end added to [chat] is counted by both or
neither. Whitespace-only values are not configured: an env var name of " "
resolves to nothing and " " cannot be listened on.

The setup checklist stays. It renders each step as a title, a detail and a done
mark with no control behind it, so it answers "what is this deployment
missing?" rather than promising to fix it; the process that cannot apply setup
never offered to. Removing it would delete the one surface that distinguishes a
fresh deployment from a finished one, and the values it reads already cross the
boundary in ConfigView at no cost to the daemon. The write path stays descoped
for Phase 3 (docs/prds/ui-service-boundary.md, /api/config (write) row): the
checklist reports configuration, it does not change it.

docs/prds/ui-service-boundary.md records that judgement and corrects the
"Real-process evidence" paragraph, which claimed the channel flag covered every
chat channel.
2026-09-14 10:53:16 +00:00
sam 87d8d39321 fix(webui): publish per-identity forges so multi-identity task rows keep their links
Task rows in a deployment configuring [[identities]] rendered no forge links.
ConfigView carried the default identity's forge alone, so resolveForge
(api_tasks.go) withheld the links entirely rather than pointing every row at
the wrong forge -- production behaviour since the UI process cutover
(archie-core-8cda.5.4), where the dashboard runs in a process with no
config.Holder. archie-core-ml30 then removed webui.forgeConfigForTask and its
test, which resolved a task's forge from config.Config and had no reachable
caller once the holder was gone.

Fix at the producer, not the renderer. ConfigView gains `identities`: each
configured identity's forge type and host, plus the repositories it owns. That
is the whole answer to "which forge owns this task", and it is a projection the
daemon already rebuilds and republishes on boot and on every reload, so nothing
new is needed on the publish side. Only coordinates and repository names cross
-- an identity's token is a secret reference and stays out, which the new test
asserts alongside the existing leak guard.

resolveForge ports the matching rules recovered from 5b91a3a's
forgeConfigForTask onto that projection: an exact identity name first, then
repository ownership, and an ambiguous repository -- two identities claiming the
same owner/name -- falling back to the default forge rather than inventing a
link. Two deliberate departures from the recovered shape: it indexes the
identity list once per request instead of rescanning config per task, since the
projection supplies repo slices it can key on directly; and a document that
reports multi-identity but carries no per-identity forges still withholds,
because that is what an older daemon published and guessing there is the
original bug. The recovered code's first-wins scan for a duplicated identity
name is preserved.

Tests: the projection's per-identity forges and their secret-freedom; the three
matching rules and both fallbacks through resolveForge; every row of a
multi-identity GET /api/tasks carrying the right forge's link; and the real
archie-ui binary driven over HTTP against a multi-identity projection, which
fails on the pre-fix resolver with three unlinked rows.
2026-09-14 10:36:29 +00:00
sam d7304e3897 docs(research): design a deep-research fan-out capability
Records the design for an orchestrator that spawns 1..N subagents to
research in parallel, collates their findings, and returns one cited
report grounded in web search and web fetch.

Grounds every claim against the tree: web search has no implementation,
fan-out has no owner (agentloop runs one mission; the only nested loop
is the PR reviewer's Subagent), and no operator-push delivery path
exists. Maps the six stages, the three candidate shapes, and the six
decisions -- most importantly that citations are rendered from a source
store rather than model prose, since the disclosed failure modes and an
EMNLP 2026 error localisation both put the majority of final-report
errors at the orchestrator.

Adds a deterministic cross-check and a separate citation pass, neither
of which appears in any surveyed implementation.
2026-09-14 10:29:08 +00:00
sam 9e73e9190a docs(curator): correct forge-tools dependency; record chat shell reach 2026-09-13 14:27:08 +10:00
sam d91ff8affa docs(curator): settle dynamically-defined curator definitions as data 2026-09-12 13:36:13 +00:00
sam de150f2068 chore(docs): remove the VitePress site and its build step
The docs site was never published: GitHub Pages is not configured for this
repository, so the workflow built and uploaded a site nobody served. docs/ is
repository documentation — Markdown read in the repository, an editor, or the
forge's file view — and does not need a renderer.

Removed:

- docs/.vitepress/config.mts, docs/package.json, docs/pnpm-lock.yaml (1620
  lines), docs/pnpm-workspace.yaml
- docs/index.md (the site's landing page)
- .github/workflows/docs.yml (pnpm install, VitePress build, Pages deploy)
- the docs build-artefact ignores from .gitignore

Kept and corrected:

- docs/prds/01-project-management.md linked its decision documents with
  VitePress root-absolute paths (/architecture/...), which only resolve under a
  site build. Repointed to repository-relative paths.
- docs/architecture/generated-documentation.md named VitePress as the renderer
  throughout. Now records the renderer and publishing surface as an open
  decision, with the consequences stated: reference pages unrendered, no link
  checker, no authoring server. Also corrected three claims that were never
  true — the docsgen all/check subcommands and the docs:* tasks do not exist,
  and no pre-commit hook is installed.
- .agents skills: build-and-env and docs-and-writing no longer describe a docs
  site to build; the diagnostics scripts drop .vitepress skip rules and the
  dead github_docs_build scan.

Generated output is unchanged: docs/data/generated/contracts.json and the
docsgen toolchain are untouched, and tools/ remains its own module.
2026-09-12 01:01:12 +10:00
sam 03afd2e8ad refactor(webui): take configuration off the dashboard server
webui.Server declared Cfg *config.Holder with eight read sites, none of
which ran in the UI process: composition leaves it nil there. The field
survived because the daemon kept a webui.Server it never served, using it
to render the published ConfigView snapshot and to hold the readiness
probes (archie-core-ml30).

Split at the producer. LocalConfigView becomes webui.BuildConfigView, a
pure function over a ConfigViewInput the configuration owner assembles;
the DTO and its schema stay where the UI renders them. The daemon builds
that input from its own state (boot.configViewInput) and publishes the
result. Readiness reads the daemon's Holder, channel manager and chat
contract, and the registry it produces is a daemon field, not a field on
a server with no listener. Boot now owns one Holder instead of seeding a
second and replacing it in buildDaemon; operator retry caps read it too,
so they follow a reload rather than a boot-time snapshot.

Server loses Cfg, ConfigProvenance, LastReload, ConfigOverrides and
SetProvenance. The nil-guarded branches they fed went with them, each
checked first against what the UI process actually serves:

- chat.show_tool_calls and the /api/setup checklist were degraded, not
  dead. ConfigView gains a chat section carrying show_tool_calls, the
  operator name and whether a channel is configured, and both surfaces
  read the projection. The end-to-end suite asserts the checklist renders
  from the published snapshot.
- /api/logs takes its path as a process-local option. The history is on
  the daemon's disk, so a dashboard elsewhere cannot read it by learning
  the path; that route still needs a contract.
- handleChannels drops its config-derived fallback, superseded by the
  status manager, which already carries the descriptions and detail.
- trustForwardedHeaders keeps only the process's own setting, which the
  UI process already sets.
- resolveForge keeps the published-projection path it already had.

ConfigView.Editable moves to handleConfig, decided by whether this
process holds UpdateConfig. It describes the writer, not the document, so
the write contract (archie-core-j28m) makes the page editable by wiring
one field. The write handlers and their seams stay for it.

overlay.Store gains Keys: Snapshot nests dotted keys for decoding, so the
overridden-key list was publishing section names ("budgets") where the
dashboard marks and resets rows by stored key ("budgets.max_steps").

Multi-identity forge links move to archie-core-pv6t: forgeConfigForTask
resolved a task's forge from config.Config, had no reachable caller once
the holder was gone, and belongs in the projection rather than the
rendering package.
2026-09-11 23:57:38 +10:00
sam b7fa45e76d docs(decomposition): reconcile the UI coupling record with the closed phase
The audit this PRD-class doc carried (archie-core-6pg1) was superseded by the
ratified UI boundary and the shipped phase, but the doc still read as though
UI extraction were pending: the open-questions heading called itself blocking
before implementation, the coupling inventory said UI extraction "must remove"
the config.Holder alias, and Q3 still described the State Store as defaulting
local with a not-yet-extracted caveat (Phase 2 deleted every local fallback
and made an empty target a startup error).

State what is true: three phases shipped, the third coupling is closed, the
remaining holder alias is daemon-internal (archie-core-ml30) rather than a
cross-service coupling, and the open questions are historical record.
2026-09-11 23:31:08 +10:00
sam 5b91a3aeb4 docs(ui): record Phase 3 complete and name the amended criterion
Phase 3 (archie-core-8cda.5, UI Service extraction) is closed. The doc
claimed the boundary was ratified but not yet satisfied; it now records the
outcome with the evidence per gate: the deletion gate re-runs on every
check, the composition test pins no holder / no concrete store / gRPC-only
Gateway, the real-process smoke drives the binary over HTTP against live
dependencies, and the dashboard listener exists only in archieui -- the
daemon's two http.Servers are its own health endpoint and the webhook
receiver, so there is no dual UI authority.

Acceptance criterion 1 is amended to name the UI process rather than the
internal/webui package: the process receives no config.Holder, while the
daemon keeps one inside its own process to render the published ConfigView
snapshot. That residue is daemon-internal, tracked by archie-core-ml30, and
does not cross a service boundary.
2026-09-11 23:21:29 +10:00
sam 1837cc9335 docs: name the prd inline-review to match the feature term 2026-09-11 22:43:34 +10:00
sam 99883d7461 docs: add inline review comments prd 2026-09-11 22:43:34 +10:00
sam 5dd596d51f Merge pull request #787 from samcharles93/feat/review-calibration
feat(workflow): review calibration -- checked properties, style nits out of contract
2026-09-11 04:23:16 -07:00
sam bdf73ed371 feat(workflow): review calibration -- checked properties, style nits out of contract
Closes archie-core-h019.5. The shipped contract already made only a confirmed
error-level finding block, and kept zero-findings distinct from not-run; what
was missing was the other half of calibration, and that is what a reviewer that
cries wolf needs.

- ReviewReport gains Checked []ReviewCheck {Property, Evidence}: the properties
  the reviewer verified clean. Evidence is required, for the same reason a
  finding requires a failure scenario -- a check without evidence is an
  assertion, not a verification.
- The reviewer records checks through a typed record_checked tool, mirroring
  record_finding, so it cannot end its turn having silently skipped the
  checklist.
- Style/formatting/naming nits are stated out of contract, in the ReviewFinding
  type doc and the reviewer prompt: they are the padding that trains an
  operator to skim.
- The PR-body findings section renders the cleared properties, so a
  zero-finding review arrives backed by what was checked rather than reading
  the same as a review that never looked.

Design: docs/prds/review-calibration.md.
2026-09-11 20:18:06 +10:00
sam 50845430e3 test(ui): smoke the archie-ui process against live dependencies
The in-process suite proved the composition; nothing proved the process.
This builds the real binary, points it at a State Store and a Gateway on
loopback gRPC through an operator-shaped config.toml, and drives it over
HTTP: the token exchange and its 401s, the embedded SPA, a chat stream
relayed frame by frame, an operator task action crossing to the Gateway
and refused without the CSRF header, unauthenticated capture intake, the
ratified degradations, readiness dropping when a dependency dies while
liveness holds, and a clean SIGTERM.

It found one regression, fixed here at the producer. Task rows lost their
forge links in the extracted process: taskURLs read config.Holder, which
is nil once the dashboard stops sharing the daemon's process, so every
click-through to the issue and the PR silently disappeared. The forge is
now resolved once per request from whichever source that process owns,
the daemon's configuration or the daemon's published projection.

A multi-identity deployment keeps no links rather than gaining wrong ones:
the projection carries the default identity alone, so it now says so and
the renderer withholds.
2026-09-11 20:10:59 +10:00
sam 51234eaed4 test(ui): enforce the UI process deletion gate on every check
The severance that cut archie-ui's package closure from 68 to 26 was a
one-time measurement: nothing re-ran go list -deps, so the next import of
a type sitting beside a runtime would have relinked that runtime silently
and left the suite green.

TestUIProcessLinksNoDaemonRuntime re-measures the closure and fails on any
package in a banned category, with the categories named as the PRD names
them. Its two exceptions are checked in both directions so the allowlist
cannot decay into an open prefix. database/sql is matched exactly rather
than as a subtree: database/sql/driver arrives from google/uuid's
Valuer/Scanner and brings no driver with it.

Verified by violation: one blank import of internal/store relights eleven
banned packages across three categories.
2026-09-11 20:00:41 +10:00
sam a00c578cb7 refactor(ui): sever the archie-ui binary from every daemon runtime package
Completes the objective deletion gate for the UI Service
(archie-core-8cda.5.6): go list -deps ./cmd/archie-ui now links zero
banned packages -- no modernc.org/sqlite, no internal/store, gateway,
channels, memory, secret, agentexec, tools, skill, yaegiutil, curator,
or the workflow engine. The closure shrinks from 68 to 26 archie-core
packages. Each cut is a producer-side move; no consumer-side defensive
shims.

- Store contracts (TaskStore family, value types, sentinels) moved from
  internal/store to internal/domain/storecontract -- the approved contract
  location per state-store-contract rev. 2d, and NOT internal/contracts:
  that tree is buf generate output and tools/proto.sh check deletes
  hand-written files there. internal/store keeps aliases; sentinel
  message strings are byte-identical and remain the wire contract.
- Chat contracts (ChatContract, sessions, turns, streaming, commands)
  moved from internal/gateway to internal/domain/messaging; gateway keeps
  aliases. ToolCallEvent rendering helpers become gateway functions
  (methods cannot live on alias types).
- Task vocabulary (Task, statuses, mid-run Store, Definition) split into
  internal/domain/workflow/task; the pipeline engine stays in package
  workflow with aliases, so daemon-side callers are unchanged.
- overlay.DeniedKeys moved to internal/infrastructure/configuration:
  webui referenced the constant and that dragged the overlay SQLite
  store in.
- webui.Server's concrete runtime handles become webui-owned view
  interfaces with daemon-side bootstrap adapters: channel lifecycle
  (internal/channels/status), MemoryStatus, CuratorStatus, and a
  SkillCatalog seam replacing the direct skill.DefaultRoots/CatalogRoots
  calls. Each degrades to an empty page when unwired.
- config.SecretRef moved into internal/config (config vocabulary);
  internal/secret keeps an alias and Registry.Resolve absorbs the
  zero-value short-circuit.

Docs: state-store-contract rev. 2d relocation record; ui-service-boundary
deletion gate marked satisfied; ARCHITECTURE.md package map rows.
2026-09-10 03:03:33 +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 ad1e6ea0d3 feat(gateway): operator-triggered PR review with selectable reviewer model
Add a channel-neutral review_pr command that runs the adversarial reviewer
against an existing pull request and returns structured findings. The Web UI
chat and Telegram invoke the same command; the reviewer model is models.reviewer
(falling back to models.builder), configurable independently of planner/builder.

- forge: PullRequest + PullRequestReader.GetPullRequest (github, gitea)
- worktree: Manager.CheckoutPR materialises a PR head for Diff/Snapshot
- agentworker: NewOperatorReviewer + ReviewerModel (single model-resolution rule)
- gateway: review_pr tool, ChatPRReviewer, wired into TurnRunner for every channel
- archied: prReviewer adapter with identity-scoped repo allow-list and
  per-PR single-flight, so duplicate/concurrent reviews are deterministic

Closes archie-core-h019.8.
2026-09-10 01:09:31 +10:00
sam 2025e5f1ac docs: record the UI cutover and the archie-ui deployment story
- ui-service-boundary.md: the /api/captures|/mappings|/bindings row is
  resolved by the cutover; archie-ui composes the store contracts and
  mounts the captureintake receiver.
- event-capture-storage.md HTTP surface: the receiver mounts on the one
  process serving the dashboard; work intake stays with the daemon.
- config.example.toml: [web].listen is the archie-ui process's bind
  address; [capture] is projected by archie-ui.
- deployments: document running archie-ui alongside the other services
  and add its systemd unit; capabilities comments updated for the
  single-serving composition.
2026-09-10 01:03:40 +10:00
sam e404471602 docs: add pr review remediation prd 2026-09-10 00:33:49 +10:00