@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/mcp-phase-1-scope.md

@@ -1,272 +0,0 @@
----
-stability: experimental
-mcp_scope: full
----
-
-# MCP Server — Phase 1–6 Scope (A0 Hard Contract)
-
-> **Status:** Active · covers Phase 1 (A1–A7) + Phase 2 (B1–B5) +
-> Phase 3 (C1–C4) + Phase 4 (D1–D4) + Phase 6 F1/F3 of
-> `road-to-mcp-server.md`. Phase 6 F2 (SSE transport) is owned by
-> [`mcp-cloud-scope.md`](mcp-cloud-scope.md) — the hosted Cloudflare
-> Worker bridge — and remains out of scope here. This contract retains
-> exclusive ownership of `scripts/mcp_server/` (local stdio).
-> **Stability:** experimental — not linked from README, AGENTS.md, or
-> `docs/architecture.md`. Internal index reference only per `STABILITY.md`.
-
-## Purpose
-
-Locks the **execution-safety boundary** for the MCP server through
-Phase 2. Any code under `scripts/mcp_server/` must satisfy this
-contract verbatim. Deviation → not Phase 1/2; promote to a follow-up
-phase with its own design-call gate.
-
-## In-scope (Phase 1 + Phase 2)
-
-- Transport: **stdio**. No SSE, no HTTP, no WebSocket.
-- MCP primitives: **`prompts/list`** + **`prompts/get`** — read-only.
-- Source data: **`dist/agent-src/skills/<name>/SKILL.md`** and
-  **`dist/agent-src/commands/**/*.md`** (condensed projections, never the
-  uncondensed source-of-truth tree).
-- Loaded set (Phase 2): every well-formed skill + command under
-  `dist/agent-src/` (Phase 1 hand-picked set retained as a smoke fixture
-  in `prompts.py::PHASE_1_SKILLS`).
-- **Pagination** (B4): cursor-based `nextCursor` on `prompts/list`,
-  default `page_size=100`. Cursor is an opaque stringified offset.
-- **Hot-reload** (B5): `PromptCache` re-scans on mtime / path-set
-  change before each `prompts/list` response. No background thread,
-  no inotify, no debounce — the request itself is the rate-limiter.
-- **Frontmatter validation** (B3): entries missing `name` or
-  `description` are skipped with a stderr warning at boot; malformed
-  files do not crash the server.
-- Process lifetime: one server per project, launched per-client by the
-  consumer (Claude Desktop, Zed, Continue) at MCP-config time.
-
-## Out-of-scope (Phase 1 + Phase 2)
-
-- **`tools/*` beyond the Phase 4 allowlist** — only the two
-  built-in tools listed below in *Phase 4 amendment* are reachable.
-  Any other name raises `ValueError`. `work_engine` is not exposed.
-- **`resources/*` beyond rules / guidelines / contexts** — no model
-  outputs, no roadmaps, no chat history surfaced as resources.
-- **Filesystem writes outside the Phase 4 write allowlist** — the only
-  writable targets are `agents/runtime/.agent-chat-history` (current
-  default), `agents/.agent-chat-history`, and `.agent-chat-history`
-  under `<consumer_root>`. No log files, no telemetry writes, no
-  `.work-state.json` mutation.
-- **Direct shell execution from `mcp_server/*`** — modules under
-  `scripts/mcp_server/` do not `import subprocess`, `os.system`, or
-  `os.popen` directly. Project helpers that internally spawn shells
-  (`skill_linter`'s `--changed` git mode, etc.) may be called only via
-  read-only wrappers that bypass those code paths.
-- **Network egress** — the server does not call external APIs;
-  the AI Council, anthropic SDK, and openai SDK are not imported by
-  any module under `scripts/mcp_server/`.
-- **Authentication / multi-tenancy** — single-process, single-project.
-  Multi-tenant SSE is Phase 6 (F2).
-
-## Static guarantees enforced by tests
-
-`tests/test_mcp_server.py` asserts the boundary at unit level:
-
-1. `prompts/list` returns the full skills + commands set with
-   `skill.<name>` and `command.<name>` wire-name prefixes.
-2. `prompts/get` returns a non-empty `messages[].content.text` body
-   matching the SKILL.md / command-file body (frontmatter stripped).
-3. `prompts/get` for an unknown name raises `ValueError` (no silent
-   fallback to filesystem scan).
-4. `scripts.mcp_server.prompts` imports cleanly without `subprocess`,
-   `os.system`, `os.popen`, or any `requests` / `httpx` call.
-5. `prompts/list` paginates with `nextCursor` and pages do not
-   overlap.
-6. `PromptCache` re-scans on mtime change (hot-reload).
-7. Malformed frontmatter is skipped with an error line, not crashed.
-
-A future regression that adds a `tools/*` handler outside the
-allowlist or writes outside the Phase 4 write allowlist fails the
-import-surface + behaviour assertions and the contract review in code
-review.
-
-## Phase 4 amendment — tool allowlist (D1–D4)
-
-Phase 4 lifts the read-only line for **exactly** the two built-in
-tools registered in `scripts/mcp_server/tools.py::ALLOWLIST`. Every
-other tool name is unreachable: `tools/call` against an unlisted name
-returns `isError=True`.
-
-| Tool name | Mode | Side effects |
-|---|---|---|
-| `lint_skills` | read-only | Wraps `scripts.skill_linter.lint_file`. Never spawns `git` (no `--changed`). Returns the same JSON shape as `scripts/skill_linter.py --format json`. |
-| `chat_history_append` | path-scoped write | Wraps `scripts.chat_history.append`. Writes are allowed only when the resolved target is `agents/runtime/.agent-chat-history` (current default), `agents/.agent-chat-history`, or `.agent-chat-history` under `<consumer_root>`. `dry_run=True` validates the payload without touching the filesystem. |
-
-**Path-scoping invariant** — any tool that writes must resolve its
-target through `_validate_in_tree_path` before the underlying writer
-runs. Escapes (absolute paths outside the root, relative paths that
-resolve outside, or filenames not in the write allowlist) raise
-`ValueError` and surface as `isError=True` in `tools/call`.
-
-**Boot-time enumeration** — `run_stdio` prints one stderr line
-listing the registered tool names so operators see the surface at
-launch. Adding a tool to `ALLOWLIST` is a code-review event; no
-settings flag can enable an unlisted tool.
-
-Additional tool tests in `tests/test_mcp_server.py`:
-
-8. `tools/list` returns exactly the allowlisted names.
-9. `tools/call` against a valid `dry_run` payload returns
-   `isError=False` with a JSON-serialized result.
-10. `tools/call` with a path escape returns `isError=True` referencing
-    the escape — no exception propagates past the handler.
-11. `tools/call` against an unknown tool name returns `isError=True`.
-12. `scripts.mcp_server.tools` does not import `subprocess`,
-    `os.system`, `os.popen`, or any HTTP client directly.
-
-## Phase 6 amendment — identity metadata + Docker bundle (F1, F3)
-
-Phase 6 adds **observability** and **packaging** without changing the
-A0 wire surface. F2 (SSE transport) is explicitly deferred — see
-status header.
-
-### F1 — Identity metadata
-
-Three values surface at server boot, written to **stderr** in a single
-`mcp-server: identity …` line (the canonical surface — the high-level
-MCP SDK builds `serverInfo` with a fixed field set, so wire-surface
-lift waits on SDK support):
-
-- **`serverVersion`** — hand-maintained SemVer in
-  `scripts/mcp_server/__init__.py::__version__`. Bumps on
-  **wire-surface** changes only: new tool, new resource MIME type,
-  protocol-level break. Does **not** bump for content edits inside
-  `dist/agent-src/`.
-- **`packageVersion`** — read from `package.json::version` at boot.
-  Bumps on every agent-config bundle release; build-ID semantics, not
-  a stability signal.
-- **`skillSetSignature`** — first 12 hex chars of the SHA-256 over the
-  joined sorted `(path, mtime)` tuples of `PromptCache` and
-  `ResourceCache`. **Not a version** — a content fingerprint. Auto-
-  updates with every `task sync`; intended for cache-key /
-  reproducibility use, never for SemVer-style compatibility claims.
-
-Implementation: `scripts/mcp_server/metadata.py`. The signature is
-deterministic for a given snapshot of the loaded file set; any mtime
-change invalidates it.
-
-### F3 — Stdio Docker bundle
-
-`internal/docker/mcp-server/Dockerfile` ships a stdio-only image. The contract:
-
-- **No HTTP / SSE listener** in the image. Stdio is the only wire.
-- The image embeds `scripts/mcp_server/`, the two tool dependencies
-  (`scripts/skill_linter.py`, `scripts/chat_history.py`),
-  `dist/agent-src/`, `docs/guidelines/`, and `package.json`. Nothing
-  outside the COPY-listed paths reaches the runtime stage.
-- The image runs as a non-root user (`mcp:mcp`); host volumes mounted
-  for `chat_history_append` writes must be writable by that uid/gid.
-- The A0 contract from Phase 1–4 transfers verbatim — the import-
-  surface guard tests run identically inside and outside the image.
-
-Operator documentation: `docs/setup/mcp-server-docker.md`. The image
-does not introduce a new tool, resource type, or protocol surface.
-
-### What Phase 6 explicitly does **not** add
-
-- **No HTTP/SSE transport**, native or otherwise. F2 is deferred to
-  the successor roadmap; revival is gated on a real consumer ask, and
-  the locked design is the bridge pattern from
-  [`mcp-request-signing § Appendix`](../guidelines/agent-infra/mcp-request-signing.md#appendix--http-bridge-stdio-kernel-pattern-reference)
-  — never a native SSE server inside `scripts/mcp_server/`.
-- **No new tools** beyond the Phase 4 allowlist.
-- **No multi-tenancy** — the Docker image is single-tenant, one
-  process per stdio session. Multi-tenancy lives with the future
-  bridge, not the kernel.
-
-## Amendment — MCP Full Power (accepted 2026-07-07)
-
-> **Status: Accepted.** Recorded by `road-to-mcp-full-power.md` Phase 3.
-> User signoff on the `a0-amendment-signoff` blocker plus the council
-> verdict in `agents/decisions/mcp-write-exec-cut-2026-07-07.md` both
-> landed 2026-07-07. Existing Phase 1–6 sections above predate the TS
-> migration (they still reference `scripts/mcp_server/*.py` and a
-> two-tool allowlist) and are known-stale beyond what this amendment
-> covers; a full contract refresh is a separate follow-up, out of scope
-> here.
-
-**Named consumer ask.** Operator, 2026-07-07: expose the CLI/script long
-tail (roadmap, telemetry, capabilities, doctor, council, memory, …) through
-MCP in safety tiers, not just the current 9-tool read-only/single-write set.
-
-**Safety-tier model** (full classification:
-[`agents/settings/contexts/mcp-tool-tier-map.md`](../../agents/settings/contexts/mcp-tool-tier-map.md)):
-
-| Tier | Contract treatment |
-|---|---|
-| `read-only` | May be implemented without further gate — same bar as the existing 9 tools. |
-| `fs-write-in-tree` | May be implemented once path-guarded via `_validateInTreePath` — same pattern as `chat_history_append`. |
-| `shell-exec` | Requires the safety envelope: fixed argv (no shell interpolation of caller-supplied strings), timeout, output truncation, no network access from the spawned process. Implementation requires the Phase 3 council verdict naming it in the cut list. |
-| `network` | Never silent-default. Every call surfaces cost/consequence before executing; billable calls (e.g. `council:run`) require the caller to pass an explicit confirmation flag echoed back in the tool result, not just be callable. |
-| `long-running` | Structurally excluded — not tool-call-shaped (blocks or starts a server). |
-| `hard-floor-never` | **Permanently excluded.** Secrets (`keys:install-*`), the global/outside-repo install (`upgrade`, `global`, `refresh`, `settings:migrate`), and bulk-destructive commands (`uninstall`, `prune`) are never reachable via any MCP tool, bridge, or allowlist entry, under any settings value. This list only grows, never shrinks, without a fresh A0 amendment of its own. |
-
-**Deny-by-default, build-time only.** No consumer-settings allowlist ships
-(a `mcp.tools.allow` runtime setting was considered and **rejected** by
-the Phase 3 council — see below). A tool is reachable if and only if it
-was generated into the build from an approved tier-map entry. Enabling a
-new tool is a code change (add the entry, rebuild), never a settings
-edit. `hard-floor-never` tier entries are never generated — the
-exclusion is structural (the tool does not exist in `tools/list`), not a
-runtime rejection.
-
-**Bridge shape (Phase 5) — decided: pure build-time codegen.** Every
-approved tool, in every tier including `shell-exec`, is generated at
-build time from `src/cli/registry.ts` metadata plus the tier map — one
-MCP tool per approved command, each with its own JSON Schema. A generic
-`agent_config_cli` tool with a runtime-validated `subcommand` argument
-was considered and rejected: the package's existing `chat_history_append`
-pattern is already a compiled tool with a hardcoded path guard, not a
-generic bridge gated by an editable setting, and the council verdict
-(`agents/decisions/mcp-write-exec-cut-2026-07-07.md`) found the
-runtime-allowlist approach strictly weaker on security grounds for no
-countervailing benefit. Shell-exec tools additionally compile in their
-safety envelope (fixed argv, timeout, output cap, no network) as
-constants, not configuration.
-
-**Shell-exec safety review (Phase 5, shipped pilot: `run_tests`).**
-Lethal-trifecta pass for the one approved exec-tier tool:
-
-- *Untrusted-content ingestion:* the tool's inputs (`filter`, `path`) come
-  from the MCP caller — the same principal that already holds the chat
-  surface; no fetched/external content selects what runs. Caller strings
-  become literal argv elements via
-  `src/scripts/mcp_exec/safety_envelope.ts` (`execFile`, no shell) — a
-  hostile string cannot become a second command.
-- *Private-data access:* the spawned vitest run sees the consumer tree,
-  same as every fs tool; no credential paths are added to its env.
-- *Egress:* the envelope adds no network I/O of its own. Arbitrary test
-  code MAY use the network — that is a property of the project's tests,
-  not of the tool; the envelope's guarantees are spawn-surface guarantees
-  (no shell, `SIGKILL` timeout, per-stream byte caps), stated as such and
-  never marketed as network isolation.
-- *Compiled constants:* 120s timeout, 64KB per-stream cap — code-review
-  events, not settings.
-
-**Long-running policy (Phase 5) — decided: synchronous truncation.** No
-async job/poll pattern ships: an exec call that exceeds its compiled
-timeout returns `timed_out: true` with the captured, capped output.
-Revisit only if a council-approved tool genuinely cannot fit a
-synchronous budget (e.g. a future `council:run`).
-
-## Revision policy
-
-This contract is **experimental** — breaking changes are allowed in any
-release with a CHANGELOG note. Promotion to `beta` follows the same
-gate as Phase 1 itself: at least one shipped client renders Phase 1
-prompts end-to-end without a contract amendment.
-
-## See also
-
-- [`mcp-cloud-scope.md`](mcp-cloud-scope.md) — hosted Worker contract
-  (sibling, not child). Extends the bridge pattern from
-  [`mcp-request-signing § Appendix`](../guidelines/agent-infra/mcp-request-signing.md#appendix--http-bridge-stdio-kernel-pattern-reference)
-  for multi-tenant SSE.
-- [`STABILITY.md`](STABILITY.md) — stability policy for `docs/contracts/`.

package/docs/contracts/mcp-registry-manifest.schema.json

@@ -1,129 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://event4u.app/schemas/mcp-registry-manifest.json",
-    "title": "MCP Registry Manifest",
-    "description": "Source of truth for every external MCP-registry submission. R5 Phase 2.1. Lifecycle status per entry — handles 'they said no' without rewriting history.",
-    "type": "object",
-    "additionalProperties": false,
-    "required": [
-        "version",
-        "generated_at",
-        "package",
-        "server",
-        "registries"
-    ],
-    "properties": {
-        "version": {
-            "const": 1
-        },
-        "generated_at": {
-            "type": "string",
-            "description": "UTC date (YYYY-MM-DD). Day-precision keeps the manifest stable across same-day reruns."
-        },
-        "package": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["name", "version", "description", "homepage", "repository"],
-            "properties": {
-                "name": { "type": "string", "minLength": 1 },
-                "version": { "type": "string", "minLength": 1 },
-                "description": { "type": "string", "minLength": 1 },
-                "homepage": { "type": "string", "format": "uri" },
-                "repository": { "type": "string", "format": "uri" }
-            }
-        },
-        "server": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": [
-                "name",
-                "transports",
-                "tools_count",
-                "install_hint_stdio"
-            ],
-            "properties": {
-                "name": { "type": "string", "minLength": 1 },
-                "transports": {
-                    "type": "array",
-                    "minItems": 1,
-                    "uniqueItems": true,
-                    "items": { "enum": ["stdio", "worker"] }
-                },
-                "tools_count": {
-                    "type": "integer",
-                    "minimum": 0,
-                    "description": "Sourced from internal/workers/mcp/content.json#/tool_catalog/tools. Hard-sourced — no fallback. R3 (discovery roadmap) is a hard prerequisite per the AI-Council external review."
-                },
-                "install_hint_stdio": { "type": "string", "minLength": 1 }
-            }
-        },
-        "topics": {
-            "type": "array",
-            "uniqueItems": true,
-            "items": { "type": "string", "minLength": 1 },
-            "description": "Mirror of `.github/topics.yml#/topics`. Lets registries that accept topic tags pick from one source."
-        },
-        "discovery": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["artefact_count", "scanner_version"],
-            "properties": {
-                "artefact_count": { "type": "integer", "minimum": 0 },
-                "scanner_version": { "type": "string", "minLength": 1 }
-            }
-        },
-        "registries": {
-            "type": "array",
-            "minItems": 2,
-            "maxItems": 2,
-            "items": { "$ref": "#/$defs/registry" }
-        }
-    },
-    "$defs": {
-        "registry": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": [
-                "id",
-                "label",
-                "listing_format",
-                "submission_url",
-                "status",
-                "submitted_at",
-                "pr_url",
-                "last_verified",
-                "rendered_payload"
-            ],
-            "properties": {
-                "id": {
-                    "enum": ["awesome-mcp-servers", "mcp-cloudflare-catalogue"],
-                    "description": "Closed vocabulary. Adding a third registry requires a schema-version bump."
-                },
-                "label": { "type": "string", "minLength": 1 },
-                "listing_format": { "enum": ["markdown-row", "json-entry"] },
-                "submission_url": { "type": "string", "format": "uri" },
-                "status": {
-                    "enum": ["pending", "listed", "rejected", "unlisted"],
-                    "description": "Lifecycle. `pending` = not yet submitted. `listed` = upstream PR merged. `rejected` = upstream said no (don't auto-resubmit). `unlisted` = was listed, then removed."
-                },
-                "submitted_at": {
-                    "type": ["string", "null"],
-                    "description": "ISO date (YYYY-MM-DD) when the submission PR was opened. Null while status=pending."
-                },
-                "pr_url": {
-                    "type": ["string", "null"],
-                    "description": "URL of the submission PR. Null while status=pending."
-                },
-                "last_verified": {
-                    "type": ["string", "null"],
-                    "description": "ISO date (YYYY-MM-DD) the maintainer last opened the live listing and confirmed it still points at this package. Null while status=pending. SHOULD be refreshed every release."
-                },
-                "rendered_payload": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "Repo-relative path to the rendered payload (e.g. `dist/mcp/awesome-mcp-servers.row.md`)."
-                }
-            }
-        }
-    }
-}

