@event4u/agent-config 3.3.0 → 4.2.0

package/docs/contracts/file-ownership-matrix.md

@@ -19,7 +19,7 @@ This contract defines the **schema** of the file-ownership matrix: the
 machine-readable JSON at `docs/contracts/file-ownership-matrix.json` and
 the human-readable mirror at
 `agents/settings/contexts/structural/file-ownership-matrix.md`. Both are
-regenerated from `.agent-src.uncompressed/` by the generator and locked
+regenerated from `.agent-src.uncondensed/` by the generator and locked
 by CI.
 
 **Status:** internal-locked (`stability: beta`). Schema bumps require a
@@ -49,7 +49,7 @@ The JSON document is a single object:
 {
   "version": 1,
   "generated_by": "scripts/generate_ownership_matrix.py",
-  "source_of_truth": ".agent-src.uncompressed/",
+  "source_of_truth": ".agent-src.uncondensed/",
   "files": {
     "<repo-root-relative path>": {
       "kind": "rule | skill | command | context | persona",
@@ -111,7 +111,7 @@ backstop; the consistency gate fails if regeneration drifts.
 ## Scope notes (v1)
 
 - **Greppable surface:** `rules/`, `skills/`, `commands/`, `contexts/`,
-  `personas/` under `.agent-src.uncompressed/`. Generated tool
+  `personas/` under `.agent-src.uncondensed/`. Generated tool
   projections (`.augment/`, `.claude/`, `.cursor/`, …) are intentionally
   ignored — they are downstream of the source of truth.
 - **`skill:` frontmatter in rules** (named in roadmap 0.1.2) is reserved.

package/docs/contracts/frontmatter-contract.md

@@ -10,7 +10,7 @@ keep-beta-until: 2026-08-19
 > ADR is the decision; this file is the worked-example reference linters,
 > installer, and contributors cite at runtime.
 
-Every `.md` artefact under `.agent-src.uncompressed/` MUST declare the five
+Every `.md` artefact under `.agent-src.uncondensed/` MUST declare the five
 ADR-013 discovery keys. The release-time manifest builder
 (`scripts/build_discovery_manifest.py`) derives all workspace/pack assignment
 from these alone — **no manual workspace or pack list is ever maintained**.
@@ -118,7 +118,7 @@ the linter rejects that collision.
 | Surface | What runs | When |
 |---|---|---|
 | Local | `task lint-artefact-frontmatter` | manual / pre-commit |
-| Pre-commit | `pre-commit-roadmap-progress` template | when `.agent-src.uncompressed/*.md`, `config/discovery/*.yml`, or the linter itself is staged |
+| Pre-commit | `pre-commit-roadmap-progress` template | when `.agent-src.uncondensed/*.md`, `config/discovery/*.yml`, or the linter itself is staged |
 | CI | `task ci` → `lint-artefact-frontmatter` | every push / PR |
 
 Install the pre-commit hook with:
@@ -133,8 +133,8 @@ are staged.
 
 ## Roundtrip invariant
 
-Frontmatter survives the `task sync` compression pipeline. Path-bearing
+Frontmatter survives the `task sync` condensation pipeline. Path-bearing
 keys (`load_context`) may be rewritten relative to the projected location,
 but the five Phase-1 keys above are byte-stable between
-`.agent-src.uncompressed/`, `.agent-src/`, and `.augment/`. Enforced by
+`.agent-src.uncondensed/`, `.agent-src/`, and `.augment/`. Enforced by
 `tests/test_frontmatter_roundtrip.py`.

package/docs/contracts/ghostwriter-schema.md

@@ -25,7 +25,7 @@ explicit `accept` step on `/ghostwriter:fetch` re-runs.
   profiles live here. **Gitignored by default** via the package-managed
   `.gitignore` block. A `--shared` opt-in to commit profiles is
   deferred to v2; only the doc note lands in v1.
-- **Package source** — `.agent-src.uncompressed/ghostwriter/` ships
+- **Package source** — `.agent-src.uncondensed/ghostwriter/` ships
   the README, this schema doc, and `fictional: true` fixtures only.
   **Zero real-person profiles ever ship with the OSS package.** A CI
   lint (`task lint-ghostwriter-source`) enforces this rule by failing
@@ -181,7 +181,7 @@ attribution stays deterministic.
 fixtures are schema examples for a single canonical name; aliases are a
 consumer-only deployment feature. The package-source lint
 (`task lint-ghostwriter-source`) fails on `aliases:` in
-`.agent-src.uncompressed/ghostwriter/`.
+`.agent-src.uncondensed/ghostwriter/`.
 
 ### Settings toggle (consumer-only)
 
@@ -293,7 +293,7 @@ instead of merging.
 
 The lint runs in `task ci` and fails on:
 
-1. Any file under `.agent-src.uncompressed/ghostwriter/` whose stem is
+1. Any file under `.agent-src.uncondensed/ghostwriter/` whose stem is
    **not** on the fixture allowlist (`scripts/ghostwriter_fixture_allowlist.txt`).
 2. Any allowlisted file missing `fictional: true` in frontmatter.
 3. Any package-source file (`fictional: true`) carrying an `aliases:`

package/docs/contracts/gui-wizard.md

@@ -8,20 +8,27 @@ keep-beta-until: 2026-08-19
 > Companion to the agent-mode protocol
 > ([`installer-agent-mode.md`](installer-agent-mode.md)) and the
 > trust-and-safety layer ([`trust-and-safety.md`](trust-and-safety.md)).
-> The wizard is a thin HTTP wrapper around the same install plan, the
-> same lockfile, and the same atomic-write semantics as the CLI/TUI
-> paths. It is **optional by design** — the CLI is the canonical entry
-> point; the wizard exists for non-technical users who want a visual
-> picker.
+> The wizard is a thin HTTP wrapper: it is a **selection front-end**, and
+> every real write goes through the single installer
+> `scripts/install.py --apply-payload` (D12 / ADR-020). It is **optional by
+> design** — the CLI is the canonical entry point; the wizard exists for
+> non-technical users who want a visual picker.
 
 ## Source of truth
 
-- Server: [`packages/core/installer/src/gui/server.ts`](../../packages/core/installer/src/gui/server.ts)
-- Handlers: [`packages/core/installer/src/gui/handlers.ts`](../../packages/core/installer/src/gui/handlers.ts)
-- Security primitives: [`packages/core/installer/src/gui/security.ts`](../../packages/core/installer/src/gui/security.ts)
-- Inlined SPA: [`packages/core/installer/src/gui/static-assets.ts`](../../packages/core/installer/src/gui/static-assets.ts)
-- Transaction log: [`packages/core/installer/src/gui/transaction-log.ts`](../../packages/core/installer/src/gui/transaction-log.ts)
-- Tests: [`packages/core/installer/tests/gui-*.test.ts`](../../packages/core/installer/tests/)
+The GUI is a Fastify server (`src/server/`) serving a Preact SPA
+(`src/ui/`), booted by the `install` / `setup` / `ui:serve` CLI
+subcommands. The legacy `packages/core/installer/src/gui/*` tree was
+retired; the single real installer is `scripts/install.py`.
+
+- Server app + security hooks: [`src/server/app.ts`](../../src/server/app.ts) (Host allow-list, Origin allow-list, CSRF token — `onRequest` hooks)
+- Wizard routes (incl. the real-apply bridge): [`src/server/routes/wizard.ts`](../../src/server/routes/wizard.ts)
+- Read-only install routes (detect / plan-preview / recovery / legacy-v3): [`src/server/routes/install.ts`](../../src/server/routes/install.ts)
+- Atomic / 2PC writes: [`src/server/io/atomicWrite.ts`](../../src/server/io/atomicWrite.ts), [`atomicMultiWrite.ts`](../../src/server/io/atomicMultiWrite.ts)
+- SPA: [`src/ui/`](../../src/ui/) (entry `src/ui/pages/WizardPage.tsx`)
+- CLI boot + `WIZARD_READY` contract: [`src/cli/commands/uiServe.ts`](../../src/cli/commands/uiServe.ts)
+- The single installer (all real writes): [`scripts/install.py`](../../scripts/install.py)
+- Tests: [`tests/server/`](../../tests/server/) + [`tests/e2e/`](../../tests/e2e/)
 
 ## Local-only invariant
 
@@ -34,126 +41,132 @@ no cross-origin asset, no remote endpoint — CSP
 ## Boot sequence
 
 ```
-npx @event4u/agent-config init --gui [--gui-port=<n>] [--no-open] [--gui-idle=<s>]
+agent-config install   (or `setup`, or `init` → scripts/install.py → spawns
+                        `node dist/cli/agent-config.js install --no-open`)
   │
-  ├─► inspect agents/runtime/gui/server.pid → abort if live
-  ├─► load dist/discovery/discovery-manifest.json (walks up from CWD)
-  ├─► generate per-server CSRF token (64-hex)
-  ├─► http.createServer + listen({ host: '127.0.0.1', port: 0 })
-  ├─► write agents/runtime/gui/server.pid (POSIX pid, single line)
-  ├─► default-spawn the OS browser opener (skipped with --no-open)
-  └─► return GuiServerHandle { url, port, csrfToken, pidFile, close }
+  ├─► pick a free loopback port; mint a per-server bearer/CSRF token
+  ├─► Fastify listen({ host: '127.0.0.1', port })
+  ├─► print `WIZARD_READY <url>` on stdout (url carries `?token=…` + `#/…`)
+  ├─► open the OS browser at <url>   (skipped with --no-open / headless)
+  └─► serve until Ctrl-C
 ```
 
-Idle timeout (default 600 s, configurable via `--gui-idle`) is keyed on
-the **last HTTP request timestamp**, not on SSE event activity.
+`init` is the consumer entry point: it delegates to `scripts/install.py`,
+which — on a TTY with a display and no `--no-ui` / `CI` / explicit
+`--tools=` — spawns the `install` subcommand with `--no-open` and waits for
+the `WIZARD_READY <url>` handshake (progressive 10/20/40/80 s budget) before
+printing the URL banner. Headless / CI / `--no-ui` / explicit `--tools=`
+installs run the non-interactive `install.py` path directly and never boot
+the GUI.
+
+### `WIZARD_READY` stdout contract
+
+The server emits exactly one line on stdout when it has bound:
+
+```
+WIZARD_READY http://127.0.0.1:<port>/?token=<token>#/<route>
+```
+
+The supervisor matches `^WIZARD_READY (http://(127.0.0.1|localhost):\d+/\S*)$`
+(no `url=` prefix; the query/hash are part of the captured URL). The line is
+unconditional so headless CI can detect "Fastify bound" without polling the
+port.
 
 ## Endpoints
 
-| Method | Path             | Purpose                                              |
-|--------|------------------|------------------------------------------------------|
-| GET    | `/`              | SPA shell with CSRF token injected via `<meta>`      |
-| GET    | `/app.css`       | Static stylesheet                                    |
-| GET    | `/app.js`        | Inlined SPA logic                                    |
-| GET    | `/api/manifest`  | `{ manifest, sha256 }` — bytes-identical to disk     |
-| GET    | `/api/auto-detect` | `{ signals: { composer, package, pyproject } }`    |
-| POST   | `/api/preview`   | `{ plan, lockfileSha256 }` for current selection     |
-| POST   | `/api/apply`     | SSE: `plan-file`, `progress`, `done`, `error`        |
-| POST   | `/api/cancel`    | Flush in-flight transaction log, close SSE stream    |
-
-All POSTs require:
-
-1. `Origin` header matching `http://127.0.0.1:<port>` or
-   `http://localhost:<port>`.
-2. Body field `csrf` matching the per-server token (timing-safe
-   compare in `security.ts`).
-
-A bad CSRF returns `403` with no body. A bad Origin or Host returns
-`403` with a short plaintext reason.
-
-## Transaction log + rollback
-
-Every `POST /api/apply` writes append-only JSONL entries to
-`<projectRoot>/agents/runtime/gui/install-<ts>.log`. Shapes are
-declared in
-[`types.ts § TransactionLogEntry`](../../packages/core/installer/src/gui/types.ts):
-
-- `start` — workspaces + packs selected
-- `plan` — one entry per planned write (`path`, `pack`)
-- `commit` — `filesWritten`, `lockfileSha256`
-- `cancel` — explicit `POST /api/cancel`
-- `error` — terminating failure with `message`
-
-The next `--gui` boot inspects the most recent log and offers to roll
-back if it ended on `start`/`plan`/`error` without a matching
-`commit`/`cancel`. The CLI path consumes the same log, so a mid-install
-crash can be undone from either entry point.
+Versioned under `/api/v1/`. Selected routes:
+
+| Method | Path                          | Purpose                                                                 |
+|--------|-------------------------------|-------------------------------------------------------------------------|
+| GET    | `/`                           | SPA shell (token passed via the `?token=` query)                        |
+| GET    | `/api/v1/wizard/state`        | Resumable partial wizard state                                          |
+| POST   | `/api/v1/wizard/state`        | Persist state between steps                                             |
+| GET    | `/api/v1/wizard/manifest`     | Locked discovery-manifest (extended mode)                               |
+| GET    | `/api/v1/wizard/auto-detect`  | Project-signal evidence for the `ai-tools` step (extended mode)         |
+| POST   | `/api/v1/wizard/finish`       | 2PC commit of settings + user-identity                                  |
+| POST   | `/api/v1/wizard/apply`        | **Single real-apply route.** `dry_run:true` → buffered plan preview; otherwise SSE-streams `scripts/install.py --apply-payload` |
+| GET    | `/api/v1/install/detect`      | Scope + project shape + tool presence                                   |
+| POST   | `/api/v1/install/plan`        | Plan preview (per-tool file counts + conflicts) for the Review step     |
+| GET    | `/api/v1/install/recovery`    | Interrupted-run recovery state                                          |
+| GET    | `/api/v1/install/legacy-v3`   | v3-install detection (backup screen)                                    |
+
+The TypeScript apply engine and its `POST /api/v1/install/apply` SSE route
+were removed (road-to-single-install-source-of-truth § Phase 3). All real
+writes now flow through `POST /api/v1/wizard/apply` → `scripts/install.py`.
+
+Every request passes three `onRequest` hooks in
+[`src/server/app.ts`](../../src/server/app.ts): a `Host`-header allow-list,
+an `Origin` allow-list (browser-issued requests), and a per-server bearer
+token (`Authorization: Bearer <token>`, minted at boot, surfaced in the
+`?token=` URL). A bad token / Host / Origin returns `403`.
+
+## Real apply — single source of truth
+
+`POST /api/v1/wizard/apply` is the only write path:
+
+- `dry_run: true` → spawns `install.py --apply-payload <tmp> --dry-run` and
+  returns the buffered plan-summary text (used by the Review preview).
+- otherwise → spawns `install.py --apply-payload <tmp>` (real apply) and
+  **streams** the installer's NDJSON stdout
+  (`{type:"file",…}` / `{type:"done"|"error"}`) mapped to the SSE frames the
+  SPA consumes. The child is killed if the client disconnects
+  (abort-on-disconnect, Finding #24). The installer owns its own
+  transactional state (the user-scope lockfile + project manifest), so the
+  GUI does not maintain a parallel transaction log.
 
 ## SSE event framing
 
-Every `POST /api/apply` event is `data: <json>\n\n`. The terminal event
-is one of:
+Each real-apply event is `data: <json>\n\n`. Frames:
 
 ```jsonc
-{ "type": "done", "filesWritten": 12, "lockfileSha256": "<64-hex>" }
-{ "type": "error", "message": "<reason>" }
+{ "type": "progress", "file": "<tool>", "status": "deployed", "written": 1, "total": 3 }
+{ "type": "done", "summary": { "written": 3, "total": 3 } }
+{ "type": "error", "code": "<code>", "message": "<reason>", "recoverable": false }
 ```
 
-The browser closes the EventSource on either; the server flushes the
-transaction log and unblocks the idle timer.
-
-## Tarball budget
-
-GUI assets under `packages/core/installer/src/gui/` (inlined HTML +
-CSS + JS in `static-assets.ts`) must stay **≤ 200 KB compiled**. The
-constraint is enforced by reviewer judgment for now; a CI check is
-tracked under the Phase 6 follow-ups.
+The browser stops reading on `done` / `error`; the server ends the stream.
 
 ## Security failure modes covered
 
-- **Remote exploitation** — loopback bind, Host allowlist, Origin
-  allowlist, CSRF token, CSP `default-src 'self'`.
-- **DNS rebinding** — Host header check covers POSTs that omit
-  `Origin` (form posts).
-- **Zombie servers** — ephemeral port + PID file + last-request idle
-  timer. Stale PIDs (process gone) are silently overwritten on next
-  boot; live PIDs block boot with a helpful message.
-- **Mid-install crash** — transaction log + boot-time rollback prompt.
-- **Hidden state** — closing the tab triggers idle timeout; no
-  cross-tab session.
+- **Remote exploitation** — loopback bind, Host allow-list, Origin
+  allow-list, per-server bearer token.
+- **DNS rebinding** — Host header check covers POSTs that omit `Origin`.
+- **Mid-install crash** — `scripts/install.py` owns the user-scope
+  lockfile + project manifest; the recovery routes
+  (`/api/v1/install/recovery`) surface an interrupted run on next boot.
 
 ## Non-goals (documented contract)
 
-- Not a hosted SaaS — no auth, no account model, no telemetry.
-- Not a settings editor — read-only on the lockfile; writes go
-  through the same install plan as the CLI.
-- Not a CI surface — every operation is reachable via `--gui-port=0
-  --no-open` is supported for headless smoke tests, but the canonical
-  CI path is the flag-driven non-interactive CLI.
+- Not a hosted SaaS — no auth account model, no telemetry.
+- Not a parallel installer — the GUI is a selection front-end; every
+  real write goes through `scripts/install.py --apply-payload`.
+- Not a CI surface — `--no-open` headless boots are supported for smoke
+  tests, but the canonical CI path is the flag-driven non-interactive CLI.
 
 ## Apply payload — versioning handshake (road-to-global-only-install Phase 0.4 · D12)
 
-`/api/apply` accepts a discriminated-union body keyed on
+`POST /api/v1/wizard/apply` accepts a discriminated-union body keyed on
 `schema_version`. The full JSON Schema lives at
-[`schemas/wizard-apply-payload.schema.json`](../../schemas/wizard-apply-payload.schema.json).
+[`internal/schemas/wizard-apply-payload.schema.json`](../../internal/schemas/wizard-apply-payload.schema.json).
 
 | `schema_version` | Variant | Shape |
 |---|---|---|
 | `"installer-v1"` | `InstallerPayloadV1` | `{ ai_tools[], configs{}, dry_run? }` — legacy Installer-GUI, AI tools only. |
 | `"wizard-v2"` | `WizardPayloadV2` | `{ tools[], packs[], settings{}, scope_to_project_only?, dry_run? }` — unified 9-step wizard. |
 
-**D12 (locked).** Single `/api/apply` endpoint with a `schema_version`
+**D12 (locked).** Single apply endpoint with a `schema_version`
 discriminator — **not** two endpoints with a shared Python backend.
-Reasoning: one bind, one CSRF token, one transaction log; the
+Reasoning: one bind, one token, one installer; the
 Python `scripts/install.py` payload-router branches on
 `schema_version` before any disk write. The dual-endpoint variant was
-considered and rejected for doubling the CSRF + idle-timer surface
-with no observability gain.
+considered and rejected for doubling the surface with no gain.
 
 `schema_version` is **required**. Servers MUST reject any body that
-lacks it (HTTP 400, single-line error pointing at the schema). This
-locks the contract before Phase 1 implementation so no implicit fork
-can sneak in at Phase 1.5.
+lacks it (HTTP 4xx, single-line error pointing at the schema). The
+real-apply path is now wired end-to-end
+(road-to-single-install-source-of-truth § Phases 1–2): `install.py`
+translates the payload into the canonical install and streams NDJSON
+progress back to the GUI.
 
 ## Unified 9-step flow (road-to-global-only-install § Phase 1.6)
 

package/docs/contracts/harness-expectations.md

@@ -0,0 +1,123 @@
+# Harness Expectations — when AI tool behaviour looks like a package bug but isn't
+
+**Status:** Active (Phase D of `road-to-clean-skill-distribution-channels.md`)
+**Owner:** maintainer-team
+**Inputs:** Phase D roadmap steps + the 2026-05-25 misdiagnosis chat session that opened this track.
+
+## The case for this document
+
+On 2026-05-25 a Claude Code session surfaced three behaviours that looked like `event4u/agent-config` bugs. Two of the three turned out to be **host-harness behaviour** the package has no control over. The third (cross-scope skill drift) was a real package-side bug fixed in Phases A–C. This document captures the host-side three so the next agent / onboarding session / opened issue does not re-run the misdiagnosis loop.
+
+## Class A — Plugin-namespaced peer skills
+
+### Symptom
+
+The session shows skills under namespaces like `codex:`, `cc-gemini-plugin:`, or another `<vendor>:` prefix:
+
+```
+- codex:setup
+- cc-gemini-plugin:gemini-agent
+- codex:rescue
+```
+
+These names do NOT appear in `event4u/agent-config`'s skill catalog, the README, or the contracts.
+
+### What's actually happening
+
+Claude Code (and similar harnesses) supports **sibling plugins** in addition to the primary `event4u/agent-config` install. Each sibling plugin owns its own skills, namespaced by the plugin id. The harness surfaces every loaded plugin's skills in the same `<available_skills>` list during the session.
+
+- `codex:*` skills come from a sibling plugin that wraps the Codex CLI.
+- `cc-gemini-plugin:*` skills come from a sibling plugin that wraps Gemini-CLI integration.
+
+`event4u/agent-config` does not ship, control, or update these plugins. They are independent installs by independent maintainers.
+
+### What the package can do
+
+Nothing — sibling plugins are out of scope by construction. The user can:
+
+- Remove the sibling plugin if it is unwanted (via the harness's plugin management — outside this package).
+- Ignore the namespaced names; they will not collide with this package's skill IDs because the prefix differs.
+
+### Where to look for the true source
+
+Per Claude Code: `claude plugin list` (or equivalent) shows every loaded plugin. Each `<vendor>:` namespace traces back to a plugin row in that listing. Bug reports for those skills go to the respective plugin maintainer.
+
+## Class B — Deferred tools that need ToolSearch
+
+### Symptom
+
+A session sees a `<system-reminder>` block like:
+
+```
+The following deferred tools are now available via ToolSearch.
+Their schemas are NOT loaded — calling them directly will fail with
+InputValidationError. Use ToolSearch with query "select:<name>[,<name>...]"
+to load tool schemas before calling them:
+TaskCreate
+WebFetch
+Monitor
+mcp__claude_ai_Linear__authenticate
+...
+```
+
+The named tools are real — they show up in the harness's runtime — but the agent cannot call them directly because the tool **schema** isn't loaded yet.
+
+### What's actually happening
+
+Claude Code's tool-loading is **context-budgeted**. The full tool registry (TaskCreate, WebFetch, every MCP tool from every registered server, etc.) can be many kilobytes of JSON-schema. Loading every schema on every turn would blow the context budget for routine reads. The harness solves this by registering tool **names** up-front and deferring schema load until `ToolSearch` is called — that's the on-ramp.
+
+This is not a package issue, and `event4u/agent-config` cannot pre-load these schemas — the harness owns the budget.
+
+### What the package can do
+
+Nothing — the loading strategy is the harness's contract with the model. Skills that want to use a deferred tool must:
+
+1. Run `ToolSearch` with `select:<name>` to load the schema.
+2. Call the tool with the now-known parameters.
+
+Skills in this package that need deferred tools document the load step explicitly (see `agents-md-thin-root` § Tool loading for the pattern).
+
+### Where to look for the true source
+
+Per Claude Code's documentation on tool surfaces and the `ToolSearch` primitive. The package does not own this behaviour.
+
+## Class C — Duplicate skill registration (real package bug, fixed in Phases A–C)
+
+### Symptom
+
+The same skill appears twice in `<available_skills>` with different `description:` strings, or behaves inconsistently across calls.
+
+### What's actually happening
+
+A user-global install (e.g. `~/.claude/skills/`) and a project-local install (`./.claude/skills/`) coexist at **different versions**. The harness loads both. The earlier register wins the description in some calls, the later in others.
+
+Unlike Classes A and B, this is a real package-side issue.
+
+### What the package does
+
+1. **Default install is filesystem-only** ([`skill-distribution-channels.md`](skill-distribution-channels.md)).
+2. **Pre-flight scope guard** refuses installs that would create cross-scope drift ([`install-scopes.md`](install-scopes.md)).
+3. **Post-install probe** surfaces any remaining drift after install (`task probe:skills`).
+4. **Cleanup script** for stale other-scope installs (`bash scripts/cleanup_other_scope.sh --confirm`).
+
+### Where to look for the true source
+
+```bash
+task probe:skills
+```
+
+The probe lists every duplicate / drift finding with the exact source paths so the cause is visible in one read.
+
+## When in doubt — diagnostic sequence
+
+1. Run `task probe:skills` — rules out Class C.
+2. If the suspicious skill carries a `<vendor>:` prefix you don't recognise → Class A. Check `claude plugin list`.
+3. If the harness logs `deferred tools … available via ToolSearch` → Class B. The skill needs an explicit `ToolSearch` step.
+4. None of the above → file an issue at https://github.com/event4u-app/agent-config with the output of `task probe:skills` attached.
+
+## See also
+
+- [`skill-distribution-channels.md`](skill-distribution-channels.md) — canonical channel per tool.
+- [`install-scopes.md`](install-scopes.md) — scope guard contract.
+- [`agents/evidence/audits/2026-05-distribution-channels/`](../../agents/evidence/audits/2026-05-distribution-channels/) — the underlying audits.
+- [`README.md` § Harness expectations](../../README.md#harness-expectations) — front-of-house pointer to this contract.

package/docs/contracts/host-agent-protocol.md

@@ -1,3 +1,7 @@
+---
+stability: experimental
+---
+
 # Host-Agent Protocol Contract
 
 > **Status** · v0 / inventory · 2026-05-24. The daily workspace shells out to

package/docs/contracts/implement-ticket-flow.md

@@ -12,7 +12,7 @@ keep-beta-until: 2026-08-12
 > - **Created:** 2026-04-22
 > - **Status:** Phase 1 shipped 2026-04-23 — `DeliveryState` +
 >   dispatcher live under
->   [`.agent-src.uncompressed/templates/scripts/implement_ticket/`](../../.agent-src.uncompressed/templates/scripts/implement_ticket/).
+>   [`.agent-src.uncondensed/templates/scripts/implement_ticket/`](../../.agent-src.uncondensed/templates/scripts/implement_ticket/).
 >   Step wiring (Phase 2) still open. Schema **v1** envelope
 >   (`work_engine.state` / `work_engine.migration.v0_to_v1`) shipped
 >   2026-04-27 as R1 Phase 2 — see [State schema v1](#state-schema-v1)
@@ -265,7 +265,7 @@ Bounded per the top-level roadmap rule:
 - **Four allowed types:** `domain-invariants`,
   `architecture-decisions`, `incident-learnings`,
   `historical-patterns`. All four exist in the
-  [templates directory](../../.agent-src.uncompressed/templates/agents/memory/).
+  [templates directory](../../.agent-src.uncondensed/templates/agents/memory/).
 - **Keys:** files touched by the plan, symbols referenced by the
   ticket.
 - **Decision-change rule:** a memory hit that did not change an
@@ -278,7 +278,7 @@ Bounded per the top-level roadmap rule:
 
 Read from `.agent-settings.yml` `roles.active_role` and resolved
 via `resolve_policy()` in
-[`persona_policy.py`](../../.agent-src.uncompressed/templates/scripts/implement_ticket/persona_policy.py).
+[`persona_policy.py`](../../.agent-src.uncondensed/templates/scripts/implement_ticket/persona_policy.py).
 Policies live alongside the dispatcher so the flow can consume
 them directly; the shared
 [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md)
@@ -319,7 +319,7 @@ skill.
 When a step returns `blocked`, the orchestrator:
 
 1. Emits the numbered questions per
-   [`user-interaction`](../../.agent-src.uncompressed/rules/user-interaction.md).
+   [`user-interaction`](../../.agent-src.uncondensed/rules/user-interaction.md).
 2. Writes a partial report up to the last successful step.
 3. Exits with a `blocked` status — no guess, no fallback.
 
@@ -332,7 +332,7 @@ the context. V1 explicitly does **not** attempt resumable sessions.
 Every step declares — in code — the conditions under which it
 can return `blocked`. The declarations live as module-level
 `AMBIGUITIES` tuples (see
-[`directives/backend/__init__.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/backend/__init__.py)
+[`directives/backend/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/backend/__init__.py)
 `.all_ambiguities()`). The
 [`test_ambiguity_coverage.py`](../../tests/implement_ticket/test_ambiguity_coverage.py)
 suite locks the contract: adding a new `blocked` path without
@@ -377,7 +377,7 @@ empty, but all headings are present unless explicitly marked
    because nothing was changed.
 
 Implementation: see
-[`directives/backend/report.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/backend/report.py).
+[`directives/backend/report.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/backend/report.py).
 Section renderers are pure and deterministic; consumers can rely
 on the heading order and on each section either rendering with
 content or being omitted per the rules above.
@@ -621,6 +621,6 @@ are blocked by `freeze-guard.yml::manifest-integrity` at PR time.
 - [`../../.github/workflows/freeze-guard.yml`](../../.github/workflows/freeze-guard.yml) — manifest-integrity + live-replay gates
 - [`agent-memory-contract.md`](agent-memory-contract.md)
 - [`../../docs/guidelines/agent-infra/role-contracts.md`](../../docs/guidelines/agent-infra/role-contracts.md)
-- [`../../.agent-src.uncompressed/rules/user-interaction.md`](../../.agent-src.uncompressed/rules/user-interaction.md)
-- [`../../.agent-src.uncompressed/rules/scope-control.md`](../../.agent-src.uncompressed/rules/scope-control.md)
-- [`../../.agent-src.uncompressed/rules/minimal-safe-diff.md`](../../.agent-src.uncompressed/rules/minimal-safe-diff.md)
+- [`../../.agent-src.uncondensed/rules/user-interaction.md`](../../.agent-src.uncondensed/rules/user-interaction.md)
+- [`../../.agent-src.uncondensed/rules/scope-control.md`](../../.agent-src.uncondensed/rules/scope-control.md)
+- [`../../.agent-src.uncondensed/rules/minimal-safe-diff.md`](../../.agent-src.uncondensed/rules/minimal-safe-diff.md)

package/docs/contracts/install-scopes.md

@@ -0,0 +1,77 @@
+# Install Scopes — user-global vs project-local
+
+**Status:** Active (locked 2026-05-25 via Phase B of `road-to-clean-skill-distribution-channels.md`)
+**Owner:** maintainer-team
+**Inputs:** [`docs/contracts/skill-distribution-channels.md`](skill-distribution-channels.md), [`agents/evidence/audits/2026-05-distribution-channels/03-installer-scope-flow.md`](../../agents/evidence/audits/2026-05-distribution-channels/03-installer-scope-flow.md)
+
+## Rule
+
+`event4u/agent-config` may be installed at **one** of two scopes per developer machine:
+
+| Scope | Lives at | Default for | Rationale |
+|---|---|---|---|
+| **project-local** | `<project-root>/.augment/`, `<project-root>/.claude/skills/`, … | Application repos | The skills, rules, and personas are pinned alongside the code they serve. The install is reproducible from the repo. |
+| **user-global** | `~/.augment/`, `~/.claude/skills/`, … | Tooling repos / dotfiles | The same skills follow the developer across every project they touch. Useful when no specific repo "owns" the install. |
+
+Installing at **both** scopes simultaneously is the failure mode the canonical-channel contract prevents — the host harness loads both registrations, and any version drift surfaces as duplicate skills with stale frontmatter (the 2026-05-25 bug).
+
+## The installer enforces this
+
+`scripts/install.sh` runs `scripts/_lib/scope_guard.sh` before any file write:
+
+1. **`OK`** — no install at the other scope. Proceed.
+2. **`WARN`** — install at the other scope, same version. Same content; duplicate registration but no drift. Surface a warning, proceed.
+3. **`DRIFT`** — install at the other scope, different version. Block with a numbered-options prompt:
+
+```
+  1. Abort install — fix drift first (recommended)
+  2. Upgrade the OTHER scope first
+  3. Force install at this scope — accept drift (set SCOPE_GUARD_BYPASS=1)
+  4. Clean the other scope (bash scripts/cleanup_other_scope.sh --confirm)
+```
+
+Non-interactive shells default to **abort**. CI runs and the orchestrator set `SCOPE_GUARD_BYPASS=1` to skip the gate.
+
+The `agent-config setup` wizard exposes the same check at `GET /api/v1/wizard/scope-guard` (extended-mode endpoint). The first wizard step renders the verdict before the user picks an install scope.
+
+## How to clean a stale other-scope install
+
+Use the companion script:
+
+```bash
+# Dry-run (default) — list what would be removed
+bash scripts/cleanup_other_scope.sh --user
+
+# Confirm and delete
+bash scripts/cleanup_other_scope.sh --user --confirm
+
+# Narrow to a single tool
+bash scripts/cleanup_other_scope.sh --user --confirm --tools=claude-code
+
+# Remove from a specific project root
+bash scripts/cleanup_other_scope.sh --project /path/to/proj --confirm
+```
+
+The script refuses to delete anything without `--confirm` per `non-destructive-by-default`. It only touches the tool-scoped paths the contract names (`.claude/skills/`, `.augment/`, `.cursor/rules/`, `.clinerules/`, `.windsurf/rules/`, `.github/copilot-instructions.md`); the rest of the scope root is never modified.
+
+## When to pick which scope
+
+- **App repo** (Laravel, Next.js, monorepo) → project-local. The skills/rules ship with the code; CI installs them deterministically.
+- **Tooling repo** (dotfiles, personal sandbox) → user-global. The install follows the developer.
+- **Both apply** (a tooling repo that also has project-specific overrides) → project-local for the overrides, no user-global install. The override mechanism at `agents/overrides/` covers the divergence.
+
+The scope guard does **not** make the picking decision; it enforces "one scope per machine at one version".
+
+## Failure modes the guard catches
+
+- A user installed `event4u/agent-config` globally a year ago, then `npx`d a recent project that pulled v3.x into `./.claude/skills/`. Same skill ID, different frontmatter on disk. Without the guard, the Claude session sees both registrations and the agent reasons against the wrong description.
+- A maintainer ran `scripts/install.sh --target=$HOME` for a quick test and forgot to clean up. The next project install at the same scope spawns a drift the user has no easy way to debug.
+- A CI run on a worker that previously cached `~/.claude/skills/` from a stale prior job. `CI=true` skips the gate, but the probe (Phase C) catches it post-install.
+
+## See also
+
+- [`docs/contracts/skill-distribution-channels.md`](skill-distribution-channels.md) — per-tool canonical channel.
+- [`scripts/_lib/scope_guard.sh`](../../scripts/_lib/scope_guard.sh) — guard implementation.
+- [`scripts/cleanup_other_scope.sh`](../../scripts/cleanup_other_scope.sh) — companion cleanup.
+- [`tests/test_cleanup_other_scope.py`](../../tests/test_cleanup_other_scope.py) — safety regression.
+- [`README.md` § Installation](../../README.md) — consumer-facing install path.