@event4u/agent-config 9.8.0 → 9.9.0

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

@@ -1,259 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# `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 condensed file
-  (`dist/agent-src/...`), measured by `os.path.getsize()`. The
-  uncondensed source paths in frontmatter are mapped to their
-  condensed 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.
-
-## Load order (Q1) — file order in frontmatter
-
-Locked by Phase 1.2 of `road-to-context-layer-maturity` (council
-session `2026-05-03T17-56-21Z`, v2 lock).
-
-When a rule declares multiple `load_context:` and / or
-`load_context_eager:` entries, the agent processes them in the order
-they appear in the YAML list, top to bottom. `load_context_eager:`
-entries are concatenated into the active context in declaration
-order; `load_context:` entries are available for lazy retrieval in
-the same order, surfaced first-listed-first when the rule body cites
-them in prose.
-
-**Rejected alternatives:**
-
-- *Citation order in prose* — non-machine-readable; would force every
-  rule to embed a sort hint and the linter to parse rule body text.
-- *Priority field per entry* — adds frontmatter surface area without
-  observable benefit. The current rule with the most contexts
-  (`autonomous-execution`, 3 contexts) reads each in declaration
-  order without ambiguity.
-
-This contract treats list order as the canonical signal. Authors
-must order their `load_context:` entries from "load this first" to
-"load this last" so prose citations and frontmatter agree.
-
-## Per-rule context-count cap (Q2) — ≤ 3 contexts per rule
-
-Locked by Phase 1.3 of `road-to-context-layer-maturity` (council
-session `2026-05-03T17-56-21Z`, v2 lock). Enforced by
-`scripts/check_always_budget.py` as `MAX_CONTEXTS_PER_RULE = 3`.
-
-A rule's combined count of `load_context:` + `load_context_eager:`
-top-level entries must not exceed **3**. The cap is on *declared*
-entries (depth 1 from the rule), not transitive closure — depth-2
-context citations are governed by the depth-2 nesting cap below.
-
-**Rationale:**
-
-- Empirical max in the current rule set is 3
-  (`autonomous-execution`); the cap locks the ceiling without forcing
-  any rewrite.
-- A 4th declared context is the structural signal that the rule
-  should split (one rule, one obligation surface), not load more.
-- Cross-platform mechanical: a count check is O(N), no semantic
-  analysis, identical observable on Augment and Claude Code.
-
-The cap applies to **all rule types** (`always` and `auto`) — Q2 is
-a structural constraint on rule shape, not a budget concern.
-
-## Cross-rule sharing (Q3) — Model (b) literal locked
-
-Locked by Phase 1.4 of `road-to-context-layer-maturity` (decision
-3a). The accounting model in § The locked model above stands without
-shared-context discount.
-
-**Decision:** when context X is loaded by N rules, each rule pays
-the full `RawSize(X)` under Model (b). No `chars(X) / N` discount.
-
-**Rationale (3a over 3b):**
-
-- The linter is correct as-is — `RECOVERY_BAND_ENABLED` plus the
-  per-rule allowlist is already a working ratchet to drive total
-  utilization below 100 %.
-- 3b would require a linter rewrite plus a new failure-mode test
-  family (cross-rule attribution, divisor-stability invariants).
-  Phase 1.4a's 4-hour / 200-LOC feasibility cap was structured to
-  reject 3b on cost; with no current shared-context patterns
-  exceeding 1 loader per context (verified Phase 1.1 inventory), 3b
-  has no measurable upside.
-- Phase 4c (shared-context discount) becomes a no-op under 3a.
-  Phase 4 leverage shifts to 4a (demote), 4b (merge), and 4d
-  (hard-condense) — see `road-to-context-layer-maturity` Phase 4
-  inputs gate.
-
-**Reopener:** if a future inventory shows ≥ 3 shared-context loaders
-and total utilization re-enters the 95–100 % zone after Phase 4
-completes, run the Phase 1.4a feasibility spike and propose 3b via
-contract version bump.
-
-## 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

