@event4u/agent-config 9.6.0 → 9.8.0

package/src/config/agent-settings.template.yml

@@ -546,6 +546,39 @@ consistency:
   #        reading of whichever source it happened to read).
   cross_source: "on"
 
+# --- Documentation screenshots ---
+#
+# When the agent creates screenshots for documentation (e.g. generating a docs
+# site) and embeds them, sensitive data visible on the screenshot MUST be
+# anonymized / pixelated before it ships. Consumed by the `doc-screenshot-hygiene`
+# rule and the `screenshot-hygiene` skill. Automated detection is a helper that
+# flags + pre-redacts — never a clearance; the gate for a data-bearing screenshot
+# is human confirmation (routing into `non-destructive-by-default`, since a
+# shipped screenshot is an irreversible published egress).
+screenshots:
+  # Public identity tokens that are SAFE to show unredacted — the maintainer's
+  # OWN public handles (e.g. a username shown in an admin panel) plus well-known
+  # fake-data tokens. This is NOT a general fake-data dictionary and NOT
+  # identity-resolution: everything not on this list is treated as sensitive by
+  # default. A public handle co-located with a real name does NOT whitelist the
+  # real name. Default: [] (nothing auto-allowed; every identity is human-decided).
+  identity_allowlist: []
+
+  # true | false  (default: true)
+  # true  = terminal / CLI / IDE screenshots are FORBIDDEN (highest leak vector:
+  #         absolute local paths, env tokens). Use text code blocks with text
+  #         redaction instead.
+  # false = allowed, but still subject to the data-bearing human gate.
+  forbid_terminal_capture: true
+
+  # on | off  (default: on)
+  # on  = a data-bearing screenshot embed is gated behind this-turn human
+  #       confirmation; uncertain/unresolved regions → redact-or-refuse, never
+  #       ship-and-hope. Illustrative / no-data screenshots (diagrams, logos,
+  #       placeholder-only UI) may embed with a stated justification.
+  # off = no data-bearing gate (legacy; the anonymization taxonomy still applies).
+  data_bearing_gate: "on"
+
 code_style:
   # minimal | full  (default: minimal)
   #
@@ -1007,6 +1040,16 @@ hooks:
   design_slop:
     enabled: false
 
+  # PreToolUse code-graph nudge (ADR-124 Phase 4). Default-OFF. When enabled
+  # AND a native code-graph engine has built a cache (or the repo ships a
+  # graph.json / SCIP index), WARNS once per session (exit 2, never blocks) as
+  # the agent is about to Grep/Glob or Read a source file: query the graph
+  # first for "who calls / where used / impact" questions (or rebuild if the
+  # index is stale, or build one if absent). Source G's strict block-first-read
+  # mode is deliberately un-ported. Build the cache with `code_graph build`.
+  code_graph:
+    enabled: false
+
 # --- Decision engine ---
 #
 # Controllable gates layered over the observability surface. Absent

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/scripts/_dispatch.bash

@@ -205,6 +205,15 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              Usage: hooks:replay --platform <name> --event <event>
                                     --payload <path|event-name> [--native-event <native>]
                                     [--manifest <path>] [--json] [--dry-run]
+  reach:doctor               Health report over the reach channel registry: per channel
+                             the active backend, lifecycle, and the pinned install command
+                             for this platform when a backend is missing/broken.
+                             Read-only — no writes, no installs; NOT a router and NOT an
+                             agent-facing recommendation.
+                             Flags: --format json|table, --strict (CI), --channel <id>,
+                             --registry <path>, --deep (⚠️  opt-in NETWORK: one real
+                             read-only request per declared backend; never runs in CI,
+                             writes nothing)
   memory:lookup              Retrieve memory entries (text or JSON envelope)
   linked-projects:list       List opted-in IDE-attached sibling repos (path · detected_via · large)
                              Flags: --all (show undecided too), --format json
@@ -636,6 +645,11 @@ cmd_hooks_replay() {
   exec_hook "src/scripts/hooks/replay_hook" "$@"
 }
 
+# Read-only reach-channel health report. Never installs, never writes.
+cmd_reach_doctor() {
+  exec_hook "src/scripts/reach_doctor" "$@"
+}
+
 cmd_chat_history_checkpoint() {
   local script
   script="$(resolve_script "src/scripts/chat_history.ts")" || return 1
@@ -1085,6 +1099,7 @@ main() {
     hooks:status)            cmd_hooks_status "$@" ;;
     hooks:doctor)            cmd_hooks_doctor "$@" ;;
     hooks:replay)            cmd_hooks_replay "$@" ;;
+    reach:doctor)            cmd_reach_doctor "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;
     telemetry:status)        cmd_telemetry_status "$@" ;;
     telemetry:report)        cmd_telemetry_report "$@" ;;

package/src/scripts/_lib/adversarial_bench_score.ts

