workflow-toolkit 1.0.1

package/.agents/skills/wtk-implement/references/checklist-format.md

@@ -0,0 +1,116 @@
+# Checklist format
+
+Load this file only when writing `.checks/<feature>.md` — after the source is read, the refuse gate is passed, and the sweep is walked. Do not load it during the first pass of Extract.
+
+Replace every placeholder with a concrete value, or omit the section. A heading with "N/A" under it does not appear.
+
+## Template
+
+Write `.checks/<feature>.md`:
+
+```markdown
+# <Feature>
+
+Sources:
+
+- <ticket URL, document path, or "conversation"> - <what it settles>
+- <design / screens> - **binding for the interface**: screens <ids>
+
+## Out of scope
+
+- <excluded capability> - <why>
+
+## Landing
+
+<Two or three lines: which modules this touches and what it reuses instead of duplicating.>
+
+| One-way door | Literal shape | Alternative rejected |
+| --- | --- | --- |
+| `subscription.status` gains `Suspended` | enum value, not null, existing rows backfilled to `Active` | a boolean `is_suspended` - cannot express the next state |
+| Provider status mapping becomes a module-level table | `map(providerStatus) -> localStatus`, total over the provider's 9 values | an inline switch per call site, the convention today - it drifts silently when the provider adds a status |
+
+- Nothing else in this change is hard to reverse
+
+## Checks
+
+### S1 - Suspension on a failed charge · 4 files · 38 KB · ~10k
+
+**C1** - A failed charge sets status to Suspended, never Cancelled
+Proof: `pytest tests/billing/test_dunning.py::test_failed_charge_suspends`
+
+**C2** - Every provider status maps to exactly one local status
+Proof: `pytest tests/billing/test_status_map.py::test_every_provider_status_maps`
+
+### S2 - Webhook ingest · 9 files · 140 KB · ~35k
+
+**C3** - Retrying the same webhook delivery id changes nothing
+Proof: `bun test -- -t "retry is idempotent"`
+
+## Swept
+
+- validation: C5
+- failure modes: C1
+- idempotency: C3
+- authorization: existing auth guard already covers this route
+- concurrency: C7 - second concurrent start returns 409
+- data lifecycle: not in scope - nothing is retained
+- dependency failure: C6
+- state transitions: C1, C2
+- observability: not in scope - no log requirement in V1
+
+## 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 | - |
+| `trialDays` bound (4 edges) | 0, 1, 30, 31 all in C5 | - |
+| `Suspended` transitions (3) | into it C1 · out to `Active` C6 · out to `Cancelled` C7 | - |
+| 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
+```
+
+**Sources** is a list because what feeds this is a list. A task normalises several documents - a ticket, a PRD, a design, a branch - and a single-line field quietly keeps the ones that look like documents. Carry every source the upstream artifact names, each with what it settles, and mark the design as binding for the interface. Losing one here is a failure of Extract rather than a formatting preference: what does not cross into this file stops existing for whoever builds, and the design is the usual casualty, because it is the only source that is not prose.
+
+`Landing` carries the doors this change closes and nothing else. A door is one-way when reversing it costs more than a refactor: a persisted schema, a contract someone else consumes, a new dependency, a data backfill - and a pattern the codebase does not have yet, because precedent stops being reversible once the next features have copied it. Each row shows the **literal shape** the next person will copy and what you rejected, named with the property that disqualified it: "cleaner" cannot be argued with, "cannot express the next state" can. Where the choice was forced rather than compared, name the constraint that forced it; where two options were live, give each one a row. For a pattern the rejected option is the convention already in the code. Decomposition inside a convention that already exists is not a door: it is reversible at the cost of a refactor, and writing it down produces exactly the design document that goes stale and then misleads. `None - <why nothing here is one-way>` is a complete answer, and the closing line is what makes the omission contestable.
+
+That deferral is what keeps this skill from emitting a design document, and it presupposes something to defer to. Where there is no convention to read, both halves are empty at once - nothing written down and nothing to inherit - and the work belongs in a flow that does design before this one starts.
+
+Where the repo already keeps a decision log or ADRs, append the rows that outlive this feature there once the checklist is approved - the checklist stops being read after the merge, and a choice with its rejected alternative keeps its value long after the code has moved. Do not start a log for this skill.
+
+**Checks group under the slices they came from.** The upstream task already cuts the work into slices of one observable outcome each; flattening them into `C1..Cn` loses a structure the source had and that `## Handoff` later refers to by name. Keep the slice, keep its name, number the checks straight through.
+
+Each slice heading carries its **size**, and the arithmetic is `wc -c` on the files that slice touches - the ones its checks land in, which `Landing` and your own walk already named - divided by four. That is a floor: it counts what you will read, not the iteration on top, which is the larger and less predictable half. It is still worth writing, because ranking slices by weight is the decision, and a floor ranks correctly even when it under-counts.
+
+A check is **one** observable claim. If you need "and", split it. The proof must name a specific test, not a whole suite - a suite going green says nothing about *this* claim. Repeat `Proof:` when one test cannot settle the whole claim, and every proof listed must be green.
+
+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 proof that exercises two - that gap needs a second proof, and it is a question about coverage rather than about test style.
+
+The proof also has to be able to **reach the claim's subject**. A claim phrased as a response at a boundary is not settled by a test that never crosses it, and 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 one is cheaper to write.
+
+**The level is the project's call, not this skill's** - but a proof settles the layer it asserts at, never the layers it passes through, so a claim proven at the boundary leaves the decision table behind it unproven. Follow what the repo declares - `AGENTS.md`, contributing docs, testing guidelines - and where its declaration does not say which code must be proven at which level and how deeply, derive that from the shape of the code, propose it with the checklist, and write the approved rows into the repo's own guidelines so the next run inherits them - under `standard` or `ui`, following [test-policy.md](references/test-policy.md); under `light` follow the repo and leave the gap unclosed, which is one of the things that profile buys you. Never impose a pyramid the codebase does not have, and never read a thin existing suite as the bar for logic it does not cover.
+
+`Coverage` answers the sampling question in writing, while it is still cheap to act on. It is a **join, not a summary**: every set a proof must cover gets a row, and every member of that set 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.
+
+The rows are not a new inventory - they are the enumerations this artifact has already named somewhere: a door in `Landing`, a decision table in the test-policy evidence, the input space behind a claim. Anything you enumerated in prose owes a row here, which is the point: the two places have to agree, and only one of them can hide a member.
+
+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. And state the gap as members rather than as an absence: `deleted` sitting in the `Unproven` column is contestable by anyone reading, while "nothing is missing" can only be checked by redoing the entire allocation, so nobody does. Never assert a negative here - write the count and its denominator, and let `-` 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, so the size of the row is the number of assemblies rather than always two. The member is the place and never the value: the failure is not a wrong value, it is a value present in one assembly and absent from another, and a row whose member is the setting collapses into a single cell that cannot be empty.
+
+Two resolutions count - a proof at each place, or one shared assembly both paths use. Prefer the second: it deletes the seam instead of testing it twice, and a row with two members is already the argument for collapsing them. When the setting already lives in exactly one place both paths share, no row is owed, and that is the better state rather than a loophole. A proof that passes only because the test assembles the system differently from production is **assembly substitution** - the same family as the level substitution in [test-policy.md](references/test-policy.md), and invisible to every coverage policy there is, because the branch *is* covered and only the assembly differs.
+
+Under `profile: ui` the designed screens are a set too, with a row of their own - [screens.md](references/screens.md) has its shape.
+
+The last two lines close the level gap the same way. List every check whose claim names a status code, a route or a response shape; each of them needs a proof that crosses the boundary. Writing the ids down is the whole mechanism: a check claiming a `400` while all its proofs sit below the boundary has to appear in that list, and the line is then false on its face.
+
+Find the real commands first: read the package manifest, the task runner and the CI workflows. Prefer a command that already runs in CI. When nothing exists for what a check needs, ask - never invent a command, because a proof that cannot run is worse than none.
+
+Then write the checklist and keep going into Build. Waiting for approval by default buys nothing when someone already decided the source and the checklist mostly restates it.
+
+**What keeps it 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. Where the project tracks `.checks/`, that ordering is worth a commit of its own before any code; where the project ignores it - which is common, and correct for a working artifact the skill says stops being read after the merge - the ordering still holds and nothing about it depends on git.
+
+Stop only for what the user alone can settle: a `Landing` door with a live alternative - a forced choice needs no permission, a chosen one does; scope the sweep raised that would grow the work; anything the refuse-rather-than-guess door caught that asking did not resolve; and writing test-policy rows into the repo's guidelines, which you build under either way. Stop at the artifact when the request asked for the checklist alone.

