@event4u/agent-config 9.8.0 → 9.9.0

package/docs/migration/divergences/src-scripts-check_memory.md

@@ -1,91 +0,0 @@
-# Divergence: check_memory
-
-## Script
-
-- Python: `src/scripts/check_memory.py`
-- TypeScript: `src/scripts/check_memory.ts`
-
-## Symptom
-
-Two byte-level mismatches, both confined to paths that depend on external
-behaviour the TS port cannot reproduce in-language:
-
-### 1. YAML-parse-error class name (`--path`, malformed `.yml`)
-
-When a `.yml` file fails to parse, the finding message ends with the parser's
-exception class name:
-
-- **Python output:** `YAML parse error: ScannerError` (or `ParserError`,
-  `ComposerError`, … — whatever PyYAML's scanner/parser raised for the input)
-- **TS output:** `YAML parse error: YAMLError` (constant)
-- Affected channel(s): stdout (text + json `message` field)
-
-### 2. `--shadow-report` backend label
-
-- **Python output:** `Shadow report — backend: misconfigured` (or whatever
-  `scripts.memory_status.status` returns at runtime), with real per-type
-  hit/shadow counts pulled from `scripts.memory_lookup.retrieve`.
-- **TS output:** `Shadow report — backend: unknown`, all per-type counts 0.
-- Affected channel(s): stdout (text + json `backend` / `per_type` fields)
-
-## Root cause
-
-### 1. YAML-parse-error class name
-
-The Python original catches `except Exception as exc` and renders
-`exc.__class__.__name__`. PyYAML's scanner/parser raises specific subclasses
-(`ScannerError`, `ParserError`, `ComposerError`, `ConstructorError`) chosen by
-its hand-written state machine. The TypeScript port uses the `yaml` npm
-package, whose error taxonomy is structurally different (`YAMLParseError` with
-`code` values like `BAD_INDENT`, `BAD_SCALAR_START`, `TAB_AS_INDENT`,
-`DUPLICATE_KEY`). The two classifiers disagree even on which *phase* the error
-belongs to — e.g. an unquoted backtick scalar is a `ScannerError` in PyYAML
-but is first reported as `BAD_INDENT` by `yaml`. Reproducing PyYAML's exact
-class for an arbitrary malformed input would require porting PyYAML's scanner
-and parser state machines verbatim, which is out of scope for this phase and
-provides no behavioural value — the class name is a debugging hint appended to
-the stable `YAML parse error: ` prefix, not a contract field. The TS port
-emits a constant `YAMLError` after that prefix.
-
-### 2. `--shadow-report`
-
-`_shadow_report` imports `scripts.memory_lookup` (`CURATED_TYPES`,
-`retrieve`, `RetrievalResult`) and best-effort `scripts.memory_status`. Both
-modules are **unported** in Phase 4 (they belong to the memory/telemetry
-cluster, Phase 7). The TS port reproduces the scaffold with a zero-shadow
-result and a `backend: unknown` label so the CLI surface (flag, channels,
-output shape) stays identical until those modules land. The Python original's
-`backend` value (`misconfigured` on this machine) reflects the real
-`memory_status` probe, which has no TS equivalent yet.
-
-## Verdict
-
-`formatting-only` for (1) — the byte difference is a debugging-hint suffix
-with no semantic or consumer impact; the stable `YAML parse error: ` prefix
-(which every caller and test asserts on) is preserved.
-
-`intentional-improvement` is **not** claimed for (2); it is an unavoidable
-consequence of cross-phase ordering. The `--shadow-report` path is scaffolding
-("Ships today as scaffolding" per the Python docstring) whose real backend is
-absent until `@event4u/agent-memory` and the Phase-7 memory modules exist. The
-TS scaffold is behaviourally faithful to the *absent-backend* state the feature
-was designed around (zero shadows). Full byte-parity for `--shadow-report`
-re-opens when `memory_lookup` / `memory_status` are ported.
-
-## Evidence
-
-- pytest suite `tests/test_check_memory.py` and the TS twin
-  `tests/scripts/check_memory.test.ts` assert the **substring**
-  `YAML parse error` (not the class name), so both suites pass under the
-  divergence.
-- Golden-parity tests in the TS suite cover every other `--path` /
-  `--format` / `--append-only` case byte-exact (stdout + stderr + exit) and
-  explicitly exclude the malformed-YAML class-name suffix and
-  `--shadow-report` per this doc.
-
-## Approval
-
-Approved as a Phase-4 documented divergence. Both items are tracked: (1) is
-permanent (cross-library error taxonomy); (2) closes when the Phase-7 memory
-modules are ported and `--shadow-report` can call real `retrieve` /
-`memory_status` twins.

package/docs/migration/divergences/src-scripts-inventory_abstraction_budget.md

@@ -1,65 +0,0 @@
-# Divergence: inventory_abstraction_budget
-
-## Script
-
-- Python: `src/scripts/inventory_abstraction_budget.py`
-- TypeScript: `src/scripts/inventory_abstraction_budget.ts`
-
-## Symptom
-
-In the generated `frontmatter.csv` / Markdown audit table, the
-`dominant_value` column can differ between the Python and TypeScript runs
-**on rows where the top frequency is shared by two or more values** (a
-top-frequency tie). All other columns — `class`, `field`, `total`,
-`distinct`, `dominant_share`, `bloat_candidate` — are byte-identical.
-
-- Observed (CI, ext4): `fm row 5 col 4` — Python `4`, TS `3`.
-- Not observed locally (macOS APFS) — the two filesystems happened to
-  iterate the source files in the same order, so the tie resolved to the
-  same value.
-- Affected channel(s): the `dominant_value` cell only, and only on
-  rows whose `dominant_share` ≤ 50% (no strict majority → a tie is
-  possible).
-
-## Root cause
-
-`dominant_value` is `Counter.most_common(1)[0]` in Python — among the
-max-count group it returns the **first-inserted** value, and insertion
-order is the file-iteration order. Python `Path.glob("**/*.md")` returns
-files in **unsorted OS `readdir` order**; the TS twin's `_globPattern`
-sorts (`out.sort()`). When a field has two values tied at the top count,
-the "first-inserted" winner depends on that file order, so the sorted-TS
-order and the unsorted-Python order can pick different tied values.
-
-This is **unreconcilable**, not a port bug: Python's own glob order is
-OS-nondeterministic, so two Python runs on different filesystems can
-already disagree on the same tie. Forcing the TS twin to sort does not
-help (Python is unsorted); forcing it to read unsorted would still not
-reliably reproduce CPython's recursive-glob traversal order across
-runtimes. Every other derived value (the counts, the share, the bloat
-flag) is order-independent and stays byte-identical.
-
-## Verdict
-
-`formatting-only` — the byte difference is confined to a single
-display-label column that is inherently OS-iteration-order-dependent in
-the Python original itself. No count, share, or bloat-candidate decision
-changes. The column that the script exists to drive (`bloat_candidate`,
-gated on `dominant_share > 0.95`) is unaffected, because a >95% share is a
-strict majority and therefore never tied.
-
-## Evidence
-
-`tests/scripts/inventory_abstraction_budget.test.ts` — the golden-parity
-suite asserts `inventory.csv` byte-identical, and for `frontmatter.csv`
-compares every column byte-identical **except** `dominant_value` on rows
-without a strict majority (`dominant_share` ≤ 50%, where a top tie is
-possible). On rows with `dominant_share > 50%` the dominant value is
-provably unique and IS compared. The Markdown table comparison
-independently permits a per-line divergence only in the `dominant_value`
-cell (pipe-cell index 5) and asserts every other cell identical.
-
-## Approval
-
-- Reviewer: matze4u
-- Date: 2026-06-12

package/docs/migration/divergences/src-scripts-lint_marketplace.md

@@ -1,57 +0,0 @@
-# Divergence: lint_marketplace
-
-## Script
-
-- Python: `src/scripts/lint_marketplace.py`
-- TypeScript: `src/scripts/lint_marketplace.ts`
-
-## Symptom
-
-One byte-level mismatch, confined to the malformed-`marketplace.json` path
-where the message embeds the language's native JSON-parser error text:
-
-- **Python output:** `❌  .claude-plugin/marketplace.json is not valid JSON: Expecting property name enclosed in double quotes: line 1 column 3 (char 2)`
-- **TS output:** `❌  .claude-plugin/marketplace.json is not valid JSON: Expected property name or '}' in JSON at position 2 (line 1 column 3)`
-- Affected channel(s): stdout
-
-Every other case (valid repo, missing file, missing field, version mismatch,
-nonexistent / SKILL.md-less / duplicate skill paths, empty plugins, missing
-owner email, reverse-drift, completeness exemptions) is byte-identical.
-
-## Root cause
-
-The Python original catches `json.JSONDecodeError` and renders `str(exc)`,
-which is CPython's hand-written decoder message
-(`Expecting property name enclosed in double quotes: line L column C (char N)`).
-The TypeScript port catches the `JSON.parse` `SyntaxError` and renders
-`e.message`, which is V8's decoder message
-(`Expected property name or '}' in JSON at position N (line L column C)`).
-The two decoders disagree on wording, position vs. char offset, and clause
-order for the same malformed input. Reproducing CPython's exact decoder
-message in TS would require porting CPython's `json.scanner` state machine
-verbatim — out of scope and of no consumer value: the message is a debugging
-hint appended to the stable `… is not valid JSON: ` prefix, which is the
-actual contract (alongside exit code 1). Mirrors the same cross-language
-parser-error-text divergence already accepted for `check_memory`
-(YAML parse-error class name).
-
-## Verdict
-
-`formatting-only` — the byte difference is a debugging-hint suffix with no
-semantic or consumer impact. The stable `… is not valid JSON: ` prefix and the
-exit code (1) are preserved; both are what callers and tests assert on.
-
-## Evidence
-
-- The TS twin `tests/scripts/lint_marketplace.test.ts` runs python3 and tsx in
-  the same tmp cwd and asserts **byte-identical** stdout/stderr/exit for every
-  fixture **except** the malformed-JSON one, where it asserts the stable
-  contract (exit 1 + the `is not valid JSON` prefix on both) per this doc.
-- The real-repo golden-parity case (the live CI invocation, which has a valid
-  `marketplace.json`) is byte-identical.
-
-## Approval
-
-Approved as a Phase-4 documented divergence. Permanent — it stems from the
-cross-language JSON-decoder error taxonomy, the same class as the accepted
-`check_memory` YAML divergence.

package/docs/migration/divergences/src-scripts-lint_mcp_registry_manifest.md

@@ -1,70 +0,0 @@
-# Divergence: lint_mcp_registry_manifest
-
-## Script
-
-- Python: `src/scripts/lint_mcp_registry_manifest.py`
-- TypeScript: `src/scripts/lint_mcp_registry_manifest.ts`
-
-## Symptom
-
-**Conditional, latent divergence — not reached on the real repo.** Golden
-parity (python3 vs tsx, no-arg and `--quiet`) is byte-identical today, because
-`dist/mcp/` is absent in this worktree, so both versions short-circuit on the
-first artefact check and emit:
-
-- stderr: `❌  missing: dist/mcp/registry-manifest.json`
-- exit: 1
-
-The only branch where the two versions *would* differ is the schema-validation
-failure message, which fires solely on a **structurally invalid** manifest
-(after all four `dist/mcp/*` artefacts exist):
-
-- **Python output:** `❌  schema validation: <jsonschema e.message> at <list(e.absolute_path)>`
-  — wording produced by `jsonschema.Draft202012Validator`.
-- **TS output:** `❌  schema validation: <subset-validator message> at [<path…>]`
-  — wording produced by the hand-rolled Draft-2020-12 subset validator in the
-  TS port.
-- Affected channel(s): stderr (only on an invalid manifest)
-
-The stable prefix `schema validation: ` and the surrounding control flow
-(which artefact is checked, in what order, the exit code 1, the `❌  `
-glyph + two-space prefix) are identical. Only the embedded
-validator-specific error string and the `at [...]` path rendering can differ.
-
-## Root cause
-
-Python uses `jsonschema.Draft202012Validator(schema).validate(manifest)` and
-formats `f"schema validation: {e.message} at {list(e.absolute_path)}"`. The TS
-runtime has only `ajv` v6 (Draft-07) available — it cannot evaluate a
-Draft-2020-12 schema with `jsonschema`-identical diagnostics. Following the
-established Wave-4b pattern (`src/scripts/lint_discovery_manifest.ts`), the TS
-port ships a faithful Draft-2020-12 **subset** validator that ACCEPTS every
-valid manifest (the golden path) but renders rejection messages in its own
-wording. Matching `jsonschema`'s per-keyword English message text + Python
-`repr` of the instance + `list(absolute_path)` rendering byte-for-byte is out
-of scope and provides no consumer value (the manifest is generated, so an
-invalid manifest is a build bug surfaced equally by either version).
-
-## Verdict
-
-`intentional-improvement` — both behaviors reject an invalid manifest with a
-non-zero exit and a `schema validation: …` stderr line; the TS wording is a
-deliberate, documented substitute for the unavailable Draft-2020-12
-`jsonschema` diagnostics. The accept/reject decision (the consumer-relevant
-behavior) is preserved.
-
-## Evidence
-
-- `tests/scripts/lint_mcp_registry_manifest.test.ts`:
-  - the behavioural-spec block asserts the subset validator ACCEPTS a fully
-    valid manifest and REJECTS each malformed shape (wrong `version` const,
-    missing required key, unknown additional property, bad `status` enum,
-    `< minItems` registries) — i.e. the accept/reject contract holds.
-  - the golden-parity block asserts byte-identical stdout + stderr + exit on
-    the real repo for both the no-arg and `--quiet` invocations (the
-    `missing:` branch), proving no actual mismatch ships today.
-
-## Approval
-
-- Reviewer: <pending>
-- Date: <pending>

package/docs/migration/divergences/src-scripts-spotcheck_thin_root.md

@@ -1,60 +0,0 @@
-# Divergence: spotcheck_thin_root
-
-## Script
-
-- Python: `src/scripts/spotcheck_thin_root.py`
-- TypeScript: `src/scripts/spotcheck_thin_root.ts`
-
-## Symptom
-
-The entire `main()` is a **live AI-council call** (Anthropic `claude-sonnet-4-5`
-+ OpenAI `gpt-4o`) that requires API keys + network access and produces a
-**non-deterministic** report — per-call `latency_ms` and `tokens_in/out` vary
-every run, and the model prose is not reproducible. There is therefore no
-golden-parity path: python3 vs tsx output cannot be byte-compared, and the
-script cannot run inside CI.
-
-- Affected channel(s): written files (`thin-root-platform-spotcheck.md` /
-  `.json`) + stderr (`Running …`, `✅  Wrote …`).
-
-## Root cause
-
-The Python original imports three still-Python `ai_council` modules with no TS
-twin in this wave:
-
-- `ai_council.clients` — `AnthropicClient`, `OpenAIClient`,
-  `load_anthropic_key`, `load_openai_key` (~1,385 lines, network clients).
-- `ai_council.orchestrator` — `CostBudget`, `CouncilQuestion`, `consult`
-  (~1,206 lines).
-- `ai_council.pricing` — `load_prices` (ported as `ai_council/pricing.ts`).
-
-A `.ts` cannot import a `.py`, and the "PORT + import, never inline the
-un-ported logic" rule forbids re-implementing those ~2,800 lines of
-network-calling code inside this twin. Per the established precedent for
-un-ported Python deps (`check_discovery_determinism.ts` runs its un-ported
-scanner via `python3`; `smoke_quickstart.ts` Step 3 imports `decision_engine`
-via a `python3` shim), the TS twin delegates the live `consult(...)` call to a
-`python3` shim that imports the real Python modules. The deterministic parts —
-artefact assembly, the `json.dumps(indent=2)` writer, the Markdown report
-layout, the stderr lines — are ported faithfully in TS.
-
-## Verdict
-
-`intentional-improvement` — both behaviors are defensible; the TS twin
-preserves the byte-shape of the written report and the stderr surface while
-running the unportable, non-deterministic, network-bound council step through
-the still-Python modules. Porting the two large network clients is out of this
-wave's scope and tracked separately.
-
-## Evidence
-
-`tests/scripts/spotcheck_thin_root.test.ts` asserts the module imports without
-a top-level throw and exposes the `main` entry point (the deterministic CLI
-surface). The live council path (network + keys) is excluded from CI by
-construction — there is no fixture that could pin a non-deterministic
-LLM-latency report.
-
-## Approval
-
-- Reviewer: <pending — porting subagent, Wave 8h>
-- Date: 2026-06-13

package/docs/migration/divergences/src-scripts-validate_agent_settings.md

@@ -1,58 +0,0 @@
-# Divergence: validate_agent_settings
-
-## Script
-
-- Python: `src/scripts/validate_agent_settings.py`
-- TypeScript: `src/scripts/validate_agent_settings.ts`
-
-## Symptom
-
-Only the **error-message prose** of a schema violation can differ. The exit
-code, the GitHub `::error file=…::<loc>:` location prefix, the violation
-count, the summary line, and the clean-pass line are byte-identical.
-
-- **Python output (violation):** `::error file=…::rule_loading_tier: 'lean' is not one of ['minimal', 'balanced', 'full', 'custom']`
-  — the trailing clause is produced verbatim by the `jsonschema` library and
-  is Python-version-dependent.
-- **TS output (violation):** same `::error file=…::rule_loading_tier:` prefix
-  and field path; the enum/type clause is reproduced by a minimal Draft-07
-  validator (`_iter_errors`) and may differ in exact wording from a given
-  `jsonschema` release.
-- Affected channel(s): stdout (only the prose tail of a violation line).
-
-## Root cause
-
-The Python script delegates message text to `jsonschema.Draft7Validator`,
-whose `ValidationError.message` wording is not a stable contract (it has
-changed across `jsonschema` releases). The package ships no `ajv`/jsonschema
-dependency for the TS side and `package.json` is frozen for this wave, so the
-twin implements the exact constraint subset the shared schema uses (`type`
-object/string, string `enum`, `properties`, permissive `additionalProperties:
-true`) and approximates the message text. Per ADR-200 §4 the parity contract
-for schema-validation findings is **exit code + flagged field-paths**, not
-byte-exact jsonschema prose.
-
-## Verdict
-
-`formatting-only` — the constraint set, the violating field path, the error
-location prefix, the violation count, and both summary lines match exactly;
-only the human-readable enum/type clause may differ, with no semantic or
-consumer impact (CI greps the `::error file=…::<loc>:` location, not the tail).
-
-## Evidence
-
-- `tests/scripts/validate_agent_settings.test.ts` asserts: every valid
-  `rule_loading_tier` accepted; an out-of-enum value rejected **at the
-  `['rule_loading_tier']` path** with a message naming the allowed values;
-  the legacy `cost_profile` key tolerated (shipped reality); nested enums
-  (`memory.cadence`, `model.auto_switch`, `worktrees.mode`) enforced at the
-  correct paths.
-- Golden parity: the same test runs `python3 validate_agent_settings.py` vs
-  `tsx validate_agent_settings.ts` on the real repo and asserts stdout, stderr,
-  and exit code are byte-identical (the clean repo never triggers a violation
-  line, so the only golden-parity surface is the OK summary — byte-identical).
-
-## Approval
-
-- Reviewer: <pending — porting subagent, ADR-200 Phase 4 / Wave 4c>
-- Date: 2026-06-11

package/docs/migration/node-floor.md

@@ -1,86 +0,0 @@
-# Node Floor Audit
-
-> Phase 1 Step 12 of `agents/roadmaps/archive/road-to-typescript-only-scripts.md`.
-> Decision: which Node.js floor the TS-only script suite supports, where it is
-> enforced, and what CI tests.
-
-## Facts (as audited 2026-06-11, branch feat/py2ts-phase1-infra)
-
-| Surface | Value | Source |
-|---|---|---|
-| `engines.node` | `>=20.11.0` | `package.json:53-55` |
-| tsconfig target | `ES2022` (`module: ESNext`, `moduleResolution: Bundler`) | `tsconfig.json:3-5` |
-| tsconfig lib | `ES2022` (+ `DOM` in `tsconfig.ui.json:4`, `tsconfig.test.json:6`) | tsconfig files |
-| CI — tests.yml | Node `20` | `.github/workflows/tests.yml:241` |
-| CI — release-drift.yml | Node `20` | `.github/workflows/release-drift.yml:44` |
-| CI — publish-npm.yml | Node `20` | `.github/workflows/publish-npm.yml:48` |
-| CI — smoke-public-install.yml | matrix `node: ['20', '22']` × 3 OS | `smoke-public-install.yml:78-80` |
-| CI — deploy-mcp-worker.yml | Node `22` | `deploy-mcp-worker.yml:68` |
-| `engine-strict` | not set (no `.npmrc`) — `engines` is advisory only | repo root |
-| Installer Node check | none today (Python installer never inspects `process.version`) | grep of `src/scripts/install*`, `setup.sh` |
-
-Feature scan of `src/` TypeScript (sampled, not exhaustive):
-
-- `node:` protocol imports — 34 files (Node ≥ 16; trivially within floor).
-- Global `fetch` in Node-side code — `src/server/token.ts` (stable without flag
-  since Node 18, marked stable in 21; fine on ≥ 20.11).
-- No hits for `structuredClone`, top-of-module top-level `await`,
-  `Array.prototype.at(-…)`, `Object.hasOwn`, `findLast` in `src/` TS.
-- Browser-only `fetch` usage (`src/ui/api.ts`) is covered by the `DOM` lib, not
-  the Node floor.
-
-Conclusion of the scan: nothing in the current TS code requires more than
-Node 18; the ES2022 compile target is the binding constraint and is fully
-served by every Node ≥ 18.12. The floor question is therefore a **support
-lifecycle** decision, not a syntax one.
-
-## Recommendation
-
-**Raise the floor to Node `>=22.0.0` as part of the TS-only migration; test
-22 (minimum) and 24 (current LTS) in CI.** Keep `>=20.11.0` only until the
-first major/breaking release of the migration lands, then flip — the bump is a
-semver-major signal per the package's versioning policy.
-
-## Rationale
-
-- **Node 20 is end-of-life.** Its maintenance window ended April 2026. A
-  migration that will ship through 2026/27 should not anchor its floor on a
-  line that no longer receives security fixes; keeping it implies supporting
-  consumers on an unpatched runtime.
-- **Node 22 (maintenance LTS) and 24 (active LTS) are the 2026 reality.** CI
-  already runs 22 in two workflows; the smoke matrix already proves installs
-  on 22. Raising the floor to 22 costs no code changes (the feature scan shows
-  no >ES2022 usage to add or remove) and removes a dead line from the matrix.
-- **Consumer compatibility risk is low and visible.** The package is a dev-time
-  tool invoked via `npx`/global install, not a production runtime dependency.
-  Consumers still on Node 20 get a clear, immediate failure at install time
-  (see Enforcement) rather than a latent one.
-- **Why not 24 as the floor:** 24 only entered LTS in late 2025; many CI images
-  and corporate baselines still pin 22. Floor = oldest non-EOL LTS (22),
-  matrix-test up to current LTS (24).
-
-## Enforcement points
-
-1. **`package.json` `engines`** — flip to `">=22.0.0"` at the breaking release.
-   Advisory only without `engine-strict`; npm prints a warning, pnpm/yarn fail
-   harder. Do **not** set `engine-strict` repo-wide (it would also bind
-   maintainers); rely on point 2 for the hard gate.
-2. **TS installer runtime check (the hard gate).** Phase 3 Step 2 already
-   requires "Node-version check with a clear error": the TS installer must
-   compare `process.versions.node` against the floor on startup and fail with
-   an actionable message before writing anything. This is the enforcement the
-   Python installer never had — it must land with the TS installer.
-3. **CI matrix** — pin the floor and the current LTS:
-   - `smoke-public-install.yml`: `node: ['22', '24']` (replacing `['20', '22']`).
-   - `tests.yml` / `release-drift.yml` / `publish-npm.yml`: bump single-version
-     jobs `20` → `22`; add a `24` leg to `tests.yml` if budget allows.
-4. **Docs** — README Quickstart and `docs/getting-started.md` state the floor
-   explicitly ("requires Node 22+"); CHANGELOG `### Breaking` entry +
-   `BREAKING_CHANGES.md` index the bump per the versioning policy.
-
-## Decision status
-
-Recommended here; the `engines` flip itself is release-gated (semver-major)
-and should ride the first breaking release of the TS migration, not this
-infra PR. Until then `>=20.11.0` stays in `package.json`, and CI keeps one
-Node 20 leg solely to honor the published floor.

package/docs/migration/v1-to-v2.md

@@ -1,156 +0,0 @@
-# Migration — v1 → v2 (npx-only runtime)
-
-> **Status:** active. The one-shot `npx @event4u/agent-config migrate`
-> is implemented in `scripts/_cli/cmd_migrate.py`; its action matrix +
-> exit-code contract live in
-> [`docs/contracts/migrate-command.md`](../contracts/migrate-command.md).
-> This document is the user-facing narrative; the contract is the
-> normative reference.
-
-## Why this change
-
-v2 retires the local-install scheme (Composer dependency, npm
-`postinstall`, `--global` symlink namespace under `~/.claude/`,
-`~/.cursor/`, `~/.codeium/windsurf/`, `~/.config/agent-config/`) in
-favour of an **npx-only runtime**. The trade-off and the council's Q1
-rejection + the user's override are recorded in
-[`docs/architecture.md` § Distribution model](../architecture.md#distribution-model--npx-only--version-pin-governance).
-
-## TL;DR
-
-```bash
-npx @event4u/agent-config migrate
-```
-
-One command, idempotent. Re-runs on an already-migrated repo do nothing.
-
-## What disappears from the consumer
-
-| Path / entry                                          | Reason                                  |
-|-------------------------------------------------------|-----------------------------------------|
-| `composer.json` → `require-dev.event4u/agent-config`  | No Composer dependency under v2.        |
-| `composer.lock` line for `event4u/agent-config`       | Same; lockfile updated by Composer.     |
-| `package.json` → `devDependencies.@event4u/agent-config` | No npm dependency under v2.          |
-| `package-lock.json` / `pnpm-lock.yaml` entries        | Same.                                   |
-| `node_modules/@event4u/agent-config/`                 | Removed by the package manager once the `package.json` entry is gone. |
-| `vendor/event4u/agent-config/`                        | Removed by Composer once the require entry is gone. |
-| `~/.claude/{rules,skills}/event4u/`                   | Retired `--global` namespace dir.       |
-| `~/.cursor/rules/imported/event4u/`                   | Same.                                   |
-| `~/.codeium/windsurf/global_workflows/event4u/`       | Same.                                   |
-| `~/.config/agent-config/{rules,skills}/event4u/`      | Same (fallback path).                   |
-| Legacy `.gitignore` block lines marked `event4u/agent-config (legacy local install)` | Replaced by the v2 block written by `sync-gitignore`. |
-
-The retired `templates/global-install-manifest.yml` shipped inside the
-package and is gone in v2; consumers never carried it directly.
-
-## What appears in the consumer
-
-| Path / entry                                          | Owner / shape                           |
-|-------------------------------------------------------|-----------------------------------------|
-| `.agent-settings.yml` → `agent_config_version: "<pin>"` | Project version pin, reviewed in PRs. |
-| `.agent-settings.yml` → `update_check:` block         | Defaults shipped by `init`; opt-out per knob. |
-| Updated `.gitignore` block                            | v2 entries written by `sync-gitignore`. |
-
-The per-tool glue (`.claude/`, `.cursor/`, `.clinerules/`,
-`.windsurfrules`, `GEMINI.md`, `.github/copilot-instructions.md`,
-`.augment/`, `.vscode/settings.json`) keeps the same shape as v1 — only
-the source that writes them changed (from `vendor/` /
-`node_modules/` scripts to the npx-resolved runtime).
-
-## The `migrate` command
-
-```bash
-npx @event4u/agent-config migrate              # apply, real changes
-npx @event4u/agent-config migrate --dry-run    # plan only, zero writes
-```
-
-One opinionated command, one flag. The full action matrix +
-exit-code contract is documented in
-[`docs/contracts/migrate-command.md`](../contracts/migrate-command.md);
-the operations summary below is the narrative form.
-
-Order of operations (fixed; foundation-first):
-
-1. Detect every legacy signal in one pass: `composer.json` require
-   entry, `package.json` devDependency, managed symlinks pointing
-   into `vendor/` / `node_modules/`, v0
-   `.implement-ticket-state.json`, project-local `.agent-settings.yml`
-   / `.agent-user.yml` (flat or under `settings/`), empty
-   `agent-config/` shell.
-2. Under `--dry-run`, print the planned change set and stop with
-   exit 0.
-3. Strip the package entries from `package.json` / `composer.json`
-   in-place; preserve sibling keys + formatting.
-4. Purge legacy symlinks; preserve user-managed symlinks elsewhere
-   with a warning.
-5. Migrate `.implement-ticket-state.json` → `.work-state.json`
-   (renames the v0 source to `.bak`).
-6. **Hard-delete** legacy project-local config files. The wizard
-   (`agent-config setup`) recreates fresh global config on the next
-   run — deletion is the design, not a regression.
-7. Remove the empty `agent-config/` shell directory if present.
-8. Refresh the `.gitignore` agent-config managed block.
-9. Print a summary listing every action taken.
-
-Idempotency: re-running on a fully-migrated repo prints
-*"already migrated — nothing to do"* and exits 0 without touching
-the filesystem.
-
-## Verification after migration
-
-```bash
-npx @event4u/agent-config doctor    # P3 — runtime sanity check
-```
-
-Expected: pin resolved, no v1 markers detected, `update_check` reachable.
-
-## v2 → v2.4 — `~/.event4u/agent-config/` namespace move
-
-v2.4 relocates package-owned user-scope state from
-`~/.config/agent-config/` to `~/.event4u/agent-config/`. Tool anchors
-(`~/.claude/`, `~/.augment/`, `~/.cursor/`, `~/.codeium/windsurf/`) are
-**not** moved — those belong to their host tools.
-
-### What moves
-
-| Old path                                            | New path                                                |
-|-----------------------------------------------------|---------------------------------------------------------|
-| `~/.config/agent-config/agent-settings.yml`         | `~/.event4u/agent-config/agent-settings.yml`            |
-| `~/.config/agent-config/installed.lock`             | `~/.event4u/agent-config/installed.lock`                |
-| `~/.config/agent-config/installed-tools.yml`        | `~/.event4u/agent-config/installed-tools.yml`           |
-| `~/.config/agent-config/update-check.json`          | `~/.event4u/agent-config/update-check.json`             |
-| `~/.config/agent-config/ai-council/`                | `~/.event4u/agent-config/ai-council/`                   |
-
-### Migration — zero action required
-
-A one-shot auto-migration shim runs on the first `init` / `update` /
-`uninstall` after upgrading to ≥ 2.4:
-
-1. If `~/.event4u/agent-config/` already exists → no-op.
-2. Otherwise, copy every file from `~/.config/agent-config/` to the new
-   path, preserving mtimes.
-3. Drop a `MIGRATED.md` breadcrumb in the legacy dir pointing at the new
-   home. Legacy files stay readable; loaders fall back to them until a
-   subsequent install overwrites the new path.
-
-Override the target dir with `EVENT4U_HOME=/some/path` if you keep a
-non-standard home (`$HOME` substitute) or want to test the migration
-against a sandbox.
-
-### Claude Desktop — new bundle output
-
-v2.4 ships a real Claude Desktop deployment instead of the
-marker-only stub. Running `npx @event4u/agent-config init
---tools=claude-desktop` (or any superset that includes it) now produces
-one ZIP per `.claude/skills/<name>/` under
-`~/.event4u/agent-config/claude-desktop/bundles/`. Import them via
-Claude Desktop → Customize → Skills → Upload. See
-[`docs/setup/per-ide/claude-desktop.md`](../setup/per-ide/claude-desktop.md)
-for the click-through.
-
-## See also
-
-- [`docs/architecture.md` § Distribution model](../architecture.md#distribution-model--npx-only--version-pin-governance) — Q1 council rejection + override + pin substitution.
-- [`agents/roadmaps/road-to-portable-runtime-and-update-check.md`](../../agents/roadmaps/road-to-portable-runtime-and-update-check.md) — full delivery plan and acceptance criteria.
-- [`agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md`](../../agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md) — v2.4 namespace + bundle delivery plan.
-- [`docs/installation.md`](../installation.md) — v2 install reference.