@event4u/agent-config 1.14.0 → 1.15.0

package/.agent-src/rules/user-interaction.md

@@ -18,6 +18,7 @@ EXACTLY ONE LINE NAMES THE RECOMMENDED NUMBER. NO INLINE TAG. NO SECOND PROSE NU
 THE OPTION BLOCK STAYS NEUTRAL. THE RECOMMENDATION LINE IS THE ONLY SOURCE OF TRUTH.
 DRIFT BETWEEN OPTION-BLOCK AND PROSE IS STRUCTURALLY IMPOSSIBLE WHEN THE TAG DOES NOT EXIST.
 MISSING RECOMMENDATION = RULE VIOLATION, NOT A SLIP.
+POSITION-AGNOSTIC. END-OF-TURN MENUS COUNT. NEXT-STEP LISTS COUNT. NO EXCEPTIONS.
 ```
 
 The agent has read the code, the contracts, the trade-offs. Refusing
@@ -25,6 +26,16 @@ to take a position dumps that work back on the user. Take the
 position; be wrong out loud if needed. "Egal, was bevorzugst Du?" /
 "no preference" is NEVER acceptable.
 
+**Position-agnostic — closes the most common slip:** End-of-turn
+"Wie weiter?" / "What next?" / "How to proceed?" / "How should we
+continue?" blocks with numbered options are **numbered-options
+blocks**. Same Iron Law applies — exactly one `Empfehlung: N` /
+`Recommendation: N` line, every time. There is no "these are just
+follow-up suggestions" exception, no "the user knows better here"
+exception, no "I genuinely don't have a preference" exception. If
+the agent prints `1. … 2. … 3. …` anywhere in the reply, the
+recommendation line is mandatory.
+
 **Format — non-negotiable:**
 
 - Options block stays NEUTRAL — no `(recommended)`, no `(rec)`, no `←`, no bold, no checkmark.
@@ -58,16 +69,28 @@ SKIPPING IT IS A RULE VIOLATION, NOT A SLIP.
 ```
 
 Before emitting any reply that contains numbered options, scan the
-drafted text:
+**entire drafted reply** — top to bottom, including end-of-turn
+"Wie weiter?" / "What next?" continuation menus, follow-up
+suggestion blocks, and any list of `1. … 2. … 3. …` regardless of
+its position or framing:
 
 1. Count occurrences of `(recommended)` / `(rec)` / `(empfohlen)` inline next to a numbered option → MUST be **zero**. Found one → rewrite, drop the tag.
-2. Count distinct `Recommendation:\s*N` / `Empfehlung:\s*N` lines (case-insensitive) → MUST be **exactly one**. Zero → add one. Two or more distinct numbers → rewrite, pick one.
-3. The number on the recommendation line MUST exist in the option block.
+2. Count `1\.\s` / `2\.\s` / `3\.\s` patterns inside blockquotes or top-level prose → if **any** numbered-option block exists anywhere in the reply, the recommendation line is mandatory.
+3. Count distinct `Recommendation:\s*N` / `Empfehlung:\s*N` lines (case-insensitive) → MUST be **exactly one per options block**. Zero → add one. Two or more distinct numbers → rewrite, pick one.
+4. The number on the recommendation line MUST exist in the option block it follows.
+5. If the reply has multiple options blocks (e.g. a clarification block AND an end-of-turn menu), each block gets its own `Recommendation: N` line directly underneath.
 
 Mechanical backstop: `python3 scripts/check_reply_consistency.py --stdin < draft.md`
 (non-zero exit on any rule above). Self-scan is the primary gate; the
 script is the deterministic safety net for ambiguous cases.
 
+### Common failure modes — known, named, no excuses
+
+- **End-of-turn menu skipped.** Reply answers the question fine, then ends with `> 1. Foo > 2. Bar > 3. Stop` and no `Empfehlung:`. Iron Law 1 was violated — these are numbered options, position is irrelevant.
+- **"Genuinely no preference" hedge.** Pick anyway. The agent has more context than the user on the trade-off; refusing to pick dumps the work back. Pick the safest option, name the flip-condition.
+- **"User knows the project better" hedge.** Same failure mode, different costume. The user asked for an opinion by virtue of accepting the options block; deliver it.
+- **Multi-block reply with one recommendation.** Two options blocks but only one `Empfehlung:` line — the second block is unguarded. Rule 5 above closes this.
+
 ## Numbered Options — Always
 
 When asking the user a question with predefined choices, **always