package/.agents/skills/wtk-implement/references/screens.md

@@ -0,0 +1,129 @@
+# Screens
+
+**Read this only under `profile: ui`.** Under `light` or `standard` the interface is out of
+scope for the checks, and loading this file costs a run that will not use it.
+
+## The design decides, the check records
+
+**On a screen the concrete values live in the design, so open it before writing the check.**
+"Renders the intake" and "the body includes montando" pass under any interface at all - that is
+"gracefully" wearing a string literal. Not fidelity, which no exit code settles, but the values
+that are assertable and only the design carries: which elements exist, what the labels say, what
+the step counter reads, whether a state is its own screen or a band on one that already exists.
+Named, they are settled by the runner like every other check.
+
+**A design is binding, not reference.** When a check and the design disagree, the check is wrong
+until the user says otherwise. This is the failure worth naming, because it does not look like
+one: a checklist that contradicts the design ships the contradiction with every proof green, and
+the build is then correct against the artifact and wrong against the decision.
+
+**It also outranks the screen that is already there.** Reuse is about components - the card, the
+button, the container - never about a layout the design replaced. When the feature lands on an
+existing screen and the design draws that screen differently, the old composition is the thing
+the change is for; keeping it because it was already built is the most comfortable way to ship
+the wrong screen with every check green.
+
+## When the repo has a design system
+
+Both are binding and they do not collide, because they decide different things. **The design
+decides structure and hierarchy** - which regions exist, what contains what, which indicator, in
+what order. **The system decides the values that realise it** - the colour token, the type scale,
+the spacing scale, the component that already exists.
+
+So never lift a hex or a font family out of a mock into a repo that has tokens: that breaks
+theming, and the system is right. And never surrender the arrangement on the way there. "Use the
+tokens" answers colour and answers nothing at all about whether the progress indicator is a ring
+or a bar. Where a value in the mock has no token to land in, that is a finding for the user, not
+a licence to redraw the screen around what the system already had.
+
+## Open it, and say how
+
+**Resolve it before writing a screen check, and do not assume you cannot.** Most designs are
+reachable: an artifact URL opens with a fetch, a design file opens through its MCP where one is
+connected, an attachment on a tracker issue comes down through that tracker's API, and an image
+committed to the repo is a file to read. Work through whatever the environment actually offers,
+then say which route worked - "the link was in the ticket" and "I opened the design" are
+different claims, and only one of them is evidence.
+
+**Opened means you saw the screens, not that a fetch returned bytes.** A design attachment often
+arrives as something that is not an image: a JS bundle, an archive, a page whose markup is a
+loader. Downloading that and recording the source as opened is the worst of the three outcomes,
+worse than reporting it unreachable, because the checklist then claims an authority nobody
+consulted and every later step trusts the claim. If you cannot see the arrangement, the design is
+**unresolved** - say what came back, mark the screen checks as written without it, and let the
+`Unproven` column carry the composition.
+
+Falling back is allowed; doing it silently is not, and neither is falling back without trying -
+a link reported as inaccessible on the strength of its domain is a fabricated fact, not caution.
+When nothing resolves, record against the entry in `Sources` what you attempted and what came
+back, build the screen checks from the values the task transcribed, and mark those checks as
+written without the design. An unresolved design is a finding somebody can act on; an
+unmentioned one is what produces the wrong screens.
+
+## How far a screen check reaches
+
+How far a screen check reaches is the same question as any other level and has the same answer:
+whatever the repo already asserts. Where a suite drives a browser, a screen check can live there;
+where only request tests exist, structural assertions are the ceiling. Never bring in a browser
+stack to satisfy this - a proof that cannot run in the project's own setup is worse than none, and
+this skill installs nothing.
+
+What the ceiling leaves out is far narrower than it sounds, and overstating it turns this into an
+amnesty. A selector reaches presence, absence, order, count, text **and containment**: that a
+progress bar is in the markup, that no breadcrumb is, that the primary button comes before the
+secondary, that the counter reads `1 de 3`, that `AGORA` sits inside the week band rather than
+beside it. All of that is an ordinary check and none of it is exempt. What no selector reaches is
+spacing, colour and type weight.
+
+**Composition is assertable, so it is not exempt either.** Which regions the screen has, what
+contains what, a bar where the design draws a bar and not a ring - those are presence,
+containment and order wearing a visual name, and a list of the assertable that leaves them out
+hands the arrangement back by accident. This is the failure this section has actually produced:
+every label copied, every count correct, and a screen that reads as a different product. So write
+the structural checks the design decides - one column or two, this indicator and not that one,
+this block nested inside that one - and leave only the three properties above unproven.
+
+So the exemption has to enumerate, under the same rule as every other negative in this skill.
+"Visual fidelity is unproven" is a blanket that legitimises every mistake of form written after
+it - including the ones a check would have caught - and a verifier reading it treats a real gap as
+a limitation properly declared. Name the screen and the property: `03 overview - spacing and card
+elevation unproven`. Then a person reviews three lines instead of being handed the whole surface
+back.
+
+## The Screens table needs a column for arrangement
+
+Give the artifact a `## Screens (ui)` section with one row per screen and **three** columns, so
+the omission shows up as an empty cell rather than as a shorter sentence:
+
+```markdown
+| Screen | Copy and elements (selector) | Arrangement (selector) | Visual unproven |
+| --- | --- | --- | --- |
+| 01 mid-cycle | kicker `CICLO DE {N} DIAS`, `dia K de N`, `ESTA SEMANA`, `AGORA`, Continuar, Deixar para depois, Regenerar | progress is a **bar**, not a ring · `AGORA` nested **inside** the week band, between last-opened and next · community in **two** columns · stages as numbered circles on a rail · footer: feedback left, Regenerar right | spacing, colour, type weight |
+```
+
+The middle column is the one this whole file exists for. Without it a row reads as complete with
+nothing but labels in it - which is how a screen ships with every string correct and a layout
+nobody decided. Each item there is an ordinary check: presence, absence, containment, order,
+count. What genuinely does not reach goes right, named, per screen.
+
+## Screens are a Coverage set
+
+**Designed screens are a set whose members are the screens.** The design already numbers them, so
+the enumeration exists and owes a row like any other. The row is what forces the artifact open,
+which is exactly where this fails: a screen nobody mapped is a screen nobody built, and it stays
+invisible while every check is green. Map each screen to the check that renders it and leave the
+rest in `Unproven`.
+
+```markdown
+| designed screens (6) | `01` intake C1 · `02` montando C5 · `03` overview C19 · `04` player C26 · `05` conclusão C20 | `06` |
+```
+
+Where the design draws a state as a band on an existing screen and a check turned it into a
+screen of its own, that is not a gap but a contradiction - say so in the row and settle it with
+the user, because the check is the side that is wrong.
+
+And mark the design in `Sources` as binding for the interface, naming the screens it covers:
+
+```markdown
+- <design URL or path> - **binding for the interface**: screens 01-06
+```