@@ -1,220 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# `load_context:` Frontmatter Schema
-
-> **Audience:** rule authors and reviewers who want to keep an Always-rule
-> small while making deeper reasoning available on demand.
-> **Linter:** `scripts/lint_load_context.py` (run via `task lint-load-context`).
-> **Companion:** [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) —
-> hierarchy that decides *which* rule wins when several fire on the same turn.
-
-This contract defines the frontmatter convention by which a rule (or
-another context) declares the deeper reading material it relies on.
-The convention is **lazy by default**: declared entries are *available
-to load* when the situation demands them, never auto-loaded into every
-turn.
-
-## Schema
-
-Two keys, both optional, both top-level frontmatter:
-
-```yaml
----
-type: "always"
-description: "..."
-load_context:                # lazy — on-demand reference list
-  - contexts/<area>/<file>.md         # logical name (canonical)
-  - agents/settings/contexts/<file>.md         # project-local
-load_context_eager:          # opt-in eager — auto-loaded on rule fire
-  - contexts/<area>/<file>.md
----
-```
-
-> **Logical names only.** The `.agent-src.uncondensed/` prefix is
-> rejected by the schema regex (`scripts/schemas/rule.schema.json`) and
-> by `scripts/lint_load_context.py`. The condense-time rewriter
-> (`scripts/condense.py::_rewrite_paths`) resolves logical names to the
-> deployment-correct relative path (e.g. `../contexts/<area>/<file>.md`
-> for a rule at `rules/<name>.md`). The full migration history lives
-> in the archived path-fixes roadmap under `agents/roadmaps/archive/`.
-
-| Key | Loading | When to use |
-|---|---|---|
-| `load_context:` | **Lazy.** The agent reads the entry only when the rule's reasoning needs it. | Default. Use for everything that is "available knowledge" rather than "on every turn". |
-| `load_context_eager:` | **Eager.** The entry is concatenated into the active context whenever the rule fires. | Only when the deeper material is needed *every single time* the rule fires. Counts against the combined char budget. |
-
-**No default eager-load.** A rule with `load_context:` only does **not**
-auto-load anything; the agent decides per turn. Eager loading is
-opt-in and budget-gated.
-
-## Path rules
-
-- Logical names rooted at the source. The rewriter resolves them at
-  condense time.
-- Paths MUST end in `.md`.
-- Allowed roots:
-  - `contexts/<area>/<file>.md` — canonical logical name (resolves
-    against `.agent-src.uncondensed/`).
-  - `agents/settings/contexts/<file>.md` — project-local material (consumer
-    repo only).
-  - `dist/agent-src/contexts/<file>.md` — condensed mirror; tolerated
-    defensively, not authored.
-- The `.agent-src.uncondensed/` prefix is **rejected** by the schema
-  regex and by `lint_load_context.py` with a remediation hint pointing
-  at the canonical logical name.
-- A rule MAY reference contexts under either tree, but a package-shipped
-  rule SHOULD NOT eager-load an `agents/settings/contexts/` file (project-local
-  leak into shared package). Linter warns on this combination.
-- A context file may itself declare `load_context:` (chain reasoning).
-  The linter rejects cycles.
-
-## Subdirectory conventions
-
-Subdirectories under `contexts/` are **conventional, not enforced**.
-The linter only validates the root prefix; subdirectory layout is a
-documentation contract for human reviewers.
-
-Two canonical subdirectories are in production:
-
-| Subdir | Holds | First consumer |
-|---|---|---|
-| `contexts/execution/` | runtime decision logic, mechanics, and examples for execution-time rules (autonomy detection, verification mechanics, etc.) | `autonomous-execution` (Phase 2 of `road-to-pr-34-followups`) |
-| `contexts/authority/` | mechanics behind authority gates — what makes commits, scope changes, and git ops legal vs. illegal | `commit-policy` and `scope-control` (Phase 6 of `road-to-pr-34-followups`) |
-
-A third subdirectory, `contexts/communication/`, was proposed by the
-PR #34 round-6 review for user-interaction and language-and-tone
-mechanics. It is **not yet created** — the anti-speculation guard in
-Phase 6 forbids creating a context root before its triggering rule
-exists. Add it the same turn as the first migrating rule, not before.
-
-A new subdirectory is justified when:
-
-- A second rule needs to share contexts with the first one, AND
-- The contexts have a coherent topic (execution, authority, communication, …), AND
-- The triggering rule and its content move at the same time
-  (no empty subdir reservations).
-
-Single-rule contexts that don't fit one of the canonical topics live
-directly under `contexts/` (see `contexts/model-recommendations.md`,
-`contexts/skills-and-commands.md`).
-
-## Per-rule context-count cap (Q2)
-
-A rule's combined count of `load_context:` + `load_context_eager:`
-top-level entries MUST be ≤ **3**. Enforced by
-`scripts/check_always_budget.py` (`MAX_CONTEXTS_PER_RULE`); see
-[`load-context-budget-model.md § Per-rule context-count cap (Q2)`](load-context-budget-model.md#per-rule-context-count-cap-q2--3-contexts-per-rule)
-for the locking contract.
-
-A 4th context is the structural signal that the rule should split,
-not load more. Authors hitting the cap should extract a sibling rule
-with its own obligation surface, not stretch the existing one.
-
-## Load order
-
-Entries load in **frontmatter list order**, top-to-bottom. Author
-your list in "first read" order so prose citations and frontmatter
-agree. See
-[`load-context-budget-model.md § Load order (Q1)`](load-context-budget-model.md#load-order-q1--file-order-in-frontmatter)
-for the locking rationale.
-
-## Combined char-budget guard
-
-`load_context_eager:` triggers a budget check:
-
-```
-chars(rule.md) + sum(chars(eager_target.md) for each entry) ≤ rule_cap
-```
-
-`rule_cap` is the per-rule budget:
-
-- Always rule: 2,500
-- Auto rule: 4,000
-- Safety rule (`type: "always"` AND covers Hard-Floor topics): 5,000
-
-Linter computes the rule's class from frontmatter `type:` and the
-hard-floor allowlist (`non-destructive-by-default`,
-`security-sensitive-stop`). Exceeding the cap → linter error.
-
-Lazy `load_context:` does **not** count against the budget — by
-definition it is not loaded into every turn.
-
-## Public-vs-internal leak
-
-A rule shipped to consumers (`.agent-src.uncondensed/rules/`) may
-declare `load_context:` entries pointing at:
-
-- `.agent-src.uncondensed/contexts/` — public, OK.
-- `agents/settings/contexts/` — package-internal, **lint warning** (the entry
-  will not exist in consumer projects).
-
-Project-local rules may reference either. The linter classifies by
-the rule's tree, not by the target's tree.
-
-## No circular references
-
-A `load_context:` graph that cycles fails the linter. Cycles are
-defined across both `load_context:` and `load_context_eager:` edges.
-
-## Examples
-
-### Real consumer — `autonomous-execution`
-
-`.agent-src.uncondensed/rules/autonomous-execution.md` is the first
-production rule to declare `load_context:`. Its frontmatter:
-
-```yaml
----
-type: "auto"
-description: "Deciding whether to ask the user or just act on a workflow step — trivial-vs-blocking classification, autonomy opt-in detection, commit default; defers to non-destructive-by-default for the Hard Floor"
-alwaysApply: false
-source: package
-load_context:
-  - .agent-src.uncondensed/contexts/execution/autonomy-detection.md
-  - .agent-src.uncondensed/contexts/execution/autonomy-mechanics.md
-  - .agent-src.uncondensed/contexts/execution/autonomy-examples.md
----
-```
-
-Three lazy-loaded contexts, no `load_context_eager:`. The agent reads
-each context only when the corresponding section of the slim rule
-points at it (the rule body cites the same paths in prose so the
-load is intent-driven, not blanket).
-
-Pattern proven by this consumer:
-
-- **Slim the rule to obligations only** — the 192-line pre-split
-  source dropped to 119 lines (≤ 120 target met) by extracting LOGIC
-  (detection algorithm), MECHANICS (setting table, cloud behavior),
-  and EXAMPLES (anchor phrases, worked cases, failure modes) into
-  three separate context files.
-- **Cite, don't duplicate** — the slim rule contains zero
-  algorithm/mechanics/example prose; everything moved was physically
-  removed (verified by Phase 2.5 obligation diff:
-  [`agents/runtime/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md`](../../agents/runtime/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md)).
-- **Lazy by default** — no eager-load is declared; the budget guard
-  is therefore a no-op for this rule.
-
-`task lint-load-context` reports **1 declarer**, all paths resolve,
-no cycles.
-
-## Stability
-
-`beta` — schema is settled and serves one production rule
-(`autonomous-execution`). A breaking schema change is a SemVer-minor
-pre-1.0 bump. Adding a new optional key is non-breaking. The first
-consumer surfaced no schema gaps; the next migration batch (roadmap
-`road-to-pr-34-followups` Phase 6 — `commit-policy`, `scope-control`,
-`verify-before-complete`) is the next stress test.
-
-## Cross-references
-
-- [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) — which
-  rule wins on conflict; this schema is orthogonal (depth, not
-  priority).
-- [`rule-interactions.yml`](rule-interactions.yml) — pairwise rule
-  interaction matrix.
-- [`STABILITY.md`](STABILITY.md) — beta-tag implications.

package/docs/contracts/local-analytics.md

@@ -1,160 +0,0 @@
----
-stability: experimental
----
-
-# Local Analytics Contract
-
-> **Status** · v0 / design · 2026-05-24. Phase 7 of the
-> employee-product workstream.
-> **Local-only.** Does NOT lift the Hard-Floor item from 3.1.0 — no
-> network egress, no remote Worker, no POST. Inertia of the prior
-> telemetry roadmap is preserved.
-
-## Position vs the 3.1.0 telemetry SDK
-
-3.1.0 shipped the telemetry SDK + Cloudflare Worker as **source-only**;
-the kill-switch defaults off and nothing is deployed. Phase 7 builds
-a **separate local-only** analytics path:
-
-| Surface | Lives | Egress | Default |
-|---|---|---|---|
-| 3.1.0 remote telemetry | Worker (undeployed) | ✗ inert | off, Hard-Floor |
-| **Phase 7 local analytics** | `~/.event4u/agent-config/workspace/analytics/` | ✗ never | **on** for local-only |
-
-The two surfaces share **event vocabulary** where it overlaps; they
-never share a transport. Local analytics writes to disk; remote
-telemetry remains undeployed.
-
-## Event vocabulary
-
-Re-uses the `install_stage` schema (3.1.0) where applicable, and
-adds the `workspace_event` schema for launcher / document / explain
-interactions:
-
-| schema | source | example fields |
-|---|---|---|
-| `install_stage/v1` | installer (3.1.0) | `stage`, `outcome`, `duration_ms`, `package_version` |
-| `workspace_event/v0` | Phase 4–6 workspace | `event`, `role`, `task`, `host_tier`, `duration_ms` |
-
-`workspace_event/v0` event names (closed set):
-
-- `launcher.opened` · `launcher.task_picked` · `launcher.task_launched`
-- `session.started` · `session.host_turn` · `session.completed`
-- `document.created` · `document.edited` · `document.exported`
-- `explain.opened` · `explain.mode_toggled` · `why.invoked`
-- `knowledge.queried` · `knowledge.source_clicked`
-- `rule.tier2_loaded` · `persona.cited` · `skill.activated` — **6.0.0-C
-  evidence-based-pruning measurement.** `rule.tier2_loaded` fires when a
-  router-gated (tier-2) rule is loaded; `persona.cited` when a persona is
-  cited-in-use by a skill/command; `skill.activated` when a skill activates
-  under the active profile. Payload fields: the artefact `id` (or `rule`,
-  `persona`, `skill`) and the active `profile` — nothing else. These feed the
-  thresholds in [`evidence-based-pruning.md`](evidence-based-pruning.md) so a
-  later, data-bearing roadmap cuts on usage, not on a guessed target.
-
-No prompt bodies. No response bodies. No PII. Only counters, role
-labels, task slugs (already public), artefact ids, and durations.
-
-## Storage
-
-```
-~/.event4u/agent-config/workspace/analytics/
-├── events.jsonl              ← append-only event log
-└── retention.lock            ← prune-pass mutex
-```
-
-One JSON record per line:
-
-```json
-{
-  "ts": "2026-05-24T12:08:00Z",
-  "schema": "workspace_event/v0",
-  "event": "launcher.task_launched",
-  "data": { "role": "galabau", "task": "angebot-erstellen",
-            "host_tier": 1, "duration_ms": 420 }
-}
-```
-
-Rolling retention: **90 days local**. A prune pass on workspace
-launch trims records older than 90 days; the lockfile prevents
-concurrent prune (cheap fs lock, not a real mutex).
-
-## Opt-out
-
-Single env var, single config flag, both checked:
-
-| Surface | Default | Override |
-|---|---|---|
-| Env | `AGENT_CONFIG_NO_LOCAL_ANALYTICS` unset | set to any non-empty value → no writes |
-| Config | `.agent-settings.yml` → `analytics.local: on` | set to `off` → no writes |
-
-Either set to off → emitter short-circuits before opening the file.
-No retention pruning either; the existing log stays until the user
-removes it.
-
-## Emitter API
-
-```python
-# packages/core/src/workspace/analytics/emitter.py
-class LocalAnalytics:
-    def emit(self, event: str, data: dict) -> None: ...
-    def query(self, since: datetime, event: str | None = None) -> list[Event]: ...
-    def prune(self) -> int: ...   # returns number of records dropped
-```
-
-The emitter is a synchronous append-line write. Never blocks the UI
-thread above 5 ms (90th percentile); no async / queue / batch
-machinery in v0.
-
-## `/analytics:show` command
-
-Local-only query. Renders to ASCII / Markdown table; never POSTs.
-
-```
-$ npx @event4u/agent-config analytics:show --window 30d
-
-Top prompts (last 30 days)
-  galabau · angebot-erstellen          47
-  content-creator · video-from-script  31
-  consultant · meeting-memo            24
-
-Launcher → completion rate per role
-  galabau           87% (47 launched · 41 completed)
-  content-creator   71% (31 launched · 22 completed)
-  consultant        92% (24 launched · 22 completed)
-
-Average session length: 4m 12s
-Knowledge sources clicked: 18 (handbuch.pdf · offer-template.md · …)
-```
-
-Flags: `--window <30d|7d|24h>` · `--event <name>` · `--role <slug>` ·
-`--format <markdown|csv|json>`. No `--upload`, no `--share`; the
-command can only read and render.
-
-## Coverage (Phase 7 Step 4)
-
-- pytest against fixture JSONL stores (`tests/fixtures/local-analytics/`):
-  emitter writes, query filters by window + event + role, prune
-  drops correctly at the 90-day boundary.
-- Env-flag short-circuit: emitter is a no-op when
-  `AGENT_CONFIG_NO_LOCAL_ANALYTICS=1`; no file is created.
-- Concurrency: two emitters writing the same file produce
-  well-formed lines (POSIX `O_APPEND` semantics — test on Linux,
-  document Windows caveat).
-
-## Failure modes
-
-- Disk full → emitter logs warning to stderr, drops the event, never
-  raises. UI thread is unaffected.
-- Malformed line in `events.jsonl` → query skips the line, increments
-  a `malformed_lines` counter exposed via `/analytics:show --health`.
-- Schema bump (`workspace_event/v0` → `v1`) → emitter writes the new
-  schema; query reads both. Migration is forward-compatible.
-
-## Cross-references
-
-- Phase 4 shell that produces the events: [`daily-workspace`](daily-workspace.md).
-- Phase 5 document events: [`workspace-documents`](workspace-documents.md).
-- Phase 6 explain events: [`explain-modes`](explain-modes.md).
-- 3.1.0 telemetry inertia: archived `road-to-product-adoption.md` Phase 4.
-- Walkthrough doc (Phase 7 Step 5): `docs/guides/local-analytics.md` (deferred).