@event4u/agent-config 9.0.0 → 9.1.0

package/src/scripts/lint_agents_layout.ts

@@ -42,7 +42,11 @@ const ALLOWED_FLAT_FILES: ReadonlySet<string> = new Set([
     // separate violation caught by check_tracked_but_ignored.ts.
     '.ai-video.xml',       // operator AI-video config; gitignored per .gitignore § AI Video
     'installed-tools.lock', // installer per-user inventory; gitignored per ADR-020
-    '.event4u-bridge.yml',  // consumer bridge marker; ADR-020 (should only be in consumers)
+    // Retired marker (ADR-020 amendment 2026-07-13). No longer written; the
+    // global root resolves from `~/.event4u/agent-config`. Kept tolerated so a
+    // legacy leftover in a not-yet-reinstalled consumer is not flagged as a
+    // violation — the next install deletes it.
+    '.event4u-bridge.yml',
 ]);
 
 // All directories allowed at the agents/ root in the SOURCE REPO.
@@ -75,6 +79,8 @@ const ALLOWED_SOURCE_DIRS: ReadonlySet<string> = new Set([
 const CONSUMER_EXPECTED_ENTRIES: ReadonlySet<string> = new Set([
     // Required consumer entries
     'overrides',
+    // Retired marker (ADR-020 amendment 2026-07-13) — no longer written, but
+    // kept in the tolerated set so a legacy leftover does not warn.
     '.event4u-bridge.yml',
     '.gitkeep',
     // Optional but legitimate consumer entries (will not trigger warnings)
@@ -93,9 +99,9 @@ const CONSUMER_EXPECTED_ENTRIES: ReadonlySet<string> = new Set([
 const MIGRATE_HINT =
     'Run `npx @event4u/agent-config migrate` to sweep legacy project-scope ' +
     'artefacts in one pass. The unified `migrate` command (see ' +
-    '`docs/contracts/migrate-command.md`) leaves `agents/overrides/` + ' +
-    '`agents/.event4u-bridge.yml` as the only consumer-side files; the ' +
-    'wizard recreates fresh config on `agent-config setup`.';
+    '`docs/contracts/migrate-command.md`) leaves `agents/overrides/` as the ' +
+    'only consumer-side agent surface; the wizard recreates fresh config on ' +
+    '`agent-config setup`.';
 
 function _isDir(p: string): boolean {
     try {

package/src/scripts/lint_breaking_changes_index.ts

@@ -0,0 +1,303 @@
+#!/usr/bin/env tsx
+/**
+ * BREAKING_CHANGES.md ↔ CHANGELOG sync linter (road-to-feedback-9.0 P1.4).
+ *
+ * `BREAKING_CHANGES.md` is the discoverable index of consumer-facing breaking
+ * changes, one per major (`X.0.0`). When a diff ships a NEW breaking entry in a
+ * RELEASED CHANGELOG section it must also touch the index in the same change,
+ * or the index silently rots behind the changelog.
+ *
+ * TRIGGER: a git diff (working tree vs `origin/main` — staged + unstaged) that
+ * ADDS a `### BREAKING` / `### BREAKING CHANGES` subheading under a RELEASED
+ * major section (`## [N.0.0]`) in `CHANGELOG.md`, where the same major had no
+ * such subheading at the base ref (a wholly-new released section counts). A
+ * breaking note under `## [Unreleased]` is WIP and never trips the gate.
+ *
+ * REQUIREMENT: when triggered, the same diff must also modify
+ * `BREAKING_CHANGES.md`.
+ *
+ * Escape hatch (mirrors `check_structural_breaking.ts`'s `ci-override` trailer):
+ * an own-line trailer `ci-override: breaking-index-override` (the bare token
+ * `breaking-index-override` on its own line is also accepted) in any commit
+ * body in the range, or the env var `BREAKING_INDEX_OVERRIDE=1`, clears the
+ * gate for an intentional index-deferred change.
+ *
+ * CLI: exit 0 clean/cleared, 1 violation (or selftest failure), 2 usage error.
+ * `--selftest` proves the rule on inline string fixtures (no git needed).
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+// src/scripts/lint_breaking_changes_index.ts → two levels up is the repo root.
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const BASE_REF = 'origin/main';
+const CHANGELOG_REL = 'CHANGELOG.md';
+const INDEX_REL = 'BREAKING_CHANGES.md';
+
+// A RELEASED major section heading: `## [N.0.0]…` (minor + patch both 0).
+// `## [Unreleased]` never matches, so WIP breaking notes are out of scope.
+const RELEASED_MAJOR_HEADING_RE = /^## \[(?<version>\d+\.0\.0)\]/;
+// Any other level-1/2 heading closes the current section.
+const SECTION_BOUNDARY_RE = /^##? /;
+// A breaking subheading as emitted by release-please: `### BREAKING` or
+// `### BREAKING CHANGES` (all-caps). Mixed-case `### Breaking changes` under
+// Unreleased is intentionally NOT matched.
+const BREAKING_SUBHEADING_RE = /^### BREAKING\b/;
+// Override trailer — same shape as check_structural_breaking's `ci-override:`
+// mechanism (own line, not an inline mention); the bare token is also accepted.
+const OVERRIDE_RE = /^(?:ci-override:\s*)?breaking-index-override\s*$/m;
+
+/**
+ * Return the set of RELEASED major versions whose CHANGELOG section contains a
+ * `### BREAKING` subheading.
+ */
+export function released_breaking_majors(lines: readonly string[]): Set<string> {
+    const found = new Set<string>();
+    for (let i = 0; i < lines.length; i++) {
+        const m = RELEASED_MAJOR_HEADING_RE.exec(lines[i]!);
+        if (!m) {
+            continue;
+        }
+        const version = m.groups!['version']!;
+        // Section body: heading line down to (exclusive) the next boundary.
+        let end = lines.length;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (SECTION_BOUNDARY_RE.test(lines[j]!)) {
+                end = j;
+                break;
+            }
+        }
+        if (lines.slice(i + 1, end).some((ln) => BREAKING_SUBHEADING_RE.test(ln))) {
+            found.add(version);
+        }
+    }
+    return found;
+}
+
+/**
+ * Core check. Returns the sorted list of RELEASED major versions that GAINED a
+ * `### BREAKING` subheading between `oldLines` and `newLines` — the versions
+ * that should be reflected in `BREAKING_CHANGES.md`.
+ */
+export function added_released_breaking_majors(
+    oldLines: readonly string[],
+    newLines: readonly string[],
+): string[] {
+    const before = released_breaking_majors(oldLines);
+    const after = released_breaking_majors(newLines);
+    const added = [...after].filter((v) => !before.has(v));
+    added.sort();
+    return added;
+}
+
+export interface CheckResult {
+    readonly addedMajors: readonly string[];
+    readonly indexChanged: boolean;
+    readonly overridden: boolean;
+    readonly violation: boolean;
+}
+
+/** Pure decision: violation iff a released BREAKING was added, the index was not touched, and no override cleared it. */
+export function evaluate(
+    oldLines: readonly string[],
+    newLines: readonly string[],
+    indexChanged: boolean,
+    overridden: boolean,
+): CheckResult {
+    const addedMajors = added_released_breaking_majors(oldLines, newLines);
+    const violation = addedMajors.length > 0 && !indexChanged && !overridden;
+    return { addedMajors, indexChanged, overridden, violation };
+}
+
+// ─── git helpers (CLI only) ──────────────────────────────────────────────────
+
+function _git(...args: string[]): string {
+    const proc = spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf-8' });
+    return (proc.stdout as string | null) ?? '';
+}
+
+function _base(): string {
+    const mb = _git('merge-base', BASE_REF, 'HEAD').trim();
+    return mb || BASE_REF;
+}
+
+function _splitlines(s: string): string[] {
+    return s.split(/\r\n|\r|\n/);
+}
+
+/** File contents at a ref, or '' when the path did not exist there. */
+function _blob_at(ref: string, rel: string): string {
+    return _git('show', `${ref}:${rel}`);
+}
+
+// ─── selftest fixtures ─────────────────────────────────────────────────────────
+
+function _changelog(sections: string): string[] {
+    return ('# Changelog\n\n## [Unreleased]\n\n' + sections).split('\n');
+}
+
+const _RELEASED_WITH_BREAKING =
+    '## [9.0.0](https://example/compare/8.13.0...9.0.0) (2026-07-13)\n\n' +
+    '### BREAKING CHANGES\n\n* installer path changed ([abc1234](https://example))\n\n';
+const _RELEASED_NO_BREAKING =
+    '## [9.0.0](https://example/compare/8.13.0...9.0.0) (2026-07-13)\n\n' +
+    '### Features\n\n* a feature ([abc1234](https://example))\n\n';
+
+function run_selftest(): number {
+    let failed = 0;
+    const assert = (label: string, ok: boolean): void => {
+        process.stdout.write(`${ok ? '✅' : '❌'}  selftest: ${label}\n`);
+        if (!ok) failed += 1;
+    };
+
+    const oldNoBreaking = _changelog(_RELEASED_NO_BREAKING);
+    const newWithBreaking = _changelog(_RELEASED_WITH_BREAKING);
+
+    // 1. Released BREAKING added, index NOT changed, no override → VIOLATION.
+    const red = evaluate(oldNoBreaking, newWithBreaking, false, false);
+    assert(
+        'released BREAKING added without index change FAILS',
+        red.violation && red.addedMajors.length === 1 && red.addedMajors[0] === '9.0.0',
+    );
+
+    // 2. Same, but the index WAS changed → passes.
+    const greenIdx = evaluate(oldNoBreaking, newWithBreaking, true, false);
+    assert('index change clears the gate', !greenIdx.violation && greenIdx.addedMajors.length === 1);
+
+    // 3. Same, index untouched, but override present → passes.
+    const greenOverride = evaluate(oldNoBreaking, newWithBreaking, false, true);
+    assert('override clears the gate', !greenOverride.violation);
+
+    // 4. BREAKING only under [Unreleased] (WIP) → never trips.
+    const oldEmpty = _changelog('');
+    const newUnreleasedBreaking = (
+        '# Changelog\n\n## [Unreleased]\n\n### BREAKING CHANGES\n\n* wip break ([abc1234](https://example))\n\n'
+    ).split('\n');
+    const wip = evaluate(oldEmpty, newUnreleasedBreaking, false, false);
+    assert('Unreleased BREAKING does not trip the gate', !wip.violation && wip.addedMajors.length === 0);
+
+    // 5. A released BREAKING already present at base (no new addition) → clean.
+    const noop = evaluate(newWithBreaking, newWithBreaking, false, false);
+    assert('pre-existing released BREAKING is not re-flagged', !noop.violation);
+
+    if (failed > 0) {
+        process.stderr.write(`❌  selftest: ${failed} fixture(s) failed.\n`);
+        return 1;
+    }
+    process.stdout.write('✅  selftest: all fixtures behave as specified.\n');
+    return 0;
+}
+
+// ─── CLI ───────────────────────────────────────────────────────────────────────
+
+interface ParsedArgs {
+    selftest: boolean;
+    quiet: boolean;
+}
+
+function _argparse_error(message: string): never {
+    process.stderr.write(`lint_breaking_changes_index: error: ${message}\n`);
+    process.exit(2);
+}
+
+function parse_args(argv: readonly string[]): ParsedArgs {
+    const args: ParsedArgs = { selftest: false, quiet: false };
+    for (const arg of argv) {
+        if (arg === '--selftest') {
+            args.selftest = true;
+        } else if (arg === '--quiet') {
+            args.quiet = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write('usage: lint_breaking_changes_index [-h] [--selftest] [--quiet]\n');
+            process.exit(0);
+        } else {
+            _argparse_error(`unrecognized arguments: ${arg}`);
+        }
+    }
+    return args;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+    if (args.selftest) {
+        return run_selftest();
+    }
+
+    const base = _base();
+    if (!base) {
+        return 0; // no trunk to diff against (e.g. shallow CI) → no-op
+    }
+
+    const oldLines = _splitlines(_blob_at(base, CHANGELOG_REL));
+    const changelogPath = path.join(REPO_ROOT, CHANGELOG_REL);
+    const newLines = fs.existsSync(changelogPath)
+        ? _splitlines(fs.readFileSync(changelogPath, 'utf-8'))
+        : [];
+
+    // Was BREAKING_CHANGES.md touched (staged or unstaged) vs the base?
+    const indexChanged = _git('diff', '--name-only', base, '--', INDEX_REL).trim() !== '';
+
+    const log = _git('log', '--format=%B', `${base}..HEAD`);
+    const overridden = OVERRIDE_RE.test(log) || process.env['BREAKING_INDEX_OVERRIDE'] === '1';
+
+    const result = evaluate(oldLines, newLines, indexChanged, overridden);
+
+    if (!result.violation) {
+        if (!args.quiet) {
+            if (result.addedMajors.length > 0) {
+                const why = result.overridden ? 'override' : `${INDEX_REL} updated`;
+                process.stdout.write(
+                    `✅ lint-breaking-changes-index: ${result.addedMajors.length} released ` +
+                        `BREAKING addition(s), cleared by ${why}\n`,
+                );
+            } else {
+                process.stdout.write(
+                    '✅ lint-breaking-changes-index: no new released BREAKING entries vs trunk\n',
+                );
+            }
+        }
+        return 0;
+    }
+
+    process.stderr.write(
+        `❌ lint-breaking-changes-index: released BREAKING entr(y/ies) added to ${CHANGELOG_REL} ` +
+            `without a matching ${INDEX_REL} change:\n`,
+    );
+    for (const v of result.addedMajors) {
+        process.stderr.write(`   - ## [${v}] gained a ### BREAKING section\n`);
+    }
+    process.stderr.write(
+        `\nWhen a released major ships a breaking change, ${INDEX_REL} — the discoverable\n` +
+            `index (one entry per major) — must be updated in the same change. Resolve by:\n` +
+            `  • adding the matching entry to ${INDEX_REL}, or\n` +
+            '  • adding an own-line `ci-override: breaking-index-override` trailer to a commit\n' +
+            '    body (or setting BREAKING_INDEX_OVERRIDE=1) for an intentionally deferred index.\n',
+    );
+    return 1;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { main, run_selftest, RELEASED_MAJOR_HEADING_RE, BREAKING_SUBHEADING_RE, OVERRIDE_RE };

package/src/scripts/mcp_server/tools.ts

@@ -775,9 +775,7 @@ async function _runDoctorLeg(consumerRoot: string): Promise<{
         let tagDrift: Record<string, unknown>[] = [];
         let checks: Record<string, unknown>[];
         if (manifest === null) {
-            const bridgePresent = fs.existsSync(
-                path.join(projectRoot, doctor.BRIDGE_MARKER_RELATIVE),
-            );
+            const bridgePresent = doctor._is_global_only_consumer(projectRoot);
             checks = doctor._run_checks_no_manifest(projectRoot, bridgePresent, null);
         } else {
             const [records, known] = doctor._collect_manifest_entries(projectRoot, manifest);

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

@@ -106,6 +106,23 @@
           "description": "Controls whether skills marked token_budget_class: rich may load in full (exempt from telegraph-speak and thin-projector trimming). on = allowed (default); off = fall back to standard condensed behavior; ask = surface an estimated token delta (tokens, not dollars) and ask the user once per session before loading."
         }
       }
+    },
+    "commands": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "create_pr": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "detail_level": {
+              "type": "string",
+              "enum": ["min", "med", "max"],
+              "description": "Verbosity tier for the generated PR description body, consumed by /create-pr. min (default) = title + 2-3 sentence what/why/impact + linked ticket; med = min + grouped changes + tests note; max = med + how-to-test + edge cases + reviewer guidance. Critical info (breaking changes, migrations, security, rollback) is always included at every tier."
+            }
+          }
+        }
+      }
     }
   }
 }

package/src/scripts/self_review_gate.test.ts

@@ -62,4 +62,15 @@ describe('renderReview', () => {
         expect(renderReview(blocking, false)).toContain('WOULD block');
         expect(renderReview(blocking, true)).toContain('merge-blocking');
     });
+    it('labels each row (Blocking)/(Advisory) so a critical-but-non-blocking row never reads as inconsistent with the count', () => {
+        const findings = [f('critical', 'correctness'), f('critical', 'security')];
+        const out = renderReview(findings, false);
+        // critical × correctness is NOT blocking → labelled Advisory
+        expect(out).toContain('| critical (Advisory) | correctness |');
+        // critical × security IS blocking → labelled Blocking
+        expect(out).toContain('| critical (Blocking) | security |');
+        // verdict count matches the number of (Blocking) rows (exactly 1)
+        expect(out).toContain('1 finding(s) WOULD block');
+        expect((out.match(/\(Blocking\)/g) ?? []).length).toBe(1);
+    });
 });

