@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/STABILITY.md

@@ -1,188 +0,0 @@
----
-stability: stable
----
-
-# Stability policy for `docs/contracts/`
-
-This directory ships the **public contract surface** of `agent-config`.
-Every file here declares a stability level in YAML frontmatter:
-
-```yaml
----
-stability: stable | beta | experimental
----
-```
-
-The level dictates how the contract may be linked from the public
-surface (README, AGENTS.md, `docs/architecture.md`) and what kind of
-change to it requires what kind of release.
-
-## Levels
-
-### `stable`
-
-- **Breaking change** requires a **SemVer-major** bump (`X.0.0`).
-- README, AGENTS.md, and `docs/architecture.md` MAY link to it
-  without a marker.
-- Typical content: settled ADRs (decisions don't reopen without a
-  successor ADR); fully released contracts that have shipped through
-  one major release without breaking.
-
-### `beta`
-
-- **Breaking change** is allowed in a **minor-version** release
-  (`1.X.0`), provided the change appears in `CHANGELOG.md` under a
-  `### Breaking` heading.
-- README, AGENTS.md, and `docs/architecture.md` MAY link to it,
-  **provided** the link text or the surrounding sentence carries a
-  visible `(beta)` marker.
-- Typical content: flow contracts and recipes that are shipped and
-  load-bearing, but whose surface is expected to evolve before a
-  SemVer-major lock.
-
-### `experimental`
-
-- **Breaking change** is allowed in **any release** (including
-  patches), with a CHANGELOG note.
-- README, AGENTS.md, and `docs/architecture.md` MUST NOT link to
-  experimental contracts. Only the index inside `docs/contracts/`
-  may reference them.
-- Typical content: spike artefacts, runtime modules in pilot status,
-  early API drafts not yet wired into a roadmap-locked phase.
-
-## Frontmatter requirement
-
-Every `*.md` under `docs/contracts/` (except this `STABILITY.md` file
-itself) MUST start with a YAML frontmatter block declaring `stability:`.
-
-The link checker (`scripts/check_public_links.py`, P0.1b) reads this
-frontmatter and:
-
-- **fails CI** when README / AGENTS.md / `docs/architecture.md` links to
-  a contract marked `experimental`, to a missing target, or into
-  `agents/settings/contexts/` (internal surface).
-- **warns** (non-fatal in default mode; fatal under `--strict`) when a
-  public-surface link to a `beta` contract has no `(beta)` marker in
-  the surrounding text.
-- ignores `stable` links.
-
-Run `task check-public-links` locally; `task ci` invokes the same
-checker in default mode.
-
-## Promotion path
-
-`experimental → beta → stable`. Demotion is allowed (e.g. `stable →
-beta` to permit a refactor) but appears in `CHANGELOG.md` under
-`### Breaking` and gets a SemVer-major bump.
-
-Promotion criteria:
-
-- `experimental → beta` — at least one shipped roadmap phase has
-  consumed the contract end-to-end without a breaking change.
-- `beta → stable` — at least one SemVer-minor release has shipped
-  with the contract unchanged, or the contract has been explicitly
-  frozen as part of a roadmap step.
-
-## Beta-review markers
-
-Every `stability: beta` contract MUST carry exactly one of the
-following frontmatter markers (audit-acceptance for the periodic beta
-review; see `road-to-productization.md` § P5.4):
-
-| Marker | Shape | Meaning |
-|---|---|---|
-| `promote-to: stable` | literal | Contract has been ≥ 30 days in beta, zero breaking changes in the last 14 days, ≥ 1 consumer reference. Schedule promotion in the next release. |
-| `keep-beta-until: YYYY-MM-DD` | ISO date | API still moving or consumer count = 0. Date is the next review deadline (max 90 days from the last review). |
-| `superseded-by: <contract-id>` | string | Replaced by a stable contract. Slated for deprecation, not deletion. |
-
-The audit is repeated whenever the `keep-beta-until` date passes for
-≥ 25 % of beta contracts, or at the start of any roadmap phase that
-touches the contract surface.
-
-## Current contracts
-
-See the file headers themselves for current levels. The frontmatter is
-the authoritative source — this list is illustrative, not load-bearing,
-and is generated by `scripts/check_public_links.py --list`.
-
-## Budget contracts
-
-Numeric caps on the always-active rule surface. These are **load-bearing
-constants** — every reply the agent emits pays the always-rule cost, so
-the budget is part of the public contract, not an implementation detail.
-
-The accounting model since Phase 0.2 of `road-to-structural-optimization`
-is **Model (b) literal** — a rule's effective size is its own char count
-plus every context it loads (transitively, depth ≤ 2). See
-[`load-context-budget-model.md`](load-context-budget-model.md) (beta)
-for the contract and the transitional allowlist.
-
-| Constant | Value | Stability | Owner |
-|---|---|---|---|
-| Total always-rule budget | **49,000 chars** (extended) | `stable` | `tests/test_always_budget.py::test_always_rules_total_extended_within_tolerance` |
-| G3 tolerance band | **2 % overshoot** (≤ 49,980 chars) | `beta` | `scripts/check_always_budget.py` · `tests/test_always_budget.py` |
-| Warn threshold (CI) | **80 % (39,200 chars)** | `beta` | `scripts/check_always_budget.py` |
-| Fail threshold (CI) | **90 % (44,100 chars)** below 100 %; **> 102 %** above | `beta` | `scripts/check_always_budget.py` |
-| Per-rule cap | **6,000 chars** (extended) with transitional allowlist | `beta` | `tests/test_always_budget.py::test_no_unallowlisted_per_rule_breach` · `scripts/check_always_budget.py` |
-| Top-3 combined cap | **24,500 chars** (extended, 50 % of total) | `beta` | `tests/test_always_budget.py::test_top3_extended_under_cap` · `scripts/check_always_budget.py` |
-| `load_context:` nesting cap | **depth ≤ 2** | `beta` | `tests/test_always_budget.py::test_load_context_depth_within_cap` · `scripts/check_always_budget.py` |
-
-**Promises a consumer can rely on:**
-
-- The total budget will not silently grow. A bump to `TOTAL_CAP`
-  requires a `### Breaking` CHANGELOG entry and a SemVer bump per the
-  `stable` policy above.
-- The CI gate (`task check-always-budget`, run on every PR) prevents
-  drift toward the cap without a maintainer noticing — the warn/fail
-  thresholds give two PR-cycles of advance notice before the wall.
-- Per-rule and top-3 caps prevent a single monster rule re-emerging
-  under the global cap. The current per-rule cap is `beta` because the
-  numbers are still being tuned against real-world rule churn; promotion
-  to `stable` follows one SemVer-minor cycle without a tightening or
-  loosening change.
-
-**What's intentionally not promised:**
-
-- The exact composition of the top-5 set. Rules may be split, merged,
-  or relocated to `contexts/` between releases as long as the global
-  and per-rule caps still hold.
-- The condensed-vs-uncondensed delta. The CI gate runs against the
-  shipped `dist/agent-src/` (condensed) directory; the uncondensed
-  source size is informational only.
-
-## Schema versioning and structural breaking changes
-
-The breaking-change gate is **two-layered** so it does not depend on
-author discipline alone:
-
-1. **Commit-annotation layer (`release.py`).** `infer_bump` reads the
-   Conventional-Commits annotation (`<type>!:` bang or a
-   `BREAKING CHANGE` line) and returns a major bump when present.
-2. **Structural layer (`check_structural_breaking.py`, run in
-   `task ci-fast`).** Independently of the commit message, the detector
-   inspects the diff against the trunk and FAILS when a structural break
-   is present *without* an annotation — forcing the annotation to exist.
-
-A change is **structurally breaking** when either:
-
-- a tracked artifact *source* file is **deleted or renamed** — a skill
-  `SKILL.md`, a rule, a command `command.md`, a pack manifest, or a
-  contract schema; or
-- a contract schema under `src/scripts/schemas/` is **modified without
-  bumping its `x-schemaVersion`**. The four contract schemas (`pack`,
-  `skill`, `rule`, `command`) carry an `x-schemaVersion`. Bump it when an
-  enum value is added or removed, a field type changes, or a validation
-  rule tightens — these are breaking-for-consumers yet invisible to a
-  name-status diff. Purely *additive* schema changes (a new optional
-  field) do not require a bump.
-
-Escape for an intentional break (e.g. a deprecation cycle completing):
-add `ci-override: structural-breaking-ok` to a commit body. The detector
-accepts ~20% false-negatives on purely *semantic* breaks (behaviour
-change with no artifact/schema delta); the structural + schema + commit
-cross-check reaches ~95% coverage (2026-06-16 council).
-
-## See also
-
-- [`docs/architecture.md`](../architecture.md) — package architecture overview
-- [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) — which always-rule wins on conflict

