@event4u/agent-config 5.10.0 → 6.0.0

package/docs/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`](../../../.agent-src.uncondensed/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
+
+Adopted from [`ginobefun/deep-reading-analyst-skill`](https://github.com/ginobefun/deep-reading-analyst-skill) @ commit `26cd7dc9` · `src/deep-reading-analyst/references/comparison_matrix.md` · MIT License.

package/docs/guidelines/agent-infra/corpus-grounding-authoring.md

@@ -0,0 +1,91 @@
+# Corpus-grounding authoring guide — qualification, shape, governance
+
+> The gate every new domain corpus passes before it enters
+> `src/skills/<skill>/data/`. Architecture: ADR-061; engine + manifest
+> contract: [`corpus-grounding`](../../../src/skills/corpus-grounding/SKILL.md).
+
+## 1. Qualification checklist — ALL must hold
+
+- [ ] **Decision-rule utility test.** The domain's *selection/constraint*
+  decision is externalizable as auditable rules that **beat the agent's
+  priors**. 8 rows with strong conditionals beat 300 flat rows — row
+  count is never the argument.
+- [ ] **Before-action test.** Grounding constrains the option space
+  *before* the agent acts. Mid-action lookup is **reference** (→
+  `references/` / RAG); post-action checking is **validation** (→ a
+  rule/linter); the procedure itself is **method** (→ a framework skill).
+  Route each to its mechanism — never the corpus.
+- [ ] **"Fits in 5 lines" test.** If the knowledge compresses into ≤5
+  lines of an always-on rule, write the rule. A corpus that thin is
+  grounding theater.
+- [ ] **Owner + cadence.** A named maintainer and a refresh cadence are
+  declared in the manifest (`owner`, `refresh_cadence`) — the engine's
+  schema validator refuses manifests without them. Unowned corpora rot;
+  they are not merged (domain-adoption Gate 2).
+- [ ] **Provenance pin.** `upstream{repo, sha, last_checked}` names the
+  authoritative source and its version (git SHA, spec version like
+  "ATT&CK v16" / "WCAG 2.2", or vendor-doc date).
+- [ ] **Evidence gate for conditional candidates.** Domains on the
+  *conditional* list (architecture-pattern selection, finance method
+  selection) additionally require the change-my-mind anchor: the corpus
+  measurably beats the existing framework skill over **≥10 real
+  sessions**. Until then they stay `[~]` deferred.
+
+## 2. Shape — what a domain ships
+
+```
+src/skills/<domain-skill>/data/
+  manifest.json     # schema-agnostic plug-in (see corpus-grounding SKILL.md)
+  <axis>.csv        # the corpus — domain declares its OWN columns
+```
+
+- Tier honestly: `lookup-only` (search + rule columns the agent applies)
+  is the right starting tier for most domains; `conditional-grounding`
+  (engine-evaluated reasoning map + decision rules) only when a natural
+  category→rules two-stage exists; `constraint-emission` only for mature
+  directive-integrated domains (frontend).
+- Every output carries `confidence` + `evidence_gap` — engine-enforced.
+- Consultation default (Tier 1): the skill queries, proposes grounded
+  options, the human confirms. Directive integration is the exception,
+  not the goal ("directive engines everywhere" = orchestration envy).
+- Validate before merge:
+  `python3 src/skills/corpus-grounding/scripts/ground.py validate --manifest …`
+  plus a smoke query, plus an eval-fixture test under `tests/`.
+
+## 3. Governance per shipped corpus (Step 9.8)
+
+| Obligation | Mechanism |
+|---|---|
+| Named owner + cadence | `manifest.json` keys — schema-validator-enforced |
+| Staleness visibility | `upstream.last_checked` bumped on every refresh; quarterly default |
+| Link integrity | `Docs URL` / source columns are plain URLs; `check-refs` + the quarterly refresh catch 404s |
+| Eval lock | one `tests/test_<domain>_corpus.py` with representative queries |
+| License | source obligations recorded in the owning skill (ATTRIBUTION pattern) |
+
+## 4. Rejected domains — recorded, do not relitigate (Step 9.7)
+
+Per ADR-061 §5 and the 2026-06-03 council (3-model deep debate, no
+split), the following are **rejected as corpora**:
+
+| Candidate | Why rejected | Right mechanism |
+|---|---|---|
+| People/org practices (hiring loops, comp, 1:1 cadence) | Volatile, culturally specific ("fads"); rules don't beat priors stably | Framework skills (`hiring-loop-design`, `comp-banding`, …) |
+| GTM playbooks | Same volatility; context dominates selection | Framework skills + discovery interviews |
+| Founder-strategy verdicts | Verdicts are human decisions (strategy-safety-floor); no auditable selection rule | Framework skills + safety floors |
+| Formula/spec lookup (WACC, WCAG criterion text, API param lists) | Mid-action **reference**, not pre-action grounding | `references/` docs / RAG |
+| Lint-able conventions (no hardcoded hex, commit format) | Post-action **validation** | Rules / linters (`tokens.py validate`, commit lints) |
+| Anything ≤5 always-on lines | Grounding theater | A rule |
+
+Conditional (deferred, evidence-gated — NOT rejected): finance *method
+selection*, architecture-pattern selection. Watch note:
+`agents/settings/contexts/domain-watch/conditional-grounding-candidates.md`.
+
+## 5. Shipped domain corpora (registry)
+
+| Domain | Skill / manifest | Tier | Source pin |
+|---|---|---|---|
+| Frontend design | `design-intelligence/data/manifest.json` | conditional-grounding | ui-ux-pro-max @ b7e3af80 |
+| Security / threat-modeling | `threat-modeling/data/manifest.json` | conditional-grounding | MITRE ATT&CK v16 + OWASP ASVS 4.0 (derived) |
+| API design | `api-design/data/manifest.json` | lookup-only | RFC 9110/9457 + field-standard practice (derived) |
+| DB-query tuning | `database/data/manifest.json` | lookup-only | PostgreSQL 16 / MySQL 8 docs (derived) |
+| Accessibility patterns | `accessibility-auditor/data/manifest.json` | lookup-only | W3C ARIA APG + WCAG 2.2 (derived) |

package/docs/guidelines/agent-infra/direct-answers-demos.md

@@ -29,9 +29,8 @@ Eigenschaft des Systems. Lass mich das für dich aufschlüsseln —
 aktuell sind es 38 Always-Rules.
 ```
 
