@event4u/agent-config 9.7.0 → 9.9.0

package/src/config/discovery/packs.yml

@@ -133,6 +133,28 @@
   domain: engineering
   size_class: medium
 
+- id: scale-discipline
+  label: Scale Discipline
+  description: Scale-safe persistence — index parity, bounded reads, migration safety, growth budgets, thin request path, durable async; deterministic pattern lints gate, heuristics advise.
+  workspaces: [engineering]
+  requires: [engineering-base]
+  trust_level_default: experimental
+  surface_tier: lab
+  domain: engineering
+  size_class: small
+  default_install: false
+
+- id: history-discipline
+  label: History Discipline
+  description: Audit/change history done right — audit coverage on declared scopes, cheapest-sufficient tier selection (default row-level audit log; event sourcing only by waiver), audit-table hygiene, privacy + reliability interlocks.
+  workspaces: [engineering]
+  requires: [scale-discipline]
+  trust_level_default: experimental
+  surface_tier: lab
+  domain: engineering
+  size_class: small
+  default_install: false
+
 - id: python
   label: Python
   description: Python-language patterns.

package/src/config/discovery/workspaces.yml

@@ -13,7 +13,7 @@
   description: Code, tests, CI, reviews, architecture.
   example_roles: [Developer, CTO, Tech Lead]
   default_packs: [engineering-base, git]
-  optional_packs: [php, laravel, symfony, javascript, typescript, react, nextjs, python, frontend-design, brand, analysis-workbench]
+  optional_packs: [php, laravel, symfony, javascript, typescript, react, nextjs, python, frontend-design, brand, analysis-workbench, scale-discipline, history-discipline]
 
 - id: product
   label: Product

package/src/config/evaluator-budgets.json

@@ -0,0 +1,47 @@
+{
+    "_comment": "Outside-in evaluator budgets (road-to-credible-install Phase 6). VALUES ARE FROZEN FROM MEASURED ACCEPTANCE NUMBERS of Phases 0-3 (2026-07-27, packed tarball @ 9.8.0 tree, --omit=dev consumer install), never invented. The umbrella harness (src/scripts/evaluator_umbrella.sh) measures the packed artifact and check_evaluator_budgets.ts enforces: absolute budget AND >regression_pct growth vs last_measured fails even under budget. Owner + review date are lint-enforced (lint_budget_ownership). Timing metrics carry a per-entry regression_pct override (200) — wall-clock noise would flap a 10% creep rule; their absolute max is the binding gate. Sizes/counts keep the tight 10% creep.",
+    "schema_version": 1,
+    "owner": "maintainer",
+    "review_by": "2027-07-27",
+    "regression_pct": 10,
+    "budgets": {
+        "unpacked_size_mb": {
+            "max": 28,
+            "last_measured": 26.05,
+            "method": "npm pack --json → dist.unpackedSize / 1e6 — includes the Phase-1 precompiled bundles (dist/hooks/dispatch.js + dist/mcp/server.mjs, ~2.1 MB) that bought the 23x hook-latency win and the tsx removal"
+        },
+        "node_modules_mb": {
+            "max": 140,
+            "last_measured": 127,
+            "method": "du -sm node_modules after `npm install --omit=dev <tarball>` in a clean project"
+        },
+        "runtime_dep_count": {
+            "max": 200,
+            "last_measured": 187,
+            "method": "package-lock.json packages count (minus root) of the clean --omit=dev install"
+        },
+        "cli_version_cold_ms": {
+            "max": 1500,
+            "last_measured": 370,
+            "method": "wall-clock of the FIRST `agent-config --version` after install (cold fs cache run counts)",
+            "regression_pct": 200
+        },
+        "mcp_boot_to_initialize_ms": {
+            "max": 2000,
+            "last_measured": 264,
+            "method": "initialize request piped to `node dist/mcp/server.mjs`, wall-clock to response",
+            "regression_pct": 200
+        },
+        "cli_help_command_count": {
+            "max": 80,
+            "last_measured": 80,
+            "method": "registry enumeration — count of `{ name: '...', disposition` entries in src/cli/registry.ts (NOT --help prose parsing; methods historically disagreed 74 vs 76 vs 79)",
+            "baseline_note": "79 → 80 on 2026-07-29 (9.9.0). This RECORDS growth that already shipped through its own reviewed PRs; it does not authorize new surface. Net +6 registry entries since the 9.8.0 tag (7 added — code-graph, knowledge, analytics, memory:get, memory:learn, rtk:detect, dispatch:hook; 1 removed — the old dispatch:hook entry), and the frozen 79 was never re-measured after them. The gate did its job: it made the drift visible at release time rather than letting it accrue silently. Next addition breaches again by design."
+        },
+        "mcp_public_tool_count": {
+            "max": 19,
+            "last_measured": 19,
+            "method": "tools/list length on the stdio server (post-ADR-132: implemented tools only)"
+        }
+    }
+}

