@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/guidelines/agent-infra/artifact-drafting-protocol-mechanics.md

@@ -0,0 +1,222 @@
+# Artifact Drafting Protocol — Mechanics
+
+> Phase A/B/C detail and the roadmap batch-mode carve-out for the `artifact-drafting-protocol` rule
+
+_Origin: migrated from `src/rules/artifact-drafting-protocol.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, the trigger surface, and the golden rules stay in the rule; this file carries the per-phase procedure._
+
+## Phase A — Understand
+
+**Question zero, asked first: should this artifact exist at all?**
+
+Before the five below, put the extend-versus-create question to the user —
+*is there an existing artifact this belongs in?* It used to live in Phase B,
+after the research, and it was measured moving: one source found that the same
+stop placed after work had begun was passed straight through, because mid-build
+momentum beats restraint. A stop that only fires once you are invested is a stop
+that does not fire.
+
+Asking it first costs one question and is answerable without the research: the
+user usually knows whether they are extending something. Phase B still runs the
+overlap scan — that is what turns a guess into a verdict — but it now *confirms
+or overturns* an answer already on the record rather than raising the question
+for the first time at the point where a draft is half-formed.
+
+Ask up to **5** further clarifying questions (numbered options, each with a
+*"skip / I don't know yet"* escape):
+
+1. **Problem** — what does this solve that no existing artifact solves?
+2. **Trigger surface** — which user phrasings should fire this?
+3. **Should-trigger examples** — 2-3 in the user's words.
+4. **Near-miss cases** — 2-3 phrasings that must **not** fire.
+5. **Artifact type** — skill, rule, command, or guideline? Offer a
+   3-line primer if unsure.
+
+If the user skips Q1 or Q5, stop and surface the ambiguity — don't guess.
+
+## Phase B — Research
+
+Run the **search protocol** from
+[`learning-to-rule-or-skill` § 4](../../skills/learning-to-rule-or-skill/SKILL.md)
+— `ls` all four surfaces (`skills/`, `rules/`, `guidelines/`, `commands/`),
+grep with **solution-words AND problem-words**, scan sub-directory
+taxonomies, then **open and skim** the 3 nearest matches. A negative grep
+alone is not proof of no overlap. Report the top 3-5 most-similar
+artifacts and ask (numbered options) — this **confirms or overturns** the
+question-zero answer from Phase A with evidence, rather than raising it for the
+first time:
+
+- Extend an existing one?
+- Create a new one — gap is real?
+- Show overlap first?
+- Promote via `learning-to-rule-or-skill` instead?
+
+A Phase-B verdict that contradicts the Phase-A answer is the useful outcome, not
+an embarrassment: it is the research doing its job. Surface the contradiction
+and let the user re-decide.
+
+Carry the summary into the commit message (*"Reviewed before drafting:
+X, Y"*).
+
+### Where the answer is written — `composition_review:`
+
+A commit message is not a tree artifact. Measured 2026-08-27 over the twenty most
+recently added skills and rules
+(`agents/evidence/analysis/authoring-search-record-sample-2026-08-27.md`), **1 of
+20** carried a machine-readable record of the Phase-B verdict; 9 carried a strict
+prose one, and the rest carried a `See also` gloss or a routing row. So an
+artifact authored after a thorough scan and one authored after none were
+indiscernible in the tree — which is why the overlap tools
+(`audit_overlap`, `audit_skill_overlap`, `report_layer_overlap`) run over a
+corpus rather than over a decision.
+
+The record is a frontmatter block, defined in `skill.schema.json` and
+`rule.schema.json`, and **optional on existing artifacts by design — nothing is
+backfilled**:
+
+```yaml
+composition_review:
+  - candidate: skill:existing-ui-audit      # skill: / rule: / command: / guideline: / none
+    disposition: create_separate            # what happened to this candidate
+    rationale: audits what exists before a write; this governs the write itself
+```
+
+Four dispositions, and the discriminator for each:
+
+| Value | Means |
+|---|---|
+| `extend_incumbent` | the incumbent absorbed the change; no new artifact was created |
+| `compose_with_incumbent` | the new artifact routes to the incumbent rather than restating it |
+| `create_separate` | the incumbent exists, was evaluated, and a separate artifact was authored anyway |
+| `none_found` | the search ran and found no credible incumbent — pairs only with `candidate: none` |
+
+`none_found` exists so an author is never pushed to **invent** an incumbent to
+satisfy the schema. That failure would manufacture the pro-forma record the
+mechanism is supposed to measure, using the mechanism.
+
+`create_separate` is the value no other disposition vocabulary in this tree can
+express, and it is why this is a fifth enum rather than a reuse. The nearest
+incumbent is the harvest ledger's `adopt | adapt`
+(`lint_harvest_provenance.ts:76`), which deliberately **excludes** rejection
+(`:222`) because a rejected harvest has no artifact to cite. This record is the
+mirror image — it is written *on* the artifact being created — so rejection is
+the value it most needs. The finding, review and archive vocabularies are about
+defects, review rows and roadmap files respectively; none of them has a slot for
+"an incumbent existed and I built anyway".
+
+**What the lint does and does not do.** `lint_composition_review` fails a record
+whose `candidate` resolves to no artifact, or whose `none` / `none_found` pair
+disagrees — a record naming an incumbent that is not in the tree reads as
+evidence of a search that cannot have happened. It *reports without failing* an
+addition carrying no record at all. It cannot check that the search happened,
+that the rationale is true, or that the named incumbent is the nearest one;
+flipping the advisory half to a block needs a false-positive rate from at least
+one release of advisory operation, which does not exist yet.
+
+## Phase C — Draft
+
+Propose **2-3 description variants** — Conservative / Pushy
+(per `skill-quality`) / Concrete (embedded trigger example). User picks
+or merges. Only then draft the body. Surface every structural choice
+(size class, section order) as numbered options if in doubt.
+
+Enforce size live: *"Body is at 420/500 lines. Split?"* (budgets per
+`size-enforcement`). New skills also get an `evals/triggers.json` stub
+(5 should-trigger + 5 should-not-trigger). See `skill-writing` § 1c.
+
+## Roadmap-run batch mode — the ONE structured bypass
+
+When a `/roadmap:process-*` run starts under an **accepted execution
+contract** (`roadmap-execution-contract`) whose pre-scan detected
+artifact-authoring steps, the protocol runs in batch mode for exactly
+those artifacts:
+
+- **Phase B (Research) runs ONCE at contract time, against the CURRENT
+  artifact state** — one overlap scan covering every artifact the
+  roadmap plans; results (nearest matches, extend-vs-create verdicts)
+  are surfaced inside the contract summary the user accepts. This is
+  why authoring-time-only checking is not enough: a sibling roadmap may
+  have landed overlapping artifacts between authoring and execution.
+- **Phases A (Understand) and C (Draft) run non-interactively during
+  the run** — the roadmap step text is the Understand input; the
+  contract acceptance is the approval that the per-phase prompts exist
+  to obtain.
+- **Scope is the batch, nothing more.** An artifact NOT declared in the
+  roadmap (discovered mid-run) triggers the full interactive protocol —
+  or, under the contract, the scope-out-of-roadmap halt. That halt is the
+  **default** and stays the default; see § Late artifacts below for the one
+  declared value that changes it.
+- Batch mode never skips the Research pass itself — it relocates and
+  batches it. `artifact_protocol: skip` does not exist.
+
+### Late artifacts — `halt` by default, `auto-research` only when declared
+
+The bullet above is the whole rule when the contract says nothing. A contract
+may instead declare `late_artifacts: auto-research`
+([`roadmap-execution-contract § 2a`](../../contexts/execution/roadmap-execution-contract.md)),
+and then a mid-run discovery runs **this** procedure rather than halting:
+
+1. **Re-run Phase B against current state** — the same overlap scan the batch
+   ran at contract time, now over the artifact the run just found. Nothing new
+   is invented: this is the accepted-as-non-interactive procedure, later.
+2. **Extend verdict → extend silently.** The nearest match is edited. This is
+   the outcome the overlap scan exists to produce and it needs no approval it
+   did not already have.
+3. **Create verdict → derive Phase A from what is already on the record.** The
+   understand-answers come from the roadmap step text plus the decision-sheet
+   answers the user accepted. No new question is opened.
+4. **Genuine overlap conflict → halt.** Two plausible extend targets, or a
+   match whose scope contradicts the step, is a real decision and stops the
+   run.
+5. **Cap: three per run, then halt regardless of verdict.**
+
+`halt` remains the shipped default (`decision 2026-08-20`, AI council 2/2 on
+the `autonomy-defaults-sheet` fork; record
+`agents/evidence/council/drain-blocker-dispositions-a.md`). The reasoning is
+short: the cap bounds how far an unplanned artifact can drift the run, but it
+does not decide whether the drift is wanted, and the conservative side of that
+fork is the behaviour the tree already had. Making `auto-research` a declared
+value rather than an inherited one is also what makes its own kill criterion —
+the late-artifact revisit rate — attributable to the runs that chose it.
+Reverting is one word in each of the two tables; no mechanism depends on the
+default's direction.
+
+**Kill criterion for `auto-research`, at the site rather than in a roadmap:**
+a late-artifact revisit rate above 20 % — an auto-authored or auto-extended
+artifact later reworked or reverted — removes the value and returns every
+late discovery to `halt`. **No instrument today:** nothing counts late
+artifacts or their revisits, so the rate is unmeasured rather than low, and
+the cap of three is the only live bound. Recorded here because a criterion
+that lives only in the roadmap that flipped the default becomes unreachable
+the moment that roadmap is archived.
+
+
+## Complexity budget — the six questions before a new artifact
+
+Folded here from the 9.4.0 review (Prio 5), which named the failure mode:
+"das Paket kann fast jede Kritik mit einem weiteren Mechanismus beantworten"
+(Problem → Regel → Lint → Hook → Report → Roadmap → Claim → Test = governance
+inflation). This REPLACES the ad-hoc "should this exist" prose — it is a
+checklist, not a new gate/rule (adding a gate to enforce "add less" would be
+the very inflation it guards against). Before drafting any new skill / rule /
+command / hook / gate, answer all six; a "no" on **replaces** or **removable**
+is a strong signal to fold into an existing artifact instead:
+
+1. **Replaces?** — what existing mechanism does this retire or subsume? (If
+   nothing, justify why the surface must grow.)
+2. **Overlaps?** — does it duplicate a trigger / responsibility another
+   artifact already owns?
+3. **Discoverable?** — will a user actually find it, or does it just raise the
+   catalog count?
+4. **Measurable?** — is there a signal that would show it earning its place
+   (or a null that would retire it)?
+5. **Removable?** — can it be demoted / de-eligibled / deleted later without a
+   migration?
+6. **Who debugs it?** — is the maintenance owner real, given bus-factor?
+
+The load-bearing question the review elevates: not "how do we prevent this
+error in future?" but **"which existing mechanism gets removed or replaced?"**
+
+## See also
+
+- `artifact-drafting-protocol` (rule) — Iron Law, triggers, golden rules.
+- `ask-when-uncertain` · `improve-before-implement` · `user-interaction` · `skill-quality` — the protocol extends these; cross-link, don't restate.

package/dist/agent-src/guidelines/agent-infra/ask-when-uncertain-demos.md

@@ -0,0 +1,134 @@
+---
+demo_for: ask-when-uncertain
+layer: pattern-memory
+prose_delta:
+  rule_chars_before: 3893
+  rule_chars_after: 4267
+  measured_at: phase-3.3-cross-link-landing
+  note: "+374 chars from the Examples cross-link block; future prose-pruning rounds (out of scope for Phase 3) will pull pattern prose from the rule into this demo and drive the after-count below the before-count."
+---
+
+# ask-when-uncertain — Pattern Memory
+
+> Wrong / right / why demos for the `ask-when-uncertain` Iron Law
+> (one question per turn, vague-request must ask). Linked from
+> [`ask-when-uncertain`](../../rules/ask-when-uncertain.md)
+> § Examples. Outcome baseline at
+> [`tests/golden/outcomes/ask_when_uncertain.json`](../../../tests/golden/outcomes/ask_when_uncertain.json).
+
+## Demo 1 — Vague request, multi-question stack
+
+### Wrong shape
+
+```
+User: improve this
+
+Agent:
+1. Should I optimize for readability or speed?
+2. Refactor the function signature?
+3. Add tests too?
+4. Run PHPStan after?
+
+Reply with a, b, c, d so I can pick.
+```
+
+**Failure mode:** four `?` aimed at the user, structured-answer
+demand (`a, b, c, d`), no triage. Iron Law breach: a turn with a
+question has *exactly one*. Compound thinking load — answer to Q1
+reframes Q2.
+
+### Right shape
+
+```
+User: improve this
+
+Agent: Welche Achse soll "improve" treffen?
+
+1. Lesbarkeit (Naming, Funktions-Splits)
+2. Performance (Allokationen, N+1)
+3. Robustheit (Error-Handling, Edge Cases)
+
+Dann lege ich los.
+```
+
+### Why it works
+
+Single `?`, numbered options without compound asks, picks the
+question whose answer reframes everything downstream. The follow-up
+("tests? PHPStan?") rides on the next turn — its framing depends on
+the answer here.
+
+## Demo 2 — Drive-by execution on a vague trigger
+
+### Wrong shape
+
+```
+User: clean up this file
+
+Agent: [edits 12 files, removes 200 lines, reformats imports,
+extracts 3 helpers, renames 5 variables]
+Done.
+```
+
+**Failure mode:** "clean up" is a vague-request trigger
+(`ask-when-uncertain` § Vague-request triggers). MUST-ask before
+touching code. Without scope, the diff is a guess at the user's
+intent.
+
+### Right shape
+
+```
+User: clean up this file
+
+Agent: Was bedeutet "clean up" hier?
+
+1. Toten Code raus
+2. Format / Imports sortieren
+3. Refactor (Funktionen splitten)
+
+Pick one — sonst ist der Diff Raten.
+```
+
+### Why it works
+
+Names the trigger explicitly ("vague-request"), surfaces the three
+canonical interpretations from the rule's trigger table, and
+declines to act without scope. The cost of asking once << cost of
+ripping through 12 files in the wrong direction.
+
+## Demo 3 — Stacked questions inside a handoff
+
+### Wrong shape
+
+```
+Agent: Bevor ich die Roadmap übergebe:
+
+- Welcher Branch?
+- Soll ich PRs erwähnen?
+- Welches Modell für die Fortsetzung?
+- Soll ich agents/runtime/.agent-chat-history zitieren?
+
+Antworte als 1, 2, 3, 4.
+```
+
+**Failure mode:** four-question handoff block. Per § Ordering &
+handoff: handoff questions ride LAST, after domain clarifications,
+folded into the handoff prompt itself — not as a parallel quiz.
+
+### Right shape
+
+```
+Agent: [delivers the handoff prompt with sensible defaults filled
+in: current branch, PR link present if open, model
+recommendation per `model-recommendation`, history reference
+auto-included]
+
+Welche der vier Defaults soll ich vor dem Übergeben anpassen?
+```
+
+### Why it works
+
+Defaults absorb three of the four "questions"; the remaining
+question is the only one that genuinely needs user input — and it's
+phrased so a one-word answer ("PR link" / "model" / "passt") closes
+the loop.

package/dist/agent-src/guidelines/agent-infra/asking-and-brevity-examples.md

@@ -0,0 +1,198 @@
+# asking-and-brevity-examples
+
+Companion examples for three always-rules:
+[`ask-when-uncertain`](../../rules/ask-when-uncertain.md),
+[`no-cheap-questions`](../../rules/no-cheap-questions.md),
+[`direct-answers`](../../rules/direct-answers.md).
+
+The rules carry the Iron Laws and the obligation surface. This file
+carries the illustrative material (example questions, rationale
+tables, failure-mode catalogs) that does not need to live in the
+always-loaded rule body — extracted to fit the always-rule budget.
+
+## Vague-request triggers — example questions
+
+Companion to `ask-when-uncertain` § Vague-request triggers. This
+section is the canonical home for the nine trigger patterns, the
+missing-info each one hides, and the example clarifying question —
+the rule cites it instead of restating the catalog.
+
+| Pattern | Missing info | Example clarifying question |
+|---|---|---|
+| "improve / optimize this" | metric — speed, readability, memory? | "Optimize for what — execution speed or readability?" |
+| "add caching" | store, scope, invalidation | "Which cache driver, and what invalidates it?" |
+| "make it better / cleaner" | by what standard? | "What specifically feels wrong in the current code?" |
+| "clean up this file" | dead code, format, refactor? | "Remove unused code, reformat, or restructure?" |
+| "fix this" (no symptom) | what output is wrong? | "What output/behavior is wrong right now?" |
+| "refactor X" | target pattern, boundaries | "Refactor toward what — smaller methods, extract class, or something else?" |
+| "use best practices" | whose, for what? | "Best practices for what specifically — testing, naming, structure?" |
+| "handle errors properly" | which errors — log/retry/propagate? | "For which failure modes, and what should happen on error?" |
+| "add a UI / component / tile / page" in mixed-framework repo | which stack? | "This repo uses {A} and {B} for UI — which one for this?" |
+
+## One-question-per-turn — why serial always wins
+
+Companion to `ask-when-uncertain` § How to ask. The rule states the
+Iron Law and the self-check; this file expands the rationale.
+
+| Situation | Why serial always wins |
+|---|---|
+| Design / architecture decisions | Answer to Q1 reframes Q2 |
+| Naming / command-syntax / API shape | Later choices depend on it |
+| Scope / PR boundaries | Changes what the other questions even mean |
+| Tool / library selection | Downstream choices branch from it |
+| "Which approach: A vs B vs C" | Each answer opens a different follow-up |
+| Even "independent" yes/no pairs | User still has to parse two contexts |
+| Any question the user has to **think** about, not just pick | Thinking load compounds when stacked |
+
+The shorthand: if the user has to *think* about an answer, that
+answer almost always reframes whatever question would have come
+next. Serial preserves the framing; parallel destroys it.
+
+## Cheap-question class catalog — extended examples
+
+Companion to `no-cheap-questions` § What counts as cheap. This
+section is the canonical home for the nine cheap-question classes
+and their per-class patterns — the rule cites it instead of
+restating the catalog.
+
+| Class | Pattern · why cheap | Concrete example |
+|---|---|---|
+| **Sequencing** | "Step 2 or 3 next?" when roadmap orders them — answer is in the roadmap | Roadmap says "2.1 then 2.2" → don't ask "should I do 2.2 next?" |
+| **Format-only** | "Table or paragraph?" — no semantic trade-off | User asked for a summary; format is a non-decision |
+| **Commit asks** | "Commit now?" — `commit-policy`: never ask | The commit-policy Iron Law forbids the question |
+| **CI / test asks** | "Run tests now?" — `verify-before-complete` decides | Verification is mandatory before completion claims; not a choice |
+| **Fenced-step re-asks** | "Start Phase 1?" after "plan only" — `scope-control § fenced step` | The fence stands until the user explicitly lifts it |
+| **Iron-Law option** | Option breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default` — does not exist | Don't surface "force-push to main?" as Option 2 |
+| **Context-derived** | Answer follows from prior turn / standing instruction / roadmap — act, state assumption inline | "Use the same branch?" after user said "stay on this branch" |
+| **Dominant option** | One choice obviously correct; alternatives carry no upside — pick it | "Run the linter or skip it?" when the linter is part of CI |
+| **Re-ask after decline** | Same path after user said no — `scope-control § decline = silence` | User declined a separate branch → don't propose it again on the same task |
+
+## Direct-answers — severity-tiered claim examples
+
+Companion to `direct-answers` § Iron Law 2 (no invented facts). This
+section is the canonical home for the severity tiers, per-tier
+verification actions, and the override carve-out — the rule cites it
+instead of restating the table.
+
+| Severity | Examples | Verification action |
+|---|---|---|
+| **High — load-bearing** | "Method `X::y()` exists at `path/to/file.php:142`", "version 12.4.1 added the API", "this test passes" | MUST verify with `view`, `grep`, `codebase-retrieval`, or fresh command output **before** claiming. Too expensive → ask. |
+| **Medium — project-shape** | "This project uses Pest for testing", "controllers live under `app/Http/Controllers`" | Verify if one tool call reaches it; otherwise hedge: *"I'd guess X — not checked"*. |
+| **Low — well-known idioms** | "PHP `array_map` returns a new array", "git tags are immutable", "JS arrays are zero-indexed" | Inference acceptable. Mark as inference if not 100% sure. |
+
+**Override:** "just guess" / "rough estimate" / "skip verify" in the
+user's turn drops every claim to **Low** for that turn only. Reverts
+on the next turn unless the user repeats the override.
+
+Hedge-language patterns:
+
+- ✅ "haven't verified X — likely from {known-similar-codebase}"
+- ✅ "guess, not checked — `path/to/file.php:142` is my best read"
+- ❌ "probably" alone — name what's unverified
+- ❌ "vermutlich" without hedge target  <!-- md-language-check: ignore -->
+
+### Volatile-fact freshness — which claims need a live source
+
+Generalizes `direct-answers` Iron Law 2's git/PR live-state clause to any
+research or knowledge claim, not just repo state.
+
+| Class | Examples | Rule |
+|---|---|---|
+| **Fresh-lookup** | current role/status of a person or org, prices/versions/quotas, laws & regulatory policy, an unrecognized entity (tool, package, product), a binary event (release, deprecation, incident) | Never answer from model memory — search or cite a live source, every time. These change silently and staleness is invisible until wrong. |
+| **Stable** | math/CS fundamentals, settled historical facts, language/framework basics pinned by the project's own lockfiles | Model knowledge is acceptable; no live lookup required. |
+
+The line is whether the fact **could have changed since training** in a way
+that matters for the claim. When in doubt, treat it as fresh-lookup — the
+cost of one extra search is far lower than a stale claim stated with
+confidence.
+
+### No duration estimates (Iron Law 2 family)
+
+An LLM has no wall-clock and no latency training signal, so a duration estimate
+is a fabricated fact wearing a number:
+
+- Never predict how long **the agent's own work** will take ("this refactor is
+  ~2 hours", "I'll have it in a few minutes").
+- Never predict how long **the user's work** will take ("this is a 2–3 week
+  project", "should take you an afternoon").
+- Instead: break the work into **actionable steps** and let the user judge
+  timing against their own context — they have the clock, the agent does not.
+
+A step list is honest ("A → B → C, C depends on B"); a schedule is invention.
+
+**Carve-out — world-knowledge ranges.** An industry-typical duration sourced
+from public benchmarks in strategy-advisory output ("integrations of this
+class typically run 4–8 weeks") is a statement about the world, not a
+prediction of the agent's or the user's own latency — allowed, but it MUST
+carry an "industry-typical, not a prediction" qualifier. Unqualified, it
+reads as the banned schedule.
+
+### Never cite the rule as the reason
+
+When declining or constraining an action, give the **actual, substantive
+reason** — never "my rules / guidelines / instructions require X":
+
+- ❌ "I can't do that, my guidelines don't allow it." / "A rule requires me to ask first."
+- ✅ "Sending this would post publicly and can't be undone, so confirm the recipient first." / "This edits a production branch — I need your go-ahead."
+
+Appealing to a hidden rule (a) replaces real reasoning the user can evaluate,
+and (b) widens the prompt-extraction surface (it advertises that hidden
+instructions exist and invites probing them). State the real-world consequence,
+not the rule's existence.
+
+## Direct-answers — failure modes the user will call out
+
+Companion to `direct-answers` § Failure modes. The rule lists the
+modes; this file adds the trigger phrases and the in-language
+correction pattern.
+
+| Failure | User's typical callout | Correct response |
+|---|---|---|
+| Iron Law 1 violation | "skip the flattery", "ohne smalltalk" | drop the opener; deliver substance |
+| Iron Law 2 violation | "have you actually checked?", "wo steht das?" | re-verify with a tool call; correct or retract the claim |
+| Iron Law 3 violation | "kürzer", "less prose", "tldr" | trim to one sentence + the answer |  <!-- md-language-check: ignore -->
+| Emoji blacklist hit | "ohne emojis", "no decoration" | re-render plain |
+
+Acknowledge once, in the user's language, switch behavior, no
+excuses (mirrors `language-and-tone` § slip handling).
+
+### Bullet floor
+
+Companion to `direct-answers` § Iron Law 3. Multi-step content earns
+bullets; each bullet is a complete 1–2-sentence statement, never a
+fragment masquerading as a list item ("Faster." / "Better UX." with no
+subject or verb). A decline or refusal is never rendered as a bulleted
+list of reasons — declines are short prose, one or two sentences, because
+a bulleted refusal reads as a checklist to argue against rather than a
+direct answer.
+
+## No Cheap Questions — Iron Law 3 detail (paternalistic state options)
+
+Companion to `no-cheap-questions` § Iron Law 3. The rule states the
+prohibition; this file lists the patterns and the carve-outs.
+
+**Forbidden patterns** (non-exhaustive):
+
+- "Stop hier — du hast genug für heute"  <!-- md-language-check: ignore -->
+- "Take a break and come back fresh"
+- "Weitermachen wenn frisch"  <!-- md-language-check: ignore -->
+- "Du wirkst genervt, sollen wir pausieren?"  <!-- md-language-check: ignore -->
+- "Sleep on it"
+- "That's a good stopping point" as a numbered option
+- Any option whose recommendation rests on inferred fatigue,
+  frustration, or end-of-day mood.
+
+**Carve-outs** — allowed because they cite **observable, in-message**
+evidence, not inferred state:
+
+- User said "ich bin müde / done for today / let's stop" **this turn**  <!-- md-language-check: ignore -->
+  → ack and stop (instruction, not option).
+- Hard Floor confirmation per `non-destructive-by-default` → "confirm
+  or abort" is the option, not "rest".
+- Context-window / freshness threshold tripped per `context-hygiene` →
+  cite the threshold ("fresh chat at 75%"), do not infer mood.
+
+**The rule of thumb**: every numbered option must be a technical /
+scope / sequencing choice with a real trade-off, not a mood-management
+nudge. If the only remaining differentiator is "you might be tired" →
+drop the option, recommend a concrete next step instead.

package/dist/agent-src/guidelines/agent-infra/break-glass-usage.md

@@ -0,0 +1,113 @@
+# Break-Glass Usage
+
+Guideline for operating the agent under a controlled emergency state —
+when a production incident requires faster stabilization than normal
+verification allows.
+
+Break-glass is **a narrowing, not a bypass**. The rules still apply; the
+gate is just smaller. Never decide to "break glass" unilaterally.
+
+## When break-glass is justified
+
+All of the following must hold:
+
+- **Active customer-impacting incident** — data loss, outage, security
+  exposure, billing regression. Not "we have a deadline".
+- **Explicit user invocation** — the user says "break-glass" or
+  "hotfix, skip the full suite". Ambiguous wording is not enough; ask.
+- **No viable rollback path** that would be faster than the forward fix.
+
+Not a break-glass situation:
+
+- Friday afternoon and you want to ship a feature.
+- CI is slow and you want to skip tests.
+- You can't reproduce a flaky test locally.
+- A reviewer is asleep and you want to self-approve.
+
+## How to invoke
+
+The user sets one of:
+
+1. **Conversation flag** — says "break-glass: true" or "this is a hotfix".
+2. **PR label** — `break-glass` on the PR (optional; the agent still
+   requires explicit invocation in the current turn).
+3. **Commit trailer** — `Break-Glass: <incident-id>` in the commit
+   message of the hotfix.
+
+The agent confirms: "Entering break-glass — narrowing verification to
+targeted test + smoke check. Follow-up PR required within 24h. Confirm?"
+If the user agrees, proceed. If not, stay in the normal gate.
+
+## What narrows
+
+| Layer | Normal gate | Break-glass |
+|---|---|---|
+| Tests | Targeted + full suite | Targeted only — covering the regression |
+| Quality tools | PHPStan + Rector + ECS | Deferred to follow-up PR |
+| Migrations review | Full dry-run + rollback check | Dry-run only, rollback note mandatory |
+| Code review | ≥ 1 reviewer from required roles | 1 reviewer, can be post-merge |
+| Changelog | Required | Deferred to follow-up PR |
+
+Zero tests is **never** acceptable. If the incident fix genuinely cannot
+be tested in the available time, document that explicitly and attach a
+reproducer to the follow-up ticket.
+
+## What does NOT narrow
+
+These rules stay fully in force, break-glass or not:
+
+- [`minimal-safe-diff`](../../rules/minimal-safe-diff.md) — the hotfix is
+  still the **smallest** change that stops the bleeding. No drive-by
+  cleanups.
+- [`security-sensitive-stop`](../../rules/security-sensitive-stop.md) — a
+  security-relevant change still needs the threat-model pass.
+- [`scope-control`](../../rules/scope-control.md) — never mix the
+  hotfix with unrelated refactors from another branch.
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — more
+  asking, not less, when the blast radius is live.
+
+## Required artifacts
+
+The hotfix PR must include, in the description:
+
+1. **Incident link** — ticket, Sentry issue, or Statuspage entry.
+2. **Skipped validations** — bullet list of what was deferred (e.g.
+   "full PHPUnit suite", "PHPStan", "Rector").
+3. **Evidence attached in-PR** — targeted test output, smoke-check log or
+   curl response, migration dry-run if applicable.
+4. **Follow-up commitment** — link to the follow-up ticket or PR that
+   will run the full gate. Due within 24h.
+
+## After the incident
+
+Within 24 hours:
+
+1. Open the **follow-up PR** — runs the full verification gate against
+   the same branch or a rebase onto main.
+2. Write a short **incident note** (2–5 lines) — what failed, what the
+   hotfix did, what was deferred. Store in the project's postmortem
+   location.
+3. If the incident exposed a recurring failure mode, add an entry to
+   `historical-bug-patterns.yml` (see
+   [`review-routing-data-format`](review-routing-data-format.md)).
+
+## Anti-patterns — reject them
+
+- "Break-glass" used as a label for every urgent task — the word stops
+  meaning anything.
+- Shipping the hotfix **and** a refactor in the same commit "since the
+  file was open".
+- Skipping the follow-up PR because "the hotfix was fine". The gate
+  runs once, not zero times.
+- Logging the incident as "false alarm" when the hotfix actually
+  changed behavior. If behavior changed, write the note.
+
+## See also
+
+- [`minimal-safe-diff`](../../rules/minimal-safe-diff.md) — break-glass
+  exception section.
+- [`verify-before-complete`](../../rules/verify-before-complete.md) —
+  break-glass reduction section.
+- [`security-sensitive-stop`](../../rules/security-sensitive-stop.md).
+- [`review-routing-data-format`](review-routing-data-format.md) —
+  where to register newly-discovered failure modes.