@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/release.ts

@@ -1451,9 +1451,30 @@ function execute(
         // publish that already happened.
         if (ci) {
             _step(9, total, 'Dispatch release-guard.yml + publish-npm.yml + cloud-release.yml for the tag');
-            run(['gh', 'workflow', 'run', 'release-guard.yml', '--ref', MAIN_BRANCH, '-f', `tag=${plan.target}`]);
-            run(['gh', 'workflow', 'run', 'publish-npm.yml', '--ref', MAIN_BRANCH, '-f', `tag=${plan.target}`]);
-            run(['gh', 'workflow', 'run', 'cloud-release.yml', '--ref', MAIN_BRANCH, '-f', `tag=${plan.target}`]);
+            // NON-FATAL by design. By this point the release is already complete
+            // — the tag is pushed and the GitHub Release is created above, and
+            // npm publish runs asynchronously. These explicit dispatches are a
+            // FALLBACK for a tag pushed with the default GITHUB_TOKEN, which does
+            // NOT fire tag-triggered workflows (GitHub's recursion guard). When
+            // the tag was pushed with a PAT (RELEASE_PR_TOKEN), those three
+            // workflows already fired on the push and this dispatch is redundant.
+            // Dispatching via the API additionally needs the token's
+            // `actions:write` scope; a 403 here (scope missing) must NOT mark an
+            // already-shipped release as failed — warn and continue.
+            for (const wf of ['release-guard.yml', 'publish-npm.yml', 'cloud-release.yml']) {
+                const r = run(['gh', 'workflow', 'run', wf, '--ref', MAIN_BRANCH, '-f', `tag=${plan.target}`], {
+                    check: false,
+                });
+                if (r.returncode !== 0) {
+                    process.stderr.write(
+                        `⚠️  Could not dispatch ${wf} (exit ${r.returncode}) — the release ${plan.target} is ` +
+                            `already complete (tag + GitHub Release created; npm publishes async). If the tag was ` +
+                            `pushed with a PAT, ${wf} already fired on the tag push. If you rely on the explicit ` +
+                            `dispatch, grant RELEASE_PR_TOKEN the "Actions: read and write" scope (fine-grained PAT) ` +
+                            `or the "workflow" scope (classic PAT).\n`,
+                    );
+                }
+            }
         }
     }
 

package/src/scripts/report_install_drift.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env tsx
+/**
+ * Installer drift report — measures, never gates.
+ *
+ * Compares the sha256 hashes recorded in `agents/installed-tools.lock`
+ * (`kind: 'deployed'` entries) against the current on-disk content of those
+ * same files and reports anything locally modified or deleted since the
+ * last install/upgrade. This is telemetry for the "do consumers edit
+ * framework-authoritative files" premise — it is NEVER a gate. The drift
+ * report itself always exits 0 regardless of what it finds; only a usage
+ * error (unknown flag, missing value) exits non-zero, matching the rest of
+ * this package's CLI scripts.
+ *
+ * `install.ts`'s global-install upgrade path calls the same
+ * `_lib/install_drift.ts` library directly (not this CLI) and always
+ * proceeds with the redeploy regardless of what the report finds.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/report_install_drift
+ *   ./scripts-run src/scripts/report_install_drift --project <path>
+ *   ./scripts-run src/scripts/report_install_drift --format json
+ *
+ * Exit codes: 0 report emitted (clean or drifted) · 2 usage error.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { collect_drift, format_drift_report } from "./_lib/install_drift.js";
+
+interface Options {
+  project: string;
+  format: "text" | "json";
+}
+
+function fail(message: string): never {
+  process.stderr.write(`❌  report_install_drift: ${message}\n`);
+  process.exit(2);
+}
+
+function _parse(argv: string[]): Options {
+  const opts: Options = { project: process.cwd(), format: "text" };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      process.stdout.write(
+        "usage: report_install_drift [--project <path>] [--format text|json]\n",
+      );
+      process.exit(0);
+    } else if (arg === "--project") {
+      const value = argv[i + 1];
+      if (value === undefined) fail("--project requires a value");
+      opts.project = path.resolve(value);
+      i += 1;
+    } else if (arg === "--format") {
+      const value = argv[i + 1];
+      if (value !== "text" && value !== "json") {
+        fail(`--format must be 'text' or 'json' (got ${JSON.stringify(value ?? null)})`);
+      }
+      opts.format = value;
+      i += 1;
+    } else {
+      fail(`unknown argument: ${arg}`);
+    }
+  }
+  return opts;
+}
+
+/**
+ * Run the report and print it. Always returns 0 — the finding is telemetry,
+ * never a build/CI failure signal.
+ */
+export function main(argv: string[] = process.argv.slice(2)): number {
+  const opts = _parse(argv);
+  const entries = collect_drift(opts.project);
+
+  if (opts.format === "json") {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          project_root: opts.project,
+          manifest_found: entries !== null,
+          drift: entries ?? [],
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    process.stdout.write(format_drift_report(entries));
+  }
+  return 0;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+    if (here === argv1) {
+      process.exit(main(process.argv.slice(2)));
+    }
+  } catch {
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+      process.exit(main(process.argv.slice(2)));
+    }
+  }
+}

