@event4u/agent-config 9.9.0 → 9.10.0

package/docs/guidelines/agent-infra/api-cost-levers.md

@@ -109,18 +109,69 @@ different model.
 
 ## Claude Code note
 
-In Claude Code, prompt caching is automatic — resending the same context prefix
-is cheap, so keeping a stable prefix pays off without any explicit
-`cache_control`. The session-level hygiene levers are `/clear` and `/compact` to
-shed accumulated context, plus subagent delegation for verbose output so it
-never lands in the main context window.
+In Claude Code, prompt caching is automatic for the **main loop** — resending
+the same context prefix is cheap, so keeping a stable prefix pays off without
+any explicit `cache_control`. The session-level hygiene levers are `/clear`
+and `/compact` to shed accumulated context, plus subagent delegation for
+verbose output so it never lands in the main context window.
+
+**Subagents and forks pay a different cache economy — verified against host
+version 2.1.220 (2026-07-30), re-check on drift:**
+
+- A **named subagent** starts its own conversation with its own system
+  prompt and tool set. It builds its own cache from scratch, so its **first
+  call has no cache hit** — the entire per-spawn preamble (rules, tools,
+  dispatch prompt) is a cold write. Subagents use the **five-minute TTL**
+  even on a subscription; there is no per-agent setting to change that (see
+  `## Known upstream costs` below).
+- A **fork** inherits the parent's system prompt, tools, and conversation
+  history exactly, so its first request **reads the parent's cache** instead
+  of writing a fresh one — the only documented mechanism that shares a cache
+  across a dispatch boundary. Forking forces background mode, which changes
+  the tool set and therefore invalidates the very prefix that motivated the
+  fork; weigh that cost before reaching for it — see the fork-vs-subagent
+  ordering rule in See also.
+- Either way, the **cold-start preamble is re-written on every spawn** — the
+  always-loaded rule set, the tool definitions, and the dispatch prompt are
+  not shared across separate subagent instances. Fan-out (many subagents
+  from one parent) multiplies this cost by cohort size; see
+  `## Known upstream costs` below for the fan-out re-prefill issue this
+  package cannot fix.
+
+## Known upstream costs
+
+Host-controlled behaviour this package has confirmed but cannot change at
+any layer. Each entry carries the host version observed and the command to
+re-verify it — a stale entry degrades into a dated observation, never a
+false promise, when Anthropic changes the behaviour underneath it.
+
+| Cost | Observed on | Re-verify |
+|---|---|---|
+| Fan-out (`do-in-parallel`-shaped dispatch) re-prefills the parent-accumulated context **per child** — the waste scales linearly with fan-out width, worst exactly where fan-out is most valuable (anthropics/claude-code#81389, open). No fix at any layer. | Claude Code 2.1.220, 2026-07-30 | `claude --version`; re-check the linked issue for a status change |
+| Host-dispatched subagents are pinned to the **five-minute** cache TTL regardless of subscription tier or any environment variable; `ENABLE_PROMPT_CACHING_1H` does not apply to them. | Claude Code 2.1.220, 2026-07-30 | `claude --version`; re-check the official caching docs for a subagent-TTL setting |
+
+Neither entry implies a package-side fix exists or is planned — both are
+request-construction facts inside the host binary, outside this package's
+reach. This package's own scope is measurement and payload size (what it
+authors), never subagent request construction (what the host authors).
 
 ## See also
 
+- [`cache-economy-refusals`](../../../agents/settings/contexts/cache-economy-refusals.md) —
+  the measured cache figures behind the Claude Code note above, plus the
+  refusals (no interception proxy, no blanket 1h TTL, no cache-hit auto-tuning)
+  recorded so they are not rebuilt.
+
 - [`model-recommendation.md`](model-recommendation.md) — tier routing (the
   capability band behind lever 3).
 - [`size-and-scope.md`](size-and-scope.md) — token discipline for the artifacts
   that become the cached prefix.
