@event4u/agent-config 1.13.0 → 1.15.0

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

@@ -7,95 +7,151 @@ source: package
 
 # User Interaction
 
-## Numbered Options — Always
+Two Iron Laws govern every reply that contains numbered options. They
+override conversation momentum, brevity, and the urge to defer to the
+user. **Missing a recommendation is a rule violation, not a slip.**
+
+## Iron Law 1 — Single-Source Recommendation
+
+```
+EXACTLY ONE LINE NAMES THE RECOMMENDED NUMBER. NO INLINE TAG. NO SECOND PROSE NUMBER.
+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
+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.
+- Directly after the options block, ONE line, bolded, in the user's language:
+  - English: `**Recommendation: N — <option-name>** — <why>. Caveat: <flip-condition>.`
+  - German:  `**Empfehlung: N — <option-name>** — <warum>. Caveat: <flip-bedingung>.`
+- Other numbers MAY appear later in the prose, but ONLY as caveats
+  (`escalate to 3 if …`, `flip to 1 when …`). NEVER as a primary recommendation.
+- If the agent genuinely cannot pick (rare — true 50/50 with missing data),
+  say what data would break the tie and ask for that instead.
 
-When asking the user a question with predefined choices, **always present numbered options**.
-The user should be able to reply with just a number (e.g., `1`) instead of typing a sentence.
+**What does NOT count as a recommendation:**
 
-### Format
+- "Both work" / "either is fine" / "depends on what you prefer"
+- Listing pros and cons without picking a number
+- "I'd lean towards X" without a reason
+- Hiding behind "you know the project better"
+- Inline `(recommended)` tag with no follow-up `Recommendation: N` line
+
+**Slip handling — same protocol as [`language-and-tone`](language-and-tone.md#when-the-user-calls-out-a-language-slip).**
+User calls out a missing or wrong recommendation → acknowledge once
+in the user's language, rewrite the reply with a recommendation,
+ship. No "from now on" promises — only the next reply proves
+compliance.
+
+## Iron Law 2 — Pre-Send Self-Check
 
 ```
-> 1. First option — brief explanation
-> 2. Second option — brief explanation
-> 3. Third option — brief explanation
+EVERY REPLY WITH NUMBERED OPTIONS RUNS THE SELF-CHECK. NO EXCEPTIONS.
+SKIPPING IT IS A RULE VIOLATION, NOT A SLIP.
 ```
 
-### Rules
+Before emitting any reply that contains numbered options, scan the
+**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:
 
-- **Every question with choices** must use numbered options — no exceptions.
-- **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** — see iron law below.
-- **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").
+1. Count occurrences of `(recommended)` / `(rec)` / `(empfohlen)` inline next to a numbered option → MUST be **zero**. Found one → rewrite, drop the tag.
+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.
 
-### Iron Law — ALWAYS recommend
+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.
 
-```
-EVERY numbered-option question MUST state which option the agent recommends and WHY.
-"Egal, was bevorzugst Du?" / "no preference" is NEVER an acceptable agent stance.
-```
+### Common failure modes — known, named, no excuses
 
-The user is asking the agent because the agent has read the code, the
-contracts, the trade-offs. Refusing to take a position dumps that work
-back on the user. Take the position; be wrong out loud if needed.
+- **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.
 
-**Format:**
+## Numbered Options — Always
 
-- Mark the recommended option inline: `1. Do X — short explanation (recommended)`.
-- After the option block, state **WHY** in 1–3 sentences: the trade-off
-  that tips the balance, plus the **caveat** that would flip it.
-- If the agent genuinely cannot pick (rare — true 50/50 with missing
-  data), say what data would break the tie and ask for that instead.
+When asking the user a question with predefined choices, **always
+present numbered options**. The user should be able to reply with
+just a number (e.g., `1`) instead of typing a sentence.
 
-**Example:**
+### Format
 
 ```
-> 1. Hybrid contract — keys + query (recommended)
-> 2. Key-based — extend the package
-> 3. Semantic — change all call sites
+> 1. First option — brief explanation
+> 2. Second option — brief explanation
+> 3. Third option — brief explanation
 
