simt-dev 0.7.0 → 0.7.1

package/src/commands/skills.mjs

@@ -10,6 +10,7 @@
 // black box.
 
 import { readFile, realpath } from 'node:fs/promises';
+import { repoContext } from '../context.mjs';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 
@@ -24,6 +25,7 @@ import { localSkillNodes } from '../resolve/local.mjs';
 import { nearMatches } from '../resolve/near.mjs';
 import { CLI } from '../name.mjs';
 import { parsePathList } from '../argv.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export { parsePathList };
 
@@ -82,11 +84,11 @@ async function skillsRegistry(args) {
  * costs a fingerprint plus a directory scan, so it runs only when the registry did
  * not answer.
  */
-async function findSkill(registry, root, name, verb) {
+async function findSkill(registry, root, name, verb, ctx) {
   if (!name) skillsFailure(`${verb} needs a skill name`, `usage: ${CLI} skills ${verb} <name>`, EXIT.USAGE);
   const skill = registry.skills.find((s) => s.name === name);
   if (skill) return skill;
-  const repoStack = (await fingerprint(root)).signals;
+  const repoStack = (await ctx.fingerprint()).signals;
   const local = (await localSkillNodes(root, registry, repoStack)).find((s) => s.name === name);
   if (local) return local;
   const near = nearMatches(name, registry.skills.map((s) => s.name));
@@ -114,7 +116,10 @@ function skillFacts(skill) {
 /** Tier 1: the selection the task resolves to, with the text packet's display sets. */
 export async function skillsBriefFacts(root, args = {}) {
   const registry = await skillsRegistry(args);
-  const repo = await fingerprint(root);
+  // One context per call: a second question about the same repository inside this
+  // command costs nothing (review 0003 Q67).
+  const ctx = args.ctx ?? repoContext(root);
+  const repo = await ctx.fingerprint();
   const { note: workspace, root: workspaceRoot } = await announceWorkspace(args);
   const repoStack = repo.signals;
   const paths = args.paths ? parsePathList(args.paths) : await dirtyPaths(root);
@@ -246,7 +251,7 @@ export async function skillsFindFacts(root, query, args = {}) {
     ...registry.skills
       .map((skill) => ({ skill, ...scoreSkill(skill, context) }))
       .filter((r) => selectionVerdict(r.evidence, r.reasons) === null),
-    ...(await localSkillNodes(root, registry, (await fingerprint(root)).signals))
+    ...(await localSkillNodes(root, registry, (await (args.ctx ?? repoContext(root)).fingerprint()).signals))
       .map((skill) => ({ skill, ...scoreSkill(skill, context) }))
       .filter((r) => r.score > 0),
   ].sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
@@ -259,7 +264,7 @@ export async function skillsFindFacts(root, query, args = {}) {
 /** Tier 2: one skill body and the metadata needed to judge it. */
 export async function skillsShowFacts(root, name, args = {}) {
   const registry = await skillsRegistry(args);
-  const skill = await findSkill(registry, root, name, 'show');
+  const skill = await findSkill(registry, root, name, 'show', args.ctx ?? repoContext(root));
   const { note: workspace, root: workspaceRoot } = await announceWorkspace(args);
   // The repo is a location for a declared source too, so `show` reads a body the
   // caller already has instead of reporting the body missing.
@@ -287,8 +292,9 @@ export async function skillsShowFacts(root, name, args = {}) {
 /** The signal chain for one skill in one repository. */
 export async function skillsWhyFacts(root, name, args = {}) {
   const registry = await skillsRegistry(args);
-  const skill = await findSkill(registry, root, name, 'why');
-  const repo = await fingerprint(root);
+  const ctx = args.ctx ?? repoContext(root);
+  const skill = await findSkill(registry, root, name, 'why', ctx);
+  const repo = await ctx.fingerprint();
   const paths = args.paths ? parsePathList(args.paths) : await dirtyPaths(root);
   const tokens = tokenize(args.task ?? '');
   const { score, reasons } = scoreSkill(skill, { repoStack: repo.signals, taskTokens: tokens, paths });
@@ -386,7 +392,6 @@ export async function indexCommand(args, flags) {
       '',
       `deferred entries return a pointer, not a body. Fetch one with: ${CLI} skills show <name>`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return EXIT.OK;
 }
@@ -429,14 +434,14 @@ async function emitAllFacts(facts, flags) {
   if (deferred.length > 0) {
     lines.push('', `DEFERRED ${deferred.length}: ${deferred.map((s) => s.name).join(', ')}`);
   }
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
 // --- find ---------------------------------------------------------------------
 
 export async function findCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   let facts;
   try {
     facts = await skillsFindFacts(root, args.join(' '), flags);
@@ -449,7 +454,6 @@ export async function findCommand(args, flags) {
   if (isJson(flags)) {
     emitJson(
       { ok: true, query, workspace, results },
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
@@ -469,17 +473,17 @@ export async function findCommand(args, flags) {
           `${r.name.padEnd(26)} ${kb(r.bytes).padStart(7)}  ${r.reasons.join(' ')}`,
       ),
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return EXIT.OK;
 }
 
 // --- brief: tier 1 ------------------------------------------------------------
 export async function briefCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
+  const ctx = repoContext(root);
   let facts;
   try {
-    facts = await skillsBriefFacts(root, flags);
+    facts = await skillsBriefFacts(root, { ...flags, ctx });
   } catch (error) {
     return fail(error.message, error.exitCode ?? EXIT.FAIL, error.remedy);
   }
@@ -498,21 +502,20 @@ export async function briefCommand(args, flags) {
   }
 
   if (facts.warning) {
-    const repo = await fingerprint(root);
+    const repo = await ctx.fingerprint();
     emit(
       [
         `repo ${root.split('/').pop()} (${repoLine(repo)})`,
         '',
         facts.warning,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
 
   const { shown, shownDeferred, shownUsed, pointerOnly, excludedEntries, workspace, workspaceRoot, budget } = facts;
   const lines = [];
-  const repo = await fingerprint(root);
+  const repo = await ctx.fingerprint();
 
   lines.push(
     `RESOLVED ${shown.length} skills, ${kb(shownUsed)}${flags.all || shownUsed <= budget ? '' : ' (budget capped)'} - repo ${root.split('/').pop()} (${repoLine(repo)})`,
@@ -533,7 +536,7 @@ export async function briefCommand(args, flags) {
       lines.push('', `NOT SELECTED ${hidden.length}`, '', `  notes: ${CLI} skills why <name> | ${CLI} skills show <name>`);
     }
     lines.push('', 'OVERRIDE  --skill <name> | --budget <bytes> | --all | --paths <globs>');
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -578,14 +581,14 @@ export async function briefCommand(args, flags) {
   }
 
   lines.push('', 'OVERRIDE  --skill <name> | --budget <bytes> | --all | --paths <globs>');
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
 // --- show: tier 2 -------------------------------------------------------------
 
 export async function showCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   let facts;
   try {
     facts = await skillsShowFacts(root, args[0], flags);
@@ -595,7 +598,7 @@ export async function showCommand(args, flags) {
   const { skill, workspace, body, bodyFrom, bodyText } = facts;
   const source = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
   if (isJson(flags)) {
-    emitJson({ ok: true, ...skill, workspace, body, bodyFrom, bodyText }, { maxBytes: flags.maxBytes ?? 0 });
+    emitJson({ ok: true, ...skill, workspace, body, bodyFrom, bodyText });
     return EXIT.OK;
   }
   emit(
@@ -618,7 +621,6 @@ export async function showCommand(args, flags) {
     ]
       .filter((l) => l !== null)
       .join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return EXIT.OK;
 }
@@ -626,7 +628,7 @@ export async function showCommand(args, flags) {
 // --- why ----------------------------------------------------------------------
 
 export async function whyCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   let facts;
   try {
     facts = await skillsWhyFacts(root, args[0], flags);
@@ -641,7 +643,7 @@ export async function whyCommand(args, flags) {
   // to scrape: a skill that can never be selected in this repo is a decision, not
   // a line of output.
   if (isJson(flags)) {
-    emitJson({ ok: true, command: 'skills why', ...facts }, { maxBytes: flags.maxBytes ?? 0 });
+    emitJson({ ok: true, command: 'skills why', ...facts });
     return EXIT.OK;
   }
 
@@ -667,7 +669,7 @@ export async function whyCommand(args, flags) {
   if (facts.variantOf) lines.push('', `variant-of      ${facts.variantOf} (sibling group, one body per stack)`);
   if (facts.requires?.length > 0) lines.push(`requires        ${facts.requires.join(', ')}`);
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -773,7 +775,7 @@ export async function evalCommand(positional, flags) {
   }
 
   lines.push('', okRun ? 'OK the resolver meets the gold corpus' : 'REGRESSION: the resolver no longer meets the gold corpus');
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return okRun ? EXIT.OK : EXIT.FAIL;
 }
 

package/src/commands/skillscompile.mjs

@@ -22,6 +22,7 @@ import { nearMatches } from '../resolve/near.mjs';
 import { resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
 import { CLI } from '../name.mjs';
 import { LOCAL_DIR } from '../state.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 async function readSkillRawText(skill, workspaceRoot, root) {
   const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
@@ -68,7 +69,7 @@ export async function compileCommand(args, flags) {
   const { registry, errors, ok } = await loadRegistry(null, flags);
   if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
 
-  const root = resolve(flags.root ?? process.cwd());
+  const root = resolve(commandRoot(flags));
   const ws = await resolveWorkspace(flags);
   const targetName = args[0] ?? null;
 
@@ -117,7 +118,6 @@ export async function compileCommand(args, flags) {
           splitPlan: s.splitPlan,
         })),
       },
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
@@ -150,7 +150,7 @@ export async function compileCommand(args, flags) {
     }
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -223,7 +223,6 @@ async function runSingleSkillCompile(skill, registry, { root, workspaceRoot, fla
           : null,
         proposal,
       },
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
@@ -246,7 +245,7 @@ async function runSingleSkillCompile(skill, registry, { root, workspaceRoot, fla
     }
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   if (!mode.apply) {
     note(`note    dry-run  nothing written; apply with: ${CLI} skills compile ${skill.name} --yes`);
   }

package/src/commands/skillsinstall.mjs

@@ -38,6 +38,7 @@ import { resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { nameProblems } from '../graph/spec.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 /**
  * Where skills live in this repo. The estate already has a convention - a
@@ -82,7 +83,7 @@ export async function installCommand(args, flags) {
   const ws = await resolveWorkspace(flags);
   if (ws.error) return fail(`workspace config: ${ws.error}`, EXIT.CONFIG, 'fix the JSON, or remove the file');
 
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   const repo = await fingerprint(root);
   const pick = await chooseSource(skill, repo.signals, flags, { root, workspaceRoot: ws.root });
   if (pick.error) return fail(pick.error, EXIT.USAGE, pick.remedy);
@@ -210,7 +211,6 @@ export async function installCommand(args, flags) {
       ]
         .filter((l) => l !== null)
         .join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
   }
 

package/src/commands/slice.mjs

@@ -52,6 +52,7 @@ import { coreIgnoreCase } from '../repo-root.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { CLI, MANIFEST_FILE } from '../name.mjs';
 import { LOCAL_DIR } from '../state.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 const exec = promisify(execFile);
 
@@ -125,6 +126,15 @@ function subjectFor(type, id, title) {
   return `${type}(${id.toLowerCase()}): ${description}`;
 }
 
+/**
+ * The trailer of every commit this tool writes: attribution to the tool, in the
+ * form git renders as a co-author. The slice-commit rule ends every message it
+ * defines with the same line, so a commit the tool writes and one an agent
+ * writes from the rule agree on attribution. Module-local: one caller needs no
+ * export, and an export is a promise to a caller (deadcode).
+ */
+const CO_AUTHOR = 'Co-Authored-By: Simt Dev <noreply@simt.space>';
+
 /** Resolve one named slice through `plan next`, which already knows missing and ambiguous. */
 async function resolveSlice(main, id) {
   const found = await planNext(main, id);
@@ -209,7 +219,7 @@ async function releaseSlice(main, id, session) {
 }
 
 export async function sliceCommand(sub, args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   if (sub === 'start') {
     const id = args[0];
     if (!id) return fail(`${CLI} slice start needs a slice id`, EXIT.USAGE, `run: ${CLI} plan next`);
@@ -286,7 +296,7 @@ async function startSlice(root, id, flags) {
       `state    ${preview.from} -> ${preview.to}`,
       `apply    ${apply}`,
     ];
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -363,7 +373,7 @@ async function startSlice(root, id, flags) {
     lease === null ? 'lease    (none)' : `lease    slice ${id} as ${session}`,
     `state    ${row.from} -> ${row.to}`,
   ];
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -468,7 +478,7 @@ async function finishSlice(root, id, flags) {
       `state    ${row.from} -> ${row.to}`,
       `apply    ${apply}`,
     ];
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -545,17 +555,18 @@ async function finishSlice(root, id, flags) {
       return EXIT.FAIL;
     }
     for (const n of gates.notes ?? []) note(`note     ${n}`);
-    emit(renderGateReport('pre-commit', declared, gates).join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(renderGateReport('pre-commit', declared, gates).join('\n'));
     return EXIT.FAIL;
   }
 
   let sha = null;
+  const message = `${subject}\n\n${CO_AUTHOR}`;
   try {
-    await git(root, ['commit', '-m', subject]);
+    await git(root, ['commit', '-m', message]);
     sha = await git(root, ['rev-parse', 'HEAD']);
   } catch (error) {
     const detail = String(error.stderr ?? error.message ?? error).trim().split('\n')[0];
-    return fail(`the gates passed but the commit failed: ${detail}`, EXIT.FAIL, `run: git -C ${root} commit -m ${JSON.stringify(subject)}`);
+    return fail(`the gates passed but the commit failed: ${detail}`, EXIT.FAIL, `run: git -C ${root} commit -m ${JSON.stringify(message)}`);
   }
 
   const row = await planDone(main, id, { sha, test, dryRun: false });
@@ -596,7 +607,7 @@ async function finishSlice(root, id, flags) {
   ];
   if (row.evidenceRecorded) lines.push(`evidence ${sha}${test ? `  test: ${test}` : ''}`);
   else if (row.evidenceNote) lines.push(`note     ${row.evidenceNote}`);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -645,7 +656,7 @@ async function abandonSlice(root, id, flags) {
       `state    ${preview.from} -> ${preview.to}`,
       `apply    ${apply}`,
     ];
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -707,6 +718,6 @@ async function abandonSlice(root, id, flags) {
     return EXIT.OK;
   }
   const lines = [`repo     ${root}`, `slice    ${id}  ${doc}`, ...removed, `state    ${row.from} -> ${row.to}`, `lease    ${leaseLine}`];
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }

package/src/commands/spec.mjs

@@ -0,0 +1,151 @@
+// The command spec: one row per path this binary dispatches (review 0003 Q60).
+//
+// The list of commands existed in four places that disagreed - the dispatch map, a
+// hand-written `--help` template, the completions table and the README - so a command
+// could work and be undiscoverable, or be documented and absent. A row here is the one
+// place a command is declared; `src/commands/index.mjs` derives its dispatchable paths
+// and group defaults from it, and `test/spec.test.mjs` fails when the registry and the
+// spec stop agreeing in either direction.
+//
+// The fields that only some consumers need (`tier`, `writes`, `args`, `flags`) arrive
+// with the slices that read them: help (Q61), validation (Q62), MCP (Q66). A field no
+// code reads is a field that drifts, and a wrong `writes` claim is worse than none.
+//
+// `defaultFor` marks the subcommand a bare group resolves to. It sits on the row that
+// IS the default rather than on a separate map, so the reason for a default lives beside
+// the command it names - `skills` alone indexes because the read is the safe default,
+// `slice` alone starts because an id-less `start` fails before it writes anything.
+
+/**
+ * @typedef {object} SpecRow
+ * @property {string} path the dispatch key: `status`, or `group subcommand`
+ * @property {string} summary one phrase, printed by help and by the generated docs
+ * @property {string} [defaultFor] the group whose bare form resolves to this row
+ * @property {string} [mcp] the MCP tool name that answers this row, when one does
+ */
+
+/** @type {SpecRow[]} */
+export const SPEC = [
+  { path: 'agent-hook', summary: 'the harness entry point: decide one tool call, or deliver the prompt packet', flags: ["diff","harness"], },
+  { path: 'agent-hooks install', summary: "write this repository's policies into each harness hooks file", writes: 'repo', flags: ["yes","diff","harness"], },
+  { path: 'agent-hooks status', summary: 'what each harness will run, and what is not trusted yet', defaultFor: 'agent-hooks', flags: ["diff","harness"], },
+  { path: 'agents install', summary: 'write the Simt-Agent into each harness agents file', writes: 'repo', flags: ["yes","diff","harness"], },
+  // A group like `agent-hooks`: `install` writes the agent file into each harness's own
+  // directory and `status` reports what a harness carries. The default is the read.
+  { path: 'agents status', summary: 'what each harness carries, and what is not installed yet', defaultFor: 'agents', flags: ["diff","harness"], },
+  { path: 'bench ablate', summary: 'measure one arm of the brief against its ablation', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench critic', summary: 'score the review critic against the labelled bench set', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench export', summary: 'write the sealed bench corpus as one signed document', writes: 'repo', flags: ["yes","all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench import', summary: 'verify a sealed corpus and load it into the vault', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench mine', summary: 'mine tasks out of a repository history', writes: 'repo', defaultFor: 'bench', flags: ["yes","all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench probes', summary: 'run the deterministic probes against a workspace', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench report', summary: 'summarise the runs recorded in the vault', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench run', summary: 'run agents against the mined tasks', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench variants', summary: 'run one task across its variant prompts', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'brief', mcp: { name: 'brief', flags: ['budget', 'paths', 'task'] }, summary: 'the packet for a task: rules, skills and the files it names, within a budget', flags: ["budget","explain","paths","task"], },
+  { path: 'check', mcp: { name: 'check', flags: [] }, summary: 'report stale or missing generated regions and every check finding', flags: ["check","diff","dry-run"], },
+  { path: 'ci', summary: "refresh simt-dev's own .github workflow and Dependabot files", flags: ["check","diff"], },
+  { path: 'compare', mcp: { name: 'compare', flags: [] }, summary: 'the adoption and drift matrix across every sibling repository', flags: [], },
+  { path: 'completions', summary: 'print a bash, zsh or fish completion script generated from this spec', flags: [], },
+  { path: 'decide', summary: 'scaffold a numbered decision record with its frontmatter', writes: 'repo', flags: ["yes","check","diff","dry-run","paths","supersedes","task"], },
+  { path: 'distill', summary: 'turn a repository into a skill or rule proposal', flags: [], },
+  { path: 'doctor', mcp: { name: 'doctor', flags: [] }, summary: 'report what is wrong with this installation', writes: 'repo', flags: ["yes","diff","fix"], },
+  { path: 'evidence', summary: 'the runs recorded against the tree on disk', flags: [], },
+  { path: 'evidence check', summary: 'a commit message claiming a run this tree does not have', flags: [], },
+  { path: 'explain', summary: 'what one check finding code means, and how to fix it', flags: [], },
+  { path: 'gate', summary: 'the tests a change reaches, and only those', flags: ["changed"], },
+  { path: 'graph lint', summary: 'check the skill registry against the skills on disk', defaultFor: 'graph', flags: ["spec"], },
+  { path: 'harness detect', summary: 'which harness is installed, and what it carries', defaultFor: 'harness', flags: ["at","reader","table","user"], },
+  { path: 'harness loaders', summary: 'the instruction files each harness loads, and what they cost', flags: ["at","reader","table","user"], },
+  { path: 'hooks install', summary: 'install the shared dispatcher and report what it would run', writes: 'repo', flags: ["yes","diff","dry-run"], },
+  { path: 'hooks run', summary: "run one git event's gates now, as git would", writes: 'repo', flags: ["yes","diff","dry-run"], },
+  { path: 'hooks status', summary: 'what each git event routes to, and whether it is wired', defaultFor: 'hooks', flags: ["diff","dry-run"], },
+  { path: 'ignore', summary: 'render the one ignore list into every harness ignore file', flags: ["diff"], },
+  { path: 'impact', summary: 'who a change reaches: importers, their tests and the contract', flags: [], },
+  { path: 'index', summary: 'rebuild the local file index from git blob hashes', flags: ["allow-remote","embed"], },
+  { path: 'init', summary: 'adopt this repository: manifest, region, hooks and toolchain pins', writes: 'repo', flags: ["yes","accept-conflicts","backup","diff","surfaces"], },
+  { path: 'lease', summary: 'claim files for one session, or list the claims', flags: ["harness","session","ttl"], },
+  { path: 'lessons capture', summary: 'scan the ledger and history for new lesson candidates', flags: ["diff","expires","paths","task"], },
+  { path: 'lessons list', summary: 'deterministic lesson candidates and the promoted lessons', defaultFor: 'lessons', flags: ["diff","expires","paths","task"], },
+  { path: 'lessons review', summary: 'promote one lesson candidate into docs/lessons', flags: ["diff","expires","paths","task"], },
+  { path: 'local doctor', summary: 'the local model endpoints, and whether they answer', defaultFor: 'local', flags: ["allow-remote"], },
+  { path: 'map', summary: 'the files a task is most likely to touch, within a byte budget', flags: ["allow-remote","budget","embed","level","recall","task"], values: { level: ['outline', 'names', 'signatures'] }, },
+  { path: 'mcp', summary: 'serve the read-only MCP surface over stdio', flags: ["list"], },
+  // Plan 0003 R45. The default is the read: `pack` alone lints the working directory,
+  // the way `skills` alone indexes and `graph` alone lints.
+  { path: 'pack lint', summary: 'lint a rule pack in the working directory', defaultFor: 'pack', flags: ["diff","require-measured","source"], },
+  { path: 'pack new', summary: 'scaffold a rule pack', flags: ["diff","require-measured","source"], },
+  { path: 'pack publish', summary: 'publish a rule pack', flags: ["diff","require-measured","source"], },
+  { path: 'plan done', mcp: { name: 'plan_done', flags: ['state', 'test'] }, summary: 'mark one tracker row complete, with its SHA and its evidence', flags: ["diff","state","test"], },
+  { path: 'plan next', mcp: { name: 'plan_next', flags: [] }, summary: "one ready slice's section, or the one named", flags: ["diff","state","test"], },
+  { path: 'plan status', summary: 'count the tracker rows', defaultFor: 'plan', flags: ["diff","state","test"], },
+  { path: 'plugin', summary: 'generate a harness package from the same tables the hooks use', flags: ["diff","out"], },
+  { path: 'pr-body', mcp: { name: 'pr_body', flags: ['base'] }, summary: 'the pull request body: evidence, decisions, gate state and residual risk', flags: ["base"], },
+  { path: 'review', summary: 'review the staged diff against the estate rules', flags: [], },
+  { path: 'rules decisions', summary: 'every known decision, and which layer each came from', writes: 'repo', flags: ["yes","all"], },
+  { path: 'rules list', mcp: { name: 'rules_list', flags: [] }, summary: 'the rule catalogue, marked with what applies to this repository', defaultFor: 'rules', flags: ["all"], },
+  { path: 'rules show', summary: 'one rule body', flags: ["all"], },
+  { path: 'rules why', mcp: { name: 'rules_why', flags: [] }, summary: 'the decision that settled a rule, and whether it is still in force', flags: ["all"], },
+  { path: 'shared install', summary: 'install the shared rules into a reader home directory', writes: 'repo', flags: ["yes","diff"], },
+  // ADR-084. `shared` is the one group whose default writes nothing, and it is `plan`
+  // for the same reason `skills`'s is `index`: the read answers "what would this do, and
+  // where", and `install` - the subcommand that touches a reader's home directory - is
+  // the one that needs `--yes` before it does anything.
+  { path: 'shared plan', summary: 'what the shared install would write, and where', writes: 'repo', defaultFor: 'shared', flags: ["yes","diff"], },
+  { path: 'skills brief', mcp: { name: 'skills_brief', flags: ['all', 'task'] }, summary: 'the packet for a task, read from the skill registry', flags: ["all", "plan", "task"], },
+  { path: 'skills compile', summary: 'compile a skill to the Agent Skills standard', flags: [], },
+  { path: 'skills eval', summary: 'score the skill registry against transcripts', flags: ["all","plan"], },
+  { path: 'skills find', mcp: { name: 'skills_find', flags: [] }, summary: 'skills that match a query', flags: ["all","plan"], },
+  { path: 'skills index', mcp: { name: 'skills_index', flags: [] }, summary: 'rebuild the skill index', defaultFor: 'skills', flags: ["all","plan"], },
+  { path: 'skills install', summary: 'install skills into the workspace', writes: 'repo', flags: ["yes","diff","from","variant"], },
+  { path: 'skills show', mcp: { name: 'skills_show', flags: [] }, summary: 'one skill packet', flags: ["all","plan"], },
+  { path: 'skills why', mcp: { name: 'skills_why', flags: [] }, summary: 'which skill covers a task', flags: ["all","plan"], },
+  { path: 'slice abandon', summary: 'remove a slice worktree, delete its branch, and return the row', flags: ["session","test","type"], },
+  { path: 'slice finish', summary: 'run the gates, commit the slice and record its evidence', writes: 'repo', flags: ["yes","session","test","type"], },
+  // Plan 0003 R53. Both halves write, so a bare `slice` has no read to default to.
+  // `start` is the default because with the id it is missing it fails with a usage error
+  // before anything is created - the one default here that cannot mutate.
+  { path: 'slice start', summary: 'give a slice its own worktree, branch and brief', defaultFor: 'slice', flags: ["session","test","type"], },
+  { path: 'status', summary: 'gate state from the last check', flags: ["line"], },
+  { path: 'sync', summary: 're-render the generated regions from the rule content', writes: 'repo', flags: ["yes","check","diff","dry-run"], },
+  { path: 'tests', summary: 'the tests that exercise a file', flags: ["cochange"], },
+  { path: 'tokens', summary: 'count tokens per instruction file and per skill', flags: ["repos","session"], },
+  { path: 'undo', summary: 'restore the last journaled set of writes, if untouched', writes: 'repo', flags: ["yes","diff"], },
+  { path: 'upgrade', summary: 'replace this installation with the pinned release', writes: 'repo', flags: ["yes","all","diff","workspace"], },
+  { path: 'why', summary: 'what governs a file: decisions, rules, skills, gates and lessons', flags: [], },
+];
+
+
+/**
+ * Which tier a command belongs to, decided by its group: the commands a reader reaches
+ * for while working are core and appear in `--help`; the rest are advanced and appear
+ * under `help --all`. A tier is a presentation fact, not a permission, so a command
+ * cannot be missing from both pages - `test/help.test.mjs` checks that every path is on
+ * one of them (review 0003 Q61).
+ */
+const CORE_GROUPS = new Set(['brief', 'check', 'gate', 'graph', 'hooks', 'impact', 'init', 'map', 'plan', 'rules', 'skills', 'slice', 'status', 'sync', 'tests', 'why']);
+
+/** The tier a path is listed under: `core` or `advanced`. */
+export function tierOf(path) {
+  return CORE_GROUPS.has(path.split(' ')[0]) ? 'core' : 'advanced';
+}
+
+/**
+ * The tools that answer a question no command asks.
+ *
+ * `federation_query` reads the federation config and consults a sibling repository
+ * directly (src/federation/query.mjs). There is no CLI verb for it, so giving it a spec
+ * row would advertise a command this binary cannot dispatch; leaving it undeclared is
+ * how a tool list and a command list drift apart. It is listed here with the reason
+ * instead, and test/mcp-spec.test.mjs accepts a tool without a row only when this table
+ * says why.
+ */
+export const MCP_ONLY = [
+  { tool: 'federation_query', why: 'a transport-only read: no command in this binary asks a sibling repository a question' },
+];
+
+/** The dispatchable paths, sorted - the answer to "what can this binary do". */
+export const SPEC_PATHS = SPEC.map((row) => row.path).sort();
+
+/** group -> the subcommand its bare form resolves to. */
+export const GROUP_DEFAULTS = new Map(SPEC.filter((row) => row.defaultFor !== undefined).map((row) => [row.defaultFor, row.path.split(' ')[1]]));

package/src/commands/status.mjs

@@ -10,12 +10,13 @@
 // only mode this command has is `--line`, and running something else by
 // default would invent a second answer to what the status is.
 
-import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson, present } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { currentHead, readCheckCache, renderStatusLine } from '../status.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function statusCommand(args, flags) {
-  const root = flags.root ?? args[0] ?? process.cwd();
+  const root = commandRoot(flags, args);
   if (flags.line !== true) {
     return fail('status needs --line', EXIT.USAGE, `run: ${CLI} status --line --root ${root}`);
   }
@@ -25,11 +26,7 @@ export async function statusCommand(args, flags) {
     // Informational, not a failure: a repository that never ran `check` — or
     // one a writer just invalidated — has no state to report, and a prompt
     // that errored until the first check would train its reader to ignore it.
-    if (isJson(flags)) {
-      emitJson({ ok: true, command: 'status', root, line: null, cached: false, stale: false });
-      return EXIT.OK;
-    }
-    emit('simt no cache - run check');
+    present({ ok: true, command: 'status', root, line: null, cached: false, stale: false }, () => 'simt no cache - run check', flags);
     return EXIT.OK;
   }