@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/discovery-manifest.md

@@ -1,209 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-19
----
-
-# Discovery manifest — worked-example reference
-
-> Companion to [ADR-015](../decisions/ADR-015-discovery-manifest-contract.md)
-> and [`discovery-manifest.schema.json`](discovery-manifest.schema.json).
-> The ADR is the decision; the schema is the contract; this file is the
-> worked-example reference linters, the installer, and contributors
-> cite at runtime.
-
-## Source of truth
-
-The generator
-[`scripts/build_discovery_manifest.py`](../../src/scripts/build_discovery_manifest.py)
-walks `.agent-src.uncondensed/` and emits the manifest to
-`dist/discovery/discovery-manifest.json` plus a sidecar
-`discovery-manifest.json.sha256` for tamper detection.
-
-```bash
-task build-discovery                  # regenerate the manifest
-task validate-discovery-manifest      # re-build to tempdir + diff committed
-task discovery-stats                  # pretty-print the stats block
-```
-
-`task ci` runs `build-discovery`, `validate-discovery-manifest`,
-`check-discovery-determinism`, and `check-artefact-checksums` so a
-stale committed manifest, a non-deterministic build, or a
-per-artefact checksum drift all fail CI (Phase-6 invariants).
-
-## Top-level shape
-
-```jsonc
-{
-  "version": 1,
-  "generated_at": "2026-05-21T00:00:00Z",
-  "scanner_version": "a1b2c3d4e5f6",
-  "checksum": "sha256:<64 hex>",
-  "workspaces": [ /* one entry per workspace in src/config/discovery/workspaces.yml */ ],
-  "packs":      [ /* one entry per pack in src/config/discovery/packs.yml */ ],
-  "artefacts":  [ /* sorted by path, ADR-013 frontmatter projected here */ ],
-  "unassigned": [ /* artefacts that failed assignment; reason required */ ],
-  "documented_unassigned": [ /* explicit skips from src/config/discovery/unassigned-artefacts.yml */ ],
-  "stats": { /* see below */ }
-}
-```
-
-- `version` — stays `1` for additive changes (ADR-015). Breaking → bump.
-- `generated_at` — UTC ISO-8601. **Only field allowed to differ** between
-  two determinism runs.
-- `scanner_version` — first 12 hex of `sha256(build_discovery_manifest.py)`.
-- `checksum` — `sha256:<hex>` of the JSON with `checksum` zeroed and
-  `generated_at` normalized to `"<normalised>"`.
-
-## Worked artefact entry
-
-```jsonc
-{
-  "path": ".agent-src.uncondensed/skills/laravel/SKILL.md",
-  "category": "skill",
-  "name": "laravel",
-  "workspaces": ["engineering"],
-  "packs": ["laravel"],
-  "requires": ["php"],
-  "lifecycle": "active",
-  "trust": {
-    "level": "professional",
-    "confidence": "high",
-    "human_review_required": false
-  },
-  "install": { "default": false, "removable": true },
-  "checksum": "sha256:<64 hex of normalized file content>"
-}
-```
-
-- `path` is the canonical identity. There is no `id` field — the path
-  is short, unique, and survives renames via git history (ADR-015).
-- `requires` is optional. Empty/absent → no extra pack dependencies
-  beyond the artefact's own `packs[]`.
-- `checksum` covers the on-disk bytes with frontmatter normalized
-  (sorted keys, trailing newline, no trailing whitespace). Used by the
-  Phase-3 installer for drift detection.
-
-## Worked pack entry
-
-```jsonc
-{
-  "id": "laravel",
-  "label": "Laravel",
-  "description": "PHP framework — Eloquent, Artisan, queues, jobs.",
-  "workspaces": ["engineering"],
-  "requires_hint": ["php"],
-  "trust_level_default": "professional",
-  "artefact_count": 18
-}
-```
-
-`requires_hint` is a vocabulary-side hint (lives in
-`src/config/discovery/packs.yml`); the canonical dependency edges sit on
-the artefact-level `requires` field, which the installer aggregates.
-
-## Stats block
-
-```jsonc
-{
-  "total_artefacts": 419,
-  "by_category":      { "skill": 246, "rule": 91, "command": 76, "template": 6 },
-  "by_lifecycle":     { "active": 405, "experimental": 12, "deprecated": 2, "archived": 0 },
-  "by_trust_level":   { "core": 142, "professional": 220, "experimental": 41, "advisory": 12, "restricted": 4 },
-  "unassigned_count": 0,
-  "documented_unassigned_count": 3
-}
-```
-
-Counts derive from the `artefacts[]` list — no second walk, no desync
-risk. The optional `_count` fields mirror the lengths of the
-`unassigned` and `documented_unassigned` arrays for dashboard ease.
-
-## Published files
-
-`task build-discovery` writes:
-
-| File | Purpose |
-|---|---|
-| `dist/discovery/discovery-manifest.json` | The canonical manifest. |
-| `dist/discovery/discovery-manifest.json.sha256` | Sidecar checksum of the on-disk file bytes. |
-| `dist/discovery/discovery-manifest.summary.md` | Human-readable workspace/pack summary. |
-| `dist/discovery/deprecation-report.md` | Phase-4 lifecycle report — lists every `lifecycle: deprecated` artefact with workspace / pack context. |
-| `dist/discovery/trust-report.md` | Phase-4 trust report — per-workspace breakdown of trust levels and `human_review_required` artefacts. |
-| `dist/discovery/orphan-report.md` | Phase-4 orphan report — non-experimental artefacts whose declared pack has no other members (typo signal). |
-| `dist/discovery/workspaces.json` | Phase-5 flattened workspace sub-view — per workspace, the set of packs + artefact paths visible in it. Lightweight surface for browser wizard previews. |
-| `dist/discovery/packs.json` | Phase-5 flattened pack sub-view — per pack, the artefact paths, plus `by_lifecycle` and `by_trust_level` counts. Lightweight surface for pack-picker UIs. |
-
-### Sub-view shape
-
-`workspaces.json` and `packs.json` carry the parent manifest's
-`checksum`, `generated_at`, and `scanner_version` so consumers can
-pin against the same source-of-truth version. Artefacts are
-referenced by `path` (the stable identity from the main manifest);
-there is no `id` field.
-
-```jsonc
-// workspaces.json
-{
-  "generated_at": "…",
-  "scanner_version": "…",
-  "checksum": "sha256:…",
-  "workspaces": [
-    {
-      "id": "engineering",
-      "label": "Engineering",
-      "description": "…",
-      "default_packs": ["engineering-base", "php", "laravel"],
-      "optional_packs": ["symfony"],
-      "artefact_count": 124,
-      "packs": [
-        { "id": "engineering-base", "artefact_count": 83, "artefacts": [".agent-src.uncondensed/skills/…/SKILL.md", "…"] }
-      ]
-    }
-  ]
-}
-```
-
-```jsonc
-// packs.json
-{
-  "generated_at": "…",
-  "scanner_version": "…",
-  "checksum": "sha256:…",
-  "packs": [
-    {
-      "id": "engineering-base",
-      "label": "Engineering Base",
-      "description": "…",
-      "workspaces": ["engineering"],
-      "requires_hint": [],
-      "trust_level_default": "core",
-      "artefact_count": 83,
-      "artefacts": [".agent-src.uncondensed/skills/…/SKILL.md", "…"],
-      "by_lifecycle":   { "active": 82, "experimental": 1, "deprecated": 0, "archived": 0 },
-      "by_trust_level": { "core": 83, "professional": 0, "experimental": 0, "advisory": 0, "restricted": 0 }
-    }
-  ]
-}
-```
-
-Both sub-views are byte-identical between two consecutive
-`task build-discovery` runs (modulo `generated_at`), same determinism
-guarantee as the main manifest.
-
-## Consumer guide
-
-- **Phase-3 installer** — reads `artefacts[]`, resolves `requires`,
-  verifies each file against its `checksum` before write.
-- **Browser wizard / docs site** — reads `workspaces[]`, `packs[]`,
-  `stats` to render pickers and counts.
-- **Third-party tools** — treat the schema as the contract; pin the
-  schema by `version` and watch for breaking-change ADRs.
-
-## See also
-
-- [ADR-013](../decisions/ADR-013-discovery-frontmatter-contract.md) —
-  the frontmatter contract (input side).
-- [ADR-015](../decisions/ADR-015-discovery-manifest-contract.md) —
-  the manifest contract (output side, this file).
-- [`frontmatter-contract.md`](frontmatter-contract.md) — per-artefact
-  worked frontmatter examples.