-I recommend 1: solves the acute consult-flow without a cross-repo PR,
-and the file-fallback stays trivial. Caveat — if hit-rate on the
-concat-shim turns out poor in practice, escalate to 2.
+**Recommendation: 2 — Second option** — <one-sentence reason>. Caveat: <flip-condition>.
 ```
 
-**What does NOT count as a recommendation:**
+### Rules
 
-- "Both work" / "either is fine" / "depends on what you prefer"
-- Listing pros and cons without picking
-- "I'd lean towards X" without a reason
-- Hiding behind "you know the project better" (the agent just researched it)
+- **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. 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").
 
 ### Examples
 
-**Binary choice (with recommendation):**
+**Binary choice:**
+
 ```
-> 1. Interactive — ask before each comment (recommended)
+> 1. Interactive — ask before each comment
 > 2. Automatic — handle all independently
 
-I recommend 1: the comments touch security-sensitive code, so a wrong
-auto-fix is more expensive than the friction of approving each one.
-Switch to 2 if the comments turn out to be pure formatting.
+**Recommendation: 1 — Interactive** — the comments touch security-sensitive code,
+so a wrong auto-fix is more expensive than approving each one. Caveat: flip to 2
+if the comments turn out to be pure formatting.
 ```
 
-**Multiple choice with skip (with recommendation):**
+**Multiple choice with skip:**
+
 ```
-> 1. Fix the code (recommended)
+> 1. Fix the code
 > 2. Fix the test
 > 3. Skip
 
-I recommend 1: the test is asserting the documented behavior; the
-production code drifted from the contract. Pick 2 only if the contract
+**Recommendation: 1 — Fix the code** — the test asserts the documented behaviour;
+the production code drifted from the contract. Caveat: pick 2 only if the contract
 itself is wrong.
 ```
 
-**Confirmation with context (recommendation implicit in framing):**
+**Confirmation with context:**
+
 ```
 > Found PR #1399 on branch `chore/refactor-agent-setup-2`.
 >
-> 1. Yes, that's the right PR (recommended — branch matches)
+> 1. Yes, that's the right PR
 > 2. No, different PR — I'll provide the URL
+
+**Recommendation: 1 — Yes** — the branch name matches the PR title exactly.
+Caveat: flip to 2 if the PR was reopened from a different branch.
 ```
 
 ### When NOT to use numbered options

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:
@@ -73,6 +87,10 @@ class PhaseStats:
     def total_active(self) -> int:  # denominator for %
         return self.done + self.open_
 
+    @property
+    def total_all(self) -> int:  # all checkboxes incl. deferred + cancelled
+        return self.done + self.open_ + self.deferred + self.cancelled
+
     @property
     def percent(self) -> int:
         return round(self.done * 100 / self.total_active) if self.total_active else 0
@@ -117,11 +135,46 @@ class RoadmapStats:
     def total_active(self) -> int:
         return self.done + self.open_
 
+    @property
+    def total_all(self) -> int:
+        return self.done + self.open_ + self.deferred + self.cancelled
+
     @property
     def percent(self) -> int:
         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
@@ -172,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)
@@ -197,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")
@@ -213,12 +273,16 @@ def render(roadmaps: list[RoadmapStats]) -> str:
         lines.append("_No open roadmaps._\n")
         return "\n".join(lines) + "\n"
     lines.append("## Open roadmaps\n")
-    lines.append("| # | Roadmap | Phases | Steps | Done | Open | Deferred | Cancelled | Progress |")
+    # Steps = ALL checkboxes (done + open + deferred + cancelled) so the row
+    # arithmetic adds up: Steps − Done − Deferred − Cancelled = Open. Open
+    # comes before Done by design — at-a-glance "what's left to do" first,
+    # historical "what's behind us" second.
+    lines.append("| # | Roadmap | Phases | Steps | Open | Done | Deferred | Cancelled | Progress |")
     lines.append("|---|---|---:|---:|---:|---:|---:|---:|---|")
     for i, r in enumerate(roadmaps, 1):
         lines.append(
-            f"| {i} | [{r.rel}](roadmaps/{r.rel}) | {len(r.phases)} | {r.total_active} | "
-            f"{r.done} | {r.open_} | {r.deferred} | {r.cancelled} | "
+            f"| {i} | [{r.rel}](roadmaps/{r.rel}) | {len(r.phases)} | {r.total_all} | "
+            f"{r.open_} | {r.done} | {r.deferred} | {r.cancelled} | "
             f"{bar(r.percent)} {r.percent}% |"
         )
     lines.append("")
@@ -227,11 +291,11 @@ def render(roadmaps: list[RoadmapStats]) -> str:
     for r in roadmaps:
         lines.append(f"### [{r.rel}](roadmaps/{r.rel})\n")
         lines.append(f"**{r.title}** — {r.done} / {r.total_active} done ({r.percent}%)\n")
-        lines.append("| # | Phase | State | Done | Open | Deferred | Cancelled | % |")
+        lines.append("| # | Phase | State | Open | Done | Deferred | Cancelled | % |")
         lines.append("|---|---|---|---:|---:|---:|---:|---:|")
         for p in r.phases:
             lines.append(
-                f"| {p.id} | {p.name} | {p.state} | {p.done} | {p.open_} | "
+                f"| {p.id} | {p.name} | {p.state} | {p.open_} | {p.done} | "
                 f"{p.deferred} | {p.cancelled} | {p.percent}% |"
             )
         lines.append("")

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

@@ -1,19 +1,39 @@
 ---
 name: blade-ui
-description: "Use when creating or editing Blade views, components, partials, layouts, or view logic — even when the user says 'add a new page' or 'render this data' without naming Blade."
+description: "Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic."
 source: package
 ---
 
 # blade-ui
 
+## Positioning — dispatched, not standalone
+
+`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 |
+|---|---|
+| 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) |
+| Review + polish loop | [`directives/ui/review.py`](../../templates/scripts/work_engine/directives/ui/review.py) + [`polish.py`](../../templates/scripts/work_engine/directives/ui/polish.py) |
+
 ## When to use
 
