@gobing-ai/spur 0.3.62 → 0.3.64

package/plugins/sp/skills/dogfood-testing/SKILL.md

@@ -48,7 +48,7 @@ testee (a /sp:... command, Skill(...), or shell CLI invocation)
 The command forwards these via `$ARGUMENTS`:
 
 | Argument | Description | Default |
-|----------|-------------|---------|
+| ---------- | ------------- | --------- |
 | `testee` | What to exercise — a slash command, agent skill, or CLI invocation (positional, required). Quote it if it contains flags. | (required) |
 | `--agent <name\|auto>` | **Testee-scoped** agent: the agent the **testee** runs under, forwarded into the testee invocation. The driver (this skill) always runs in the current session. **Omit it** to forward nothing — the testee runs under its own default. See [§Testee-scoped agent](#testee-scoped-agent). | (omitted → forward nothing) |
 | `--max-retry <n>` | Fix attempts per failed step. The **default is `2`** (fix mode): apply `Edit`/`Write` fixes to the working tree, up to 2 attempts per step. This flag is **mandatory** for two independent mutation sources: (a) pipeline-driving testees and (b) testees carrying a mutating `--fix` mode (`--fix all` / `--fix blockers-first`). Pass `--max-retry 0` for **observe-only**, or `--max-retry N` to acknowledge fix-mode mutation risk. For a mutating-`--fix` testee, `--max-retry 0` bounds the **driver only** — the testee still mutates the tree. | `2` unless the testee is pipeline-driving or carries a mutating `--fix` mode |
@@ -239,6 +239,7 @@ Full section contract, frontmatter, Cost shape, and footer:
 **[report-template.md](references/report-template.md)**.
 
 **Sinks** (composable):
+
 - **Always-on report files** → live + `docs/dogfood/YYYY-MM-DD-<testee-slug>-dogfood.md` (see Phase 1).
 - `--save` → no-op for delivery; still print/document the report path (back-compat).
 - `--task` → file findings as a review task (`spur task create --template review`), writing the
@@ -276,6 +277,7 @@ which always launches a fresh agent subprocess.
 - Producing a structured findings report (and optionally a fix task) from a real run.
 
 Do **not** use this skill for:
+
 - Requirements-traceability verdicts — use `sp:code-verification` (`/sp:dev-verify`).
 - SECU code review of a diff — use `sp:code-verification` (`/sp:dev-review`).
 - Running a task through the fix pipeline — use `sp:spur-dev` (`/sp:dev-run`).
@@ -606,3 +608,14 @@ Findings (P1+P2):
 A report missing any of the six headings, the on-disk live ledger, dual paths, terminal `status`,
 the Cost block, or this footer does not satisfy the dogfood contract on this platform, regardless
 of `Skill()` availability.
+
+## Engine-driven testees under a sandboxed session
+
+A subprocess executor dies at startup, not at model time, when `.claude/settings.json` denies
+it its state directory (`~/.pi`, `~/.grok`, `~/.gemini`, `~/.codex`, `~/.cache`) or local
+socket binding. Signals: `EPERM: operation not permitted`, `FS_PERMISSION_DENIED`,
+`bind: operation not permitted`. Two affordances must be granted and the session restarted:
+`sandbox.filesystem.allowWrite` covering the executor home dirs, and
+`sandbox.network.allowLocalBinding`. Caveat: `spur agent doctor` reports `usable: true` from
+configuration alone — it never probes a real dispatch, so `usable` means *configured*, not
+*proven runnable under this sandbox*.

package/plugins/sp/skills/dogfood-testing/references/report-template.md

@@ -237,6 +237,36 @@ downstream task creation does not inherit an unactionable acceptance criterion:
 
 The tag is a prompt to whoever turns findings into tasks: `[stale]` → drop, `[unverifiable]` →
 reframe or defer, `[feasible]` → proceed. A finding without a tag is treated as `[feasible]`.
+
+**Optional class tag (environment lens, task 0686).** A finding line may carry one closed class
+tag — `environment` | `testee` | `waste` — positioned immediately after the em dash and distinct
+from the trailing feasibility tag:
+
+```
+- **P2** — [environment] <what's wrong>. → **Action:** <concrete change>.  (`file:line`, ~effort)  `[feasible]`
+```
+
+Omitting the class preserves the current line shape; untagged findings remain valid and the
+protocol stays `sp:dogfood-testing@1.2` (the validator gains no required field; the cache-health
+P3 above needs no class).
+
+- `testee` — a defect in the testee's contract (the protocol the run grades). Bounded fix-mode
+  may repair it, unchanged.
+- `environment` — a steering/placement/check-shaped observation projected from the
+  [environment-improvement lens](../../../references/environment-lens.md), which owns the
+  category table and the placement rule. **Proposal-only:** even under `--max-retry N`, bounded
+  retries never `Edit` or `Write` `AGENTS.md`, `CLAUDE.md`, skills, rules, numbered docs, or
+  plugin references for an environment-tagged finding — it stays a recommended action here.
+- `waste` — a token/tool-waste diagnostic with no missing environment affordance behind it.
+
+Class, not the cited file path, decides whether bounded fix may mutate. A session mistake a
+linter, typechecker, test, or filesystem gate could have caught is `environment`, and its
+recommended action proposes a new-or-tighter automated check — never another sentence in an
+always-loaded steering file. Missed coding standards are `environment` owned by a review path
+(`sp:code-verification`, `sp:code-review`, or pipeline review) — never the implementer skill;
+navigation friction and dead always-loaded instructions are likewise `environment`, not
+`testee`.
+
 Severity scale:
 
 - **P1** — blocks correct use or causes drift/wrong output; fix before shipping the testee.

package/plugins/sp/skills/history-anatomy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: history-anatomy
-description: "Independent owner of diagnostic interpretation over already-imported history — the daily/ad-hoc mode contract, a closed finding taxonomy, the eleven-section report contract, and the enrich/validate rubrics. Triggers: history-anatomy, run the daily report, ad-hoc diagnosis, find issues over history."
+description: "Independent owner of diagnostic interpretation over already-imported history — the daily/ad-hoc mode contract, a closed finding taxonomy, the twelve-section report contract, and the enrich/validate rubrics. Triggers: history-anatomy, run the daily report, ad-hoc diagnosis, find issues over history."
 license: Apache-2.0
 version: 1.0.0
 metadata:
@@ -37,7 +37,7 @@ fresh skill cannot be added to the BASELINE exemption map).
 **Choose the mode first.** The single entry is `--mode daily|ad-hoc` (default `daily`):
 `references/modes.md`.
 
