docs: adopt workspace-wide agent standards and retire sow-docs
ci / ci (pull_request) Canceled after 21s

Scaffold the per-repo configuration the engineering skills expect, and put
the three-way split of work into standing law:

- Live work -> wayfinder maps + Gitea issues (closeable, assignable,
  queryable).
- Settled decisions -> ADR files in docs/adr/ (immutable, findable, never
  closed).
- Standing law -> DOCTRINE.md / AGENTS.md / CONTEXT.md.

Adds docs/agents/{issue-tracker,triage-labels,domain}.md and an
"Agent skills" section in AGENTS.md. The tracker doc records Gitea via the
tea CLI, the wayfinder map/ticket/blocking operations, and the rule that
issues follow ownership: file work in the repo that owns it, not the one you
happen to be standing in.

ADR-0001 (markdown is reference, law, or an ADR - nothing else) is adopted
from sow-codebase so the rule is local to every repo.

sow-docs is retired: its 35 decisions become ADRs in the repos that own them,
its living docs move to sow-platform and sow-assets-manifest, and its
unfinished intent becomes Gitea issues.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-07-24 20:30:28 +02:00
co-authored by Claude Opus 5
parent 3f500dabc8
commit 03e193d8cb
8 changed files with 288 additions and 0 deletions
@@ -0,0 +1,55 @@
# ADR-0001: Markdown in this repo is reference, law, or an ADR — nothing else
- **Status:** Accepted
- **Date:** 2026-07-24
- **Origin:** Adopted workspace-wide from `sow-codebase` ADR-0001, which records
the full context (a `docs/` tree that had grown to 434 files, ~27MB, most of
it dead process artifacts). This repo adopts the same law so the rule is
local, not a cross-repo reference.
## Context
Markdown that *claims to describe current state or a plan* rots, because
reality diverges and nobody edits the file. Markdown that claims neither — a
dated, immutable decision record, or a standing rule — does not rot.
Two different things get conflated:
- **Rationale** — why a system is shaped the way it is. Worth keeping.
- **Process artifacts** — plans, specs, concepts, handoffs, trackers. A record
of how work happened, not what is true now.
Left unchecked, every completed effort leaves its planning behind and the repo
accumulates a "historical" pile that agents and humans must route around to
find the few live docs.
## Decision
Markdown may exist in this repo only as one of three genres:
1. **Current-state reference** — describes what the code does now, kept honest
by code review touching it.
2. **Standing law**`DOCTRINE.md`, root and folder-scoped `AGENTS.md`,
`CONTEXT.md`. States rules and vocabulary, not plans.
3. **Immutable decision record** — ADRs under `docs/adr/`. Append-only; never
edited, only superseded by a later ADR that points back.
Anything else — implementation plans, design specs, concepts, handoffs,
progress trackers, scratch — is **process** and does not live in the repo. It
lives in Gitea issues and wayfinder maps, where it can be assigned, closed, and
superseded. Small tasks need no written plan at all.
Deleting a process document is not destroying history: `git log -- <path>`
recovers it. The exception is *unfinished intent* (a design never built, an
open question still wanted) — that is live, not history, and must be harvested
to a Gitea ticket before its file is deleted. A citation from a living doc or
from code must be resolved before the cited file is deleted.
## Consequences
- The documentation map lists only current truth; there is no "historical" pile
to route around.
- No agent, under any plugin or skill, writes process-markdown into the repo.
The rule is plugin-agnostic on purpose — it binds the agent, not a named tool.
- History of deleted process docs is in git; unfinished intent is in the issue
tracker; rationale is in ADRs and law. Each thing has exactly one home.
@@ -0,0 +1,12 @@
# ADR-0002: `sow-tools` becomes the Crucible suite
- **Status:** Accepted
- **Date:** 2026-06-11
- **Migrated from:** `sow-docs` `07-decisions-log.md` entry **D11**, on the
retirement of `sow-docs`. Content is the original decision, unchanged.
- **Decision:** Rename the future toolchain surface to Crucible: one Go module,
multiple `cmd/` binaries, plus a dispatcher so wrapper commands can stay
stable.
- **Rationale:** Depot, HAK, module, topdata, and wiki tooling share internals
but have different command surfaces. One module avoids premature repo splits.
@@ -0,0 +1,29 @@
# ADR-0003: Crucible binary contract: standalone shims, fail-closed scaffold, no committed binaries
- **Status:** Accepted
- **Date:** 2026-06-11
- **Migrated from:** `sow-docs` `07-decisions-log.md` entry **D19**, on the
retirement of `sow-docs`. Content is the original decision, unchanged.
- **Decision:** Phase 5 builds `migration/sow-tools` (Crucible, D11) as a
multi-binary Go scaffold:
- One `crucible` dispatcher plus standalone `crucible-{depot,hak,module,topdata,wiki}`
binaries sharing one registry (`internal/dispatch`). The dispatcher is for
humans/CI; the **standalone shims are canonical for consumers** so wrapper
scripts resolve a single-token command and `"$builder" args` quoting stays
correct.
- Consumer resolution order: explicit env override
(`$SOW_MODULE_BUILD`/`$SOW_TOPDATA_BUILD`/`$CRUCIBLE`) → `crucible-<name>`
legacy `sow-<name>-build`. CI runs inside the pinned `crucible:<sha>` image.
- Every builder is **unwired** in the scaffold and fails closed (exit 70);
it never fakes an artifact. The `internal/` logic is migrated from
`gitea/sow-tools` by the operator at cutover (hard rule: no source
transplant by tooling).
- **Binaries are never committed** — they are CI artifacts / image layers.
Retires the committed `nwn-tool` / `tools/sow-toolkit`.
- Builders take `NWN_ROOT` only via explicit env/flag; no `$HOME` defaulting.
- **Rationale:** Locks the command surface, container, and CI shape so migrated
logic drops into a stable frame; aligns the three artifact repos onto one
Crucible contract while keeping back-compat with the pre-D11 skeletons.
- **Image name:** `registry.westgate.pw/deployment/crucible:<git-sha>` (the bare
`crucible:<sha>` is the local/dev tag).
@@ -0,0 +1,24 @@
# ADR-0004: Nix-built OCI images start server-side with Crucible; local Anvil images deferred
- **Status:** Accepted
- **Date:** 2026-06-12
- **Migrated from:** `sow-docs` `07-decisions-log.md` entry **D29**, on the
retirement of `sow-docs`. Content is the original decision, unchanged.
- **Decision:** Introduce Nix-built OCI images as an artifact-production option,
starting with `sow-tools`/Crucible in server-side CI. `sow-tools` will grow a
Nix-built `crucible` package plus `crucible-image`; PR CI builds/smokes it and
`main` publishes the normal pinned OCI image
`registry.westgate.pw/deployment/crucible:<sha>`. `docker/Dockerfile` stays during
parity and as the client-compatible fallback.
- **Local rule:** Nix users may get optional wrappers that provide tools and
call the existing Dockerfiles for local Anvil/NWServer testing. A true
`nix build .#nwserver-test-image` is explicitly deferred until real
`sow-codebase/src` exists and the Dockerfile image is proven.
- **Rationale:** Server-side image build shape is harder to change once deploy
promotion and registry gates are active, so prove Nix image builds before
cutover. Crucible is the lowest-risk pilot because it is a Go toolchain image;
NodeBB and Anvil/NWServer depend more heavily on upstream container filesystem
semantics.
- **Non-goals:** no source builds in `sow-platform`; no `nix-sidecar` or
Kubernetes-style runtime cache layer; no removal of client Dockerfiles.