+- [`subagent-orchestration/prompts/README.md`](../../../src/skills/subagent-orchestration/prompts/README.md)
+  § Prompt-cache discipline — sibling-uniformity rules and the
+  fork-vs-subagent dispatch ordering that follow from this cache economy.
+- [`docs/contracts/ai-council-config.md`](../../contracts/ai-council-config.md)
+  § `prompt_cache.ttl` — the one surface where this package DOES control a
+  cache-control TTL (the council's own Anthropic calls, never host subagents).
 - The Claude Code `claude-api` plugin skill (external, not vendored here) — the
   authoritative, versioned API reference these figures derive from; re-check it
   when Anthropic pricing or the caching/batch surface changes.

package/docs/guidelines/agent-infra/simplicity-and-goal-demos.md

@@ -1,3 +1,13 @@
+---
+demo_for: minimal-safe-diff, think-before-action
+layer: pattern-memory
+prose_delta:
+  rule_chars_before: 5927
+  rule_chars_after: 6903
+  measured_at: lint-examples-shape-conformance-pass
+  note: "Counts are of THIS demo file, measured with wc -c before and after the pass. The delta is frontmatter plus the Demo / Wrong shape / Right shape / Failure mode / Why it works headings required by lint_examples — no prose was migrated out of a rule and none was removed; every code block is byte-identical."
+---
+
 # Simplicity and Goal Discipline — wrong/right demos
 
 Recognition surface for [`minimal-safe-diff § Anti-over-engineering`](../../src/rules/minimal-safe-diff.md)
@@ -7,11 +17,13 @@ execution clause in `think-before-action`. Per council convergence
 the violation cannot recognize it, no matter how crisp the checklist question.
 Match your diff against the *right* column before presenting.
 
-## 1. Over-abstraction vs. one function
+## Demo 1 — Over-abstraction vs. one function
 
 **Ask:** "Add a function to calculate a percentage discount."
 
-**Wrong — Strategy pattern for a single caller (PHP):**
+### Wrong shape
+
+Strategy pattern for a single caller (PHP):
 
 ```php
 interface DiscountStrategy { public function calculate(float $amount): float; }
@@ -21,7 +33,13 @@ final readonly class DiscountConfig { /* strategy, minPurchase, maxDiscount */ }
 final class DiscountCalculator { /* 30+ lines of orchestration */ }
 ```
 
-**Right — one function until the second discount type is real:**
+**Failure mode:** the wrong version is not "bad code" — it is *premature*
+code: harder to read, more surface to test, and speculative until the
+requirement exists.
+
+### Right shape
+
+One function until the second discount type is real:
 
 ```php
 function calculateDiscount(float $amount, float $percent): float
@@ -30,17 +48,19 @@ function calculateDiscount(float $amount, float $percent): float
 }
 ```
 
-**Why:** No second caller, no second strategy → no abstraction. When the
+### Why it works
+
+No second caller, no second strategy → no abstraction. When the
 second type genuinely arrives, refactor then (`prefer-enums-over-literals` /
-Strategy sniff test governs that moment). The wrong version is not "bad
-code" — it is *premature* code: harder to read, more surface to test, and
-speculative until the requirement exists.
+Strategy sniff test governs that moment).
 
-## 2. Speculative features vs. just-what-was-asked
+## Demo 2 — Speculative features vs. just-what-was-asked
 
 **Ask:** "Save user preferences to the database."
 
-**Wrong — options nobody requested (TypeScript):**
+### Wrong shape
+
+Options nobody requested (TypeScript):
 
 ```ts
 class PreferenceManager {
@@ -52,7 +72,13 @@ class PreferenceManager {
 }
 ```
 
-**Right — the ask, nothing else:**
+**Failure mode:** every optional parameter with one call site, every
+"flexibility" flag, and every handler for a scenario that cannot occur is
+speculative complexity.
+
+### Right shape
+
+The ask, nothing else:
 
 ```ts
 async function savePreferences(db: Db, userId: number, prefs: Prefs) {
@@ -61,66 +87,94 @@ async function savePreferences(db: Db, userId: number, prefs: Prefs) {
 }
 ```
 
-**Why:** Every optional parameter with one call site, every "flexibility"
-flag, and every handler for a scenario that cannot occur is speculative
-complexity. Add caching when performance data demands it, validation when bad
+### Why it works
+
+Add caching when performance data demands it, validation when bad
 data appears, merging when the requirement lands.
 