-**Then hold the report to the contract.** Every report must contain the eleven sections and every
+**Then hold the report to the contract.** Every report must contain the twelve sections and every
 finding the full field set, with evidence rules and an explicit comparability verdict:
 `references/report-contract.md`.
 
@@ -63,5 +63,5 @@ finding the full field set, with evidence rules and an explicit comparability ve
 | Reference | Owns |
 | --- | --- |
 | [`references/modes.md`](references/modes.md) | The daily/ad-hoc mode matrix, bounds normalization, the DST-aware calendar-day rule, and the fail-loud message shape. |
-| [`references/report-contract.md`](references/report-contract.md) | The eleven sections (in order), the per-finding field set, the closed category vocabulary, the stable-key grammar, the evidence rules, comparison semantics, recurrence classes, and the positive-pattern / remediation standards. |
+| [`references/report-contract.md`](references/report-contract.md) | The twelve sections (in order), the per-finding field set, the closed category vocabulary, the stable-key grammar, the evidence rules, comparison semantics, recurrence classes, and the positive-pattern / remediation standards. |
 | [`references/operations.md`](references/operations.md) | The `enrich` and `validate` operation rubrics; neither launches a workflow. |

package/plugins/sp/skills/history-anatomy/references/operations.md

@@ -15,7 +15,7 @@ duplicated into the YAML: the rubric cannot recurse.
 
 | Operation | Input | Output |
 | --- | --- | --- |
-| `enrich` | current forensics artifact + baseline artifact (plain `HistoryArtifact` JSON) | the model-authored report sections (Baseline comparison, Findings, Recurrence ledger, Remediation options, Performance analysis, Workflow and process improvements, Positive patterns) meeting the report contract |
+| `enrich` | current forensics artifact + baseline artifact (plain `HistoryArtifact` JSON) | the model-authored report sections (Baseline comparison, Findings, Recurrence ledger, Remediation options, Performance analysis, Workflow and process improvements, Report-only advisories, Positive patterns) meeting the report contract |
 | `validate` | a candidate report + the current/baseline artifacts | a PASS / FAIL verdict with per-finding and per-section evidence checks, naming any failing rule |
 
 Freeze these operation names and this input/output contract — 0660 consumes them verbatim.
