atris 3.46.1 → 3.48.0

package/lib/ci-runner.js

@@ -25,6 +25,14 @@ function clockDate(clock) {
   return date;
 }
 
+function parseRunnerMarker(line) {
+  const text = String(line);
+  if (text.includes('Running job:')) return { type: 'start' };
+  const completed = text.match(/completed with result:\s*([a-z]+)/i);
+  if (completed) return { type: 'complete', result: completed[1].toLowerCase() };
+  return null;
+}
+
 function runnerAssetName(platform, arch, version = RUNNER_VERSION) {
   const platformNames = { darwin: 'osx', linux: 'linux' };
   const archNames = { x64: 'x64', arm64: 'arm64' };
@@ -53,14 +61,19 @@ function parseRepo(value) {
 
 function parseRunnerArgs(argv) {
   const options = { label: null, once: false };
-  let repoValue = null;
+  const repos = [];
+  const seenRepos = new Set();
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === '--repo') {
-      if (repoValue !== null) throw new Error('--repo may only be set once');
-      repoValue = argv[index + 1];
+      const repoValue = argv[index + 1];
       if (!repoValue || repoValue.startsWith('--')) throw new Error('--repo owner/name is required');
+      const repo = parseRepo(repoValue);
+      const key = repo.slug.toLowerCase();
+      if (seenRepos.has(key)) throw new Error(`duplicate --repo: ${repo.slug}`);
+      seenRepos.add(key);
+      repos.push(repo);
       index += 1;
     } else if (arg === '--label') {
       if (options.label !== null) throw new Error('--label may only be set once');
@@ -78,7 +91,8 @@ function parseRunnerArgs(argv) {
     }
   }
 
-  return { repo: parseRepo(repoValue), label: options.label, once: options.once };
+  if (repos.length === 0) throw new Error('--repo owner/name is required');
+  return { repos, label: options.label, once: options.once };
 }
 
 function parseUsageArgs(argv) {
@@ -143,6 +157,11 @@ function summarizeUsage(records, options = {}) {
     const repo = repos.get(record.repo) || { repo: record.repo, jobs: 0, minutes: 0 };
     repo.jobs += 1;
     repo.minutes += minutes;
+    if (typeof record.result === 'string' && /^[a-z]+$/i.test(record.result)) {
+      if (!repo.results) repo.results = {};
+      const result = record.result.toLowerCase();
+      repo.results[result] = (repo.results[result] || 0) + 1;
+    }
     repos.set(record.repo, repo);
   }
 
@@ -161,10 +180,25 @@ function formatUsageSummary(summary) {
     `total minutes: ${summary.totalMinutes}`,
     `minutes this month: ${summary.monthMinutes}`,
     'per repo:',
-    ...summary.repos.map((repo) => (
-      `${repo.repo}: ${repo.jobs} ${repo.jobs === 1 ? 'job' : 'jobs'}, `
-      + `${repo.minutes} ${repo.minutes === 1 ? 'minute' : 'minutes'}`
-    )),
+    ...summary.repos.map((repo) => {
+      const resultOrder = ['succeeded', 'failed', 'cancelled', 'skipped'];
+      const results = repo.results
+        ? Object.entries(repo.results).sort(([left], [right]) => {
+          const leftIndex = resultOrder.indexOf(left);
+          const rightIndex = resultOrder.indexOf(right);
+          if (leftIndex !== -1 || rightIndex !== -1) {
+            return (leftIndex === -1 ? resultOrder.length : leftIndex)
+              - (rightIndex === -1 ? resultOrder.length : rightIndex);
+          }
+          return left.localeCompare(right);
+        })
+        : [];
+      return [
+        `${repo.repo}: ${repo.jobs} ${repo.jobs === 1 ? 'job' : 'jobs'}`,
+        ...results.map(([result, count]) => `${count} ${result}`),
+        `${repo.minutes} ${repo.minutes === 1 ? 'minute' : 'minutes'}`,
+      ].join(', ');
+    }),
   ].join('\n');
 }
 
@@ -314,21 +348,130 @@ async function ensureRunner(options = {}) {
   return runnerDir;
 }
 
-function runWorker(runnerDir, jitConfig, start = spawn) {
+function linkRunnerTree(source, destination) {
+  fs.mkdirSync(destination, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = path.join(source, entry.name);
+    const destinationPath = path.join(destination, entry.name);
+    if (fs.existsSync(destinationPath)) continue;
+    if (entry.isDirectory()) {
+      linkRunnerTree(sourcePath, destinationPath);
+    } else if (entry.isSymbolicLink()) {
+      fs.symlinkSync(fs.readlinkSync(sourcePath), destinationPath);
+    } else {
+      try {
+        fs.linkSync(sourcePath, destinationPath);
+      } catch (error) {
+        if (!error || error.code !== 'EXDEV') throw error;
+        fs.copyFileSync(sourcePath, destinationPath);
+      }
+    }
+  }
+}
+
+function ensureRepoRunnerDirectory(runnerDir, repo) {
+  const destination = path.join(runnerDir, 'repos', repo.owner.toLowerCase(), repo.repo.toLowerCase());
+  if (fs.existsSync(path.join(destination, 'run.sh'))) return destination;
+  fs.mkdirSync(destination, { recursive: true });
+  const ignored = new Set([
+    '.credentials',
+    '.credentials_rsaparams',
+    '.runner',
+    '.service',
+    '_diag',
+    '_work',
+    'repos',
+  ]);
+  for (const entry of fs.readdirSync(runnerDir, { withFileTypes: true })) {
+    if (ignored.has(entry.name)) continue;
+    const sourcePath = path.join(runnerDir, entry.name);
+    const destinationPath = path.join(destination, entry.name);
+    if (fs.existsSync(destinationPath)) continue;
+    if (entry.isDirectory()) {
+      linkRunnerTree(sourcePath, destinationPath);
+    } else if (entry.isSymbolicLink()) {
+      fs.symlinkSync(fs.readlinkSync(sourcePath), destinationPath);
+    } else {
+      try {
+        fs.linkSync(sourcePath, destinationPath);
+      } catch (error) {
+        if (!error || error.code !== 'EXDEV') throw error;
+        fs.copyFileSync(sourcePath, destinationPath);
+      }
+    }
+  }
+  if (!fs.existsSync(path.join(destination, 'run.sh'))) {
+    throw new Error('github actions runner cache did not contain run.sh');
+  }
+  return destination;
+}
+
+function forwardRunnerStream(stream, output, prefix, inspectLine) {
+  if (!stream) return;
+  let pending = '';
+  stream.setEncoding('utf8');
+  stream.on('data', (chunk) => {
+    pending += chunk;
+    let newline = pending.indexOf('\n');
+    while (newline !== -1) {
+      const line = pending.slice(0, newline).replace(/\r$/, '');
+      pending = pending.slice(newline + 1);
+      inspectLine(line);
+      output.write(`${prefix}${line}\n`);
+      newline = pending.indexOf('\n');
+    }
+  });
+  stream.on('end', () => {
+    if (!pending) return;
+    const line = pending.replace(/\r$/, '');
+    inspectLine(line);
+    output.write(`${prefix}${line}`);
+  });
+}
+
+function runWorker(runnerDir, jitConfig, options = {}) {
   return new Promise((resolve, reject) => {
-    const child = start('./run.sh', ['--jitconfig', jitConfig], {
+    const clock = options.clock || (() => new Date());
+    const child = (options.start || spawn)('./run.sh', ['--jitconfig', jitConfig], {
       cwd: runnerDir,
       env: process.env,
-      stdio: 'inherit',
+      stdio: ['inherit', 'pipe', 'pipe'],
     });
-    child.on('error', reject);
-    child.on('exit', (code, signal) => {
+    let startedAt = null;
+    let finishedAt = null;
+    let result = null;
+    let settled = false;
+    const measurement = () => ({ startedAt, finishedAt, result });
+    const inspectLine = (line) => {
+      const marker = parseRunnerMarker(line);
+      if (!marker) return;
+      if (marker.type === 'start' && !startedAt) startedAt = clockDate(clock);
+      if (marker.type === 'complete' && !finishedAt) {
+        finishedAt = clockDate(clock);
+        result = marker.result;
+      }
+    };
+    forwardRunnerStream(child.stdout, options.stdout || process.stdout, options.prefix || '', inspectLine);
+    forwardRunnerStream(child.stderr, options.stderr || process.stderr, options.prefix || '', inspectLine);
+    child.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      error.ciUsage = measurement();
+      reject(error);
+    });
+    child.on('close', (code, signal) => {
+      if (settled) return;
+      settled = true;
       if (code === 0) {
-        resolve();
+        resolve(measurement());
       } else if (signal) {
-        reject(new Error(`github actions runner stopped with signal ${signal}`));
+        const error = new Error(`github actions runner stopped with signal ${signal}`);
+        error.ciUsage = measurement();
+        reject(error);
       } else {
-        reject(new Error(`github actions runner exited with code ${code}`));
+        const error = new Error(`github actions runner exited with code ${code}`);
+        error.ciUsage = measurement();
+        reject(error);
       }
     });
   });
@@ -348,20 +491,39 @@ async function runJobLoop(options, dependencies = {}) {
     const runnerName = `${options.runnerName}-${completedJobs + 1}`;
     const jitConfig = await mint(options.token, options.repo, options.label, runnerName);
     log(`worker ready, waiting for jobs on ${options.repo.slug}`);
-    const startedAt = clockDate(clock);
     let workerError = null;
+    let workerUsage = null;
     try {
-      await startWorker(options.runnerDir, jitConfig);
+      workerUsage = await startWorker(options.runnerDir, jitConfig, {
+        clock,
+        prefix: options.logPrefix || '',
+        start: dependencies.spawn,
+        stderr: dependencies.stderr,
+        stdout: dependencies.stdout,
+      });
     } catch (error) {
       workerError = error;
+      workerUsage = error && error.ciUsage;
     } finally {
-      const finishedAt = clockDate(clock);
-      const durationSeconds = Math.max(0, Math.ceil((finishedAt.getTime() - startedAt.getTime()) / 1000));
-      const line = `${JSON.stringify({
+      const markerStart = workerUsage && workerUsage.startedAt
+        ? clockDate(() => workerUsage.startedAt)
+        : null;
+      const markerFinish = workerUsage && workerUsage.finishedAt
+        ? clockDate(() => workerUsage.finishedAt)
+        : null;
+      const startedAt = markerStart || markerFinish || clockDate(clock);
+      const durationSeconds = markerStart && markerFinish
+        ? Math.max(0, Math.ceil((markerFinish.getTime() - markerStart.getTime()) / 1000))
+        : 0;
+      const record = {
         repo: options.repo.slug,
         started_at: startedAt.toISOString(),
         duration_seconds: durationSeconds,
-      })}\n`;
+      };
+      if (workerUsage && typeof workerUsage.result === 'string') {
+        record.result = workerUsage.result.toLowerCase();
+      }
+      const line = `${JSON.stringify(record)}\n`;
       await appendUsage(file, line);
     }
     if (workerError) throw workerError;
@@ -374,17 +536,42 @@ async function runCiRunner(options, dependencies = {}) {
   const token = (dependencies.resolveGithubToken || resolveGithubToken)();
   const runnerDir = await (dependencies.ensureRunner || ensureRunner)({ log: dependencies.log });
   const host = String((dependencies.hostname || os.hostname)()).toLowerCase().replace(/[^a-z0-9-]+/g, '-');
-  return runJobLoop({
-    ...options,
-    token,
-    runnerDir,
-    runnerName: `atris-${host || 'worker'}-${process.pid}`,
-  }, dependencies);
+  const log = dependencies.log || console.log;
+  const prepare = dependencies.ensureRepoRunnerDirectory || ensureRepoRunnerDirectory;
+  const startLoop = dependencies.runJobLoop || runJobLoop;
+  const manyRepos = options.repos.length > 1;
+  const loops = options.repos.map((repo, index) => (async () => {
+    const repoRunnerDir = await prepare(runnerDir, repo);
+    const repoLog = manyRepos ? (line) => log(`${repo.slug}: ${line}`) : log;
+    return startLoop({
+      ...options,
+      repo,
+      token,
+      runnerDir: repoRunnerDir,
+      runnerName: `atris-${host || 'worker'}-${process.pid}-${index + 1}`,
+      logPrefix: manyRepos ? `${repo.slug}: ` : '',
+    }, { ...dependencies, log: repoLog });
+  })());
+  const settled = await Promise.allSettled(loops);
+  const failures = settled
+    .map((outcome, index) => ({ outcome, repo: options.repos[index] }))
+    .filter(({ outcome }) => outcome.status === 'rejected');
+  for (const failure of failures) {
+    const detail = String(failure.outcome.reason?.message || failure.outcome.reason || 'runner loop failed')
+      .replace(/\s+/g, ' ')
+      .trim();
+    log(`${failure.repo.slug}: ${detail.toLowerCase()}`);
+  }
+  if (failures.length > 0) {
+    throw new Error(`${failures.length} ci runner ${failures.length === 1 ? 'loop' : 'loops'} failed`);
+  }
+  return settled.reduce((total, outcome) => total + outcome.value, 0);
 }
 
 module.exports = {
   buildJitConfigRequest,
   formatUsageSummary,
+  parseRunnerMarker,
   parseRunnerArgs,
   parseUsageArgs,
   readUsageRecords,

package/lib/engine-ask.js

@@ -9,7 +9,11 @@ const {
   DEFAULT_CLAUDE_RUNNER_MODEL,
   RUNNER_PROFILE_DEFS,
 } = require('./runner-command');
-const { canonicalEngineName } = require('./engine-registry');
+const {
+  canonicalEngineName,
+  engineFailureHealthStatus,
+  setEngineHealth,
+} = require('./engine-registry');
 const {
   appendEngineLiveLogChunk,
   createEngineLiveLog,
@@ -452,6 +456,15 @@ function answerStatus(answer) {
   return engineTerminalStatus(answer);
 }
 
+function recordEngineAskHealth(answers, root) {
+  for (const answer of answers) {
+    const status = answer.ok
+      ? 'ready'
+      : engineFailureHealthStatus({ ...answer, status: 'errored' });
+    if (status) setEngineHealth(answer.engine, status, root);
+  }
+}
+
 function engineAskReceipt(answers, { concurrency, timeoutMs, at = new Date().toISOString() }) {
   const receiptAnswers = answers.map((answer) => ({ ...answer, status: answerStatus(answer) }));
   const answered = receiptAnswers.filter((answer) => answer.status === 'answered').length;
@@ -582,6 +595,7 @@ async function runEngineAskCommand(args, root = process.cwd(), deps = {}) {
       signal: abort.signal,
       onOutputChunk: (chunk, stream) => appendLiveLog(liveLogPath, chunk, stream),
     });
+    recordEngineAskHealth(answers, root);
     const receipt = engineAskReceipt(answers, {
       concurrency: parsed.concurrency,
       timeoutMs: parsed.timeoutMs,

package/lib/engine-registry.js

@@ -16,6 +16,27 @@ const ENGINE_ROLES = Object.freeze(['navigator', 'executor', 'validator']);
 const ENGINE_DUTIES = Object.freeze(['leader', 'errands', 'learning']);
 const ENGINE_HEALTH_STATUSES = Object.freeze(['ready', 'not_installed', 'credit_out', 'error']);
 
+function engineFailureHealthStatus(result) {
+  if (!result || result.status !== 'errored') return null;
+  const signalText = [
+    result.reason,
+    result.model_unavailable,
+    result.report,
+    result.stdout,
+    result.stderr,
+    result.error,
+    result.claude && result.claude.summary,
+    result.claude && result.claude.receipt_text,
+    result.claude && result.claude.stderr,
+    result.rate_limit_info && JSON.stringify(result.rate_limit_info),
+  ].filter(Boolean).join('\n').toLowerCase();
+  if (/usage[ _-]?limit|purchase more credits|insufficient credits|credit(?:s)?[ _-]?(?:out|limit)|rate[ _-]?limit|not authenticated|please log in|login required|auth(?:entication)?[ _-]?expired|payment required|subscription/.test(signalText)) {
+    return 'credit_out';
+  }
+  if (/timeout|model-unavailable/.test(signalText)) return 'not_installed';
+  return 'error';
+}
+
 const ENGINE_SEED_META = Object.freeze({
   'atris-fast': Object.freeze({ tier: 'fast', roles: Object.freeze(['navigator']), models: Object.freeze(['atris fast']), duty: 'learning', fallback_order: 10 }),
   codex: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), models: Object.freeze(['codex']), fallback_order: 10 }),
@@ -356,6 +377,7 @@ module.exports = {
   resolveEngineForRoleRanked,
   resolveEngineForRole,
   resolveEngineForRoleWithPreference,
+  engineFailureHealthStatus,
   setEngineOverrides,
   setEngineHealth,
 };

package/lib/fleet.js

@@ -23,6 +23,7 @@ const {
   worktreeBaseRef,
 } = require('./brief-ledger');
 const { RUNNER_PROFILE_DEFS, buildRunnerCommand } = require('./runner-command');
+const { engineFailureHealthStatus, setEngineHealth } = require('./engine-registry');
 const { resolveDefaultVerifier } = require('./default-verifier');
 const { rankEnginesDetailed } = require('./router-brain');
 const {
@@ -560,6 +561,18 @@ function detectDeadEngineDispatch(result) {
   return { reason: 'nonzero_exit', exitCode };
 }
 
+function recordDispatchEngineHealth(result, failure, root) {
+  if (!result || !result.engine) return null;
+  const status = failure
+    ? engineFailureHealthStatus({
+      ...result,
+      status: 'errored',
+      reason: [result.reason, failure.reason].filter(Boolean).join('\n'),
+    })
+    : 'ready';
+  return status ? setEngineHealth(result.engine, status, root) : null;
+}
+
 function normalizeInstalledEngines(engines) {
   return [...new Set((engines || [])
     .map((entry) => (typeof entry === 'string' ? entry : entry && entry.name))
@@ -672,6 +685,7 @@ async function dispatchEntryWithRestaff({
 
   const first = await runOnce(engine);
   const deadEngine = detectDeadEngineDispatch(first);
+  recordDispatchEngineHealth(first, deadEngine, root);
   if (!deadEngine) return first;
   stampDispatchBrief(root, first.brief_id, 'fail', `restaffed from ${engine}: ${deadEngine.reason}`);
 
@@ -687,6 +701,7 @@ async function dispatchEntryWithRestaff({
 
   restaffState.used = true;
   const fallbackResult = await runOnce(fallback);
+  recordDispatchEngineHealth(fallbackResult, detectDeadEngineDispatch(fallbackResult), root);
   return {
     ...fallbackResult,
     restaffed: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.46.1",
+  "version": "3.48.0",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof.",
   "main": "bin/atris.js",
   "bin": {
@@ -14,6 +14,7 @@
     "commands/",
     "decks/",
     "scripts/agent_worktree.py",
+    "scripts/det/",
     "utils/",
     "lib/",
     "templates/",

package/scripts/det/README.md

@@ -0,0 +1,162 @@
+# Deterministic task scripts
+
+Small, zero-dependency scripts for jobs LLMs get asked to do constantly but that
+are actually deterministic: extracting, converting, counting, reformatting text,
+and drafting commit/PR text from git. A cheap model (or a human, or a cron) runs
+the script instead of spending tokens and risking a wrong guess. The output is
+exact and reproducible, not inferred.
+
+## Pick a tool (one read)
+
+Find the row that matches the ask, run the command. All paths are under
+`node scripts/det/`. Add `--json` to any script for structured output.
+
+| If the ask is… | Run | Modes / notes |
+|----------------|-----|---------------|
+| pull links / emails / code / numbers out of text | `extract.js <mode> < in` | `urls` `emails` `code` `numbers` `ipv4` `hashtags` |
+| reformat / validate / flatten JSON, or JSON to CSV | `json.js <mode> < in` | `pretty` `min` `validate` `keys` `csv` |
+| dedupe / sort / count / slugify / trim lines | `text.js <mode> < in` | `dedupe` `sort` `rsort` `count` `slug` `trim` |
+| base64 / hex encode-decode, sha256 / sha1 / md5 hash | `hash.js <mode> < in` | `b64` `b64d` `sha256` `sha1` `md5` `hexenc` `hexdec` |
+| convert a timestamp, or get the weekday (all UTC) | `date.js <mode> < in` | `iso` `epoch` `epochms` `weekday` |
+| write a commit message | `git add -A && commit-msg.js` | reads the staged diff |
+| summarize what changed since a release | `changelog.js [ref]` | reads git log |
+| write a PR description for this branch | `pr-description.js [base]` | reads the branch diff |
+
+If no row matches, do the task normally. This library grows one verified script
+at a time; never add one without a self-test.
+
+## How to call
+
+The first five read stdin, write stdout, exit 0 on success and non-zero on bad
+input. The last three read git directly (their input is the repo, not stdin).
+
+You can call any script directly, or use the dispatcher as a discovery front door:
+
+```bash
+node scripts/det/det.js                 # print the catalog (all 8 tools)
+node scripts/det/det.js <script> <mode> < input   # route stdin through it
+```
+
+`det.js` lists every tool: the five stdin scripts it can route, plus the three
+git-facing scripts (which it points you to run directly, since their input is the
+repo). The stdin catalog is derived from the scripts' own exports, so it can never
+drift from what actually runs. Trust the output; do not "improve" it.
+
+## stdin scripts
+
+### extract.js
+
+```bash
+cat page.html   | node scripts/det/extract.js urls
+node scripts/det/extract.js emails < contacts.txt
+node scripts/det/extract.js code   < README.md       # fenced blocks, contents only
+node scripts/det/extract.js --json urls < page.html  # JSON array
+```
+
+Duplicates removed, first-seen order preserved. Unknown mode exits 2.
+
+### json.js
+
+```bash
+cat data.json     | node scripts/det/json.js pretty       # 2-space indent
+node scripts/det/json.js min      < data.json             # minified
+node scripts/det/json.js validate < data.json             # "valid" or errors (exit 2)
+node scripts/det/json.js keys     < data.json             # top-level keys
+node scripts/det/json.js csv      < array.json            # array of objects -> RFC-4180 CSV
+```
+
+`csv` handles the escaping LLMs get wrong: fields with commas or quotes are
+quoted, inner quotes doubled. Columns follow first-seen key order across rows.
+
+### text.js
+
+```bash
+cat list.txt | node scripts/det/text.js dedupe    # drop dup lines, keep first order
+node scripts/det/text.js sort  < list.txt         # byte-order sort (rsort = reverse)
+node scripts/det/text.js count < list.txt         # lines / words / chars (tab-separated)
+node scripts/det/text.js slug  < titles.txt       # each line -> url slug (accents folded)
+node scripts/det/text.js trim  < messy.txt        # strip trailing ws, drop blank lines
+```
+
+`count` is exact, no more eyeballed line/word totals. `slug` folds accents
+(Café to cafe) so slugs are stable across inputs.
+
+### hash.js
+
+```bash
+printf 'hi' | node scripts/det/hash.js b64        # base64 encode (b64d decodes)
+node scripts/det/hash.js sha256 < file.txt        # real hex sha256 (sha1, md5 too)
+node scripts/det/hash.js hexenc < file.txt        # raw <-> hex (hexdec reverses)
+```
+
+A single trailing newline is stripped before encoding/hashing, so `echo hi` and
+`printf 'hi'` give the same result. These are real crypto digests, not the
+plausible-looking fakes an LLM emits.
+
+### date.js
+
+```bash
+echo 1700000000 | node scripts/det/date.js iso       # epoch (s or ms) -> ISO UTC
+echo 2026-07-07 | node scripts/det/date.js epoch     # date -> epoch seconds (epochms for ms)
+echo 2026-07-07 | node scripts/det/date.js weekday   # -> Tuesday
+```
+
+Everything is UTC and machine-independent: epoch auto-detects seconds vs ms, and
+a bare date string with no timezone is pinned to UTC instead of guessing local.
+
+## git-facing scripts
+
+These replace LLM *generation*, not just data munging. They read git directly, so
+there is no stdin and they sit outside the dispatcher catalog.
+
+### commit-msg.js
+
+```bash
+git add -A && node scripts/det/commit-msg.js        # print the drafted message
+node scripts/det/commit-msg.js --json               # {type,scope,subject,body,...}
+```
+
+Type and scope come from the changed paths (`docs`/`test`/`chore`/`feat`/`fix`,
+scope = deepest common dir); the body is exact diff stats. No intent-guessing.
+Multi-file changes name the lead file (the added one, else the biggest churn), as
+`add changelog.js (+2 more)`, never the vague `update 3 files`.
+
+### changelog.js
+
+```bash
+node scripts/det/changelog.js                       # since the last tag -> markdown
+node scripts/det/changelog.js v3.34.0               # since a specific ref
+node scripts/det/changelog.js v3.34.0 HEAD          # explicit range
+node scripts/det/changelog.js --json                # {sections,counts,breaking,...}
+```
+
+Sections, order, and bullets come straight from the commit subjects grouped by
+Conventional-Commits type (`feat` to Features, `fix` to Fixes, ...); `type!:`
+commits surface under BREAKING CHANGES. Subjects that don't match the header
+grammar land in "Other" so nothing is dropped. No paraphrase, no invented or
+missing entries.
+
+### pr-description.js
+
+```bash
+node scripts/det/pr-description.js                  # diff origin/master...HEAD -> markdown
+node scripts/det/pr-description.js origin/main      # different base branch
+node scripts/det/pr-description.js origin/main HEAD # explicit base + head
+node scripts/det/pr-description.js --json           # {title,summary,testPlan,...}
+```
+
+Title comes from the commits (one commit -> its subject; many -> dominant type
+plus lead file); the summary is one bullet per changed area with counts and
+churn; the test-plan lists the touched test files plus one check per non-test
+area. Every line is backed by a real change in the diff, no invented rationale.
+
+## Verifying the library
+
+```bash
+node scripts/det/test.js   # runs every script against known input/output
+```
+
+Runs fast, no deps, CI-safe. A script is not "done" until it appears here with a
+passing test. This suite is also gated by the repo's `npm test` via
+`test/det.test.js`, which runs it as a subprocess, so the library cannot silently
+rot in CI.