@event4u/agent-config 2.12.0 → 2.14.0

package/docs/contracts/installed-tools-lockfile.md

@@ -12,7 +12,8 @@ repository.
 - **Authoritative module:** [`scripts/_lib/installed_tools.py`](../../scripts/_lib/installed_tools.py)
 - **ADR:** [`docs/decisions/ADR-008-installed-tools-manifest.md`](../decisions/ADR-008-installed-tools-manifest.md)
 - **Workflow guide:** [`docs/guidelines/agent-infra/installed-tools-manifest.md`](../guidelines/agent-infra/installed-tools-manifest.md)
-- **Active roadmap:** P1.1 of [`agents/roadmaps/road-to-multi-package-coexistence.md`](../../agents/roadmaps/road-to-multi-package-coexistence.md)
+- **Active roadmap:** P1.1 of the `road-to-multi-package-coexistence`
+  roadmap (see `agents/roadmaps/` for current status).
 
 ## Versions
 

package/docs/contracts/low-impact-corpus-format.md

@@ -0,0 +1,95 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+# `low-impact-decisions.md` — corpus format contract (step-9 P4)
+
+Parser-visible invariants for `agents/low-impact-decisions.md` and any
+upstream seed at the same path. The hardened parser lives in
+[`scripts/ai_council/low_impact_corpus.py`](../../scripts/ai_council/low_impact_corpus.py)
+and ships in two modes:
+
+| Mode | Entry point | Behaviour on drift |
+|---|---|---|
+| **Lenient** (routing hot-path) | `load_validated_phrases(path)` | Silently drops the offending line. Routing never blocks on a malformed corpus. |
+| **Strict** (CI lint + intake) | `parse_corpus_strict(path)` | Raises `CorpusParseError` with a typed `reason` and 1-based `line` on the first anomaly. |
+
+## Required sections
+
+```
+## On Probation
+
+<!-- intake-anchor: probation -->
+
+…
+
+## Validated
+
+<!-- intake-anchor: validated -->
+
+…
+
+## Anti-Examples (Always Ask User)
+
+…
+```
+
+- Heading level **MUST** be `##` (two hashes). `###` → `heading_drift`.
+- Trailing punctuation on a heading (`## Validated:`) → `heading_drift`.
+- Sections may appear in any order; missing sections are tolerated by
+  both modes (an empty corpus is valid).
+- The intake-anchor HTML comments **MUST** be present for the two
+  intake-bearing sections (`probation`, `validated`) once any section
+  body is present. Strict mode raises `missing_anchor` otherwise; the
+  lenient shim ignores anchors (anchors are for the intake writer, not
+  the routing reader).
+
+## Bullet shape
+
+```
+- "<phrase>" — optional trailing metadata
+```
+
+Strict invariants:
+
+| Drift | `reason` | Example |
+|---|---|---|
+| Curly opening quote (`U+201C` / `U+2018`) | `curly_quotes` | `- “foo bar”` |
+| Single-quoted phrase | `single_quotes` | `- 'foo bar'` |
+| Non-dash list marker (`*`, `+`, `1.`) | `non_dash_bullet` | `* "foo bar"` |
+| Opening `"` with no matching close on the same line | `unclosed_quote` | `- "foo bar — meta` |
+| Phrase normalises to empty (whitespace / punctuation only) | `empty_phrase` | `- "   …"` |
+
+Trailing metadata (everything after the closing `"`) is preserved on
+the `CorpusEntry.trailing_metadata` field but is **not** consulted for
+routing — only the normalised phrase is.
+
+## Phrase normalisation
+
+A phrase is normalised before equality / similarity comparison:
+
+1. Lowercase.
+2. Replace every non-`[\w\s]` character with a single space.
+3. Collapse runs of whitespace.
+4. Strip leading / trailing whitespace.
+
+This normalisation runs in both modes and is stable across the
+routing classifier (`classify_impact_with_corpus`), the intake module
+(`low_impact_intake`), and the probation gate.
+
+## Failure-mode fixtures
+
+The seven canonical failure cases ship as fixtures under
+[`tests/fixtures/corpus-robust/`](../../tests/fixtures/corpus-robust/),
+one file per `reason`. The strict-mode suite
+[`tests/test_low_impact_corpus_robustness.py`](../../tests/test_low_impact_corpus_robustness.py)
+asserts each fixture trips the matching `CorpusParseError.reason` and
+that the lenient shim degrades silently for per-bullet drift.
+
+## Cross-references
+
+- Privacy floor — `.augment/rules/low-impact-corpus-privacy-floor.md`
+- Routing — `scripts/ai_council/necessity.py § classify_impact_with_corpus`
+- Intake — `scripts/ai_council/low_impact_intake.py`
+- Promotion / pruning — `scripts/ai_council/probation_gate.py`

