@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/skills/livewire/SKILL.md

@@ -1,18 +1,39 @@
 ---
 name: livewire
-description: "Use when writing Livewire components — reactive state, events, lifecycle hooks, and clean separation between component logic and Blade templates."
+description: "Stack-implementation skill for Livewire — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Livewire. Covers reactive state, events, lifecycle hooks, and component/view separation."
 source: package
 ---
 
 # livewire
 
+## Positioning — dispatched, not standalone
+
+`livewire` is the **apply-step executor** for the Livewire stack. It is
+invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py)
+once the design brief is locked, and revisited by `review.py` /
+`polish.py` during the design-review loop. It does **not** own the
+flow, does **not** drive the audit, and does **not** lock the design.
+
+| Concern | Owner |
+|---|---|
+| Audit + token inventory (mandatory pre-step) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) |
+| Design brief (layout / states / microcopy) | [`directives/ui/design.py`](../../templates/scripts/work_engine/directives/ui/design.py) |
+| Universal design heuristics | [`fe-design`](../fe-design/SKILL.md) |
+| Static Blade partials inside the view | [`blade-ui`](../blade-ui/SKILL.md) |
+| Flux primitives inside the view | [`flux`](../flux/SKILL.md) |
+
 ## When to use
 
-Use when creating or editing Livewire components — reactive state, forms, tables, real-time updates.
+Cite this skill when:
+
+- `state.stack.frontend == "livewire"` and `directives/ui/apply.py` dispatches to this skill
+- Editing or creating Livewire components — reactive state, forms, tables, real-time updates
 
 Do NOT use when:
-- Static Blade views (use `blade-ui` skill)
-- Flux UI components (use `flux` skill)
+
+- Static Blade views with no interactivity (use `blade-ui` skill)
+- Flux UI primitives (use `flux` skill — `livewire` composes Flux internally)
+- Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
 
 ## Procedure: Create a Livewire component
 
@@ -58,6 +79,30 @@ Do NOT use when:
 1. Livewire component class with typed properties and actions
 2. Blade view with wire: bindings and Flux components
 
+### Review pass — a11y findings + preview envelope
+
+When this skill is dispatched by `directives/ui/review.py` (test slot)
+or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
+not the initial apply — it also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
+  severity_floor?, accepted_violations?}`. Use the same `(rule, selector)`
+  shape as `state.ui_audit.a11y_baseline` so the engine's de-dup matches
+  pre-existing entries on replay. Omit the envelope on apply passes; the
+  engine's `_apply_a11y_gate` only fires when a baseline is present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
+  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
+  populated triggers the `preview_render_failed` halt; `render_ok: true`
+  with `screenshot_path` threads the screenshot into the delivery
+  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
+  a consumer-project dependency — this package does not ship one.
+
+Polish dispatch: when the dispatcher skips `review` because a previous
+review pass already returned `SUCCESS`, this skill MUST itself
+synthesise the updated `state.ui_review.findings` (including any
+remaining `a11y_violation` entries) so the engine's gate sees the
+current state on the next polish round.
+
 ## Gotcha
 
 - Public properties serialize between requests — don't put large objects in state.

package/.agent-src/skills/md-language-check/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: md-language-check
+description: "Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 30
+  allowed_tools: []
+  command:
+    - python3
+    - scripts/check_md_language.py
+---
+
+# md-language-check
+
+## When to use
+
+Fire **before** saving any `.md` file under:
+
+- `.agent-src.uncompressed/` (source of truth)
+- `.agent-src/` (compressed projection)
+- `.augment/` (local agent projection)
+- `agents/` (project roadmaps, contexts, sessions)
+
+Per [`language-and-tone`](../../rules/language-and-tone.md) § "`.md`
+files are ALWAYS English" + § Detection heuristic, every `.md` in
+those trees must be English. Bilingual content lives only in labeled
+`DE: … · EN: …` anchor blocks.
+
+Do NOT use when:
+
+- Editing project content outside the trees above
+- Reviewing non-`.md` files (checker rejects them)
+
+## Procedure
+
+### 1. Identify the file(s) about to be saved
+
+Collect every `.md` path the agent is about to create or modify this
+turn. Multiple files → one invocation.
+
+### 2. Run the checker
+
+```bash
+python3 scripts/check_md_language.py <path> [<path> …] [--format json]
+```
+
+Exit codes: `0` clean, `1` violations (save **blocked** until fixed
+or suppressed), `3` internal error.
+
+### 3. Resolve findings
+
+| Kind | Cause | Fix |
+|---|---|---|
+| `umlaut` | German prose in body | Translate to English |
+| `de_word` | German function word in unquoted prose | Translate; or move into `DE: … · EN: …` block |
+
+Meta-doc that **must** quote German tokens (e.g. the heuristic in
+`language-and-tone.md` itself) → append
+`<!-- md-language-check: ignore -->` to that single line. Never as a
+wholesale silencer.
+
+### 4. Re-run and confirm
+
+After every fix re-run on the same paths. Save proceeds only on `0`.
+
+## Allowed escape hatches
+
+- **Labeled anchor** — lines starting with `DE:` / `- DE:` / `* DE:`
+  (and the same for `EN:`) auto-skipped.
+- **Fenced code blocks** — exempt; shell snippets, JSON fixtures,
+  quoted user input pass through.
+- **Inline code** — backtick spans stripped before scanning.
+- **Per-line marker** — `<!-- md-language-check: ignore -->` on lines
+  that genuinely quote German tokens (rare).
+
+## Output format
+
+1. One-line summary: `clean` or `N violation(s) found`
+2. Per violation: `file:line — kind \`match\`` plus the offending line
+3. Next action: translate, move into a `DE:`/`EN:` block, add the
+   per-line ignore marker, or revert
+
+## Gotchas
+
+- `.md` files only; non-`.md` paths emit a warning and skip
+- Word list is short and conservative — clean run is **necessary
+  but not sufficient**; agent owns the final language judgement
+- Frontmatter (`--- … ---`) is exempt
+
+## Do NOT
+
+- Do NOT silence by deleting trigger words from
+  `scripts/check_md_language.py`; extend the allow-list instead
+- Do NOT use the ignore marker as a generic mute
+- Do NOT skip the gate "because the file is small"
+
+## Cloud Behavior
+
+Cloud surfaces (Claude.ai Web, Skills API) ship without the script,
+so this skill is **inert** there — apply the heuristic from
+[`language-and-tone`](../../rules/language-and-tone.md) manually.