-**Failure mode:** flattery opener ("Sehr gute Frage!"), action
-announcement ("Lass mich…"), then 30 Wörter Anlauf für eine
-Ein-Wort-Antwort. Iron Law 1 + Iron Law 3 zusammen verletzt.
+**Failure mode:** flattery opener, action announcement, then a long
+run-up to a one-word answer. Iron Law 1 + Iron Law 3 violated together.
 
 ### Right shape
 
@@ -43,8 +42,8 @@ Agent: 38.
 
 ### Why it works
 
-Eine Frage mit einer wahren Antwort = ein Satz. Kein Anlauf, kein
-Kissen, kein "let me…". Die Zahl ist die ganze Antwort.
+One question with one true answer = one sentence. No run-up, no
+cushion, no "let me…". The number is the whole answer.
 
 ## Demo 2 — Hedged claim without verification (Iron Law 2)
 
@@ -57,10 +56,10 @@ Agent: Ja, ich glaube schon — die meisten Always-Rules haben das
 inzwischen. Sollte in der Frontmatter stehen.
 ```
 
-**Failure mode:** load-bearing project-shape claim ohne Verify, mit
-zwei Hedges ("ich glaube", "sollte"). Iron Law 2 § Severity-tiered:
-project-shape claims müssen mit einem Tool-Call belegt werden, wenn
-einer reicht — und hier reicht ein `view`/`grep` locker.
+**Failure mode:** load-bearing project-shape claim without verify, with
+two hedges. Iron Law 2 § Severity-tiered: project-shape claims must be
+backed by a tool call when one suffices — and here a `view` / `grep`
+easily suffices.
 
 ### Right shape
 
@@ -74,9 +73,9 @@ Eintrag (nur die anderen vier Safety-Floor-Rules tun das).
 
 ### Why it works
 
-Tool-Call vor Antwort, dann konkrete Aussage mit Begründung. Wenn
-der Verify-Aufwand zu groß wäre → fragen, nicht raten. Hier kostet
-ein `grep` zwei Sekunden, also Tool-Call ist Pflicht.
+Tool call before the answer, then a concrete statement with reasoning.
+If the verify cost were too high → ask, don't guess. Here a `grep`
+costs two seconds, so a tool call is mandatory.
 
 ## Demo 3 — Post-hoc summary creep (Iron Law 3)
 
@@ -95,10 +94,9 @@ und ist Teil der Phase 3 von road-to-context-layer-maturity.
 Lass mich wissen, falls du Fragen dazu hast.
 ```
 
