workflow-toolkit 1.0.1

package/.agents/skills/wtk-plan/references/document-format.md

@@ -0,0 +1,222 @@
+# Task document format
+
+Load this file only when writing `.tasks/<name>.md` — after the cut, the grounding, the surface walk, and the sweep. Do not load it during Cut.
+
+Section headings stay as they are — the next skill refers to them by name — while the prose follows the language of the document and identifiers are never translated. The document is for humans first: `wtk-implement` copies criteria into checks, and nothing under `Unresolved` gets settled while building.
+
+Replace every placeholder with a concrete value, or omit the section. A heading with "N/A" under it does not appear.
+
+## Template
+
+Write `.tasks/<name>.md`, one file per task:
+
+````markdown
+# <Title>
+
+> Build this with **wtk-implement** (`<repo-relative path, when the project vendors the skill>`).
+> Every criterion below becomes a check with a proof, referenced by its number. Nothing under
+> `Unresolved` gets settled while building.
+
+## Intent
+
+<The problem, in the present tense, with no solution in it: what is true today that should not be,
+who pays for it, and what it costs them. Copy the evidence the source gives.>
+
+<The change: what is different for a user when this ships. For interface work, name the screen and
+the flow, and link the design - it is a source, not an illustration.>
+
+<N criteria in M slices · K one-way doors · Q open, of which B block>
+
+## Criteria
+
+One observable outcome per line, with the concrete value. State the precondition when the
+outcome depends on one. On a screen, every state that matters is its own line: empty, loading,
+error, unauthorised, and it names the screen the design gives it. Use whichever shape the criterion
+actually has - most are When/Then, and the list below is a menu, not a quota. Headings are the
+slices; numbering runs across the whole task.
+
+### <slice - the outcome someone can watch>
+
+1. Given <state>, when <trigger>, then <observable outcome with the concrete value>.
+2. When <trigger>, then <observable outcome>.
+
+### <slice>
+
+3. While <state holds>, <observable outcome>.
+4. If <condition goes wrong>, then <observable outcome>.
+5. Always, <invariant with the concrete value>.
+
+## States
+
+Only when the task changes a lifecycle. Every edge carries the criterion that states it.
+
+```mermaid
+stateDiagram-v2
+    <From> --> <To>: <trigger> (<criterion number>)
+    <ExistingState> --> <ExistingState>: <unchanged - label as existing>
+```
+
+## Out of scope
+
+- <excluded capability> - <why>
+
+## Observable
+
+Every item of every surface this task exposes. A landing is a criterion already written, `existing`, `n/a`, or `Unresolved` - never a behaviour the walk invented.
+
+| Surface | Decision | Landing |
+| --- | --- | --- |
+| screen `<name>` | empty state | 1 |
+| screen `<name>` | error state | Unresolved 2 |
+| screen `<name>` | destructive action confirms | existing - <the pattern already in use> |
+| API `<METHOD> /<path>` | error shape and codes | n/a - <why it does not apply> |
+
+<Or:> `None - no user-facing surface`
+
+## Swept
+
+Where each unwritten requirement landed. All nine, one line each, every time.
+
+- validation: <criterion number>
+- failure modes: <criterion number>
+- idempotency and retry: <criterion number>
+- authorization: existing - <the guard or policy that already covers this>
+- concurrency and ordering: <criterion number>
+- data lifecycle: n/a - <why it does not apply>
+- external-dependency failure: <criterion number>
+- state transitions: <criterion number>
+- observability: Unresolved <number>
+
+## Impact
+
+What already exists and gets disturbed. "Nothing" is a valid answer; a missing row is not.
+
+| Front | What changes |
+|---|---|
+| domain | new term: `<Name>` - <one-line definition>, lives in <module> |
+| domain | existing term: `<Name>` meant <x>, now means <y> - <who branches on it today> |
+| stored data | <backfill now / migrate on read / dual write / nothing to migrate> |
+
+## Decided
+
+Only what is hard to reverse, with the literal shape. `None - <why nothing here is one-way>` is
+a valid row.
+
+| Decision | Shape | Alternative rejected |
+|---|---|---|
+| <what was decided> | <schema, endpoint + body, enum value, event payload, dependency> | <the option and the property that disqualified it> |
+
+## Relations
+
+Only when the task changes the shape of stored data, and only what `Decided` already settled:
+entities, cardinality, and the constraints that are one-way. No columns, no types.
+
+```mermaid
+erDiagram
+    <Entity> ||--o{ <Entity> : <verb>
+    <Entity> ||--|| <Entity> : "<verb> - unique, decision <row>"
+```
+
+## Surface
+
+Only when the task adds or changes an interface consumed outside it. The signature, not a
+specification.
+
+| Route | In | Out | Status | Criteria |
+|---|---|---|---|---|
+| `<METHOD> /<path>` | `<field>`, `<field>` | `<field>`, `<field>` | `<code>`, `<code>` | <numbers> |
+
+## Sources
+
+- <link> - <what it settles>
+- <design> - **binding for the interface**: screens <ids>, and where the copy lives
+
+This task is the record of decision. If a linked document diverges, ask before building.
+
+## Unresolved
+
+Questions the source does not settle and asking did not close. Nobody fills these in while
+building. `None` when nothing is open — one row, Question is `None`, other cells empty. A missing
+section is not an answer.
+
+| # | Kind | Question | Until answered |
+|---|---|---|---|
+| 1 | blocks | <question> | <which criterion cannot be satisfied until it is answered> |
+| 2 | blocks go-live | <question> | <what cannot be switched on for real users until it is answered> |
+| 3 | open | <question> | <what stays imprecise, and what was written in the meantime> |
+````
+
+**The handoff line** comes first because whoever opens this file was handed a path and nothing else - increasingly a model, with no memory of the conversation that produced the task. It names the skill that turns criteria into checks, so the reader does not improvise a plan out of a document that deliberately contains none, and it repeats the one rule that gets broken under pressure: an open question is not an invitation to decide. Name the skill, never a path - where it is installed differs per repository, and a link that does not resolve teaches the reader to skip the line. Add a repo-relative path beside the name only where the project vendors the skill in-tree, and only as a fallback: a skill configured as explicitly-invoked-only never appears in an agent's list, and in a headless or cloud run the name on its own is a reference nobody can act on. A path into somebody's home directory is the one that goes stale - never write that.
+
+**Intent** is two paragraphs because it is two questions, and asking both in one breath reliably returns only the second. The change is already in the source and costs nothing to restate; the problem has to be recovered, so that is the half that gets dropped. Splitting them makes the omission visible.
+
+Write the problem in the present tense with no solution inside it. "We have no Stripe integration" is not a problem - it is the absence of this task's answer, and a problem phrased that way can only ever justify the thing already chosen. Say what is true today that should not be, who pays for it and what it costs them: "anyone evaluating the product has to enter a card first" is a sentence someone can disagree with, and being disagreeable is the test. Copy whatever evidence the source gives, literally - a conversion figure, a support volume, a date somebody else set. Where it gives none, say so instead of manufacturing urgency.
+
+When the source states no problem at all, that is a gap like any other and it comes back as a question. Not blocking, since the criteria stand without it, but worth asking, because decided work whose problem nobody can state is the likeliest to be the wrong work. The problem is also what makes the rest reviewable: every rejected alternative in `Decided` argues about means, so with the end unwritten a reviewer can confirm the task is well-formed and never that it is right.
+
+**Criteria** are numbered because everything downstream refers to them by number - a proof, a review comment, a question. One **outcome** per line, which is not one assertion: a single outcome usually has several observable facets, and a trial that comes back `Trialing`, sets `trialEndsAt` and leaves a subscription at the provider is one criterion rather than three. Split when a line carries two triggers or two outcomes that can succeed independently - never merely because it contains "and". Splitting facets into separately provable pieces is the next skill's job, where each check owes exactly one proof. Given/When/Then only where a precondition changes the outcome; a bare When reads better and says the same thing.
+
+When/Then answers a trigger, and three kinds of criterion have no trigger to answer. An **invariant** holds always - "a paused subscription never grants access" - and inventing a moment for it moves the criterion off what it actually claims. A **state-driven** outcome holds while something is true rather than at an instant: "while the trial is active, usage is recorded and not billed". An **unwanted condition** responds to something going wrong rather than to someone acting: "if the provider does not answer within 10s, the charge is not retried". Give each its own shape - `Always`, `While`, `If`. Squeezed into a When, they come out as a subordinate clause inside some other criterion, which is exactly where failure handling and invariants get lost.
+
+**Write the connectives in the language of the task.** `Given`, `When`, `Then`, `While`, `If` and `Always` are shapes, not keywords, and nothing parses them - a task written in Portuguese writes `Dado`, `Quando`, `Então`. A document that switches language mid-sentence costs the reader a beat on every line and buys nothing. Three tiers, and only the middle one moves: the section headings stay as they are, because they are a schema that this skill and the next one both refer to by name; the prose and the connectives follow the document; identifiers are never translated, so a status value, a field, a route, an HTTP code and a class name keep the spelling the system uses. Translating `Trialing` into a criterion is how a task starts describing a system that does not exist.
+
+The headings are the slices the cut already found. Enumerating them and then writing a flat list throws the shape of the work away: nobody can tell where starting a trial ends and cancelling begins without reading every line, and the seams you would otherwise describe from memory when someone asks about splitting are already drawn. **Number across the whole task, never per heading** - everything downstream refers to a criterion by number, and a `3` that exists three times is worse than no grouping at all. Under about six criteria skip the headings; a list you can see whole does not need signposting.
+
+**The status line** closing `Intent` is the file obeying the rule the chat already follows: lead with the verdict. A reviewer decides in seconds whether to read now or hand it back, and the three facts that decide it - how much work, how much is locked, how much is open - otherwise sit in three different sections, the last of them at the bottom. Count, never characterise: "4 open, 1 blocks go-live" is a fact a reviewer can act on, "mostly settled" is a feeling.
+
+Each one will get a proof attached downstream, so a criterion for which nobody can name a test is not ready to be written. You do not name the test here - finding the real command needs the repository's own test setup, and that is the next skill's job.
+
+**States** exists because a lifecycle is the one thing a list of criteria describes badly. Each transition is right on its own line and the machine they form is nowhere, so the missing edge - the state nobody said how to leave - stays invisible exactly where it costs most. Draw it only when the task changes a lifecycle, and draw it **from** the criteria: every edge carries the number that states it, and an edge you want but cannot number is a gap to close rather than a fact to add. That rule is the entire safeguard. Without it this becomes a design document with opinions of its own, which is the thing that goes stale and then misleads.
+
+Include the states that already exist and are not changing, marked as existing. The dangerous edge is usually the one between what you are adding and what was already there.
+
+That rule is what admits `Relations` and `Surface` below and excludes everything else. A map of components and a sequence of calls are design: they assert what nothing in the task sustains, so nothing holds them honest and they are the first thing to diverge - and a component diagram drawn by someone who has not read the code invents components the repository does not have, then reads as settled because it is drawn. Where a call sequence really is load-bearing it is a one-way door and belongs in `Decided` as a literal shape. If tasks live in a tracker, check that it renders mermaid before standardising on it - an unrendered block is still readable, but barely.
+
+**Impact** has fixed rows because the failure here is omission rather than vagueness. A section that is simply absent looks like nothing to answer; an empty row is a question someone can see.
+
+The domain row matters more than it looks. A name leaks: it becomes a class, a column, a payload key, a route, and renaming it later costs a migration plus every consumer, so naming is a one-way door that does not look like one. Give the new term its definition in one line and say where it lives. For a term that changes meaning, the second half - **who branches on it today** - is what catches the silent breakage, because those callers never appear in the feature's diff.
+
+Past two terms, give each one its own `domain` row instead of packing them into one cell. Six terms separated by punctuation inside a single cell cannot show a gap, and being able to see the gap is the only reason this is a table.
+
+The stored-data row is about what runs against existing data, not only about rows you move. A constraint added to a populated table is data-dependent: a unique index over a column that was never unique fails on the first pair that already exists, and it fails in production against real rows rather than in a test against three fixtures. "Nothing to migrate" answers the other half of the question. Say what the migration needs to be true before it runs.
+
+**Decided** carries a persisted schema, a contract someone else consumes, a new dependency, a data backfill, or a pattern the codebase does not have yet - precedent is the part that 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.
+
+Weigh the rejection against what comes after this task, not only against this task. A constraint that settles the problem in front of you can forbid something a later slice needs - a uniqueness rule written for anti-abuse also decides that a user can never have a second row, which is a question for whoever builds renewals and never appears in the reasoning that produced it. When a door reaches past the boundary, say what it closes. That sentence is what the review is for.
+
+Two things look like decisions here and are not, and letting them in is how the table turns into a dumping ground. Scope - "V1 does not charge" - reverses by doing the next slice, and it already has a home in `Out of scope`. A rule with no mechanism - "one trial per user" - reverses by changing a condition; it becomes a door only once something persisted enforces it, and then the row is the unique index, with its literal definition, rather than the rule.
+
+A column and a type belong here whenever they are doors, and the tell is never the word "column". Identifier width is the plainest case - formally a type, irreversibly a door, because you do not migrate it once there is volume. Uniqueness decides product behaviour, not storage. Nullability over a populated table is a migration that depends on the rows already there. A field a consumer binds to stops being yours to rename. Everything else about the schema - names, indexes, ordinary types - is settled by whoever implements, from the conventions in the repository, and deciding it here means deciding it without having read the code that has to hold it. Where a data decision needs argument rather than a row - partitioning, denormalising, changing store - it is an RFC.
+
+When a decision needs a paragraph to justify itself, or several one-way doors arrive together, that is an RFC and it comes **before** the task. Write it first, then link it and keep the row literal.
+
+**Relations** renders what `Decided` settled, so it decides nothing. That is the whole licence for drawing it: cardinality is the part of stored data that reads worst in prose and best in a picture
+- `1 --> 1` against `1 --> *` is the difference between a user who can never hold a second subscription and one who can, and buried in a decision row it goes past a reviewer who would have caught it at a glance.
+
+Entities, cardinality and the constraints that are one-way. Nothing else, and columns least of all: a full diagram looks authoritative, so the next person builds exactly what is drawn, and the four fifths the planner filled in without opening the code arrive looking decided. An invented schema wearing the costume of a decision is worse than no diagram, because nobody argues with it. Every relationship traces to a row in `Decided`; one you cannot trace is a decision nobody made.
+
+**Surface** is the same move for an interface, and it earns a section for the reason a shape does not survive being scattered. Route, method, fields in, fields out, statuses - spread across eight criteria, all of it is present and none of it is legible, and a missing status is invisible because absence has nowhere to show. Consolidated, the hole is a blank cell. Every row cites the criteria that state it, so this stays a projection rather than a second source competing with them.
+
+The signature, never a specification. Types, examples and a catalogue of errors are OpenAPI, which is the heavyweight artifact this skill exists to do without, and the half of it nobody decided would get invented to fill the page. Only interfaces something outside this task binds to: a public endpoint, a webhook payload, a published event, a CLI. An internal method is refactorable, so it is not a door and it is not yours to fix here. What the source leaves open - the error body, an unnamed status - is `Unresolved`, not a guess in a table cell.
+
+**Sources** are usually several and rarely in one shape - a PRD, a design doc, a thread. The task normalises them so what comes next has one stable input instead of five formats.
+
+A design is a source like any other, and the one that gets demoted to decoration. Mark it binding and say which screens it carries, because downstream a check gets written from whatever this section calls binding - a link without the mark arrives as background reading, and the interface then gets built from whatever the codebase already looks like. On a screen the design is also where the concrete values are, so a criterion that renders one carries its screen: without that, "shows the assembling state" is as empty as "gracefully" and passes under any interface.
+
+Open it, then transcribe what it decides. Most designs resolve: an artifact URL with a fetch, a design file through its MCP, an attachment on the issue through the tracker, an image committed to the repo as an ordinary file read. The one that does not resolve is an image pasted into a chat and nowhere else, so commit it and reference the path - otherwise it is gone before anyone builds.
+
+**Whether a link opens is something you find out, not something you infer.** A domain name tells you nothing about whether there is a sign-in behind it, and reporting a public artifact as inaccessible without having made the request is a fabricated fact about the environment - the same failure as inventing an API, wearing the costume of caution. Fetch it. The attempt costs one call; the assumption costs the interface.
+
+When it genuinely fails, say what you tried and what came back. "I could not access the design" leaves the user nowhere; "the fetch returned 403" tells them whether to paste an export, connect the MCP, or grant access, which is the difference between a task that is blocked and one the next message unblocks.
+
+Transcribing is not a substitute for the link and not a bet that the link will fail. It is there because what a check asserts is text, and because the readers downstream differ: a sub-agent may have no vision and a CI job certainly has none. The link stays for the person; the values travel in the criterion for each screen - what the heading says, which controls are present, what the step counter reads, which states are one screen rather than a band on another.
+
+That is also what makes this work on a picture at all, where "quote the deciding lines" has nothing to quote. Describing is still forbidden and transcribing is required, and the two are easy to tell apart: "a clean screen with cards" gives nobody anything to check, while "heading is the question, options as full-width cards, a `1 de 3` counter, Voltar and Continuar" is four things a check can assert.
+
+When a source has no address - a conversation, a document pasted into a chat - say so and quote the deciding lines instead of describing them. Nothing downstream can re-read a chat, so a description is where the decision quietly stops existing.
+
+Copy only the slice that this task cannot get wrong, and copy it literally. The reasoning stays in the source, where it has readers and outlives the merge. Two reasons to copy rather than link: the source covers more than this slice and keeps being edited for months, while the task is the record at the moment of building; and whoever builds needs the exact shape in front of them, not a link to thirty pages containing it somewhere.
+
+**Observable** is the surface walk made checkable. A blank landing is an item nobody decided; an `n/a` without a reason is the same blank wearing an escape. A row that would need a new behaviour cites `Unresolved <n>` and stops - writing a criterion to fill the cell is the failure the landing rule exists to prevent. `None - no user-facing surface` is a complete answer, and stating it is what makes the omission contestable.
+
+**Unresolved** is a table because `Kind` has to travel with the question. A numbered list with a bold prefix still lets a blocking row read as a note, which is the failure this section exists to prevent. The three `Kind` values are a closed set: `blocks` (a criterion cannot be satisfied), `blocks go-live` (proofs can be green and real users still cannot be switched on), `open` (imprecise, not blocking - including a default you assumed and nobody confirmed). Order the rows that way, so the status line can be counted from the column rather than inferred from wording. `#` stays because Swept, Observable and the chat refer to a row by number. `Until answered` is where a written-in-the-meantime value lives, so a reviewer can see what to tear up when the question closes. Never treat silence as confirmation: an assumed default stays `open` until a human says otherwise.

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