package/docs/contracts/mcp-beta-criteria.md

@@ -7,8 +7,8 @@ mcp_scope: lite
 
 > **Status:** Active · governs the `experimental → beta` promotion for
 > the MCP surface (`scripts/mcp_server/` local stdio kernel + the
-> hosted `workers/mcp/` bridge). Owned by Phase 3 of
-> [`road-to-surface-discipline.md`](../../agents/roadmaps/road-to-surface-discipline.md).
+> hosted `workers/mcp/` bridge). Owned by Phase 3 of the
+> `road-to-surface-discipline` roadmap (see `agents/roadmaps/`).
 > Companion contract:
 > [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) (local) ·
 > [`mcp-cloud-scope.md`](mcp-cloud-scope.md) (hosted).
@@ -91,8 +91,9 @@ ping. Evidence: the workflow file (`.github/workflows/mcp-no-drift.yml`)
 1. Open a release-candidate branch named `release/mcp-beta-rcN`.
 2. Run `./agent-config doctor --check mcp-beta-readiness` — must
    print all six gates green.
-3. Flip the wording in the **five** surfaces inventoried in
-   [`road-to-surface-discipline.md` Phase 3 Step 1](../../agents/roadmaps/road-to-surface-discipline.md):
+3. Flip the wording in the **five** surfaces inventoried in the
+   `road-to-surface-discipline` roadmap (Phase 3 Step 1, under
+   `agents/roadmaps/`):
    `docs/mcp-server.md` (status banner + Remote-MCP sub-claim),
    `README.md` (pointer line), `scripts/mcp_server/server.py`
    (initialize-result `serverInfo.name`),
@@ -125,5 +126,5 @@ delta for Phase 3: ≤ 0.
 - [`STABILITY.md`](STABILITY.md) — stability tier definitions
   (`experimental` / `beta` / `stable`) and what wording each tier may
   use in user-visible surfaces.
-- [`road-to-surface-discipline.md`](../../agents/roadmaps/road-to-surface-discipline.md)
+- The `road-to-surface-discipline` roadmap (under `agents/roadmaps/`)
   — Phase 3 acceptance criteria and step-level evidence pointers.

package/docs/contracts/mcp-cloud-scope.md

@@ -31,9 +31,9 @@ alongside auth).
 
 The package ships **two MCP surfaces** governed by named scopes. Every
 MCP-related doc, ADR, and code path carries `mcp_scope: lite|full|deferred`
-in its frontmatter (Phase 1 Step 6 of
-`agents/roadmaps/road-to-distribution-maturity.md`) so the boundary is
-machine-checkable, not prose-only.
+in its frontmatter (Phase 1 Step 6 of the distribution-maturity roadmap,
+under `agents/roadmaps/`) so the boundary is machine-checkable, not
+prose-only.
 
 ### `mcp_scope: lite` — hosted, read-only knowledge surfaces
 
@@ -239,7 +239,8 @@ The README MCP section may **only** name modes that this `## Auth
 surface` section declares. This contract must declare every mode the
 README names. The drift test
 `tests/test_mcp_contract_readme_sync.py` enforces both directions
-per Phase 1 Step 4 of `agents/roadmaps/road-to-distribution-maturity.md`.
+per Phase 1 Step 4 of the distribution-maturity roadmap (under
+`agents/roadmaps/`).
 
 ## A0-cloud invariants
 

package/docs/contracts/multi-tool-projection-fidelity.md