-## 3. Drive-by refactor vs. surgical diff
+## Demo 3 — Drive-by refactor vs. surgical diff
 
 **Ask:** "Fix the bug where an empty email crashes the validator."
 
-**Wrong:** the fix PLUS improved email regex, new username length checks,
+### Wrong shape
+
+The fix PLUS improved email regex, new username length checks,
 rewritten comments, and a fresh docstring — four changes, one was asked.
 
-**Right:** only the lines that make the empty-email case safe change; every
+**Failure mode:** the "improvements" belong in a follow-up proposed via
+`active-remediation`'s note-and-ask ladder — not smuggled into the bug fix.
+
+### Right shape
+
+Only the lines that make the empty-email case safe change; every
 other line of the function is byte-identical.
 
-**Why:** Every changed line must trace to the stated task
-(`minimal-safe-diff`). The "improvements" belong in a follow-up proposed via
-`active-remediation`'s note-and-ask ladder — not smuggled into the bug fix.
+### Why it works
 
-## 4. Style drift vs. match-existing-style
+Every changed line must trace to the stated task
+(`minimal-safe-diff`).
+
+## Demo 4 — Style drift vs. match-existing-style
 
 **Ask:** "Add logging to the upload function."
 
-**Wrong:** the diff adds logging AND flips quote style, adds type hints,
+### Wrong shape
+
+The diff adds logging AND flips quote style, adds type hints,
 reshapes the boolean return, reflows whitespace — the reviewer can no longer
 see the logging change.
 
-**Right:** logger import + three log lines, inserted in the file's existing
+**Failure mode:** a diff that reformats while changing behavior hides the
+behavior change.
+
+### Right shape
+
+Logger import + three log lines, inserted in the file's existing
 style (its quoting, its spacing, its return pattern), even where you would
 personally write it differently.
 
-**Why:** Style consistency is a repo property, not a per-diff taste decision.
-A diff that reformats while changing behavior hides the behavior change.
+### Why it works
 
-## 5. Own-orphan vs. pre-existing dead code
+Style consistency is a repo property, not a per-diff taste decision.
+
+## Demo 5 — Own-orphan vs. pre-existing dead code
 
 **Ask:** "Replace the legacy formatter call in `processA` with the new one."
 
-**Wrong (too little):** `processA` no longer calls `legacyFormat()`, but the
+### Wrong shape
+
+**Too little:** `processA` no longer calls `legacyFormat()`, but the
 now-unused import and the helper it alone referenced stay behind — the diff
 shipped its own litter.
 
-**Wrong (too much):** while in the file, the agent also deletes
+**Too much:** while in the file, the agent also deletes
 `oldHelper()`, which `processB` — untouched by this diff — still references
 in another module, or which was already orphaned *before* this task.
 
-**Right:** remove exactly the imports/variables/functions whose **last
+**Failure mode:** two directions of the same error — the diff shipped its own
+litter (too little), or it deleted code that untouched files still reference,
+or that was already orphaned before this task (too much).
+
+### Right shape
+
+Remove exactly the imports/variables/functions whose **last
 reference disappeared in a file this diff touched**; anything still
 referenced from untouched files — or orphaned before the task — is
 pre-existing debt: mention it, don't delete it.
 
-**Why:** The boundary is mechanical (grep after editing), so there is no
+### Why it works
+
+The boundary is mechanical (grep after editing), so there is no
 judgment call to rationalize — see
 [`minimal-safe-diff § Own-orphan cleanup`](../../src/rules/minimal-safe-diff.md#own-orphan-cleanup).
 
-## 6. Vague plan vs. verifiable per-step plan
+## Demo 6 — Vague plan vs. verifiable per-step plan
 
 **Ask:** "Add rate limiting to the API."
 
-**Wrong — unverifiable narration:**
+### Wrong shape
+
+Unverifiable narration:
 
 ```
 1. Review the code
@@ -129,7 +183,11 @@ judgment call to rationalize — see
 4. Test the changes
 ```
 
-**Right — every step carries its check:**
+**Failure mode:** a step without a `verify:` is an assumption.
+
+### Right shape
+
+Every step carries its check:
 
 ```
 1. In-memory limit on one endpoint → verify: 11th request in a minute → 429 (test)
@@ -137,7 +195,9 @@ judgment call to rationalize — see
 3. Shared store backend → verify: counter survives app restart; two instances share the count
 ```
 
-**Why:** A step without a `verify:` is an assumption. Strong criteria let the
+### Why it works
+
+Strong criteria let the
 loop run independently (`verify-before-complete` then has something to
 check); "make it work" guarantees clarification churn after the fact instead
 of before.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.9.0",
+    "version": "9.10.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,

package/src/agent-src/templates/scripts/tier_usage_report.ts

@@ -234,7 +234,7 @@ function _within_window(ts_bucket: string, window_days: number | null): boolean
     return ms >= Date.now() - window_days * 24 * 60 * 60 * 1000;
 }
 
