Commit Graph
107 Commits
Author SHA1 Message Date
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 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 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 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
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 d6fc2b3f1e docs(architecture): make the dashboard configuration page read-only for Phase 3
archie-core-ymut. The ratified boundary assumed one narrow admin contract
carrying both the configuration read and the write. It splits.

Read: webui.ConfigView is already a UI-owned, secret-free value projection
(ProviderView carries the API key's env var name and a Configured bool, never
a value; RepoView is metadata only) and is already the exact shape the browser
receives. The daemon publishes it, plus provenance, reload status and the
overridden-key list, as a snapshot the UI reads over two new State Store RPCs.
Nothing is designed, only moved.

Rejected a config admin service on archied. That would make the daemon a gRPC
server for the first time: grpc.NewServer appears only in RunGateway and
RunStateStore, which are the standalone binaries' entry points, not the
daemon's, so it costs a new listener, port, token and interceptor.

Write: PATCH /api/config, POST /api/config/reset and the repo-field route
answer 503 in the UI process, and the SPA hides the controls. This is a
deliberate feature reduction. The update policy is daemon-local
(installUpdateConfigHandler denies non-runtime-tunable keys, applies a dotted
overlay to a clone, validates the materialised config, writes overlay rows and
rebuilds provenance); contracting it verbatim would build a Configuration
Service inside a migration bead. Revisit with archie-core-1786637498420-327,
where it is a feature rather than migration residue.

Implementation is assigned to archie-core-8cda.5.4, the cutover that removes
the daemon's dashboard. Nothing is built here.
2026-09-09 03:00:56 +10:00
sam eafb58e1c0 feat(webui): deliver live dashboard events by polling the State Store cursor
archie-core-za9f. The UI process owns no event bus, so after the .5.4 cutover
the activity feed would show history at page load and then go silent: live
delivery is a Server.Broadcast call made only from the daemon's bus
subscription.

Decided against the push-subscription RPC the bead assumed, on three findings:

* store.Open sets SetMaxOpenConns(1), so writes serialise and the event id is
  assigned in commit order. The gap-skipping failure that normally rules out
  polling an autoincrement cursor cannot happen here, and SSE catch-up already
  depends on the same property.
* sseStream.drain treats a broadcast as a wakeup, not a payload: it fills the
  persisted gap via catchUp and delivers the event only if catch-up missed it,
  deduplicating on the since watermark. A poller substitutes for the bus with
  no change to sse.go and no new SSE semantics.
* The events table is the only complete fan-out point. ArchiveTask writes an
  audit event inside its transaction and daemon.go inserts binding-dispatch
  failures directly, neither touching the bus. A push hub needs a hook at every
  write site and misses any added later.