package/docs/contracts/discovery-manifest.schema.json

@@ -1,254 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://event4u.app/agent-config/schemas/discovery-manifest.schema.json",
-  "title": "Discovery Manifest",
-  "description": "Release-time scan output for @event4u/agent-config. See ADR-013 and agents/roadmaps/archive/automated-pack-workspace-and-skill-discovery.md (archived, status: completed).",
-  "type": "object",
-  "required": ["version", "generated_at", "scanner_version", "checksum", "workspaces", "packs", "artefacts", "unassigned", "stats"],
-  "additionalProperties": false,
-  "properties": {
-    "version": {
-      "const": 2,
-      "description": "Manifest schema version. Bump on breaking change. v2 (road-to-tier-removal Phase 1 / ADR-092) adds the top-level `deprecations` block; the integer command `tier` field stays emitted (non-breaking)."
-    },
-    "deprecations": {
-      "type": "array",
-      "description": "road-to-tier-removal Phase 1 / ADR-092 — machine-readable deprecation signals for keys still emitted (non-breaking) but scheduled for removal. Lets external manifest consumers migrate during the soak window before any field is dropped.",
-      "items": { "$ref": "#/$defs/deprecation" }
-    },
-    "generated_at": {
-      "type": "string",
-      "format": "date-time",
-      "description": "UTC ISO-8601 timestamp; the only field allowed to differ between determinism runs."
-    },
-    "scanner_version": {
-      "type": "string",
-      "pattern": "^[0-9a-f]{12}$",
-      "description": "First 12 hex chars of sha256(scripts/build_discovery_manifest.py)."
-    },
-    "checksum": {
-      "type": "string",
-      "pattern": "^sha256:[0-9a-f]{64}$",
-      "description": "sha256 of the JSON file with the checksum field zeroed out."
-    },
-    "workspaces": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/workspace" },
-      "minItems": 1
-    },
-    "packs": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/pack" },
-      "minItems": 1
-    },
-    "artefacts": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/artefact" }
-    },
-    "unassigned": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/unassigned" },
-      "description": "Artefacts that failed assignment. Each entry MUST carry a reason."
-    },
-    "documented_unassigned": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/unassigned" },
-      "description": "Artefacts explicitly skipped via src/config/discovery/unassigned-artefacts.yml. Each entry MUST carry a reason."
-    },
-    "stats": { "$ref": "#/$defs/stats" }
-  },
-  "$defs": {
-    "deprecation": {
-      "type": "object",
-      "required": ["key", "replacement", "since"],
-      "additionalProperties": false,
-      "description": "A single deprecated manifest key still emitted during its soak window.",
-      "properties": {
-        "key": { "type": "string", "minLength": 1, "description": "The deprecated key (e.g. `tier`)." },
-        "scope": { "type": "string", "minLength": 1, "description": "Where the key appears (e.g. `command` artefact entries)." },
-        "replacement": { "type": "string", "minLength": 1, "description": "The canonical key consumers should read instead (e.g. `visibility`)." },
-        "since": { "type": "string", "minLength": 1, "description": "The decision that deprecated it (e.g. an ADR id)." },
-        "sunset": { "type": ["string", "null"], "description": "Maintainer-owned removal date/marker; null until the soak window clears (scope-control: agents do not pin dates)." },
-        "note": { "type": "string", "description": "Human-readable migration guidance." }
-      }
-    },
-    "workspace_id": {
-      "type": "string",
-      "enum": ["engineering", "product", "finance", "founder", "gtm", "ops", "small-business", "construction", "legal-review-prep", "agent-config-maintainer"]
-    },
-    "pack_id": {
-      "type": "string",
-      "enum": [
-        "engineering-base", "php", "laravel", "symfony", "javascript", "typescript", "react", "nextjs", "python",
-        "product-basic", "product-discovery",
-        "finance-basic", "finance-advanced",
-        "gtm-sales", "gtm-marketing",
-        "ops-people", "founder-strategy", "small-business", "construction", "ai-video", "ai-image", "fun", "meta", "git", "frontend-design", "brand",
-        "memory", "analytics", "product-reasoning", "analysis-workbench", "legal-review-prep"
-      ]
-    },
-    "lifecycle": {
-      "type": "string",
-      "enum": ["active", "deprecated", "experimental", "archived"]
-    },
-    "trust_level": {
-      "type": "string",
-      "enum": ["core", "professional", "experimental", "advisory", "restricted"]
-    },
-    "workspace": {
-      "type": "object",
-      "required": ["id", "label", "description", "default_packs"],
-      "additionalProperties": false,
-      "properties": {
-        "id": { "$ref": "#/$defs/workspace_id" },
-        "label": { "type": "string", "minLength": 1 },
-        "description": { "type": "string", "minLength": 1 },
-        "default_packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" } },
-        "optional_packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" } },
-        "example_roles": { "type": "array", "items": { "type": "string", "minLength": 1 } }
-      }
-    },
-    "pack": {
-      "type": "object",
-      "required": ["id", "label", "description", "workspaces", "trust_level_default", "artefact_count"],
-      "additionalProperties": false,
-      "properties": {
-        "id": { "$ref": "#/$defs/pack_id" },
-        "label": { "type": "string", "minLength": 1 },
-        "description": { "type": "string", "minLength": 1 },
-        "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "minItems": 1 },
-        "requires": { "type": "array", "items": { "$ref": "#/$defs/pack_id" }, "description": "capability-packs.md — hard dependency graph (transitive, acyclic). Supersedes requires_hint." },
-        "requires_hint": { "type": "array", "items": { "$ref": "#/$defs/pack_id" }, "description": "Deprecated alias of `requires`, emitted during the deprecation window." },
-        "suggests": { "type": "array", "items": { "$ref": "#/$defs/pack_id" }, "description": "capability-packs.md — soft companion graph (one-hop, advisory)." },
-        "domain": { "type": "string", "minLength": 1, "description": "capability-packs.md — single primary vertical. Required for in-use packs." },
-        "size_class": { "enum": ["core", "small", "medium", "large", "platform"], "description": "capability-packs.md — per-pack visible-command budget input. Required for in-use packs." },
-        "always_on": { "type": "boolean", "description": "capability-packs.md — default pack the resolver includes in every projection regardless of profile/workspace." },
-        "cluster": { "$ref": "#/$defs/pack_id" },
-        "trust_level_default": { "$ref": "#/$defs/trust_level" },
-        "artefact_count": { "type": "integer", "minimum": 0 },
-        "human_review_required": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Phase 5 (ADR-018) — count of artefacts in this pack with trust.human_review_required=true. Zero for core-only packs."
-        },
-        "trust_summary": {
-          "type": "object",
-          "additionalProperties": false,
-          "description": "Phase 5 (ADR-018) — per-pack artefact counts broken down by trust level. Sum equals artefact_count.",
-          "properties": {
-            "core":         { "type": "integer", "minimum": 0 },
-            "professional": { "type": "integer", "minimum": 0 },
-            "advisory":     { "type": "integer", "minimum": 0 },
-            "restricted":   { "type": "integer", "minimum": 0 },
-            "experimental": { "type": "integer", "minimum": 0 }
-          }
-        }
-      }
-    },
-    "artefact": {
-      "type": "object",
-      "required": ["path", "category", "workspaces", "packs", "lifecycle", "trust", "install", "checksum"],
-      "additionalProperties": false,
-      "properties": {
-        "path": { "type": "string", "minLength": 1, "description": "POSIX path relative to repo root." },
-        "category": { "type": "string", "enum": ["skill", "rule", "command", "template", "subagent"] },
-        "name": { "type": "string" },
-        "pack": { "$ref": "#/$defs/pack_id", "description": "capability-packs.md — canonical OWNER pack (ownership/budget unit). Orthogonal to `packs` (discovery tags); the owner need not appear in `packs`." },
-        "tier": { "type": "integer", "enum": [0, 1, 2], "description": "6.0.0-C — command-surface tier surfaced on `category: command` artefacts so the CLI discovery surface reads the manifest, not a parallel catalog. DEPRECATED back-compat alias of `visibility` since ADR-090; still dual-emitted (non-breaking) but announced for removal in the top-level `deprecations` block (road-to-tier-removal Phase 1 / ADR-092). Read `visibility`." },
-        "visibility": { "type": "string", "enum": ["visible", "advanced", "internal"], "description": "ADR-090 — named command-surface visibility (visible↔tier 0, advanced↔tier 1, internal↔tier 2); the classifier source of truth. Dual-emitted alongside `tier` on `category: command` artefacts during the deprecation window." },
-        "intent": { "type": "string", "description": "6.0.0-C — command routing metadata (one-line existence justification). Present on visible command artefacts." },
-        "routes_to": { "type": "array", "items": { "type": "string" }, "description": "6.0.0-C — command routing metadata (skill/cluster-sub/command slugs the intent routes to)." },
-        "replaces": { "type": "array", "items": { "type": "string" }, "description": "6.0.0-C — command routing metadata (prior names/aliases this command absorbs; may be empty)." },
-        "slug": { "type": "string", "description": "6.0.0-D — canonical path-derived invocation slug (ADR-044; pack-stripped subpath + opt-in slug_prefix). Distinct from `name` (display, may still be colon for renames deferred to 6.1). The identity `commands ls --profile` matches on." },
-        "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "description": "Non-empty for skill/rule/command/template (enforced by build_discovery_manifest._classify). ADR-109 subagents legitimately carry [] — default-off, opt-in-by-name, never pack/workspace-scoped." },
-        "packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" }, "description": "Non-empty for skill/rule/command/template (enforced by build_discovery_manifest._classify). ADR-109 subagents legitimately carry [] — recommended for no pack; included only via include: [\"subagent:<name>\"]." },
-        "requires": {
-          "type": "array",
-          "items": { "$ref": "#/$defs/pack_id" },
-          "description": "Optional dependency edges — pack IDs the artefact transitively needs at install time. Closed vocabulary."
-        },
-        "checksum": {
-          "type": "string",
-          "pattern": "^sha256:[0-9a-f]{64}$",
-          "description": "sha256 of the artefact file content with frontmatter normalized (sorted keys, no trailing whitespace, trailing newline). Drift-detection for the Phase-3 installer."
-        },
-        "lifecycle": { "$ref": "#/$defs/lifecycle" },
-        "trust": {
-          "type": "object",
-          "required": ["level", "confidence", "human_review_required"],
-          "additionalProperties": false,
-          "properties": {
-            "level": { "$ref": "#/$defs/trust_level" },
-            "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
-            "human_review_required": { "type": "boolean" }
-          }
-        },
-        "install": {
-          "type": "object",
-          "required": ["default", "removable"],
-          "additionalProperties": false,
-          "properties": {
-            "default": { "type": "boolean" },
-            "removable": { "type": "boolean" }
-          }
-        }
-      }
-    },
-    "unassigned": {
-      "type": "object",
-      "required": ["path", "category", "reason"],
-      "additionalProperties": false,
-      "properties": {
-        "path": { "type": "string", "minLength": 1 },
-        "category": { "type": "string", "enum": ["skill", "rule", "command", "template", "unknown"] },
-        "reason": { "type": "string", "minLength": 1 }
-      }
-    },
-    "stats": {
-      "type": "object",
-      "required": ["total_artefacts", "by_category", "by_lifecycle", "by_trust_level"],
-      "additionalProperties": false,
-      "description": "Aggregate counts over the manifest. Cheap sanity surface for `task discovery-stats` and downstream dashboards.",
-      "properties": {
-        "total_artefacts": { "type": "integer", "minimum": 0 },
-        "by_category": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "skill":    { "type": "integer", "minimum": 0 },
-            "rule":     { "type": "integer", "minimum": 0 },
-            "command":  { "type": "integer", "minimum": 0 },
-            "template": { "type": "integer", "minimum": 0 },
-            "subagent": { "type": "integer", "minimum": 0 }
-          },
-          "required": ["skill", "rule", "command", "template"]
-        },
-        "by_lifecycle": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "active":       { "type": "integer", "minimum": 0 },
-            "experimental": { "type": "integer", "minimum": 0 },
-            "deprecated":   { "type": "integer", "minimum": 0 },
-            "archived":     { "type": "integer", "minimum": 0 }
-          },
-          "required": ["active", "experimental", "deprecated", "archived"]
-        },
-        "by_trust_level": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "core":         { "type": "integer", "minimum": 0 },
-            "professional": { "type": "integer", "minimum": 0 },
-            "experimental": { "type": "integer", "minimum": 0 },
-            "advisory":     { "type": "integer", "minimum": 0 },
-            "restricted":   { "type": "integer", "minimum": 0 }
-          },
-          "required": ["core", "professional", "experimental", "advisory", "restricted"]
-        },
-        "unassigned_count": { "type": "integer", "minimum": 0 },
-        "documented_unassigned_count": { "type": "integer", "minimum": 0 }
-      }
-    }
-  }
-}

