@event4u/agent-config 9.18.0 → 9.19.0

package/src/scripts/check_iron_law_prominence.ts

@@ -277,6 +277,10 @@ export function main(argv?: readonly string[]): number {
         process.stderr.write(`❌  ${exc instanceof Error ? exc.message : String(exc)}\n`);
         return 2;
     }
+    // Gate-coverage contract (src/config/gate-coverage.yml rule 1): publish the
+    // asserted count machine-readably. Written to stderr because `--format json`
+    // owns stdout here — a count on stdout would corrupt the JSON payload.
+    process.stderr.write(`scanned: ${String(targets.length)}\n`);
 
     const all_violations: Violation[] = [];
     for (const p of targets) {

package/src/scripts/check_release_highlights.ts

@@ -11,8 +11,14 @@
  * commit types + rule/schema diffs, honest-null markers, removed public
  * surface) and FAILS when a populated generated category meets a `_none_`
  * curated field. It blocks the contradiction only — a human still writes the
- * prose; nothing here auto-formulates highlights, and a filled field is
- * never judged for quality.
+ * prose, and a filled field is never judged for quality.
+ *
+ * The classifier lives in `_lib/release_highlights.ts` and is shared with the
+ * generator, which now pre-fills each substantiated label instead of writing
+ * `_none_` everywhere. That removes the guaranteed first-run red (9.17.0,
+ * 9.18.0) without blunting this gate: a machine-written `_none_` was never the
+ * failure it was built for — a HUMAN writing one was (9.13.0, 9.14.0), and that
+ * still fails here. An unrewritten derived line warns; it never blocks.
  *
  * Derivation is deliberately conservative (documented per-label below):
  * a false red makes every release annoying; a miss only returns the head to
@@ -25,96 +31,41 @@
  * `--from` defaults to the latest reachable release tag before `--to`
  * (default HEAD). Exit codes: 0 plausible · 1 contradiction · 2 usage error.
  */
-import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import {
+    HEAD_LABELS,
+    HEAD_NONE,
+    type SpanCommit,
+    collect_span_commits,
+    derive_categories,
+    parse_git_log,
+    previous_release_tag,
+    stale_draft_labels,
+} from './_lib/release_highlights.js';
 import { extract_changelog_section } from './_lib/release_material.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
