Commit Graph
154 Commits
Author SHA1 Message Date
sam 93418801e9 feat(docs): publish generated news and per-version release notes
Derive a public news page and one release-notes page per component version
from CHANGELOG.archied.md and CHANGELOG.archie.md, the notes the release
process already freezes.

- tools/newsgen writes docs/news/releases.json, the canonical artifact a host
  renders from, plus the MkDocs pages. Check mode fails when the committed
  files lag a changelog edit, and runs in task check; tools/release.sh --tag
  regenerates and stages them in the release commit, skipping files already
  current.
- mkdocs.yml keeps the version pages out of the derived navigation without
  excluding them from the site.
2026-09-22 05:03:29 +10:00
sam a092e2198e test(eda): pin playbook dispatch ledger docs and regression gaps 2026-09-22 04:51:17 +10:00
sam c9765d9afd fix(eda): wire playbook dispatch ledger and validate its key 2026-09-22 04:36:28 +10:00
sam 207b071917 fix(archied): build the Gateway's worktree manager so it serves review_pr
boot.prReviewer returns nil without a worktree manager, and a nil reviewer
omits review_pr from every channel's tool set. RunGateway never called
buildTreesAndIdentities, so the Gateway resolved a nil reviewer and no
channel could review a PR.

Extract the manager's construction into boot.buildWorktreeManager, called
by buildTreesAndIdentities (daemon, unchanged field-for-field) and by
startGatewayRuntime before setupGatewayChat. The Gateway does not call
buildTreesAndIdentities: that also registers daemon identity runners the
Gateway must not own, and PR review only needs a clone of the PR head,
which worktree.Manager.CheckoutPR does from the forge.

Pin the ordering by source position in composition_order_test.go, alongside
the memory-engine ordering the same function already carries, and pin both
compositions behaviourally in worktree_manager_composition_test.go: the
Gateway's step must yield a reviewer that advertises review_pr, and the
daemon must still build its root manager plus one runner per identity with
a distinct WorkDir.

Correct docs/prds/operator-pr-review.md, which still asserted the daemon
supplies ChatPRReviewer and holds the review in-flight set.
2026-09-22 03:44:45 +10:00
sam 5f267ac686 docs(prds): correct the PR review PRD's stale owner and file list
Section 1 attributed the PullRequestReader type-assertion to the daemon while
section 4 now correctly says the Gateway serves review_pr, and the Files list
cited internal/app/archied/telegram_setup.go, which does not exist. Both found
by the cp-gwreview lane and left by it as out-of-scope staleness.
2026-09-22 03:38:49 +10:00
sam 18cca53bab fix(webhook): keep a route path out of the sender identity
A webhook set SenderID to its configured route path. The turn path reads that
field through a per-channel resolver which refuses webhook, but the session
curator derives its participant from the raw field with no channel filter, so a
webhook session with exactly one distinct sender and one extracted fact wrote
agent-user memory addressed to User: "/hooks/...". Nothing reads it, and every
pass added more, because the facts are identical strings with no dedup.
docs/prds/memory-engine-unification.md criterion 7 requires that a route path
never become a user identity.

Clear it at the producer rather than teaching every consumer which channels are
lying: a route path is a source, not a person, so it no longer enters SenderID.
It still keys the inbound rate limit, where it is the documented per-source
budget for webhooks (config.RateLimitConfig), so it travels in the new
transport-only Inbound.BudgetKey -- carried on the wire beside Page, never
persisted, and never read as an identity.

pb.Message gains budget_key (field 9) for the same reason page (field 7) exists:
transport context that rides with an inbound message and is deliberately absent
from storedProto's rendering of a canonical record.

The curator needs no change. An empty SenderID already fails closed as an
unidentified user message, which is the path a dashboard session takes, and
sessionParticipant's existing skip covers it; the test name now says so.
2026-09-22 03:18:59 +10:00
sam e5669c9117 fix(archied): serve only the health facts a /status reply can carry
setupGatewayChat is the only production constructor of a Router and it runs
in the Gateway, which owns no container pool, no poll loop and no channel
manager. The producers wired to those three built report sections no reply
could carry, and /status' own description of itself claimed all five fields.
The health source now carries the broker connection and the chat-model
outcome, the two facts the answering process holds.

The tests for the deleted producers go with them, replaced by one that pins
the served shape with a pool and a daemon present in the boot.

Corrects docs/prds/status-health-surface.md, where the intro, the Phase 2
summary and the rendering bullet all claimed the five-line surface.
2026-09-22 01:58:00 +10:00
sam ce006fabc7 docs(eda): point the expression PRD at its unbuilt decisions
Three of its decisions have no implementation: J1 action ids, J2 args as CEL,
and generated Result schemas declared to CEL for field-level result typing.
That is why it stays Approved rather than Finalised, so the header names the
beads that close the gap.
2026-09-22 01:57:00 +10:00
sam b2ac69ace3 docs(eda): split the expression decision out and cut the playbook PRD to its design
The playbook engine PRD had grown to 972 lines against CLAUDE.md's one-page
bar, because four documents were living in it.

The expression decision was the worst of it: an H2 nested inside a numbered
list item, 270 lines with twelve H3s and its own Status and Date fields. That
broke the outline and gave the document a second, non-canonical status. It is
now docs/prds/playbook-expression-syntax.md, named flat and linked by a Parent
field the way module-position.md already relates to this epic. The parent
keeps the decision and a pointer.

Repetition, against the state-each-fact-once rule: reject-at-load was stated
ten times, the plugin engine rule nine, producer-only seven. The producer-only
argument ran 32 lines and closed by restating itself; it is eight lines and
stated once. One heading read "confirmed non-issue (stated once)" above the
third statement of the point.

Open question 3 was closed by module-position.md and still listed here as
open. The section holding four decisions and one note is no longer called
"Open questions", and the note is a standing constraint, which is what it is.

