workflow-toolkit 1.0.1

package/docs/toolkit/guidelines/QA-SCENARIOS.md

@@ -0,0 +1,165 @@
+# QA Scenarios
+
+**Read when:** the diff changes user-visible behaviour, or you are planning a QA pass.
+
+**Why this exists:** Feature verification dies with the feature. Without a tracker, a stale `pass`
+looks like a current promise, and nothing remembers what a user can still do. A scenario holds a
+verdict that survives between features and goes stale when a diff invalidates it.
+
+`docs/qa/scenarios/` answers one question: **what does this product promise its users, and what state
+is each promise in right now?**
+
+This is not a test list. A test is checked when it runs; a scenario's verdict survives until a diff
+invalidates it.
+
+## Layout
+
+```
+docs/qa/
+├── README.md                          area codes, entry points, how to reach the product
+├── personas.md                        who walks the journeys
+├── journeys/J-<slug>.md               journey maps and flows
+│                                      (optional `**Tags:** <flow>` line; `/wtk-qa <flow>` selects by it)
+├── scenarios/<AREA>-<slug>.md         the tracker — one file per promise
+├── bugs/BUG-<YYYYMMDD>-<slug>.md      registry, deduplicated by symptom
+├── charters/CH-<slug>.md              session missions, immutable once written
+├── reports/<YYYY-MM-DD>-<scope>.md    one per run, never overwritten
+└── automation-backlog/<slug>.md       exploratory findings worth automating later
+```
+
+`docs/qa/evidence/` and any generated table view are gitignored. Everything else is committed.
+
+## Scenario file
+
+```markdown
+---
+id: PUB-public-form-happy
+area: PUB
+title: Submit the public form end to end
+persona: Visitor
+journey: J-public-form
+expected: Confirmation visible, row present, reload shows the submitted state
+entry_points: /
+qa_status: untested
+bug_ids:
+fix_status:
+retest_status:
+fix_commits:
+evidence:
+last_report:
+overlaps:
+---
+
+Free prose lives here and only here.
+```
+
+**Flat frontmatter, one field per line, fixed order, enum-only values, all prose in the body.** This is
+not style — it is what makes the tree greppable and merge-safe. `grep -l 'qa_status: fail'
+docs/qa/scenarios/` must be the whole query, not an interpretation exercise.
+
+## Field rules
+
+| Field | Content |
+| --- | --- |
+| `id` | `<AREA>-<slug>` — equals the filename, never renamed |
+| `area` | Code from the consuming project's `docs/qa/README.md` |
+| `title` | Verb-first, ≤80 chars |
+| `persona` | Exact name from `personas.md` |
+| `journey` | A `J-<slug>` that exists in `journeys/` |
+| `expected` | The observable that proves success, in user language, one sentence |
+| `entry_points` | URL, route or command — semicolon-separated |
+| `qa_status` | Enum only |
+| `bug_ids` | Registry ids, semicolon-separated |
+| `fix_status` | Enum only, meaningful when `bug_ids` is non-empty |
+| `retest_status` | Enum only, meaningful when `fix_status: fixed` |
+| `fix_commits` | Short SHAs, semicolon-separated |
+| `evidence` | Paths backing the current verdict |
+| `last_report` | Path of the report that produced the verdict |
+| `overlaps` | Scenario ids covering the same behaviour, canonical owner first |
+
+## Status enums
+
+`qa_status` — `untested` · `pass` · `fail` · `blocked-verify` · `blocked-decision` · `skipped`
+
+- `pass` requires the expected observable confirmed with evidence, through an independent read path,
+  surviving a reload. Optimistic UI is not confirmation.
+- `fail` requires `bug_ids` to be non-empty.
+- `blocked-verify` is for legs only a human can complete — a real payment, a real email, a real
+  third-party account. It says *no session will ever walk this*, so a missing tool, an unconnected
+  browser or an absent fixture leaves the scenario `untested` instead: that gap closes on its own,
+  and `untested` is the only status the next cycle picks back up.
+- `blocked-decision` needs a product call before it can pass.
+
+`fix_status` — *(empty)* · `pending` · `fixed` · `deferred`
+`retest_status` — *(empty)* · `pending` · `pass` · `fail`
+
+A scenario is done for a cycle when `qa_status` is terminal **and** any `fixed` bug has
+`retest_status: pass`.
+
+## Area codes
+
+The consuming project owns the area table in `docs/qa/README.md`. Adding an area updates that file
+first.
+
+## Id minting
+
+Ids are **content-addressed** — derived from the behaviour, never from a counter. `PUB-public-form-happy`,
+not `PUB-003`.
+
+This matters when several checkouts run at once. Nothing reads "the highest existing number", so
+parallel branches cannot collide on minting. Two planners describing the same behaviour mint the
+same id — that is deduplication working, not a conflict.
+
+Ids are stable forever. Retiring a scenario means `qa_status: skipped` with `retired — <reason>` in
+the body. The file stays as memory.
+
+## Flag, then verify — the rule that keeps the tree honest
+
+Before completing any task, ask: **does this diff change user-visible behaviour** — a screen, a route,
+a config key, user-facing copy?
+
+The classification contract takes precedence for behavior-preserving direct corrections. A
+`direct correction` or `UI-only correction` that replaces an existing component or applies a named
+reference while preserving the product promise does not create/reset a scenario or start a QA
+cycle; record its targeted integration check instead. If the correction changes a browser-only
+invariant, walk the existing owning scenario only.
+
+Instruction-only skills, their declarative registration in an existing installer, and bounded CLI
+copy corrections follow `.agents/skills/wtk/references/validation.md`; being agent-facing or installable does not itself start QA.
+Use the owning package/adoption/output check and state the validation method. Correct stale promise
+text without reopening unrelated journeys. A broader QA cycle requires an explicit QA request or
+a changed user interaction not covered by that boundary check. If a cycle was over-scoped, record
+its unwalked legs as skipped with the scope reason; do not claim a manual pass from automated tests.
+
+- **No** — state "no user-visible change" in the completion notes. Done.
+- **New behaviour** — add scenario files with `qa_status: untested`.
+- **Changed behaviour** — reset the affected files to `untested`. **A stale `pass` is worse than no
+  verdict.**
+
+Named visual-reference work follows `.agents/skills/wtk/references/validation.md`: use `UI-UX.md#verifying-the-built-screen` in scoped
+validation, and create or reset a QA scenario only when the product promise changes or QA is selected.
+When QA runs, point the report at the feature `uiux.md` reference rows and retain behavioral evidence.
+
+Then walk them in the feature-closing QA session, per `docs/toolkit/guidelines/QA-EXECUTION.md`. A flag
+without a walk is `untested` debt that no cycle is guaranteed to clear. A slice flags; it never walks.
+
+The feature-closing QA session runs after the final implementation wtk-deep-review group, per
+`docs/toolkit/guidelines/QA-EXECUTION.md` and `docs/toolkit/guidelines/REVIEW-ROUNDS.md`. It walks every scenario
+the feature's slices flagged.
+
+## Merge behaviour
+
+- Different scenarios → different files → never conflict.
+- Same scenario, different fields → git auto-merges, because fields are one per line.
+- Same scenario, same field → a small one-file conflict; keep the values whose `last_report` is newer.
+- Same behaviour, two slugs → not a git conflict, so it must be hunted: fold the newer file into the
+  older id, merge verdicts by report recency, update references, delete the duplicate.
+
+## Anti-patterns
+
+- **Prose statuses.** `qa_status: "passed after retest"` makes the tree unqueryable. The enum is
+  `pass`; the story goes in the body.
+- **Counter ids.** They reintroduce the shared counter that makes parallel checkouts collide.
+- **A file per round.** One scenario, one file, forever. History lives in the dated reports.
+- **Scenario bodies growing into narratives.** The frontmatter answers "what state is this in"; the
+  why and how live in bug files and reports.