package/src/config/hook-latency-budget.json

@@ -0,0 +1,20 @@
+{
+    "_comment": "Pre-registered hook-latency budget (road-to-credible-install Phase 1). Committed BEFORE the first optimization landed, per the roadmap's pre-registration discipline: the numbers below are the acceptance bar the precompile + single-process work is measured against, not a post-hoc fit. Consumed by the bench harness (scripts/bench_hook_latency) and its CI gate. Every budget carries an owner and a review date per the Phase-6 budget-ownership lint.",
+    "schema_version": 1,
+    "registered_at": "2026-07-27",
+    "owner": "maintainer",
+    "review_by": "2027-07-27",
+    "hardware_reference": {
+        "ci": "GitHub-hosted ubuntu-latest runner (the numbers the gate enforces)",
+        "floor": "1 vCPU reference container (documented ceiling, not CI-enforced)"
+    },
+    "budgets_ms": {
+        "pre_tool_use": { "p95_ci": 150, "p95_1vcpu": 400 },
+        "any_hook_event": { "p95_ci": 250 }
+    },
+    "regression_gate": {
+        "max_regression_pct": 200,
+        "_comment": "Pathology net only — the ABSOLUTE budgets above are the binding gate for wall-clock. The original 20% window was falsified by measured GitHub-runner variance: two CI runs of IDENTICAL code measured p95 77-89 ms and 92-103 ms (+23% run-to-run, 2026-07-27, runs 30303438480 / round-2 tests.yml). Same rationale as the regression_pct 200 override on the evaluator timing budgets: a tight creep rule on shared-runner wall-clock flaps; sizes/counts keep tight windows, timings get absolute caps."
+    },
+    "honest_null_consequence": "If the budget is missed after precompile + single-process + lazy I/O, hooks ship default-off with an explicit opt-in flag and the measured numbers published under a 'known cost' heading. A resident-dispatcher daemon is NOT improvised as a rescue (council 2026-07-26)."
+}

package/src/config/reach-channels.yml