-Use when creating or editing Blade views, components, partials, layouts, or forms.
+Cite this skill when:
+
+- `state.stack.frontend == "blade"` (or the project is clearly Blade-only without Livewire / Flux) and `directives/ui/apply.py` dispatches to this skill
+- Editing or creating Blade views, components, partials, layouts, or forms
 
 Do NOT use when:
+
 - API-only endpoints (use `api-endpoint` skill)
-- Livewire components (use `livewire` skill)
+- 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
 
 ## Procedure: Create Blade view or component
 
@@ -54,6 +74,30 @@ Do NOT use when:
 1. Blade view or component file(s) following project conventions
 2. Component class (if applicable) with typed props
 
+### 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
 
 - `@include` shares parent scope — components don't. Know the difference.

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

@@ -40,6 +40,38 @@ Only ask the user if inference fails and the command cannot proceed without the
 | `.augment/commands/` | Shared commands (work across projects) |
 | `agents/overrides/commands/` | Project-specific overrides (used instead of original) |
 
+## Commands that dispatch to a Python engine
+
+Most commands are pure markdown procedures — the agent reads the steps
+and executes them. Two commands delegate to the `work_engine` Python
+module via the `./agent-config` dispatcher; both share the same
+Option-A loop (read state → run engine → handle exit code → repeat),
+they only differ in the input envelope they build:
+
+| Command | Subcommand | Envelope | Use when |
+|---|---|---|---|
+| `/implement-ticket` | `./agent-config implement-ticket` | `input.kind="ticket"` | User points at a Jira/Linear ticket or supplies a structured ticket payload |
+| `/work` | `./agent-config work` | `input.kind="prompt"` | User supplies a free-form prompt — no ticket id, no acceptance criteria yet |
+
+Route prompt-shaped intents (`"add a CSV export endpoint…"`,
+`"fix the failing login test"`, `"refactor the audit-log controller"`)
+to `/work`. Route ticket-shaped intents
+(`"work on PROJ-123"`, `"start on the ticket on this branch"`) to
+`/implement-ticket`. If the user pastes both a ticket id **and** a
+free-form goal, prefer `/implement-ticket` and let it pull the AC from
+the ticket — `/work` is the fallback when no ticket exists.
+
+The actual step logic, halt formats, scoring breakdowns, and delivery
+report are emitted by the engine. Do not paraphrase or reorder engine
+output — surface it as-is. The two flows are mutually exclusive at the
+state-file level: one `.work-state.json` carries one envelope at a
+time, and the engine refuses to switch mid-flight.
+
+A sibling subcommand `./agent-config migrate-state` upgrades a legacy
+`.implement-ticket-state.json` file to the v1 `.work-state.json`
+schema. The wrapper invokes it automatically when the legacy file is
+detected; agents should not bypass the dispatcher.
+
 ## GitHub API: Replying to PR review comments
 
 When commands reply to PR review comments (e.g. `/fix-pr-bot-comments`):

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