package/src/scripts/risk_escalation_shadow.ts

@@ -0,0 +1,160 @@
+/**
+ * Risk-escalation shadow report — measure before adding teeth.
+ *
+ * Walks the last N first-parent merges, classifies each one's touched paths by
+ * trust-boundary risk, and writes what *would* have escalated. Nothing is
+ * gated. Nothing fails. The output is a number whose only job is to decide
+ * whether the gate is worth building.
+ *
+ * This is the same sequencing ADR-127 used on `exec:` evidence: pre-register a
+ * threshold, measure, then decide. The threshold here — >= 5 of ~100 merges
+ * landing in a trust-boundary class — was written into
+ * `agents/roadmaps/road-to-executable-evidence.md` Phase 2 before this script
+ * was first run, so a disappointing number cannot be re-framed into a
+ * justification afterwards.
+ *
+ * Why it must not gate yet: the escalation the reference pairs this with is
+ * *non-declinable* — a user's "no" stops counting. That trades away something
+ * this package's authority model holds (`agent-authority`, `ask-when-uncertain`),
+ * and a trade that size needs evidence that the class it protects is real here,
+ * not merely real somewhere.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/risk_escalation_shadow
+ *     ./scripts-run src/scripts/risk_escalation_shadow --limit 200
+ *     ./scripts-run src/scripts/risk_escalation_shadow --json
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { classify_diff, type RiskClass } from './_lib/risk_paths.js';
+
+const _FILE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_FILE), '..', '..');
+const OUT_REL = 'internal/reports/risk-escalation-shadow.json';
+
+/** Pre-registered in the roadmap BEFORE this report was first read. */
+const TEETH_THRESHOLD = 5;
+
+interface MergeRow {
+    sha: string;
+    subject: string;
+    files: number;
+    risk: RiskClass;
+    reasons: string[];
+}
+
+function git(args: string[]): string {
+    const r = spawnSync('git', args, { cwd: REPO, encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 });
+    if (r.status !== 0) return '';
+    return r.stdout ?? '';
+}
+
+function parse_limit(argv: string[]): number {
+    const i = argv.indexOf('--limit');
+    if (i === -1) return 100;
+    const n = Number(argv[i + 1]);
+    return Number.isFinite(n) && n > 0 ? n : 100;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const limit = parse_limit(argv);
+    const asJson = argv.includes('--json');
+
+    const log = git(['log', '--first-parent', `-${limit}`, '--format=%H%x00%s']).trim();
+    if (!log) {
+        process.stderr.write('❌  risk_escalation_shadow: no git history readable\n');
+        return 2;
+    }
+
+    const rows: MergeRow[] = [];
+    for (const line of log.split('\n')) {
+        const [sha, subject] = line.split('\0');
+        if (!sha) continue;
+        // First-parent diff: what this merge brought to the trunk.
+        const files = git(['show', '--first-parent', '--name-only', '--format=', sha])
+            .split('\n')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        if (files.length === 0) continue;
+        const verdict = classify_diff(files);
+        rows.push({
+            sha: sha.slice(0, 9),
+            subject: (subject ?? '').slice(0, 90),
+            files: files.length,
+            risk: verdict.risk,
+            reasons: [...new Set(verdict.reasons.map((r) => r.because))],
+        });
+    }
+
+    const counts: Record<RiskClass, number> = {
+        none: 0,
+        governance: 0,
+        auth: 0,
+        'trust-boundary': 0,
+    };
+    for (const r of rows) counts[r.risk] += 1;
+
+    const trustBoundary = counts['trust-boundary'];
+    const justified = trustBoundary >= TEETH_THRESHOLD;
+
+    const report = {
+        _doc:
+            'Shadow report for trust-boundary risk escalation. NOTHING IS GATED BY THIS FILE. It answers one ' +
+            'question: over recent history, how often did a merge land in a class the reference would have ' +
+            'escalated? The threshold below was pre-registered in the roadmap before this was first read.',
+        measured_at_sha: rows[0]?.sha ?? null,
+        merges_examined: rows.length,
+        pre_registered_teeth_threshold: TEETH_THRESHOLD,
+        counts,
+        trust_boundary_merges: trustBoundary,
+        decision: justified
+            ? `JUSTIFIED — ${trustBoundary} of ${rows.length} first-parent merges touched a trust-boundary path, ` +
+              `at or above the pre-registered threshold of ${TEETH_THRESHOLD}. A non-declinable escalation for ` +
+              'that class gets its own ADR and its own PR; it is deliberately NOT enabled by this report.'
+            : `NOT JUSTIFIED — ${trustBoundary} of ${rows.length} first-parent merges touched a trust-boundary ` +
+              `path, below the pre-registered threshold of ${TEETH_THRESHOLD}. The escalation stays unbuilt and ` +
+              'the authority model stays intact. This is the honest-null outcome, published as the answer.',
+        note:
+            'Classification is path-based and reproducible from the diff alone — no model judgement. Docs-only ' +
+            'changes are exempt by extension, except on kernel-rule paths, where a markdown file IS the ' +
+            'governed surface.',
+        escalating_merges: rows.filter((r) => r.risk !== 'none').slice(0, 40),
+    };
+
+    const abs = path.join(REPO, OUT_REL);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, JSON.stringify(report, null, 2) + '\n');
+
+    if (asJson) {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        return 0;
+    }
+
+    process.stdout.write(
+        `risk-escalation shadow · ${rows.length} first-parent merges examined\n` +
+            `    trust-boundary ${counts['trust-boundary']} · auth ${counts.auth} · ` +
+            `governance ${counts.governance} · none ${counts.none}\n` +
+            `    pre-registered threshold: ${TEETH_THRESHOLD} → ${justified ? 'JUSTIFIED' : 'NOT JUSTIFIED'}\n` +
+            `✅  wrote ${OUT_REL}\n`,
+    );
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    const a = process.argv[1];
+    if (!a) return false;
+    if (a === _FILE || pathToFileURL(path.resolve(a)).href === import.meta.url) return true;
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(_FILE);
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) process.exit(main());
+
+export { REPO, OUT_REL, TEETH_THRESHOLD };

