docs: correct 12 stale spec statuses and 2 shipped plans, and record the rule (#159)

A `status:` line is written once, at authoring time, and nothing updates it when
the work lands. Measured across docs/superpowers on 2026-08-03:

  12 of 47 specs claimed draft / "design (plan pending)" / "DESIGNED — ready for
  a plan" for work already on main — including staged-context verification,
  which said "ready for a plan" the day after it merged in #152.

  2 plans still carried `status: pending` on every task for code shipped in May,
  under a header instructing agents to execute them. Following that header would
  have meant re-implementing the live DispatchExecutor and orchestrator.

Every correction cites the marker verified on main (`context-check.ts`,
`executors/dispatch.ts`, `secret-store/`, `audit/audit-log.ts`,
`mailbox/local-dir.ts`, `buildGitEnv`, `terminationSignal`, and so on), and keeps
the original text under **Originally:**. Only specs with positive code evidence
were touched: cron-trigger, the three callback specs, mneme integration and
worker-env-block-exposure were left alone, because their statuses are accurate —
that work genuinely is not built.

The two shipped plans get a HISTORICAL header rather than flipped task markers.
Flipping them would fake a per-task verification nobody performed; the markers
describe the plan at authoring time, and that is worth preserving.

Added docs/superpowers/README.md stating the rule — update the status in the PR
that lands the work — and explaining why there is deliberately no status index:
it would need the same maintenance these lines already fail to get, and would
become a second stale source disagreeing with the first.

Same class as the KNOWN-ISSUES backfill (#156): a marker that is not maintained
is worse than none, because it is believed.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: BrettNye

docs/superpowers/README.md

@@ -0,0 +1,38 @@
+# `docs/superpowers/`
+
+`specs/` holds design documents. `plans/` holds the DAG plans that execute them.
+
+## The one rule: a status marker is a claim, not a fact
+
+**Verify a `status:` line against the code before believing it.** These markers
+are written once, when the document is authored, and there is no mechanism that
+updates them when the work lands. They rot silently, and they rot in the
+direction that wastes the most time — a shipped thing still advertising itself as
+unbuilt.
+
+Measured on 2026-08-03: **12 of 47 specs** claimed `draft` / `design (plan
+pending)` / `DESIGNED — ready for a plan` for work that was already on `main`,
+including one marked "ready for a plan" the day after it merged. Two plans in
+`plans/` still carried `status: pending` on every task for code that shipped in
+May, under a header instructing agents to execute them — which would have meant
+re-implementing live code.
+
+That is the failure mode to guard against. It is not a filing inconvenience: an
+agent or a consumer scanning for work takes these lines literally.
+
+## When you touch a spec or plan
+
+- Landing the work? **Update the status in the same PR.** It is one line, and it
+  is the only moment anyone reliably knows the truth.
+- Correcting a stale marker? Say what you verified (`Verified on main: <path>`)
+  and keep the original text under **Originally:**. What was believed, and when
+  it stopped being true, is part of the record.
+- A plan that shipped is **historical**. Mark it so at the top, and do not
+  silently flip its per-task markers — those describe the plan at authoring time,
+  and rewriting them fakes a verification nobody performed.
+
+## Why there is no status index here
+
+An index would need the same maintenance the `status:` lines already fail to get,
+and would then be a second stale source disagreeing with the first. The rule
+above is the durable version. If you want current state, read the code.

docs/superpowers/plans/2026-05-29-agora-dispatch-executor-dag.md

@@ -3,6 +3,15 @@ title: agora dispatch-executor (PR3)
 created: 2026-05-29
 ---
 
+> **HISTORICAL — this plan shipped. Do NOT execute it.** (Added 2026-08-03.)
+> The per-task `status: pending` markers below were never updated when the work
+> landed; verified on main: `packages/pangolin-orchestrator/src/executors/dispatch.ts`
+> exists and is the live `DispatchExecutor`. The markers are kept as authored so
+> the plan still reads as the record of how the work was decomposed — but they
+> describe the plan's state at authoring time, **not** the state of the codebase.
+> An agent reading the line below and executing this plan would re-implement
+> shipped code.
+
 > **For agentic workers:** REQUIRED SUB-SKILL: Use parallel-dag-execution:executing-dag-plans to execute this plan. Per-task `status` frontmatter is the source of truth.
 
 ```mermaid

docs/superpowers/plans/2026-05-29-agora-orchestrator-skeleton-dag.md

@@ -3,6 +3,15 @@ title: agora-orchestrator skeleton (PR2)
 created: 2026-05-29
 ---
 
+> **HISTORICAL — this plan shipped. Do NOT execute it.** (Added 2026-08-03.)
+> The per-task `status: pending` markers below were never updated when the work
+> landed; verified on main: `packages/pangolin-orchestrator/src/engine/tick.ts`
+> and the surrounding orchestrator are live and have been extended many times
+> since. The markers are kept as authored so the plan still reads as the record
+> of how the work was decomposed — but they describe the plan's state at
+> authoring time, **not** the state of the codebase. An agent reading the line
+> below and executing this plan would re-implement shipped code.
+
 > **For agentic workers:** REQUIRED SUB-SKILL: Use parallel-dag-execution:executing-dag-plans to execute this plan with continuous parallel subagent dispatch. Per-task `status` frontmatter is the source of truth; the mermaid block is regenerated on every save.
 
 ```mermaid

docs/superpowers/specs/2026-05-21-agora-mvp-design.md

@@ -5,7 +5,7 @@ type: spec
 created: 2026-05-21
 updated: 2026-05-21
 wiki: _meta
-status: draft
+status: **SHIPPED — status corrected 2026-08-03.** Verified on main: `packages/pangolin-{core,client,worker}`. This line previously read "draft", which was stale: the work landed and the marker was never updated. **Originally:** draft
 summary: "Caller-side SDK that lets integrators register versioned subagents, capabilities, and env bundles, then dispatch a containerized Claude Code sub-agent to a compute target by reference. Worker fetches registered artifacts at boot, overlays capabilities as filesystem layers, invokes the sub-agent, returns the result. Pluggable interfaces for compute, credentials, storage, channels, result sinks, and telemetry. Strict orthogonality: agora knows nothing about Stoa, Bedrock, RaState, or any other Quarry Systems library."
 author: agent:claude-code
 ---

docs/superpowers/specs/2026-05-29-agora-dispatch-executor-design.md

@@ -1,7 +1,7 @@
 ---
 title: Agora dispatch-executor (PR3) — design
 date: 2026-05-29
-status: design (approved; plan pending)
+status: **SHIPPED — status corrected 2026-08-03.** Verified on main: `pangolin-orchestrator/src/executors/dispatch.ts`. This line previously read "design (approved; plan pending)", which was stale: the work landed and the marker was never updated. **Originally:** design (approved; plan pending)
 authors: [human:Brett, agent:claude-opus-4-8]
 relates_to: docs/superpowers/specs/2026-05-28-agora-orchestrator-design.md (§4 Executor, §6 D6)
 ---

docs/superpowers/specs/2026-05-29-secretstore-unification-design.md

@@ -1,7 +1,7 @@
 ---
 title: SecretStore unification — every secret through one adapter seam
 created: 2026-05-29
-status: draft
+status: **SHIPPED — status corrected 2026-08-03.** Verified on main: `packages/pangolin-secret-store/`. This line previously read "draft", which was stale: the work landed and the marker was never updated. **Originally:** draft
 ---
 
 # SecretStore unification

docs/superpowers/specs/2026-05-31-agora-offload-audit-design.md

@@ -1,7 +1,7 @@
 ---
 title: Agora Offload — offload-audit wave design (tamper-evident audit log)
 date: 2026-05-31
-status: design (approved direction; implementation plan pending)
+status: **SHIPPED — status corrected 2026-08-03.** Verified on main: `pangolin-orchestrator/src/audit/audit-log.ts`. This line previously read "design (approved direction; implementation plan pending)", which was stale: the work landed and the marker was never updated. **Originally:** design (approved direction; implementation plan pending)
 branch: feat/offload-audit
 authors: [human:Brett, agent:claude-opus-4-8]
 builds_on: "[[docs/superpowers/specs/2026-05-29-agora-offload-v1-design.md]]"

docs/superpowers/specs/2026-05-31-agora-offload-mailbox-design.md

@@ -1,7 +1,7 @@
 ---
 title: Agora Offload — Mailbox Seam (real submission backend)
 date: 2026-05-31
-status: design (approved direction; implementation plan pending)
+status: **SHIPPED — status corrected 2026-08-03.** Verified on main: `pangolin-orchestrator/src/mailbox/local-dir.ts`. This line previously read "design (approved direction; implementation plan pending)", which was stale: the work landed and the marker was never updated. **Originally:** design (approved direction; implementation plan pending)
 branch: docs/agora-offload-v1-spec
 authors: [human:Brett, agent:claude-opus-4-8]
 builds_on: "[[docs/superpowers/specs/2026-05-29-agora-offload-v1-design.md]]"

docs/superpowers/specs/2026-05-31-agora-offload-surface-design.md

@@ -1,7 +1,7 @@
 ---
 title: Agora Offload — offload-surface wave design (operator surface)
 date: 2026-05-31
-status: design (approved direction; DAG plan pending)
+status: **SHIPPED — status corrected 2026-08-03.** Verified on main: `packages/pangolin-cli + packages/pangolin-mcp`. This line previously read "design (approved direction; DAG plan pending)", which was stale: the work landed and the marker was never updated. **Originally:** design (approved direction; DAG plan pending)
 branch: offload-surface
 authors: [human:Brett, agent:claude-opus-4-8]
 builds_on:

docs/superpowers/specs/2026-06-01-agora-docs-site-design.md

@@ -1,7 +1,7 @@
 ---
 title: Agora Documentation Site — Architecture & Structure Spec
 date: 2026-06-01
-status: draft
+status: **SHIPPED — status corrected 2026-08-03.** Verified on main: `docs-site/ (deployed by the Deploy docs site workflow)`. This line previously read "draft", which was stale: the work landed and the marker was never updated. **Originally:** draft
 branch: docs/agora-docs-site-spec
 authors: [human:Brett, agent:claude-opus-4-8]
 builds_on: "[[docs/superpowers/specs/2026-05-29-agora-offload-v1-design.md]]"