@event4u/agent-config 9.8.0 → 9.10.0

package/docs/contracts/smoke-contracts.md

@@ -1,144 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-14
----
-
-# Smoke Contracts — Phase 3 of an internal parity roadmap (local-only)
-
-> **Status:** active · **Owner:** step-11 Phase 3 · **Sibling:**
-> [`measurement-baseline.md`](measurement-baseline.md) (snapshot semantics)
-> · [`cost-enforcement.md`](cost-enforcement.md) (cost ladder)
-
-Per-tier smoke scripts validate the system's structural baselines on
-every PR that touches the tier. Each script is **fast** (≤ 30 s wall),
-**deterministic** (same input → same exit), and **measured** (baseline
-numbers come from `task smoke:*` on `main` at lock-in, not from claims).
-
-## § 1 — Runtime budget
-
-Every `scripts/smoke/<tier>.sh` honours:
-
-| Limit | Value | Rationale |
-|---|---:|---|
-| Wall time | ≤ 30 s | CI matrix slot; local dev iteration |
-| External I/O | none beyond filesystem | no network, no MCP |
-| Output | last line is the **baseline declaration** | parseable by CI summary |
-
-A smoke that approaches 30 s should be split into sub-smokes, not
-optimised in place.
-
-## § 2 — Path-trigger globs
-
-CI's `.github/workflows/smoke.yml` dispatches the right scripts based on
-the paths touched in the PR:
-
-| Tier | Globs that trigger | Script |
-|---|---|---|
-| kernel | `.agent-src.uncondensed/rules/**`, `dist/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.
-
-## § 3 — Baseline declarations (locked 2026-05-16)
-
-Smoke baselines are **measured today**, not aspirational. They lock
-**regression**: a smoke goes red only if the count drifts the wrong way.
-Drift toward the ideal (fewer breaches, more fences) updates the
-constant in the script body and the row below.
-
-### § 3.1 — Kernel (`scripts/smoke/kernel.sh`)
-
-```
-10 kernel rules · 9 carry Iron-Law fences · 1 dispatch index · ≤ 2 budget breaches
-```
-
-- **10 kernel rules** — fixed by [`kernel-membership.md`](kernel-membership.md).
-- **9 carry Iron-Law fences** — measured 2026-05-16. `agent-authority`
-  is the **dispatch index** (priority table pointing at the other four
-  authority rules); it is structurally exempt from the Iron-Law-fence
-  requirement and listed in the script's `EXEMPT_FROM_FENCE` set.
-- **≤ 2 budget breaches** — `./scripts-run src/scripts/measure_rule_budget
-  --kernel-budget-check` currently reports 2 breaches
-  (`kernel-bucket > 26000`, `no-cheap-questions > 4000`). The smoke
-  asserts the count does not grow; reductions update `EXPECTED_BREACHES`
-  in `scripts/smoke/kernel.sh`. See
-  `road-to-kernel-and-router.md`
-  for the path back to zero.
-
-### § 3.2 — Router (`scripts/smoke/router.sh`)
-
-```
-68 router ids · 0 broken rule pointers · 36 routes_to refs · 2 missing contracts
-```
-
-- **68 ids** — 10 kernel + 23 tier_1 + 35 tier_2; every id resolves to
-  `dist/agent-src/rules/<id>.md`.
-- **0 broken rule pointers** — hard assertion; smoke fails on any miss.
-- **36 routes_to refs** across tier_1 + tier_2; resolver honours the
-  four prefixes (`skill:`, `command:`, `guideline:`, `contract:`).
-- **2 missing contracts** — measured 2026-05-16:
-  `contract:artifact-engagement-flow`,
-  `contract:command-suggestion-flow`. Tracked separately under
-  ``step-11` Phase 4 (ADR layout)`;
-  smoke asserts the count is `≤ EXPECTED_MISSING_CONTRACTS=2`.
-
-### § 3.3 — Schema (`scripts/smoke/schema.sh`)
-
-```
-438 lintable artefacts · 0 schema FAILs · ≤ 92 warns
-```
-
-- **0 FAILs** — hard assertion. `scripts/skill_linter.py --all` returns
-  exit 0/1 (warns) but never 2 (fail).
-- **≤ 92 warns** — measured 2026-05-16; locks regression. Warns
-  trending down updates the constant.
-- **v2 schema (step-5) deferred** — when
-  `step-5-schema-rigor.md`
-  Phase 1 closes, this smoke gains a `model_tier` presence assertion;
-  Phase 3 adds `schema_version: "2"`. Until then, v1 schema in
-  `scripts/schemas/skill.schema.json` is the contract.
-
-### § 3.4 — Skills (`scripts/smoke/skills.sh`)
-
-```
-5/5 random skills resolve · frontmatter parses · name matches directory
-```
-
-- **5 random skills** picked deterministically (seed = epoch day) from
-  `.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`](../../src/scripts/agent-config/cmd_explain.py));
-  filesystem-resolution is the contract.
-
-## § 4 — Local invocation
-
-```bash
-task smoke            # all four
-task smoke:kernel     # individual tiers
-task smoke:router
-task smoke:schema
-task smoke:skills
-```
-
-Every script honours `SMOKE_QUIET=1` (suppresses table output, keeps
-the final baseline line) for CI summary parsing.
-
-## § 5 — Failure modes
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `kernel.sh` reports > 9 missing fences | Kernel rule lost its Iron Law block during edit | Restore the fence; update `EXEMPT_FROM_FENCE` only for new dispatch indexes |
-| `router.sh` reports > 0 broken pointers | `dist/router.json` references an id without a rule file | Add the rule or remove the route — never edit the smoke baseline up |
-| `schema.sh` reports FAILs | A skill / rule lost a required field | Restore via [`scripts/schemas/skill.schema.json`](../../src/scripts/schemas/skill.schema.json) |
-| `skills.sh` 5/5 random sample fails | Hand-edit broke frontmatter or renamed directory without updating `name:` | Restore filename ↔ slug coupling |
-
-## § 6 — See also
-
-- [`measurement-baseline.md`](measurement-baseline.md) — measurement substrate.
-- [`cost-enforcement.md`](cost-enforcement.md) — cost ladder, sibling smoke surface.
-- [`kernel-membership.md`](kernel-membership.md) — the 10-rule kernel set.
-- [`rule-router.md`](rule-router.md) — router contract.
-- `road-to-kernel-and-router.md` — kernel budget reduction path.

package/docs/contracts/subagent-boundary.md

@@ -1,74 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-17
----
-
-# Subagent Boundary Contract
-
-What a subagent **owns** and what it must **never** own. As delegation spreads
-(the `subagent-orchestration` modes, the `delegation-policy` auto-trigger,
-workflow fan-out), the failure mode is scope drift: a subagent quietly
-redefining the task, expanding scope, or bypassing a floor. This contract draws
-the line.
-
-## The ownership line
-
-A subagent **executes one scoped, named task and returns a conclusion.** That is
-the whole of its authority.
-
-### A subagent OWNS
-
-- **Its scoped task** — the single, well-specified slice it was dispatched with.
-- **Its method** — how it searches, reads, reasons, or drafts within that slice.
-- **Its return** — a conclusion + evidence, sized to what the orchestrator asked for (structured output when a schema was given).
-
-> **Explainability is durable, not host-ephemeral.** The return must carry a brief
-> *why + evidence* (which sources/steps led to the conclusion) **in the artefact /
-> output itself**, not only in the host's session reasoning. A user opening the
-> result later — possibly across sessions — must be able to trace the *why* without
-> reassembling provider chat logs. This is the reasoning-in-notes discipline applied
-> to delegation: conclusions + evidence travel with the output, raw chain-of-thought
-> does not.
-
-### A subagent must NEVER own
-
-- **Task meaning** — it does not redefine, broaden, or reinterpret the parent task. An ambiguous slice returns "ambiguous + why", it does not guess a bigger task.
-- **Cross-task memory / state** — it does not write durable memory, mutate shared roadmaps, or persist decisions for other tasks; its output is its only channel.
-- **Pack / surface decisions** — it does not decide what ships, what installs, or what a pack contains; those are orchestrator + human calls.
-- **Safety-floor bypass** — every floor applies *inside* the subagent. The Hard Floor ([`non-destructive-by-default`](../../src/rules/non-destructive-by-default.md)), the domain safety floors, [`scope-control`](../../src/rules/scope-control.md), and [`commit-policy`](../../src/rules/commit-policy.md) are not lifted by being one level down. A subagent cannot do what its parent may not.
-- **Silent scope expansion** — touching files / systems beyond its slice is a contract violation, surfaced, not absorbed.
-
-## Orchestrator obligations (the other side)
-
-- **Verify, never adopt blind** — a subagent return is evidence, not truth; the orchestrator verifies per [`delegation-policy`](../../src/rules/delegation-policy.md)'s Iron Law before adopting it.
-- **Tier-size the slice, not the agent** — dispatch at the slice's complexity, not the session's.
-- **Own the safety decision** — a Hard-Floor or egress action surfaced by a subagent is decided by the orchestrator + human, never executed by the subagent.
-- **Re-confirm; the subagent's confirmation does not count** — a destructive or irreversible mutation *proposed by a subagent* is subject to the same Hard Floor as one the orchestrator proposed, and the subagent's own "I checked, it's fine" does not satisfy the gate. Without this clause, delegation is a detour around it: ask a subagent, receive a blessing, act.
-- **Deliver the floor, do not assume it** — the floor reaches a worker because [`generate_subagent_floor.ts`](../../src/scripts/generate_subagent_floor.ts) writes it into every dispatch prompt and CI fails on drift.
-
-### Honest scope of the floor guarantee
-
-The invariant above — *a subagent cannot do what its parent may not* — is now
-**delivered** for subagents dispatched through this package's prompt templates:
-the floor is generated from the kernel rules and drift-gated. It was previously
-asserted here and carried by nothing; the brief schema, the spawn composer, and
-all eight prompt templates contained no floor text at all.
-
-What stays unproven, and is therefore not claimed: whether a subagent spawned by
-a host primitive outside these templates inherits any of it. That is a host
-property this package does not control and does not test. A contract that
-quietly covered it would repeat the exact defect this section exists to close.
-
-## Failure modes
-
-- A research subagent that, finding the task underspecified, invents a broader task and "helpfully" does it.
-- A subagent that writes to shared memory / a roadmap dashboard as a side effect.
-- A subagent that commits, pushes, or deletes because "the task implied it".
-- An orchestrator that pastes a subagent's claim into the answer without verifying it.
-
-## See also
-
-- [`subagent-orchestration`](../../src/skills/subagent-orchestration/SKILL.md) — the dispatch modes this contract bounds.
-- [`delegation-policy`](../../src/rules/delegation-policy.md) — the delegate-by-default trigger + verify-every-return Iron Law.
-- [`capability-boundary`](capability-boundary.md) — the pack-level companion (this is the agent-level one).
-- [`non-destructive-by-default`](../../src/rules/non-destructive-by-default.md) — the Hard Floor that applies inside subagents too.

package/docs/contracts/surface-agent-contracts.md

@@ -1,153 +0,0 @@
-# Surface-Agent Contracts — medium invariants, not one generic agent
-
-Backbone for `road-to-surface-specific-agent-contracts`.
-One generic agent does every medium badly. Each **surface** (spreadsheet, deck,
-document, browser, mobile/chat, code, …) has non-negotiable local invariants and
-its own verification truth source. This contract names them, maps them to owner
-skills, and defines how the agent detects a surface, resolves conflicts, and
-hands off between surfaces — advisory first (staged rollout below).
-
-Capability + honest-degrade for the *verification* primitives these contracts
-rely on is the sibling [`design-artifact-verification`](design-artifact-verification.md)
-(browser / screenshot / pdf_render / doc_export / image_decode / static_inspect);
-this contract adds the office/data primitives and the surface-routing layer.
-
-## Iron Law — the medium's truth source verifies the work
-
-```
-EACH SURFACE HAS A NON-NEGOTIABLE INVARIANT AND ITS OWN TRUTH SOURCE.
-VERIFY WITH THE MEDIUM'S TRUTH SOURCE — A FORMULA READ-BACK, A RENDERED SLIDE,
-A FETCHED PAGE — NEVER A GENERIC "LOOKS RIGHT". WHEN THE SURFACE TOOL IS
-ABSENT, SAY WHAT COULD NOT BE VERIFIED — NEVER PRETEND THE MEDIUM STEP RAN.
-```
-
-## Surface detection — before applying any surface rule
-
-Resolve the surface from these signals, in priority order:
-
-1. **Explicit file type** — `.xlsx`/`.csv` → spreadsheet, `.pptx`/`.key` → deck, `.docx`/`.md` → document, `.ipynb` → notebook.
-2. **Requested output format** — "as a deck", "export to PDF", "a spreadsheet".
-3. **Named tool / plugin / connector** — a named app connector wins over generic browsing.
-4. **User environment** — mobile/chat host vs desktop IDE vs CI.
-5. **Data shape** — tabular/numeric → spreadsheet; slides → deck; prose → document.
-6. **Task verb** — "chart", "model", "present", "browse", "refactor".
-7. **Target deliverable** — what the user will actually use.
-
-**Ambiguity handling.** When ≥2 surfaces plausibly apply and the choice changes
-the work materially, ask ONE compact question (per
-[`ask-when-uncertain`](../../src/rules/ask-when-uncertain.md)); when the user
-already constrained it, proceed and state the surface assumption.
-
-## Surface conflict rule
-
-When the user asks for output **native to a different connected surface**,
-delegate to (or ask to enable) that surface — do not force a local workaround.
-A request for a spreadsheet answered with a markdown table, or a deck answered
-with prose, is a surface violation. Prefer the connected surface; if it is
-unavailable, say so and offer the degraded form explicitly as degraded.
-
-## Surface taxonomy
-
-Each surface records: **owner** skills/commands · **allowed** tools · **forbidden**
-shortcuts · **truth source** (how the medium verifies) · **handoff** in/out ·
-**trigger** examples · **capability** requirement · **degrade** language.
-
-| Surface | Owner skills | Forbidden shortcut | Truth source | Capability → degrade |
-|---|---|---|---|---|
-| **code** | `scope-control`/`verify-before-complete` (rules), stack skills | edit unread files; broad refactor around a fix | tests + type-checker + fresh run | local exec → static-only caveat |
-| **design** | `fe-design`, `design-review`, `existing-ui-audit` | taste before inspecting the system | rendered artifact ([design-artifact-verification](design-artifact-verification.md)) | browser/screenshot → static caveat |
-| **spreadsheet** | `spreadsheet-authoring` (Phase 2) | hardcode a computed value; unofficial financial source unmarked | formula read-back after write | native tooling → exported-file only → "cannot verify" |
-| **document** | `doc-coauthoring`, `markitdown` | rasterize selectable text to PDF | open/export readback | doc parser → format caveat |
-| **deck** | `html-deck` | build slides before an outline; tiny text | export + slide render | deck export → outline-only caveat |
-| **browser** | `browser` surface (Phase 4), MCP fetch | invent a URL; fetch when not needed | the fetched page itself | fetch → "not fetched, cannot confirm" |
-| **mobile/chat** | interaction floor (Phase 5) | markdown tables in narrow chat; multi-question walls | the host's rendering | tappable UI → concise text choices |
-| **research** | `research:deep`/`research:report` | claim without a retrieved source | per-part grounding + disconfirmation | — |
-| **visualizer/diagram** | `html-deck`, image skills | decorative chart over the data's shape | the rendered diagram | render → described-structure caveat |
-| **cowork/dispatch** | `subagent-orchestration` | one agent doing parallel-safe work serially | verified subagent returns | spawn primitive → in-session |
-| **MCP/app connector** | `mcp` | generic web search when a connector fits | the connector's own result | connector present → suggest/opt-in |
-
-This taxonomy table **is** the canonical work-surface map. (Note: the existing
-`src/config/surface-matrix.yml` is a *different* concept — per-tool **install-surface**
-de-duplication, set-equality-enforced against `install.ts::USER_SCOPE_PATHS` by
-`lint_surface_matrix`; extending it with *work* surfaces would break that
-linter, so the work-surface map lives here, not there.) Host verification
-capability is `src/config/host-capabilities.yml` +
-[`design-artifact-verification`](design-artifact-verification.md). Carrier
-choice vs host capability vs these invariants stay aligned with the
-artifact-routing work — do not let the three diverge.
-
-## Staged rollout
-
-Each surface contract: **advisory** (skills reference the invariant) →
-**routed** (owner skills updated + eval fixtures pass) → **default-on** only
-once the host capability/degrade behaviour is documented for that surface. A
-contract is never default-on for a host class that cannot run the surface's
-truth-source check — it stays advisory + caveat there.
-
-## Cross-surface handoff envelope
-
-When work moves between surfaces (spreadsheet → deck, research → document,
-browser evidence → report, design prototype → production code), the source
-surface emits a **handoff envelope** the target consumes instead of redoing
-work:
-
-```
-source_surface · target_surface · user_goal · assets/files ·
-constraints · verification_already_done · pending_checks ·
-capability_limits · assumptions · privacy/source_restrictions
-```
-
-- The target surface **trusts `verification_already_done`** and does not repeat
-  it; it runs only `pending_checks`.
-- The target honours `privacy/source_restrictions` — a source-specific
-  restriction (e.g. an internal-only dataset) is never widened by the handoff.
-- **Degrade:** if the target surface's tooling is absent, the envelope remains a
-  durable **plan** (what to do + what is verified) — never a faked generated
-  artifact.
-
-## Mobile/chat interaction floor
-
-Interaction style is host-sensitive, not one verbose desktop default.
-
-- **Narrow-chat output.** Avoid markdown tables in a narrow chat host; use short
-  prose/bullets. Keep post-tool summaries short.
-- **Ask at most one compact question**, and only when it changes the work:
-  - **No options** when the user asked for the agent's *analysis* of A vs B — give the recommendation (fixture `ssac-a-or-b-analysis`).
-  - **Offer options** when *eliciting a preference* — tappable choices where the host supports them, degrading to concise text choices otherwise (fixture `ssac-preference-elicitation`).
-  - **Proceed on stated constraints** when the prompt already fixes them — no redundant questions (fixture `ssac-enough-constraints-no-question`).
-
-## Code surface — audit dispositions (Phase 6)
-
-The external code-prompt mechanisms, audited against existing rules — **covered**
-(cite the owner, do not duplicate), **tightened** (a note added), or **rejected**
-(host-specific):
-
-| Mechanism | Disposition | Owner / note |
-|---|---|---|
-| Read before proposing | **covered** | `think-before-action`, `source-discovery-gate` (fixture `ssac-edit-unread-file`) |
-| Minimal scoped changes | **covered** | `minimal-safe-diff` (fixture `ssac-broad-refactor-around-bugfix`) |
-| Todo/task visibility | **covered** | host task tooling + roadmap loop; no new rule |
-| Parallel independent exploration | **tighten** | note in `subagent-orchestration` / this contract's cowork row — sequential independent reads when parallel is available is a miss |
-| Specialized tools over shell | **covered** | `mcp` § tool-tier ladder (execution-discipline harvest) |
-| No shell as user communication | **covered** | `output-discipline` / `direct-answers` |
-| Line-specific references | **covered** | `file_path:line` convention in host instructions |
-| No time estimates | **covered** | `direct-answers` § no-duration (execution-discipline harvest) |
-| Fresh verification before "done" | **covered** | `verify-before-complete` (fixture `ssac-claim-done-without-verification`) |
-
-No new code-surface rule is created — the deltas are already owned; the one
-**tighten** (parallel-safe exploration) is recorded here + in the cowork row. No
-Codex/host-specific phrasing is adopted.
-
-## Rejected (host/vendor-specific — not adopted)
-
-Vendor-specific tool names, per-host UI affordance details, and single-provider
-prompt phrasings from the source family are **not** adopted here — this contract
-encodes surface invariants, not one vendor's tooling. Per-phase rejects are
-recorded in the roadmap.
-
-## Related
-
-- [`design-artifact-verification`](design-artifact-verification.md) — verification-primitive capability + honest-degrade (design surface).
-- [`design-artifact-lifecycle`](design-artifact-lifecycle.md) — the design surface's own lifecycle.
-- [`host-capability-manifest`](../../src/agent-src/contexts/execution/host-capability-manifest.md) — subagent primitives (cowork/dispatch surface).
-- [`tests/surface-contracts/eval-fixtures.md`](../../tests/surface-contracts/eval-fixtures.md) — the surface-contract eval fixtures.

package/docs/contracts/surface-matrix.md

@@ -1,108 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-10-06
----
-
-# Surface Matrix — per-tool canonical-surface contract
-
-> Machine-checked inventory of which install surface is canonical per tool,
-> which alternates are legitimate, what counts as a duplicate surface, and
-> how a duplicate converges. One data file replaces 23 hand-maintained
-> special cases (council Q3, 2026-07-07 — see
-> `agents/settings/contexts/claude-code-single-surface-decision.md` for the
-> parent decision).
-
-## The file
-
-`src/config/surface-matrix.yml` — ships in the npm package, resolved at
-runtime relative to the package root (works from both the tsx dev path and
-the bundled CLI).
-
-```yaml
-schema_version: 1
-tools:
-  <tool-id>:                # must exist in install.ts::USER_SCOPE_PATHS
-    surface: projection | plugin | bundles | export-only
-    scope_path: "~/..."     # must equal USER_SCOPE_PATHS[tool-id]
-    hooks: managed-settings-block | settings-hooks-opt-in | plugin | none
-    alternates:             # optional — legitimate secondary surfaces
-      - id: <slug>
-        role: <why it is legitimate>
-        detail: <prose>
-    duplicate:              # optional — the duplicate-surface class
-      description: <prose>
-      detect:
-        all_of: [<path>, …] # ~/ = user scope, ./ = package-relative;
-                            # ALL present ⇒ duplicate surface exists
-      # OR, when suspected but unverified:
-      pending_evidence: <prose + pointer to the evidence gate>
-    converge:               # required when detect is defined
-      action: <slug>
-      command: "<copy-paste fix>"
-      reaps: [<path>, …]    # package-tagged locations converge may remove
-    notes: <provenance>
-```
-
-## Semantics
-
-- **`surface`** — `projection` (installer writes content into the user
-  scope path; that projection is canonical), `plugin` (the tool's own
-  plugin channel is canonical — e.g. Copilot, where no user-scope
-  projection exists), `bundles` (manual import artifacts, e.g.
-  Claude Desktop ZIPs), `export-only` (config/marker export, no content
-  tree).
-- **`duplicate.detect.all_of`** — existence checks only, never content
-  reads. All paths present ⇒ the duplicate class is live. Tools without a
-  `detect` block are never flagged.
-- **`pending_evidence`** — documents a *suspected* class that MUST NOT be
-  acted on (doctor ignores it, converge refuses it) until an evidence gate
-  defines real detect paths. Current example: Augment
-  (`agents/settings/contexts/augment-surface-parity.md`).
-- **`converge`** — the consented cleanup. `converge.reaps` is the
-  exhaustive allowlist of what `agent-config converge` may remove for this
-  tool; anything outside it is refused (hard floor: never user-authored
-  files).
-
-## Consumers
-
-| Consumer | What it reads | Behavior |
-|---|---|---|
-| `agent-config doctor` (`surface-state` check) | `duplicate.detect.all_of` | Existence-checks every declared duplicate class; `fail` names the tool + the `converge.command` as copy-paste remedy. The legacy `claude-plugin` check stays as the named first consumer with richer version diagnostics. |
-| `agent-config converge` (+ `upgrade --converge`) | `converge.*` | Performs the per-tool cleanup, only on matrix-declared, package-tagged paths (`converge.reaps`), after consent (`install.auto_converge` or interactive y/N). |
-| `dispatch:hook` `surface-probe` concern | `duplicate.detect.all_of` | Once-per-day SessionStart existence probe; one-line nudge naming the duplicate + the converge command. Fail-open, never blocking. |
-| CI (`task lint-surface-matrix` → `src/scripts/lint_surface_matrix.ts`) | whole file | Set equality with `USER_SCOPE_PATHS`, scope-path drift, enum validity, detect-path resolution, converge-command presence, plugin-id drift guard. |
-
-## Onboarding a new tool
-
-1. Add the tool to `install.ts::USER_SCOPE_PATHS` (and `SCOPE_SUPPORT`,
-   deploy sources) as usual.
-2. Add the matrix entry in the same commit — `lint-surface-matrix` fails
-   the build on a missing entry (that is the point: no tool ships without
-   a declared canonical surface).
-3. Default shape for a plain projection with no plugin channel:
-   `surface: projection`, `hooks: none`, no `duplicate` block.
-4. Only add a `duplicate` block when a second install channel actually
-   exists for the tool — and only add `detect.all_of` once the class has
-   been reproduced on a real setup (evidence gate; until then use
-   `pending_evidence`).
-
-## Consent model (converge)
-
-- First `agent-config converge` run persists `install.auto_converge: true`
-  into the **global** settings file
-  (`~/.event4u/agent-config/agent-settings.yml`). The key is read directly
-  by the CLI (converge/upgrade); it is intentionally NOT part of the
-  `MERGEABLE_KEYS` whitelist — it never merges into project-level agent
-  settings and never reaches session context.
-- Plain `upgrade` without the key keeps the print-only prompt (no silent
-  mutation of a user-owned surface — council Q2, 2026-07-07).
-- `converge --dry-run` prints the exact actions without touching anything.
-
-## See also
-
-- `agents/settings/contexts/claude-code-single-surface-decision.md` —
-  parent decision (single surface for Claude Code).
-- `agents/settings/contexts/augment-surface-parity.md` — the Augment
-  evidence gate that keeps its duplicate class `pending_evidence`.
-- `docs/contracts/skill-distribution-channels.md` — canonical-channel
-  contract the matrix operationalizes.

package/docs/contracts/surface-tiers.md

@@ -1,81 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-15
----
-
-# Surface tiers — core vs lab
-
-Every shipped artefact carries a **surface tier** so lab churn cannot
-destabilise the lean engine users install (road-to-install-contract-stability
-Phase 2).
-
-- **`core`** — the lean stable multi-host engine: rules + skills + install +
-  condensation, plus the engineering/authoring packs and the script tooling
-  that build and ship them. This is the adoptable surface.
-- **`lab`** — experimental / pilot meta-tooling that must not ride the same
-  release train as the core: AI media pipelines, the multi-model council, the
-  MCP server, prediction-pool, cost analytics, chat-history, benchmarking.
-
-The split is council-locked (2026-06-17, claude-sonnet-4-5 + gpt-4o, design
-mode, full convergence). Where it lives:
-
-- **Packs/domains** carry `surface_tier: core | lab` in their `pack.yaml`
-  manifest (default `core`; sourced from `src/config/discovery/packs.yml`).
-- **`src/scripts/` clusters** are mapped in
-  [`src/scripts/surface-tiers.yml`](../../src/scripts/surface-tiers.yml)
-  (exhaustive over cluster directories).
-- A **boundary guard** (`scripts/check_surface_tiers.py`) asserts the registry
-  is exhaustive and that no `core` module hard-imports a `lab` module.
-
-## Pack / domain tiers
-
-| Pack / domain | Tier | Reason |
-|---|---|---|
-| engineering-base, git, php, laravel, symfony | core | framework-neutral engineering hygiene + language patterns |
-| javascript, typescript, react, nextjs, python | core | language / framework pattern packs |
-| frontend-design, brand | core | design-intelligence + brand-consistency corpus |
-| product-basic, product-discovery | core | PO/PM + discovery surface |
-| finance-basic, finance-advanced | core | cash/runway + valuation cognition |
-| gtm-sales, gtm-marketing | core | pipeline + positioning surface |
-| ops-people, founder-strategy, small-business, construction | core | stable role/vertical packs |
-| analysis-workbench | core | RCA / post-mortem learning loop, no lab deps |
-| meta, memory, analytics, product-reasoning | core | always-on maintainer engine |
-| **ai-video** | **lab** | AI video pipeline, `trust_level_default: experimental` |
-| **ai-image** | **lab** | AI image generation, `trust_level_default: experimental` |
-| **fun** | **lab** | prediction-pool tips, non-essential, experimental |
-
-## Script-cluster tiers
-
-Authoritative map: [`src/scripts/surface-tiers.yml`](../../src/scripts/surface-tiers.yml).
-
-| Cluster | Tier | Reason |
-|---|---|---|
-| `_cli`, `_lib` | core | install / condense / CLI engine |
-| `adr`, `config`, `hooks`, `schemas`, `skill_tools`, `tools`, `smoke`, `repro` | core | engine tooling: ADR, discovery vocab, hooks, schemas, linters, fixtures |
-| `ai_council` | lab | multi-model council orchestration, external API deps |
-| `mcp_server` | lab | MCP stdio server, separate runtime, pilot distribution |
-| `media`, `ai-video`, `ai-image` | lab | AI media adapters + shared substrate (experimental consumers only) |
-| `command_suggester` | lab | context-aware suggestion engine, pilot; no core caller |
-| `prediction-pool` | lab | prediction-pool optimizer (fun pack) |
-| `cost` | lab | cost tracking / budget gate, observability (not a core/CI dep) |
-| `_archive` | lab | archived / deprecated scripts |
-
-Top-level lab scripts (`council_cli`, `chat_history`, `mine_session`,
-`mcp_render`, `bench_ab_*`, `cost_*`, `build_cloud_bundle`,
-`build_linear_digest`, `build_mcp_registry_manifest`, `memory_report`,
-`memory_signal`, …) are listed under `lab_modules` in the registry; every other
-top-level script defaults to `core`.
-
-## Core → lab coupling
-
-The boundary guard forbids a `core` module from **hard**-importing a `lab`
-module. A `try/except ModuleNotFoundError` *optional* import is allowed —
-core degrades gracefully when lab is absent. The only existing core→lab edges
-are three such guarded optional imports (`_lib/knowledge_global_redaction.py`
-and `_cli/cmd_doctor.py` → `ai_council`); they are tolerated by design.
-
-## See also
-
-- [`install-layout.md`](install-layout.md) — the install-ABI freeze this split builds on.
-- [`src/scripts/surface-tiers.yml`](../../src/scripts/surface-tiers.yml) — the cluster registry.
-- [`docs/architecture.md`](../architecture.md) — core vs full install (the consumer-facing framing).

package/docs/contracts/telegraph-telemetry.md

@@ -1,83 +0,0 @@
----
-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`](../../src/scripts/telegraph_stats.py) — reads
-  this constant, computes per-session / per-conversation / lifetime
-  deltas from `agents/cost-tracking/sessions.jsonl`.
-- [`scripts/cost_summary.py`](../../src/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.