@event4u/agent-config 1.21.0 → 1.23.0

package/.agent-src/skills/adr-create/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: adr-create
+description: "Use when capturing an architectural decision — naming the file, picking the next ADR number, filling Status / Context / Decision / Consequences, and regenerating the index — even without saying 'ADR'."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 30
+  allowed_tools: []
+  command:
+    - python3
+    - scripts/adr/regenerate_index.py
+---
+
+# adr-create
+
+## When to use
+
+Use this skill when:
+
+- A non-trivial architectural choice needs a written record (kernel
+  membership, cap raises, contract changes, library swap, deprecation).
+- A decision overrides a previous one and needs `supersedes:` linkage.
+- A roadmap phase closes and the chosen variant must be cited.
+- The user says "write an ADR for X", "decision log this", "we need
+  a record of why we picked Y".
+
+Do NOT use when:
+
+- The change is reversible without governance impact (typo, lint
+  fix, refactor that stays inside one module).
+- The decision is already covered by an existing ADR — extend or
+  supersede it instead of duplicating.
+- A skill, rule, or guideline is the better home (use those skills).
+
+## Goal
+
+- Sequential `ADR-NNN-<slug>.md` numbering with no gaps.
+- Standard template: Status, Context, Decision, Consequences,
+  Alternatives, References.
+- Regenerated index so readers find the ADR by topic, not by ls.
+- Zero MCP-tool dependency — pure filesystem + Python.
+
+## Preconditions
+
+- An ADR directory exists (default `docs/adr/`; `docs/decisions/` is
+  the recognised alias used in this package and many older projects).
+- The decision is **already made** — ADRs record outcomes, they do
+  not run the decision process. For unresolved trade-offs, run the
+  council or consult `adversarial-review` first.
+
+## Procedure
+
+### 1. Inspect and resolve the ADR directory
+
+Identify the canonical directory in this order:
+
+1. `docs/adr/` — default per spec.
+2. `docs/decisions/` — accepted alias if `docs/adr/` is missing.
+3. Anything else — fail, ask the user to pick one of the two
+   canonical paths. Do not invent a third location.
+
+### 2. Pick the next ADR number
+
+Scan the directory for `ADR-*.md`, parse the leading 3-digit number,
+take `max + 1` (zero-padded). For an empty directory, start at `001`.
+Reject re-use of an existing number — the index regenerator treats
+duplicates as a hard failure.
+
+### 3. Pick a slug
+
+Short, hyphen-lowercase, scope-revealing. Match peer ADRs in the
+directory. Examples: `kernel-swap-deferred`, `flat-cluster-subs`,
+`http-bridge-deferred-with-trigger`. Reject slugs longer than 60 chars.
+
+### 4. Author the ADR
+
+Use the standard template (frontmatter + body). All sections are
+required; "n/a" is acceptable for genuinely empty Alternatives or
+References blocks but never for Status, Context, Decision, or
+Consequences.
+
+```markdown
+---
+adr: NNN
+status: proposed | accepted | superseded | deprecated
+date: YYYY-MM-DD
+decision: <slug>
+supersedes: — | ADR-MMM
+superseded_by: — | ADR-MMM
+phase: <roadmap> · <phase-id>
+---
+
+# ADR-NNN — <Decision Title>
+
+## Status
+
+**<Proposed | Accepted | …>** · YYYY-MM-DD.
+
+## Context
+
+What problem forced this decision? What constraints applied? What
+alternatives were on the table at decision time?
+
+## Decision
+
+The chosen variant, in one paragraph. Concrete enough that a reader
+six months later knows what was actually picked.
+
+## Consequences
+
+### Accepted
+
+- Hard guarantees we now make.
+
+### Trade-offs
+
+- What we gave up. Mitigations, if any.
+
+## Alternatives considered
+
+- **Variant X — <name>.** Rejected because <reason>.
+- **Variant Y — <name>.** Rejected because <reason>.
+
+## References
+
+- Linked roadmap, contract, prior ADR, council session id.
+```
+
+### 5. Regenerate the index
+
+Run the dispatcher:
+
+```bash
+python3 scripts/runtime_dispatcher.py run --skill adr-create
+# or directly:
+python3 scripts/adr/regenerate_index.py --dir docs/adr/
+```
+
+The script scans `ADR-*.md`, reads frontmatter (`adr`, `status`,
+`date`, `decision`, `supersedes`), and writes `INDEX.md` with one
+table row per ADR plus broken-supersede warnings on stderr.
+
+### 6. Validate
+
+- `python3 scripts/adr/regenerate_index.py --check` exits 0
+  (index is up to date, no number gaps, no broken supersedes).
+- The project's CI / quality pipeline passes locally.
+
+## Output format
+
+1. Path of the new `ADR-NNN-<slug>.md` file.
+2. Path of the regenerated `INDEX.md`.
+3. One-line summary of the decision.
+4. Linked roadmap or phase, if any.
+
+## Gotchas
+
+- `docs/adr/` is the default path; some projects use
+  `docs/decisions/` (this package included). Pass `--dir` to the
+  index regenerator when running outside the default.
+- Frontmatter `adr:` is the canonical number; the filename prefix
+  must match. The index regenerator fails on mismatch.
+- ADRs are append-only history. To revise a decision, write a new
+  ADR with `supersedes: ADR-MMM` and flip the old one's status to
+  `superseded`.
+- Never delete an ADR file — supersede it. Deletion breaks
+  historical links and round-trips through git history checks.
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every ADR you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, `## Context` states the
+  forcing function in 2–3 sentences; no historical narrative.
+- Per the cite-don't-restate principle, `## Decision` links the
+  rules / contracts it overrides; no rule body is quoted in full.
+- Per the cheap-question check, `## Alternatives considered` lists
+  genuine design alternatives, not strawmen.
+
+**Pre-save self-check:**
+1. Does `## Context` carry more than 5 sentences of setup?
+2. Does `## Decision` restate rule text instead of citing the rule?
+3. Are alternatives evaluated with a real consequence each, or with
+   stylistic preference?
+4. Does the ADR forecast consequences with hedge phrases ("might",
+   "could potentially") instead of decidable claims?
+
+## Do NOT
+
+- Skip Context — a decision without context is folklore.
+- Reuse an existing ADR number — the index regenerator hard-fails.
+- Author ADRs for reversible refactors or minor cleanups.
+- Cite a council session id without ensuring the file is committed
+  or otherwise reachable from the repo (per `no-council-references`).

