docs(plans): require absorbing deferrals into downstream plans

"Deferred to <plan>" in a closeout Follow-ups section was a pointer
that didn't oblige anyone to do anything — the downstream plan
could ship without ever absorbing the deferred work, and the
deferral would rot in place. Caught when reviewing the workspace
plan's .env.example follow-up.

Tighten:

  * "Deferred to <plan>" is only valid when the downstream plan is
    still `status: planned`
  * The same closeout commit must edit that downstream plan to
    absorb the deferral — typically a new bullet under Approach and
    a new criterion under Validation
  * If the downstream plan is `in-progress` or `done`, use the
    Issue shape instead — never modify a plan that's actively being
    implemented or already frozen

Applied immediately to plans/api-skeleton.md to demonstrate the
protocol and actually close the workspace deferral:

  * Approach.Env validation gains a paragraph requiring
    .env.example to ship with one entry per EnvSchema field
  * Validation gains a checkbox confirming it exists, cross-linked
    back to the workspace plan that deferred it

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: themightychris

.claude/CLAUDE.md

@@ -40,7 +40,7 @@ Plans index: [plans/README.md](../plans/README.md). Workflow:
    - **Notes** section: non-actionable carry-forwards — decisions, surprises, gotchas, learnings. Things future-you would want to know.
    - **Follow-ups** section: actionable items that didn't ship with this plan. Each entry is one of:
      - `Issue [#N](link) — short description` — when actionable and not owned by an existing planned-or-in-progress plan, file the issue first (`gh-axi issue create`) and link it
-     - `Deferred to [`<other-plan>`](<other-plan>.md) — short description` — when the work is owned by a downstream plan already
+     - `Deferred to [`<other-plan>`](<other-plan>.md) — short description` — when an unstarted (`status: planned`) downstream plan should own the work. **The same closeout commit must also edit that downstream plan to absorb the deferral** — typically a new bullet under Approach and a new criterion under Validation. If the downstream plan is already `in-progress` or `done`, use the Issue shape instead; never modify a plan that's actively being implemented or already frozen.
      - `Tracked as: <free-form pointer>` — for anything else (waiting on community input, vendor response, etc.)
      - `None.` — explicit when there's nothing, so a future reader can see the section was considered, not just absent
    - The plan is frozen after merge — historical record, no further edits

plans/README.md

@@ -10,7 +10,7 @@ Documented in [`.claude/CLAUDE.md`](../.claude/CLAUDE.md#plans). Briefly:
 
 1. Add a plan to start new work. `status: planned` and `depends:` set.
 2. Move to `in-progress` when starting, as the first commit on the branch (`chore(plans): mark <slug> in-progress`). Skippable for tiny plans.
-3. **Move to `done` as the last commit on the branch, before merge.** That one commit (message: `chore(plans): mark <slug> done (PR #<n>)`) flips frontmatter to `status: done` + `pr: <n>`, ticks each verified validation checkbox, fills in **Notes** (decisions and gotchas worth carrying forward), and fills in **Follow-ups** (actionable items not shipped). Unverifiable criteria stay `[ ]` with a Notes entry explaining where they'll close out — never rewrite a criterion to match what you ended up doing.
+3. **Move to `done` as the last commit on the branch, before merge.** That one commit (message: `chore(plans): mark <slug> done (PR #<n>)`) flips frontmatter to `status: done` + `pr: <n>`, ticks each verified validation checkbox, fills in **Notes** (decisions and gotchas worth carrying forward), and fills in **Follow-ups** (actionable items not shipped). Unverifiable criteria stay `[ ]` with a Notes entry explaining where they'll close out — never rewrite a criterion to match what you ended up doing. When a Follow-up takes the "Deferred to `<plan>`" shape, the same commit must also edit that downstream plan to absorb the deferral (Approach + Validation) — and the downstream plan must still be `planned`; otherwise file an issue.
 4. After merge: frozen. Historical record, no further edits.
 5. A plan implements specs that already exist. If specs need to change mid-plan, the spec change is its own PR before the plan continues.
 

plans/api-skeleton.md

@@ -62,6 +62,8 @@ export const EnvSchema = z.object({
 
 Validation runs at boot; bad config exits 1 with a clear error. No `process.env.X` reads outside `env.ts`.
 
+Ship a `.env.example` file at the repo root that enumerates every `EnvSchema` field with placeholder values + an inline comment per field describing what it's for. This is what new contributors `cp .env.example .env` on first checkout. Keeps the `EnvSchema` and `.env.example` in lockstep is a per-PR review concern; if it drifts, that's a CI follow-up worth filing.
+
 ### Response envelope
 
 `apps/api/src/lib/response.ts` exports:
@@ -113,6 +115,7 @@ In-memory `Map<personId+key, cachedResponse>` with a 24h TTL. Mutating endpoints
 - [ ] Per-IP rate limit kicks in: 61 anonymous reads from the same IP within a minute → 429 with `Retry-After`
 - [ ] Repeat POST with the same `Idempotency-Key` returns the cached response (verified by a stub route)
 - [ ] `/api/_openapi.json` returns a valid OpenAPI 3.1 document; `/api/_docs` renders Swagger UI
+- [ ] `.env.example` exists at the repo root with one entry per `EnvSchema` field (deferred from [`workspace`](workspace.md))
 - [ ] CI passes type-check + tests
 
 ## Risks / unknowns