CHANGELOG.archied.md and CHANGELOG.archie.md were two version streams that
drifted: a release that moved both components had two numbers, two pages and
two tags, and a reader had to visit two files to learn what shipped.
The merged history holds 65 versions from 64 archied and 34 archie sections --
33 that both components released, 31 only archied, one only archie -- so 98
published pages become 65. A version's date is the newest of its sections'
dates, and a component whose own date differs carries it on its label, because
the history has two dates and the merge must not invent one. `## [Unreleased]`
is not a release: it gets no page, and it stays at the top of the file.
A level-two heading is where the merge could silently drop a section, so the
merge is verified by content rather than by the generator: section counts per
source, the merged version set against the exact union, and every source `###`
title present both as a substring and, after stripping the component prefix, as
an identical heading. Counting `##` headings rather than releases overcounts by
one here, which is how the empty `[Unreleased]` block was caught.
- newsgen reads one file and writes `docs/news/<version>.md`, the index, the
canonical `releases.json`, and `docs/news/redirects.json`. The redirect table
is what keeps the retired `/news/<component>/<version>/` URLs alive; it is
generated beside the pages so it cannot drift from them.
- release.sh takes one `--version`, keeps commit and tag (the Woodpecker
pipeline that will own them does not exist yet), and exits 3 when the commit
set justifies no release, so a pipeline can finish green without tagging.
- The consumers of the two files follow: the deploy workflow's tag gate and
release-notes extraction, the zip contents, the update check's changelog
links, the packaged-path note, the docs skill, and newsgen's tests.
The per-component detail survives as labelled sections inside each release, so
a reader still learns whether archied or the agent changed; what goes away is
the separate numbers and the separate pages.
Two defects, both from consuming a ref's object id as if it were a commit.
1. IMMUTABLE IDENTITY. Both images published only `:latest`, so a deployed
artifact could not be traced to a commit or restored. Each build now also
publishes `sha-<commit>`. The commit is NOT `github.sha`: on a tag push that
is the ref's object id, and every release tag in this repo is annotated —
measured, 80 of 80 archied/v* and archie/v* tags are tag objects (archied/
v1.36.0 points at 6720bc42 and dereferences to 576718c3). So the new step
resolves `git rev-parse "${GITHUB_REF}^{commit}"` and the tags use that.
Annotated tags are the right thing for the producer to create; the consumer
stops guessing rather than the tag type being downgraded.
2. NO BARE dev STAMP. `[ -n "$GATEWAY_VERSION" ] || GATEWAY_VERSION=dev` made a
main build indistinguishable from any other, and is why a release's stamping
looked transient: the next commit to main republished :latest as plain `dev`.
The fallback is now `dev+<short sha>`, so an unreleased build is identifiable
and visibly not a release. The warning at the gate now states the consequence
it previously only implied.
Scope: this file only. Nothing else in the checkout was touched.
The updater is component-driven: it compares the daemon and agent versions and
acts only when they differ, so a host whose individual binaries disagree looks
healthy. Carina ran a hand-installed archie-messaging 1.35.0 against a 1.30.0
state store and crash-looped on an RPC the older store does not serve, while
the updater reported "no approved component changes; nothing to install".
The reason a comparison was impossible: three of the six host binaries carried
no version at all. archie-ui, archie-messaging and archie-playbooks did not link
internal/app/archied, so the release ldflags never reached them; the gateway and
state store linked the variable but exposed no flag. Only archied could say what
it was.
- internal/buildinfo carries Version, stamped by all three build sites: the
zip, install.sh, and the updater itself.
- Every host binary answers -version ("<name> <version>"). archied's existing
two-line output is unchanged, because something parses it.
- archie-update-install reads each installed binary before it can report
"nothing to install" and refuses, naming every binary that disagrees with the
daemon's version; after an install it verifies the same set against the
release it just installed, so a binary the release did not rebuild is skew
rather than success.
- TestDistZipShipsEveryHostCommand pins stamping across the three build sites
and requires each cmd/ to report, so a seventh command cannot arrive unstamped.
The v1.30.0 extraction moved Telegram, email and webhook out of archied and into
cmd/archie-messaging, and nothing packaged it. dist-zip built and copied only the
five older binaries, and scripts/archie-update-install omitted it from both its
service and binary lists. A host upgraded across v1.30.0 therefore ran on with no
messaging process at all: archied logged that it stopped serving the telegram
gateway at the extraction, nothing replaced it, and the bot was dead for two days
with no error anywhere -- the daemon looked healthy throughout (archie-core-1c01).
Fixed in all four places the host component set was enumerated: the zip's build
loop, the zip's copy list, the installer's GATEWAY_SERVICES (messaging is a
service, so it is installed AND restarted) and its GATEWAY_BINARIES. The comment
claiming every process in the documented deployment ships in the zip is now true,
and says what makes it true.
The duplication was the actual defect, so the sets are pinned to cmd/ instead:
TestHostCommandListsCannotDrift derives the host-run commands from cmd/ and
asserts all four lists, plus the reference runbook's units, agree with it. Adding
a command or extracting one fails the test until it is packaged -- the check that
would have caught this on the day. The installer's own test grew the same
coverage, and the reason it passed while the bug was live is worth recording: its
fixture created only the stale cmd/ set, so the script's `[ -d ./cmd/$cmd ]` guard
silently skipped messaging.
Documentation, because the installer now refuses an update when a service unit is
missing and sends the operator to the runbook -- so a service the runbook omits is
a dead end: a messaging unit in deployments/systemd-user-service.md, the component
list and start sequence in deployments/INSTRUCTIONS.md (which ships inside the
zip), and the packaged-binary list in RELEASING.md.
Verified: task check exit 0, including test:tools and test:ui. Both new guards
were made to fail on purpose: reintroducing each omission produces "missing
archie-messaging" and "no call with fragments [./cmd/archie-messaging]".
`task fmt` formats with the standalone gofumpt and `task lint` re-checks that
formatting with the gofumpt golangci-lint vendors. `task check` runs `fmt`
then `lint` without diffing the tree, so `lint` is the only hard failure for
formatting -- and when the two versions differ, any construct they disagree on
makes the gate unsatisfiable: the standalone formatter rewrites a file one way
and lint rejects it, with nothing a contributor can run to satisfy both.
The surfaces had drifted onto three different pairs. This machine ran gofumpt
v0.7.0 against golangci-lint 2.13.2 (vendors v0.11.0), the image pinned
golangci-lint 2.12.2 (vendors v0.9.2) next to gofumpt v0.11.0, and CI
installed gofumpt@latest. `any((Trees)(nil))` in changes_test.go is the
construct that surfaced it: gofumpt <= v0.9.2 keeps the redundant parens,
>= v0.10.0 removes them.
- Dockerfile: golangci-lint 2.13.2, whose vendored gofumpt v0.11.0 now equals
the pinned GOFUMPT_VERSION, so the image's two formatters agree.
- Dockerfile: fail the build if the pins ever diverge, rather than ship an
image whose gate cannot pass.
- deploy.yml: gofumpt@v0.11.0 instead of @latest, which drifts ahead of
whatever golangci-lint vendors.
- Record the invariant where an agent will meet it: AGENTS.md (CLAUDE.md) and
the build-and-env skill, whose snapshots now name the pinned pair instead of
calling both unpinned.
.github/workflows/docs.yml runs actions/setup-python@v6 with cache: pip. That
option hashes a requirements.txt or pyproject.toml to build the cache key and
fails outright when neither exists:
##[error]No file in ... matched to
[**/requirements.txt or **/pyproject.toml]
This repository is Go and has no Python manifest, so the step failed as the
first step of every run triggered by the workflow's pull_request paths: docs/**
filter. mkdocs build --strict therefore never executed: docs changes were not
being verified, and every docs-touching PR was reported as a build failure. It
only surfaced on #878 because #878 touches docs/architecture/; PRs that do not
touch docs report no checks at all.
Drop cache: pip. The only Python use is a single `pip install mkdocs-material`,
so there is nothing worth caching.
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.
The dist-zip job built the linux/amd64 zip and uploaded it as an Actions
artifact, then stopped. An artifact is reachable only from the run's page,
behind an Actions login, and expires after 90 days -- so every release since
the zip job landed produced a download an operator could not find. The one
Release on this repo (archied/v1.22.0) was created by hand and carries no
asset at all: nothing in CI has ever created one.
Publish the Release from this job and attach the zip:
- Job-level `permissions: contents: write`. The workflow default is
contents:read, so a publish step would fail without it; scoping it to this
job keeps the build-and-push jobs read-only.
- The body is this version's changelog section, extracted from the "## [x.y.z]"
heading to the next "## [" heading rather than pasting the whole file. The
changelog stays the single source of truth, and the tag/changelog gate in
`gate` has already proven the section exists.
- Attached to the archied tag, because the zip is named and versioned for
archied; `--follow-tags` pushes both tags at one commit, so the runtime
release is the same commit.
- Idempotent: `gh release view` decides between `create` and
`upload --clobber`, so a retried or superseded deploy run cannot fail on an
existing Release or duplicate the asset.
- Fails loudly when the section extracts empty, rather than publishing a
Release with no notes.
Two independent faults meant archied v1.23.0 shipped no zip at all.
dist-zip was gated on `startsWith(github.ref, 'refs/tags/archied/v')`. A
release is pushed as main plus both tags at one SHA, the SHA-keyed
concurrency group collapses those three runs into one, and the survivor
is whichever ref started last. For v1.23.0 that was refs/heads/main, so
the job was skipped and both tag runs that would have matched had already
been cancelled: 0 artifacts across all three runs. Resolve the archied
tag from the commit, the way build-and-push already does, and gate on
that instead of on the ref that happened to win the race.
The zip was also incomplete. It carried archied, archie-gateway,
archie-state-store and archie-playbooks, but not archie-ui, which since
1.23.0 is the process that serves the dashboard: a deployment cannot be
stood up from those four. Build every process the reference deployment
runs, and stamp each with the archied version rather than leaving the
state store and playbooks unversioned.
Closes archie-core-803r, archie-core-xi02.
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.
New dist-zip job, independent of build-and-push (no change to the
archied/archie-agent Docker image jobs). Triggers on any archied/vX.Y.Z
tag, so a gateway-only release (RUNTIME=skip) still produces it, keyed
to the archied version alone -- these binaries aren't in
tools/release.sh's two-component split and don't need to be for this.
archie-agent is deliberately excluded: it only ever runs inside the
Docker image build-and-push already publishes, never as a host binary.
Zip contains the four linux/amd64 binaries, the new
deployments/INSTRUCTIONS.md (quickstart + deployment-profile/systemd
pointers), and CHANGELOG.md/CHANGELOG.archied.md/CHANGELOG.archie.md.
README.md is included only if present -- it doesn't exist in this repo
yet, so omitted for now rather than fabricated here.
Verified locally: all four binaries build clean under
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 (modernc.org/sqlite is pure Go,
no cgo sqlite driver to worry about), and the assembled zip's contents
match what the workflow step produces.
git push --follow-tags pushes main plus both archied/v* and archie/v*
tags in one operation, all pointing at the same commit. on.push
matches branches and tags, so every release push fired three identical
deploy runs -- observed just now: archied/v1.19.7, archie/v1.19.7, and
main all running in parallel from the same commit. The ref-keyed
concurrency group added earlier couldn't see these as the same work
since github.ref differs per trigger. Key on github.sha instead so all
three collapse into one.
Both images built via plain docker build/push with no cache, so every
push to main rebuilt archie-agent's full toolchain (apt packages,
golangci-lint, gofumpt, buf, uv+python, npm globals) from scratch --
several minutes, even when none of those inputs changed. Switch to
docker/build-push-action with GHA-backed layer caching per image.
Also add a concurrency group so a burst of pushes (e.g. a fix commit
immediately followed by its release commit) cancels the superseded
deploy rather than running three in parallel for capacity none of them
can use -- only the last one's :latest push matters anyway.
CI's go-version was a floating "1.26" independent of go.mod, so it
could silently drift from the toolchain the project actually builds
with. Switched to go-version-file: go.mod as the single source of
truth, and added `task vuln` (govulncheck) plus a CI scan step -- kept
out of `task check` since it needs network access to the vuln DB.
The gate derived the version with ${tag#archied/}, which leaves "v1.7.0",
then looked for a "## [v1.7.0]" heading. Changelog sections carry no v --
tools/release.sh writes and validates "## [1.7.0]" -- so the gate could
never match and every tagged release failed before the images were built.
This is the gate's first tagged run: it landed in dd9bddc, after the
archied/v1.6.0 tag, so nothing had exercised this branch until v1.7.0.
grepBinary() resolves rg from PATH since the embedded binaries were
dropped, but nothing installed it: not the GitHub Actions runner (CI
grep tests fell back to direct search and failed), and not the
archie-agent image (Dockerfile) that runs grep tool calls for sandboxed
tasks. Production was masked by carina's host already having ripgrep
installed system-wide for archied's own tool execution.
Dockerfile.archied is unused by the current deployment (docker-compose
builds only Dockerfile; archied runs on the host under systemd) --
corrected its stale "ripgrep is embedded" comment rather than adding
the package to an image nothing builds from.
GitHub's hosted runner has no gofumpt preinstalled, unlike the
self-hosted Gitea runner this workflow was copied from -- gofumpt -w .
failed with "command not found" on the first run.
Mirrors the existing Gitea deploy workflow's gate (fmt/vet/build/test,
dashboard tests, tag<->changelog check) but publishes to
ghcr.io/samcharles93/{archied,archie-agent} using the built-in
GITHUB_TOKEN. Additive: docker-compose.yml and the carina watchtower
setup are untouched, so production still runs off the Gitea-built
images until that's explicitly cut over.
.gitea/workflows/deploy.yml is removed from this checkout now that the
Gitea remote is gone; the git.catlow.cloud-hosted copy is unaffected
until that repo is pushed to again.
Fold the old docs/ into the VitePress site and rename docs-2 -> docs.
The 12 architecture PRDs become first-class pages at docs/architecture/
with sidebar nav, rather than being buried under an archive path.
Historical material stays at docs/archive/. Rewrites every docs-2 and
docs/prds/architecture reference across the repo. Site builds clean.