@event4u/agent-config 8.11.0 → 8.13.0

package/docs/maintainers/branch-protection.md

@@ -0,0 +1,105 @@
+# Branch protection for `main` — prepared config (user-applied)
+
+> The one reviewer point open since PR #223, repeated in every 8.11 review:
+> "no code needed." Correct — and that is exactly why an agent never applies
+> it: changing repository protection is a repo-admin, outward-facing action
+> that affects every future merge. This page prepares the exact
+> configuration; a human runs it. Blocker `branch-protection-apply` (owner:
+> user) in `road-to-feedback-8.11-2` tracks the application.
+
+## Design decisions (council 2026-07-12)
+
+- **PR required, no direct pushes to `main`** — including the maintainer;
+  the agent-side rules already treat `main` as a Hard-Floor trunk, this
+  makes GitHub enforce the same.
+- **No force-pushes, no branch deletion.**
+- **Required checks = a MINIMAL STABLE CORE, not all ~59 checks.**
+  Requiring everything turns every workflow/job rename into a lockout.
+  Core = the suites that gate correctness on every PR:
+  - `Static Checks (ESLint · typecheck · prepack)`
+  - `Node Tests (ubuntu-latest, shard 1/4)` … `shard 4/4`
+  - `Golden Tests (ubuntu-latest)`
+  - `Install Aux Tests (ubuntu-latest)`
+  (macOS twins stay unrequired — same code, second OS; they still run and
+  still show red, they just don't lock the merge on a runner outage.)
+- **Enforce for admins: yes** (otherwise the protection is decorative).
+- **Required reviews: 0 for now** — the trailing-90-day distinct-reviewer
+  count is 1 (bus-factor reality); requiring a second reviewer would block
+  every merge. Revisit when a second maintainer exists
+  (`road-to-maintainer-bus-factor`).
+
+## Verify the current check names first (renames happen)
+
+```bash
+gh api repos/event4u-app/agent-config/commits/main/check-runs \
+  --jq '.check_runs[].name' | sort -u
+```
+
+Adjust the `contexts` list below to the names that actually exist — this
+doc is a preparation, the live names win.
+
+## The ready-to-run command
+
+```bash
+gh api -X PUT repos/event4u-app/agent-config/branches/main/protection \
+  --input - <<'JSON'
+{
+  "required_status_checks": {
+    "strict": false,
+    "contexts": [
+      "Static Checks (ESLint · typecheck · prepack)",
+      "Node Tests (ubuntu-latest, shard 1/4)",
+      "Node Tests (ubuntu-latest, shard 2/4)",
+      "Node Tests (ubuntu-latest, shard 3/4)",
+      "Node Tests (ubuntu-latest, shard 4/4)",
+      "Golden Tests (ubuntu-latest)",
+      "Install Aux Tests (ubuntu-latest)"
+    ]
+  },
+  "enforce_admins": true,
+  "required_pull_request_reviews": null,
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+JSON
+```
+
+Notes: `strict: false` deliberately — with a single maintainer,
+require-branches-up-to-date adds a rebase round-trip per merge with no
+second-writer race to protect against; flip to `true` when there are
+concurrent mergers. `required_pull_request_reviews: null` per the
+bus-factor reality above.
+
+## Operating conditions under `strict: false`
+
+`strict: false` drops the branches-up-to-date requirement, so three
+conditions become merge-time habits the config cannot enforce:
+
+- **The checked commit must not change after green CI.** No post-CI
+  amend or force-push on the PR branch — the config already blocks
+  force-pushes to `main`; the same discipline applies to the head that
+  CI checked: what went green is what merges.
+- **Critical checks must have run on the final head before merge.** A
+  human glance at the checks tab on the PR's latest commit — with
+  `strict: false` GitHub does not re-run required checks when the base
+  moves, so the green you see is only as fresh as the head it ran on.
+- **Auto-merge must not be enabled in a way that merges with pending or
+  failed required checks.** Enable auto-merge only once the required
+  list is complete and green on the final head — never as a
+  fire-and-forget while checks are still queued.
+
+## Rollback
+
+```bash
+gh api -X DELETE repos/event4u-app/agent-config/branches/main/protection
+```
+
+## After applying
+
+- Verify: `gh api repos/event4u-app/agent-config/branches/main/protection --jq '{checks: .required_status_checks.contexts, admins: .enforce_admins.enabled}'`
+- Update the blocker in `road-to-feedback-8.11-2` (resolved-when: this
+  command ran, or the user records why not).
+- Any future check rename: update the contexts list in the SAME PR that
+  renames the job — a required check that no longer reports blocks every
+  merge until an admin edits the list.

package/docs/maintainers/system-map.md

@@ -0,0 +1,85 @@
+# System map — how the whole thing fits together
+
+> One page, by design. This is a MAP, not a contract — where this page and a
+> linked contract disagree, the contract wins. It exists so a new maintainer
+> (or the same maintainer in six months) can orient without reading 121 ADRs.
+> Requested by both 8.11 external reviews ("a 'how the whole system fits
+> together' document that does not presuppose reading every contract").
+
+## The one chain that explains everything
+
+```
+src/                    ← the ONLY thing you edit
+  → condensation        (condense.sh; hashes in internal/.condensation-hashes.json)
+  → dist/agent-src/     (shipped projection — generated, read-only)
+  → host projection     (task generate-tools → .claude/ .cursor/ .clinerules/ …)
+  → installer           (npx @event4u/agent-config init → consumer's .augment/ etc.)
+  → consumer runtime    (host agent runs; hooks fire via the dispatcher)
+```
+
+Everything below either feeds this chain or checks it.
+
+## Subsystems, one paragraph each
+
+- **Rules + router** — `src/rules/*.md`, compiled into `dist/router.json`.
+  9 kernel rules load always; the rest route on trigger-sets. Heavy rule
+  bodies migrate to skills/guidelines (P4 pattern); inbound routes are
+  derivable per target (`internal/reports/rule-backlinks.md`). Contracts:
+  `docs/contracts/kernel-membership.md`, `docs/contracts/rule-router.md`.
+
+- **Skills / commands / personas** — the capability library
+  (`src/skills`, command domains under `src/domains`, personas). Counts are
+  generated and drift-gated (`CAPABILITIES.yaml`, count-messaging gate).
+  Catalog: `docs/catalog.md`.
+
+- **Knowledge + memory** — file-first, no DB. Per-card origin tier AND
+  sensitivity class (`prohibited/project/shareable`, ADR-121) gate what may
+  reach the global store (`~/.event4u/agent-config/knowledge/`); promotion
+  needs a human reason; deletion leaves tombstones. Design:
+  `agents/settings/contexts/knowledge-sensitivity.md`.
+
+- **Council** — external multi-model deliberation (no repo access),
+  debate/stance/chairman machinery complete and default-off; further
+  expansion is gated on the pre-registered council-vs-solo baseline
+  (`docs/design/council-vs-solo-baseline.md`). Config contract:
+  `docs/contracts/ai-council-config.md`.
+
+- **Subagents / orchestration** — in-session delegation with a form gate
+  before mode selection; implementer/judge separation; telemetry on the
+  audit JSONL. Team mode (cross-model builder/reviewer WITH repo access) is
+  the depth complement — `agents/roadmaps/road-to-team-mode.md`.
+
+- **Telemetry + measurement** — engagement records (id-only,
+  PII-excluded-by-construction, default-off; ON in this repo since
+  2026-07-12 with pre-registered decision criteria at
+  `docs/design/utilization-window-criteria.md`); orchestration audit lines;
+  bench harnesses with spend gates.
+
+- **Claims + proof** — every public claim binds to resolvable evidence:
+  `docs/CLAIMS.md` (source) → `docs/proof.md` (generated). Honest nulls are
+  published; pre-registration before data is the norm. Gate:
+  `check_claims`, `build_proof --check`.
+
+- **Introspection lenses (all report-only, all with kill criteria)** —
+  `complexity_report` (system-complexity soft ratchet vs checked-in
+  baseline), `explain_run` (why rules/skills/dispatches happened),
+  `rule_backlinks`. None fails a build; each dies if it informs no decision.
+
+- **CI gates** — `task ci` locally mirrors remote CI; remote CI is the
+  authoritative gate (`quality.local_auto_run: false` BY DESIGN — narrow
+  diff-scoped probes still run locally; new gates run once locally). The
+  consumer matrix installs the real package and fires real hook lifecycle
+  events. Branch protection: `docs/maintainers/branch-protection.md`.
+
+## Where to change what (the 10-second router)
+
+| You want to… | Edit… | Never touch… |
+|---|---|---|
+| Change agent behavior | `src/rules` / `src/skills` / `src/domains` | `dist/`, `.claude/`, `.cursor/` (generated) |
+| Change what ships | `src/config/packs.yml`, profiles | consumer trees |
+| Change counts/claims/proof | `docs/CLAIMS.md` + regenerate | `docs/proof.md` directly |
+| Change install/hooks | `src/install`, `src/scripts/_lib/claude_settings_hooks.ts` | consumer settings by hand |
+| Record a decision | `docs/decisions/ADR-*` via adr-create | roadmaps as decision storage |
+
+Deeper operating material (release runbook, succession, incident playbooks)
+is owned by `road-to-maintainer-bus-factor` — this page stays the map.

package/docs/proof.md

@@ -27,8 +27,8 @@ evidence pointer, or `task check-claims` fails the build.
 | Claim | Kind | Evidence | Resolves |
 |---|---|---|---|
 | The release process is documented as an inheritable runbook + succession doc, and the project's bus-factor (trailing-90-day distinct human reviewers) is tracked and reported truthfully — currently 1, not implied to be more. | qual | `docs/succession.md#trailing 90 days` | ✅ |
-| 178 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
-| The retrieval economy cuts always-loaded context tokens ~65.6% measured against the FULL always-loaded projection — 98,529 → 33,897 tokens (eager rule load + skill/command descriptions + MCP schemas, thin-flipped). Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4). | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
+| 183 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| A MEASURED-BUT-NOT-SHIPPED experiment — the thin rule projection reduced eager rule load 78,513 → 13,881 GPT-tokens (whole always-loaded projection 98,529 → 33,897, ~65.6%), but FAILED the quality gate (thin win-rate 36.2% vs required 48%) and does not ship; it un-defers only behind `discipline_profile: essential`. Shipped behavior does NOT include this reduction. Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4); quality gate per the Phase-0 paired judge run. | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
 | On a weak host (claude-haiku-4-5) the package produces a significant, placebo-controlled discipline lift on scope/downstream traps; on a strong host the same measurement is a published null — the package transplants discipline a weak model lacks, not model intelligence. | quant | `docs/benchmark.md#weak-host-specific` | ✅ |
 | The non-coding domain skills (finance/founder/ops/content) are forged on TS/PHP and labeled unvalidated until they pass a sourced domain-truth fixture; no public prose implies proven domain correctness, and the validated count is CI-ratcheted. | qual | `src/scripts/domain_soundness_status.ts#checkRatchet` | ✅ |
 | The validated non-coding domain-skill count is pinned and CI-ratcheted at a maintainer-set floor (9 of 20 default-surface skills carry a sourced `evals/domain-truth.json` fixture at pin time, 2026-07-11 — 5 deterministic, keys from cited formulas; 4 rubric, criteria matching a named external practice); the floor only rises via a maintainer `--write-floor` after a new sourced fixture lands. | quant | `internal/evals/domain-soundness-floor.json#validated` | ✅ |
