@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/settings-api.md

@@ -1,264 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-18
----
-
-# Settings GUI — REST API Contract (v1)
-
-> Local-only HTTP API exposed by `agent-config ui:serve` and reused by
-> `agent-config config` (alias `settings`) / `agent-config setup`. Listens on `127.0.0.1`
-> only; no auth, no cross-origin. The browser SPA is the sole client —
-> the legacy `/onboard` chat skill has been retired.
->
-> Server-side validators live in `src/server/schemas/`; the JSON-Schema
-> emitted at `GET /api/v1/schema` is derived from those Zod modules via
-> `zod-to-json-schema` so client and server cannot drift.
-
-## Conventions
-
-- Base path: `/api/v1`. Any breaking change bumps the version segment.
-- Content type: `application/json; charset=utf-8` on every request and
-  response unless noted.
-- Errors: HTTP status carries the verdict; bodies are
-  `{ error: { code, message, fields?: Array<{ path, message }> } }`.
-- Time format: ISO-8601 UTC (`2026-05-20T14:23:11.842Z`).
-- File mtime: integer milliseconds since epoch (`fs.statSync(...).mtimeMs`
-  truncated to integer) — wire-stable across JSON parsers.
-- Optimistic locking: every endpoint that mutates an on-disk file
-  echoes `lastModified` on read and requires `If-Unmodified-Since` on
-  write. Drift returns **409 Conflict** with the current file body so
-  the client can render a 3-way merge.
-
-## Endpoints
-
-### `GET /api/v1/schema`
-
-Returns the JSON-Schema rendition of `settingsSchema` and `userMdSchema`
-so the SPA can build forms without bundling Zod.
-
-Response (200):
-
-```json
-{
-    "settings": { "$schema": "...", "type": "object", "properties": { ... } },
-    "userMd":   { "$schema": "...", "type": "object", "properties": { ... } },
-    "generatedAt": "2026-05-20T14:23:11.842Z"
-}
-```
-
-### `GET /api/v1/settings`
-
-Returns the **three-layer merged** settings tree plus the freshness
-token for optimistic locking. Merge order (per **ADR-020** + roadmap
-`road-to-global-only-install` § Phase 2.2):
-
-```text
-defaults (src/config/agent-settings.template.yml)
-  < global (~/.event4u/agent-config/settings/.agent-settings.yml)
-    < project (<projectRoot>/settings/.agent-settings.yml, optional)
-```
-
-Defaults come from the package template with `__RULE_LOADING_TIER__` /
-`__USER_TYPE__` placeholders substituted for their permissive defaults
-(`balanced` / `""`). Global and project layers are read with the typed
-subdir preferred over the legacy flat path. The route mirrors
-`scripts/install.py::read_layered_settings` 1:1 so the Python installer
-and the Fastify GUI cannot drift.
-
-Response (200):
-
-```json
-{
-    "values":       { "rule_loading_tier": "balanced", "...": "..." },
-    "lastModified": 1747749791842,
-    "path":         "settings/.agent-settings.yml",
-    "legacyHints":  { "user_name": "Matze" },
-    "sources":      { "global": ["rule_loading_tier", "personal.ide"], "project": [] }
-}
-```
-
-`sources` (road-to-setup-experience § Phase 5.4) carries the dotted
-leaf paths present in each layer FILE (not the merged tree) so the
-settings hub can badge which layer supplies a value — a `project`
-entry overrides a `global` one per the merge order above.
-
-`legacyHints` is an out-of-band sidecar carrying values that have moved
-out of `settingsSchema` but still live in a pre-v2 file on disk. Keys
-are omitted when empty, never `null`. Current hints:
-
-| Key         | Source (legacy)        | New home                                |
-| ----------- | ---------------------- | --------------------------------------- |
-| `user_name` | `personal.user_name`   | `.agent-user.md` &rarr; `identity.name` |
-
-The wizard consumes hints on first run only — when `.agent-user.md`
-does not yet exist — to pre-fill the merged identity field. Subsequent
-PUTs strip the legacy keys (Zod-unknown), so the next read returns no
-hints.
-
-Errors: **404** when **neither** the global nor the project file
-exists (defaults alone are not an "installed" state — the SPA should
-redirect to `/#/wizard/Welcome`); **500** with `code=YAML_PARSE` when
-either layer is on disk but unparseable (body includes the line/column).
-
-### `POST /api/v1/settings/diff`
-
-Computes the merged delta without writing. Used by the **Preview
-changes** modal. Request:
-
-```json
-{
-    "values":             { "...": "..." },
-    "ifUnmodifiedSince":  1747749791842
-}
-```
-
-Response (200): `{ "changes": [{ "path": "rule_loading_tier", "from": "minimal", "to": "balanced" }, ...] }`.
-
-Errors: **409** on mtime drift; **422** on validation failure (`fields`
-populated).
-
-### `PUT /api/v1/settings`
-
-Validates, merges with disk, writes atomically.
-
-Request: same shape as `/diff`. Required header:
-`If-Unmodified-Since: <ms-epoch>`.
-
-Response (200): `{ "lastModified": <new-ms-epoch>, "writtenPaths": [".agent-settings.yml"] }`.
-
-Errors: **412 Precondition Required** when the header is absent;
-**409 Conflict** when the on-disk mtime is newer than the header value;
-**422 Unprocessable Entity** with per-field errors on validation
-failure; **500** with `code=ATOMIC_WRITE` if the temp-rename loop fails.
-
-### `GET /api/v1/settings/changes`
-
-Pending upgrade-time settings-surface delta
-(road-to-settings-change-review). The installer persists the flattened
-settings surface (`state/settings-surface.json`: per dotted leaf its
-type / default / enum / description + package version) on every global
-install; when a previous snapshot from a different version exists it
-computes the semantic delta and writes `state/settings-delta.json` —
-that file is what this route serves. Classification against the user's
-current values happens client-side via the shared
-`src/shared/settingsSurface.ts` module (`must_fix` / `adopt` /
-`review` / `info`).
-
-Response (200):
-
-```json
-{
-    "delta": {
-        "oldVersion": "8.3.0",
-        "newVersion": "8.4.0",
-        "changes": [
-            { "key": "personal.autonomy", "kind": "default_changed", "old": { "...": "..." }, "new": { "...": "..." } },
-            { "key": "discipline_profile", "kind": "added", "new": { "...": "..." } }
-        ]
-    },
-    "source": "writeRoot"
-}
-```
-
-`kind` &isin; `added | removed | default_changed | enum_added |
-enum_removed | type_changed`. `source` is `userGlobal` when the delta
-was found via the package-sandbox read fallback.
-
-Errors: **404** with `code=NO_PENDING_CHANGES` when no (parseable)
-delta file exists.
-
-### `POST /api/v1/settings/changes/ack`
-
-Clears the pending delta after the review form is resolved (or
-dismissed). Deletes only `<writeRoot>/state/settings-delta.json` —
-never the real machine's file when running in a sandbox. Idempotent.
-
-Response (200): `{ "ok": true, "cleared": true }` (`cleared: false`
-when nothing was pending; `dryRun: true` and no deletion in dry-run
-mode).
-
-A matching `settings-review-pending` doctor check warns while the
-delta file exists; the settings hub renders a review banner linking to
-`#/settings/changes`.
-
-### `GET /api/v1/user-md`
-
-Reads `<projectRoot>/.agent-user.md`. Returns `{ body: '', exists: false, lastModified: null }`
-when the file is missing (wizard pre-fill case).
-
-### `GET /api/v1/user-md/template`
-
-Returns the package-shipped template (`src/templates/agent-user.md`) when
-present, else 204 No Content. Wizard uses this to pre-fill the textarea
-on first run.
-
-### `PUT /api/v1/user-md`
-
-Validates the body through `userMdSchema` (`gray-matter` parse must
-succeed; ≤ 8 000 chars). Atomic-writes with mode 0600.
-
-Required header: `If-Unmodified-Since: <ms-epoch>` (omitted only when
-`exists=false` on the prior GET — server treats absence as "create new").
-
-### `GET /api/v1/wizard/state`
-
-Returns the persisted partial wizard state, or
-`{ step: 0, totalSteps: <N>, partial: {}, startedAt: null }` when no
-state file exists.
-
-### `POST /api/v1/wizard/state`
-
-Persists partial state between step transitions. Body:
-`{ step: number, partial: Record<string, unknown> }`.
-
-### `POST /api/v1/wizard/finish`
-
-Two-Phase-Commit (council HIGH 2026-05-18): assigns a `txnId`, writes
-`settings.yml.tmp-{txnId}` + `user-md.tmp-{txnId}` + an empty
-`wizard.commit-intent-{txnId}` marker, renames both target files, then
-deletes the marker. Server boot replays orphaned markers idempotently.
-
-Response (200): `{ writtenPaths: string[], txnId: string }`.
-
-Errors: **500** with `code=TXN_PARTIAL` when the marker survives a crash
-(client should redirect the user to a "your last save is being
-recovered" screen and refetch state).
-
-## CLI: `agent-config settings migrate`
-
-Companion to the layered reader (ADR-020). Lifts an existing
-project-local `.agent-user.yml` / `.agent-settings.yml` into
-`~/.event4u/agent-config/`. Idempotent — refuses to overwrite a
-non-empty global file without `--force`. Order matches Phase 5
-amendment A2 (`copy → verify`; the destructive `move` step is owned by
-the unified `agent-config migrate` command, not this subcommand — see
-`docs/contracts/migrate-command.md`).
-
-Flags:
-
-- `--from <path>` — project root to read from (default: `cwd`).
-- `--force` — overwrite a non-empty global file.
-- `--dry-run` — list intended copies; zero writes; exit 0.
-
-Exit codes: `0` on success or no-op; `1` on validation failure or a
-non-empty global file without `--force`.
-
-## Status codes summary
-
-| Code | Meaning                                              |
-| ---- | ---------------------------------------------------- |
-| 200  | Success                                              |
-| 204  | No content (template-not-shipped case)               |
-| 404  | Target file missing                                  |
-| 409  | `If-Unmodified-Since` drift                          |
-| 412  | `If-Unmodified-Since` header missing on write        |
-| 422  | Validation failure (`error.fields` populated)        |
-| 500  | YAML parse / atomic-write / 2PC partial recovery     |
-
-## Test fixtures
-
-Round-trip fixtures live in `tests/server/fixtures/`. Every endpoint
-above has a happy-path test in `tests/server/<endpoint>.test.ts` and at
-least one error-path test (409 or 422). The schema↔template parity
-test (`tests/server/schemas/parity.test.ts`) is the gate that keeps
-`settingsSchema` and `src/config/agent-settings.template.yml` in lockstep.

package/docs/contracts/settings-gui-agent-mode.schema.json

@@ -1,128 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://event4u.app/contracts/settings-gui-agent-mode.schema.json",
-    "title": "settings-gui-agent-mode",
-    "description": "Machine-readable mode of `agent-config settings`. When invoked with `--agent`, the CLI emits a single JSON envelope to stdout instead of opening a browser; the caller (chat agent, CI script, IDE extension) drives the wizard or settings editor via the same `/api/v1/*` routes through this envelope. Lives at `docs/contracts/settings-gui-agent-mode.schema.json` per the frontend-engineer council finding (roadmap line 333).",
-    "type": "object",
-    "additionalProperties": false,
-    "required": ["version", "kind", "endpoint", "auth"],
-    "properties": {
-        "version": {
-            "type": "string",
-            "const": "1",
-            "description": "Envelope schema version. Bumped on breaking changes."
-        },
-        "kind": {
-            "type": "string",
-            "enum": ["wizard", "settings"],
-            "description": "Which mode the server booted in. `wizard` = first-run flow; `settings` = settings editor."
-        },
-        "endpoint": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["base", "discoveryFile"],
-            "properties": {
-                "base": {
-                    "type": "string",
-                    "format": "uri",
-                    "pattern": "^http://127\\.0\\.0\\.1:[0-9]+/?$",
-                    "description": "Fastify server URL. Always 127.0.0.1; the port is picked from the foundation roadmap's port-picker."
-                },
-                "discoveryFile": {
-                    "type": "string",
-                    "description": "Absolute path to `.agent-config/skill-bridge.port` / `.token` / `.pid` discovery file the caller should read for handshake."
-                }
-            }
-        },
-        "auth": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["scheme", "token"],
-            "properties": {
-                "scheme": {
-                    "type": "string",
-                    "const": "Bearer"
-                },
-                "token": {
-                    "type": "string",
-                    "description": "Random per-boot token; the caller MUST send `Authorization: Bearer <token>` on every API request. Token rotates on every `agent-config settings` boot."
-                }
-            }
-        },
-        "routes": {
-            "type": "object",
-            "description": "Stable list of routes the caller may use. Schema-bound to roadmap step 0.4; new routes added here MUST land in `docs/contracts/settings-api.md` simultaneously.",
-            "additionalProperties": false,
-            "properties": {
-                "settings": {
-                    "type": "object",
-                    "additionalProperties": false,
-                    "properties": {
-                        "get": {"type": "string", "const": "/api/v1/settings"},
-                        "diff": {"type": "string", "const": "/api/v1/settings/diff"},
-                        "put": {"type": "string", "const": "/api/v1/settings"}
-                    }
-                },
-                "userMd": {
-                    "type": "object",
-                    "additionalProperties": false,
-                    "properties": {
-                        "get": {"type": "string", "const": "/api/v1/user-md"},
-                        "put": {"type": "string", "const": "/api/v1/user-md"},
-                        "template": {"type": "string", "const": "/api/v1/user-md/template"}
-                    }
-                },
-                "wizard": {
-                    "type": "object",
-                    "additionalProperties": false,
-                    "properties": {
-                        "state": {"type": "string", "const": "/api/v1/wizard/state"},
-                        "finish": {"type": "string", "const": "/api/v1/wizard/finish"}
-                    }
-                }
-            }
-        },
-        "shutdown": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["signal", "timeoutSeconds"],
-            "properties": {
-                "signal": {
-                    "type": "string",
-                    "enum": ["SIGTERM", "SIGINT"],
-                    "description": "Signal the caller sends to gracefully stop the server."
-                },
-                "timeoutSeconds": {
-                    "type": "integer",
-                    "minimum": 1,
-                    "maximum": 60,
-                    "description": "Caller's grace window before SIGKILL. Server drains in-flight requests within this window."
-                }
-            }
-        },
-        "capabilities": {
-            "type": "array",
-            "description": "Optional feature flags the server advertises. Callers MAY ignore unknown values for forward compatibility.",
-            "items": {
-                "type": "string",
-                "enum": ["wizard.resumeState", "settings.diff", "settings.optimisticLock", "userMd.template", "wizard.crashRecovery"]
-            },
-            "uniqueItems": true
-        }
-    },
-    "examples": [
-        {
-            "version": "1",
-            "kind": "settings",
-            "endpoint": {
-                "base": "http://127.0.0.1:41999/",
-                "discoveryFile": "/Users/dev/proj/.agent-config/skill-bridge.port"
-            },
-            "auth": {
-                "scheme": "Bearer",
-                "token": "9f3a7b2c1d4e8f6a"
-            },
-            "capabilities": ["settings.diff", "settings.optimisticLock"]
-        }
-    ]
-}

