Files
archie/Taskfile.yml
T
sam 66167571cb feat(tools): fail the gate when docs cite a path that no longer exists
docs/architecture is declared authoritative for settled design, so a page that
cites code which has moved actively misleads every session and every subagent
brief that reads it. Nothing in the gate compared a prose citation against the
tree: docsgen checks the contract schema against Go types, docsite checks
generated artifacts against their Markdown sources, prdlint checks PRD writing
style. All three verify internal consistency, so a page can describe a package
deleted months ago and every check stays green -- which is how a page describing
a removed system survives behind a hand-written "removed" banner.

Add tools/docdrift. It resolves every internal/... citation under docs/ against
the tree and fails on one that dangles, handling the shapes prose actually uses:
a package with a symbol (internal/config.Config), a test with its package
(internal/app/archieui/TestFoo), a file-shape template
(internal/webui/api_<concern>.go), and a Go package pattern (internal/...).
Generated artifacts are skipped so embedded page bodies are not double-counted.

The baseline is a burn-down list of the 48 citations already broken -- packages
that moved (internal/store, internal/memory, internal/nats) and ones never built
(internal/policy, the image and research capability docs). It is not a licence:
the check also fails when an allowlisted citation starts resolving again, so an
exemption cannot outlive its reason. Regenerate with `docdrift list`.

Wire it into `task check` as docs:drift.

Also correct AGENTS.md, which listed `policy` among the cross-cutting packages
sitting under internal/. No such package has ever existed in this tree; the
design is approved and unbuilt (docs/architecture/policy.md). That is exactly
the class of stale claim this check now catches.
2026-10-03 00:31:06 +10:00

369 lines
11 KiB
YAML

