@event4u/agent-config 8.13.0 → 9.1.0

package/dist/agent-src/skills/security-maturity-assessment/evals/triggers.json

@@ -0,0 +1,52 @@
+{
+    "skill": "security-maturity-assessment",
+    "last_eval": "2026-07-12",
+    "description": "5 should-trigger + 5 should-not-trigger queries. Should-trigger covers DE + EN posture/scorecard/baseline phrasings. Should-not-trigger covers the neighbouring security skills (vuln hunt, authz chain, threat model, secure coding, agent config) whose vocabulary overlaps.",
+    "queries": [
+        {
+            "q": "how mature is the security posture of our billing module?",
+            "trigger": true
+        },
+        {
+            "q": "give me a security scorecard for this codebase with evidence per category",
+            "trigger": true
+        },
+        {
+            "q": "wie sicher ist dieses Modul aufgestellt? Bitte pro Kategorie bewerten",
+            "trigger": true
+        },
+        {
+            "q": "baseline our security maturity before the hardening sprint",
+            "trigger": true
+        },
+        {
+            "q": "rate input validation, secrets and tenant isolation for the API package",
+            "trigger": true
+        },
+        {
+            "q": "audit this module for SQL injection and XSS vulnerabilities",
+            "trigger": false,
+            "note": "vulnerability hunt → security-audit"
+        },
+        {
+            "q": "review the authorization chain for the invoice download route",
+            "trigger": false,
+            "note": "single-route authz → authz-review"
+        },
+        {
+            "q": "threat-model the new file-upload feature before we build it",
+            "trigger": false,
+            "note": "pre-implementation → threat-modeling"
+        },
+        {
+            "q": "write a policy and gate for this new admin action",
+            "trigger": false,
+            "note": "writing secure code → security"
+        },
+        {
+            "q": "red-team my Claude agent's MCP and hook config",
+            "trigger": false,
+            "note": "agent config/behaviour → agent-security-review"
+        }
+    ]
+}

package/dist/agent-src/skills/skill-writing/SKILL.md

@@ -451,12 +451,91 @@ to every skill you author.
 4. Does the description carry filler ("comprehensive", "advanced",
    "powerful")?
 