@@ -87,9 +110,10 @@ just a number (e.g., `1`) instead of typing a sentence.
 ### Rules
 
 - **Every question with choices** must use numbered options — no exceptions.
+- **Every numbered list with `1. … 2. … 3. …`** is a numbered-options block, regardless of position. End-of-turn "Wie weiter?" / "What next?" / "How to proceed?" menus, mid-reply continuation prompts, and clarification blocks all count.
 - **Keep options short** — one line each, with a brief explanation after the dash.
 - **Always include a "skip" or "no change" option** when applicable.
-- **Always state a recommendation** — Iron Law 1 above.
+- **Always state a recommendation** — Iron Law 1 above. Per options block, every time, position-agnostic.
 - **Use the user's language** for the question and options.
 - **Accept both** the number and a natural language answer (e.g., "1" or "the first one").
 

package/.agent-src/scripts/update_roadmap_progress.py

@@ -16,6 +16,13 @@ Checkbox states:
 Percentage = done / (done + open). Deferred and cancelled do not count towards
 "open" (they are explicit decisions).
 
+Roadmap visibility is binary:
+
+  - No `status:` frontmatter (or `status: ready`) → executable, listed.
+  - `status: draft` → hidden from the dashboard entirely (not counted,
+    not listed). Drafts become visible the moment the frontmatter flag
+    is removed or flipped to `ready`.
+
 Invocation (from project root):
   python3 .augment/scripts/update_roadmap_progress.py              # rewrite
   python3 .augment/scripts/update_roadmap_progress.py --check      # CI: exit 1 if stale
