@event4u/agent-config 9.16.0 → 9.17.0

package/src/scripts/lint_profile_personas.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env tsx
+/**
+ * Profile → persona id resolution gate.
+ *
+ * ## The defect this catches
+ *
+ * Every seed profile under `src/agent-src/profiles/*.yml` pre-selects persona
+ * ids in `defaults.personas`. Persona ids are the filenames under
+ * `src/agent-src/personas/` (plus `personas/advisors/`), and nothing else
+ * historically checked the join — all six seed profiles shipped ids
+ * (`reviewer`, `security`, `editor`, …) that resolved to no persona file at
+ * all, so the pre-selection was silently dead. This gate makes a broken id a
+ * CI failure with a nearest-match hint.
+ *
+ * Contract (src/config/gate-coverage.yml): emits exactly one `scanned: <N>`
+ * line, N = profiles scanned.
+ *
+ * Exit: 0 clean · 1 usage/IO error · 2 findings.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export interface Finding {
+    file: string;
+    id: string;
+    hint: string;
+}
+
+/** Persona ids = `.md` basenames under personas/ and personas/advisors/. */
+export function known_persona_ids(repoRoot: string): Set<string> {
+    const ids = new Set<string>();
+    const roots = [
+        path.join(repoRoot, 'src', 'agent-src', 'personas'),
+        path.join(repoRoot, 'src', 'agent-src', 'personas', 'advisors'),
+    ];
+    for (const dir of roots) {
+        if (!fs.existsSync(dir)) continue;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+            if (entry.name === 'README.md') continue;
+            ids.add(entry.name.slice(0, -'.md'.length));
+        }
+    }
+    return ids;
+}
+
+function levenshtein(a: string, b: string): number {
+    const prev: number[] = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0]!;
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cur = prev[j]!;
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            prev[j] = Math.min(cur + 1, prev[j - 1]! + 1, diag + cost);
+            diag = cur;
+        }
+    }
+    return prev[b.length]!;
+}
+
+/** Closest known id by substring containment first, edit distance second. */
+export function nearest_match(id: string, known: ReadonlySet<string>): string {
+    let best = '';
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const candidate of known) {
+        const contains = candidate.includes(id) || id.includes(candidate);
+        const score = levenshtein(id, candidate) - (contains ? 100 : 0);
+        if (score < bestScore) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    return best;
+}
+
+/**
+ * Scan every `profiles/*.yml` under `repoRoot`'s profile dir and resolve
+ * `defaults.personas` against the known persona ids.
+ */
+export function scan_profiles(repoRoot: string): { findings: Finding[]; scanned: number } {
+    const profileDir = path.join(repoRoot, 'src', 'agent-src', 'profiles');
+    if (!fs.existsSync(profileDir)) {
+        throw new Error(`profile directory not found: ${profileDir}`);
+    }
+    const known = known_persona_ids(repoRoot);
+    const findings: Finding[] = [];
+    let scanned = 0;
+    const files = fs
+        .readdirSync(profileDir)
+        .filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))
+        .sort();
+    for (const file of files) {
+        const full = path.join(profileDir, file);
+        const rel = path.relative(repoRoot, full);
+        const parsed = parseYaml(fs.readFileSync(full, 'utf-8')) as Record<string, unknown> | null;
+        scanned += 1;
+        const profile = (parsed?.['profile'] ?? {}) as Record<string, unknown>;
+        const defaults = (profile['defaults'] ?? {}) as Record<string, unknown>;
+        const personas = defaults['personas'];
+        if (!Array.isArray(personas)) continue;
+        for (const raw of personas) {
+            const id = String(raw);
+            if (known.has(id)) continue;
+            const hint = known.size > 0 ? `did you mean \`${nearest_match(id, known)}\`?` : 'no personas found';
+            findings.push({ file: rel, id, hint });
+        }
+    }
+    return { findings, scanned };
+}
+
+export function main(argv?: readonly string[]): number {
+    let quiet = false;
+    for (const arg of argv ?? process.argv.slice(2)) {
+        if (arg === '--quiet') {
+            quiet = true;
+        } else {
+            process.stderr.write(`usage: lint_profile_personas [--quiet]\n`);
+            return 1;
+        }
+    }
+
+    let result: { findings: Finding[]; scanned: number };
+    try {
+        result = scan_profiles(REPO_ROOT);
+    } catch (e) {
+        process.stderr.write(`error: ${String(e)}\n`);
+        return 1;
+    }
+
+    for (const f of result.findings) {
+        process.stdout.write(
+            `❌  ${f.file}  defaults.personas id \`${f.id}\` resolves to no file under src/agent-src/personas/ — ${f.hint}\n`,
+        );
+    }
+    if (result.findings.length === 0 && !quiet) {
+        process.stdout.write(
+            `✅  profile personas: every defaults.personas id resolves to a persona file\n`,
+        );
+    }
+    // gate-coverage contract (src/config/gate-coverage.yml): profiles inspected.
+    process.stdout.write(`scanned: ${String(result.scanned)}\n`);
+    return result.findings.length > 0 ? 2 : 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}

