@event4u/agent-config 14.23.0 → 16.0.0

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.

package/dist/agent-src/guidelines/agent-infra/carve-out-predicates.md

@@ -0,0 +1,17 @@
+# Decidable Carve-Out Predicates
+
+Companion to [`frugality-charter`](../../contexts/contracts/frugality-charter.md). Each carve-out below carries a one-sentence test. If the test cannot be answered yes/no from the artifact alone, the carve-out does not fire and default-terse rules apply.
+
+## Predicates
+
+- **Iron-Law literal** — the prose is an ALL-CAPS fenced block inside a rule whose title appears in [`docs/contracts/kernel-membership.md`](../../contracts/kernel-membership.md).
+
+- **Numbered-options with genuine trade-off** — the options differ in consequence (a chosen path produces a measurably different artifact or state), not in sequencing or output format. Per [`no-cheap-questions § What counts as cheap`](../../rules/no-cheap-questions.md#what-counts-as-cheap).
+
+- **Security-sensitive prompt** — the prompt requires credential input OR modifies auth / tenant / secret state, matching a trigger in [`security-sensitive-stop`](../../rules/security-sensitive-stop.md).
+
+- **Structured CLI contract** — the script's stdout is consumed by another script (a downstream parser exists under `scripts/` or `.augment/scripts/`), so the format is part of an interface contract, not narration.
+
+## How to use
+
+Writer skills (`skill-writing`, `rule-writing`, `command-writing`, `guideline-writing`, `context-authoring`, `agent-docs-writing`, `conventional-commits-writing`, `readme-writing`, `readme-writing-package`, `adr-create`, `persona-writing`, `roadmap-writing`) cite this file when an artifact's pre-save check needs a decidable test for a carve-out exception. The default is **terse** — predicates here only fire when the artifact provides the yes/no evidence.

package/dist/agent-src/guidelines/agent-infra/comparison-matrix.md

@@ -0,0 +1,179 @@
+# Multi-Source Comparison Matrix
+
+Reference guideline for Wing-1 deep-thinking work — the cross-source
+synthesis lens. Use when analyzing multiple articles, papers, or
+perspectives on the same topic: systematically compare claims, evidence
+quality, and viewpoints to synthesize an integrated understanding rather
+than a stack of independent summaries. Adopted under the
+**Reference-Guideline Sunset Policy** and cross-referenced from:
+
+- [`deep-reading-analyst`](../../skills/deep-reading-analyst/SKILL.md)
+  — L4 Research analysis depth (web-search 2–3 related sources, compare,
+  synthesize).
+- [`critical-thinking`](critical-thinking.md) — per-source argument
+  quality feeds the evidence-strength column here.
+- [`systems-thinking`](systems-thinking.md) — interdisciplinary matrix
+  pairs with cross-domain pattern recognition.
+
+> **Core principle:** Compare to synthesize, not to tally. Weight sources
+> by credibility, separate what is settled from what is debated, and name
+> your own interpretive bias.
+
+## When to use
+
+- Reading 3+ sources on the same topic.
+- Encountering conflicting information across sources.
+- Trying to synthesize best practices from competing approaches.
+- Building comprehensive understanding before a decision.
+
+## Standard Comparison Matrix
+
+```markdown
+# Comparative Analysis: [Topic]
+
+## Sources Overview
+
+| Source | Type | Author Expertise | Date | Bias/Lens |
+|--------|------|-----------------|------|-----------|
+| [Source 1] | [Article/Paper/Book] | [Credentials] | [Date] | [Perspective] |
+| [Source 2] | [...] | [...] | [...] | [...] |
+| [Source 3] | [...] | [...] | [...] | [...] |
+
+## Key Claims Matrix
+
+| Claim/Question | Source 1 | Source 2 | Source 3 | Consensus? |
+|----------------|----------|----------|----------|------------|
+| [Question 1] | [Position] | [Position] | [Position] | ✅/❌ |
+| [Question 2] | [Position] | [Position] | [Position] | ✅/❌ |
+
+## Evidence Quality
+
+| Source | Evidence Type | Strength (1-5) | Notes |
+|--------|---------------|----------------|-------|
+| Source 1 | [Data/Anecdote/Study] | ⭐⭐⭐⭐ | [Assessment] |
+| Source 2 | [...] | ⭐⭐⭐ | [...] |
+```
+
+## Agreement vs. Disagreement
+
+- **Universal agreement** — points all sources converge on.
+- **Partial consensus** — where two align and one diverges.
+- **Complete divergence** — where views split, listed per source.
+
+## Synthesized Insights
+
+- **What we know with confidence** — convergent evidence across sources.
+- **Open questions** — where sources disagree or lack data.
+- **Integrated framework** — synthesis combining the best of each source.
+- **Source-specific contributions** — what only each source provides.
+- **Recommended reading order** — sequence for someone new to the topic,
+  with the reason per step.
+
+## Matrix variants
+
+Pick the shape that fits what the sources actually differ on:
+
+### Method comparison
+
+When sources describe different methods/approaches:
+
+```markdown
+| Method | Source | Best For | Limitations | Difficulty | Results |
+|--------|--------|----------|-------------|------------|---------|
+| [Method A] | [Source 1] | [Use case] | [Weakness] | Easy | [Outcome] |
+| [Method B] | [Source 2] | [Use case] | [Weakness] | Hard | [Outcome] |
+
+Recommendation: use [X] when [condition]; combine [X + Y] for [scenario].
+```
+
+### Viewpoint spectrum
+
+When sources sit at different positions on a spectrum:
+
+```markdown
+[Extreme Position A] ←―――――――――――→ [Extreme Position B]
+        ↑                    ↑                    ↑
+    [Source 1]          [Source 2]          [Source 3]
+
+Per position: core belief · reasoning · strongest point · weakest point.
+My position: where you land after reviewing all perspectives, and why.
+```
+
+### Evolution over time
+
+When tracking how understanding of a topic evolved:
+
+```markdown
+| Period | Representative Source | Key Insight | What Changed Next |
+|--------|----------------------|-------------|-------------------|
+| [Era 1] | [Source/Author] | [Prevailing view] | [Paradigm shift] |
+
+Pattern analysis: what stayed constant · what repeatedly changed ·
+current frontier.
+```
+
+### Interdisciplinary
+
+When the same topic is analyzed from different fields:
+
+```markdown
+| Discipline | Source | Core Question | Key Findings | Limitations |
+|------------|--------|---------------|--------------|-------------|
+| Economics | [Source] | [Question] | [Insight] | [Blind spot] |
+| Psychology | [Source] | [Question] | [Insight] | [Blind spot] |
+
+Synthesis: complementary insights · contradictions + resolution ·
+blind spots one field fills for another.
+```
+
+### Practical / how-to
+
+For how-to content from multiple sources: common steps all sources agree
+on, a variations table per aspect, reported results/credibility per
+source, then a personalized recommendation for the reader's context.
+
+## Conflict resolution
+
+When sources directly contradict, investigate before picking a winner.
+Five common reasons a contradiction is only apparent:
+
+1. **Different definitions** — they define the key term differently;
+   not actually contradicting if talking about different things.
+2. **Different contexts** — different time/place/population; both can be
+   right in their own context.
+3. **Different evidence** — quality difference explains the disagreement.
+4. **Different values/goals** — different optimization targets lead to
+   different conclusions.
+5. **One is wrong** — one source has flawed reasoning.
+
+Resolution lands on one of: which source is more reliable for *this*
+claim and why · how both can be true depending on context · this remains
+unresolved and needs more evidence.
+
+## Pitfalls
+
+- ❌ Forcing false equivalence — not all views are equally valid.
+- ❌ Cherry-picking to support a predetermined view.
+- ❌ Ignoring publication quality / expertise differences.
+- ❌ Over-detailed comparison that misses the forest for the trees.
+
+## Best practices
+
+- ✅ Weight sources by credibility.
+- ✅ Look for convergent evidence.
+- ✅ Note what is settled vs. debated.
+- ✅ Name your own biases in interpretation.
+
+## How to populate
+
+1. Read each source independently first.
+2. Identify common themes / questions across sources.
+3. Choose the matrix shape based on what you are comparing.
+4. Fill in each source's position.
+5. Analyze patterns and synthesize — do not stop at the table.
+
+---
+
+## ADOPT citation
+
+Adapted from an external reference.

package/dist/agent-src/guidelines/agent-infra/context-hygiene-mechanics.md

@@ -0,0 +1,165 @@
+# Context Hygiene — Mechanics
+
+> Suggestion templates, state-dump format, read-loop self-checks, and host fallbacks for the `context-hygiene` rule
+
+_Origin: migrated from `src/rules/context-hygiene.md` per the P4 pattern of `road-to-kernel-and-router.md`. The freshness thresholds, the 3-failure rule (with failure-identity and hard-blocker classes), the tool-loop cap, and the read-loop 15/25 Iron Law stay in the rule; this file carries the templates and per-host procedures._
+
+## Conversation-freshness suggestion — how to phrase it
+
+Estimate token cost: responses × ~1,500 tokens.
+
+```
+> ⚡ This conversation has ~{N} messages (~{N×1500} tokens history cost — charged on EVERY request).
+> A fresh chat saves ~{N×1500} input tokens per request.
+>
+> 1. Start fresh — I'll initiate a session handoff
+> 2. Continue here
+```
+
+**If the user picks 1:** Initiate a session handoff or start fresh.
+
+## Read-loop self-check (fires at the 15-min warning)
+
+1. Source expectation known? If no → read **once**, then act.
+2. Can a single failing test name the error? If yes → run it now.
+3. Regression in working code? → `git log` + `git show <sha> -- <file>`.
+4. Guessing at mock / payload shape? → read the producer **once**.
+
+## Read-loop abort block (the 25-min stop)
+
+```
+> ⛔ Loop: N read-only turns, ~M min. Read: <files>. Hypothesis: <X>.
+> 1. Different approach (suggestion: <Y>)
+> 2. Point me at the right spot
+> 3. Fresh chat with state dump
+```
+
+Non-bypassable. An autonomous mandate (`/work`, `/roadmap:process-*`,
+"entscheide selbst") does **not** lift the abort — it is the safety
+net that protects autonomy from becoming a token sink.
+
+Debug procedure for "I'm in a read loop fixing tests" →
+`systematic-debugging` § Debug micro-loop (one test, one fix, one re-run).
+
+## State dump format
+
+```
+## State Dump: [Task]
+### Tried: 1. [Approach] → [Why failed] 2. ... 3. ...
+### Known: [Key facts]
+### Hypothesis: [Best guess for root cause]
+### Recommendation: [Next approach for fresh session]
+```
+
+Use `/agent-handoff` to generate a context summary for a fresh conversation.
+
+## Augment-specific: ignored-skills recovery
+
+Skills excluded via `.augmentignore` don't appear in `<available_skills>`.
+If you need an ignored skill: read its SKILL.md directly, apply guidance, then ask:
+
+```
+> 💡 I loaded `{name}` manually — currently ignored in `.augmentignore`.
+> 1. Remove from ignore — relevant for this project
+> 2. Keep ignored — one-off
+```
+
+## Copilot fallback
+
+GitHub Copilot has no `PostToolUse` hook surface, so
+`scripts/context_hygiene_hook.ts` cannot run structurally and
+`agents/state/context-hygiene.json` is not maintained automatically
+(tool-call count, loop signal, freshness milestones at 20/40/60).
+
+The cooperative path: track turns and tool-loop signals from memory
+during the conversation and apply the suggest-a-new-chat / 3-failure
+stop / loop-detection rules. To refresh the state file manually so the
+dashboard or another tool can read the latest counters, run:
+
+```bash
+./scripts-run src/scripts/context_hygiene_hook < /dev/null
+```
+
+The script reads from stdin if a JSON envelope is provided and
+otherwise writes a no-op snapshot under the shared dispatcher lock.
+Exit code is always 0 — hooks must never block the agent loop.
+
+## See also
+
+- `context-hygiene` (rule) — thresholds, 3-failure rule, tool-loop cap, read-loop Iron Law.
+- `systematic-debugging` § Debug micro-loop — the one-test-one-fix-one-rerun procedure.
+
+## The CI waiter — use the helper, never the hand-written loop
+
+`./scripts-run src/scripts/ci_settle <pr> [--timeout-min N] [--interval-sec N]`
+
+Exit codes: **0** settled green · **1** settled red, with the failing checks
+named · **2** did not settle, or the API could not be read — never a verdict.
+
+Four states classify as *not settled*, and each one is a way the hand-written
+form goes wrong: an API error, a non-zero `gh` exit, unparseable output, and
+**zero registered checks** (a run that has not registered its checks yet looks
+exactly like a finished one with nothing to report).
+
+**Why it exists.** Measured 2026-08-20:
+
+```bash
+until ! gh pr checks 1459 | grep -q "pending"; do sleep 60; done
+```
+
+The API then failed. Its error text — `error connecting to api.github.com` —
+contains no `pending`, so the loop exited, the session reported a settle that
+had not happened, and the claim had to be retracted to the user in the next
+reply. The bug is not the sleep or the grep: **absence of the word `pending`
+was treated as evidence of completion**, and an error is neither settled nor
+pending. The exit condition is the part that is easy to get wrong, so it lives
+in one place rather than in every agent's head.
+
+## Waiting is one waiter — why the loop test misses it
+
+Migrated from [`context-hygiene`](../../rules/context-hygiene.md)
+§ *Waiting is one waiter, never a fleet* under the P4 pattern
+(`road-to-standing-payload-diet` step 1.3). The rule keeps the Iron Law, the
+one-waiter instruction and the enforcement verdict; the argument for them is
+here.
+
+The loop test in that rule fails on waiting in **both** of its clauses:
+
+- **"Same parameters" fails.** A `sleep 240` followed by `sleep 420` followed by
+  `sleep 595` are three different calls by any parameter comparison, so nothing
+  reads them as repetition.
+- **"Repetition without new information" fails too**, and this is the subtler
+  half: the poll genuinely returns a different value each round — 31 green, then
+  34, then 36 — which *feels* like progress. It is not information unless a
+  different digit would make you act differently. It would not: the only actions
+  available were wait, or stop and report, and 34 licensed neither more than 31
+  did. **The discriminator is the decision, not the digits.**
+
+So state it separately: pick **one** waiter for the condition and let it finish.
+Where the harness re-invokes on completion, waiting costs nothing and polling
+costs a turn per expiry — and every stacked waiter is a turn that arrives *after*
+the answer already did. Where it does not, one `until <condition>` loop is still
+one call rather than N.
+
+**Measured once, at n=1, and worth naming for its shape rather than its
+frequency** (2026-08-12): a CI wait started roughly 35 background commands —
+a fresh timer *and* a fresh condition-watcher per round, none cancelled when the
+next pair started. CI settled with about fifteen still live; each then expired
+and produced an empty turn. Nothing was corrupted, which is exactly why it ran
+so long: every individual step looked reasonable.
+
+**Enforcement: none, and the reason is structural.** The `context-hygiene` hook
+counts tool calls; a waiter is indistinguishable from any other call at that
+layer, and nothing in the envelope says two live waiters are watching one
+condition. This is model-carried on every host.
+
+## The declared-protocol cap — why 8, and when it changes
+
+Migrated from [`context-hygiene`](../../rules/context-hygiene.md)
+§ *Declared read protocol* under the same pattern. The rule keeps the cap and the
+three-field declaration contract; the honesty note about the number is here.
+
+> **The 8 is a guess, and specifically a LOWER BOUND.** One observed run — the coherence audit that motivated this clause — needed 8+ read turns and was legibly the protocol working, not a loop. So 8 is "the number that was enough once", not a measured optimum: n=1 says almost nothing about where the tail of the distribution sits, and nobody knows how many sessions silently hit the old 5 and should have continued. Calling this a derivation would be false advertising, which is the same failure class as the "17 rules carry absolutes" figure this rule's own roadmap refuted.
+> **Revisit-if — whichever comes first:** (a) **≥ 10 declared-protocol sessions** have been observed, at which point set the cap from their p95 and delete this note; or (b) **90 days** elapse with fewer than 10, which is itself the answer — declared protocols are rare, the cap is not load-bearing, and it drops back to the undeclared 5. A condition like "once a distribution exists" was rejected as unfalsifiable: it is gradual, never feels urgent, and absence of complaints is indistinguishable from absence of measurement. <!-- enforcement-count-ok: not an enforcement denominator — the 10 is a revisit threshold for observed declared-protocol read sessions and the 90 a calendar deadline; neither is a count of rules, obligations, or covered platforms, so there is no resolver output to cite instead -->
+
+