@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/ui-stack-extension.md

@@ -1,237 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# UI Stack Extension — adding a new frontend stack to the UI track
-
-> **Audience:** maintainers adding a new stack (Svelte, SolidJS, Astro,
-> Qwik, …) to the UI directive set. Consumers of the package never run
-> this; they get the stacks shipped here.
-> **Source of truth:** [`ui-track-flow.md`](ui-track-flow.md) for the
-> contract; [`adr-product-ui-track.md`](adr-product-ui-track.md) for
-> the rationale.
-> **Status:** recipe only — R3 ships four stacks
-> (`blade-livewire-flux`, `react-shadcn`, `vue`, `plain`); no
-> additional stacks are scheduled. Add one only when a real consumer
-> project asks for it.
-
-## What "adding a stack" actually means
-
-Three artefacts plus a Golden fixture. The engine's directive set is
-fixed; only the dispatch tables and the implementation skill bundles
-change.
-
-| Artefact | File | Change |
-|---|---|---|
-| Stack label | [`scripts/work_engine/stack/detect.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/stack/detect.py) | New entry in `KNOWN_STACKS` + a heuristic in `detect_stack` |
-| Apply skill | `.agent-src.uncondensed/skills/ui-apply-<stack>/SKILL.md` | New skill bundle |
-| Review skill | `.agent-src.uncondensed/skills/ui-design-review-<stack>/SKILL.md` | New skill bundle |
-| Polish skill | `.agent-src.uncondensed/skills/ui-polish-<stack>/SKILL.md` | New skill bundle |
-| Dispatch tables | `directives/ui/{apply,review,polish}.py` | New row in each `STACK_DIRECTIVES` map |
-| Golden fixture | `tests/golden/sandbox/recipes/gt_u<NN>_<stack>_*.py` | One happy-path baseline at minimum |
-
-Skill names are not free — they are read by the dispatcher as
-`ui-apply-<stack>`, `ui-design-review-<stack>`, `ui-polish-<stack>`.
-A typo is silently handled by the `DEFAULT_DIRECTIVE` fallback
-(`ui-apply-plain` / `ui-design-review-plain` / `ui-polish-plain`),
-which is recoverable but probably not what the maintainer intended.
-
-## Step 1 — pick the label
-
-Convention: lowercase, hyphenated, framework-only (no version pin).
-
-| Good | Bad | Why |
-|---|---|---|
-| `svelte` | `svelte5` | Major-version drift handled by the audit's version-anchor warning, not by splitting the stack. |
-| `solid` | `solid-js` | Match the package name developers say out loud. |
-| `astro` | `astro-content` | Sub-modes (Astro components vs MDX) live inside the apply skill, not in the label. |
-
-Add the label to `KNOWN_STACKS` (the frozenset is exported and used by
-state validation; missing it makes detection silent-fail back to
-`plain`).
-
-## Step 2 — heuristic in `detect_stack`
-
-The detector reads `composer.json` and `package.json` once and applies
-heuristics in **priority order** — first match wins. The order matters:
-a Laravel + React project must hit `blade-livewire-flux` only when
-Livewire and Flux are present, otherwise `react-shadcn`.
-
-Insert the new heuristic **before** the `plain` fallback and **after**
-any stack that could legitimately co-exist with yours. For Svelte:
-
-```python
-def _has_svelte(package: dict[str, object]) -> bool:
-    deps = _all_dependencies(
-        package,
-        "dependencies",
-        "devDependencies",
-        "peerDependencies",
-        "optionalDependencies",
-    )
-    return "svelte" in deps
-```
-
-```python
-# inside detect_stack(), before the `plain` fallback
-if _has_svelte(package):
-    return StackResult(frontend="svelte", mtime=mtime)
-```
-
-**Failure mode to watch.** A heuristic that overlaps with an existing
-stack (Astro lists `react` as a peer dep when used with React adapters)
-must be ordered carefully. Test against real fixtures, not hand-edited
-JSON.
-
-## Step 3 — three skills, one shape
-
-Each skill is a SKILL.md bundle with frontmatter and prose. The
-contract for each:
-
-### `ui-apply-<stack>`
-
-Reads `state.ui_design.brief` and `state.ui_audit.components_found`.
-Writes a populated `state.ticket["ui_apply"]` envelope:
-
-```yaml
-ui_apply:
-  files: ["resources/components/UserCard.svelte"]
-  rendered:                 # full text per file, microcopy-locked
-    "resources/components/UserCard.svelte": |
-      <script>...</script>
-      ...
-  components_added: ["UserCard"]
-  components_reused: ["Button", "Card"]   # from audit
-  microcopy_lock: true      # affirms strings come from brief verbatim
-```
-
-**Hard rule:** strings in `rendered` must not contain
-`PLACEHOLDER_PATTERNS` (`<placeholder>`, `lorem`, `todo:`, `tbd`,
-`xxx`). The dispatcher rejects on producer side; the skill must reject
-on consumer side too.
-
-### `ui-design-review-<stack>`
-
-Reads `state.ui_apply` + `state.ui_design.brief`. Writes
-`state.ui_review` with `findings: list` and `review_clean: bool`.
-Findings are tagged `kind` ∈ `{token_violation, microcopy_drift,
-a11y_gap, layout_break, prop_misuse, …}` — extend the kind set
-sparingly. Token violations carry `category` and `value` so polish
-can route them through token extraction.
-
-### `ui-polish-<stack>`
-
-Reads `state.ui_review.findings` + `state.ui_audit.design_tokens`.
-Writes a fix envelope and increments `state.ui_polish.rounds`. Hard
-ceiling at `POLISH_CEILING = 2` is enforced by the dispatcher;
-the skill does **not** check the ceiling itself but must respect
-`token_repeat_threshold = 2` for unmatched-token extraction.
-
-## Step 4 — wire dispatch tables
-
-Three identical edits in
-[`directives/ui/apply.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/apply.py),
-[`directives/ui/review.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/review.py),
-and [`directives/ui/polish.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/polish.py):
-
-```python
-STACK_DIRECTIVES: dict[str, str] = {
-    "blade-livewire-flux": "ui-apply-blade-livewire-flux",
-    "react-shadcn": "ui-apply-react-shadcn",
-    "vue": "ui-apply-vue",
-    "plain": "ui-apply-plain",
-    "svelte": "ui-apply-svelte",          # ← new row
-}
-```
-
-Same shape in `review.py` (`ui-design-review-svelte`) and `polish.py`
-(`ui-polish-svelte`). The dispatcher does not validate that the skill
-actually exists — it emits the `@agent-directive` and trusts the agent
-loader. A typo or missing skill manifests as a halt loop the maintainer
-notices on first replay.
-
-## Step 5 — version anchor in skill frontmatter
-
-Every stack-specific skill declares the upstream library version it
-was tested against, in frontmatter:
-
-```yaml
-tested_against:
-  svelte: "5.x"
-  svelte_kit: "2.x"      # if applicable
-```
-
-The audit step reads installed versions from `package.json` and
-compares against the anchor. A mismatch warns but does not block;
-the user picks whether to proceed or pin. Forgetting the anchor
-fails CI (`task lint-skills` enforces presence on `ui-apply-*`,
-`ui-design-review-*`, `ui-polish-*`).
-
-## Step 6 — Golden fixture
-
-Add at least one happy-path Golden that exercises the full UI flow
-on the new stack. Recipe lives at
-`tests/golden/sandbox/recipes/gt_u<NN>_<stack>_happy.py` and follows
-the pattern of `gt_u11_high_confidence.py`:
-
-1. Seed state with a clear `ui-build` prompt and an audit that finds
-   exactly one strong match (so `audit_path = "high_confidence"`).
-2. Pin the halt budget — high-confidence happy path is **1 halt**
-   (design-brief sign-off only).
-3. Capture under `tests/golden/baseline/GT-U<NN>/` via `task golden-capture`.
-4. The replay harness (`tests/golden/test_replay.py`) auto-discovers
-   the new baseline; no Taskfile change needed.
-
-For a complete pair, also add an `ambiguous` fixture — `2 halts max`,
-matching `gt_u12_ambiguous.py`'s shape. Skip the greenfield branch
-unless the stack has a meaningful difference there.
-
-See [`tests/golden/CAPTURING.md`](../../tests/golden/CAPTURING.md)
-for capture mechanics.
-
-## Step 7 — verify end-to-end
-
-```bash
-task sync                  # propagate detect.py + skill changes
-task generate-tools        # refresh .claude/, .cursor/, etc.
-task lint-skills           # checks frontmatter + version anchor
-task golden-replay         # runs all R1+R2+R3 baselines
-task ci                    # full pipeline
-```
-
-If `golden-replay` regresses on a non-`<stack>` baseline, your
-detector heuristic is over-matching — re-order the priority chain.
-
-## What you do **not** add
-
-- **A new directive set.** UI / UI-trivial / mixed are exhaustive for
-  R3. A stack-specific directive set means you've reached for a hammer
-  the engine doesn't have.
-- **A new entrypoint command.** `/work` and `/implement-ticket` route
-  through `directive_set` and `state.stack.frontend`; a `/build-svelte`
-  command would create a UX divergence the engine's intent classifier
-  is supposed to prevent.
-- **`fe-design` content.** That skill is the framework-agnostic
-  reference; new stack-specific heuristics live in the apply skill,
-  not in `fe-design`.
-- **Visual review.** Roadmap 4's headless-browser pipeline is the
-  destination for screenshot capture and a11y tooling. Stack
-  extensions don't need to wait on it.
-
-## When NOT to add a stack
-
-Defer the work and stay on `plain` if any apply:
-
-- Only one consumer project asks; the cost of maintaining the apply
-  skill exceeds the value.
-- The framework's idiom is close enough to an existing stack that
-  the existing apply skill produces acceptable output (Preact ≈
-  `react-shadcn` for most components).
-- The framework is in beta or pre-1.0 — the version anchor will drift
-  faster than you can re-capture goldens.
-
-The audit gate is the safety net: even on `plain`, the audit finds
-existing components and the design step uses them. The cost of
-**not** adding a stack is generally lower than the cost of adding
-one prematurely.

