@event4u/agent-config 14.23.0 → 16.0.0

package/dist/agent-src/guidelines/agent-infra/api-cost-levers.md

@@ -0,0 +1,177 @@
+# API Cost Levers
+
+Reference material for a downstream AI-coding agent that wants to cut its own
+Claude API dollar bill. Four platform-level billing levers, the exact economics
+of each, and how they interact. Read on demand — not always-loaded.
+
+Facts sourced from the in-repo `claude-api` plugin skill plus platform research
+(2026-07-14). Do not invent an API shape beyond what is stated here.
+
+## The four levers at a glance
+
+| Lever | Cuts | Best for | Watch out for |
+|---|---|---|---|
+| Prompt caching | Repeated input tokens | Stable prefix reused across calls (system prompt, tools, repo map) | Any byte change in the prefix invalidates the rest |
+| Batch API | 50% input + output | Non-interactive bulk work (classification, summarization, evals) | Async, up to 24h, results unordered |
+| Model tiering | Per-token price | Routine work on a cheaper model | Switching model is a cache miss |
+| Effort / output sizing | Thinking + output tokens | Routine turns that don't need deep reasoning | Oversized `max_tokens` risks runaway output |
+
+## 1. Prompt caching
+
+Put the large, byte-**stable** context first — system prompt, tool definitions,
+a corpus or repo map, few-shot examples — behind a
+`cache_control: {type: 'ephemeral'}` breakpoint. Keep volatile content (the
+varying question, timestamps, per-request IDs) **after** the last breakpoint.
+The cache is a **prefix match**: any byte change in the cached prefix
+invalidates everything after it. Render order is tools then system then
+messages.
+
+Caching is GA — **no beta header needed**.
+
+Economics:
+
+- Cache reads cost approximately 0.1x the base input price.
+- Cache writes cost 1.25x (5-minute TTL) or 2x (1-hour TTL).
+- Break-even is after **one** read on the 5-minute TTL.
+
+Constraints:
+
+- The minimum cacheable prefix is model-dependent (approximately 1024–4096
+  tokens). Shorter prefixes silently do not cache.
+- The cache is workspace-isolated (since February 2026).
+
+Verify a hit with `usage.cache_read_input_tokens > 0`.
+
+```json
+{
+  "system": [
+    { "type": "text", "text": "<large stable system prompt>",
+      "cache_control": { "type": "ephemeral" } }
+  ],
+  "messages": [
+    { "role": "user", "content": "<the varying question>" }
+  ]
+}
+```
+
+## 2. Batch API
+
+For **non-interactive, non-latency-sensitive bulk work** — bulk classification,
+mass file summarization, eval runs. Not chatbots or interactive assistants.
+
+- **50% off both input and output tokens.**
+- Async: results within 24h (usually much less), keyed by `custom_id`, arriving
+  **unordered** — key results by `custom_id`, never by position.
+- **Stacks with prompt caching**: a cached-batch input token can reach
+  approximately 0.05x the standard input price.
+
+## 3. Model tiering
+
+Treat models like a team — a cheap model for mechanical or routine work, the
+expensive model only for hard judgment. Approximate input / output price per 1M
+tokens:
+
+| Model | Input | Output |
+|---|---|---|
+| Haiku | $1 | $5 |
+| Sonnet | $3 | $15 |
+| Opus | $5 | $25 |
+| Fable | $10 | $50 |
+
+Opus input is approximately 5x Haiku. Tier by task **difficulty**, not blindly:
+a cheaper model that gives wrong answers on judgment tasks costs correction
+cycles, which erases the saving.
+
+**Interaction with caching.** The prompt cache is keyed by `(model, prefix)`, so
+switching a call to a cheaper model is a cache **miss**. Weigh the downgrade
+saving against the lost cache-read saving before routing a cached call to a
+different model.
+
+## 4. Effort and output right-sizing
+
+- `output_config.effort` (low through max) controls thinking and output depth,
+  and therefore spend. Dial effort **down** on routine turns; reserve high / max
+  for hard reasoning.
+- Right-size `max_tokens` — do not leave a huge ceiling. An unrealistically
+  large `max_tokens` does not cost tokens by itself, but it risks runaway output
+  and defeats pre-flight budgeting.
+
+## When to reach for which
+
+| Situation | Lever |
+|---|---|
+| Same large context reused across many calls | Prompt caching |
+| Thousands of independent, non-urgent jobs | Batch API (+ caching) |
+| Turn is mechanical / narrow / well-specified | Cheaper model tier |
+| Turn is routine and does not need deep thinking | Lower `effort` |
+| Output could balloon unnecessarily | Cap `max_tokens` |
+| Interactive latency matters | Caching + tiering; not Batch |
+
+## Claude Code note
+
+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`](../../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/dist/agent-src/guidelines/agent-infra/artifact-drafting-protocol-mechanics.md

@@ -0,0 +1,222 @@
+# Artifact Drafting Protocol — Mechanics
+
+> Phase A/B/C detail and the roadmap batch-mode carve-out for the `artifact-drafting-protocol` rule
+
+_Origin: migrated from `src/rules/artifact-drafting-protocol.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, the trigger surface, and the golden rules stay in the rule; this file carries the per-phase procedure._
+
+## Phase A — Understand
+
+**Question zero, asked first: should this artifact exist at all?**
+
+Before the five below, put the extend-versus-create question to the user —
+*is there an existing artifact this belongs in?* It used to live in Phase B,
+after the research, and it was measured moving: one source found that the same
+stop placed after work had begun was passed straight through, because mid-build
+momentum beats restraint. A stop that only fires once you are invested is a stop
+that does not fire.
+
+Asking it first costs one question and is answerable without the research: the
+user usually knows whether they are extending something. Phase B still runs the
+overlap scan — that is what turns a guess into a verdict — but it now *confirms
+or overturns* an answer already on the record rather than raising the question
+for the first time at the point where a draft is half-formed.
+
+Ask up to **5** further clarifying questions (numbered options, each with a
+*"skip / I don't know yet"* escape):
+
+1. **Problem** — what does this solve that no existing artifact solves?
+2. **Trigger surface** — which user phrasings should fire this?
+3. **Should-trigger examples** — 2-3 in the user's words.
+4. **Near-miss cases** — 2-3 phrasings that must **not** fire.
+5. **Artifact type** — skill, rule, command, or guideline? Offer a
+   3-line primer if unsure.
+
+If the user skips Q1 or Q5, stop and surface the ambiguity — don't guess.
+
+## Phase B — Research
+
+Run the **search protocol** from
+[`learning-to-rule-or-skill` § 4](../../skills/learning-to-rule-or-skill/SKILL.md)
+— `ls` all four surfaces (`skills/`, `rules/`, `guidelines/`, `commands/`),
+grep with **solution-words AND problem-words**, scan sub-directory
+taxonomies, then **open and skim** the 3 nearest matches. A negative grep
+alone is not proof of no overlap. Report the top 3-5 most-similar
+artifacts and ask (numbered options) — this **confirms or overturns** the
+question-zero answer from Phase A with evidence, rather than raising it for the
+first time:
+
+- Extend an existing one?
+- Create a new one — gap is real?
+- Show overlap first?
+- Promote via `learning-to-rule-or-skill` instead?
+
+A Phase-B verdict that contradicts the Phase-A answer is the useful outcome, not
+an embarrassment: it is the research doing its job. Surface the contradiction
+and let the user re-decide.
+
+Carry the summary into the commit message (*"Reviewed before drafting:
+X, Y"*).
+
+### Where the answer is written — `composition_review:`
+
+A commit message is not a tree artifact. Measured 2026-08-27 over the twenty most
+recently added skills and rules
+(`agents/evidence/analysis/authoring-search-record-sample-2026-08-27.md`), **1 of
+20** carried a machine-readable record of the Phase-B verdict; 9 carried a strict
+prose one, and the rest carried a `See also` gloss or a routing row. So an
+artifact authored after a thorough scan and one authored after none were
+indiscernible in the tree — which is why the overlap tools
+(`audit_overlap`, `audit_skill_overlap`, `report_layer_overlap`) run over a
+corpus rather than over a decision.
+
+The record is a frontmatter block, defined in `skill.schema.json` and
+`rule.schema.json`, and **optional on existing artifacts by design — nothing is
+backfilled**:
+
+```yaml
+composition_review:
+  - candidate: skill:existing-ui-audit      # skill: / rule: / command: / guideline: / none
+    disposition: create_separate            # what happened to this candidate
+    rationale: audits what exists before a write; this governs the write itself
+```
+
+Four dispositions, and the discriminator for each:
+
+| Value | Means |
+|---|---|
+| `extend_incumbent` | the incumbent absorbed the change; no new artifact was created |
+| `compose_with_incumbent` | the new artifact routes to the incumbent rather than restating it |
+| `create_separate` | the incumbent exists, was evaluated, and a separate artifact was authored anyway |
+| `none_found` | the search ran and found no credible incumbent — pairs only with `candidate: none` |
+
+`none_found` exists so an author is never pushed to **invent** an incumbent to
+satisfy the schema. That failure would manufacture the pro-forma record the
+mechanism is supposed to measure, using the mechanism.
+
+`create_separate` is the value no other disposition vocabulary in this tree can
+express, and it is why this is a fifth enum rather than a reuse. The nearest
+incumbent is the harvest ledger's `adopt | adapt`
+(`lint_harvest_provenance.ts:76`), which deliberately **excludes** rejection
+(`:222`) because a rejected harvest has no artifact to cite. This record is the
+mirror image — it is written *on* the artifact being created — so rejection is
+the value it most needs. The finding, review and archive vocabularies are about
+defects, review rows and roadmap files respectively; none of them has a slot for
+"an incumbent existed and I built anyway".
+
+**What the lint does and does not do.** `lint_composition_review` fails a record
+whose `candidate` resolves to no artifact, or whose `none` / `none_found` pair
+disagrees — a record naming an incumbent that is not in the tree reads as
+evidence of a search that cannot have happened. It *reports without failing* an
+addition carrying no record at all. It cannot check that the search happened,
+that the rationale is true, or that the named incumbent is the nearest one;
+flipping the advisory half to a block needs a false-positive rate from at least
+one release of advisory operation, which does not exist yet.
+
+## Phase C — Draft
+
+Propose **2-3 description variants** — Conservative / Pushy
+(per `skill-quality`) / Concrete (embedded trigger example). User picks
+or merges. Only then draft the body. Surface every structural choice
+(size class, section order) as numbered options if in doubt.
+
+Enforce size live: *"Body is at 420/500 lines. Split?"* (budgets per
+`size-enforcement`). New skills also get an `evals/triggers.json` stub
+(5 should-trigger + 5 should-not-trigger). See `skill-writing` § 1c.
+
+## Roadmap-run batch mode — the ONE structured bypass
+
+When a `/roadmap:process-*` run starts under an **accepted execution
+contract** (`roadmap-execution-contract`) whose pre-scan detected
+artifact-authoring steps, the protocol runs in batch mode for exactly
+those artifacts:
+
+- **Phase B (Research) runs ONCE at contract time, against the CURRENT
+  artifact state** — one overlap scan covering every artifact the
+  roadmap plans; results (nearest matches, extend-vs-create verdicts)
+  are surfaced inside the contract summary the user accepts. This is
+  why authoring-time-only checking is not enough: a sibling roadmap may
+  have landed overlapping artifacts between authoring and execution.
+- **Phases A (Understand) and C (Draft) run non-interactively during
+  the run** — the roadmap step text is the Understand input; the
+  contract acceptance is the approval that the per-phase prompts exist
+  to obtain.
+- **Scope is the batch, nothing more.** An artifact NOT declared in the
+  roadmap (discovered mid-run) triggers the full interactive protocol —
+  or, under the contract, the scope-out-of-roadmap halt. That halt is the
+  **default** and stays the default; see § Late artifacts below for the one
+  declared value that changes it.
+- Batch mode never skips the Research pass itself — it relocates and
+  batches it. `artifact_protocol: skip` does not exist.
+
+### Late artifacts — `halt` by default, `auto-research` only when declared
+
+The bullet above is the whole rule when the contract says nothing. A contract
+may instead declare `late_artifacts: auto-research`
+([`roadmap-execution-contract § 2a`](../../contexts/execution/roadmap-execution-contract.md)),
+and then a mid-run discovery runs **this** procedure rather than halting:
+
+1. **Re-run Phase B against current state** — the same overlap scan the batch
+   ran at contract time, now over the artifact the run just found. Nothing new
+   is invented: this is the accepted-as-non-interactive procedure, later.
+2. **Extend verdict → extend silently.** The nearest match is edited. This is
+   the outcome the overlap scan exists to produce and it needs no approval it
+   did not already have.
+3. **Create verdict → derive Phase A from what is already on the record.** The
+   understand-answers come from the roadmap step text plus the decision-sheet
+   answers the user accepted. No new question is opened.
+4. **Genuine overlap conflict → halt.** Two plausible extend targets, or a
+   match whose scope contradicts the step, is a real decision and stops the
+   run.
+5. **Cap: three per run, then halt regardless of verdict.**
+
+`halt` remains the shipped default (`decision 2026-08-20`, AI council 2/2 on
+the `autonomy-defaults-sheet` fork; record
+`agents/evidence/council/drain-blocker-dispositions-a.md`). The reasoning is
+short: the cap bounds how far an unplanned artifact can drift the run, but it
+does not decide whether the drift is wanted, and the conservative side of that
+fork is the behaviour the tree already had. Making `auto-research` a declared
+value rather than an inherited one is also what makes its own kill criterion —
+the late-artifact revisit rate — attributable to the runs that chose it.
+Reverting is one word in each of the two tables; no mechanism depends on the
+default's direction.
+
+**Kill criterion for `auto-research`, at the site rather than in a roadmap:**
+a late-artifact revisit rate above 20 % — an auto-authored or auto-extended
+artifact later reworked or reverted — removes the value and returns every
+late discovery to `halt`. **No instrument today:** nothing counts late
+artifacts or their revisits, so the rate is unmeasured rather than low, and
+the cap of three is the only live bound. Recorded here because a criterion
+that lives only in the roadmap that flipped the default becomes unreachable
+the moment that roadmap is archived.
+
+
+## Complexity budget — the six questions before a new artifact
+
+Folded here from the 9.4.0 review (Prio 5), which named the failure mode:
+"das Paket kann fast jede Kritik mit einem weiteren Mechanismus beantworten"
+(Problem → Regel → Lint → Hook → Report → Roadmap → Claim → Test = governance
+inflation). This REPLACES the ad-hoc "should this exist" prose — it is a
+checklist, not a new gate/rule (adding a gate to enforce "add less" would be
+the very inflation it guards against). Before drafting any new skill / rule /
+command / hook / gate, answer all six; a "no" on **replaces** or **removable**
+is a strong signal to fold into an existing artifact instead:
+
+1. **Replaces?** — what existing mechanism does this retire or subsume? (If
+   nothing, justify why the surface must grow.)
+2. **Overlaps?** — does it duplicate a trigger / responsibility another
+   artifact already owns?
+3. **Discoverable?** — will a user actually find it, or does it just raise the
+   catalog count?
+4. **Measurable?** — is there a signal that would show it earning its place
+   (or a null that would retire it)?
+5. **Removable?** — can it be demoted / de-eligibled / deleted later without a
+   migration?
+6. **Who debugs it?** — is the maintenance owner real, given bus-factor?
+
+The load-bearing question the review elevates: not "how do we prevent this
+error in future?" but **"which existing mechanism gets removed or replaced?"**
+
+## See also
+
+- `artifact-drafting-protocol` (rule) — Iron Law, triggers, golden rules.
+- `ask-when-uncertain` · `improve-before-implement` · `user-interaction` · `skill-quality` — the protocol extends these; cross-link, don't restate.

package/dist/agent-src/guidelines/agent-infra/ask-when-uncertain-demos.md

@@ -0,0 +1,134 @@
+---
+demo_for: ask-when-uncertain
+layer: pattern-memory
+prose_delta:
+  rule_chars_before: 3893
+  rule_chars_after: 4267
+  measured_at: phase-3.3-cross-link-landing
+  note: "+374 chars from the Examples cross-link block; future prose-pruning rounds (out of scope for Phase 3) will pull pattern prose from the rule into this demo and drive the after-count below the before-count."
+---
+
+# ask-when-uncertain — Pattern Memory
+
+> Wrong / right / why demos for the `ask-when-uncertain` Iron Law
+> (one question per turn, vague-request must ask). Linked from
+> [`ask-when-uncertain`](../../rules/ask-when-uncertain.md)
+> § Examples. Outcome baseline at
+> [`tests/golden/outcomes/ask_when_uncertain.json`](../../../tests/golden/outcomes/ask_when_uncertain.json).
+
+## Demo 1 — Vague request, multi-question stack
+
+### Wrong shape
+
+```
+User: improve this
+
+Agent:
+1. Should I optimize for readability or speed?
+2. Refactor the function signature?
+3. Add tests too?
+4. Run PHPStan after?
+
+Reply with a, b, c, d so I can pick.
+```
+
+**Failure mode:** four `?` aimed at the user, structured-answer
+demand (`a, b, c, d`), no triage. Iron Law breach: a turn with a
+question has *exactly one*. Compound thinking load — answer to Q1
+reframes Q2.
+
+### Right shape
+
+```
+User: improve this
+
+Agent: Welche Achse soll "improve" treffen?
+
+1. Lesbarkeit (Naming, Funktions-Splits)
+2. Performance (Allokationen, N+1)
+3. Robustheit (Error-Handling, Edge Cases)
+
+Dann lege ich los.
+```
+
+### Why it works
+
+Single `?`, numbered options without compound asks, picks the
+question whose answer reframes everything downstream. The follow-up
+("tests? PHPStan?") rides on the next turn — its framing depends on
+the answer here.
+
+## Demo 2 — Drive-by execution on a vague trigger
+
+### Wrong shape
+
+```
+User: clean up this file
+
+Agent: [edits 12 files, removes 200 lines, reformats imports,
+extracts 3 helpers, renames 5 variables]
+Done.
+```
+
+**Failure mode:** "clean up" is a vague-request trigger
+(`ask-when-uncertain` § Vague-request triggers). MUST-ask before
+touching code. Without scope, the diff is a guess at the user's
+intent.
+
+### Right shape
+
+```
+User: clean up this file
+
+Agent: Was bedeutet "clean up" hier?
+
+1. Toten Code raus
+2. Format / Imports sortieren
+3. Refactor (Funktionen splitten)
+
+Pick one — sonst ist der Diff Raten.
+```
+
+### Why it works
+
+Names the trigger explicitly ("vague-request"), surfaces the three
+canonical interpretations from the rule's trigger table, and
+declines to act without scope. The cost of asking once << cost of
+ripping through 12 files in the wrong direction.
+
+## Demo 3 — Stacked questions inside a handoff
+
+### Wrong shape
+
+```
+Agent: Bevor ich die Roadmap übergebe:
+
+- Welcher Branch?
+- Soll ich PRs erwähnen?
+- Welches Modell für die Fortsetzung?
+- Soll ich agents/runtime/.agent-chat-history zitieren?
+
+Antworte als 1, 2, 3, 4.
+```
+
+**Failure mode:** four-question handoff block. Per § Ordering &
+handoff: handoff questions ride LAST, after domain clarifications,
+folded into the handoff prompt itself — not as a parallel quiz.
+
+### Right shape
+
+```
+Agent: [delivers the handoff prompt with sensible defaults filled
+in: current branch, PR link present if open, model
+recommendation per `model-recommendation`, history reference
+auto-included]
+
+Welche der vier Defaults soll ich vor dem Übergeben anpassen?
+```
+
+### Why it works
+
+Defaults absorb three of the four "questions"; the remaining
+question is the only one that genuinely needs user input — and it's
+phrased so a one-word answer ("PR link" / "model" / "passt") closes
+the loop.