Also removed: two list summaries written before their lists, ten dated
attributions, two progress claims, three orphan line citations, and the
undefined { Call: ... } notation.

Five findings in other PRDs came from tightening the guard, not from this
split.
2026-09-22 01:07:05 +10:00
sam f604e0ed9e docs(eda): approve the Channel and Forge positions PRD
Maintainer sign-off on the Channel resolution. Draft -> Approved.
2026-09-22 00:50:11 +10:00
sam fcde69c76c docs(prds): normalise statuses and remove writing dated to its own day
Three defects the first sweep left behind, each caught by a rule the guard
did not yet have.

Statuses. RULES.md gives three; the tree had 25 values, and the free-text ones
were carrying progress. "Implemented (wiring landed)" and "Ratified (rev. 2e).
Rev. 2e adds the OpenTaskByPR lookup. Rev. 2d revised section 10..." were both
changelogs living in the one field the other rules exempt. Every PRD now
declares Draft, Approved or Finalised and nothing else; five that declared
nothing now declare one. A revision number moves to **Revision:**, a pointer
to the authoritative document to **Authority:**, and what a past revision
changed to git. CLAUDE.md's citation of state-store-contract rev. 2e still
resolves.

Stale cross-references. "Supersedes the 2026-09-03 open question", "this
bullet previously said", "an earlier draft of this document claimed" all point
at text the reader cannot see, because it was replaced. A supersede marker
survives only when it names a file, a section or a symbol that can be found.

Temporal hedges. 100 uses of today, currently and right now across 31 files.
Each dates its sentence to the day it was written: "[notify] today is one
webhook URL, read in one place" stops being true the moment this design lands,
while still reading as the premise it rests on.

The header-field exemption was also too wide. "**Date:** 2026-09-03, Channel
resolved 2026-09-22" smuggled a dated status into the one line the rules did
not read; the exemption is now a Date holding only a date and a Status holding
only one of the three.
2026-09-22 00:38:35 +10:00
sam 95743b60cc docs(prds): remove session-bound writing from every PRD
183 findings across 28 of 46 PRDs, of which 150 were file:line citations. Two
were already hard-broken: one named a file that no longer exists, one pointed
past the end of its file. The rest resolved to a line that still exists,
which is the worse failure -- a citation that silently drifted onto unrelated
code still reads as authoritative.

Citations now name the file and the symbol. Dated status markers become the
decision they carried ("Status 2026-09-05: resolved" -> "Resolved"), since
whether a question is answered is design information and when it was answered
is not. Progress inventories become scope statements: mcp-tool-completion now
fences what is out of scope rather than reporting what shipped.
status-health-surface drops phase-completion from its headings and keeps the
rule that earned them, that a reported field must have a truthful source.

eda-playbook-engine.md was the worst file and my own t2db.23 status block was
part of why; it is rewritten as the resolution it records.
2026-09-22 00:21:28 +10:00
sam 11f154b7b9 build(docs): gate docs/prds against session-bound writing
A PRD states a decision, a requirement, a constraint or evidence. Those
survive the code moving underneath them. A line number, a progress report or
a dated status claim does not: it is true on the day it is written and
silently wrong a month later, while still reading as authoritative.

prdlint rejects five shapes: file:line citations (including a document citing
its own line numbers), dated status claims, progress reports on the work
being designed, phase-completion narration, and records of how a finding was
produced. Each finding names the file, line, rule and fix.

The rules target decay, not subject matter. A PRD may describe a phased plan,
name a dependency that exists, and carry its own Status and Date header
fields; what it may not do is assert the state of the tree on the day it was
written. Fenced blocks are skipped, since a listing may specify a line
reference as its literal content.

Wired into task check next to docs:check. A sweep alone would not stop the
class recurring.
2026-09-22 00:21:27 +10:00
sam 141aac08a3 docs(eda): strip status and editing narration from the positions PRD
Headings carried scheduling status the Blocked-on line already states, and
two paragraphs narrated how the document was written rather than what was
decided. Both violate the PRD rule that every sentence adds a decision,
requirement, constraint, evidence or verification step.
2026-09-22 00:09:02 +10:00
sam 7d0ea243bc docs(eda): resolve the Channel action position
Notification is a contract in internal/domain/messaging, not a channel type.
A channel implementation satisfies it by importing its own parent, which it
already does, so channels.Channel gains no notification method and no import
and the dependency stays channels -> messaging. A notification has no
lifecycle, no inbound direction and no config schema, so modelling it as a
channel would force Start/Stop/ConfigSchema onto something with no meaning
for them.

Destinations are configured, never named by a playbook: [notify] grows from
one webhook URL into named destinations, each binding a name to a channel
already registered in the Messaging composition plus that channel's address.
An action names a destination. Playbook triggers are reachable from a public
intake surface, so an action that could address an arbitrary chat would be a
new exfiltration surface.

Host access needs no new process surface. archie-messaging dials out only and
deliberately has no NATS connection, so nothing can push to it today.
Delivery travels the Gateway connection every process already holds, as a new
server-streaming RPC on ChatService; the per-turn Stream RPC is not reused.

The 2026-09-03 section presenting two options is superseded. Its claim that no
send capability exists anywhere was too strong: telegram.SendPendingReport
already sends unsolicited to a stored chat id, with no interface for it.

Closes archie-core-t2db.19
2026-09-22 00:06:52 +10:00
sam 298c3133f3 feat(eda): wire the playbook coordinator into production workflow selection
A loaded playbook now decides a real task's workflow. The wiring point is the
daemon's definition pin (Daemon.resolveWorkflowID, consumed by
pinWorkflowFromCollection), not pollNATS/publishTask as the design doc
assumed: routing moved out of the agent process when workflow definitions
became database rows pinned before dispatch, so the pin is the one place a
task's workflow is chosen.