@@ -0,0 +1,217 @@
+# Reach channel registry — standalone operator tooling
+# (road-to-internet-reach Phase 1).
+#
+# WHAT THIS FILE IS. A machine-checked answer to three operator questions:
+# which external backend does a reach recipe need, is that backend healthy,
+# and is its install command pinned. Schema:
+# src/scripts/schemas/reach-channels.schema.json; gate:
+# `task check-reach-channels`.
+#
+# WHAT THIS FILE IS NOT. Not a routing table, not a recommendation, not an
+# agent-facing surface. The Phase 0 pre-registered benchmark returned
+# `band: stop` (native arm 12/12, reach arm 0 outright wins), so no router
+# skill ships and NO channel below is routed, preferred, or suggested to an
+# agent. Reading a channel here as "the agent should use this" is a
+# misreading of the verdict.
+#
+# BACKEND ORDER IS THE SWITCH. `backends:` is an ordered candidate list —
+# each entry satisfies the channel on its own (an alternative, never a
+# pipeline stage). Changing the preferred candidate is reordering this list,
+# never editing code. Channel order carries no meaning.
+#
+# LIFECYCLE VOCABULARY IS BORROWED, NOT FORKED. `lifecycle:` uses the four
+# values from docs/contracts/provider-lifecycle.md (`experimental | stable |
+# deprecated | community`). `stable` here means the same thing it means
+# there: a maintainer exercised it against a real run at least once.
+#
+# PINNING IS LOAD-BEARING. Every `install:` string is either an explicitly
+# version-pinned command or an `os-baseline:` sentinel (see below). Moving
+# targets — `latest`, `main`, `master`, `HEAD`, archive/tarball URLs — are
+# rejected by the schema pattern, not by good intentions. The package never
+# executes these strings: a human reads and runs them.
+#
+# OS BASELINES ARE NOT PACKAGE INSTALLS. `curl` and `node` are assumed
+# present: they ship with the OS or the developer's base image. Their
+# prescriptions therefore name the platform's own package manager and stay
+# unpinned wherever a version pin is not meaningful, marked with the
+# explicit `os-baseline:` sentinel so the absence of a pin is a declared
+# decision rather than an oversight. Where a pin IS meaningful — Node's
+# major line — a real versioned formula is used.
+#
+# `jq` IS DELIBERATELY NOT A BACKEND. JSON shaping happens inside the
+# operator's own recipe, downstream of retrieval; it is not a candidate
+# that satisfies a channel. If it ever becomes one, it inherits the same
+# `os-baseline:` convention as curl.
+#
+# PIN PROVENANCE (looked up 2026-07-24, never invented):
+#   gh 2.96.0      — `gh --version` on the authoring machine, corroborated by
+#                    https://api.github.com/repos/cli/cli/releases/latest
+#                    (tag_name v2.96.0) and
+#                    https://formulae.brew.sh/api/formula/gh.json (stable 2.96.0).
+#   yt-dlp 2026.7.4 — https://pypi.org/pypi/yt-dlp/json (.info.version).
+#   node@22        — https://formulae.brew.sh/api/formula/node@22.json
+#                    (versioned formula exists; stable 22.23.1 at lookup time).
+#   asdf plugin `github-cli` — exists in the asdf plugin index
+#                    (raw.githubusercontent.com/asdf-vm/asdf-plugins → plugins/github-cli).
+#                    Homebrew has no versioned `gh` formula, so an exactly
+#                    pinned macOS/Linux prescription goes through asdf.
+#   winget id `GitHub.cli` version 2.96.0 — present in the winget-pkgs manifest
+#                    tree (api.github.com/repos/microsoft/winget-pkgs/contents/
+#                    manifests/g/GitHub/cli lists 2.96.0).
+#
+# `last_verified:` MUST stay quoted — an unquoted ISO date parses as a
+# timestamp, not a string, and fails the schema type check.
+schema_version: reach-channels-v1
+
+channels:
+  # Repository metadata: issues, PRs, releases, workflow runs, raw file reads.
+  # `free-key`: unauthenticated GitHub API access is rate-limited hard enough
+  # that a token is the practical floor. The token is operator-provisioned;
+  # nothing here reads, stores, or forwards it.
+  - id: github
+    description: Repository, issue, release and workflow metadata from the GitHub API.
+    tier: free-key
+    lifecycle: stable
+    override_key: reach.channels.github.backend
+    last_verified: "2026-07-24"
+    backends:
+      - id: gh
+        probe_cmd: gh
+        probe_args: ["--version"]
+        install:
+          darwin: asdf plugin add github-cli && asdf install github-cli 2.96.0
+          linux: asdf plugin add github-cli && asdf install github-cli 2.96.0
+          win32: winget install --id GitHub.cli --version 2.96.0
+          default: asdf plugin add github-cli && asdf install github-cli 2.96.0
+
+  # Video metadata and subtitle tracks. `yt-dlp` is NOT installed on the
+  # authoring machine, and that is expected: this file is validated offline
+  # against the schema only, so an absent backend cannot fail the gate. Its
+  # health is the probe layer's question, never the registry's.
+  # `experimental` for exactly that reason — the shape is right, no
+  # maintainer has exercised this backend against a real run.
+  - id: youtube
+    description: Video metadata and subtitle tracks for a public video URL.
+    tier: zero-config
+    lifecycle: experimental
+    override_key: reach.channels.youtube.backend
+    last_verified: "2026-07-24"
+    backends:
+      - id: yt-dlp
+        probe_cmd: yt-dlp
+        probe_args: ["--version"]
+        install:
+          darwin: pipx install yt-dlp==2026.7.4
+          linux: pipx install yt-dlp==2026.7.4
+          win32: py -m pipx install yt-dlp==2026.7.4
+          default: pipx install yt-dlp==2026.7.4
+
+  # Feed retrieval. Two independent candidates: fetch the feed with curl, or
+  # fetch-and-parse it in a Node one-liner. Either satisfies the channel.
+  - id: rss
+    description: Atom and RSS feed retrieval for a known feed URL.
+    tier: zero-config
+    lifecycle: stable
+    override_key: reach.channels.rss.backend
+    last_verified: "2026-07-24"
+    backends:
+      - id: curl
+        probe_cmd: curl
+        probe_args: ["--version"]
+        install:
+          darwin: "os-baseline: macOS ships curl (8.7.1 observed 2026-07-24) at /usr/bin/curl — no package install prescribed"
+          linux: "os-baseline: distro-provided curl package (apt / dnf / apk) — version tracks the distro, no pin meaningful"
+          win32: "os-baseline: Windows 10+ ships curl.exe in System32 — no package install prescribed"
+          default: "os-baseline: a system curl is assumed present; if absent, install it from the platform package manager — never a piped remote installer"
+      - id: node
+        probe_cmd: node
+        probe_args: ["--version"]
+        install:
+          darwin: brew install node@22
+          linux: "os-baseline: distro or NodeSource nodejs package — version tracks the chosen channel, no pin meaningful here"
+          win32: "os-baseline: winget package OpenJS.NodeJS.LTS — version tracks the LTS line, no pin meaningful here"
+          default: "os-baseline: any Node runtime at or above this package's engines floor (>=20.11.0) already on PATH"
+
+  # Single-page read. Same two candidates as `rss`: curl fetches the bytes;
+  # Node covers the case where the extraction step runs in-process.
+  - id: web-read
+    description: Single public web page fetch for a URL the operator already has.
+    tier: zero-config
+    lifecycle: stable
+    override_key: reach.channels.web-read.backend
+    last_verified: "2026-07-24"
+    backends:
+      - id: curl
+        probe_cmd: curl
+        probe_args: ["--version"]
+        install:
+          darwin: "os-baseline: macOS ships curl (8.7.1 observed 2026-07-24) at /usr/bin/curl — no package install prescribed"
+          linux: "os-baseline: distro-provided curl package (apt / dnf / apk) — version tracks the distro, no pin meaningful"
+          win32: "os-baseline: Windows 10+ ships curl.exe in System32 — no package install prescribed"
+          default: "os-baseline: a system curl is assumed present; if absent, install it from the platform package manager — never a piped remote installer"
+      - id: node
+        probe_cmd: node
+        probe_args: ["--version"]
+        install:
+          darwin: brew install node@22
+          linux: "os-baseline: distro or NodeSource nodejs package — version tracks the chosen channel, no pin meaningful here"
+          win32: "os-baseline: winget package OpenJS.NodeJS.LTS — version tracks the LTS line, no pin meaningful here"
+          default: "os-baseline: any Node runtime at or above this package's engines floor (>=20.11.0) already on PATH"
+
+  # Discussion search over the public Hacker News search API. Keyless, and
+  # the endpoint returns JSON directly — one candidate is enough.
+  - id: hackernews
+    description: Discussion and comment search over the public Hacker News search API.
+    tier: zero-config
+    lifecycle: stable
+    override_key: reach.channels.hackernews.backend
+    last_verified: "2026-07-24"
+    backends:
+      - id: curl
+        probe_cmd: curl
+        probe_args: ["--version"]
+        install:
+          darwin: "os-baseline: macOS ships curl (8.7.1 observed 2026-07-24) at /usr/bin/curl — no package install prescribed"
+          linux: "os-baseline: distro-provided curl package (apt / dnf / apk) — version tracks the distro, no pin meaningful"
+          win32: "os-baseline: Windows 10+ ships curl.exe in System32 — no package install prescribed"
+          default: "os-baseline: a system curl is assumed present; if absent, install it from the platform package manager — never a piped remote installer"
+
+  - id: reddit
+    description: Reddit discussion reading in two tiers — durable Atom text, and time-bounded ranked HTML.
+    tier: zero-config
+    lifecycle: experimental
+    override_key: reach.channels.reddit.backend
+    last_verified: "2026-07-25"
+    backends:
+      - id: curl
+        probe_cmd: curl
+        probe_args: ["--version"]
+        install:
+          darwin: "os-baseline: macOS ships curl (8.7.1 observed 2026-07-25) at /usr/bin/curl — no package install prescribed"
+          linux: "os-baseline: distro-provided curl package (apt / dnf / apk) — version tracks the distro, no pin meaningful"
+          win32: "os-baseline: Windows 10+ ships curl.exe in System32 — no package install prescribed"
+          default: "os-baseline: a system curl is assumed present; if absent, install it from the platform package manager — never a piped remote installer"
+      - id: node
+        probe_cmd: node
+        probe_args: ["--version"]
+        install:
+          darwin: brew install node@22
+          linux: "os-baseline: distro or NodeSource nodejs package — version tracks the chosen channel, no pin meaningful here"
+          win32: "os-baseline: winget package OpenJS.NodeJS.LTS — version tracks the LTS line, no pin meaningful here"
+          default: "os-baseline: any Node runtime at or above this package's engines floor (>=20.11.0) already on PATH"
+
+  - id: twitter-oembed
+    description: Single public tweet read through the platform's own oEmbed endpoint, credential-free.
+    tier: zero-config
+    lifecycle: experimental
+    override_key: reach.channels.twitter-oembed.backend
+    last_verified: "2026-07-25"
+    backends:
+      - id: curl
+        probe_cmd: curl
+        probe_args: ["--version"]
+        install:
+          darwin: "os-baseline: macOS ships curl (8.7.1 observed 2026-07-25) at /usr/bin/curl — no package install prescribed"
+          linux: "os-baseline: distro-provided curl package (apt / dnf / apk) — version tracks the distro, no pin meaningful"
+          win32: "os-baseline: Windows 10+ ships curl.exe in System32 — no package install prescribed"
+          default: "os-baseline: a system curl is assumed present; if absent, install it from the platform package manager — never a piped remote installer"