@@ -0,0 +1,115 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+# Multi-Tool Projection Fidelity Contract
+
+**Status:** beta · **Phase 4 of the `step-1-v2-feedback-followup`
+roadmap** (under `agents/roadmaps/`).
+
+Names the **per-tool guarantees** the projection pipeline (`scripts/compress.py --sync` + `scripts/compress.py --generate-tools`) actually delivers. Byte-equivalence is not behaviour-fidelity — each consumer tool has its own frontmatter grammar, its own activation model, and its own surface for skills / rules / commands.
+
+## Source of truth
+
+Every projection starts from `.agent-src/` (compressed) which is generated from `.agent-src.uncompressed/`. The projection layer **never** writes to source; it only reads.
+
+## Per-tool projection map
+
+| Tool | Rules surface | Skills surface | Commands surface | Frontmatter grammar |
+|---|---|---|---|---|
+| **Augment** (host) | `.augment/rules/*.md` (copies; symlink opt-in via `augment.rules_use_symlinks`) | `.augment/skills/<name>/SKILL.md` (symlink → `.agent-src/skills/`) | `.augment/commands/*.md` | full source frontmatter preserved |
+| **Claude** (Code + Desktop) | `.claude/rules/*.md` | `.claude/skills/<name>/SKILL.md` | `.claude/skills/<name>/SKILL.md` (commands rendered as skills) | full source frontmatter preserved |
+| **Cursor** | `.cursor/rules/*.mdc` + legacy `.md` symlinks (130 files = 65 × 2) | **not projected** | `.cursor/commands/*.md` | `description`, `globs`, `alwaysApply` only — `triggers`, `routes_to`, `tier`, `type` are **dropped** |
+| **Windsurf** | `.windsurfrules` (single concatenated file) + `.windsurf/rules/*.md` (per-rule) | **not projected** | `.windsurf/workflows/*.md` | concatenated body; per-rule frontmatter only retained in `.windsurf/rules/`, not in the legacy `.windsurfrules` single-file |
+| **Cline** | `.clinerules/*.md` | **not projected** | **not projected** | full router frontmatter preserved (`type`, `tier`, `description`, `triggers`, `routes_to`) |
+| **Gemini** | `GEMINI.md` (single-file digest) | embedded inline | embedded inline | digest only — no per-rule frontmatter |
+| **Copilot** | `AGENTS.md` / `copilot-instructions.md` | embedded inline | embedded inline | digest only |
+
+`AGENTS.md` is the **tool-agnostic root pointer** and exists at workspace root regardless of which projections are enabled.
+
+## Fidelity guarantees per axis
+
+### 1. Rule body fidelity
+
+| Tool | Body identical to source? |
+|---|---|
+| Augment | yes (copy or symlink) |
+| Claude | yes (copy) |
+| Cursor `.mdc` | yes |
+| Cline | yes |
+| Windsurf single-file | concatenated, separator `---` between rules |
+| Windsurf per-rule | yes |
+| Gemini / Copilot digest | summarised — **no fidelity guarantee** |
+
+### 2. Trigger fidelity (`triggers:` keyword / `path_prefix`)
+
+| Tool | `triggers:` preserved? |
+|---|---|
+| Augment, Claude, Cline, Windsurf-per-rule | **yes** — the host LLM sees the trigger set verbatim |
+| Cursor `.mdc` | **no** — Cursor's frontmatter grammar does not honour `triggers:`; activation falls back to `globs:` + `alwaysApply: <bool>` + description match |
+| Windsurf single-file `.windsurfrules` | **no** — concatenated body strips per-rule frontmatter |
+| Gemini, Copilot | **no** — digest format |
+
+**Consequence:** rules that depend on `triggers:` for activation (tier-2a path-prefix routing, tier-3 keyword routing) **silently degrade on Cursor and on the Windsurf single-file**. They still appear in body, but the host must infer activation from prose.
+
+### 3. `routes_to:` fidelity
+
+Same matrix as `triggers:` — preserved on Augment, Claude, Cline, Windsurf-per-rule; **dropped** on Cursor `.mdc` and Windsurf single-file.
+
+**Consequence:** the four tier-3 routing rules (`laravel-routing`, `symfony-routing`, `copilot-routing`, `devcontainer-routing`) added in Phase 3.3 will route deterministically on Augment / Claude / Cline; on Cursor / Windsurf-single-file the host must rely on description matching alone.
+
+### 4. Skill surface
+
+Cursor, Windsurf, Cline, Gemini, Copilot have **no native skill surface**. Skills are projected only for Augment and Claude. Consumers on the other tools see skill content only indirectly (via rule bodies that cite skills, or via the catalogue in `AGENTS.md`).
+
+### 5. Command surface
+
+| Tool | Where commands appear |
+|---|---|
+| Augment | `.augment/commands/*.md` (native slash-command surface) |
+| Claude | `.claude/skills/<command>/SKILL.md` (commands rendered as skills with `disable-model-invocation: true`) |
+| Cursor | `.cursor/commands/*.md` (106 files) |
+| Windsurf | `.windsurf/workflows/*.md` (106 files) |
+| Cline | none |
+| Gemini, Copilot | listed only inside `AGENTS.md` / `GEMINI.md` digest |
+
+## Automated probe — `task lint-projection-fidelity`
+
+`scripts/probe_projection_fidelity.py` reads `tests/fixtures/projection_fidelity/fixtures.yml` and asserts the per-tool guarantees above against the actual projected trees. The fixture covers five representative artefacts:
+
+| Fixture entry | Tier | Stress-tests |
+|---|---|---|
+| `rule:non-destructive-by-default` | kernel | always-active body fidelity across all five rule surfaces |
+| `rule:laravel-translations` | tier-2a | `path_prefix:` trigger preservation (Cline) vs drop (Cursor) |
+| `rule:laravel-routing` | tier-3 | `routes_to:` preservation (Cline) vs drop (Cursor, Windsurf-single) |
+| `skill:laravel` | skill | Augment + Claude only; rationale for absence on others |
+| `command:commit` | command | per-tool command surface divergence |
+
+Run: `python3 scripts/probe_projection_fidelity.py` — exits non-zero on any divergence. Report at `agents/reports/projection-fidelity.json`.
+
+## Known divergences (do not file as bugs)
+
+These are **architectural facts**, not regressions. They are documented so installers and consumers know what to expect.
+
+1. **Cursor `.mdc` drops router metadata.** Cursor's third-party rule format only honours `description`, `globs`, `alwaysApply`. Adding `triggers:` or `routes_to:` to a Cursor rule has no effect at activation time. The body still loads when the description matches; the deterministic routing layer does not.
+2. **Windsurf single-file (`.windsurfrules`) strips per-rule frontmatter.** Legacy compatibility surface. The new `.windsurf/rules/*.md` per-rule files preserve the full frontmatter — consumers should prefer those.
+3. **Skills do not project to Cursor / Windsurf / Cline / Gemini / Copilot.** These tools have no native skill loader. Skill content reaches consumers indirectly via rule bodies and the `AGENTS.md` catalogue.
+4. **Augment historically did not load symlinked rules.** Default is to **copy** rules into `.augment/rules/`. Opt into symlinks via `augment.rules_use_symlinks: true` in `.agent-settings.yml`.
+5. **`task generate-tools` does not refresh `.augment/rules/`.** Only `task sync` (== `scripts/compress.py --sync`) copies rules into the Augment tree. Investigators who edit a rule, run only `generate-tools`, and then `ls .augment/rules/` will see stale state.
+
+## Acceptance criteria for this contract
+
+- [x] Fixture under `tests/fixtures/projection_fidelity/`
+- [x] Probe script under `scripts/probe_projection_fidelity.py`
+- [x] Report under `agents/reports/projection-fidelity.json`
+- [x] Per-tool guarantee table above
+- [x] Known-divergence list above
+
+## Related
+
+- [`source-projection`](../architecture/source-projection.md) — pipeline A (source compression)
+- [`augment-projection`](../architecture/augment-projection.md) — pipeline B (Augment-specific)
+- [`multi-tool-projection`](../architecture/multi-tool-projection.md) — pipeline C (the per-tool emitters)
+- [`rule-router`](rule-router.md) — the `triggers:` / `routes_to:` grammar this contract pins
+- [`agents/council-sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md`](../../agents/council-sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md) — origin council feedback <!-- council-ref-allowed: contract origin trace -->