package/docs/contracts/ui-track-flow.md

@@ -1,329 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# UI Track — Flow Contract
-
-> Technical contracts for the UI directive sets.
-> Sibling of [`implement-ticket-flow.md`](implement-ticket-flow.md) — that
-> doc covers `backend`; this one covers `ui`, `ui-trivial`, and the
-> `mixed` set that stitches both.
->
-> - **Created:** 2026-05-01
-> - **Status:** Phase 1–6 shipped — audit / design / apply / review /
->   polish handlers live under
->   [`.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/).
->   Mixed under `directives/mixed/`. `ui-trivial` under
->   `directives/ui_trivial/`. R4 (Visual Review Loop) added the
->   a11y gate, the preview envelope, and a polish-termination rewrite
->   that splits subjective ceilings from objective a11y blocks.
->   Golden Transcripts GT-U1..U4, U7, U8, U9..U12 plus GT-U5 (mixed
->   flow), GT-U6A/B (stack dispatch), and R4's GT-U13..U15 (a11y polish,
->   a11y ceiling, preview render failure) pin happy-path, ambiguity,
->   mixed orchestration, stack dispatch, trivial happy path, and the
->   visual-review gates.
-> - **Runtime:** Python 3.10+. Same `DeliveryState` envelope, same
->   eight-slot dispatcher as the backend track — only the slot handlers
->   differ.
-
-## What this doc is
-
-The **shape** of the four UI-related directive sets: which slot runs
-which handler, what each handler reads / writes on `DeliveryState`, the
-hard thresholds (similarity, polish ceiling, trivial limits), and the
-sentinels that release each gate.
-
-## What this doc is *not*
-
-- A skill spec — `existing-ui-audit`, `ui-design-brief`, the stack
-  apply / review / polish skills are documented in their own
-  `SKILL.md` files.
-- A migration guide for the schema — see
-  [`implement-ticket-flow.md`](implement-ticket-flow.md#state-schema-v1).
-
-## The four directive sets
-
-| Set | When picked | Slot 1–8 |
-|---|---|---|
-| `backend` | Default — no UI keywords, no UI envelope | `refine → memory → analyze → plan → implement → test → verify → report` (see sibling doc) |
-| `ui` | UI keywords, `improve` envelope, or refine routing to UI | `audit → ⊘ → design → ⊘ → apply → review → polish → report` |
-| `ui-trivial` | Phase-1 classifier hits "single-line tweak" pattern | `refine → ⊘ → ⊘ → ⊘ → apply → test → ⊘ → report` |
-| `mixed` | Backend + UI in one input | `refine → memory → analyze → contract → ui → stitch → verify → report` |
-
-`⊘` = `_passthrough.run` (or `_skipped.run` in `ui-trivial`). The slot
-exists so the dispatcher's completeness check is satisfied; no logic
-runs and no state is touched.
-
-Source of truth for slot wiring:
-[`directives/ui/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/__init__.py),
-[`directives/mixed/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/mixed/__init__.py),
-[`directives/ui_trivial/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui_trivial/__init__.py).
-
-## The `ui` set — slot-by-slot
-
-### `refine` → audit
-
-Mandatory pre-step. Routes on `state.ui_audit` shape:
-
-| State | Outcome | Handler |
-|---|---|---|
-| `None` / empty / non-dict | `BLOCKED` + `@agent-directive: existing-ui-audit` | First-pass delegation |
-| `greenfield=True`, no `greenfield_decision` | `BLOCKED` numbered options | User picks `scaffold` / `bare` / `external_reference` |
-| `shadcn_inventory.version` major ≠ `TESTED_AGAINST_SHADCN_MAJOR` (`2`) and no `version_mismatch_decision` | `BLOCKED` soft halt | "Cautious composition / abort" |
-| Confidence `high` + ≥1 match with similarity ≥ `STRONG_SIMILARITY` (`0.7`) and no runner-up within `TIE_GAP` (`0.05`) | `SUCCESS`, `audit_path = "high_confidence"` | Design folds findings into brief |
-| Anything else populated | `BLOCKED` numbered options | User picks candidate to extend (or "build new"); records `audit_path = "ambiguous"` + `candidate_pick` |
-
-Constants live in
-[`directives/ui/audit.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/audit.py):
-`STRONG_SIMILARITY = 0.7`, `TIE_GAP = 0.05`,
-`TESTED_AGAINST_SHADCN_MAJOR = 2`. Idempotent re-entry: once
-`audit_path` is set the step round-trips through `SUCCESS` without
-re-emitting.
-
-### `analyze` → design
-
-Produces the **locked design brief**. `apply` consumes microcopy
-verbatim — that's the lock.
-
-Required brief keys (`REQUIRED_BRIEF_KEYS`): `layout`, `components`,
-`states`, `microcopy`, `a11y`. Required state coverage
-(`REQUIRED_STATE_KEYS`): `empty`, `loading`, `error`, `success`,
-`disabled`.
-
-Microcopy is rejected when any string matches `PLACEHOLDER_PATTERNS`:
-`<placeholder>`, `lorem`, `todo:`, `tbd`, `xxx` (case-insensitive
-substring). The same tuple is re-imported by `apply` so the rejection
-fires at the producer first, at the consumer as defense-in-depth.
-
-Sentinel: `state.ui_design.design_confirmed`. Without it the brief
-halt fires every pass; with it the step round-trips through `SUCCESS`.
-
-### `implement` → apply
-
-Stack-dispatched. Routes on `state.stack.frontend`:
-
-| `state.stack.frontend` | Directive | Skill bundle |
-|---|---|---|
-| `blade-livewire-flux` | `ui-apply-blade-livewire-flux` | `flux` + `livewire` + `blade-ui` |
-| `react-shadcn` | `ui-apply-react-shadcn` | `react-shadcn-ui` |
-| `vue` | `ui-apply-vue` | `ui-apply-vue` |
-| `plain` (or unknown — `DEFAULT_DIRECTIVE`) | `ui-apply-plain` | `blade-ui` + Tailwind base |
-
-Apply does **not** re-validate the brief — it validates *output* against
-`PLACEHOLDER_PATTERNS`. A hallucinated `<placeholder>` string in the
-rendered envelope triggers
-`apply_placeholders_in_output` and forces re-render with the locked
-microcopy. Once `state.ticket["ui_apply"]` is well-formed, apply records
-changes and returns `SUCCESS`.
-
-### `test` → review
-
-Stack-dispatched design-review pass. Same dispatch table shape as
-apply, prefix `ui-design-review-`. Writes
-`state.ui_review.findings` (list) + `state.ui_review.review_clean`
-(bool). The step does **not** enforce
-`review_clean == (len(findings) == 0)` — that would block the
-legitimate "ship as-is with open findings" replay path. Honesty of the
-flag is the producer's contract; review only validates shape.
-
-**R4 — a11y gate** (after the basic clean/findings gates pass).
-`_apply_a11y_gate` reads `state.ui_review.a11y.violations`, filters
-out entries already in `state.ui_audit.a11y_baseline` (pre-existing
-violations stay informational, never block), drops anything below
-`severity_floor` (default `moderate`; unknown severities default to
-`moderate` so a malformed envelope cannot weaken the gate), and
-filters entries listed in `state.ui_review.a11y.accepted_violations`
-(idempotent re-entry after the polish-ceiling Accept choice).
-Surviving violations are synthesised as
-`{kind: "a11y_violation", rule, selector, severity}` findings (deduped
-by `(rule, selector)`) and `review_clean` is forced to `False`
-engine-side. Opt-in: when `state.ui_audit.a11y_baseline` exists but
-`state.ui_review.a11y` is missing, the step halts with
-`review_a11y_pending` so the skill writes the envelope on the next
-pass; pre-R4 envelopes without a baseline bypass the gate entirely.
-
-**R4 — preview envelope** (the engine never renders).
-`_apply_preview_gate` reads `state.ui_review.preview`. Shape:
-`render_ok: bool`, optional `screenshot_path`, `dom_dump_path`,
-`error`, `skipped`. `render_ok: False` halts with
-`preview_render_failed` so the user picks retry / skip / abort; Skip
-flips `state.ui_review.preview.skipped = true` and the gate becomes a
-no-op on re-entry. `render_ok: True` with `screenshot_path` set
-threads the path into the delivery report's `artifacts` list. The
-gate is independent of the a11y gate; both can fire on the same pass.
-
-### `verify` → polish
-
-Bounded fix loop. Base ceiling: `POLISH_CEILING = 2` rounds. R4
-splits termination into **subjective** and **objective** branches:
-the subjective `polish_ceiling_reached` halt only fires when the
-remaining findings are non-a11y; objective a11y violations take the
-explicit `polish_a11y_blocking` branch with its own option set.
-
-| `review_clean` | `rounds` | Remaining findings | Behaviour |
-|---|---|---|---|
-| `True` | any | — | `SUCCESS` — advance to report |
-| `False` | `< effective_ceiling` | any | `BLOCKED` + `@agent-directive: ui-polish-<stack>`; skill applies fixes, re-runs review, increments `rounds` |
-| `False` | `== effective_ceiling` | contains `a11y_violation` | `BLOCKED` numbered options: extend (one extra round, sets `extension_used = True`; option disappears once spent) / accept (appends rule ids to `state.ui_review.a11y.accepted_violations`, then continues) / abort |
-| `False` | `== effective_ceiling` | non-a11y only | `BLOCKED` numbered options: ship as-is / abort / hand off |
-
-`effective_ceiling = POLISH_CEILING + 1` once
-`state.ui_polish.extension_used` is set; the schema validator widens
-the upper bound from `[0, 2]` to `[0, 3]` only when the flag is
-`True`, so the ceiling holds across in-memory state, on-disk state,
-and the dispatcher. `rounds > 3` is rejected unconditionally, even
-with the extension flag.
-
-**Idempotent re-entry on Accept.** A `state.ui_review.a11y.accepted_violations`
-list with rule ids matching the remaining a11y findings round-trips
-through `SUCCESS` because the review gate's `_apply_a11y_gate`
-filters accepted entries before synthesising `a11y_violation`
-findings. The Accept branch and the Ship-as-is branch are therefore
-asymmetric: Ship-as-is flips `review_clean` directly; Accept records
-explicit rule ids so replay reproduces the same gate decision.
-
-**Token-violation extraction.** Findings with
-`kind == "token_violation"` carry `category` and `value`. Polish
-classifies them against `state.ui_audit.design_tokens`:
-
-- Matched value → fix uses the named token; counted as a regular round.
-- Unmatched value repeated `> TOKEN_REPEAT_THRESHOLD` (`2`) times →
-  emits `polish_token_extraction_pending`: extract the value to a new
-  token before the next round runs. One-off unmatched values stay
-  inline.
-
-Stack-directive table mirrors apply / review with prefix
-`ui-polish-`. `DEFAULT_DIRECTIVE = "ui-polish-plain"`.
-
-### `report` → backend renderer
-
-Re-export of
-[`directives.backend.report.run`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/backend/report.py).
-The renderer is pure and state-driven; the same Markdown contract
-serves both tracks.
-
-## Halt budget — happy path
-
-`ui` set, fresh state, audit + design pass cleanly:
-
-1. **Audit pick** — first-pass `existing-ui-audit` directive halt.
-2. **Design sign-off** — `design_confirmed` numbered-options halt.
-
-Two user halts. Apply / review / polish all run silently when their
-producers write clean envelopes on the first attempt. GT-U1..U4 pin
-this budget.
-
-Additional halts surface only on real ambiguity:
-greenfield-undecided (+1), shadcn-version-mismatch (+1), audit-ambiguous
-(+1), placeholder rejection (+N until microcopy is fixed),
-polish round (+1 per dirty review, capped at the effective ceiling),
-polish ceiling — subjective (+1 when both rounds fail and remaining
-findings are non-a11y) **or** a11y-blocking (+1 when remaining
-findings include `a11y_violation` entries; the Extend option grants
-one extra round, then disappears),
-preview render failure (+1 when `state.ui_review.preview.render_ok`
-is `False`; user picks retry / skip / abort),
-review a11y pending (+1 when an `a11y_baseline` exists but the review
-skill has not yet written `state.ui_review.a11y`).
-
-## The `ui-trivial` set — short-circuit path
-
-For provably bounded edits (single class swap, copy tweak, one-prop
-adjustment). Phase-1 intent classifier writes
-`directive_set = "ui-trivial"`.
-
-Hard preconditions in
-[`directives/ui_trivial/apply.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui_trivial/apply.py):
-
-- `MAX_FILES = 1` — exactly one file touched.
-- `MAX_LINES_CHANGED = 5` — diff stays under five changed lines.
-
-Violation flips `state.directive_set` to `ui` (the full audit gate)
-and the dispatcher restarts. The trivial path **never** silently
-swallows scope creep.
-
-Skipped slots (`memory`, `analyze`, `plan`, `verify`) share
-`_skipped.run` — they record `success` without work so the dispatcher
-completeness check is satisfied. `report` renders a one-line summary
-instead of the full delivery report.
-
-## The `mixed` set — contract + UI + stitch
-
-Used when a single input touches both layers. Slot mapping:
-
-| Slot | Handler | Purpose |
-|---|---|---|
-| `refine`, `memory`, `analyze`, `verify`, `report` | reused from `backend` | Same handlers, by reference |
-| `plan` | `mixed.contract` | Lock `data_model` + `api_surface` |
-| `implement` | `mixed.ui` | Delegate to UI sub-flow |
-| `test` | `mixed.stitch` | End-to-end smoke scenarios |
-
-**Sentinels** that release each mixed gate:
-
-- `state.contract.contract_confirmed = True` — UI sub-flow refuses to
-  start without it (defense-in-depth even if `outcomes["plan"] ==
-  "success"`). Required keys: `data_model`, `api_surface`
-  (`REQUIRED_CONTRACT_KEYS`).
-- `state.ui_review.review_clean = True` — mixed `ui` step's success
-  condition. Polish-ceiling semantics live in the UI track; if the
-  user reaches mixed.ui's "ship as-is / hand off / abort" halt, the
-  UI track has already given up.
-- `state.stitch.verdict = "success"` — stitch's success condition.
-  `blocked` / `partial` halts with three numbered options unless
-  `state.stitch.integration_confirmed = True` (explicit user override).
-
-`stitch` emits `@agent-directive: integration-test` so an
-agent-side handler runs the end-to-end smokes; `mixed.ui` emits
-`@agent-directive: ui-track` to delegate the visible-surface work
-back into the full UI directive set.
-
-## Idempotency and replay
-
-Every UI step is idempotent on its sentinel:
-
-| Step | Sentinel | Effect on replay |
-|---|---|---|
-| audit | `audit_path` ∈ `{"high_confidence", "ambiguous", "greenfield"}` | `SUCCESS` without halt |
-| design | `design_confirmed = True` | `SUCCESS` without halt |
-| apply | `state.ticket["ui_apply"]` well-formed, no placeholders | `SUCCESS`, changes recorded once |
-| review | well-formed envelope (`findings` list + `review_clean` bool) | `SUCCESS` |
-| polish | `review_clean = True` (any round count) | `SUCCESS` |
-| contract | `contract_confirmed = True` | `SUCCESS` |
-| stitch | `verdict = "success"` OR `integration_confirmed = True` | `SUCCESS` |
-
-The dispatcher walks the same eight slots on every replay; sentinels
-are the only thing keeping a re-run from re-asking a question the
-user already answered. Replay coverage is locked by the
-Golden-Transcript suite under `tests/golden/baseline/GT-U*/`.
-
-## Declared ambiguity surfaces
-
-Each step re-exports an `AMBIGUITIES: tuple[dict[str, str], ...]`
-constant. The
-[`test_ambiguity_coverage.py`](../../tests/implement_ticket/test_ambiguity_coverage.py)
-suite asserts every `BLOCKED` path has a matching declaration.
-
-| Step | Codes |
-|---|---|
-| `audit` | `audit_missing`, `greenfield_undecided`, `shadcn_version_mismatch`, `audit_ambiguous` |
-| `design` | `design_missing`, `design_placeholders`, `design_unconfirmed` |
-| `apply` | `apply_envelope_missing`, `apply_placeholders_in_output` |
-| `review` | `review_envelope_missing`, `review_findings_missing`, `review_clean_missing`, `review_a11y_pending`, `preview_render_failed` |
-| `polish` | `polish_round_pending`, `polish_ceiling_reached`, `polish_a11y_blocking`, `polish_token_extraction_pending` |
-| `contract` (mixed) | `upstream_analyze_failed`, `contract_missing`, `contract_incomplete`, `contract_unconfirmed` |
-| `mixed.ui` | `contract_sentinel_missing`, `ui_subflow_missing`, `ui_subflow_dirty` |
-| `stitch` | `upstream_ui_failed`, `stitch_missing`, `stitch_malformed`, `stitch_verdict_unsuccessful` |
-
-## See also
-
-- [`implement-ticket-flow.md`](implement-ticket-flow.md) — sibling
-  contract for the `backend` set; covers `DeliveryState`, schema v1,
-  hooks, persona policies, replay protocol.
-- [`adr-product-ui-track.md`](adr-product-ui-track.md) — locked
-  decisions for the UI track (R3) and the visual-review-loop
-  amendment (R4: a11y gate, preview envelope, polish-termination).
-- [`existing-ui-audit` SKILL](../../.agent-src.uncondensed/skills/existing-ui-audit/SKILL.md)
-  — producer of `state.ui_audit`.
-- [`ui-audit-gate` rule](../../.agent-src.uncondensed/rules/ui-audit-gate.md)
-  — the always-on rule that mirrors the audit gate at the agent layer.