Precedence: an explicit Task.Workflow (the waiting_human -> approved requeue)
still wins, then a matching playbook, then workflow.ResolveWorkflowID's
existing label/kind bindings. A playbook naming an undefined workflow is a
reported failure that parks the task rather than a silent fall-through to the
binding's choice -- the operator bound that trigger deliberately.

Store.Dispatch returns the selected workflow name plus the matching playbook's
id and version, instead of a compiled workflow.Workflow: the production caller
decides against the active definition collection, and the id/version are the
first two components of the resolved gap-2 idempotency key. The playbook
package no longer imports internal/domain/workflow.

The shipped example's `when` read event.priority, a field no intake supplies,
so it could never have fired once wired. Both examples now read the event
surface playbookInput really builds, and label-trigger.yaml documents the axis
an instance defines for itself: trigger.kind is the closed workintake
vocabulary because a kind addresses a NATS subject, while trigger.labels is
free-form and binds an operator's own taxonomy to a workflow.

Module/Channel/Forge positions stay rejected at load; they need the
playbook_dispatches ledger first (archie-core-t2db.24).

Closes archie-core-t2db.23
2026-09-21 23:47:06 +10:00
sam dcdaa9f451 feat(webui): show which process is running which settings version
The settings page now reads apply status beside each resource: every known
process with the version it applied, its error if it rejected the edit, and
whether it is still reporting at all. It re-reads after each save, so the page
reflects what the processes did with an edit rather than what was stored.

The server derives liveness only, because it knows whether a record went stale
but not which version the page is showing. The client compares against the
resource it is rendering, which is what turns a live record on an older
version into a pending restart.

A process that stopped re-stamping and one that never reported are separate
rows with separate wording, and neither is an error: the setting may be fine
and the process simply absent, which an operator acts on differently. A failed
apply-status read leaves the previous rows rather than taking the settings
page down with it.

state-store-contract.md gains the pair in its inventory and its count moves
from 45 to 47, with the note that this read is a list rather than the
config-snapshot pair's found=false singleton.

Closes archie-core-pskb.
2026-09-21 15:57:46 +10:00
sam 21b5931f15 feat(statestore): carry control-plane apply status on the store contract
Adds PutApplyStatus/ListApplyStatus so each process can report which version
of a control-plane resource it is running, and the UI can read it back.
docs/prds/control-plane-apply-status.md is the approved design.

It goes on the State Store contract rather than the control plane, whose
service is for editing a resource: a status report is not an edit. The
config-snapshot pair is the precedent, and the deny-by-default arm of
authorizesTaskScopedCall already refuses both new RPCs to a task grant, which
TestOnlyAdminReportsApplyStatus pins.

The row is keyed on (process, kind) and replaced in place, because a process
re-stamps on an interval and nothing reads a history of re-stamps. An error
leaves applied_version alone, so a rejected edit never erases the fact that an
older version is live. The read is a list and an empty one is not an error,
unlike the config snapshot's found=false singleton.

Contract PRD inventory and RPC count follow in the same series.

Relates to archie-core-pskb.
2026-09-21 15:44:31 +10:00
sam dc5e7ca9c5 docs(prds): leave apply-status liveness open instead of deciding it
RULES.md says not to turn a requested outcome into extra product features and
to keep inferences open until the maintainer or repository evidence settles
them. The first draft broke that: a reviewer found that a record replaced in
place lets a process that applied a version and then died keep reading as
current, and I answered it by adding a periodic re-stamp, a recurring write in
three processes that neither the tracking issue nor runtime-control-plane.md
asks for.

The hazard is real, so it stays in the document as an open question with three
options and a recommendation, for Sam to settle. The re-stamp and the instance
identity come out of the design.

Also the sentence pass RULES.md requires before approval, which had not been
done: the staleness rule was stated in three sections, and rationale stood
where a requirement belongs.

Relates to archie-core-pskb.
2026-09-21 15:33:14 +10:00
sam 7312bf662b docs(prds): decide where control-plane apply status is reported
runtime-control-plane.md requires each process to report the version it is
using or why it failed, and does not say where that report goes. It cannot be
a control-plane operation: that service is the surface for editing a resource,
and a status report is not an edit. It goes on the State Store contract,
following the config snapshot pair, whose administrative RPCs a task-scoped
grant already cannot reach.

Draft, pending approval. Reviewed by three independent lenses first, per
docs/prds/RULES.md. The operator lens opposed the first draft on two counts
now fixed: a record replaced in place with no re-stamp would let a process
that applied a version and then died keep asserting health, inverting the
choice status-health-surface.md made deliberately; and the dominant failure,
an unreachable State Store, can never report itself, because every apply point
is reached only after the store has answered. The draft now carries instance
identity and a re-stamp interval, says plainly which failures are reportable
at all, and gives the three kinds of absence distinct renderings.

The boundary lens required the surface be reconciled against ConfigView's
reload status rather than duplicating it; apply status covers resource kinds
and ReloadStatus stays the file document's only report. The contract lens
established that task-grant denial needs no new rule, that the read is a list
rather than a found=false singleton, and that the contract's RPC count moves
from 45 to 47 in two places.

Relates to archie-core-pskb.
2026-09-21 14:55:04 +10:00
sam f24ee12910 docs(prds): define three PRD statuses and approve the control plane
PRD headers carry 26 distinct status strings across docs/prds/. Draft,
Approved and Finalised are the only three, and a finalised PRD is superseded
rather than edited.

runtime-control-plane.md still read "Draft -- not approved" after it was
approved to proceed.
2026-09-21 10:43:08 +10:00
sam 02720c8e81 feat(controlplane): runtime administration over the State Store's gRPC server
The Web UI and messaging channels now read and write Archie's runtime
settings through one versioned, audited control-plane API hosted on the
State Store's existing gRPC server: catalog, query, command, watch. Each
feature owns its resource, validation and commands; storage only writes
versions and audit records.

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

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