@@ -0,0 +1,14 @@
+---
+name: wtk-qa
+description: "Run one tagged QA planning or execution phase through `/wtk-qa [plan] <flow>`. Use for verifier-owned journey work."
+argument-hint: "[plan] <flow>"
+context: fork
+agent: verifier
+background: false
+---
+
+# QA
+
+Run this phase for: $ARGUMENTS. If empty, stop and ask for the flow.
+
+Run exactly one QA phase: wtk-qa-plan when the first argument is plan, else wtk-qa-execute, over journeys tagged with the flow; read .agents/skills/wtk-qa-plan/SKILL.md or wtk-qa-execute/SKILL.md in full; if no journey carries the tag, report and stop.

package/.agents/skills/wtk-qa-execute/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: wtk-qa-execute
+description: Execute planned QA through existing public interfaces and record evidence or defects. Use when a Verifier walks QA; Don't use for planning, product fixes, or framework setup.
+metadata:
+  author: Antonio Fulgêncio
+---
+
+# QA Execute
+
+Walk the current QA plan through the consuming project's public surfaces. Select the adapter already
+declared by the project, capture evidence, write durable results, and return product defects to an
+Implementer for a fresh Verifier cycle.
+
+## Provenance
+
+Author: Antonio Fulgêncio.
+
+This is an original project-owned adaptation for this workflow, inspired by Pedro Nauck's
+[`qa-execution` skill](https://github.com/pedronauck/skills/tree/main/skills/mine/qa-execution).
+
+## Inputs and boundaries
+
+Read `docs/qa/README.md`, the QA Plan handoff, the in-scope scenarios and charters, open bugs, and
+`docs/toolkit/guidelines/QA-SCENARIOS.md` in full. The guideline owns scenario fields, ids, statuses, and
+flag/reset rules. Read [`references/session-protocol.md`](references/session-protocol.md) in full
+before the first charter.
+
+Use real public interfaces and the project's existing browser, API, CLI, mobile, or manual adapter.
+When no runner is adopted, choose the closest reachable public interface or a manual adapter and
+record the limitation. Mark only an unreachable leg `untested`; missing tooling alone is a
+limitation, not an unreachable product surface. Report the exact adapter, path, evidence, and
+limitation. Keep raw evidence in the repository's disposable evidence path and keep reports, scenario
+status, and bug records durable.
+
+QA execution validates the product; it does not write product code, install a framework, invent a
+command, or replace the automated gate.
+
+## Procedure
+
+### 1. Preflight the cycle
+
+Read the profile, plan handoff, affected scenarios, open bugs, and charters. Confirm the recorded
+automated gate is green and the product is reachable through a production-parity path. Resolve the
+adapter and prerequisite gaps before the first walk. If a runner is missing, use the closest
+reachable public interface or manual adapter and record the limitation. A leg is `untested` only
+when its product surface is unreachable; a leg that only a human can complete may be
+`blocked-verify` with the exact reason.
+
+**Done when:** every charter has a reachable entry point or a named limitation, the gate result is
+recorded, and the selected adapter is supported by the profile.
+
+### 2. Select the adapter
+
+Choose the closest existing adapter for each public surface: browser, API, CLI, mobile, or manual.
+Prefer a reachable manual walk when no automated runner exists.
+Follow the profile's setup, authentication, fixture, seed, cleanup, and residue checks. Preserve the
+project's runner and commands as declared by its manifest or CI. Read
+[`references/session-protocol.md`](references/session-protocol.md) in full for the execution and
+evidence contract.
+
+**Done when:** the session log names one adapter and exact execution path for every walkable surface,
+with setup and cleanup prerequisites resolved or recorded as limitations.
+
+### 3. Open the report
+
+Create `docs/qa/reports/<YYYY-MM-DD>-<scope>.md` before the first charter, or resume the current
+report when one exists for this cycle. Add every charter and scenario to the matrix with a pending
+verdict. Include the adapter, environment, gate command/result, and evidence destination. When a
+visual criterion is in scope, point the row at its feature `uiux.md` source/frame and record paired reference
+and implementation captures with the declared state, exact viewport, fonts/assets, and expected
+differences. Do not count that manual comparison as an automated test.
+
+**Done when:** one dated report contains every in-scope charter and scenario, and no walk has started
+with a missing matrix row.
+
+### 4. Walk in persona
+
+Adopt the charter's persona, enter through its public entry point, and walk the journey to its true
+end state. Confirm the expected observable through an independent read path and after a reload. Capture
+evidence at each checkpoint and divergence, then update the report and scenario status immediately.
+
+**Done when:** every charter has a recorded verdict, independent confirmation, evidence path, and
+debrief, or an explicit limitation with the status prescribed by `QA-SCENARIOS.md`.
+
+### 5. Probe the changed surface
+
+Run the charter's tour and choose 5–10 relevant edge probes. Re-walk the two largest changed
+journeys with the comprehension, recovery, trust, speed, accessibility, and language lenses when
+the cycle has enough surface to justify them. Record clean attempts as results and keep evidence
+paths beside their report rows.
+
+**Done when:** the selected tour, every chosen edge, and every applicable lens have a recorded
+result, evidence path, or named limitation.
+
+### 6. Record findings and govern fixes
+
+Deduplicate against `docs/qa/bugs/` and linked scenario bug ids. File a new bug only for a new
+symptom; append re-found or regressed observations to the existing record and link affected
+scenarios. When a product defect is confirmed, read
+[`references/fix-loop.md`](references/fix-loop.md) in full, hand the defect to an Implementer, and
+close this Verifier session before remediation.
+
+**Done when:** every finding has a deduplicated bug record, affected scenario links, severity and
+evidence, and every product fix is explicitly assigned to an Implementer rather than changed here.
+
+### 7. Close or resume the cycle
+
+After a fix, start a fresh Verifier, rerun only impact-invalidated technical proofs, and resume from the affected journey
+plus its adjacent canary. Keep the original report history and update statuses, retest fields, bug
+links, and evidence. At close, replace every pending row with a terminal result or an allowed
+`untested`/`blocked-verify` explanation, apply `.agents/skills/wtk/references/validation.md` and record
+the selected commands, reused evidence and results. QA close does not automatically repeat a full gate.
+
+**Done when:** no report row remains pending, every fixed bug has a passing retest or an explicit
+decision, every scenario status matches its evidence, and the final gate result is recorded.

package/.agents/skills/wtk-qa-execute/references/fix-loop.md

@@ -0,0 +1,23 @@
+# QA fix loop
+
+Read this reference in full when a walk finds a product defect.
+
+## Handoff
+
+Deduplicate the symptom, file or update the bug record, link every affected scenario, and return the
+smallest clear remediation to the Implementer. Include the expected observable, observed result,
+adapter, exact path, evidence, and a regression-test recommendation when the project can own one.
+
+**Done when:** the Implementer has a bug id, reproducible path, evidence, expected result, and
+affected scenario list.
+
+## Fresh verification
+
+End the current QA execution session before the product changes. After the Implementer reports the
+fix, a fresh Verifier selects invalidated technical proofs using incremental impact validation and
+retests the affected journey plus its adjacent
+canary. QA then resumes from the affected charter and records the retest result in the original
+report.
+
+**Done when:** the fix has a fresh Verifier result, the affected journey is re-walked, and the bug
+and scenario statuses carry matching evidence.

package/.agents/skills/wtk-qa-execute/references/session-protocol.md

@@ -0,0 +1,25 @@
+# QA session protocol
+
+Read this reference in full before the first charter.
+
+## Enter, act, verify, capture
+
+Enter through the public entry point named by the charter and adopt its persona. Act only through
+the selected browser, API, CLI, mobile, or manual surface. Verify the expected observable through an
+independent read path and after a reload where the surface supports it. Capture the evidence path,
+environment, adapter, and any divergence immediately.
+
+Keep a clean session between retries. A stalled flow gets one clean retry; record the stall and its
+result in the report. The session records attempted-and-clean edges as results.
+
+**Done when:** each charter interaction has an entry point, action, independent verification, and
+evidence or a named limitation.
+
+## Evidence contract
+
+Evidence identifies the scenario or charter, adapter, exact path, timestamp, and expected versus
+observed result. Store raw screenshots, traces, logs, or captures under the consuming project's
+ignored evidence path. Link those files from the durable report; keep scenario prose focused on the
+promise and current status.
+
+**Done when:** every report verdict can be traced to a durable row and its raw evidence or limitation.

package/.agents/skills/wtk-qa-plan/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: wtk-qa-plan
+description: Plan user-visible QA journeys, scenarios, and charters. Use when a Verifier prepares QA; Don't use for live walks, product fixes, or framework setup.
+metadata:
+  author: Antonio Fulgêncio
+---
+
+# QA Plan
+
+Plan a reviewable QA cycle for a user-visible change. Keep the plan stack-agnostic: the consuming
+project's operational profile chooses the public interface and adapter later.
+
+## Provenance
+
+Author: Antonio Fulgêncio.
+
+This is an original project-owned adaptation for this workflow, inspired by Pedro Nauck's
+[`qa-report` skill](https://github.com/pedronauck/skills/tree/main/skills/mine/qa-report).
+
+## Inputs and boundaries
+
+Read the feature contract or Verifier packet, the current diff, `docs/qa/README.md`, and the
+affected QA records. Read `docs/toolkit/guidelines/QA-SCENARIOS.md` in full before creating or changing a
+scenario. It owns the scenario tree, fields, ids, statuses, and flag/reset rules.
+
+Plan journeys, scenarios, and charters. Leave live walks, evidence capture, defect remediation,
+and framework selection to `wtk-qa-execute` or the next independent Verifier session.
+
+When the profile is missing or incomplete, read
+[`references/profile.md`](references/profile.md) in full before discovering capabilities or writing
+`docs/qa/README.md`.
+
+## Procedure
+
+### 1. Resolve scope
+
+Read the feature contract, acceptance criteria, current diff, and existing QA records. Classify each
+changed surface as user-visible or internal. Include routes, screens, public configuration, CLI
+commands, API responses, mobile surfaces, and user-facing copy when their observable behaviour
+changed.
+
+Maintain a criterion disposition for every changed acceptance criterion. Map user-visible criteria
+to a QA journey/scenario; for an internal criterion, enumerate it in the handoff with the reason it
+does not change a user-visible promise. If no criterion is user-visible, record `no user-visible
+change` in the task handoff and stop.
+
+For a visual criterion, point the disposition at the owning feature `uiux.md` reference row and follow
+`UI-UX.md#verifying-the-built-screen`. The visual comparison remains evidence for that criterion; it
+does not replace behavioral coverage.
+
+**Done when:** every changed acceptance criterion has one explicit disposition, and the no-surface
+case has a written handoff.
+
+### 2. Load the QA context
+
+Read `docs/qa/README.md`, the relevant personas, journeys, scenarios, open bugs, and current
+charters. If the operational profile is absent or lacks a capability needed to plan the scope,
+follow [`references/profile.md`](references/profile.md) in full and record discovered facts with
+links to executable manifests or CI. Keep product-owned documentation intact while updating the
+profile.
+
+**Done when:** the plan names the profile path, every in-scope persona, and every existing journey or
+scenario that can cover the changed surface.
+
+### 3. Map the promises
+
+Map every user-visible acceptance criterion to an existing journey under `docs/qa/journeys/` and a
+scenario under `docs/qa/scenarios/`. Mint a stable, content-addressed scenario for a new promise.
+Fold duplicate coverage into the canonical scenario and record overlaps there. Include one adjacent
+canary journey when the feature has a user-visible surface. Keep each internal criterion's explicit
+reason in the disposition handoff.
+
+Use the schema and status vocabulary from `QA-SCENARIOS.md`; keep field definitions in that file.
+Describe the expected observable in user language and preserve scenario ids once published.
+
+**Done when:** every changed acceptance criterion has a disposition: one canonical
+`docs/qa/journeys/` + `docs/qa/scenarios/` mapping for a user-visible promise, or a handoff entry
+that names the criterion and explains why no user promise changed.
+
+### 4. Flag the cycle
+
+Create a scenario under `docs/qa/scenarios/` with `qa_status: untested` when the promise is new.
+Reset an affected existing scenario to `untested` when the diff changes its promise. Link open bugs
+and preserve the latest report path and evidence according to the schema. Update journey maps under
+`docs/qa/journeys/` when the route through the product changed.
+
+**Done when:** every affected scenario is new or reset to `untested`, and its journey, bug links,
+and report references are internally consistent.
+
+### 5. Write session charters
+
+Create one new dated charter under `docs/qa/charters/` per meaningful persona × journey × tour ×
+time-box for this cycle. Never update an existing charter. Journeys and scenarios may be refreshed
+when the contract changes. Point each charter at its scenario and journey, state the public entry
+point, and define the observable that proves success. Include the adjacent canary and prioritize
+changed or risky paths.
+
+**Done when:** every affected scenario is covered by a dated, bounded charter with a persona,
+journey, entry point, tour, time-box, and expected observable.
+
+### 6. Hand off for execution
+
+Summarize the criterion disposition ledger, the `docs/qa/journeys/`, `docs/qa/scenarios/`, and
+`docs/qa/charters/` outputs, profile path, adapter candidates, and any missing prerequisite for the
+next fresh Verifier. State that execution must use `wtk-qa-execute`, the project's existing public
+interface, and the profile's declared adapter. End this skill before launching the product or
+changing product code.
+
+**Done when:** the handoff lists every changed criterion with its disposition, every affected
+scenario and charter output, names the next Verifier session, and contains no live execution result
+or product fix.

package/.agents/skills/wtk-qa-plan/references/profile.md

@@ -0,0 +1,35 @@
+# QA capability profile
+
+Read this reference in full when `docs/qa/README.md` is absent or lacks the capability needed to
+plan a changed surface.
+
+## Discover
+
+Inspect the repository read-only. Find the package or build manifest, declared gates, CI workflows,
+production-parity start and health path, public browser/API/CLI/mobile entry points, authentication
+setup, fixtures or seed path, cleanup path, installed QA runners, and known unavailable surfaces.
+Use the actual directory and command names found in manifests or CI.
+
+Record each capability under the matching heading in `docs/qa/README.md`:
+
+- Public interfaces and area codes
+- Runner or adapter, linked to its manifest, CI job, or documented entry point
+- Build/start path and health signal
+- Authentication and session setup
+- Fixtures, seed, cleanup, and residue check
+- Limitations and unavailable surfaces
+
+Keep executable command strings in their manifest or CI authority. Link to that authority instead of
+copying a command that can drift.
+
+**Done when:** `docs/qa/README.md` names every required capability, its source of truth, and every
+known limitation needed by the QA plan.
+
+## Choose the next step
+
+If an existing adapter can reach the changed surface, record it for `wtk-qa-execute`. If no runner is
+adopted, record the closest public interface and the limitation. Framework installation is a
+separate planned change; the profile remains useful without it.
+
+**Done when:** the handoff identifies one existing adapter or an explicit reachability limitation
+for every affected public surface.

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

@@ -0,0 +1,49 @@
+---
+name: wtk-ship
+description: Ship a proven feature through verification, local gates, lifecycle closeout, and authorized branch delivery. Use when asked to ship a proven feature.
+disable-model-invocation: true
+argument-hint: "[the work, in your own words]"
+---
+
+# Workflow Toolkit Ship
+
+Deliver the requested branch using the scope rules in `.agents/skills/wtk/references/validation.md`.
+
+## Previously verified work
+
+Identify the recorded verified base and the subsequent diff. If that diff is bounded maintenance,
+use the existing receipt plus its scoped evidence and proceed to delivery. A merge request does not
+trigger a new full-branch Verifier, full gate or QA cycle. Closed artifacts may remain in Git; do not
+recreate them merely to satisfy this entrypoint. Apply active feature closeout only to unverified
+feature work or a substantive change whose named risk requires that scope.
+
+## Active feature closeout
+
+An active Lean feature has `.specs/features/<feature>/plan.md`, `checks.md`, and independent
+`verification.md`. The following steps apply to that feature scope.
+
+Resolve or resume the provider route through `.agents/skills/wtk-config/SKILL.md` before dispatch.
+
+1. Confirm the feature's verification report passes the profile recorded in `checks.md` by running
+   `.agents/skills/wtk-lean/scripts/validate_verification.py <feature>`.
+2. Apply incremental impact selection from `.agents/skills/wtk/references/validation.md`, including merges from main.
+   Run invalidated proofs and reuse valid evidence; a full gate needs that reference's trigger or an
+   explicit human request. Run selected `wtk-deep-review`, security, UI and QA procedures only for
+   their affected scope.
+3. Promote durable decisions, lessons, product promises, architecture rules, and QA evidence to
+   their owning stores. Promotion is semantic work; do not invent an automatic knowledge merger.
+4. After promotion is complete, delete the entire transient feature directory with
+   `python3 .agents/skills/wtk-ship/scripts/close_feature.py <feature> --promoted`. The helper refuses
+   cleanup without a passing verification receipt and explicit promotion confirmation.
+
+## Delivery authority
+
+Invoking this skill authorizes the feature branch push, one pull request, and merge after readiness
+is rechecked immediately before the merge. Do not pause between those scoped delivery steps. Deploy,
+release, production mutations, force-push, direct push to `main`, and unrelated remote actions remain
+separately authorized.
+
+If required readiness evidence is missing, name the affected scope and required check. A builder
+never certifies its own feature; feature verification uses a fresh agent over the complete feature
+range. Confirmed Critical, Major,
+and Minor Deep Review findings are fixed in the feature run before delivery.