package/docs/contracts/universal-skills.md

@@ -1,91 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-13
----
-
-
-# Universal Skills — Allowlist Contract
-
-> **Status:** beta · **Owner:** step-12 Phase 3 · **Stability:** additive only (no removals without a migration note in `STABILITY.md`)
-
-## Purpose
-
-When `agent-config init --interactive` writes a `.agent-config.local.json` with a `user_type` (e.g., `creator`, `founder`, `consultant`), the host agent filters its loaded skill set to that user-type's recommended skills + this allowlist. **Skills on this allowlist are loaded for every user-type regardless of profile.**
-
-The allowlist solves the over-siloing risk identified by the AI Council 2026-05-15 review: a `consultant` user still needs `decision-record` and `risk-officer`; a `creator` still needs `refine-prompt` and `verify-completion-evidence`. These are not domain skills — they are agent-OS primitives.
-
-## The 15
-
-| Skill | Why universal |
-|---|---|
-| [`refine-prompt`](../../dist/agent-src/skills/refine-prompt/SKILL.md) | Every free-form request needs AC + assumption + confidence band before the engine runs. |
-| [`refine-ticket`](../../dist/agent-src/skills/refine-ticket/SKILL.md) | Every ticket (Jira / Linear / GH issue) needs scoped AC before plan. |
-| [`estimate-ticket`](../../dist/agent-src/skills/estimate-ticket/SKILL.md) | Sizing + split + risk — applies to any work item, technical or not. |
-| [`verify-completion-evidence`](../../dist/agent-src/skills/verify-completion-evidence/SKILL.md) | Iron-Law gate: fresh evidence before any "done" claim. Survives every mode. |
-| [`threat-modeling`](../../dist/agent-src/skills/threat-modeling/SKILL.md) | Pre-implementation abuse-case enumeration — same lens applies to a marketing form and a payment endpoint. |
-| [`systematic-debugging`](../../dist/agent-src/skills/systematic-debugging/SKILL.md) | Reproduce → isolate → hypothesize → verify — works on broken pipelines, broken docs, broken funnels. |
-| [`doc-coauthoring`](../../dist/agent-src/skills/doc-coauthoring/SKILL.md) | 3-stage write loop (context → section → reader-test) for any long-form doc. |
-| [`deep-reading-analyst`](../../dist/agent-src/skills/deep-reading-analyst/SKILL.md) | Article / long-form analysis via SCQA + mental models — used by every role that reads. |
-| [`decision-record`](../../dist/agent-src/skills/decision-record/SKILL.md) | Trade-off framing before any commit. ADR-shape works for tech, hiring, and pricing. |
-| [`adr-create`](../../dist/agent-src/skills/adr-create/SKILL.md) | Naming + numbering + index regen — the file mechanics of `decision-record`. |
-| [`risk-officer`](../../dist/agent-src/skills/risk-officer/SKILL.md) | Blast-radius framing + residual-risk verdict before any commit. |
-| [`adversarial-review`](../../dist/agent-src/skills/adversarial-review/SKILL.md) | Devil's advocate stress-test — opt-in but always available. |
-| [`customer-research`](../../dist/agent-src/skills/customer-research/SKILL.md) | Discovery-slice shaping (JTBD, switch-event) — used by founder, GTM, consultant, creator. |
-| [`stakeholder-tradeoff`](../../dist/agent-src/skills/stakeholder-tradeoff/SKILL.md) | Per-lens framing when stakeholders disagree — applies in every org. |
-| [`md-language-check`](../../dist/agent-src/skills/md-language-check/SKILL.md) | Hard gate: `.md` files stay English; the agent translates at runtime. |
-
-## Inclusion criteria
-
-A skill earns the universal label when **all three** hold:
-
-1. **Cross-role payback.** ≥ 4 of the 6 seeded user-types (creator / founder / consultant / GTM / finance-ops / developer) reach for it in week-one workflows. The non-dev eval corpus ([`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml)) is the empirical test.
-2. **No stack assumption.** The skill body does not rely on a specific language, framework, or repo shape. `laravel`, `nextjs-patterns`, `pest-testing` are domain skills, not universal.
-3. **Agent-OS primitive.** The skill encodes a meta-pattern of agent behavior (refine, verify, decide, debug, document, threat-model) rather than a domain deliverable (write a launch email, draft an ADR for the auth module).
-
-## Exclusion criteria
-
-- **Domain anchor.** `voice-and-tone-design` (creator), `runway-cognition` (founder), `quality-tools` (developer), `pipeline-strategy` (GTM) — strong-fit for one user-type, weak for the other five. These tag via the `recommended_for_user_types:` frontmatter field defined in [`skill.schema.json`](../../src/scripts/schemas/skill.schema.json).
-- **Tool-specific.** `laravel-horizon`, `nextjs-patterns`, `mcp-builder`, `terraform` — load only when the matching stack flag is set.
-- **Council / role review.** `judge-bug-hunter`, `judge-security-auditor`, `architecture-review-lens` — load via subagent orchestration, not via universal allowlist.
-
-## How loading works (forward-compatible)
-
-```json
-// .agent-config.local.json — written by `agent-config init --interactive`
-{
-  "user_type": "consultant",
-  "stack": "none",
-  "verbosity": "normal",
-  "enabled_skill_prefixes": ["consulting/*", "writing/*"],
-  "default_persona": "discovery-lead"
-}
-```
-
-The host agent's skill loader is expected to:
-
-1. Resolve `enabled_skill_prefixes` against the per-user-type recommendation list (Phase 5 `recommended_for_user_types:` tags).
-2. Union with this universal allowlist (always, no opt-out).
-3. Surface a `loaded_skills_count` in the agent's debug / status output so the operator can verify filtering ran.
-
-**Runtime filter status:** the prefix-filter pass is gated on the user-types axis shipping the `user-types/` directory and `--user-type` flag. Until then, every skill loads (current v2.x behavior); this contract is the forward declaration of the eventual filter, not its implementation.
-
-## Change procedure
-
-Adding a skill to this allowlist:
-
-1. Open a PR that edits this file + the relevant skill's `recommended_for_user_types:` (omitted = universal).
-2. Cite ≥ 4 user-type prompts from `tests/eval/corpus-non-dev.yaml` that select the skill.
-3. Require approval from one Tier-1 reviewer (architecture-review-lens or skill-writing).
-4. Document the inclusion in `agents/evidence/eval-findings/` with the supporting eval prompts.
-
-Removing a skill is breaking. It must be announced in `STABILITY.md` with a deprecation window ≥ one minor release.
-
-## Versioning
-
-- This contract is **beta**. Once non-dev selection-accuracy ≥ 0.60 sustains across two consecutive `task bench --corpus non-dev` runs, status promotes to **stable** and entries become semver-protected.
-
-## Related
-
-- [`STABILITY.md`](STABILITY.md) — public-identifier stability surface.
-- [`docs/getting-started-by-role.md`](../getting-started-by-role.md) — consumer-facing role docs that reference these skills.
-- [`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml) — empirical test corpus.