package/src/scripts/roadmap_progress_hook.ts

@@ -40,6 +40,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { hardenedSpawnEnv } from "./_lib/spawn_env.js";
 import { log_dispatch_issue } from "./hooks/dispatch_issues.js";
+import { readHookStdin } from "./hooks/hook_stdin.js";
 
 export const REPLAY_ENV_VAR = "AGENT_CONFIG_REPLAY";
 
@@ -458,11 +459,7 @@ function parse_args(argv: string[]): ParsedArgs {
 }
 
 function _readStdin(): string {
-  try {
-    return fs.readFileSync(0, "utf-8");
-  } catch {
-    return "";
-  }
+  return readHookStdin();
 }
 
 export function main(argv?: string[]): number {
@@ -471,7 +468,13 @@ export function main(argv?: string[]): number {
   return run(_readStdin(), { consumer_root: root, verbose: args.verbose });
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }

package/src/scripts/schemas/agent-settings.schema.json

@@ -95,6 +95,29 @@
         }
       }
     },
+    "screenshots": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "identity_allowlist": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Consumed by the doc-screenshot-hygiene rule and screenshot-hygiene skill. Public identity tokens SAFE to show unredacted in a documentation screenshot — the maintainer's own public handles plus well-known fake-data tokens. Not a general fake-data dictionary and not identity-resolution: everything not listed is treated as sensitive by default, and a public handle co-located with a real name does not whitelist the real name. Default [] = nothing auto-allowed."
+        },
+        "forbid_terminal_capture": {
+          "type": "boolean",
+          "default": true,
+          "description": "Consumed by the doc-screenshot-hygiene rule. true (default) = terminal/CLI/IDE screenshots are forbidden (highest leak vector: absolute local paths, env tokens); use text code blocks with text redaction instead. false = allowed, still subject to the data-bearing human gate."
+        },
+        "data_bearing_gate": {
+          "type": "string",
+          "enum": ["on", "off"],
+          "default": "on",
+          "description": "Consumed by the doc-screenshot-hygiene rule. on (default) = 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 may embed with a stated justification. off = no data-bearing gate (the anonymization taxonomy still applies)."
+        }
+      }
+    },
     "code_style": {
       "type": "object",
       "additionalProperties": true,

package/src/scripts/schemas/license-policy.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "license-policy.schema.json",
+  "title": "license-policy.yaml — derived borrow-compatibility policy",
+  "description": "Contract for the S1.2 override surface (road-to-provenance-and-license-governance). `policy.{allow,conditional,deny}` are the closed compatibility-matrix source classes; the top-level `deny` array is a flattened, concrete-SPDX-id view of `policy.deny` — it is the shape `src/scripts/lint_provenance.ts`'s `resolveDenyPolicy()` already reads directly, so this file works as its override surface without any change on that side. `derived_from: manual` marks the file as a consumer override the detector must never silently overwrite (loosening any class below the derived verdict is rejected unless this is set). Enforced by the hand-rolled Draft-07 subset validator in validate_frontmatter.ts (`validate()`/`load_schema()`) — keep to its supported keyword set: type, required, properties, additionalProperties, items, minItems, pattern, minLength, maxLength, enum. No oneOf/const/patternProperties.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "derived_from", "detection", "target_class", "workspace_scope", "policy", "deny", "warnings", "derived_at"],
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "enum": [1]
+    },
+    "derived_from": {
+      "type": "string",
+      "enum": [
+        "MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "0BSD",
+        "MPL-2.0", "LGPL-2.1", "LGPL-3.0", "GPL-2.0", "GPL-3.0", "AGPL-3.0",
+        "SSPL-1.0", "Unlicense", "CC0-1.0",
+        "none-detected", "manual"
+      ],
+      "description": "The SPDX id the policy was derived from; 'none-detected' when no license source resolved; 'manual' when a consumer authored this file directly (never auto-overwritten, and the only value allowed to loosen policy below the derived verdict)."
+    },
+    "detection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "license_sha256"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "enum": ["license-file", "package-json", "composer-json", "none", "manual"]
+        },
+        "license_sha256": {
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA-256 hex digest of the detected LICENSE/LICENSE.md/COPYING file content; null when no such file exists. A later change to that file's content changes this hash, which is the invalidation trigger (re-derive on mismatch, escalate on downgrade)."
+        }
+      }
+    },
+    "target_class": {
+      "type": "string",
+      "enum": ["permissive", "weak-copyleft", "gpl-2.0", "gpl-3.0", "agpl", "none"]
+    },
+    "workspace_scope": {
+      "type": "string",
+      "enum": ["single", "homogeneous-multi"],
+      "description": "'single' when the repo declares no workspaces; 'homogeneous-multi' when workspaces are declared and none diverge from the root SPDX id. A divergent workspace escalates instead of writing this file at all (v1 scope-limiter — full per-workspace derivation is parked, see agents/roadmaps/later/road-to-per-workspace-license-policy.md)."
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "conditional", "deny"],
+      "description": "The closed compatibility-matrix verdict, keyed by SOURCE license class (not concrete SPDX id) — this is the roadmap S1.2 matrix output. The three arrays repeat the same item schema inline (not $ref — the hand-rolled Draft-07 subset validator this file is checked against does not resolve $ref).",
+      "properties": {
+        "allow": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["permissive", "public-domain", "weak-copyleft", "gpl-2.0", "gpl-3.0", "agpl", "sspl", "unknown"] }
+        },
+        "conditional": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["permissive", "public-domain", "weak-copyleft", "gpl-2.0", "gpl-3.0", "agpl", "sspl", "unknown"] }
+        },
+        "deny": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["permissive", "public-domain", "weak-copyleft", "gpl-2.0", "gpl-3.0", "agpl", "sspl", "unknown"] }
+        }
+      }
+    },
+    "deny": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "0BSD",
+          "MPL-2.0", "LGPL-2.1", "LGPL-3.0", "GPL-2.0", "GPL-3.0", "AGPL-3.0",
+          "SSPL-1.0", "Unlicense", "CC0-1.0"
+        ]
+      },
+      "description": "Flattened concrete-SPDX-id expansion of policy.deny — the shape lint_provenance.ts's resolveDenyPolicy() reads directly (top-level `deny: [<SPDX id>, ...]`). Never hand-edit; loosening this array without derived_from: manual is rejected by the merge step."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "derived_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}"
+    }
+  }
+}