-**Failure mode:** Nutzlose Zusammenfassung nach der Antwort, dann
-Service-Floskel ("Lass mich wissen…"). Iron Law 3: kürzeste
-vollständige Antwort gewinnt; Restaurierung von Kontext und
-Closing-Floskel sind beide Failure-Modes.
+**Failure mode:** useless summary after the answer, then a service
+phrase. Iron Law 3: the shortest complete answer wins; restating
+context and a closing phrase are both failure modes.
 
 ### Right shape
 
@@ -110,9 +108,8 @@ Agent: `docs/guidelines/agent-infra/verify-before-complete-demos.md`
 
 ### Why it works
 
-Pfad ist die ganze Antwort. Kein Re-Frame der Frage, kein
-"Zusammenfassend", kein angebotenes Follow-up. Wenn Matze mehr
-will, fragt er.
+The path is the whole answer. No re-frame of the question, no
+"in summary", no offered follow-up. If the user wants more, they ask.
 
 ## Demo 4 — Functional emoji vs prose flair
 
@@ -122,10 +119,10 @@ will, fragt er.
 Agent: 🚀 Tests sind durch! ✨ Alle 47 grün 🎉 Bereit für den nächsten Schritt 💪
 ```
 
-**Failure mode:** Emoji als Stil-Element, nicht als funktionaler
-Marker. § Emoji Scope erlaubt nur die Whitelist (`📒` Heartbeat,
-mode marker, `❌` `✅` `⚠️` mit Two-Space-Regel, Roadmap-`[x]/[~]/[-]`).
-Alles andere ist Rauschen.
+**Failure mode:** emoji as a style element, not as a functional
+marker. § Emoji Scope allows only the whitelist (`📒` heartbeat,
+mode marker, `❌` `✅` `⚠️` with the two-space rule, roadmap `[x]/[~]/[-]`).
+Everything else is noise.
 
 ### Right shape
 
@@ -140,6 +137,6 @@ $ vendor/bin/pest -q
 
 ### Why it works
 
-Genau ein Emoji aus der Whitelist (`✅` mit Two-Space), funktional
-verwendet als Status-Marker neben dem CLI-Output. Keine Deko, keine
-Reaktions-Emojis.
+Exactly one emoji from the whitelist (`✅` with two-space), used
+functionally as a status marker next to the CLI output. No decoration,
+no reaction emojis.

package/docs/guidelines/agent-infra/language-and-tone-examples.md

@@ -1,6 +1,6 @@
 # language-and-tone — examples and failure modes
 
-> Reference companion to [`.agent-src/rules/language-and-tone.md`](../../.agent-src/rules/language-and-tone.md).
+> Reference companion to [`dist/agent-src/rules/language-and-tone.md`](../../dist/agent-src/rules/language-and-tone.md).
 > Pulled out so the always-active rule stays under its character budget.
 > Linked from the rule via the **Examples** section; agents do not load this file
 > automatically, only when they want concrete demonstrations or are debugging a
@@ -100,7 +100,7 @@ rewrite the whole reply.
 
 ## `.md` files — pre-save detection heuristic
 
-Before saving any `.md` under `.augment/`, `.agent-src/`,
+Before saving any `.md` under `.augment/`, `dist/agent-src/`,
 `.agent-src.uncondensed/`, or `agents/`, scan the body for:
 
 - Umlauts (`ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`, `ß`) **outside** fenced code,
@@ -112,3 +112,30 @@ Before saving any `.md` under `.augment/`, `.agent-src/`,
 
 Any hit → translate to English, OR move to a `DE: … · EN: …` anchor
 block (the only allowed German location).
+
+## Generated `.md` — fix the generator, never the page
+
+When a `.md` page is produced by a generator (e.g. `docs/value.md` from
+`scripts/render_value_md.py`, the catalogs from the index/catalog
+generators), German lives in the **generator's source strings** or the
+data it reads — fix it there so the page regenerates English. Hand-edits
+to a generated page are overwritten on the next regen. If a generated
+page legitimately carries German (e.g. catalogs echoing skill-description
+**trigger-phrase examples**), the page belongs **outside** the docs
+language gate — scanning a derived artefact is the wrong layer; the source
+artefact is what the relevant linter checks.
+
+## Sanctioned escapes for genuinely-required German
+
+Two — and only two — escapes are allowed when a line must carry German:
+
+1. **Labeled `DE: … · EN: …` anchor** — the only location for German
+   *prose* (a translated passage shown alongside its English).
+2. **Per-line `<!-- md-language-check: ignore -->` marker** — for a single
+   line that quotes a German **trigger-phrase example** (illustrating
+   German-input handling) or a **verbatim provenance quote** (an
+   immutable historical citation, e.g. the original user ask in an ADR).
+
+The marker is line-scoped and auditable. Never scatter it through a
+generated file to silence the linter — fix the generator instead. Both
+escapes are recognized by `scripts/check_md_language.py`.

package/docs/guidelines/agent-infra/layered-settings.md

@@ -9,7 +9,7 @@ project-local choices always win.
 Referenced by `road-to-project-memory.md` Phase 0 and
 `road-to-portable-dev-preferences.md`. Consumed by the centralized
 settings loader at
-[`scripts/_lib/agent_settings.py`](../../../scripts/_lib/agent_settings.py),
+[`scripts/_lib/agent_settings.py`](../../../src/scripts/_lib/agent_settings.py),
 the `/onboard` command, and any agent that edits `.agent-settings.yml`
 on user request.
 
@@ -32,7 +32,7 @@ All three are YAML. Schemas:
 - Developer (project-local): [`agent-settings.md`](../../templates/agent-settings.md).
 - Team: [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml).
 - User-global: six exact dotted paths — whitelist in
-  [`scripts/_lib/agent_settings.py`](../../../scripts/_lib/agent_settings.py).
+  [`scripts/_lib/agent_settings.py`](../../../src/scripts/_lib/agent_settings.py).
 
 ## Merge order
 
@@ -254,7 +254,7 @@ after that.
 The contract is **additive merge with user-line preservation** —
 the user's file is the ground truth, the template only contributes
 keys the user is missing. Round-trip parser and merger live in
-[`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py); the
+[`scripts/sync_yaml_rt.py`](../../src/scripts/sync_yaml_rt.py); the
 supported YAML subset (block-mappings, scalars, lists, comments,
 CRLF/LF) is documented in its module docstring. The stdlib-only
 choice (vs. `ruamel.yaml`) and its revisit triggers are recorded in

