docs(specs): spec lifecycle — ledger, precedence rule, delete-on-ship

.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.

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 <name>`._
 
 ## State
 
+Follow [rules/state.md](.agents/rules/state.md): record progress in `.agents/STATE_<context>_<timestamp>.md` snapshots. Snapshots are per-engineer and not indexed unless marked `shared: true` in frontmatter.
+
+### Shared
+
 - [STATE.md](.agents/STATE.md)
 
 <!-- sync-agents:claude-imports:start -->
@@ -48,6 +53,7 @@ _No skills defined yet. Add one with `sync-agents add skill <name>`._
 @.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
 <!-- sync-agents:claude-imports:end -->

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;

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 <sha>^:specs/<file>`.
+
+## 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**.