@event4u/agent-config 12.0.0 → 13.0.0

package/src/scripts/_lib/bench_ab_workspace.ts

@@ -0,0 +1,111 @@
+/**
+ * Per-trial workspace lifecycle — the clone, and the transcript beside it.
+ *
+ * The two belong together: `reset_fixture` re-creates the clone AND drops the
+ * sibling transcript, and both are the delta-#7 evidence an offline re-scorer
+ * reads. They moved out of `bench_ab_v2_run.ts` because the source-size ratchet
+ * is shrink-only and extraction is its intended answer — raising the baseline
+ * is a defect, and trimming the prose out of load-bearing comments is worse.
+ *
+ * ## Transcript preservation — delta #7's sibling, for T5.
+ *
+ * T5 scores what a run did BEFORE it wrote, which leaves no residue in the
+ * final tree: the transcript is the only evidence, and the report discards it.
+ * These two functions are what make a completed sweep re-scorable for search
+ * adherence instead of needing a re-run.
+ *
+ * BESIDE the clone, never inside it. `changed_files` diffs the clone against
+ * the pristine fixture, so a transcript written into the workspace would appear
+ * as a file the run created: T5's evidence would corrupt T1's, and the size
+ * endpoint would gain one added file per trial for a reason no reader could see.
+ *
+ * A file rather than a field on the trial record because transcripts are the
+ * largest thing a sweep produces, and inlining them would multiply a pinned
+ * report's size for data only the T5 re-scorer ever reads. Truncating instead
+ * was the other option and is worse: a rubric scored on a clipped transcript
+ * measures the clip.
+ *
+ * KNOWN COVERAGE GAP, stated rather than silently carried: the
+ * `package-recursive` arm records neither `workspace` nor `transcript_path`, so
+ * T1/T2/T4 and now T5 all skip it. The workspace half predates this module and
+ * closing it would alter what the existing endpoints cover, which is a
+ * different decision from adding one — so it is named here and in the T5
+ * re-scorer's "no transcript recorded" reason instead of being half-fixed.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
+const FIXTURES_ROOT = path.join(REPO_ROOT, 'internal', 'bench', 'ab');
+const WORK_ROOT = path.join(os.tmpdir(), 'agent-config-bench-v2-clones');
+
+type Dict = Record<string, unknown>;
+
+/** Where this trial's transcript is preserved — a sibling of the clone. */
+export function transcript_path_for(clone: string): string {
+    return `${clone}.transcript.txt`;
+}
+
+/**
+ * Write the transcript beside the clone; return the path, or `null` when there
+ * was nothing to preserve or the write failed.
+ *
+ * A null propagates onto the trial as `transcript_path: null`, which the T5
+ * re-scorer reads as "not measured on this trial" — never as a zero score. A
+ * failed write must not be able to look like a run that searched for nothing.
+ */
+export function preserve_transcript(clone: string, transcript: string): string | null {
+    if (!transcript) return null;
+    const dest = transcript_path_for(clone);
+    try {
+        fs.writeFileSync(dest, transcript, { encoding: 'utf-8' });
+    } catch {
+        return null;
+    }
+    return dest;
+}
+
+
+/**
+ * Workspace directory for one trial — delta #7 of the S0.3 spike.
+ *
+ * Keyed by `task|arm|seed`, not by task alone. The old task-only key meant every
+ * arm and every seed of a task reused ONE directory that the next trial deleted,
+ * so at the end of a sweep exactly one workspace survived per task — the last one
+ * written, with no record of which arm or seed it belonged to.
+ *
+ * That is not a tidiness problem. Phase 3's anti-golfing gate is specified as
+ * retro-fittable onto already-completed runs by offline re-scoring, and the
+ * roadmap calls that gate cheap *because* the workspaces are preserved. Under the
+ * old key there was nothing to re-score, so the claim was false. A distinct
+ * directory per trial is what makes it true.
+ *
+ * `arm` is sanitised because arm names are used verbatim as a path segment and
+ * one of them would otherwise be free to escape the root.
+ */
+export function workspace_dir(task_id: string, arm: string, seed: number): string {
+    const safe_arm = arm.replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(WORK_ROOT, `${task_id}__${safe_arm}__seed${seed}`);
+}
+
+/**
+ * Copy the task's pristine fixture into this trial's own working clone.
+ *
+ * The clone is re-created from the fixture on every call, so a resumed or
+ * repeated trial still starts pristine — the per-trial key changes *which*
+ * directory that is, never whether it is clean.
+ */
+export function reset_fixture(task: Dict, arm: string, seed: number): [string, string] {
+    const fixture = path.join(FIXTURES_ROOT, String(task['fixture']));
+    const dest = workspace_dir(String(task['id']), arm, seed);
+    if (fs.existsSync(dest)) {
+        fs.rmSync(dest, { recursive: true, force: true });
+    }
+    fs.rmSync(transcript_path_for(dest), { force: true });
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.cpSync(fixture, dest, { recursive: true });
+    return [dest, fixture];
+}

