@event4u/agent-config 8.13.0 → 9.1.0

package/docs/decisions/ADR-049-configuration-trust-boundary.md

@@ -44,7 +44,9 @@ filtered** to a small curated set (`MERGEABLE_KEYS` = `name`, `ide`,
 ignored. `ai_council` is not on the whitelist, and council configuration lives
 project-local in `agents/settings/.ai-council.yml` (per
 [`ai-council-config`](../contracts/ai-council-config.md), the Phase-0 single
-source of truth).
+source of truth). <!-- Council placement superseded by ADR-104: the config is
+now user-global only (`~/.event4u/agent-config/settings/.ai-council.yml`),
+never project-local. The trust-boundary reasoning below is unaffected. -->
 
 The maintainer questioned whether that project-local placement is a bug. The AI
 council was asked to decide and **converged** that it is **not** a bug — the
@@ -72,6 +74,12 @@ personas, rule tier) **belongs in version control**, and onboarding stays clean
    for council config is `agents/settings/.ai-council.yml`
    ([`ai-council-config`](../contracts/ai-council-config.md)); personas live in
    the project surface. Neither is a user-global concern.
+   <!-- Superseded for the COUNCIL part by ADR-104: council config is now
+   user-global only, never project-local (personas are unaffected). -->
+   **Update (ADR-104):** the council half of this decision was reversed — the
+   council config now lives user-global only
+   (`~/.event4u/agent-config/settings/.ai-council.yml`) and the project tree is
+   never read. Personas stay project-local as stated.
 
 3. **Only secrets and the curated identity whitelist are global.** Provider API
    keys already live global in `~/.event4u/agent-config/<provider>.key` (0600);

package/docs/featured-skills.md

@@ -1,6 +1,6 @@
 # Featured Skills
 
-A curated subset of the 271 skills. Three tiers, one per primary audience. Full catalog lives in [`dist/agent-src/skills/`](../dist/agent-src/skills/); see also [`docs/catalog.md`](catalog.md) for the complete index and [`docs/featured-commands.md`](featured-commands.md) for command-level highlights.
+A curated subset of the 275 skills. Three tiers, one per primary audience. Full catalog lives in [`dist/agent-src/skills/`](../dist/agent-src/skills/); see also [`docs/catalog.md`](catalog.md) for the complete index and [`docs/featured-commands.md`](featured-commands.md) for command-level highlights.
 
 > **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (see `road-to-product-adoption.md` Phase 1), this page is documentation, not marketing. The entries below are the candidates the corpus tests against; their description quality is what the eval validates.
 
@@ -92,4 +92,4 @@ task lint-featured-skills
 
 CI runs this in `taskfiles/ci-fast.yml`. Stale entries (renamed / removed skill or command) fail the build. See [`scripts/lint_featured_skills.py`](../src/scripts/lint_featured_skills.py) for the matcher.
 
-→ Browse all 271 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 183 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)
+→ Browse all 275 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 184 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)

package/docs/getting-started-by-role.md

@@ -2,7 +2,7 @@
 
 > Pick the entry that matches what you do day-to-day. Each section names the three skills you will reach for first and shows whether MCP (no terminal) or CLI (terminal) is the simpler install path for that role.
 
-`agent-config` ships 271 skills, 104 governed rules, and 183 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
+`agent-config` ships 275 skills, 104 governed rules, and 184 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
 
 > **Taglines at a glance →** [`docs/role-experiences.md`](role-experiences.md) — the one-line pitch per role experience, in one table.
 

package/docs/getting-started.md

@@ -174,25 +174,36 @@ Your agent now understands slash commands:
 | `/fix quality` | Run and fix all quality checks |
 | `/chat-history import` | Pull a prior session into the current chat (resume) |
 
-→ [Browse all 183 active commands](../dist/agent-src/commands/)
+→ [Browse all 184 active commands](../dist/agent-src/commands/)
 
 ---
 
 ## Team mode — cross-model review (default off)
 