@@ -31,13 +31,23 @@ Given the current and baseline artifacts, author the model half of the report. A
    calendar day; ad-hoc → immediately preceding equal-duration window. If baseline coverage is
    insufficient or materially different, emit `not comparable` and **no** trend/delta/percentage.
 3. **Findings** — each with the full per-finding field set (key, category, impact, trend,
-   observation, inference, confidence, contradictions, evidenceAnchor). Categories from the closed
-   vocabulary; stable keys of the form `<category>:<owner-surface>:<signal>`.
+   observation, inference, confidence, contradictions, evidenceAnchor, severity, reproCommand,
+   ownerSurface). Categories from the closed vocabulary; stable keys of the form
+   `<category>:<owner-surface>:<signal>`. Severity is the closed P1/P2/P3 vocabulary and is
+   orthogonal to confidence; reproCommand reproduces the observation verbatim; ownerSurface names
+   the concrete owning surface (file/package/command), consistent with the key's middle segment.
 4. **Recurrence ledger** — classify every finding against the baseline on the **stable key**.
 5. **Telemetry gaps** — every dimension the artifact cannot support, rendered `not available`.
 6. **Remediation options** — proposals only (owner surface, expected impact, verification method,
-   reversibility). No applied change/diff/command.
-7. **Positive patterns** — same evidence standard as problems.
+   reversibility), plus the printed `spur task create` handoff invocation carrying the finding's
+   stable key for accepted proposals. No applied change/diff/auto-write to the corpus.
+7. **Report-only advisories** — repeated identical tool-and-argument signatures surfaced with
+   repetition counts; proposes no automatic interruption (report-only, 0680 R5).
+8. **Positive patterns** — same evidence standard as problems.
+
+Run-cost note (0680 R6): Performance analysis reports what this run's chained `agent.run`
+stages cost using the pairing analytics fold (totalCostUsd / meanDurationMs per pairing); a
+pairing without cost signal renders `not available`, never zero.
 
 Never fabricate a value, a trend, an anchor, or an applied fix. Never launch a workflow.
 
@@ -45,11 +55,14 @@ Never fabricate a value, a trend, an anchor, or an applied fix. Never launch a w
 
 Given a candidate report and the artifacts, independently verify:
 
-- **Eleven-section completeness and order** — all eleven section names present in the frozen
+- **Twelve-section completeness and order** — all twelve section names present in the frozen
   order; none renamed/omitted.
 - **Per-finding fields** — every finding (problem and positive) carries key, category, impact,
-  trend, observation, inference, confidence, contradictions, evidenceAnchor; category in the closed
-  vocabulary; stable-key grammar.
+  trend, observation, inference, confidence, contradictions, evidenceAnchor, severity (P1/P2/P3),
+  reproCommand, ownerSurface; category in the closed vocabulary; stable-key grammar. A finding
+  missing any triage field FAILs (the deterministic gate enforces the same set).
+- **Remediation handoff** — each accepted-proposal handoff carries a `spur task create`
+  invocation naming the finding's stable key; no auto-written tasks.
 - **Evidence anchors** — every finding has at least one verifiable anchor; no anchor → FAIL.
 - **Causality gate** — a causal claim with one signal must be labelled a hypothesis with a
   confirmation path; otherwise FAIL.

package/plugins/sp/skills/history-anatomy/references/report-contract.md

@@ -1,10 +1,10 @@
 # Report contract — `sp:history-anatomy` (HA-S1, 0658)
 
-The published report is the skill's contract. This reference owns the eleven sections (in order),
+The published report is the skill's contract. This reference owns the twelve sections (in order),
 the per-finding field set, the closed category vocabulary, the stable-key grammar, the evidence
 rules, comparison semantics, recurrence classes, and the positive-pattern / remediation standards.
 
-## Eleven required sections (in order, frozen)
+## Twelve required sections (in order, frozen)
 
 1. Scope and provenance
 2. Executive summary
@@ -15,8 +15,9 @@ rules, comparison semantics, recurrence classes, and the positive-pattern / reme
 7. Remediation options
 8. Performance analysis
 9. Workflow and process improvements
-10. Positive patterns
-11. Evidence ledger
+10. Report-only advisories (0680 R5)
+11. Positive patterns
+12. Evidence ledger
 
 These names are consumed verbatim by 0659's structure gate and 0660's validation stage. Do not
 rename, reorder, omit, or restate them.
@@ -26,7 +27,13 @@ rename, reorder, omit, or restate them.
 - Categories: `reliability` | `repetition` | `workflow` | `performance` | `coverage` |
   `telemetry` | `positive`.
 
-Every finding's category is drawn from this closed set. No category is invented.
+Every finding's category is drawn from this closed set. No category is invented — explicit
+`category` values outside it fail the structure gate (`finding-invalid-category:<value>`), and so
+do stable keys whose first segment falls outside it (`finding-invalid-key-category:<value>`,
+task 0686). Environment-lens retro category names are encoded only in `<signal>` or the
+owner-surface segment — never as a category. The authoritative seven-name projection table lives
+in the [environment-improvement mapping](../../../references/environment-lens.md), which this
+reference defers to rather than restates.
 
 ## Stable finding key (frozen)
 
@@ -58,6 +65,9 @@ Every finding — problem and positive alike — carries the full field set:
 | `confidence` | Per-finding: `high` / `medium` / `low`. Never one blanket report-level score. |
 | `contradictions` | Any contradicting signal shown beside the finding, not silently reconciled. |
 | `evidenceAnchor` | At least one anchor to the forensics artifact or cited `file:line`. An entry with no anchor is invalid. |
