workflow-toolkit 1.0.1

package/.agents/skills/wtk-lean/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: wtk-lean
+description: 'Run spec-driven feature work through a reviewed plan, proof-backed checks, build, and independent verification. Use for `.specs/features/` work; not modular task lists or standalone design.'
+license: CC-BY-4.0
+metadata:
+  author: Tech Leads Club - github.com/tech-leads-club
+  version: '1.0.0'
+---
+
+# Tech Lead's Club - Spec, Lean
+
+Run a decided feature through four moves: `PLAN → CHECKS → BUILD → VERIFY`. A human reviews the
+feature shape before checks freeze its obligations; builders choose reversible implementation detail;
+one fresh Verifier proves the complete feature. There is no task breakdown or component catalogue.
+
+## Core contract
+
+1. Every check is one observable claim with a concrete value and a proof whose exit code settles it.
+2. Tests come from the approved checks, never from the implementation. Do not weaken, skip, or
+   delete a test to pass a gate; a wrong or impossible check stops for user renegotiation.
+3. Approved `checks.md` and `Test policy` rows are fixed. New `Landing`, `Relations`, and `Surface`
+   rows may be added when building discovers a door, entity, or route; approved rows are never
+   rewritten. Keep `Flow` and `Impact` current when the path changes.
+4. The coordinator dispatches one fresh Verifier over `<feature base>..HEAD` with every check after
+   the last slice. The builder reports and stops; verification is never optional or self-authored.
+5. The declared profile is a floor. Its report names the profile and `validate_verification.py` must
+   exit 0. An approved spec authorizes local edits and commits only; push, deploy, and production
+   data changes require explicit authorization.
+
+## Profile
+
+`AGENTS.md` or the feature snapshot declares the profile. The resolver defaults to `standard`;
+`light`, `standard`, and `ui` remain valid upstream levels. The profile is a floor, not a preference,
+and `checks.md` plus the verification report must name the same value.
+
+```markdown
+## wtk-lean
+
+profile: standard
+budget: 150k
+```
+
+| Profile | Proof obligations |
+| --- | --- |
+| `light` | proofs at `HEAD`, named tests exist and ran, one located assertion per check, level/sampling gaps, and `Swept existing` re-read |
+| `standard` | light plus recomputed `Coverage`, `Test policy` verdicts, and one fault per assertion surface |
+| `ui` | standard plus binding-source comparison and per-screen copy and arrangement enumeration |
+
+An empty input costs a recorded line, not a skipped step. `validate_verification.py` rejects a
+profile mismatch and missing sections required by `standard` or `ui`. If the declared floor is too
+thin, ask the user to raise it rather than silently changing the profile.
+
+## Artifacts
+
+```
+.specs/
+├── STATE.md                    # Decisions log (AD-NNN) + Handoff snapshot
+├── LESSONS.md                  # rendered by scripts/lessons.py - never hand-edit
+├── lessons.json                # machine-owned
+└── features/<feature>/
+    ├── plan.md                 # problem, EARS criteria, surfaces walked, then flow, relations, surface, landing, impact
+    ├── checks.md               # claims + proofs, the coverage join, test policy, swept
+    └── verification.md         # the Verifier's report
+```
+
+Create each file when its phase produces content. For a change under roughly three files with no
+one-way door, write only `checks.md` with an `## Intent` paragraph and skip `plan.md` - one
+bounded escape, not a sizing matrix.
+
+The plan is the human review boundary: write criteria before shape, then record the shape that
+implements them. Its fixed sections are `Problem`, `Out of scope`, `Assumptions`, `Criteria`,
+`Traceability`, `Observable`, `Flow`, `Relations`, `Surface`, `Landing`, and `Impact`. `Flow` is
+the path, `Relations` the entities and one-way constraints, `Surface` the route/signature/statuses,
+`Landing` the literal irreversible choices and rejected alternatives, and `Impact` what existing
+terms or data change. Placement and reversible implementation detail stay in the diff.
+
+`checks.md` derives proof-backed checks from the plan and joins every enumerated route, entity,
+status, and door to a check. `plan.md`, `checks.md`, and `verification.md` therefore stay
+distinct: the first freezes reviewed shape, the second freezes obligations, and the third is the
+independent evidence. An unresolved architecture choice needs its own ADR/RFC/spike before it can
+be recorded as a `Landing` decision.
+
+## Phase references
+
+- **Plan:** human review of EARS criteria, boundary, surfaces, nine implicit dimensions, and the
+  five shape sections. Ask only genuine decisions; use `n/a - <reason>` where a dimension does not
+  apply. Full procedure and closure gate: [plan.md](references/plan.md).
+- **Checks:** derive proof-backed claims, join every enumerated set member, and record swept
+  landings: [checks.md](references/checks.md).
+- **Build:** tests come from checks; implementation decomposition is yours. Keep new `Landing`,
+  `Relations`, and `Surface` rows additive before closing code, then use the scope guardrail and
+  handoff procedure: [build.md](references/build.md).
+- **Verify:** after the feature's last slice, the coordinator sends one fresh Verifier over the
+  full range with every check; procedure and report schema: [verify.md](references/verify.md).
+- **Memory:** decisions, handoff, and lessons live in [memory.md](references/memory.md).
+
+## Scripts
+
+Resolve `<skill-dir>` as the directory containing this `SKILL.md` and invoke
+`python3 <skill-dir>/scripts/<name>.py`. Project data under `.specs/` stays relative to the
+project root; pass `--root` when cwd differs. A non-zero exit stops the phase.
+
+| When | Command |
+| --- | --- |
+| Before presenting the plan | `validate_plan.py <feature>` |
+| Before starting to build | `validate_checks.py <feature>` |
+| Before each commit | `check_commit.py --message "<msg>"` |
+| Before declaring done | `validate_verification.py <feature>` |
+| At distillation | `lessons.py add ...` |
+| After editing a validator or template | `selftest.py` |
+
+The validators own structural detail: `validate_plan.py` closes the human-reviewed shape,
+`validate_checks.py` catches missing proofs, coverage, swept rows, and profile, and
+`validate_verification.py` requires evidence, no surviving mutant, no `Unproven` member, and a
+non-author Verifier. Run `selftest.py` only after changing a validator or template. If execution is
+unavailable, perform the same checks by inspection and report the degraded path.
+
+## Sub-agents and handoff
+
+One builder owns whole slices sequentially. Before code, record the intended split and budget
+arithmetic under `## Handoff`; if reading exceeds the declared budget (default 150k tokens), hand off
+only between slices. Before handoff, the outgoing builder records closed checks, user decisions, and
+abandoned approaches, and continues only after every proof in the batch is green. The next builder
+reads the artifact and landed diff, not a narrative. Never split a slice or create a task DAG. The
+coordinator owns checkpoint synchronization and the final full-range Verifier; builders report and
+stop.
+
+## Knowledge chain
+
+Use existing code and conventions, project docs, library docs (Context7 where available), then web
+search; mark anything still uncertain. Never invent an API, flag, command, or behaviour.
+
+## Output
+
+Produce the artifact, lead with the verdict, and keep schema headings and identifiers unchanged.
+For a concrete feature path, `.specs/features/lockfile-v2/plan.md` is reviewed before its checks;
+the route then validates checks, builds, and dispatches the fresh full-range Verifier.