package/docs/guidelines/agent-infra/linked-projects-onboarding-gate.md

@@ -0,0 +1,80 @@
+# Linked-Projects Onboarding Gate
+
+> IDE-attached sibling repo detection, one-time opt-in flow, persistence shape, and the cross-repo behavioral directive
+
+_Origin: migrated from `src/rules/linked-projects-onboarding-gate.md` per the P4 pattern of `road-to-kernel-and-router.md`._
+
+**Iron Law.** When the IDE has attached a sibling repository to this project
+and the sibling is not yet recorded in `linked_projects`, prompt the developer
+**once** to opt it into scope, persist the choice local-only, and thereafter
+proactively flag cross-repo impact — never bulk-include the sibling's files.
+
+This closes the **proactivity gap**: the agent can already read/write a sibling
+repo, but it does not *consider* one unless told — and the developer who most
+needs cross-repo awareness is precisely the one who won't think to mention the
+sibling. Detection reads the relationship the developer already encoded by
+attaching the repo in their IDE (zero-knowledge). See the cross-repo guide
+(`docs/guides/cross-repo-linked-projects.md`) and ADR-032.
+
+## When this fires
+
+First substantive turn of a session (and on a new IDE attachment), when a
+detected sibling is absent from `linked_projects` in `.agent-settings.local.yml` (in agents/settings/).
+Inert when no sibling is attached, or when every detected sibling already has a
+recorded decision (opted-in or declined).
+
+## Detection
+
+Run the detector against the project root:
+
+```bash
+python3 -c "from scripts._lib.linked_projects import detect_linked_projects; \
+import json,sys; print(json.dumps(detect_linked_projects('.')))"
+```
+
+It returns config-attached siblings only (PhpStorm `.idea/modules.xml` +
+`vcs.xml`, VS Code `*.code-workspace`) that resolve outside the project, exist,
+and are git repos. A sibling above `linked_projects_max_files` (default 20000)
+carries `"large": true` — surfaced as awareness only, never excluded.
+
+## Opt-in (one-time per sibling)
+
+For each detected sibling **not** already in `linked_projects`, ask once
+(numbered options per `user-interaction`): include it / decline it / always /
+never-ask. Persist to `.agent-settings.local.yml` (in agents/settings/) (the gitignored per-machine
+layer — never the committed `.agent-settings.yml`):
+
+```yaml
+linked_projects:
+  - path: /abs/path/to/sibling
+    include: true        # false = declined; never re-prompt
+```
+
+A declined sibling (`include: false`) is never prompted again.
+
+## Behavioral directive (for each `include: true` sibling)
+
+While that sibling is in scope, the agent:
+
+- **proactively checks cross-repo impact** when a change here may affect it —
+  API-contract changes, shared-type / enum drift, renamed routes the sibling
+  consumes — and **warns** before finishing;
+- **does not bulk-include** the sibling's files in context (passive awareness,
+  not implicit inclusion — large repos stay cheap);
+- treats out-of-root edits to the sibling as normal work, but the host agent's
+  own out-of-root **permission gate still applies** (no silent cross-repo write).
+
+## Kill-switch
+
+This is an experimental, removable rule. If opt-in is consistently declined or
+siblings are never cited, remove it — no telemetry, the signal is local.
+
+## Follow-up (not yet shipped)
+
+- Consumer-install detector reachability: ✅ shipped 2026-05-30 — the detector is
+  now exposed as `agent-config linked-projects:list` (closes the ADR-032
+  follow-up); cross-repo retrieval over opted-in siblings ships as
+  `/knowledge:cross-repo`.
+- Multi-agent verification: only Claude Code was empirically validated
+  (ADR-032). Cursor / Augment / Copilot behavior is unverified — the manual
+  fallback in the guide covers them until tested.

