@event4u/agent-config 9.7.0 → 9.9.0

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

@@ -115,12 +115,32 @@
       "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
       "description": "ADR-013 pack ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/packs.yml."
     },
+    "roles": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["developer", "reviewer", "tester", "po", "incident", "planner"]
+      },
+      "description": "Subagent role-mode scoping axis (road-to-lean-agent-init Phase 4), parallel to `workspaces`/`packs`. Closed vocabulary — the six RoleMode ids from src/scripts/_lib/subagent_spawn.ts. Absent/empty = untagged, fails safe (ships to every role). Kernel rules (type: always) always ship regardless of this field. Enforced via this schema's `enum` (not a src/config/discovery/*.yml + lint_artefact_frontmatter.ts cross-check like workspaces/packs) because lint_artefact_frontmatter.ts still scans the retired legacy rules tree (0 artefacts post-ADR-051 src/ migration) and is a no-op for src/rules/*.md today; validate_frontmatter.ts (the active src/rules linter) enforces this enum instead."
+    },
     "lifecycle": {
       "type": "string",
       "enum": ["active", "deprecated", "experimental", "archived"],
       "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,

package/src/scripts/self_review_gate.test.ts

@@ -1,11 +1,19 @@
-import { describe, expect, it } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
 
 import {
     LARGE_DIFF_LINES,
+    buildPlan,
     classifyBlocking,
+    detectReleaseVersion,
     escalationReasons,
     gateVerdict,
     isReviewablePath,
+    pickPreviousTag,
     renderReview,
     type Finding,
 } from './self_review_gate.js';
@@ -122,3 +130,167 @@ describe('renderReview — escalation banner', () => {
         expect(out).toContain('Escalation warranted');
     });
 });
