Review fixes for PR #876. The production fix is unchanged; this reworks only
the test.
- Bound the wait for the handler-start signal and select on the request
goroutine's error and on an early serve() exit, so a request that never
reaches the handler fails promptly instead of hanging until the package-wide
timeout.
- Restructure into a table, per AGENTS.md:256 / CLAUDE.md:256 ("table-driven
tests against target behaviour"): a request that drains within
ShutdownTimeout returns nil, and a request still in flight when it elapses is
force-closed and still returns nil.
The overrun row was verified to fail against the previous
"return server.Shutdown(shutdownCtx)" and to pass against the approved
force-close. Both rows hold the request in flight deterministically, so no case
depends on machine load.
The per-identity sweep skipped the root forge and root repo list whenever
[[identities]] was configured, on the reasoning that Run never polls them
there. Polling is not the only way a task reaches a repo: dispatchBinding
enqueues with an empty identity, resolveBindingRepo falls back to the root
repo list, and forgeFor/repoFor resolve an empty identity to the root forge
and root repos. Root targets stay reachable in multi-identity mode, so they
stay worth verifying at boot.
Collapse both sweeps into one sweepAccess path over the root plus every
identity. Each forge is swept in its own goroutine under its own deadline:
Startup gates the gateways and the run loop and a forge client carries no
request deadline, so warning on a failed sweep isolated a failing sibling
but not a stalled one.
Test is table-driven over single-identity, multi-identity, and an identity
with no repos.
Message.Sender's doc comment asserted "role discrimination uses Role, never this
field", which the code contradicts: at the gateway wire boundary Role is
deliberately dropped and rebuilt from Sender via RoleForSender, and the wire
carries no role field at all.
The comment was wrong, not the code. gatewayrpc already documents the design
(values.go:28, server.go:152 -- "The wire carries no role; both sides derive from
... messaging.RoleForSender"), and RoleForSender's own comment states the rule.
Only the Sender comment disagreed, so it is corrected to say that Role is
authoritative in-process while Sender is preserved for the wire reconstruction,
history search, and transcript rendering.
Resolves .local/issue-tracker messaging-2. Doc-only: no behaviour change.
The gate failed intermittently with "task: Failed to run task \"test\": exit
status 1" and a tailed log that hid the failing package. The package was
cmd/archie-ui, which sorts before internal/logging and so never appeared in the
visible tail.
Cause: serve() returned the error from server.Shutdown, which is
context.DeadlineExceeded whenever a request is still draining when
ShutdownTimeout elapses. That converted a normal load-induced overrun into a
non-zero process exit, and TestUIProcessServesTheDashboardAgainstLiveDependencies
asserts a clean exit after SIGTERM.
Fix at the producer, in serve(): on overrun, force-close the remaining
connections and report a clean shutdown. No timeout is lengthened, no retry,
skip or -p 1 is added, and the smoke test's assertion is untouched.
Reproduced under parallel build load: -count=30 on the suspect test produced the
exact shutdown-deadline signature once; after the fix, 30/30 pass with zero
occurrences. The new test drives the deadline path deterministically by holding
a request in flight rather than relying on machine load.
archie.reaction.* had no matching stream. bootstrap.go:501-502 bound only
ARCHIE_TASKS to archie.task.> under WorkQueuePolicy, so any publish to a
reaction subject made js.PublishMsg fail and the publisher saw a publish error
-- the reason a previously landed reaction producer would have answered HTTP 500
on every webhook delivery.
ARCHIE_TASKS must stay WorkQueuePolicy: under it a second consumer on an
overlapping filter subject silently receives nothing, which is the trap recorded
in CLAUDE.md. Reactions need the opposite property, so they get a second stream:
- workintake.SubjectReactionWildcard ("archie.reaction.>")
- nats.DefaultReactionStreamName ("ARCHIE_REACTIONS")
- nats.FanOutRetention(), a pointer helper so composition can select
LimitsPolicy without importing the NATS SDK, since nil Retention already means
WorkQueuePolicy and the zero value (LimitsPolicy) is a valid explicit choice
- a second nats.Connect in connectNATS carrying that stream, closed on failure
and registered for shutdown cleanup
Red-then-green: TestConnectNATSCreatesReactionStream failed with "publish to
archie.reaction.* = nats: no response from stream, want it to land in
ARCHIE_REACTIONS" before the stream existed.
Step 1 of docs/prds/pr-review-remediation.md (bead archie-core-8li9.1).
daemon.Startup ran the invitation sweep and push verification only against the
root forge and Cfg().Repos. In multi-identity mode Run branches to
runIdentities, where each identity polls its own forge and its own repo list --
so per-identity invitations were never accepted and per-identity repos were
never push-verified. A task from those repos failed later at dispatch instead of
warning at boot.
Startup now branches on len(d.Identities) and sweeps each identity through
sweepIdentity, which reuses id.Forge and id.Repos -- the same IdentityRunner
fields runIdentities and pollForIdentity already iterate, so there is no second
identity-to-forge mapping. One identity's forge outage cannot abort a sibling's
sweep: failures are logged as warnings, matching Run's stated failure-isolation
intent.
Red-then-green: TestStartupSweepsEveryIdentityForgeAndRepos failed with
"identity one AcceptInvitations = 0, want 1" (and both identities' repos empty)
before the change.
/restart could never work in production. boot.setupGateways captured the
Telegram adapter's restart callback into boot.restartTelegram, a field no code
ever read, so gateway.Router.Restart was nil in every composition:
handleRestartAdapter always answered "not configured" and LocalChatAdapter's
snapshot always reported RestartAvailable: false.
Fix at the producer: buildTelegramRouter assigns Router.Restart directly from
the adapter it already holds. The dead field and the telegramSetup.RegisterRestart
indirection are deleted rather than kept alive.
Red-then-green: TestBuildTelegramRouterWiresRestartCallback failed with
"router.Restart = nil, want the telegram adapter restart callback wired into the
router" before the change. TestBuildTelegramRouterRestartUnconfigured pins the
unchanged no-adapter behaviour, including the not-configured reply.
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
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.
The selection criteria alone left workflow optional and defaulted an omitted
or unrecognised value to implement, so a decide call could still skip the
decision and send an unsettled capability straight to the builder.
Omission is now a retryable rejection: CaptureTool gains RequiredWhenTrue, a
conditional requirement a flat RequiredFields entry cannot express, because
the close-without-change branch has no workflow to name and must not be made
to invent one. A rejected call is not recorded, so it does not consume
MaxCalls and the model retries with the field.
A value outside the enum now fails the stage rather than degrading to
implement: reaching OnResult with one means the model ignored its own schema.
Splits validateCaptureArgs into per-constraint checks (cyclop) and carries
the regenerated contracts.json.
The classify stage picked between implement, tdd and feasibility with no
stated criteria: the mission spent its guidance on needs_code_change and the
schema said only 'Which workflow fits best', with implement as the free
default for an omitted or unrecognised answer. Issue 813 was classified
implement on that basis.
Both surfaces now state what each workflow is for and say not to pick
implement merely because nothing else obviously fits. The mission moves to a
named triageMission so a test can assert the criteria reach the model.
Closes archie-core-s5ys
labelKinds is keyed on bare strings, and this repo namespaces its labels
(type::feature, priority::medium), so KindsForLabels matched nothing and
every issue fell through kind routing to Route's triage fallback. Kind
routing has therefore never fired here: issue 813, a type::feature that
defaultKindWorkflows binds to feasibility, reached implement instead.
Labels now resolve to the value after the last '::'. The namespace is not
checked: bug/feature/bootstrap is specific enough that a label ending in one
means that kind whatever the tracker files it under.
Closes archie-core-tjoc
Timer.Stop cannot unwind a max-uptime callback that has already begun, so
cancelling still let the reaper and Release both stop and remove the same
container, which is the duplicate teardown and the misleading 'No such
container' warnings this was meant to remove.
Teardown is now claimed once per container: whichever of the two gets there
first talks to Docker and the loser skips to its own bookkeeping. Release
still claims after the grace period, so MaxUptime keeps biting during it.
Also table-drives the event pump priming cases, per the repo's test directive.
The reaper was cancelled at the top of Release, before the grace-period
sleep, which let a container outlive MaxUptime by GracePeriod. MaxUptime is
documented as a cap from creation enforced regardless of task state, and a
grace period is task state, so the cancel belongs after the sleep.
Also asserts the disarmed reaper directly rather than only inferring it from
the absence of later Docker calls.
The timer stayed armed after Release removed the container, so an hour later
it stopped and removed an ID Docker had already forgotten and logged two
warnings that read like a failed teardown.
archie-ui binds before archie-state-store is guaranteed to be listening, so
the first prime is routinely refused. PumpEvents returned on that error, which
left the activity feed history-only for the life of the process. Prime now
retries with capped backoff and gives up only when the context ends.
Orders archie-ui.service after archie-state-store.service as well, which
narrows the window without closing it: After= sequences the start, it does
not wait for the listener.
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
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.
printf '%s\\n' emitted the literal characters backslash-n, which
archie-update-check's release-version check rejects, so every managed-agent
update left the installed agent version reported as unknown.
Both gRPC listeners took their bind address from a -listen flag default alone,
with no config key. The port a service binds and the port its clients dial were
therefore two separate facts -- the flag default, and [services.<name>].target --
with nothing keeping them in step.
On a host that already owned the default the effect read as a code fault rather
than a port collision: the store died with "bind: address already in use" while
every client reported "state store: connection error ... error reading server
preface: EOF". Cockpit binds 9090 by default, so this is not hypothetical.
Verifying the dashboard on such a host needed a hand-written overlay plus a
matching -listen, two things to keep in step by hand.
- [services.state].listen and [services.gateway].listen now name the bind
address. Precedence is -listen, then config, then a default applied by the
loader. An empty result is a startup ERROR, never a fallback: net.Listen reads
"" as "any free port", so defaulting there would bind the service somewhere no
client looks and still report success.
- Both flag defaults become "" so configuration can win, mirroring how archie-ui
already prefers [web].listen over its flag.
- Gateway listen defaults to the same constant as the gateway target, so a
default deployment's client and server cannot drift onto different ports.
[services.state].target still has no default: an empty target stays a startup
error in the daemon and gateway, which no longer serve a local store.
- ServiceConnection gains the field. Its doc now says clients read only Target
and TargetToken, and Listen belongs to the process that owns the service --
the previous wording claimed the struct starts no listeners while carrying one.
- deployments/dev.toml states each port once, beside the target it must match, so
`task dev` is retargetable on a host that owns 9090 by editing one overlay.
Tests. Unit: config defaults, explicit values, and precedence. Process: the
existing real-process smoke test now takes its listen from configuration instead
of -listen, so the end-to-end wiring is proven by the test that already starts
the binary, with no extra process. Both were verified load-bearing by mutation --
inverting the precedence fails the unit test, and making the app layer ignore
config fails the process test with "state: no listen address".
Verified: task check exit 0. Also documented in config.example.toml, the
configuration architecture table, and the `task dev` summary.
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.
The events table had no attempt column, so two attempts of the same task were
indistinguishable: a retried task's stage events interleaved into one timeline and
nothing could say which run produced a given result.
- events gains an `attempt` column through the existing presence-gated
migrateTasks loop rather than a version bump, so user_version stays 3 and an
existing archie.db is migrated in place. A legacy-database test builds the
pre-change schema and proves both that existing rows survive unattributed
(attempt = 0) and that a new value round-trips.
- Event.attempt = 11 and ReadTaskLogRequest.stage = 9 are field additions to
existing messages: no new RPC, no new table, and no change to any canonical error
message that crosses the state-store wire.
- Every task event the workflow engine emits now carries the attempt. Producers
that have no attempt yet (task_queued, binding_dispatch_failure) stay
unattributed rather than guessing one.
- Changed files are captured as a durable changes_captured event at commit and push
time, reusing the existing three-dot diff primitive: paths from FilePatches(),
counts from Stats(), base_sha recorded as the merge base actually diffed rather
than the base tip, a 200-file cap with totals kept complete. Consumption goes
through an unexported optional interface so workflow.Trees -- the yaegi capability
surface for interpreted stage plugins -- is not widened. A capture is also taken
once the pull request exists, so the capture can link it.
- The per-attempt configuration is captured as a durable config_captured event
carrying the non-secret config.TaskConfig, instead of a new table plus two new
state-store RPCs: events are already this system's per-attempt provenance stream,
so a table would have given one feature two provenance mechanisms. Redaction is
proven against canary secrets. Measured payload: 539 bytes typical, 2333 bytes at
20 models.
- Captures carry a schema marker and are refused unless their key set matches the
declared payload shape, so drift surfaces as "recorded but could not be read"
rather than as a capture of zeroes.
- Three read endpoints serve the attempt rail, the changed-file captures and a raw
debug view, mapping to UI-owned response types rather than dumping store types.
- The task-log read gains a stage filter, bound to the stage logger for that
stage's own lines; agent and tool output records no stage.
A task-scoped grant may already insert events on its own task, so this provenance
is exactly as trustworthy as the rest of that task's event stream. That limit is
documented rather than papered over.
Add two field-only extensions to the State Store contract, no new message
and no new RPC: Event.attempt (11) gives every task event an attempt key,
and ReadTaskLogRequest.stage (9) lets a log read be scoped to one stage.
Generated stubs regenerated with tools/proto.sh and committed as LAW so
proto:check, which diffs the working tree against the index, can pass.
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.
internal/tools/builtin.RegisterBuiltins has always accepted a GrepIndex and
nothing ever passed one, so every grep ran the direct walk no matter what
[indexing] was set to. internal/indexing was fully implemented and tested
with zero production callers, and internal/config decoded IndexingConfig into
nothing. Two halves of one defect.
The composition root now builds an indexing.Manager and hands it to the
workspace tool provider, which forwards it to RegisterBuiltins. deadcode
confirms the result rather than the commit message asserting it: unreachable
functions drop from 88 to 73, and all 15 internal/indexing entries are gone.
Failure degrades rather than propagates. A manager that cannot build logs a
warning and grep keeps its direct walk, which is exactly what it did before
this was wired. An accelerator must never stop the daemon starting.
The context is detached with WithoutCancel rather than replaced with
Background: the index build's lifetime is the process, while the gateway
path's boot context is cancelled once startup returns, so inheriting
cancellation would kill the build mid-flight. Background would have satisfied
the linter too, but would silently drop the caller's context values, so
registerTools now takes the context its callers already had.
internal/agentexec's RegisterBuiltins call is deliberately left alone. It
registers builtins only to harvest their names for a plugin tool-name
collision check and never executes them, so there is no grep there to
accelerate.
Two fixes to the published site, both about not shipping something false.
exclude_docs held back prds/ but let ui-service-boundary.md through, because
architecture/migration-decisions.md links to it three times. That PRD in turn
links to service-decomposition.md and config-schema.md, so the exclusion was
still producing two dead links on the published site. Letting those two
through closes the chain: the build now reports no excluded-link references
at all.
generated-documentation.md's "Step 9: CI" said no workflow builds, checks or
publishes documentation. Adding .github/workflows/docs.yml made the first
clause false. Restated to say what that workflow does and, more importantly,
what it deliberately does not: it does not run docsgen, regenerate
contracts.json, or publish. Generated-artifact drift is still gated locally by
task check, which is the split that section exists to protect, since a CI job
that regenerated output could paper over uncommitted differences rather than
fail on them.
Build-only. The site deploys from the Ansible control node via the
vectislabs.automation docs_site role against nebula, so CI has nothing to
publish; what it catches is a docs change that will not build at all, before
it reaches a deploy.
Path-filtered to docs sources, so the ~600 commits a month that touch no
documentation do not run it.
Adds an mkdocs.yml, a landing page, and `task docs:site` / `task docs:serve`.
Deliberately hosting-agnostic: MkDocs is the same input Backstage TechDocs
consumes, so choosing where this lands later costs nothing.
exclude_docs holds back four subtrees, since everything under docs/ would
otherwise be published. archive/ is superseded design and would compete with
the current architecture for a reader's attention; inspiration/ discusses
other products by name; prds/ are open decisions rather than settled design;
github-token.md is credential setup. One PRD is let back through because
architecture/migration-decisions.md links to it three times, and a page
excluded out from under a live link is just a 404 with extra steps.
No nav block. MkDocs derives it from the directory layout, so a new page
under docs/architecture/ publishes without a second edit, and there is no
hand-maintained tree to drift against the repository.
Builds --strict, so a dead internal link fails rather than ships.
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.
All three Greptile findings were valid against the code; each is fixed at its
cause rather than at the symptom, and each fix is covered by a test that
fails when the fix is reverted.
**Check could silently write.** `check` was matched only as the first
argument, and leftover positional arguments were never inspected. So
`docsgen --repo-root .. check` — and any misspelled subcommand — fell
through to the write path and overwrote the artifact the check promises not
to touch. That is the exact guarantee the mode exists to provide, so the
failure was silent and in the wrong direction.
Extracted argument handling into a testable `parseOptions` and made a leftover
positional argument an error with usage text. Switched the flag set from
`ExitOnError` to `ContinueOnError` so the error surfaces as a value rather
than a process exit, which is what makes it testable.
**Obsolete detection claimed files it does not own.** It treated every
sibling `.json` as docsgen's and reported it obsolete, so checking an
artifact in a mixed-use directory produced a false stale result, and the
documented target layout — which anticipates further named artifacts in
`docs/data/generated/` (catalog.json, AsyncAPI output) — would have been
reported stale as soon as a second artifact legitimately existed.
Ownership is now declared rather than inferred: `generatedArtifacts` maps each
directory docsgen owns end-to-end to the names it produces there, and a
directory docsgen does not own is never judged. A new unit test pins both
halves — the orphan inside an owned directory is still caught, and a foreign
`.json` in an arbitrary `--out` directory is not.
**Provenance traversal stopped at one level.** Refs were walked only inside
the top-level contract schemas, so a definition reachable solely through
another definition resolved to "no authoritative definition found" — the
diagnostic lying about the code it points at. Replaced the single pass with a
breadth-first walk that follows discovered definitions transitively, seeded
with every published contract first so a definition reachable from several
contracts is attributed to the alphabetically first rather than to whichever
the walk happened to reach. `walkSchemaRefs` now iterates map keys in sorted
order for the same reason.
`schemaProvenance` takes its roots as a parameter, which is what makes the
transitive case testable without real types.
Verified by mutation: with each fix reverted in turn, its test fails —
`parseOptions(["--repo-root" ".." "check"]) returned nil error`,
`obsoleteArtifacts() = [...someone-elses.json is obsolete...]`, and
`provenance[Leaf] = ""`. Control run passes unmutated, and the file is
byte-identical after restoration.
Also confirmed end to end that the previously silent invocation now exits
non-zero with usage instead of writing, and that the committed artifact is
untouched by it.
`task check`: exit 0, 0 failures.
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.
`docs/data/generated/contracts.json` sat stale since 4b340d2b with nothing
to notice: no task, no test, and no CI step regenerates or compares it, so
the committed contract reference quietly drifted from the Go types it
claims to describe. It was only found by hand-running the generator.
Implements Step 6 of docs/architecture/generated-documentation.md, which
already specified this command and closed the gap filed in
docs/prds/contract-conformance-audit.md ("`docsgen check` is documented and
does not exist"):
1. generates into a temporary directory;
2. normalizes line endings;
3. compares the schema trees with the committed output;
4. reports missing, changed, and obsolete files;
5. names the authoritative definition behind each mismatch;
6. exits non-zero without modifying the working tree.
The check never writes to the working tree, so the author applies the
regenerated bytes rather than the gate silently doing it. That is why this
is a `check` and not a CI auto-update: the code change that shifted the
contract surface should be reviewed with its regenerated artifact in one
commit, and a bot commit would bless an unintended contract change with no
reviewer ever seeing it. Step 9 states the same prohibition directly.
Diagnostics name the Go type, so a failure says where to look:
docs/data/generated/contracts.json is stale; regenerate it with:
go -C tools run ./docsgen --repo-root ..
schema "AgentExecutionResult" changed (authoritative definition:
github.com/samcharles93/archie-core/internal/agentexec.Result)
schema "MediaAttachment" changed (authoritative definition:
reached from .../internal/gateway.MessageEvent)
Nested definitions are attributed through the published contract that
references them, iterated in sorted order so the diagnostic is
deterministic when several contracts share a definition.
Usage: `go -C tools run ./docsgen check --repo-root ..`, plus the existing
`--out` to compare an arbitrary artifact.
Reuses the write path rather than reimplementing encoding, so check and
generate cannot disagree about the expected bytes.
Tests cover: the committed artifact is current (the regression guard that
would have caught this), changed/removed/missing/obsolete detection, and
that a failing check leaves the artifact's bytes, mode, and directory
contents untouched.
`task docs:check` wiring into `task check` is deliberately not in this
commit: Taskfile.yml is being edited concurrently in this working tree.
Verified with `task check` (green).
All ten `archie-*` skills carried claims that no longer matched the
checkout. Re-verified each against code, git history, and the shipped
configuration, then corrected the drift.
Structural changes the skills had not caught up with:
- Composition root moved: `cmd/archied/main.go` is a ~30-line dispatcher
into `internal/app/archied.Run()` with wiring in `bootstrap.go`. The
skills still described `cmd/archied` as the wiring site, which also
silently zeroed the diagnostics delivery snapshot.
- Config decoding moved out of `internal/config` into
`internal/infrastructure/configuration`. `config.Load` / `config.LoadDir`
no longer exist; the loader is `configuration.New` + `Loader.Resolve`.
- Task contract moved to `internal/domain/storecontract`, with
`internal/store/interface.go` holding aliases only. The task type is
`internal/domain/workflow/task.Task`.
- `internal/workflow` became `internal/domain/workflow`; `internal/storerpc`
became gRPC `internal/infrastructure/staterpc`; `internal/policy` does not
exist.
- `Store.Transition` now guards on `from` and writes status plus history in
one transaction. Three skills still described the old non-atomic behavior
as current and open.
- `internal/domain/{messaging,workflow,workintake}`, `internal/eventbus`,
`internal/app`, and `internal/infrastructure` now exist.
`internal/domain/{agent,identity}` and `internal/policy` remain target-only.
Tooling and environment facts:
- Go 1.27.0 (root and tools modules), golangci-lint 2.13.2, staticcheck
2026.2.1; snapshot dates and HEAD moved to 2026-09-18 / 2e1e1549.
- Re-ran the bundled diagnostics and re-baselined its snapshot table.
Confirmed 78.6% store coverage, a clean race run, and zero dupl findings.
- Corrected the claim that no `.dockerignore` exists; it does.
- Replaced skill script paths that pointed at the untracked `.claude/skills`
symlink with the canonical tracked `.agents/skills` location.
- Fixed the delivery-snapshot comment's wrong commit hash for the Gitea
workflow removal (dd9bddc2, not e539048).
Findings the verification closed:
- The VitePress site and `.github/workflows/docs.yml` were removed
(84b32694); the Gitea workflow was dropped (dd9bddc2).
- The changelog `vX.Y.Z`-vs-`X.Y.Z` contradiction is settled, not open: both
changelogs and the CI gate agree on `## [<version>]`.
- Tracked `docs/node_modules` and the skill-script test regression are
settled, not current.
- The six unmerged `origin/fix/*` and `origin/feat/*` candidate branches no
longer exist.
Also regenerates `docs/data/generated/contracts.json`, which the
verification found stale since 4b340d2b: docsgen emits 11 schemas now, and
`MediaAttachment.raw` plus an `AgentExecutionResult.required` field were
missing. `cmp` passes after regeneration.
Verified with `task check` (green).
The agent-side half of the same gap. A stage failure already logged
"stage failed -- parking" before parking, but a run whose OUTCOME was parked
(a review that could not run, a workflow that ended with no outcome) reached
the timeline as a KindParked event and the store as park_reason and never
the log an operator downloads.
park is the one place a park's reason is final, so it is now the one place
that logs it; the stage-failure branch no longer logs its own near-copy, and
the stage names itself inside the reason. The entry carries the stage as a
field so nothing is lost by dropping the duplicate line.
observability.md's "Implemented design" section documented the container's
system-log path as though it were the only source of task-log content; it
now records the daemon's and the workflow's own park writers, including why
the entry follows the transition rather than preceding it.
An operator who asks "why did task 1 attempt 3 park?" and downloads that
attempt's log got a zero-byte file, because nothing daemon-side wrote to a
task log at all: the container's system-log subscription was the only
writer, so an attempt that parked before any container produced output --
a worktree prepare failure, an unavailable worker, a taskrun error -- left
the file the sink had created empty and the reason only in the daemon-wide
log.
Both park paths now write the reason into that attempt's sink. The entry is
written after the guarded transition lands, so a park another actor won
does not leave a log claiming an outcome the task board contradicts -- the
same race the parked event is already withheld for.
Write built its own context.Background() for the handler call, which meant
any new caller with a context to offer could not hand it over. Taking the
caller's context is what the next commit's park-reason writer needs, and it
is what contextcheck requires of a daemon-side writer.
No behaviour change: the context is used for the handler's own attribute
extraction and never consulted for cancellation -- a park is recorded at
exactly the moment a run's context has been cancelled, so a cancelled
context must not suppress the entry.
A container run only restored ownership of the bind-mounted worktree on the
CommitAll/Push success path (archie-core#520). The agent runs as root inside
the container, so every other way a run can end -- a gate failure that parks
the task, a stage error, an early return -- left the worktree owned by UID 0
on the host. The daemon is the process that later cleans and resets that
directory as its own non-root user, and it cannot even unlink inside a
root-owned directory, so the next attempt failed before it could start no
matter what the worktree refresh did.
runTask now defers the same reconcileOwnership the commit and push paths
already call, so it runs at every exit. The retry recoveries in worktree
package cannot fix this from the daemon side: a non-root process cannot
chown, and removing the directory needs write access to it.
Observed through a supplementary group -- a non-root process may move a file
it owns into a group it is a member of -- so the test proves the chown ran
without needing root.
Residual, filed as archie-core-zcg8: a container that is SIGKILLed never
runs this defer.
A retry after any attempt that did not commit failed with
worktree prepare failed: checkout branch <branch>:
a branch named "refs/heads/<branch>" already exists
on a branch that was never the problem. refresh inferred "the branch does
not exist yet" from a failed checkout and reported whatever the Create
fallback then returned, so the real failure was replaced by a false one --
and the operator had no way to tell that the park reason was fiction.
The real failure, reproduced: a stage running in the container can leave a
path whose TYPE contradicts the tree refresh resets onto -- a directory
where the base tree has a file, or a file where the base tree has a
directory. go-git's hard reset cannot write over that contradiction and
fails with `openat <path>: is a directory` / `not a directory`, which is
exactly the failure the Create fallback then relabelled. Retry could not
recover from it, and a second path of the same class (a branch removed
while HEAD still pointed at it) failed with "reference not found".
refresh now clears the worktree against the tree it is resetting ONTO
before it checks anything out, which removes exactly those conflicts -- an
on-disk directory the tree declares as a file is untracked, and so is a
file the tree declares as a directory -- and resolves the branch's
existence from the reference store instead of inferring it. Resume gets the
same treatment, so the remediate path cannot fail the same way.
This is the third fix to this function (Force in 37792c9e was the second),
so the checkout/reset/clean sequence is rewritten rather than patched again.
Every client method that decodes a repeated proto field goes through
mapValues, which returned nil for nil input. Protobuf decodes an empty
repeated field to nil, so an empty collection crossed the wire as JSON null
rather than an empty list: the field's type depended on whether it happened
to have contents, and the wire path disagreed with the local path, which
normalises its own slices.
This is the nil-slice class the contract-conformance audit deferred, arriving
by the route its own revisit condition names -- a handler that can produce
nil. The audit checked the webui handlers (clean, as it said) and did not
cover the wire mapping added afterwards, so the regressed field was the new
one: ReadTaskLog's components, observed as "components": null from the live
dashboard.
mapValues now returns []B{} for empty input, which fixes the class once at
the mapping helper rather than at each of its 36 call sites -- none of them
compares the result to nil, so nothing depended on the old behaviour.
TaskLog also normalises components, which is read straight from the proto
rather than through mapValues.
Red first: the test drives the existing local/grpc matrix and asserts the
marshalled JSON, so it fails on a null collection without depending on which
path is under test. Both collections are exercised empty -- entries present
with components empty, and a log file that exists with no lines -- because
the first shape alone leaves the entries side untested. Verified by mutation:
restoring the nil return fails it on "entries marshalled to null".