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).
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
- 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.
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.
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.
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.
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.
* 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
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.
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.
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).
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.
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.
* 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
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.
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
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
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.
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.
Records the AWX pluggable-architecture and Ansible task-model inspiration
thread verbatim, the verified current-vs-ideal coupling analysis (webui's
in-process HTTP task-action detour, direct gateway internals access,
shared config.Holder), the external service-discovery research
(K8s-native primary + NATS fallback behind one ServiceRegistry seam), and
a Proposed-status PRD recording the target service shape and open
questions before any implementation work is filed.
Phase 1 (archie-core-wp9s) shipped /tasks and the /status queue-depth
aggregate. This documents the remaining ask -- broker connectivity,
provider reachability, channel state, container pool, last poll --
split into cheap wiring (nats.Conn.Status(), container.Pool's
already-tracked active count, a new last-poll timestamp) versus two
real product decisions (live-probe vs last-known-outcome for provider
reachability; the ChannelManager-backed shape for channel state).
Proposed resolution, awaiting Sam's sign-off before Phase 2 lands.
Drafted for archie-core-t2db.17 (idempotency) and .18 (mid-run
failure), following the same evidence-then-sign-off process the CEL
resolution used -- explicitly marked PROPOSED, not decided, pending
Sam's approval. Every claim checked against the real shipped code
during drafting, not assumed, catching two wrong assumptions before
they landed:
- Gap 1 (mid-run failure): proposes reusing workflow.Run's existing
three-way distinction (real error -> stop+report; shutdown
interruption -> not a failure; no-outcome -> definition-bug parked)
rather than inventing new semantics. States the producer-only
boundary and the J3 (condition-error) vs action-failure distinction
explicitly, and states plainly that rollback is not attempted.
- Gap 2 (idempotency): proposes reusing internal/store/bindings.go's
binding_dispatches at-most-once ledger shape (INSERT OR IGNORE +
sentinel error) rather than a new mechanism. Caught two real gaps
while drafting, both stated honestly rather than glossed over: (1)
t2db.15's shipped Playbook struct has no ID/Version to key a ledger
on -- Binding gets its identity from being a DB row, a playbook is
just a loaded file; (2) DispatchInput is a task-label trigger (same
vocabulary as workflow.Route()), NOT a webhook-capture trigger --
captured_events.id, the first instinct, does not apply to what
shipped, and DispatchInput doesn't yet carry any task identity to
key on either. Both are named as concrete prerequisites for whoever
implements this, not silently assumed solved.
Not marked as settled -- the status lines say "awaiting Sam's sign-off"
explicitly, matching the process this doc already used for the CEL
decision.
Self-review caught a real architecture bug in a doc I'd just written:
organisation.md's target structure moves forge/ under
internal/infrastructure/forge/; today's internal/forge is a flat,
unmigrated legacy package. A new internal/domain/eda package depending
on it directly would create a domain-to-infrastructure dependency that
breaks the moment forge migrates -- the same trap the workflow domain
package already solved for itself via its own narrow Forger interface
(CloseIssue/CreatePR/LinkBranch, already exactly the three proposed
operations), already satisfied by the daemon's real forge client today.
Depend on workflow.Forger, not internal/forge.
Investigation for t2db.19. Forge is ready to design: internal/forge.Forge
is already a typed, general-purpose interface with real implementations
(GitHub/Gitea) -- native-Go-by-name, no Yaegi/Module detour needed.
close-issue/link-branch are the safe first-slice operations; create-pr
is deferred (harder idempotency shape than a single-call operation).
Corrects the crew investigation's assumption about Channel: verified
directly that channels.Channel has no Send capability at all (only
Name/Start/Stop + config validation). The only generic outbound
mechanism in the codebase is the single-destination Notify webhook.
Real per-channel sending (telegramApprover) is deliberately
conversation-scoped, not a reusable registry lookup -- a documented
precedent to prevent reading a shared bot handle across chats, which
doesn't transfer to a playbook trigger with no chat turn to anchor to.
Flags two materially different things "Channel action" could mean and
recommends Sam decide before any Channel design work starts, rather
than guessing.
Seventh slice of docs/prds/eda-playbook-engine.md (t2db.15), consuming
t2db.14's expr package: the rich trigger+actions playbook document and
the coordinator that dispatches it.
- internal/domain/eda/playbook: Load(dir) reads *.yaml/*.yml playbook
documents (trigger + exactly one workflow-kind action + optional CEL
when), validating the HARD BOUNDARY at load: a playbook with 2+ actions
or a non-workflow action position is a reported load failure --
multi-action and Module/Channel/Forge actions stay blocked on the
unresolved execution-time gaps. Any malformed YAML, invalid trigger,
missing workflow name, or when compile failure fails the WHOLE load
(reject-at-load, same shape as routing collisions); a missing dir is an
empty store. Trigger reuses the existing workintake kind/label
vocabulary (no second label-matching mechanism). Dispatch matches
trigger, evaluates when (CEL, event context with actions: {} -- no
prior actions in single-action playbooks), and returns the named
workflow from the registry via the same lookup Route() uses -- no
duplicated dispatch logic. when eval error follows the resolved doc's
J3: false, skip, caller logs.
- Store.Dispatch(reg, DispatchInput) is the coordinator entrypoint; input
carries Labels/Kind/Event. Production task intake wiring
(daemon.go/pollNATS/publishTask) is explicitly NOT in this ticket -- a
follow-up; proven end to end via direct tests plus the shipped example
(examples/eda-playbooks/bug-tdd.yaml) loaded and dispatched through the
real path.
- Config: EDAPlaybookDir (eda_playbook_dir), documented as DISTINCT from
PlaybookDirs (flat binding files) -- a reader cannot confuse the two.
- Bootstrap: playbook.Load wired in loadWorkflows, log-and-abort on
failure matching every prior slice; nonexistent dir is an empty store.
- workflow.Route(), workflowForLabels, and the t2db.9-.12 binding loaders
are UNTOUCHED (verified: their full test suites pass, zero regressions).
Also carries small lint cleanups on t2db.13/.14 code flagged by the gate
run: expr Eval no longer type-asserts to ref.Val (Eval returns ref.Val
directly in v0.32.0; cel-go's own Eval wraps evaluation in recover --
verified in source); module decodeLogArgs extracted to clear the nestif
finding. golangci-lint: 0 issues.
Tests (10): single-action round trip, when-false skip, 2-action load
failure, non-workflow position load failure, when compile failure drops
playbook, empty trigger load failure, trigger mismatch skip, no-when
match, one-invalid-file fails whole load, missing dir empty store, plus
the shipped example load+dispatch. task check clean (113/113 UI, exit 0).
CEL (cel.dev/cel-go, pinned v0.32.0) is the single expression mechanism
covering both an action's `when` condition and its `args` values,
evaluated against a read-only context (`event`, `actions.<id>.result`).
Rejects the custom-gate precedent (Yaegi-in-YAML) as inverting the
design's own "YAML is data, Yaegi is logic" premise. Expressions
compile/type-check at playbook load, consistent with the existing
collision-handling reject-at-load rule; generated Module Result schemas
become CEL type declarations so result-path typos reject at load too.
Vetted against expr-lang/expr, gval, govaluate (archived), starlark-go:
CEL wins on structural safety (non-Turing-complete, CostLimit-bounded,
error values not panics, zero security advisories on record) despite
the largest binary cost (+13MB) of the candidates -- accepted because
the alternative is re-implementing CEL's type-checker on a bespoke
grammar for the same guarantee.
Sign-off (Sam, 2026-09-03): all judgment calls (J1-J5) accepted as
proposed, including J2's per-value CEL-literal quoting cost and the
+13MB binary size trade.
Cross-references in module-position.md updated to point at this
resolution instead of citing open question 1 as unresolved.