-type BucketKey = string; // `${tier}${command}` — composite (tier, command) key.
+type BucketKey = string; // `${tier}\0${command}` — composite (tier, command) key.
 interface RowStats {
     count: number;
     distinct_users: number;
@@ -274,7 +274,7 @@ function aggregate(log_path: string, window_days: number): AggregateResult {
         }
         kept += 1;
         const tier = Math.trunc(rec.tier);
-        const key = `${tier}${rec.command}`;
+        const key = `${tier}\0${rec.command}`;
         if (!keyMeta.has(key)) {
             keyMeta.set(key, { tier, command: rec.command });
             counts.set(key, 0);

package/src/agent-src/templates/scripts/work_engine/directives/ui/polish.ts

@@ -336,7 +336,7 @@ function _classify_token_violations(
     tokens: Record<string, Any>,
 ): [Record<string, Any>[], Record<string, Any>[]] {
     const matched: Record<string, Any>[] = [];
-    // Insertion-ordered map keyed by `${category}${value}` to mirror the
+    // Insertion-ordered map keyed by `${category}\0${value}` to mirror the
     // Python `dict[tuple[str, str], int]` insertion order.
     const unmatched_counts = new Map<string, { category: string; value: string; count: number }>();
     for (const finding of findings) {
@@ -356,7 +356,7 @@ function _classify_token_violations(
             matched.push(finding);
             continue;
         }
-        const key = `${category}${value}`;
+        const key = `${category}\0${value}`;
         const existing = unmatched_counts.get(key);
         if (existing) {
             existing.count += 1;

package/src/agent-src/templates/scripts/work_engine/directives/ui/review.ts

@@ -294,7 +294,7 @@ function _filter_known(violations: Any[], known: Any[]): Any[] {
  * scalars, mirroring Python tuple-equality in a JS `Set`.
  */
 function _keyOf(rule: Any, selector: Any): string {
-    return `${_tag(rule)}${_tag(selector)}`;
+    return `${_tag(rule)}\0${_tag(selector)}`;
 }
 
 function _tag(v: Any): string {

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

@@ -145,6 +145,36 @@ rule_loading_tier: __RULE_LOADING_TIER__
 lean_projection:
   mode: eager-all
 
+# --- Telegraph condensation (output-side) ---
+#
+# speak_scope: off | prose_only | aggressive   (QUOTE the value — bare `off` is a
+#                                              YAML 1.1 boolean, not the string)
+#
+# `off` is the shipped default per docs/adrs/telegraph/0001-default-off-until-bench.md
+# (Status: accepted) and docs/contracts/condensation-default-kill-criterion.md.
+# Reason it is off: the only output-side bench (telegraph-v1, n=10, 2026-05-16)
+# measured median vs_terse -9.27% (API counts) / -5.47% (exact cl100k_base
+# re-analysis) — telegraph emits MORE tokens than a plain "be terse" instruction.
+# The kill-criterion table therefore lands on "criterion not met — defer" and the
+# telemetry multiplier stays suspended (0.9155 < 1.0).
+#
+# NOTE: `speak_scope: off` disables the BEHAVIOUR but not the COST — the projector
+# gates this rule on `telegraph.speak`, never on speak_scope, so under
+# `lean_projection.mode: eager-all` the ~982-token body still ships every session.
+# Set `speak: false` for zero-cost dormancy.
+#
+# Stated explicitly here because until 2026-07-29 this default existed only in
+# prose — and two prose sources disagreed (the rule said prose_only, the accepted
+# ADR said off). Do not flip without a passing output-side bench.
+telegraph:
+  # speak: false = DORMANT (the shipped default per docs/adrs/telegraph/0002).
+  # The rule is omitted from dist/router.json entirely, so its ~982-token body
+  # never ships. This — not speak_scope — is the lever that stops the cost:
+  # compile_router gates on `speak` and never reads speak_scope.
+  # Set true only after an output-side bench clears the kill-criterion bar.
+  speak: false
+  speak_scope: "off"
+
 # --- Token-rich skills governance ---
 #
 # Skills marked `token_budget_class: rich` in their frontmatter are exempt
@@ -642,7 +672,7 @@ subagents:
   # delegate frontier-priced or speculative work. `resolveShippedDefault()`
   # remains the telemetry-driven DEMOTION gate: a measured regression demotes
   # back to `ask`.
-  auto: on
+  auto: "on"
 
   # Route delegable sub-tasks to the lowest-capable model tier (cost + speed
   # via model downshift). true (default) = downshift per declared model_tier;
@@ -1114,7 +1144,7 @@ decision_engine:
   #   low    = refuse to advance when band is below low
   #   medium = refuse when below medium
   #   high   = refuse when below high
-  min_confidence: off
+  min_confidence: "off"
 
   # Risk-class ceiling for Phase=Implement.
   #   off    = no ceiling (default)

package/src/config/ci-local-parity.yml

@@ -0,0 +1,142 @@
+# CI ↔ local parity manifest — the input to `check_ci_local_parity.ts`.
+#
+# WHY THIS EXISTS
+# ---------------
+# The local aggregate (`task ci`) and the CI workflows drifted apart in BOTH
+# directions, and each direction cost real defects:
+#
+#   CI-only  — a gate CI runs that no local chain reaches. The contributor pushes,
+#              CI goes red, and the fix costs a round trip. Measured 2026-07-30:
+#              check_portability and check_adr_frontmatter turned a PR red that a
+#              local run would have caught, twice in one session.
+#
+#   local-only — a gate `task ci` runs that no workflow does. Nothing enforces it
+#              remotely, so a defect merges. Measured: check-index had verified the
+#              artefact index for a long time and ran in no workflow, which is how
+#              16 stale rows in agents/index.md + docs/catalog.md reached main.
+#              check_bridge_derivation is the same shape.
+#
+# A gate that exists on one side only drifts silently on the other. This manifest
+# plus the checker makes each direction a declared, reviewable choice instead of an
+# accident.
+#
+# THE CONTRACT
+# ------------
+# The checker DERIVES both sides — it never trusts a hand-maintained list of gates:
+#
+#   CI side     parsed from .github/workflows/*.yml — every `./scripts-run
+#               src/scripts/<name>`, `npx tsx src/scripts/<name>`, `node <path>` and
+#               `task <name>` invocation.
+#   local side  the transitive closure of the `task ci` / `task consistency` chains
+#               plus the pre-push hook, resolved through taskfiles/*.yml.
+#
+# Anything present on one side and absent on the other must appear below with a
+# reason, or the checker fails. That is the whole mechanism: drift is allowed, but
+# only on the record.
+#
+# Parity is by gate ID, not by argv. Three gates run locally in a cheap variant and
+# in CI in a strict one (check_release_published bare vs --strict --check-npm,
+# build_cloud_bundle --check vs --all --clean, build_linear_digest offline vs live).
+# They need no declaration: the parity question is "can a contributor run this before
+# pushing at all", and the answer is yes. Declaring them anyway produced exactly the
+# dead exemption the stale-declaration check exists to catch — it was removed rather
+# than kept, because an exemption nothing needs is one the next reader trusts.
+#
+# WHY NOT JUST "RUN task ci BEFORE EVERY PUSH"
+# --------------------------------------------
+# Because a pre-push gate that is red for a reason the contributor did not cause
+# either blocks every push or trains people to ignore it, and the second is worse
+# than no gate. Two measured bounds from the same sweep:
+#
+#   bucket A (repo-content gates) sum to ~14.5s  → affordable before a push
+#   check_enforcement_coverage alone is 30.7s    → belongs in the post-CI loop
+#
+# So `pre_push_budget_seconds` below is a real budget, not a wish. A gate declared
+# `local_only` or `both` that exceeds it is reported, not silently added to the hook.
+
+# Wall-clock ceiling for the pre-push gate set, in seconds. Derived from the
+# measured bucket-A sum (14.5s) plus headroom; the existing hook already costs
+# `task consistency` + eslint + tsc, so this is a bounded increase, not a new tax.
+pre_push_budget_seconds: 25
+
+# Gates CI runs that no local chain reaches — each needs a reason it cannot or
+# should not run locally. `reason` is free text; `class` is one of:
+#   network        needs a token, a registry, or a live API
+#   release        verifies tag / release / published-package state
+#   artifact       needs something only CI builds (site, tarball, bundle)
+#   benchmark      it is a measurement, timing-sensitive or paid
+#   matrix         needs an OS or Node version this machine is not
+ci_only:
+  - id: adoption_snapshot
+    class: network
+    reason: "live api.npmjs.org + api.github.com calls, reads GITHUB_TOKEN"
+  - id: sync_github_metadata
+    class: network
+    reason: "hard-fails without GITHUB_TOKEN; mutates repo topics/description via the API"
+  - id: check_release_pr_shape
+    class: release
+    reason: "shells out to `gh pr diff <n>` — needs a live PR and a token"
+  - id: check_release_adjacent_health
+    class: release
+    reason: "queries GitHub Actions run history via gh"
+  - id: bench_drift_check
+    class: benchmark
+    reason: "consumes rolling bench reports that only a bench run produces"
+  - id: bench_baseline_ready
+    class: benchmark
+    reason: "same — no local baseline to compare against"
+  - id: bench_hook_latency
+    class: benchmark
+    reason: "a latency measurement; 24.0s measured and timing-sensitive on a loaded machine"
+  - id: check_site_links
+    class: artifact
+    reason: "needs the built Starlight site; exits 2 unbuilt or stale (registered in gate-coverage.yml with unavailable_exit: 2)"
+  - id: pack_mcp_content
+    class: artifact
+    reason: "writes the tracked internal/workers/mcp/content.json deploy artifact — a local run dirties the tree"
+  - id: consumer_matrix
+    class: matrix
+    reason: "consumes the npm pack tarball across a Node version matrix"
+  - id: cross_model_smoke
+    class: network
+    reason: "paid cross-model canary calls, secret-gated"
+  - id: trigger_eval_rotation
+    class: network
+    reason: "paid model calls"
+  - id: self_review_gate
+    class: network
+    reason: "--dry-run in the PR job; the live variant is a paid model call on the PR diff"
+  - id: bench_run
+    class: benchmark
+    reason: "paid model calls against a corpus"
+  - id: bench_runner
+    class: benchmark
+    reason: "the runner behind bench_run — same paid calls"
+  - id: skill_trigger_eval
+    class: benchmark
+    reason: "paid cross-model trigger-activation eval; the offline structural half is check_trigger_evals, which IS local"
+  - id: evaluator_umbrella
+    class: artifact
+    reason: "shell umbrella over CI-only evaluator fixtures"
+  - id: smoke_host_loadability
+    class: artifact
+    reason: "temp-HOME install + `claude plugin validate`; measured >100s, did not finish inside a 2-minute budget"
+  - id: install
+    class: matrix
+    reason: "the installer end-to-end against a scratch HOME on the OS matrix; a local run would rewrite this machine's own agent config"
+  - id: release
+    class: release
+    reason: "tags, bumps, publishes, opens the release PR — the release itself"
+
+# Gates a local chain runs that no workflow does — each needs a reason it is not
+# worth remote enforcement, OR it should simply be added to a workflow. Prefer
+# adding it: a local-only gate is the direction that let real defects merge.
+local_only:
+  - id: check_knowledge_sharing
+    class: staging-scoped
+    reason: >
+      Inspects the STAGED set (a gitignored intake file staged anyway via `git add -f`),
+      and CI has no staged set — the commit already happened by the time a workflow
+      runs. The committed-tree equivalent ("a file that should be gitignored is
+      tracked") is a different invariant and would need its own mode, so this is not
+      the local-only-by-neglect case the manifest warns about.