simt-dev 0.6.2 → 0.7.0

package/src/prbody.mjs

@@ -0,0 +1,253 @@
+// The `simt pr-body` engine (plan 0003 R55).
+//
+// A pull request body assembled from what the tool already knows, rather than
+// what its author remembers to write: the evidence block from the ledger (R17),
+// the decision records the diff touches, the gate state from the last check,
+// and the residual risk in ADR-008's verdict vocabulary. Read-only throughout:
+// it names the tree, reads the ledger, reads the check cache and diffs names,
+// and writes nothing, so it needs no preview, no `--yes` and no journal entry.
+//
+// The base defaults to the branch's upstream fork point (`origin/main`, then
+// `main`), and `--base` names anything else. When no base resolves, the body
+// falls back to the working-tree diff against HEAD: a report that refused
+// without a base would be useless on a repository with a single branch.
+
+import { execFile } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { readLedger, treeId } from './ledger/index.mjs';
+import { readCheckCache } from './status.mjs';
+import { readManifest } from './projection/manifest.mjs';
+import { splitFrontmatter } from './memory/decide.mjs';
+import { decisionsDir } from './decisions/dir.mjs';
+
+const exec = promisify(execFile);
+
+/**
+ * The ref the body diffs against: the override when given, else the first
+ * candidate that shares history with HEAD. Returns the ref, or null when the
+ * repository has a single branch and the body should diff the worktree.
+ */
+async function resolveBase(root, override = null) {
+  if (override !== null && override !== undefined && String(override) !== '') {
+    try {
+      await exec('git', ['rev-parse', '--verify', '--quiet', `${override}^{commit}`], { cwd: root });
+      return { base: String(override), error: null };
+    } catch {
+      return { base: null, error: `unknown base ${override}` };
+    }
+  }
+  for (const candidate of ['origin/main', 'main', 'origin/master', 'master']) {
+    try {
+      await exec('git', ['merge-base', 'HEAD', candidate], { cwd: root });
+      return { base: candidate, error: null };
+    } catch {
+      // Not present or shares no history; the next candidate may.
+    }
+  }
+  return { base: null, error: null };
+}
+
+/**
+ * Every path the pull request would carry: the branch range when there is a
+ * base, plus whatever the worktree adds on top. Sorted, deduplicated, and
+ * without `.simt/` state: the ledger and the check cache prove the body, they
+ * are not its content.
+ */
+async function changedPaths(root, base) {
+  const paths = new Set();
+  const add = (stdout) => {
+    for (const line of String(stdout ?? '').split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed !== '' && !trimmed.startsWith('.simt/')) paths.add(trimmed);
+    }
+  };
+  if (base !== null) {
+    try {
+      const { stdout } = await exec('git', ['diff', '--name-only', `${base}...HEAD`], {
+        cwd: root,
+        maxBuffer: 16 << 20,
+      });
+      add(stdout);
+    } catch {
+      // An unborn HEAD or an unreadable range contributes nothing; the worktree
+      // reads below still answer.
+    }
+  }
+  for (const args of [
+    ['diff', '--name-only', 'HEAD'],
+    ['ls-files', '--others', '--exclude-standard'],
+  ]) {
+    try {
+      const { stdout } = await exec('git', args, { cwd: root, maxBuffer: 16 << 20 });
+      add(stdout);
+    } catch {
+      // Not a repository, or no commit yet: the body reports the absence.
+    }
+  }
+  return [...paths].sort();
+}
+
+/**
+ * The decision records the diff touches: one entry per `docs/decisions/*.md`
+ * in the changed paths, carrying the id from the filename and the title and
+ * status from the file itself. Sorted by id; a file that will not parse is
+ * reported with what it has rather than dropping the row.
+ */
+async function changedDecisions(root, paths) {
+  // Q55: the prefix is the repository's own decisions directory, not a literal.
+  const relDir = await decisionsDir(root);
+  const absDir = join(root, relDir);
+  const names = paths.filter((p) => p.startsWith(`${relDir}/`) && p.toLowerCase().endsWith('.md'));
+  try {
+    await readdir(absDir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names.sort()) {
+    const id = /^ADR-\d{3,}/i.exec(name.slice(relDir.length + 1))?.[0].toUpperCase() ?? name;
+    let title = id;
+    let status = 'unknown';
+    try {
+      const text = await readFile(join(root, name), 'utf8');
+      const { body } = splitFrontmatter(text);
+      const heading = /^#\s+(.*)$/m.exec(body)?.[1] ?? id;
+      title = heading.replace(/^ADR-\d{3,}\s*[—–-]\s*/i, '').trim() || id;
+      status = /^Status:\s*(.+)$/im.exec(body)?.[1].trim() ?? 'unknown';
+    } catch {
+      // An unreadable record is still a changed decision; the body says so
+      // rather than silently omitting a file the diff names.
+    }
+    out.push({ path: name, id, title, status });
+  }
+  return out;
+}
+
+/**
+ * Assemble the whole body. Never throws for a missing ledger, cache or base:
+ * each absence is a line in the report, because a PR body whose evidence is
+ * missing is precisely the case the residual-risk section exists to say out loud.
+ */
+export async function buildPrBody(root, { base = null } = {}) {
+  const resolved = await resolveBase(root, base);
+  if (resolved.error !== null) return { error: resolved.error };
+
+  let tree = null;
+  let treeError = null;
+  try {
+    tree = await treeId(root);
+  } catch (error) {
+    treeError = String(error.message ?? error);
+  }
+
+  let entries = [];
+  let ledgerErrors = [];
+  try {
+    const ledger = await readLedger(root);
+    entries = tree === null ? [] : ledger.entries.filter((e) => e.tree === tree);
+    ledgerErrors = ledger.errors;
+  } catch (error) {
+    ledgerErrors = [String(error.message ?? error)];
+  }
+
+  const cache = await readCheckCache(root).catch(() => null);
+  const { manifest } = await readManifest(root).catch(() => ({ manifest: null }));
+  const declared = [
+    ...(manifest?.gates?.preCommit ?? []),
+    ...(manifest?.gates?.prePush ?? []),
+  ];
+  const evidenceMode = manifest?.gates?.evidence;
+
+  const paths = await changedPaths(root, resolved.base);
+  const decisions = await changedDecisions(root, paths);
+
+  const passing = entries.filter((e) => e.exit === 0);
+  const unreviewed = [];
+  if (tree === null) unreviewed.push(`the tree could not be named (${treeError ?? 'not a git repository'})`);
+  else if (passing.length === 0) unreviewed.push('no passing run is recorded for this tree');
+  if (cache === null) unreviewed.push('gate state unmeasured (no check has run)');
+  for (const error of ledgerErrors) unreviewed.push(`ledger unreadable: ${error}`);
+
+  // ADR-008's vocabulary, exactly: BLOCK for a known failure, APPROVE WITH
+  // RESIDUAL RISK when the review budget ran out before something was read,
+  // APPROVE only when everything was. The constraint travels with the verdict:
+  // a residual-risk body never converts a known failure into an approval.
+  const blocking = cache?.blocking ?? 0;
+  const verdict = blocking > 0 ? 'BLOCK' : unreviewed.length > 0 ? 'APPROVE WITH RESIDUAL RISK' : 'APPROVE';
+
+  return {
+    error: null,
+    base: resolved.base,
+    tree,
+    evidence: { entries, errors: ledgerErrors },
+    decisions,
+    paths,
+    gates: {
+      declared,
+      evidenceMode: evidenceMode ?? null,
+      run: cache === null ? null : { gatesRun: cache.gatesRun, gatesTotal: cache.gatesTotal },
+      rulesOk: cache?.rulesOk ?? null,
+      hooksOk: cache?.hooksOk ?? null,
+      blocking,
+      warnings: cache?.warnings ?? 0,
+      cached: cache !== null,
+    },
+    verdict,
+    unreviewed,
+  };
+}
+
+/**
+ * The markdown body: four sections in a fixed order — evidence, changed
+ * decisions, gates, residual risk — so a snapshot can pin it byte for byte.
+ */
+export function renderPrBody(report) {
+  const lines = [];
+  lines.push('## Evidence');
+  lines.push('');
+  if (report.tree === null) {
+    lines.push('No tree recorded: run this inside a git repository.');
+  } else if (report.evidence.entries.length === 0) {
+    lines.push(`tree ${report.tree}`);
+    lines.push('No run is recorded for this tree.');
+  } else {
+    lines.push(`tree ${report.tree}`);
+    lines.push('');
+    for (const e of report.evidence.entries) {
+      lines.push(`- ${e.exit === 0 ? 'pass' : 'fail'} \`${e.cmd}\` (exit ${e.exit}, ${e.summary})`);
+    }
+  }
+  for (const error of report.evidence.errors) lines.push(`- ledger error: ${error}`);
+  lines.push('');
+  lines.push('## Changed decisions');
+  lines.push('');
+  if (report.decisions.length === 0) {
+    lines.push(`None${report.base === null ? ' (worktree diff against HEAD)' : ` (range ${report.base}...HEAD, plus worktree)`}.`);
+  } else {
+    for (const d of report.decisions) lines.push(`- ${d.id} — ${d.title} (${d.status})`);
+  }
+  lines.push('');
+  lines.push('## Gates');
+  lines.push('');
+  if (report.gates.cached) {
+    const g = report.gates;
+    lines.push(`- rules: ${g.rulesOk ? 'ok' : 'failing'}, hooks: ${g.hooksOk ? 'ok' : 'failing'}`);
+    lines.push(`- gates run: ${g.run.gatesRun}/${g.run.gatesTotal}, blocking: ${g.blocking}, warnings: ${g.warnings}`);
+    if (g.declared.length > 0) lines.push(`- declared: ${g.declared.join(', ')}`);
+  } else {
+    lines.push('No check has run: gate state unmeasured.');
+  }
+  lines.push('');
+  lines.push('## Residual risk (ADR-008)');
+  lines.push('');
+  lines.push(`Verdict: ${report.verdict}`);
+  if (report.unreviewed.length > 0) {
+    lines.push('');
+    lines.push('Not reviewed:');
+    for (const item of report.unreviewed) lines.push(`- ${item}`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/projection/baselines.mjs

@@ -76,7 +76,7 @@ trim_trailing_whitespace = false
 indent_style = space
 indent_size = 2
 
-[*.{py,pyi,java,kt,kts}]
+[*.{py,pyi,java,kt,kts,rs}]
 indent_size = 4
 
 [{Makefile,*.mk}]

package/src/projection/disclosure.mjs

@@ -25,7 +25,7 @@ const SKILL_DIRS = ['.agents/skills', '.cursor/skills', '.claude/skills', '.open
  * share a name both stay, because dropping one would hide a trigger.
  *
  * @param {string} root
- * @returns {Promise<{name: string, trigger: string, dir: string}[]>}
+ * @returns {Promise<{name: string, trigger: string, dir: string, file: string}[]>}
  */
 export async function installedSkills(root) {
   const seen = new Set();
@@ -61,7 +61,7 @@ export async function installedSkills(root) {
       const fallback = entry.isDirectory() ? entry.name : entry.name.replace(/\.md$/, '');
       const name = typeof meta.name === 'string' && meta.name !== '' ? meta.name : fallback;
       const trigger = typeof meta.description === 'string' ? meta.description.replace(/\s+/g, ' ').trim() : '';
-      skills.push({ name, trigger, dir });
+      skills.push({ name, trigger, dir, file: key });
     }
   }
   skills.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));

package/src/projection/loaders.mjs

@@ -146,10 +146,16 @@ export const LOADERS = [
     nested: 'cumulative up to the project root at session start; files below the workspace load when that area is read',
     skills: ['.agents/skills', '.opencode/skills', '.claude/skills'],
     hooks: {
-      path: '.opencode/plugins/',
+      path: '.opencode/plugins/simt-dev.js',
       verified:
         'OpenCode v2 plugins docs: direct .ts and .js files and immediate plugin packages are loaded from every discovered .opencode/plugins/ directory, and the plugins array in opencode.json(c)',
     },
+    agents: {
+      dir: '.opencode/agents',
+      ext: '.md',
+      verified:
+        'OpenCode v2 agents docs (opencode.ai/v2/docs/agents, read 2026-10-30): subagents are markdown files with a description frontmatter under .opencode/agents/',
+    },
     mcp: {
       path: 'opencode.json',
       key: 'mcp.servers',
@@ -242,6 +248,12 @@ export const LOADERS = [
       verified:
         'Claude Code hooks docs, hook locations: project settings at .claude/settings.json and .claude/settings.local.json, user settings at ~/.claude/settings.json',
     },
+    agents: {
+      dir: '.claude/agents',
+      ext: '.md',
+      verified:
+        'Claude Code subagents docs (code.claude.com/docs/en/sub-agents, read 2026-10-30): project subagents are markdown files with name and description frontmatter under .claude/agents/',
+    },
     mcp: {
       path: '.mcp.json',
       key: null,
@@ -320,6 +332,12 @@ export const LOADERS = [
       verified:
         'Codex hooks docs: <repo>/.codex/hooks.json or ~/.codex/hooks.json, or inline [hooks] tables in config.toml',
     },
+    agents: {
+      dir: '.codex/agents',
+      ext: '.toml',
+      verified:
+        'Codex custom agents docs (developers.openai.com/codex/subagents, read 2026-10-30): standalone TOML files under .codex/agents/ defining name, description and developer_instructions',
+    },
     mcp: {
       path: '.codex/config.toml',
       key: 'mcp_servers',
@@ -386,6 +404,12 @@ export const LOADERS = [
       path: '.cursor/hooks.json',
       verified: 'Cursor agent hooks docs: <project-root>/.cursor/hooks.json and ~/.cursor/hooks.json',
     },
+    agents: {
+      dir: '.cursor/agents',
+      ext: '.md',
+      verified:
+        'Cursor subagents docs (cursor.com/docs/subagents, read 2026-10-30): project subagents are markdown files with name and description frontmatter under .cursor/agents/',
+    },
     mcp: {
       path: '.cursor/mcp.json',
       key: null,
@@ -470,6 +494,12 @@ export const LOADERS = [
       path: '.agents/hooks.json',
       verified: 'Antigravity hooks docs: workspace level .agents/hooks.json, global ~/.gemini/config/hooks.json',
     },
+    agents: {
+      dir: '.agents/agents',
+      ext: '.md',
+      verified:
+        'Google Antigravity subagents docs (antigravity.google/docs/subagents, read 2026-10-30): project subagents are markdown files with name and description frontmatter under .agents/agents/',
+    },
     mcp: {
       path: '.agents/mcp_config.json',
       key: null,
@@ -541,6 +571,12 @@ export const LOADERS = [
       verified:
         'Gemini CLI hooks reference (geminicli.com/docs/hooks/reference/, read 2026-10-26): a project .gemini/settings.json carries a top-level hooks object whose events are arrays of {matcher, hooks:[{type:"command",command,timeout? (milliseconds)}]} — the same shape Claude and Codex use; BeforeTool denies with {decision:"deny",reason}, BeforeAgent and AfterTool inject via hookSpecificOutput.additionalContext',
     },
+    agents: {
+      dir: '.gemini/agents',
+      ext: '.md',
+      verified:
+        'Gemini CLI subagents docs (geminicli.com/docs/core/subagents, read 2026-10-30): project subagents are markdown files with name and description frontmatter under .gemini/agents/',
+    },
     mcp: {
       path: '.gemini/settings.json',
       key: 'mcpServers',
@@ -603,6 +639,8 @@ export const LOADERS = [
     skillsNote: 'no project skill directory is documented for Copilot',
     hooks: null,
     hooksNote: 'no hooks file is documented for Copilot in any first-party page checked on 2026-10-14',
+    agents: null,
+    agentsNote: 'no file-based agents are documented for Copilot in any first-party page checked on 2026-10-30',
     mcp: {
       path: '.vscode/mcp.json',
       key: null,
@@ -707,6 +745,8 @@ export const LOADERS = [
     hooks: null,
     hooksNote:
       'DeepSeek harness hooks docs: the Claude Code and Codex bridges take an explicit configPath, and project-local hooks.json discovery is still marked TODO, so no repository path is loaded by default',
+    agents: null,
+    agentsNote: 'no file-based agents are documented for the DeepSeek harness in any first-party page checked on 2026-10-30',
     mcp: {
       path: null,
       key: '@deepseek-ai/dsh-mcp-client',

package/src/projection/lock.mjs

@@ -13,11 +13,10 @@ import { join } from 'node:path';
 
 import { readLockedVariants } from '../kernel/variants.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
+import { LOCK_FILE, LOCK_LEGACY } from '../name.mjs';
 import { desiredRegion, provenanceDigest, LOCAL_PROFILE_DIR } from './rules.mjs';
 import { readManifest } from './manifest.mjs';
 
-export const LOCK_FILE = 'simt-dev.lock.json';
-
 /** Manifest keys that change what the region contains. Anything else in the file is
  *  the repository's own notes, and hashing it would make a comment fail the lock. */
 const MANIFEST_KEYS = ['mode', 'budget', 'shared', 'surfaces', 'gates'];
@@ -28,12 +27,15 @@ const MANIFEST_KEYS = ['mode', 'budget', 'shared', 'surfaces', 'gates'];
  * @param {string} root
  * @param {object} [flags] the same flags `sync` rendered with, so the output is the
  *   body that was written and not a body for a different set of surfaces
+ * @param {object} [manifest] the manifest to digest, in place of the one on disk. A
+ *   writer that is about to write a manifest (a fresh `init`) passes it here so the
+ *   lock records the state the repo will have, not the state it has (Q29).
  */
-export async function computeLock(root, flags = {}) {
+export async function computeLock(root, flags = {}, manifest = undefined) {
   const variants =
     flags?.variants !== undefined ? flags.variants : await readLockedVariants(root);
   const desired = await desiredRegion(root, { ...flags, variants });
-  const inputs = await inputDigest(root, variants);
+  const inputs = await inputDigest(root, variants, manifest);
   const outputs = createHash('sha256').update(desired.body).digest('hex');
   const hasVariants =
     variants && typeof variants === 'object' && Object.keys(variants).length > 0;
@@ -41,7 +43,7 @@ export async function computeLock(root, flags = {}) {
 }
 
 /**
- * Record locked variant winners in `simt-dev.lock.json` alongside updated digests.
+ * Record locked variant winners in `simt.lock.json` alongside updated digests.
  */
 export async function writeLockVariants(root, nextVariants, flags = {}) {
   const existing = await readLockedVariants(root);
@@ -53,15 +55,20 @@ export async function writeLockVariants(root, nextVariants, flags = {}) {
 
 /** Read a lock, or null when the file is not there. A file that does not parse is an
  *  error the caller reports, not a missing lock: absence and damage are different
- *  repairs. */
+ *  repairs. A lock under the legacy name is a lock (ADR-110): it is read until the
+ *  next write migrates it, and a permission failure on the new name is not an excuse
+ *  to fall back to an older file. */
 export async function readLock(root) {
-  let text;
-  try {
-    text = await readFile(join(root, LOCK_FILE), 'utf8');
-  } catch (error) {
-    if (error.code === 'ENOENT') return { lock: null, error: null };
-    throw error;
+  let text = null;
+  for (const name of [LOCK_FILE, LOCK_LEGACY]) {
+    try {
+      text = await readFile(join(root, name), 'utf8');
+      break;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
   }
+  if (text === null) return { lock: null, error: null };
   try {
     const lock = JSON.parse(text);
     if (typeof lock?.inputs !== 'string' || typeof lock?.outputs !== 'string') {
@@ -79,13 +86,13 @@ export async function readLock(root) {
   }
 }
 
-async function inputDigest(root, variants = {}) {
+async function inputDigest(root, variants = {}, manifest = undefined) {
   const hash = createHash('sha256');
   hash.update(`provenance:${await provenanceDigest()}\n`);
   const { stack, facts } = await fingerprint(root);
   hash.update(`signals:${JSON.stringify({ stack, facts })}\n`);
-  const { manifest } = await readManifest(root);
   const owned = {};
+  if (manifest === undefined) manifest = (await readManifest(root)).manifest;
   if (manifest && typeof manifest === 'object') {
     for (const key of MANIFEST_KEYS) {
       if (manifest[key] !== undefined) owned[key] = manifest[key];