package/src/scripts/_lib/git_common_dir.ts

@@ -126,3 +126,176 @@ export function git_common_dir(project_root: string): string | null {
         return null;
     }
 }
+
+// ---------------------------------------------------------------------------
+// Workspace identity
+// ---------------------------------------------------------------------------
+
+/**
+ * One answer to one identity question, and never a silent default.
+ *
+ * The census that motivated this type (`agents/evidence/analysis/
+ * workspace-identity-census.md`) found three of eight repo-root sites falling
+ * back to a value that is *plausible but wrong* when git cannot answer —
+ * `process.cwd()`, a path derived from the script's own location, an
+ * exception. A caller cannot distinguish those from a real answer, which is
+ * how a gate ends up scanning the wrong tree and exiting green.
+ */
+export type IdentityField =
+    | { readonly resolved: true; readonly value: string; readonly provenance: string }
+    | { readonly resolved: false; readonly reason: string };
+
+/** The five workspace-identity questions, each independently resolvable. */
+export interface WorkspaceIdentity {
+    /**
+     * Top level of the working tree the caller is in — the drop-in for
+     * `git rev-parse --show-toplevel`. Inside a linked worktree this is the
+     * worktree's own root, exactly as git reports it.
+     */
+    readonly repoRoot: IdentityField;
+    /**
+     * The main (non-linked) checkout. Derived from the common git dir, so it
+     * is the same value from every worktree of the repo. This is the field the
+     * two shipped misclassification defects needed and did not have.
+     */
+    readonly mainWorktree: IdentityField;
+    /**
+     * The checkout the caller is in. Its `value` equals `repoRoot` by git's own
+     * definition; the two fields exist separately because the *provenance*
+     * differs and that is the part callers need — `main-checkout` versus
+     * `linked-worktree` is precisely the question `isStandardLocation` got
+     * wrong twice.
+     */
+    readonly currentWorktree: IdentityField;
+    /** Branch of the current checkout; unresolved on a detached HEAD. */
+    readonly branch: IdentityField;
+    /**
+     * The remote's default branch, as a `refs/remotes/<remote>/<name>` ref —
+     * the offline notion of "what a PR from here would target".
+     *
+     * Deliberately NOT the `gh`-derived base of an actual open PR: that needs
+     * network and auth, and `check_branch_freshness.ts` already owns it. This
+     * field answers the question a gate can answer without leaving the disk,
+     * and reports `unresolved` rather than guessing `main` when the repo has
+     * no recorded default.
+     */
+    readonly prBase: IdentityField;
+}
+
+function resolved(value: string, provenance: string): IdentityField {
+    return { resolved: true, value, provenance };
+}
+
+function unresolved(reason: string): IdentityField {
+    return { resolved: false, reason };
+}
+
+/**
+ * Walk up from `start` to the first directory holding a `.git` entry.
+ *
+ * File-based on purpose, like everything else here: `rev-parse --show-toplevel`
+ * would be redirected by an inherited `GIT_DIR`, and the symptom is a wrong
+ * path rather than an error.
+ */
+function discover_root(start: string): string | null {
+    let dir = realpath_or_self(path.resolve(start));
+    for (;;) {
+        if (fs.existsSync(path.join(dir, '.git'))) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+
+/**
+ * Is `project_root`'s `.git` a linked-worktree pointer file rather than a
+ * directory? Returns `null` when there is no `.git` entry at all.
+ */
+function is_linked_worktree(project_root: string): boolean | null {
+    try {
+        return !fs.statSync(path.join(project_root, '.git')).isDirectory();
+    } catch {
+        return null;
+    }
+}
+
+/** The remote default branch ref, read from disk. `null` when unrecorded. */
+function remote_head_ref(common_dir: string, remote: string): string | null {
+    // A symbolic ref is stored loose; `git pack-refs` never packs one, so
+    // packed-refs is not a fallback for this specific ref — a repo that has
+    // never run `git remote set-head` simply has no answer on disk.
+    try {
+        const raw = fs.readFileSync(path.join(common_dir, 'refs', 'remotes', remote, 'HEAD'), 'utf-8');
+        const m = raw.match(/^ref:\s*(refs\/remotes\/.+?)\s*$/m);
+        return m === null ? null : m[1]!.trim();
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Resolve all five workspace-identity questions from `start` (default: the
+ * process cwd), reading files only.
+ *
+ * Every field is either a value with its provenance or an explicit reason it
+ * could not be resolved. Nothing here throws and nothing guesses.
+ */
+export function workspaceIdentity(
+    start: string = process.cwd(),
+    remote = 'origin',
+): WorkspaceIdentity {
+    const root = discover_root(start);
+    if (root === null) {
+        const why = `no .git entry in ${path.resolve(start)} or any ancestor`;
+        return {
+            repoRoot: unresolved(why),
+            mainWorktree: unresolved(why),
+            currentWorktree: unresolved(why),
+            branch: unresolved(why),
+            prBase: unresolved(why),
+        };
+    }
+
+    const linked = is_linked_worktree(root);
+    const repoRoot = resolved(root, 'upward .git walk from cwd');
+    const currentWorktree = resolved(
+        root,
+        linked === true
+            ? 'linked-worktree (.git is a gitdir pointer file)'
+            : 'main-checkout (.git is a directory)',
+    );
+
+    const common = git_common_dir(root);
+    let mainWorktree: IdentityField;
+    if (common === null) {
+        mainWorktree = unresolved('no common git dir resolvable from the repo root');
+    } else if (path.basename(common) === '.git') {
+        mainWorktree = resolved(path.dirname(common), 'dirname of the common git dir');
+    } else {
+        // Bare repo, `core.worktree`, or a separate-gitdir layout: the common
+        // dir is not `<main>/.git`, so `dirname` would name a directory that is
+        // not a checkout. Refusing is the point of the type.
+        mainWorktree = unresolved(
+            `common git dir ${common} is not named .git — bare or separate-gitdir layout has no main worktree to derive`,
+        );
+    }
+
+    const br = current_branch(root);
+    const branch = br === null
+        ? unresolved('detached HEAD, or HEAD unreadable in the per-worktree git dir')
+        : resolved(br, 'ref line of <git-dir>/HEAD');
+
+    let prBase: IdentityField;
+    if (common === null) {
+        prBase = unresolved('no common git dir resolvable from the repo root');
+    } else {
+        const ref = remote_head_ref(common, remote);
+        prBase = ref === null
+            ? unresolved(
+                `no refs/remotes/${remote}/HEAD on disk — run \`git remote set-head ${remote} -a\`; not guessed`,
+            )
+            : resolved(ref, `symbolic ref refs/remotes/${remote}/HEAD`);
+    }
+
+    return { repoRoot, mainWorktree, currentWorktree, branch, prBase };
+}

package/src/scripts/_lib/model_tier.ts

@@ -25,7 +25,16 @@ import fs from "node:fs";
 
 // Tier → Claude model. The ONLY per-vendor mapping the package maintains
 // (ADR-035 § 3); other agents resolve the tier band to their own line-up.
+//
+// `frontier` was added by ADR-232, which amends ADR-035 § Decision 1 on that
+// record's own reopen condition. The asymmetry that triggered it is worth
+// keeping visible here: `MODEL_FAMILIES` in the orchestration-record hook has
+// enumerated four families since it shipped, while this map named three — so a
+// dispatch on the fourth band was recordable but not declarable. Adding the row
+// here rather than a second table elsewhere is what keeps ADR-035 § 3 intact:
+// one mapping, one owner, no two-clocks drift.
 export const TIER_TO_CLAUDE_MODEL: Record<string, string> = {
+  frontier: "fable",
   high: "opus",
   medium: "sonnet",
   lite: "haiku",

package/src/scripts/_lib/release_highlights.ts

@@ -76,6 +76,91 @@ const _PUBLIC_SURFACE_PREFIXES = [
 
 const _RULE_OR_SCHEMA_PREFIXES = ['src/rules/', 'src/scripts/schemas/'];
 
+/**
+ * Paths whose repair is a correctness fix to shipped *behaviour* rather than a
+ * record of one. The distinction is load-bearing: 43 % of `fix(...)` commits
+ * over the six spans measured in
+ * `agents/evidence/analysis/release-head-derivation-recall.md` touch no
+ * executable file at all — `52d7fe1 fix(worktrees): the inventory
+ * misclassifies from inside a worktree, totally` changes two markdown files and
+ * repairs nothing. Keying on the touched surface is what separates a bug fix
+ * from a bug report, and it moves hand-judged precision from 54 % to 96 %.
+ */
+const _EXECUTABLE_SUFFIX = /\.(?:ts|tsx|js|mjs|cjs|sh|py)$/u;
+const _EXECUTABLE_PREFIXES = ['.github/workflows/', '.github/actions/'];
+
+/**
+ * Shebang entry points with no extension, which a suffix test cannot see. An
+ * exact set rather than a heuristic: the alternative is reading file contents,
+ * which a span commit does not carry.
+ *
+ * The recall limit that remains, named rather than left for a reader to
+ * discover: a NEW extensionless entry point is invisible until it is added
+ * here. Precision was measured over six spans; this predicate's recall was not,
+ * and adding to this set is the maintenance that follows a new entry point.
+ */
+const _EXECUTABLE_EXACT: ReadonlySet<string> = new Set([
+    'scripts-run',
+    'src/scripts/agent-config',
+]);
+
+function _touches_executable(files: SpanCommit['files']): boolean {
+    return files.some(
+        (f) =>
+            _EXECUTABLE_SUFFIX.test(f.path) ||
+            _EXECUTABLE_EXACT.has(f.path) ||
+            _EXECUTABLE_PREFIXES.some((p) => f.path.startsWith(p)),
+    );
+}
+
+/**
+ * Conventional-commit type, lower-cased, or `''` when the subject carries no
+ * conventional prefix.
+ *
+ * Two things this deliberately does, both of which an earlier version got
+ * wrong. It requires the conventional `:` separator, so `fix the flaky runner`
+ * is not classified as type `fix` — otherwise this function disagrees with the
+ * scope regex three lines below it and with every prose description of the
+ * rule. And it recognises `Revert "<subject>"`, the form `git revert` writes by
+ * default, which is not conventional at all: without it the documented revert
+ * half only ever applied to a hand-written `revert(scope):`, and a revert of
+ * shipped behaviour is the commit class most likely to be a correctness repair.
+ */
+function _commit_type(subject: string): string {
+    if (/^Revert\s+"/u.test(subject)) {
+        return 'revert';
+    }
+    const m = /^(\w+)(?:\([^)]*\))?!?:/u.exec(subject);
+    return m ? m[1]!.toLowerCase() : '';
+}
+
+/**
+ * Recorded-null forms beyond the literal marker, taken from real subjects and
+ * bodies over the six measured spans rather than invented: a waived-rather-than-
+ * met condition, a published or recorded null, an archival on a roadmap's own
+ * falsifier. All six commits these add across the six spans are true positives.
+ */
+const _NULL_FORMS: readonly RegExp[] = [
+    /honest[ -]null/iu,
+    /\bwaived,? (?:rather than|not) met\b/iu,
+    /\bsoak was waived\b/iu,
+    // The trailing lookahead keeps a recorded *result* apart from a field that
+    // merely holds null. This pattern is applied to the body as well as the
+    // subject, and a body is where "records null token_delta" appears — a
+    // telemetry field, not a null result. Excluding an identifier-shaped token
+    // after `null` costs nothing real: "records the null result" and "closed as
+    // a published null" both still derive. The lookahead is deliberately
+    // SAME-LINE (`[ \t]`, never `\s`): the first version used `\s+` and dropped
+    // a true positive, because 92f9b9a ends its subject on "closed as a
+    // published null" and its body then opens with `count_open reached 0` — an
+    // identifier on the NEXT line, which `\s+` happily crossed. The residual
+    // limit, named rather than left to be discovered: a field name with no
+    // underscore ("records null delta") is still caught.
+    /\b(?:publish(?:es|ed|ing)?|record(?:s|ed|ing)?|report(?:s|ed|ing)?) (?:the |an |a |its )?(?:honest )?null\b(?![ \t]+`?[a-z][a-z0-9]*_[a-z0-9_]*)/iu,
+    /\bnull(?: result)? (?:stands|is the answer)\b/iu,
+    /\bon (?:its|the) own falsifier\b/iu,
+];
+
 /**
  * Why a label fired, in generator-facing prose. Keyed by label; a label absent
  * here is never derived (`Known limitations` is pure prose, not checkable).
@@ -83,25 +168,37 @@ const _RULE_OR_SCHEMA_PREFIXES = ['src/rules/', 'src/scripts/schemas/'];
 const _DERIVED_REASON: Readonly<Record<string, string>> = {
     'Behaviour changes': 'rule/schema diffs, breaking commits or removed public surface',
     'Default changes + migration': 'commits naming a default, migration or migrate',
-    'Security and correctness': 'security-scoped commits',
-    'Honest nulls': 'commits carrying an honest-null marker',
+    'Security and correctness': 'security-scoped commits or fixes to executable surface',
+    'Honest nulls': 'commits recording a null, waived or falsified result',
 };
 
 /**
  * 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.
+ *   whole word "security" in the subject — plus the *correctness* half the
+ *   label names: a `fix` or `revert` commit touching executable surface.
  * - 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.
+ * - Honest nulls: subject or body carrying one of the recorded-null forms —
+ *   the literal marker, a waived-rather-than-met condition, a published or
+ *   recorded null, an archival on a roadmap's own falsifier.
  * - Known limitations: never derived — pure prose, not gate-checkable.
  *
  * Derivation is deliberately conservative: a false red makes every release
- * annoying, a miss only returns the head to the pre-gate state.
+ * annoying, a miss only returns the head to the pre-gate state. Conservative
+ * is not the same as silent, and two labels had crossed that line: measured
+ * over the six spans in
+ * `agents/evidence/analysis/release-head-derivation-recall.md`, `Security and
+ * correctness` fired **1 of 45** hand-confirmed in-category commits and
+ * `Honest nulls` **3 of 9**, so the
+ * curated `_none_` shipped uncontested where the span carried the evidence.
+ * The widening is aimed at those two and measured before it landed; the naive
+ * "any `fix(` counts" alternative was rejected on data (54 % precision against
+ * 96 %), not on taste.
  */
 export function derive_category_hits(
     commits: readonly SpanCommit[],
@@ -113,7 +210,10 @@ export function derive_category_hits(
     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)) {
+        const type = _commit_type(c.subject);
+        const correctnessFix =
+            (type === 'fix' || type === 'revert') && _touches_executable(c.files);
+        if (/secur/iu.test(scope) || /\bsecurity\b/iu.test(c.subject) || correctnessFix) {
             out['Security and correctness']!.push({ sha: c.sha, text: c.subject });
         }
         const removedPublic = c.files.filter(
@@ -134,7 +234,8 @@ export function derive_category_hits(
         if (/\b(default|migration|migrate)\b/iu.test(c.subject)) {
             out['Default changes + migration']!.push({ sha: c.sha, text: c.subject });
         }
-        if (/honest[ -]null/iu.test(`${c.subject}\n${c.body}`)) {
+        const subjectAndBody = `${c.subject}\n${c.body}`;
+        if (_NULL_FORMS.some((re) => re.test(subjectAndBody))) {
             out['Honest nulls']!.push({ sha: c.sha, text: c.subject });
         }
     }