docs: adopt spec/ADR/plan lifecycle + prune coded plans

.gitignore

@@ -23,3 +23,8 @@ secrets.*
 # OS
 .DS_Store
 Thumbs.db
+
+# Implementation plans are local-only, ephemeral work artifacts (see docs/plans/README.md).
+# They go stale the moment code merges; the durable "why" lives in docs/specs/ + docs/adrs/.
+docs/plans/*
+!docs/plans/README.md

docs/adrs/0000-adr-template.md

@@ -0,0 +1,37 @@
+# ADR-NNNN: <short decision title>
+
+- **Status:** Proposed <!-- Proposed → Accepted → Superseded by ADR-NNNN / Deprecated -->
+- **Date:** YYYY-MM-DD
+- **Deciders:** <who>
+- **Spec:** [`../specs/YYYY-MM-DD-<topic>-design.md`](../specs/YYYY-MM-DD-<topic>-design.md) <!-- the deep-dive this decision came from; omit if none -->
+
+## Context
+
+What forces a decision now? The problem, the constraints, the pressures. State the facts and
+the forces at play — not the answer. Enough that a reader a year from now understands *why this
+was even a question*.
+
+## Decision
+
+The choice, stated in one or two active-voice sentences: "We will …". Name the option picked.
+
+### Alternatives considered
+
+- **<Option A>** — why not (one line).
+- **<Option B>** — why not (one line).
+
+(The full comparison lives in the linked spec; capture just enough here to show the decision
+wasn't made in a vacuum.)
+
+## Consequences
+
+What becomes easier, and what becomes harder or is now owed as follow-up. Include the costs we
+knowingly accepted — the honest ones, not just the upside.
+
+- Positive: …
+- Negative / accepted cost: …
+- Follow-up owed: …
+
+---
+
+*Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>*

docs/adrs/README.md

@@ -0,0 +1,46 @@
+# Architecture Decision Records (ADRs)
+
+This directory is the **permanent decision spine** of the harness. An ADR captures **one
+significant decision** — the context that forced it, the choice made, and the consequences
+we accepted — in a form that stays true even as the code around it changes.
+
+## What an ADR is (and isn't)
+
+| | ADR | Spec (`../specs/`) | Plan (`../plans/`) |
+|---|---|---|---|
+| Answers | *what we decided & why* | *what & why, in depth* (alternatives, trade-offs, deferred) | *how, in what order* |
+| Size | short (one decision) | long (a whole design) | a checklist |
+| Retention | **permanent, immutable** | committed, point-in-time | **local-only, ephemeral** |
+| On change | write a **new** ADR that supersedes | add a `Status:` header, don't rewrite | delete once coded |
+
+An ADR is deliberately small: it records the *decision*, not the *design*. The full design
+lives in a dated spec under [`../specs/`](../specs/); the ADR links to it. Use an ADR when a
+choice is (a) hard to reverse, (b) cross-cutting, or (c) likely to be questioned later ("why
+Connect instead of raw gRPC?", "why is the harness filesystem-free?").
+
+## Rules
+
+1. **Immutable.** Once accepted, an ADR is never edited except to change its `Status` line
+   (e.g. to `Superseded by ADR-0007`). To change a decision, write a **new** ADR that
+   references and supersedes the old one. The record of *why we once thought otherwise* has
+   value.
+2. **Numbered, monotonic.** Files are `NNNN-kebab-title.md`, zero-padded, next free number.
+   Numbers are never reused.
+3. **One decision per ADR.** If you're recording two, write two.
+4. **Link to the spec.** The ADR states the decision; the spec carries the reasoning.
+
+## Status vocabulary
+
+`Proposed` → `Accepted` → `Superseded by ADR-NNNN` (or `Deprecated`). Same vocabulary as
+specs (see [`../specs/README.md`](../specs/README.md#documentation-lifecycle)).
+
+## Creating one
+
+```sh
+cp docs/adrs/0000-adr-template.md docs/adrs/NNNN-your-decision.md
+# fill in Context / Decision / Consequences; set Status: Accepted; link the spec
+```
+
+---
+
+*Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>*

docs/plans/README.md

@@ -0,0 +1,30 @@
+# Implementation plans (local-only, gitignored)
+
+Plans that describe **how** to build something — ordered steps, checklists, task
+breakdowns — live here **on your machine only**. Everything in this directory except this
+README is gitignored (see the repo `.gitignore`).
+
+## Why plans aren't committed
+
+A plan answers *how, in what order*. The moment the code merges, the code becomes the source
+of truth for *how* — the plan is now a stale, lower-fidelity copy. The durable value of our
+docs is the ***why***: the decisions and rejected alternatives. Those live in:
+
+- **[`../specs/`](../specs/)** — dated design docs (*what & why*, in depth).
+- **[`../adrs/`](../adrs/)** — permanent decision records (*one decision + consequences*).
+
+So a plan's whole life is: write it → execute it → **delete it**. Committing it would just
+create a maintenance burden that goes stale and misleads.
+
+## Workflow
+
+1. Write your plan here: `docs/plans/YYYY-MM-DD-<topic>.md` (named for the spec it implements).
+2. Execute it.
+3. Delete it once the work is coded and merged. The matching spec + the code carry everything
+   that remains true.
+
+New plans authored via the writing-plans workflow land here by convention.
+
+---
+
+*Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>*

docs/specs/README.md

@@ -135,15 +135,44 @@ live only in identity-keyed egress points. Dependency-ordered:
 
 ---
 
+## Documentation lifecycle
+
+Three artifact types, three lifecycles. Code is the source of truth for *how*; the durable
+value of docs is the *why* — decisions and the alternatives we rejected.
+
+| Artifact | Answers | Retention | Home |
+|---|---|---|---|
+| **Spec** (design doc) | *what & why* — alternatives, trade-offs, deferred work | committed, point-in-time; mark `Superseded by …`, don't delete | `docs/specs/` (here) |
+| **ADR** | one significant decision + context + consequences | committed, **permanent & immutable**, supersession-aware | [`docs/adrs/`](../adrs/) |
+| **Plan** (impl steps) | *how, in what order* | **local-only, ephemeral** — delete once coded; never committed | [`docs/plans/`](../plans/) (gitignored) |
+
+- A **spec** is a dated deep-dive. It's never retro-edited — a superseded spec gets a
+  `Status:` header pointing at its successor and stays in git as the point-in-time record.
+- An **ADR** is the permanent spine: a short, immutable record of a single decision that links
+  out to the spec for the full reasoning. See [`docs/adrs/README.md`](../adrs/README.md).
+- A **plan** is a throwaway checklist, obsolete the moment the code merges — so plans are
+  local-only work artifacts (gitignored). See [`docs/plans/README.md`](../plans/README.md).
+
+### Status vocabulary (specs & ADRs)
+
+Every spec and ADR carries a `Status:` line in its header, drawn from:
+
+> `Proposed` → `Accepted` → `Implemented` → `Superseded by <link>` (or `Deprecated`)
+
+When a design is replaced, set the old spec's status to `Superseded by <link to successor>`
+rather than deleting it — the record of what we once thought, and why we changed, has value.
+(For example, the removed Redis-transport remote-exec design is marked superseded by the
+gRPC/Connect sandbox-transport spec, which records the supersession in its own §12.)
+
 ## Conventions going forward
 
 - **New Phase-2 specs** take the next free **`Zx`** id and record it in this table.
 - **Filenames stay dated + descriptive** (`YYYY-MM-DD-<topic>-design.md`); the canonical `Zx` id
   lives here, not in the filename, to avoid rename churn.
 - Each spec keeps the existing header block (Version / Status / Scope / Builds-on); cross-reference
   by **canonical id** (e.g. "Z3") with the filename in parentheses on first mention.
-- Implementation plans live in `docs/superpowers/plans/` per repo convention, named for the spec
-  they implement.
+- Implementation plans live in [`docs/plans/`](../plans/) (local-only, gitignored), named for the
+  spec they implement, and are deleted once the work is coded and merged.
 
 ---