package/docs/contracts/adoption-signal-floor.md

@@ -1,127 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-26
-roadmap_ref: road-to-adoption-proof-and-ci-green.md
----
-
-# Adoption Signal Floor
-
-> **Status** · v0 / beta · 2026-05-26. Phase D Step 1 of
-> the `road-to-adoption-proof-and-ci-green` roadmap (archived).
-> Defines the privacy-floor for adoption-signal collection — what
-> the package may measure, what it may NOT, and the opt-in gate
-> consumer-side telemetry would need to clear before it could ship.
-
-## The Iron Law
-
-```
-LOCAL-ONLY BY DEFAULT. NO CONSUMER TELEMETRY. NO PER-USER DATA.
-NO CROSS-PROJECT CORRELATION. ANY SIGNAL THAT LEAVES A CONSUMER
-MACHINE IS EXPLICITLY OPT-IN, NEVER ON BY DEFAULT.
-```
-
-The package's adoption story is told through **public surfaces only**
-— npm registry counters, GitHub public-API metrics, registry-listing
-status. The consumer's machine stays opaque to the maintainer unless
-the consumer opts in explicitly and the contract names the opt-in
-gate.
-
-## Allowed signals — public sources only
-
-All four signals below come from public APIs and require no
-consumer-side instrumentation. The roadmap's Phase D Step 2
-collector (`scripts/adoption_snapshot.py`) pulls them into a single
-weekly snapshot.
-
-| Signal | Source | Refresh cadence | Privacy posture |
-|---|---|---|---|
-| **npm install count** | npm registry API (`https://api.npmjs.org/downloads/`) | Daily granularity; we snapshot weekly. | Public. Aggregated across all installs; no IP / user identification possible from this surface. |
-| **npm version distribution** | npm registry API (`https://registry.npmjs.org/@event4u%2Fagent-config`) | Per-publish; we snapshot the latest version on each cron. | Public. Reveals which versions are still being pulled, not who pulls them. |
-| **GitHub stars / forks** | GitHub REST API (`/repos/event4u-app/agent-config`) | Snapshot-on-demand. | Public. GitHub already exposes the count on the repo page. |
-| **Topic-search rank** | GitHub search API (`/search/repositories?q=topic:agent-skills` and `topic:cinematic-ai-video`) | Snapshot-on-demand. | Public. Surfaces where the package lands in topic-based discovery. |
-
-The collector stores one dated JSONL row per cron run at
-`agents/runtime/metrics/adoption-snapshots.jsonl`. The file is
-local-only — it never leaves the consumer's CI runner; the project
-publishes only the rolled-up `adoption-report.md` (see Phase D
-Step 3).
-
-## Disallowed signals — never collected, never on-by-default
-
-The four classes below would violate the Iron Law. They are listed
-explicitly so the boundary is unambiguous:
-
-1. **Consumer-side telemetry.** Any signal that originates on a
-   consumer's machine — CLI invocation count, error rates,
-   feature-use counters, prompt token counts, install-success-on-OS
-   metrics — is **forbidden** without an explicit opt-in flag
-   the consumer sets per-install.
-2. **Per-user data.** Even aggregated, the package does not collect
-   anything that can identify an individual (email, IP, machine
-   fingerprint, hostname). The aggregate-only carve-out does not
-   apply to anything narrower than country-level.
-3. **Cross-project correlation.** Two consumer projects that both
-   install the package must never be linkable through any signal
-   the package emits. (npm install counts are aggregated by npm
-   itself; the package does not retain or correlate them.)
-4. **Outbound network from the package runtime.** No `fetch()`,
-   no `requests.post()`, no `httpx.post()` to a maintainer-side
-   endpoint. The package's `0` outbound calls posture is a feature.
-
-## Opt-in gate — what consumer-side telemetry would need
-
-Should a future phase want to add consumer-side telemetry (for
-example, anonymous error reporting), each of the four gates below
-must clear before the code lands:
-
-| Gate | Requirement |
-|---|---|
-| **Explicit opt-in flag** | A consumer-side environment variable or `.agent-settings.yml` field defaulting to `false`. Never on at install time. |
-| **Per-event consent UX** | The first time the flag flips, the agent / CLI prints a one-screen explanation of what is collected and a y/N confirmation prompt. |
-| **Local-first storage** | Every emitted event must land on disk first (so the consumer can read it before it leaves); upload is a separate later step. |
-| **Maintainer-controlled receiver** | The receiving endpoint is maintainer-owned, documented in `docs/contracts/`, and reviewed by `domain-safety-pii` + `data-handling-judgment` before any code points at it. |
-
-Until all four gates are written and reviewed, consumer-side
-telemetry is **forbidden** even as a discussion item in roadmaps.
-
-## Extraction demand gate — lint_originality standalone probe
-
-Added 2026-07-20 (road-to-originality-gate-and-contributor-funnel Phase 3,
-council 2026-07-20: extraction is demand-gated; the floor IS the demand gate,
-applied post-probe). Uses **allowed public signals only** — inbound GitHub
-issues/PRs and their authors; no consumer telemetry, consistent with the Iron
-Law above.
-
-| Field | Value |
-|---|---|
-| **Probe surface** | [`docs/anti-reskin-gate.md`](../anti-reskin-gate.md) — run-from-clone recipe + signal instructions |
-| **Signal definition** | A distinct external (non-maintainer) GitHub account opening an issue titled `anti-reskin gate: standalone request`, or referencing `lint_originality` in an inbound issue/PR about their own catalog |
-| **Floor** | ≥ 3 distinct external signals |
-| **Window** | 90 days from the probe page landing on `main` |
-| **Floor met** | Extract `lint_originality` as a standalone zero-config npx package (`--changed` mode, no repo coupling, regression suite included); npm publish remains a maintainer decision (name, scope, moment) |
-| **Floor missed** | Extraction **cancelled** — recorded via decision-record; not relitigated without new evidence |
-
-## Re-audit cadence
-
-Re-audit on each of:
-
-- A new adoption signal (proposed for the collector).
-- A consumer asks for a feature that would require knowing how they
-  use the package — the answer is "we don't collect that; here is
-  how the existing public signals approximate it".
-- Quarterly check against the Phase D Step 4 trend snapshot — if
-  the existing four signals stop tracking adoption faithfully, the
-  question is "add a new public signal" never "add consumer
-  telemetry".
-
-## See also
-
-- [`scripts/adoption_snapshot.py`](../../src/scripts/adoption_snapshot.py)
-  — the collector for the four public signals.
-- `domain-safety-pii` rule — the redaction floor any future opt-in
-  telemetry would inherit.
-- `data-handling-judgment` skill — the regulatory read for any
-  cross-border data flow.
-- [`registry-submissions.md`](../distribution/registry-submissions.md)
-  § Adoption-tracking signal — how the snapshot trend interacts
-  with the registry-row status counters.

