@event4u/agent-config 9.15.0 → 9.17.0

package/dist/ui/index.html

@@ -27,7 +27,7 @@
                 document.documentElement.setAttribute('data-theme', theme);
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-DJY_vQVn.js"></script>
+      <script type="module" crossorigin src="/assets/index-DmR0mbk4.js"></script>
       <link rel="stylesheet" crossorigin href="/assets/index-jSfMW8_t.css">
     </head>
     <body>

package/docs/guidelines/abstraction-thresholds.md

@@ -0,0 +1,53 @@
+# Abstraction Thresholds — the per-class canon
+
+> The single source of truth for "how many repetitions before you extract". Every
+> other artifact that states a numeric extraction threshold cites this table and
+> names its artifact class — a bare number outside this file is drift
+> (enforced by `src/scripts/lint_abstraction_thresholds.ts`).
+
+_Origin: council convergence 2026-08-03 (claude-sonnet-4-5 + gpt-4o, unanimous), recorded in ADR-213. Before this file, four artifacts stated four bare numbers (2 / 3+ / ≥4 / ≥3) with no scope tags — an agent loading them together received contradictory instructions._
+
+## Why the bars differ — cost scales with the artifact class
+
+Extracting a pure helper function is a near-zero-cost act; extracting a stateful
+UI component creates a file, a props contract, and a test surface. The threshold
+is a price signal: the heavier the extraction, the more proven repetition it
+must buy. These are **deliberately different bars for different acts**, not
+editorial drift.
+
+## The canon
+
+| Artifact class | Concrete tag (what to check) | Threshold |
+|---|---|---|
+| **Code-level abstraction** — helper, method, class, Strategy, generic, config layer | any non-UI code shape | **2 real repetitions** (or a genuine second axis of change) |
+| **Pure-markup UI shell** — props-only fragment, no state (button shell, card frame, header) | renders props, holds no state | **3+ uses** |
+| **Stateful UI component** — carries real props/state (form, table, filter) | repeats **AND** has varying props / local state | **~4+ repeats AND real state** (both conditions) |
+| **Utility-class string** (Tailwind et al.) — repeated class list | identical class string | **≥ 3 duplications** (mechanism table: [`tailwind-engineer`](../../src/skills/tailwind-engineer/SKILL.md)) |
+
+The code-level bar of **two** is this suite's settled base decision (the
+borrowed "Rule of Three" for code was evaluated and not adopted — see
+[`minimal-safe-diff-mechanics`](agent-infra/minimal-safe-diff-mechanics.md)).
+The UI rows are scoped carve-outs **above** that base bar, never a license to
+lower it.
+
+## The qualitative floor — applies to every row
+
+A number alone never justifies an extraction. In every class, a reviewer must
+be able to name the **concrete duplication or the concrete second axis of
+change** the abstraction removes. One occurrence is not a component; one branch
+is not a Strategy; a repeat with no varying props is inlined, not extracted.
+
+## Precedence
+
+[`minimal-safe-diff`](../../src/rules/minimal-safe-diff.md) / YAGNI win on every
+conflict: these thresholds authorize extraction when repetition is **already
+present in the diff** — never speculative abstraction for "this could grow
+later". See [`component-oriented-and-oop-development`](component-oriented-and-oop-development.md)
+§ The load-bearing caveat.
+
+## See also
+
+- [`architecture`](../../src/rules/architecture.md) — the rule that carries the code-level bar.
+- [`fe-design`](../../src/skills/fe-design/SKILL.md) § Component granularity — the UI-shell bar in context.
+- [`ui-component-architect`](../../src/skills/ui-component-architect/SKILL.md) § Componentization threshold — the stateful-component bar in context.
+- ADR-213 — the decision record scoping the bars.

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

@@ -135,7 +135,7 @@ source's remote lookup is dropped — a lethal-trifecta egress concern).
 - Is the scope bounded? (not "make it better" but "add X to Y")
 - Are edge cases considered?
 
-**If unclear** → ask ONE focused question. Max 2 questions, never an interrogation.
+**If unclear** → ask ONE focused question per turn (`ask-when-uncertain` Iron Law — serial, never batched), never an interrogation.
 
 ### 8b. Does it fit the existing architecture?
 

