The rule belongs in CLAUDE.md, the inventory belongs in the config skill. The
skill already carried a decoded-but-unwired ledger and defines its status terms
exactly, so the entry now points at it instead of duplicating it, and the ledger
gains the live instance from 2026-09-22 (per-identity forge intake) plus the
three shapes an unwired field can take - not-consumed, not-projected, and
deliberately-not-projected, the last being UpdateCheckCommand/UpdateInstallCommand
read from base by design.
Project skill for running a bounded agent fleet on this repository. It stays
thin on purpose: the method -- doctrine, pipeline shape, the interview, the
pi-subagents ceilings and traps, scripts/, templates/ -- is the user-scope
high-throughput-programming skill, which is normative for method. This skill
carries only archie's facts and is normative for those.
What it carries: the seven invariants every lane call must repeat (fail-closed
control plane, the webui/workflow deletion gate, single ownership of
<db_path>-tasks.sqlite, no .beads/ commits, generated assets as LAW, scratch in
/tmp because CommitAll stages untracked files, and the cmd -> app -> {domain,
infrastructure} direction); the canonical gate-evidence.sh invocation and why it
must run the module build and the linter, not just a scoped test; the scoped
test-command shape for a lane plus the fact that task check is the serial full
gate the merge train owns; the agent-discovery trap (a lane worktree is a
sibling, so .pi/agents must be symlinked into it or children die with "Unknown
agent: cp-writer"); bd conventions; and that .pi/control-plane-run/ is
disposable run evidence, not documentation.
Also moves the September 2026 control-plane run out of the user-scope skill's
references/worked-example/ and into references/worked-example/ here, so exactly
one copy exists and it is committed. The user-scope skill's References table and
normative-copy paragraph now point at this repository, and note that a run in
another repository uses templates/ plus its own filled-in briefs. The moved
README gains the worktree agent-symlink fix and loses its stale "everything here
is gitignored" claim; its paths to scripts/ and templates/ now name the
user-scope skill explicitly. The scripts warning is unchanged: they are the
snapshot's and must not be copied.
31622ec5 deleted the overlay but not its documentation of record, leaving
docs/architecture/ asserting a subsystem that no longer exists.
safe-change-and-recovery.md was the dangerous one. It listed three ways back
from a bad runtime setting, all of them gone, so its recovery section was a
dead end. The replacement records the posture honestly: the control plane
fails closed, a stored value that will not validate stops the daemon starting,
and there is no escape hatch until archie-core-6zw0 lands.
configuration.md's ledger rows for the overlay store and the two dashboard
write routes become one row for the control-plane command. migration-decisions
marks the config-write descope superseded rather than deleting it, per
docs/prds/RULES.md.
Also removes leftovers the gate could not catch: a dashboard banner bound to
ReloadStatus.overlay_unavailable, a field the server stopped sending, and a
delivery-snapshot scan pointed at ApplyOverlayValues in a composition root that
no longer calls it.
The reload trace behind this found archie-core-ju85: SIGHUP republishes the
file document alone, reverting every database-owned setting until restart.
Recorded in the ledger as current behaviour.
task check's proto:check and ui:check verify committed artifacts rather than
the build, so both fail on correct but unstaged work and both read as a broken
generator. Cost this session twice.
A registered service client always resolves to a non-empty target, so
Services.Get(name).Target != "" proves nothing: a guard meaning "only dial when
configured" dials always, and a test that sets no target reaches for a real
process on the developer's machine.
Also corrects the config skill's input-path table, which still described the
dashboard runtime overlay deleted in 31622ec5. The rest of that stale surface
is archie-core-b7dn.
`git merge-base --is-ancestor` answers a topology question, so it reports a
landed repair as never-landed for every squash merge and for any rebase merge
that had to replay commits. This repository squash-merged its last fifteen
pull requests (everything merged up to 2026-09-18 used merge commits), so the
check documented in the failure-archaeology skill is a false negative for all
of them.
Add scripts/on-main.sh: `--is-ancestor` stays the offline fast path, and a
non-ancestor falls back to the GitHub API, where merge state is recorded
independently of the commit graph. It separates landed (0) from not-landed (1)
from undetermined (2) instead of folding an unanswered question into a
negative -- `if on-main.sh <ref>; then` is the mistake it exists to prevent.
Verified against live data: ancestor -> 0, squash-merged PR #899 -> 0, closed
unmerged PR #896 -> 1, commit in no pull request -> 1, local-only commit
GitHub has never seen -> 2, bad ref / bad base / no args / bad option -> 2.
`task lint` enables gofumpt's `extra-rules`, so it demands `func f(a, b int)`
where `task fmt`'s bare `gofumpt -w .` left `func f(a int, b int)` alone --
and `task fmt` is the documented repair for a failing gate, so a contributor
had no command that could satisfy `task check`. That is the same failure shape
as the version drift fixed alongside it, one layer up: fmt and lint are not
the same formatter, so only the rules they happen to share are safe.
`-extra` matches `extra-rules`, and nothing reformats as a result: the tree is
already clean under it (`gofumpt -extra -l .` is empty).
Still open, filed as archie-core-q288: gci's custom-order places archie-core
imports last where gofumpt sorts them alphabetically, so `task fmt` can still
produce formatting it will never fix. That needs a decision about which
formatter owns formatting rather than another flag, and it is a decision CI
cannot currently surface at all -- the deploy gate never runs golangci-lint.
`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.
Extract the shape that worked for image-capability-contract.md (decisive
per-sub-feature decisions instead of deferrals, a call-site inventory, and
a council-lens assignment per slice) into a template so future PRDs get
written the same way -- and so the resulting sub-issues are clear enough
for a cheaper/faster model to implement without re-deriving the design.
- references/templates.md: new "PRD: open capability design with
multi-agent execution" template.
- SKILL.md: docs/prds/ was missing from the "choose one destination"
table entirely; added.
- image-capability-contract.md: retrofitted with the Execution breakdown
(lens assignment per #498-501) the template now asks for.
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.
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).
MemoryConfig.SessionTTL and ToolPolicy.ParallelExecution were decoded by
config loading and read nowhere, so setting either silently did nothing.
Removing them routes both keys into the unknown-key detector, which names
them in a boot warning instead. A live-looking knob wired to nothing is
the worse state, and the sibling memory.provider already earned a loud
load-time rejection for exactly this.
Also drops the config.example.toml line that shipped session_ttl into
every first-run config.toml via configtemplate.go, and the commented-out
dir_test.go assertions that would have re-created both fields under that
file's "make these pass without modifying them" header.
Three defects made every archie-diagnostics-and-tooling measurement wrong:
- source-metrics.go and config-use-candidates.go walked .worktrees/, the
live git worktrees nested inside the repo root. Each is a near-complete
copy of the module, so counts were multiplied by the number of checkout
worktrees: production_go_files read 1234 against 422 tracked, and 248 of
421 PACKAGE/HOTSPOT rows were duplicates. Selector counts were inflated
~3x, which hid Repo.TestGlob behind a real candidate and buried the rest.
- delivery-snapshot.sh scanned .gitea/workflows, deleted in e539048. Under
`set -eu` that aborted the run at rc=2 after 10 of 26 rows, silently
dropping every HYGIENE and MODULE row.
- Its composition-root anchors pointed at cmd/archied/main.go, now a ~30
line dispatcher, so all five rows reported a misleading 0. Repointed at
internal/app/archied, where the wiring actually lives.
Both filesystem walkers now skip .worktrees (package-shape.sh reads
`go list` and was already immune), the CI scan covers the surviving GitHub
workflow including docker/build-push-action, and the MODULE find prunes
.worktrees.
Refresh SKILL.md to HEAD d565fb8: the dated snapshot, the delivery and
coverage claims, and notes on why only one candidate status is a signal
and why a composition-root zero is evidence about the anchor.
source-metrics.go now reconciles exactly with git ls-files: 408 + 9
production and 397 test files, plus the tools module's 5 / 2 / 0, against
422 non-test and 398 test tracked files.
Nothing in the delivery gate entered tools/, so its dependency drift was
only ever discovered by a command that silently repaired it, dirtying the
tree with an unrelated diff. task check now runs test:tools.
-mod=readonly is passed explicitly on every documented tools command: a
developer's global GOFLAGS=-mod=mod in go env overrides the toolchain
default and re-enables the rewrite.
Also corrects the archie-build-and-env coverage table, which claimed task
check omits task lint.
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.
cmd/archie-agent used to own worker construction, NATS lifecycle, task execution, MCP setup, and workflow wiring. It now owns process input only and invokes internal/app/agentworker, while transport-specific NATS, boot-brief, and git-safety mechanics live under infrastructure.
Task and event persistence now uses a dedicated SQLite sidecar derived from the configured state prefix, matching the independently persisted conversation store. The configured path now means a state-path prefix rather than a database file so fresh SQLite state never attempts to interpret the previous storage format.
Remove the retired implementation and dependency completely, strengthen SQLite migrations and concurrency behavior, restore backend-neutral coverage, and align configuration, operational guidance, UI labels, and deployment documentation with the new storage and host-daemon topology.
All 416 beads issues (open, in-progress, and closed) are migrated to
GitHub Issues with parent/sub-issue hierarchy preserved; the 66 issues
carrying beads "notes" content had that backfilled as GitHub comments.
The local Dolt DB and .beads/ export were never git-synced (no-git-ops:
true in config.yaml), so this is a clean removal with nothing left
behind on any remote.
- Reword docs and comments to drop vague "legacy" qualifiers where they no longer describe deprecation status
- Remove unused code: RecentEvents, MessageEvent.ToLegacy, index setState, stderr redaction tool, telegramOnlyCommands
- Delete or comment out tests covering removed or superseded behavior
Applies the four-reviewer pass over the forge/dashboard-actions work.
The through-line is that several capabilities were wired but inert, and
one of them could cost real work.
DUPLICATE WORK. "Closes #N" was dropped from PR bodies in favour of
LinkBranch, which is sidebar linkage on Gitea and a no-op stub on
GitHub -- neither closes anything, and nothing else did either. So a
merged task left its issue open, labelled and assigned; the next poll
re-enqueued it, and once the dashboard's Clear removed the task row that
became a second implementation and a second PR for work already merged.
reconcilePRs now closes the issue on merge, and a rejected task closes
its issue too. A PR closed without merging deliberately leaves the issue
open: that usually means "try again".
MAX RETRIES. Configured, defaulted and reported by /api/config, and
enforced nowhere -- markDead was unreachable and EffectiveMaxRetries had
no callers, so the dashboard's retry incremented retry_count forever.
The retry action now retires a task to dead at the cap.
DEAD ON ARRIVAL. Tasks() never selected plan or source, so the
"Decision required" panel could not render and chat tasks -- whose issue
number is synthetic -- linked to forge issues that do not exist.
COSMETIC FAILURE, FATAL RESULT. OpenPR failed the whole stage when
LinkBranch errored, so the pull request was never opened and the task
parked; a retry re-links the same branch, which Gitea answers with a
conflict, so every retry parked again. It is best-effort now.
INVISIBLE ACTIONS. Approve/retry/reject wrote store rows and nothing
else, so the timeline and activity stream never showed that a human had
intervened. They emit events now.
Also: store write failures answer 500 rather than 409; the dashboard
surfaces the server's actual reason instead of "409 Conflict"; action
buttons stop propagation (acting on a task no longer also expands it),
disable in flight, keep per-task errors instead of one shared string,
and confirm before rejecting.
Removed: the maybeRetryParked shim and markDead with their now-vacuous
tests, WaitingTasks (no consumers; its tests were rewritten to assert
the same routing through TaskByID), write-only Daemon.Runtime, and
dir/dirs response bloat from /api/skills. skillSource checked workDir
before sharedDir, mislabelling every shared skill when the two are equal.
DefaultRoots now dedupes roots differing only by a trailing separator.
The air build rule claiming to keep ui/dist current never ran -- it
required one file to satisfy include_dir and include_file together, and
ui/ is excluded from the walk. Deleted with the comment that promised it.
task test:ui joins task check and CI; it ran nowhere before, so the
dashboard suite could rot silently.
Docs corrected where they described behaviour that no longer exists:
parks no longer comment on the issue, state labels no longer drive
retries, and forgerpc's doc claimed four proxied methods while listing
three of five.
WriteTaskJSON wrote task.json to the worktree root -- the same worktree
the agent commits from. CommitAll stages with go-git's All option, and
go-git's Add does not honour .gitignore or .git/info/exclude, so the
brief was swept into the agent's commit and pushed onto every task
branch. That is how a task.json for issue #57 ended up committed in
the repo root.
This is the identical failure the prepared sentinel hit; worktree.go
already documents the fix. Nothing under .git can ever be tracked, so
put the brief there rather than papering over it with an exclude.
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.
Skills now declare their workflow in metadata.archie.workflow.
Catalog() scans frontmatter only (lazy, Tier 1). SkillForWorkflow()
derives the skill directory from the catalog — no hardcoded maps.
Removed workflowToSkill map (agent.go) and workflowToSkillDir switch
(worker.go). Both daemon and agent use the same catalog-based lookup.
Skills renamed to archie-wf-* convention. SKILL.md files updated with
workflow metadata field.
Progressive disclosure Tier 1: Catalog() returns name+description
+workflow. Tier 2: LoadBody() loads full body on activation.
Adds internal/skill package with YAML frontmatter parsing and skill
discovery from .agents/skills/ (agentskills.io spec convention).
- Frontmatter struct with name, description, version, metadata.archie
- Parse() extracts YAML frontmatter delimited by --- markers
- Discover() scans .agents/skills/*/SKILL.md (follows wfeval pattern)
- LoadBody() for single-skill lazy loading
Skills moved from .archie/skills/ to .agents/skills/ per the
agentskills.io specification.
Wiring: TaskContext.SkillBody field, lazy-loaded on first agent stage
from worktree. When non-empty, prepended to Mission as "Follow these
project-specific guidelines" context. Hardcoded Mission templates stay
(task-specific formatting). Backward compatible: empty when no skill
found.