simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/src/compare/discover.mjs

@@ -0,0 +1,212 @@
+// Find the sibling repositories a `simt-dev compare` should report on.
+//
+// Three things here are load-bearing, and each exists because the alternative is
+// a wrong answer rather than a missing one:
+//
+//   1. `.git` may be a DIRECTORY (a normal repo) or a FILE (a linked worktree).
+//      stat-following the directory scan alone misses every worktree, and the
+//      estate has one. A tool that silently omits a repo is worse than one that
+//      lists it as a repo, because an agent reads absence as "nothing there".
+//   2. A git worktree is not an independent consumer. It shares another repo's
+//      object store and its `.git` file points at that repo's `worktrees/` entry,
+//      so it must be attributed to its parent or a projection drift gets reported
+//      against the wrong directory.
+//   3. Directories that are not repos are not candidates, but they are still
+//      COUNTED. A directory of 25 PNG screenshots is not a rule source; silently dropping it
+//      hides the fact that a directory in the workspace is unmanaged, which is a
+//      real finding during a migration.
+//
+// Nothing here assumes a workspace layout, a repo count, or that simt-dev's
+// siblings are git repos at all (ADR-013: the tool must be useful outside SIMT).
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+
+/** `@param {string} p` @returns {Promise<boolean>} true when `p` is a directory. */
+async function isDir(p) {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** `@param {string} p` @returns {Promise<string|null>} file contents, or null. */
+async function readIfFile(p) {
+  try {
+    return await readFile(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The raw `gitdir:` pointer from a `.git` file, or null when the file is not one.
+ *
+ * The pointer is NOT resolved here: a relative pointer is relative to the
+ * worktree, not to the process cwd, and only the caller knows the worktree.
+ */
+export function parseGitdirPointer(text) {
+  if (typeof text !== 'string') return null;
+  const match = /^gitdir:\s*(.+)$/m.exec(text.trim());
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Split a resolved `gitdir` path into the repo that owns the worktree and the
+ * worktree's own slug, or null when the path is not a worktree entry.
+ *
+ * `<repo>/.git/worktrees/<slug>` - so `<slug>` is the worktree directory name with
+ * its leading dot dropped and `/` turned into `-`: `.wt-wear-redesign` becomes
+ * `-wt-wear-redesign`.
+ */
+export function ownerFromGitdir(gitdir) {
+  if (!gitdir) return null;
+  // The leading slash is significant: splitting on '/' and dropping empty parts
+  // would turn `/a/b/.git/...` into `a/b`, a path that then resolves against the
+  // cwd instead of the filesystem root. Absolute stays absolute.
+  const absolute = gitdir.startsWith('/');
+  const parts = gitdir.split('/').filter(Boolean);
+  const at = parts.lastIndexOf('worktrees');
+  if (at < 2) return null;
+  const owner = parts.slice(0, at - 1).join('/');
+  if (owner === '') return null;
+  return { ownerDir: absolute ? `/${owner}` : owner, slug: parts[at + 1] ?? '' };
+}
+
+/**
+ * Compare a worktree's directory name against its git slug.
+ *
+ * The slug loses the leading dot, so `.wt-wear-redesign` -> `-wt-wear-redesign`.
+ * A mismatch means the directory was renamed after `git worktree add` and the
+ * slug can no longer be trusted to identify which repo owns it - which is exactly
+ * when reporting the wrong owner would be most damaging, because the finding
+ * would be attributed to an innocent repo.
+ */
+export function slugMatchesDir(slug, dirName) {
+  if (!slug || !dirName) return false;
+  const normalise = (s) => s.replace(/^[.-]+/, '');
+  return normalise(slug) === normalise(dirName);
+}
+
+/**
+ * Classify one candidate directory.
+ * @returns {Promise<{kind:'repo'|'worktree'|'directory'|'unreadable', gitdir?:string,
+ *                    owner?:string, ownerMatches?:boolean, slug?:string}>}
+ */
+export async function classify(dir) {
+  const git = join(dir, '.git');
+  const info = await stat(git).catch(() => null);
+
+  if (info === null) {
+    // No .git at all. It may still be a readable directory (an unmanaged
+    // workspace member) or not readable at all; either way it is not a repo.
+    return { kind: (await isDir(dir)) ? 'directory' : 'unreadable' };
+  }
+  if (info.isDirectory()) return { kind: 'repo' };
+
+  const text = await readIfFile(git);
+  const raw = parseGitdirPointer(text);
+  if (!raw) {
+    // A .git file that is not a gitdir pointer is something else entirely, and
+    // treating it as a repo would make every later command fail confusingly.
+    return { kind: 'directory' };
+  }
+
+  // A relative pointer is relative to the worktree, not to the cwd.
+  const gitdir = raw.startsWith('/') ? raw : resolve(dir, raw);
+  const owner = ownerFromGitdir(gitdir);
+  const dirName = basename(dir);
+  return {
+    kind: 'worktree',
+    gitdir,
+    owner: owner?.ownerDir ?? null,
+    ownerName: owner ? basename(owner.ownerDir) : null,
+    ownerMatches: owner ? slugMatchesDir(owner.slug, dirName) : false,
+    slug: owner?.slug ?? null,
+  };
+}
+
+/**
+ * Scan `root` and classify what is there.
+ *
+ * Two shapes are both valid, and which one you have is a FACT of the filesystem rather
+ * than something the caller has to configure (ADR-014):
+ *
+ *   - `root` IS a repository -> it is the single repo to report on. This is the
+ *     common case outside a multi-repo workspace, and treating it as an error
+ *     ("contains no git repositories") would mean the tool only works for people
+ *     who happen to keep several repos together.
+ *   - `root` CONTAINS repositories -> its immediate children are the estate.
+ *
+ * Only the second shape scans one level deep, on purpose. The estate is flat
+ * siblings; a recursive walk would descend into node_modules and every build output,
+ * which is unbounded work for a dashboard. A monorepo names its members explicitly
+ * (ADR ruling #2).
+ *
+ * @returns {Promise<{root:string, shape:'repo'|'workspace', repos:string[],
+ *                    worktrees:object[], directories:string[], error:string|null}>}
+ */
+export async function discover(root) {
+  const self = await classify(root);
+  if (self.kind === 'repo') {
+    return { root, shape: 'repo', repos: [root], worktrees: [], directories: [], error: null };
+  }
+  if (self.kind === 'worktree') {
+    // A worktree passed directly is attributed, never counted: its files are its
+    // parent's HEAD checked out elsewhere, so reporting it as a consumer would
+    // double-count one repo's drift.
+    return {
+      root,
+      shape: 'repo',
+      repos: [],
+      worktrees: [{ path: root, name: basename(root), ...self }],
+      directories: [],
+      error: null,
+    };
+  }
+
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    return {
+      root,
+      shape: 'workspace',
+      repos: [],
+      worktrees: [],
+      directories: [],
+      error: error.code ?? String(error),
+    };
+  }
+
+  const repos = [];
+  const worktrees = [];
+  const directories = [];
+
+  for (const entry of entries) {
+    // A dotfile is never a consumer: `.wt-wear-redesign` is caught as a worktree
+    // below, and skipping dotdirs here only removes editor and VCS noise.
+    if (entry.name.startsWith('.') && !entry.name.startsWith('.wt')) continue;
+    if (!entry.isDirectory()) continue;
+
+    const path = join(root, entry.name);
+    const kind = await classify(path);
+    if (kind.kind === 'repo') repos.push(path);
+    else if (kind.kind === 'worktree') worktrees.push({ path, name: entry.name, ...kind });
+    else if (kind.kind === 'directory') directories.push(path);
+  }
+
+  // A stable order makes two runs diffable, which is the whole point of a
+  // dashboard: an agent comparing yesterday's output to today's must not be
+  // reading reordering as change.
+  const byName = (a, b) => basename(a).localeCompare(basename(b));
+  return {
+    root,
+    shape: 'workspace',
+    repos: repos.sort(byName),
+    worktrees: worktrees.sort((a, b) => a.name.localeCompare(b.name)),
+    directories: directories.sort(byName),
+    error: null,
+  };
+}

simt_dev/vendored/src/compare/hooksstate.mjs

@@ -0,0 +1,159 @@
+// Read a repo's hook routing and shim state without changing anything.
+//
+// This is the read half of what `simt-dev hooks status` does inline. It is a separate
+// module because two callers need it - `hooks status` and `simt-dev compare` - and a
+// second implementation of "is this shim current?" would be exactly the
+// duplicated-source-of-truth problem the tool exists to remove. `compare` reads it
+// for N repos, so it must not shell out per repo per event.
+
+import { execFile } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, fileFor, renderShim } from '../hooks/shim.mjs';
+import { foreignHooks, resolveHooksDir } from '../hooks/where.mjs';
+
+const exec = promisify(execFile);
+
+/**
+ * The chained shim at `path`, read back out of the file itself.
+ *
+ * Content, for the reason given on `CHAIN_MARKER`: the file is named after the
+ * repository's hook, so the name is exactly the thing that cannot identify it.
+ *
+ * The target is parsed out of the file rather than remembered from install time
+ * because the only authority on what a shim does is the shim. A re-install has to
+ * render the identical bytes, and rendering them from a remembered target would let
+ * the two drift the moment a repository moved.
+ *
+ * @param {string} path
+ * @returns {Promise<{event:string, target:string}|null>}
+ */
+export async function readChainedShim(path) {
+  let content;
+  try {
+    content = await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+  if (!content.includes(CHAIN_MARKER)) return null;
+  const target = /^TARGET='(.+)'$/m.exec(content);
+  const event = /^# simt-dev does not gate (\S+),/m.exec(content);
+  if (!target || !event) return null;
+  return { event: event[1], target: target[1] };
+}
+
+/** Whether this file is a chained shim this tool wrote. */
+async function isChainedShim(path) {
+  return (await readChainedShim(path)) !== null;
+}
+
+/** `core.hooksPath`, or null when unset or the repo is not a git repo. */
+export async function readHooksPath(root) {
+  try {
+    const { stdout } = await exec('git', ['config', '--get', HOOKS_PATH_KEY], { cwd: root });
+    const value = stdout.trim();
+    return value === '' ? null : value;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One shim's state. A shim that differs from what this simt-dev generates is
+ * `stale`: the gates it enforces are from another version, so it cannot be
+ * assumed to know about a gate added since.
+ */
+export async function describeShim(path) {
+  let content;
+  try {
+    content = await readFile(path, 'utf8');
+  } catch {
+    return { present: false, executable: false, stale: false };
+  }
+  let info;
+  try {
+    info = await stat(path);
+  } catch {
+    return { present: false, executable: false, stale: false };
+  }
+  let stale = true;
+  try {
+    stale = content !== renderShim(basename(path));
+  } catch {
+    stale = true;
+  }
+  return { present: true, executable: (info.mode & 0o111) !== 0, stale };
+}
+
+/**
+ * @param {string} root
+ * @param {{declaresGate?: (event:string)=>boolean}} [options] a missing shim is
+ *   only a problem when the repo has a gate that shim would enforce.
+ * @returns {Promise<{current:string|null, routed:boolean, complete:boolean,
+ *                    installed:object[], foreign:object[], liveDir:string|null,
+ *                    problems:string[]}>}
+ */
+export async function readHooksState(root, options = {}) {
+  const declaresGate = options.declaresGate ?? (() => true);
+  const current = await readHooksPath(root);
+  const installed = [];
+  for (const event of EVENTS) {
+    installed.push({ event, ...(await describeShim(join(root, fileFor(event)))) });
+  }
+
+  // What git runs right now, which is not the same question as "is a simt-dev
+  // shim installed". Before this existed the tool read an unset core.hooksPath
+  // as "no hooks" and reported a live hand-written hook as not installed.
+  const where = await resolveHooksDir(root);
+  const live = where.how === 'not-a-repo' ? [] : await foreignHooks(root);
+  // A shim is also called `pre-commit`, so the name cannot tell ours from a
+  // hand-written one. Only the bytes can.
+  const foreign = [];
+  const chained = [];
+  for (const hook of live) {
+    if (EVENTS.includes(hook.event) && !(await describeShim(hook.path)).stale) continue;
+    // A chained shim is ours too, and its name says nothing: `post-commit` is what the
+    // repository called its own hook, and the shim exists under that name precisely so
+    // git finds it. Reading it as foreign would make every re-install refuse with "this
+    // repo already runs hooks simt did not write" - a shim this tool wrote, refusing
+    // itself. Identity is content, the same rule as the dispatcher shim above.
+    const chain = await readChainedShim(hook.path);
+    if (chain) {
+      chained.push({ ...chain, path: hook.path });
+      continue;
+    }
+    foreign.push(hook);
+  }
+
+  const problems = [];
+  for (const i of installed) {
+    if (!declaresGate(i.event)) continue;
+    if (!i.present) problems.push(`${i.event} not installed`);
+    else if (!i.executable) problems.push(`${i.event} is not executable`);
+    else if (i.stale) problems.push(`${i.event} differs from this simt-dev; reinstall`);
+  }
+  for (const f of foreign) {
+    problems.push(`git runs ${f.event} at ${f.path} (${f.bytes} bytes), which is not a simt-dev shim`);
+  }
+
+  return {
+    current,
+    routed: current === HOOKS_DIR,
+    // Complete means routed AND every shim present, executable and current. A repo
+    // can route correctly while a shim is missing, which looks installed and is not.
+    complete: current === HOOKS_DIR && problems.length === 0,
+    installed,
+    foreign,
+    // The chained shims this repo is already running, read back off disk. `install`
+    // re-renders them from here so a second run keeps maintaining them rather than
+    // quietly forgetting them; without this field the set of things install maintains
+    // would depend on whether the operator happened to run it twice.
+    chained,
+    liveDir: where.dir,
+    problems,
+  };
+}
+
+export { HOOKS_DIR, HOOKS_PATH_KEY };

simt_dev/vendored/src/compare/row.mjs

@@ -0,0 +1,299 @@
+// The matrix a `simt-dev compare` row is built from: one repo's adoption state.
+//
+// The shape of a row answers one question - "would this repo behave correctly if
+// an agent followed it today?" - from the four things that can make it not:
+//
+//   manifest   is the repo in the ecosystem at all?
+//   region     does the committed projection match this simt-dev?
+//   hooks      would a commit actually be gated?
+//   gates      do the declared gates exist, and can they run?
+//
+// A repo can be adopted and still wrong (drifted region, missing hooks), which is
+// the case a hand audit misses: the repo LOOKS done. That is why these are four
+// columns and not one status.
+//
+// Ordering within a row is fixed. Output design (plan 0002 section 6) requires one
+// fact per line in a stable field order so two runs diff cleanly; a row that
+// reordered its columns would make every comparison between two runs unreadable.
+
+import { checkTargets, PRIMARY_TARGET } from '../projection/project.mjs';
+import { readManifest } from '../projection/manifest.mjs';
+import { loadRules, select } from '../projection/rules.mjs';
+import { knownGates } from '../hooks/resolve.mjs';
+import { fingerprint } from '../resolve/fingerprint.mjs';
+import { readHooksState } from './hooksstate.mjs';
+import { CLI } from '../name.mjs';
+import { MANIFEST_FILE } from '../name.mjs';
+
+/**
+ * @typedef {object} RepoRow
+ * @property {string} name        directory name, the thing a human reads
+ * @property {string} path
+ * @property {'adopted'|'unmanaged'|'broken'} adoption
+ * @property {string|null} id     manifest id, when declared
+ * @property {string[]} stack
+ * @property {string[]} facts
+ * @property {string[]} profiles  profile ids that would be selected
+ * @property {string|null} pinnedSha
+ * @property {string|null} recordedSha
+ * @property {'current'|'drift'|'unmanaged'|'absent'|'malformed'} region
+ * @property {string|null} regionDetail
+ * @property {boolean} hooksRouted   core.hooksPath points at the shared dispatcher
+ * @property {boolean} hooksComplete every event installed, executable, not stale
+ * @property {string[]} gatesDeclared
+ * @property {string[]} gateProblems
+ * @property {string[]} problems     everything wrong, one line each; drives the exit code
+ * @property {string[]} notes        worth knowing, but not wrong; does NOT drive the exit code
+ */
+
+/**
+ * Build one row. Never throws: a repo that cannot be read becomes a row with a
+ * problem, because a dashboard that drops unreadable repos reports a smaller
+ * estate than exists and the reader has no way to know.
+ *
+ * @param {string} path
+ * @param {{expectedSha: string, gates: Set<string>}} context
+ * @returns {Promise<RepoRow>}
+ */
+export async function buildRow(path, context) {
+  const name = path.split('/').filter(Boolean).pop() ?? path;
+  const problems = [];
+  const notes = [];
+
+  const [manifest, fp, hooks, findings] = await Promise.all([
+    readManifest(path),
+    fingerprint(path),
+    readHooksState(path),
+    checkTargets(path),
+  ]);
+
+  // The row's `region` stays the AGENTS.md finding, because that is what a reader
+  // recognises. The rule files and pointers are summarised beside it, because a repo
+  // can have a current AGENTS.md and three stale rule files - which is exactly the
+  // state a rule written to four surfaces can drift into.
+  const region = findings.find((f) => f.file === PRIMARY_TARGET) ?? { status: 'absent' };
+  const ruleFindings = findings.filter((f) => f.surface !== undefined);
+  const pointers = findings.filter((f) => f.status?.startsWith('pointer'));
+
+  // Adoption is settled BEFORE any problem is collected. Every gate below asks
+  // `row.adoption`, and this block used to run after them - so the stale-rule-file gate
+  // below compared against the initialiser's `'unmanaged'` and could never fire. In the
+  // estate, with 0 of 3 rule files current, report a problems list that mentioned
+  // neither the rule files nor anything the exit code could see. A gate
+  // that reads a field the line above has not set yet is not a gate.
+  //
+  // An absent manifest is not a defect; it is the pre-adoption state, which is the normal
+  // condition of most repos on day one of a migration. It is counted and reported, never
+  // called a problem.
+  const adoption = !manifest.exists ? 'unmanaged' : manifest.error ? 'broken' : 'adopted';
+
+  // The profile ids this repo's signals select. These are the two calls `desiredRegion`
+  // makes, on the same inputs it uses, so a dashboard cannot disagree with what `sync`
+  // would render. `test/compare.test.mjs` asserts the two agree rather than trusting this
+  // comment: the field sat at its initial value for the whole life of this file, and the
+  // prose above it was still true.
+  const { selected: chosen } = select(await loadRules(path), fp.stack ?? [], fp.facts ?? []);
+
+  const row = {
+    name,
+    path,
+    adoption,
+    id: manifest.manifest?.id ?? null,
+    stack: fp.stack ?? [],
+    declaredStack: manifest.manifest?.stack ?? [],
+    facts: fp.facts ?? [],
+    profiles: chosen.map((r) => r.id),
+    pinnedSha: manifest.manifest?.projection?.simtDevSha ?? null,
+    recordedSha: region.recordedSha ?? null,
+    region: region.status,
+    regionDetail: region.detail ?? null,
+    surfaces: manifest.manifest?.surfaces ?? null,
+    ruleFiles: {
+      total: ruleFindings.filter((f) => f.status !== 'orphaned').length,
+      current: ruleFindings.filter((f) => f.status === 'current').length,
+      stale: ruleFindings.filter((f) => f.status !== 'current' && f.status !== 'orphaned').map((f) => f.file),
+      // Managed rule files this run would not write, counted apart from the rule files.
+      // They are a different kind of thing: `sync` cannot repair them and would never
+      // write them again, so they are a note with a remedy and not a problem
+      // (ADR-021 ruling 6).
+      orphaned: ruleFindings.filter((f) => f.status === 'orphaned').map((f) => f.file),
+    },
+    pointers: pointers.map((p) => ({ file: p.file, state: p.status })),
+    hooksRouted: hooks.routed,
+    hooksComplete: hooks.complete,
+    gatesDeclared: declaredGates(manifest.manifest),
+    gateProblems: [],
+    foreignHooks: [],
+    problems,
+    notes,
+  };
+
+  // A rule file on any surface that is not current is a defect the row would
+  // otherwise hide. It names the files, because "something is stale" is not
+  // actionable and this command exists to be acted on.
+  //
+  // Gated on adoption, and that gate is the whole point. A repo that has never been
+  // adopted has no rule files at all, and reporting them as "not current" turns the
+  // normal mid-migration state into a red estate — the same mistake ADR-018 records
+  // for hooks, where an unadopted repo's own hooks are a note rather than a problem.
+  if (row.ruleFiles.orphaned.length > 0) {
+    notes.push(
+      `${row.ruleFiles.orphaned.length} generated rule file(s) repeat text already folded into AGENTS.md (${row.ruleFiles.orphaned.join(', ')}); delete them, or the reader loads the rule twice. simt-dev will not remove a file it wrote.`,
+    );
+  }
+
+  if (adoption === 'adopted' && row.ruleFiles.stale.length > 0) {
+    problems.push(
+      `${row.ruleFiles.stale.length} of ${row.ruleFiles.total} rule files are not current (${row.ruleFiles.stale.join(', ')}); run: ${CLI} sync --yes`,
+    );
+  }
+
+  if (manifest.error) {
+    problems.push(`${MANIFEST_FILE} ${manifest.error}`);
+  }
+
+  // --- region --------------------------------------------------------------
+  // Only meaningful for an adopted repo. An unmanaged repo has no manifest, so
+  // its `absent` region is a consequence of not having adopted, not a second
+  // independent defect - reporting both would double-count one root cause.
+  if (adoption === 'adopted') {
+    if (region.status === 'drift') {
+      // A drift has two causes with different fixes, and the SHA says which. When
+      // the recorded SHA matches this simt-dev, the region was hand-edited and
+      // `simt-dev sync --yes` is right; when it does not, the repo is simply behind and the
+      // same command is also right - but the message must not claim a version
+      // mismatch when the versions are identical, because that sends the reader
+      // looking for a pin that is already correct.
+      const sameSha = region.recordedSha === context.expectedSha;
+      problems.push(
+        sameSha
+          ? `the generated region was hand-edited; restore it with: ${CLI} sync --yes`
+          : `projection is ${region.recordedSha ?? '(no sha)'} but this simt-dev is ${context.expectedSha}; run: ${CLI} sync --yes`,
+      );
+    } else if (region.status === 'malformed') {
+      problems.push(`generated region is malformed: ${region.detail}; run: ${CLI} sync --yes`);
+    } else if (region.status === 'unmanaged') {
+      problems.push(`adopted but AGENTS.md has no generated region; run: ${CLI} sync --yes`);
+    } else if (region.status === 'absent') {
+      problems.push(`adopted but AGENTS.md does not exist; run: ${CLI} sync --yes`);
+    } else if (region.status === 'current' && row.pinnedSha && row.pinnedSha !== context.expectedSha) {
+      // The region matches this simt-dev but the manifest pins an older one. The
+      // next sync would stamp the newer SHA silently, so the pin is the thing
+      // that is stale - and it is the value `simt-dev upgrade` reads.
+      problems.push(
+        `manifest pins simt-dev ${row.pinnedSha}, this is ${context.expectedSha}; run: ${CLI} upgrade`,
+      );
+    }
+  }
+
+  // --- declared stack vs detected stack ------------------------------------
+  // `simt-dev.json` records what the repo claims to be; fingerprint records what
+  // the files prove. Selection uses detection, so a stale claim does not change
+  // which profile is projected - but it DOES mean the manifest misdescribes the
+  // repo, and a reader of the manifest would be misled. Reported rather than
+  // silently reconciled: picking a winner would hide the edit that caused it.
+  //
+  // An empty declared stack counts as a disagreement when detection found
+  // something. That is not pedantry: `init` writes the detected stack, so an empty
+  // one means either the repo was adopted before the markers existed or someone
+  // emptied it by hand, and in both cases the manifest is wrong.
+  if (adoption === 'adopted') {
+    const declared = new Set(row.declaredStack);
+    const detected = new Set(row.stack);
+    const extra = row.declaredStack.filter((t) => !detected.has(t));
+    const missing = row.stack.filter((t) => !declared.has(t));
+    if (extra.length > 0 || missing.length > 0) {
+      const parts = [];
+      if (extra.length > 0) parts.push(`declares ${extra.join(', ')} but no marker proves it`);
+      if (missing.length > 0) parts.push(`detected ${missing.join(', ')} but the manifest omits it`);
+      problems.push(`manifest stack disagrees with detection: ${parts.join('; ')}`);
+    }
+  }
+
+  // --- hooks ---------------------------------------------------------------
+  // A repo running its own hooks is a fact about today, independent of whether
+  // simt-dev has been adopted. It is a NOTE, not a problem: adopting this repo is
+  // the normal mid-migration state, and a dashboard that goes red for it teaches
+  // everyone to ignore the dashboard. What it costs is only visible at install
+  // time, which is where the takeover guard asks for consent.
+  row.foreignHooks = hooks.foreign.map((h) => ({ event: h.event, bytes: h.bytes }));
+  for (const h of hooks.foreign) {
+    notes.push(`runs its own ${h.event} (${h.bytes} bytes); hooks install will replace it and asks first`);
+  }
+
+  if (adoption === 'adopted') {
+    if (!hooks.routed) {
+      problems.push(
+        hooks.current === null
+          ? `no core.hooksPath; commits are ungated. run: ${CLI} hooks install --yes`
+          : `core.hooksPath is "${hooks.current}", not the shared dispatcher; run: ${CLI} hooks install --yes`,
+      );
+    } else if (!hooks.complete) {
+      for (const h of hooks.problems) problems.push(`hooks: ${h}`);
+    }
+  }
+
+  // --- gates ---------------------------------------------------------------
+  // A declared gate the dispatcher does not know is a hard failure at commit
+  // time (step 8 fails closed), so it is a defect here. A command-kind gate with
+  // no command declared is the same failure one step later.
+  if (adoption === 'adopted') {
+    const commands = manifest.manifest?.gates?.commands ?? {};
+    const invoked = new Set([...row.gatesDeclared, ...Object.keys(commands)]);
+    const unknown = [...invoked].filter((g) => !context.gates.has(g)).sort();
+    const uncommanded = [...invoked].filter(
+      (g) => context.gates.has(g) && context.gateKinds?.get(g) === 'command' && !commands[g],
+    );
+    const neverRun = Object.keys(commands)
+      .filter((c) => !row.gatesDeclared.includes(c))
+      .sort();
+
+    row.gateProblems = [
+      ...unknown.map((g) => `gate "${g}" is not a known gate`),
+      ...uncommanded.map((g) => `gate "${g}" is a command gate with no declared command`),
+      ...neverRun.map((c) => `declared command "${c}" is in no gate list`),
+    ];
+    problems.push(...row.gateProblems);
+  }
+
+  return row;
+}
+
+function declaredGates(manifest) {
+  if (!manifest) return [];
+  return [...(manifest.gates?.preCommit ?? []), ...(manifest.gates?.prePush ?? [])];
+}
+
+/**
+ * The headline facts about an estate, aggregated over rows.
+ *
+ * Counts, not verdicts. A single summary line an agent can read before deciding
+ * whether it needs the table - and the numbers that make a migration legible
+ * ("12 of 16 repos still unmanaged") in a way a per-repo list cannot.
+ */
+export function summarise(rows, extra = {}) {
+  const count = (pred) => rows.filter(pred).length;
+  const shas = new Map();
+  for (const r of rows) {
+    const sha = r.pinnedSha ?? '(none)';
+    shas.set(sha, (shas.get(sha) ?? 0) + 1);
+  }
+  return {
+    repos: rows.length,
+    adopted: count((r) => r.adoption === 'adopted'),
+    unmanaged: count((r) => r.adoption === 'unmanaged'),
+    broken: count((r) => r.adoption === 'broken'),
+    drifted: count((r) => r.region === 'drift'),
+    current: count((r) => r.region === 'current'),
+    noRegion: count((r) => r.region === 'unmanaged' || r.region === 'absent'),
+    malformed: count((r) => r.region === 'malformed'),
+    hooksRouted: count((r) => r.hooksRouted),
+    staleRuleFiles: rows.reduce((n, r) => n + (r.ruleFiles?.stale?.length ?? 0), 0),
+    withProblems: count((r) => r.problems.length > 0),
+    withOwnHooks: count((r) => (r.foreignHooks ?? []).length > 0),
+    shas: [...shas.entries()].sort((a, b) => (a[0] === '(none)' ? 1 : b[0] === '(none)' ? -1 : b[1] - a[1])),
+    ...extra,
+  };
+}
+
+export { knownGates };