archie-messaging gains -state-store-target/-state-store-token and reads
channel settings from the database, failing closed when the State Store
is unreachable: the database is authoritative for those settings.
2026-09-21 08:17:42 +10:00
sam 1103b4f1e6 feat(tools): a capture-intake sender for exercising the Events surfaces
Posts to /webhooks/capture/{source} with a realistic GitHub, Sentry, form or
large payload (or an exact body), reads the capture back so a silent drop is
visible immediately, and names the intake's rate and size limits when it
hits them. Wired as task webhook:send.
2026-09-21 01:10:30 +10:00
sam d3dcdcd773 feat(webui): refine system navigation and appearance 2026-09-21 00:45:02 +10:00
sam 1def531437 feat(webui): port the dashboard (Phases 3-5)
Every page from the deleted Preact dashboard, rebuilt in Vue 3 + shadcn-vue.
The navigation restructure landed earlier on this branch; this is the surfaces
behind it, and the two are now one app.

Dashboard, Tasks (list and detail), Configuration split six ways, Logs,
Inspector, Mappings, Bindings, Workflows, Skills, Curators, Channels, chat.

Components, not files: docs/prds/dashboard-port-brief.md requires one
component, one job, one file, with shared state in a module beside it. So a
page file composes and holds nothing, and a shape repeated across panes becomes
its own component (LogRow, PageHeader, PanelLoading, WorkflowBar).

Behaviour that had to survive, because each was a fix:

- Live activity's detail is clamped to one line with the payload on the title.
  Unclamped, one row made the dashboard 7,481px tall.
- Each health card takes its own height. Equalising left a mostly-empty box
  taking a quarter of the first screen once setup was done.
- Tasks: `tab`/`attempt` live in the query string and are written with
  router.replace, so a tab click adds no history entry and does not remount.
  The list's deep-link reveal honours prefers-reduced-motion.
- LOG_LEVELS is a wire contract (the server matches that CSV server-side), used
  unchanged by both log panes.
- The chat panel's Phase 5 list: a FAB that is the only toggle, a morph whose
  scale, radius and position interpolate together, no scrim, no close button,
  Escape returning focus to the launcher, Stop only while streaming.
- Unconfigured is not broken. A 501 on /api/version or the log stream renders
  what is true ("Not configured on this deployment") rather than blank, and a
  read-only Configuration says so instead of offering controls that cannot work.

Three things the port decided rather than carried:

- Button gains an `attention` variant and Badge the five status tones, in the
  project's own cva. The pill's dot did not come across: the Badge's shape is
  the affordance, and the same tone now covers a trend indicator.
- The icon module is not ported. Its name-to-glyph lookup is the pattern
  shadcn-vue's rules call out as wrong, so icons come from @lucide/vue at the
  call site. The five bespoke glyphs have no consumer yet and become components
  if a page draws them.
- The theme control left the topbar for /system/appearance, per the approved
  navigation design. ThemeToggle.vue and Placeholder.vue are deleted rather
  than orphaned: every route now resolves to a real page.

Also fixes the bundle freshness check failing on the first build after every
change. ui/dist is committed, so nothing ignores it and Tailwind's content
detection scanned it, making each build an input to the next.
2026-09-20 20:04:55 +10:00
sam c799e3209c feat(webui): port the shared primitives (Phase 2)
The Preact tree's ui/src/base/ was deleted with the dashboard. This rebuilds
what depended on it, on the shadcn layer rather than as new bespoke markup.

Badge and Card come from the shadcn-vue CLI, so they match the already-vendored
components, and the composed pieces sit on top of them:

- Badge gains the five status variants the pills used, over the palette's status
  tokens. The pill's dot did not come across: the Badge's own shape is the
  affordance, and the same variant now covers a trend indicator, where a dot
  reads as noise.
- base/StatTile.vue uses full Card composition instead of dumping everything
  into one content slot, with base/Sparkline.vue and the goodDirection logic
  that says whether "up" is good news.
- base/Gauge.vue and base/SegmentBar.vue, both of them: the original exported
  two components from one file and budget composition uses the second.
- base/LogRow.vue over lib/log.ts, which holds the LOG_LEVELS wire contract
  (the server matches that CSV server-side, so it is not a display choice).
- lib/status.ts, so status colour has one home: a task state, a gate result, a
  log level and a trend all draw from the same five kinds.

Two deliberate departures:

The icon module is not ported. Its name-to-glyph string lookup is the pattern
shadcn-vue's rules call out as wrong, and nothing consumes the five bespoke
glyphs anyway: the navigation is text with tooltips. Icons come from @lucide/vue
at the call site, and the five become components if a page draws them.

The gauge's aria-label announces the rounded percentage. It announced the raw
one, so a screen reader read 71.38461538461539% where the screen showed 71%
(bead 86au).

Also lands the four modules the checklist marks copy-verbatim, which encode
bugs fixed just before the delete: dashboard/activity-detail, chat/
command-scroll, workflows/workflow-rows and logs/logs-empty.
2026-09-20 19:38:17 +10:00
sam e88a25afef feat(webui): land the Phase 1 foundation on the navigation restructure
Two Vue branches were in flight and looked like competing versions of the same
change. They were not: this branch had the navigation restructure (Phase 4)
and the route table, and the other worktree had the Phase 1 foundation, still
uncommitted. Neither had ported a page. This reconciles them.

What came across from the foundation:

- lib/api.ts, the one client every request goes through, so the CSRF and
  Content-Type headers live in a single place, plus the four framework-free
  modules it needs: uuid, stream-state, format, task-meta.
- loadTaskMeta() at boot, so /api/task-meta replaces the freeze-dried
  lifecycle defaults instead of the catalogue being frozen into the bundle.
- capabilities.ts keeps the other branch's pure hiddenRoutes, but reads
  route.meta.section. The other version read route.section, which is always
  undefined for this route table, so its capability gating was silently dead.

