@event4u/agent-config 1.16.0 → 1.17.0

package/docs/contracts/file-ownership-matrix.md

@@ -0,0 +1,134 @@
+---
+stability: beta
+---
+
+# File-ownership matrix
+
+> **Audience:** roadmap authors, phase reviewers, and CI gate writers
+> who need to know which artefact reads which, and whether two phases
+> can run concurrently without colliding.
+> **Generator:** `scripts/generate_ownership_matrix.py`
+> (run via `task generate-ownership-matrix`).
+> **Validator:** `task check-ownership-matrix` (fails if the JSON drifts
+> from a fresh regeneration).
+> **Companion contracts:** [`load-context-schema.md`](load-context-schema.md),
+> [`context-paths.md`](context-paths.md).
+
+This contract defines the **schema** of the file-ownership matrix: the
+machine-readable JSON at `docs/contracts/file-ownership-matrix.json` and
+the human-readable mirror at
+`agents/contexts/structural/file-ownership-matrix.md`. Both are
+regenerated from `.agent-src.uncompressed/` by the generator and locked
+by CI.
+
+**Status:** internal-locked (`stability: beta`). Schema bumps require a
+contract version increment plus a roadmap revision (per
+`road-to-structural-optimization.md` § 0.1).
+
+## Why the matrix exists
+
+`road-to-structural-optimization` Phase 0.1 (CRITICAL) is the DAG
+successor of Phase 0.6 (path conventions). Subsequent phases (1, 2A,
+2B, 3, 6) extract material into context files, slim rules, and reorder
+command surface. The matrix is the substrate that lets later phases
+ask three questions deterministically:
+
+1. **Which files does my edit reach transitively?** Answered by the
+   `READ_ONLY` edges plus their depth-2 closure.
+2. **Can Phase X and Phase Y land in either order?** Answered by
+   intersecting per-phase `WRITE` sets — empty intersection = safe.
+3. **Has the matrix drifted since the last green CI run?** Answered by
+   the `check-ownership-matrix` consistency gate.
+
+## Schema (v1)
+
+The JSON document is a single object:
+
+```json
+{
+  "version": 1,
+  "generated_by": "scripts/generate_ownership_matrix.py",
+  "source_of_truth": ".agent-src.uncompressed/",
+  "files": {
+    "<repo-root-relative path>": {
+      "kind": "rule | skill | command | context | persona",
+      "rule_type": "always | auto | manual | null",
+      "load_context": ["<path>", ...],
+      "load_context_eager": ["<path>", ...]
+    }
+  },
+  "edges": [
+    {
+      "source": "<path>",
+      "target": "<path>",
+      "type": "READ_ONLY | WRITE | BLOCKS_IF_CONCURRENT",
+      "via": "load_context | load_context_eager | load_context_transitive | body_link",
+      "depth": 1
+    }
+  ]
+}
+```
+
+**Edge types**
+
+| Type | Meaning | Populated in v1 |
+|---|---|:-:|
+| `READ_ONLY` | Source file reads target (frontmatter declaration or body markdown link). | ✅ |
+| `WRITE` | Source file owns target. Self-edge for every file (`source == target`). | ✅ |
+| `BLOCKS_IF_CONCURRENT` | Two phases would write the same file. Derived later from a phase manifest; reserved in v1. | ⏳ |
+
+**Edge `via` values**
+
+- `load_context` — frontmatter `load_context:` entry (lazy).
+- `load_context_eager` — frontmatter `load_context_eager:` entry.
+- `load_context_transitive` — depth-2 hop reached by following a target's own
+  `load_context*` declarations one level deeper.
+- `body_link` — markdown link in body to a path inside one of the
+  scanned roots.
+
+## Depth invariant (G2 — v3.1)
+
+The generator computes the transitive closure of `load_context` /
+`load_context_eager` edges **up to depth 2**. Any chain
+`R → A → B → C` where every hop is a `load_context*` edge **fails the
+build** with exit code 2. This duplicates the same nesting cap that
+Phase 0.2.4 will enforce in `scripts/check_always_budget.py` — two
+enforcement points, one invariant.
+
+## Regeneration policy
+
+| Trigger | What runs | What fails |
+|---|---|---|
+| `task generate-ownership-matrix` | Regenerates JSON + MD in place. | Depth-3 chain → exit 2. |
+| `task check-ownership-matrix` (CI) | Regenerates to memory, diffs against committed JSON. | Diff non-empty → exit 1. Depth-3 → exit 2. |
+| Pre-commit hook (Phase 2A — A1 fix) | Future: regenerate and diff on commits that touch contexts. | Same as `check-ownership-matrix`. |
+
+Any commit that adds, moves, or modifies a context, rule, skill, or
+command MUST regenerate the matrix in the same commit. CI is the
+backstop; the consistency gate fails if regeneration drifts.
+
+## Scope notes (v1)
+
+- **Greppable surface:** `rules/`, `skills/`, `commands/`, `contexts/`,
+  `personas/` under `.agent-src.uncompressed/`. Generated tool
+  projections (`.augment/`, `.claude/`, `.cursor/`, …) are intentionally
+  ignored — they are downstream of the source of truth.
+- **`skill:` frontmatter in rules** (named in roadmap 0.1.2) is reserved.
+  No rules currently declare it; the generator scans for it but emits
+  zero edges of that kind in v1.
+- **Body link parser** is conservative: it only recognises markdown
+  link targets ending in `.md` whose path resolves under one of the
+  scanned roots. Bare backtick-name references (e.g., `` `skill-quality` ``)
+  are **not** edges in v1; they are too ambiguous to attribute.
+- **Cycles** are not the matrix's concern — the existing
+  `lint_load_context.py` rejects them. The matrix generator follows
+  edges with a visited-set so a cycle, if one slipped through, cannot
+  loop forever; it would surface as a depth-3 abort.
+
+## Versioning
+
+`version: 1` is the initial lock. Schema-breaking changes (renaming a
+field, removing an edge type, changing semantics of an existing
+`via`) require a version bump and a roadmap revision. Additive changes
+(new `via` values, new optional file fields) MAY land at the current
+version with a `CHANGELOG.md` entry under `### Beta`.