+## Read-only-by-default scripts
+
+A script shipped inside a skill (`scripts/**`) is **side-effect-free by
+default** — inspects, computes, prints; does not mutate. Mutation (write /
+delete / rename / copy) gates behind an explicit flag named in this SKILL.md —
+`--writable` / `--apply` / `--write` / `--output` / `--fix` — so the default
+invocation is safe. A generator whose *declared purpose* is to write (emits an
+artifact to a caller-supplied path) is allowlisted with a rationale in
+`src/scripts/lint_skill_scripts_readonly_allowlist.json` instead of a redundant
+flag. `lint_skill_scripts_readonly` enforces this: an ungated, non-allowlisted
+write fails the build.
+
+## Description-optimizer loop (U1 — held-out, not vibes)
+
+Descriptions are the trigger surface; tune them like a model, not like prose:
+
+1. Draft 2-3 candidate descriptions for the skill.
+2. Ensure `evals/triggers.json` has should- AND should-not-trigger queries
+   (grow beyond the 5+5 stub when optimizing — more queries = a real test split).
+3. Run the helper: `npx tsx src/scripts/optimize_skill_description.ts
+   --skill <id> --candidate "…" [--candidate "…"] [--live]` — it splits the
+   queries deterministically into train/held-out, scores every candidate
+   (deterministic token-overlap proxy by default; `--live` = haiku judge,
+   ~$0.001 per query·candidate), and picks the best **held-out** accuracy.
+4. Adopt the pick ONLY if it beats the current description on the held-out
+   split — a train-only win is overfitting to the queries you wrote.
+
+## Self-QA loop for output-producing skills (optional pattern)
+
+For skills whose product is a rendered/structural artifact (decks, docs,
+diagrams, dashboards, generated UI): **assume there are problems** and have a
+fresh-eyes pass find them before handing back. The author-context is blind to
+its own omissions; a context-free verifier is not.
+
+1. Produce the artifact.
+2. Dispatch a fresh subagent (no authoring context) with ONLY the artifact +
+   the acceptance criteria: "list every visual/structural defect; assume at
+   least one exists."
+3. Fix what it finds; re-run once. Two clean passes → done.
+
+Worked example (deck skill): the author renders 12 slides; the fresh-eyes
+pass gets the PDF + "check overflow, contrast, orphaned bullets, broken
+images" — it flags a clipped title on slide 7 the author never re-read.
+One fix, one re-check, done.
+
+Scope: complements `verify-before-complete` (which gates the completion
+claim); this pattern is HOW to get the fresh evidence for artifacts where no
+deterministic checker exists. Skip it when a real validator covers the
+surface (linter, schema, test) — deterministic checks beat judge passes.
+
+## Known-pitfalls section (optional pattern, tool skills)
+
+Tool/integration skills teach the happy path; the recurring support burden is
+the *silent* failures — the ones that cost money, corrupt state, or fail with no
+error. For a high-support-burden tool skill, add a `## Known pitfalls` section
+in this micro-format:
+
+1. **A Symptom → Root cause → Fix table.** Each row starts from the *observable
+   symptom* (what the user sees), not the internal cause — the user greps for
+   the symptom, not the fix.
+
+   | Symptom | Root cause | Fix |
+   |---|---|---|
+   | `<what the user observes>` | `<why it happens>` | `<the concrete action>` |
+
+2. **Optionally, a quick-reference anti-pattern checklist** (Anti-pattern ·
+   cost/impact · fix difficulty) for traps worth scanning before shipping — add
+   it only when it does not restate the skill's existing `## Gotcha` / `## Do
+   NOT`; the table is the load-bearing part.
+
+Sourcing floor — **real, not invented**: every entry names a genuinely common
+failure (a high-vote community question, a documented incident class), never a
+hypothetical. **≤ 5 entries per skill.** The value is a short, sourced,
+high-signal list; a long one is noise. A pitfall is a *section on the existing
+tool skill*, **never** a new skill per pitfall and never a generated grid (see
+[`size-enforcement`](../../rules/size-enforcement.md) § Per-tool pitfall
+content).
+
 ## Do NOT
 
 * Write documentation-style, pointer-only, or too-broad skills ("Laravel skill")
 * Skip Procedure or use vague validation
 * Exceed size limits (see `docs/guidelines/agent-infra/size-and-scope.md`)
 * Duplicate rules
+* Ship a skill script that mutates the filesystem on its default invocation — gate it behind a flag or allowlist it with a rationale
 
 ## Encode usage policy in the description
 

package/dist/agent-src/skills/spreadsheet-authoring/SKILL.md

@@ -41,9 +41,17 @@ prose document/table (that is the document surface, `doc-coauthoring`).
 2. **Formulas over hardcoded values.** Any computed cell holds a **formula**
    (`=SUM(...)`, `=B2*C2`), never the typed-in result. Hardcoding a computed
    value is the cardinal spreadsheet defect — it does not recalculate.
-3. **Read back after every write.** After writing a formula, read the cell back
-   and confirm no formula error (`#REF!`, `#DIV/0!`, `#VALUE!`). The read-back is
-   the spreadsheet's verification truth source.
+3. **Read back after every write, and RECALCULATE first.** After writing a
+   formula, force a recalculation, then read the cell back — a library that
+   writes formulas without recalculating leaves the cached value stale, so a
+   read-back before recalc proves nothing. The **zero-formula-error contract**:
+   any of `#REF!` / `#DIV/0!` / `#VALUE!` / `#N/A` / `#NAME?` in a written cell
+   is a **failure**, not a warning — reject the output and fix the formula. The
+   recalc'd read-back is the spreadsheet's verification truth source.
+   **Formulas, never hardcoded computed values** — a library that writes the
+   Python-computed number into the cell instead of the `=` formula has produced
+   a dead spreadsheet that will not update when inputs change; write the formula
+   string and let the recalc compute it.
 4. **Source-comment web-sourced cells.** Any figure taken from the web carries a
    cell comment with its source. Financial figures follow the
    [`spreadsheet-source-quality`](../../rules/spreadsheet-source-quality.md) rule

package/dist/agent-src/skills/subagent-orchestration/prompts/README.md

@@ -33,6 +33,17 @@ hits (Anthropic `cache_control: ephemeral`) across the cohort — the prefix is
 cached after the first sibling and served from cache for the rest, cutting
 input-token cost proportionally to cohort size.
 