package/.agent-src/skills/adversarial-review/SKILL.md

@@ -4,6 +4,7 @@ description: "ONLY when user explicitly requests adversarial review, devil's adv
 personas:
   - critical-challenger
 source: package
+council_depth: deep
 ---
 
 # Adversarial Review

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

@@ -168,6 +168,7 @@ When starting work, read documentation in this order:
 | Significant multi-step change | Ask user about creating a roadmap in `agents/roadmaps/` |
 | New convention introduced | Update relevant doc in `./agents/` or `.augment/guidelines/` |
 | Database schema changed | Update `agents/docs/database-setup.md` |
+| Architectural decision made | Use the [`adr-create`](../adr-create/SKILL.md) skill — writes a numbered ADR under `docs/adr/` (or `docs/decisions/`) and regenerates the index |
 
 ## When to update documentation
 
@@ -187,7 +188,7 @@ After completing a significant code change, run this mental checklist:
 | New API endpoint | OpenAPI annotations, `AGENTS.md` API section |
 | New module created | Create `app/Modules/{Module}/agents/` |
 | Service/repository signature changed | Check if referenced in `agents/docs/services-and-repos.md` |
-| New environment variable | `.env.example`, `AGENTS.md` env section |
+| New environment variable | `.env.example`, `AGENTS.md` environment section |
 | Docker/compose change | `agents/docs/docker.md`, `Makefile` documentation |
 | New Artisan command | `AGENTS.md` commands section |
 | New pattern/convention introduced | Relevant guideline in `.augment/guidelines/` |
@@ -220,6 +221,27 @@ Do NOT auto-update docs without the user's knowledge. Flag what needs updating a
 - AGENTS.md and copilot-instructions.md have different audiences — don't copy content between them.
 - Module docs go in `app/Modules/*/agents/`, NOT in the central `agents/` directory.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every agent-doc update you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, doc updates state what