package/src/config/reach-prescriptions-intake.yml

@@ -0,0 +1,200 @@
+# Reach prescription intake record — committed supply-chain evidence
+# (road-to-internet-reach Phase 3, Step 2).
+#
+# WHAT THIS FILE IS. The offline substitute for a network lookup at lint time.
+# `src/scripts/validate_reach_prescriptions.ts` (gate:
+# `task check-reach-prescriptions`) reads THIS file to answer "does the package
+# this prescription names exist, is its pin the one we checked, and was it
+# CVE-reviewed" — it never fetches a registry. That is a hard architectural
+# constraint, not a convenience: the Class A boundary
+# (docs/contracts/no-runtime-boundary.md, ADR-124) forbids network access in the
+# build path, and a lint that phones a third party is a flaky lint.
+#
+# CONSEQUENCE. Every claim below is a HUMAN-RUN check frozen at `checked_on`.
+# Freshness is a maintenance duty, not a guarantee this file can make about
+# itself: re-run the recorded commands, update `pinned_version` +
+# `verified_on`, and change the registry pin in the same commit.
+#
+# WHAT AN ENTRY IS FOR. `tools:` carries exactly one entry per EXTERNALLY
+# INSTALLED third-party tool named by an install prescription in
+# src/config/reach-channels.yml. A prescription whose backend has no entry
+# here cannot ship — the validator fails closed on it.
+#
+# WHY `os_baseline:` IS A SEPARATE CLASS, NOT A THIN `tools:` ENTRY. `curl`,
+# `node` and `jq` are not package installs this project prescribes: they ship
+# with the OS or the developer's base image. Writing a fake intake entry for
+# them — "existence verified: it is curl" — would launder an assumption into
+# evidence and put a registry/CVE claim on this project's ledger that nobody
+# actually checked per platform. They are declared as baselines instead, with
+# the reason, and the validator exempts them from the `tools:` requirement
+# while still enforcing the pinning rules on any string they do carry.
+#
+# EXECUTION HONESTY. `asdf` and `pipx` are ABSENT on the authoring machine
+# (`which asdf` / `which pipx` → not found), so no install command below was
+# ever executed here. That is the design: prescription-first, human-performed,
+# no auto-install (roadmap `## Non-goals`). Existence was verified against the
+# registries' own metadata APIs, which is what the pin depends on.
+#
+# ISO DATES MUST STAY QUOTED — unquoted, YAML parses them as timestamps and
+# the validator's string check fails loudly.
+schema_version: reach-prescriptions-intake-v1
+
+# The date every `verification.command` below was last executed by a human.
+checked_on: "2026-07-24"
+
+tools:
+  # ── gh ────────────────────────────────────────────────────────────────────
+  # Backend of the `github` channel. Two package identities because no
+  # single registry offers an exactly-pinnable `gh` on every platform:
+  # Homebrew ships only an unversioned `gh` formula (a pin there would be a
+  # lie), so macOS/Linux go through asdf, and Windows through winget.
+  - backend: gh
+    tool: gh
+    pinned_version: "2.96.0"
+    packages:
+      - registry: asdf
+        package: github-cli
+      - registry: winget
+        package: GitHub.cli
+    intake:
+      existence_verified: >-
+        Three independent confirmations at the pin. (1) The binary itself
+        reports 2.96.0 on the authoring machine. (2) The asdf plugin index
+        contains plugins/github-cli (blob sha
+        b8ab100243bc01e361a61c50d11d4ab66b790c92). (3) The winget-pkgs manifest
+        tree lists exactly 2.96.0 under manifests/g/GitHub/cli. Not a
+        model-produced name: every identifier came out of a registry response.
+      pinned: >-
+        Exact, both platforms — `asdf install github-cli 2.96.0` and
+        `winget install --id GitHub.cli --version 2.96.0`. No range, no
+        `latest`, no branch, no archive URL. Homebrew was rejected as the
+        macOS/Linux path precisely because its unversioned `gh` formula admits
+        no exact pin at all — a pinned-looking Homebrew line would be fiction.
+      lockfile_note: >-
+        No project lockfile applies — gh is an external CLI a human installs,
+        never a dependency of this package (absent from package.json, and this
+        repo ships no .tool-versions). The lock equivalent is the exact pin in
+        this record plus asdf's own .tool-versions in the operator's
+        environment, if they use one. Nothing in this repo can pin it for them.
+      cve_note: >-
+        GitHub Advisory Database, ecosystem `go`, package
+        github.com/cli/cli/v2: 6 advisories, newest first_patched_version
+        2.93.0 (GHSA-8xvp-7hj6-mcj9, TUF-mirror auth header). 2.93.0 <= 2.96.0,
+        so no listed advisory affects the pin. Reviewed by advisory listing, not
+        by a scanner — osv-scanner and pip-audit are not installed here, and
+        neither covers a system CLI install anyway.
+    verified_on: "2026-07-24"
+    verification:
+      - command: gh --version
+        source: local PATH on the authoring machine
+        observed: "gh version 2.96.0 (2026-07-02)"
+      - command: gh api repos/asdf-vm/asdf-plugins/contents/plugins/github-cli --jq '.sha + " " + .path'
+        source: https://api.github.com/repos/asdf-vm/asdf-plugins
+        observed: "b8ab100243bc01e361a61c50d11d4ab66b790c92 plugins/github-cli"
+      - command: gh api repos/microsoft/winget-pkgs/contents/manifests/g/GitHub/cli --jq '[.[].name] | map(select(startswith("2.96")))'
+        source: https://api.github.com/repos/microsoft/winget-pkgs
+        observed: '["2.96.0"]'
+      - command: gh api "/advisories?ecosystem=go&affects=github.com%2Fcli%2Fcli%2Fv2&per_page=100" --jq '[.[].vulnerabilities[] | select(.package.name=="github.com/cli/cli/v2") | .first_patched_version] | unique | sort'
+        source: https://api.github.com/advisories
+        observed: '["2.62.0","2.63.0","2.63.1","2.67.0","2.92.0","2.93.0"]'
+
+  # ── yt-dlp ────────────────────────────────────────────────────────────────
+  # Backend of the `youtube` channel, and NOT installed here — the roadmap
+  # blocker `yt-dlp-not-installed` is open by design. An intake record is
+  # about whether the prescription is safe to hand a human, which is a
+  # different question from whether the tool is present locally; the probe
+  # layer owns the second one.
+  - backend: yt-dlp
+    tool: yt-dlp
+    pinned_version: "2026.7.4"
+    packages:
+      - registry: PyPI
+        package: yt-dlp
+    intake:
+      existence_verified: >-
+        PyPI JSON API reports .info.version 2026.7.4 for the project, and the
+        per-release endpoint /pypi/yt-dlp/2026.7.4/json resolves with 2 upload
+        files — so the exact pinned release exists, not merely the project name.
+        Typo-adjacency checked deliberately: `yt-dlp` is the hyphenated form,
+        the shape most prone to hallucinated variants (`ytdlp`, `yt_dlp`,
+        `youtube-dl`); the identifier used here is the one PyPI returned.
+      pinned: >-
+        Exact PyPI equality pin — `pipx install yt-dlp==2026.7.4` (Windows:
+        `py -m pipx install yt-dlp==2026.7.4`). yt-dlp publishes date-shaped
+        versions, so a `latest`-style install would silently roll forward
+        every few days; the schema rejects that form outright.
+      lockfile_note: >-
+        No project lockfile applies — an isolated pipx application, not a
+        dependency of this package. pipx records the exact spec in its own
+        venv metadata; the pin above is the only lock this repo controls.
+      cve_note: >-
+        GitHub Advisory Database, ecosystem `pip`, package yt-dlp: 11
+        advisories, newest first_patched_version 2026.6.9 (GHSA-69qj-pvh9-c5wg
+        `--exec` command injection, plus three siblings patched in the same
+        release). 2026.6.9 < 2026.7.4, so no listed advisory affects the pin.
+        Worth carrying forward: the tool's own history is dominated by
+        argument-injection and filename-sanitization classes, which is one more
+        reason its output is untrusted content, never instructions
+        (src/rules/untrusted-input-defense.md).
+    verified_on: "2026-07-24"
+    verification:
+      - command: curl -fsSL https://pypi.org/pypi/yt-dlp/json | jq -r '.info.version'
+        source: https://pypi.org/pypi/yt-dlp/json
+        observed: "2026.7.4"
+      - command: curl -fsSL https://pypi.org/pypi/yt-dlp/2026.7.4/json | jq -r '.info.version + " files=" + (.urls|length|tostring)'
+        source: https://pypi.org/pypi/yt-dlp/2026.7.4/json
+        observed: "2026.7.4 files=2"
+      - command: gh api "/advisories?ecosystem=pip&affects=yt-dlp&per_page=100" --jq '[.[].vulnerabilities[] | select(.package.name=="yt-dlp") | .first_patched_version] | unique | sort'
+        source: https://api.github.com/advisories
+        observed: '["2023.09.24","2023.11.14","2023.7.06","2024.04.09","2024.07.01","2024.07.07","2026.02.21","2026.6.9"]'
+
+# ── OS baselines — declared non-installs ──────────────────────────────────
+# Present because the registry names them as backends, NOT because this
+# project prescribes installing them. Each entry states why a pin is not
+# meaningful; the validator exempts these from the `tools:` requirement and
+# still enforces "pinned or explicit os-baseline sentinel" on every string
+# they carry.
+os_baseline:
+  - tool: curl
+    os_baseline: true
+    rationale: >-
+      Ships with macOS (/usr/bin/curl) and Windows 10+ (System32\curl.exe),
+      and is a distro package on Linux whose version tracks the distro. There
+      is no cross-platform version this project could pin without prescribing
+      a source it does not control — so the registry carries `os-baseline:`
+      sentinels and no version, deliberately.
+    verification:
+      - command: curl --version | head -1
+        source: local PATH on the authoring machine
+        observed: "curl 8.7.1 (x86_64-apple-darwin24.0) libcurl/8.7.1"
+
+  - tool: node
+    os_baseline: true
+    rationale: >-
+      A Node runtime is this package's own execution baseline
+      (package.json engines >=20.11.0), so any environment that can run the
+      validator already has it. The one platform where a pin IS meaningful —
+      Homebrew's versioned major-line formula — carries a real pin
+      (`brew install node@22`), verified below; the remaining platforms track
+      their own LTS channel and stay unpinned behind an explicit sentinel.
+    verification:
+      - command: curl -fsSL https://formulae.brew.sh/api/formula/node@22.json | jq -r '.versions.stable'
+        source: https://formulae.brew.sh/api/formula/node@22.json
+        observed: "22.23.1 (versioned formula node@22 exists)"
+      - command: node --version
+        source: local PATH on the authoring machine
+        observed: "v25.9.0"
+
+  - tool: jq
+    os_baseline: true
+    rationale: >-
+      Named nowhere in the registry as a backend on purpose — JSON shaping
+      happens inside the operator's own recipe, downstream of retrieval, so jq
+      never satisfies a channel. Recorded here so its absence from `tools:` is
+      a documented decision rather than an omission: if jq ever becomes a
+      backend it inherits curl's `os-baseline:` treatment, not a fabricated
+      pin.
+    verification:
+      - command: jq --version
+        source: local PATH on the authoring machine
+        observed: "jq-1.7.1-apple"