The route table stays this branch's: internal/gateway's registry test holds it
in parity with the agent-facing page index in both directions, and the other
branch's table fails it with seven errors.

The frame is Tailwind on the shell, not a ported stylesheet. layout.css
described a shell, a topbar and a nav as authored classes, but the topbar is a
Vue component like every other surface and emits none of them, so two thirds
of that file had no consumer. What the frame needs is now the shell element's
own utilities plus the canvas, focus floor and motion preference in
style.css's base layer, where a global element rule belongs. Verified equal to
the stylesheet it replaces: 20px radius, hairline border, blur(28px)
saturate(1.2), and the narrow-screen collapse.

Also fixes the bundle freshness check failing on the first build after any
change, which had cost both branches of this port a rebuild-and-retry. ui/dist
is committed, so nothing ignores it and Tailwind's content detection scanned
it, making every build an input to the next: class strings left in the bundle
generated utilities for classes nothing references any more, so an unchanged
tree built a different bundle. Excluding it also drops ~12KB of dead CSS.
2026-09-20 19:14:46 +10:00
sam e553b2ca9c feat(webui): grouped topbar navigation, built from components
Five top-level items instead of eleven flat ones: Dashboard as a link, then
Work, Agent, Events and System as dropdowns, with each item's one-line
description on a hover tooltip. Configuration dissolves into /system/{status,
appearance,tasks,models,repos,advanced} and /settings redirects to the first of
them, so existing bookmarks still land somewhere. Logs gets a nav entry for the
first time.

The bar is composed from named components rather than one file: Brand (Logo,
BrandName), Nav (NavTrigger, NavGroup, NavItem), SearchBar, SupportLink,
ThemeToggle, ProfileDropdown. The nav model reads the route table, so a route
and its nav entry cannot disagree, and a group whose every child is gated off
is dropped while a group left with one child stays a dropdown.

The Go page registry moves with it, which its parse-the-route-table test
enforces.
2026-09-20 18:46:11 +10:00
sam 017ef21ab2 docs(webui): nav item descriptions are hover tooltips 2026-09-20 18:25:56 +10:00
sam e2e6dd0b26 feat(webui): history routing
createWebHistory with base "/". The Go server already falls back to index.html
for any unmatched path and [web] has no path-prefix option, so the dashboard is
always at the root.

legacy-hash-redirect.ts rewrites `#/path` links minted before this change.
Verified against archie-ui rather than the Vite dev server: /tasks, /tasks/42
and /settings all serve index.html with assets resolving, and #/settings lands
on /settings.
2026-09-20 18:14:37 +10:00
sam 2377513133 fix(webui): self-host Geist, and fold the cross-check findings into the plan
Four review agents checked the bootstrap and the migration checklist against
the deleted tree and the Go handlers. Three found real problems.

The shadcn-vue CLI's default font resolved to a Google Fonts @import. archied
is deployed on LAN-only and air-gapped hosts, where that silently falls back to
a generic sans and makes an admin tool that otherwise has no third-party calls
start making one. Now @fontsource-variable/geist, self-hosted: five woff2 files
in dist and no external URL left in the bundle.

vite.config.ts used __dirname for the @ alias, which Vite 8 already warns is
unsupported under its native config loader. Now import.meta.url. Dropped the
leftover template vite.svg.

The checklist gained what the review found missing, most of it consequential:

  - main.jsx was never named as a source, so the jump-to search, the `soon:`
    nav treatment, the boot-time task-meta re-render and the route-keying rule
    (keyed on path+params but NOT the query, so a tab switch does not remount)
    had no home. vue-router needs an equivalent key strategy.
  - css/layout.css is 498 lines and holds the shell, the chat dock and morph,
    and every breakpoint Phase 5 described only in prose. Named as the source
    to port from rather than left to reverse-engineering.
  - Six further CSS files carried behaviour with no mapping: focus-visible,
    .sr-only, the global prefers-reduced-motion override, and the pill colours
    a Badge port has to match.
  - Chat's content features -- session switching, persona and model selectors,
    inline tool-call rendering -- were absent; Phase 5 described only chrome.
  - Configuration's editable-vs-read-only dual mode (503 when the process only
    holds a published snapshot) is architecture, not styling.
  - Tasks writes tab/attempt state with history.replaceState specifically to
    avoid a remount per tab click.
  - statTile also exports Sparkline, gauge also exports SegmentBar, and five
    icons have no 1:1 Lucide equivalent, so those swaps are design calls.
  - LOG_LEVELS is a wire contract matched by splitCSV server-side.

Corrections: the API surface is 48 methods plus two SSE subscribers, not ~45.
Mutations require both X-Archie-CSRF: 1 and Content-Type: application/json,
answered 403 and 415 -- the likeliest silent breakage after the port, now
stated exactly. My claim that a test enforced "no second fetch()" was wrong:
that text-scan was deliberately removed upstream for testing the file's wording
rather than its behaviour. The real guard was per-method header classification,
flagged as the one test worth bringing back first.

The 106px clipping figure is a live measurement and not recoverable from git,
so it now carries the viewport and both edge positions.
2026-09-20 17:22:51 +10:00
sam 7fb91de71d docs(webui): migration checklist for the Vue + shadcn-vue port
Records what has to exist again, the contracts that break silently if missed
(embed output shape, the Go route registry, capability gating, the single
fetch path, SSE teardown), and the behaviour shipped today that lives only in
the deleted tree -- the chat launcher, the topbar shrink rules, the clamped
activity detail, the corrected contrast tokens, the readyState-derived stream
state.

Five deleted modules are framework-free and port by rename; each encodes a bug
fixed today, so re-deriving them by hand is how those bugs come back.
2026-09-20 17:17:48 +10:00
sam b90f733825 feat(webui): bootstrap Vue 3 + shadcn-vue, replacing the Preact dashboard
Sam owns this codebase and reads Vue fluently, not Preact; a UI its maintainer
cannot read is the liability that outweighs the port. shadcn-vue is Vue-only,
so adopting it means the framework moves with it.