package/docs/contracts/mcp-tool-inventory.md

@@ -1,64 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-14
----
-
-# MCP tool inventory
-
-> Generated by [`src/scripts/audit_mcp_tools.ts`](../../src/scripts/audit_mcp_tools.ts)
-> from the source-of-truth catalog
-> [`src/scripts/mcp_server/consumer_tool_catalog.json`](../../src/scripts/mcp_server/consumer_tool_catalog.json).
-> Do **not** hand-edit; rerun `./scripts-run src/scripts/audit_mcp_tools --write`.
->
-> Step-11 Phase 5 Step 3 (an internal parity roadmap (local-only)).
-
-## Summary
-
-- **Total tools:** 31
-- **By transport:** stdio=19
-- **By side-effect:** fs-write=8, ro=20, shell=3
-- **Discovery-only stubs (no implementation):** 12
-
-## Tools
-
-| Tool | Side-effect | Transports | Catalog | Handler |
-|---|---|---|---|---|
-| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.ts:1198`](../../src/scripts/mcp_server/tools.ts#L1198) |
-| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.ts:1226`](../../src/scripts/mcp_server/tools.ts#L1226) |
-| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.ts:1287`](../../src/scripts/mcp_server/tools.ts#L1287) |
-| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:63`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L63) | [`tools.ts:1363`](../../src/scripts/mcp_server/tools.ts#L1363) |
-| `memory_get` | `ro` | stdio | [`consumer_tool_catalog.json:81`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L81) | [`tools.ts:1430`](../../src/scripts/mcp_server/tools.ts#L1430) |
-| `memory_signal` | `fs-write` | stdio | [`consumer_tool_catalog.json:95`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L95) | [`tools.ts:1539`](../../src/scripts/mcp_server/tools.ts#L1539) |
-| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:111`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L111) | [`tools.ts:1454`](../../src/scripts/mcp_server/tools.ts#L1454) |
-| `skill_trigger_eval` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:118`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L118) | _stub-only_ |
-| `suggest_command` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:134`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L134) | _stub-only_ |
-| `suggest_skill_for_task` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:149`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L149) | _stub-only_ |
-| `mine_session` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:164`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L164) | _stub-only_ |
-| `update_form_request_messages` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:178`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L178) | _stub-only_ |
-| `sync_gitignore` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:193`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L193) | _stub-only_ |
-| `sync_agent_settings` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:206`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L206) | _stub-only_ |
-| `run_tests` | `shell` | stdio | [`consumer_tool_catalog.json:220`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L220) | [`tools.ts:1714`](../../src/scripts/mcp_server/tools.ts#L1714) |
-| `run_quality_checks` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:234`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L234) | _stub-only_ |
-| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:247`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L247) | [`tools.ts:1468`](../../src/scripts/mcp_server/tools.ts#L1468) |
-| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:254`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L254) | [`tools.ts:1483`](../../src/scripts/mcp_server/tools.ts#L1483) |
-| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.ts:1498`](../../src/scripts/mcp_server/tools.ts#L1498) |
-| `compile_router` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:268`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L268) | _stub-only_ |
-| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:281`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L281) | [`tools.ts:1514`](../../src/scripts/mcp_server/tools.ts#L1514) |
-| `roadmap_progress` | `fs-write` | stdio | [`consumer_tool_catalog.json:295`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L295) | [`tools.ts:1573`](../../src/scripts/mcp_server/tools.ts#L1573) |
-| `roadmap_archive` | `fs-write` | stdio | [`consumer_tool_catalog.json:308`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L308) | [`tools.ts:1596`](../../src/scripts/mcp_server/tools.ts#L1596) |
-| `capabilities_index` | `fs-write` | stdio | [`consumer_tool_catalog.json:315`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L315) | [`tools.ts:1612`](../../src/scripts/mcp_server/tools.ts#L1612) |
-| `doctor_report` | `ro` | stdio | [`consumer_tool_catalog.json:328`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L328) | [`tools.ts:1635`](../../src/scripts/mcp_server/tools.ts#L1635) |
-| `conformance_check` | `ro` | stdio | [`consumer_tool_catalog.json:335`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L335) | [`tools.ts:1649`](../../src/scripts/mcp_server/tools.ts#L1649) |
-| `telemetry_report` | `ro` | stdio | [`consumer_tool_catalog.json:342`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L342) | [`tools.ts:1663`](../../src/scripts/mcp_server/tools.ts#L1663) |
-| `catalog_search` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:355`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L355) | _stub-only_ |
-| `catalog_inspect` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:372`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L372) | _stub-only_ |
-| `catalog_load` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:387`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L387) | _stub-only_ |
-| `council_estimate` | `ro` | stdio | [`consumer_tool_catalog.json:401`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L401) | [`tools.ts:1685`](../../src/scripts/mcp_server/tools.ts#L1685) |
-
-## Glossary
-
-- **Side-effect** — `ro` (read-only) · `fs-write` (filesystem write) · `shell` (spawns processes).
-- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`internal/workers/mcp/`). A tool may live on both.
-- **Stub** — catalog-listed for discovery; returns the `not_implemented` envelope from
-  [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) until promoted.
-

package/docs/contracts/mcp-tool-stub-envelope.md

@@ -1,78 +0,0 @@
----
-stability: experimental
----
-
-# MCP Tool Stub Envelope — Phase 1 Discovery Contract
-
-> **Status:** Active · governs the Discovery-First MCP coverage strategy
-> ([`mcp-coverage-strategy.md`](../../agents/settings/contexts/mcp-coverage-strategy.md)).
-> **Stability:** experimental — internal index reference only per
-> `STABILITY.md`.
-
-## Purpose
-
-Locks the wire shape of the `not_implemented` envelope returned by
-`tools/call` when a consumer agent invokes a catalog entry that has no
-implementation on the active transport. Every denied call returns a
-structured payload with a recovery hint, never a silent 404 and never
-a 500.
-
-## Source of truth
-
-`scripts/mcp_server/consumer_tool_catalog.json` (schema_version 1).
-Both the stdio server and the Cloud Worker bundle (`internal/workers/mcp/`,
-packed by `scripts/pack_mcp_content.py`) read from this file. The
-manifest returned by `tools/list` is byte-identical apart from
-per-tool `implemented_on` metadata.
-
-## Catalog entry
-
-```json
-{
-  "name": "<snake_case>",
-  "description": "<≤500 chars; agent-facing>",
-  "side_effect": "ro | fs-write | shell",
-  "implemented_on": ["stdio"],
-  "input_schema": { "type": "object", "...": "JSON Schema draft-7" }
-}
-```
-
-`implemented_on` lists transports where a real handler is wired;
-missing transports return the envelope.
-
-## Envelope wire shape
-
-```json
-{
-  "code": "not_implemented",
-  "tool": "<catalog name>",
-  "transport": "stdio | worker",
-  "install_hint": "<copyable shell command>",
-  "alternative": "stdio",
-  "message": "<one-sentence explainer>"
-}
-```
-
-Stdio returns this as the JSON-RPC `result` (SDK wraps in
-`TextContent`); the Worker returns it as `error.data` alongside
-`code: -32601`. Field invariants: `code` is the frozen literal
-`not_implemented`; `tool` echoes the caller; `transport` is set per
-surface; `install_hint` comes from the catalog's `install_hint_stdio`
-field; `alternative` is the frozen literal `stdio` until Phase 3.
-Consumer agents must drive logic from `code`, not `message`.
-
-## Unknown-tool / latent-demand path
-
-A call to a name not in the catalog returns JSON-RPC error `-32601`
-with the same envelope shape, `code: "unknown_tool"`. Both transports
-log the attempt with `outcome: "latent_demand"` so Phase 2 can
-promote unforeseen names.
-
-## Acceptance
-
-- Both transports return `code == "not_implemented"` for every
-  catalog entry whose `implemented_on` excludes the transport.
-- Both transports return `code == "unknown_tool"` for any name not in
-  the catalog.
-- Schema version bumps on any incompatible field rename; new optional
-  fields are compatible.

package/docs/contracts/measurement-baseline.md

@@ -1,103 +0,0 @@
----
-stability: stable
----
-
-# Measurement baseline — contract
-
-> **Status:** locked 2026-05-16 · **Owner:** `step-4-measurement-and-benchmark.md`
-> · **Cited by:** every P2 enforcement roadmap (skill rationalization G0, north-star G1, condensation default decision).
-
-Single source of truth for what `task bench` measures, what counts as
-drift, and what unblocks enforcement. Read this before pinning a number
-to a roadmap or PR description.
-
-## What `task bench` measures
-
-Four axes, all numeric, all reproducible from the same input:
-
-| Axis | Source | Definition | Units |
-|---|---|---|---:|
-| **selection accuracy** | [`scripts/bench_runner.py`](../../src/scripts/bench_runner.py) | Keyword-overlap ranker hits the expected skill in top-K | % |
-| **cost** | [`scripts/cost/track.mjs`](../../src/scripts/cost/track.mjs) session jsonl | Token+USD per model, captured live | USD |
-| **quality** | regex / rubric assertions per prompt | `quality_assertion` matches in agent output | % |
-| **projection fidelity** | [`scripts/bench_per_tool.py`](../../src/scripts/bench_per_tool.py) | `accuracy(tool) / accuracy(augment)` for skill-projecting tools | ratio |
-
-Schemas: [`benchmark-report-schema.md`](benchmark-report-schema.md) ·
-[`benchmark-corpus-spec.md`](benchmark-corpus-spec.md). Reports land at
-`internal/bench/reports/<utc-stamp>-<corpus>[-projection].{json,md}` —
-timestamped, never overwritten, content-addressed by run.
-
-## Corpora — frozen for the soak window
-
-| Corpus | Path | Prompts | Purpose |
-|---|---|---:|---|
-| `dev` | [`tests/eval/corpus-dev.yaml`](../../tests/eval/corpus-dev.yaml) | 10 | Developer task surface (Laravel/Symfony/React/CI/PR) |
-| `non-dev` | [`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml) | 16 | Founder / agency / content creator surface (Wing-4) |
-
-Total 26 prompts ≥ Acceptance Criteria floor of 25. Mid-window edits
-to either YAML restart the 60-day clock per
-[`condensation-default-kill-criterion.md`](condensation-default-kill-criterion.md) § 2.
-
-## What counts as drift
-
-[`scripts/bench_drift_check.py`](../../src/scripts/bench_drift_check.py)
-compares the latest report against a sliding window of the prior N runs
-(default 5) for the same corpus.
-
-| Axis | Threshold | Note |
-|---|---|---|
-| selection accuracy | latest − baseline_mean ≤ −5 pp | always evaluated |
-| cost | latest / baseline_mean ≥ +20 % | only when both sides have `source: captured` |
-| quality | latest − baseline_mean ≤ −10 pp | skipped when latest is `not_collected` |
-| projection fidelity | tool fidelity < 0.85 | exit 1 from `task bench:projection` |
-
-Drift exits with code 2 from `task bench:drift`. **CI posture during
-soak:** all bench-drift steps `continue-on-error: true` and post a
-sticky PR comment — informational only, not a merge gate. Flip to
-required check happens via a separate PR once
-`task bench:baseline-ready` returns 0 (see below).
-
-## What unblocks enforcement (the G1 gate)
-
-```
-TASK bench:baseline-ready EXIT 0 IS THE ONLY AUTHORITY.
-NO ANECDOTE, NO INDIVIDUAL REPORT, NO ROADMAP-SIDE OVERRIDE.
-```
-
-[`scripts/bench_baseline_ready.py`](../../src/scripts/bench_baseline_ready.py)
-returns exit 0 iff both:
-
-1. **Wall-clock soak:** `today − internal/bench/baseline-start.txt ≥ --min-days` (default 60)
-2. **Report density:** `internal/bench/reports/*-<corpus>.json` count ≥ `--min-reports` (default 30)
-
-Soak start anchored at [`internal/bench/baseline-start.txt`](../../bench/baseline-start.txt)
-= **2026-05-16**. Earliest possible flip: **2026-07-15**, contingent
-on the 30-report floor.
-
-Downstream consumers:
-
-- ``step-99-north-star-restructure.md` § Acceptance G1` — reads this exit code.
-- [`condensation-default-kill-criterion.md` § 3](condensation-default-kill-criterion.md) — reads the decision table after baseline closes.
-- ``step-2-skill-inventory-rationalization.md` § G0` — usage-data soak floor.
-
-## What the closeout writes
-
-On baseline closure, the step-4 closeout writes the numeric verdict to
-[`docs/parity/bench.json`](../parity/bench.json) — frozen snapshot with
-the 30+ reports averaged, drift verdict, and the condensation-default
-decision per the kill-criterion table. That file is the artefact every
-P2 roadmap reads — not the live `internal/bench/reports/` directory.
-
-## Carve-outs
-
-- **Pricing freshness:** [`internal/bench/pricing.yaml`](../../bench/pricing.yaml) rows must carry `sourced_on: YYYY-MM-DD`. Stale prices = stale numbers = no trust (external "measured-vs-claimed" pattern).
-- **Subjective grading excluded:** quality scoring is mechanical via `quality_assertion`. No vibes.
-- **Cursor / Cline / Windsurf:** rules-only surfaces, no SKILL.md projection. `bench:projection` reports them as `not_applicable` — the gap is acknowledged, not silently dropped.
-
-## Cross-references
-
-- [`ADR-118`](../decisions/ADR-118-loop-engineering-boundaries.md) · bench-drift stays advisory by decision — never a blocking gate (disposition #4)
-- [`benchmark-report-schema.md`](benchmark-report-schema.md) · per-report JSON schema
-- [`benchmark-corpus-spec.md`](benchmark-corpus-spec.md) · corpus YAML schema
-- [`condensation-default-kill-criterion.md`](condensation-default-kill-criterion.md) · decision table read by step-4 closeout
-- `step-4-measurement-and-benchmark.md` · the owning roadmap