package/docs/contracts/implement-ticket-flow.md

@@ -4,10 +4,9 @@ stability: beta
 
 # `/implement-ticket` — Flow Contract
 
-> Technical contracts for the delivery orchestrator shipped under
-> [`road-to-implement-ticket.md`](../../agents/roadmaps/road-to-implement-ticket.md).
-> This document is the stable reference; the roadmap tracks phased
-> delivery.
+> Technical contracts for the `/implement-ticket` delivery orchestrator.
+> This document is the stable reference for engine boundaries, state
+> schema, and replay protocol.
 >
 > - **Created:** 2026-04-22
 > - **Status:** Phase 1 shipped 2026-04-23 — `DeliveryState` +
@@ -133,9 +132,9 @@ against actual engine output rather than synthetic fixtures.
 Prompt envelopes (`input.kind="prompt"`) carry a free-form goal
 instead of a refined ticket. The `refine` step routes on shape
 (presence of `raw` key) and on the first pass emits an
-`@agent-directive: refine-prompt` halt — the agent runs the
-matching skill, which reconstructs `acceptance_criteria` +
-`assumptions`. On the rebound, `scoring/confidence.py` produces a
+`@agent-directive: refine-prompt` halt — the host agent is
+instructed to run the matching skill, which reconstructs
+`acceptance_criteria` + `assumptions`. On the rebound, `scoring/confidence.py` produces a
 frozen `ConfidenceScore(band, score, dimensions, reasons,
 ui_intent)` and the dispatcher branches on `band`:
 
@@ -616,8 +615,6 @@ are blocked by `freeze-guard.yml::manifest-integrity` at PR time.
 
 ## See also
 
