@event4u/agent-config 3.3.0 → 4.1.0

package/docs/contracts/skill-distribution-channels.md

@@ -0,0 +1,61 @@
+# Skill Distribution Channels — canonical per AI tool
+
+**Status:** Active (locked 2026-05-25 via Phase A of `road-to-clean-skill-distribution-channels.md`)
+**Owner:** maintainer-team
+**Inputs:** [`agents/evidence/audits/2026-05-distribution-channels/`](../../agents/evidence/audits/2026-05-distribution-channels/) (audits 01 + 02), AI Council convergence `agents/runtime/council/responses/2026-05-25-canonical-channel.json` (claude-sonnet-4-5 + gpt-4o, 2026-05-25)
+
+## Rule
+
+For every AI tool the package supports, **exactly one channel** is the canonical registration surface used by the consumer installer. The other channel (where one exists at the upstream tool level) is either:
+
+- not projected into the consumer install at all (default), or
+- projected behind the `--legacy-both` opt-in flag for users on older harnesses.
+
+## Per-tool matrix
+
+| Tool | Channels supported by host | Canonical (consumer install) | Other channel behaviour | Rationale |
+|---|---|---|---|---|
+| **Claude Code** | Plugin manifest (`.claude-plugin/marketplace.json`) + filesystem (`.claude/skills/`) | **filesystem** | Manifest not projected by default; use `--legacy-both` to opt in | Cross-tool consistency. Filesystem is the only channel all six tools share. The package's own `.claude-plugin/marketplace.json` stays at the source repo for users who run `claude plugin install <name>` directly. |
+| **Augment** | Manifest with `source: "."` (`.augment-plugin/marketplace.json`) + filesystem (`.augment/`) | **filesystem** | Manifest stays — it is metadata-only, not a second registry. No `--legacy-both` needed. | The manifest points at the same directory the harness scans; one source of truth on disk. |
+| **Cursor** | Filesystem only (`.cursor/rules/*.mdc`) | **filesystem** | n/a — no second channel exists | No host-level alternative. |
+| **Cline** | Filesystem only (`.clinerules/`) | **filesystem** | n/a | No host-level alternative. |
+| **Windsurf** | Filesystem only (`.windsurf/rules/`, `.windsurf/workflows/`) | **filesystem** | n/a | No host-level alternative. |
+| **Copilot** | Single file (`.github/copilot-instructions.md` or root `copilot-instructions.md`) | **filesystem** | n/a | Single file, not a registry. |
+
+## Decision drivers
+
+1. **Cross-tool consistency.** Four of six tools have only a filesystem channel. Picking filesystem for the other two makes one rule cover everything.
+2. **Same-install dual-registration is closed by default.** If `scripts/install.sh` does not project the Claude plugin manifest into the consumer install, the harness has only the filesystem to scan, so the manifest+filesystem double-register risk is eliminated regardless of how the host harness deduplicates.
+3. **Cross-scope drift is orthogonal.** The canonical-channel decision does NOT solve the actual 2026-05-25 bug (cross-scope user-global + project-local with different frontmatter). Phase B installer guard + Phase C runtime probe close that path. They are companions to this contract, not substitutes for it.
+4. **Publication surface preserved.** The source repo continues to ship `.claude-plugin/marketplace.json` for users who want to install via `claude plugin install <event4u/agent-config>`. Removing the manifest from the **consumer install** does not affect that path.
+5. **`--legacy-both` is opt-in only.** Users on harness versions that genuinely require both channels can request the legacy projection. Default is single-channel.
+
+## Council convergence (2026-05-25)
+
+Two-round debate on whether filesystem or plugin should be canonical for Claude. The transparently-merged verdict:
+
+- **Anthropic (R2):** "MIXED leaning DISAGREE on the proposal **as written**" — pointed out that the proposal does not address cross-scope drift by itself, and that the canonical-channel decision only matters if the Claude harness double-registers on same-install. Test scenarios surfaced as critical path before locking. Conclusion: if Claude does ambient filesystem discovery (it does, in practice), **filesystem becomes canonical not by choice but because manifest adds a second registration mechanism with no isolation benefit**.
+- **OpenAI (R2):** Endorsed filesystem-canonical with a fail-loud Phase C probe. Suggested user research on `--legacy-both` adoption.
+
+Both members agreed the decision is structurally correct **conditional on** the cross-scope drift fix landing in Phase B and the probe being fail-loud in Phase C. This contract is published with those follow-up commitments.
+
+## Acceptance criteria for follow-up phases
+
+Phase B and Phase C of `road-to-clean-skill-distribution-channels.md` MUST:
+
+- (Phase B) Add a pre-install guard that detects existing installs at the other scope and either refuses, warns, or upgrades — surfaced via numbered options.
+- (Phase C) Run a probe at `agent-config setup` time AND from `scripts/install.sh --strict` that fails the install on cross-scope drift findings (per the council convergence — fail-loud, not informational).
+- (Phase A Step 4) Update `scripts/install.sh` and `task generate-tools` so the canonical channel above is what lands in the consumer install. Document `--legacy-both` for opt-in.
+
+## Out of scope
+
+- Manifest format changes upstream (Claude Code's marketplace shape) — host-controlled.
+- Alternative install paths (vendored copies, git submodules, npm `--prefix`) — package's npm install is the supported path.
+- Re-litigating the channel pick after this lock — reopened only on a new audit that surfaces a structurally different shape (e.g. a host change that removes ambient filesystem discovery).
+
+## See also
+
+- [`docs/contracts/install-scopes.md`](install-scopes.md) — companion contract for cross-scope behaviour (authored in Phase B).
+- [`docs/contracts/harness-expectations.md`](harness-expectations.md) — Phase D companion documenting host-side behaviours that look like package bugs but are not.
+- [`agents/evidence/audits/2026-05-distribution-channels/`](../../agents/evidence/audits/2026-05-distribution-channels/) — the underlying audits (01 Claude, 02 Augment, 03 installer flow).
+- [`README.md § Installation`](../../README.md) — consumer-facing install path.

package/docs/contracts/skill-domains.md

@@ -10,7 +10,7 @@ keep-beta-until: 2026-08-12
 > · **Schema:** `scripts/schemas/skill.schema.json` § `domain`
 
 Locks the canonical 6-domain taxonomy that classifies every skill in
-`.agent-src.uncompressed/skills/`. Each skill MUST declare exactly one
+`.agent-src.uncondensed/skills/`. Each skill MUST declare exactly one
 `domain:` value from the allow-list below in its `SKILL.md` frontmatter.
 
 ## § 1 — Allow-list
@@ -139,6 +139,6 @@ release notes.
 
 ## See also
 
-- [`skill-quality`](../../.agent-src.uncompressed/rules/skill-quality.md) — frontmatter contract for skills
+- [`skill-quality`](../../.agent-src.uncondensed/rules/skill-quality.md) — frontmatter contract for skills
 - [`rule-classification`](rule-classification.md) — sister taxonomy for rules (kernel vs auto)
 - `road-to-better-skills-and-profiles.md` — Block B (taxonomy lock + back-fill + folder reorg)

package/docs/contracts/smoke-contracts.md

@@ -34,10 +34,10 @@ the paths touched in the PR:
 
 | Tier | Globs that trigger | Script |
 |---|---|---|
-| kernel | `.agent-src.uncompressed/rules/**`, `.agent-src/rules/**`, `dist/router.json`, `scripts/measure_rule_budget.py` | `scripts/smoke/kernel.sh` |
-| router | `dist/router.json`, `.agent-src.uncompressed/rules/**`, `.agent-src.uncompressed/skills/**`, `docs/contracts/**`, `docs/guidelines/**` | `scripts/smoke/router.sh` |
-| schema | `.agent-src.uncompressed/skills/**`, `.agent-src.uncompressed/rules/**`, `scripts/schemas/**`, `scripts/skill_linter.py`, `scripts/validate_frontmatter.py` | `scripts/smoke/schema.sh` |
-| skills | `.agent-src.uncompressed/skills/**` | `scripts/smoke/skills.sh` |
+| kernel | `.agent-src.uncondensed/rules/**`, `.agent-src/rules/**`, `dist/router.json`, `scripts/measure_rule_budget.py` | `scripts/smoke/kernel.sh` |
+| router | `dist/router.json`, `.agent-src.uncondensed/rules/**`, `.agent-src.uncondensed/skills/**`, `docs/contracts/**`, `docs/guidelines/**` | `scripts/smoke/router.sh` |
+| schema | `.agent-src.uncondensed/skills/**`, `.agent-src.uncondensed/rules/**`, `scripts/schemas/**`, `scripts/skill_linter.py`, `scripts/validate_frontmatter.py` | `scripts/smoke/schema.sh` |
+| skills | `.agent-src.uncondensed/skills/**` | `scripts/smoke/skills.sh` |
 
 `task smoke` runs all four locally regardless of paths.
 
@@ -107,7 +107,7 @@ constant in the script body and the row below.
 ```
 
 - **5 random skills** picked deterministically (seed = epoch day) from
-  `.agent-src.uncompressed/skills/*/SKILL.md` and re-validated via
+  `.agent-src.uncondensed/skills/*/SKILL.md` and re-validated via
   `scripts/validate_frontmatter.py`. `agent-config explain skill` is
   **not** invoked — `explain` only supports `{config,rule,route}` today
   ([`scripts/agent-config/cmd_explain.py`](../../scripts/agent-config/cmd_explain.py));

package/docs/contracts/telegraph-telemetry.md

@@ -0,0 +1,83 @@
+---
+stability: beta
+keep-beta-until: 2026-08-15
+---
+
+# telegraph telemetry — multiplier contract
+
+> **Status:** suspended (kill-criterion not met in `telegraph-v1`).
+> Telemetry surface records `telegraph_delta_tokens = 0` until a v2 bench
+> proves a positive multiplier on the load-bearing `vs_terse` arm.
+
+## Constant
+
+| Key | Value | Provenance |
+|---|---|---|
+| `telegraph_multiplier_version` | `v1` | Tied to `internal/bench/reports/telegraph-v1.{json,md}` |
+| `telegraph_multiplier_value` | `0.9155` | `median(terse_control_tokens / condensed_tokens)` over the 10-prompt v1 corpus |
+| `telegraph_multiplier_p10` | `0.4506` | 10th percentile (worst-case carve-out-tax prompts) |
+| `telegraph_multiplier_p90` | `2.3664` | 90th percentile (pure-prose prompts where telegraph wins) |
+| `telegraph_multiplier_active` | `false` | **Suspended** — kill-criterion not met (`vs_terse` median −9.27 %) |
+
+The **active** flag gates whether the multiplier is applied to runtime
+telemetry. While `false`, `scripts/telegraph_stats.py` reports
+`telegraph_delta_tokens = 0` regardless of `speak_scope` setting.
+
+## How the multiplier is interpreted
+
+`telegraph_estimated_uncondensed_tokens = telegraph_condensed_tokens × M`,
+where `M = telegraph_multiplier_value`.
+
+`telegraph_delta_tokens = telegraph_estimated_uncondensed_tokens − telegraph_condensed_tokens`.
+
+- `M > 1.0` → telegraph condenses; `delta` is **positive** (saving).
+- `M = 1.0` → break-even; no delta surfaced.
+- `M < 1.0` → telegraph costs more than the terse baseline; `delta` is
+  **negative**. Surfacing a negative saving is misleading for the
+  user (looks like a bug), so the contract is to **suspend the
+  multiplier** and record `delta = 0` until a v2 bench lifts `M`
+  above `1.0` on the load-bearing arm.
+
+## Why suspended after v1
+
+The `telegraph-v1` bench (`internal/bench/reports/telegraph-v1.md`, 30 calls,
+2026-05-16) found:
+
+- Median savings vs raw uncondensed: **+23.51 %** (inflated by the
+  carve-out-tax-free pure-prose prompts).
+- Median savings vs terse-control: **−9.27 %** (load-bearing).
+- Carve-out-heavy prompts (path-list −108 %, mode-marker −123 %)
+  drag the median negative.
+
+The terse-control arm is the kill-criterion baseline per
+[`condensation-default-kill-criterion.md`](condensation-default-kill-criterion.md).
+Until a v2 bench (broader corpus or a re-tuned dialect) lifts the
+`vs_terse` median to ≥ 0 %, the multiplier stays suspended.
+
+## How to lift the suspension
+
+1. Run an extended bench against a broader corpus (Phase 3+ work).
+2. If `median(savings_vs_terse) ≥ 0` (and ideally ≥ 30 % to flip the
+   rule default), recompute `telegraph_multiplier_value`.
+3. Update this contract: bump `telegraph_multiplier_version` to `v2`,
+   set `telegraph_multiplier_active = true`, cite the new bench file.
+4. The change is reversible — drop back to `v1` if a regression
+   appears.
+
+## Consumers
+
+- [`scripts/telegraph_stats.py`](../../scripts/telegraph_stats.py) — reads
+  this constant, computes per-session / per-conversation / lifetime
+  deltas from `agents/cost-tracking/sessions.jsonl`.
+- [`scripts/cost_summary.py`](../../scripts/cost_summary.py) — emits
+  the stable JSON contract for inter-tool consumption per
+  [`cost-summary-schema.md`](cost-summary-schema.md).
+- `agent-status` skill — surfaces the per-session delta in the
+  status report under the `[telegraph: …]` widget.
+
+## See also
+
+- [`condensation-default-kill-criterion.md`](condensation-default-kill-criterion.md) — the rule-default-flip gate; this multiplier is gated on the same `vs_terse` arm.
+- [`internal/bench/reports/telegraph-v1.md`](../../bench/reports/telegraph-v1.md) — provenance for the `v1` value.
+- [`internal/bench/reports/telegraph-v2.md`](../../bench/reports/telegraph-v2.md) — input-side (orthogonal); does NOT feed this multiplier (this multiplier is output-side).
+- [`telegraph-speak`](../../.agent-src.uncondensed/rules/telegraph-speak.md) — runtime rule the multiplier measures.

package/docs/contracts/trust-and-safety.md

@@ -11,7 +11,7 @@ keep-beta-until: 2026-08-21
 Phase 1 stamped every artefact with `trust.level`,
 `trust.confidence`, and `trust.human_review_required`. Phase 5
 **enforces** those fields: the installer surfaces them at selection
-time, the compressor injects banners into compiled output, the
+time, the condenseor injects banners into compiled output, the
 runtime gates `human_review_required: true` artefacts before final
 output, and a lint catches drift. This contract is what those four
 consumers depend on.
@@ -37,7 +37,7 @@ demand review on its specific surface.
 
 ## § 2 — HRR banner
 
-The compressor (`scripts/compress.py`) prepends every artefact whose
+The condenseor (`scripts/condense.py`) prepends every artefact whose
 frontmatter declares `trust.human_review_required: true` with:
 
 ```text
@@ -48,9 +48,9 @@ frontmatter declares `trust.human_review_required: true` with:
 ```
 
 - The HTML comment is the parser-stable marker
-  (`_HRR_BANNER_MARKER` in `scripts/compress.py`). Runtime detection
+  (`_HRR_BANNER_MARKER` in `scripts/condense.py`). Runtime detection
   greps for this string, never the prose line.
-- Idempotent: re-compressing a file that already carries the marker
+- Idempotent: re-condensing a file that already carries the marker
   leaves it unchanged.
 - `<domain>` is the first pack id that ships the artefact (e.g.
   `finance-basic`, `founder-strategy`); falls back to `core` for
@@ -135,7 +135,7 @@ Exits 0 clean, 1 on any violation. Tests in
 ## § 7 — References
 
 - ADR: [`ADR-018 — Trust & Safety Layer`](../decisions/ADR-018-trust-and-safety-layer.md)
-- Compressor implementation: [`scripts/compress.py`](../../scripts/compress.py)
+- Condenseor implementation: [`scripts/condense.py`](../../scripts/condense.py)
   (`_inject_hrr_banner`, `_HRR_BANNER_MARKER`)
 - Installer implementation: [`packages/core/installer/src/trust-escalation.ts`](../../packages/core/installer/src/trust-escalation.ts)
 - Lint implementation: [`scripts/lint_trust_coherence.py`](../../scripts/lint_trust_coherence.py)

package/docs/contracts/ui-stack-extension.md

@@ -24,10 +24,10 @@ change.
 
 | Artefact | File | Change |
 |---|---|---|
-| Stack label | [`scripts/work_engine/stack/detect.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/stack/detect.py) | New entry in `KNOWN_STACKS` + a heuristic in `detect_stack` |
-| Apply skill | `.agent-src.uncompressed/skills/ui-apply-<stack>/SKILL.md` | New skill bundle |
-| Review skill | `.agent-src.uncompressed/skills/ui-design-review-<stack>/SKILL.md` | New skill bundle |
-| Polish skill | `.agent-src.uncompressed/skills/ui-polish-<stack>/SKILL.md` | New skill bundle |
+| Stack label | [`scripts/work_engine/stack/detect.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/stack/detect.py) | New entry in `KNOWN_STACKS` + a heuristic in `detect_stack` |
+| Apply skill | `.agent-src.uncondensed/skills/ui-apply-<stack>/SKILL.md` | New skill bundle |
+| Review skill | `.agent-src.uncondensed/skills/ui-design-review-<stack>/SKILL.md` | New skill bundle |
+| Polish skill | `.agent-src.uncondensed/skills/ui-polish-<stack>/SKILL.md` | New skill bundle |
 | Dispatch tables | `directives/ui/{apply,review,polish}.py` | New row in each `STACK_DIRECTIVES` map |
 | Golden fixture | `tests/golden/sandbox/recipes/gt_u<NN>_<stack>_*.py` | One happy-path baseline at minimum |
 
@@ -131,9 +131,9 @@ the skill does **not** check the ceiling itself but must respect
 ## Step 4 — wire dispatch tables
 
 Three identical edits in
-[`directives/ui/apply.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/apply.py),
-[`directives/ui/review.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/review.py),
-and [`directives/ui/polish.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/polish.py):
+[`directives/ui/apply.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/apply.py),
+[`directives/ui/review.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/review.py),
+and [`directives/ui/polish.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/polish.py):
 
 ```python
 STACK_DIRECTIVES: dict[str, str] = {

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

@@ -13,7 +13,7 @@ keep-beta-until: 2026-08-12
 > - **Created:** 2026-05-01
 > - **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/).
+>   [`.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/).
 >   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
@@ -56,9 +56,9 @@ exists so the dispatcher's completeness check is satisfied; no logic
 runs and no state is touched.
 
 Source of truth for slot wiring:
-[`directives/ui/__init__.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/__init__.py),
-[`directives/mixed/__init__.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/mixed/__init__.py),
-[`directives/ui_trivial/__init__.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui_trivial/__init__.py).
+[`directives/ui/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/__init__.py),
+[`directives/mixed/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/mixed/__init__.py),
+[`directives/ui_trivial/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui_trivial/__init__.py).
 
 ## The `ui` set — slot-by-slot
 
@@ -75,7 +75,7 @@ Mandatory pre-step. Routes on `state.ui_audit` shape:
 | Anything else populated | `BLOCKED` numbered options | User picks candidate to extend (or "build new"); records `audit_path = "ambiguous"` + `candidate_pick` |
 
 Constants live in
-[`directives/ui/audit.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/audit.py):
+[`directives/ui/audit.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/audit.py):
 `STRONG_SIMILARITY = 0.7`, `TIE_GAP = 0.05`,
 `TESTED_AGAINST_SHADCN_MAJOR = 2`. Idempotent re-entry: once
 `audit_path` is set the step round-trips through `SUCCESS` without
@@ -199,7 +199,7 @@ Stack-directive table mirrors apply / review with prefix
 ### `report` → backend renderer
 
 Re-export of
-[`directives.backend.report.run`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/backend/report.py).
+[`directives.backend.report.run`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/backend/report.py).
 The renderer is pure and state-driven; the same Markdown contract
 serves both tracks.
 
@@ -234,7 +234,7 @@ adjustment). Phase-1 intent classifier writes
 `directive_set = "ui-trivial"`.
 
 Hard preconditions in
-[`directives/ui_trivial/apply.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui_trivial/apply.py):
+[`directives/ui_trivial/apply.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui_trivial/apply.py):
 
 - `MAX_FILES = 1` — exactly one file touched.
 - `MAX_LINES_CHANGED = 5` — diff stays under five changed lines.
@@ -323,7 +323,7 @@ suite asserts every `BLOCKED` path has a matching declaration.
 - [`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)
+- [`existing-ui-audit` SKILL](../../.agent-src.uncondensed/skills/existing-ui-audit/SKILL.md)
   — producer of `state.ui_audit`.
-- [`ui-audit-gate` rule](../../.agent-src.uncompressed/rules/ui-audit-gate.md)
+- [`ui-audit-gate` rule](../../.agent-src.uncondensed/rules/ui-audit-gate.md)
   — the always-on rule that mirrors the audit gate at the agent layer.

package/docs/contracts/user-type-schema.md

@@ -7,7 +7,7 @@ keep-beta-until: 2026-08-14
 
 > **Status:** active · **Stability:** beta · **Owner:** step-6-user-types-axis
 > · **Linter:** `scripts/skill_linter.py § lint_usertype`
-> · **Source-of-truth dir:** `.agent-src.uncompressed/user-types/`
+> · **Source-of-truth dir:** `.agent-src.uncondensed/user-types/`
 > · **Sibling axis (distinct):** install-time `user-types/` (package root) — see [`adr-install-user-type-axis`](adr-install-user-type-axis.md)
 > · **ADR:** [`adr-user-types-axis`](adr-user-types-axis.md)
 
@@ -127,7 +127,7 @@ The linter (`scripts/skill_linter.py § lint_usertype`) enforces:
 - description ≤ 160 chars
 
 Authors must use the template at
-`.agent-src.uncompressed/user-types/_template/user-type.md`.
+`.agent-src.uncondensed/user-types/_template/user-type.md`.
 
 ## § 7 — Versioning
 
@@ -142,5 +142,5 @@ version bump and a separate ADR.
 - [`persona-schema`](persona-schema.md) — sister axis (methodology vs end-user)
 - [`adr-user-types-axis`](adr-user-types-axis.md) — why the axis split exists
 - [`adr-install-user-type-axis`](adr-install-user-type-axis.md) — the install-time `user_type` axis (distinct layer, same vocabulary)
-- `.agent-src.uncompressed/user-types/README.md` — authoring entry point
-- `.agent-src.uncompressed/user-types/_template/user-type.md` — template starter
+- `.agent-src.uncondensed/user-types/README.md` — authoring entry point
+- `.agent-src.uncondensed/user-types/_template/user-type.md` — template starter

package/docs/contracts/workflow-packs.md

@@ -21,7 +21,7 @@ gates.
 ## Schema
 
 ```yaml
-# .agent-src.uncompressed/packs/<pack-id>.yml
+# .agent-src.uncondensed/packs/<pack-id>.yml
 pack:
   id: <pack-id>                      # kebab-case, file name without .yml
   audience:
@@ -52,7 +52,7 @@ pack:
 | `composition.preset_id` | string | yes | Override applied to the chain documented in [`config-presets`](config-presets.md). Same opt-in semantics. |
 | `surface.commands_allowed` | list[string] | yes | Cap = **12**. Items must appear in [`command-clusters`](command-clusters.md). The pack does **not** disable other commands — the cap is for the wizard's first-screen rendering, not enforcement. |
 | `surface.skills_allowed` | list[string] | yes | Cap = **15**. Items must appear in `docs/skills-catalog.md`. Same render-only semantics. |
-| `surface.personas` | list[string] | yes | Cap = **4**. Items must appear in `.agent-src.uncompressed/personas/`. |
+| `surface.personas` | list[string] | yes | Cap = **4**. Items must appear in `.agent-src.uncondensed/personas/`. |
 | `rationale.*` | string | yes | Forces every pack to justify its composition in plain prose; reviewed at PR time, not at runtime. |
 
 ## Resolution chain
@@ -95,7 +95,7 @@ this schema.
 - **Do not** declare new commands. Use [`command-clusters`](command-clusters.md).
 - **Do not** modify rules. Use the kernel-rule edit process.
 - **Do not** override safety floors. Domain-safety rules
-  (`.agent-src.uncompressed/rules/domain-safety-*.md`) apply
+  (`.agent-src.uncondensed/rules/domain-safety-*.md`) apply
   unconditionally — packs cannot widen the deny-list.
 - **Do not** ship telemetry or usage hints. Packs are pure composition.
 
@@ -109,7 +109,7 @@ Three packs ship at Phase 2 Item 7 close:
 | `content-engine` | `content_creator` | `balanced` | Editorial calendar, brand voice, and ghostwriter on one loop. |
 | `agency-delivery` | `agency` | `strict` | Multi-client refine → estimate → deliver with audit-grade trace. |
 
-Each pack lives at `.agent-src.uncompressed/packs/<id>.yml` and is
+Each pack lives at `.agent-src.uncondensed/packs/<id>.yml` and is
 covered by the validation rules above.
 
 ## See also

package/docs/contracts/workspace-documents.md

@@ -1,3 +1,7 @@
+---
+stability: experimental
+---
+
 # Workspace Documents Contract
 
 > **Status** · v0 / design · 2026-05-24. Phase 5 of the

package/docs/customization.md

@@ -66,7 +66,7 @@ ide
 cost_profile
 personal.bot_icon
 personal.autonomy
-caveman.speak_scope
+telegraph.speak_scope
 ```
 
 **Merge order** (lowest → highest precedence; every layer optional):
@@ -179,7 +179,7 @@ is recovered on the next server boot.
 | `chat_history.enabled` | `true` | Persistent JSONL log at `agents/runtime/.agent-chat-history` for crash recovery. |
 | `chat_history.frequency` | per profile | Logging granularity: `per_turn`, `per_phase`, or `per_tool` (see matrix below). |
 | `chat_history.max_size_kb` | per profile | Max file size before overflow handling (see matrix below). |
-| `chat_history.on_overflow` | per profile | `rotate` drops oldest, `compress` marks for summarization (see matrix below). |
+| `chat_history.on_overflow` | per profile | `rotate` drops oldest, `condense` marks for summarization (see matrix below). |
 | `onboarding.onboarded` | `false` | Whether the setup wizard has run. The `onboarding-gate` rule prompts for `agent-config setup` while this is `false`. |
 | `ai_council.enabled` | `false` | Master switch for the `/council` command. Even when enabled, every consultation asks before spending tokens. |
 | `ai_council.members.<provider>.enabled` | `false` | Per-provider opt-in (`anthropic`, `openai`). Tokens live in `~/.event4u/agent-config/<provider>.key` (mode 0600), never in this file. Legacy `~/.config/agent-config/<provider>.key` is read as a fallback. |
@@ -226,7 +226,7 @@ to `false` in `.agent-settings.yml` to silence post-task analysis without
 changing the profile.
 
 The authoritative matrix of all matrix-controlled settings lives in
-[`.agent-src.uncompressed/templates/agent-settings.md`](../.agent-src.uncompressed/templates/agent-settings.md).
+[`.agent-src.uncondensed/templates/agent-settings.md`](../.agent-src.uncondensed/templates/agent-settings.md).
 
 ### Chat-history defaults per profile
 
@@ -240,13 +240,13 @@ behavior — the per-profile table is just the initial default.
 | `chat_history.enabled` | `true` | `true` | `true` |
 | `chat_history.frequency` | `per_turn` | `per_phase` | `per_tool` |
 | `chat_history.max_size_kb` | `128` | `256` | `512` |
-| `chat_history.on_overflow` | `rotate` | `rotate` | `compress` |
+| `chat_history.on_overflow` | `rotate` | `rotate` | `condense` |
 
 `custom` ignores these defaults — set every value explicitly.
 
 ### Verbosity
 
-The `verbosity:` block and `caveman.speak_scope` control how much narration
+The `verbosity:` block and `telegraph.speak_scope` control how much narration
 the agent emits around routine actions. Defaults are tuned for token
 frugality — flip values to `true` (or higher tier) to restore legacy verbose
 output. Iron-Law gates (`commit-policy`, `scope-control` git-ops,
@@ -261,10 +261,10 @@ output. Iron-Law gates (`commit-policy`, `scope-control` git-ops,
 | `verbosity.intent_announcements` | `true`, `false` | `false` | Intent announcements ("Let me check…", "Now I will…", "Found it") in skill bodies. `false` = act and emit the result. |
 | `verbosity.script_output` | `silent`, `minimal`, `verbose` | `minimal` | Stdout chatter from `scripts/*.py`, `scripts/*.sh`, and `.augment/scripts/`. `silent` = stderr only; `minimal` = one summary line per script; `verbose` = pre-Phase-10 per-step prints. Iron-Law surfaces (release confirms, install secrets prompts, error markers) ignore this key. |
 | `verbosity.taskfile_command_echo` | `true`, `false` | `false` | Suppress the `task: [name] cmd...` echo Taskfile prints before each task body. `true` = echoes preserved (legacy behaviour); `false` = `silent: true` is set on every Phase-10 safe task. |
-| `caveman.speak_scope` | `off`, `prose_only`, `aggressive` | `prose_only` | How widely caveman-speak grammar applies in chat. `off` = no caveman; `prose_only` = caveman in body prose, numbered options + Iron-Law-literal blocks stay full prose; `aggressive` = caveman everywhere except Iron-Law literals. |
+| `telegraph.speak_scope` | `off`, `prose_only`, `aggressive` | `prose_only` | How widely telegraph-speak grammar applies in chat. `off` = no telegraph; `prose_only` = telegraph in body prose, numbered options + Iron-Law-literal blocks stay full prose; `aggressive` = telegraph everywhere except Iron-Law literals. |
 
 The cross-rule index for these defaults lives in
-[`.agent-src.uncompressed/contexts/contracts/frugality-charter.md`](../.agent-src.uncompressed/contexts/contracts/frugality-charter.md).
+[`.agent-src.uncondensed/contexts/contracts/frugality-charter.md`](../.agent-src.uncondensed/contexts/contracts/frugality-charter.md).
 Writer skills (`skill-writing`, `rule-writing`, `command-writing`,
 `guideline-writing`, `roadmap-writing`, `persona-writing`,
 `agent-docs-writing`, `context-authoring`, `conventional-commits-writing`,
@@ -394,7 +394,7 @@ tarball and is the source of truth consumed by:
 > When you read "the Laravel pack", picture a filter over the shared
 > artefact tree — not a separate npm package. The day ADR-011's
 > extraction trigger flips, the same scan output drives the split;
-> until then, every artefact lives under `.agent-src.uncompressed/`.
+> until then, every artefact lives under `.agent-src.uncondensed/`.
 
 Alongside the JSON manifest, the scanner writes
 `dist/discovery/discovery-manifest.json.sha256` — a sidecar hash that
@@ -502,6 +502,26 @@ in `.agent-settings.yml`; the command then exits 0 with a one-line
 notice instead of producing a trace. Exit codes: `0` rendered or
 disabled · `1` no recent run found · `2` invocation error.
 
+## Troubleshooting
+
+### A skill appears twice in my AI tool
+
+Most common cause: cross-scope drift between a user-global install (e.g.
+`~/.claude/skills/`) and a project-local install (e.g. `./.claude/skills/`).
+Run the probe to confirm:
+
+```bash
+task probe:skills
+# or directly: python3 scripts/probe_skill_registration.py
+```
+
+The probe lists every registration across all six tools and flags
+`DUPLICATE` (same skill in ≥ 2 sources) and `DRIFT` (same skill, different
+descriptions or versions — the actual 2026-05-25 failure mode). To clean a
+stale install at the other scope: `bash scripts/cleanup_other_scope.sh --confirm`.
+Background: [`docs/contracts/skill-distribution-channels.md`](contracts/skill-distribution-channels.md)
++ [`docs/contracts/install-scopes.md`](contracts/install-scopes.md).
+
 ---
 
 ← [Back to README](../README.md)

package/docs/decisions/ADR-001-kernel-swap-deferred.md

@@ -37,7 +37,7 @@ landed in `kernel-membership.md` § 5.2:
 **Variant (a) — status quo through P2.2 + P3.1.**
 
 - Keep `agent-authority` in the kernel.
-- Keep `autonomous-execution` in `compress-and-keep` (auto-tier) per
+- Keep `autonomous-execution` in `condense-and-keep` (auto-tier) per
   `docs/contracts/rule-classification.md` § 3.2.
 - Re-evaluate the swap as a P3.2 ADR after the router schema and
   compiler ship.
@@ -47,7 +47,7 @@ landed in `kernel-membership.md` § 5.2:
 ### Accepted
 
 - 25k hard cap stays intact (no governance erosion via cap-raise).
-- 2 Iron-Law-override ADRs land in P2.2 if post-compression
+- 2 Iron-Law-override ADRs land in P2.2 if post-condensation
   measurement confirms overage (`direct-answers`, `language-and-tone`).
 - The 9-rule set carried into P2.2 is the locked § 4 list.
 
@@ -78,7 +78,7 @@ precedence at build time. At that point:
   (`docs/guidelines/agent-authority.md`) as documentation of the
   band model.
 - `autonomous-execution` can be promoted into the kernel under a
-  new ADR (ADR-N) that replaces this one, *if* its post-compression
+  new ADR (ADR-N) that replaces this one, *if* its post-condensation
   size fits the cap with no further demotion.
 
 This deferral is **not** indefinite: P3.2 ships the router compiler;
@@ -90,7 +90,7 @@ migrations) so the migration plan reflects the final kernel set.
 - **Variant (b) — swap + raise cap to 27k.** Rejected. Raising the
   hard cap mid-roadmap weakens the original 25k contract that the
   whole roadmap is built around. If 27k turns out to be the real
-  ceiling, that is a separate ADR after compression measurement
+  ceiling, that is a separate ADR after condensation measurement
   proves the band, not a pre-emptive concession.
 - **Variant (c) — swap + demote `verify-before-complete`.**
   Rejected. `verify-before-complete` carries criterion #1 (Iron
@@ -105,5 +105,5 @@ migrations) so the migration plan reflects the final kernel set.
 - `docs/contracts/kernel-membership.md` § 4, § 5.2
 - `agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json` <!-- council-ref-allowed: ADR decision trace -->
 - `agents/roadmaps/road-to-kernel-and-router.md` § Decisions, § Phase 2
-- `.agent-src.uncompressed/rules/agent-authority.md` (subject)
-- `.agent-src.uncompressed/rules/autonomous-execution.md` (proposed promotion)
+- `.agent-src.uncondensed/rules/agent-authority.md` (subject)
+- `.agent-src.uncondensed/rules/autonomous-execution.md` (proposed promotion)

package/docs/decisions/ADR-002-kernel-bucket-overrides.md

@@ -1,7 +1,7 @@
 # ADR-002 — Kernel-Bucket Cap Raise (25k → 26k) and Per-Rule Iron-Law Overrides
 
 - **Status:** Accepted (2026-05-06)
-- **Phase:** Road to Rule Kernel and Router · P2.2 (Heavy Compression)
+- **Phase:** Road to Rule Kernel and Router · P2.2 (Heavy Condensation)
 - **Supersedes:** none — extends the Council R2 amendments locked in
   `docs/contracts/kernel-membership.md` § 5.1 (median r=0.712, per-rule cap 2.5k,
   kernel-bucket 25k).
@@ -10,27 +10,27 @@
 
 ## Context
 
-P1.3 projected the post-compression kernel bucket at **23 071 chars** using
+P1.3 projected the post-condensation kernel bucket at **23 071 chars** using
 the median pilot ratio r=0.712 (3 pilots: agent-authority, direct-answers,
 language-and-tone). Pilot rules were **short to medium** (1.0k–2.5k baseline).
 
-P2.2 applied the same compression discipline to the remaining 6 kernel rules
+P2.2 applied the same condensation discipline to the remaining 6 kernel rules
 (ask-when-uncertain, commit-policy, no-cheap-questions,
 non-destructive-by-default, scope-control, plus the verify-before-complete
 auto-tier rule kept by ADR-001). Iron-Law SHA preservation verified for
 all 8 rules with Iron-Law fences (`scripts/iron_law_sha.py`).
 
-**Empirical post-compression measurements (2026-05-06):**
+**Empirical post-condensation measurements (2026-05-06):**
 
 | metric | projected | actual |
 |---|---:|---:|
 | kernel bucket sum | 23 071 | **25 590** |
-| compression ratio r (kernel-wide) | 0.712 (median pilot) | **0.795** |
+| condensation ratio r (kernel-wide) | 0.712 (median pilot) | **0.795** |
 | rules > 2.5k cap | 2 (pilots) | 6 |
 | rules > 4.0k ceiling | 0 | 0 |
 
 The actual ratio (0.795) is worse than the pilot median (0.712) because
-**longer rules compress less efficiently than short ones**: each Iron-Law
+**longer rules condense less efficiently than short ones**: each Iron-Law
 rule has a fixed payload of frontmatter, Iron-Law fence, exception
 enumeration, see-also list — shrinkage is bounded by what cannot leave
 the rule without breaking the rule's contract. The 5 longest source rules
@@ -61,7 +61,7 @@ enumeration + pre-send self-check + decline/fence semantics).
    | `direct-answers` | 2 841 | +341 | ✓ |
 
 3. **Cap stays sticky.** Future kernel additions or rule-body growth must
-   either (a) compress within the 26k bucket, (b) externalise to a
+   either (a) condense within the 26k bucket, (b) externalise to a
    `contexts/authority/*` companion, or (c) require a follow-up ADR.
 
 ## Rationale
@@ -92,23 +92,23 @@ place.
 The `commit-policy` rule was trimmed below 2.5k (2 354 chars) by removing
 a redundant cross-reference line, demonstrating that aggressive trimming
 is possible where the rule does not carry an enumeration. The 6 overrides
-are the rules where further compression would force semantic loss.
+are the rules where further condensation would force semantic loss.
 
 ## Consequences
 
 - **Pro:** Iron-Law fidelity preserved — every fence still byte-identical
   to baseline (verified by `iron_law_sha.py --all-kernel`).
-- **Pro:** Empirical compression r=0.795 documented; future kernel work
+- **Pro:** Empirical condensation r=0.795 documented; future kernel work
   uses this as the realistic ratio (not 0.712, which was a pilot-skewed
   optimum).
 - **Pro:** Override ceiling (4 000) untouched — no rule grows
   unboundedly; the 4k cap remains the next checkpoint.
 - **Con:** 25 590 / 26 000 = 98.4 % bucket utilisation. Adding any
-  10th kernel rule would require either compression of an existing rule
+  10th kernel rule would require either condensation of an existing rule
   or a further cap raise.
 - **Con:** ratio 0.795 means future "always" promotions cost more than
   Phase 1 estimated. Phase 4 token-budget measurements should treat
-  0.795 as the reference compression rate.
+  0.795 as the reference condensation rate.
 
 ## Rollback
 

package/docs/decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md

@@ -120,7 +120,7 @@ ceiling.
 
 - [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md)
   — locked cluster set + sub-command naming contract.
-- [`.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md`](../../.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md)
+- [`.agent-src.uncondensed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md`](../../.agent-src.uncondensed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md)
   — runtime routing semantics and the colon-canonical rule.
-- [`.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md`](../../.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md)
+- [`.agent-src.uncondensed/contexts/execution/roadmap-process-loop.md`](../../.agent-src.uncondensed/contexts/execution/roadmap-process-loop.md)
   — the shared mechanics that motivated the cluster shape.

package/docs/decisions/ADR-004-rule-governance-pruning.md

@@ -234,7 +234,7 @@ documentation rewrite for marginal additional savings.
   (Phase 5.4 R3 raw debate)
 - `docs/decisions/ADR-rule-kernel-and-router.md` (kernel-membership
   contract — Phase 5 changes leave kernel untouched per Lever C lock)
-- `.agent-src.uncompressed/rules/guidelines.md` (deprecated subject)
-- `.agent-src.uncompressed/rules/size-enforcement.md` (merged subject)
-- `.agent-src.uncompressed/rules/package-ci-checks.md` (demoted subject)
-- `.agent-src.uncompressed/rules/analysis-skill-routing.md` (demoted subject)
+- `.agent-src.uncondensed/rules/guidelines.md` (deprecated subject)
+- `.agent-src.uncondensed/rules/size-enforcement.md` (merged subject)
+- `.agent-src.uncondensed/rules/package-ci-checks.md` (demoted subject)
+- `.agent-src.uncondensed/rules/analysis-skill-routing.md` (demoted subject)