-Team mode pairs two strong models on one change: one model builds, a
-second reviews the **real diff** in your working tree and hands the
-findings back for a fix round. It is the depth complement to the
+Team mode is a governed access layer with a read-only multi-host
+fallback: a second strong model reviews the **real diff** in your
+working tree and returns its findings. It is the depth complement to the
 [AI council](../dist/agent-src/skills/ai-council/SKILL.md): the council
 collects many cheap, neutral opinions on an artefact's *text*; team mode
-puts one strong, opinionated reviewer *inside the repo*.
+puts one strong, opinionated reviewer *inside the repo*. An iterated
+build→review→fix loop is gated future work — it unlocks only with a
+positive verdict from the pre-registered benchmark.
 
 | Axis | Council | Team mode |
 |---|---|---|
 | Repo access | none — members see only the artefact text | full — the reviewer reads the real diff and git state |
-| Shape | breadth — N neutral opinions, one round | depth — one strong reviewer, build→review→fix iteration |
+| Shape | breadth — N neutral opinions, one round | depth — one strong reviewer on the real diff |
 | Cost model | API-billed members (per-token) | subscription-authed `codex` CLI (runs under your existing plan) |
 
+**Host support.** Only Claude Code with the Codex plugin gets the native
+path; every other host runs a reduced, read-only fallback — no host
+outside Claude Code has feature parity.
+
+| Host | Path | Capability |
+|---|---|---|
+| Claude Code + Codex plugin | native — wrappers delegate to the plugin's `/codex:*` commands | full wrapper set: review, adversarial, status (incl. plugin job view), delegate (double-opt-in write path) |
+| Any other host | read-only fallback via the `codex` CLI (repo-diff bundle) | review-shaped output only — no plugin job control, no background jobs, no delegate write path |
+
 **Setup.** Run `agent-config doctor --check team` — it verifies the
 `codex` binary + auth and, on Claude Code hosts, the Codex plugin, and
 prints the exact remediation command for anything missing.

package/docs/governance-advantage.md

@@ -33,7 +33,7 @@ the host lacks (a static host gives it no runtime attention guarantee, but a
 runtime-only system gives it nothing at all here). A runtime-only system contributes *nothing* on these hosts.
 
 ### 2. Intent routing, not a 500-artefact dump