-- [`agents/roadmaps/road-to-implement-ticket.md`](../../agents/roadmaps/road-to-implement-ticket.md)
-- [`agents/roadmaps/road-to-universal-execution-engine.md`](../../agents/roadmaps/road-to-universal-execution-engine.md)
 - `tests/golden/` — capture sandbox, recipes, and Capture Packs
 - [`../../tests/golden/harness.py`](../../tests/golden/harness.py) — Strict-Verb replay harness
 - [`../../.github/workflows/freeze-guard.yml`](../../.github/workflows/freeze-guard.yml) — manifest-integrity + live-replay gates

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -4,7 +4,6 @@ stability: beta
 
 # Linear AI — rules inclusion list
 
-> Phase 3 Step 1 deliverable for [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md).
 > Per-rule decision for the Linear AI rules digest. The digest is a
 > Markdown blob the user pastes into Linear's `Settings → Agents →
 > Additional guidance` (workspace / team / personal). The third-party

package/docs/contracts/linear-ai-three-layers.md

@@ -4,7 +4,6 @@ stability: beta
 
 # Linear AI — three-layer split rationale
 
-> Phase 3 Step 3 deliverable for [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md).
 > Per-rule routing is in [`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md);
 > this file documents *why* the split is workspace / team / personal and
 > what belongs in each.