-// The five curated labels, mirrored from release.ts RELEASE_HEAD_SECTIONS
-// (kept literal here so this checker has no import edge into the release
-// pipeline it audits; the unit tests pin the two lists against each other).
-export const HEAD_LABELS: readonly string[] = [
-    'Behaviour changes',
-    'Default changes + migration',
-    'Security and correctness',
-    'Honest nulls',
-    'Known limitations',
-];
-
-export const HEAD_NONE = '_none_';
-
-export interface SpanCommit {
-    sha: string;
-    subject: string;
-    body: string;
-    /** `A` / `M` / `D` / `R…` status per touched path. */
-    files: ReadonlyArray<{ status: string; path: string }>;
-    breaking: boolean;
-}
-
-/** Public artefact trees whose deletions count as removed public surface. */
-const _PUBLIC_SURFACE_PREFIXES = [
-    'src/skills/',
-    'src/rules/',
-    'src/agent-src/commands/',
-    'src/domains/',
-];
-
-const _RULE_OR_SCHEMA_PREFIXES = ['src/rules/', 'src/scripts/schemas/'];
-
-/**
- * Derive evidence per curated label from the span. Rules per label:
- *
- * - Security and correctness: conventional scope matching /secur/i, or the
- *   whole word "security" in the subject.
- * - Behaviour changes: breaking (`!` / BREAKING CHANGE) commits, diffs
- *   touching `src/rules/` or `src/scripts/schemas/`, and deletions under the
- *   public artefact trees (removed public surface).
- * - Default changes + migration: subject carrying the whole word "default",
- *   "migration", or "migrate".
- * - Honest nulls: subject or body carrying an "honest null" marker.
- * - Known limitations: never derived — pure prose, not gate-checkable.
- */
-export function derive_categories(commits: readonly SpanCommit[]): Record<string, string[]> {
-    const out: Record<string, string[]> = {};
-    for (const label of HEAD_LABELS) {
-        out[label] = [];
-    }
-    const evidence = (c: SpanCommit): string => `${c.sha.slice(0, 7)} ${c.subject}`;
-    for (const c of commits) {
-        const scopeMatch = /^\w+\(([^)]*)\)!?:/u.exec(c.subject);
-        const scope = scopeMatch ? scopeMatch[1]! : '';
-        if (/secur/iu.test(scope) || /\bsecurity\b/iu.test(c.subject)) {
-            out['Security and correctness']!.push(evidence(c));
-        }
-        const removedPublic = c.files.filter(
-            (f) => f.status.startsWith('D') && _PUBLIC_SURFACE_PREFIXES.some((p) => f.path.startsWith(p)),
-        );
-        const ruleOrSchema = c.files.some((f) =>
-            _RULE_OR_SCHEMA_PREFIXES.some((p) => f.path.startsWith(p)),
-        );
-        if (c.breaking || ruleOrSchema || removedPublic.length > 0) {
-            const detail =
-                removedPublic.length > 0
-                    ? `${evidence(c)} (removes ${removedPublic.map((f) => f.path).join(', ')})`
-                    : evidence(c);
-            out['Behaviour changes']!.push(detail);
-        }
-        if (/\b(default|migration|migrate)\b/iu.test(c.subject)) {
-            out['Default changes + migration']!.push(evidence(c));
-        }
-        if (/honest[ -]null/iu.test(`${c.subject}\n${c.body}`)) {
-            out['Honest nulls']!.push(evidence(c));
-        }
-    }
-    return out;
-}
+// Labels and derivation live in `_lib/release_highlights.ts` — ONE definition
+// shared with the generator that pre-fills the head. They used to be duplicated
+// here to keep the checker independent of the release pipeline, and that
+// independence is what produced the defect this gate now guards against from
+// the other side: the generator wrote `_none_` into every field while this
+// checker rejected exactly that, so every release PR was red on its first run.
+// Sharing the classifier does not blunt the gate — it still blocks the failure
+// it was built for, a human editing a substantiated line back to `_none_`.
+export {
+    HEAD_LABELS,
+    HEAD_NONE,
+    derive_categories,
+    parse_git_log as _parse_git_log,
+    type SpanCommit,
+};
 
 /**
  * Parse the curated head from a changelog section body. Returns null when
@@ -162,74 +113,6 @@ export function highlight_contradictions(
     return out;
 }
 
-// ─── git span collection (CLI only — the core above is pure) ────────────────
-
-const _RECORD = '\u001e';
-const _FIELD = '\u001f';
-
-export function _parse_git_log(raw: string): SpanCommit[] {
-    const commits: SpanCommit[] = [];
-    for (const record of raw.split(_RECORD)) {
-        if (!record.trim()) {
-            continue;
-        }
-        const [head, ...restLines] = record.split('\n');
-        const parts = (head ?? '').split(_FIELD);
-        if (parts.length < 3) {
-            continue;
-        }
-        const sha = parts[0]!.trim();
-        const subject = parts[1]!;
-        const bodyParts: string[] = [parts.slice(2).join(_FIELD)];
-        const files: Array<{ status: string; path: string }> = [];
-        for (const line of restLines) {
-            const m = /^([A-Z]\d*)\t(.+)$/u.exec(line);
-            if (m) {
-                // Renames carry two paths; the last tab field is the new path,
-                // the first the old — record both so a rename out of a public
-                // tree still counts its origin path.
-                const segs = m[2]!.split('\t');
-                for (const p of segs) {
-                    files.push({ status: m[1]!, path: p });
-                }
-            } else {
-                // %b is multi-line — everything that is not a name-status
-                // line is body continuation (honest-null markers live there).
-                bodyParts.push(line);
-            }
-        }
-        const body = bodyParts.join('\n');
-        commits.push({
-            sha,
-            subject,
-            body,
-            files,
-            breaking: /^\w+(\([^)]*\))?!:/u.test(subject) || /BREAKING CHANGE/u.test(body),
-        });
-    }
-    return commits;
-}
-
-function _git(args: string[]): string {
-    const r = spawnSync('git', args, { encoding: 'utf-8', cwd: REPO_ROOT, maxBuffer: 64 * 1024 * 1024 });
-    if (r.status !== 0) {
-        process.stderr.write(`git ${args.join(' ')} failed: ${r.stderr}\n`);
-        process.exit(2);
-    }
-    return r.stdout;
-}
-
-function _collect_span(from: string, to: string): SpanCommit[] {
-    const raw = _git([
-        'log',
-        `${from}..${to}`,
-        '--no-merges',
-        '--name-status',
-        '--format=%x1e%H%x1f%s%x1f%b',
-    ]);
-    return _parse_git_log(raw);
-}
-
 function main(argv: readonly string[]): number {
     let version: string | null = null;
     let from: string | null = null;
@@ -251,7 +134,13 @@ function main(argv: readonly string[]): number {
         return 2;
     }
     if (!from) {
-        from = _git(['describe', '--tags', '--abbrev=0', '--match', '[0-9]*.[0-9]*.[0-9]*', `${to}^`]).trim();
+        from = previous_release_tag(to, REPO_ROOT);
+        if (!from) {
+            process.stderr.write(
+                `no release tag reachable before ${to} — pass --from explicitly\n`,
+            );
+            return 2;
+        }
     }
     const section = extract_changelog_section(fs.readFileSync(changelogPath, 'utf-8'), version);
     if (!section) {
@@ -263,7 +152,26 @@ function main(argv: readonly string[]): number {
         process.stdout.write(`ℹ️  no curated head in the ${version} section — nothing to check\n`);
         return 0;
     }
-    const derived = derive_categories(_collect_span(from, to));
+    let span: SpanCommit[];
+    try {
+        span = collect_span_commits(from, to, REPO_ROOT);
+    } catch (err) {
+        process.stderr.write(`${(err as Error).message}\n`);
+        return 2;
+    }
+    // A generator-derived line that nobody rewrote is a prose gap, never a
+    // contradiction: the line's evidence is true, it is just unpolished. Warn
+    // so the omission is visible, and keep the exit code owned solely by the
+    // `_none_` check — a warning that reds the build is the guaranteed-red
+    // failure mode this whole change exists to remove.
+    const drafts = stale_draft_labels(curated);
+    if (drafts.length > 0) {
+        process.stdout.write(
+            `⚠️  auto-derived head line(s) not yet rewritten for ${version}: ` +
+                `${drafts.join(', ')} — advisory, not blocking.\n`,
+        );
+    }
+    const derived = derive_categories(span);
     const contradictions = highlight_contradictions(curated, derived);
     if (contradictions.length === 0) {
         process.stdout.write(`✅  curated head plausible for ${version} (span ${from}..${to})\n`);

package/src/scripts/dispatch_r2_reviewer.ts

@@ -437,11 +437,12 @@ const CI_BRANCH_ENV_KEYS = ['GITHUB_HEAD_REF', 'GITHUB_REF_NAME'] as const;
  * uses it to decide whether a leftover artifact in the reviews directory is
  * THIS branch's (and may therefore produce violations) or a foreign one.
  *
- * The CI environment is consulted FIRST because on a `pull_request` checkout
- * `HEAD` is a detached synthetic merge commit: `rev-parse --abbrev-ref HEAD`
- * yields `HEAD`, the slug degrades to `detached-<sha>`, and no artefact can
- * ever be "own" — which inverts contract §2.6 on the layer the contract calls
- * authoritative (an own malformed artefact would be reported as
+ * Resolution order is **git first, CI environment as the fallback** — see the
+ * reason inline below. The env fallback exists because on a `pull_request`
+ * checkout `HEAD` is a detached synthetic merge commit: `rev-parse --abbrev-ref
+ * HEAD` yields `HEAD`, the slug would degrade to `detached-<sha>`, and no
+ * artefact could ever be "own" — inverting contract §2.6 on the layer the
+ * contract calls authoritative (an own malformed artefact would report
  * `missing-artifact` instead of the root-cause `bad-marker`, and `stale-review`
  * would never fire in CI). A `HEAD` / `detached-*` env value carries no branch
  * identity either and is ignored.

package/src/scripts/lint_artefact_frontmatter.ts

@@ -359,6 +359,10 @@ function main(argv?: readonly string[]): number {
         process.stderr.write(`❌  ${exc.message}\n`);
         return 2;
     }
+    // Gate-coverage contract (src/config/gate-coverage.yml rule 1): publish the
+    // asserted count machine-readably, before the verdict branches, so a run
+    // that finds errors still reports the corpus it read.
+    process.stdout.write(`scanned: ${String(artefacts.length)}\n`);
     const allErrs: string[] = [];
     for (const p of artefacts) {
         allErrs.push(..._check_one(p, wsIds, packIds, quarantine));

package/src/scripts/lint_handoffs.ts

@@ -362,7 +362,13 @@ export function validate_handoff_artifact(text: string): string[] {
 
 export function main(argv?: readonly string[]): number {
     let skills_dir = SKILLS_DIR;
-    const args = argv ?? process.argv.slice(2);
+    // Positional-only: flags are NOT paths. Before this filter the CI invocation
+    // (`lint_handoffs --quiet`, injected by Taskfile's QUIET_FLAG) resolved
+    // `--quiet` as the skills root, scanned 0 files and exited 2 — the gate was
+    // red under the exact argv CI runs while green when probed bare. That is the
+    // inverse of this suite's dead-scope defect and the reason gate-coverage
+    // rule 2 pins CI-identical argv.
+    const args = (argv ?? process.argv.slice(2)).filter((a) => !String(a).startsWith('-'));
     if (args.length > 0 && String(args[0]).endsWith('HANDOFF.md')) {
         // artifact mode — validate the workflow-resume file's required fields
         const text = fs.readFileSync(_resolve(args[0] as string), 'utf-8');
@@ -399,6 +405,12 @@ export function main(argv?: readonly string[]): number {
         process.stderr.write(`❌  ${exc.message}\n`);
         return 2;
     }
+    // Gate-coverage contract (src/config/gate-coverage.yml rule 1): publish the
+    // count the assertion above just validated. Emitted before the verdict
+    // branches so a run WITH violations still reports its corpus — coverage and
+    // verdict are different questions — and outside the QUIET guard, because CI
+    // passes --quiet and a count only visible without it is not a count.
+    process.stdout.write(`scanned: ${String(scanned)}\n`);
 
     const violations = lint(skills_dir);
     if (violations.length === 0) {

package/src/scripts/lint_namespace.ts

@@ -347,6 +347,11 @@ function main(argv?: readonly string[]): number {
         process.stderr.write(`❌  ${exc.message}\n`);
         return 2;
     }
+    // Gate-coverage contract (src/config/gate-coverage.yml rule 1): publish the
+    // asserted count machine-readably. The human line below is quiet-suppressed
+    // and only prints on the clean path; this one prints on both, because a gate
+    // that found issues still scanned its corpus.
+    process.stdout.write(`scanned: ${String(checked)}\n`);
     if (issues) {
         process.stderr.write(`BASELINE: ${issues} issue(s) across ${checked} name(s)\n`);
         return 1;

package/src/scripts/release.ts

@@ -118,6 +118,12 @@ import {
     perform_split,
     plan_split,
 } from './_lib/changelog_eras.js';
+import {
+    HEAD_LABELS,
+    collect_span_commits,
+    derive_category_hits,
+    render_derived_head_values,
+} from './_lib/release_highlights.js';
 import {
     extract_changelog_section,
     pr_body_from_section,
@@ -383,13 +389,7 @@ const SECTIONS: ReadonlyArray<readonly [string, string | null, readonly string[]
  * so the package does not end up with two competing definitions of a curated
  * head.
  */