package/docs/contracts/release-trunk-sync.md

@@ -11,7 +11,8 @@ keep-beta-until: 2026-08-12
 > points across the 2.x cycle. External readers landing on `main`
 > consistently saw stale README counts and missing skill catalogues
 > relative to the npm/Packagist artefact.
-> **Closes:** [Road to Productization](../../agents/roadmaps/road-to-productization.md) § P1.2.
+> **Closes:** the `road-to-productization` roadmap § P1.2 (under
+> `agents/roadmaps/`).
 
 ## Decision
 
@@ -100,5 +101,5 @@ not orphan the convention.
 - [`.github/workflows/release-guard.yml`](../../.github/workflows/release-guard.yml)
   — tag/version-file integrity gate (orthogonal: this contract handles
   trunk position, release-guard handles version-string integrity).
-- [`agents/roadmaps/road-to-productization.md`](../../agents/roadmaps/road-to-productization.md)
-  § Phase 1.
+- The `road-to-productization` roadmap § Phase 1 (under
+  `agents/roadmaps/`).

package/docs/contracts/tier-3-contrib-plugin.md

@@ -26,10 +26,9 @@ Last refreshed: 2026-05-12.
 | **Tier-2** | Shipped | Named in roadmaps + has plausible audience | Imperative bridge, same pattern as Tier-1 |
 | **Tier-3** | **Deferred** | Named in scoping/council but zero user demand | Manifest YAML in `agents/manifests/contrib/` (not yet implemented) |
 
