session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/issue-close-strip-labels.mjs

@@ -20,19 +20,24 @@
  *     resolve to the wrong GitLab instance on a multi-host machine, turning
  *     this whole module into a silent no-op.
  *
- * Usage (from session-end Phase 5 issue-close loop):
+ * Usage (session-end Phase 5 issue-close step) — ONE command strips, closes
+ * and verifies every resolved issue:
  *
- *   import { stripStatusLabels } from '${PLUGIN_ROOT}/scripts/lib/issue-close-strip-labels.mjs';
+ *   node scripts/lib/issue-close-strip-labels.mjs --close --vcs gitlab 1388 1387
  *
- *   const { stripped, error } = await stripStatusLabels({ issueId: 42, vcs: 'gitlab' });
- *   if (error) console.warn(`⚠ label strip failed for #${issueId}: ${error}`);
- *   else if (stripped.length) console.log(`Stripped ${stripped.join(', ')} from #${issueId}`);
- *   // then close the issue with glab/gh as usual
+ * It prints one JSON line per id and exits 1 when any id did not verify as
+ * closed. The mechanical call exists because the earlier prose-only step
+ * ("call stripStatusLabels, then close") was skipped often enough that 339
+ * closed issues still carried `status:in-progress` (measured 2026-09-19).
+ * `closeIssues()` is the same sequence as a library call; `stripStatusLabels()`
+ * stays exported for callers that only strip.
  *
  * Auto-created by `scripts/lib/issue-close-strip-labels.mjs` (#308).
  */
 
 import { execFileSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { isMainModule } from './is-main-module.mjs';
 import { resolveRepoSpec } from './vcs-repo-spec.mjs';
 
 /** Regex that matches any `status:*` label name. */
@@ -43,11 +48,12 @@ const STATUS_LABEL_RE = /^status:/;
  *
  * @param {string} cmd
  * @param {string[]} args
+ * @param {typeof execFileSync} [execFile] injectable executor (tests)
  * @returns {{ ok: boolean, stdout: string, stderr: string }}
  */
-function runCli(cmd, args) {
+function runCli(cmd, args, execFile = execFileSync) {
   try {
-    const stdout = execFileSync(cmd, args, {
+    const stdout = execFile(cmd, args, {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -61,50 +67,50 @@ function runCli(cmd, args) {
 }
 
 /**
- * Fetch the label names currently applied to an issue.
+ * Read an issue as JSON via `glab issue view --output json` (every field) or
+ * `gh issue view --json <ghFields>` (only the named fields).
  *
- * @param {{ issueId: number | string, vcs: 'gitlab' | 'github', spec?: string }} opts
+ * @param {{ issueId: string, vcs: 'gitlab' | 'github', spec?: string,
+ *   ghFields: string, execFile?: typeof execFileSync }} opts
  *   `spec` is the resolved `-R`/`--repo` host-pinning value (#839); omitted
  *   (undefined) means no `-R` is appended — never emit `-R undefined`.
- * @returns {{ ok: boolean, labels: string[], stderr: string }}
+ * @returns {{ ok: boolean, data: any, stderr: string }}
  */
-function fetchLabels({ issueId, vcs, spec }) {
-  const id = String(issueId);
-
-  if (vcs === 'github') {
-    // `gh issue view <NUMBER> --json labels` returns { labels: [{name, ...}] }
-    const args = ['issue', 'view', id, '--json', 'labels'];
-    if (spec) args.push('-R', spec);
-    const res = runCli('gh', args);
-    if (!res.ok) return { ok: false, labels: [], stderr: res.stderr };
-    let parsed;
-    try {
-      parsed = JSON.parse(res.stdout);
-    } catch (e) {
-      return { ok: false, labels: [], stderr: `JSON parse failed: ${e && e.message ? e.message : String(e)}` };
-    }
-    const labels = Array.isArray(parsed?.labels)
-      ? parsed.labels.map((l) => (typeof l?.name === 'string' ? l.name : String(l))).filter(Boolean)
-      : [];
-    return { ok: true, labels, stderr: '' };
-  }
-
-  // Default: gitlab via glab.
-  // `glab issue view <IID> --output json` returns an issue object with a `labels` array.
-  const args = ['issue', 'view', id, '--output', 'json'];
+function viewIssueJson({ issueId, vcs, spec, ghFields, execFile }) {
+  const args =
+    vcs === 'github'
+      ? ['issue', 'view', issueId, '--json', ghFields]
+      : ['issue', 'view', issueId, '--output', 'json'];
   if (spec) args.push('-R', spec);
-  const res = runCli('glab', args);
-  if (!res.ok) return { ok: false, labels: [], stderr: res.stderr };
-  let parsed;
+  const res = runCli(vcs === 'github' ? 'gh' : 'glab', args, execFile);
+  if (!res.ok) return { ok: false, data: null, stderr: res.stderr };
   try {
-    parsed = JSON.parse(res.stdout);
+    return { ok: true, data: JSON.parse(res.stdout), stderr: '' };
   } catch (e) {
-    return { ok: false, labels: [], stderr: `JSON parse failed: ${e && e.message ? e.message : String(e)}` };
+    return {
+      ok: false,
+      data: null,
+      stderr: `JSON parse failed: ${e && e.message ? e.message : String(e)}`,
+    };
   }
-  // GitLab JSON shape: { labels: ["status:ready", "priority::high", ...] }
-  const labels = Array.isArray(parsed?.labels)
-    ? parsed.labels.map((l) => (typeof l === 'string' ? l : String(l))).filter(Boolean)
-    : [];
+}
+
+/**
+ * Fetch the label names currently applied to an issue.
+ *
+ * GitHub shape: `{ labels: [{ name }] }`; GitLab shape: `{ labels: ["status:ready", ...] }`.
+ *
+ * @param {{ issueId: string, vcs: 'gitlab' | 'github', spec?: string, execFile?: typeof execFileSync }} opts
+ * @returns {{ ok: boolean, labels: string[], stderr: string }}
+ */
+function fetchLabels({ issueId, vcs, spec, execFile }) {
+  const { ok, data, stderr } = viewIssueJson({ issueId, vcs, spec, ghFields: 'labels', execFile });
+  if (!ok) return { ok: false, labels: [], stderr };
+  const toName =
+    vcs === 'github'
+      ? (l) => (typeof l?.name === 'string' ? l.name : String(l))
+      : (l) => (typeof l === 'string' ? l : String(l));
+  const labels = Array.isArray(data?.labels) ? data.labels.map(toName).filter(Boolean) : [];
   return { ok: true, labels, stderr: '' };
 }
 
@@ -119,12 +125,14 @@ function fetchLabels({ issueId, vcs, spec }) {
  *   issueId: number | string,
  *   vcs?: 'gitlab' | 'github',
  *   repoRoot?: string,
- *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab' | 'github' }) => string | undefined
+ *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab' | 'github' }) => string | undefined,
+ *   execFile?: typeof execFileSync
  * }} opts
  *   `repoRoot` defaults to `process.cwd()`. `resolveRepoSpecFn` is the
  *   injectable seam for the `-R`/`--repo` host-pinning resolution (#839) —
  *   defaults to the real `resolveRepoSpec` (shells out to `git remote
- *   get-url`); tests inject a stub instead of shelling out.
+ *   get-url`); tests inject a stub instead of shelling out. `execFile`
+ *   (default `execFileSync`) runs every glab/gh call.
  * @returns {Promise<{ stripped: string[], error?: string }>}
  */
 export async function stripStatusLabels({
@@ -132,6 +140,7 @@ export async function stripStatusLabels({
   vcs = 'gitlab',
   repoRoot = process.cwd(),
   resolveRepoSpecFn = resolveRepoSpec,
+  execFile = execFileSync,
 } = {}) {
   try {
     const id = String(issueId ?? '').trim();
@@ -146,7 +155,7 @@ export async function stripStatusLabels({
     const spec = resolveRepoSpecFn({ repoRoot, vcs: vcsResolved });
 
     // Step 1: fetch current labels.
-    const { ok, labels, stderr } = fetchLabels({ issueId: id, vcs: vcsResolved, spec });
+    const { ok, labels, stderr } = fetchLabels({ issueId: id, vcs: vcsResolved, spec, execFile });
     if (!ok) {
       return { stripped: [], error: `failed to fetch labels: ${stderr}` };
     }
@@ -167,13 +176,13 @@ export async function stripStatusLabels({
         args.push('--remove-label', label);
       }
       if (spec) args.push('-R', spec);
-      stripRes = runCli('gh', args);
+      stripRes = runCli('gh', args, execFile);
     } else {
       // `glab issue update <IID> --unlabel label1,label2,...`
       // glab accepts comma-separated list in a single --unlabel flag value.
       const args = ['issue', 'update', id, '--unlabel', toStrip.join(',')];
       if (spec) args.push('-R', spec);
-      stripRes = runCli('glab', args);
+      stripRes = runCli('glab', args, execFile);
     }
 
     if (!stripRes.ok) {
@@ -189,3 +198,152 @@ export async function stripStatusLabels({
     return { stripped: [], error: msg };
   }
 }
+
+/**
+ * Strip `status:*` labels, close, and VERIFY the close for each issue id — in
+ * that order, one id at a time.
+ *
+ * `closed` is true only when a re-read of the issue AFTER the close says
+ * `state: closed` (GitLab `closed`, GitHub `CLOSED`). The close command's own
+ * exit status is not trusted: a wrong project or a silent 404 can exit 0 while
+ * closing nothing (gitlab-ops skill, "Close verification"). The re-read runs
+ * even when the close command failed, so an issue that was already closed
+ * reports `closed: true` alongside the close `error`.
+ *
+ * A strip failure is non-fatal: it is reported as `stripError` and the close
+ * still runs. An id that is not a positive integer (an optional leading `#` is
+ * accepted) gets no CLI call at all — a value starting with `-` would
+ * otherwise reach glab/gh as a flag.
+ *
+ * @param {{
+ *   ids: Array<number | string>,
+ *   vcs?: 'gitlab' | 'github',
+ *   repo?: string,
+ *   repoRoot?: string,
+ *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab' | 'github' }) => string | undefined,
+ *   execFile?: typeof execFileSync
+ * }} opts
+ *   `repo` overrides the `-R`/`--repo` spec; otherwise it is resolved once via
+ *   `resolveRepoSpecFn` exactly as `stripStatusLabels` does (#839).
+ * @returns {Promise<Array<{ id: string, stripped: string[], stripError?: string,
+ *   closed: boolean, state: string | null, error?: string }>>}
+ */
+export async function closeIssues({
+  ids = [],
+  vcs = 'gitlab',
+  repo,
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
+  execFile = execFileSync,
+} = {}) {
+  const vcsResolved = vcs === 'github' ? 'github' : 'gitlab';
+  const spec = repo?.trim() || resolveRepoSpecFn({ repoRoot, vcs: vcsResolved });
+  const cli = vcsResolved === 'github' ? 'gh' : 'glab';
+  const results = [];
+
+  for (const rawId of ids) {
+    const id = String(rawId ?? '')
+      .trim()
+      .replace(/^#/, '');
+    if (!/^[1-9]\d*$/.test(id)) {
+      results.push({
+        id: String(rawId),
+        stripped: [],
+        closed: false,
+        state: null,
+        error: 'invalid issue id',
+      });
+      continue;
+    }
+    const result = { id, stripped: [], closed: false, state: null };
+
+    // 1. strip — non-fatal. The resolved spec is handed through so strip,
+    //    close and verify all pin the same repo.
+    const strip = await stripStatusLabels({
+      issueId: id,
+      vcs: vcsResolved,
+      resolveRepoSpecFn: () => spec,
+      execFile,
+    });
+    result.stripped = strip.stripped;
+    if (strip.error) result.stripError = strip.error;
+
+    // 2. close
+    const closeArgs = ['issue', 'close', id];
+    if (spec) closeArgs.push('-R', spec);
+    const closeRes = runCli(cli, closeArgs, execFile);
+    const errors = closeRes.ok
+      ? []
+      : [`close failed: ${closeRes.stderr.trim() || 'unknown error'}`];
+
+    // 3. verify — the platform's state is the only evidence of a close.
+    const view = viewIssueJson({
+      issueId: id,
+      vcs: vcsResolved,
+      spec,
+      ghFields: 'state',
+      execFile,
+    });
+    if (view.ok) {
+      result.state = typeof view.data?.state === 'string' ? view.data.state : null;
+      result.closed = result.state?.toLowerCase() === 'closed';
+      if (!result.closed) {
+        errors.push(`verify: issue state is ${result.state ?? 'unknown'}, not closed`);
+      }
+    } else {
+      errors.push(`verify failed: ${view.stderr.trim() || 'unknown error'}`);
+    }
+    if (errors.length) result.error = errors.join('; ');
+    results.push(result);
+  }
+  return results;
+}
+
+const USAGE =
+  'usage: issue-close-strip-labels.mjs --close [--vcs gitlab|github] [-R|--repo <spec>] <id>...';
+
+/**
+ * CLI: `--close [--vcs gitlab|github] [-R <spec>] <id>...` — one JSON line per
+ * id on stdout. Exit 0 = every id verified closed, 1 = at least one did not,
+ * 2 = usage error (no GitLab/GitHub call made).
+ *
+ * @param {string[]} [argv]
+ * @returns {Promise<number>} exit code
+ */
+async function main(argv = process.argv.slice(2)) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        close: { type: 'boolean', default: false },
+        vcs: { type: 'string', default: 'gitlab' },
+        repo: { type: 'string', short: 'R' },
+      },
+    });
+  } catch (err) {
+    process.stderr.write(`${err?.message ?? err}\n${USAGE}\n`);
+    return 2;
+  }
+  const { values, positionals } = parsed;
+  if (!values.close || positionals.length === 0 || !['gitlab', 'github'].includes(values.vcs)) {
+    process.stderr.write(`${USAGE}\n`);
+    return 2;
+  }
+
+  const results = await closeIssues({ ids: positionals, vcs: values.vcs, repo: values.repo });
+  for (const r of results) {
+    if (r.stripError) {
+      process.stderr.write(
+        `⚠ label strip failed for #${r.id}: ${r.stripError} — close attempted anyway\n`,
+      );
+    }
+    process.stdout.write(`${JSON.stringify(r)}\n`);
+  }
+  return results.every((r) => r.closed) ? 0 : 1;
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = await main();
+}

package/scripts/lib/js-mask.mjs

@@ -0,0 +1,197 @@
+// js-mask.mjs — ONE JavaScript lexer for every "blank the comments / separate
+// code from data" scanner in this repo.
+//
+// WHY IT LIVES HERE. `maskSource` grew inside
+// `scripts/lib/validate/check-untracked-test-deps.mjs`, where it is used to
+// separate CODE from DATA. Three OTHER modules had hand-rolled
+// `stripComments` copies with NO regex-literal branch, and each one was
+// measurably wrong for the same input shape (`/\/*$/` — a regex whose body
+// contains `/*`), measured 2026-09-18 @ 20a4cbff:
+//   - `check-validator-registration.mjs` — the regex's `/*` opened a block
+//     comment that swallowed the rest of the surface text → a FALSE
+//     "UNREGISTERED" finding.
+//   - `check-test-git-config-target.mjs` — same swallow inside a call tail →
+//     `wrapperHasCwd` returned false → a false alarm.
+//   - `auq/parse.mjs` — the swallowed region no longer contained
+//     `(Recommended)` → a silent FALSE NEGATIVE in the AUQ clarity measurement.
+// One lexer, five consumers: the regex branch and its three named ceilings are
+// maintained once.
+//
+// Import-safety: importing this module executes nothing.
+
+/**
+ * Keywords after which a `/` opens a REGEX LITERAL, never a division. The
+ * single-character `prev` below cannot tell `return /x/` from `n / x`, because
+ * the character it sees (`n`) is a word character in both. This set is the
+ * one-token lookback that closes the difference; it is deliberately the usual
+ * short list rather than a parser (BV-001.6/BV-004 — a full expression parser
+ * for a masker is the abstraction this file exists to avoid).
+ *
+ * Named ceiling (BV-004), in the other direction: a genuine DIVISION CHAIN after
+ * one of these words (`return a / b / c`) is now read as a regex and its middle
+ * blanked. Measured 2026-09-18 over `git ls-files '*.mjs'` (1245 files): 0
+ * occurrences — all 18 files whose masking this lookback changes carry a real
+ * `return /…/` literal. REVISIT TRIGGER: the first such division chain.
+ */
+const REGEX_PRECEDING_KEYWORDS = new Set([
+  'return', 'typeof', 'case', 'in', 'of', 'new', 'delete', 'void', 'yield',
+  'await', 'instanceof', 'do', 'else',
+]);
+
+/** Word characters, for the one-token lookback above. */
+const WORD_CHAR_RE = /[A-Za-z0-9_$]/;
+
+/**
+ * Blank out the INTERIOR of every string literal, template literal, comment and
+ * regex literal, preserving byte offsets and newlines. Delimiters are kept so
+ * paren/comma balance and identifier boundaries survive.
+ *
+ * This is what separates CODE from DATA. A test that embeds fixture source in a
+ * template literal (`check-untracked-test-deps.mjs`'s own test file does) must
+ * not be scanned as though that fixture were its own body — masking makes that
+ * structural instead of relying on a self-exemption marker.
+ *
+ * With `keepLiterals: true` only COMMENTS are blanked: string, template and
+ * regex literals are still recognised (so a `//` or `/*` inside one is never read
+ * as a comment, and a quote inside a regex never opens a string) but their
+ * contents stay intact. `check-entry-guard.mjs` needs exactly that — it must see
+ * `endsWith('x.mjs')` and `${process.argv[1]}` verbatim (#1383) — and it is the
+ * mode the three `stripComments` consumers delegate in (#1388).
+ *
+ * @param {string} text
+ * @param {{ keepLiterals?: boolean }} [options]
+ * @returns {string} same-length masked source
+ */
+export function maskSource(text, { keepLiterals = false } = {}) {
+  const out = text.split('');
+  const n = out.length;
+  let i = 0;
+  // Last significant (non-space) char before `i`, and its offset, used for the
+  // regex/division disambiguation below (the offset carries the one-token
+  // keyword lookback).
+  let prev = '';
+  let prevIdx = -1;
+
+  /** The whole word ending at `idx`, or '' when `idx` is not a word char. */
+  const wordEndingAt = (idx) => {
+    if (idx < 0 || !WORD_CHAR_RE.test(text[idx])) return '';
+    let k = idx;
+    while (k > 0 && WORD_CHAR_RE.test(text[k - 1])) k--;
+    return text.slice(k, idx + 1);
+  };
+
+  const blank = (from, to) => {
+    for (let k = from; k < to && k < n; k++) if (out[k] !== '\n') out[k] = ' ';
+  };
+  // Literal interiors go through this one; comments always use `blank`.
+  const blankLiteral = keepLiterals ? () => {} : blank;
+
+  while (i < n) {
+    const c = text[i];
+    const next = text[i + 1];
+
+    // Line comment.
+    if (c === '/' && next === '/') {
+      let j = i;
+      while (j < n && text[j] !== '\n') j++;
+      blank(i, j);
+      i = j;
+      continue;
+    }
+    // Block comment — ONLY when it is actually closed.
+    //
+    // Named ceiling (BV-004), replacing an unbounded blank: an UNTERMINATED
+    // `/*` used to blank everything to EOF. In valid source that shape is a
+    // syntax error, so in practice it only ever arises from a lexer desync —
+    // a `/*` inside a regex literal the branch below failed to recognise
+    // (`return /\/*$/`). Blanking the rest of the file then hides every guard
+    // under it, which is a validator falling SILENT. The direction is therefore
+    // chosen fail-toward-REPORTING: an unclosed `/*` is not a comment at all,
+    // and the few bytes of a genuine one get scanned as code — at worst that
+    // produces a finding a human dismisses, never a silent pass.
+    // REVISIT TRIGGER: a tracked file that legitimately ends inside an
+    // unterminated block comment (i.e. the moment `node --check` accepts one).
+    if (c === '/' && next === '*') {
+      let j = i + 2;
+      while (j < n && !(text[j] === '*' && text[j + 1] === '/')) j++;
+      if (j < n) {
+        blank(i, j + 2);
+        i = j + 2;
+        continue;
+      }
+      // Unterminated — fall through and treat the `/` as ordinary source.
+    }
+    // Single/double-quoted string — keep the quotes, blank the interior.
+    if (c === "'" || c === '"') {
+      let j = i + 1;
+      while (j < n && text[j] !== c) {
+        if (text[j] === '\\') j++;
+        if (text[j] === '\n') break; // unterminated — bail at EOL
+        j++;
+      }
+      blankLiteral(i + 1, j);
+      i = Math.min(j + 1, n);
+      prev = c;
+      prevIdx = i - 1;
+      continue;
+    }
+    // Template literal — blank everything including `${…}` substitutions.
+    if (c === '`') {
+      let j = i + 1;
+      while (j < n && text[j] !== '`') {
+        if (text[j] === '\\') j++;
+        j++;
+      }
+      blankLiteral(i + 1, j);
+      i = Math.min(j + 1, n);
+      prev = c;
+      prevIdx = i - 1;
+      continue;
+    }
+    // Regex literal — only when the previous significant TOKEN cannot end an
+    // expression, AND a closing unescaped `/` exists on the SAME line. The
+    // same-line bound keeps a misread division from swallowing the file.
+    //
+    // The token is either the single char `prev`, or — when that char is a word
+    // character — the whole word ending at it, checked against
+    // REGEX_PRECEDING_KEYWORDS. Without that lookback `return /\/*$/` read as a
+    // division and its `/*` reached the block-comment branch above, which blanked
+    // the rest of the file: a validator silently passing (measured 2026-09-18).
+    //
+    // Named ceiling (BV-004): the lookback is exactly ONE token. A regex after
+    // any other non-expression-ending context — a `)` that closes `if (…)`, a
+    // statement label, `function` — is still read as division and its body
+    // scanned as code. That desync is now bounded on BOTH sides: a quote in it
+    // opens a string that bails at EOL, and a `/*` in it no longer blanks past
+    // the file (unterminated block comments are not comments — see above).
+    // REVISIT TRIGGER: a census finding that needs `)`-aware lookback, i.e. a
+    // regex used directly as the body of `if (…) /re/.test(x)`.
+    const startsRegex = c === '/' && (
+      prev === '' || '(,=:[!&|?{};+-*%~^<>'.includes(prev)
+      || REGEX_PRECEDING_KEYWORDS.has(wordEndingAt(prevIdx))
+    );
+    if (startsRegex) {
+      let j = i + 1;
+      let inClass = false;
+      let closed = -1;
+      while (j < n && text[j] !== '\n') {
+        if (text[j] === '\\') { j += 2; continue; }
+        if (text[j] === '[') inClass = true;
+        else if (text[j] === ']') inClass = false;
+        else if (text[j] === '/' && !inClass) { closed = j; break; }
+        j++;
+      }
+      if (closed > i) {
+        blankLiteral(i + 1, closed);
+        i = closed + 1;
+        prev = '/';
+        prevIdx = closed;
+        continue;
+      }
+    }
+
+    if (!/\s/.test(c)) { prev = c; prevIdx = i; }
+    i++;
+  }
+  return out.join('');
+}

package/scripts/lib/learnings/evolve-telemetry.mjs

@@ -11,13 +11,17 @@
  * a CODE call site instead: `emitEvolveCompleted()` is invoked from
  * `scripts/sweep-expired-learnings.mjs`'s `--prune` exit path (the ONE store
  * write `/evolve analyze` already performs), and `recordDialecticRun()` is
- * invoked from `scripts/dialectic-deriver.mjs::runDialecticDeriver()` for the
- * three abort statuses it can determine on its own, plus dry-run success —
- * see that module's header for why APPLY-mode success and the two
- * throw-based abort classes (`unknown-model`, `subagent-crash`) still call
- * `recordDialecticRun()` from `skills/evolve/SKILL.md` prose (the merge and
- * the dispatch-agent try/catch both happen one layer up, outside this pure
- * pipeline).
+ * invoked from `scripts/dialectic-deriver.mjs::runDialecticDeriver()` for
+ * every outcome that pipeline can determine on its own: the `ok`/abort
+ * returns (`empty-input`, `budget-exceeded`, `would-empty-card`, dry-run
+ * success) AND the two throw-based abort classes (`unknown-model`,
+ * `subagent-crash`), the latter via that module's `recordThrownAbort()`
+ * helper which records at the throw point before the original error is
+ * rethrown. Only APPLY-mode success still calls `recordDialecticRun()` from
+ * `skills/evolve/SKILL.md` prose (Step 6.4 of
+ * `skills/evolve/references/evolve-dialectic-mode.md`) — the merge
+ * (`mergePeerCard()`) happens one layer up, outside this pure pipeline, so the
+ * real merge-stats deltas are not knowable inside `runDialecticDeriver()`.
  *
  * Both emitters are best-effort and try/catch-wrapped — same posture as
  * `emitReconcileCompleted` in `scripts/lib/reconcile/engine.mjs` — because

package/scripts/lib/locks/index.mjs

@@ -1,31 +1,38 @@
 /**
- * locks/index.mjs — convenience barrel for the short-lived lock protocols split
- * out of session-lock.mjs in #630 (A1 barrel-preserving split).
+ * locks/index.mjs — DEPRECATED convenience barrel for the lock protocols
+ * split out of session-lock.mjs in #630 (A1 barrel-preserving split).
  *
- * Re-exports both protocol modules so a consumer can `import { withStateMdLock,
- * withStagingFenceLock } from '@lib/locks/index.mjs'` in one statement. This is
- * a nice-to-have: session-lock.mjs remains the canonical barrel that preserves
- * the original 22-symbol import surface, and the two protocol modules are also
- * importable directly.
+ * @deprecated since 5.2.0, removed in 6.0.0. Import directly from
+ * `./state-md-lock.mjs` / `./staging-fence-lock.mjs`, or from
+ * `scripts/lib/session-lock.mjs` for the canonical 22-symbol barrel that
+ * preserves the original import surface for all its importers.
  *
- * Pure re-export leaf — imports only the two sibling modules, never
- * session-lock.mjs, so there is no import cycle.
+ * This file shipped in 5.1.0 with zero in-repo importers and was deleted in
+ * dd05e0f8 (`check-unwired-features` S4: no hook, npm script, CI job or husky
+ * stage reached it, and it named symbols — not modules — so it did not qualify
+ * for the pure `export *` exemption that shape gets). Restored here as a
+ * one-cycle deprecation shim (`.claude/rules/development.md` § Package Lifecycle
+ * & Versioning) because `package.json` carries no `exports` map: every packed
+ * file under `scripts/lib/` is public, so a consumer that deep-imported this
+ * path before the deletion has no compile error to warn it, only a runtime
+ * "module not found" — a shim buys that consumer one minor cycle to migrate
+ * before 6.0.0 removes the path outright.
+ *
+ * Deliberately the `export *` form with ZERO named exports (matches the
+ * `scripts/lib/autopilot-telemetry.mjs` precedent): a named-export re-export
+ * barrel is exactly the shape `check-unwired-features.mjs` S4 flags as an
+ * unreachable library module (condition 4 in `collectUnreachableLibraryModules`
+ * requires named exports before a re-export shim over live code enters that
+ * census) — that flag is what got this file deleted the first time. A star
+ * re-export names no symbol, so the shim reads as `exports: []` and stays
+ * invisible to that census while its target modules stay reachable through it.
  */
 
-export {
-  STATE_LOCK_PATH,
-  DEFAULT_STATE_LOCK_TIMEOUT_MS,
-  STATE_LOCK_POLL_MS,
-  acquireStateLock,
-  releaseStateLock,
-  withStateMdLock,
-} from './state-md-lock.mjs';
+console.warn(
+  '[deprecated] scripts/lib/locks/index.mjs is deprecated since 5.2.0 and will be removed in 6.0.0 — ' +
+    "import from './state-md-lock.mjs' / './staging-fence-lock.mjs' directly, or from " +
+    'scripts/lib/session-lock.mjs for the canonical surface.',
+);
 
-export {
-  STAGING_FENCE_LOCK_PATH,
-  DEFAULT_STAGING_FENCE_LOCK_TIMEOUT_MS,
-  STAGING_FENCE_LOCK_POLL_MS,
-  acquireStagingFenceLock,
-  releaseStagingFenceLock,
-  withStagingFenceLock,
-} from './staging-fence-lock.mjs';
+export * from './state-md-lock.mjs';
+export * from './staging-fence-lock.mjs';