+| `severity` | Closed vocabulary `P1` / `P2` / `P3` — how much the finding matters. Orthogonal to `confidence`: severity orders work, confidence says how sure we are (0680 R1). The structure gate fails a finding without one. |
+| `reproCommand` | The invocation that reproduces the observation — one command a reader can run verbatim (0680 R2). Gate-enforced. |
+| `ownerSurface` | The concrete surface that owns the fix (a file path, package, or command), consistent with the key's `<owner-surface>` segment but named as a target rather than a slug (0680 R3). Gate-enforced. |
 
 ## Evidence rules
 
@@ -120,11 +130,59 @@ Each option is a **proposal** that names:
 The report must contain **no applied change, no diff, and no command it claims to have run**. The
 skill never applies a fix; it proposes one.
 
+### Remediation handoff route (0680 R4)
+
+For each proposal an operator accepts, the report supplies — printed in the report itself, never
+executed — the `spur task create` invocation that lands it, carrying the proposal's finding
+`key` in the task body so the next report classifies that finding as `resolved`. Auto-writing
+to the task corpus from a model-authored report would bypass the CLI-gated write contract; the
+operator remains the gate.
+
+### Report-only advisories (0680 R5)
+
+Section 10 is the standing home for observations that inform workflow hygiene but must never
+trigger automatic interruption: repeated identical tool-and-argument signatures are surfaced
+here with their repetition counts, proposing at most human-decided process changes. Nothing in
+this section may drive automated behavior.
+
+### Run-cost reporting (0680 R6)
+
+Performance analysis states what the run itself cost: per-pairing `totalCostUsd` /
+`meanDurationMs` figures flow from the pairing analytics fold (0679 repaired the payload
+paths), so chained `agent.run` stages are reportable instead of "~unknown". Where no cost
+signal exists for a pairing it renders `not available`, never zero.
+
+## Projected candidates — section 9 (environment lens, task 0686)
+
+Section 9 (Workflow and process improvements) stays additive report grammar: unprojected numbered
+prose remains valid and gains no required fields. A candidate **projected** through the
+[environment-improvement lens](../../../references/environment-lens.md) is a bullet beginning with
+a backticked stable key (retro name in `<signal>` or owner surface, closed category first — e.g.
+`workflow:agents-md:navigation`) and carries four bold fields, the same names remediation options
+use:
+
+```text
+- `workflow:agents-md:navigation` — **owner surface:** `AGENTS.md` see_also. **expected impact:**
+  shorter file hunt. **verification method:** subsequent daily report key `resolved` or absent.
+  **reversibility:** revert the pointer.
+```
+
+A projected candidate cites its section-4 finding `key` when one exists. Reports remain
+proposal-only: no applied change, no diff, and no command the report claims to have run.
+
 ## Evidence ledger
 
 The final section lists, for every finding, the artifact anchor(s) and any cited `file:line`,
 so a reader can verify the report's claims against the evidence plane.
 
