instar 1.2.20 → 1.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.20",
+  "version": "1.2.21",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/scripts/docs-coverage.mjs

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+/**
+ * docs-coverage.mjs — measure documentation coverage of shipped capabilities.
+ *
+ * Walks src/ to enumerate every shipped capability (routes, commands, jobs,
+ * hooks, skills, exported classes per subsystem), cross-references each
+ * against README.md and site/src/content/docs/, and produces a coverage
+ * report. Designed to converge by construction — deterministic enumeration,
+ * not stochastic discovery.
+ *
+ * Born from a multi-pass agent-driven audit (May 2026) that proved manual
+ * audit passes don't converge on a codebase with this much surface drift.
+ * The structural answer is a programmatic check that runs in CI.
+ *
+ * Output:
+ *   - .instar/docs-coverage.json — machine-readable inventory + per-item
+ *     coverage tags (DOCUMENTED / PARTIAL / UNDOCUMENTED)
+ *   - .instar/docs-coverage.md — human-readable report grouped by subsystem
+ *   - exit code 0 if coverage >= threshold, 1 otherwise
+ *
+ * Usage:
+ *   node scripts/docs-coverage.mjs           # report only, exit 0
+ *   node scripts/docs-coverage.mjs --check   # exit 1 if below threshold
+ *   node scripts/docs-coverage.mjs --json    # JSON to stdout
+ *
+ * Thresholds (override via env):
+ *   INSTAR_DOCS_COVERAGE_MIN — minimum overall coverage % (default 30 — see
+ *     note in --check; this is the FLOOR, not the goal. Real goal lives in
+ *     the per-category limits below.)
+ *   INSTAR_DOCS_COVERAGE_ROUTE_MIN, ..._COMMAND_MIN, ..._JOB_MIN, ..._HOOK_MIN
+ *     — per-category floors (each default 30; tightened over time as the
+ *     existing gap closes).
+ *
+ * The floor starts loose because the existing gap is large. The point of
+ * shipping the script first is to prevent further regression while we
+ * close the existing gap. Tighten the floors after each round of doc work.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ── CLI args ────────────────────────────────────────────────────────
+const args = new Set(process.argv.slice(2));
+const CHECK = args.has('--check');
+const JSON_ONLY = args.has('--json');
+const QUIET = args.has('--quiet');
+
+// Resolve repo root. Order of preference:
+//   1. INSTAR_DOCS_COVERAGE_ROOT env var (explicit override, used by tests)
+//   2. process.cwd() if it contains a src/ directory (running from a repo)
+//   3. script's parent directory (default — running from this repo)
+function resolveRoot() {
+  if (process.env.INSTAR_DOCS_COVERAGE_ROOT) return process.env.INSTAR_DOCS_COVERAGE_ROOT;
+  const cwd = process.cwd();
+  if (fs.existsSync(path.join(cwd, 'src'))) return cwd;
+  return path.resolve(__dirname, '..');
+}
+const ROOT = resolveRoot();
+
+const SRC_DIR = path.join(ROOT, 'src');
+const DOCS_DIR = path.join(ROOT, 'site/src/content/docs');
+const README = path.join(ROOT, 'README.md');
+const STATE_DIR = path.join(ROOT, '.instar');
+
+// ── Thresholds ──────────────────────────────────────────────────────
+const num = (env, def) => {
+  const v = process.env[env];
+  return v !== undefined ? Number(v) : def;
+};
+// Floors are calibrated to current state as of script introduction.
+// Each doc-update PR should ratchet the relevant floor upward — this is
+// how the script enforces non-regression while we close the existing gap.
+// Floors below current measured coverage by ~2-3 percentage points to
+// allow normal churn without false failures.
+const THRESHOLDS = {
+  overall: num('INSTAR_DOCS_COVERAGE_MIN', 13),
+  route: num('INSTAR_DOCS_COVERAGE_ROUTE_MIN', 11),
+  command: num('INSTAR_DOCS_COVERAGE_COMMAND_MIN', 40),
+  job: num('INSTAR_DOCS_COVERAGE_JOB_MIN', 55),
+  hook: num('INSTAR_DOCS_COVERAGE_HOOK_MIN', 22),
+  skill: num('INSTAR_DOCS_COVERAGE_SKILL_MIN', 80),
+  class: num('INSTAR_DOCS_COVERAGE_CLASS_MIN', 8),
+};
+
+// ── Capability enumeration ──────────────────────────────────────────
+
+/** Routes registered in src/server/routes.ts via router.<verb>('path', ...). */
+function enumerateRoutes() {
+  const routesFile = path.join(SRC_DIR, 'server/routes.ts');
+  if (!fs.existsSync(routesFile)) return [];
+  const content = fs.readFileSync(routesFile, 'utf-8');
+  const matches = [...content.matchAll(/router\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`]/g)];
+  const seen = new Set();
+  const out = [];
+  for (const m of matches) {
+    const id = `${m[1].toUpperCase()} ${m[2]}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push({ type: 'route', method: m[1].toUpperCase(), path: m[2], id });
+  }
+  return out;
+}
+
+/** Top-level command files in src/commands/. */
+function enumerateCommands() {
+  const dir = path.join(SRC_DIR, 'commands');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.ts') && !f.endsWith('.test.ts'))
+    .map(f => {
+      const name = f.replace(/\.ts$/, '');
+      return { type: 'command', name, id: name, path: `src/commands/${f}` };
+    });
+}
+
+/** Default job templates shipped with instar. */
+function enumerateJobs() {
+  const dir = path.join(SRC_DIR, 'scaffold/templates/jobs/instar');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => {
+      const name = f.replace(/\.md$/, '');
+      return { type: 'job', name, id: name, path: `src/scaffold/templates/jobs/instar/${f}` };
+    });
+}
+
+/** Hook scripts in src/templates/hooks/. */
+function enumerateHooks() {
+  const dir = path.join(SRC_DIR, 'templates/hooks');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(f => /\.(sh|js|mjs)$/.test(f))
+    .map(f => {
+      const name = f.replace(/\.(sh|js|mjs)$/, '');
+      return { type: 'hook', name, id: f, path: `src/templates/hooks/${f}` };
+    });
+}
+
+/** Skills under skills/. Includes user_invocable flag from frontmatter. */
+function enumerateSkills() {
+  const dir = path.join(ROOT, 'skills');
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const d of fs.readdirSync(dir)) {
+    const skillFile = path.join(dir, d, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+    const content = fs.readFileSync(skillFile, 'utf-8');
+    const fm = content.match(/^---\n([\s\S]*?)\n---/);
+    const userInvocable = !fm || !/user_invocable:\s*["']?false["']?/i.test(fm[1]);
+    out.push({ type: 'skill', name: d, id: d, userInvocable, path: `skills/${d}/SKILL.md` });
+  }
+  return out;
+}
+
+/** Top-level exported classes per subsystem. Identified by PascalCase filename. */
+function enumerateSubsystemClasses() {
+  const subsystems = [
+    'core', 'monitoring', 'memory', 'lifeline', 'messaging', 'threadline',
+    'scheduler', 'remediation', 'tasks', 'paste', 'privacy', 'tunnel',
+    'moltbridge', 'identity', 'knowledge', 'users', 'security', 'providers',
+  ];
+  const out = [];
+  for (const sub of subsystems) {
+    const subDir = path.join(SRC_DIR, sub);
+    if (!fs.existsSync(subDir) || !fs.statSync(subDir).isDirectory()) continue;
+    for (const f of fs.readdirSync(subDir)) {
+      if (!f.endsWith('.ts')) continue;
+      if (f.endsWith('.test.ts') || f.endsWith('.types.ts') || f === 'index.ts' || f === 'types.ts') continue;
+      const name = f.replace(/\.ts$/, '');
+      // Only PascalCase top-level exports count as "classes" for coverage purposes.
+      // Lowercase files are utilities not user-facing.
+      if (!/^[A-Z]/.test(name)) continue;
+      out.push({ type: 'class', subsystem: sub, name, id: `${sub}/${name}`, path: `src/${sub}/${f}` });
+    }
+  }
+  return out;
+}
+
+// ── Doc loading ─────────────────────────────────────────────────────
+
+function loadAllDocs() {
+  const docs = {};
+  if (fs.existsSync(README)) {
+    docs['README.md'] = fs.readFileSync(README, 'utf-8');
+  }
+  if (fs.existsSync(DOCS_DIR)) {
+    const walk = (dir) => {
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) walk(full);
+        else if (/\.(md|mdx)$/.test(e.name)) {
+          docs[path.relative(ROOT, full)] = fs.readFileSync(full, 'utf-8');
+        }
+      }
+    };
+    walk(DOCS_DIR);
+  }
+  return docs;
+}
+
+// ── Coverage scoring ────────────────────────────────────────────────
+
+function findMentions(capability, docs) {
+  // Returns list of doc paths that mention this capability.
+  // Coverage strategy varies per capability type.
+  let needles = [];
+  switch (capability.type) {
+    case 'route':
+      // Match exact path (with leading /). Substring match — close enough.
+      needles = [capability.path];
+      break;
+    case 'command':
+      // Match either `instar <name>` (CLI usage) or just the bare name.
+      needles = [`instar ${capability.name}`];
+      break;
+    case 'job':
+      needles = [capability.name];
+      break;
+    case 'hook':
+      needles = [capability.name];
+      break;
+    case 'skill':
+      needles = [capability.name];
+      break;
+    case 'class':
+      needles = [capability.name];
+      break;
+  }
+  const matches = [];
+  for (const [docPath, content] of Object.entries(docs)) {
+    for (const needle of needles) {
+      if (content.includes(needle)) {
+        matches.push(docPath);
+        break;
+      }
+    }
+  }
+  return matches;
+}
+
+function classifyCoverage(mentions) {
+  if (mentions.length === 0) return 'UNDOCUMENTED';
+  if (mentions.length === 1) return 'PARTIAL';
+  return 'DOCUMENTED';
+}
+
+// ── Report generation ───────────────────────────────────────────────
+
+function buildReport(items, docs) {
+  for (const item of items) {
+    const mentions = findMentions(item, docs);
+    item.mentions = mentions;
+    item.coverage = classifyCoverage(mentions);
+  }
+
+  const byType = {};
+  for (const item of items) {
+    if (!byType[item.type]) byType[item.type] = { total: 0, documented: 0, partial: 0, undocumented: 0, items: [] };
+    const bucket = byType[item.type];
+    bucket.total++;
+    bucket.items.push(item);
+    if (item.coverage === 'DOCUMENTED') bucket.documented++;
+    else if (item.coverage === 'PARTIAL') bucket.partial++;
+    else bucket.undocumented++;
+  }
+
+  for (const t of Object.keys(byType)) {
+    const b = byType[t];
+    b.coveragePct = b.total === 0 ? 100 : Math.round(((b.documented + b.partial * 0.5) / b.total) * 100);
+  }
+
+  const total = items.length;
+  const documented = items.filter(i => i.coverage === 'DOCUMENTED').length;
+  const partial = items.filter(i => i.coverage === 'PARTIAL').length;
+  const undocumented = total - documented - partial;
+  const overallPct = total === 0 ? 100 : Math.round(((documented + partial * 0.5) / total) * 100);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    totals: { total, documented, partial, undocumented, coveragePct: overallPct },
+    thresholds: THRESHOLDS,
+    byType,
+  };
+}
+
+function renderMarkdown(report) {
+  const lines = [];
+  lines.push('# Documentation Coverage Report');
+  lines.push('');
+  lines.push(`Generated: ${report.generatedAt}`);
+  lines.push('');
+  lines.push('## Overall');
+  lines.push('');
+  lines.push(`**Coverage: ${report.totals.coveragePct}%** (${report.totals.documented} documented + ${report.totals.partial} partial of ${report.totals.total} shipped capabilities)`);
+  lines.push('');
+  lines.push(`Threshold (overall): ${report.thresholds.overall}% — ${report.totals.coveragePct >= report.thresholds.overall ? 'PASS' : 'FAIL'}`);
+  lines.push('');
+  lines.push('## By capability type');
+  lines.push('');
+  lines.push('| Type | Total | Documented | Partial | Undocumented | Coverage | Floor | Status |');
+  lines.push('|---|---|---|---|---|---|---|---|');
+  for (const t of Object.keys(report.byType).sort()) {
+    const b = report.byType[t];
+    const floor = report.thresholds[t] ?? '—';
+    const status = floor === '—' ? '—' : (b.coveragePct >= floor ? 'PASS' : 'FAIL');
+    lines.push(`| ${t} | ${b.total} | ${b.documented} | ${b.partial} | ${b.undocumented} | ${b.coveragePct}% | ${floor}% | ${status} |`);
+  }
+  lines.push('');
+  lines.push('## Undocumented items');
+  lines.push('');
+  for (const t of Object.keys(report.byType).sort()) {
+    const undoc = report.byType[t].items.filter(i => i.coverage === 'UNDOCUMENTED');
+    if (undoc.length === 0) continue;
+    lines.push(`### ${t} (${undoc.length})`);
+    lines.push('');
+    for (const item of undoc) {
+      lines.push(`- \`${item.id}\`${item.path ? ` — \`${item.path}\`` : ''}`);
+    }
+    lines.push('');
+  }
+  lines.push('## Partial coverage (single mention)');
+  lines.push('');
+  for (const t of Object.keys(report.byType).sort()) {
+    const partial = report.byType[t].items.filter(i => i.coverage === 'PARTIAL');
+    if (partial.length === 0) continue;
+    lines.push(`### ${t} (${partial.length})`);
+    lines.push('');
+    for (const item of partial) {
+      lines.push(`- \`${item.id}\` → mentioned only in \`${item.mentions[0]}\``);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+
+function main() {
+  if (!QUIET && !JSON_ONLY) console.error('[docs-coverage] enumerating capabilities…');
+
+  const capabilities = [
+    ...enumerateRoutes(),
+    ...enumerateCommands(),
+    ...enumerateJobs(),
+    ...enumerateHooks(),
+    ...enumerateSkills(),
+    ...enumerateSubsystemClasses(),
+  ];
+
+  if (!QUIET && !JSON_ONLY) console.error(`[docs-coverage] enumerated ${capabilities.length} capabilities; loading docs…`);
+
+  const docs = loadAllDocs();
+  if (!QUIET && !JSON_ONLY) console.error(`[docs-coverage] loaded ${Object.keys(docs).length} docs; scoring…`);
+
+  const report = buildReport(capabilities, docs);
+
+  // Ensure state dir exists before writing.
+  if (!fs.existsSync(STATE_DIR)) fs.mkdirSync(STATE_DIR, { recursive: true });
+
+  // Write the JSON report (machine-readable, used by CI + watchers).
+  fs.writeFileSync(path.join(STATE_DIR, 'docs-coverage.json'), JSON.stringify(report, null, 2) + '\n');
+
+  // Write the markdown report (human-readable, committable artifact).
+  const md = renderMarkdown(report);
+  fs.writeFileSync(path.join(STATE_DIR, 'docs-coverage.md'), md);
+
+  if (JSON_ONLY) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  } else if (!QUIET) {
+    console.error('');
+    console.error(`Overall coverage: ${report.totals.coveragePct}% (${report.totals.documented} doc + ${report.totals.partial} partial of ${report.totals.total} capabilities)`);
+    for (const t of Object.keys(report.byType).sort()) {
+      const b = report.byType[t];
+      const floor = report.thresholds[t] ?? null;
+      console.error(`  ${t.padEnd(8)} ${String(b.coveragePct).padStart(3)}%  (${b.documented}/${b.total})${floor !== null ? `  floor ${floor}%` : ''}`);
+    }
+    console.error('');
+    console.error(`Reports written to .instar/docs-coverage.{json,md}`);
+  }
+
+  if (CHECK) {
+    // CI mode — fail if any category is below its floor.
+    const failures = [];
+    if (report.totals.coveragePct < THRESHOLDS.overall) {
+      failures.push(`overall ${report.totals.coveragePct}% < ${THRESHOLDS.overall}%`);
+    }
+    for (const t of Object.keys(report.byType)) {
+      const floor = THRESHOLDS[t];
+      if (floor === undefined) continue;
+      const pct = report.byType[t].coveragePct;
+      if (pct < floor) failures.push(`${t} ${pct}% < ${floor}%`);
+    }
+    if (failures.length > 0) {
+      process.stderr.write(`\n❌ docs-coverage check failed:\n`);
+      for (const f of failures) process.stderr.write(`  - ${f}\n`);
+      process.stderr.write(`\nFix: add doc coverage for the items listed in .instar/docs-coverage.md, then re-run.\n`);
+      process.exit(1);
+    }
+    if (!QUIET) console.error('✅ docs-coverage check passed.');
+  }
+}
+
+main();

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-22T03:32:05.394Z",
-  "instarVersion": "1.2.20",
+  "generatedAt": "2026-05-22T03:55:48.253Z",
+  "instarVersion": "1.2.21",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {

package/upgrades/1.2.21.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**feat(docs-coverage): deterministic enumeration as a structural antidrift for docs.**
+
+A multi-pass agent-driven audit (May 2026) proved that documentation drift on this codebase cannot be closed by manual audit passes. Each pass found new items the previous pass missed because the gap is large enough — only one of twenty-four `src/` subsystems has complete feature-doc coverage today — that no single pass exhaustively enumerates.
+
+This release ships the structural answer per the codebase's Structure-over-Willpower principle: a pure-Node script that walks the source tree, enumerates every shipped capability (HTTP routes, CLI commands, scheduled jobs, hooks, skills, and top-level classes per subsystem), cross-references each against `README.md` and `site/src/content/docs/`, and produces a coverage report.
+
+The script:
+
+1. **Enumerates deterministically.** No model in the loop. The same source state produces the same report every run.
+2. **Classifies coverage as DOCUMENTED / PARTIAL / UNDOCUMENTED.** Two-or-more doc mentions count as documented; exactly one counts as partial; zero counts as undocumented.
+3. **Enforces per-category floors via CI.** A new `Docs Coverage` job runs `node scripts/docs-coverage.mjs --check` on every PR and fails if any category drops below its floor. Initial floors are calibrated to current measured coverage minus a small buffer.
+4. **Ratchets upward.** PRs that improve docs raise the relevant floor. The bar moves with the codebase.
+5. **Produces two artifacts.** `.instar/docs-coverage.json` (machine-readable, used by CI and future automation) and `.instar/docs-coverage.md` (human-readable, grouped by capability type with sections for undocumented and partial items). Both are git-ignored as generated artifacts; both are uploaded as CI artifacts on every run.
+
+Initial baseline measured against current main: 15% overall coverage across 880 shipped capabilities — 36 of 457 routes mentioned in docs, 7 of 31 commands, 4 of 14 default jobs, 12 of 14 skills.
+
+Spec: `docs/specs/docs-coverage.md`. ELI16: `docs/specs/docs-coverage.eli16.md`. Side-effects review: `upgrades/side-effects/docs-coverage.md`.
+
+This is the foundation for two follow-on capabilities tracked separately: bulk doc updates (Phase 2 of the current sprint) and a weekly audit job that surfaces drift via Telegram (Phase 5).
+
+## What to Tell Your User
+
+Nothing user-visible. This release adds a CI check that enforces documentation coverage on instar's own development pipeline. Agents continue to behave identically.
+
+If a contributor asks why their pull request is failing the new docs coverage job, the failure message names the offending category and the fix is to add a doc mention for the new capability somewhere in the README or under site docs. Per-category floors can be temporarily relaxed via environment variables for one-off pull requests that genuinely need to skip the check.
+
+## Summary of New Capabilities
+
+This release is a pure infrastructure addition. No new runtime capabilities for agents. The new CI gate and reporting tool are for instar developers and direct contributors only.
+
+## Evidence
+
+The script was run against current main and produced the baseline coverage numbers above. Seven unit tests verify the enumeration, scoring, CI behavior, and artifact output against a mock repo. The CI workflow runs the script in `--check` mode and uploads the report as an artifact. `npm run lint` passes (TypeScript, destructive-ops lint, LLM-HTTP lint, Codex Rule 1 drift).
+
+The audit that motivated this script remains as evidence: it ran for six passes and never converged. The script's first run reproduces the audit's headline finding (15% coverage) in under one second of deterministic walking — proving the convergence-by-construction claim.

package/upgrades/side-effects/docs-coverage.md

@@ -0,0 +1,84 @@
+# Side-effects review — docs-coverage
+
+Spec: `docs/specs/docs-coverage.md`
+ELI16: `docs/specs/docs-coverage.eli16.md`
+
+## Surface map
+
+| Change | File(s) | Type |
+|---|---|---|
+| New script | `scripts/docs-coverage.mjs` | Pure-Node CLI, no dependencies, runnable from any cwd containing `src/` |
+| New CI job | `.github/workflows/ci.yml` (added `docs-coverage` job) | Runs the script in `--check` mode, uploads report as artifact |
+| New tests | `tests/unit/scripts/docs-coverage.test.ts` | 7 unit tests against a mock repo |
+| gitignore | `.gitignore` (added `.instar/docs-coverage.{json,md}`) | Generated artifacts excluded from commits |
+
+No production code touched. No agent behavior changes. No state migrations.
+
+## Over-block analysis
+
+**Could the CI check block a legitimate PR?**
+
+Yes, in three scenarios:
+
+1. **A PR introduces a new capability without a doc mention.** This is the desired behavior — the gate exists to require doc updates alongside feature work. Authors fix by adding a mention in the relevant doc.
+2. **A PR removes a documented capability and the floor drops below threshold.** Calibrated initial floors are set 2–3 percentage points below current coverage so normal churn doesn't trip them. A capability removal that drops 5+ percentage points in a single category would trip — and arguably should, because removing a feature is itself a doc-update event.
+3. **A PR adds many capabilities in a category that's already at floor.** A PR adding 10 new routes when the route category is at 13% would drop the category to ~12.5% and fail. The author would have to add doc mentions for at least some of the new routes. Again, desired behavior.
+
+**Escape hatches:**
+- Per-category env overrides allow temporarily relaxing a floor for a one-off PR.
+- The check can be removed from the workflow if it ever creates more friction than value (the spec lists this as a rollback path).
+
+## Under-block analysis
+
+**What does the check NOT catch?**
+
+- **Stale doc claims.** A capability can be mentioned with completely wrong information. The script only checks for the substring, not for semantic correctness. This is a genuine limitation — but it's a limitation any automated tool faces, and the manual audit work surfaced these specifically (e.g. configuration.md "all top-level" claim). The agent-driven audit and this script are complementary, not substitutes.
+- **Renamed capabilities.** If a capability is renamed and the doc still references the old name, the doc's mention won't match. This produces a false positive (capability looks undocumented) but the right fix is renaming the doc reference anyway.
+- **Conceptual coverage.** A doc page can describe a feature in detail without ever using the canonical class name or route path. The script would miss this. This is a deliberate trade-off — we'd rather flag a documented-in-spirit capability as missing than under-detect coverage gaps.
+- **Internal capabilities.** The script doesn't enumerate `utils/`, `data/`, `types/` — these are correctly excluded as not-user-facing. If we ever move a user-facing thing into one of those directories, the script wouldn't catch the move.
+
+## Level-of-abstraction fit
+
+The script lives at the right layer:
+
+- Not inside the `pre-commit` gate — that's for per-commit author concerns, and coverage is a PR-level concern.
+- Not inside individual feature workflows — that would scatter the logic across the codebase.
+- In CI as a dedicated job — runs in parallel with other checks, easy to find when it fails, easy to skip when investigating an unrelated failure.
+
+The script's enumeration logic is centralized rather than duplicated: every capability type uses the same coverage-scoring function. Adding a new capability type (say, MCP tools or runbooks) is one new `enumerate*()` function, not a separate script.
+
+## Signal-vs-authority compliance
+
+The script is **authoritative on enumeration** (it walks the source tree, no ambiguity) but **a signal on coverage** (substring matching is approximate; a single mention scores half, two or more score full). The signal-vs-authority separation is respected: the script can refuse a push but it doesn't claim to be the final word on whether docs are good — it just claims to know whether they exist. Quality remains the author's responsibility.
+
+The initial floors are calibrated loose so the script doesn't usurp judgment by being too strict on day one. As the doc-update PRs land, the floors ratchet up, and the script's signal becomes louder. This is the right progression.
+
+## Interactions with existing systems
+
+- **Pre-commit hooks.** No interaction — the script runs in CI, not pre-commit.
+- **pre-push gate** (`scripts/pre-push-gate.js`). No interaction — the script doesn't touch upgrade-notes validation.
+- **Pre-push fixture guard** (`scripts/pre-push-fixture-guard.mjs`). No interaction — different concern.
+- **PostUpdateMigrator.** No interaction — the script doesn't ship to agents, only runs at CI time.
+- **Working-tree integrity check** in CI. No interaction — that check runs after tests; this one runs as its own job in parallel.
+- **Future weekly audit job (Phase 5 of this sprint).** The job will execute this script and surface the report via Telegram. The JSON output is the contract.
+- **lint-no-direct-destructive.js.** No interaction — the script doesn't perform git or fs writes outside `.instar/`.
+
+## Rollback cost
+
+Trivially reversible. Remove three files (script, test, the workflow job block) plus the two `.gitignore` lines. No data migration, no schema change, no agent-state mutation. Reverting leaves the repo at exactly its pre-change state.
+
+## Risk summary
+
+- **Low risk of regression.** Pure-Node script, deterministic enumeration, no side effects outside writing two files under `.instar/`. Cannot break any production code path.
+- **Moderate friction risk.** Authors who add features without docs will hit the gate. This is the intended behavior, but it will surprise people the first few times. Mitigation: the spec + ELI16 are checked in alongside the script, so the failure message has a clear pointer to "what's going on and how to fix it."
+- **No risk of data loss.** The script reads only; the only writes are the two artifact files in `.instar/`, both git-ignored.
+
+## Verification done before commit
+
+- Script enumerates 880 capabilities across six types on current main.
+- `--check` exits 0 with floors calibrated to current state.
+- `--check` exits 1 with a high floor (verified in test `--check fails when any category is below floor`).
+- All seven unit tests pass.
+- `npm run lint` passes (TypeScript, destructive-ops lint, LLM-HTTP lint, Codex Rule 1 drift).
+- The mock-repo test mocks the same six capability types and verifies coverage classification.
+- Spec carries `approved: true` per direct principal authorization in Telegram topic 11235 (the autonomous-mode instruction was "Complete option 3", referring to the documentation-coverage script described as option 3 in the audit report shared minutes earlier).