package/docs/toolkit/guidelines/REVIEW-ROUNDS.md

@@ -0,0 +1,160 @@
+# Review Rounds
+
+**Read when:** reviewing code, or acting on review findings.
+
+**Why this exists:** Remediating every nitpick in one iteration is unbounded: each fix changes the
+diff and the next review finds new nits. Monotonic findings, in-run defect batches, a stall bound,
+and filed Trivials make review end.
+
+## The review stages, and what each is for
+
+| Stage | Asks | Cap |
+| --- | --- | --- |
+| **Technical Verifier** (feature closing step) | Does one fresh independent pass prove every check over the complete feature range? | One full-feature pass after the last code-changing slice |
+| **wtk-deep-review** (resolved implementation groups) | Is the code correct, safe and maintainable? | Discovery once; one remediation check per batch until no Critical/Major is open or `stall_attempts` halts |
+| **QA session** (feature closing step when the public surface changes) | Does the finished feature work for a real user? | One `wtk-qa-plan` and one `wtk-qa-execute` session |
+The provider `verifier` executes exactly one phase per packet: `technical`, `wtk-qa-plan`, or
+`wtk-qa-execute`. The orchestrator dispatches one technical packet over the complete feature range after
+the last code-changing slice and QA packets once, at feature close, when the feature changes public,
+UI, API, CLI, or adoption behaviour; no slice runs QA. Deep-review is a separate orchestrator stage, not a Verifier phase.
+The QA session reads `docs/toolkit/guidelines/QA-SCENARIOS.md`; it owns fields and
+statuses. Each stage answers a question the others cannot, so none is redundant.
+
+Intent vocabulary is routing input, not a keyword bypass. `wtk` selects discovery, integrated Lean,
+modular planning/implementation, diagnosis, or an explicitly named capability from the request and
+repository state. State facts and validation before dispatch; escalation requires newly discovered
+named evidence, not file count or UI presence. An `issue` is neutral until repository evidence
+identifies its applicable route.
+
+## Why resolved groups, not a rigid interval
+
+A discovery review reads the whole change, so its cost explodes with the diff. The remediation check
+reads only `reviewed_head..HEAD`, so remediation cost tracks the fix, not the feature.
+
+Read `.agents/skills/wtk-config/SKILL.md` before dispatch; its resolver owns cadence modes,
+default, and balanced groups. One pull request and one actor per role remain unchanged.
+
+**Stages do not loop back into each other.** A wtk-deep-review finding never sends work back to
+Technical Verifier. A clean remediation check or the stall bound ends the loop; neither revokes the
+approval for local remediation already in progress. The post-fix gate and escalation rule below
+decide whether the feature's selected review route is done.
+
+Before final QA, complete the final pending implementation wtk-deep-review group; cadence `skip` resolves no groups, so nothing waits for wtk-deep-review. For QA code remediation, review only `reviewed_head..HEAD`, then re-walk affected scenario rows.
+
+## The feature closing step
+
+A feature's closing step is the **QA session** when its public, UI, API, CLI, or adoption surface
+requires a user walk, after the final implementation review group. It needs the whole feature and
+cannot run on part of one. The `wtk-qa-plan` and `wtk-qa-execute` skills own it.
+
+It writes no product code and does not replace the feature's technical Verifier or wtk-deep-review.
+It receives distinct fresh packets, `wtk-qa-plan` and `wtk-qa-execute`, and walks every scenario the
+feature flagged.
+
+## Hard rules
+
+1. **A review contains only findings not raised before.** Before writing a finding, read the prior
+   ledger. A pending, accepted, or already-resolved issue is never re-raised. This is what makes the
+   loop monotonic and therefore finite.
+
+   `wtk` points here for remediation identity and counting; this rule prevents a renamed
+   finding from resetting its history while allowing a distinct finding to proceed.
+2. **Nitpicks never trigger a review.** Fix every confirmed wtk-deep-review defect in the active feature run. Critical and Major findings trigger one remediation batch, then one remediation check: a one-job incremental wtk-deep-review over `reviewed_head..HEAD` that dispositions every open prior finding and reviews the fix. Repeat batch + check until no Critical/Major is open or `[remediation].stall_attempts` halts. Minor findings join that batch, or close together in one Minor-only batch with one scoped gate and one commit; a Minor-only batch starts no fresh Technical Verifier, QA phase, or remediation check. Trivials and advisories go to the pull request follow-up list. **In an active, already-approved review loop, fix blocking findings without new human approval and run the scoped gate after each correction; escalate only if the post-fix gate fails or the stall threshold is reached for the same fingerprint.** Local fixes only; remote actions retain separate approval requirements.
+3. **Deduplicate by root cause, not by occurrence.** One missing null check repeated in six files is
+   one finding that lists six files — not six findings.
+4. **Verify before flagging.** Check for an adjacent comment explaining the choice, a decision in
+   `.specs/STATE.md`, or a test that validates the behaviour. Unconventional is not the same as wrong.
+5. **Never report what a linter already catches.** Run the consuming project's linter first and drop
+   every overlapping candidate.
+6. **Signal over volume.** Above 20 findings, keep all blocking ones and prune the rest to the most
+   impactful. Eight precise findings are worth more than thirty that include marginal concerns.
+7. **The reviewer is not the author.** A different actor, or at minimum a different model — the model
+that implemented the change never solely reviews it. This is cheaper than recruiting a fresh agent
+identity and buys the same independence.
+   Verifier and Deep Reviewer receive fresh role packets. They do not inherit the Implementer's
+   transcript or operator handoff. Their conclusions must come from the spec, diff, tests, and
+   assigned evidence.
+8. **Documentation and instruction changes follow the proportional classifier in `.agents/skills/wtk/references/validation.md`.** Pure maintenance and bounded instruction changes do not start wtk-deep-review or QA by default; mixed changes run canonical checks for changed executable behavior. Named concrete risk or changed public promise can select stronger review; file count and the word "feature" do not escalate them.
+8. **A passing verdict requires valid evidence for its scope.** Apply `.agents/skills/wtk/references/validation.md` to the finding's causal path and retain unaffected results.
+   A failed full run stays failed even when focused correction proofs pass.
+9. **A new control for an unobserved failure is Major (YAGNI) unless the spec named it.** A
+   killed-process shim, a test-of-the-test, or a prefix allowlist the spec did not name is overbuild.
+   Filed-issue review uses the same rule. `ponytail-review` is the skill; this rule is what makes
+   YAGNI blocking.
+## Fingerprinted remediation accounting
+`fingerprint = requirement + root cause + failure path` is each finding's immutable identity. Maintain an independent cumulative failed-remediation counter and append-only generation history for each fingerprint; count every failed post-fix Verifier result, whether or not the build gate is green. The current generation's consecutive-stall state is separate and halts only at the live `[remediation].stall_attempts` threshold. The executable state lives in `review-fingerprints.json` through the stdlib convergence script, which delegates the pure transition to `remediation.py`.
+Rewording or reopening a finding preserves its fingerprint and counter. A distinct finding starts at count zero and does not consume another fingerprint's counter; the diagnostic cap is separate.
+## The Review-Signal trailer
+
+The delivery commit for a pull request carries one `Review-Signal:` line recording its review
+outcome, so the record survives the pruning of `.specs/features/` (AD-025). `check_commit.py`
+validates the line when present and never requires one (AD-026); that validator's docstring owns
+the field-by-field grammar.
+
+## Finding shape
+Every finding states, in this order:
+
+- **Premise** — the fact in the code that starts the argument, with `file:line`
+- **Path** — the concrete sequence from that fact to a wrong outcome
+- **Verdict** — severity from the taxonomy below, never inflated
+A finding without a failure path is an advisory, not a defect. Advisories state
+**Premise → Improvement → Fix** and never block.
+
+Severity uses the scheme tlc's validation report already ships, so the Verifier and wtk-deep-review speak
+one vocabulary:
+
+| Severity | Meaning | Action | Remediation check | Blocks delivery |
+| --- | --- | --- | --- | --- |
+| `Critical` | Data loss, security hole, or the feature does not work | Fix now | yes | yes |
+| `Major` | Behaviour deviates from the spec, or a likely crash under real input | Fix now | yes | yes |
+| `Minor` | A spec edge case is unhandled, or a real maintenance hazard | Fix in the active feature batch | no | until fixed |
+| `Trivial` | Style, naming, structure — a nitpick by definition | File an issue | no | no |
+
+Every confirmed wtk-deep-review defect is fixed before feature delivery. An unfixed `Critical` or `Major`
+means the verdict is `FIX_BEFORE_SHIP`, and only those severities trigger a remediation check. Every
+`Minor` closes in the current remediation batch; the scoped gate and one commit close it without
+another proof cycle. Trivials and advisories become follow-ups and never hold a pull request.
+
+Filed Trivial issues are real work, not a disposal bin. They enter the backlog like any other item.
+
+## Fixing a filed issue
+
+**A filed Trivial issue does not re-enter the loop above.** It was already reviewed — that is how it
+came to be filed — so a verifier, a QA pass and a wtk-deep-review would re-do work that is already
+done. Minor findings never enter this path; they close inside their originating feature run.
+
+Fix one, or a batch of them, as a small change:
+
+```
+implement → scoped gate → one commit for the batch
+```
+
+No spec, no tasks file, no verifier, no wtk-deep-review round. `wtk` already sizes this way:
+a change of a few files with an obvious outcome skips planning entirely.
+
+Three things still apply, because they are about the change and not about the review:
+
+- **If the fix changes user-visible behaviour**, flag its scenario per `QA-SCENARIOS.md` and walk it.
+  A `Trivial` finding on a screen is still a change a user can see.
+- **If the fix touches a security surface**, `SECURITY.md` fires as it would for any diff.
+- **If the fix turns out to be large** — it needs a schema change, it spreads across a boundary, the
+  "one-line fix" opens a design question — it stopped being a filed issue and became a feature. Take
+  it through the full loop and say why.
+
+Batch aggressively. One commit per remediation batch is already the commit rule, and a batch of six
+`Trivial` findings in one area is one review's worth of attention, not six.
+
+## Escalation
+
+While a remediation check leaves a Critical/Major open, finish approved remediation and run its scoped gate after every attempt; the fix needs no new approval. Each attempt derives a stable signature from sorted failing-test identifiers after removing timings, absolute paths, and line numbers; a current failing-test set that is a strict subset of the running minimum failing-test set resets the counter, while an equal-size set, including one with different members, or a larger set increments it, and `stall_attempts = 0` is unbounded.
+If the gate is unavailable, halt immediately without another remediation check; when a nonzero threshold is reached, halt with the repeated signature, attempt count, and fixes tried. An open Critical alone does not halt while attempts establish new minima; wtk-ship uses the same unavailable-gate or reached-threshold halt contract.
+
+## Requirement and contract parity
+
+A green gate proves the code compiles, lints and passes its tests. It does not prove the code matches
+the feature contract. Every reviewer additionally compares the deliverable against the canonical
+artifacts — `plan.md` acceptance criteria, `checks.md` cases, the independent `verification.md` report,
+and the `uiux.md` / `dx.md` surface contracts when they exist — field by field, not by paraphrase.
+
+The failure this prevents is specific: a change can pass many review rounds while contradicting the
+plan and checks, because every round measured engineering quality against an implementation paraphrase and nothing ever compared it to the source.