package/docs/contracts/settings-sync-yaml-subset.md

@@ -1,139 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Settings-sync YAML subset
-
-**Purpose.** Pin the YAML feature set that `.agent-settings.yml` and
-`src/config/agent-settings.template.yml` may use, so contributors can cite a
-contract instead of inferring it from
-[`scripts/sync_yaml_rt.py`](../../src/scripts/sync_yaml_rt.py) source. The
-sync engine ([ADR](adr-settings-sync-engine.md)) is a custom stdlib-only
-round-trip parser/emitter; staying inside the subset below is what
-keeps user-line preservation (every byte of every user line round-trips
-unchanged unless the merger explicitly edits the key).
-
-Authoritative source: this document. The module docstring of
-`sync_yaml_rt.py` mirrors it; on drift, this file wins and the docstring
-is corrected to match.
-
-## Supported
-
-### Document shape
-
-- One YAML document per file. No `---` or `...` document separators.
-- UTF-8. CRLF and LF line endings — both accepted, preserved per-line.
-
-### Mappings (sections)
-
-- Block-style mappings only (`key: value` on its own line).
-- Indent: 2- or 4-space, **no tabs** in indent.
-- Nested mappings unlimited in depth (the template uses 3 levels —
-  e.g. `chat_history.archive.cleanup_after_days`).
-- Duplicate keys at the same level: **last wins** (the later line
-  carries the value; the earlier entry is replaced).
-
-### Scalars (values)
-
-- Bare scalars: `enabled`, `42`, `true`, `~`, `null`, `None`.
-- Single-quoted strings: `'literal text'`.
-- Double-quoted strings: `"literal text"`.
-- Bools, ints, `~` / `null` / `None` are kept **verbatim** — the
-  parser does not normalise `True` → `true` or `null` → `~`.
-
-### Lists (sequences of scalars)
-
-- Block-style lists:
-  ```yaml
-  allowlist:
-    - foo
-    - bar
-  ```
-  Indent inside the list must be consistent.
-- Inline-flow lists, **flat only**: `[a, b, c]`.
-- List items are scalars only. Nested mappings inside a list item are
-  **not** supported (see below).
-
-### Comments and blank lines
-
-- `#`-comments — full-line and inline (`key: value  # comment`). Both
-  preserved verbatim, including leading whitespace and the gap before
-  `#`.
-- Blank lines preserved verbatim — the engine never collapses them.
-
-## Not supported (parser raises `ValueError` with a line number)
-
-The following YAML features are out of contract. A user file that uses
-any of them surfaces as `ValueError` from `scripts/sync_yaml_rt.py:sync`,
-which `scripts/sync_agent_settings.py` catches and reports as **exit
-code 2** with a line-numbered message.
-
-- **Anchors and aliases** — `&name`, `*name`.
-- **Multi-document streams** — `---` / `...` separators.
-- **Nested flow mappings** — `key: {nested: value}` inline. Block-style
-  nested mappings are fine; flow-style nested mappings are not.
-- **Nested mappings inside list items** — `- name: foo` followed by
-  indented children. Lists hold scalars only.
-- **Complex keys** — `? [composite, key]: value`.
-- **Tagged scalars** — `!!str 42`, `!Custom value`.
-- **Multiline scalar styles** — `|` (literal) and `>` (folded) block
-  scalars.
-- **Tabs in indent** — even one tab character in indent.
-- **Mixed indent inside a block** — every child of a parent must share
-  the same indent.
-
-Pinned by `tests/test_sync_round_trip.py` (34 tests) — every
-not-supported feature has at least one fixture that asserts the
-`ValueError` message.
-
-## Test pinning
-
-- Verbatim round-trip: `tests/test_sync_round_trip.py::test_user_block_round_trip_is_idempotent`, `::test_three_level_idempotent`.
-- Out-of-subset rejection: same file, fixtures under
-  `tests/fixtures/sync_yaml_rt/` named `bad_*.yml`.
-- CLI exit code on malformed input:
-  `tests/test_sync_agent_settings.py::test_malformed_user_yaml_exits_2_with_message`.
-
-Any parser change is gated on those tests staying green. New fixtures
-for new features land under `tests/fixtures/sync_yaml_rt/`.
-
-## Why this subset (and why it is fixed)
-
-The driving requirement from
-[`layered-settings`](../guidelines/agent-infra/layered-settings.md) is
-**verbatim user-line preservation**. `ruamel.yaml` and PyYAML both
-re-emit through their own emitters, which normalises whitespace,
-quoting, and blank-line placement. A stdlib parser limited to this
-subset gives byte-identity across two consecutive syncs — the property
-the merger relies on for additive insertion.
-
-Out-of-subset YAML therefore is not a parser bug; it is a contract
-violation by the user file. The friendly `ValueError` and exit code 2
-are the contract's failure surface.
-
-## Revisit triggers
-
-This subset is **fixed** until one of the
-[ADR revisit triggers](adr-settings-sync-engine.md#revisit-triggers)
-fires — namely:
-
-1. `.agent-settings.yml` schema gains a YAML feature outside the subset
-   (anchors, multi-doc, complex keys, nested flow mappings) — the cost
-   of extending the parser exceeds the cost of adopting `ruamel.yaml`.
-2. The verbatim-preservation contract is relaxed — the driver for the
-   custom parser is gone.
-3. The 0-dep posture for Python tooling is dropped at the package level
-   — the marginal cost of one more dep collapses.
-4. A maintenance bug surfaces in the engine that ruamel's mature spec
-   coverage would have prevented.
-
-A new ADR (with successor link) is required to change the subset; this
-document is updated in the same commit.
-
-## See also
-
-- [`docs/contracts/adr-settings-sync-engine.md`](adr-settings-sync-engine.md) — decision record for the stdlib-only engine.
-- [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md) § Sync rules — the additive-merge-with-user-line-preservation contract this subset implements.
-- [`scripts/sync_yaml_rt.py`](../../src/scripts/sync_yaml_rt.py) — implementation; module docstring mirrors this file.
-- [`scripts/sync_agent_settings.py`](../../src/scripts/sync_agent_settings.py) — CLI driver and exit-code contract.

package/docs/contracts/skill-bundled-assets.md

@@ -1,62 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-01
----
-
-# Skill-bundled assets — `skills/<name>/{scripts,data}/` delivery contract
-
-> Sanctions and pins the pattern introduced by ADR-061: a skill may bundle
-> executable Python under `scripts/` and corpus/config files under `data/`
-> (plus `references/` docs), and those assets **reach and run at consumer
-> runtime**. Locked by `tests/test_skill_bundled_assets.py`.
-
-## The delivery chain (verified)
-
-| Stage | Mechanism | Guarantee |
-|---|---|---|
-| 1. Authoring | `src/skills/<name>/{scripts,data,references}/` | Source of truth; `.md` prose is condensed, everything else is data. |
-| 2. Sync | `src/scripts/condense.py::sync_non_md` (`task sync`) | Every non-`.md` skill asset is copied byte-identical into `dist/agent-src/skills/<name>/…`. |
-| 3. Packaging | `package.json` ships `dist/agent-src/` | Assets are inside the published npm artifact. |
-| 4. Install | `install.py::_copy_dir_dereferencing_symlinks` | Whole skill directories (including `scripts/` + `data/`) are deployed to the consumer scope, e.g. `~/.claude/skills/<name>/…`, with symlinks dereferenced so the copy survives npx cache eviction. |
-
-## Invocation contract — skill-relative, never project-relative
-
-```
-A BUNDLED SCRIPT RESOLVES EVERY SIBLING ASSET VIA ITS OWN FILE LOCATION
-(Path(__file__).resolve().parent…), NEVER VIA $PWD OR THE PROJECT ROOT.
-```
-
-- The agent invokes bundled scripts with an **absolute or skills-root-
-  relative path**: `node_modules/.bin/tsx <skills-root>/<name>/scripts/<tool>.ts …`.
-  `<skills-root>` = `~/.claude/skills` (Claude Code consumer install),
-  the tool-specific projection dir for other agents, or `src/skills`
-  inside this repo.
-- The consumer's working directory is **arbitrary** — scripts MUST work
-  from any cwd. Writing output uses caller-supplied paths (flags), never
-  cwd-implicit locations, except where a flag explicitly defaults to cwd.
-- Cross-skill references (one skill invoking another's bundled engine)
-  resolve via the common skills root (e.g. `design-intelligence` passing
-  its `data/manifest.json` to `corpus-grounding/scripts/ground.ts`).
-  Sibling deployment is guaranteed by stage 4 (whole-directory copies of
-  every installed skill into one root).
-- Bundled scripts are **pure stdlib** unless the skill's frontmatter
-  declares an `execution` block gating anything heavier
-  (`runtime-safety`); no network and no subprocess by default.
-
-## What this contract does NOT cover
-
-- Repo-root `scripts/` (e.g. `council_cli.ts`) — **maintainer-only**,
-  never shipped to consumers. Do not confuse the two layers.
-- `.md` files inside skills — they pass through condensation (prose is
-  rewritten); do not put load-bearing machine-read data in skill `.md`.
-- Binary assets — allowed by the chain, but keep corpora text-based
-  (CSV/JSON) so diffs and license review stay possible.
-
-## Regression lock
-
-`tests/test_skill_bundled_assets.py` builds a fixture skill
-(`scripts/probe.py` + `data/fixture.csv`), simulates the install copy into
-a temp skills root, invokes the script from an unrelated cwd, and asserts
-it finds its sibling data — plus runs the real `corpus-grounding` engine
-from a foreign cwd. If that test goes red, the grounding layer is theater
-at consumer runtime (road-to-frontend-design-intelligence Step 1.0).

package/docs/contracts/skill-discovery.md

@@ -1,80 +0,0 @@
----
-stability: experimental
----
-
-# Skill Discovery Contract
-
-> **Status** · v0 / design · 2026-05-30. Phase 3 of `road-to-leaner-core-and-discovery`.
-> **Local-only.** Mirrors [`local-analytics.md`](local-analytics.md): no network egress, no POST,
-> no remote Worker. The recommender reads local files only and honours the analytics opt-out.
-
-## Problem
-
-The package ships 220 skills. Both council members named "218-skill paralysis" as the dominant
-discoverability risk. This contract defines a **recommendation surface** that turns existing signals
-into a short, *explained* shortlist — and explicitly **reuses** signals already on disk. It adds **no**
-new always-loaded layer (that would fail the Phase-1 leaner-core premise).
-
-## Input signals (all local, all already on disk)
-
-| Signal | Source | Used for |
-|---|---|---|
-| Skill catalog | `dist/agent-src/skills/*/SKILL.md` frontmatter (`name`, `description`, `domain`) | candidate universe + `domain` category |
-| Role shortlist | `agents/roles/<role>/skills.yml` (priority-ordered `id` + `why`) | `most-useful-for-role` |
-| Local analytics | `~/.event4u/agent-config/workspace/analytics/events.jsonl` (`event`, `data.role`, `data.task`, optional `data.skill`) | `recently-adopted`, `popular-in-role` |
-
-The role `skills.yml` is the strongest signal and is always present; analytics is optional and
-degrades gracefully (below).
-
-## Four recommendation classes
-
-| Class | Ranking basis | `why` shape |
-|---|---|---|
-| `most-useful-for-role` | role `skills.yml` priority order | the shortlist's own `why:` line |
-| `related-to-current-task` | skills sharing the `domain` of the role's shortlist skills, not already shortlisted | `same domain (<domain>) as your role's core skills` |
-| `recently-adopted` | analytics events in the last 14 days carrying a skill id (`data.skill`), most-recent first | `used <N>d ago in this workspace` |
-| `popular-in-role` | analytics skill-events filtered by `data.role`, by frequency | `launched <N>× by the <role> role locally` |
-
-## Explanation requirement — non-negotiable
-
-```
-EVERY RECOMMENDATION CARRIES A NON-EMPTY `why`. NEVER AN UNEXPLAINED SCORE.
-```
-
-Both council members flagged "opaque / self-referential recommendations without real usage signal" as
-the main risk. A result with no `why` is a contract violation. The `why` names the *signal* (role match,
-domain adjacency, recent-adoption, role-popularity) — never a bare number.
-
-## Graceful degradation — analytics absent or opted out
-
-Analytics is optional. When the JSONL file is missing, empty, or the opt-out is set
-(`AGENT_CONFIG_NO_LOCAL_ANALYTICS` env or `analytics.local: off` config — same checks as
-`local-analytics.md`), the two analytics-backed classes do not fabricate signal:
-
-- `recently-adopted` and `popular-in-role` fall back to **role-shortlist order** with an honest `why`
-  (`from your role shortlist — no local usage signal yet`).
-- `most-useful-for-role` and `related-to-current-task` are unaffected (catalog + role only).
-
-The recommender therefore always returns a useful, explained list — even on a fresh machine with no
-analytics history. Today's analytics schema logs `data.task` (not skill ids); the skill-level classes
-read the forward-compatible `data.skill` field and degrade to the role-shortlist fallback until it is
-populated. No class ever returns an empty `why`.
-
-## Local-only / no-network floor
-
-The recommender opens local files only. It performs no network I/O, writes nothing, and never emits a
-prompt or response body. It is read-only over the catalog, the role file, and (if present) the analytics
-log. This mirrors `local-analytics.md` and does not lift the 3.1.0 Hard-Floor.
-
-## Surfaces
-
-- CLI / agent: `/skills:discover [role]` → Markdown table (`skill · class · why · first command`).
-  Defaults to the active role experience when one is set; otherwise prompts for a role.
-- GUI: a right-rail "Suggested skills" strip on the Workspace tab, reusing the `/api/v1/workspace/*`
-  bridge (no new infra). Deferrable behind the CLI surface if the employee-roadmap right-rail blocker
-  is still open.
-
-## Implementation
-
-`scripts/skill_discovery.py` (≤ 300 LOC). Pure-local, no POST. Honours the analytics opt-out env + config.
-Coverage: `tests/test_skill_discovery.py` against a fixture catalog + fixture analytics JSONL.