Scaffolded per the official Vite guide: `npm create vite --template vue-ts`,
Tailwind v4 via @tailwindcss/vite, `shadcn-vue init` (Reka UI, Lucide, neutral
base, CSS variables). Button and DropdownMenu are added, the latter being what
the pending navigation restructure needs.

Two deviations from the guide, both forced:

  - The guide sets `baseUrl` alongside `paths`. TypeScript 6 deprecates
    `baseUrl` and errors on it, and this project is heading for TS 7 native, so
    `paths` stands alone and resolves relative to the config file. Not a
    downgrade: the scaffold's typescript ~6.0.2 is untouched.
  - vite.config.ts keeps `base: "./"` and unhashed asset names. ui/embed.go
    embeds a committed dist/, served from a path the build does not know;
    hashed names would also orphan a file in git on every rebuild.

The Preact app and its 43 test files are deleted rather than ported, on Sam's
instruction: tests return when there is behaviour worth pinning rather than a
port to re-assert. `task test:ui` is now a vue-tsc typecheck, which is what
would actually catch a broken component; an empty `npm test` would pass
vacuously.

ui/src/router/index.ts carries the route table and is the new source of truth
for TestDashboardPagesRegistryCoversEveryRoute, which parsed main.jsx before.
Keeping that contract alive matters: it is what caught the stale /chat entry
earlier today. Every route resolves to a named placeholder view, so an unported
page is visibly unported rather than blank.

golangci-lint now excludes ui/node_modules. The dashboard toolchain pulls in
`flatted`, which ships a Go implementation beside its JavaScript, and the gate
was failing on complexity in a vendored third-party file.

The shadcn MCP server is registered in the root .mcp.json. `shadcn-vue mcp init`
writes it to the directory it runs in, which for a nested ui/ is a path Claude
Code never reads.
2026-09-20 17:14:47 +10:00
sam af74e93a20 feat(gateway): give /status a real daemon-health surface (#892)
* feat(gateway): give /status a real daemon-health surface

Phase 2 of archie-core-wp9s. Phase 1 split the commands apart (health vs
work) but left /status with one aggregate queue line and a static runtime
block; it could not answer the questions an operator actually asks when
something feels wrong. /status now reports, between the queue line and the
runtime block:

- Broker: the live state of this process's own NATS connection
  (eventbus/nats.Client.Connected), not a fresh dial -- a probe would
  report the probe's reachability, not the daemon's.
- Containers: the pool's own active counter against the configured cap
  (Pool.Active/Cap), not a Docker listing, which would include containers
  this pool does not own. A zero cap means unlimited, so it is not shown
  as a ratio.
- Channels: the channel manager's real lifecycle state, including a
  failed adapter's reason (the documented decision: read the existing
  manager rather than re-deriving health per adapter).
- Chat model: last-known outcome of every chat-model call this process
  made, recorded once in sendChatTurn (the single choke point) and read
  back by /status. The second documented decision: never a live probe,
  so /status stays instant and reports what happened -- or says plainly
  that nothing has been attempted yet.
- Last poll: when the most recent poll pass began, stamped on both poll
  paths (Run's single-identity loop and runIdentities' per-identity
  goroutines). A pass that hangs leaves the stamp stale, which is the
  signal; stamping completion would leave a wedged poller looking
  healthy.

Truthful or absent: a section this process has no source for is omitted
rather than rendered as a zero. The standalone Gateway owns no poll loop,
pool or channel manager, so its /status reports broker and chat-model
health only; aggregating across processes would need a new daemon RPC and
is deliberately not built. Version stays out (/version owns it).

/status and /tasks descriptions now describe what each command actually
does on both published surfaces (Telegram menu/help and the shared
specs), pinned by a test that also fails if the two surfaces drift.

Sources are read through functions, not captured values: occupancy and
channel state move, and the daemon is built after the gateways, so a
source captured at construction would freeze /status on boot state.

Left in place deliberately: the Runtime (provider/model) block, which
Phase 1 flagged and which duplicates /model and /whoami. Removing it is a
product call on a command Sam uses daily, not a mechanical follow-up.

* docs(prds): record the two open /status health decisions as settled

Both were flagged in PR #892 as needing the maintainer's call; both are now
answered, and the PRD is the place a follow-up would look:

- The Runtime (provider/model) block stays. It is the one line in /status the
  ticket's own rule says should not be there, but /status is read daily to see
  the active model at a glance, so the duplication is deliberate. Recorded as a
  settled product decision so it is not removed later as an oversight.
- Health stays per-process. Pooling the daemon's and the Gateway's chat-model
  outcomes would need a new daemon<->gateway health RPC for one status line, and
  a per-process line is true where an aggregate would be a claim about a process
  the answering one cannot see.