+  changed; no "In this section we will…" frames.
+- Per the cheap-question check, AGENTS.md surface offers options
+  only where the project genuinely diverges.
+- Per the post-action summary suppression, doc edits append change
+  notes to the existing log entry; no new "Summary of changes" block.
+
+**Pre-save self-check:**
+1. Does the doc open with a narrative intro instead of the actual
+   content?
+2. Are paragraphs added that summarize an existing table?
+3. Does the doc duplicate the rule index instead of linking the
+   relevant rule?
+4. Is German prose present outside `DE: / EN:` anchor blocks?
+
 ## Do NOT
 
 - Do NOT create docs unless there's a real need (new module, significant change).

package/.agent-src/skills/ai-council/SKILL.md

@@ -43,6 +43,7 @@ prompt that asks them to think on their own merits.
 THE COUNCIL DOES NOT SEE THE HOST AGENT'S ANALYSIS.
 THE COUNCIL DOES NOT SEE PRIOR REPLIES.
 THE COUNCIL SEES THE ARTEFACT + THE NEUTRAL SYSTEM PROMPT. NOTHING ELSE.
+THE HOST AGENT IS THE CONVENER, NEVER A REVIEWER.
 ```
 
 If you find yourself wanting to "frame" the artefact for the council,
@@ -50,6 +51,13 @@ stop. Framing is exactly what kills the second-opinion value. Use the
 unbiased system prompts in `scripts/ai_council/prompts.py`; do not
 roll your own.
 
+The host runs the council and synthesises convergence — it is the
+convener, not a reviewer. The reviewer-ban is structural: the host
+wrote (or framed) the artefact and cannot critique it independently.
+Anonymising the host as "Reviewer C" is worse than excluding it — the
+user is told they got an outside vote when they did not. Externals
+down → surface and skip; never substitute the host as a reviewer.
+
 ### Neutrality — context-handoff
 
 External reviewers do better critique when they know **what the
@@ -120,6 +128,27 @@ token counts (from the manual-paste length heuristic or the
 provider's reply, when available) for observability. Mixed runs
 (one manual + one api) gate only the api members.
 
+## Degradation modes
+
+How the council behaves when fewer than two billable members are
+reachable. The orchestrator never silently substitutes — degradation
+is visible to the user.
+
+| Reachable | Behaviour | Independence |
+|---|---|---|
+| **2+** | Full fan-out, multi-round debate. Default. | High — cross-provider diversity. |
+| **1** | Single-voice critique with a degraded-run warning. Multi-round mode lets the model see its own anonymised reply, but convergence ≠ correctness. | Low — shared blind spots. |
+| **0** | Council skipped. Surface the failure, proceed without external review. **Never** substitute the host or an unrequested manual pass. | None. |
+
+Rejected anti-patterns (council convergence, 2026-05-06): persona
+prompts (same model, same blind spots, more cost), temperature
+spread (noise, not signal), host-as-fallback (Iron Law breach).
+Supported single-provider strategy is **sibling models on the same
+provider** (e.g. Sonnet ↔ Opus, gpt-4o ↔ o1) — different training
+cutoffs / reasoning architectures within one provider family. Cost
+is real (siblings price-tier higher); explicit opt-in per invocation,
+not a default.
+
 ## Procedure
 
 1. **Resolve target.** Identify the artefact mode (`prompt`, `roadmap`,
@@ -140,9 +169,61 @@ provider's reply, when available) for observability. Mixed runs
    into the host agent's voice.
 6. **Summarise.** Write a `Convergence / Divergence` block listing
    agreements, disagreements, and unique insights — provider-attributed.
-7. **Translate to options.** Convert actionable council suggestions
-   into concrete numbered options for the user. The user decides;
-   the council advises.
+7. **Critically evaluate** every finding before it leaves the host
+   (see *Critical evaluation* below). The host is the convener **and**
+   the skeptic — never a reviewer of the artefact itself, but always a
+   reviewer of the **council's output**.
+8. **Translate validated findings to options.** Convert each finding
+   the host accepts (or accepts with modification) into a concrete
+   numbered option for the user. Tag every option with the host's
+   verdict so the user sees the agent's reasoned position, not the
+   council's raw output. The user decides; the council advises; the
+   host filters.
+
+## Critical evaluation — convener-skeptic stance
+
+```
+COUNCIL CONVERGENCE IS NOT CORRECTNESS.
+DO NOT BLINDLY ACCEPT FINDINGS. DO NOT BLINDLY REJECT THEM.
+EVERY FINDING GETS A REASONED VERDICT BEFORE IT REACHES THE USER.
+```
+
+The council is **uninformed about the codebase, ADRs, locked
+contracts, prior decisions, and project history** — it sees only the
+artefact + neutrality preamble. That is the source of its diversity
+**and** its blind spots. Convergence between members can mean shared
+generic best-practice priors, not project-specific correctness.
+
+The host applies a critical lens to **every finding** (convergence
+**and** divergence) before surfacing it as a numbered option:
+
+| Check | Question | Tool |
+|---|---|---|
+| **Codebase fit** | Does the finding match the actual code, files, signatures, conventions? | `view` / `codebase-retrieval` / `grep` |
+| **Locked-decision conflict** | Does it contradict an ADR, kernel rule, contract under `docs/contracts/`, or `docs/decisions/`? | `view` |
+| **Already addressed** | Is it a generic best-practice already covered by an existing rule, skill, or test? | `view` / `grep` |
+| **Cost / benefit** | Is the change worth the diff size, churn, and review cost vs. the marginal benefit? | reasoning |
+| **Hallucination** | Does the finding cite a file, function, or behavior that does not exist? | `view` |
+
+Each finding receives one of three verdicts:
+
+- **`accept`** — codebase fits, no locked-decision conflict, benefit clears cost. Surface as a normal numbered option.
+- **`accept-with-modification`** — core insight valid, but the proposed shape needs adjusting (wrong file, contradicts ADR detail, scope creep). Surface with the **modified** patch and a one-line note.
+- **`reject`** — finding is wrong (hallucinated reference, contradicts a locked decision, already addressed, generic noise). Surface as a **Rejected by host** entry with a one-line reason. Still visible — the user can override.
+
+The verdict is the host's **own** reasoning, not the council's.
+Pretending convergence equals correctness, or paraphrasing council
+output as host analysis, both breach the [`direct-answers`](../../rules/direct-answers.md)
+no-invented-facts rule. When the host cannot reach a confident
+verdict on a finding (mixed evidence, ambiguous scope), it surfaces
+the finding as `needs-input` with the open question — the user
+decides, the host does not guess.
+
+### What this is NOT
+
+- **Not a re-review by the host.** The host did not write the artefact independently and cannot critique it independently — that boundary still holds.
+- **Not a vote against the council.** Rejecting a finding requires evidence (file, line, contract reference), not preference.
+- **Not silent filtering.** Every finding reaches the user with its verdict and reason. The user can pick a `reject` option and override the host.
 
 ## Output path convention
 
@@ -195,16 +276,26 @@ Every council reply MUST contain, in this order:
    containing the member's verbatim output.
 3. **Convergence / Divergence summary** — bullet list, every claim
    attributed by provider name.
-4. **User-facing options** — numbered block per `user-interaction`,
-   with "discard council input" always present as an option.
-
-The host agent NEVER ships council output as its own reasoning.
-Provider attribution stays visible in every render.
+4. **Host verdict per finding** — one row per finding with `accept`
+   / `accept-with-modification` / `reject` / `needs-input` plus a
+   one-line reason citing host evidence (file:line, ADR, contract).
+   See *Critical evaluation* above.
+5. **User-facing options** — numbered block per `user-interaction`,
+   carrying the host verdict in each option, with "discard council
+   input" always present as an option.
+
+The host agent NEVER ships council output as its own reasoning, and
+NEVER ships the host verdict as council output. Provider attribution
+stays visible in the per-member sections; host verdicts stay
+attributed to the host.
 
 ## Do NOT
 
 - Do NOT paraphrase council output into the host agent's voice — strip
   attribution and you've stripped the value.
+- Do NOT surface council findings to the user without a host verdict
+  — convergence ≠ correctness, and the user deserves the agent's
+  reasoned filter, not a raw forward.
 - Do NOT pre-warm the council with the host agent's analysis or
   identity — that primes the reviewer and collapses diversity.
 - Do NOT silently truncate a too-large bundle — surface the size and
@@ -236,6 +327,9 @@ Real failure modes seen in the wild:
 | Silently truncate a too-large bundle. | Misleads the reviewer into thinking they saw the whole thing. | Bundler raises `BundleTooLarge`; surface and ask for narrower scope. |
 | Reuse the same SDK client across calls without re-loading the key. | Leaks the key in long-lived process state. | Each invocation builds fresh clients from `load_*_key()`. |
 | Auto-spend tokens under `personal.autonomy: on`. | Autonomy ≠ permission to spend money. | Always ask before consultation, even under autonomy. |
+| Forward council convergence to the user as numbered options without a host verdict. | Convergence ≠ correctness; the council never saw the codebase. | Apply the *Critical evaluation* lens; tag every finding `accept` / `accept-with-modification` / `reject` / `needs-input` with one-line reason. |
+| Reject a finding on preference, not evidence. | "I don't like this" is not a verdict. | Cite the file, line, ADR, or contract that justifies the rejection — or surface as `needs-input`. |
+| Paraphrase council output into the host's own analysis to defend a verdict. | Strips attribution, breaches `direct-answers` no-invented-facts. | Verdict cites host evidence (file:line); council output stays attributed in the per-member sections. |
 
 ## Redaction expectations
 
@@ -343,9 +437,39 @@ at least once before convergence). The host agent does **not** ask
 the settings owner already made that decision. Ask only when a
 genuinely complex artefact justifies more depth than the default.
 
+### Deep-reasoning tier (`council_depth: deep`)
+
+Architecture review, refactoring proposals, and bug-diagnosis runs
+benefit from an extra critique round. The deep tier is opt-in per
+artefact:
+
+1. The consuming **rule, skill, or command** declares
+   `council_depth: deep` in its frontmatter. The schema accepts
+   **only `deep`** — `standard` is the implicit default and is
+   rejected by the linter (every frontmatter byte costs context
+   window; see `scripts/schemas/{rule,skill,command}.schema.json`).
+   To return an artefact to default depth, **delete the key**.
+2. The **host agent** reads that frontmatter when it dispatches the
+   council and passes `--depth deep` to `council_cli`. If multiple
+   active artefacts disagree, **deep wins** (max policy).
+3. The **CLI** floors the round count at
+   `max(ai_council.deep_min_rounds, ai_council.min_rounds)` —
+   defaults to `3` and `2` respectively. Lowering `deep_min_rounds`
+   below `min_rounds` has no effect (defensive max).
+
+The CLI itself has no knowledge of frontmatter; the contract is the
+flag. Resolution chain (highest priority first):
+
+```
+--rounds N           → explicit, any value (user override)
+--depth deep         → max(deep_min_rounds, min_rounds)
+(no flag)            → min_rounds (default 2)
+```
+
 | Property | Behaviour |
 |---|---|
 | Default count | `ai_council.min_rounds` (default `2`). Override per-invocation with `rounds:N` (or `--rounds N` to the CLI). |
+| Deep floor | `ai_council.deep_min_rounds` (default `3`). Activated by `council_depth: deep` in artefact frontmatter (host translates to `--depth deep`) or explicit `--depth deep` on the CLI. Floored at `min_rounds`. |
 | Anonymisation | Provider/model identity is stripped. Reviewers are labelled `Reviewer A / B / C…` in input order. |
 | Errored prior responses | Skipped — they reveal nothing useful and can leak provider error formats. |
 | Cost budget | Accumulates across rounds. A round-2 call that breaches the cap fires `on_overrun` exactly like a round-1 breach. |

package/.agent-src/skills/bug-analyzer/SKILL.md

@@ -2,6 +2,7 @@
 name: bug-analyzer
 description: "Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs."
 source: package
+council_depth: deep
 ---
 
 # bug-analyzer

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

@@ -166,6 +166,29 @@ multi-paragraph explanation, extract it into a skill and call it.
   `.agent-src.uncompressed/`.
 * Duplicating another command's workflow instead of delegating via `skills:`.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every command you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, command output blocks state
+  the action result, not "Now we will execute…".
+- Per the post-action summary suppression, the success path emits
+  the artifact (PR URL, commit hash) without a wrapping summary.
+- Per the cheap-question check, never offer "preview vs. execute"
+  as a numbered option when the command's role is to execute.
+
+**Pre-save self-check:**
+1. Does any command step prescribe a "Let me…" or "Found it" output
+   line?
+2. Does the command default to multi-line summaries when a one-line
+   outcome suffices?
+3. Is a confirmation gate used outside the Iron-Law / Routine /
+   Contextual taxonomy?
+4. Are template placeholders (`{{var}}`) accompanied by setup prose
+   instead of action prose?
+
 ## Do NOT
 
 * Do NOT set `disable-model-invocation: false`

package/.agent-src/skills/context-authoring/SKILL.md

@@ -156,6 +156,29 @@ schema regex and by `scripts/lint_load_context.py`. Body links to
 Canonical reference: `rule-writing` § 3b and
 `docs/contracts/load-context-schema.md`.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every context file you author.
+
+**Examples in this artifact:**
+- Per the charter's index nature, context files are reviewer fuel —
+  they hold mechanics, not Iron-Law obligations.
+- Per the cite-don't-restate principle, when a section mirrors a
+  rule, link the rule and stop.
+- Per the act-skip-narration rule, lookup tables open the section;
+  explanatory prose follows only if the table is ambiguous.
+
+**Pre-save self-check:**
+1. Does the context file restate Iron-Law text instead of linking
+   the rule?
+2. Does any section open with "This document explains…" instead of
+   the lookup material?
+3. Are placeholders (`<add me>`, `TBD`) shipped instead of actual
+   content?
+4. Are the cited rules linked with stable anchors (verified to
+   exist)?
+
 ## Do NOT
 
 - Do NOT copy content between projects. Every context file is local to its

package/.agent-src/skills/conventional-commits-writing/SKILL.md

@@ -113,6 +113,29 @@ Or add `BREAKING CHANGE:` in the commit body/footer.
 - Squash merge titles should describe the net effect, not every internal detail
 - `refactor` means NO behavior change — if behavior changes, use `feat` or `fix`
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every commit message you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, the subject states the
+  change in 50 chars; no scaffolding ("This commit will…").
+- Per the post-action summary suppression, the body lists changed
+  surfaces in bullets — no closing paragraph re-summarizing them.
+- Per the cheap-question check, never propose a `feat` vs. `chore`
+  numbered choice when the type is decidable from the diff.
+
+**Pre-save self-check:**
+1. Does the subject line carry filler ("various improvements",
+   "general updates")?
+2. Does the body re-narrate the diff instead of stating intent?
+3. Are co-author / attribution footers present without explicit user
+   request (per
+   [`no-attribution-footers`](../../rules/no-attribution-footers.md))?
+4. Is the type / scope chosen from the diff, not from the asker's
+   framing?
+
 ## Do NOT
 
 - Do NOT use vague messages: `update stuff`, `fix bug`, `changes`

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

@@ -130,6 +130,28 @@ Above the split signal, break by sub-topic into sibling files in the same folder
 * Hollowing out a skill into "see guideline" — the skill must remain
   executable (see `preservation-guard`).
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every guideline you author.
+
+**Examples in this artifact:**
+- Per the charter's index nature, guidelines describe practice
+  patterns; they do **not** restate Iron-Laws from rules.
+- Per the act-skip-narration rule, code examples lead with the
+  pattern, not its motivation.
+- Per the cheap-question check, guidelines do not prescribe stylistic
+  forks ("table vs. paragraph") — pick one.
+
+**Pre-save self-check:**
+1. Does the guideline restate text from a rule body instead of
+   linking the rule?
+2. Are code examples preceded by narrative ramp-up?
+3. Does the guideline introduce a new convention without citing the
+   rule that holds the obligation?
+4. Are sections labeled "Overview" / "Background" carrying only
+   restatement?
+
 ## Do NOT
 
 * Do NOT add `type:` or `alwaysApply:` to the frontmatter