@event4u/agent-config 9.7.0 → 9.8.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/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/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/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."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/scripts/schemas/reach-doctor-payload.schema.json

@@ -0,0 +1,220 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/reach-doctor-payload.schema.json",
+  "x-schemaVersion": "1.0.0",
+  "title": "reach:doctor --format json payload",
+  "$comment": "road-to-internet-reach Phase 2 step 5 — the falsifier for 'the JSON is clean'. Emitted by src/scripts/reach_doctor.ts; real output is validated against this file by tests/scripts/reach_doctor.test.ts (Ajv, the same validator tests/scripts/evals_schema.test.ts uses — full Draft-07, so nullable unions are expressed honestly here rather than being weakened for the frontmatter validator's Draft-07 subset). SCOPE: a health report over operator-chosen backends. It is NOT a routing table and carries no field that ranks, recommends, or routes a channel to an agent — the Phase 0 benchmark returned band: stop. Any future field implying agent-facing preference is a scope violation, not a feature.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "platform",
+    "registry",
+    "deep",
+    "channels",
+    "last_verified_suggestions"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Payload format version, mirroring the hooks:doctor convention. Bumped only on a breaking payload shape change."
+    },
+    "platform": {
+      "type": "string",
+      "minLength": 1,
+      "description": "process.platform of the reporting machine — the key by which each install prescription was selected (with `default` as the fallback)."
+    },
+    "registry": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Registry file actually read, repo-relative when it lives inside the repo. Present so a report is never ambiguous about its own input."
+    },
+    "deep": {
+      "type": "boolean",
+      "description": "True only when --deep ran, i.e. when real network requests were made. False means the run touched no network at all."
+    },
+    "channels": {
+      "type": "array",
+      "description": "One row per admitted channel, in registry order. A malformed channel appears as its own `error` row rather than removing the report — per-channel isolation is part of the contract.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "status",
+          "active_backend",
+          "tier",
+          "lifecycle",
+          "last_verified",
+          "fix",
+          "warnings",
+          "credential",
+          "backends"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Channel id from the registry, or `(channel #N)` when the entry was too malformed to carry one."
+          },
+          "status": {
+            "type": "string",
+            "enum": ["ok", "missing", "broken", "timeout", "error", "removed", "not-ready"],
+            "description": "The five probe states plus `removed` and `not-ready`. `ok` = some backend is USABLE (probes ok AND, if it declares a readiness requirement, that requirement is confirmed satisfied); `not-ready` = a candidate is installed and answering its probe while its readiness requirement is unsatisfied or unconfirmed — the 'installed, unverified' ceiling, deliberately NOT reported as ok because that was the false green the readiness layer exists to close; otherwise the FIRST candidate's probe verdict (the one whose install fix the operator runs); `removed` = past removal_after, never probed. Which of unsatisfied-vs-unconfirmed applies is carried precisely by backends[].readiness.status."
+          },
+          "active_backend": {
+            "type": ["string", "null"],
+            "description": "First backend in the ordered candidate list that probes ok; null when none does. Candidate order is the switch — this field reports it, it does not choose."
+          },
+          "tier": {
+            "type": "string",
+            "description": "Access cost to the operator (zero-config | free-key | login), echoed from the registry. Documents setup effort only."
+          },
+          "lifecycle": {
+            "type": "string",
+            "description": "Registry lifecycle value, reused verbatim from docs/contracts/provider-lifecycle.md."
+          },
+          "last_verified": {
+            "type": "string",
+            "description": "ISO date a human last checked this channel, echoed from the registry."
+          },
+          "fix": {
+            "type": ["string", "null"],
+            "description": "The exact PINNED install command for this platform, echoed verbatim from the registry, and only when the first candidate is missing or broken. Never composed, never invented, never executed by the package — a human reads and runs it."
+          },
+          "warnings": {
+            "type": "array",
+            "description": "Operator-facing warnings: deprecation, removal, credential permissions. Never carries a credential's contents or any fingerprint of it.",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "credential": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "required": ["path", "present", "mode", "group_or_world_readable", "checked"],
+            "description": "Permission metadata for a declared credential file, or null when the channel declares none (the shipped registry declares none — see reach_doctor.ts § inspectCredential). Path + mode ONLY: contents and secret fingerprints are deliberately absent, because a fingerprint is a confirmation oracle rather than a redaction.",
+            "properties": {
+              "path": { "type": "string", "minLength": 1, "description": "Resolved credential path (~ expanded) — the path a chmod would target." },
+              "present": { "type": "boolean", "description": "Whether the declared file exists." },
+              "mode": {
+                "type": ["string", "null"],
+                "pattern": "^0[0-7]{3}$",
+                "description": "Octal permission bits, e.g. `0600`. Null when absent or unchecked."
+              },
+              "group_or_world_readable": {
+                "type": "boolean",
+                "description": "True when the mode grants group- or other-read (0o044) — the silent exposure this check exists to surface."
+              },
+              "checked": {
+                "type": "boolean",
+                "description": "False on win32, where POSIX mode bits are not meaningful; the check is skipped rather than asserted with a different meaning."
+              }
+            }
+          },
+          "backends": {
+            "type": "array",
+            "description": "Per-candidate probe results in registry order. Empty for a `removed` channel (not probed) and for an `error` row (not readable).",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "probe_cmd", "status", "path", "exit_code", "diagnostic", "fix", "deep"],
+              "properties": {
+                "id": { "type": "string", "minLength": 1, "description": "Backend slug within its channel." },
+                "probe_cmd": { "type": "string", "minLength": 1, "description": "Executable probed on PATH." },
+                "status": {
+                  "type": "string",
+                  "enum": ["ok", "missing", "broken", "timeout", "error"],
+                  "description": "tool_probe's five-state taxonomy, unchanged."
+                },
+                "path": { "type": ["string", "null"], "description": "Resolved binary path, or null when resolution failed." },
+                "exit_code": { "type": ["integer", "null"], "description": "Probe exit code, or null when the child never reported one." },
+                "diagnostic": { "type": "string", "minLength": 1, "description": "Short, OUTPUT-FREE explanation. Probe stdio is ignored, so fetched content and credentials can never reach a report." },
+                "fix": { "type": ["string", "null"], "description": "Platform-selected pinned prescription for this backend; populated for missing/broken only." },
+                "readiness": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "kind",
+                    "status",
+                    "config_path",
+                    "config_present",
+                    "config_flag",
+                    "runtimes",
+                    "version",
+                    "fix",
+                    "detail"
+                  ],
+                  "description": "Config-semantic readiness verdict — the answer to 'installed, or actually able to retrieve?'. PRESENT ONLY for a backend that declares a readiness requirement (declared doctor-side in reach_doctor.ts § READINESS_REQUIREMENTS, not in the registry — see the $comment of reach-channels.schema.json for why). Its ABSENCE, rather than a null value, is how a backend with no such requirement is expressed: the other channels' backend rows gain no field at all. Read-only and local: a config file is read bounded and symlink-refusing, PATH is consulted, and no network request is made in either mode.",
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "enum": ["js-runtime"],
+                      "description": "Which readiness requirement this row settles. One kind today: an external JavaScript runtime the extractor must be configured to use."
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": ["ready", "not-ready", "unknown"],
+                      "description": "`ready` = confirmed usable; `not-ready` = confirmed unusable as configured; `unknown` = deliberately not settled (the backend is not installed, or its version could not be parsed so flag support cannot be confirmed). `unknown` never reads as ok — an 'installed, unverified' ceiling is preferred to a false green."
+                    },
+                    "config_path": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "The config file path resolved THE WAY THE UPSTREAM TOOL RESOLVES IT ($XDG_CONFIG_HOME/yt-dlp/config, else ~/.config/yt-dlp/config). Reported so the doctor and the operator can never be reading different files — the specific confusion this layer exists to prevent. The emitted fix targets this same path."
+                    },
+                    "config_present": {
+                      "type": "boolean",
+                      "description": "True only when that path is a real, readable regular file. False also covers a REFUSED read (a symlink, a directory) — the reason is named in `detail`, so a refusal is never silent."
+                    },
+                    "config_flag": {
+                      "type": "boolean",
+                      "description": "True when the literal flag was found in the config (any runtime value — presence of the flag is the signal). The file's contents never appear anywhere in this payload; only this boolean is extracted."
+                    },
+                    "runtimes": {
+                      "type": "array",
+                      "description": "External JavaScript runtimes found on PATH, in the order checked (deno first — the extractor enables it by default, so finding it settles the question with no config).",
+                      "items": { "type": "string", "minLength": 1 }
+                    },
+                    "version": {
+                      "type": ["string", "null"],
+                      "description": "The backend version PARSED to a YYYY.M.D release, or null when it could not be parsed (which is reported as `unknown`, never as new-enough). Raw `--version` output never reaches this payload — only this re-rendered numeric form, so child output cannot travel into a report."
+                    },
+                    "fix": {
+                      "type": ["string", "null"],
+                      "description": "An IDEMPOTENT, OS-specific remedy for the operator to run: create the config dir if needed and append the flag only when it is not already present. Printed, never executed. Null when there is nothing to fix, when the remedy is an upgrade rather than a config edit (a build predating the flag would reject it), or when readiness could not be settled."
+                    },
+                    "detail": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "One-line explanation of the verdict, including any refusal reason. Carries no config contents and no raw child output."
+                    }
+                  }
+                },
+                "deep": {
+                  "type": ["object", "null"],
+                  "additionalProperties": false,
+                  "required": ["status", "endpoint", "exit_code", "detail"],
+                  "description": "Result of the one real read-only request made under --deep; null in the default shallow mode (no network).",
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "enum": ["ok", "failed", "skipped", "not-declared"],
+                      "description": "`not-declared` = no deep endpoint is declared for this backend, and none is invented for it."
+                    },
+                    "endpoint": { "type": ["string", "null"], "description": "The endpoint actually contacted; null when no deep probe is declared." },
+                    "exit_code": { "type": ["integer", "null"], "description": "Exit code of the deep request." },
+                    "detail": { "type": "string", "minLength": 1, "description": "One-line explanation of the deep verdict." }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "last_verified_suggestions": {
+      "type": "array",
+      "description": "--deep only (empty otherwise): the `last_verified` lines an operator MAY choose to commit. The command prints them and writes nothing — staleness stays a human-attested field, not a machine-refreshed one.",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}

package/src/scripts/schemas/rule.schema.json

@@ -121,6 +121,16 @@
       "default": "active",
       "description": "ADR-013 lifecycle state."
     },
+    "enforced_by": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^(hook:[a-z0-9_-]+|validator:[A-Za-z0-9_./-]+|test:[A-Za-z0-9_./-]+|observer:[a-z0-9 _-]+|none)$"
+      },
+      "description": "What mechanically enforces this rule. `validator:<script>` and `test:<path>` must resolve on disk AND be wired into a taskfile, workflow, or the hook manifest — a script that exists but runs nowhere resolves to unwired, not covered. `hook:<name>` must be registered in hook_manifest.yaml with fail_closed: true; a hook that never blocks is `observer:`, not `validator:`. `none` is legal and counted — an honest gap beats a false claim. Resolved, not trusted, by check_enforcement_coverage.ts."
+    },
     "trust": {
       "type": "object",
       "additionalProperties": false,