-const RELEASE_HEAD_SECTIONS: ReadonlyArray<string> = [
-    'Behaviour changes',
-    'Default changes + migration',
-    'Security and correctness',
-    'Honest nulls',
-    'Known limitations',
-];
+const RELEASE_HEAD_SECTIONS: ReadonlyArray<string> = HEAD_LABELS;
 
 /**
  * Cap on the head, in rendered lines.
@@ -402,16 +402,44 @@ const RELEASE_HEAD_SECTIONS: ReadonlyArray<string> = [
 export const RELEASE_HEAD_CAP_LINES = 10;
 
 /**
- * The default value of every head line.
+ * The fallback value of a head line the span does not substantiate.
+ *
+ * `_none_` and not a placeholder token: where nothing was derived it is the
+ * **true** answer, and a release that genuinely changed no defaults should say
+ * so rather than carry an unfilled marker.
  *
- * `_none_` and not a placeholder token: for most releases it is the **true**
- * answer, and a release that genuinely changed no defaults should say so
- * rather than carry an unfilled marker. That also keeps the skeleton free of
- * the placeholder prose `output-discipline` bans — there is nothing here that
- * is wrong-if-shipped, only something that is uninformative-if-unedited.
+ * It is a fallback and no longer a blanket default. Writing `_none_` into
+ * every field made the generator assert five things it had not checked, and
+ * `check_release_highlights` rejected exactly that assertion the moment the
+ * span contradicted it — which for this package is every release, because every
+ * release touches `src/rules/` or `src/scripts/schemas/`. Substantiated labels
+ * are now pre-filled from the span (`_derive_head_prefill`), so the tool states
+ * only what it can support and `_none_` means what it says.
  */
 const HEAD_DEFAULT = '_none_';
 