package/docs/contracts/adr-architectural-consensus-mechanism.md

@@ -1,68 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# ADR — Architectural Consensus Mechanism (bus-factor / multi-author readiness)
-
-> **Status:** Decided · 2026-05-14
-> **Context:** v2 council finding C1 (file [01-bus-factor-and-consensus.md](../../agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md)) flagged that a single-author skill suite cannot detect ontology drift (two skills with overlapping triggers, drift between description and body, generic best-practice patterns repeated across clusters). The package needs a **mechanical consensus signal** that does not depend on the original author's judgment. <!-- council-ref-allowed: ADR decision trace -->
-> **Roadmap:** Closes Phase 5.2 of the v2 feedback follow-up roadmap
-> (see `agents/roadmaps/`).
-
-## Decision
-
-A **two-tier consensus mechanism**, layered by cost:
-
-1. **Tier A — Automated ontology lint (every PR).** `scripts/skill_collision_clusters.py` produces `agents/runtime/reports/skill-collision-clusters.json`. New skills that fall into an existing collision cluster (description-vector similarity ≥ threshold or trigger-keyword overlap ≥ threshold) **break the build** unless paired with one of:
-   - A routing rule (tier-2a path-prefix or tier-3 keyword) that declares ownership, OR
-   - An ADR under `docs/contracts/adr-*.md` that names the trade-off.
-2. **Tier B — ADR on first collision (per cluster, not per skill).** When Tier A flags a new collision and the author chooses to keep both skills, they write a one-page ADR naming what each skill owns and where the boundary lives. The ADR is **per cluster**, not per skill — adding a fourth `php-*` skill to an established `php-*` cluster does not require a new ADR; only the cluster's first ADR matters.
-
-Tier C (external review per N skills) is **rejected** as standing process; it is reserved for major-version boundaries (v3, v4) where the host wants a one-shot external sanity pass.
-
-## Why this was a real question
-
-The three options from feedback file 01 were:
-
-| Option | Cost | Detection power | Failure mode |
-|---|---|---|---|
-| (a) ADR per cluster | medium author cost, near-zero CI cost | high once written, zero before | author forgets to write the ADR; drift accumulates silently |
-| (b) Automated ontology lint | low marginal cost per PR, one-time build cost | catches collisions at PR time; no semantic depth | flags noise (similar descriptions that own different surfaces); needs threshold tuning |
-| (c) External review per N skills | high USD + calendar cost | high but lagged | gate fires too late; expensive |
-
-Picking only (a) means the gate fires after the drift has already shipped (review of a written ADR ≠ detection of a missing ADR). Picking only (b) means the lint surfaces a number but the human still has to decide what to do with it. Picking only (c) means the gate fires once per quarter at best and costs real money.
-
-The two-tier choice is the convener-skeptic synthesis: **(b) is the always-on gate, (a) is the high-signal moment (b) creates.** (c) stays reserved for the moments where neither (b) nor (a) can answer — and those moments are rare enough not to warrant standing process.
-
-## Consequences
-
-- **Author cost (steady-state):** zero. The lint runs in CI; the author only writes an ADR when they introduce a new cluster head.
-- **Author cost (when collisions land):** one ADR per cluster, ~150-300 lines.
-- **CI cost:** O(skills²) similarity scan; current 210 skills → ~22k pairs scanned at ms-each. Acceptable for `ci-fast`.
-- **Reviewer cost:** the cluster ADR is the single review surface — reviewers don't have to re-derive the cluster boundary on every PR touching the cluster.
-- **What this does not catch:** drift between a skill's description and its body. That is a different problem, addressed by `audit-descriptions` / `lint-skills` (already in CI).
-- **What this does not replace:** the `skill-quality` Iron-Law rule (every skill must be executable, validated, self-contained) and `description-assist` (push-toward-trigger phrasing). Those remain author-time obligations.
-
-## Rejected alternatives
-
-- **(c) alone — external review per N skills.** Too expensive as standing process; gate fires too late to prevent drift.
-- **Tier A as warn-only forever.** Defeats the purpose — drift accumulates if there is no fail-the-build state.
-- **Persona-prompted self-review** (host runs sibling models). Rejected by `ai-council` skill (council convergence, 2026-05-06): same model, same blind spots, more cost.
-
-## Acceptance test
-
-- [x] `scripts/skill_collision_clusters.py` exists and emits `agents/runtime/reports/skill-collision-clusters.json`
-- [x] `scripts/score_skill_selection.py` exists and emits `agents/runtime/reports/skill-selection-accuracy.json`
-- [x] Phase 3 routing rules (`laravel-routing`, `symfony-routing`, `copilot-routing`, `devcontainer-routing`) demonstrate the tier-B response to a flagged cluster
-- [ ] Lint promoted to `fail-the-build` once thresholds are confirmed stable across one full release cycle (currently `warn-only`)
-
-The final acceptance gate (lint going from warn-only to fail-the-build) is deferred to the next release window so the threshold has time to settle without breaking PRs on borderline noise. Tracked as a follow-up in the next step-N roadmap.
-
-## Related
-
-- Origin: [`agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md`](../../agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md) <!-- council-ref-allowed: ADR decision trace -->
-- Mechanical scripts: [`scripts/skill_collision_clusters.py`](../../src/scripts/skill_collision_clusters.py), [`scripts/score_skill_selection.py`](../../src/scripts/score_skill_selection.py)
-- Sibling decision: [`docs/contracts/rule-router.md`](rule-router.md) — the routing layer the ADR feeds
-- Sibling decision: [`docs/contracts/multi-tool-projection-fidelity.md`](multi-tool-projection-fidelity.md) — Phase 4 of the same roadmap
-- Standing skill: [`.augment/skills/ai-council/SKILL.md`](../../.augment/skills/ai-council/SKILL.md) — the explicit-opt-in path for the rare moments tier C is invoked