package/.agent-src/skills/php-coder/SKILL.md

@@ -37,6 +37,30 @@ Do NOT use when:
 → See guideline `php/general.md` for detailed PHP conventions.
 → See guideline `php/controllers.md`, `php/eloquent.md`, etc. for domain-specific conventions.
 
+### Step 3: Stop-gate — branching on a discriminator?
+
+Before writing **a second** `match`/`switch` arm, **a second** `if/elseif`
+branch, or **a second** class hardcoded to one enum/string value (e.g.
+`Provider::FOO->value`, `'stripe'`, a `case Type::CSV`), STOP and run the
+Strategy sniff test.
+
+Trigger keywords in the task or surrounding code:
+
+- enum/string used as a type-tag: `Provider`, `Type`, `Channel`, `Format`,
+  `Driver`, `Kind`
+- repeated `match ($x)` / `switch ($x)` blocks on the same value
+- class names that bake a single enum case in: `StripeImportService`,
+  `CsvExporter`, `Ks21Job` next to `GeoCaptureJob` with the same shape
+- allowlist constants: `private const SUPPORTED_FOO = [Type::A, Type::B]`
+
+→ Run the sniff test in
+[`guidelines/php/patterns/strategy.md`](../../guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
+Two "yes" answers → propose Strategy + Registry **before** adding the new
+branch. Three "yes" → it is already overdue and the refactor is the change.
+
+This gate fires **per task**, not per file — once you've passed the sniff
+test for a given discriminator, do not re-ask on the next branch.
+
 ### Core principles
 
 - **KISS** — simplest solution that works. No over-engineering.

package/.agent-src/skills/react-shadcn-ui/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: react-shadcn-ui
+description: "Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack."
+source: package
+---
+
+# react-shadcn-ui
+
+## Compatibility
+
+- **Tested against:** `shadcn@2.1`, Tailwind CSS `3.x`, React `18+`.
+- Audit step (`directives/ui/audit.py`) reads the line above and compares it with `state.ui_audit.shadcn_inventory.version`; major mismatch triggers a soft halt before this skill runs.
+
+## When to use
+
+Use when `state.stack.frontend == "react-shadcn"` and `directives/ui/apply.py`, `review.py`, or `polish.py` dispatches to this skill, or when a React project clearly uses shadcn/ui (presence of `components.json`, `@radix-ui/*` dependencies, a `components/ui/` folder of generated primitives).
+
+Do NOT use when:
+
+- Project is Blade + Livewire + Flux (use `flux` / `livewire` / `blade-ui`).
+- Project is Vue (use the Vue stack skills).
+- Plain React without shadcn/ui — fall back to manual composition; this skill assumes the primitive set exists.
+
+## Gotcha
+
+- shadcn/ui is **not** an npm package. Primitives are copied into `components/ui/` and edited in-place. Do not `npm install shadcn-ui`. Run `npx shadcn@latest add <primitive>` to scaffold; then edit.
+- Major-version drift between this skill's `## Compatibility` line and the project's installed primitives is a real risk. Audit step writes `state.ui_audit.shadcn_inventory` with the detected version — when it diverges by a major, audit emits a soft halt before this skill runs.
+- shadcn/ui composes Radix primitives. Accessibility built in via Radix but only when wrapper components used correctly (`asChild`, `<DialogTrigger>` instead of bare `<button>`).
+- Tailwind tokens come from `tailwind.config.{js,ts}` (`theme.extend.colors`) and CSS custom properties on `:root` and `.dark` (`--background`, `--foreground`, `--primary`, `--ring`, …). Audit writes them into `state.ui_audit.design_tokens`. Use those tokens; do not hardcode values.
+- Dark mode is class-based (`<html class="dark">`). Every color must come from `bg-background`, `text-foreground`, etc. — never raw `bg-white`.
+- Every interactive primitive must declare a focus-visible state via `focus-visible:ring-2 focus-visible:ring-ring`; comes free with generated primitives but easy to remove during a refactor.
+
+## Covered primitives
+
+Validated against the following shadcn primitives at the declared version:
+
+- **Form / inputs:** `Button`, `Input`, `Textarea`, `Checkbox`, `RadioGroup`, `Select`, `Switch`, `Label`, `Form` (react-hook-form wrapper + `zodResolver`).
+- **Overlay:** `Dialog`, `Sheet`, `Popover`, `Tooltip`, `DropdownMenu`, `AlertDialog`.
+- **Layout:** `Card`, `Separator`, `Tabs`, `Accordion`, `ScrollArea`.
+- **Data display:** `Table` (with `@tanstack/react-table`), `Badge`, `Avatar`, `Skeleton`, `Progress`.
+- **Feedback:** `Toast` (sonner), `Alert`.
+
+## Not covered — fall back to manual composition
+
+- Marketing-only components (Hero, Pricing, Features) — outside shadcn/ui.
+- `Calendar` / `DatePicker` — composition skill required, not generated.
+- `Combobox` — built from `Command` + `Popover`; case-by-case.
+- Streaming / partial-prerender boundaries — use the project's framework patterns (Next.js / Remix), not shadcn/ui.
+
+## Procedure: render a shadcn/ui component for the design brief
+
+### Step 0: Inspect
+
+1. Read `state.ui_audit.shadcn_inventory.version` and confirm it matches the version in `## Compatibility` within the same major. If audit flagged a mismatch, user already chose to proceed — note that in `state.changes`.
+2. Read `state.ui_audit.design_tokens` — every color, spacing, and radius in rendered output must reference a token from this map.
+3. Read `state.ui_design`:
+   - `components` → the primitive list to compose.
+   - `microcopy` → button labels, empty-state text, validation messages. **Lock — render verbatim.**
+   - `states` → empty / loading / error / success / disabled coverage.
+   - `a11y` → ARIA labels, keyboard nav, focus order.
+
+### Step 1: Compose primitives
+
+1. Import primitives from project's `components/ui/` path (`@/components/ui/button`, …) — never from `shadcn` or `radix-ui`.
+2. Compose Radix-style: `<Dialog>` → `<DialogTrigger asChild>` → `<DialogContent>` → `<DialogHeader>` → `<DialogTitle>`. Never wrap `DialogTrigger` around a pre-styled `<button>`; pass `asChild`.
+3. Use variant API of `Button` (`variant="default" | "destructive" | "outline" | "secondary" | "ghost" | "link"`); do not override with raw Tailwind for the variant set.
+4. Forms: `useForm` (react-hook-form) + `zodResolver(schema)` → `<Form>` → `<FormField>` → `<FormItem>` → `<FormLabel>` → `<FormControl>` → `<FormMessage>`. Validation messages come from the zod schema, mirrored to design-brief microcopy.
+
+### Step 2: Apply tokens, dark mode, a11y
+
+1. Colors via semantic classes: `bg-background`, `text-foreground`, `bg-primary text-primary-foreground`, `text-muted-foreground`. No `bg-white` / `text-black` / hardcoded `#fff`.
+2. Spacing / radius from theme tokens (`rounded-lg` mapped to `--radius` in `tailwind.config.{js,ts}`). Polish refactors hardcoded values when a token equivalent exists.
+3. Dark mode: never branch on a `dark` prop; rely on `.dark` class on root and semantic tokens.
+4. Every interactive primitive: keyboard trigger present (Enter/Space on buttons, Esc on dialogs — Radix free), visible focus ring, `aria-label` from `state.ui_design.a11y` when icon-only.
+
+### Step 3: State coverage
+
+1. Empty: render design-brief empty-state copy in a `Card` or inline placeholder; never `null`.
+2. Loading: `Skeleton` rows for tables; `Button` `disabled` + `Loader2` icon for submit-in-flight.
+3. Error: `Alert variant="destructive"` with design-brief message; `FormMessage` for field-level errors.
+4. Success: `toast.success(...)` from `sonner` with design-brief confirmation copy.
+5. Disabled: `disabled` prop on trigger plus design-brief reason as `aria-describedby` text.
+
+### Step 4: Validate
+
+1. No raw `<input>` / `<button>` / `<select>` outside the primitive set.
+2. No hardcoded colors / spacing — every value is a token.
+3. Microcopy matches `state.ui_design.microcopy` byte-for-byte.
+4. Dark mode: toggle `.dark` on `<html>`, render the component, every surface still legible (no `text-white on bg-white`).
+5. Keyboard: Tab through every focusable element; focus ring visible.
+
+## Output format
+
+1. React component file(s) under project's `components/` (or `app/`) tree, importing primitives from `@/components/ui/*`.
+2. Per file, one entry recorded in `state.changes` with `kind="ui"`, `stack="react-shadcn"`, and the design-brief summary.
+
+### Review pass — a11y findings + preview envelope
+
+When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Run a11y tool against rendered output (e.g. `axe-core` via Playwright, `@axe-core/react`, `jest-axe`) and translate hits into this shape. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
+
+Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+
+## Do NOT
+
+- Do NOT install `shadcn-ui` from npm — primitives are scaffolded.
+- Do NOT hardcode colors / spacing / radii — use the token map.
+- Do NOT branch on a `dark` prop — use semantic tokens + the `.dark` class.
+- Do NOT rewrite microcopy — it is locked by `state.ui_design`.
+- Do NOT skip `asChild` on `DialogTrigger` / `SheetTrigger` / similar Radix wrappers — breaks the accessibility contract.
+- Do NOT introduce a non-shadcn UI library (MUI, Chakra) into the same surface — pick one system per surface.
+
+## Auto-trigger keywords
+
+- shadcn / shadcn ui / shadcn/ui
+- React component (when project uses shadcn)
+- Radix primitive
+- Tailwind dark mode
+- React Hook Form + zod

package/.agent-src/skills/refine-prompt/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: "refine-prompt"
+description: "Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'."
+personas:
+  - developer
+  - senior-engineer
+  - ai-agent
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# Refine Prompt
+
+> Move a free-form prompt from "raw text" to "engine-ready" in one run.
+> Produces reconstructed acceptance criteria, explicit assumptions,
+> and a confidence band that decides whether the engine proceeds
+> silently, halts for confirmation, or refuses to plan.
+>
+> Sibling of [`refine-ticket`](../refine-ticket/SKILL.md) — same
+> reconstruction-of-intent pattern, different input shape. Tickets
+> arrive structured (id, title, AC); prompts arrive as one string.
+
+## When to use
+
+- The user invokes `/work "<prompt>"` or pastes a free-form request.
+- The dispatcher hits `input.kind="prompt"` in the `refine` step.
+- A prompt looks ambiguous, broad, or scope-undefined and the user
+  asks "ist das klar genug, um loszulegen?".
+- Before any plan/apply step on prompt-driven work — never after.
+
+## When NOT to use (near-misses)
+
+| Phrasing | Route to |
+|---|---|
+| "refine this ticket" | [`refine-ticket`](../refine-ticket/SKILL.md) |
+| "estimate this prompt" | not supported — score then estimate downstream |
+| "plan this feature" | `/feature-plan` (downstream) |
+| "is this a duplicate?" | `validate-feature-fit` (sub-skill, post-refine) |
+
+`refine-prompt` is the *first* gate on prompt-driven flow. It does not
+plan, does not implement, does not write back anywhere.
+
+## Input
+
+Exactly one path: a non-empty raw string carried in
+`state.input.data.raw` (built by [`work_engine.resolvers.prompt`](../../templates/scripts/work_engine/resolvers/prompt.py)).
+No branch detection, no URL parsing, no clipboard fallback — the
+calling command (`/work`) owns prompt capture; this skill only refines.
+
+If `raw` is missing, empty, or whitespace-only the resolver already
+raised `PromptResolverError`. The skill never receives that input.
+
+## Procedure
+
+### 1. Read and analyze the prompt
+
+Examine the raw text top to bottom *before* changing anything in
+state. Identify the *single* desired outcome in one sentence —
+verb + object + observable result. If the prompt names two
+unrelated outcomes (e.g. "fix login AND refactor the dashboard"),
+record both but flag scope-overload in step 5; the score will
+land in `medium` or `low`.
+
+This is an analysis pass, not an execution pass. The skill does
+not modify the prompt, infer code changes, or call any tool — it
+investigates the input and produces a structured envelope the
+dispatcher reads.
+
+### 2. Enumerate explicit constraints
+
+Pull every concrete signal from the prompt verbatim:
+
+- **Files / modules** named in the text (`UserController`,
+  `auth.service.ts`, `migrations/2024_…`).
+- **Behaviour anchors** — endpoints, routes, commands, fixtures.
+- **Hard rules** — "must not break X", "without changing the API",
+  "keep backwards compat".
+
+Constraints come from the prompt only. Inferred constraints belong in
+step 3 (assumptions), never here.
+
+### 3. Infer reasonable assumptions
+
+Anything the prompt implies but does not state. Examples:
+
+- "fix the login bug" → assumes the bug is in the existing `auth/`
+  module (no new auth provider).
+- "add caching" → assumes the project's primary cache driver
+  (per `.agent-settings.yml` / `config/cache.php`).
+- "speed up the export" → assumes "faster" means runtime, not memory.
+
+Each assumption is a single line, prefixed with `assumes:`. The
+medium-band halt surfaces them verbatim — no rewording, no
+explanations.
+
+### 4. Generate the AC list
+
+Three to seven bullet points. Each bullet is observable and
+testable in the project's existing test surface (Pest / Jest /
+pytest / etc.). Avoid:
+
+- "works correctly" / "is fast" / "looks better" (untestable)
+- "no regressions" (the test suite already covers that)
+- "follows best practices" (not an AC)
+
+Anchor each bullet to a constraint from step 2 or an assumption from
+step 3 — never both implicit.
+
+### 5. Score confidence
+
+Delegate to [`scripts.work_engine.scoring.confidence`](../../templates/scripts/work_engine/scoring/confidence.py):
+
+```python
+from work_engine.scoring.confidence import score
+result = score(raw=prompt_raw, ac=reconstructed_ac, assumptions=assumptions)
+# result.band ∈ {"high", "medium", "low"}
+# result.score ∈ [0.0, 1.0]
+# result.dimensions: dict[str, int]   # 0–2 per dimension
+# result.reasons: list[str]            # human-readable rationale
+```
+
+The rubric (5 dimensions × 0–2, sum / 10) and band thresholds
+(`high ≥ 0.8`, `medium 0.5–0.79`, `low < 0.5`) are owned by
+`confidence.py`. Do not re-derive them in prose.
+
+## Band-action mapping
+
+The `refine` dispatcher step in `directives/backend/refine.py` reads
+the score and returns one of three outcomes — the skill does not
+decide the action, only produces the inputs.
+
+| Band | Outcome | What the user sees |
+|---|---|---|
+| `high` | `SUCCESS` | Silent proceed; AC + assumptions land in the delivery report |
+| `medium` | `PARTIAL` | Assumptions report halt: numbered list of `assumes:` lines + AC, user confirms or edits |
+| `low` | `BLOCKED` | One clarifying question (per [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) Iron Law) |
+
+## Output format
+
+The skill emits a structured envelope; the dispatcher renders it.
+Required fields, in order:
+
+1. **Goal** — single sentence, verb + object + observable result
+2. **Acceptance criteria** — numbered list, 3–7 entries, each
+   anchored to a step-2 constraint or a step-3 assumption
+3. **Assumptions** — bullet list, each line prefixed `assumes:`
+4. **Confidence** — band + score + per-dimension breakdown from
+   `work_engine.scoring.confidence`
+
+The shape below is the rendered surface for `medium` / `low`
+halts; for `high` the same envelope lands in the delivery report
+without a halt.
+
+````markdown
+## Reconstructed prompt
+
+**Goal:** <one sentence, verb + object + observable result>
+
+**Acceptance criteria:**
+1. <bullet>
+2. <bullet>
+3. <bullet>
+
+**Assumptions:**
+- assumes: <line>
+- assumes: <line>
+
+**Confidence:** medium (0.62) — goal_clarity 2 · scope_boundary 1 · ac_evidence 2 · stack_data 1 · reversibility 0
+````
+
+For `low`, the question replaces the AC list:
+
+```
+> The prompt does not name <missing dimension>.
+>
+> 1. <option that resolves the gap>
+> 2. <alternative resolution>
+> 3. <skip / abandon>
+```
+
+## Gotchas
+
+- The model invents AC that *sound* observable but aren't anchored
+  in the prompt or a concrete file. Every AC must trace to a step-2
+  constraint or a step-3 assumption — no free-floating bullets.
+- Assumptions are not commitments. The medium-band halt is the
+  user's chance to flip them; the skill never asserts an assumption
+  as fact.
+- The scorer is heuristic, not LLM-based. Token count is not a
+  signal — a 200-word prompt can score `low` if the goal is vague,
+  and a 20-word prompt can score `high` if scope is unambiguous.
+- UI-shaped prompts ("redesign the dashboard", "make the form
+  prettier") score `low` on `stack_data` until R3 lands the UI
+  directive set; band-action is a pointer to R3, not a refusal.
+
+## Do NOT
+
+- Do NOT call this skill on `input.kind="ticket"` — that path runs
+  through [`refine-ticket`](../refine-ticket/SKILL.md).
+- Do NOT auto-confirm assumptions on the user's behalf in the
+  medium-band halt. The halt is the contract.
+- Do NOT stack multiple clarifying questions in the low-band halt.
+  Iron Law: one question per turn.
+- Do NOT mutate `state.input.data.raw`. The original prompt stays
+  verbatim for replay; reconstructed output lands in
+  `data.reconstructed_ac` and `data.assumptions`.
+- Do NOT re-derive band thresholds in prose. They live in
+  `confidence.py` and only there.
+
+## See also
+
+- [`refine-ticket`](../refine-ticket/SKILL.md) — sibling for ticket-shaped input
+- [`work_engine.resolvers.prompt`](../../templates/scripts/work_engine/resolvers/prompt.py) — envelope builder
+- [`work_engine.scoring.confidence`](../../templates/scripts/work_engine/scoring/confidence.py) — rubric + band thresholds
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — one-question-per-turn Iron Law
+- [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — this skill was drafted under it
+- `agents/roadmaps/archive/road-to-prompt-driven-execution.md` — Phase 3 owns this skill (archived on completion)

package/.agent-src/skills/refine-ticket/SKILL.md

@@ -47,19 +47,24 @@ execution:
 
 ## Language strategy
 
-Pick output prose language once, up front; apply to every section.
-First hit wins:
+The refined output's prose language is picked once, up front, and
+applied to every section (refined description, risks, persona voices,
+orchestration notes, close-prompt). Fallback order — first hit wins:
 
-1. **User-message language.** Latest user message decides. Honours the
-   global `language-and-tone` iron law.
+1. **User-message language.** If the latest user message is in
+   German, the entire output is German; if English, English; etc.
+   This honours the global `language-and-tone` iron law.
 2. **Ticket body language.** When the user's message is ambiguous
-   (one-word `/refine-ticket PROJ-123`), mirror the language the ticket
-   is written in (summary + description).
-3. **`.agent-settings.yml` default** (`personal.language` or equivalent).
-   If missing, default to English.
+   (one-word `/refine-ticket PROJ-123`), mirror the language the
+   ticket is written in — detected from the summary + description.
+3. **`.agent-settings.yml` default.** If both are silent or unclear,
+   fall back to the project default in `.agent-settings.yml`
+   (`personal.language` or equivalent). If that is also missing,
+   default to English.
 
-Quoted identifiers (keys, paths, commands, code) stay native. Only
-prose mirrors the picked language.
+Quoted identifiers (ticket keys, file paths, command names, code
+snippets) stay in their native form. Only the prose mirrors the
+selected language.
 
 ## Inputs (four equivalent paths)
 
@@ -88,8 +93,8 @@ Delegate to `jira-ticket` §1-3:
 If pasted text: skip API, parse markdown, extract title + AC
 bullets + body.
 
-**Auto-fetch parent (Phase F4).** Before detection, check the issue
-type and fold parent context in:
+**Auto-fetch parent (Phase F4).** Before detection, check the
+issue type and fold parent context in:
 
 ```python
 from scripts.refine_ticket_detect import (
@@ -105,18 +110,19 @@ if issuetype_needs_parent(ticket["issuetype"]):
 ```
 
 Rules:
-- Applies to `Story` and `Sub-task` (and Linear / Shortcut equivalents).
-  `Task` / `Bug` / `Epic` skip the auto-fetch unless a `parent` link is
-  populated — then the agent folds explicitly without the issuetype guard.
+- Applies to `Story` and `Sub-task` (and their Linear / Shortcut
+  equivalents). `Task` / `Bug` / `Epic` skip the auto-fetch unless a
+  `parent` link field is already populated — in that case the agent
+  folds explicitly without the issuetype guard.
 - `fold_parent_context()` is idempotent; folding twice with the same
   parent does not duplicate the block.
-- Parent fetch fails (404, permission, network) → skip the fold, append
-  to orchestration notes:
+- When the parent fetch fails (404, permission, network), skip the
+  fold and append a line to orchestration notes:
   *"Parent `<key>` not reachable — AC may lack upstream context."*
 
-Parent AC lines surfaced this way must be cited verbatim in the refined
-output's *Open questions* section so the user sees which constraints
-come from the parent.
+Parent AC lines surfaced this way must be cited verbatim in the
+refined output's *Open questions* section so the user sees which
+constraints come from the parent.
 
 ### 2. Inspect ticket + detect orchestration triggers
 
@@ -130,7 +136,7 @@ Then run the deterministic detection helper — do **not** re-derive trigger
 logic in prose:
 
 ```bash
-python3 scripts/refine_ticket_detect.py <ticket-body-file>
+./agent-config refine-ticket:detect <ticket-body-file>
 # or, inside the skill run:
 from scripts.refine_ticket_detect import detect, load_map
 decision = detect(ticket_body, load_map(), cwd=Path.cwd())
@@ -206,8 +212,7 @@ open a planning doc.
 
 ## Output template
 
-Frozen per Q25 (see
-[`road-to-ticket-refinement.md`](../../../agents/roadmaps/road-to-ticket-refinement.md)).
+Frozen per Q25.
 
 ````markdown
 ## Refined ticket
@@ -247,8 +252,8 @@ so the user can grab it verbatim.
 
 ## Close-prompt (mandatory final step)
 
-**Probe write access first (Phase F6).** Cheap upfront check before
-rendering:
+**Probe write access first (Phase F6).** Before rendering, do a
+cheap upfront check:
 
 ```python
 from scripts.refine_ticket_detect import render_close_prompt
@@ -272,8 +277,8 @@ Behaviour:
 | Probe failed (`None`) | Full three-option prompt; skill degrades to copy-paste on selection (v1 fallback) |
 
 Per user interaction rules, accept number or free text. `editmeta`
-is cheap and cacheable; cache per Jira project key for the session,
-re-probe on project change.
+is cheap and cacheable; cache the result per Jira project key for
+the session, re-probe on project change.
 
 ## Output format
 
@@ -306,5 +311,4 @@ re-probe on project change.
 - [`feature-explore`](../../commands/feature-explore.md) — upstream idea capture; hints at `/refine-ticket` when input looks like a ticket
 - [`feature-plan`](../../commands/feature-plan.md) — downstream planning
 - [`adversarial-review`](../adversarial-review/SKILL.md) — same `critical-challenger` persona, different stage (post-plan)
-- [`road-to-ticket-refinement.md`](../../../agents/roadmaps/road-to-ticket-refinement.md) — governing roadmap
 - [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — this skill was drafted under it