From 324e6c1309fd9706cd6364f4f0beca397ccee239 Mon Sep 17 00:00:00 2001 From: nmccready Date: Tue, 14 Jul 2026 22:28:48 -0400 Subject: [PATCH] =?UTF-8?q?docs(specs):=20spec=20lifecycle=20convention=20?= =?UTF-8?q?=E2=80=94=20ledger,=20precedence=20rule,=20delete-on-ship?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - specs/README.md: permanent ledger back-filled for SPEC-001..008 (status, retire commit, durable-doc destinations); lifecycle steps - .agents/rules/specs.md (always_on): docs/ and code are current truth; specs never outrank them; ship → promote to docs + delete + ledger row; no specs/completed graveyards - docs/README.md: point the retired-specs note at the ledger - AGENTS.md regenerated (sync-agents index) Co-Authored-By: Claude Fable 5 --- .agents/rules/specs.md | 24 ++++++++++++++++++++++++ AGENTS.md | 6 ++++++ docs/README.md | 8 ++++---- specs/README.md | 38 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 72 insertions(+), 4 deletions(-) create mode 100644 .agents/rules/specs.md create mode 100644 specs/README.md diff --git a/.agents/rules/specs.md b/.agents/rules/specs.md new file mode 100644 index 0000000..d16604e --- /dev/null +++ b/.agents/rules/specs.md @@ -0,0 +1,24 @@ +--- +trigger: always_on +--- + +# specs lifecycle and precedence + +`docs/` and the code are **current truth**. `specs/` contains **active +proposals only** — never treat a spec (active, retired, or dug out of +git history) as outranking docs or code; where they conflict, docs/code +win. + +- The permanent index of every spec ever written is + [`specs/README.md`](../../specs/README.md) (the ledger). Consult it — + not git archaeology — to learn whether a SPEC ID shipped and where its + durable content now lives in `docs/`. +- When a spec ships **fully**: in the same PR, promote its durable + decisions/contracts into `docs/`, DELETE the spec file, and update its + ledger row (status, retire commit, doc destinations). Git history is + the archive; do not create `specs/completed/` or similar graveyards. +- When a spec ships **partially**: trim shipped parts to a short + summary, keep only open work in the body, update frontmatter + `status:` and the ledger row. +- Reference specs by ID (`SPEC-00N`), which stays resolvable via the + ledger even after the file is deleted. diff --git a/AGENTS.md b/AGENTS.md index 18d8e31..ce79ba8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,6 +23,7 @@ This file indexes all rules, skills, and workflows defined in `.agents/`. - [integrity](.agents/rules/integrity.md) - [iterative-code-review](.agents/rules/iterative-code-review.md) - [security](.agents/rules/security.md) +- [specs](.agents/rules/specs.md) - [testing](.agents/rules/testing.md) - [tradeoffs](.agents/rules/tradeoffs.md) @@ -36,6 +37,10 @@ _No skills defined yet. Add one with `sync-agents add skill `._ ## State +Follow [rules/state.md](.agents/rules/state.md): record progress in `.agents/STATE__.md` snapshots. Snapshots are per-engineer and not indexed unless marked `shared: true` in frontmatter. + +### Shared + - [STATE.md](.agents/STATE.md) @@ -48,6 +53,7 @@ _No skills defined yet. Add one with `sync-agents add skill `._ @.claude/rules/integrity.md @.claude/rules/iterative-code-review.md @.claude/rules/security.md +@.claude/rules/specs.md @.claude/rules/testing.md @.claude/rules/tradeoffs.md diff --git a/docs/README.md b/docs/README.md index 23f8f43..37a57c0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -90,10 +90,10 @@ The authoritative source for *what we're building and why* lives in IDs but is never the source of truth for them. Only specs with **open work** are kept in the tree; fully-shipped specs -(SPEC-001 go-install/goreleaser, SPEC-002 promote/global sync, SPEC-003 -source manifest, SPEC-004 asset buckets, SPEC-007 linked sources) are -retired to git history — `git log --all --oneline -- specs/` finds -them. +are promoted into `docs/` and retired to git history. The +[**spec ledger**](../specs/README.md) is the permanent index — every +SPEC ID ever used has a row there (status, retire commit, where its +durable content lives), so IDs stay resolvable after the file is gone. - [SPEC-005](../specs/SPEC-005-sandboxing-quarantine.md) — supply-chain safety: Parts A+B (fetch hardening, quarantine + scan) shipped; diff --git a/specs/README.md b/specs/README.md new file mode 100644 index 0000000..53c91b6 --- /dev/null +++ b/specs/README.md @@ -0,0 +1,38 @@ +# Specs — ledger and lifecycle + +`specs/` contains **active proposals only**: work that is drafted, in +flight, or partially shipped. Fully-shipped specs do not live here — +their durable content is promoted into [`docs/`](../docs/README.md) and +the spec body is deleted in the same PR (git history is the archive). +This ledger is the permanent index: every spec that ever existed has a +row, so SPEC IDs stay resolvable after the file is gone. + +**Precedence:** `docs/` and code are current truth. A spec — active, +retired, or found in git history — never outranks them. Agents: do not +treat retired spec content as current intent. + +## Lifecycle + +1. **Draft → Active** — spec lives here, frontmatter `status:` tracks it. +2. **Shipped (fully)** — in one PR: promote durable decisions/contracts + into `docs/`, delete the spec file, update this ledger row (status, + retire commit, doc destinations). +3. **Shipped (partially)** — trim the spec to only the open work + (collapse shipped parts to a short summary), update `status:`. +4. Recover any retired body verbatim: + `git log --all --oneline -- specs/` then `git show ^:specs/`. + +## Ledger + +| ID | Title | Status | Retired in | Durable docs | +| --- | --- | --- | --- | --- | +| SPEC-001 | go-install first-class (goreleaser) | ✅ shipped v1.4.0 | `6c53595` | [install](../docs/install.md) | +| SPEC-002 | promote + global sync (semantic routing) | ✅ shipped v1.4.0 | `6c53595` (siblings merged in `9de9326`) | [promote](../docs/commands/promote.md), [global-sync](../docs/commands/global-sync.md), [semantic-routing](../docs/architecture/semantic-routing.md) | +| SPEC-003 | source manifest pull (`sources.lock`) | ✅ shipped v1.4.0 | `6c53595` | [sources](../docs/sources.md) | +| SPEC-004 | new asset buckets (agents/plans/specs/hooks) + lint | ✅ shipped v1.4.0 | `6c53595` | [topology](../docs/topology.md), [lint](../docs/commands/lint.md) | +| SPEC-005 | sandboxing + quarantine | 🟡 Parts A+B shipped v1.1.0–v1.2.0; **Part C open** | — (active) | [quarantine](../docs/quarantine.md) | +| SPEC-006 | OS-scoped routing | 🟡 core shipped v1.3.0; **badge + concat headers open** | — (active) | [os-scoped-routing](../docs/os-scoped-routing.md) | +| SPEC-007 | linked sources | ✅ shipped v1.4.0 | `6c53595` | [linked-sources](../docs/linked-sources.md) | +| SPEC-008 | full-context integrity lock (`agents.lock` + `agents.sum`) | 📝 draft | — (active) | — | + +Next spec ID: **SPEC-009**.