package/src/scripts/lint_token_budget_discipline.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env tsx
+/**
+ * Token-budget-discipline gate (src/rules/token-budget-discipline.md).
+ *
+ * The rule names this linter as its CI enforcer for two obligations on
+ * `token_budget_class: rich` skills:
+ *
+ * 1. CAP — at most 15 % of the suite's skills may claim `rich`. Exceeding
+ *    the ratio is a hard fail (both numbers are printed).
+ * 2. JUSTIFICATION — every `rich`-tagged skill carries a
+ *    `## Why this skill is rich` section explaining the irreducible
+ *    complexity.
+ *
+ * Additionally, any `token_budget_class` value outside
+ * `lean | standard | rich` is a finding (schema drift).
+ *
+ * Exit: 0 clean · 1 usage/IO error · 2 findings.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const SKILLS_ROOT = 'src/skills';
+
+/** The rule's cap: rich-tagged skills / total skills must stay <= 15 %. */
+export const RICH_RATIO_CAP = 0.15;
+
+export const VALID_CLASSES = ['lean', 'standard', 'rich'] as const;
+
+export const RICH_SECTION_HEADING = '## Why this skill is rich';
+
+export interface Finding {
+    /** repo-relative path */
+    file: string;
+    message: string;
+}
+
+export interface ScanResult {
+    findings: Finding[];
+    /** SKILL.md files scanned. */
+    scanned: number;
+    /** Skills declaring token_budget_class: rich. */
+    richCount: number;
+}
+
+/** `token_budget_class` value from a SKILL.md's YAML frontmatter, or null. */
+export function frontmatter_class(content: string): string | null {
+    if (!content.startsWith('---')) {
+        return null;
+    }
+    const end = content.indexOf('\n---', 3);
+    if (end === -1) {
+        return null;
+    }
+    const frontmatter = content.slice(0, end);
+    const m = /^token_budget_class:\s*['"]?([^'"\s#]+)/m.exec(frontmatter);
+    return m ? m[1]! : null;
+}
+
+/** Scan one skills root (directory of `<skill>/SKILL.md`). */
+export function scan_skills(skillsRoot: string): ScanResult {
+    const findings: Finding[] = [];
+    let scanned = 0;
+    let richCount = 0;
+    const entries = fs
+        .readdirSync(skillsRoot, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    for (const name of entries) {
+        const skillFile = path.join(skillsRoot, name, 'SKILL.md');
+        if (!fs.existsSync(skillFile)) {
+            continue;
+        }
+        scanned += 1;
+        const rel = path.relative(REPO_ROOT, skillFile).split(path.sep).join('/');
+        const content = fs.readFileSync(skillFile, 'utf-8');
+        const cls = frontmatter_class(content);
+        if (cls === null) {
+            continue; // no key = lean by default (rule § the three classes)
+        }
+        if (!(VALID_CLASSES as readonly string[]).includes(cls)) {
+            findings.push({
+                file: rel,
+                message: `invalid token_budget_class '${cls}' — must be one of ${VALID_CLASSES.join(' | ')}`,
+            });
+            continue;
+        }
+        if (cls === 'rich') {
+            richCount += 1;
+            if (!content.includes(RICH_SECTION_HEADING)) {
+                findings.push({
+                    file: rel,
+                    message: `rich-tagged skill missing the '${RICH_SECTION_HEADING}' justification section`,
+                });
+            }
+        }
+    }
+    if (scanned > 0 && richCount > scanned * RICH_RATIO_CAP) {
+        findings.push({
+            file: SKILLS_ROOT,
+            message:
+                `rich-skill cap exceeded: ${String(richCount)} rich of ${String(scanned)} skills ` +
+                `(${((richCount / scanned) * 100).toFixed(1)} % > ${String(RICH_RATIO_CAP * 100)} % cap, ` +
+                `max ${String(Math.floor(scanned * RICH_RATIO_CAP))})`,
+        });
+    }
+    return { findings, scanned, richCount };
+}
+
+export function main(argv?: readonly string[]): number {
+    let quiet = false;
+    for (const arg of argv ?? process.argv.slice(2)) {
+        if (arg === '--quiet') {
+            quiet = true;
+        } else {
+            process.stderr.write('usage: lint_token_budget_discipline [--quiet]\n');
+            return 1;
+        }
+    }
+
+    let result: ScanResult;
+    try {
+        result = scan_skills(path.join(REPO_ROOT, SKILLS_ROOT));
+    } catch (e) {
+        process.stderr.write(`error: ${String(e)}\n`);
+        return 1;
+    }
+
+    for (const f of result.findings) {
+        process.stdout.write(`❌  ${f.file}  ${f.message}\n`);
+    }
+    if (result.findings.length === 0 && !quiet) {
+        process.stdout.write(
+            `✅  token-budget discipline: ${String(result.richCount)} rich of ${String(result.scanned)} skills within the ${String(RICH_RATIO_CAP * 100)} % cap; every rich skill justifies itself\n`,
+        );
+    }
+    // gate-coverage contract (src/config/gate-coverage.yml): files inspected.
+    process.stdout.write(`scanned: ${String(result.scanned)}\n`);
+    return result.findings.length > 0 ? 2 : 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}

package/src/scripts/release.ts

@@ -118,6 +118,12 @@ import {
     perform_split,
     plan_split,
 } from './_lib/changelog_eras.js';
+import {
+    extract_changelog_section,
+    pr_body_from_section,
+    release_notes_from_section,
+    tag_message_from_section,
+} from './_lib/release_material.js';
 
 // `__doc__.splitlines()[0]` in `_parse_args` — the argparse description. Kept
 // as a referenceable constant so the first docstring line is preserved exactly.
@@ -517,6 +523,22 @@ interface RunResult {
  * stderr so release preflight failures are diagnosable without re-running with
  * a debugger.
  */
+/**
+ * Drill/test seam — when set, every external command run() would spawn is
+ * answered by this function instead. The check/die/CalledProcessError
+ * semantics of run() still apply to the simulated result, so the drill
+ * exercises the REAL error paths of the orchestration (release_drill.ts).
+ */
+type ExecOverride = (args: readonly string[]) => {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+let _exec_override: ExecOverride | null = null;
+function _set_exec_override(fn: ExecOverride | null): void {
+    _exec_override = fn;
+}
+
 function run(
     args: readonly string[],
     opts: { check?: boolean; capture?: boolean; cwd?: string | null } = {},
@@ -526,13 +548,15 @@ function run(
     const cwd = opts.cwd ?? REPO_ROOT;
 
     const [cmd, ...rest] = args;
-    const res = spawnSync(cmd as string, rest, {
-        cwd,
-        encoding: 'utf-8',
-        // capture_output=True → pipe; else inherit so child writes straight to
-        // this process's stdout/stderr (text mode, matching subprocess text=True).
-        stdio: capture ? ['ignore', 'pipe', 'pipe'] : ['inherit', 'inherit', 'inherit'],
-    });
+    const res = _exec_override
+        ? { ..._exec_override(args), error: undefined as Error | undefined }
+        : spawnSync(cmd as string, rest, {
+              cwd,
+              encoding: 'utf-8',
+              // capture_output=True → pipe; else inherit so child writes straight to
+              // this process's stdout/stderr (text mode, matching subprocess text=True).
+              stdio: capture ? ['ignore', 'pipe', 'pipe'] : ['inherit', 'inherit', 'inherit'],
+          });
 
     if (res.error) {
         // FileNotFoundError analogue (ENOENT) and other spawn failures — Python
@@ -619,6 +643,31 @@ export function _failed_checks_report(names: readonly string[]): string {
             'empty (docs/contracts/release-pr-gating.md § Mid-release fixes).',
         );
     }
+    if (names.includes('PR body equals CHANGELOG entry')) {
+        lines.push(
+            '',
+            'Surface equality: the PR body drifted from the CHANGELOG entry. A',
+            'resume run refreshes it from the branch head (release-truth Phase 1);',
+            'never hand-edit the PR body away from the changelog section.',
+        );
+    }
+    if (names.includes('Curated highlights plausible against the span')) {
+        lines.push(
+            '',
+            'Highlights: a curated `_none_` field contradicts the release span.',
+            'Fill the curated head in CHANGELOG.md on the release branch — the',
+            'gate output lists the deriving commits (release-truth Phase 2).',
+        );
+    }
+    if (names.includes('Blocking review findings dispositioned')) {
+        lines.push(
+            '',
+            'Dispositions: a blocking/high self-review finding has no committed',
+            'disposition. Ingest + adjudicate it in',
+            'agents/evidence/release-findings/<version>.json (release-truth Phase 3):',
+            '  ./scripts-run src/scripts/check_finding_dispositions --ingest <findings.json>',
+        );
+    }
     lines.push('', 'After fixing, resume with: task release -- --resume --yes', '');
     return lines.join('\n');
 }
@@ -635,24 +684,24 @@ export function _failed_checks_report(names: readonly string[]): string {
  * freshly-pushed branch.
  */
 function watch_pr_checks(branch: string): void {
-    // time.sleep(5) — blocking grace period. Never reached on any test path.
-    const until = Date.now() + 5000;
-    while (Date.now() < until) {
-        // busy-wait stand-in for time.sleep(5) without an event-loop yield.
+    if (_exec_override === null) {
+        // time.sleep(5) — blocking grace period for GitHub to register runs
+        // on a freshly-pushed branch. Skipped under the drill seam: there is
+        // no GitHub to wait for, and 5s per simulated wait adds up.
+        const until = Date.now() + 5000;
+        while (Date.now() < until) {
+            // busy-wait stand-in for time.sleep(5) without an event-loop yield.
+        }
     }
     // The branch is passed explicitly — `gh` inferring the PR from HEAD
     // resolved to `main` mid-run once (2026-08-03, 9.16.0 resume) and the
     // whole release died on "no pull requests found for branch main".
-    const proc = spawnSync('gh', ['pr', 'checks', branch, '--watch'], {
-        cwd: REPO_ROOT,
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'pipe'],
+    const proc = run(['gh', 'pr', 'checks', branch, '--watch'], {
+        check: false,
+        capture: true,
     });
-    if (proc.error) {
-        throw proc.error;
-    }
     const output = ((proc.stdout || '') + (proc.stderr || '')).trim();
-    const returncode = proc.status ?? 0;
+    const returncode = proc.returncode;
     if (returncode === 0) {
         if (output) {
             process.stdout.write(output + '\n');
@@ -670,10 +719,9 @@ function watch_pr_checks(branch: string): void {
     if (output) {
         process.stderr.write(output + '\n');
     }
-    const summary = spawnSync('gh', ['pr', 'checks', branch, '--json', 'name,bucket'], {
-        cwd: REPO_ROOT,
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'pipe'],
+    const summary = run(['gh', 'pr', 'checks', branch, '--json', 'name,bucket'], {
+        check: false,
+        capture: true,
     });
     const report = _failed_checks_report(_failed_check_names(summary.stdout ?? ''));
     if (report) {
@@ -734,11 +782,45 @@ const _MERGE_UPDATE_ROUNDS = 3;
  * version-bump allowlist (docs/contracts/release-pr-gating.md § Mid-release
  * fixes) — do it here instead of aborting the run.
  */
+/**
+ * Re-derive the release-PR body from the CHANGELOG section at the current
+ * release-branch head and push it to the PR (release-truth Phase 1: one
+ * final source — late commits and maintainer edits on the branch must reach
+ * the PR body instead of leaving it frozen at plan time). Best-effort sync
+ * of the local branch first; a no-op when the derived body is unchanged.
+ */
+function _target_from_branch(branch: string): string {
+    return branch.replace(/^release\//u, '');
+}
+
+function _refresh_pr_body_from_head(branch: string, target: string): void {
+    run(['git', 'pull', '--ff-only', REMOTE, branch], { check: false });
+    const changelog = fs.readFileSync(CHANGELOG, 'utf-8');
+    const section = extract_changelog_section(changelog, target);
+    if (!section) {
+        die(`CHANGELOG.md at ${branch} head carries no section for ${target} — cannot derive PR body`);
+    }
+    const capped = _cap_body(section!.body, GH_PR_BODY_LIMIT - 200, '`CHANGELOG.md` in this PR');
+    const body = pr_body_from_section(capped, target);
+    const live = run(['gh', 'pr', 'view', branch, '--json', 'body', '-q', '.body'], {
+        check: false,
+        capture: true,
+    });
+    if (live.returncode === 0 && live.stdout.replace(/\r\n/gu, '\n').trim() === body.trim()) {
+        return;
+    }
+    run(['gh', 'pr', 'edit', branch, '--body', body]);
+}
+
 function merge_release_pr(branch: string, wait_for_checks: boolean): void {
     if (git(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true }) !== branch) {
         run(['git', 'checkout', branch]);
     }
     for (let round = 0; round <= _MERGE_UPDATE_ROUNDS; round++) {
+        // One final generation step at the final head: every merge attempt
+        // first re-derives the PR body from the branch-head CHANGELOG, so
+        // update rounds and maintainer edits can never desynchronize it.
+        _refresh_pr_body_from_head(branch, _target_from_branch(branch));
         if (_pr_merge_state(branch) !== 'BEHIND') {
             const merged = run(['gh', 'pr', 'merge', branch, '--merge', '--delete-branch'], {
                 check: false,
@@ -1708,18 +1790,27 @@ function execute(
     if (pr_merged) {
         _step(5, total, `PR #${pr_info!['number']} already merged — skip`);
     } else if (resume && pr_state === 'OPEN') {
-        _step(5, total, `PR already open: ${pr_info!['url']}`);
+        // One final source: a resumed run re-derives the body from the
+        // branch-head CHANGELOG instead of leaving the plan-time snapshot —
+        // this was the 9.14.0 test-count desync (resume re-rendered from a
+        // later HEAD while the changelog kept the branch's entry).
+        _step(5, total, `PR already open: ${pr_info!['url']} — refresh body from branch head`);
+        _refresh_pr_body_from_head(branch, plan.target);
     } else {
         _step(5, total, 'Open pull request');
+        // Derive the PR body from the CHANGELOG section step 2 just wrote —
+        // the file is the single source; the in-memory plan is only its
+        // author (release-truth Phase 1).
+        const section = extract_changelog_section(fs.readFileSync(CHANGELOG, 'utf-8'), plan.target);
+        if (!section) {
+            die(`CHANGELOG.md carries no section for ${plan.target} — cannot derive PR body`);
+        }
         const pr_changelog = _cap_body(
-            plan.changelog_body,
+            section!.body,
             GH_PR_BODY_LIMIT - 200, // leave room for the prefix + footer
             '`CHANGELOG.md` in this PR',
         );
-        const pr_body =
-            `Release ${plan.target}.\n\n` +
-            `${pr_changelog}\n\n` +
-            'Created by `scripts/release.py`.';
+        const pr_body = pr_body_from_section(pr_changelog, plan.target);
         run([
             'gh',
             'pr',
@@ -1770,8 +1861,21 @@ function execute(
             run(['git', 'push', REMOTE, plan.target]);
         }
     } else {
-        _step(8, total, `Tag merge commit and push ${plan.target}`);
-        run(['git', 'tag', plan.target]);
+        // Sequencing is load-bearing (release-truth Phase 1, council
+        // 2026-08-03): merge FIRST (step 7), pull main (above), THEN derive
+        // the tag message from the MERGED changelog — tagging before the
+        // merge would read a section that does not exist yet. The annotated
+        // tag replaces the previous lightweight one so tag metadata is a
+        // fourth surface carrying the same single-source content.
+        _step(8, total, `Tag merge commit (annotated, from merged CHANGELOG) and push ${plan.target}`);
+        const merged = extract_changelog_section(fs.readFileSync(CHANGELOG, 'utf-8'), plan.target);
+        if (!merged) {
+            die(
+                `CHANGELOG.md on ${MAIN_BRANCH} carries no section for ${plan.target} — ` +
+                    'refusing to tag a release whose changelog entry is missing',
+            );
+        }
+        run(['git', 'tag', '-a', plan.target, '-m', tag_message_from_section(merged!.body, plan.target)]);
         run(['git', 'push', REMOTE, plan.target]);
     }
 
@@ -1786,8 +1890,19 @@ function execute(
                 ? 'Create GitHub Release (tag push under GITHUB_TOKEN triggers nothing — dispatching next)'
                 : 'Create GitHub Release (triggers publish-npm on the tag)',
         );
+        // One final source: the notes come from the CHANGELOG as recorded AT
+        // THE TAG — never from the plan-time render (whose scope can differ
+        // from the merged content; that was the 9.14.0 desync).
+        const tagged_changelog = git(['show', `${plan.target}:CHANGELOG.md`], { capture: true });
+        const tagged_section = extract_changelog_section(tagged_changelog, plan.target);
+        if (!tagged_section) {
+            die(
+                `CHANGELOG.md at tag ${plan.target} carries no section for ${plan.target} — ` +
+                    'refusing to publish release notes from a different source',
+            );
+        }
         const notes = _cap_body(
-            plan.changelog_body || `Release ${plan.target}`,
+            release_notes_from_section(tagged_section!.body, plan.target),
             GH_RELEASE_NOTES_LIMIT,
             '`CHANGELOG.md`',
         );
@@ -2363,5 +2478,14 @@ export {
     SEMVER_RE,
     _RELEASE_BRANCH_RE,
     MODULE_DOC_FIRST_LINE,
+    // Drill seam (release_drill.ts) — the step machinery under a simulated
+    // git/gh world, so orchestration bugs surface in vitest, not mid-release.
+    execute,
+    _set_exec_override,
+    push_release_branch,
+    merge_release_pr,
+    watch_pr_checks,
+    _pr_merge_state,
+    _MERGE_UPDATE_ROUNDS,
 };
 export type { Args };