package/src/scripts/self_review_gate.ts

@@ -183,8 +183,14 @@ export function renderReview(findings: Finding[], enforce: boolean): string {
         return `${banner}\n\n✅ Self-review gate: no findings.`;
     }
     const blocking = findings.filter(classifyBlocking);
+    // Each row carries an explicit (Blocking)/(Advisory) marker so a
+    // critical-but-non-blocking finding (e.g. critical × correctness) can never
+    // read as inconsistent with the narrow `blocking.length` verdict count.
     const rows = findings
-        .map((f) => `| ${f.severity} | ${f.kind} | ${f.file ?? '—'} | ${f.title} |`)
+        .map((f) => {
+            const marker = classifyBlocking(f) ? 'Blocking' : 'Advisory';
+            return `| ${f.severity} (${marker}) | ${f.kind} | ${f.file ?? '—'} | ${f.title} |`;
+        })
         .join('\n');
     const verdictLine = blocking.length
         ? enforce

package/src/scripts/skill_eval_coverage.ts

@@ -219,7 +219,10 @@ export function writeFloor(opts: CoverageOptions = {}): CoverageReport {
                 _comment:
                     'Behavioural-eval coverage ratchet floor (road-to-skill-eval-coverage Phase 3). ' +
                     'skill_eval_coverage --check fails if coverage drops below these counts. ' +
-                    'Regenerate with `--write-floor` ONLY after authoring evals — the floor only rises.',
+                    'Regenerate with `--write-floor` ONLY after authoring evals — the floor only rises. ' +
+                    'LOWERING POLICY: a legitimate drop (skills merged, redundant eval removed) is allowed ' +
+                    'ONLY by editing a count downward WITH a logged reason in coverage-floor.README.md — ' +
+                    'never by deleting the floor file or a tier key. See coverage-floor.README.md.',
                 ...floor,
             },
             null,