+Every row MUST name the artifact path in backticks — the deterministic structure gate's
+`evidence-claim-without-anchor` check matches `` `[^`]+\.(md|ts|json)` `` or a
+`path:line` — never a bare `current`/`baseline` label. Write each anchor as:
+
+```text
+`telemetry:history-analyze:duration-coverage-gap` | `.spur/run/<runId>-history-anatomy-current.json` — `#/warnings/0`, `#/derived/timeDecomposition`, `#/stepSupport`
+```
+
 ## Truthfulness invariants
 
 - `not available` is the true rendering for an unsupported dimension, never a masked gap.

package/plugins/sp/skills/next-router/SKILL.md

@@ -42,12 +42,12 @@ silently (that is a HITL stop).
 ## Inputs
 
 | Input | Semantics |
-|-------|-----------|
+| ------- | ----------- |
 | `target` | Task WBS (digits), task `.md` path, or feature id (`^[A-Z][1-9]*$`). Required for dispatch; omit → stop **U1** (usage). |
 | `--dry-run` | Print the resolved plan (**P1**) and do not dispatch. |
 | `--once` | Strip `--next` from the shaped child argv so only the current step runs; no router re-entry. |
 | `--auto` | Forward into dispatched children that support it. **Never** breaks multi-candidate HITL ties. |
-| `--agent <inline\|auto\|name>` | Execution-surface selector forwarded into the dispatched child when that child documents `--agent`. Router defaults to omit semantics: Omit forwards nothing, and the dispatched child applies its own default (host session, 0508 eligibility). Explicit `--agent inline` is the zero-dispatch carve-out, forwarded as-is; escalation triggers reject `inline` (no override). |
+| `--agent <inline\|auto\|name>` | Execution-surface selector forwarded into the dispatched child when that child documents `--agent`. Router defaults to omit semantics: Omit forwards nothing, and the dispatched child applies its own default (`inline`, task 0687 — native-subagent-first with host fallback). Explicit `--agent inline` is forwarded as-is and resolves identically; escalation triggers take precedence over `inline`. |
 | `--full` | When the primary route is `dev-run … --next`, substitute `dev-run <wbs> --mode full` (no `--next`). No effect on non-run routes → warning **W-FULL**. |
 
 ## Protocol (deterministic)
@@ -126,7 +126,7 @@ but redundant. See the glossary entry for the disambiguation in full.
 **[references/messages.md](references/messages.md)** (exact templates, prefixed `dev-next:`). The router fires them by id:
 
 | Id | Fires when | Kind |
-|----|-----------|------|
+| ---- | ----------- | ------ |
 | U1 | no target | stop — usage |
 | U2 | target unresolvable | stop |
 | U3 | no route (table miss / cancelled) | stop |
@@ -147,7 +147,7 @@ bypass lifecycle guards (`--no-lifecycle`) to force progress.
 ## Common Rationalizations
 
 | Rationalization | Reality |
-|---|---|
+| --- | --- |
 | "Two candidates are both fine — pick the higher-priority one." | Multi-candidate is a HITL stop (routing-table §4). A silent pick hides a real fork from the operator; print the decision-brief. |
 | "The task is todo, so run the full pipeline to be safe." | Full mode is not the v1 default (non-route). A3 dispatches the `--next` chain link; `--full` exists for the explicit override. |
 | "I can loop dev-next until the task is done." | Step budget is one dispatch per invocation. Self-looping makes token cost unbounded; the operator re-invokes after non-chain dispatches. |

package/plugins/sp/skills/pr-reviewing/SKILL.md

@@ -86,11 +86,10 @@ Parse the first positional argument as the mode; default `full`.
 - `--agent <inline|auto|name>` — names **who performs model-bearing work**, per the
   [inline-default execution-surface contract](../spur-dev/references/cross-cutting.md#inline-default-execution-surface).
   Omit: the current agent is the default owner (eligible model stages may use one native subagent
-  under the shared contract). `inline` keeps all model work in the host session as the hard
-  zero-dispatch guarantee. `auto` resolves the command's declared role; a named executor pins that executor.
+  under the shared contract). `inline` (also what omission resolves to, task 0687) keeps model work in the host session — native-subagent-first with host fallback where eligible `auto` resolves the command's declared role; a named executor pins that executor.
   An alternate executor gets one `spur agent run --agent <value>` dispatch with the selector removed
   from child args; that child owns model work. Current-agent selection stays inline.
-  Headless surfaces reject explicit `inline` with the shared stable error.
+  Headless surfaces substitute tier resolution for `inline` with a warning (task 0687), never refusing.
 - `--agent` describes the model owner only; it is independent of the deterministic git/GitHub spine
   and the workflow/direct route. Run the selected route in that resolved skill context. A separate
   workflow subprocess belongs to the caller's execution surface or an objective trigger (for example,

package/plugins/sp/skills/redesign-web-ui/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: redesign-web-ui
+description: "Upgrade an existing website or app UI past generic AI defaults without rewriting the stack. Triggers: \"redesign this UI\", \"make it look premium\", \"generic AI design\", \"polish this page\", \"restyle the web app\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - pipeline
+    - reviewer
+  pipeline_steps:
+    - scan
+    - diagnose
+    - plan
+    - apply
+    - verify
+  operations:
+    - redesign
+  openclaw:
+    emoji: "🎨"
+see_also:
+  - sp:code-implementation
+  - sp:code-review
+  - sp:source-driven-development
+---
+
+# redesign-web-ui — existing-UI visual upgrade
+
+This is a **technique** skill: it edits presentation. Specific product copy stays; placeholder copy
+becomes real draft text. Information architecture, routing, and data behavior stay unless the
+operator widens the scope.
+
+## When to use
+
+- Redesign or restyle an existing page, app shell, or component set.
+- Make an existing UI look premium / high-end rather than templated.
+- Strip generic AI design fingerprints (Inter-only type, purple-blue gradients, three equal feature cards).
+- Polish a page that feels unfinished (missing hover, focus, loading, empty, or error states).
+- Restyle a web app in place without a framework migration.
+
+## When not to use
+
+- **Greenfield visual identity with no existing UI** — there is nothing to upgrade; design from the brief.
+- **IA or navigation restructure** — out of scope unless the operator asks.
+- **Stack migration** — swapping CSS frameworks or component libraries.
+- **Non-UI work** — APIs, CLI, schemas, backend.
+- **Inventing legal or compliance surfaces** — privacy pages, terms, cookie banners. Link only
+  destinations the product already has.
+
+## Authority (read before changing tokens)
+
+Resolve visual authority in this order. A lower layer never overrides a higher one. Cite the source
+on every token change.
+
+1. **Repository-root `DESIGN.md`** — if it exists, it is the UI SSOT (palette, type, surfaces, motion,
+   density). Read it. Use its tokens by name.
+2. **Existing theme / CSS variables / Tailwind theme** — the live token file the app already compiles.
+3. **This skill's audit heuristics** — only for axes the two layers above leave free.
+
+`docs/04_DESIGN.md` owns non-UI surfaces (commands, flags, DTOs). It is not this skill's authority.
+
+Framework and CSS API facts (Tailwind v3 vs v4, styled-components APIs, browser features): verify
+with source for the pinned version via `sp:source-driven-development`. Cross-check against docs
+before changing config.
+
+## Pipeline
+
+Run in order. Later steps consume the previous step's artifact. Stop after Diagnose when the
+operator asked only for an audit.
+
+### Step 1 — Scan
+
+Read the target UI and its styling entrypoints. Record, with evidence:
+
+| Field | Evidence |
+|---|---|
+| Framework | manifest / entry file |
+| Styling system | Tailwind v3/v4, CSS modules, vanilla, styled-components, … |
+| Token source | `DESIGN.md`, CSS variables, `tailwind.config`, theme file |
+| Scope | routes, layouts, and shared components that will render the change |
+
+Done when every row has a path (or `none — proceed on heuristics`).
+
+### Step 2 — Diagnose
+
+Walk [references/audit-checklist.md](references/audit-checklist.md). Emit a findings table. Every
+row must cite `path:line`. No finding, no change. Cite the reference row you matched.
+
+```markdown
+| ID | Pattern | Severity | Evidence | In-stack fix |
+|----|---------|----------|----------|--------------|
+| F1  | …       | a11y \| fingerprint \| polish | `file:line` | … |
+```
+
+Severity:
+
+- **a11y** — focus, skip-link, alt, contrast, reduced-motion, keyboard path. Visible focus is required. Fix these.
+- **fingerprint** — generic AI look that fights this product. Fix unless a higher authority specifies it.
+- **polish** — optional quality. Apply when it does not fight the authority or the product type.
+
+Done when every checklist category has been considered and every hit is a table row (or the
+category is marked `none`).
+
+### Step 3 — Plan
+
+Order the findings by the Fix Priority below. State the typefaces, palette, and one signature
+choice, each cited to authority or to a subject-specific reason. Optional motion and layout
+upgrades live in [references/upgrade-techniques.md](references/upgrade-techniques.md) — load that
+file only when a finding needs a technique from it.
+
+The plan should list every **a11y** and **fingerprint** finding. Always cite the token source.
+Done when both are present.
+
+### Step 4 — Apply
+
+Work in the existing styling system. Targeted upgrades, not a rewrite.
+
+Fix Priority:
+
+1. Accessibility
+2. Token alignment to authority
+3. Typography and color fingerprints
+4. Hover, focus, active, loading, empty, error
+5. Layout, spacing, max-width
+6. Generic component cliches
+7. Motion that serves the product (and honors `prefers-reduced-motion`)
+
+Before any new import, read the project's dependency manifest. Before editing Tailwind config,
+validate the installed major version against its docs.
+
+Done when every planned **a11y** and **fingerprint** row is reflected in the diff, or explicitly
+deferred with a one-line reason.
+
+### Step 5 — Verify
+
+Confirm with evidence, not assertion. See **Verification** below.
+
+## Hard constraints
+
+- Keep the current framework and styling library.
+- Preserve existing functionality; a visual change that breaks a flow is a failed run.
+- Keep the diff reviewable — small, targeted edits over a greenfield restyle.
+- Prefer the project's existing icon set, font loader, and image pipeline over new dependencies.
+- Honor `prefers-reduced-motion` for every motion addition.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll migrate to a nicer component library while I'm here." | Stack change is out of scope. Upgrade what is already compiled. |
+| "DESIGN.md is just a mood board — I'll pick better colors." | Root `DESIGN.md` is authority. Cite its tokens; do not invent a parallel palette. |
+| "A full rewrite is faster than patching these class names." | Rewrites drop states, a11y, and behavior. Patch in place; the audit is the map. |
+| "I'll add stock photos / a new icon library for polish." | New assets and libraries are fingerprints of their own. Use the project's pipeline. |
+| "Legal links and a cookie banner will make it feel finished." | Invented compliance UI is worse than omission. Link only destinations the product already has. |
+| "A screenshot of the happy path is enough." | Verify behavior, shared routes, empty/error/focus, and both viewports when layout changed. |
+
+## Red Flags
+
+- Diff introduces a second CSS framework or a new icon/font package without a dependency-file check.
+- Palette or typeface that contradicts repository-root `DESIGN.md`.
+- Finding with no `path:line` evidence.
+- Custom scroll hijacking or inertia scroll on a product UI.
+- Claimed "done" with no visual verification evidence (or no statement of what could not be verified).
+- Placeholder copy (`Lorem ipsum`, "John Doe", "Acme Corp") left in the shipped UI.
+
+## Verification
+
+After Apply, ensure each box has evidence (command output, screenshot, or `file:line`), not assertion:
+
+- [ ] Every **a11y** and **fingerprint** finding is fixed or deferred with a reason.
+- [ ] Token changes cite `DESIGN.md`, the live theme file, or a subject-specific reason (source named).
+- [ ] Existing tests still pass; new imports exist in the dependency manifest.
+- [ ] Shared layouts/components that consume the changed tokens still render consistently — cross-check each route that shares them.
+- [ ] Browser (or closest substitute): golden path + empty/error/focus; desktop and mobile viewports when layout or spacing changed.
+- [ ] `prefers-reduced-motion` still disables added motion.
+- [ ] Document what could not be verified (no browser tools → say so; do not claim visual QA).
+
+## See also
+
+- **`sp:source-driven-development`** — verify framework/CSS API facts against the pinned version before editing config.
+- **`sp:code-implementation`** — owns feature implementation; this skill owns the visual upgrade pass.
+- **`sp:code-review`** — review the visual diff for regressions and out-of-scope stack changes.

package/plugins/sp/skills/redesign-web-ui/references/audit-checklist.md

@@ -0,0 +1,121 @@
+# Audit checklist
+
+Lookup for `sp:redesign-web-ui` Diagnose. Every hit becomes a findings-table row with `path:line`
+evidence and an in-stack fix. Severity values (`a11y` / `fingerprint` / `polish`) and when to
+apply each are defined in the skill's Diagnose step.
+
+A category with no hits is recorded as `none`. Do not invent findings to fill the table.
+
+---
+
+## Typography
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Browser default, Inter, Roboto, or Arial as the only face | Pick a display + body pair for *this* product's subject and cite why. Repeating Inter, or swapping Inter for Geist/Outfit/Satoshi with no subject reason, is still a default. | fingerprint |
+| Headlines lack presence | Increase display size, tighten letter-spacing, reduce line-height so titles feel intentional. | fingerprint |
+| Body line length unconstrained | Cap paragraph measure near 65 characters; raise line-height for reading blocks. | polish |
+| Only 400 and 700 weights | Add 500/600 where hierarchy needs a middle step. | polish |
+| Proportional figures in tables, prices, metrics | Tabular nums (`font-variant-numeric: tabular-nums`) or a monospace face for data. | polish |
+| No tracking on display vs. labels | Negative tracking on large headers; slight positive tracking on small labels/small-caps. | polish |
+| All-caps subheaders as the only accent | Sentence case, small-caps, or italic — one treatment, used sparingly. | fingerprint |
+| Orphaned last words in headings | `text-wrap: balance` (headings) or `text-wrap: pretty` (body). | polish |
+
+## Color and surfaces
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Pure `#000` canvas or pure `#fff` only | Off-black / off-white or a tinted dark from the authority palette. | fingerprint |
+| Oversaturated accents | Keep saturation in range with surrounding neutrals; one chromatic accent unless authority specifies more. | fingerprint |
+| Mixing warm and cool gray families | One gray family, tinted with a consistent hue. | fingerprint |
+| Purple/blue "AI gradient" (or cream+serif+terracotta, or acid-green-on-black used as a default) | Neutral bases + the authority accent. Those three looks are legitimate for some briefs; they are fingerprints when chosen without a subject reason. | fingerprint |
+| Generic black `box-shadow` | Tint shadows to the surface hue. | polish |
+| Perfectly even 45° linear fades | Radial, mesh, or a noise overlay — or no gradient. | fingerprint |
+| Conflicting light sources across shadows | One implied light direction. | polish |
+| A single inverted-color band in an otherwise consistent page | Same palette, shifted shade — or a full committed dark/light mode. | fingerprint |
+| Empty flat sections that need presence | Texture, a restrained ambient gradient, or an existing product image. Use the project's image pipeline; do not inject random stock URLs. | polish |
+
+## Layout
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Everything centered and symmetrical | Offset, mixed aspect ratios, or left-aligned headers over centered content — when the content supports it. | fingerprint |
+| Three equal card columns as the feature row | Asymmetric grid, 2-column zig-zag, or a single highlighted module. | fingerprint |
+| `height: 100vh` full-screen sections | `min-height: 100dvh` (mobile browser chrome). | a11y |
+| No max-width on reading/marketing content | Container ~1200–1440px with auto margins. Data-dense dashboards may stay full-bleed. | polish |
+| Uniform radius on every element | Tighter radius on inner controls, softer on outer containers — or sharp, if authority is sharp. | polish |
+| Missing whitespace on marketing pages | Increase spacing until groups read as groups. Dense is correct for data tables. | polish |
+| Card CTAs / feature lists at uneven baselines | Align shared elements (title, price, list start, button) across the row. | polish |
+| Optical vs. mathematical centering (icon-in-circle, play button) | 1–2px optical adjustment. | polish |
+
+Do **not** treat "dashboard has a left sidebar" as a defect. Changing IA is out of scope.
+
+## Interactivity and states
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| No hover on pointer-capable buttons/links | Background, border, or 1px translate — 150–250ms. | fingerprint |
+| No active/pressed feedback | `scale(0.98)` or `translateY(1px)`. | polish |
+| Instant transitions (`transition: none` on chrome) | 150–250ms on interactive chrome; leave data-dense tables snappy. | polish |
+| Missing visible focus ring | Visible `:focus-visible` using the authority accent. Keyboard path is required. | a11y |
+| Spinner-only loading | Skeleton that matches the layout shape. | polish |
+| Blank empty states | A composed getting-started / zero-data view with one next action. | polish |
+| Errors via `window.alert()` or no inline message | Inline field/form error in the product voice. | a11y |
+| Buttons that go to `#` | Real href, or a disabled control with a reason. | a11y |
+| No current-page indication in nav | Distinct active style. | a11y |
+| Instant anchor jumps | `scroll-behavior: smooth` on the document, with reduced-motion fallback to instant. | polish |
+| Animating `top` / `left` / `width` / `height` | Animate `transform` and `opacity`. | polish |
+
+## Content
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| `Lorem ipsum` or `placeholder` copy | Real draft copy for this product. | fingerprint |
+| "John Doe", "Jane Smith", "Acme Corp", "Nexus", "SmartFlow" | Contextual names. | fingerprint |
+| Fake round metrics (`99.99%`, `$100.00`) | Organic figures, or label them as examples. | fingerprint |
+| AI cliches: Elevate, Seamless, Unleash, Next-Gen, Game-changer, Delve, Tapestry, "In the world of…" | Plain, specific language. | fingerprint |
+| "Oops!" / exclamation-mark success toasts | Direct: "Saved." / "Connection failed. Try again." | fingerprint |
+| Title Case On Every Header | Sentence case, unless the brand guide says otherwise. | polish |
+| Identical dates or avatars on every dummy person | Unique assets per distinct person, or drop the avatars. | fingerprint |
+
+## Component patterns
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Card = border + shadow + white fill on every block | Cards only when elevation encodes hierarchy; otherwise background or spacing. | fingerprint |
+| Always one filled + one ghost button | Text/tertiary action when the second action is low emphasis. | polish |
+| Pill "New"/"Beta" badges as decoration | Square badge, flag, or plain label — or remove. | polish |
+| Accordion FAQ / 3-card testimonial carousel / 3-tower pricing as empty decoration | A layout that matches the actual content. Keep the pattern when it *is* the product's IA. | fingerprint |
+| Modal for a single-field edit | Inline edit or a slide-over. | polish |
+| Footer link farm (4+ columns of unused links) | Primary paths + real legal destinations the product already has. | polish |
+
+## Iconography and media
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Mixed icon sets / mixed stroke widths | Standardize on the set already in the dependency manifest. Do not add Phosphor/Heroicons/Lucide as a second library. | fingerprint |
+| Rocket = Launch, shield = Security, as the only metaphors | Less obvious icons from the *same* set, or text. | polish |
+| Missing favicon | Branded favicon in the project's existing public/asset pipeline. | polish |
+| Random stock "team" photos | Real assets, a consistent illustration style, or no people photos. | fingerprint |
+
+## Code quality (UI)
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Non-semantic soup for nav/main/content | `<nav>`, `<main>`, `<article>`, `<aside>`, `<section>` where they match the role. | a11y |
+| Inline styles mixed into a class-based system | Move the declaration into the project's styling system. | polish |
+| Hardcoded px widths on fluid layouts | `%`, `rem`, `em`, `max-width`, or the system's spacing scale. | polish |
+| Meaningful images with empty or `alt="image"` | Describe the image; decorative images get `alt=""` plus `role="presentation"` if needed. | a11y |
+| `z-index: 9999` and friends | A documented z-scale on the theme. | polish |
+| Missing `<title>`, description, or social meta | Fill from the product name and the page's job. | polish |
+| Import not in the dependency manifest | Use an already-installed package, or stop and ask before adding one. | fingerprint |
+
+## Completeness (product UI, not decoration)
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| No skip-to-content link | Visually hidden skip link targeting `<main>`. | a11y |
+| Dead-end views with no way back | A back/close path that uses the existing router. | a11y |
+| No custom 404 | Branded empty-route view with a path home. | polish |
+| Forms without client-side required/format checks | Validate in the existing form library; keep server-side as source of truth. | a11y |
+| Footer legal links that 404 | Point at real routes, or omit. | polish |