package/docs/toolkit/guidelines/SECURITY.md

@@ -0,0 +1,160 @@
+# Security
+
+**Read when:** the change touches runtime code, configuration, dependencies, schemas, deployment, data
+flows, or public behaviour. Pure documentation and formatting changes are exempt.
+
+**Why this exists:** Security that lives only in a review at the end is theatre. Surfaces declared at
+Specify become countable `SEC-` cases; review looks for what the table missed. A control with no test
+is a memory, not a requirement.
+
+Security is built, not reviewed in. Review catches what construction missed; it is the last line, not
+the first. This guideline is self-contained — it does not depend on any other security document.
+
+Product rules stay authoritative in the consuming project's product docs. Architecture invariants stay
+authoritative in its architecture docs. This says how feature work applies and verifies them; it does
+not restate them.
+
+## External filesystem writers
+
+Run an external tool that writes files in an isolated environment or with explicitly allowed
+directories. Validate destination paths and symlinks before the first write. Preserve destination-only
+files and never delete them automatically.
+
+## 1. Before coding — build with the right guidance loaded
+
+1. Apply the installed `security-implementation` skill to secure-by-default implementation and
+   hardening. It is not an audit; surface any Critical or High concern encountered immediately.
+2. During Specify, invoke the installed `security-spec` skill to define security requirements and
+   negative tests.
+3. During Specify or Design when section 4's surfaces apply, invoke `security-threat-model` to map
+   assets, boundaries and threats.
+4. Identify affected languages, frameworks and versions; load the applicable concept references.
+   Verify framework APIs and defaults using the consumer's documentation tools and current official
+   docs for the installed version. Use a matching framework skill when available; record uncertainty.
+5. **Convert that guidance into security outcomes in the spec and the test contract.** Outcomes, not
+   controls: a test asserts the required *result*, never the presence of a particular implementation.
+
+## 2. At Specify — declare the surfaces
+
+Every feature declares which of these eleven surfaces it touches. The identifiers are stable; never
+rename them.
+
+| ID | Surface |
+| --- | --- |
+| S1 | Runtime, configuration, dependency, schema, deployment, data-flow or public-behaviour change |
+| S2 | External route, ingress or trust boundary |
+| S3 | Authentication, session, cookie, CSRF, IP trust or rate limit |
+| S4 | Server-side authorization and ID- or tenant-identified resources |
+| S5 | Credentials, tokens, secrets, keys or data delivered to the browser |
+| S6 | Untrusted input/output and HTML, URL, SQL, shell or filesystem sinks |
+| S7 | Uploads, SVG, active content, parsers or decoders |
+| S8 | Personal, contact, tenant data or user-generated content |
+| S9 | External providers, callbacks, webhooks, jobs or queues |
+| S10 | Persistence whose confidentiality or integrity affects product authority |
+| S11 | Deployment, processes or isolation |
+
+`## Security Surfaces` goes in `plan.md`. One row per applicable surface, naming the control and the
+`SEC-NNN` requirements that prove it:
+
+```markdown
+## Security Surfaces
+
+| ID | Surface | Control | Requirements |
+| --- | --- | --- | --- |
+| S2 | `POST` public create route, unauthenticated | Per-IP rate limit, strict input validation | SEC-001, SEC-002 |
+| S6 | Free-text name rendered back to the page | Escaped on output; no HTML sink | SEC-003 |
+| S8 | Email stored at rest | Never returned by any list endpoint | SEC-004 |
+```
+
+A surface with no control is an open question, not a finished row. Surfaces the feature does not touch
+are simply absent — do not write a row to say so.
+
+## 3. At the test contract — abuse cases get IDs
+
+Every control becomes one or more `SEC-` cases in `.specs/features/<feature>/checks.md`. Each case
+uses the native checks contract: its claim has a concrete outcome and one or more named proofs, and
+each enumerated abuse-case member appears in `Coverage`. SEC IDs trace to native `C<n>` checks, not
+tasks, and are audited for orphaned claims like the rest. See `.agents/skills/wtk/references/test-contract.md` and
+the [native Lean checks reference](../../../.agents/skills/wtk-lean/references/checks.md).
+
+Examples only — not a `checks.md` schema:
+
+| ID | Abuse case | Attempt | Expected |
+| --- | --- | --- | --- |
+| SEC-001 | Unauthenticated read of another account's records | `GET` the list route, no session | 401, no body leakage |
+| SEC-002 | Submission floods the endpoint | 100 requests in 10s from one IP | 429 past the limit, no rows written |
+| SEC-004 | Personal data leaks through a list endpoint | `GET` the list route as an entitled operator | No `email` field in any item |
+
+This is the whole point: **a control becomes countable instead of remembered.** Pick the cheapest
+discriminating layer — most abuse cases are integration tests against the route, not e2e.
+
+Authentication, session, cookie, CSRF, trusted-IP, rate-limit, authorization and tenant-identity
+outcomes are layer-independent. A cheaper layer may discriminate the behaviour, but it never removes
+the permanent security smoke coverage when the changed surface is unknown, transversal, or
+classification-failed.
+
+Browser fixtures use scenario-owned identities and IPs, in-memory session state, exact `finally`
+cleanup, and secret-free diagnostics. **No test artifact ever contains credentials, cookies, database
+URLs, session headers, or reusable tokens.**
+
+## 4. Threat model — when the surface is serious
+
+Write a scoped threat model during **Specify or Design, before coding**, when the feature introduces
+or changes any of S2, S3, S4, S5, S7, S8, S9, S10 or S11. S1 and S6 alone do not trigger one.
+
+Scope it to `.specs/features/<feature>/` and write the report to
+`.specs/features/<feature>/threat-model.md`. Ground the deployment, data-sensitivity and attacker
+assumptions in canonical documentation, not invention.
+
+Run it again when scope, entrypoints, architecture, assets, trust boundaries or attacker assumptions
+change. Behaviour-preserving refactors do not need one.
+
+## 5. At review — the residual only
+
+With surfaces declared and controls tested, review looks for what the table missed rather than
+rediscovering the table.
+
+The independent verifier uses the installed `security-review` skill to review the complete feature
+diff. It detects flaws in code that now exists — injection, exposed secrets, broken access control,
+vulnerable dependencies — which the before-coding skills cannot catch because they ran before the
+code was written. Both are needed; neither replaces the other.
+
+Findings carry the same weight as any other: **unresolved Critical or High blocks completion**,
+regardless of any project priority label. Accepting a risk requires your explicit approval and an
+append-only `AD-NNN` in `.specs/STATE.md`.
+
+## Evidence
+
+The feature's validation report ends with a security section carrying:
+
+- The security skills applied
+- The threat-model path, or a specific reason it does not apply
+- Every `SEC-NNN`, its surface, `PASS` or `FAIL`, and a resolvable `` `file:line` `` citation
+- Open Critical and High counts, each an actual number
+- The verdict
+
+**A verdict with no requirement behind it is not evidence**, and a severity named without a number is
+not a count. Documentary presence never proves the absence of a vulnerability.
+
+## Scoped campaigns, outside the feature loop
+
+Feature-time security covers the feature. It does not cover the codebase.
+
+Run a scoped security review against an area on its own schedule. It reads the whole codebase to
+build confidence but reports only on the scoped area, and what it finds becomes filed issues fixed as
+their own work. Never on a feature's critical path.
+
+Two rules keep a campaign useful: **research broadly, report narrowly** — trace where the input
+actually comes from and what protections already exist before flagging; and **high confidence only**
+— a finding needs a concrete path from attacker-controlled input to a vulnerable sink, never a
+pattern match.
+
+## What this drops from earlier ceremony
+
+The substance is unchanged. What goes is the bookkeeping:
+
+- The eleven-row declaration required a row for **every** surface including inapplicable ones. Absent
+  now means not applicable.
+- A gate that only reads the *shape* of security evidence, and never reads product code looking for a
+  flaw, is not a security gate. Keep it out of the full gate.
+- The separate security-review artifact folds into the validation report. One evidence file.