-A prompt does not load all 271 skills. `dist/router.json` (100 routed rules, intent →
+A prompt does not load all 275 skills. `dist/router.json` (100 routed rules, intent →
 skill, keyword/phrase/path triggers) carries the right skill on intent. The
 governance value is *selection discipline* — the host gets the relevant rule
 set, not the whole catalogue as context ballast.

package/docs/guidelines/agent-infra/active-remediation-mechanics.md

@@ -0,0 +1,45 @@
+# Active Remediation — Mechanics
+
+> Ladder detail, version-gated modernization, and anti-nagging guardrails for the `active-remediation` rule
+
+_Origin: migrated from `src/rules/active-remediation.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, the ladder tier names, and the live-security carve-out stay in the rule; this file carries the per-tier criteria and the modernization gates._
+
+## The ladder — classify, then act
+
+### Fix now (autonomous, inline) — a bounded amendment to `minimal-safe-diff`
+
+Allowed **only** when ALL hold — this is the testable "small + task-aligned" definition:
+
+- **Same request path / module** as the current task (not an unrelated feature).
+- **≤ ~10 changed lines** in one production file plus its test file — no wider cross-file ripple.
+- **No public-API / response-shape change**, no new parameter.
+- **No dependency bump, no migration, no data change.**
+- **Its verification ships in the same commit** — e.g. the security fix's negative test, or the correctness fix's case.
+
+Under those constraints the fix is auditable in the same diff and is *not* scope creep — it corrects a boundary the agent touched. Anything outside them → the fix is **note + ask**, never auto. (`minimal-safe-diff` still governs everything else: no reformatting, no opportunistic refactor, no drive-by rename.)
+
+### Note + ask (batched)
+
+Bigger, or diverges from the task → do **not** refactor inline, do **not** interrupt the flow. Note the site (file:line + the issue). Surface the batch as **one** numbered-options prompt (per `user-interaction`, one recommendation line) **after the task is delivered** — or mid-work only when the flow makes it natural. Each option must carry a real trade-off (`no-cheap-questions`). Refactor only on an explicit yes, as a separate scoped change (`scope-control`, `downstream-changes`).
+
+### Propose a follow-up PR (many spots)
+
+When the issues are too many to fold in without blowing the current diff's scope, propose **one or more separate follow-up PRs** (or a roadmap under `agents/roadmaps/`, using the shared-prefix convention) so the user reviews the changes before merge. Creating the PR/roadmap is **permission-gated** — propose, get a yes, then create (`scope-control`, `commit-policy`).
+
+## Version-gated modernization
+
+Update stale idioms to the version the project **actually runs** — but only when that version is **verified**:
+
+- **Establish the version first** from the manifest constraint (`composer.json` `require`, `package.json` `engines`, `.tool-versions`, lockfile) — use the **lowest** bound; on an ambiguous/monorepo range, ask once. **Unknown version → do not touch** (must fit the project structure — this is the `source-discovery` gate).
+- **Syntax-only, behavior-preserving idioms** (e.g. `array()` → `[]`, `isset($x)?$x:$d` → `$x ?? $d`, string concat → template) that are provably equivalent → treat as a small fix (auto per the ladder).
+- **Behavioral changes** (`readonly`/typed properties, new language semantics) and **any dependency/version bump** → **ask only**, never auto (a version bump stays under `minimal-safe-diff`'s no-dependency-bump prohibition; a pure syntax idiom is categorically different).
+
+## Guardrails — don't become a nagging machine
+
+- Subordinate to `no-cheap-questions` (self-check items 3 & 14 — real trade-off, not a disguised continuation/commit ask), `autonomous-execution` (the end-of-session batch must not read as "shall I continue?"), `user-interaction`, `ask-when-uncertain` (one batched prompt = one question).
+- Threshold to surface at all: a **real, nameable** improvement with a concrete benefit. Cosmetic nitpicks with no trade-off → drop silently. The live-security carve-out is the only case that interrupts or overrides autonomy.
+
+## See also
+
+- [`active-remediation`](../../../src/rules/active-remediation.md) — the rule this file details (Iron Law + ladder + live-security carve-out).
+- [`minimal-safe-diff`](minimal-safe-diff-mechanics.md) — the diff-shape mechanics the fix-now tier amends.

package/docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md

@@ -101,6 +101,34 @@ _Origin: migrated from `src/rules/improve-before-implement.md` per the P4 patter
 
 Before coding a new feature, refactor, module, or behavior-altering change, quickly verify:
 
+### 8-pre. Demand gate — should this exist at all? (build / defer)
+
+One altitude ABOVE engineering-fit. Fires on a "build me an app / add this
+feature" ask, before checks 8a–8c. It is a three-question advisor, NOT a
+product-management framework — surface it in one short block, then proceed on
+the user's answer (never block; `improve-before-implement`'s golden rule holds).
+
+Three questions:
+
+1. **Who requested this?** (a real user / segment, or an internal hunch?)
+2. **What happens if you DON'T build it?** (churn / blocked deal, or nothing measurable?)
+3. **What's the demand evidence?** (requests, usage data, lost revenue — or a feeling?)
+
+Map the answers to a compressed feature-demand hierarchy and recommend:
+
+| Level | Signal | Recommendation |
+|---|---|---|
+| L0 | Founder/agent anxiety — "it feels missing" | **Defer** — validate demand first |
+| L1 | One anecdotal request, no pattern | **Defer** — watch for repetition |
+| L2 | Repeated requests, no measured impact | **Validate** — instrument before building |
+| L3 | Blocks activation/retention for a real segment | **Build** |
+| L4 | Users are churning / deals lost without it | **Build now** |
+
+Build only at **L3–L4**; L0–L2 get a defer/validate recommendation with the
+one missing evidence named. This is advisory — the user decides; a "just build
+it" answer proceeds immediately to 8a. No network, no case-memory API (the
+source's remote lookup is dropped — a lethal-trifecta egress concern).
+
 ### 8a. Is the request clear?
 
 - Are acceptance criteria defined or derivable?

package/docs/guidelines/agent-infra/api-cost-levers.md

@@ -0,0 +1,126 @@
+# API Cost Levers
+
+Reference material for a downstream AI-coding agent that wants to cut its own
+Claude API dollar bill. Four platform-level billing levers, the exact economics
+of each, and how they interact. Read on demand — not always-loaded.
+
+Facts sourced from the in-repo `claude-api` plugin skill plus platform research
+(2026-07-14). Do not invent an API shape beyond what is stated here.
+
+## The four levers at a glance
+
+| Lever | Cuts | Best for | Watch out for |
+|---|---|---|---|
+| Prompt caching | Repeated input tokens | Stable prefix reused across calls (system prompt, tools, repo map) | Any byte change in the prefix invalidates the rest |
+| Batch API | 50% input + output | Non-interactive bulk work (classification, summarization, evals) | Async, up to 24h, results unordered |
+| Model tiering | Per-token price | Routine work on a cheaper model | Switching model is a cache miss |
+| Effort / output sizing | Thinking + output tokens | Routine turns that don't need deep reasoning | Oversized `max_tokens` risks runaway output |
+
+## 1. Prompt caching
+
+Put the large, byte-**stable** context first — system prompt, tool definitions,
+a corpus or repo map, few-shot examples — behind a
+`cache_control: {type: 'ephemeral'}` breakpoint. Keep volatile content (the
+varying question, timestamps, per-request IDs) **after** the last breakpoint.
+The cache is a **prefix match**: any byte change in the cached prefix
+invalidates everything after it. Render order is tools then system then
+messages.
+
+Caching is GA — **no beta header needed**.
+
+Economics:
+
+- Cache reads cost approximately 0.1x the base input price.
+- Cache writes cost 1.25x (5-minute TTL) or 2x (1-hour TTL).
+- Break-even is after **one** read on the 5-minute TTL.
+
+Constraints:
+
+- The minimum cacheable prefix is model-dependent (approximately 1024–4096
+  tokens). Shorter prefixes silently do not cache.
+- The cache is workspace-isolated (since February 2026).
+
+Verify a hit with `usage.cache_read_input_tokens > 0`.
+
+```json
+{
+  "system": [
+    { "type": "text", "text": "<large stable system prompt>",
+      "cache_control": { "type": "ephemeral" } }
+  ],
+  "messages": [
+    { "role": "user", "content": "<the varying question>" }
+  ]
+}
+```
+
+## 2. Batch API
+
+For **non-interactive, non-latency-sensitive bulk work** — bulk classification,
+mass file summarization, eval runs. Not chatbots or interactive assistants.
+
+- **50% off both input and output tokens.**
+- Async: results within 24h (usually much less), keyed by `custom_id`, arriving
+  **unordered** — key results by `custom_id`, never by position.
+- **Stacks with prompt caching**: a cached-batch input token can reach
+  approximately 0.05x the standard input price.
+
+## 3. Model tiering
+
+Treat models like a team — a cheap model for mechanical or routine work, the
+expensive model only for hard judgment. Approximate input / output price per 1M
+tokens:
+
+| Model | Input | Output |
+|---|---|---|
+| Haiku | $1 | $5 |
+| Sonnet | $3 | $15 |
+| Opus | $5 | $25 |
+| Fable | $10 | $50 |
+
+Opus input is approximately 5x Haiku. Tier by task **difficulty**, not blindly:
+a cheaper model that gives wrong answers on judgment tasks costs correction
+cycles, which erases the saving.
+
+**Interaction with caching.** The prompt cache is keyed by `(model, prefix)`, so
+switching a call to a cheaper model is a cache **miss**. Weigh the downgrade
+saving against the lost cache-read saving before routing a cached call to a
+different model.
+
+## 4. Effort and output right-sizing
+
+- `output_config.effort` (low through max) controls thinking and output depth,
+  and therefore spend. Dial effort **down** on routine turns; reserve high / max
+  for hard reasoning.
+- Right-size `max_tokens` — do not leave a huge ceiling. An unrealistically
+  large `max_tokens` does not cost tokens by itself, but it risks runaway output
+  and defeats pre-flight budgeting.
+
+## When to reach for which
+
+| Situation | Lever |
+|---|---|
+| Same large context reused across many calls | Prompt caching |
+| Thousands of independent, non-urgent jobs | Batch API (+ caching) |
+| Turn is mechanical / narrow / well-specified | Cheaper model tier |
+| Turn is routine and does not need deep thinking | Lower `effort` |
+| Output could balloon unnecessarily | Cap `max_tokens` |
+| Interactive latency matters | Caching + tiering; not Batch |
+
+## Claude Code note
+
+In Claude Code, prompt caching is automatic — resending the same context prefix
+is cheap, so keeping a stable prefix pays off without any explicit
+`cache_control`. The session-level hygiene levers are `/clear` and `/compact` to
+shed accumulated context, plus subagent delegation for verbose output so it
+never lands in the main context window.
+
+## See also
+
+- [`model-recommendation.md`](model-recommendation.md) — tier routing (the
+  capability band behind lever 3).
+- [`size-and-scope.md`](size-and-scope.md) — token discipline for the artifacts
+  that become the cached prefix.
+- The Claude Code `claude-api` plugin skill (external, not vendored here) — the
+  authoritative, versioned API reference these figures derive from; re-check it
+  when Anthropic pricing or the caching/batch surface changes.

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

@@ -0,0 +1,76 @@
+# 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
+
+Ask up to **5** 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](../../../src/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):
+
+- Extend an existing one?
+- Create a new one — gap is real?
+- Show overlap first?
+- Promote via `learning-to-rule-or-skill` instead?
+
+Carry the summary into the commit message (*"Reviewed before drafting:
+X, Y"*).
+
+## 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.
+- Batch mode never skips the Research pass itself — it relocates and
+  batches it. `artifact_protocol: skip` does not exist.
+
+## 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/docs/guidelines/agent-infra/context-hygiene-mechanics.md

@@ -0,0 +1,90 @@
+# 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/runtime/state/context-hygiene.json` is not maintained automatically
+(turn 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.

package/docs/guidelines/agent-infra/domain-adoption-gates.md

@@ -0,0 +1,112 @@
+# Domain Adoption — Gates
+
+> The three-gate evidence contract, sunset policy, and failure-mode catalog for the `domain-adoption-policy` rule
+
+_Origin: migrated from `src/rules/domain-adoption-policy.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law and the three gate names stay in the rule; this file carries the per-gate evidence bars and procedures._
+
+## Gate 1 — Demand signal
+
+At least one of the following must be **true and citeable** in the roadmap:
+
+- **≥ 2 consumer projects** in the domain. Cite repository names or
+  `agents/settings/contexts/` notes — not "I think there might be".
+- **Named user direction with target.** A specific user ask plus a target
+  project / use case — e.g. "harvest the mobile skills for project X, due
+  next quarter". Vague *"this might be useful"* does not count.
+- **Public-incident pull.** A reproducible incident on a consumer project
+  the domain would have prevented, captured in `agents/settings/contexts/` with
+  the missing surface area named.
+
+If none of the three is citeable, **defer**. Open a watch-only context note
+under `agents/settings/contexts/domain-watch/<domain>.md` listing the missing signal
+so the next harvest can re-evaluate without re-relitigating the case.
+
+## Gate 2 — Named maintenance owner
+
+Domain plates rot. Pick the owner before the import, not after.
+
+- The roadmap names a **single maintainer** (not "the team", not "TBD")
+  responsible for the domain quarterly review.
+- The owner commits to the **refresh cadence** — quarterly review at
+  minimum, faster if the domain is volatile (mobile RN/Expo SDK,
+  ML model APIs).
+- Each adopted artefact carries an **inline upstream-source line** with
+  SHA + last-checked timestamp so refresh is mechanical, not archaeological.
+
+If no owner is named or no cadence is set, **defer**. An unowned domain
+plate becomes broken authoritative-links and stale skills inside two cycles.
+
+## Gate 3 — CI-tooling decision
+
+Either the domain's verification tooling is validated in CI, or the suite
+explicitly accepts platform-bound reference-only status.
+
+- **Validated.** The CI pipeline runs the relevant linters/tests/integration
+  checks for the domain (e.g. `mobile-e2e` runners, ML model validation,
+  contract conformance) on every PR. Cost noted in the roadmap risk
+  register.
+- **Out-of-scope (reference-only).** The domain is a platform fact the
+  suite cannot validate (iOS Simulator on non-macOS runners, GPU-bound
+  ML, hardware-bound IoT). The roadmap states this explicitly; affected
+  artefacts carry a "reference-only on \<unsupported platforms\>" header
+  so consumers do not file false-positive bugs.
+
+If neither line is drawn, **defer**. Half-validated CI silently rots the
+domain — green builds while the underlying tooling drifts.
+
+## Sunset Policy stacks on top
+
+Every domain track inherits the authoritative-link Sunset path documented
+in any plate that imports volatile upstream content:
+
+- Volatile content (SDK-pinned, API-pinned, tool-version-pinned) lives as
+  guideline body + SHA-pinned upstream link, not as forked scripts.
+- Refresh trigger: quarterly cadence or earlier if a SHA-pinned link
+  404s in CI.
+- The `check-refs` and `check-portability` linters apply unchanged.
+
+Adopting a domain does not exempt it from any other suite-wide rule —
+`augment-edit-discipline`, `skill-quality`, `size-enforcement`,
+`rule-type-governance`. Every domain artefact passes the same gates as a
+core artefact.
+
+## Failure modes
+
+- *"It's just one skill, not a domain."* — Audit the skill's prerequisites.
+  If it pulls in a new toolchain, simulator, language runtime, or
+  platform-specific build system, it **is** a domain entry. Run the gates.
+- *"The upstream is well-maintained, we can just track it."* — Tracking
+  upstream means owning the diff, the breaking changes, and the migrations.
+  Tracking is maintenance work; budget for it under Gate 2 or skip the
+  adoption.
+- *"We'll add CI later."* — Later does not arrive. Either CI is wired in
+  the same plate, or the artefacts ship with explicit reference-only
+  headers so users do not assume validated coverage.
+- *"Council convergence is enough."* — Council informs the gates; it does
+  not replace them. A council session may surface that all three gates
+  pass; the roadmap still cites the evidence.
+- *"Demand-signal is the user asking once."* — Single-shot interest is a
+  watch trigger, not an open trigger. Either name the target use case
+  with project + timeline, or open a watch note and wait.
+
+## What to do when the gates fail
+
+1. Mark the domain plate `[-] gated — <gate name> not met` in the relevant
+   roadmap. Do **not** silently shrink scope to dodge the gate.
+2. Open a watch-only context note under `agents/settings/contexts/domain-watch/`
+   capturing what's missing — citations, owner candidates, CI feasibility.
+3. Re-evaluate at the next harvest cycle. The note is the evidence trail
+   so the same questions are not relitigated.
+
+## Allowed without gates
+
+- Adding **a single skill** to an **already-opened** domain follows the
+  regular harvest plate; the gates do not re-fire per skill.
+- Authoring a **guideline** that documents a domain the suite already
+  ships in — the domain is open, the guideline is a within-domain artefact.
+- A **rule** that constrains an already-opened domain — within-domain.
+
+## See also
+
+- `domain-adoption-policy` (rule) — the Iron Law + gate names.
+- `size-enforcement` · `rule-type-governance` · `skill-quality` — the suite-wide floors every domain artefact still passes.

package/docs/guidelines/agent-infra/framework-neutrality-patterns.md

@@ -0,0 +1,66 @@
+# Framework Neutrality — Patterns
+
+> Forbidden-pattern table, cross-stack documentation allowance, and carve-out pointer shape for the `framework-neutrality-in-generic-skills` rule
+
+_Origin: migrated from `src/rules/framework-neutrality-in-generic-skills.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, scope, and exemption list stay in the rule; this file carries the pattern reference._
+
+## Forbidden patterns in generic artifacts
+
+| Pattern | Why it leaks | Fix |
+|---|---|---|
+| `FormRequest` as a mandate | Laravel-only validation class | Say "request-validation primitive (FormRequest in Laravel, zod in Next.js, pydantic in FastAPI)" or move to `laravel-validation` carve-out |
+| `php artisan …` as a canonical command | Laravel CLI | Generalize to "the framework's CLI" or move to `artisan-commands` carve-out |
+| `PHPStan` as the only example | PHP-only static analyser | List peers (`mypy` for Python, `tsc` for TypeScript) or move to `quality-tools` carve-out |
+| `composer.json` mentioned alone | PHP package manifest | Add `package.json` / `pyproject.toml` peers, or move to a PHP-scoped carve-out |
+| `Eloquent` / `Model::…` | Laravel ORM | Generalize to "the project's ORM/data layer" or move to `eloquent` carve-out |
+| `Pest` as the only test runner | PHP/Laravel test framework | List peers (`pytest`, `vitest`, `jest`) or move to `pest-testing` carve-out |
+| `Blade` / `Livewire` / `Flux` as default UI | Laravel view stack | Generalize to "the project's UI layer" or move to `blade-ui` / `livewire` / `flux` carve-outs |
+| `vendor/bin/<tool>` as a canonical path | PHP/Composer-specific binary path | Say "the project's quality CLI" or carve-out it |
+| `Rector` as the only refactor tool | PHP-only refactorer | List peers (`ts-morph`, `libcst`) or carve-out it |
+| "every controller" / "all controllers" | Assumes MVC PHP framework | Generalize to "every request handler" / "every endpoint" |
+
+## Allowed: cross-stack documentation
+
+Multi-stack tables or detection maps with **at least two ecosystems
+side-by-side** are documentation, not leakage. The linter's
+auto-detect heuristic skips a hit when its ±2-line window contains
+patterns from a different ecosystem family (`php_family` vs
+`js_family` vs `python_family`).
+
+Example (allowed):
+
+```
+- PHP/Composer project → `composer.json` present
+- Node project        → `package.json` present
+- Python project      → `pyproject.toml` present
+```
+
+## Allowed: carve-out pointers
+
+A generic artifact may end a section with a one-line handoff to its
+framework-specific peers. Canonical shape:
+
+```
+→ Laravel-specific: see [laravel-validation](../skills/laravel-validation/SKILL.md)
+→ Next.js-specific: see [nextjs-patterns](../skills/nextjs-patterns/SKILL.md)
+```
+
+The pointer is a link, not a procedure — the generic artifact never
+inlines stack-specific code.
+
+## Enforcement
+
+`scripts/lint_framework_leakage.ts` runs in the package CI pipeline.
+Exit codes:
+
+- `0` — no hits, or every hit is auto-detected as cross-stack, or
+  every hit is allowlisted in
+  `scripts/lint_framework_leakage_allowlist.json` with a `reason`.
+- `1` — at least one hit in a generic artifact (non-carve-out) that
+  is neither cross-stack nor allowlisted.
+
+## See also
+
+- `framework-neutrality-in-generic-skills` (rule) — Iron Law, scope, exemption list.
+- `roadmap-ci-steps-policy` — sibling Tier-2a rule that drove this pattern.
+- `skill-quality` — every skill must remain executable; carve-outs must still pass skill-quality.