package/src/scripts/schemas/provenance-borrow.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "provenance-borrow.schema.json",
+  "title": "Provenance ledger borrow record",
+  "description": "One line of provenance/borrows.jsonl — a single conscious external-code borrow. Contract: provenance/README.md. Enforced by src/scripts/lint_provenance.ts (hand-rolled validator, following the ticket.schema.json / ticket-manifest.schema.json precedent — this file documents the contract; it is not loaded at runtime).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["source_url", "license", "source_sha", "borrowed_at", "files", "transformation_note", "cleared_by"],
+  "properties": {
+    "source_url": {
+      "type": "string",
+      "pattern": "^(https?://\\S+|git@\\S+)$",
+      "description": "Where the borrowed code came from."
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX identifier of the source's license, or the literal 'unknown'. 'unknown' and any deny-class SPDX id (GPL/AGPL/SSPL family, under the default conservative policy) fail the linter — an unresolved license must never land in the ledger (principle #1: unknown escalates, never down-guessed)."
+    },
+    "source_sha": {
+      "type": "string",
+      "pattern": "^[0-9a-fA-F]{7,64}$",
+      "description": "Commit or blob SHA the borrow was taken from."
+    },
+    "borrowed_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO-8601 date (YYYY-MM-DD) the borrow landed."
+    },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Repo-relative paths touched by the borrow. Every path must exist and must not escape the repo root."
+    },
+    "transformation_note": {
+      "type": "string",
+      "minLength": 20,
+      "description": "What structurally changed. Rename-only phrasing is rejected — per principle #6, rename-only is not transformation; clearing requires structural re-derivation (the hit disappears on rescan) or an attributed ledger entry describing an actual structural change."
+    },
+    "cleared_by": {
+      "type": "string",
+      "enum": ["rescan", "ledger", "human"],
+      "description": "How the borrow was cleared: an automated rescan found the hit gone after rewrite, this ledger entry itself is the clearance, or a human reviewed and cleared it."
+    }
+  }
+}