package/docs/toolkit/guidelines/UI-UX.md

@@ -0,0 +1,117 @@
+# UI/UX Surface Map
+
+**Read when:** a feature adds or changes a screen, or a task names an approved visual reference.
+
+**Why this exists:** `uiux.md` freezes states and the approved visual source so design and implementation
+can execute in one pass and QA can judge the user-visible result. The repository stores only the approved
+handoff. Features with no new or changed screen skip the surface map.
+
+## The artifact
+
+`.specs/features/<feature>/uiux.md`, written in Specify before internal design begins. Keep reference facts
+here; tasks and packets point to its rows instead of copying a second manifest. When phases are skipped
+and a task names a reference, keep the same fields in a bounded inline task record.
+
+An approved source, frame, or frozen export selects reference fidelity, including for a new screen. Open
+design keeps its exploration procedure. Resolve disagreements in this order: `spec.md` → `uiux.md` →
+approved design artifact → tool or plugin output, then legacy mockup. The source owns visual appearance;
+runtime truth, accessibility, and explicit product constraints still apply. Identify and resolve a
+conflict with its owner; do not silently reinterpret, round, or rewrite the reference. External/global
+aesthetic skills advise within this contract.
+
+```markdown
+# <Feature> UI Change Map
+## Reference (when an approved source is supplied)
+- **Approved source/frame:** tool and frame, or checked-in export path
+- **Revision/frozen export:** revision, or frozen export path plus commit/hash
+- **Route and mapping:** route; state ↔ exact viewport width×height pairs
+- **Captures:** original/reference and implementation capture paths
+- **Environment:** browser, OS, DPR, fixtures/content, and loaded fonts/assets
+- **Tokens:** source provenance; mapped tokens; aliases/themes; inferred or missing values
+- **Layout/responsive constraints:** geometry, breakpoints, and supported differences
+- **Expected differences/tolerances:** approved differences recorded before judgment
+## Screens
+### <Screen name> — `<route>`
+- **New or changed:** changed
+- **Story:** links the user story it serves
+- **Entry points:** how a user reaches it
+- **States:** empty · loading · populated · error · submitting · success
+- **Viewports:** exact width×height values and the responsive rule at each
+## Components
+| Component | New or existing | States and variants | Source |
+| --- | --- | --- | --- |
+| `PublicForm` | new | idle, validating, submitting, error, success | existing primitives |
+## Copy
+Every user-visible string this feature introduces, in the product's language, with its context.
+## Out of scope
+Screens and components this feature deliberately does not touch.
+```
+
+## Rules
+
+1. **Enumerate states.** Never write "all states"; list each state a design agent can execute.
+2. **Reuse before create.** Check design docs and the component inventory; a new generic primitive needs
+   a reason and a domain variant takes a domain-prefixed name.
+3. **Extract tokens before coding.** Extract actual source values into the canonical token source,
+   preferably from a structured export: typography metrics, font weights, line-height, tracking, spacing,
+   colours, radii, borders, and shadows. Keep layout constraints separate. Reuse matching tokens, map
+   aliases/themes, and record deliberate shared-token changes. Mark raster/fragment inferences explicitly.
+4. **Truthful UI wins.** Never render an unsupported control or metric. Runtime truth wins on conflict,
+   and the conflict is recorded.
+5. **Freeze the surface before internals.** Reopen this document explicitly when the surface changes.
+6. Its existence marks the feature UI-bearing for QA when the proportional classifier selects QA.
+7. **Trace the common completion path.** Walk from user intent to completion for each changed
+   interaction. Remove avoidable clicks, repeated input, navigation, and keyboard-pointer switches with
+   platform conventions while preserving clear choices, validation, and feedback. Record start,
+   completion, recovery, and next-action behavior in acceptance criteria, then verify that path.
+8. **Use native form submission.** For web workflows with an explicit submission, use native `<form>`
+   semantics and a primary submit action. Enter in a plain single-line input and activating the submit
+   button must use the same submission path; preserve expected Enter behavior for multiline fields,
+   selection controls, and active input composition.
+
+   **Example:** Given a valid tag name and selected color, pressing Enter creates exactly one tag with
+   those values; an error keeps the input. If repeated creation is intended, leave the next entry ready
+   without reopening or restoring focus manually.
+
+## Optional design tooling
+
+When an approved HTML/CSS export is the declared visual source, render it with supplied fonts/assets and
+verify that render is ready before implementation; compare it with an original frame only when that
+frame is the declared authority. Port structure/styles into the project stack, adapting syntax,
+component ownership, and behavior while preserving visual values. The export is source material, not a
+blind generated-code dump or compulsory DOM-identity contract; React and Tailwind are examples, not
+source-pack dependencies. Keep supported exports/assets usable when the design tool is unavailable; tool
+absence or failure falls back to the normal repository artifacts and does not block unrelated work.
+Missing source, fonts, assets, or responsive evidence is an
+explicit gap; fidelity cannot PASS on assumptions, stale captures, or unavailable proof.
+
+## Working with a design agent
+
+1. State constraints first: user goal, required states/actions, hierarchy, accessibility, responsive behavior, runtime/data
+   limits, brand principles, and existing components.
+2. Read selected references and inspect affected components read-only. With an approved reference, load
+   its `uiux.md` rows and source/export before proposing changes.
+3. For an open genuinely new screen or meaningful redesign, provide three distinct directions and a fourth only
+   for a named tradeoff. An approved reference selects the direction and skips alternatives; corrections
+   never require variants.
+4. For open design, prototype in the available tool, isolated HTML, or component playground when useful;
+   keep variants out of production. With an approved source, render and inspect it before porting.
+5. Subtract purposeless UI only during open design, retaining discoverability, accessibility, actions,
+   and feedback. Review against `uiux.md` and the source; one exploration pass and one refinement cap applies
+   to open design only.
+6. Record source/frame, reused components, states, viewports, copy, token mappings, expected differences,
+   and tradeoffs in the UI contract. A reference task points to these rows through `design_excerpt` and
+   records paired evidence. Human local QA is recorded only after human confirmation.
+
+No new showcase, preview deployment, design integration, or split frontend/backend delivery is mandatory.
+
+## Verifying the built screen
+
+When a visual reference is named, completion requires fresh paired reference and implementation captures
+for every declared exact viewport and state, with fixtures/content, browser/DPR, and loaded fonts/assets.
+Use the existing adapter and paired inspection, overlay, or diff to compare geometry, typography, tokens,
+imagery, interaction states, and responsive behavior. Record expected differences/tolerances before
+judging; source or implementation changes invalidate affected evidence. Missing evidence is unverified;
+an unacceptable mismatch fails. Functional assertions alone do not prove fidelity, and no universal
+arbitrary pixel threshold applies. Manual comparison is evidence, not an automated test. Keep raw captures
+disposable and put the durable verdict and source pointers in the existing task, verifier, or QA report.