-Phase 2.1 + 2.2 of
-[`road-to-global-first-install`](../../agents/roadmaps/road-to-global-first-install.md)
-closed Tier-1 and Tier-2 at **16 AIs**. Tier-3 is the explicit
-overflow bucket.
+Phase 2.1 + 2.2 of the `road-to-global-first-install` roadmap
+(under `agents/roadmaps/`) closed Tier-1 and Tier-2 at **16 AIs**.
+Tier-3 is the explicit overflow bucket.
 
 ## Candidate list (frozen at proposal time)
 
@@ -126,5 +125,5 @@ not "preemptively scaffold" Tier-3 entries.
 - [`ADR-008`](../decisions/ADR-008-installed-tools-manifest.md) —
   `agents/installed-tools.lock` for per-project state, distinct
   from this maintainer-side contract.
-- [`road-to-global-first-install`](../../agents/roadmaps/road-to-global-first-install.md)
-  Phase 2.6 — completion trigger for this contract.
+- The `road-to-global-first-install` roadmap (under
+  `agents/roadmaps/`) Phase 2.6 — completion trigger for this contract.

package/docs/getting-started.md

@@ -106,7 +106,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 61 rules. No configuration needed.
+This is enforced automatically by 67 rules. No configuration needed.
 
 ---
 