@@ -38,6 +38,8 @@ evidence pointer, or `task check-claims` fails the build.
 | On the fixture corpus (n = 20 before/after pairs, 16 length-controlled within ±25%), the humanizer pass removes every mechanically detected AI-writing tell (mean hard hits 0.9 → 0, cluster score 53.97 → 0 per 500 words, dash density 9.22 → 0), and a blind judge (claude-sonnet-4-5, deterministic per-pair A/B seed) preferred the humanized text in 16/16 length-controlled pairs. Scope note — the "before" fixtures were deliberately tell-seeded, so this measures seeded-tell removal on a self-constructed corpus, NOT real-draft improvement; real-world lift is unmeasured until step 4b has processed real ghostwriter drafts (see the road-to-humanizer-hardening live-usage blocker). | quant | `internal/bench/reports/humanizer-v1.md#prefers the humanized text` | ✅ |
 | A hand-rolled, dependency-free BM25 + trigram lexical index resolves the "recalls but does not rank" gap: on the retrieval-precision corpus (9 keyword-overlapping-confuser tasks) it drives the mean top tie-set from 3.333 (the `_score` bucket scorer) to 1.0 — every needed decision uniquely top-ranked — with precision@1 and precision@5 unchanged at 1.0. Method: deterministic, model-free re-ranking of the SAME retrieved entry set; both scorers measured over the identical store via `measure_lexical_ranking.ts`. | quant | `internal/bench/reports/lexical-ranking.json` | ✅ |
 | The whole layer is compiled into host agents with zero runtime daemon. | qual | `docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite` | ✅ |