+**Break-even + failure modes.** A cache write costs ~1.25× the base input rate
+(5-min TTL); a read costs ~0.1×. So the prefix pays off once **≥ 2** siblings
+read it — a lone subagent with no sibling reuse only pays the write premium and
+saves nothing. The cache is a **byte-exact prefix match**: any drift in the
+shared prefix (a timestamp, a per-sibling id, reordered text) forces a re-write
+instead of a read, and the prefix must be re-hit within the **5-minute TTL**, so
+dispatch siblings promptly rather than trickling them. This is why the win is
+real for **fan-out** (many siblings, one prefix) and marginal for one-shot
+dispatch. Verify a cohort is actually reading, not re-writing, by checking
+`usage.cache_read_input_tokens > 0` on the 2nd+ sibling.
+
 ## Loading
 
 `tests/test_subagent_prompt_loading.py` asserts that every mode named

package/dist/agent-src/skills/subagent-orchestration/schemas/team-review-status.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://event4u.dev/agent-config/schemas/team-review-status.json",
+  "title": "Team Review Status Envelope",
+  "description": "Wire format for every /team:review return — plugin path and multi-host fallback alike. Extends the subagent-status.json frame (same status enum, same NEEDS_CONTEXT/BLOCKED semantics) with review findings, the reviewed ref, and quota visibility. Emitted by src/scripts/ai_team/team_dispatch.ts; contract prose in docs/contracts/ai-team-config.md.",
+  "type": "object",
+  "required": ["status", "findings", "reviewed_ref", "model", "quota"],
+  "additionalProperties": false,
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
+      "description": "DONE = review ran, no findings above info. DONE_WITH_CONCERNS = review ran and findings[] needs the caller's attention, OR the model output was unparseable (raw carries the verbatim text — never silently dropped). NEEDS_CONTEXT = reviewer lacks context beyond the bundle; blocking_question must be answered. BLOCKED = no review was produced (auth, quota, transport); blocking_reason describes why."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One- or two-sentence review outcome."
+    },
+    "findings": {
+      "type": "array",
+      "description": "Review findings. Empty for a clean DONE and for BLOCKED (no review happened).",
+      "items": {
+        "type": "object",
+        "required": ["severity", "evidence", "suggested_fix"],
+        "additionalProperties": false,
+        "properties": {
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "major", "minor", "info"],
+            "description": "critical = data loss / security / correctness on the main path. major = real defect, wrong under realistic input. minor = defect on an edge path or maintainability trap. info = observation, no action required."
+          },
+          "evidence": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What is wrong, citing the exact hunk/line from the reviewed diff — never invented code."
+          },
+          "suggested_fix": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Concrete, minimal fix proposal."
+          },
+          "location": {
+            "type": "string",
+            "description": "file[:line] when known."
+          }
+        }
+      }
+    },
+    "reviewed_ref": {
+      "type": "string",
+      "minLength": 1,
+      "description": "HEAD sha the repo-context bundle was built from — pins what was actually reviewed."
+    },
+    "model": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Reviewer model id, or the literal 'auto' when the codex CLI default was used (no --model flag passed)."
+    },
+    "quota": {
+      "type": "object",
+      "required": ["used", "ceiling"],
+      "additionalProperties": false,
+      "description": "Shared cli_call_budget openai-bucket visibility after this run.",
+      "properties": {
+        "used": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Today's openai-bucket call count (UTC-day, shared with the council)."
+        },
+        "ceiling": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "ai_team.max_calls_per_day — the team-side ceiling on the shared bucket."
+        }
+      }
+    },
+    "raw": {
+      "type": "string",
+      "description": "Verbatim model output, present ONLY when the findings contract could not be parsed (status is then DONE_WITH_CONCERNS). Preserved so a malformed review is loud, never dropped."
+    },
+    "blocking_question": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Single specific question whose answer would unblock. Required when status = NEEDS_CONTEXT."
+    },
+    "blocking_reason": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Why no review was produced (auth_expired → codex login, cli_quota_exhausted, transport error). Required when status = BLOCKED."
+    }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"status": {"const": "NEEDS_CONTEXT"}}, "required": ["status"]},
+      "then": {"required": ["blocking_question"]}
+    },
+    {
+      "if": {"properties": {"status": {"const": "BLOCKED"}}, "required": ["status"]},
+      "then": {"required": ["blocking_reason"]}
+    }
+  ]
+}

package/dist/agent-src/skills/terraform/SKILL.md