@@ -146,7 +146,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 106 active commands](../.agent-src/commands/)
+→ [Browse all 109 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guidelines/agent-infra/installed-tools-manifest.md

@@ -4,7 +4,8 @@ Project-committed bill of materials for AI tooling. Answers the
 question "which AIs does this project use, where do their bridges live,
 and is everyone on the team on the same set?". Canonical schema is
 ADR-008 ([`docs/decisions/ADR-008-installed-tools-manifest.md`](../../decisions/ADR-008-installed-tools-manifest.md)).
-Phase 3 of [`road-to-global-first-install`](../../../agents/roadmaps/road-to-global-first-install.md).
+Delivered under the global-first-install roadmap (Phase 3) — see
+`agents/roadmaps/` for current status.
 
 This file lives at **`agents/installed-tools.lock`** — committed,
 machine-managed, and orthogonal to `.agent-project-settings.yml`

package/docs/installation.md

@@ -646,6 +646,38 @@ the symlinks and regenerates derived files (`.windsurfrules`,
 
 ---
 
+## AI Council local state
+
+The AI Council ([`docs/contracts/ai-council-config.md`](contracts/ai-council-config.md))
+writes two local-only files outside the repo contract:
+
+- `~/.event4u/agent-config/cli-calls.json` — per-day call counter for
+  `mode: cli` members. Daily UTC reset. Inspect with
+  `agent-config council quota`; clear today's counter for one provider
+  with `agent-config council quota --reset <provider> --confirm`.
+- `agents/council-events.log` — JSONL audit trail. One line per
+  necessity-gate decision and per quota block. Gitignored by the
+  installer (managed `.gitignore` block); never committed.
+  `original_ask` is hashed `sha256[:12]` before write — the raw prompt
+  is never persisted.
+
+Both are opt-in by construction: the quota counter only fires when a
+provider has `cli_call_budget.max_calls_per_day.<provider>` set, and
+the events log is purely additive (deletable at any time).
+
+### Kill-switches
+
+Per-feature environment overrides for ephemeral worktrees, CI runners,
+or sandbox testing:
+
+- `AGENT_CONFIG_NO_EVENTS_LOG=1` — disables every write to
+  `agents/council-events.log` in-process. Quota counter and council
+  output stay untouched.
+- `AGENT_CONFIG_LEGACY_ANCHOR=1` — opt back into the pre-step-7
+  legacy-anchor behaviour for `.agent-settings.yml` migration.
+
+---
+
 ## Windows
 
 Native Windows is not a first-class target. Use one of the following:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.12.0",
+    "version": "2.14.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_archive/README.md

@@ -0,0 +1,59 @@
+# Script Archive — One-Shot Migrations
+
+This directory preserves migration / bootstrap / back-fill scripts that have
+already run to completion and are no longer invoked by any productive code
+path. They are kept as forensic reference, mirroring the archival convention
+used by [`agents/roadmaps/archive/`](../../agents/roadmaps/archive/).
+
+**Do not run these scripts.** They are one-shot transformations whose
+target state is already the working tree. Re-running them on the current
+codebase is undefined behaviour.
+
+## Provenance
+
+Archived 2026-05-14 as part of [`agents/roadmaps/step-1-v2-feedback-followup.md`](../../agents/roadmaps/step-1-v2-feedback-followup.md)
+Phase 1 Step 3, addressing audit finding F3 / council finding C3 from
+[`agents/council-sessions/2026-05-14-v2-analysis/feedback/03-migration-scripts-archival.md`](../../agents/council-sessions/2026-05-14-v2-analysis/feedback/03-migration-scripts-archival.md).
+
+## Inventory
+
+| Script | Migration / phase served | What it did |
+|---|---|---|
+| [`_backfill_skill_domains.py`](_backfill_skill_domains.py) | B3 domain back-fill | Injected `domain:` frontmatter into every `SKILL.md`. Source of truth now lives in each skill's frontmatter directly. |
+| [`_bootstrap_tier_frontmatter.py`](_bootstrap_tier_frontmatter.py) | Tier-frontmatter bootstrap | Injected `tier: N` frontmatter into every slash command during the kernel / tier-1 / tier-2 routing introduction. |
+| [`_p43_bodies.py`](_p43_bodies.py) | Phase 4.3 — rule-body compression | Wrote compressed rule bodies after `_p43_compress.py` produced the manifest. Paired with `_p43_compress.py`. |
+| [`_p43_compress.py`](_p43_compress.py) | Phase 4.3 — rule-body compression | Surgical compression of 22 `compress-and-keep` auto-rules; produced the manifest consumed by `_p43_bodies.py`. |
+| [`_p4_migrate.py`](_p4_migrate.py) | Phase 4.1 + 4.2 — rule reclassification | Migrated rules into the skill / guideline / command / contract-stub split that the package ships today. |
+| [`_phase2_shim_helper.py`](_phase2_shim_helper.py) | Phase 2 — deprecation shim | One-shot helper that injected `superseded_by:` + `deprecated_in:` + deprecation warning into rules retired during Phase 2. |
+| [`_pilot_council_question.py`](_pilot_council_question.py) | Phase 1 pilot — kernel-membership council prep | Built the Phase-1 council question file used for the kernel-membership R1/R2 cross-check. The resulting council artefacts live under `agents/council-sessions/20260506T*`. |
+
+## Why these stayed live and were NOT archived
+
+The 2026-05-14 audit (F3) listed 9 candidate scripts. Two of those turn out
+to have productive (non-incestuous) references and remain in `scripts/`:
+
+- **`scripts/_emit_domain_table.py`** — cited as the regeneration command in
+  [`docs/contracts/skill-domains.md`](../../docs/contracts/skill-domains.md)
+  ("regenerate via `python3 scripts/_emit_domain_table.py`"). The
+  domain-table snapshot is a derived view that the contract doc explicitly
+  expects to be regenerable from this script.
+- **`scripts/_pilot_measure.py`** — cited by
+  [`docs/contracts/kernel-membership.md`](../../docs/contracts/kernel-membership.md)
+  as the reproducibility-verification command for the kernel pilot SHAs, and
+  its algorithm is mirrored by [`scripts/iron_law_sha.py`](../iron_law_sha.py).
+  Both productive paths assume the script remains in place.
+
+The audit's F3 framing ("zero productive references") was correct for the 7
+archived scripts and wrong for these 2. Recorded here so the F3 finding is
+not re-litigated without context.
+
+## How to restore one (if a future migration needs it)
+
+```bash
+git mv scripts/_archive/<script>.py scripts/
+git commit -m "chore(scripts): restore <script> for <reason>"
+```
+
+Restoration should come with an issue / PR explaining why the historical
+one-shot is being reused — by construction these scripts assume their
+pre-migration starting state.

package/scripts/_cli/cmd_doctor.py

@@ -36,6 +36,7 @@ import argparse
 import hashlib
 import json
 import re
+import shutil
 import sys
 from pathlib import Path
 from typing import Any
@@ -287,6 +288,7 @@ CHECK_IDS = (
     "offline-readiness",
     "python-runtime",
     "tier-usage-readiness",
+    "council-cli",
     "unsupported-combos",
 )
 
@@ -675,6 +677,137 @@ def _check_tier_usage_readiness(project_root: Path) -> dict[str, Any]:
     }
 
 
+#: Provider → (default binary, billable flag). Mirrors the
+#: ``CliClient`` subclass attributes in ``scripts/ai_council/clients.py``
+#: without importing them at module load time (keeps doctor lightweight
+#: and robust if council deps fail to load).
+_CLI_PROVIDER_META: dict[str, tuple[str, bool]] = {
+    "anthropic": ("claude", False),
+    "openai": ("codex", False),
+    "gemini": ("gemini", False),
+    "xai": ("grok", True),
+    "perplexity": ("perplexity", True),
+}
+
+
+def _check_council_cli(project_root: Path) -> dict[str, Any]:
+    """Health-probe each enabled ``mode: cli`` council member.
+
+    For every CLI member in ``agents/.ai-council.yml`` reports binary
+    presence (via ``shutil.which``), billable flag, daily-quota state
+    (used/cap or used/—), and rolls up to a single status icon.
+
+    No subprocess is spawned: ``--version`` probes would defeat the
+    cheap-by-default contract and surface flaky network paths (Codex
+    talks home on first run). Binary presence + the cached
+    ``cli-calls.json`` counter cover the actionable failure modes.
+
+    Status rules:
+
+    - ``ok`` — every enabled CLI member has its binary on PATH AND
+      (when capped) usage is below ``warn_at``.
+    - ``warn`` — at least one binary is missing OR usage crosses
+      ``warn_at`` for at least one capped member.
+    - returns ``ok`` with "no council config" if
+      ``agents/.ai-council.yml`` is absent (consumer project that
+      hasn't enabled the council yet).
+    """
+    council_path = project_root / "agents" / ".ai-council.yml"
+    if not council_path.exists():
+        return {
+            "id": "council-cli", "status": "ok",
+            "message": "no council config (agents/.ai-council.yml not present)",
+            "remedy": "",
+        }
+    try:
+        from scripts.ai_council.clients import load_cli_call_counts
+        from scripts.ai_council.config import load_council_config
+    except Exception as exc:  # noqa: BLE001 — defensive: doctor must not crash
+        return {
+            "id": "council-cli", "status": "warn",
+            "message": f"council deps unavailable ({type(exc).__name__})",
+            "remedy": "install PyYAML and ensure scripts/ai_council is importable",
+        }
+    try:
+        cfg = load_council_config(council_path)
+    except Exception as exc:  # noqa: BLE001
+        return {
+            "id": "council-cli", "status": "warn",
+            "message": f"council config invalid: {exc}",
+            "remedy": "fix agents/.ai-council.yml and re-run doctor",
+        }
+    cli_members: list[tuple[str, Any]] = [
+        (name, m) for name, m in cfg.members.items()
+        if m.enabled and m.mode == "cli" and name in _CLI_PROVIDER_META
+    ]
+    if not cli_members:
+        return {
+            "id": "council-cli", "status": "ok",
+            "message": "no enabled CLI-mode members",
+            "remedy": "",
+        }
+    counts = load_cli_call_counts()
+    caps = cfg.cli_call_budget.max_calls_per_day
+    warn_at = float(cfg.cli_call_budget.warn_at)
+    missing: list[str] = []
+    over_warn: list[str] = []
+    lines: list[str] = []
+    for name, member in cli_members:
+        default_bin, billable = _CLI_PROVIDER_META[name]
+        binary_name = member.binary or default_bin
+        resolved = shutil.which(binary_name)
+        binary_glyph = "✅" if resolved else "❌"
+        if resolved is None:
+            missing.append(name)
+        used = int(counts.get(name, 0))
+        cap = caps.get(name)
+        if cap is not None:
+            ratio = used / cap if cap > 0 else 0.0
+            quota_glyph = "⚠️" if ratio >= warn_at else "✅"
+            if ratio >= warn_at:
+                over_warn.append(name)
+            quota_str = f"{used}/{cap}"
+        else:
+            quota_glyph = "—"
+            quota_str = f"{used}/—"
+        billable_str = "billable" if billable else "subscription"
+        lines.append(
+            f"{name}: binary {binary_glyph} ({binary_name}) · "
+            f"quota {quota_glyph} {quota_str} · {billable_str}"
+        )
+    detail = " | ".join(lines)
+    if missing:
+        return {
+            "id": "council-cli", "status": "warn",
+            "message": (
+                f"{len(missing)}/{len(cli_members)} CLI member(s) missing binary "
+                f"({', '.join(missing)}) · {detail}"
+            ),
+            "remedy": (
+                "install the missing CLI(s) — see `council:estimate` pre-flight "
+                "for per-provider install hints, or flip "
+                "ai_council.members.<name>.mode to 'api'"
+            ),
+        }
+    if over_warn:
+        return {
+            "id": "council-cli", "status": "warn",
+            "message": (
+                f"{len(over_warn)}/{len(cli_members)} CLI member(s) at/over "
+                f"quota warn_at={warn_at} ({', '.join(over_warn)}) · {detail}"
+            ),
+            "remedy": (
+                "wait for UTC rollover or run "
+                "`python3 scripts/council_cli.py quota --reset` to clear the counter"
+            ),
+        }
+    return {
+        "id": "council-cli", "status": "ok",
+        "message": f"{len(cli_members)} CLI member(s) healthy · {detail}",
+        "remedy": "",
+    }
+
+
 def _check_unsupported_combos(manifest: dict[str, Any]) -> dict[str, Any]:
     """Flag tools whose ``scope`` violates the global-only or project-only rules."""
     global_only = {"droid", "qoder"}
@@ -720,6 +853,7 @@ def _run_checks(
         "offline-readiness": lambda: _check_offline_readiness(),
         "python-runtime": lambda: _check_python_runtime(),
         "tier-usage-readiness": lambda: _check_tier_usage_readiness(project_root),
+        "council-cli": lambda: _check_council_cli(project_root),
         "unsupported-combos": lambda: _check_unsupported_combos(manifest),
     }
     out: list[dict[str, Any]] = []

package/scripts/ai_council/_default_prices.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 
 # YYYY-MM-DD of when this table was last hand-edited. Keep in sync with
 # the test_default_prices freshness assertion if you bump this.
-LAST_UPDATED = "2026-04-29"
+LAST_UPDATED = "2026-05-14"
 
 # (provider, model)  ->  (input_per_1m_usd, output_per_1m_usd)
 DEFAULT_PRICES: dict[tuple[str, str], tuple[float, float]] = {
@@ -30,6 +30,15 @@ DEFAULT_PRICES: dict[tuple[str, str], tuple[float, float]] = {
     ("openai", "gpt-4o-mini"): (0.15, 0.60),
     ("openai", "o1"): (15.00, 60.00),
     ("openai", "o3-mini"): (1.10, 4.40),
+    # ── Google Gemini ────────────────────────────────────────────────
+    ("gemini", "gemini-2.5-pro"): (1.25, 10.00),
+    ("gemini", "gemini-2.5-flash"): (0.30, 2.50),
+    # ── xAI Grok ─────────────────────────────────────────────────────
+    ("xai", "grok-4"): (3.00, 15.00),
+    ("xai", "grok-3-mini"): (0.30, 0.50),
+    # ── Perplexity ───────────────────────────────────────────────────
+    ("perplexity", "sonar-pro"): (3.00, 15.00),
+    ("perplexity", "sonar"): (1.00, 1.00),
 }