package/docs/guidelines/agent-infra/missing-tool-handling.md

@@ -0,0 +1,66 @@
+# Missing Tool Handling
+
+> CLI tool needed for the task is not installed — ask before working around it; do NOT install silently
+
+_Origin: migrated from `src/rules/missing-tool-handling.md` per the P4 pattern of `road-to-kernel-and-router.md`._
+
+When a CLI tool is needed to solve the task cleanly and is **not installed**
+(`command not found`, `which X` empty, missing from `$PATH`), **STOP and ask**
+before working around it or installing it.
+
+## The rule
+
+- **Never install silently.** Installing is an action that changes the user's
+  system — it requires explicit permission (see `scope-control`).
+- **Never silently work around** a missing tool with a brittle substitute
+  (awk-regex for YAML, `grep` for JSON, string splicing) when a proper tool
+  is the standard answer for the job. The workaround hides the real
+  dependency and makes the decision invisible to the user.
+- **Ask with numbered options** (see `user-interaction`). State which tool,
+  why it's the best fit, the install command, and the workaround cost.
+
+## When it applies
+
+- Any shell command fails with `command not found` for a tool the task
+  genuinely needs (yq, jq, rtk, gh, docker, mkcert, terraform, …).
+- A skill or spike requires a tool that is the idiomatic answer but is
+  absent locally.
+- You are about to substitute a verbose script for a single tool invocation
+  because the tool isn't there.
+
+## When it does NOT apply
+
+- The tool is a nice-to-have and a clean substitute already exists in the
+  repo (e.g. `jq` present → no need for `yq` just for JSON).
+- The tool is explicitly forbidden by project policy (check
+  `scope-control` and tool-allowlists first).
+- The missing artefact is a library dependency — those go through
+  `composer require`, `npm install`, `pip install` per the package-manager
+  rules, still with explicit permission.
+
+## How to ask
+
+```
+> `yq` is not installed. It's the cleanest way to parse the ticket YAML
+> in the Bash prototype — the alternative is shelling out to python3,
+> which adds ~50ms to every run.
+>
+> 1. Install via `brew install yq` (recommended — one-time, stays on PATH)
+> 2. Use the python3 fallback — slower but no install needed
+> 3. Drop YAML — convert fixtures to JSON, use `jq` only
+> 4. Skip this path — I propose a different approach
+```
+
+After the user picks: if **install**, wait for confirmation that it is
+done (or run the documented install command only if the user explicitly
+authorises it in this turn). If **workaround**, record the decision in
+the artefact (comment or ADR) so the cost is visible.
+
+## Capture the learning
+
+If the same tool keeps coming up as missing across multiple tasks, flag
+it in the project's setup docs or `.agent-settings.yml` prerequisites.
+Don't make every session re-discover the gap.
+
+See also: `scope-control` · `ask-when-uncertain` · `user-interaction` ·
+`tool-safety`.