@@ -4,6 +4,8 @@ description: "Use when creating or editing a slash command in .agent-src.uncompr
 source: package
 ---
 
+<!-- cloud_safe: degrade -->
+
 # command-writing
 
 ## When to use
@@ -58,9 +60,37 @@ name: {command-name}          # must match filename without .md
 description: "Short human-readable summary of what /{name} does"
 disable-model-invocation: true
 skills: [optional-skill-1]    # optional — skills this command delegates to
+suggestion:                   # required (road-to-context-aware-command-suggestion Phase 2)
+  eligible: true              # default; set false to opt out of auto-surfacing
+  trigger_description: "natural-language pattern, comma-separated examples"
+  trigger_context: "concrete signal — branch name, file pattern, recent tool output"
 ---
 ```
 
+Or, when opting out:
+
+```yaml
+suggestion:
+  eligible: false
+  rationale: "one-line reason this command must be invoked deliberately"
+```
+
+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,
 no silent edits, max two rounds.
@@ -105,8 +135,8 @@ multi-paragraph explanation, extract it into a skill and call it.
 * Run `bash scripts/compress.sh --sync` → regenerates `.agent-src/commands/{name}.md`.
 * Run `python3 scripts/compress.py --generate-tools` → creates the Claude symlink at
   `.claude/skills/{name}/SKILL.md`.
-* Run the full CI pipeline locally — each script directly — must exit 0
-  except for tolerated warnings.
+* Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
+  the script list) — must exit 0 except for tolerated warnings.
 
 ## Output format
 
@@ -133,6 +163,26 @@ multi-paragraph explanation, extract it into a skill and call it.
 * Do NOT edit `.agent-src/`, `.augment/`, or `.claude/` projections
 * Do NOT exceed the hard size limit without a waiver
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's
+`scripts/skill_linter.py`, `scripts/compress.py`, and the `task`
+runner are not available. This skill still applies — but with
+prose-only validation:
+
+* Emit the full command file as a copyable Markdown block. Do not
+  attempt to write it to disk.
+* Self-check the frontmatter against the rules below — `name`,
+  `description`, `disable-model-invocation: true` MUST all be
+  present.
+* Self-check the body shape: numbered steps, explicit safety gates,
+  no inline skill-level detail.
+* Tell the user to save the file under
+  `.agent-src.uncompressed/commands/{name}.md` and run
+  `task sync && task lint-skills` locally before committing.
+* Skip every reference to running the linter, compressor, or
+  generators yourself — they only run on the user's machine.
+
 ## Examples
 
 Good description (trigger-shaped, outcome-focused):

package/.agent-src/skills/description-assist/SKILL.md

@@ -4,6 +4,8 @@ description: "Use when polishing a skill/rule/command/guideline frontmatter desc
 source: package
 ---
 
+<!-- cloud_safe: degrade -->
+
 # description-assist
 
 ## When to use
@@ -155,6 +157,25 @@ and stop. Do not loop further.
 * Do NOT run `scripts/skill_trigger_eval.py` from inside this skill — eval
   execution spends API tokens and is a separate user action
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's
+`scripts/audit_skill_descriptions.py`, `scripts/skill_linter.py`,
+and `scripts/skill_trigger_eval.py` are not reachable. The skill
+still applies — with prose-only inspection:
+
+* Reason from the description text in the conversation. The agent
+  acts as the inspector; no separate audit pass runs.
+* Apply the same checklist used by the local audit: length budget,
+  trigger prefix ("Use when …"), domain class, symptom class,
+  undertrigger tail.
+* Emit verdict + up to 3 numbered variants. The user picks; the
+  agent emits the new frontmatter as a copyable block.
+* Skip every reference to running the audit or trigger-eval scripts.
+  Recommend the user run the package's local linter after applying.
+* Never claim a description has been "graded" or "scored" by an
+  external pass — there isn't one.
+
 ## Examples
 
 Inspection verdict (good — compact):

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

@@ -182,5 +182,4 @@ copy-paste instructions if missing.
 - [`refine-ticket`](../refine-ticket/SKILL.md) — sibling; refine first if the ticket is vague
 - [`jira-ticket`](../../commands/jira-ticket.md) — ticket loader
 - [`feature-plan`](../../commands/feature-plan.md) — downstream planning
-- [`road-to-ticket-refinement.md`](../../../agents/roadmaps/road-to-ticket-refinement.md) — governing roadmap
 - [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — drafting protocol