@event4u/agent-config 8.13.0 → 9.0.0

package/docs/catalog.md

@@ -569,11 +569,11 @@ are excluded.
 | command | [`team-knowledge`](../dist/agent-src/commands/team-knowledge.md) | cluster: team-knowledge | Team-knowledge orchestrator — routes to consolidate and bootstrap |
 | command | [`team-knowledge-bootstrap`](../dist/agent-src/commands/team-knowledge/bootstrap.md) | cluster: team-knowledge | One-shot deterministic seed for a fresh project's knowledge layer — stages template pages from real config/directory detection, never LLM-invented claims. Review-then-commit. |
 | command | [`team-knowledge-consolidate`](../dist/agent-src/commands/team-knowledge/consolidate.md) | cluster: team-knowledge | Review pending typed knowledge-observation events and file them into agents/knowledge/ pages as a human-reviewed batch — never writes without approval. |
-| command | [`team`](../dist/agent-src/commands/team.md) | cluster: team | Team orchestrator — cross-model depth review (one strong model builds, a second reviews the real diff); routes to review, adversarial, delegate, status |
+| command | [`team`](../dist/agent-src/commands/team.md) | cluster: team | Team orchestrator — governed cross-model access layer (a second strong model reviews the real diff; read-only multi-host fallback); routes to review, adversarial, delegate, status |
 | command | [`team-adversarial`](../dist/agent-src/commands/team/adversarial.md) | cluster: team | Thin wrapper — adversarial cross-model review on a named focus via the official plugin (/codex:adversarial-review). Escalation rung above the single-model adversarial-review skill. |
 | command | [`team-delegate`](../dist/agent-src/commands/team/delegate.md) | cluster: team | Thin wrapper — hand a task to the second model as a native worker via the official plugin (/codex:rescue). The only write-access wrapper; double-gated behind ai_team.allow_delegate. |
 | command | [`team-review`](../dist/agent-src/commands/team/review.md) | cluster: team | Thin wrapper — cross-model review of the current diff via the official plugin (/codex:review). Gated on ai_team.enabled; fails closed when the plugin is absent. |
-| command | [`team-status`](../dist/agent-src/commands/team/status.md) | cluster: team | Thin wrapper — plugin job status via /codex:status plus a ledger line with today's cli_call_budget openai count. Gated on ai_team.enabled; fails closed when the plugin is absent. |
+| command | [`team-status`](../dist/agent-src/commands/team/status.md) | cluster: team | Thin wrapper — plugin job status via /codex:status plus a quota block showing the shared openai counter against both ceilings (team + council). Gated on ai_team.enabled; fails closed when the plugin… |
 | command | [`tests`](../dist/agent-src/commands/tests.md) | cluster: tests | Tests orchestrator — routes to create, execute, e2e-plan, e2e-heal |
 | command | [`tests-create`](../dist/agent-src/commands/tests/create.md) | cluster: tests | Write meaningful tests for the current branch — stack-adaptive (pest / phpunit / vitest / jest / pytest / …) |
 | command | [`tests-e2e-heal`](../dist/agent-src/commands/tests/e2e-heal.md) | cluster: tests | Find, debug, and fix failing Playwright E2E tests |

package/docs/contracts/ai-council-config.md

@@ -787,11 +787,18 @@ error) when any of these hold:
 
 ## Migration footprint (Phase 0)
 
+> Historical record of the Step-2 consolidation. **The project-local file
+> described below is no longer read** — ADR-104 (superseding ADR-093) moved
+> the council config to the user-global location documented at the top of
+> this contract. A `.ai-council.yml` under any project `agents/` tree is
+> ignored. Read this section for provenance only, not for placement.
+
 - `.agent-settings.yml` → 14-key inventory under `ai_council:` removed
   after a one-line breadcrumb comment is in place pointing at this
   contract.
 - `.agent-settings.template.yml` → same removal.
-- New file `agents/settings/.ai-council.yml` checked in with two enabled
+- New file `agents/settings/.ai-council.yml` checked in with two enabled <!-- council-config-allowed -->
   providers (anthropic + openai) and three disabled
   (gemini + xai + perplexity). Models pre-filled from the Phase 0
-  default set; comments mirror this contract.
+  default set; comments mirror this contract. *(This project-tracked file
+  was later removed; per ADR-104 the config is user-global only.)*

package/docs/contracts/ai-team-config.md

@@ -47,6 +47,9 @@ ai_team:
   allow_delegate: <bool>          # second opt-in for the write path, default false
   max_calls_per_day: <int >= 0>   # default 50; counts into the shared openai bucket
   suppress_setup_hint: <bool>     # default false; cosmetic wizard-hint suppression