package/.agents/skills/wtk-implement/references/test-policy.md

@@ -0,0 +1,152 @@
+# Test policy
+
+**Goal:** the repo, not this skill, decides which code must be proven at which level and how
+deeply - and says so in writing, so the next agent and the next human inherit the decision
+instead of re-deriving it.
+
+## The failure this prevents
+
+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; it says nothing about the
+other paths, and it 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.
+
+So obligations **add up rather than substitute**. When code that decides something is reached
+across a boundary - a route, a queue, a scheduled job, a CLI entry point - two different claims
+are in play and each needs its own asserted proof:
+
+- the **entry point's contract**: it accepts what it should, rejects what it should, returns the
+  right shape, persists or emits what it promised. Proven where the boundary really is, with the
+  real transport.
+- the **decision table inside**: every branch that changes the outcome, asserted case by case,
+  isolated from the transport so the cases can be enumerated at all.
+
+The second one is what gets lost. It disappears whenever a requirement is phrased as an
+observable outcome, because the observable outcome names the entry point and the decision hides
+behind it.
+
+## 1. Does the repo already answer this?
+
+Do not judge whether the repo "has testing docs" - it almost always does, and that impression is
+what makes this step never fire. Ask the two questions a policy has to answer, for each layer
+this change touches:
+
+1. **Which level proves this code?**
+2. **How much of its input space must the proof assert to count?**
+
+If the declaration answers both for every touched layer, follow it and skip the rest of this
+file. If either is unanswered for code that decides something, derive the missing rows.
+
+A statement answers neither question when it only says **where** tests live or how they are
+named, **how** to run them, **how a test is built** (which dependencies are real and which are
+doubled), or **that** testing matters. Those are all useful and none of them allocate: they
+describe the tests, while a policy has to describe the code. Watch for the third one especially,
+because it is the one that looks like an allocation rule: keying the level to whether a test
+uses real dependencies decides *how* to write a test, and if you read it as deciding *what
+deserves* one, every decision table that touches a real dependency gets routed away from its own
+layer and is never enumerated.
+
+## 2. Classify by the shape of the code, never by the name of the layer
+
+Layer names lie. A file named like a service can be a pass-through, and a handler that looks like
+plumbing can hold the densest decision table in the change. Classify each candidate on a signal
+you can point at.
+
+**Instrumentation** - the body forwards its arguments to one call, or maps one shape onto another
+with no conditional deciding the result. Its correctness is its consumer's problem; a test over
+it re-asserts the framework underneath.
+
+**Decision** - anything that changes an outcome. A dispatch over a status, event type or code. A
+boundary or validation check. A state transition. A payload assembled conditionally. A mapping
+table with more than one row. A guard, a precedence rule, an ordering rule.
+
+Count it and write the number down: decision points added or touched, per file. "Dispatches over
+six event types, eleven branch points" is contestable. "Looks like business logic" is not.
+
+Then **name the members, not only the count** - `paused`, `updated`, `deleted`, `trial_will_end`,
+other. Those names are what `Coverage` joins each proof against, and a set that only ever exists
+as a number cannot be joined at all: the member you left out of the sentence is the one that ends
+up with no proof and is never missed.
+
+**The level follows the branch, not the observation.** A requirement phrased as an outcome at the
+boundary does not discharge the code behind it. Decide the level from where the branch lives.
+
+## 3. Derive from the code, not from the current suite
+
+The existing tests set style, location and commands - never the bar. A module with no tests at a
+level is evidence about its history, not evidence that its logic needs none; deriving the policy
+from the suite you found codifies the gap you were asked to look at.
+
+**Judge the house pattern across the whole repo, not the folder you happen to be changing.** That
+folder is the smallest and least reliable sample there is, and reading it as the standard is how
+a local gap gets promoted to a rule. Search instead for the closest analogue **by code shape** -
+the other state machine, the other dispatcher, the other validator - wherever it lives. When you
+find one, cite it in the evidence: a proposal that points at a sibling proven at that level is
+precedent, and one that does not is taste.
+
+When the existing suite or an existing rule contradicts what you propose, say so in one line.
+That contradiction is information for the user, not a reason to lower the proposal.
+
+## 4. Propose
+
+Present it with the checklist - one place, not two. It goes in the artifact as a
+`## Test policy` section immediately before `## Checks`, because every proof below depends on the
+rows above. Use the repo's own level names, locations and commands; invent none.
+
+```markdown
+## Test policy (proposed - the repo does not declare this)
+
+| Code | Required proofs | Coverage expectation |
+| --- | --- | --- |
+| Decides, and is 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 or adapter 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
+- <existing declaration> decides <what it decides> and leaves the two questions open
+- closest analogue in the repo: <file>, same shape, already proven at this level with <n> cases
+- the module has <n> proofs at this level today, which the table deliberately does not match
+
+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.
+```
+
+A floor, never a ceiling, and a target rather than a description of what exists today. State the
+cost in the proposal - a row set nobody can price is a governance debate, and a row set with a
+number next to it is a five-second decision.
+
+## 5. Ask, then write
+
+**One question, not a menu.** The rows you derived are the default you build under: state them
+and keep going. Offering a choice between allocation philosophies hands back the analysis this
+step exists to do, and the option that always looks like the conservative one - prove everything
+at the boundary, the way the repo already does - is level substitution wearing a hat.
+
+So the only explicit question is the narrow one: **do these rows go into the repo's guidelines?**
+Building under them is reversible and needs no permission. Writing them is not: project
+guidelines reach every future agent and every human in the repo, a wider blast radius than the
+feature you were asked to build, so approved rows go in their own commit, before the build
+starts, and never ride along in a feature commit.
+
+Ask it in one line, with both outcomes stated, so silence is not ambiguous. Adapt the names, keep
+the shape:
+
+> These rows are the bar I build under - approving the checklist is enough for that. Writing them
+> into `<guidelines file>` needs an explicit yes, and it lands as its own commit before the build.
+> Without one I build under them and leave the file alone.
+
+Then stop asking. The answer settles it for this feature, and rule 4 keeps the rows fixed from
+that point on.
+
+**Fix what misleads, do not just add to it.** If an existing line is being read as an allocation
+rule and is not one, leaving it in place means the next run re-derives the same wrong answer and
+the Verifier defers to it. Quote the line, say what it actually decides, and propose the edit that
+scopes it - as part of the same approval, in the same commit as the new rows.
+
+If the user does not answer, do not write. Carry the proposal inside the checklist as a stated
+assumption, build under it, and leave the files alone - a policy nobody agreed to is worse than
+no policy, for exactly the reason above.