+| On a 12-fixture option-decision corpus (3 arms × 2 providers, blind rubric judge claude-opus-4-8, pre-registered hypotheses), famous-figure identity framing added nothing beyond the underlying method text (method 5.04 vs figure 4.88, Δ=0.17, sign-test p=0.607), and provider diversity moved judged quality ~15× more than persona identity (provider Δ=2.58 vs identity Δ=0.17); the whole persona layer lifted only +0.08 over bare prompts. Honest null — persona panel-mode stays CUT, evidence-closed. | quant | `internal/bench/reports/persona-placebo.json#honest-null` | ✅ |
+| On the live end-to-end retrieval benchmark (9 tasks × 3 arms × 3 seeds on claude-haiku, fixture store with keyword-overlapping confusers), the memory retrieval substrate scored precision@5 = 100% (9/9) with 100% poisoned-entry rejection, and the retrieval-on arm passed 27/27 model-scored tasks vs 2/27 with retrieval off and 4/27 with a placebo injection. Known limit stays published: mean tie-set 4.1 means top-k ties break by store order, not relevance (the ADR-116/FTS5 signal). | quant | `internal/bench/reports/second-brain-retrieval.json#retrieval-on` | ✅ |
 | 104 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | On a deterministic multi-session recall corpus, the memory substrate produces a measured, placebo-controlled recall lift — memory-on 27/27 vs no-memory 10/27 and vs equal-byte placebo 9/27 (claude-haiku-4-5, n=9 tasks x 3 seeds, sign test p=0.031 for BOTH pairings). Scoped honestly: this is the context-value upper bound (perfect retrieval on a one-fact-per-task corpus), not retrieval precision under a large store. | quant | `internal/bench/reports/second-brain-delta.json` | ✅ |
 | Removing the perfect-retrieval assumption, the substrate's REAL keyword retrieval recalls the needed decision into the top-5 under keyword-overlapping confusers (precision@5 9/9) and the model disambiguates it from the co-injected confusers — retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27 (claude-haiku-4-5, 9 tasks x 3 seeds, sign test p=0.008 both). Named limit: retrieval RECALLS but does not RANK (mean tie-set 3.3, ties broken by store order, not relevance) — the discrimination gap that motivates the SQLite-FTS5 activation path (ADR-116) at larger scale. | quant | `internal/bench/reports/second-brain-retrieval.json` | ✅ |