package/docs/guidelines/agent-infra/asking-and-brevity-examples.md

@@ -120,6 +120,13 @@ is a fabricated fact wearing a number:
 
 A step list is honest ("A → B → C, C depends on B"); a schedule is invention.
 
+**Carve-out — world-knowledge ranges.** An industry-typical duration sourced
+from public benchmarks in strategy-advisory output ("integrations of this
+class typically run 4–8 weeks") is a statement about the world, not a
+prediction of the agent's or the user's own latency — allowed, but it MUST
+carry an "industry-typical, not a prediction" qualifier. Unqualified, it
+reads as the banned schedule.
+
 ### Never cite the rule as the reason
 
 When declining or constraining an action, give the **actual, substantive

package/docs/guidelines/agent-infra/context-hygiene-mechanics.md

@@ -68,8 +68,8 @@ If you need an ignored skill: read its SKILL.md directly, apply guidance, then a
 
 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).
+`agents/state/context-hygiene.json` is not maintained automatically
+(tool-call 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

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

@@ -27,12 +27,14 @@ The smallest change is also the least *abstract* and least *speculative* one:
   / generic / config layer to dedupe two or three call sites — inline
   repetition is cheaper to read and change than the wrong abstraction. Per new
   abstraction: **cite the second caller — or inline it.** The operative
-  threshold in this suite is the **second real repetition** (or a genuine second
-  axis of change), matching `architecture` and
+  **code-level** threshold in this suite is the **second real repetition** (or a
+  genuine second axis of change), matching `architecture` and
   [`component-oriented-and-oop-development`](../component-oriented-and-oop-development.md);
   the "three lines" phrasing is about *line* count inside one call site, not a
   third-occurrence gate. A borrowed "wait for the third occurrence" rule is
-  **not** adopted — it would fork a threshold this repo already decided.
+  **not** adopted for code — it would fork a threshold this repo already
+  decided. UI extractions carry deliberately higher, scoped bars (ADR-213) —
+  the per-class canon is [`abstraction-thresholds`](../abstraction-thresholds.md).
 - **No speculative features.** Nothing beyond what was asked: no
   configurability or "flexibility" nobody requested, no parameters with one
   call site, no error handling for scenarios that cannot occur in this

package/docs/guidelines/agent-infra/size-and-scope.md

@@ -81,8 +81,11 @@ Commands orchestrate — not implement.
 
 ## AGENTS.md
 
-- Target: **200–800 words**
-- Acceptable: **up to ~1200 words**
+- Enforced budget: **character caps** via `lint_agents_md.ts` — package
+  root fails at **3,000 chars** (warns 2,800); consumer template fails at
+  **2,500 chars** (warns 2,300).
+- Word guidance: aim for **≤ ~450 words** — that is roughly what fits
+  under the 3,000-char cap.
 
 High-level only.
 
@@ -92,6 +95,9 @@ High-level only.
 
 - Ideal: **< 60 lines**
 - Acceptable: **< 100–150 lines**
+- Note: Copilot Code Review reads only the **first 4,000 characters**
+  (see `src/agent-src/templates/copilot-instructions.md`), so the
+  effective cap is character-based — highest-priority rules go up top.
 
 Must stay lightweight.
 

package/docs/guidelines/component-oriented-and-oop-development.md

@@ -48,9 +48,13 @@ package's restraint posture and defers to it on every conflict:
   pattern for a five-line function, no class where a function is clearer.
 
 Rule of thumb: **two real repetitions (or a genuine second axis of change)
-before you extract.** One occurrence is not a component; one branch is not a
-Strategy. A reviewer should be able to name the concrete duplication or the
-concrete change-axis the abstraction removes.
+before you extract a code-level abstraction.** One occurrence is not a
+component; one branch is not a Strategy. A reviewer should be able to name the
+concrete duplication or the concrete change-axis the abstraction removes.
+UI extractions carry deliberately higher, scoped bars (shell 3+ · stateful
+component ~4 + real state) — the per-class canon is
+[`abstraction-thresholds`](abstraction-thresholds.md); this file does not
+restate it.
 
 **Precedence (explicit): `minimal-safe-diff` / YAGNI always trump OOP
 advocacy.** When "prefer OO shape" and "smallest change" conflict, the smallest
@@ -67,11 +71,12 @@ when they repeat. Depth and mechanics already live in dedicated skills — consu
 them, don't duplicate:
 
 - [`fe-design`](../../src/skills/fe-design/SKILL.md) § Component Architecture —
-  the stack-agnostic "kind, not framework" taxonomy, granularity, extract-on-3+.
+  the stack-agnostic "kind, not framework" taxonomy, granularity, and the
+  UI-shell bar (per [`abstraction-thresholds`](abstraction-thresholds.md)).
 - [`ui-component-architect`](../../src/skills/ui-component-architect/SKILL.md) —
   how to *shape* a reusable component: composition over inheritance, slot
-  contracts, prop-API caps, controlled/uncontrolled, the componentization
-  threshold (repeat **and** real state).
+  contracts, prop-API caps, controlled/uncontrolled, the stateful-component
+  bar (repeat **and** real state, per the same canon).
 - [`existing-ui-audit`](../../src/skills/existing-ui-audit/SKILL.md) — the
   reuse-before-invent gate: inventory existing components/tokens/primitives
   first (enforced by [`ui-audit-gate`](../../src/rules/ui-audit-gate.md)).

package/docs/guidelines/docs/readme-size-and-splitting.md

@@ -18,7 +18,10 @@ and `readme-reviewer` skills.
 | **< 150** | Healthy | No splitting needed |
 | **150–300** | Busy | Add a Table of Contents; review for padding |
 | **300–500** | Overloaded | Split deep content to `/docs/` or `references/` |
-| **> 500** | Broken | Hard split required; README has stopped being an entry point |
+| **> 500** | Broken | Split strongly recommended; README has stopped being an entry point |
+
+These bands are editorial; the **enforced** limit is **750 lines** —
+`lint_readme_size.ts` fails the build above it.
 
 Lines, not bytes — tables, code blocks, and badges inflate bytes but stay
 scannable. The real signal is: **can a new reader reach install/usage
@@ -61,7 +64,7 @@ docs/
   api.md               ← full API reference
 ```
 
-README stays < 200 lines. Each `/docs/` file is a self-contained chapter.
+After a split, aim for a README < 200 lines. Each `/docs/` file is a self-contained chapter.
 
 ### Strategy 2 — Deep-link tables for multi-platform repos
 

package/llms.txt

@@ -180,6 +180,7 @@ onboarding-program: Use when shaping employee onboarding — time-to-productivit
 one-on-one-cadence: Use when designing engineering 1:1s — cadence, agenda mix, growth-vs-blocker-vs-trust shape, cancellation anti-patterns. Triggers on 'fix my 1:1s', 'should I cancel 1:1s this week'.
 openapi: Use when documenting APIs — OpenAPI/Swagger, PHP attributes, Redocly validation, versioned specs — even when the user just says 'document this endpoint' without naming OpenAPI.
 org-design: Use when shaping team structure — functional vs squad, span-of-control, reorg cost, Conway-aware boundaries. Triggers on 'should we reorg', 'how do we split this team'.
+overbuild-review-lens: Use when a diff builds more than the task needs — code that should not exist, a dependency the platform already covers, or a clever form where a flat one reads better. Deletion-hunting, not quality.
 override-management: Creates and manages project-level overrides for shared skills, rules, and commands — extending or replacing originals from .augment/ with project-specific behavior in agents/overrides/.
 pdf-tools: Use when creating, merging, splitting, filling, or extracting from a PDF — library-per-task, output validated. Triggers on 'merge these PDFs', 'fill this PDF form', 'split the PDF', 'create a PDF'.
 perf-feedback-craft: Use when shaping feedback — situation-behavior-impact, growth-vs-corrective split, cadence design, ladder-of-inference checks. Triggers on 'how do I give this feedback', 'perf review shape'.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.15.0",
+    "version": "9.17.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,
@@ -110,11 +110,11 @@
         "@fastify/static": "^10.1.2",
         "@modelcontextprotocol/sdk": "^1.30.0",
         "@preact/signals": "^2.10.0",
-        "commander": "^12.1.0",
+        "commander": "^15.0.0",
         "execa": "^9.5.0",
         "fastify": "^5.11.0",
-        "js-yaml": "^4.1.0",
-        "open": "^10.2.0",
+        "js-yaml": "^5.2.0",
+        "open": "^11.0.0",
         "preact": "^10.29.0",
         "yaml": "^2.9.0",
         "zod": "^3.25.0",

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

@@ -321,6 +321,28 @@ personal:
   # See user-types/README.md for the per-id contract.
   user_type: "__USER_TYPE__"
 
+# --- Reply verbosity ---
+verbosity:
+  # Announce intent before tool batches ("Let me check X…") — only honored
+  # when personal.play_by_play is ALSO true (the direct-answers narration
+  # carve-out requires both). Default false = no intent narration.
+  intent_announcements: false
+
+  # Show generated commit messages, PR titles/bodies, branch names before
+  # acting. false = use generated content directly (/commit terse path).
+  preview_artifacts: false
+
+  # Confirmation prompts for routine workflow steps with one obvious answer.
+  # Iron-Law gates (commit-policy, scope-control git-ops, Hard Floor) ALWAYS
+  # ask regardless of this setting.
+  routine_confirmations: false
+
+  # Offer "run AI Council on this?" inside delivery commands.
+  offer_council_in_delivery: false
+
+  # Status blocks after a successful action: off | minimal | full.
+  post_action_reports: minimal
+
 # --- Project / team preferences ---
 project:
   # Path to the PR template file (relative to project root)
@@ -724,7 +746,9 @@ subagents:
   # the resource-availability gate (council 2026-08-03).
   #   ask  = (default) first budget-motivated downshift of a session asks once
   #   auto = apply the relation silently (telemetry line per routed request)
-  #   off  = today's behavior; single-flip rollback
+  #   off  = today's behavior; single-flip rollback — QUOTE it ("off") when
+  #          editing: bare off is YAML-1.1 boolean false (readers coerce, but
+  #          the quoted form is the unambiguous one, same as `auto: "on"`)
   budget_routing: ask
 
   # Prefer a separate-quota-pool model for delegable sub-tasks WHERE the host

package/src/config/budget-routing.json

@@ -0,0 +1,7 @@
+{
+  "$comment": "Single source of truth for the budget-routing reserve lifecycle (docs/contracts/budget-routing.md). Read by BOTH reserve readers — src/scripts/_lib/tier_budget_routing.ts (acquireBudgetPermit) and src/scripts/cost/budget.mjs (tier subcommand) — so the reserve window can never diverge between them. reserve_ttl_ms: reserves are RACE PROTECTION, not spend accounting — a pending entry older than this is dead and is dropped at the next compaction. lock_break_ms: an .lock file older than this is a crash leftover and is broken (unlink + one retry).",
+  "owner": "maintainer",
+  "review_by": "2027-08-03",
+  "reserve_ttl_ms": 600000,
+  "lock_break_ms": 30000
+}

package/src/config/evaluator-budgets.json

@@ -8,7 +8,9 @@
         "on_release": "fail",
         "on_main_and_prs": "warn",
         "on_local": "fail",
-        "always_blocking": ["a metric with no measurement supplied"],
+        "always_blocking": [
+            "a metric with no measurement supplied"
+        ],
         "rationale": "road-to-gates-that-can-fail Phase 5. A hard fail on main turns every legitimate command addition into a blocked merge, which is how budgets get quietly raised with a cushion instead of consciously — so budget / regression / drift findings are ADVISORY on main, the nightly and ordinary PRs, and BLOCKING on a release ref. Not a weakening: before the Phase-4 path triggers, this gate ran on release PRs and the nightly only, so the surfaces that now warn never saw it at all. A LOCAL run (no CI env) is strict, because a maintainer running it by hand — including release.ts — wants the strict answer and blocks nobody. A metric with NO measurement is always blocking in either posture: that is a broken harness reporting green on nothing. Implemented in src/scripts/check_evaluator_budgets.ts::detectPosture; override with --posture warn|fail.",
         "delivery": "This posture IS the nightly-visibility route (council 2026-08-02, blocker nightly-visibility-owner), not a second mechanism beside it: the nightly publishes measurement_record below, a later run re-measures and compares, and the contradiction warns on main / fails on release. No notification channel, no auto-managed issue — a one-maintainer channel producing routine noise gets muted, and a muted channel reproduces the original failure."
     },
@@ -25,13 +27,8 @@
         },
         "not_re_measured": "unpacked_size_mb, node_modules_mb, runtime_dep_count, cli_version_cold_ms, mcp_boot_to_initialize_ms. All five require the packed-tarball harness (npm pack of a fully built tree, then a clean `npm install --omit=dev <tarball>` into a scratch project) that evaluator_umbrella.sh runs in CI. They were NOT re-measured in this pass and their values remain the 2026-07-27 acceptance numbers — stated rather than invented. The next nightly writes the real numbers into measurement_record, and the drift check then reports any contradiction with last_measured on the PR that carries it."
     },
+    "removed_2026_08_04": "unpacked_size_mb (max 28) — removed by maintainer decision at the 9.17.0 release: the gate turned every legitimate payload addition into a blocked release (measured 28.22 vs max 28 with all functional gates green), and the maintainer judged tarball size not worth gating. evaluator_umbrella.sh still MEASURES and records unpacked_size_mb as evidence; only the budget enforcement is gone. ADR-204 review_trigger (a) fired and was resolved this way.",
     "budgets": {
-        "unpacked_size_mb": {
-            "max": 28,
-            "last_measured": 26.05,
-            "last_measured_at": "2026-07-27",
-            "method": "npm pack --json → dist.unpackedSize / 1e6 — includes the Phase-1 precompiled bundles (dist/hooks/dispatch.js + dist/mcp/server.mjs, ~2.1 MB) that bought the 23x hook-latency win and the tsx removal, plus dist/cli-delegate/ (~1.40 MB, ADR-204) which finished that removal for the consumer command surface. This gate is the ONLY size trip-wire on those bundles by design: a dedicated per-bundle budget key would need its own measurement wired into evaluator_umbrella.sh, and an unwired key fails check_evaluator_budgets with 'no measurement supplied' instead of guarding anything. ADR-204 projected 27.45 against max 28 without packing — the next real measurement here is the confirming one, and headroom is thin"
-        },
         "node_modules_mb": {
             "max": 140,
             "last_measured": 127,
@@ -61,11 +58,11 @@
             "deterministic": false
         },
         "cli_help_command_count": {
-            "max": 81,
-            "last_measured": 81,
-            "last_measured_at": "2026-08-03",
+            "max": 82,
+            "last_measured": 82,
+            "last_measured_at": "2026-08-04",
             "method": "registry enumeration — count of `{ name: '...', disposition` entries in src/cli/registry.ts (NOT --help prose parsing; methods historically disagreed 74 vs 76 vs 79)",
-            "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR."
+            "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82."
         },
         "mcp_public_tool_count": {
             "max": 19,

package/src/config/gate-coverage.yml

@@ -260,6 +260,36 @@ gates:
       failure direction was false-positive rather than false-green, but the
       cause was the same dead root.
 
+  - id: lint_abstraction_thresholds
+    argv: []
+    min_scanned: 400
+    corpus: "src/rules + src/skills + src/agent-src/commands + docs/guidelines .md (533 at baseline)"
+    status: enforced
+    note: >
+      A collapse below the floor would mean the gate stopped reading the tree
+      that states extraction thresholds, so a bare or diverging threshold
+      (ADR-213 drift) could land while the gate still printed green.
+
+  - id: lint_profile_personas
+    argv: []
+    min_scanned: 5
+    corpus: "src/agent-src/profiles/*.yml (6 seed profiles at baseline)"
+    status: enforced
+    note: >
+      Fewer than 5 profiles scanned would mean the gate stopped reading the
+      seed-profile dir, so a defaults.personas id that resolves to no persona
+      file could land while the gate still printed green.
+
+  - id: lint_token_budget_discipline
+    argv: []
+    min_scanned: 200
+    corpus: "src/skills/*/SKILL.md (288 at baseline)"
+    status: enforced
+    note: >
+      A collapse below the floor would mean the gate stopped reading the skills
+      tree, so a rich-tagged skill without its justification section (or a cap
+      breach) could land while the gate still printed green.
+
   - id: lint_framework_leakage
     argv: []
     min_scanned: 350