package/src/server/schemas/settings.ts

@@ -343,6 +343,21 @@ export const settingsSchema = z.object({
             preview_description: z.boolean().default(false).describe(
                 'When /create-pr runs, show the generated title and body and wait for confirmation before opening the PR. Off by default (zero-friction PR creation); turn on if you want a last-look gate.',
             ),
+            detail_level: z.enum(['min', 'med', 'max']).default('min').describe(
+                'Verbosity tier for the generated PR description body. min (default) = title + 2-3 sentence what/why/impact + linked ticket (token-frugal); med = min + grouped changes + tests note; max = med + how-to-test + edge cases + reviewer guidance. Critical info (breaking changes, migrations, security, rollback) is ALWAYS included at every tier — the tier governs explanatory depth, never whether a critical callout appears.',
+            ),
+            api_examples: z.boolean().default(true).describe(
+                'JSON request/response examples for API-endpoint changes. true (default) = include a fenced example ONLY when grounded in a real source (response DTO/resource, OpenAPI/schema, test fixture, or an actual probe); no grounded source → a one-line pointer, never an invented example. false = never add API examples.',
+            ),
+            screenshots: z.boolean().default(false).describe(
+                'Screenshots for frontend changes. false (default) = never attempt. true = attempt when the host has browser/preview tooling and the diff touches a frontend surface; capability-gated (emits a one-line note and leaves the placeholder when tooling is absent, never fails or blocks the PR). Before/after + changed-region highlighting is best-effort.',
+            ),
+            ui_paths: z.array(z.string()).default([]).describe(
+                'Optional glob list that makes frontend detection explicit instead of heuristic (e.g. ["resources/views/**", "src/pages/**"]). Empty (default) = a light path/extension heuristic that fails open (no false enrichment when the surface is ambiguous).',
+            ),
+            api_paths: z.array(z.string()).default([]).describe(
+                'Optional glob list that makes API-endpoint detection explicit instead of heuristic (e.g. ["app/Http/Controllers/Api/**", "src/pages/api/**"]). Empty (default) = a light path/extension heuristic that fails open.',
+            ),
         }),
     }),
     memory: z.object({