@@ -128,4 +127,3 @@ does not maintain `event4u/agent-config`.
 - Per-rule decision: [`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md)
 - Builder script: [`scripts/build_linear_digest.py`](../../scripts/build_linear_digest.py)
 - Generated digests: `dist/linear/{workspace,team,personal}.md` (gitignored)
-- Roadmap: [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md) Phase 3

package/docs/contracts/load-context-budget-model.md

@@ -0,0 +1,178 @@
+---
+stability: beta
+---
+
+# `load_context:` Budget Accounting Model
+
+> **Audience:** maintainers of `type: "always"` rules and the budget
+> linter who need a single, deterministic answer to "how many chars
+> does this rule cost the always-budget?".
+> **Linter:** `scripts/check_always_budget.py`
+> (run via `task check-always-budget`).
+> **Companion:** [`load-context-schema.md`](load-context-schema.md) —
+> frontmatter contract for citing a context from a rule.
+> [`STABILITY.md § Budget contracts`](STABILITY.md#budget-contracts) —
+> the numeric caps this model enforces.
+
+This contract locks the **accounting model** by which a `type: "always"`
+rule's `load_context:` declarations contribute to the always-rule
+budget. It resolves the "is the rule its file size or its file size
+plus everything it loads?" ambiguity surfaced by Round-2 council on
+`road-to-structural-optimization` (Finding 7, CRITICAL).
+
+**Status:** internal-locked. Changes require a contract version bump
+and a roadmap revision (per
+`road-to-structural-optimization.md` § Definitions). The 2 % tolerance
+band on the retroactive test (G3 in v3.1) is the only legal way to
+adjust the model parameters without a roadmap revision; an overshoot
+above the band rejects the model and escalates to the council.
+
+## The locked model — Model (b) literal
+
+For any rule with frontmatter `type: "always"`:
+
+```
+EffectiveSize(rule) = RawSize(rule)
+                    + Σ RawSize(c) for every c in transitive_closure(rule.load_context*)
+```
+
+Where:
+
+- `load_context*` is the union of `load_context:` (lazy) **and**
+  `load_context_eager:` entries declared in frontmatter
+  (per [`load-context-schema.md`](load-context-schema.md)).
+- `transitive_closure` walks `load_context:` declarations on
+  context files **up to depth 2** — see § Nesting cap below.
+- `RawSize` is the byte size of the compressed file
+  (`.agent-src/...`), measured by `os.path.getsize()`. The
+  uncompressed source paths in frontmatter are mapped to their
+  compressed counterparts before sizing.
+- A context loaded by N always-rules counts **N times** (once per
+  loading rule). Rationale: the always-budget protects context-window
+  utilization at activation time; if rule A and rule B both fire on
+  the same turn, the agent pays both costs.
+
+### Why model (b) and not (a) or (c)
+
+| Model | Definition | Why rejected |
+|---|---|---|
+| (a) rule chars only | `EffectiveSize = RawSize(rule)` | Ignores the cost of declared contexts. Phase-2A obligation extraction would *appear* free, allowing unbounded context bloat. |
+| (b) literal *(this contract)* | `EffectiveSize = RawSize(rule) + Σ contexts` | Simplest invariant. Aligns with how the agent actually pays the cost when both rule and context fire on a turn. |
+| (c) shared-divisor | `EffectiveSize = RawSize(rule) + Σ (RawSize(c) / N_loaders)` | Tempting for shared `commit-mechanics`-style contexts but breaks the "what does each rule cost in isolation" question. Reserved as the **first refinement step** if the 2 % tolerance band is exceeded. |
+
+Council Round 3 converged A/A/A on the **separate-skills + shared-context**
+extraction pattern (Q1) and the **one-rule + three-contexts** consolidation
+(Q2); model (b) literal is the accounting that makes both patterns
+honest about their cost.
+
+## Nesting cap — depth 2
+
+A rule's `load_context:` may cite a context (depth 1). A context may
+cite further contexts in its own frontmatter (depth 2). A depth-2
+context citing a third context (depth 3) **aborts the build**.
+
+Rationale: bounded recursion makes the linter terminate in O(N) and
+prevents accidental cycles. Council Round-2 finding 9 (HIGH).
+
+The check is enforced by `scripts/check_always_budget.py` as a
+separate exit-code-1 condition (independent of the budget caps), so
+that a depth violation surfaces with the violating chain, not as a
+budget-cap breach.
+
+## Known-breach allowlist (transitional)
+
+Phase 2A targets `non-destructive-by-default` and `scope-control`
+for slimming. Both rules currently exceed the **6,000-char per-rule
+cap** under model (b) literal — this is expected and intentional:
+Phase 0.2 lands the model and its measurement; Phase 2A brings the
+breaches under the cap.
+
+To keep CI green during the transition, the linter and the test
+suite carry an explicit `KNOWN_PER_RULE_BREACHES` allowlist with the
+**measured ceiling** for each entry. Each entry must:
+
+- Be referenced by the Phase 2A roadmap step that will retire it.
+- Have a documented expected-removal date or roadmap milestone.
+- Fail the build the moment the breach **grows** above the recorded
+  ceiling (regression guard).
+
+Phase 2A's success criterion (`budget delta ≥ −5 %`) is the trigger
+to remove entries from the allowlist. The allowlist must be **empty**
+before Phase 2A is marked complete.
+
+## Retroactive test result (Phase 0.2.3)
+
+PR #34's `autonomous-execution` split moved mechanics into three
+contexts under `contexts/execution/`. Re-measuring under model (b)
+literal:
+
+| Metric | Value | Cap | Utilization |
+|---|---:|---:|---:|
+| Total extended budget | 49,311 chars | 49,000 | **100.6 %** |
+| Top-3 extended | 22,248 chars | 24,500 | 90.8 % |
+| Per-rule breaches | 2 of 9 | 0 | `non-destructive-by-default` (7,887), `scope-control` (8,529) |
+
+The total sits **0.6 % over** the cap — within the 2 % tolerance band
+(G3) which permits parameter refinement before model rejection. Per
+the contract, the model is **accepted**; the per-rule breaches are
+recorded in the transitional allowlist for Phase 2A.
+
+`autonomous-execution` itself is `type: "auto"` and does not enter
+the always-budget. Its own extended size (rule 5,196 + three contexts
+8,453) = 13,649 chars is reported by the linter for Phase 2B
+diagnostics but does not gate the always-budget cap.
+
+## Linter contract
+
+`scripts/check_always_budget.py` enforces:
+
+1. `EffectiveSize` per always-rule against the per-rule cap (with
+   the transitional allowlist).
+2. Sum of `EffectiveSize` across all always-rules against the total
+   cap (warn at 80 %, fail at ≥ 90 % — unchanged from PR #34).
+3. Top-3 sum against the top-3 cap.
+4. Depth ≤ 2 on every `load_context:` chain reachable from an
+   always-rule.
+
+### Recovery band (Phase 2A → Phase 5 transitional)
+
+Locked by AI Council session `2026-05-03T12-02-42Z` (verdict A1)
+after Phase 2A was attempted and reverted: the 1:1 rule-to-context
+split was uneconomical under Model (b) literal because the
+frontmatter and citation-line tax on the new context file outweighed
+the chars removed from the rule. Reverting Phase 2A left the budget
+at 96.8 % — strictly better than the `main` baseline at 100.6 % but
+inside the 90–100 % gap zone the linter rejects.
+
+While `RECOVERY_BAND_ENABLED = True`, the linter accepts a branch in
+the gap zone iff:
+
+- `total_ext < baseline` (read from `.github/budget-baseline.txt`,
+  the chars at last-green `main`), AND
+- every per-rule cap holds (allowlisted entries unchanged), AND
+- top-3 cap holds, AND
+- depth-2 cap holds.
+
+A branch passing only the recovery band reports
+`⚠️  WARN (recovery band, baseline N)`. The band is a one-way ratchet:
+once a smaller branch lands on `main`, the baseline file must be
+updated to the new total in the same commit. Phase 5 of
+`road-to-structural-optimization` flips `RECOVERY_BAND_ENABLED` to
+`False` and removes both the band and the G3 tolerance — the gate
+collapses to `total < TOTAL_CAP` strict.
+
+Exit codes: 0 = pass (or warn, including recovery band), 1 = any cap
+breach or depth violation, 3 = internal error.
+
+## What this contract intentionally does **not** promise
+
+- **No claim about runtime cost.** The model treats every context
+  as if it were active when its rule fires. The agent may cache or
+  short-circuit lazy loads at runtime; the budget is the **upper
+  bound**, not the realised cost.
+- **No claim about `type: "auto"` rules.** Auto rules enter the
+  agent's context only when their description matches; they have
+  their own per-rule LOC targets in Phase 2B (not a global budget).
+- **No claim about commands or skills.** Commands and skills load
+  on user invocation. Their token cost is accounted by the
+  command-cluster and skill-family contracts, not here.

package/docs/contracts/load-context-schema.md

@@ -93,9 +93,7 @@ directly under `contexts/` (see `contexts/model-recommendations.md`,
 chars(rule.md) + sum(chars(eager_target.md) for each entry) ≤ rule_cap
 ```
 
-`rule_cap` is the per-rule budget from
-[`road-to-rebalancing.md`](../../agents/roadmaps/road-to-rebalancing.md)
-§ Target architecture:
+`rule_cap` is the per-rule budget:
 
 - Always rule: 2,500
 - Auto rule: 4,000

package/docs/contracts/rule-interactions.md

@@ -104,4 +104,3 @@ junior (yields). For `complements`, ordering is documentary only.
 
 - [`docs/contracts/STABILITY.md`](STABILITY.md) — public-surface stability tiers.
 - [`docs/contracts/adr-chat-history-split.md`](adr-chat-history-split.md) — ADR pattern for major rule structural changes.
-- [`agents/roadmaps/archive/road-to-post-pr29-optimize.md`](../../agents/roadmaps/archive/road-to-post-pr29-optimize.md) § P2.2 — anchor for this matrix.

package/docs/contracts/rule-priority-hierarchy.md

@@ -64,7 +64,7 @@ which one's Iron Law gets the final say.
 | Situation | Bands that fire | Winner | Why |
 |---|---|---|---|
 | Standing autonomy + roadmap step says "merge to `main`" | 1, 7 | **1** | Hard Floor predates and outranks autonomy; surface the merge, ask. |
-| `/commit-in-chunks` on a diff that removes a directory | 1, 5 | **1** | Commit exception authorizes *commits*, not *bulk deletions*. Confirm diff this turn. |
+| `/commit:in-chunks` on a diff that removes a directory | 1, 5 | **1** | Commit exception authorizes *commits*, not *bulk deletions*. Confirm diff this turn. |
 | User asks "improve this" with no metric named | 4, 7 | **4** | Vague-request trigger fires before any autonomy decision; ask the one clarifying question. |
 | Editing `app/Auth/PasswordReset.php` mid-feature | 2, 7 | **2** | Security-sensitive surface stops the edit until threat-model is recorded. |
 | Agent about to claim "ready to merge" with no fresh test output | 5, 6 | **6** | Verification gate fires before the commit/push question is even valid. |

package/docs/contracts/ui-track-flow.md

@@ -4,8 +4,7 @@ stability: beta
 
 # UI Track — Flow Contract
 
-> Technical contracts for the UI directive sets shipped under
-> [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md).
+> Technical contracts for the UI directive sets.
 > Sibling of [`implement-ticket-flow.md`](implement-ticket-flow.md) — that
 > doc covers `backend`; this one covers `ui`, `ui-trivial`, and the
 > `mixed` set that stitches both.
@@ -14,11 +13,10 @@ stability: beta
 > - **Status:** Phase 1–6 shipped — audit / design / apply / review /
 >   polish handlers live under
 >   [`.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/).
->   Mixed (Phase 4) under `directives/mixed/`. `ui-trivial` (Phase 2 Step 6)
->   under `directives/ui_trivial/`. R4 (Visual Review Loop) added the
+>   Mixed under `directives/mixed/`. `ui-trivial` under
+>   `directives/ui_trivial/`. R4 (Visual Review Loop) added the
 >   a11y gate, the preview envelope, and a polish-termination rewrite
->   that splits subjective ceilings from objective a11y blocks — see
->   [`road-to-visual-review-loop.md`](../../agents/roadmaps/road-to-visual-review-loop.md).
+>   that splits subjective ceilings from objective a11y blocks.
 >   Golden Transcripts GT-U1..U4, U7, U8, U9..U12 plus GT-U5 (mixed
 >   flow), GT-U6A/B (stack dispatch), and R4's GT-U13..U15 (a11y polish,
 >   a11y ceiling, preview render failure) pin happy-path, ambiguity,
@@ -42,8 +40,6 @@ sentinels that release each gate.
   `SKILL.md` files.
 - A migration guide for the schema — see
   [`implement-ticket-flow.md`](implement-ticket-flow.md#state-schema-v1).
-- A roadmap — phased delivery lives in
-  [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md).
 
 ## The four directive sets
 
@@ -323,15 +319,9 @@ suite asserts every `BLOCKED` path has a matching declaration.
 - [`implement-ticket-flow.md`](implement-ticket-flow.md) — sibling
   contract for the `backend` set; covers `DeliveryState`, schema v1,
   hooks, persona policies, replay protocol.
-- [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md)
-  — phased delivery and Golden-Transcript matrix.
-- [`road-to-product-ui-track-followup.md`](../../agents/roadmaps/archive/road-to-product-ui-track-followup.md)
-  — pinned GT-U5 (mixed flow), GT-U6A/B (stack dispatch), GT-U7
-  (trivial happy path), GT-U8 (trivial reclassification).
-- [`road-to-visual-review-loop.md`](../../agents/roadmaps/road-to-visual-review-loop.md)
-  — R4 contract: a11y gate, preview envelope, polish-termination
-  rewrite. Pinned by GT-U13 (a11y polish), GT-U14 (a11y ceiling),
-  GT-U15 (preview render failure).
+- [`adr-product-ui-track.md`](adr-product-ui-track.md) — locked
+  decisions for the UI track (R3) and the visual-review-loop
+  amendment (R4: a11y gate, preview envelope, polish-termination).
 - [`existing-ui-audit` SKILL](../../.agent-src.uncompressed/skills/existing-ui-audit/SKILL.md)
   — producer of `state.ui_audit`.
 - [`ui-audit-gate` rule](../../.agent-src.uncompressed/rules/ui-audit-gate.md)

package/docs/customization.md

@@ -67,6 +67,8 @@ those sections.
 | `ai_council.cost_budget.max_total_usd` | `0.0` | Per-invocation USD ceiling. `0` disables (token caps still apply). |
 | `ai_council.cost_budget.daily_limit_usd` | `0.0` | Rolling 24h USD ceiling across all `/council` calls. `0` disables. Ledger lives at `~/.config/agent-config/council-spend.jsonl` (mode 0600). |
 
+> **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
+
 Council API tokens are installed via `./agent-config keys:install-anthropic`
 and `./agent-config keys:install-openai` — they prompt on `/dev/tty`, write to
 `~/.config/agent-config/<provider>.key` with mode `0600`, and never accept env

package/docs/getting-started.md

@@ -115,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 57 rules. No configuration needed.
+This is enforced automatically by 58 rules. No configuration needed.
 
 ---
 
@@ -155,7 +155,7 @@ Your agent now understands slash commands:
 | `/chat-history-resume` | Recover context after a crashed or switched session |
 | `/chat-history-clear` | Wipe the chat-history log (with confirmation) |
 
-→ [Browse all 69 active commands](../.agent-src/commands/)
+→ [Browse all 95 active commands](../.agent-src/commands/)
 
 ---
 
@@ -167,8 +167,9 @@ for every profile), the agent keeps a JSONL log of your conversation in
 rotates at the size configured in the profile (`128 KB` on `minimal`,
 `256 KB` on `balanced`, `512 KB` on `full`).
 
-When a chat opens and finds an existing log, the agent runs a
-4-state ownership check and chooses the right flow:
+When a chat opens and finds an existing log, the host agent is
+instructed to run a 4-state ownership check and choose the right
+flow:
 
 - **match** — this chat already owns the file. Append silently.
 - **foreign** — a different session's file. You get 3 options:

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

@@ -0,0 +1,100 @@
+# asking-and-brevity-examples
+
+Companion examples for three always-rules:
+[`ask-when-uncertain`](../../../.agent-src.uncompressed/rules/ask-when-uncertain.md),
+[`no-cheap-questions`](../../../.agent-src.uncompressed/rules/no-cheap-questions.md),
+[`direct-answers`](../../../.agent-src.uncompressed/rules/direct-answers.md).
+
+The rules carry the Iron Laws and the obligation surface. This file
+carries the illustrative material (example questions, rationale
+tables, failure-mode catalogs) that does not need to live in the
+always-loaded rule body — extracted to fit the always-rule budget.
+
+## Vague-request triggers — example questions
+
+Companion to `ask-when-uncertain` § Vague-request triggers. The rule
+lists the trigger patterns and the "missing info" columns; this file
+adds the example question to ask back at the user.
+
+| Pattern | Example clarifying question |
+|---|---|
+| "improve / optimize this" | "Optimize for what — execution speed or readability?" |
+| "add caching" | "Which cache driver, and what invalidates it?" |
+| "make it better / cleaner" | "What specifically feels wrong in the current code?" |
+| "clean up this file" | "Remove unused code, reformat, or restructure?" |
+| "fix this" (without specifying) | "What output/behavior is wrong right now?" |
+| "refactor X" | "Refactor toward what — smaller methods, extract class, or something else?" |
+| "use best practices" | "Best practices for what specifically — testing, naming, structure?" |
+| "handle errors properly" | "For which failure modes, and what should happen on error?" |
+| "add a UI / component / tile / page" when the repo mixes frameworks | "This repo uses {A} and {B} for UI — which one for this?" |
+
+## One-question-per-turn — why serial always wins
+
+Companion to `ask-when-uncertain` § How to ask. The rule states the
+Iron Law and the self-check; this file expands the rationale.
+
+| Situation | Why serial always wins |
+|---|---|
+| Design / architecture decisions | Answer to Q1 reframes Q2 |
+| Naming / command-syntax / API shape | Later choices depend on it |
+| Scope / PR boundaries | Changes what the other questions even mean |
+| Tool / library selection | Downstream choices branch from it |
+| "Which approach: A vs B vs C" | Each answer opens a different follow-up |
+| Even "independent" yes/no pairs | User still has to parse two contexts |
+| Any question the user has to **think** about, not just pick | Thinking load compounds when stacked |
+
+The shorthand: if the user has to *think* about an answer, that
+answer almost always reframes whatever question would have come
+next. Serial preserves the framing; parallel destroys it.
+
+## Cheap-question class catalog — extended examples
+
+Companion to `no-cheap-questions` § What counts as cheap. The rule
+lists the classes; this file adds longer-form examples per class.
+
+| Class | Pattern · why cheap | Concrete example |
+|---|---|---|
+| **Sequencing** | "Step 2 or 3 next?" when roadmap orders them — answer is in the roadmap | Roadmap says "2.1 then 2.2" → don't ask "should I do 2.2 next?" |
+| **Format-only** | "Table or paragraph?" — no semantic trade-off | User asked for a summary; format is a non-decision |
+| **Commit asks** | "Commit now?" — `commit-policy`: never ask | The commit-policy Iron Law forbids the question |
+| **CI / test asks** | "Run tests now?" — `verify-before-complete` decides | Verification is mandatory before completion claims; not a choice |
+| **Fenced-step re-asks** | "Start Phase 1?" after "plan only" — `scope-control § fenced step` | The fence stands until the user explicitly lifts it |
+| **Iron-Law option** | Option breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default` — does not exist | Don't surface "force-push to main?" as Option 2 |
+| **Context-derived** | Answer follows from prior turn / standing instruction / roadmap — act, state assumption inline | "Use the same branch?" after user said "stay on this branch" |
+| **Dominant option** | One choice obviously correct; alternatives carry no upside — pick it | "Run the linter or skip it?" when the linter is part of CI |
+| **Re-ask after decline** | Same path after user said no — `scope-control § decline = silence` | User declined a separate branch → don't propose it again on the same task |
+
+## Direct-answers — severity-tiered claim examples
+
+Companion to `direct-answers` § Iron Law 2 (no invented facts). The
+rule lists the severity table; this file adds concrete examples and
+hedge-language patterns.
+
+| Severity | Examples | Verification action |
+|---|---|---|
+| **High — load-bearing** | "Method `X::y()` exists at `path/to/file.php:142`", "version 12.4.1 added the API", "this test passes" | MUST verify with `view`, `grep`, `codebase-retrieval`, or fresh command output **before** claiming. Too expensive → ask. |
+| **Medium — project-shape** | "This project uses Pest for testing", "controllers live under `app/Http/Controllers`" | Verify if one tool call reaches it; otherwise hedge: *"I'd guess X — not checked"*. |
+| **Low — well-known idioms** | "PHP `array_map` returns a new array", "git tags are immutable", "JS arrays are zero-indexed" | Inference acceptable. Mark as inference if not 100% sure. |
+
+Hedge-language patterns:
+
+- ✅ "haven't verified X — likely from {known-similar-codebase}"
+- ✅ "guess, not checked — `path/to/file.php:142` is my best read"
+- ❌ "probably" alone — name what's unverified
+- ❌ "vermutlich" without hedge target
+
+## Direct-answers — failure modes the user will call out
+
+Companion to `direct-answers` § Failure modes. The rule lists the
+modes; this file adds the trigger phrases and the in-language
+correction pattern.
+
+| Failure | User's typical callout | Correct response |
+|---|---|---|
+| Iron Law 1 violation | "skip the flattery", "ohne smalltalk" | drop the opener; deliver substance |
+| Iron Law 2 violation | "have you actually checked?", "wo steht das?" | re-verify with a tool call; correct or retract the claim |
+| Iron Law 3 violation | "kürzer", "less prose", "tldr" | trim to one sentence + the answer |
+| Emoji blacklist hit | "ohne emojis", "no decoration" | re-render plain |
+
+Acknowledge once, in the user's language, switch behavior, no
+excuses (mirrors `language-and-tone` § slip handling).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.16.0",
+    "version": "1.17.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,