@@ -56,6 +63,13 @@ EXCLUDE_NAMES = {"template.md", "README.md", "progress.md", "roadmaps-progress.m
 EXCLUDE_PREFIXES = ("open-questions",)
 EXCLUDE_DIRS = {"archive", "skipped"}
 
+# Frontmatter — minimal YAML block at the top of a roadmap. Used to hide
+# drafts (`status: draft`) from the dashboard. Anything else (no
+# frontmatter, `status: ready`, unknown values) counts as a normal
+# executable roadmap.
+FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\s*\n", re.DOTALL)
+DRAFT_VALUES = frozenset({"draft"})
+
 
 @dataclass
 class PhaseStats:
@@ -130,6 +144,37 @@ class RoadmapStats:
         return round(self.done * 100 / self.total_active) if self.total_active else 0
 
 
+def parse_frontmatter(text: str) -> dict[str, str]:
+    """Parse a leading YAML frontmatter block. String scalars only.
+
+    Returns an empty dict if no frontmatter is present. Handles quoted and
+    unquoted values; ignores blank lines and comments. Nested keys, lists,
+    and multiline scalars are out of scope — the dashboard only needs flat
+    string flags (`status`, `mode`).
+    """
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    fm: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        fm[key.strip()] = value.strip().strip('"').strip("'")
+    return fm
+
+
+def is_draft(fm: dict[str, str]) -> bool:
+    """Return True when frontmatter declares the roadmap as draft.
+
+    `status: draft` is the single supported way to hide a roadmap from
+    the dashboard. Everything else (no frontmatter, `status: ready`,
+    unknown values) counts as an executable roadmap.
+    """
+    return fm.get("status", "").lower() in DRAFT_VALUES
+
+
 def is_roadmap_candidate(path: Path) -> bool:
     if path.name in EXCLUDE_NAMES:
         return False
@@ -180,10 +225,14 @@ def bar(pct: int, width: int = 10) -> str:
 
 
 def collect(roadmap_root: Path) -> list[RoadmapStats]:
+    """Collect executable roadmaps. Drafts are excluded."""
     results: list[RoadmapStats] = []
     for path in sorted(roadmap_root.rglob("*.md")):
         if not path.is_file() or not is_roadmap_candidate(path):
             continue
+        text = path.read_text(encoding="utf-8")
+        if is_draft(parse_frontmatter(text)):
+            continue
         stats = parse_roadmap(path, roadmap_root)
         if stats:
             results.append(stats)
@@ -205,14 +254,17 @@ def render(roadmaps: list[RoadmapStats]) -> str:
     overall_pct = round(total_done * 100 / total_active) if total_active else 0
     lines: list[str] = []
     lines.append("# Roadmap Progress\n")
+    header_meta = (
+        f"> {len(roadmaps)} open roadmap"
+        f"{'s' if len(roadmaps) != 1 else ''}"
+        " · [roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · "
+        "[skipped/](roadmaps/skipped/)\n"
+    )
     lines.append(
         "> Auto-generated by `.augment/scripts/update_roadmap_progress.py`. "
         "Do not edit — regenerated on every roadmap-create, -execute, or "
         "completion change (last-modified timestamp lives in git history).\n>\n"
-        f"> {len(roadmaps)} open roadmap"
-        f"{'s' if len(roadmaps) != 1 else ''} · "
-        "[roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · "
-        "[skipped/](roadmaps/skipped/)\n"
+        + header_meta
     )
     lines.append("## Overall\n")
     lines.append(f"**{total_done} / {total_active} steps done · {overall_pct}%**\n")

package/.agent-src/skills/blade-ui/SKILL.md

@@ -8,7 +8,11 @@ source: package
 
 ## Positioning — dispatched, not standalone
 
-`blade-ui` is the **apply-step executor** for the Blade stack. 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. Does **not** own the flow, drive the audit, or lock the design.
+`blade-ui` is the **apply-step executor** for the Blade 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 |
 |---|---|
@@ -27,7 +31,7 @@ Cite this skill when:
 Do NOT use when:
 
 - API-only endpoints (use `api-endpoint` skill)
-- Livewire components (use `livewire` skill — composes Blade views internally)
+- Livewire components (use `livewire` skill — it composes Blade views internally)
 - Flux UI components (use `flux` skill)
 - Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
 
@@ -39,11 +43,11 @@ Do NOT use when:
 2. Inspect existing UI patterns — layouts, partials, component naming, CSS conventions.
 3. Check form handling style — old input, validation errors, session flashes, reusable field partials.
 4. Inspect neighboring templates — match indentation, directives, slot usage, classes.
-5. Determine data flow — controller/view model vs. template.
+5. Determine data flow — what belongs in controller/view model vs. template.
 
 ### Step 1: Create the template
 
-1. Use project's existing layout system.
+1. Use the project's existing layout system.
 2. Keep template presentation-focused — no business logic, no DB queries.
 3. Extract repeated sections into partials or components.
 
@@ -72,12 +76,27 @@ Do NOT use when:
 
 ### 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?}`. 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.
+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
 

package/.agent-src/skills/command-writing/SKILL.md

@@ -67,7 +67,7 @@ suggestion:                   # required (road-to-context-aware-command-suggesti
 ---
 ```
 
-Opt-out shape:
+Or, when opting out:
 
 ```yaml
 suggestion:
@@ -75,10 +75,21 @@ suggestion:
   rationale: "one-line reason this command must be invoked deliberately"
 ```
 
-Linter enforces ≥10-char triggers when eligible; rationale required when
-ineligible. Optional `confidence_floor` (0.0–1.0) and `cooldown` (e.g. `10m`)
-override the global settings per command. Eligibility decisions live in
+Suggestion-block rules (linter-enforced):
+
+* `eligible` is **required** and must be `true` or `false`.
+* `eligible: true` → both `trigger_description` and `trigger_context` must be
+  non-empty (≥ 10 chars each); the linter rejects empty or overly generic
+  patterns. The suggestion layer never auto-executes; the user always picks.
+* `eligible: false` → `rationale` must be non-empty. Use the opt-out for
+  intentional-only invocations (settings mutations, destructive actions,
+  package-internal tools, niche maintenance).
+* Optional `confidence_floor` (0.0–1.0) and `cooldown` (e.g. `10m`)
+  override the global settings per command.
+
+Eligibility decisions are tracked in
 [`agents/contexts/command-suggestion-eligibility.md`](../../../agents/contexts/command-suggestion-eligibility.md).
+Add or revise entries there before changing a command's `suggestion` block.
 
 When iterating on the description, delegate to the
 [`description-assist`](../description-assist/SKILL.md) skill — approval-gated,

package/.agent-src/skills/existing-ui-audit/SKILL.md

@@ -128,19 +128,31 @@ Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `ba
 
 ### 8. (Optional) Capture an a11y baseline
 
-R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline` when present; review gate filters incoming `state.ui_review.a11y.violations` against it so pre-existing violations stay informational and only NEW or CHANGED entries block polish loop. Without baseline gate sees every violation as actionable — fine for greenfield, noisy for legacy surfaces.
+The R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline`
+when present; the review gate then filters incoming
+`state.ui_review.a11y.violations` against it so pre-existing
+violations stay informational and only NEW or CHANGED entries block
+the polish loop. Without a baseline the gate sees every violation as
+actionable — fine for greenfield, noisy for legacy surfaces.
 
-Capture baseline when:
+Capture the baseline when:
 
-- Audit covers components with known a11y debt project does not intend to fix this run (legacy templates, third-party embeds, vendor widgets).
-- User says "don't block on existing a11y issues" or similar.
+- The audit covers components with known a11y debt the project does
+  not intend to fix in this run (legacy templates, third-party
+  embeds, vendor widgets).
+- The user says "don't block on existing a11y issues" or similar.
 
-Skip baseline (omit key, leave `state.ui_audit.a11y_baseline` unset) when:
+Skip the baseline (omit the key, leave `state.ui_audit.a11y_baseline`
+unset) when:
 
-- Surface is greenfield — review gate should treat every violation as new.
-- Project's a11y posture is "zero known violations" and any finding is by definition actionable.
+- The surface is greenfield — the review gate should treat every
+  violation as new.
+- The project's a11y posture is "zero known violations" and any
+  finding is by definition actionable.
 
-Shape (each entry MUST carry at least `rule` + `selector`; severity optional but recommended so review gate's severity-floor filter behaves same on replay):
+Shape (each entry must carry at least `rule` + `selector`; severity
+is optional but recommended so the review gate's severity-floor
+filter behaves the same on replay):
 
 ```
 state.ui_audit.a11y_baseline = [
@@ -150,7 +162,10 @@ state.ui_audit.a11y_baseline = [
 ]
 ```
 
-Producer parity: review skill that writes `state.ui_review.a11y.violations` MUST use same `(rule, selector)` shape, otherwise engine's de-dup will miss matches and pre-existing violations will surface as new findings on every run.
+Producer parity: the review skill that writes
+`state.ui_review.a11y.violations` MUST use the same `(rule, selector)`
+shape, otherwise the engine's de-dup will miss matches and pre-existing
+violations will surface as new findings on every run.
 
 ### 9. Validate and write findings
 

package/.agent-src/skills/fe-design/SKILL.md

@@ -8,7 +8,9 @@ source: package
 
 ## Positioning — reference, not executor
 
-`fe-design` is a **universal reference skill**, not an executor. Stack-agnostic heuristics that the UI directive set cites; does **not** own the flow.
+`fe-design` is a **universal reference skill**, not an executor. It carries
+stack-agnostic heuristics that the UI directive set cites; it does **not**
+own the flow.
 
 | Concern | Owner |
 |---|---|
@@ -35,7 +37,10 @@ Do NOT use this skill to:
 
 ## How the directive set cites this skill
 
-`directives/ui/design.py` produces the design brief (layout, components, states, microcopy, a11y). Brief picks heuristics from this reference when audit doesn't already pin a project pattern. Stack-specific choices come from the dispatched implementation skill.
+`directives/ui/design.py` produces the design brief (layout, components,
+states, microcopy, a11y). The brief picks heuristics from this reference
+when the audit doesn't already pin a project pattern. Stack-specific
+choices come from the dispatched implementation skill, not from here.
 
 ## Component Architecture
 
@@ -53,7 +58,8 @@ Page layout
 └── Footer (static)
 ```
 
-Stack-specific mapping (Blade partial vs. Livewire component vs. React island vs. Vue SFC) is the apply-step's concern.
+The stack-specific mapping (Blade partial vs. Livewire component vs.
+React island vs. Vue SFC) is the apply-step's concern, not this skill's.
 
 ### When to use what (kind, not framework)
 
@@ -69,7 +75,7 @@ Stack-specific mapping (Blade partial vs. Livewire component vs. React island vs
 
 - **One stateful component per concern** — don't build mega-components.
 - **Compose with reusable UI components** for shared shells, headers, fields.
-- **Use the project's library primitives first** — never rebuild what the design system provides (audit findings tell you which).
+- **Use the project's library primitives first** — never rebuild what the design system already provides (audit findings tell you which).
 - **Extract when used 3+ times** — DRY applies to UI too.
 
 ## Form Design
@@ -194,20 +200,20 @@ Step indicator (1 — 2 — 3)
 
 When `directives/ui/design.py` (or any caller) cites this skill:
 
-1. **Confirm audit ran first** — `state.ui_audit` from [`existing-ui-audit`](../existing-ui-audit/SKILL.md) is mandatory. Stop and request audit if missing.
-2. **Pick smallest matching section** — Component Architecture, Form Design, Table Design, Responsive Strategy, Accessibility, or UX Principles. Cite by H2/H3 heading, never paste whole skill.
-3. **Defer to audit findings** — when audit pins a project pattern (token, primitive, layout convention), use it. Heuristics here are fallbacks for gaps, not overrides.
-4. **Defer to stack apply skill** — Blade vs. Livewire vs. Flux vs. React-shadcn choices come from dispatched implementation skill, never from this reference.
-5. **Surface conflicts** — if heuristic here contradicts an audit finding or stack convention, name both and let caller decide; do not silently pick.
+1. **Confirm the audit ran first** — `state.ui_audit` from [`existing-ui-audit`](../existing-ui-audit/SKILL.md) is mandatory. Stop and request the audit if missing.
+2. **Pick the smallest matching section** — Component Architecture, Form Design, Table Design, Responsive Strategy, Accessibility, or UX Principles. Cite by H2/H3 heading, never paste the whole skill.
+3. **Defer to audit findings** — when the audit pins a project pattern (token, primitive, layout convention), use it. The heuristics here are fallbacks for gaps, not overrides.
+4. **Defer to the stack apply skill** — Blade vs. Livewire vs. Flux vs. React-shadcn choices come from the dispatched implementation skill, never from this reference.
+5. **Surface conflicts** — if a heuristic here contradicts an audit finding or stack convention, name both and let the caller decide; do not silently pick.
 
 ## Output format
 
 When this skill's content is folded into a design brief or review:
 
-1. Quote cited heuristic verbatim, with H2/H3 heading and one-line "why this applies" tie-back to request.
-2. Map each heuristic to a concrete artifact in brief (component, form section, table column, breakpoint rule, a11y check, UX state).
-3. Keep stack-agnostic — never name Blade/Livewire/Flux/React primitives in cited prose; apply step adds those.
-4. Mark anything overridden by audit findings as `[audit override]` and link to audit entry.
+1. Quote the cited heuristic verbatim, with the H2/H3 heading and a one-line "why this applies" tie-back to the request.
+2. Map each heuristic to a concrete artifact in the brief (component, form section, table column, breakpoint rule, a11y check, UX state).
+3. Keep stack-agnostic — never name Blade/Livewire/Flux/React primitives in the cited prose; the apply step adds those.
+4. Mark anything overridden by audit findings as `[audit override]` and link to the audit entry.
 
 ## Related
 
@@ -222,7 +228,7 @@ When this skill's content is folded into a design brief or review:
 
 ## Gotcha
 
-- Don't design components without running `existing-ui-audit` first — audit's component/token inventory is canonical for "what already exists in this project". Reinventing is the #1 failure mode.
+- Don't design components without running `existing-ui-audit` first — the audit's component/token inventory is the canonical source for "what already exists in this project". Reinventing is the #1 failure mode.
 - Heuristics in this reference apply across stacks; do not promote them to project rules without checking the audit.
 - Mobile-first is not optional — every layout must work on 320px width.
 
@@ -232,4 +238,3 @@ When this skill's content is folded into a design brief or review:
 - Do NOT use fixed pixel widths for responsive layouts.
 - Do NOT ignore accessibility requirements.
 - Do NOT use this skill as an executor — it is a reference cited by `directives/ui/design.py`.
-

package/.agent-src/skills/file-editor/SKILL.md

@@ -8,6 +8,8 @@ execution:
   allowed_tools: []
 ---
 
+<!-- cloud_safe: noop -->
+
 # file-editor
 
 ## When to use
@@ -127,3 +129,10 @@ code app/Models/User.php
 - Do NOT prompt the user about IDE settings during normal work — suggest `/onboard` (for first-run) or editing `.agent-settings.yml` directly.
 - Do NOT open files that were only read, not edited.
 - Do NOT open more than 10 files at once — summarize instead.
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this skill is **fully inert** —
+there is no local IDE to open files in, no `.agent-settings.yml` to read, and
+no shell handler available. The cloud agent simply finishes its edits and
+reports back; file-opening is a local-agent concern.

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

@@ -8,7 +8,11 @@ source: package
 
 ## Positioning — dispatched, not standalone
 
-`livewire` is the **apply-step executor** for the Livewire stack. 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. Does **not** own the flow, drive the audit, or lock the design.
+`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 |
 |---|---|
@@ -77,12 +81,27 @@ Do NOT use when:
 
 ### 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?}`. 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.
+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
 

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
 
@@ -246,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
@@ -271,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