+
+// ── Release-PR review mode (road-to-feedback-9.2.0-followups Phase 3) ──
+// See docs/design/release-pr-review-mode.md — anchored to the PR #957
+// false-advisory case (release features reading as "not in the diff").
+
+describe('detectReleaseVersion', () => {
+    const changelogAdd = (v: string) =>
+        `+## [${v}](https://github.com/event4u-app/agent-config/compare/9.1.0...${v}) (2026-07-14)`;
+    const packageAdd = (v: string) => `+    "version": "${v}",`;
+
+    it('detects a release PR when the changelog heading and the package.json bump agree', () => {
+        const patch = [
+            'diff --git a/CHANGELOG.md b/CHANGELOG.md',
+            '@@ -14,6 +14,8 @@',
+            ' ## [Unreleased]',
+            '+',
+            changelogAdd('9.2.0'),
+            'diff --git a/package.json b/package.json',
+            '@@ -1,6 +1,6 @@',
+            '-    "version": "9.1.0",',
+            packageAdd('9.2.0'),
+        ].join('\n');
+        expect(detectReleaseVersion(patch)).toBe('9.2.0');
+    });
+
+    it('is NOT a release PR when only the changelog heading changed (no version bump)', () => {
+        expect(detectReleaseVersion(changelogAdd('9.2.0'))).toBeNull();
+    });
+
+    it('is NOT a release PR when only package.json bumped (no changelog heading)', () => {
+        expect(detectReleaseVersion(packageAdd('9.2.0'))).toBeNull();
+    });
+
+    it('is NOT a release PR on a normal feature-PR patch (neither signal present)', () => {
+        const patch = ['+export function foo() {}', '-export function bar() {}'].join('\n');
+        expect(detectReleaseVersion(patch)).toBeNull();
+    });
+
+    it('refuses to guess when the changelog and package.json versions disagree', () => {
+        const patch = [changelogAdd('9.2.0'), packageAdd('9.3.0')].join('\n');
+        expect(detectReleaseVersion(patch)).toBeNull();
+    });
+
+    it('ignores removed lines (the old version) and reads only the added one', () => {
+        const patch = ['-    "version": "9.1.0",', packageAdd('9.2.0'), changelogAdd('9.2.0')].join('\n');
+        expect(detectReleaseVersion(patch)).toBe('9.2.0');
+    });
+});
+
+describe('pickPreviousTag', () => {
+    it('picks the highest tag strictly below the release version', () => {
+        expect(pickPreviousTag('9.2.0', ['9.0.0', '9.1.0', '9.2.0'])).toBe('9.1.0');
+    });
+    it('handles a v-prefixed tag naming convention', () => {
+        expect(pickPreviousTag('9.2.0', ['v9.0.0', 'v9.1.0'])).toBe('v9.1.0');
+    });
+    it('returns null when no tag is strictly below the version', () => {
+        expect(pickPreviousTag('9.2.0', ['9.2.0', '9.3.0'])).toBeNull();
+        expect(pickPreviousTag('9.2.0', [])).toBeNull();
+    });
+    it('ignores non-semver tags (branch-backup names etc.) instead of crashing', () => {
+        expect(
+            pickPreviousTag('9.2.0', [
+                'backup/pre-rebase-augment-limit-fit',
+                '9.1.0',
+                'local-squashed-tip-2026-05-18',
+            ]),
+        ).toBe('9.1.0');
+    });
+});
+
+describe('buildPlan — release-PR shape (PR #957 reproduction)', () => {
+    function git(root: string, ...args: string[]) {
+        return spawnSync('git', args, {
+            cwd: root,
+            encoding: 'utf8',
+            env: {
+                ...process.env,
+                GIT_AUTHOR_NAME: 'T',
+                GIT_AUTHOR_EMAIL: 't@e.test',
+                GIT_COMMITTER_NAME: 'T',
+                GIT_COMMITTER_EMAIL: 't@e.test',
+            },
+        });
+    }
+    function write(root: string, rel: string, content: string): void {
+        const full = path.join(root, rel);
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, content, 'utf-8');
+    }
+    function mkTmp(): string {
+        return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'srg-')));
+    }
+
+    let root: string | undefined;
+    afterEach(() => {
+        if (root) fs.rmSync(root, { recursive: true, force: true });
+        root = undefined;
+    });
+
+    it('release mode sees the pre-cut feature file; the packaging diff alone does not (PR #957 shape)', () => {
+        root = mkTmp();
+        git(root, 'init', '-q', '-b', 'main');
+        write(root, 'package.json', '{\n  "name": "x",\n  "version": "9.0.0"\n}\n');
+        write(root, 'CHANGELOG.md', '# Changelog\n\n## [Unreleased]\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'baseline');
+        git(root, 'tag', '9.1.0'); // the previous release tag
+
+        // The feature merges into main BEFORE the release cut — the PR #957 shape.
+        write(root, 'feature.txt', 'new cross-source-consistency rule content\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'feat: cross-source-consistency');
+
+        // Release branch cut from main's current tip — no divergence yet, so
+        // main...release-branch only shows the release-cut commit below.
+        git(root, 'checkout', '-q', '-b', 'release-branch');
+        write(
+            root,
+            'CHANGELOG.md',
+            '# Changelog\n\n## [Unreleased]\n\n' +
+                '## [9.2.0](https://github.com/event4u-app/agent-config/compare/9.1.0...9.2.0) (2026-07-14)\n',
+        );
+        write(root, 'package.json', '{\n  "name": "x",\n  "version": "9.2.0"\n}\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'chore(release): 9.2.0');
+
+        const plan = buildPlan('main', root);
+
+        expect(plan.release?.version).toBe('9.2.0');
+        expect(plan.release?.previousTag).toBe('9.1.0');
+        // The packaging diff (main...HEAD) alone does NOT show the pre-cut
+        // feature — the exact false-advisory shape PR #957 hit.
+        expect(plan.release?.packagingFiles).not.toContain('feature.txt');
+        expect(plan.release?.packagingFiles).toEqual(
+            expect.arrayContaining(['CHANGELOG.md', 'package.json']),
+        );
+        // Release mode's actual analysis range (previousTag...HEAD) DOES
+        // include it — this is what stops "feature not in diff" recurring.
+        expect(plan.files).toContain('feature.txt');
+        expect(plan.analysisBase).toBe('9.1.0');
+    });
+
+    it('a normal feature PR (no changelog/version bump) uses the unchanged base', () => {
+        root = mkTmp();
+        git(root, 'init', '-q', '-b', 'main');
+        write(root, 'package.json', '{\n  "name": "x",\n  "version": "9.1.0"\n}\n');
+        write(root, 'CHANGELOG.md', '# Changelog\n\n## [Unreleased]\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'baseline');
+        git(root, 'tag', '9.1.0');
+
+        git(root, 'checkout', '-q', '-b', 'feature-branch');
+        write(root, 'feature.txt', 'some feature\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'feat: add feature');
+
+        const plan = buildPlan('main', root);
+
+        expect(plan.release).toBeUndefined();
+        expect(plan.analysisBase).toBe('main');
+        expect(plan.files).toContain('feature.txt');
+    });
+});