package/docs/contracts/adr-chat-history-split.md

@@ -1,140 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# ADR — Chat-history rule split
-
-> **Status:** Superseded · 2026-05-04 · by
-> [`agents/settings/contexts/chat-history-platform-hooks.md`](../../agents/settings/contexts/chat-history-platform-hooks.md).
-> The cooperative three-rule split this ADR locked in
-> (`chat-history-ownership` / `-cadence` / `-visibility`) has been
-> reduced to a hook-only structural artifact. The three always-rules,
-> the heartbeat marker, and the Foreign-Prompt handshake are gone;
-> `session_start` hooks auto-adopt foreign sessions silently. The text
-> below is preserved for historical context only.
->
-> **Original status:** Decided · 2026-05-02
-> **Context:** AI #1, AI #3, AI #5 review of PR #29 flagged the
-> 200-line monolithic `rules/chat-history.md` as the rule the agent
-> revisited 12+ times during the 1.14.0 cycle — three independent
-> concerns coupled into one Iron Law block.
-> **Builds on:** [`adr-implement-ticket-runtime.md`](adr-implement-ticket-runtime.md)
-> — engine path was added to the existing rule mid-flight, which
-> exposed the coupling.
-> **Defers to:** Phase 2 P2.9 (memory-visibility surface) for the
-> reuse of the heartbeat plumbing.
-
-## Decision
-
-`rules/chat-history.md` is split into **three sibling `always` rules**,
-each owning one orthogonal concern and a clear single Iron Law:
-
-| Rule | Iron Law owned | What it answers |
-|---|---|---|
-| `chat-history-ownership.md` | Foreign/Returning/Missing handshake — whose file is this? | Activation, two-paths table (HOOK/ENGINE/CHECKPOINT/MANUAL), Foreign/Returning prompts |
-| `chat-history-cadence.md` | turn-check + append gates — when to write? | Turn-start gate, append cadence (`per_turn`/`per_phase`/`per_tool`), `OWNERSHIP_REFUSED` handling |
-| `chat-history-visibility.md` | Heartbeat marker — how does the user see drift? | Heartbeat invocation, `on`/`off`/`hybrid` modes, memory-typing-the-marker hard-rule |
-
-The original `rules/chat-history.md` is deleted. Cross-references
-across the three splits are explicit one-line backlinks at the top of
-each file. The CHECKPOINT-path Iron Law (the three-gate block) is
-re-anchored: ownership owns gate 1 (turn-check), cadence owns gate 2
-(append), visibility owns gate 3 (heartbeat).
-
-## Why this was a real question
-
-Three options were on the table:
-
-1. **Leave the monolith, add sub-section index.** Rejected: the
-   12-iteration churn was on individual sub-sections (heartbeat
-   visibility modes, foreign/returning prompts, cadence frequencies)
-   touching unrelated parts of the file. Index doesn't separate
-   concerns; it only renames the problem.
-2. **Move the Iron Law block to a context doc, leave the rule as a
-   thin pointer.** Rejected: contexts are reference, rules are
-   triggers — the three gates ARE the trigger surface. Demoting them
-   to context bleeds enforcement.
-3. **Three sibling rules, one concern each (chosen).** Adopted
-   because each concern has a distinct lifecycle: ownership is a
-   first-turn handshake (rare event, high stakes), cadence is per-
-   phase (high frequency, low stakes per write), visibility is per-
-   reply (every turn, observability-only). Coupling them produced the
-   "memory-typing the marker" failure mode we hardened against in
-   1.14.0 — separating them makes future hardening surgical.
-
-## Sizing & always-rule budget
-
-Pre-split: `chat-history.md` = 201 lines. Always-rule budget pre-split = 2207 lines across 18 rules.
-
-Post-split target (frontmatter + cloud-behavior + interactions
-sections triplicated):
-
-| File | Target lines |
-|---|---:|
-| `chat-history-ownership.md` | ≤ 95 |
-| `chat-history-cadence.md` | ≤ 80 |
-| `chat-history-visibility.md` | ≤ 65 |
-| **Total** | **≤ 240** |
-
-Net always-rule budget delta: **+39 lines** (≈ 1.8 % of the current
-2207-line total). Within the ~49k-token target ceiling tracked in
-`road-to-governance-cleanup.md`.
-
-## Consequences
-
-**Wins**
-
-- Each rule has one Iron Law instead of three. Future edits to
-  cadence don't risk touching ownership prompt mechanics.
-- The `chat-history-visibility.md` rule becomes a clean reuse target
-  for Phase 2 P2.9 (memory-visibility surface).
-- Refactoring the engine-side hooks (`chat_history_turn_check.py`,
-  `chat_history_append.py`, `chat_history_heartbeat.py`) is now
-  1:1 with rule files — one rule per hook.
-
-**Costs / migration surface**
-
-- Every cross-reference to `chat-history` across the package must be
-  updated to point at the right split. Inventory: ~30 files (rules,
-  templates, scripts, commands, contexts, README, AGENTS.md).
-- `docs-sync.md` table needs the new triple instead of the singleton.
-- `scripts/check_references.py` runs catch broken links; CI gates the
-  split.
-- Any consumer project carrying a project-level override of
-  `chat-history` must also split (or alias) — handled by an explicit
-  migration note in `docs/migrations/commands-1.15.0.md` (extended
-  for this rule split).
-
-**Reversibility**
-
-Split is a structural refactor, not a behavior change. Reverting
-would mean re-concatenating the three files — mechanical but loud
-in CI. The CHECKPOINT-path Iron Law numbering is preserved, so
-agents that learned "gates 1-2-3" still find the same numbered
-sequence, just across three files.
-
-## Out of scope
-
-- Behavior changes to `scripts/chat_history.py` — the script's
-  CLI surface is unchanged.
-- Adding new cadence frequencies or visibility modes — separate
-  decision, not part of this split.
-- Removing the CHECKPOINT-path entirely — Cline-on-Windows still
-  needs cooperative gates; that's a Phase 3+ conversation.
-
-## Implementation plan (this PR)
-
-1. Create the three new rules under `.agent-src.uncondensed/rules/`.
-2. Delete `.agent-src.uncondensed/rules/chat-history.md`.
-3. Run `bash scripts/condense.sh --sync` to project the change into
-   `dist/agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`,
-   `.windsurfrules`.
-4. Update every cross-reference (~30 files) — `check-refs` is the
-   gate.
-5. Append a migration note to `docs/migrations/commands-1.15.0.md`
-   under a new "Rule splits" section.
-6. Regenerate `agents/roadmaps-progress.md`.
-7. Verify: `task ci` (lint-skills, check-refs, check-public-links,
-   check-condensation, counts-check, lint-readme, runtime-e2e,
-   roadmap-progress-check, lint-readme).

