@event4u/agent-config 1.14.0 → 1.16.0

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

@@ -0,0 +1,338 @@
+---
+stability: beta
+---
+
+# UI Track — Flow Contract
+
+> Technical contracts for the UI directive sets shipped under
+> [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md).
+> 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.uncompressed/templates/scripts/work_engine/directives/ui/`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/).
+>   Mixed (Phase 4) under `directives/mixed/`. `ui-trivial` (Phase 2 Step 6)
+>   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 — see
+>   [`road-to-visual-review-loop.md`](../../agents/roadmaps/road-to-visual-review-loop.md).
+>   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).
+- A roadmap — phased delivery lives in
+  [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md).
+
+## 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.uncompressed/templates/scripts/work_engine/directives/ui/__init__.py),
+[`directives/mixed/__init__.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/mixed/__init__.py),
+[`directives/ui_trivial/__init__.py`](../../.agent-src.uncompressed/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.uncompressed/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.uncompressed/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.uncompressed/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.
+- [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md)
+  — phased delivery and Golden-Transcript matrix.
+- [`road-to-product-ui-track-followup.md`](../../agents/roadmaps/archive/road-to-product-ui-track-followup.md)
+  — pinned GT-U5 (mixed flow), GT-U6A/B (stack dispatch), GT-U7
+  (trivial happy path), GT-U8 (trivial reclassification).
+- [`road-to-visual-review-loop.md`](../../agents/roadmaps/road-to-visual-review-loop.md)
+  — R4 contract: a11y gate, preview envelope, polish-termination
+  rewrite. Pinned by GT-U13 (a11y polish), GT-U14 (a11y ceiling),
+  GT-U15 (preview render failure).
+- [`existing-ui-audit` SKILL](../../.agent-src.uncompressed/skills/existing-ui-audit/SKILL.md)
+  — producer of `state.ui_audit`.
+- [`ui-audit-gate` rule](../../.agent-src.uncompressed/rules/ui-audit-gate.md)
+  — the always-on rule that mirrors the audit gate at the agent layer.

package/docs/customization.md

@@ -58,6 +58,20 @@ those sections.
 | `chat_history.max_size_kb` | per profile | Max file size before overflow handling (see matrix below). |
 | `chat_history.on_overflow` | per profile | `rotate` drops oldest, `compress` marks for summarization (see matrix below). |
 | `onboarding.onboarded` | `false` | Whether `/onboard` has run. The `onboarding-gate` rule prompts for `/onboard` while this is `false`. |
+| `ai_council.enabled` | `false` | Master switch for the `/council` command. Even when enabled, every consultation asks before spending tokens. |
+| `ai_council.members.<provider>.enabled` | `false` | Per-provider opt-in (`anthropic`, `openai`). Tokens live in `~/.config/agent-config/<provider>.key` (mode 0600), never in this file. |
+| `ai_council.members.<provider>.model` | per provider | Which model the provider sends the query to (e.g. `claude-sonnet-4-5`, `gpt-4o`). |
+| `ai_council.cost_budget.max_input_tokens` | `50000` | Hard cap on summed input tokens per `/council` invocation. |
+| `ai_council.cost_budget.max_output_tokens` | `20000` | Hard cap on summed output tokens per `/council` invocation. |
+| `ai_council.cost_budget.max_calls` | `10` | Maximum council members per invocation. |
+| `ai_council.cost_budget.max_total_usd` | `0.0` | Per-invocation USD ceiling. `0` disables (token caps still apply). |
+| `ai_council.cost_budget.daily_limit_usd` | `0.0` | Rolling 24h USD ceiling across all `/council` calls. `0` disables. Ledger lives at `~/.config/agent-config/council-spend.jsonl` (mode 0600). |
+
+Council API tokens are installed via `./agent-config keys:install-anthropic`
+and `./agent-config keys:install-openai` — they prompt on `/dev/tty`, write to
+`~/.config/agent-config/<provider>.key` with mode `0600`, and never accept env
+vars. The `/council` command refuses to run if the key file's permissions
+drift.
 
 ### Cost profiles
 

package/docs/end-to-end-walkthroughs.md

@@ -0,0 +1,165 @@
+# End-to-end walkthroughs
+
+Four cycle-by-cycle traces of the engine commands — backend ticket,
+free-form prompt, UI track, and a blocked path. Each walkthrough cites
+a checked-in **golden transcript** under [`tests/golden/baseline/`](../tests/golden/baseline/);
+the transcripts are regenerated by `python3 -m tests.golden.capture` and
+diffed in CI, so the cycle counts and directive names below stay
+in sync with the engine's actual behavior.
+
+> Behavior demos (autonomy, commit policy, hard floor, verification)
+> live in [`showcase.md`](showcase.md). This file is the cycle-trace
+> companion: input → directives → outcome.
+
+---
+
+## 1. Backend ticket → ship — `/implement-ticket`
+
+**Anchor:** [`tests/golden/baseline/GT-1/`](../tests/golden/baseline/GT-1/) ·
+[`tickets/gt-1-happy.json`](../tests/golden/sandbox/tickets/gt-1-happy.json)
+
+**Input** — a ticket payload with three concrete acceptance criteria:
+
+```text
+GT-1-MULT — Add multiply(a, b) to the toy calculator
+AC: signature multiply(a: int, b: int) -> int returning the product;
+    edge cases multiply(0, n)=0, multiply(-2, 3)=-6;
+    pytest test_multiply_returns_product in tests/test_calculator.py.
+```
+
+**Trace** — five cycles, exit code `0` on the last:
+
+| Cycle | Directive | What the agent does |
+|---|---|---|
+| c1 | `create-plan` | Builds the three-step plan (impl, test, run) |
+| c2 | `apply-plan` | Edits `src/calculator.py` and `tests/test_calculator.py` |
+| c3 | `run-tests` | `pytest` — `4 passed` (targeted scope) |
+| c4 | `review-changes` | Four judges (bug, security, test-coverage, code-quality) — `success` |
+| c5 | _(none)_ | Engine emits the delivery report, exits `0` |
+
+**Outcome** — verified delivery report at
+[`GT-1/delivery-report.md`](../tests/golden/baseline/GT-1/delivery-report.md):
+plan, changes, test verdict, judge findings, suggested next command
+(`/commit`).
+
+**Anchored in:** [`commands/implement-ticket.md`](../.agent-src/commands/implement-ticket.md)
+(eight-step contract) · [`work_engine/dispatcher.py`](../.agent-src/templates/scripts/work_engine/dispatcher.py)
+(`STEP_ORDER`).
+
+---
+
+## 2. Free-form prompt → ship — `/work`
+
+**Anchor:** [`tests/golden/baseline/GT-P1/`](../tests/golden/baseline/GT-P1/) ·
+[`prompts/gt-p1-high.txt`](../tests/golden/sandbox/prompts/gt-p1-high.txt)
+
+**Input** — one line, no AC, no ticket:
+
+```text
+Add modulo(a, b) to src/calculator.py — return a % b for ints
+```
+
+**Trace** — six cycles. The extra cycle vs. GT-1 is the
+`refine-prompt` step that reconstructs the prompt into AC + assumptions
++ confidence band before any plan runs:
+
+| Cycle | Directive | Effect |
+|---|---|---|
+| c1 | `refine-prompt` | High confidence — AC reconstructed, no halt |
+| c2 | `create-plan` | Two-step plan |
+| c3 | `apply-plan` | Edits `src/calculator.py` |
+| c4 | `run-tests` | targeted pass |
+| c5 | `review-changes` | judges green |
+| c6 | _(none)_ | delivery report, exit `0` |
+
+**Outcome** — `success`. The same dispatcher and judges as GT-1; only
+the input envelope (`input.kind="prompt"` vs `"ticket"`) differs.
+
+**Anchored in:** [`commands/work.md`](../.agent-src/commands/work.md) ·
+[`skills/refine-prompt/SKILL.md`](../.agent-src/skills/refine-prompt/SKILL.md)
+· [`docs/contracts/adr-prompt-driven-execution.md`](contracts/adr-prompt-driven-execution.md).
+
+---
+
+## 3. UI improvement → review-loop ship — `/work` (UI track)
+
+**Anchor:** [`tests/golden/baseline/GT-U2/`](../tests/golden/baseline/GT-U2/) ·
+[`diffs/gt-u2-improve-diff.diff`](../tests/golden/sandbox/diffs/gt-u2-improve-diff.diff)
+
+**Input** — a Blade diff that adds a `<label>` and a heading change to
+`resources/views/contact.blade.php`. The input shape (a diff, not a
+prompt) routes the engine onto the **UI track** instead of the
+generic implement loop.
+
+**Trace** — six cycles, none of them `create-plan` / `apply-plan` /
+`run-tests`. The UI track has its own directive set:
+
+| Cycle | Directive | Effect |
+|---|---|---|
+| c1 | `existing-ui-audit` | Inventory existing components / tokens before any new design |
+| c2 | `ui-design-brief` | Brief for the proposed change |
+| c3 | _(none — `_no_directive`)_ | Engine threads forward to the apply step |
+| c4 | `ui-apply-plain` | Apply the diff |
+| c5 | `ui-design-review-plain` | Design review judge |
+| c6 | _(none)_ | delivery report, exit `0` |
+
+**Outcome** — `success`. The audit-first ordering is enforced by the
+[`ui-audit-gate`](../.agent-src/rules/ui-audit-gate.md) rule: any
+non-trivial UI change without `state.ui_audit` halts before design.
+
+**Anchored in:** [`docs/ui-track-mental-model.md`](ui-track-mental-model.md) ·
+[`rules/ui-audit-gate.md`](../.agent-src/rules/ui-audit-gate.md) ·
+[`skills/existing-ui-audit/SKILL.md`](../.agent-src/skills/existing-ui-audit/SKILL.md).
+
+---
+
+## 4. Blocked on ambiguity — `/implement-ticket` halts
+
+**Anchor:** [`tests/golden/baseline/GT-2/`](../tests/golden/baseline/GT-2/) ·
+[`tickets/gt-2-ambiguity.json`](../tests/golden/sandbox/tickets/gt-2-ambiguity.json)
+
+**Input** — a ticket whose AC list contains a vague entry:
+
+```text
+GT-2-DIV — divide(a, b)
+AC: ... vague acceptance criteria at position(s) 2 ...
+```
+
+**Trace** — one cycle, exit code `1`:
+
+| Cycle | Directive | Effect |
+|---|---|---|
+| c1 | _(none)_ | Engine refuses to plan; surfaces refine prompt |
+
+**Halt surface** — the engine does not write a plan, does not edit any
+file, and emits a numbered-options block (verbatim from
+[`GT-2/halt-markers.json`](../tests/golden/baseline/GT-2/halt-markers.json)):
+
+```text
+> Ticket GT-2-DIV is missing: vague acceptance criteria at position(s) 2.
+> 1. Run `/refine-ticket GT-2-DIV` and re-invoke `/implement-ticket`
+> 2. Provide the missing details in chat — I'll merge them into the ticket
+> 3. Abandon this ticket — too vague to implement
+```
+
+**Outcome** — `halt_unhandled`; the run is recorded as **blocked** in
+the outcome-aware telemetry (`outcomes: ["blocked"]`, see
+[P2 #9](../agents/roadmaps/road-to-1-15-followups.md#phase-9--outcome-aware-telemetry-p2-9)).
+No work is committed, no auto-guess is taken.
+
+**Anchored in:** [`rules/ask-when-uncertain.md`](../.agent-src/rules/ask-when-uncertain.md)
+· [`rules/non-destructive-by-default.md`](../.agent-src/rules/non-destructive-by-default.md)
+· [`skills/refine-ticket/SKILL.md`](../.agent-src/skills/refine-ticket/SKILL.md).
+
+---
+
+## Reproducing these locally
+
+```bash
+python3 -m tests.golden.capture --scenarios GT-1 GT-P1 GT-U2 GT-2
+```
+
+Each scenario writes a fresh `transcript.json`, `delivery-report.md`,
+and `halt-markers.json` under `tests/golden/baseline/<id>/`. CI diffs
+the regenerated output against the committed baseline; drift fails the
+build via the `roadmap-progress-check` and `golden-replay` tasks.

package/docs/getting-started.md

@@ -1,23 +1,39 @@
 # Getting Started
 
+`agent-config` is a stack-agnostic orchestration contract for coding
+agents. The installer detects the project shape (Composer / npm / both /
+neither) and wires the matching glue. **Pick the entrypoint that
+matches the project**, not the language you happen to prefer.
+
 ## Installation
 
+The installer is the same orchestrator across stacks — it reads
+`composer.json` and/or `package.json`, syncs the payload, and generates
+the tool-specific glue. Pick one entrypoint:
+
 ```bash
-# Composer (PHP) — two steps: install, then run the orchestrator
+# Composer-based projects (PHP / Laravel / Symfony / Zend / Laminas)
 composer require --dev event4u/agent-config
 php vendor/bin/install.php
 # Equivalent: bash vendor/event4u/agent-config/scripts/install
 
-# npm (JavaScript/TypeScript) — the orchestrator runs via postinstall
+# npm-based projects (Next.js / React / Node / Vue / plain JS/TS)
 npm install --save-dev @event4u/agent-config
-# Re-run or pick a profile:
+# Postinstall runs the orchestrator. Re-run or pick a profile:
 # bash node_modules/@event4u/agent-config/scripts/install --profile=balanced
+
+# Mixed Composer + npm projects (Laravel + Inertia, Symfony + Vue, …)
+# Run both — the orchestrator merges results, no double-write.
+
+# Stack-less or polyglot repos (no Composer, no npm)
+git clone https://github.com/event4u-app/agent-config /tmp/agent-config
+bash /tmp/agent-config/scripts/install --target "$PWD"
 ```
 
 That's it. Your agent now follows your team's standards. The orchestrator
 runs a bash payload sync and a Python bridge generator (Python 3 is
 recommended; without it the payload sync still runs). No Task or Make
-required for end users.
+required for end users — those are contributor-only.
 
 ## Project CLI — `./agent-config`
 
@@ -99,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 53 rules. No configuration needed.
+This is enforced automatically by 57 rules. No configuration needed.
 
 ---
 
@@ -131,13 +147,15 @@ Your agent now understands slash commands:
 |---|---|
 | `/commit` | Stage and commit with Conventional Commits |
 | `/create-pr` | Create PR with Jira-linked description |
-| `/fix-ci` | Fetch and fix GitHub Actions failures |
+| `/fix ci` | Fetch and fix GitHub Actions failures |
+| `/optimize skills` | Audit skills, find duplicates, run linter |
+| `/feature plan` | Interactively plan a feature |
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log |
 | `/chat-history-resume` | Recover context after a crashed or switched session |
 | `/chat-history-clear` | Wipe the chat-history log (with confirmation) |
 
-→ [Browse all 77 commands](../.agent-src/commands/)
+→ [Browse all 69 active commands](../.agent-src/commands/)
 
 ---
 
@@ -165,7 +183,7 @@ Run `/chat-history-resume` to walk through the prompts explicitly, or
 let the agent ask on the first turn of a new chat. All merge/replace/
 resume paths read the on-disk entries into context before any write.
 
-See the [`chat-history` rule](../.agent-src/rules/chat-history.md) and
+See the [`chat-history` rule](../.agent-src/rules/chat-history-ownership.md) and
 [`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
 
 ---
@@ -173,7 +191,7 @@ See the [`chat-history` rule](../.agent-src/rules/chat-history.md) and
 ## Next steps
 
 1. **Stay on `minimal`** — use it for a few days, see if the difference is noticeable
-2. **Try commands** — `/commit`, `/create-pr`, `/fix-ci` are great starting points
+2. **Try commands** — `/commit`, `/create-pr`, `/fix ci` are great starting points
 3. **Upgrade when ready** — switch to `balanced` to let the runtime dispatcher execute skills that declare a shell command
 4. **Customize** — add [project overrides](customization.md) for your team's specific patterns
 

package/docs/github-topics.md

@@ -13,8 +13,12 @@ ai-coding
 agent-skills
 agent-rules
 governance
+orchestration
 laravel
 php
+nextjs
+nodejs
+typescript
 devcontainer
 augment-agent
 claude-code
@@ -30,8 +34,9 @@ agentskills-standard
 | `agent-skills` | Aligns with the [Agent Skills](https://agentskills.io) community spec |
 | `agent-rules` | Complementary — rules govern behavior, skills provide expertise |
 | `governance` | Differentiates from prompt collections |
-| `laravel` | Primary domain — Laravel projects are the main audience |
-| `php` | Broader PHP audience |
+| `orchestration` | Captures the core identity — a deterministic orchestration contract / state machine |
+| `laravel`, `php` | Reference-implementation stack — currently the deepest skill density |
+| `nextjs`, `nodejs`, `typescript` | Parallel skill sets for JS/TS surfaces (project-analysis, UI directives) |
 | `devcontainer` | One of our 4 core concerns |
 | `augment-agent`, `claude-code`, `copilot` | Tool-specific discovery |
 | `agentskills-standard` | SKILL.md format is compatible with the agentskills.io spec |
@@ -53,8 +58,12 @@ gh repo edit event4u-app/agent-config \
   --add-topic agent-skills \
   --add-topic agent-rules \
   --add-topic governance \
+  --add-topic orchestration \
   --add-topic laravel \
   --add-topic php \
+  --add-topic nextjs \
+  --add-topic nodejs \
+  --add-topic typescript \
   --add-topic devcontainer \
   --add-topic augment-agent \
   --add-topic claude-code \
@@ -69,7 +78,7 @@ curl -X PUT \
   -H "Authorization: Bearer $GITHUB_TOKEN" \
   -H "Accept: application/vnd.github+json" \
   https://api.github.com/repos/event4u-app/agent-config/topics \
-  -d '{"names":["ai-coding","agent-skills","agent-rules","governance","laravel","php","devcontainer","augment-agent","claude-code","copilot","agentskills-standard"]}'
+  -d '{"names":["ai-coding","agent-skills","agent-rules","governance","orchestration","laravel","php","nextjs","nodejs","typescript","devcontainer","augment-agent","claude-code","copilot","agentskills-standard"]}'
 ```
 
 ## Verify