Files
archie/Taskfile.yml
T
sam c29cdf6f79 feat(workflow): post line-anchored review comments with suggested fixes (#891)
* feat(workflow): post line-anchored review comments with suggested fixes

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

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

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

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

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

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

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

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

* fix(build): drop the Dockerfile pin assertion

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Two findings from the review of q9au.

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

Suggestion was documented single-line only, because GitHub applies a suggestion
fence up to its first line and a multi-line replacement would silently corrupt
the file. Only the verdict was validated, so a multi-line suggestion reached the
renderer and posted as that truncated fence. Validate now rejects an embedded
newline, which makes record_finding refuse it with feedback the model can act on
instead of the reviewer discovering the corruption later.
2026-09-19 23:37:23 +10:00

423 lines
17 KiB
YAML

version: "3"
vars:
BIN_DIR: "bin"
tasks:
default:
desc: List available tasks
cmds:
- task --list
fmt:
desc: Format and fix Go source (gofumpt, go fix)
cmds:
# -extra must match the gofumpt formatter's extra-rules in
# .golangci.yml. Without it `task fmt` cannot produce what `task lint`
# demands -- e.g. func f(a int, b int) -> func f(a, b int) -- so a
# contributor has no command that satisfies the gate.
- gofumpt -extra -w .
- go fix ./...
proto:install:
desc: Install the pinned Buf and protobuf Go generators
cmds:
- bash tools/proto.sh install
proto:generate:
desc: Generate and format committed grpc-go service contracts
cmds:
- bash tools/proto.sh generate
proto:lint:
desc: Lint protobuf contracts and check compatibility with main
cmds:
- bash tools/proto.sh lint
proto:check:
desc: Regenerate contracts and reject uncommitted generated differences
cmds:
- bash tools/proto.sh check
docs:generate:
desc: Regenerate the committed contract reference from Archie-owned types
summary: |
Writes docs/data/generated/contracts.json. The output is committed, so
this dirties the tree deliberately: review the diff and commit it with
the code change that shifted the contract surface. Never hand-edit the
artifact.
-mod=readonly is mandatory on every `go -C tools` command; see
task test:tools for why.
cmds:
- go -C tools run -mod=readonly ./docsgen --repo-root ..
docs:check:
desc: Verify the committed contract reference matches Archie-owned types
summary: |
Implements Step 6 of docs/architecture/generated-documentation.md:
generates into a temporary directory, compares it with the committed
output, names the authoritative Go definition behind each mismatch, and
exits non-zero without modifying the working tree.
Fix a failure with `task docs:generate`, then commit the result in the
same commit as the code change that shifted the contract surface. This
checks rather than regenerates on purpose: a gate that silently rewrote
the artifact would bless an unintended contract change with no reviewer
ever seeing it, which Step 9 explicitly forbids.
cmds:
- go -C tools run -mod=readonly ./docsgen check --repo-root ..
vet:
desc: Run go vet
cmds:
- go vet ./...
lint:
desc: Run golangci-lint
cmds:
- golangci-lint run ./...
lint:playbooks:
desc: "Lint playbook binding dirs for collisions (standalone tool, cmd/archie-playbooks)"
summary: |
Runs the standalone playbook linter (archie-playbooks lint) against
./playbooks by default. It validates playbook YAML binding files
against the same loaders the daemon uses at startup, so a pre-merge
check can never disagree with runtime validation. Exit non-zero on
any collision / malformed file / invalid binding.
Lint a different set of directories directly:
go run ./cmd/archie-playbooks lint -dir ./a -dir ./b
cmds:
- go run ./cmd/archie-playbooks lint -dir ./playbooks
vuln:
desc: "Scan for known stdlib/dependency CVEs (govulncheck). Not part of task check: it needs network access to the vuln DB and is not build/test-blocking; run it explicitly or in CI."
cmds:
- govulncheck ./...
deadcode:
desc: "Report functions no shipped binary can reach (whole-program RTA from ./cmd/...). Not part of task check: it reports a standing backlog, so gating on it would fail every run until that backlog is zero."
summary: |
Answers "is this reachable in production", which no linter does:
golangci-lint's unused check is package-scoped, so anything exported
and called from a sibling package looks live even when no binary
reaches it.
Run via `go run ...@latest` deliberately. A locally installed 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".
Building it against the repo toolchain makes that failure impossible.
-test=false is the point of the report: a function reached only by its
own tests is not reachable in production.
Read the output in one direction only. RTA over-approximates what is
reachable, so "unreachable func" is sound and worth acting on, while
silence proves nothing: interface dispatch and any address-taken
function (every reflect.ValueOf entry in the *extract tables) is
assumed reachable whether or not it is ever called.
cmds:
- go run golang.org/x/tools/cmd/deadcode@latest -test=false ./cmd/...
reachaudit:
desc: "Classify unreachable code as tracked / untracked / dynamic (tools/reachaudit). Wraps task deadcode with provenance and tracker status."
summary: |
deadcode says a function is unreachable. reachaudit says whether that
is a known gap, a forgotten one, or an artifact of runtime loading
(yaegi, reflection) that must never be deleted.
Two report sections, because a dead whole package and a dead symbol
inside a live one are different failure modes: "unreachable-*" is a
package no shipped binary imports at all; "in-package-*" is a symbol
dead inside a package that IS shipped -- the ChatCourier/Dispatch
shape, where the feature is wired everywhere except its own call site.
Both carry the same tracked/untracked/dynamic classification.
--refresh re-runs the analysis. Without it the tool reuses
/tmp/reachaudit-deadcode-<sha>.txt with no staleness check beyond HEAD
and a dirty-tree check, which will happily report last week's tree
against today's code if HEAD hasn't moved.
--json PATH and --md PATH write the same findings as structured data or
a Markdown report, in addition to the terminal summary.
cmds:
- python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}}
docs:site:
desc: "Build the documentation site into ./site (MkDocs). --strict, so a dead internal link fails the build."
summary: |
Publishes docs/ minus the subtrees held back in mkdocs.yml's
exclude_docs. Requires mkdocs-material:
pip install --user mkdocs-material
Distinct from docs:check, which verifies the generated contract data
rather than the site.
cmds:
- mkdocs build --strict
docs:serve:
desc: "Serve the documentation site locally with live reload on :8000."
cmds:
- mkdocs serve
ui:deps:
desc: Install the dashboard's node dependencies (ui/node_modules is gitignored)
internal: true
dir: ui
cmds:
- npm install --no-audit --no-fund
ui:
desc: Build the dashboard into ui/dist (committed; the Go build embeds it)
dir: ui
deps: [ui:deps]
cmds:
- npm run build
test:ui:
desc: Run the dashboard's node tests (DOM-building primitives)
dir: ui
# Without this, a fresh clone fails the gate on a missing jsdom rather
# than a real test failure: ui/node_modules is gitignored and nothing
# else in `task check` installs it.
deps: [ui:deps]
cmds:
- npm test
dev:
desc: "Develop: archied live-reload + archie-gateway + archie-state-store + archie-ui + Vite HMR together. Open http://localhost:5173"
summary: |
Runs the dev loop in one terminal:
* air rebuilds and restarts archied on Go changes
* archie-gateway serves ChatContract on 127.0.0.1:8585 (archied
and archie-ui dial it; neither embeds a gateway)
* archie-state-store owns archie.db on 127.0.0.1:9090, loopback,
no token (deployments/dev.toml); archied,
archie-gateway and archie-ui dial it -- none owns
the DB in-process
(docs/prds/state-store-contract.md §12 step 7)
* archie-ui serves the dashboard on 127.0.0.1:8484 from the
embedded dist (deployments/dev.toml). After the
UI cutover (archie-core-8cda.5.4) archied runs no
dashboard listener: this is what :8484 is.
* vite serves the dashboard with hot reload on :5173,
proxying /api and /events through to archie-ui
on :8484
The gRPC ports come from [services.state].listen and [services.gateway].listen in
deployments/dev.toml, each paired with the target that dials it. Move them there
when the host already owns one: cockpit binds 9090 by default.
Open http://localhost:5173 -- not :8484. The Vite server is the one with
hot reload; :8484 serves the last built dist/ and will look stale.
Ctrl-C stops all five.
deps: [dev:daemon, dev:gateway, dev:state-store, dev:dashboard, dev:ui]
dev:daemon:
desc: archied only, live-reloading via air (prefer `task dev`)
cmds:
- air -build.args_bin="-config-overlay,deployments/dev.toml"
dev:dashboard:
desc: archie-ui only, no live-reload (prefer `task dev`)
cmds:
- go run ./cmd/archie-ui -config-overlay deployments/dev.toml
dev:state-store:
desc: archie-state-store only, no live-reload (prefer `task dev`)
cmds:
- go run ./cmd/archie-state-store -config-overlay deployments/dev.toml
dev:gateway:
desc: archie-gateway only, no live-reload (prefer `task dev`)
# The overlay carries [services.state].target, which archie-gateway
# requires (openStateStoreAdapter fails closed on an empty target).
# Without it `task dev` leaves the gateway dialling whatever the
# developer's installed config names, or unable to start at all, while
# archied, archie-ui and the state store all dial 127.0.0.1:9090.
cmds:
- go run ./cmd/archie-gateway -config-overlay deployments/dev.toml
dev:ui:
desc: Vite dev server only, expects archie-ui already running (prefer `task dev`)
dir: ui
cmds:
- npm install --no-audit --no-fund
- npm run dev
dev:mobile:
desc: Serve the dashboard on your LAN (token-protected) for phone viewing
summary: |
Starts archie-ui with a LAN-reachable [web] bind and a minted dashboard
token, printing the URL (LAN IP + token) and a QR code to scan. After
the UI cutover the dashboard is archie-ui's process: this task starts
archie-ui only. Run the daemon separately (task dev, or archied) for
actual archie operation -- two daemons sharing the bot identity would
double-poll the forge.
The frontend served is the embedded dist, so run `task ui` if you
changed the frontend. The token file is the path archied used to mint
before the cutover, so an existing phone setup keeps its token.
deps:
- ui
cmds:
- cmd: |
IP=$(hostname -I | awk '{print $1}')
TOKEN_FILE="${XDG_DATA_HOME:-$HOME/.local/share}/archie/web-token"
go run ./cmd/archie-ui -listen 0.0.0.0:8484 -token-file "$TOKEN_FILE" &
UI_PID=$!
sleep 2
TOKEN=$(cat "$TOKEN_FILE" 2>/dev/null)
URL="http://$IP:8484/?t=$TOKEN"
echo "Phone URL: $URL"
echo "$URL" | qrencode -t ANSIUTF8
trap "kill $UI_PID 2>/dev/null" EXIT
wait $UI_PID
build:
desc: Build archie services and agent binaries
# Version stamping used to live only in Dockerfile.archied, so any build
# from source -- including a host deployment -- reported "dev" for
# both components and /version was useless there. Derive the same
# -X values from the release tags so a source build is stamped too.
# git describe (without --abbrev=0) yields 1.7.0-2-gbb54786 when HEAD is
# past the tag, which is the honest answer for a mid-cycle build.
vars:
GATEWAY_VERSION:
sh: git describe --tags --match 'archied/v*' 2>/dev/null | sed 's|^archied/v||' || echo dev
RUNTIME_VERSION:
sh: git describe --tags --match 'archie/v*' 2>/dev/null | sed 's|^archie/v||' || echo dev
sources:
- "**/*.go"
- go.mod
- go.sum
generates:
- "{{.BIN_DIR}}/archied"
- "{{.BIN_DIR}}/archie-gateway"
- "{{.BIN_DIR}}/archie-state-store"
- "{{.BIN_DIR}}/archie-ui"
- "{{.BIN_DIR}}/archie-messaging"
- "{{.BIN_DIR}}/archie-agent"
cmds:
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archied ./cmd/archied
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-gateway ./cmd/archie-gateway
- go build -o {{.BIN_DIR}}/archie-state-store ./cmd/archie-state-store
- go build -o {{.BIN_DIR}}/archie-ui ./cmd/archie-ui
- go build -o {{.BIN_DIR}}/archie-messaging ./cmd/archie-messaging
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-agent ./cmd/archie-agent
test:
desc: Run the Go test suite
cmds:
- go test ./... -count=1
test:tools:
desc: Run the nested tools module suite, refusing to rewrite its go.mod
summary: |
tools/go.mod replaces the root module, so its build list must satisfy
the root module's requirements. When the root moves on, the tools module
goes stale and any plain go command there rewrites tools/go.mod and
tools/go.sum to catch up, leaving an unrelated dirty diff.
-mod=readonly is explicit because a developer's global GOFLAGS=-mod=mod
overrides the toolchain default and re-enables the silent rewrite.
Fix a failure here with: go -C tools mod tidy
cmds:
- go -C tools test -mod=readonly ./... -count=1
check:
desc: "Full quality gate: fmt, go fix, proto, docs, vet, lint, build, test, tools tests, ui tests"
cmds:
- task: fmt
- go fix ./...
- task: proto:lint
- task: proto:check
- task: docs:check
- task: vet
- task: lint
- task: build
- task: test
# The tools module is not covered by ./... from the root; without this
# its dependency drift is only ever discovered by a command that
# silently repairs it.
- task: test:tools
# The dashboard's suite runs here too. Left out of the gate it rots
# silently: nothing else executes it, so a broken DOM primitive ships.
- task: test:ui
contract:
desc: "Report contract conformance: declared surfaces, their consumers, and the drift between them"
summary: |
Walks every declared contract surface -- the two gRPC services, the
dashboard HTTP API -- and classifies each subject as consumed,
declared-unconsumed, undeclared, or a stale declaration.
ADVISORY, and deliberately NOT part of `task check`, matching
tools/reachaudit. The surfaces are discovered by scanning source text:
the .proto files, the adapter bodies that call the generated client, the
route registrations in internal/webui, and the path literals under
ui/src. That makes it useful for a periodic survey and unsafe as a gate
-- a rename or a reformat elsewhere in the tree can change its output
without anything being wrong, and it has already produced a batch of
false "unconsumed" readings once when the dashboard's request helper was
renamed.
Read the findings as a prompt to go and check, not as a verdict. To make
it fail on an undeclared or stale entry, pass --strict by hand:
go -C tools run ./contractaudit --repo-root .. --strict
See docs/prds/contract-conformance-audit.md.
cmds:
- go -C tools run ./contractaudit --repo-root ..
release:preview:
desc: "Show the release notes that would be generated (VERSION=1.2.0, or GATEWAY=/RUNTIME= to version the two components separately)"
cmds:
- tools/release.sh --gateway {{.GATEWAY | default .VERSION}} --runtime {{.RUNTIME | default .VERSION}} --dry-run
requires:
vars: [VERSION]
release:prepare:
desc: "Write the generated notes into the changelogs, uncommitted, for editing (VERSION=1.2.0)"
cmds:
- tools/release.sh --gateway {{.GATEWAY | default .VERSION}} --runtime {{.RUNTIME | default .VERSION}} --prepare
requires:
vars: [VERSION]
release:
desc: "Freeze the edited changelogs into a release commit and tags (VERSION=1.2.0). Run release:prepare first."
cmds:
- tools/release.sh --gateway {{.GATEWAY | default .VERSION}} --runtime {{.RUNTIME | default .VERSION}} --tag
requires:
vars: [VERSION]
clean:
desc: Remove build artifacts
cmds:
- rm -rf {{.BIN_DIR}}
docker-build:
desc: Build the archie-agent sandbox image
cmds:
- docker compose build agent
docker-up:
desc: Start the optional external NATS service via docker compose
cmds:
- docker compose up -d nats
docker-down:
desc: Stop the docker compose stack
cmds:
- docker compose down
docker-logs:
desc: Follow the NATS container logs
cmds:
- docker compose logs -f nats