package/.agents/skills/wtk-lean/references/build.md

@@ -0,0 +1,168 @@
+# Build
+
+**Goal:** satisfy the checks. How is yours.
+
+No task list, no phase plan, no per-task review tables, no `Files to touch` declaration before
+each edit. The checks are the bar; the route is your call. If you find yourself writing a plan
+for the model to obey, you are rebuilding the thing this skill removed.
+
+## What is fixed and what is not
+
+Fixed: the checks, the `Test policy` rows, and the proofs each check names. Lowering either is
+renegotiation with the user, visible in the diff.
+
+Yours: order, decomposition, how many commits, where files go, naming, error shapes, which
+helper gets extracted. The repo's conventions answer most of it and the rest is reversible and
+reviewed in the diff.
+
+The plan's shape sections have a rule each, and the split matters because it is what keeps one
+file both approved and current.
+
+Additive: `Landing`, `Relations`, `Surface`. A door you discover while building gets a row - never
+a deletion, and never a rewrite of a row the user approved. `Relations` and `Surface` grow the
+same way, because both were reviewed: an entity or a route appearing mid-build is new information,
+one that quietly changes shape is a renegotiation.
+
+**Kept true: `Flow` and `Impact`.** They are a map, not an obligation, so changing them is not
+renegotiation - but a map that no longer matches the road is worse than none, because the next
+reader trusts it. Take a different path and the hop changes, in the commit that takes it. The rule
+is the same as `Landing`'s and for the same reason: written afterwards it describes what you
+happened to do, which is the failure mode of every architecture document that ever went stale.
+
+A hop you *add* is worth a second look before you write it. Reaching a fifth module in a feature
+scoped to two is not a `Flow` edit, it is evidence the boundary was wrong - say so rather than
+quietly extending the path.
+
+## Tests come from the checks
+
+Write the test from the check's claim and its concrete value. Never write a test by reading the
+implementation and asserting what it currently does: that produces a test that passes under the
+bug it was supposed to catch.
+
+**Hard constraints, no exceptions:**
+
+- Do not weaken an assertion to make it pass.
+- Do not delete a test, and do not use the framework's skip / disable / pending mechanism to
+  bypass a failing one.
+- Do not modify a check's test afterwards to make the implementation pass.
+
+A red proof is a stop, not a note. If a check turns out to be wrong or impossible, stop and
+renegotiate with the user. The same holds for a `Landing` row the user approved that the build
+proves unbuildable - they approved that shape specifically.
+
+Extra tests beyond the proofs are welcome and there is no quota. A guard clause, a log line, a
+clear error message at an edge the checks did not name: that is the work, not scope creep.
+
+## Landing rows go in before the code
+
+A door found mid-build did not exist when the design was confirmed, so it lands the same way that
+file's rows did. Decide it yourself - stopping to ask on every one defeats the point of getting out
+of your way. Then record it in `plan.md`: append the row with its literal shape and the
+alternative you rejected **before the code that closes it is written**, and in that code's commit.
+
+The timing is the mechanism. An alternative is only knowable while you are still choosing between
+them; written at the end it becomes a justification of what you already wrote, which is the stale
+design document `Landing` exists to avoid. Stating what the other option would have done is also
+the one thing that can expose a bad decision with nobody else in the loop.
+
+A new door that contradicts nothing already approved never stops the build.
+
+## Commit
+
+One coherent piece per commit, [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/):
+`<type>(<scope>): <description>`, types `feat` `fix` `refactor` `docs` `test` `style` `perf`
+`build` `ci` `chore`. Imperative mood, lowercase, no trailing period. A `!` marker requires a
+`BREAKING CHANGE:` footer.
+
+Validate before committing:
+
+```bash
+python3 <skill-dir>/scripts/check_commit.py --message "feat(billing): suspend on failed charge"
+```
+
+Optional git-level guard, independent of any agent:
+
+```bash
+ln -sf <skill-dir>/scripts/check_commit.py .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+```
+
+Skip the hook if the project manages hooks its own way. Mark the check complete in `checks.md`
+before the commit that satisfies it, and include that update in the same commit - a crash between
+those two steps is how a resume redoes finished work.
+
+Never add Co-Authored-By, Made-with, or any agent attribution trailer.
+
+## How to write the code
+
+Behavioural bias, not a checklist:
+
+**Simplicity.** No features beyond what was asked. No abstraction for single-use code. No
+"flexibility" nobody requested. No error handling for impossible scenarios. Two hundred lines
+that could be fifty: rewrite them.
+
+**Surgical changes.** Do not improve adjacent code, comments or formatting. Do not refactor what
+is not broken. Match existing style even where you would do it differently. Remove only the
+imports and variables your own change orphaned; pre-existing dead code gets mentioned, not
+deleted.
+
+**Push back.** Multiple interpretations exist: present them, do not pick silently. A simpler
+approach exists: say so. The user's approach looks wrong: disagree honestly.
+
+After each change, ask whether a senior engineer would call it overcomplicated. If yes, simplify
+before proceeding.
+
+## Scope guardrail
+
+You will notice things that could be improved. Do not act on them. A bug gets surfaced to the
+user; an improvement gets noted in chat or as a follow-up. The heuristic: is this in a check? If
+no, do not touch it.
+
+**Blast radius.** An approved spec authorizes local edits and local commits. `git push`,
+force-push, deploy, production DB changes and any other remote or destructive operation need an
+explicit go-ahead for that action, even mid-build.
+
+## Running out of context
+
+Two ways through it, and they are not equivalent. Automatic compaction summarises the
+*conversation* and chooses for you what to drop. A handoff to a fresh builder carries the
+*artifact*, at a boundary you chose. This skill is built for the second - that is why `Landing`
+rows are appended before the code that closes them rather than at the end.
+
+**Handing off.** Only on green, with every proof in the batch passing. The next builder reads
+`checks.md` and the **diff of what already landed** - never a narrative summary. The diff is the
+state, and it carries the hundred reversible choices that sit below the `Landing` bar: naming,
+error shape, where the helper went. Those are exactly what drifts between builders and exactly
+what no document records.
+
+Then append the three `## Handoff` lines - boundary, what the user settled mid-build, what was
+abandoned. They go in the artifact rather than in the next builder's prompt: a briefing written
+into a prompt survives exactly one boundary, and the third builder needs the first one's.
+
+**When compaction happens anyway,** re-read `checks.md` and the diff before continuing. You
+cannot see the limit approaching, but you can see that a compaction occurred - so build the
+recovery on the signal that exists.
+
+## Then stop
+
+When the last check of **your batch** is committed, report and stop: checks closed, commit
+hashes, proof results, deviations. Do not dispatch the Verifier - that is the orchestrator's
+step, after the last batch of the whole feature, over the full check set. A Verifier briefed by
+the builder that just closed the final batch inherits that builder's scope even though it
+inherits none of its tokens, and reports a pass over four checks that reads exactly like a pass
+over forty. See [verify.md](verify.md).
+
+## What was deliberately removed
+
+If you are used to a per-task cycle, these are gone on purpose:
+
+| Removed | Why |
+| --- | --- |
+| Granular task breakdown with `Where` / `Tools` / `Depends on` | buys ordering, not correctness, and competes with the checks for attention |
+| Per-task test adequacy review with evidence tables | author self-review reproduces the author's own blind spot; the Verifier does it once, better |
+| Pre-implementation assumption declaration per task | the assumptions that matter are in the spec, closed by its gate |
+| The component catalogue in a design doc - `Purpose` / `Location` / `Interfaces` / `Dependencies` per class | reversible detail that goes stale with the authority of a document; the plan keeps the path, the entities, the signature and the doors, and nothing per-component |
+| The `graph TD` architecture diagram, as the default rendering of the path | a picture of five boxes carries less than five lines that each say what enters, what crosses and what is handed on, and it rots silently while `Flow` is kept true through the build; a mermaid `flowchart` stays available for the case a list genuinely cannot express - a fan-out, a fork, an async hand-off |
+| The `Code Reuse Analysis` table - `Component` / `Location` / `How to Use` | the inventory is already distributed through `Flow`, where each hop marks whether its module exists; what a table adds beyond that is the catalogue again, so only the decision survives, as the sentence opening `Flow` on what is reused instead of duplicated |
+| The pace question (`Quick` / `Guided` / `Detailed`) and a `context.md` of its own | a meta-question spends a turn deciding how to spend turns; the elicitation rules apply always, and their output lands in the plan's `Assumptions` |
+| A quota of gray areas to generate per feature | a quota manufactures questions; the surface rubric in `## Observable` is a fixed enumeration with an `n/a` escape instead, which finds items without inventing them |
+| An offer to spawn sub-agents | logistics the user cannot decide better than you |