package/docs/contracts/evidence-based-pruning.md

@@ -1,102 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-04
----
-
-# Evidence-based pruning contract
-
-> 6.0.0-C Phase 3 Step 7. The **rule by which a later, data-bearing roadmap
-> cuts** personas, skills, and rules — replacing the part1 feedback's arbitrary
-> targets (4 personas, halve rules, 223→120 skills) with measured thresholds.
-> **No artefact is cut by this contract or by 6.0.0-C.** This phase ships the
-> thresholds; a future roadmap, holding ≥ 30 days of telemetry, applies them.
-
-## Why thresholds, not targets
-
-The external review demanded fixed reduction numbers. The council
-(claude-sonnet-4-5 + gpt-4o, 2026-06-02) rejected them as guesses:
-
-> "Both the plan ('223 is fine') and the reviewer ('223 is too many') argue
-> maintenance burden in the absence of data. Add telemetry; decide on usage."
-
-A target says "cut to N". A threshold says "an artefact below this measured bar
-is a *candidate*, surfaced for a human merge/deprecate decision." The cut is
-always defensible because it traces to a number, and the option-value artefacts
-(rarely-loaded but load-bearing when they fire) survive unless the data says
-otherwise.
-
-## The data source
-
-The thresholds read the local-analytics events added in Step 6
-([`local-analytics.md` § Event vocabulary](local-analytics.md)):
-`rule.tier2_loaded`, `persona.cited`, `skill.activated`, plus the existing
-git-history and citation signals. Local, anonymized, opt-out, 90-day retention —
-never POSTed. A pruning pass requires **≥ 30 days** of telemetry before any
-candidate list is trustworthy; a shorter window is surfaced as "insufficient
-data", never as "unused".
-
-## Thresholds
-
-### Personas — deprecation candidate
-
-A specialist persona is a **deprecation candidate** when **both** hold:
-
-- **< 5 skill citations** — counted by `lint_persona_governance.py`'s
-  `citations_for()` (the `personas: [<id>]` frontmatter references), and
-- **< 3 commits in the trailing 12 months** — from `git log --follow` on the
-  persona file.
-
-Both, not either: a persona cited by 4 skills but actively maintained is not
-dead; a persona with 6 stale citations is not dead either. Core personas
-(`developer`, `senior-engineer`, `product-owner`, `stakeholder`,
-`critical-challenger`, `ai-agent`) are **exempt** — they are always-loaded
-cross-cutting lenses, not domain specialists (per `persona-governance`).
-
-### Skills — merge candidate
-
-A pair of skills is a **merge candidate** when **both** hold:
-
-- **> 70% content overlap** — content similarity (not name-prefix), measured by
-  the Phase 4 overlap analysis (Step 8), and
-- **same domain** — both map to the same content domain.
-
-Merge candidate ≠ merge order: the pair is surfaced for a human merge decision
-that preserves the stronger skill's triggers, examples, and anti-patterns (per
-`preservation-guard`). Scope ladders, union dispatchers, and tier-gated
-specialists that *look* similar but are intentionally distinct are kept.
-
-### Rules — prune candidate
-
-A tier-2 (router-gated) rule is a **prune candidate** when:
-
-- **< 5% load rate over 30 days** — `rule.tier2_loaded` events for the rule
-  divided by sessions in the window, below 5%.
-
-Kernel (always-on) rules are **exempt** — they are not router-gated and carry no
-load signal. A tier-2 rule that fires rarely but is load-bearing when it does
-(a safety floor, a destructive-op gate) is surfaced with its load contexts so
-the human decision sees *why* it fired, not just *how often*.
-
-## The decision is always human
-
-Every threshold produces a **candidate list**, never an automatic deletion. The
-pruning roadmap that consumes this contract:
-
-1. Runs the measurement (telemetry window ≥ 30 days + overlap analysis).
-2. Produces the candidate lists under `agents/reports/`.
-3. Surfaces each candidate with its evidence (citation count, commit count, load
-   rate, overlap pair + similarity score).
-4. A maintainer decides merge / deprecate / keep per candidate, recording the
-   rationale (ADR for structural cuts, commit message for routine ones).
-
-No artefact is deleted by a number alone. The number qualifies it as a
-candidate; the human, seeing the evidence, makes the call.
-
-## See also
-
-- [`ADR-118`](../decisions/ADR-118-loop-engineering-boundaries.md) — engagement counts stay ONE input; the pruning decision is never automated (disposition #2).
-- [`local-analytics.md`](local-analytics.md) — the measurement events + privacy floor.
-- [`capability-packs.md`](capability-packs.md) — sibling per-pack budget governance.
-- [`ADR-041`](../decisions/ADR-041-controlled-command-verbs.md) — sibling command-surface governance.
-- `lint_persona_governance.py` — persona citation counting.
-- `scripts/audit_skill_overlap.py` — skill-family overlap analysis (Step 8).