@event4u/agent-config 8.12.0 → 9.0.0

package/docs/getting-started.md

@@ -174,7 +174,48 @@ 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 178 active commands](../dist/agent-src/commands/)
+→ [Browse all 183 active commands](../dist/agent-src/commands/)
+
+---
+
+## Team mode — cross-model review (default off)
+
+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*. 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 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.
+
+**Default off.** Team mode ships disabled (`ai_team.enabled: false` in
+`.agent-settings.yml`); no team command runs and no cross-model call is
+made until you opt in.
+
+**No lift claim.** Whether cross-model team review catches more real
+defects than single-model adversarial self-review is **unproven** — the
+package makes no review-quality claim until the pre-registered benchmark
+has run and its verdict is recorded.
 
 ---
 

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 274 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/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.

package/docs/guidelines/agent-infra/minimal-safe-diff-mechanics.md

@@ -0,0 +1,99 @@
+# Minimal Safe Diff — Mechanics
+
+> Anti-over-engineering criteria, larger-change guidance, break-glass exception, and the bounded remediation carve-out for the `minimal-safe-diff` rule
+
+_Origin: migrated from `src/rules/minimal-safe-diff.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, "The rule", "Before writing the diff", the red-flags list, and "Own-orphan cleanup" (anchor-referenced by `downstream-changes`) stay in the rule; this file carries the worked criteria._
+
+## When the task seems to require a larger change
+
+- A rename, restructure, or framework upgrade that crosses the minimal-diff
+  line is a **separate, explicit** task — ask the user before expanding.
+- A bug fix that exposes a broader design problem stays a bug fix. Log the
+  design problem as a follow-up (ticket, note, TODO) and ship the fix alone.
+- A new feature that tempts you to "clean up" the module first: resist.
+  Add the feature, commit it, then propose the cleanup as a separate change.
+
+## Auto-formatter or linter rewrites unrelated code
+
+Revert those hunks before staging. The diff you present is the diff you own.
+If project policy forbids partial formatting, split into two commits:
+*format only* · *behavior change*.
+
+## Anti-over-engineering
+
+The smallest change is also the least *abstract* and least *speculative* one:
+
+- **Three similar lines beat a premature abstraction.** Do not extract a helper
+  / generic / config layer to dedupe two or three call sites — inline
+  repetition is cheaper to read and change than the wrong abstraction. Per new
+  abstraction: **cite the second caller — or inline it.**
+- **No speculative features.** Nothing beyond what was asked: no
+  configurability or "flexibility" nobody requested, no parameters with one
+  call site, no error handling for scenarios that cannot occur in this
+  codebase.
+- **The rewrite trigger.** If the change could be half the size without losing
+  behavior, rewrite before presenting. Self-check: *"Would a senior engineer
+  call this overcomplicated?"* — if yes, simplify.
+- **No tombstones.** Delete removed code completely — no `_oldName` renames,
+  no `// removed X` / `// no longer used` markers, no dead re-export shims kept
+  "for safety". Git history is the tombstone.
+- **No docstrings/comments on untouched code.** Do not annotate code the diff
+  does not change.
+
+Wrong/right pairs for each ban:
+[`simplicity-and-goal-demos`](simplicity-and-goal-demos.md)
+— the demos are the recognition surface; match your diff against the *right*
+column before presenting.
+
+**Not adopted (council):** the source's "validate only at system boundaries /
+trust internal code" clause is **rejected** — internal code can be wrong, and
+"trust" is not a testing strategy. Keep validating internal invariants; this
+fold is about *diff shape*, not about dropping internal checks.
+
+## Break-glass exception
+
+The rule stays in force during production incidents. "Break-glass mode"
+narrows verification (see `verify-before-complete`) — it does **not**
+license drive-by edits.
+
+Allowed during break-glass:
+
+- The **smallest** change that stops the bleeding — one file, one
+  method, one guard — preferred over any refactor.
+- A fast revert to a known-good commit, even if it undoes unrelated
+  improvements shipped in the same PR.
+
+Not allowed, even in break-glass:
+
+- "While I'm in there" cleanups, reformatting, or dependency bumps.
+- Expanding the fix to neighboring modules without evidence they are
+  part of the incident.
+- Merging the hotfix with pending refactors from another branch.
+
+After the incident, open a **follow-up PR** for any scope that was
+intentionally deferred and reference the break-glass commit in its
+description.
+
+## Bounded remediation carve-out
+
+The default stands: no drive-by edits, no opportunistic refactors. The one
+bounded exception — a **small, task-aligned security/correctness fix in code
+the current task already touches** — is governed by `active-remediation`
+(mechanics: [`active-remediation-mechanics`](active-remediation-mechanics.md)).
+It is permitted inline **only** when ALL hold: same request path / module,
+≤ ~10 changed lines in one production file (plus its test file), no
+public-API / response-shape change, no dependency bump or migration, and its
+verification (e.g. the negative test) ships in the same commit. Anything
+outside those five conditions is **not** this carve-out — it is note + ask
+per `active-remediation`. This never licenses reformatting, renames,
+dependency bumps, or version upgrades (a syntax-idiom modernization is
+allowed only under `active-remediation`'s version-gated,
+behavior-preserving clause; a dependency/version bump stays ask-only). The
+sole case that may interrupt is a **live cross-user/tenant data exposure**
+(`broken-access-control`) — fix-now-if-small, else stop and surface; never
+defer it silently.
+
+## See also
+
+- `minimal-safe-diff` (rule) — Iron Law, the rule, pre-diff checklist, red flags, own-orphan cleanup.
+- [`active-remediation-mechanics`](active-remediation-mechanics.md) — the fix-now / note+ask / follow-up-PR ladder detail.

package/docs/guidelines/agent-infra/skill-quality-checklist.md

@@ -17,6 +17,19 @@ Every skill must answer four questions. If ANY answer is weak, the skill is not
 | 3 | How do I verify it worked? | `Procedure` (validation step) | Concrete checks, not "verify it works" |
 | 4 | What common failure must I avoid? | `Gotcha` + `Do NOT` | Real failure patterns, not platitudes |
 
+## Register — explain the trade-off, except in the safety kernel
+
+Two registers, chosen by artifact class (U4, ecosystem harvest 2026-07-13):
+
+- **Capability skills** (workflows, analyses, generators) **explain the
+  trade-off** — say *why* the recommended path beats the alternative instead of
+  shouting ALL-CAPS MUSTs; an agent that understands the why generalizes to
+  cases the skill never enumerated.
+- **The safety kernel keeps its imperative Iron-Law register** — kernel rules,
+  safety floors (`*-safety-floor`), and Hard-Floor surfaces stay ALL-CAPS
+  fenced-law imperative, non-negotiable (`preservation-guard` enforces the
+  byte-level protection). Never downgrade an Iron Law to friendly prose.
+
 ## Required Sections
 
 Every skill MUST have: `When to use`, `Procedure`, `Gotcha`, `Output format`, `Do NOT`.