package/src/scripts/schemas/reach-channels.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/reach-channels.schema.json",
+  "x-schemaVersion": "1.0.0",
+  "title": "Reach channel registry (src/config/reach-channels.yml)",
+  "$comment": "road-to-internet-reach Phase 1. Validated by src/scripts/check_reach_channels.ts (task check-reach-channels). SCOPE: standalone operator tooling — the registry answers 'which external backend does a reach recipe need, is it healthy, is its install command pinned'. The Phase 0 benchmark returned band: stop, so no channel here is routed, recommended, or agent-facing; nothing in this schema may be read as a routing table. Lifecycle vocabulary is REUSED from docs/contracts/provider-lifecycle.md — never fork a second enum. NO $ref / patternProperties / if-then anywhere: the validator is the Draft-07 subset exported by src/scripts/validate_frontmatter.ts (type, required, properties, additionalProperties:false, items, minItems, pattern, minLength, enum), so the install-string schema is inlined per platform key on purpose. DELIBERATELY ABSENT — a per-backend readiness field (road-to-gated-reach Phase 2 step 3): a backend can pass its `--version` probe and still be unable to retrieve (`yt-dlp` needs an external JavaScript runtime it must be configured to use), and that config-semantic check is implemented DOCTOR-SIDE, keyed on the backend id, in src/scripts/reach_doctor.ts § READINESS_REQUIREMENTS. Rationale: (1) it keeps this schema honest for the backends that have no such requirement — they declare nothing, instead of each omitting an optional key a reader must interpret as an absence; (2) the requirement is a property of the upstream tool, not of an operator's registry entry, so a registry that could omit it would hand back the very false green the check closes; (3) this file is UNTRUSTED input at runtime (reach_doctor.collect() validates it before spawning anything), and a field of the form 'check this config file' would widen that input's influence into which local path the doctor reads; (4) same precedent as the doctor's DEEP_PROBES table, which is code-side for the same reason. The rejected trade-off, stated: a field here would be visible to an operator reading the registry and would let a future backend with the same need be added in YAML rather than in code — that cost is accepted, because its failure mode is only extra maintainer work, whereas the alternative's failure mode is a wrong health verdict.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "channels"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "enum": ["reach-channels-v1"],
+      "description": "Registry format version. Bumped only on a breaking shape change."
+    },
+    "channels": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Channel list. A channel is a retrieval need (repository metadata, a feed, a page read); its `backends` are the ORDERED candidate tools that can satisfy it — first healthy candidate wins, so switching a backend is reordering this list, never editing code. Order carries meaning; channel order does not.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "description", "tier", "lifecycle", "override_key", "last_verified", "backends"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "description": "Channel slug — unique within the registry, lowercase."
+          },
+          "description": {
+            "type": "string",
+            "minLength": 10,
+            "description": "What the channel retrieves, in operator terms. Never a recommendation to use it."
+          },
+          "tier": {
+            "type": "string",
+            "enum": ["zero-config", "free-key", "login"],
+            "description": "Access cost to the operator: `zero-config` = no credential; `free-key` = a free token/API key the operator provisions; `login` = an authenticated account session. Documents setup effort only — it does not authorize credential harvesting of any kind."
+          },
+          "lifecycle": {
+            "type": "string",
+            "enum": ["experimental", "stable", "deprecated", "community"],
+            "description": "Reused verbatim from docs/contracts/provider-lifecycle.md § tiers. `experimental` = shape is right, no maintainer-verified real run; `stable` = maintainer-verified against a real run at least once; `deprecated` = successor declared, kept for one migration window (see removal_after / replacement); `community` = externally contributed, best-effort."
+          },
+          "override_key": {
+            "type": "string",
+            "pattern": "^reach\\.channels\\.[a-z0-9-]+\\.backend$",
+            "description": "Settings key by which an operator pins one backend for this channel, bypassing candidate order."
+          },
+          "last_verified": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+            "description": "ISO date the channel's backends and pins were last checked by a human. MUST be quoted in YAML — an unquoted date parses as a timestamp, not a string, and fails this type check loudly. Replaces a scheduled network CI job: staleness is checked offline against this field."
+          },
+          "removal_after": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+            "description": "Deprecation path, optional. Only meaningful with lifecycle `deprecated`: until this date the channel still probes with a warning; past it the doctor reports the channel as removed and the staleness lint flags its continued presence in this file."
+          },
+          "replacement": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "description": "Deprecation path, optional. Channel id that supersedes this one."
+          },
+          "credential_path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^\\n]+$",
+            "description": "Optional path to the credential file this channel's backend reads (`~` is expanded). The doctor ONLY stats it, to warn when it is group- or world-readable — it never opens it, never hashes it, and never reports its contents. Declared here because reach_doctor.ts enforces this schema at runtime and additionalProperties is false, so a field the code supports must be declared or no registry could use it. No shipped channel declares one."
+          },
+          "backends": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Ordered candidate tools. Each is an alternative that satisfies the channel on its own — not a pipeline stage.",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "probe_cmd", "probe_args", "install"],
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9_.-]*$",
+                  "description": "Backend slug — unique within its channel."
+                },
+                "probe_cmd": {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9_.-]*$",
+                  "description": "Bare executable name resolved on PATH. No path separators, no shell — the probe layer spawns it directly through hardenedSpawnEnv(). MUST equal this backend's `id`: a backend probes its own binary and nothing else, so a report row labelled `gh` can never be the health of `/bin/sh`. The equality is a cross-field rule this Draft-07 subset cannot express, so it is asserted by check_probe_cmd_binding() in src/scripts/check_reach_channels.ts and reported as rule `probe_cmd-binding`."
+                },
+                "probe_args": {
+                  "type": "array",
+                  "minItems": 1,
+                  "description": "Side-effect-free probe arguments only — a version / help / status query. The item pattern is an ALLOWLIST, not a denylist: an argument must be flag-shaped (`--version`, `-V`, `version`, `rate_limit`) and nothing else. A denylist was tried first and leaked — it admitted `cp`, `cat`, `-c`, `--data-binary` and every URL, so `probe_cmd: sh` + `probe_args: [\"-c\", \"<payload>\"]` passed the gate. What is actually true after the allowlist plus the probe_cmd===id binding plus runtime enforcement of this schema in reach_doctor.collect(): no path, no URL, no shell metacharacter, and no `-c`-style inline payload can reach the spawned child, and the child is the backend's own binary. This bounds the argument shape; it is not a proof that every upstream binary is side-effect-free under every flag — that judgement stays with the human who adds the backend.",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^-{0,2}[A-Za-z][A-Za-z0-9._-]*$"
+                  }
+                },
+                "install": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["default"],
+                  "description": "Human-performed install prescription per platform, selected by process.platform with `default` as the fallback. The package NEVER runs these: prescription-first, no auto-install, no piped remote installer. Platform keys are optional; `default` is not.",
+                  "properties": {
+                    "darwin": {
+                      "type": "string",
+                      "pattern": "^(?!.*(?:\\blatest\\b|\\bmain\\b|\\bmaster\\b|\\bHEAD\\b|archive/|\\.zip|\\.tgz|\\.tar\\.gz|\\.tar\\.xz))(?:os-baseline: [^\\n]{10,}|(?=.*(?:(?:==|@|=)v?[0-9]+(?:\\.[0-9]+)*|--version[ =]v?[0-9]+(?:\\.[0-9]+)*|\\sv?[0-9]+\\.[0-9]+\\.[0-9]+))[^\\n]+)$",
+                      "description": "See `default` for the pinning contract."
+                    },
+                    "linux": {
+                      "type": "string",
+                      "pattern": "^(?!.*(?:\\blatest\\b|\\bmain\\b|\\bmaster\\b|\\bHEAD\\b|archive/|\\.zip|\\.tgz|\\.tar\\.gz|\\.tar\\.xz))(?:os-baseline: [^\\n]{10,}|(?=.*(?:(?:==|@|=)v?[0-9]+(?:\\.[0-9]+)*|--version[ =]v?[0-9]+(?:\\.[0-9]+)*|\\sv?[0-9]+\\.[0-9]+\\.[0-9]+))[^\\n]+)$",
+                      "description": "See `default` for the pinning contract."
+                    },
+                    "win32": {
+                      "type": "string",
+                      "pattern": "^(?!.*(?:\\blatest\\b|\\bmain\\b|\\bmaster\\b|\\bHEAD\\b|archive/|\\.zip|\\.tgz|\\.tar\\.gz|\\.tar\\.xz))(?:os-baseline: [^\\n]{10,}|(?=.*(?:(?:==|@|=)v?[0-9]+(?:\\.[0-9]+)*|--version[ =]v?[0-9]+(?:\\.[0-9]+)*|\\sv?[0-9]+\\.[0-9]+\\.[0-9]+))[^\\n]+)$",
+                      "description": "See `default` for the pinning contract."
+                    },
+                    "default": {
+                      "type": "string",
+                      "pattern": "^(?!.*(?:\\blatest\\b|\\bmain\\b|\\bmaster\\b|\\bHEAD\\b|archive/|\\.zip|\\.tgz|\\.tar\\.gz|\\.tar\\.xz))(?:os-baseline: [^\\n]{10,}|(?=.*(?:(?:==|@|=)v?[0-9]+(?:\\.[0-9]+)*|--version[ =]v?[0-9]+(?:\\.[0-9]+)*|\\sv?[0-9]+\\.[0-9]+\\.[0-9]+))[^\\n]+)$",
+                      "description": "PINNING CONTRACT — an install prescription is EITHER (a) a command carrying an explicit version specifier (`name==1.2.3`, `name@22`, `--version 2.96.0`, or a whitespace-separated exact `1.2.3` triple), OR (b) an `os-baseline: <explanation>` sentinel for a tool the platform ships and no package install is prescribed for. Everything else FAILS: an unpinned command, and any moving-target source — `latest`, `main`, `master`, `HEAD`, `archive/…`, `.zip`, `.tgz`, `.tar.gz`, `.tar.xz`. This mechanizes the supply-chain intake floor (verify, pin, lock, never pipe a remote script to a shell) instead of asserting it."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}