version: "3"
vars:
BIN_DIR: "bin"
tasks:
default:
desc: List available tasks
cmds:
- task --list
fmt:
desc: Fix and format Go source
cmds:
- go fix ./...
- golangci-lint fmt
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
db:generate:
desc: "Regenerate the sqlc query code from the schema and query files"
cmds:
- go -C tools tool sqlc generate -f {{.ROOT_DIR}}/internal/infrastructure/postgres/sqlc.yaml
db:check:
desc: "Regenerate the sqlc code and reject uncommitted generated differences"
cmds:
- task: db:generate
- git diff --exit-code -- internal/infrastructure/postgres/postgresdb
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
cmds:
- go -C tools run -mod=readonly ./docsgen --repo-root ..
docs:check:
desc: Verify the committed contract reference matches Archie-owned types
cmds:
- go -C tools run -mod=readonly ./docsgen check --repo-root ..
docs:prds:
desc: Reject session-bound writing in docs/prds
cmds:
- go -C tools run -mod=readonly ./prdlint --repo-root ..
docs:drift:
desc: Reject docs that cite a repository path which no longer exists
cmds:
- go -C tools run -mod=readonly ./docdrift check --repo-root ..
news:
desc: Regenerate the release data artifacts from the changelog
cmds:
- go -C tools run -mod=readonly ./newsgen --repo-root ..
news:check:
desc: Verify the committed release notes match the changelog
cmds:
- go -C tools run -mod=readonly ./newsgen check --repo-root ..
docs:artifact:
desc: Regenerate the canonical docs artifacts from the Markdown sources
cmds:
- go -C tools run -mod=readonly ./docsite --repo-root ..
docs:artifact:check:
desc: Verify the committed docs artifacts match the Markdown sources
cmds:
- go -C tools run -mod=readonly ./docsite check --repo-root ..
vet:
desc: Run go vet
cmds:
- go vet ./...
lint:
desc: Run golangci-lint
cmds:
- golangci-lint run ./...
- task: lint:tools
lint:tools:
desc: Run golangci-lint over the tools module
dir: tools
cmds:
- golangci-lint run ./...
lint:playbooks:
desc: Validate playbook bindings
cmds:
- go run ./cmd/archie-playbooks lint -dir ./playbooks
vuln:
desc: Scan for known vulnerabilities (requires network access)
cmds:
- govulncheck ./...
deadcode:
desc: Report unreachable production functions (advisory)
cmds:
- go run golang.org/x/tools/cmd/deadcode@latest -test=false ./cmd/...
reachaudit:
desc: Classify unreachable code against tracked work (advisory)
cmds:
- python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}}
ui:deps:
desc: Install dashboard dependencies
internal: true
# Parallel UI checks must share one dependency install.
run: once
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
ui:check:
desc: Rebuild the dashboard into a temporary directory and reject a stale ui/dist
deps: [ui:deps]
cmds:
- bash tools/uidist.sh check
test:ui:
desc: Test and type-check the dashboard
dir: ui
deps: [ui:deps]
cmds:
- npm test
- npm run typecheck
webhook:send:
desc: Send a test event to the dashboard's capture intake (--help for kinds)
cmds:
- bash tools/webhook-send.sh {{.CLI_ARGS}}
bench:prreview:
desc: Review or rescore the Martian benchmark (-- -review-model PROVIDER/MODEL -classification-model PROVIDER/MODEL; --help for flags)
cmds:
- go run ./cmd/archie-prbench {{.CLI_ARGS}}
dev:
desc: Run development services and Vite at http://localhost:5173
deps: [dev:daemon, dev:gateway, dev:state-store, dev:dashboard, dev:ui]
dev:postgres:
desc: Start PostgreSQL and wait for readiness
cmds:
- docker compose up -d postgres
- |
set -eu
for _ in $(seq 1 60); do
status=$(docker inspect --format '{{`{{.State.Health.Status}}`}}' "$(docker compose ps -q postgres)" 2>/dev/null || true)
if [ "$status" = "healthy" ]; then
exit 0
fi
sleep 1
done
echo "postgres did not become healthy within 60s" >&2
exit 1
dev:daemon:
desc: Run archied with live reload
cmds:
- |
# The daemon and Gateway read their settings from the State Store at
# boot and exit if it is not up yet; it starts only once PostgreSQL
# is healthy, so wait for its port ([services.state] in
# deployments/dev.toml) first.
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
exit 1
- air -build.args_bin="-config-overlay,deployments/dev.toml"
dev:dashboard:
desc: Run the dashboard backend
cmds:
- go run ./cmd/archie-ui -config-overlay deployments/dev.toml
dev:state-store:
desc: Run the State Store with development PostgreSQL
deps: [dev:postgres]
cmds:
- go run ./cmd/archie-state-store -config-overlay deployments/dev.toml
dev:gateway:
desc: Run the development Gateway
cmds:
- |
# The daemon and Gateway read their settings from the State Store at
# boot and exit if it is not up yet; it starts only once PostgreSQL
# is healthy, so wait for its port ([services.state] in
# deployments/dev.toml) first.
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
exit 1
- go run ./cmd/archie-gateway -config-overlay deployments/dev.toml
dev:ui:
desc: Run Vite (requires the dashboard backend)
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
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
vars:
GATEWAY_VERSION: '{{.GATEWAY_VERSION | default "dev"}}'
RUNTIME_VERSION: '{{.RUNTIME_VERSION | default "dev"}}'
SERVICE_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
-X github.com/samcharles93/archie-core/internal/buildinfo.Version={{.GATEWAY_VERSION}}
-X github.com/samcharles93/archie-core/internal/buildinfo.Runtime={{.RUNTIME_VERSION}}
sources:
- "**/*.go"
- go.mod
- go.sum
- "ui/dist/**"
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:
# One flag set for every service, matching scripts/archie-update-install
# and the release workflow, so each binary reports the same version.
- for: [archied, archie-gateway, archie-state-store, archie-ui, archie-messaging]
cmd: go build -ldflags "{{.SERVICE_LDFLAGS}}" -o {{.BIN_DIR}}/{{.ITEM}} ./cmd/{{.ITEM}}
- 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 short Go tests with caching
cmds:
- go test -short ./...
test:full:
desc: Run the whole Go test suite uncached, including the wall-clock-bound tests
cmds:
- go test ./... -count=1
test:tools:
desc: Run the nested tools module suite, refusing to rewrite its go.mod
cmds:
- go -C tools test -mod=readonly ./... -count=1
check:
desc: Run the full quality gate
# Finish mutations before starting parallel checks.
cmds:
- task: fmt
- task: proto:check
- task: db:check
- task: check:readonly
check:readonly:
internal: true
deps:
- task: proto:lint
- task: docs:check
- task: docs:prds
- task: docs:drift
- task: news:check
- task: docs:artifact:check
- task: vet
- task: lint
- task: build
- task: test
- task: test:tools
- task: test:ui
- task: ui:check
contract:
desc: Report contract conformance (advisory)
cmds:
- go -C tools run ./contractaudit --repo-root ..
release:preview:
desc: "Show the release notes that would be generated (VERSION=1.2.0)"
cmds:
- tools/release.sh --version {{.VERSION}} --dry-run
requires:
vars: [VERSION]
release:prepare:
desc: Prepare changelog notes for editing (VERSION=1.2.0)
cmds:
- tools/release.sh --version {{.VERSION}} --prepare
requires:
vars: [VERSION]
release:
desc: Commit and tag the prepared release (VERSION=1.2.0)
cmds:
- tools/release.sh --version {{.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