package/docs/guidelines/agent-infra/model-recommendation.md

@@ -0,0 +1,72 @@
+# Model Recommendation
+
+> Surface-aware model_tier routing — when to auto-switch, when to suggest, how to phrase the one-question suggestion
+
+_Origin: migrated from `src/rules/model-recommendation.md` per the P4 pattern of `road-to-kernel-and-router.md`._
+
+**Iron Law.** When a skill or command carries a `model_tier` (a vendor-neutral
+capability band), route the turn to **that agent's best model in that band** —
+automatically where the surface supports a per-turn override, as a single
+suggestion where it does not. Never recommend another vendor's model. Never
+double-ask, never front-load the question.
+
+## Source of truth — the capability tier
+
+Each skill/command declares `model_tier: lite | medium | high | inherit`
+(ADR-035) — a band, not a model. `inherit` = "no opinion, keep the session
+model". The task→tier heuristics live in
+`contexts/model-recommendations.md` — cite them, don't restate. The **only**
+tier→model mapping the package maintains is the Claude generator's
+(`high→opus`, `medium→sonnet`, `lite→haiku`); every other agent resolves the
+band to its own line-up.
+
+## Surface-aware behaviour
+
+Read `model.auto_switch` from `.agent-settings.yml` (`auto | suggest | off`,
+default `suggest`) live, then:
+
+- **Claude Code / Desktop (native per-turn `model:` override).** When
+  `auto_switch: auto`, the rendered skill's native `model:` (mapped from the
+  tier by the generator) already performed the switch — **do NOT ask, do NOT
+  re-state it**. When `suggest`, no native key was emitted; surface the
+  one-question suggestion below using the skill's `model_tier`.
+- **Any surface without a per-turn override (Augment, etc.).** When
+  `auto_switch` is `auto` or `suggest`, surface **one** suggestion (per
+  `ask-when-uncertain`) naming the **tier** — the user maps it to their
+  agent's model. Do NOT name a specific vendor model; the package keeps no
+  per-vendor table. Never auto-act where the surface can't.
+- **`auto_switch: off`.** Inert. No native key, no suggestion.
+
+## The suggestion (non-auto surfaces)
+
+Ask **last** — after context / domain clarification, never before the task is
+understood. Name the tier, not a vendor model:
+
+```
+> 💡 This skill recommends the **{model_tier}** capability tier for {task type}.
+>
+> 1. Switch to your **{model_tier}**-tier model — continue
+> 2. Stay on the current model
+```
+
+(Tier → your model: `high` = your strongest reasoning model, `medium` = your
+balanced daily model, `lite` = your fastest/cheapest.) On "switched" → accept,
+continue. On "stay" → accept, no pushback; don't re-ask until the task type
+changes.
+
+## Preserved flows (re-pointed at tiers)
+
+- **Downgrade reminder.** After a `high`-tier task (architecture / refactoring /
+  root-cause found), remind the user that the implementation phase is cheaper on
+  the **`medium`** tier — using the next skill's `model_tier` as the target.
+  Full flow: `contexts/model-recommendations.md` § Downgrade reminder.
+- **Gemini warning.** Detected model `gemini` → surface the not-recommended
+  warning once, then accept the user's choice. Flow:
+  `contexts/model-recommendations.md` § Gemini warning.
+
+## No standing-selection fight
+
+A user's explicit `/model` choice is standing; the native per-turn `model:`
+override reverts on the next prompt, so the rule never overrides a standing
+selection beyond the current turn. With the default `suggest`, no native key is
+emitted at all — the user's `/model` is never silently overridden.