package/docs/contracts/adr-command-suggestion.md

@@ -1,144 +0,0 @@
----
-stability: stable
----
-
-# ADR — Context-Aware Command Suggestion
-
-> **Status:** Decided · Phases 1–7 shipped · 2026-04-30
-> **Rule:** [`command-suggestion`](../../.agent-src.uncondensed/rules/command-suggestion-policy.md)
-> **Eligibility table:** [`command-suggestion-eligibility.md`](command-suggestion-eligibility.md)
-> **Engine:** `scripts/command_suggester/`
-> **Orthogonal to:** R1 (`adr-work-engine-rename.md`) — the suggester is a
-> read-only shortcut *finder*; it never invokes a command. Engine boundaries
-> stay intact.
-
-## Decision
-
-Add a **deterministic, read-only** suggestion layer that scans every
-non-`/`-prefixed user turn against eligible command frontmatter
-(`suggestion.trigger_description` + `trigger_context`) and surfaces matches
-as a **numbered-options block** with the user-interaction Iron Law shape:
-
-- N command options, neutral labels (no inline `(recommended)` tag).
-- Always-last "Just run the prompt as-is, no command" escape hatch.
-- Exactly one `**Recommendation: K — /command**` line, omitted when the
-  top two scores are within `0.05` of each other.
-
-The suggester **never executes** anything — option-N is what triggers the
-standard slash-command flow on the next turn (with all per-command halts
-intact). The user picks every time.
-
-## Why this was a real question
-
-A maintainer who types "Setze Ticket ABC-123 um" got a generic
-implementation walk-through, not the `/implement-ticket` engine. The
-package owns 75 commands; the agent has the list in context but no
-contract telling it "when the prompt looks like *this*, offer *that*
-command". Three forces converged:
-
-1. **Discoverability gap.** Users learn `/command` only when documented;
-   most never type it.
-2. **Safety anchor.** Auto-execution is non-negotiably out (`scope-control`,
-   per-command halts). Anything we ship cannot weaken that floor.
-3. **Determinism.** ML-based intent detection is non-replayable; goldens
-   would drift. Pattern + keyword matching keeps GT-CS replays byte-stable.
-
-Three alternatives were rejected:
-
-- **Auto-route to commands** (bypass the user). Rejected: violates the
-  "user always picks" anchor; one wrong route inside `/implement-ticket`
-  is a multi-hour blast radius.
-- **Trigger-based command auto-prefix** (silently rewrite the prompt
-  to `/command <prompt>`). Rejected: same anchor breach, plus the user
-  loses the "skip" option.
-- **LLM intent classifier**. Rejected: non-deterministic, untestable in
-  the GT-CS harness, and the eligibility table is small enough that
-  pattern matching reaches the same precision at zero cost.
-
-## Eligibility rubric
-
-A command is **eligible** (default `true`) unless:
-
-- Invocation is **intentional-only** (`/onboard`, `/package-reset`,
-  `/mode`, `/agent-handoff`, `/chat-history-clear`).
-- Triggers would overlap so heavily with normal prose that the floor +
-  cooldown can't suppress the noise.
-- The command has no natural-language signal distinct from neighbours.
-
-The locked table is
-[`command-suggestion-eligibility.md`](command-suggestion-eligibility.md).
-Eligibility changes are roadmap follow-ups, not drive-by edits.
-
-## Anti-noise heuristics
-
-`rank.py` drops matches that fail any of:
-
-- Score below `confidence_floor` (default `0.6`; per-command override
-  via frontmatter).
-- Single match within `floor + 0.1` of the floor and no structural
-  bonus (high uncertainty isn't worth interrupting).
-- Short prompt (< 6 words) hitting > 2 commands without a structural
-  bonus (too vague to disambiguate).
-- Pure continuation phrase (`ok`, `weiter`, `mach weiter`, `go on`,
-  `continue`) with no structural bonus.
-- Same `(command, evidence)` pair shown within `cooldown_seconds`
-  (default `600`, per-command override).
-
-Structural bonuses (ticket key, file path, branch shape) override
-suppression when they signal real intent.
-
-## Hardening — what suggestion must never do
-
-The rule (`.agent-src.uncondensed/rules/command-suggestion-policy.md`)
-binds the engine to five non-negotiables, mirrored as goldens:
-
-1. **No execution without user pick.** `SUGGEST. NEVER INVOKE.` is the
-   first Iron Law in the rule.
-2. **No multi-question stacks.** Clarification (`ask-when-uncertain`)
-   wins; suggestion stays silent that turn.
-3. **No conversation hijack.** `enabled: false`, no matches above floor,
-   or a senior rule active → zero output.
-4. **No echo-trigger.** `sanitize.py` strips fenced/inline code and the
-   engine's own previous block shape (`> N. /command — …`,
-   `**Recommendation: N — …**`) before scoring.
-5. **Hard subordination.** `scope-control`, `ask-when-uncertain`,
-   `verify-before-complete`, and any active role-mode contract outrank
-   suggestion.
-
-GT-CS1 through GT-CS9 (`tests/test_command_suggester_goldens.py`) lock
-the contract end-to-end.
-
-## Three opt-out paths
-
-| Path | Mechanism | Scope |
-|---|---|---|
-| Global | `commands.suggestion.enabled: false` in `.agent-settings.yml` | Whole project |
-| Per-command | `commands.suggestion.blocklist: [/cmd]` | Specific command stays as-is |
-| Per-conversation | `/command-suggestion-off` directive | Until user re-enables or chat ends |
-
-All three are deterministic and tested. `/command-suggestion-on`
-re-enables mid-conversation.
-
-## Consequences
-
-**Positive.** The maintainer's intent surfaces commands they didn't
-remember to type. Anti-noise heuristics keep the layer near-silent on
-prose. Goldens replay byte-stable; GT-CS9 covers adversarial echo.
-
-**Negative.** A new always-on rule adds context budget — kept under
-size budget by the size-enforcement rule. Per-command frontmatter now
-carries `suggestion.*` keys; the linter enforces them so drift is
-caught early.
-
-**Open.** Trigger drift over time — a command's
-`trigger_description` gets stale as conventions move. Mitigation: the
-artefact-engagement telemetry pipeline (default-off) measures
-suggestion pick-rate per command, surfacing weak triggers as
-retirement candidates without a hard SLA.
-
-## See also
-
-- [`command-suggestion`](../../.agent-src.uncondensed/rules/command-suggestion-policy.md) — runtime rule
-- [`command-suggestion-eligibility.md`](command-suggestion-eligibility.md) — locked eligibility table
-- [`adr-prompt-driven-execution.md`](adr-prompt-driven-execution.md) — `/work` entrypoint that explicit slash invocations route to
-- [`agent-settings`](../../.agent-src.uncondensed/templates/agent-settings.md) — `commands.suggestion.*` reference