# Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)

Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`; the plan gates (`boundary`, then `testing` plan-gate mode) run in the same pass that writes the plan, against the still-`Draft` file — a plan is not finished, and is not shown as finished, until its `Gates:` line carries every verdict, so what the user approves is the gated plan. The status flips to `Status: In Progress` at the first implementation step, and the file freezes at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.

The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `testing` skill (plan-gate mode) writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.

**Both ledgers are read by a wall, so their cells obey a table's grammar.** A literal pipe inside a cell is written `\|` — the parser splits on unescaped pipes and unescapes what survives, so an escaped one is safe, and an unescaped one silently adds a column and shifts every later cell left. Prefer rephrasing (`` `install` or `update` ``) over escaping where the sentence allows it: the cell then reads the same to a person and to the wall.

**Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.

The **`Gates:`** line carries two machine-read segments. The compliance hook greps **`Boundary:`** — implementation edits inside the plan's scope are blocked while it reads `Boundary: pending`; the `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`. The other two plan gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. A **`Polygraph:`** segment appears only when the user has the `polygraph` agent audit the plan's documents — it appends `Polygraph: passed YYYY-MM-DD (N docs · N claims · N corrected · N registered)`, or `Polygraph: pending` while an owner question is open. It is a trace for readers, never an obligation: a plan carries none by default, no hook or CI check reads it, and it is never hand-written. Never hand-edit the line to skip a gate.

```
# {Feature Name}

**Status:** Draft | In Progress | Complete | Abandoned
**Gates:** Boundary: pending
**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)   <!-- one line per feature doc this plan implements against; a plan spanning three features names three -->
**Started:** YYYY-MM-DD
**Completed:** YYYY-MM-DD   <!-- fill in the SAME edit that flips Status to Complete — along with every ledger Outcome cell: the flip freezes the file instantly, so anything left for a second edit is unreachable (the frozen-record gate rightly blocks it) -->

## Background

Why this work is happening *now*. Link to the spec for *what* we're building; this section is the motivation and the trigger. One paragraph.

## Proposed Changes

### New Files

- `src/path/new-file.js` — purpose

### Modified Files

- `src/path/existing.js` — what changes and why

### New Entities / State

- `entities.foo` — new Redux slice / DB table / persisted shape
- Persisted state addition: `state.bar.baz` (default `null` for existing users on rehydrate)

### API Changes

- `POST /api/foo` — new route, request `{...}`, response `{status, data}`
- `PUT /api/bar` — request shape changes; see Migration

### Cross-Module Contracts Affected

- List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
- "None" is a valid answer and means the `boundary` check will pass cleanly

## Doc Obligations

<!-- One row per feature doc whose `owns:` globs intersect the Proposed Changes above — resolve
     them against the injected ownership index. Hand-authored: this is a lookup, not research.
     Amendable while the plan is open; discharged at Completion. -->

| Doc | Claim that changes | `owns:` still accurate? | Outcome |
| --- | --- | --- | --- |
| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — new paths to add | written empty; discharged at Completion — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog) |

**"None" is valid** — a plan touching only unowned paths owes no doc update, and says so explicitly. It is not a free pass: `boundary` builds its own touch list from the same Proposed Changes and reports docs this table missed.

## Implementation Steps

1. Concrete, ordered, testable
2. Each step ends with something verifiable
3. ...

## Test Obligations

<!-- Written by the `testing` skill (plan-gate mode) at the plan gate (after `boundary`). One row per
     promised behavior: layer · target file · oracle · fixtures · an empty Outcome cell the
     verification gate fills (satisfied / owes nothing / blocked → backlog). Amendable while the
     plan is open. Do not hand-author. NEVER put a pipe in a ledger cell, escaped or not — the
     compliance hook splits rows on `|` at a fixed column index with no unescaping, so a
     markdown-legal `\|` shifts every later cell and the wall blocks a row that is in fact
     discharged. Write "`install` or `update`", not "`install \| update`". -->

## Open Questions

- Question — who decides, by when

## Risks

- Risk — likelihood / impact / mitigation
```