@@ -128,6 +128,16 @@ Each env has a GitHub IAM role with:
 - resources
 - state management
 
+## Known pitfalls
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| `Error acquiring the state lock` blocks every command | A prior `apply` crashed / was killed and left the lock held (DynamoDB / backend lock) | Confirm no apply is actually running, then `terraform force-unlock <lock-id>` — never delete the lock table |
+| `plan` wants to destroy+recreate a resource after a rename | Renaming a resource block changes its address; Terraform sees the old address gone and a new one added | `terraform state mv <old.addr> <new.addr>` (or a `moved {}` block) so it tracks the same object |
+| `count`/`for_each` errors with "value depends on resource attributes that cannot be determined until apply" | The count/for_each expression reads an unknown (not-yet-created) value | Key `for_each` off a static/known map, or split into a two-stage apply with `-target` |
+| A change applies but the next `plan` shows the same diff again (perpetual diff) | The provider normalizes/computes the attribute differently than written (ordering, defaults, case) | Match the provider's canonical form, or `ignore_changes` on that attribute in `lifecycle` |
+| `plan` shows a resource as tainted/replaced after a manual console change | Out-of-band drift — someone edited the resource outside Terraform | `terraform apply -refresh-only` to reconcile state, then decide code-vs-cloud; stop the manual edits |
+
 ## Gotcha
 
 - `terraform apply` without `-auto-approve` requires interactive confirmation — don't use in CI without the flag.

package/dist/agent-src/skills/test-driven-development/SKILL.md