package/src/install/agentSwitchDetection.ts

@@ -0,0 +1,90 @@
+/**
+ * agent-switch detection — passive wizard recommendation (S0.1 honest-null
+ * council verdict, 2026-07-28: PASSIVE ROW ONLY, never a proactive card).
+ *
+ * agent-switch (https://github.com/event4u-app/agent-switch,
+ * `@event4u/agent-switch` on npm) isolates multiple agent accounts into
+ * per-account profiles (`CLAUDE_CONFIG_DIR`) so switching accounts never
+ * requires a re-login. Unlike rtk, the install command is npm-global and
+ * identical on every OS — no per-OS command map, no name collision to
+ * disambiguate.
+ *
+ * Two independent installed-signals, either is sufficient:
+ *   - the `agent-switch` binary is resolvable on PATH (the documented
+ *     npm-global install), OR
+ *   - `~/.agent-switch/` exists — a user who installed it another way must
+ *     never be told to install it again.
+ *
+ * Version is only probed when the binary is on PATH (the directory-only
+ * signal carries no version information — reported as `null`). There is
+ * deliberately NO version-currency check and NO network call here — the
+ * wizard only ever answers "installed or not", never "up to date" (roadmap
+ * acceptance criterion: this module does not report on agent-switch's
+ * version currency).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveBinaryOnPath } from './rtkDetection.js';
+
+export const AGENT_SWITCH_REPO = 'event4u-app/agent-switch';
+export const AGENT_SWITCH_NPM = '@event4u/agent-switch';
+export const AGENT_SWITCH_INSTALL_COMMAND = 'npm install -g @event4u/agent-switch';
+
+export interface AgentSwitchDetection {
+    installed: boolean;
+    version: string | null;
+}
+
+export interface DetectAgentSwitchOptions {
+    /** Override the home directory (tests). */
+    home?: string;
+    /** Override PATH (tests). */
+    pathEnv?: string;
+    /** Override the version probe (tests). Receives the resolved binary path. */
+    probeVersion?: (bin: string) => string | null;
+}
+
+const PROBE_TIMEOUT_MS = 2000;
+
+/** First dotted-number token in `output`, or `null` when none is present. */
+export function parseVersionOutput(output: string): string | null {
+    const m = /(\d+\.\d+(?:\.\d+)?)/.exec(output);
+    return m?.[1] ?? null;
+}
+
+function defaultProbeVersion(bin: string): string | null {
+    try {
+        const res = spawnSync(bin, ['--version'], {
+            timeout: PROBE_TIMEOUT_MS,
+            encoding: 'utf-8',
+            windowsHide: true,
+        });
+        if (res.error !== undefined || res.signal !== null) return null;
+        return parseVersionOutput(`${res.stdout ?? ''}\n${res.stderr ?? ''}`);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Detect agent-switch installation. Never throws — every failure mode
+ * (spawn error, timeout, unparsable output) collapses to `version: null`.
+ */
+export function detectAgentSwitch(options: DetectAgentSwitchOptions = {}): AgentSwitchDetection {
+    const binPath = resolveBinaryOnPath('agent-switch', options.pathEnv);
+    if (binPath !== null) {
+        const probe = options.probeVersion ?? defaultProbeVersion;
+        let version: string | null;
+        try {
+            version = probe(binPath);
+        } catch {
+            version = null;
+        }
+        return { installed: true, version };
+    }
+    const home = options.home ?? homedir();
+    const dirInstalled = existsSync(join(home, '.agent-switch'));
+    return { installed: dirInstalled, version: null };
+}