package/.agents/skills/wtk-lean/references/checks.md

@@ -0,0 +1,253 @@
+# Checks
+
+**Goal:** one small, frozen, external obligation set. Every claim carries the proof that
+settles it, and every enumerated set is joined member by member, so an omission leaves an empty
+cell instead of a confident sentence.
+
+This is the artifact everything downstream refers to by check number: a proof, a review
+comment, a question, a fault. It replaces a task breakdown - it says what must be true, never
+how to work.
+
+**It is derived, not decided.** [plan.md](plan.md) settled what must be true and what is being
+built; this turns both into obligations with proofs.
+So the shape - the path, the entities, the interface, the doors - is not written here and not
+re-argued here. What *is* this file's job is the derivation, and it is where omissions surface:
+every route's statuses in `Surface`, every door in `Landing`, every entity in `Relations` owes a
+set row in `Coverage` or a check. A shape section with nothing pointing back at it from here is
+either dead or unproven, and both are findings.
+
+## Find the real commands first
+
+Read the package manifest, the task runner and the CI workflows. Prefer a command that already
+runs in CI. Where nothing exists for what a check needs, ask - never invent a command, because
+a proof that cannot run is worse than none.
+
+A proof must name a **specific test**, not a whole suite. A suite going green settles no
+individual claim. Repeat `Proof:` when one test cannot settle the whole claim; every proof
+listed must be green.
+
+## What makes a check writable
+
+Four things must be true before you write one:
+
+- someone could **observe** the outcome - if you cannot say what would be seen, it is too vague
+- it carries a **concrete value** - a status code, a field, a bound
+- **one run settles it** - a single execution either satisfies it or does not
+- you can name the **proof** - the test or command whose exit code decides
+
+Missing one is normal and asking is cheap. Proceeding on a guess is not: a vague check becomes a
+vague assertion that passes, which is the failure this whole artifact exists to prevent.
+
+## The proof has to reach the claim
+
+Read the code before choosing the proof, then check the claim against the input space behind it.
+
+A claim about nine provider statuses is not proven by a test that exercises two - that gap needs
+a second proof, and it is a question about coverage rather than about test style. A claim phrased
+as a response at a boundary is not settled by a test that never crosses it. A claim about a
+decision table is not settled by one path through it. When the claim and the proof sit at
+different levels, either split the claim or name the second proof - never let the level slide to
+whichever is cheaper to write.
+
+**Obligations add up rather than substitute.** A test proves the layer where it *asserts*, not
+the layers it happens to *pass through*. An end-to-end test that traverses a branch exercises one
+path through it and cannot fail when a second branch is wrong. Treating it as proof of the code
+it traversed is level substitution, and it is the most common way a green suite ships a broken
+branch table.
+
+## Coverage - the join
+
+Every set a proof must cover gets a row, and **every member is written as its own token** beside
+the check that proves it.
+
+A set collapsed into a sentence - "dispatches over paused, updated, deleted and trial_will_end" -
+has no empty cell, so a member can go missing while the sentence still reads perfectly. That is
+how a branch named in your own evidence ships unproven. One proof that is table-driven over the
+whole set may stand for it, with the size stated, because there the enumeration lives in the test.
+
+Walk it **from the sets, not from the checks.** Summarising the checks you just wrote can only
+find a check with nothing behind it; it cannot find a name with no check, which is the failure
+that costs. The rows are not a new inventory - they are the enumerations already named somewhere:
+a door in the plan's `Landing`, a decision table in the level evidence, the input space behind
+a claim. Anything enumerated in prose owes a row here.
+
+**Every route in the plan's `Surface` owes a row, and its members are the statuses.** That row
+is the only thing that turns the signature you reviewed into an obligation; without it a status
+listed in the plan can ship with nothing behind it, and the artifact that named it looks like
+evidence that it was covered.
+
+Never assert a negative. Write the count and its denominator and let `-` in the `Unproven`
+column be earned by the row beside it.
+
+**Startup configuration is a set too, and its members are places.** A test suite assembles the
+application itself, so anything this change needs to be true before the first request arrives now
+lives in every assembly separately - and a proof can only ever assert the one it built. Each
+assembly is a member, including every app that mounts the module. The member is the place, never
+the value: the failure is not a wrong value, it is a value present in one assembly and absent from
+another. Two resolutions count - a proof at each place, or one shared assembly both paths use.
+Prefer the second; a row with two members is already the argument for collapsing them.
+
+## Test policy (`standard`, `ui`)
+
+Only when the repo does not already answer two questions for every layer this change touches:
+**which level proves this code**, and **how much of its input space must the proof assert to
+count**. Do not judge whether the repo "has testing docs" - it almost always does, and that
+impression is what makes this step never fire.
+
+A statement answers neither question when it only says where tests live, how they are named, how
+to run them, or how a test is built (which dependencies are real and which are doubled). Watch
+for the last one especially: keying the level to whether a test uses real dependencies decides
+*how* to write a test, and read as deciding *what deserves* one, every decision table that
+touches a real dependency gets routed away from its own layer and is never enumerated.
+
+Classify by the **shape of the code**, never by the name of the layer. Layer names lie.
+
+- **Instrumentation** - the body forwards its arguments to one call, or maps one shape onto
+  another with no conditional deciding the result. A test over it re-asserts the framework.
+- **Decision** - anything that changes an outcome. A dispatch over a status or event type. A
+  boundary or validation check. A state transition. A conditionally assembled payload. A mapping
+  table with more than one row. A guard, a precedence rule, an ordering rule.
+
+Count the decision points per file and write the number down: "dispatches over six event types,
+eleven branch points" is contestable, "looks like business logic" is not. Then **name the
+members**, because those names are what `Coverage` joins against.
+
+Derive from the code, not from the current suite - a module with no tests at a level is evidence
+about its history, not that its logic needs none. Judge the house pattern across the whole repo,
+not the folder you happen to be changing: search for the closest analogue by code shape - the
+other state machine, the other dispatcher - and cite it. A proposal pointing at a sibling proven
+at that level is precedent; one that does not is taste.
+
+State the cost. Then ask **one** narrow question: do these rows go into the repo's guidelines?
+Building under them is reversible and needs no permission; writing them reaches every future
+agent, so approved rows land in their own commit before the build. If the user does not answer,
+build under them and leave the files alone.
+
+## Template: `.specs/features/<feature>/checks.md`
+
+````markdown
+# <Feature> checks
+
+Profile: light
+Plan: `.specs/features/<feature>/plan.md`
+
+## Intent
+
+<Only when there is no plan.md - a change under three files with no one-way door: the problem in
+the present tense, then what is different for a user when this ships.>
+
+<N checks in M slices · K one-way doors · Q open, of which B block>
+
+## Checks
+
+Grouped by the spec's slices; numbering runs across the whole feature.
+
+### S1 - <slice> · 4 files · 38 KB · ~10k
+
+**C1** - A failed charge sets status to Suspended, never Cancelled (FEAT-01, AC 1)
+Proof: `bin/rails test test/billing/dunning_test.rb -n "/failed_charge_suspends/"`
+
+**C2** - Every provider status maps to exactly one local status (FEAT-01, AC 4)
+Proof: `bin/rails test test/billing/status_map_test.rb -n "/every_provider_status/"`
+
+### S2 - <slice> · 9 files · 140 KB · ~35k
+
+**C3** - Retrying the same webhook delivery id changes nothing (FEAT-02, AC 5)
+Proof: `bin/rails test test/webhooks/ingest_test.rb -n "/retry_is_idempotent/"`
+
+## Coverage
+
+| Set (size) | Member -> proof | Unproven |
+| --- | --- | --- |
+| provider status -> local (9) | C2, table-driven over all 9 | - |
+| webhook event types (5) | `paused` C12 · `updated` C13 · `deleted` C14 · `trial_will_end` C15 · other C16 | - |
+| `trial_days` bound (4 edges) | 0 C5 · 1 C5 · 30 C5 · 31 C5 | - |
+| `Suspended` transitions (3) | into it C1 · out to `Active` C6 · out to `Cancelled` C7 | - |
+| `POST /webhooks/provider` statuses (3) | 200 C3 · 409 C7 · 422 C16 | - |
+| startup config: raw request body (2 assemblies) | app entry point C17 · test harness C3 | - |
+
+- Claims naming a status code, route or response shape: C7, C12, C16 - each has a proof that
+  crosses the boundary
+- No other check claims more than the single case its proof exercises
+
+## Test policy
+
+<Only at `standard` / `ui`, and only when the repo leaves the two questions open. Omit the
+section entirely otherwise.>
+
+| Code | Required proofs | Coverage expectation |
+| --- | --- | --- |
+| Decides, reached across a boundary | one at the boundary **and** one at its own layer | the contract at the boundary; one asserted case per row of the decision table at its own layer |
+| Decides, not reached across a boundary | one at its own layer | one asserted case per row of the decision table |
+| Entry point that decides nothing | one at the boundary | accepted input, each rejected input, each error path |
+| Instrumentation, pass-throughs | none of its own | covered by its consumer's proof |
+
+Evidence:
+
+- `<file>`: dispatches over <n> cases, <n> branch points -> decides
+- `<file>`: forwards a single call, no conditional -> instrumentation
+- closest analogue in the repo: `<file>`, same shape, already proven at this level with <n> cases
+
+Cost: <n> proofs at their own layer across <n> files. Without these rows, <n> decision tables are
+proven only by a path that happens to traverse them.
+
+## Swept
+
+Where each unwritten requirement landed. All nine, one line each, every time.
+
+- validation: C5
+- failure modes: C1
+- idempotency: C3
+- authorization: existing - <the guard or policy that already covers this>
+- concurrency: C7
+- data lifecycle: n/a - <why it does not apply>
+- dependency failure: C6
+- state transitions: C1, C2
+- observability: n/a - no logging requirement in this slice
+
+## Out of scope
+
+- <excluded capability> - <why>
+
+## Handoff
+
+Intended split, with the arithmetic, written before any code:
+
+- S1-S3 = 118k, all in Billing; S4 enters Webhooks at 140k -> hand off after S3
+
+<Appended by each builder as it finishes, three lines each:>
+
+- **Boundary:** C1-C7 closed at `<sha>`
+- **Settled mid-build:** <every clarification the user gave that did not become a Landing row or an edited check>
+- **Abandoned:** <tried, discarded, and why>
+````
+
+`Out of scope` is only needed when there is no plan, which already carries it - along with
+everything about the requirements and the solution's shape: [plan.md](plan.md).
+
+## Gate before building
+
+```bash
+python3 <skill-dir>/scripts/validate_checks.py <feature>
+```
+
+It fails a check with no `Proof:`, a duplicate check id, a coverage row whose declared size
+exceeds the members actually assigned, a coverage row with an empty member cell, a missing swept
+dimension, a swept landing left blank, and a missing `Profile:` line. It warns on a proof that
+names no test selector, on a claim carrying a vague word, and - the derivation check - on a route
+the plan's `Surface` names that nothing here mentions.
+
+A non-zero exit means fix before writing code. The script checks structure; the judgment - is the
+proof the right one, does the level match the claim - stays yours.
+
+## Then keep going
+
+Write the artifact and continue into [build.md](build.md). Waiting for approval by default buys
+nothing when the plan was already confirmed and the checks derive from it. Stop only for: scope
+the sweep raised that would grow the work, a derivation that contradicts the approved plan -
+which sends you back to that file, not around it - anything the writability gate caught that
+asking did not resolve, and writing test-policy rows into the repo's guidelines.
+
+What keeps this reviewable is the ordering, not a commit: the artifact is complete before you
+touch code, so it reads as what you were building toward rather than a rationalisation of what
+you built.