@@ -45,7 +47,7 @@ evidence pointer, or `task check-claims` fails the build.
 | 271 skills. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | Removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries. | qual | `docs/contracts/install-layout.md#JSON-pointer` | ✅ |
 
-**18 backed claim(s)** — all evidence pointers resolve in CI.
+**20 backed claim(s)** — all evidence pointers resolve in CI.
 
 Artefact counts in public prose (skills, commands, governed rules,
 guidelines, personas) are **generated from source and CI-drift-checked**:
@@ -53,7 +55,7 @@ guidelines, personas) are **generated from source and CI-drift-checked**:
 fails the build on any count-shaped prose mention that drifts from the
 source count — or on two different numbers for the same artefact kind.
 
-We also publish our **debt**: 2 claim(s) are logged as
+We also publish our **debt**: 4 claim(s) are logged as
 `unbacked` inventory in the ledger — not yet bound, and therefore not
 allowed to carry a marker in public prose. Hiding them would be the
 opposite of the point.
@@ -64,6 +66,15 @@ Benchmark results — **including the runs where the package changed nothing**
 live in [`docs/benchmark.md`](benchmark.md). We do not delete a measured null to
 make a number look better; the null is the evidence of honesty.
 
+The freshest example: the **persona-placebo benchmark** <!-- claim:persona-identity-placebo-null -->
+(2026-07-12, 3 arms × 2 providers, blind rubric judge, pre-registered
+hypotheses) measured whether famous-figure persona framing improves decision
+answers over the bare method text it wraps. It does not (Δ=0.17, p=0.607) —
+while provider diversity moved judged quality ~15× more than persona identity.
+The measured null closed a planned feature (persona panel-mode) instead of
+shipping theater; the full per-cell data is committed at
+`internal/bench/reports/persona-placebo.json`.
+
 **Behavioural-eval coverage — the honest baseline.** Skill *quality* is only
 as good as its measurement. Today **39 of 271** skills carry a behavioural
 `evals.json`; the highest-traffic / highest-cost tiers (default-surface +

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.11.0",
+    "version": "8.13.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/src/config/agent-settings.template.yml

@@ -473,6 +473,15 @@ quality:
   # introduces a NEW CI gate, smoke test, or test file, the agent
   # MUST execute it locally to prove the gate works. Without that
   # execution the new gate is unverified evidence.
+  #
+  # Posture note (feedback-8.11-2): `false` is a DELIBERATE, documented
+  # design decision, not an omission — remote CI is the single
+  # authoritative gate; local full-pipeline runs duplicate it at
+  # wall-clock + token cost. It never suppresses (a) narrow diff-scoped
+  # probes (type-check/lint/tests over the agent's OWN changed files
+  # before pushing — those always run), (b) the new-gate carve-out
+  # above, (c) user-invoked runs. Run-end reports must say "quality
+  # gates delegated to remote CI", never claim an unrun pipeline passed.
   local_auto_run: false
 
   # Wait for remote CI to finish on the PR / pipeline (true, false)
@@ -620,6 +629,46 @@ worktrees:
 #
 # See `docs/contracts/ai-council-config.md` for the schema.
 
+# --- AI Team (cross-model strong-pair review — /team family) ---
+#
+# Governs the default-off `/team` capability family: one strong external
+# model (via the codex CLI, subscription-authed) reviews inside the repo —
+# the depth complement to the council's breadth. Schema + validation
+# contract: `docs/contracts/ai-team-config.md`. The loader
+# (`src/scripts/ai_team/config.ts`) rejects unknown keys fail-closed.
+ai_team:
+  # Master switch. false (default) = /team commands are never suggested
+  # and every invocation refuses with an enable pointer; true = the
+  # family is live (individual gates below still apply).
+  enabled: false
+
+  # Model handed to the codex CLI. 'auto' (default) = pass NO --model
+  # flag, the codex CLI's own default applies — this tracks the
+  # subscription's current strongest model instead of pinning a stale
+  # ID. Any other value passes through verbatim as `--model <value>`.
+  model: auto
+
+  # Second opt-in for the ONLY wrapper that delegates write access
+  # (/team:delegate → the plugin's native-Codex worker). false (default)
+  # = delegate refuses with an enable pointer even when ai_team.enabled
+  # is true. Both keys must be true before delegation is reachable.
+  allow_delegate: false
+
+  # Per-day cap on team calls. Team calls count into the EXISTING
+  # cli_call_budget openai bucket (~/.event4u/agent-config/cli-calls.json,
+  # daily UTC reset) — one subscription, one counter, never a parallel
+  # count. This key is the team-side ceiling read against that shared
+  # bucket. 0 = block all team calls; raise if you review heavily.
+  max_calls_per_day: 50
+
+  # Suppress the one-line wizard/init recommendation to set up the codex
+  # plugin on Claude-Code hosts. Cosmetic only — never changes behavior.
+  suppress_setup_hint: false
+
+  # NOTE for future keys: `review_gate` (managed loop-bound governance of
+  # the plugin's Stop-hook Review Gate) lands in a later team-mode phase
+  # (Phase 4) — do not add it here ahead of that phase.
+
 # --- Onboarding ---
 #
 # Tracks whether the initial setup flow (/onboard) has been completed