instar 1.2.20 → 1.2.22

package/README.md

@@ -101,10 +101,11 @@ An agent that forgets what you discussed yesterday, doesn't recognize someone it
 | Feature | Description | Docs |
 |---------|-------------|------|
 | **Job Scheduler** | Cron-based tasks with priority levels, model tiering, and quota awareness | [→](https://instar.sh/features/scheduler/) |
-| **Telegram** | Two-way messaging via forum topics. Each topic maps to a Claude session | [→](https://instar.sh/features/telegram/) |
-| **WhatsApp** | Full messaging via local Baileys library. No cloud dependency | [→](https://instar.sh/features/whatsapp/) |
+| **Telegram** | Two-way messaging via forum topics. Each topic maps to a Claude session. Default GFM-to-HTML markdown formatter (v1.1.0+) | [→](https://instar.sh/features/telegram/) |
+| **WhatsApp** | Full messaging via local Baileys library or WhatsApp Business API webhook. No cloud dependency in Baileys mode | [→](https://instar.sh/features/whatsapp/) |
 | **iMessage** | Native macOS messaging via Messages.app database polling + `imsg` CLI. [Setup guide](#imessage-setup-macos) | |
-| **Lifeline** | Persistent supervisor. Detects crashes, auto-recovers, queues messages | [→](https://instar.sh/features/lifeline/) |
+| **Slack** | Two-way messaging via Slack adapter. Channel and DM routing, eight HTTP routes, dedicated CLI | [→](https://instar.sh/features/slack/) |
+| **Lifeline** | Persistent supervisor. Detects crashes, auto-recovers, queues messages, version-skew handling (v1.1.3+) | [→](https://instar.sh/features/lifeline/) |
 | **Conversational Memory** | Per-topic SQLite with FTS5, rolling summaries, context re-injection | [→](https://instar.sh/features/memory/) |
 | **Evolution System** | Proposals, learnings, gap tracking, commitment follow-through | [→](https://instar.sh/features/evolution/) |
 | **Relationships** | Cross-platform identity resolution, significance scoring, context injection | [→](https://instar.sh/features/relationships/) |
@@ -113,19 +114,21 @@ An agent that forgets what you discussed yesterday, doesn't recognize someone it
 | **Intent Alignment** | Decision journaling, drift detection, organizational constraints | [→](https://instar.sh/features/intent/) |
 | **Multi-Machine** | Ed25519/X25519 crypto identity, encrypted sync, automatic failover | [→](https://instar.sh/features/multi-machine/) |
 | **Serendipity Protocol** | Sub-agents capture out-of-scope discoveries without breaking focus. HMAC-signed, secret-scanned | [→](https://instar.sh/features/serendipity/) |
-| **Threadline Protocol** | Agent-to-agent conversations with canonical identity, three-layer trust model, authorization policy, Ed25519 invitations, Sybil protection, MoltBridge network discovery, rich agent profiles (auto-compiled from agent data with human review gate), discovery waterfall, message security, tamper-proof audit logging, framework-agnostic interop, and persistent listener daemon (always-on relay connection, pipe-mode sessions, sub-30s cross-machine failover). 2,324 tests across 104 test files | [→](https://instar.sh/features/threadline/) |
+| **Threadline Protocol** | Agent-to-agent conversations with canonical identity, three-layer trust model, authorization policy, Ed25519 invitations, Sybil protection, MoltBridge network discovery, rich agent profiles (auto-compiled from agent data with human review gate), discovery waterfall, message security, tamper-proof audit logging, framework-agnostic interop, persistent listener daemon (always-on relay connection, pipe-mode sessions, sub-30s cross-machine failover), eleven MCP tools (seven core + four registry-conditional). 80 modules, roughly 3,800 test cases across 74 dedicated test files plus 125 cross-cutting | [→](https://instar.sh/features/threadline/) |
 | **Self-Healing** | LLM-powered stall detection, session recovery, promise tracking | [→](https://instar.sh/features/self-healing/) |
 | **AutoUpdater** | Built-in update engine. Checks npm, auto-applies, self-restarts | [→](https://instar.sh/features/autoupdater/) |
 | **Build Pipeline** | `/build` skill with worktree isolation, 6-phase pipeline, quality gates, stop-hook enforcement | |
-| **Behavioral Hooks** | 9 automatic hooks: command guards, safety gates, identity grounding, topic context | [→](https://instar.sh/reference/hooks/) |
+| **Behavioral Hooks** | Eleven hook scripts plus nine observability event hooks: command guards, safety gates, identity grounding, topic context, channel context for iMessage and Slack, free-text guard, skill-usage telemetry, build stop-hook | [→](https://instar.sh/reference/hooks/) |
 | **Initiative Tracker** | Persisted multi-phase long-running work tracker. Phases, blockers, links, digest alerts. HTTP API at `/initiatives/*` | |
-| **Default Jobs** | Health checks, reflection, evolution, relationship maintenance | [→](https://instar.sh/reference/default-jobs/) |
+| **Observability** | Token burn detection, quota tracking with tiered backpressure, telemetry collection, homeostasis monitoring, session activity tracking, credential management | [→](https://instar.sh/features/observability/) |
+| **Cross-framework portability** | First-class Codex CLI support via `instar setup --framework codex-cli`. Codex-only init produces zero `.claude/` files. Framework-aware telegram-reply path. FrameworkSessionStore (per-runtime transcripts). FrameworkParitySentinel | [→](https://instar.sh/features/portability/) |
+| **Default Jobs** | Fourteen built-in jobs covering health, reflection, evolution, relationship maintenance, identity review, and five `overseer-*` jobs across development, learning, infrastructure, maintenance, and guardian responsibilities | [→](https://instar.sh/reference/default-jobs/) |
 
 > **Reference:** [CLI Commands](https://instar.sh/reference/cli/) · [API Endpoints](https://instar.sh/reference/api/) · [Configuration](https://instar.sh/reference/configuration/) · [File Structure](https://instar.sh/reference/file-structure/)
 
 ## Agent Skills
 
-Instar ships 12 skills that follow the [Agent Skills open standard](https://agentskills.io) -- portable across Claude Code, Codex, Cursor, VS Code, and 35+ other platforms.
+Instar ships fourteen skills total — twelve user-facing, plus two internal skills (`instar-dev` and `spec-converge`) used only by the agent that develops instar itself. The standard is the [Agent Skills open standard](https://agentskills.io) -- portable across Claude Code, Codex, Cursor, VS Code, and 35+ other platforms.
 
 **Standalone skills** work with zero dependencies. Copy a SKILL.md into your project and go:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.20",
+  "version": "1.2.22",
   "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-22T04:08:18.326Z",
+  "instarVersion": "1.2.22",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {

package/src/scaffold/templates/jobs/instar/docs-coverage-audit.md

@@ -0,0 +1,36 @@
+---
+name: Docs Coverage Audit
+description: Weekly walk of the instar source tree against the docs surface. Surfaces newly-undocumented capabilities so docs don't drift between releases. Off by default — only useful on machines that have the instar source repo locally (instar developers, contributors). Operators who want it can flip enabled to true in `.instar/jobs/instar/docs-coverage-audit.md`.
+schedule: "0 10 * * 1"
+priority: medium
+expectedDurationMinutes: 5
+model: haiku
+enabled: false
+tags:
+  - cat:learning
+  - audit
+  - instar-dev-only
+toolAllowlist: "*"
+unrestrictedTools: true
+---
+Run a weekly documentation coverage audit on the instar codebase. This job exists because docs drift between releases — features ship without doc updates, and the gap accumulates silently until someone notices. This audit catches the drift early.
+
+The job:
+
+1. Locate the instar source repo on this machine. Try in order: the workspace dir from .instar/config.json under workspace.repoPath; ~/Documents/Projects/instar/; ~/.instar/agents/<self>/.worktrees/ (any subdirectory); or whatever path the operator has configured. If you cannot find the instar repo on this machine, send a short Telegram message saying so and exit — there's no audit to run.
+
+2. Run the coverage script from inside that repo: `node scripts/docs-coverage.mjs --json > /tmp/docs-coverage-this-week.json`. The script enumerates every shipped capability (routes, commands, jobs, hooks, skills, top-level classes per subsystem) and cross-references against site docs + README. It writes both a JSON inventory and a markdown report to .instar/docs-coverage.json and .instar/docs-coverage.md.
+
+3. Compare the new report to last week's. The previous week's report lives at .instar/state/docs-coverage-last-week.json if it exists. Use plain JSON diff logic — what's the delta in undocumented count per category? What capabilities are newly undocumented (existed before but lost their doc mention, or are brand-new in src/ without any doc)? What capabilities became newly documented (good news worth surfacing)?
+
+4. If the delta is interesting (any category gained ≥3 undocumented items OR any single category dropped below its CI floor OR the overall coverage dropped by ≥2 percentage points), send a Telegram message that's a quick, conversational heads-up. Lead with the headline: "Docs coverage dipped in [category]" or "Five new endpoints landed without doc mentions" or similar. Then list the specific items in plain language with their file paths. End with a one-line suggestion of where to add the missing doc (which file in site/src/content/docs/ is the natural home).
+
+5. If the delta is uninteresting (small fluctuations, churn that nets to zero, all categories still above floor), stay silent. Most weeks should be silent — that means the docs are keeping up.
+
+6. After surfacing (or not), save the current report as next week's baseline: copy /tmp/docs-coverage-this-week.json to .instar/state/docs-coverage-last-week.json.
+
+7. Optionally, if the script's --check mode would fail (any category below its CI floor), file a higher-priority signal via the degradation reporter — this is the case where the next PR will hit a CI failure unless someone fixes coverage first.
+
+IMPORTANT: This is a guardian job, not a doer. Surface the drift and where to fix it, don't fix it yourself. The fix work belongs in a deliberate doc-update PR with proper review, not in an autonomous job run. If the drift is large, suggest the operator open a topic to scope the doc update — don't try to enumerate the full backlog in one Telegram message.
+
+Plain English. No raw JSON in the message. No structured field names. The user reads these on their phone. Write like you're texting a teammate about a code-review observation.

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/1.2.22.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**feat(docs-coverage-weekly): weekly audit job + GitHub Actions cron that surface accumulated docs drift.**
+
+Companion to the per-PR docs coverage gate that shipped in v1.2.21. The per-PR gate catches regression, but coverage can stagnate at the floor indefinitely if every PR just barely scrapes by. This release adds the trend-surface piece: a weekly check that catches accumulated drift even when the per-PR gate is satisfied.
+
+Two delivery surfaces, both light and both off the critical path:
+
+1. **Job template** — `src/scaffold/templates/jobs/instar/docs-coverage-audit.md` ships as an agentmd job, `enabled: false` by default. Instar-developing agents (the ones with the instar source repo on their machine) can flip it to `true` in their local `.instar/jobs/instar/docs-coverage-audit.md`. Once enabled, the job runs every Monday at 10:00 local time, locates the instar source repo, executes the coverage script, compares to the prior week's baseline, and sends a Telegram heads-up if anything drifted in an interesting way. Most weeks stay silent — that means docs are keeping up.
+
+2. **CI workflow** — `.github/workflows/docs-coverage-weekly.yml` runs every Monday at 10:00 UTC against the main branch. Posts the weekly report as a comment on a standing tracking issue tagged `docs-coverage`. Creates the issue on first run; appends weekly thereafter. Provides a durable, GitHub-native ledger of how coverage moves over time.
+
+Both surfaces are signals, not authorities. Neither fixes docs autonomously. The per-PR gate from v1.2.21 remains the authoritative regression check; these surface the trend.
+
+Spec: `docs/specs/docs-coverage-weekly.md`. ELI16: `docs/specs/docs-coverage-weekly.eli16.md`. Side-effects review: `upgrades/side-effects/docs-coverage-weekly.md`.
+
+## What to Tell Your User
+
+Nothing user-visible. The job is off by default and would only apply to agents that develop instar itself. The workflow runs in instar's own GitHub Actions, not the user's.
+
+## Summary of New Capabilities
+
+This release adds a single new job template (off by default) and a single new CI workflow. Both target the instar-developer use case rather than the end-user agent. No new agent runtime behavior.
+
+## Evidence
+
+The coverage script that both surfaces invoke was shipped and tested in v1.2.21. The job template was verified to parse with valid frontmatter. The workflow YAML validates against GitHub Actions schema. Both files were verified to install via existing pipelines: `installBuiltinJobs()` walks the templates directory on every install and update, and the workflow runs from `.github/workflows/` like every other workflow in the repo.

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

@@ -0,0 +1,74 @@
+# Side-effects review — docs-coverage-weekly
+
+Spec: `docs/specs/docs-coverage-weekly.md`
+ELI16: `docs/specs/docs-coverage-weekly.eli16.md`
+Companion to: `docs/specs/docs-coverage.md` (the underlying script + per-PR CI gate)
+
+## Surface map
+
+| Change | File | Type |
+|---|---|---|
+| New job template | `src/scaffold/templates/jobs/instar/docs-coverage-audit.md` | `agentmd` job, `enabled: false` by default. Distributed via `installBuiltinJobs()` on `instar init` and on every update via `PostUpdateMigrator` |
+| New CI workflow | `.github/workflows/docs-coverage-weekly.yml` | GitHub Actions cron workflow, Mondays at 10:00 UTC |
+
+No production code touched. No agent behavior changes at runtime unless an operator explicitly enables the job.
+
+## Over-block analysis
+
+**Could the job spam an operator?**
+
+The job ships `enabled: false`. Operators with the instar source repo on their machine can flip it to `true` in `.instar/jobs/instar/docs-coverage-audit.md`. The job's first action is to locate the instar source repo; if it can't find one, it sends a short message and exits — and the operator can disable the job again. So the worst case is one Telegram message before the operator turns it back off.
+
+When enabled and working correctly, the job stays silent most weeks. The delta thresholds (≥3 newly-undocumented items in a category, any category below CI floor, ≥2-point overall drop) ensure that only meaningful drift surfaces a message.
+
+**Could the CI workflow spam an issue tracker?**
+
+The workflow opens or updates one standing issue tagged `docs-coverage` and appends weekly reports as comments. If the issue is closed by a maintainer (signaling "stop tracking this"), the workflow creates a new one on the next run. This is the desired behavior — closing the issue is the soft way to say "I'm aware, I'll re-engage later." Comments accumulate on a single issue rather than creating a new issue per run.
+
+**Could the CI workflow fail and block other CI?**
+
+No. The workflow is its own job in its own file with no dependencies on other workflows. A failure is visible in the Actions UI but doesn't gate any other PR or push.
+
+## Under-block analysis
+
+**What does the weekly audit NOT catch?**
+
+- Same content-quality limitations as the per-PR coverage check — a documented capability with completely wrong content still counts as documented. The audit catches enumeration drift, not comprehension drift.
+- Doesn't catch capabilities that exist outside the enumerated locations (e.g. an exported class moved to a directory the script doesn't walk). This is a deliberate scope choice; the alternative is walking everything and producing noise.
+- Doesn't catch deleted docs that should still exist (the script measures coverage of what's in code; if code AND docs both lose a capability, neither shows up as drift).
+
+## Level-of-abstraction fit
+
+The job lives in `src/scaffold/templates/jobs/instar/` alongside the other default jobs. The CI workflow lives in `.github/workflows/` alongside other workflows. Both are at the right level: the job is at the agent-behavior layer (something the agent does), and the workflow is at the project-infrastructure layer (something the project does to itself).
+
+The script they both invoke (`scripts/docs-coverage.mjs`) was deliberately built first as a separate concern. This change layers two delivery mechanisms on top of it without modifying the script. If the cadence needs to change (daily, monthly), the script doesn't care.
+
+## Signal-vs-authority compliance
+
+Both surfaces are **signals**. Neither has authority to fail a build or block work. The per-PR coverage check from the docs-coverage spec is the authoritative gate. The weekly job and the weekly workflow are loud heads-ups, but they can't refuse to ship anything. The separation matches how other signal/authority pairs work in instar.
+
+## Interactions with existing systems
+
+- **`installBuiltinJobs()`** — picks up the new `docs-coverage-audit.md` template on every install/update. Existing agents get the template (off by default) on their next update via `PostUpdateMigrator`. No separate migration code needed because `installBuiltinJobs` already overwrites built-in templates idempotently.
+- **Scheduler** — sees the new job. With `enabled: false`, the scheduler reads it on startup but doesn't schedule it for execution. No CPU cost.
+- **GitHub Actions cron** — runs in the same project as other workflows but in its own job and on its own schedule. Doesn't share state with any per-PR workflow.
+- **Telegram adapter** — the job uses the same `telegram-reply.sh` path every other job uses for outbound messages. No new adapter integration.
+- **Docs-coverage script** — invoked via `node scripts/docs-coverage.mjs`. The script is deterministic and idempotent, safe to run repeatedly.
+
+## Rollback cost
+
+Trivially reversible. Remove the two added files. Existing agents lose the template on their next update; the workflow stops running on the next merge.
+
+## Risk summary
+
+- **Low risk of regression.** Pure additions. Job is off by default; workflow runs independently of any other workflow.
+- **Low risk of friction.** Job stays silent most weeks. Workflow posts to one standing issue rather than spraying alerts.
+- **No risk of data loss.** Both surfaces are read-only against the codebase.
+
+## Verification done before commit
+
+- Job template parses correctly (verified via reading frontmatter in test fashion).
+- CI workflow YAML validates against GitHub Actions schema (manual review).
+- The underlying script (shipped in the docs-coverage spec) is already tested and verified — no changes needed.
+- `enabled: false` confirmed in the template so this lands silently for existing agents.
+- Distribution path verified: `installBuiltinJobs()` walks `templates/jobs/instar/` and installs all `.md` files regardless of `enabled` flag, so the file reaches every agent on update; the `enabled: false` controls whether the scheduler runs it.

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).