@@ -0,0 +1,106 @@
+/**
+ * Deterministic scorer for the adversarial-council residual-detection benchmark
+ * (road-to-adversarial-council-benchmark Phase 1).
+ *
+ * Pure + countable — never LLM-computed (the anti-lesson from ADR-122). Given a
+ * corpus item's ground truth and a reviewer's structured findings, decide
+ * whether the reviewer CAUGHT the planted defect (for a defect fixture) or
+ * raised a FALSE POSITIVE (for a clean control). The two-stage recalls and FP
+ * rates this produces feed `evaluateCouncilBench` (adversarial_council_gate.ts).
+ *
+ * Matching rule (deliberately NOT exact file:line — the scorer bug from the
+ * earlier defect-finding benchmark required an exact line token and mis-scored
+ * genuine catches that cited a nearby line): a finding CATCHES a planted defect
+ * iff it names one of the defect's file(s) by basename AND its category falls in
+ * the same normalized family as the planted defect. Line numbers are advisory,
+ * never required. This credits a real catch that localizes the right file +
+ * defect class, and denies credit for a scattershot "something's wrong here"
+ * with the wrong class.
+ */
+
+/** Normalize a free-form category string to a coarse family. */
+export function categoryFamily(raw: string): string {
+    const c = raw.toLowerCase().replace(/[^a-z]/g, '');
+    if (/(accesscontrol|authz|authorization|idor|bola|ownership|privilege|rbac)/.test(c)) return 'access-control';
+    if (/(auth|authentication|session|credential|login)/.test(c)) return 'auth';
+    if (/(ssrf|serverside)/.test(c)) return 'ssrf';
+    if (/(pathtraversal|traversal|directorytraversal|lfi)/.test(c)) return 'path-traversal';
+    // NB: no bare "rce" token — it substring-matches inside "resou[rce]leak".
+    if (/(injection|sqli|xss|commandinjection|deserial|remotecodeexec)/.test(c)) return 'injection';
+    if (/(crypto|cryptographic|timing|constanttime|hash|signature)/.test(c)) return 'crypto';
+    if (/(concurrency|race|atomic|deadlock|idempoten)/.test(c)) return 'concurrency';
+    if (/(resourceleak|leak|memory|handle|unsubscrib|cleanup)/.test(c)) return 'resource-leak';
+    if (/(dataintegrity|integrity|corrupt|consistency|stale)/.test(c)) return 'data-integrity';
+    if (/(correctness|logic|offbyone|boundary|edgecase|bug)/.test(c)) return 'correctness';
+    return 'other';
+}
+
+export interface Finding {
+    /** File the finding points at (any path form; matched by basename). */
+    file: string;
+    /** Reviewer-supplied category (free text; normalized via categoryFamily). */
+    category: string;
+    /** Reviewer confidence, if given. Low-confidence findings can be excluded from FP counting. */
+    confidence?: 'high' | 'medium' | 'low';
+}
+
+export interface GroundTruth {
+    id: string;
+    /** true = clean control (no defect); a finding here is a false positive. */
+    is_clean: boolean;
+    /** Basenames of the file(s) the planted defect lives in (empty for clean). */
+    defect_files: string[];
+    /** Planted defect category family (via categoryFamily); empty for clean. */
+    defect_category: string;
+}
+
+function basename(p: string): string {
+    return p.split(/[\\/]/).pop() ?? p;
+}
+
+/**
+ * Did the reviewer CATCH the planted defect? file-basename match on any defect
+ * file AND category-family match. Clean controls always return false (they have
+ * no defect to catch — use `isFalsePositive` for them).
+ */
+export function caughtDefect(truth: GroundTruth, findings: Finding[]): boolean {
+    if (truth.is_clean) return false;
+    const wantFiles = new Set(truth.defect_files.map(basename));
+    const wantFamily = truth.defect_category;
+    return findings.some(
+        (f) => wantFiles.has(basename(f.file)) && categoryFamily(f.category) === wantFamily,
+    );
+}
+
+/**
+ * Did the reviewer raise a FALSE POSITIVE on a clean control? Any finding that
+ * points at the control file counts (a claimed defect where none exists).
+ * Low-confidence findings are excluded — a hedged "might check X" is not a FP
+ * claim. Non-clean fixtures always return false.
+ */
+export function isFalsePositive(truth: GroundTruth, findings: Finding[]): boolean {
+    if (!truth.is_clean) return false;
+    return findings.some((f) => (f.confidence ?? 'high') !== 'low');
+}
+
+export interface StageResult {
+    /** Per-defect-fixture: id → caught?. Excludes clean controls. */
+    caught: Record<string, boolean>;
+    /** Per-clean-control: id → false-positive?. */
+    fp: Record<string, boolean>;
+}
+
+/** Recall over a set of defect ids, given per-id caught flags. */
+export function recall(caught: Record<string, boolean>): number {
+    const ids = Object.keys(caught);
+    if (ids.length === 0) return 0;
+    const hits = ids.filter((id) => caught[id]).length;
+    return hits / ids.length;
+}
+
+/** FP rate over clean controls. */
+export function fpRate(fp: Record<string, boolean>): number {
+    const ids = Object.keys(fp);
+    if (ids.length === 0) return 0;
+    return ids.filter((id) => fp[id]).length / ids.length;
+}