+  review_gate:                    # managed governance of the plugin's Stop-hook Review Gate
+    managed: <bool>               # default false = byte-identical pre-Phase-4 behavior
+    max_consecutive_blocks: <int >= 1>  # default 3; circuit-breaker loop bound
 ```
 
 | Key | Type | Default | Semantics |
@@ -56,6 +59,8 @@ ai_team:
 | `allow_delegate` | bool | `false` | Second opt-in for the **only** wrapper that delegates write access (`/team:delegate`). Refuses with an enable pointer until BOTH `enabled` and `allow_delegate` are `true`. |
 | `max_calls_per_day` | int ≥ 0 | `50` | Per-day ceiling on team calls, read against the **shared** `cli_call_budget` openai bucket (see § Quota). `0` blocks all team calls. |
 | `suppress_setup_hint` | bool | `false` | Suppress the one-line wizard/init recommendation to install the codex plugin on Claude-Code hosts. Cosmetic only. |
+| `review_gate.managed` | bool | `false` | Managed governance of the codex plugin's Stop-hook Review Gate (Phase 4). `false` = no counting, no circuit breaker — the Stop path is byte-identical to pre-Phase-4 dispatch. `true` = consecutive BLOCK verdicts are counted per session (first-line `ALLOW:`/`BLOCK:` contract of the gate transcript; anything else is honestly `UNKNOWN` and never counted) and the circuit breaker trips at the bound. |
+| `review_gate.max_consecutive_blocks` | int ≥ 1 | `3` | Circuit-breaker bound. At this many CONSECUTIVE BLOCKs in one session a visible notice is injected **exactly once** and the managed layer stops re-blocking — the user decides, never an infinite Claude↔Codex loop. An ALLOW verdict resets the counter. Unknown keys inside `review_gate` are rejected fail-closed, same as the parent block. |
 
 ### Why `model: 'auto'` instead of a pinned ID
 
@@ -68,10 +73,14 @@ default, and only the codex CLI knows what that currently is. `'auto'`
 therefore delegates the choice to the CLI; a set value is a user pin and
 passes through verbatim — the loader never rewrites or "corrects" it.
 
-**Future keys:** `review_gate` (managed, loop-bound governance of the
-plugin's Stop-hook Review Gate) is reserved for a later team-mode phase
-(Phase 4). Do not add it — or any other key — ahead of its phase; the
-loader rejects unknown keys today by design.
+**`review_gate` (Phase 4, shipped):** the loop-bound governance block is
+live — module `src/scripts/ai_team/review_gate.ts` (counter state under
+`agents/runtime/state/team-review-gate.json`, ledger under
+`agents/runtime/team/events.log`, one `team.gate: BLOCK 2/3` /
+`ALLOW reset` line per gate verdict). The gate itself stays upstream's;
+upstream's own warning applies while it is enabled unmanaged: "The
+review gate can create a long-running Claude/Codex loop and may drain
+usage limits quickly." Any other key stays rejected fail-closed.
 
 ## Role semantics — the council-verdict design constraint
 
@@ -141,6 +150,30 @@ same *counter*: whichever path a call takes, it increments the one shared
 bucket, and each surface enforces its own configured cap against that
 shared count.
 
+**Worked example — two ceilings, one counter.** Council ceiling
+`cli_call_budget.max_calls_per_day.openai: 100`, team ceiling
+`ai_team.max_calls_per_day: 50`, shared counter at 45 openai calls today:
+both paths are open. Five team calls later the counter reads 50 — team
+calls are now blocked (50 >= 50) while council CLI calls continue until
+the counter reaches 100. Whichever path fires a call, the same counter
+moves; each surface only decides where *its* ceiling sits on that shared
+count. `/team status` renders exactly this state: the live counter, both
+ceilings, and which path (if any) is currently blocked.
+
+### Team-review envelope
+
+Every `/team:review` return — plugin path and multi-host fallback alike — is emitted in the
+team-review status envelope (`src/skills/subagent-orchestration/schemas/team-review-status.json`),
+which extends the `subagent-status.json` frame: `status` (`DONE | DONE_WITH_CONCERNS |
+NEEDS_CONTEXT | BLOCKED`), `findings[]` (`severity`/`evidence`/`suggested_fix`/`location?`),
+`reviewed_ref` (HEAD sha of the bundle), `model` (`'auto'` = codex CLI default), and
+`quota` (`{used, ceiling}` on the shared `cli_call_budget` openai bucket); unparseable model
+output is preserved verbatim in `raw` with status `DONE_WITH_CONCERNS` — never silently dropped.
+Plugin text is summarized INTO the envelope and preserved verbatim beneath — never rewritten.
+<!-- PLACEHOLDER: the team-review-envelope subsection (review-gate ledger
+     line format `team.gate: BLOCK n/N` read by /team status) is inserted
+     here by the orchestrator in a later step. Do not remove this marker. -->
+
 ## Validation rules (fail-closed)
 
 `load_ai_team_config` / `build_ai_team_config`

package/docs/contracts/prelaunch-diagnostics.md

@@ -0,0 +1,151 @@
+# Pre-Launch Diagnostics — finding IDs, epistemics, regression gate
+
+> Contract for the consumer-facing launch diagnostic
+> (road-to-ecosystem-harvest-prelaunch-diagnostics, Source L — a
+> production-readiness diagnostic skill; provenance in the harvest index).
+> The consumer-side sibling of the suite's own claims-ledger: a "ready"
+> verdict cannot be reached by assertion.
+>
+> Schema: [`prelaunch-report.schema.json`](../../src/scripts/schemas/prelaunch-report.schema.json) ·
+> Area vocabulary: [`prelaunch-areas.yml`](../../src/config/prelaunch-areas.yml) ·
+> Tooling: [`prelaunch_diagnostics.ts`](../../src/scripts/prelaunch_diagnostics.ts) ·
+> Skill surface: [`launch-readiness`](../../src/skills/launch-readiness/SKILL.md).
+
+## 1 — Finding-ID grammar (immutable, diff-stable)
+
+```
+AC-<AREA>-NNN        e.g. AC-AUTH-003, AC-RBK-001
+```
+
+- `<AREA>` — the uppercase code of a coverage area from
+  [`prelaunch-areas.yml`](../../src/config/prelaunch-areas.yml). The vocabulary
+  is **append-only**: codes are never renamed or re-used.
+- `NNN` — zero-padded, monotonically assigned per area, **never re-assigned**.
+  A finding that is retitled, re-scoped, or resolved keeps its ID forever; a
+  genuinely new problem gets the next number. Resolved findings stay in the
+  report with a flipped `status` — the entry never disappears, so baselines
+  diff cleanly across months.
+- The **ID is the diff key**. Titles, evidence, and severity are mutable
+  metadata; two runs are compared by ID set + per-ID state, never by prose.
+
+## 2 — Epistemics (Pass needs evidence; Unknown ≠ Pass)
+
+Every coverage area carries exactly one state:
+
+| State | Meaning | Requirement |
+|---|---|---|
+| `pass` | Diagnosed clean | **Cited evidence required** — file:line, command output, run URL. A pass without evidence fails validation: that is assertion, not diagnosis. |
+| `finding` | At least one open finding | The finding IDs live in `findings[]`. |
+| `unknown` | Not diagnosed | The honest default. **Absence of findings is `unknown`, never an automatic `pass`.** An area missing from the report entirely is `unknown` by definition. |
+| `not-applicable` | Does not exist on this surface | **Reason required** ("no DB → no migrations"). |
+
+Verdict rule (the launch gate):
+
+```
+ANY OPEN P0 FINDING → NOT READY, REGARDLESS OF EVERY OTHER AREA.
+ANY OPEN P1, OR A launch_gate AREA NOT AT pass/not-applicable → NOT READY.
+READY IS THE RESIDUAL STATE, NEVER THE DEFAULT.
+```
+
+`launch_gate: true` areas (auth, migrations, secrets, rollback) block the
+verdict while `unknown`; non-gate areas (observability, agent-governance)
+surface as unknowns + questions but do not block alone.
+
+## 3 — Coverage backbone
+
+The area vocabulary is deliberately pruned to the stacks this suite targets:
+**auth · migrations · secrets · observability · rollback · agent-governance**.
+It is not a generic compliance matrix — new areas enter by appending to
+`prelaunch-areas.yml` with a maintainer-reviewed `launch_gate` decision.
+
+Every report may carry a `questions` list — **questions that would change the
+diagnosis** ("is the admin panel exposed on the same origin?"). Questions are
+the actionable rendering of unknowns; the next run should convert them into
+evidence or findings.
+
+## 4 — Regression gate (findings diff)
+
+`prelaunch_diagnostics.ts diff <baseline.json> <current.json>` compares two
+reports **by ID**:
+
+- **new** — ID in current, not in baseline.
+- **resolved** — open in baseline, `fixed` in current.
+- **regressed** — a `launch_gate` area that was `pass` in the baseline and is
+  `finding`/`unknown` in current (Pass→Finding flip).
+- **retitled findings do not appear in the diff** — the ID survives the
+  rename (acceptance-tested).
+
+`--ci` mode exits non-zero when the diff contains a **new open P0/P1** or a
+**Pass→Finding flip in a launch-gate area** — the consumer-side sibling of the
+suite's claims-ledger CI. Everything else (new P2/P3, resolved findings,
+question churn) reports informationally and exits 0.
+
+## 5 — Suppression (evidence-backed, never silent)
+
+A consumer may suppress a finding via the project-local suppression file
+`agents/settings/prelaunch-suppressions.yml`:
+
+```yaml
+schema_version: prelaunch-suppressions-v1
+suppressions:
+  - id: AC-OBS-002
+    reason: "Dashboards land with the Q3 observability epic; alerting for the launch path exists."
+    evidence: "agents/evidence/prelaunch/obs-alerting.png"
+```
+
+- A finding with `status: suppressed-with-evidence` MUST have a matching
+  suppression entry carrying **both** `reason` and `evidence` — validation
+  fails otherwise.
+- Suppressed findings are excluded from the `--ci` triggers but **render in a
+  collapsible "suppressed" section** of the report output — the same
+  transparency contract as the review cluster's dropped-false-positives list.
+  Suppression hides nothing; it moves the item behind a fold with its receipt.
+- Suppressing a P0 does not restore a ready verdict — P0 caps the verdict
+  regardless (§ 2).
+
+## 6 — Consumer recipe (opt-in CI gating)
+
+1. Run the diagnostic (via `launch-readiness` § epistemics) and save the
+   report to `agents/evidence/prelaunch/baseline.json`. Commit it.
+2. Before a launch, produce a fresh `current.json` and run
+   `prelaunch_diagnostics.ts diff baseline.json current.json --ci` in the
+   pipeline — red on a new P0/P1 or a launch-gate Pass→Finding flip.
+3. After the launch settles, promote `current.json` to the new committed
+   baseline (a reviewed diff, like any lockfile bump).
+
+## 7 — Fix-loop discipline (Phase 3)
+
+- Rank open findings by severity, then by launch-gate membership.
+- Propose the **safest first approval batch** — explicitly the first *safe*
+  batch (reversible, small blast radius), not the full backlog. Approval is
+  the user's; the diagnostic never self-authorizes fixes
+  ([`autonomous-execution`](../../src/rules/autonomous-execution.md) and the
+  reversibility floor govern, unrestated).
+- Per-finding status vocabulary (schema-enforced): `open · fixed ·
+  accepted-risk · deferred-with-reason · suppressed-with-evidence ·
+  not-applicable` — everything except open/fixed carries a `reason`.
+- **Rescore whenever evidence changes** — a fix, a new probe, or an answered
+  question re-runs the affected area, never the memory of it.
+
+## 8 — Read-only guarantee
+
+The diagnostic **never mutates a consumer project**: the tooling reads
+reports and writes nothing outside its own output. Fixes flow through the
+normal approval-gated engines, not through this contract.
+
+## 9 — Score: council-locked (do not add)
+
+The pass-1 council **dropped the 0–100 readiness score** (gameable false
+precision). A severity-capped, never-published internal-ordering variant is
+**surfaced for council re-evaluation in the roadmap's revisit note — not
+adopted**. Until that revisit resolves: no numeric score field in the schema,
+no score in any rendered output, no score in CI messages. The ID scheme,
+epistemics, diff gate, and suppression above stand on their own.
+
+## See also
+
+- [`launch-readiness`](../../src/skills/launch-readiness/SKILL.md) — the skill
+  surface that produces the report.
+- [`docs/proof.md`](../proof.md) — the suite-side claims-ledger this mirrors.
+- `road-to-ecosystem-harvest-reliability-measurement` (archived) — measures the
+  *suite itself*; this contract measures the *consumer's launch surface*.

package/docs/contracts/release-pr-gating.md

@@ -81,6 +81,7 @@ the feature-PR floor by adding:
 | `release-validation.yml` (Phase B) | `changelog-entry` | CHANGELOG carries an entry matching the head-branch version |
 | `release-validation.yml` (Phase B) | `version-consistency` | `package.json` / `marketplace.json` / pack manifests agree on the version |
 | `consumer-matrix.yml` | `consumer-matrix` · `publish-dry-run` · `mcp-worker-dry-run` · `plugin-bootstrap` | pack-based consumer E2E + pre-tag dry-runs of the release-adjacent workflows — see the exemption note below |
+| (maintainer-local) | `task smoke-host-loadability REQUIRE=1` | real-host loadability — `claude plugin validate` + temp-home plugin install + metadata cross-consistency (marketplace ↔ plugin dirs ↔ docs). Optional in CI (runners lack the claude CLI, the step self-skips); **required before a release is cut** — `REQUIRE=1` turns a missing CLI into a failure |
 
 ## Consumer-matrix exemption — the tarball window
 

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 274 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 274 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 183 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 274 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.
 
 > **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

@@ -180,19 +180,30 @@ Your agent now understands slash 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 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.