+/**
+ * Pre-fill values for the curated head from the release span.
+ *
+ * Best-effort by design, same stance as the test-trend footer: a git failure
+ * degrades to the `_none_` skeleton rather than blocking a release. The gate
+ * that reads the result runs later, on the branch head, and derives from the
+ * same shared classifier — so a degraded run surfaces as the gate's ordinary
+ * "fill the head" message instead of a crash mid-release.
+ */
+function _derive_head_prefill(prev: string | null): Record<string, string> {
+    try {
+        const span = collect_span_commits(prev, 'HEAD', REPO_ROOT);
+        return render_derived_head_values(derive_category_hits(span));
+    } catch (err) {
+        process.stderr.write(
+            `warning: could not derive release-head highlights (${(err as Error).message}); ` +
+                'the head ships as the `_none_` skeleton\n',
+        );
+        return {};
+    }
+}
+
 /**
  * Render the curated head. Emitted by the generator on every release so it
  * cannot be forgotten; edited by the maintainer before merge.
@@ -2344,8 +2372,14 @@ function main(argv: readonly string[] | null = null): number {
     // (~15s+), which `--dry-run exits 0 without needing …` contracts (and
     // the release test) assume never runs. Real releases compute it.
     const test_trend_line = args.dry_run ? null : _render_test_trend_line(prev);
+    // Derived unconditionally, dry-run included: it is one `git log` (~25 ms),
+    // not the trend line's full vitest collection. Skipping it on `--dry-run`
+    // made the preview print the `_none_` skeleton while the real run wrote
+    // pre-filled lines — a preview that contradicts its own output, which is
+    // the exact class of surface disagreement this pre-fill exists to end.
     const [full, body] = render_changelog_entry(target, prev, commits, today, {
         test_trend_line,
+        head: _derive_head_prefill(prev),
     });
 
     // Era-split planning — gate on the POST-release view (2026-07-07 fix).

package/src/scripts/sweep_dead_scan_roots.ts

@@ -372,7 +372,7 @@ export function analyze(src: string, repoRoot: string): Analysis {
     const confirmed: Finding[] = [];
     const unproven: Finding[] = [];
     const roots = new Map<string, string>();
-    const missing = (rel: string): boolean => !fs.existsSync(path.join(repoRoot, rel));
+    const missing = (rel: string): boolean => !rootExists(repoRoot, rel);
 
     for (const [rel, e] of found) {
         roots.set(rel, [...e.names].join(',') || '(inline)');
@@ -549,12 +549,46 @@ export function censusOnlyRoots(src: string, repoRoot: string): Map<string, stri
         if (rel === '' || rel.startsWith('..')) continue;
         // `node_modules/.bin/tsx` is a tool path a gate SPAWNS, not a corpus it reads.
         if (rel === 'node_modules' || rel.startsWith('node_modules/')) continue;
-        if (!fs.existsSync(path.join(repoRoot, rel))) continue; // the safety filter — see the doc comment
+        if (!rootExists(repoRoot, rel)) continue; // the safety filter — see the doc comment
         if (!out.has(rel)) out.set(rel, '(census-only)');
     }
     return out;
 }
 
+/**
+ * Does a declared root exist, independent of checkout shape?
+ *
+ * A plain `existsSync` answers differently in a linked git worktree, where
+ * `.git` is a FILE containing `gitdir: …` rather than a directory — so a root
+ * like `.git/HEAD` resolves in a clone and vanishes in a worktree. The census
+ * has to "match a fresh run" to be worth committing, and a report whose rows
+ * depend on which checkout generated it cannot. Resolving `.git/*` through the
+ * real git directory makes the two agree.
+ */
+export function resolveRoot(repoRoot: string, rel: string): string {
+    if (rel === '.git' || rel.startsWith('.git/')) {
+        const gitPath = path.join(repoRoot, '.git');
+        try {
+            if (fs.statSync(gitPath).isFile()) {
+                // `gitdir: <abs-or-relative path>` — the worktree's real git dir.
+                const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitPath, 'utf8'));
+                const target = m?.[1]?.trim();
+                if (target !== undefined && target !== '') {
+                    const gitDir = path.isAbsolute(target) ? target : path.join(repoRoot, target);
+                    return rel === '.git' ? gitDir : path.join(gitDir, rel.slice('.git/'.length));
+                }
+            }
+        } catch {
+            /* fall through to the plain join — a missing .git is genuinely absent */
+        }
+    }
+    return path.join(repoRoot, rel);
+}
+
+export function rootExists(repoRoot: string, rel: string): boolean {
+    return fs.existsSync(resolveRoot(repoRoot, rel));
+}
+
 /** Directories never worth walking for a unit count. */
 const COUNT_SKIP: ReadonlySet<string> = new Set(['node_modules', '.git', '.venv', '__pycache__']);
 
@@ -578,7 +612,7 @@ export interface RootCount {
  * a container migration shows up as a diff instead of as silence.
  */
 export function countUnits(repoRoot: string, rel: string): RootCount {
-    const abs = path.join(repoRoot, rel);
+    const abs = resolveRoot(repoRoot, rel);
     let st: fs.Stats;
     try {
         st = fs.statSync(abs);