atris 3.47.0 → 3.48.1

package/lib/workforce-presence.js

@@ -0,0 +1,448 @@
+'use strict';
+
+const DEFAULT_STALE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
+const PROCESS_START_TOLERANCE_MS = 30 * 60 * 1000;
+const ACTIVE_TASK_STATUSES = new Set(['claimed', 'do', 'doing', 'in_progress', 'review']);
+const ACTIVE_MISSION_STATUSES = new Set(['planning', 'active', 'running', 'ready']);
+const RUNNING_RECEIPT_STATUSES = new Set(['active', 'in_progress', 'running', 'started', 'working']);
+const TERMINAL_RECEIPT_STATUSES = new Set([
+  'cancelled',
+  'completed',
+  'done',
+  'failed',
+  'landed',
+  'no_output',
+  'passed',
+  'presumed_dead',
+  'succeeded',
+  'timed_out',
+]);
+const WORK_TOKEN_STOP_WORDS = new Set([
+  'agent', 'build', 'building', 'engine', 'local', 'mission', 'process', 'running', 'task', 'working',
+]);
+
+function timestampMs(value) {
+  if (value == null || value === '') return 0;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return 0;
+    return value > 1000000000000 ? value : value * 1000;
+  }
+  const numeric = Number(value);
+  if (Number.isFinite(numeric) && String(value).trim()) return timestampMs(numeric);
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function isoTimestamp(value) {
+  const ms = timestampMs(value);
+  return ms ? new Date(ms).toISOString() : null;
+}
+
+function ageSeconds(value, nowMs) {
+  const ms = timestampMs(value);
+  return ms ? Math.max(0, Math.floor((nowMs - ms) / 1000)) : null;
+}
+
+function normalizeEngine(value) {
+  const engine = String(value || '').trim().toLowerCase();
+  if (!engine) return '';
+  if (engine === 'cursor-agent' || engine === 'cursor agent') return 'cursor';
+  if (engine === 'claude-code') return 'claude';
+  return engine.replace(/[^a-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+function engineForCommand(command) {
+  const text = String(command || '');
+  if (/ChatGPT\.app|Codex Framework\.framework|Claude\.app/.test(text)) return '';
+  const executable = text.trim().split(/\s+/)[0] || '';
+  const name = executable.split('/').pop().toLowerCase();
+  if (name === 'cursor-agent') return 'cursor';
+  if (/^codex(?:-|$)/.test(name)) return 'codex';
+  if (name === 'grok') return 'grok';
+  if (name === 'devin') return 'devin';
+  if (name === 'droid') return 'droid';
+  if (name === 'agy') return 'agy';
+  if (name === 'claude' && /(^|\s)(?:-p|--print)(?:\s|$)/.test(text)) return 'claude';
+  return '';
+}
+
+function parsePsOutput(text) {
+  const allRows = [];
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 8) continue;
+    const pid = Number(parts[0]);
+    const ppid = Number(parts[1]);
+    const command = parts.slice(7).join(' ');
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    const started = Date.parse(parts.slice(2, 7).join(' '));
+    allRows.push({
+      pid,
+      ppid: Number.isInteger(ppid) && ppid > 0 ? ppid : null,
+      command,
+      started_at: Number.isFinite(started) ? new Date(started).toISOString() : null,
+    });
+  }
+  const byPid = new Map(allRows.map((row) => [row.pid, row]));
+  const engineRows = allRows
+    .map((row) => ({ ...row, engine: engineForCommand(row.command) }))
+    .filter((row) => row.engine);
+  const parentPids = new Set(engineRows.map((row) => row.ppid).filter(Boolean));
+  return engineRows
+    .filter((row) => !parentPids.has(row.pid))
+    .map((row) => {
+      const ancestorPids = [];
+      let parent = row.ppid;
+      while (parent && !ancestorPids.includes(parent) && ancestorPids.length < 64) {
+        ancestorPids.push(parent);
+        parent = byPid.get(parent)?.ppid || null;
+      }
+      return { ...row, ancestor_pids: ancestorPids };
+    });
+}
+
+function normalizeProcesses(processes) {
+  const byPid = new Map();
+  for (const row of Array.isArray(processes) ? processes : []) {
+    const pid = Number(row?.pid);
+    const engine = normalizeEngine(row?.engine) || engineForCommand(row?.command);
+    if (!Number.isInteger(pid) || pid <= 0 || !engine) continue;
+    byPid.set(pid, {
+      pid,
+      ppid: Number(row?.ppid) || null,
+      engine,
+      command: String(row?.command || ''),
+      started_at: isoTimestamp(row?.started_at || row?.start || row?.at),
+      ancestor_pids: (Array.isArray(row?.ancestor_pids) ? row.ancestor_pids : [])
+        .map(Number)
+        .filter((value) => Number.isInteger(value) && value > 0),
+    });
+  }
+  return [...byPid.values()].sort((left, right) => left.pid - right.pid);
+}
+
+function taskRef(task) {
+  return String(task?.display_id || task?.legacy_ref || task?.id || '').trim();
+}
+
+function taskOwner(task) {
+  return String(task?.claimed_by || task?.assigned_to || task?.metadata?.assigned_to || '').trim();
+}
+
+function taskActivity(task) {
+  return task?.updated_at || task?.claimed_at || task?.created_at || null;
+}
+
+function receiptTaskRefs(receipt) {
+  const values = [receipt?.task_id, receipt?.task];
+  if (Array.isArray(receipt?.tasks)) values.push(...receipt.tasks);
+  if (Array.isArray(receipt?.task_ids)) values.push(...receipt.task_ids);
+  if (Array.isArray(receipt?.results)) values.push(...receipt.results.map((row) => row?.task || row?.task_id));
+  return [...new Set(values.map((value) => {
+    if (value && typeof value === 'object') return value.display_id || value.id || value.task;
+    return value;
+  }).map((value) => String(value || '').trim()).filter(Boolean))];
+}
+
+function receiptEngine(receipt) {
+  return normalizeEngine(
+    receipt?.engine
+      || receipt?.engines?.[0]
+      || receipt?.results?.find((row) => row?.engine)?.engine,
+  );
+}
+
+function receiptStatus(receipt) {
+  return String(receipt?.status || '').trim().toLowerCase();
+}
+
+function isRunningReceipt(receipt) {
+  return !receipt?.finished_at && RUNNING_RECEIPT_STATUSES.has(receiptStatus(receipt));
+}
+
+function isFinishedReceipt(receipt) {
+  if (!receipt || isRunningReceipt(receipt)) return false;
+  return Boolean(receipt.finished_at || TERMINAL_RECEIPT_STATUSES.has(receiptStatus(receipt)));
+}
+
+function receiptStartedAt(receipt, fallback) {
+  return receipt?.started_at || receipt?.at || receipt?.created_at || fallback || null;
+}
+
+function receiptFinishedAt(receipt, fallback) {
+  return receipt?.finished_at || receipt?.completed_at || receipt?.updated_at || fallback || null;
+}
+
+function finalResult(receipt) {
+  if (typeof receipt?.result === 'string') return receipt.result.trim();
+  if (receipt?.result && typeof receipt.result === 'object') {
+    const kind = String(receipt.result.kind || '').trim();
+    if (typeof receipt.result.passed === 'boolean') return `${kind || 'result'} ${receipt.result.passed ? 'passed' : 'failed'}`;
+    if (kind) return kind;
+  }
+  if (receipt?.summary && typeof receipt.summary === 'object') {
+    const answered = Number(receipt.summary.answered) || 0;
+    const failed = Number(receipt.summary.failed) || 0;
+    if (answered || failed) return `${answered} answered, ${failed} failed`;
+  }
+  return receiptStatus(receipt) || 'finished';
+}
+
+function taskLookup(tasks) {
+  const byRef = new Map();
+  for (const task of tasks) {
+    for (const ref of [task?.id, task?.display_id, task?.legacy_ref]) {
+      const key = String(ref || '').trim().toLowerCase();
+      if (key) byRef.set(key, task);
+    }
+  }
+  return byRef;
+}
+
+function firstTaskForRefs(refs, byRef) {
+  for (const ref of refs) {
+    const task = byRef.get(String(ref).toLowerCase());
+    if (task) return task;
+  }
+  return null;
+}
+
+function rowTask(refs, task) {
+  return taskRef(task) || refs[0] || null;
+}
+
+function baseRow({ member, task, title, engine, source, at, nowMs }) {
+  return {
+    member: member || null,
+    task: task || null,
+    title: title || null,
+    engine: engine || null,
+    source,
+    at: isoTimestamp(at),
+    age_seconds: ageSeconds(at, nowMs),
+  };
+}
+
+function buildWorkforcePresence(input = {}) {
+  const nowMs = timestampMs(input.nowMs ?? input.now ?? Date.now()) || Date.now();
+  const staleAfterMs = Number(input.staleAfterMs) > 0 ? Number(input.staleAfterMs) : DEFAULT_STALE_AFTER_MS;
+  const tasks = (Array.isArray(input.tasks) ? input.tasks : [])
+    .filter((task) => ACTIVE_TASK_STATUSES.has(String(task?.status || '').toLowerCase()) && taskOwner(task));
+  const missions = (Array.isArray(input.missions) ? input.missions : [])
+    .filter((mission) => ACTIVE_MISSION_STATUSES.has(String(mission?.status || '').toLowerCase()));
+  const receipts = Array.isArray(input.receipts) ? input.receipts : [];
+  const processes = normalizeProcesses(input.processes);
+  const byTaskRef = taskLookup(tasks);
+  const usedPids = new Set();
+  const representedTasks = new Set();
+  const working = [];
+  const waiting = [];
+  const done = [];
+  const stale = [];
+
+  const claimProcess = (engine, pid, expectedStart) => {
+    const wantedPid = Number(pid);
+    if (Number.isInteger(wantedPid) && wantedPid > 0) {
+      const exact = processes.find((row) => (
+        row.pid === wantedPid || row.ancestor_pids.includes(wantedPid)
+      ) && row.engine === engine && !usedPids.has(row.pid) && (
+        !timestampMs(expectedStart)
+        || !timestampMs(row.started_at)
+        || Math.abs(timestampMs(row.started_at) - timestampMs(expectedStart)) <= PROCESS_START_TOLERANCE_MS
+      ));
+      if (exact) usedPids.add(exact.pid);
+      return exact || null;
+    }
+    return null;
+  };
+  const workTokens = (value) => new Set(
+    (String(value || '').toLowerCase().match(/[a-z][a-z0-9]{4,}/g) || [])
+      .filter((token) => !WORK_TOKEN_STOP_WORDS.has(token)),
+  );
+  const processMatchesWork = (row, refs, title) => {
+    const command = String(row.command || '').toLowerCase();
+    if (refs.some((ref) => command.includes(String(ref).toLowerCase()))) return true;
+    const titleTokens = workTokens(title);
+    const commandTokens = workTokens(command);
+    return [...titleTokens].some((token) => commandTokens.has(token));
+  };
+  const claimMatchingProcess = (engine, refs, title) => {
+    const candidate = processes.find((row) => (
+      (!engine || row.engine === engine)
+      && !usedPids.has(row.pid)
+      && processMatchesWork(row, refs, title)
+    ));
+    if (candidate) usedPids.add(candidate.pid);
+    return candidate || null;
+  };
+
+  for (const entry of receipts) {
+    const receipt = entry?.receipt || entry;
+    const engine = receiptEngine(receipt);
+    if (!engine) continue;
+    const refs = receiptTaskRefs(receipt);
+    const task = firstTaskForRefs(refs, byTaskRef);
+    const member = String(receipt?.member || receipt?.owner || receipt?.actor || taskOwner(task) || '').trim();
+    const taskValue = rowTask(refs, task);
+    const startedAt = receiptStartedAt(receipt, entry?.mtimeMs);
+    const common = baseRow({
+      member,
+      task: taskValue,
+      title: task?.title || receipt?.objective || '',
+      engine,
+      source: 'receipt',
+      at: startedAt,
+      nowMs,
+    });
+    if (isRunningReceipt(receipt)) {
+      const processRow = claimProcess(engine, receipt.pid, startedAt)
+        || claimMatchingProcess(engine, refs, task?.title || receipt?.objective || '');
+      const row = {
+        ...common,
+        pid: processRow?.pid || Number(receipt.pid) || null,
+        receipt: entry?.name || receipt?.receipt || null,
+      };
+      if (processRow) working.push(row);
+      else if (Number(receipt.pid) > 0 || nowMs - timestampMs(startedAt) > staleAfterMs) {
+        stale.push({ ...row, reason: 'run has no live process' });
+      } else {
+        waiting.push({ ...row, reason: 'run has not started a local process' });
+      }
+      if (taskValue) representedTasks.add(String(taskValue).toLowerCase());
+      continue;
+    }
+    if (isFinishedReceipt(receipt)) {
+      done.push({
+        ...common,
+        at: isoTimestamp(receiptFinishedAt(receipt, entry?.mtimeMs)),
+        age_seconds: ageSeconds(receiptFinishedAt(receipt, entry?.mtimeMs), nowMs),
+        run_status: receiptStatus(receipt) || 'finished',
+        result: finalResult(receipt),
+        receipt: entry?.name || receipt?.receipt || null,
+      });
+    }
+  }
+
+  for (const mission of missions) {
+    const refs = Array.isArray(mission?.task_ids) ? mission.task_ids.map(String) : [];
+    if (refs.some((ref) => representedTasks.has(ref.toLowerCase()))) continue;
+    const task = firstTaskForRefs(refs, byTaskRef);
+    const engine = normalizeEngine(mission?.runner || mission?.engine || mission?.executed_by);
+    const member = String(mission?.owner || mission?.member || taskOwner(task) || '').trim();
+    const at = mission?.last_tick_at || mission?.updated_at || mission?.created_at;
+    const common = baseRow({
+      member,
+      task: rowTask(refs, task),
+      title: task?.title || mission?.objective || mission?.name || '',
+      engine,
+      source: 'mission',
+      at,
+      nowMs,
+    });
+    const processRow = engine
+      ? claimProcess(engine, mission?.pid, at) || claimMatchingProcess(engine, refs, common.title)
+      : null;
+    if (processRow) working.push({ ...common, pid: processRow.pid, mission: mission?.id || null });
+    else if (nowMs - timestampMs(at) > staleAfterMs) stale.push({ ...common, reason: 'mission has no live process', mission: mission?.id || null });
+    else waiting.push({ ...common, reason: 'mission is waiting for a local process', mission: mission?.id || null });
+    for (const ref of refs) representedTasks.add(ref.toLowerCase());
+  }
+
+  for (const task of tasks) {
+    const ref = taskRef(task);
+    if (representedTasks.has(ref.toLowerCase())) continue;
+    const engine = normalizeEngine(task?.executed_by || task?.metadata?.executed_by || task?.metadata?.engine);
+    const at = taskActivity(task);
+    const common = baseRow({
+      member: taskOwner(task),
+      task: ref,
+      title: task?.title || '',
+      engine,
+      source: 'task',
+      at,
+      nowMs,
+    });
+    const processRow = claimProcess(engine, task?.pid || task?.metadata?.pid, at)
+      || claimMatchingProcess(engine, [ref], '');
+    if (processRow) working.push({ ...common, engine: processRow.engine, pid: processRow.pid });
+    else if (nowMs - timestampMs(at) > staleAfterMs) stale.push({ ...common, reason: 'claim is older than seven days with no live process' });
+    else waiting.push({ ...common, reason: 'claim has no live process yet' });
+  }
+
+  const unowned = processes
+    .filter((row) => !usedPids.has(row.pid))
+    .map((row) => ({
+      engine: row.engine,
+      pid: row.pid,
+      command: row.command,
+      started_at: row.started_at,
+      age_seconds: ageSeconds(row.started_at, nowMs),
+      reason: 'no matching claim, mission, or run receipt',
+    }));
+
+  const newestFirst = (left, right) => timestampMs(right.at || right.started_at) - timestampMs(left.at || left.started_at);
+  working.sort(newestFirst);
+  waiting.sort(newestFirst);
+  done.sort(newestFirst);
+  stale.sort(newestFirst);
+
+  return {
+    schema: 'atris.workforce_presence.v1',
+    generated_at: new Date(nowMs).toISOString(),
+    stale_after_seconds: Math.round(staleAfterMs / 1000),
+    totals: {
+      working: working.length,
+      waiting: waiting.length,
+      done: done.length,
+      stale: stale.length,
+      unowned: unowned.length,
+    },
+    working,
+    waiting,
+    done,
+    stale,
+    unowned,
+  };
+}
+
+function formatAge(seconds) {
+  if (seconds == null) return 'age unknown';
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+function rowSubject(row) {
+  const member = row.member || 'unassigned';
+  const task = row.task || row.title || 'local work';
+  return `${member}: ${row.engine || 'unknown engine'} on ${task}`;
+}
+
+function renderWorkforcePresence(presence) {
+  const lines = [];
+  const section = (name, rows, render, limit = rows.length) => {
+    lines.push(`${name}:`);
+    if (!rows.length) lines.push('  none');
+    else rows.slice(0, limit).forEach((row) => lines.push(`  ${render(row)}`));
+    if (rows.length > limit) lines.push(`  ${rows.length - limit} more; clear finished runs with atris who --clear`);
+  };
+  section('working', presence.working, (row) => `${rowSubject(row)} (${formatAge(row.age_seconds)}, pid ${row.pid || '?'})`);
+  section('waiting', presence.waiting, (row) => `${rowSubject(row)} (${formatAge(row.age_seconds)}), ${row.reason}`);
+  section('done', presence.done, (row) => `${rowSubject(row)} (${formatAge(row.age_seconds)}), ${row.run_status}: ${row.result}`, 10);
+  section('stale', presence.stale, (row) => `${rowSubject(row)} (${formatAge(row.age_seconds)}), ${row.reason}`);
+  section('unowned', presence.unowned, (row) => `${row.engine} pid ${row.pid} (${formatAge(row.age_seconds)}), ${row.reason}`);
+  const totals = presence.totals;
+  lines.push(`totals: ${totals.working} working, ${totals.waiting} waiting, ${totals.done} done, ${totals.stale} stale, ${totals.unowned} unowned`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  buildWorkforcePresence,
+  isFinishedReceipt,
+  parsePsOutput,
+  receiptEngine,
+  renderWorkforcePresence,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.47.0",
+  "version": "3.48.1",
   "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.