So: no proto change, no new auth surface, no backpressure policy. The pump
primes past existing history (a client's own catch-up serves that), then ticks
EventsSince into Broadcast. One pump serves every browser. A failed fetch
leaves the watermark intact, so a State Store restart costs latency, not
events.

Wired into archieui.Run in the background so priming a large events table
cannot delay the listener, with -event-poll-interval (default 1s).

Decision recorded in migration-decisions.md; ui-service-boundary.md's /events
route-owner row moves to RESOLVED, and /api/logs splits out of it as still
unresolved and host-local.
2026-09-09 02:53:32 +10:00
sam 63a54e0850 docs(architecture): ratify UI service boundary 2026-09-07 18:29:42 +10:00
sam a9814e0910 test(state-store): restart/recovery + single-owner-SQLite checks, document task-grant scoping (archie-core-8cda.4.7)
Works through .4.7's remaining acceptance items:

- TestStateStoreDataSurvivesRestart: a task written by one
  archie-state-store process is still there for a fresh process opened
  against the same archie.db path.
- TestOpenStoresNeverOwnsTaskDB: the daemon/gateway composition path
  never populates b.st -- that field is reserved for the standalone
  binary, so archie.db always has exactly one owner.
- Audited internal/webui and friends for direct internal/store use:
  only the narrow contract interfaces (TaskStore, CaptureStore, ...)
  are imported, never a concrete *store.Store -- already satisfied,
  no code change needed.
- Updated docs/prds/state-store-contract.md's token lifecycle and
  payload-limits sections to describe what's actually implemented now
  (RegisterTaskGrant/RevokeTaskGrant, per-RPC scoping, the streaming
  capture RPCs) instead of the pre-.4.3 in-process-listener language.
- Ran the affected packages under -race; clean.

Left open, for Sam to decide rather than assume: archie-state-store has
no Dockerfile/CI build and isn't in RELEASING.md's two-component split
(tools/release.sh only tracks cmd/archied and cmd/archie-agent). Given
it's currently a native-binary/systemd deployment (deployments/*.toml),
this may be intentional -- flagging rather than inventing release
infra for a third binary unasked.
2026-09-07 16:45:30 +10:00
sam 5c0efaceaf refactor(workflow): relocate Task/Status/Source and define workflow.Store (#754)
* refactor(workflow,store): relocate Task/Status/Source and define workflow.Store

Move store.Task, store.Status*/store.Source*, and the 3-method workflow
store interface out of internal/store into internal/domain/workflow as
workflow.Task/workflow.Status/workflow.Source plus a consumer-owned
workflow.Store, superseding store.WorkflowStore. internal/domain/workflow
now imports zero internal/store symbols; internal/store persists the
domain type instead (infrastructure depends on domain), and its Store
satisfies workflow.Store.

Updates every production and test caller of the relocated symbols across
daemon, webui, gateway, agentworker, agenttransport/nats, storerpc,
taskrun, and worktreerpc, and removes TestRecordDispatchViaExplicitTx per
docs/prds/state-store-contract.md (rev. 2c) sections 4 and 12 step 2.

Two workflow-package integration tests that exercise the real *store.Store
move to an external workflow_test package (store_integration_test.go) to
avoid a workflow(test)->store->workflow(prod) import cycle now that store
depends on workflow.

* no-mistakes(document): docs(state-store): mark §4.8 relocation done in state-store-contract
2026-09-07 00:39:26 +10:00
sam 3b85e67cb7 docs(state-store): bump internal revision labels to rev. 2c
Update the editorial revision labels so agents reading the handoff don't think
they are on an older revision: the date and the section annotations in
docs/prds/state-store-contract.md (contract-ownership fork, transitional
internal/store, error-detail sanitisation, transport boundary, token lifecycle,
fail-closed) that describe decisions retained through rev. 2c now read
(rev. 2c), and the service-decomposition PRD's ratification pointer reads
(rev. 2c). The revision-history sentence describing what rev. 2 resolved is
kept as narrative.
2026-09-07 00:04:04 +10:00
sam 29e4ccf6eb docs(state-store): rev.2c resolves third-pass contradictions
Address the third-pass review of the State Store ratification doc:

- service-decomposition.md Q3 generic migration wording no longer contradicts
  the ratified design: the compile-time assertion example is now
  var _ workflow.Store = (*Client)(nil) (store.WorkflowStore is superseded),
  and composition selection is described as presence-based
  [services.<name>].target (empty=local, set=dial remote) instead of the dropped
  mode = "inproc" | "remote" enum. Defaults differ per service (State Store local,
  gateway remote-on-localhost). Points to state-store-contract.md section 10.
- State Store listener topology is now a single explicit rule: one in-process
  listener, bound to the host-gateway bridge address with mandatory bearer-token
  auth when agent containers consume it (the Phase 2 default), or loopback-only
  for a daemon-local-only consumer. Removed the contradictory
  "default loopback-only" wording (a container cannot reach the host's
  127.0.0.1) and the dual-listener ambiguity across sections 6, 9, and 13.
2026-09-07 00:01:38 +10:00
sam ee42cebd97 docs(state-store): rev.2b resolves second-pass review inconsistencies
Address the second-pass review of the State Store ratification doc (beads archie-core-8cda.4.1):

- State migration-decisions.md section 4 remains authoritative and open; this PRD
  does not replace it. The Task/Status/Source + interface relocation is flagged as
  a minimal, pulled-forward Phase 2 prerequisite only.
- Fix stale WorkflowStore reference in service-decomposition.md Q4: the workflow
  contract is the domain-owned workflow.Store, which supersedes internal/store's
  WorkflowStore.
- Label internal/store as a TRANSITIONAL compatibility location (target
  internal/infrastructure/store), matching dependencies-and-contracts.md.
- Call out the current-state outliers explicitly: workflow files/tests still import
  internal/store, store.WorkflowStore is still in TaskContext, and the NATS storerpc
  path is still wired -- the acceptance criterion is NOT yet met.
- Operationalize the agent gRPC handoff: who binds the in-process State Store
  listener (daemon, mirroring serveGateway), Docker-bridge host-gateway address
  selection (reuses the embedded-NATS container/network.go resolution), per-task
  injection via containerEnv beside NATS_URL, per-incumbence bearer token lifecycle
  + gRPC-interceptor validation -> codes.Unauthenticated, and fail-closed on
  non-loopback targets without TLS/token.
- Update beads archie-core-8cda.4.2/.4.5 descriptions to match the ratified scope
  (type/interface relocation, RecordDispatch *sql.Tx drop, in-process serving,
  agent gRPC handoff).
2026-09-06 23:58:17 +10:00
sam 2fe9577b0b docs(state-store): rev.2 resolves reviewer conditions on State Store contract
Address the review of the Phase 2 ratification doc (beads archie-core-8cda.4.1):

1. Domain-dependency contradiction: ownership splits by consumer layer. The
   workflow domain owns a consumer-owned workflow.Store interface plus the
   Task/Status/Source types (dependency rules #2/#7), so internal/domain/workflow
   imports no internal/store — satisfying the Phase 2 acceptance criterion. The
   daemon/webui store surfaces stay producer-owned in internal/store. The type +
   interface relocation is a Phase 2 prerequisite pulled from migration-decisions
   section 4 (store.Task -> WorkflowExecution).
2. Agent gRPC endpoint propagation: explicit boot handoff via STATE_STORE_URL /
   STATE_STORE_TOKEN (mirrors the NATS handoff), added to agentworker.Settings and
   the Transport.Store facade; per-call timeout + long-lived grpc client.
3. Transport security + error sanitisation: loopback-only + insecure default, agent
   authenticates over the container bridge with a per-task bearer token; TLS/mTLS
   is an operator choice for non-loopback/k8s. Sanitised public error details in
   gRPC; full detail logged server-side only.

Also records RecordDispatch dropping *sql.Tx as a required interface migration
before .4.2. Cross-references updated in the service-decomposition PRD.
2026-09-06 23:45:19 +10:00
sam bcde4ae69a docs(state-store): ratify Phase 2 State Store contract boundary and transport
Define the authoritative Phase 2 State Store contract boundary and
transport design (beads archie-core-8cda.4.1): one StateStore gRPC
service (40 RPCs) behind the narrow typed store contracts, producer-owned
in internal/store, with a staterpc.Client remote adapter that satisfies
the same interfaces via explicit compile-time assertions. Records method
ownership, DTO/wire representation, error semantics (structured gRPC codes
rehydrated to store sentinels so errors.Is survives), limits, mode/config
shape (presence-based [services.state].target, default local), local-
adapter compatibility, and cutover/deletion rules. Fixes the RecordDispatch
wire blocker (*sql.Tx dropped; production passes nil) and keeps Close()
off the wire. References the new doc from the service-decomposition PRD.
2026-09-06 23:36:52 +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 14c9facfe7 docs(prds): record filed service-decomposition beads epic (#720)
Beads epic archie-core-8cda (with 8 phased child issues per the
resolved extraction order) has been filed for the service-decomposition
work; the PRD's completion-criteria "file a beads epic" line now points
to it. Filing the epic does not authorize implementation -- the PRD's
completion criteria still require the captain's separate explicit
go-ahead.
2026-09-05 17:05:31 +10:00
Samuel Catlow 0e4cc46c8e feat(gateway): wire progressive tool disclosure (bridge tools)
Compose the base registry with per-turn extras into a turn-local registry and
let ContextPressureGate decide full-vs-bridge disclosure per chat turn. The
three bridge tools (tool_search, tool_describe, tool_call) are now wired into
the chat toolset and only disclosed under context pressure, keeping the LLM's
schema footprint small while preserving full arsenal access on demand.

Per-turn extras are identity-bound per channel and cannot live in the
process-wide registry (agentexec.BuildToolSetFrom invariant), so the bridge is
composed turn-locally rather than registered globally. Thread the model's
context window through TurnModel.Prepare (TurnPrepareContext) so the gate
activates with a real window.

Refs #167
2026-09-05 16:02:53 +10:00
sam a3f82753fc docs(prds): resolve execution-time gap 2 -- idempotency keying for playbook actions (#715)
Decision for channel/forge/module action keying in eda-playbook-engine.md:
one durable dedup record per (action, event) pair via a playbook_dispatches
ledger in internal/store, reusing binding_dispatches' INSERT OR IGNORE +
sentinel conventions, with record-before-invoke ordering (at-most-once, the
reverse of the binding loop's ordering, justified by the external-side-effect
harm profile). Key = (playbook_id, playbook_version, event_id, action_id):
event_id is the TaskEnvelope.IdempotencyKey() value already carried on
DispatchInput.TaskID; the key is a fixed structural composition, deliberately
not a CEL expression (event stays dyn; determinism under redelivery is the
binding constraint). Redelivery of a recorded action skips it and continues
the run at debug level, never surfaced as an error. Rows live as long as the
playbook exists, no time-based expiry.

Extends event-sources-and-reactions.md's contract without contradicting it:
PublishUnique's dedup is publish-path only (Nats-Msg-Id + 2-minute
DedupWindow), so consumer redelivery of side-effecting reactions was never
covered; the ledger adds exactly that consumer-side piece, reusing the
TaskEnvelope identity and the typed-family shape. The gap-2 prerequisites
(Playbook ID/Version, DispatchInput.TaskID) already landed in 1e736ef.
Documentation only: no code changes. Keying implementation is separate
follow-up work.

Refs: archie-core-t2db.17
2026-09-05 10:11:59 +10:00
sam ec9607a086 docs(prds): resolve execution-time gap 1 mid-playbook action failure semantics (#714)
Resolves archie-core-t2db.18. States stop-on-first-failure as the
committed default when a playbook action fails mid-run, grounded in
workflow.Run's three-way stage-failure distinction
(internal/domain/workflow/workflow.go:294, 317-336) and the t2db.9-12
load-collision drop-and-report rule (eda-playbook-engine.md:155-159),
with explicit reasoning why the default does not violate
event-sources-and-reactions.md's producer-only rule. Gap 2 (execution-time
idempotency) remains open. Documentation only; no code changes.
2026-09-05 10:03:23 +10:00
sam 1df7145b76 docs(prds): resolve service-decomposition open questions #2 and #3 (#713)
Land Q2 (contract definition mechanism: buf v2 + grpc-go, committed
proto/ tree, buf breaking gate) and Q3 (in-process-by-default
migration mechanism per organisation.md's Process boundaries rule) as
committed file edits, matching the style of already-resolved #1/#4/#5.
Transcribes decisions from a prior scout pass whose edits were
discarded when its worktree was torn down; codebase facts (go.mod,
organisation.md, servicediscovery.go, storerpc.go,
sessionstore_conformance_test.go, api_chat.go) re-verified in this
worktree before writing.
2026-09-05 09:10:05 +10:00
sam b84c0e1a17 docs: resolve service-decomposition open questions #1, #4, #5 2026-09-05 03:04:46 +10:00