@@ -83,6 +83,37 @@ talked-around. Externalized to
 [`testing-anti-patterns/process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md)
 to keep this skill under the 400-line sunset trigger.
 
+## Mode contracts — Goal / Activities / Forbidden / Output
+
+The flow runs as four modes. Each Forbidden item names **how a reviewer
+checks it from the diff** — an unverifiable prohibition does not ship.
+
+| Mode | Goal | Activities | Forbidden (diff check) | Output contract |
+|---|---|---|---|---|
+| **Design** | One-sentence behavior + enumerated cases | Steps 1–2 | **No production code** (diff touches no `src/**` production path) · no test bodies yet | Case list (happy/boundary/error) |
+| **Test-Red** | A failing test that fails RIGHT | Steps 3–4 | **No production edits** (diff = `tests/**` only) · test must fail at an **assertion, not an import/setup error** (failure output cites the assertion line) | Failing test + its observed failure reason |
+| **Implement** | Minimum code to green | Steps 5–6 | **No test edits** (no `tests/**` paths in Implement-phase diffs — changing the assertion to fit the code is the canonical violation; genuinely-wrong test → STOP and ask, never silently edit) · no scope beyond the one case | Green run output |
+| **Debug** | Fix a defect found later | (re-enter at 3) | **No bugfix before a reproducing regression test exists** (the fix commit contains a `tests/**` addition that fails without the fix) | Regression test + fix, verified red→green |
+
+### Mode inference on resume
+
+Step 0 of any resume: if `agents/runtime/state/HANDOFF.md` exists, resume
+from its Mode + Contract-owed fields (see `/agent-handoff` file mode) instead
+of re-deriving. Otherwise infer the mode from observable state — never
+assume Design:
+
+| Observed state | Resume in |
+|---|---|
+| No test for the target behavior | Design |
+| Test exists, currently failing at an assertion | Implement |
+| Test exists + passing, defect reported | Debug |
+| Test failing at import/collection error | Test-Red (fix the test, not the code) |
+
+At every mode transition, one consent-checkpoint sentence (per
+`ask-when-uncertain` / `autonomous-execution` — no new mechanism): name the
+mode you are leaving, the output contract you hand over, and the mode you
+enter; under an autonomous mandate the sentence is stated, not asked.
+
 ## Procedure
 
 ### 1. Identify the behavior to test

package/dist/agent-src/skills/threat-modeling/SKILL.md

@@ -93,6 +93,21 @@ For every distinct abuse case, answer:
 Prioritize by **impact × plausibility**, not by novelty. Skip generic
 OWASP bullets unless you can anchor them in a concrete file or line.
 
+### 3b. STRIDE coverage check
+
+Sweep the six STRIDE categories once against the change so no threat class is silently skipped. Each row names the question + control family the suite already teaches — anchor any hit in a concrete file per § 3.
+
+| STRIDE category | Ask about this change | Control family (suite reference) |
+|---|---|---|
+| **S**poofing | Can an actor claim another identity on this path? | Authentication at the boundary; token/session verification — [`security`](../security/SKILL.md) |
+| **T**ampering | Can the payload or stored state be modified in transit or at rest? | Request-boundary validation + signed webhooks + parameterized queries — [`laravel-validation`](../laravel-validation/SKILL.md) / [`sql-writing`](../sql-writing/SKILL.md) |
+| **R**epudiation | Could the actor later deny having performed the action? | Audit logging of security events (actor + outcome, no credentials) — [`logging-monitoring`](../logging-monitoring/SKILL.md) |
+| **I**nformation disclosure | What leaks if this path errors, over-serializes, or logs? | Field whitelisting + scrubbed errors/logs — [`domain-safety-pii`](../../rules/domain-safety-pii.md) |
+| **D**enial of service | Can this path be made expensive or unbounded by an attacker? | Rate limiting + bounded queries/uploads — [`security-audit`](../security-audit/SKILL.md) § rate limiting, [`performance`](../performance/SKILL.md) |
+| **E**levation of privilege | Can a lower-privilege actor reach a higher-privilege action or object? | Per-object authorization + tenant scope — [`authz-review`](../authz-review/SKILL.md), [`broken-access-control`](../../rules/broken-access-control.md) |
+
+Category with no plausible abuse case for this change → mark "n/a — no boundary crossed", never silently omit.
+
 ### 4. Convert risks to engineering actions
 
 For each prioritized abuse case, propose the **smallest effective control**

package/dist/agent-src/skills/token-optimizer/SKILL.md

@@ -64,10 +64,15 @@ INTENT
 │     → cite [agent-handoff](../../../.claude/skills/agent-handoff/SKILL.md)
 │       (structured handoff envelope; resume in fresh chat)
 │
-└── Cost-aware decision (model pick, budget, stop-criterion)
-      → cite /cost:report (when shipped) — until then, fall back to
-        [token-efficiency](../../rules/token-efficiency.md) and
-        [direct-answers § Brevity by Default](../../rules/direct-answers.md)
+├── Cost-aware decision (model pick, budget, stop-criterion)
+│     → cite /cost:report (when shipped) — until then, fall back to
+│       [token-efficiency](../../rules/token-efficiency.md) and
+│       [direct-answers § Brevity by Default](../../rules/direct-answers.md)
+│
+└── API-bill lever (stable prefix reused across calls · non-interactive
+    bulk cohort · model/effort pick against the paid Anthropic bill)
+      → cite [api-cost-levers](../../../docs/guidelines/agent-infra/api-cost-levers.md)
+        (prompt caching ~0.1x reads · Batch -50% · model tiering · effort)
 ```
 
 ## Catalog
@@ -81,6 +86,7 @@ INTENT
 | `direct-answers` | `.agent-src.uncondensed/rules/direct-answers.md` | `brevity`, `flattery`, `severity`, `tiered` | Iron-Law brevity floor (kernel) |
 | `markitdown` | upstream: github.com/microsoft/markitdown | `PDF`, `DOCX`, `HTML`, `convert` | Document → markdown converter (authoritative-link only) |
 | `/cost:report` | TBD — an internal roadmap (local-only) | `cost`, `model spend`, `budget` | Per-session cost telemetry (planned) |
+| `api-cost-levers` | `docs/guidelines/agent-infra/api-cost-levers.md` | `cache`, `caching`, `batch`, `tiering`, `effort` | Anthropic billing levers: prompt caching, Batch API, model tiering, effort/output right-sizing |
 
 ## Output format
 

package/dist/agent-src/templates/agent-settings.md

@@ -402,8 +402,31 @@ commands:
   # When `true`: show title and body in copyable code blocks and ask
   # for adjustments before creating the PR.
   # `/create-pr:description-only` always previews — that is its sole purpose.
+  #
+  # detail_level: verbosity tier of the PR Description body.
+  #   min (default) = title + 2-3 sentence what/why/impact + linked ticket;
+  #   med           = min + grouped changes + tests note;
+  #   max           = med + how-to-test + edge cases + reviewer guidance.
+  # Critical info (breaking changes, migrations, security, rollback) is
+  # ALWAYS included at every tier — the tier governs explanatory depth only.
+  #
+  # api_examples (default true): add a fenced JSON example for API-endpoint
+  #   changes ONLY when grounded in a real source (DTO/resource, OpenAPI,
+  #   fixture, probe); else a one-line pointer, never an invented example.
+  #
+  # screenshots (default false): capability-gated frontend screenshots.
+  #   true attempts capture only when the host has browser/preview tooling;
+  #   emits a note and leaves the placeholder when absent — never blocks the PR.
+  #
+  # ui_paths / api_paths: optional globs to make frontend / API detection
+  #   explicit; empty = a light heuristic that fails open.
   create_pr:
     preview_description: false
+    detail_level: min
+    api_examples: true
+    screenshots: false
+    ui_paths: []
+    api_paths: []
 
 # --- Telemetry (artefact engagement, default-off) ---
 #
@@ -582,6 +605,11 @@ the canonical narrative lives in
 | `commands.suggestion.max_options` | integer | `4` | Max number of command suggestions before the always-present "run as-is" option (total rendered = `max_options + 1`). |
 | `commands.suggestion.blocklist` | list of command names | `[]` | Commands that never appear as a suggestion. They still work when typed explicitly. |
 | `commands.create_pr.preview_description` | `true`, `false` | `false` | When `false`: `/create-pr` skips the title/body preview + adjust loop and uses the generated content directly. Saves agent tokens. When `true`: show title and body before creating and ask for adjustments. `/create-pr:description-only` always previews regardless of this setting. |
+| `commands.create_pr.detail_level` | `min`, `med`, `max` | `min` | Verbosity tier of the PR Description body. `min` = title + 2-3 sentence what/why/impact + ticket; `med` = + grouped changes + tests note; `max` = + how-to-test + edge cases + reviewer guidance. Critical info (breaking / migration / security / rollback) is included at every tier. |
+| `commands.create_pr.api_examples` | `true`, `false` | `true` | Add a grounded JSON example for API-endpoint changes; `true` includes one only from a real source (DTO/OpenAPI/fixture/probe), else a pointer, never invented; `false` = never. |
+| `commands.create_pr.screenshots` | `true`, `false` | `false` | Capability-gated frontend screenshots. `true` attempts capture when browser/preview tooling is present; notes-and-skips otherwise, never blocks the PR. Before/after is best-effort. |
+| `commands.create_pr.ui_paths` | glob list | `[]` | Optional globs pinning frontend detection; empty = light heuristic, fail-open. |
+| `commands.create_pr.api_paths` | glob list | `[]` | Optional globs pinning API-endpoint detection; empty = light heuristic, fail-open. |
 | `verbosity.preview_artifacts` | `true`, `false` | `false` | Show generated commit messages, PR titles/bodies, branch names before acting. `false` = use generated content directly. See the token-frugality plate under `agents/roadmaps/` (Phase 2/3). |
 | `verbosity.routine_confirmations` | `true`, `false` | `false` | Confirmation prompts for routine workflow steps when there is one obvious answer ("looks good — commit?"). Iron-Law gates (`commit-policy`, `scope-control` git-ops, `non-destructive-by-default`) ALWAYS ask regardless. |
 | `verbosity.offer_council_in_delivery` | `true`, `false` | `false` | Offer "run AI Council on this?" inside delivery commands (`/feature-plan`, `/review-changes`, `/roadmap-create`). Council commands themselves are unaffected. |

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "8.13.0"
+agent_config_version: "9.1.0"
 
 # --- Project identity ---
 project:

package/dist/agent-src/templates/scripts/telemetry/engagement.ts

@@ -15,6 +15,10 @@
  *       "boundary_kind": "task" | "phase-step" | "tool-call",
  *       "consulted": {"skills": [...], "rules": [...], ...},
  *       "applied":   {"skills": [...], "rules": [...], ...},
+ *       "loaded":    {"skills": [...], "rules": [...], ...}  # optional (U1a):
+ *              what was AVAILABLE/INJECTED at the boundary — the Fired/Loaded
+ *              denominator. Superset contract: consulted ⊆ loaded. Ids only
+ *              (same PII-exclusion-by-construction shape as consulted).
  *       "outcomes":  ["blocked", "verification_failed", ...]  # optional
  *       "tokens_estimate": {"consulted_load": <int>}   # optional
  *     }
@@ -127,6 +131,7 @@ export interface EngagementEventInit {
     boundary_kind: string;
     consulted?: Record<string, string[]>;
     applied?: Record<string, string[]>;
+    loaded?: Record<string, string[]> | null;
     outcomes?: string[] | null;
     tokens_estimate?: Record<string, number> | null;
     schema_version?: number;
@@ -138,6 +143,7 @@ export class EngagementEvent {
     boundary_kind: string;
     consulted: Record<string, string[]>;
     applied: Record<string, string[]>;
+    loaded: Record<string, string[]> | null;
     outcomes: string[] | null;
     tokens_estimate: Record<string, number> | null;
     schema_version: number;
@@ -148,6 +154,7 @@ export class EngagementEvent {
         this.boundary_kind = init.boundary_kind;
         this.consulted = init.consulted ?? {};
         this.applied = init.applied ?? {};
+        this.loaded = init.loaded ?? null;
         this.outcomes = init.outcomes ?? null;
         this.tokens_estimate = init.tokens_estimate ?? null;
         this.schema_version = init.schema_version ?? SCHEMA_VERSION;
@@ -171,6 +178,20 @@ export class EngagementEvent {
         }
         _validate_artefact_dict('consulted', this.consulted);
         _validate_artefact_dict('applied', this.applied);
+        if (this.loaded !== null) {
+            _validate_artefact_dict('loaded', this.loaded);
+            for (const [kind, ids] of Object.entries(this.consulted)) {
+                const avail = new Set(this.loaded[kind] ?? []);
+                for (const art_id of ids) {
+                    if (!avail.has(art_id)) {
+                        throw new EngagementSchemaError(
+                            `consulted.${kind} id '${art_id}' missing from loaded.${kind}; `
+                            + 'superset contract: consulted \u2286 loaded',
+                        );
+                    }
+                }
+            }
+        }
         if (this.outcomes !== null) {
             _validate_outcomes(this.outcomes);
         }
@@ -206,6 +227,12 @@ export class EngagementEvent {
             consulted: _normalise_artefact_dict(this.consulted),
             applied: _normalise_artefact_dict(this.applied),
         };
+        if (this.loaded !== null) {
+            const norm = _normalise_artefact_dict(this.loaded);
+            if (Object.keys(norm).length > 0) {
+                out['loaded'] = norm;
+            }
+        }
         if (this.outcomes && this.outcomes.length > 0) {
             out['outcomes'] = [...this.outcomes];
         }
@@ -310,6 +337,9 @@ export function parse_event(line: string): EngagementEvent {
         boundary_kind: (r['boundary_kind'] as string) ?? '',
         consulted: _orEmptyDict(r['consulted']),
         applied: _orEmptyDict(r['applied']),
+        loaded: r['loaded'] === undefined || r['loaded'] === null
+            ? null
+            : _orEmptyDict(r['loaded']),
         outcomes: (r['outcomes'] as string[] | null | undefined) ?? null,
         tokens_estimate: (r['tokens_estimate'] as Record<string, number> | null | undefined) ?? null,
         schema_version: r['schema_version'] === undefined

package/dist/agent-src/templates/scripts/telemetry/report_renderer.ts

@@ -121,15 +121,19 @@ export function render_markdown(aggregate: AggregateResult, opts: RenderOptions
             lines.push('');
             continue;
         }
-        lines.push('| kind | id | consulted | applied | applied/consulted | last seen |');
-        lines.push('|---|---|---:|---:|---:|---|');
+        const withLoaded = aggregate.loaded_events > 0;
+        lines.push(withLoaded
+            ? '| kind | id | loaded | consulted | applied | fired/loaded | applied/consulted | last seen |'
+            : '| kind | id | consulted | applied | applied/consulted | last seen |');
+        lines.push(withLoaded ? '|---|---|---:|---:|---:|---:|---:|---|' : '|---|---|---:|---:|---:|---|');
         for (const entry of rows) {
             const s = entry.stat;
             check_id_redaction(`buckets.${s.kind}.id`, s.artefact_id);
-            lines.push(
-                `| ${s.kind} | \`${s.artefact_id}\` | ${s.consulted} | ${s.applied} `
-                + `| ${_pyFixed(s.applied_ratio, 2)} | \`${s.last_seen_ts}\` |`,
-            );
+            lines.push(withLoaded
+                ? `| ${s.kind} | \`${s.artefact_id}\` | ${s.loaded} | ${s.consulted} | ${s.applied} `
+                    + `| ${_pyFixed(s.fired_ratio, 2)} | ${_pyFixed(s.applied_ratio, 2)} | \`${s.last_seen_ts}\` |`
+                : `| ${s.kind} | \`${s.artefact_id}\` | ${s.consulted} | ${s.applied} `
+                    + `| ${_pyFixed(s.applied_ratio, 2)} | \`${s.last_seen_ts}\` |`);
         }
         lines.push('');
     }
@@ -147,7 +151,9 @@ export function render_json(aggregate: AggregateResult, opts: RenderOptions = {}
         [BUCKET_BOTTOM]: [],
     };
     for (const entry of bucketed) {
-        (grouped[entry.bucket] as Array<Record<string, unknown>>).push(_stat_to_dict(entry.stat));
+        (grouped[entry.bucket] as Array<Record<string, unknown>>).push(
+            _stat_to_dict(entry.stat, aggregate.loaded_events > 0),
+        );
     }
     if (top !== null) {
         for (const bucket of Object.keys(grouped)) {
@@ -179,9 +185,9 @@ export function render_json(aggregate: AggregateResult, opts: RenderOptions = {}
     return `${_py_json_dumps_indent2_sorted(payload)}\n`;
 }
 
-function _stat_to_dict(stat: ArtefactStat): Record<string, unknown> {
+function _stat_to_dict(stat: ArtefactStat, withLoaded = false): Record<string, unknown> {
     check_id_redaction(`buckets.${stat.kind}.id`, stat.artefact_id);
-    return {
+    const out: Record<string, unknown> = {
         kind: stat.kind,
         id: stat.artefact_id,
         consulted: stat.consulted,
@@ -189,6 +195,13 @@ function _stat_to_dict(stat: ArtefactStat): Record<string, unknown> {
         applied_ratio: new PyFloat(_pyRound(stat.applied_ratio, 4)),
         last_seen_ts: stat.last_seen_ts,
     };
+    // U1a: emitted only when the log carries the loaded denominator, so
+    // pre-U1a logs render byte-identically to the frozen parity oracle.
+    if (withLoaded) {
+        out['loaded'] = stat.loaded;
+        out['fired_ratio'] = new PyFloat(_pyRound(stat.fired_ratio, 4));
+    }
+    return out;
 }
 
 // ── Python-parity helpers ───────────────────────────────────────────────

package/dist/agent-src/templates/scripts/telemetry_record.ts

@@ -63,6 +63,7 @@ interface RecordArgs {
     boundary: string;
     consulted: string[] | null;
     applied: string[] | null;
+    loaded: string[] | null;
     outcome: string[] | null;
     ts: string;
     payload_file: string | null;
@@ -78,6 +79,7 @@ function _build_event_from_args(args: RecordArgs): EngagementEvent {
         boundary_kind: args.boundary,
         consulted: _parse_kv_list(args.consulted ?? []),
         applied: _parse_kv_list(args.applied ?? []),
+        loaded: args.loaded && args.loaded.length > 0 ? _parse_kv_list(args.loaded) : null,
         outcomes: args.outcome && args.outcome.length > 0 ? [...args.outcome] : null,
     });
 }
@@ -101,6 +103,7 @@ function _build_event_from_payload(raw: string): EngagementEvent {
         boundary_kind: (d['boundary_kind'] as string) ?? '',
         consulted: _orEmpty(d['consulted']),
         applied: _orEmpty(d['applied']),
+        loaded: d['loaded'] === undefined || d['loaded'] === null ? null : _orEmpty(d['loaded']),
         outcomes: (d['outcomes'] as string[] | null | undefined) ?? null,
         tokens_estimate: (d['tokens_estimate'] as Record<string, number> | null | undefined) ?? null,
     });
@@ -121,6 +124,7 @@ function _parseArgs(argv: string[]): RecordArgs {
         boundary: 'task',
         consulted: null,
         applied: null,
+        loaded: null,
         outcome: null,
         ts: '',
         payload_file: null,
@@ -155,6 +159,7 @@ function _parseArgs(argv: string[]): RecordArgs {
             }
             a.boundary = v;
         } else if (tok === '--consulted') (a.consulted ??= []).push(next());
+        else if (tok === '--loaded') (a.loaded ??= []).push(next());
         else if (tok === '--applied') (a.applied ??= []).push(next());
         else if (tok === '--outcome') {
             const v = next();