/agents' published description is still left to archie-core-mxls, unchanged.
2026-09-20 00:30:23 +10:00
sam 4750ac097b feat(workflow): post line-anchored review comments with suggested fixes (#891)
* feat(workflow): post line-anchored review comments with suggested fixes

Bead archie-core-q9au (docs/prds/inline-review.md). A review's findings reached
the operator only as a flat list in the PR body, so the author had to map every
finding back to its line by hand and apply mechanical fixes by hand. Now the
line-anchored findings are also posted as inline review comments, carrying a
one-click suggestion when the reviewer could state the fix.

Domain (internal/domain/workflow):
- ReviewFinding gains Suggestion; Validate rejects one on anything but a
  confirmed finding, so the agent's record_finding call is refused with
  something it can act on. Validate splits into validateAnchor /
  validateClassification / validateDisposition, which also brings it back under
  the cyclop limit the gate enforces.
- StagePostReviewComments runs after StageOpenPR in the implement workflow. It
  posts only line-anchored findings (Line > 0); a whole-file finding has no line
  to attach to and stays in the body list, which remains the complete record.
  It is best-effort: the PR is open and the body already lists every finding, so
  a failed comment is logged, never a park -- the same reasoning as OpenPR's
  existing best-effort LinkBranch call.
- The suggestion fence is gated on Verdict == confirmed where the fence is
  written, because it is a one-click apply: a wrong suggestion breaks the code
  and the author has to notice.

Forge (internal/forge): ReviewCommentWriter + GitHub/Gitea implementations,
type-asserted like PullRequestReader so a forge that cannot is skipped rather
than faked (NoopForge is pinned as not satisfying it). GitHub loops one
CreateComment per comment and joins the failures, so one refused anchor cannot
drop the rest; Gitea carries them on a single COMMENT-state review.

Two deliberate departures from the PRD's sketch, both recorded in it:
- The interface is batch (CreateReviewComments), not one call per comment:
  Gitea's only inline shape is one submitted review, and the set then crosses
  NATS once instead of once per finding.
- The head SHA is resolved inside each forge implementation rather than by the
  caller. The stage runs in archie-agent, which holds no forge credentials and
  has no PullRequestReader; the daemon-side forgerpc handler is the only place
  that does.

Transport (internal/forgerpc): workflow.Forger gains the method, so the agent
reaches the daemon over the new create_review_comments subject; the server
type-asserts the writer and answers an incapable forge with an error the stage
logs. This is the one proxied method whose absence on an image skew does not
park a task.

The reviewer prompt and record_finding schema ask for a suggestion on a
confirmed, mechanically fixable defect only.

Regenerating the wfextract symbol table -- the documented way a new exported
workflow symbol reaches interpreted stage plugins -- also picked up symbols that
were missing from the committed table (the Status* and Source* constants,
ReviewCheck, Store, Task, and the _Store wrapper). Nil-guards were re-applied to
every wrapper afterwards, as that file's header requires.

Evidence: task check exit 0 (incl. 229 UI tests). Three mutations of the new
stage logic each fail a test that names the behaviour -- dropping the
confirmed-only gate, dropping the Line > 0 filter, and letting a posting failure
escape -- so the tests discriminate rather than passing vacuously.

* fix(build): drop the Dockerfile pin assertion

The guard fetched golangci-lint's go.mod at image build time to fail the build
when GOLANGCI_LINT_VERSION and GOFUMPT_VERSION disagreed. It only ever tripped
on self-inflicted pin drift, but it added a network fetch and a new failure
mode to the release build, which is not where that belongs.

The pins stay correct (golangci-lint 2.13.2, whose vendored gofumpt v0.11.0
equals GOFUMPT_VERSION) and the comment above them still states the invariant,
so the reasoning survives without the build-time machinery. The pin change
itself reaches the agent image through the normal release path: CI rebuilds
and pushes archie-agent on an archie/vX.Y.Z release, and a gateway-only
release deliberately does not.

* feat(workflow): add the remediate workflow for PR review remediation

Implements step 5 of docs/prds/pr-review-remediation.md: a remediate
workflow that resumes the task's existing worktree onto its PR branch
(worktree.Manager.Resume, not Prepare's refresh), runs a builder agent
against the review's actionable comments, commits and pushes to the
same branch, and replies via the forge's ReplyToReview. Task.RetryCount
doubles as the remediation round counter, capped by the repo's
max_retries; the round-cap stage parks the task and posts one comment
when it's hit.

Task gains a ReviewPayload field (JSON-encoded review unit) with full
store/proto/staterpc plumbing. workflow.Forger gains Comment and
ReplyToReview, proxied to archie-agent via a new forgerpc RPC. Resume
and its Dir lookup are added as an unexported optional Trees capability
rather than widening the exported interface, which is already at
golangci-lint's interfacebloat cap and is projected into wfextract's
Yaegi symbol table for repository-authored stage plugins.

The daemon-side reaction consumer that dispatches into this workflow
(subscribing ARCHIE_REACTIONS, grouping comments by review, enforcing
per-task serialization) is tracked separately in archie-core-8li9.4.

* feat(messaging): extract standalone messaging service binary and process composition

* feat(messaging): adapt channel frontends to consume Gateway ChatContract

* feat(messaging): remove in-process channels and Router from daemon bootstrap

Telegram, email and webhook now run only in the Messaging Service, which
reaches this process through the Gateway's ChatContract. The daemon builds
no channel and no gateway.Router, so the wiring that existed only to serve
them goes with it: setupGateways, setupEmailGateway, setupWebhookGateway,
setupTelegramGateway, buildTelegramRouter, makeTelegramReload and the
release-announcement path helper.

The seams those paths owned move to where they can still be honoured:

- Channel ValidateConfig runs in archiemessaging.compose, which now returns
  an error, so a configured-but-invalid front-end fails the service rather
  than being dropped silently.
- The inbound rate limiter moves to the Gateway process, which owns the only
  Router and therefore the only place a per-sender budget applies to every
  channel's turns.
- The daemon's gateway readiness probe becomes a ContractProbe against the
  Gateway. It cannot observe a channel lifecycle it no longer runs, and a
  channel-count probe would have reported every daemon degraded.
- telegramSetup is now chatSetup (in chat_setup.go), trimmed to the fields a
  chat turn runner actually reads.

Telegram operator features that were wired only in the daemon (/update,
release announcements, version reporting, SIGHUP reload) are not yet wired
in the Messaging Service: archie-core-8cda.6.6. Channel lifecycle reporting:
archie-core-8cda.6.8. The Gateway process builds no worktree manager, so
review_pr is unadvertised on every channel: archie-core-8cda.6.7.

* feat(messaging): re-wire the Telegram operator surface in the Messaging Service

setupTelegramGateway satisfied eight telegram.Gateway seams from the daemon's
own process. Each is resolved by where the fact it needs is owned, not by
where it used to be built; the decision table is in
docs/architecture/migration-decisions.md.

Wired here: /update (built from this service's own [chat.telegram] check and
install commands), the update-report relay (same sha256(bot_user)[:8] path the
daemon wrote, so a pending report is found rather than written afresh),
show_tool_calls, and /restart's config reload, which re-resolves the token and
allowlist from this service's own file and refuses a reload that resolves to
an empty token.

/version is sourced from the Gateway: ChatSnapshot gains a Version field
carrying the Gateway's rendered build block, read per call and bounded by the
dependency timeout. cmd/archie-messaging deliberately takes no version
ldflags, so it cannot report a partial upgrade as a matched one.

RunningVersions and ReleaseAnnouncements stay nil. Both need a component's
real running version, and the only versions this process can obtain are a
different binary's stamps -- reporting them would manufacture exactly the
false success the update check exists to catch, and the announcer without
parseable versions is a no-op that reads as configured. archie-core-8cda.6.9
carries the contract that unblocks them. Dangerous stays nil: no composition
has ever supplied a command authority.

Enrich is dropped from the update service: componentInstallTypeEnricher read
[nats], which this service must not decode, so the check command's own
reported install type stands.

* fix(workflow): guard inline review comments against head drift

Two findings from the review of q9au.

A comment's line numbers describe exactly one revision of the branch, but the
forge resolved the pull request's head at posting time -- after the review had
already read the worktree. A push in that window (a collaborator, a retry) meant
the findings were anchored to whatever now occupied those lines, mislabelling
instead of failing. The revision the review measured now travels with the
comment set: OpenPR records it from the same worktree read it already performs
(TaskContext.ReviewedHeadSHA), StagePostReviewComments threads it through
Forger to forgerpc, and the forge refuses the whole set once the head it reads
has moved off it -- which the best-effort stage logs, the PR body remaining the
record. An unmeasured revision posts unverified rather than dropping every
finding, so a worktree that cannot report one degrades instead of regressing.

Suggestion was documented single-line only, because GitHub applies a suggestion
fence up to its first line and a multi-line replacement would silently corrupt
the file. Only the verdict was validated, so a multi-line suggestion reached the
renderer and posted as that truncated fence. Validate now rejects an embedded
newline, which makes record_finding refuse it with feedback the model can act on
instead of the reviewer discovering the corruption later.
2026-09-19 23:37:23 +10:00
sam d203229f9c docs(prds): write PRDs for tool/MCP completion, self-update transaction, extensions center
Covers the three ready epics with no settled design: archie-core-1786637493439-140-2cee2e9b
(tools/MCP/guardrails, mostly already shipped — scoped down to the five real gaps),
archie-core-hj1t (self-update artifact install/topology migration/journaled transaction),
and archie-core-1786637490708-35-38424ead (Extensions center). Child issues filed and
linked back to each doc's matching section.
2026-09-19 18:59:56 +10:00
sam b6d0c1857d docs: add reusable PRD template with multi-agent execution breakdown
Extract the shape that worked for image-capability-contract.md (decisive
per-sub-feature decisions instead of deferrals, a call-site inventory, and
a council-lens assignment per slice) into a template so future PRDs get
written the same way -- and so the resulting sub-issues are clear enough
for a cheaper/faster model to implement without re-deriving the design.

- references/templates.md: new "PRD: open capability design with
  multi-agent execution" template.
- SKILL.md: docs/prds/ was missing from the "choose one destination"
  table entirely; added.
- image-capability-contract.md: retrofitted with the Execution breakdown
  (lens assignment per #498-501) the template now asks for.
2026-09-19 18:27:18 +10:00
sam 8b4f6580de docs(prds): complete the image gen/edit PRD across all five open beads
The contract-only doc (#497) explicitly deferred hosted provider (#498),
local GPU provider (#499), /image routing (#500), and channel/web delivery
(#501) to sibling beads with no design recorded. Fill in all four plus a
call-site inventory:

- Hosted: decide ai-sdk for generate, direct HTTP for edit (ai-sdk has no
  edit support) -- the decision the original doc explicitly punted on.
- Local: ComfyUI as the baseline recipe (no prior art in this repo to
  reconcile), submit/poll shaped like minimax.Client.GenerateAndWait.
- /image: Router.handleImage beside handleModel, per-request mechanism
  selection (session-scoped preference has no generic home in Router
  today, confirmed by reading its fields -- not invented here).
- Delivery: mostly already built. generate_video's MultimodalResult ->
  MediaEvent -> channel pipeline already handles "image" generically;
  Telegram already calls SendPhoto. Documented per-channel evidence
  instead of assuming a gap that isn't there.
2026-09-19 18:13:55 +10:00
sam 3773856c70 feat(workintake): authorize review reactions by owned PR 2026-09-19 10:46:18 +10:00
sam 8c71df24e2 docs: correct the withdrawn State Store topology and the authority revision
Two of the three findings from review. The third had already been fixed by the
version of the service-registry PRD that landed on main.

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

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

Not changed: the typo-visibility finding is already addressed by the PRD on main.
Its tracking name, unregisteredServiceKeys, is unimplemented in Go, so the runtime
diagnostic is still missing -- filed as archie-core-jp4g.
2026-09-19 03:07:38 +10:00
sam c94986cf38 Merge pull request #878 from samcharles93/feat/attempt-attribution
Feat/attempt attribution
2026-09-19 02:48:25 +10:00
sam 42bfd35514 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 ca28cf757e docs(prds): pin review remediation identity to the resolved task 2026-09-19 01:48:53 +10:00
sam b6569673c5 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 5aedc28aae 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 6a965ecbd5 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 4ab353ebdd 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 2eb900dabd 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 8d0716900d 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 52aa774afc feat(build): gate generated contract data in task check
Closes #855 (archie-core-5gzx).

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

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

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

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

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

Verified with `task check` (green), including the new `docs:check` step.
2026-09-18 12:46:40 +10:00