simt-dev 0.5.0 → 0.6.0

package/src/commands/harness.mjs

@@ -13,6 +13,11 @@
 // a defect in the repository: the rules in AGENTS.md still reach whichever harnesses
 // read that file, and a reader who wanted a failing command could not tell the
 // difference between "no channel" and "broken".
+//
+// R42 added the MCP registration files to the same answer. They are reported from the
+// loader table (one source of paths, with `verified` naming the vendor page) because a
+// detection question deserves the same provenance rule the loader table set: a row with
+// no source is a guess in a report.
 
 import { stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
@@ -24,7 +29,7 @@ import { LOADERS, LOADER_IDS, caps, loader } from '../projection/loaders.mjs';
 import { viewAll } from '../measure/loaderView.mjs';
 
 /**
- * `simt-dev harness detect`. The subcommand is validated by dispatch, which rejects a
+ * `simt harness detect`. The subcommand is validated by dispatch, which rejects a
  * second token that is not in the group registry rather than silently routing to the
  * default; this function therefore has exactly one thing to do and no second spelling
  * to keep in step with it.
@@ -36,7 +41,12 @@ import { viewAll } from '../measure/loaderView.mjs';
 export async function harnessCommand(positional, flags) {
   const root = flags.root ?? process.cwd();
 
-  const repo = await scan(root);
+  // MCP evidence is project-scope by construction: the loader table carries repo-root
+  // paths (.mcp.json, .codex/config.toml, …), and the same path means different scopes
+  // per harness in $HOME - Codex registers user servers in its user config, Claude Code
+  // does not keep .mcp.json there - so a home scan reports directories only, and stays
+  // right by saying less rather than by carrying a second per-harness user-scope table.
+  const repo = await scan(root, { mcp: true });
   // Only on request. The home directory is the reader's, not the repository's, and a
   // command that reports both by default is a command whose output changes because
   // somebody installed something elsewhere.
@@ -79,8 +89,13 @@ export async function harnessCommand(positional, flags) {
  * rather than raised: a permissions error on one candidate must not make the whole
  * command fail, and the difference between "could not look" and "not there" is one
  * note in the output rather than a second failure mode nobody asked for.
+ *
+ * `{ mcp: true }` (repo scans only) adds the MCP registration files the loader table
+ * records - single-sourced from `loaders.mjs` because that is the whole point of R42:
+ * the evidence is data the tool already verified once, not a second list of paths to
+ * keep in step by hand. It is file stat and nothing else: present, labelled, cited.
  */
-async function scan(root) {
+async function scan(root, { mcp = false } = {}) {
   const rows = [];
   for (const s of SURFACES) {
     for (const dir of s.configDirs ?? []) {
@@ -91,9 +106,10 @@ async function scan(root) {
   }
   for (const c of CANDIDATE_DIRS) {
     if (await present(root, c.dir)) {
-      rows.push(row(c.dir, c.harness, { readsAgentsMd: c.readsAgentsMd ?? null, verified: c.verified ?? null }));
+      rows.push(row(c.dir, c.harness, { readsAgentsMd: c.readsAgentsMd ?? null, readsAgentsMdNote: c.readsAgentsMdNote ?? null, verified: c.verified ?? null }));
     }
   }
+  if (mcp) rows.push(...(await scanMcpFiles(root)));
   rows.sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
   return { root, rows };
 }
@@ -106,11 +122,49 @@ async function present(root, dir) {
   }
 }
 
+/**
+ * The MCP registration files the loader table says a project can carry.
+ *
+ * A row requires the path to be a FILE the loader table names, and it is skipped when
+ * the loader carries none (opencode registers servers in a profile key, DeepSeek as a
+ * profile plugin). Nothing reads the file: whether the JSON parses or names servers is
+ * the harness's problem at session time, and a service that promised to validate that
+ * would be a service somebody had to keep current.
+ *
+ * This is evidence, not a channel: no rule file is projected into an MCP config, so
+ * `channel` stays false and `readsAgentsMd` stays null - the fields say what they mean
+ * instead of borrowing the meaning the directory rows give them.
+ */
+async function scanMcpFiles(root) {
+  const rows = [];
+  for (const loader of LOADERS) {
+    const mcp = loader.mcp;
+    if (mcp?.path == null) continue;
+    const file = join(root, mcp.path);
+    try {
+      if (!(await stat(file)).isFile()) continue;
+    } catch {
+      continue;
+    }
+    rows.push({
+      dir: mcp.path,
+      kind: 'mcp',
+      label: loader.label,
+      surface: loader.id,
+      channel: false,
+      readsAgentsMd: null,
+      verified: mcp.verified ?? loader.verified ?? null,
+    });
+  }
+  return rows;
+}
+
 /** One present directory, and what - if anything - this tool can project into it. */
 function row(dir, label, surface) {
   const id = surface.id ?? null;
   return {
     dir,
+    kind: 'rules',
     label,
     surface: id,
     // `channel: false` is the honest half of the answer: the directory exists and this
@@ -119,14 +173,20 @@ function row(dir, label, surface) {
     // identical in a list of names.
     channel: id !== null && surface.rule != null,
     readsAgentsMd: surface.readsAgentsMd ?? null,
+    // Which reader ("some") or which configuration ("some, under this setting") - the
+    // bare three-valued column started life on rows with many readers, where "which" is
+    // a per-row note. A row that lacks one renders without it.
+    readsAgentsMdNote: surface.readsAgentsMdNote ?? null,
     verified: surface.verified ?? null,
   };
 }
 
 function countUnclaimed(scan) {
   // A candidate that cites a document and reads AGENTS.md is covered by the standard
-  // region. One that cites nothing is the case the note exists for (ADR-067).
-  return scan.rows.filter((r) => r.surface === null && r.readsAgentsMd == null).length;
+  // region. One that cites nothing is the case the note exists for (ADR-067). An MCP
+  // config row is not "unclaimed" - it never claimed a rule channel, so it must not
+  // count toward the note, or mcp.json presence would read as a rule gap it is not.
+  return scan.rows.filter((r) => r.kind === 'rules' && r.surface === null && r.readsAgentsMd == null).length;
 }
 
 /**
@@ -149,15 +209,28 @@ function render(root, repo, user) {
 function block(scan, pad) {
   if (scan.rows.length === 0) return [`${pad}(none present)`];
   return scan.rows.map((r) => {
+    // An MCP row is judged by presence alone, so it is named first: routed last, its
+    // non-null `surface` (the loader it belongs to) would collide with the directory
+    // rows' meaning and print "AGENTS.md" under a file that carries no rules at all.
     const through =
-      r.surface === null
-        ? r.readsAgentsMd === 'all'
-          ? 'AGENTS.md'
-          : 'no rule channel in this release'
-        : r.channel
-          ? 'projected rule file'
-          : 'AGENTS.md';
-    const agents = r.readsAgentsMd === 'all' ? ' (reads AGENTS.md)' : r.readsAgentsMd === 'some' ? ' (some readers read AGENTS.md)' : '';
+      r.kind === 'mcp'
+        ? 'MCP config present'
+        : r.surface === null
+          ? r.readsAgentsMd === 'all'
+            ? 'AGENTS.md'
+            : 'no rule channel in this release'
+          : r.channel
+            ? 'projected rule file'
+            : 'AGENTS.md';
+    // "some" never renders bare when the row knows which: a reader who needs the
+    // detail already had it only in the JSON, and the detail is the answer to "is my
+    // AGENTS.md read" - the question this text is here to answer.
+    const agents =
+      r.readsAgentsMd === 'all'
+        ? ' (reads AGENTS.md)'
+        : r.readsAgentsMd === 'some'
+          ? ` (some readers read AGENTS.md${r.readsAgentsMdNote ? `: ${r.readsAgentsMdNote}` : ''})`
+          : '';
     return `${pad}${r.dir.padEnd(12)} ${r.label.padEnd(38)} ${through}${agents}`;
   });
 }

package/src/commands/help.mjs

@@ -57,6 +57,10 @@ ${CLI} agent-hooks install     write this repo's policies into the harnesses tha
                            (dry-run unless --yes; merges into the file, keeps every
                             key it does not own; Codex needs the hook trusted)
 ${CLI} agent-hooks status      what each harness will run, and what is not trusted yet
+${CLI} plugin <claude|gemini|cursor>  generate a harness package from the same tables
+                            (dry-run unless --yes; writes a self-contained runtime, the
+                            hooks and MCP registration, and for cursor the kernel rules;
+                            the skill registry is workspace data and is not shipped)
 ${CLI} plan status             count tracker rows
                            (${MANIFEST_FILE} key plans when set, otherwise
                            the ${DEFAULT_TEMPLATE} template:
@@ -92,7 +96,7 @@ ${CLI} map [--task "<text>"] [--level outline|names|signatures]
 ${CLI} evidence                the runs recorded against the tree on disk
 ${CLI} evidence check <file>   a commit message that claims a run this tree does not
                            have: a warning, or a block when gates.evidence is "block"
-${CLI} lessons list            deterministic lesson candidates in .simt-dev/lessons.jsonl
+${CLI} lessons list            deterministic lesson candidates in .simt/lessons.jsonl
                            and promoted lessons in docs/lessons/*.md
 ${CLI} lessons review [<id>]   promote a lesson candidate to docs/lessons/NNNN-<slug>.md
                            (dry-run unless --yes; writes Appendix A frontmatter)
@@ -105,7 +109,7 @@ ${CLI} local doctor            probe configured local model endpoints (chat and
                            unset; refuses non-loopback URLs without --allow-remote)
 ${CLI} distill <skill|doc>     a budgeted proposal summary of a skill body or doc,
                            every claim citing the source line range it rests on
-                           (writes .simt-dev/distilled/<digest>.md; a proposal a
+                           (writes .simt/distilled/<digest>.md; a proposal a
                            human merges - never projected or committed;
                            deterministic outline by default; --local proposes
                            from the configured chat model instead; the cache is
@@ -115,7 +119,7 @@ ${CLI} review [--local]        an ADR-008 verdict skeleton for the staged diff,
                            (deterministic without --local: the brief and its
                            governing ids only; --local proposes from the
                            configured chat model and writes
-                           .simt-dev/reviews/<digest>.md — a proposal a human
+                           .simt/reviews/<digest>.md — a proposal a human
                            reads, verified against the verdict vocabulary and
                            the brief's ids; advisory always, never a gate)
 ${CLI} shared plan            what a workspace's repeated rules cost to carry
@@ -132,8 +136,9 @@ ${CLI} tokens [--repos]       what a reader loads at session start, in bytes
                            repository under the root and what repeats an earlier)
 ${CLI} harness detect         which harnesses this repo (and, with --user, you)
                            are set up for, and which have a rule channel here
-                           (presence only: a directory found is not a claim about
-                           what its owner reads; exits 0 whatever it finds)
+                           (presence only: a directory or an MCP config file
+                           found is not a claim about what its owner reads;
+                           exits 0 whatever it finds)
 ${CLI} harness loaders        what each reader loads at session start, in bytes,
                             and what its size cap drops
                             (--table prints the vendor facts without measuring;
@@ -157,10 +162,22 @@ ${CLI} bench variants [--yes]  evaluate simt-variants rule slots on the canary s
                             winning variants in simt-dev.lock.json (dry-run unless --yes;
                             re-opens when model or harness changes)
 ${CLI} bench critic          precision and recall of the local critic over a labelled
-                            set of historical diffs (.simt-dev/critic-labels.jsonl;
+                            set of historical diffs (.simt/critic-labels.jsonl;
                             overrides --labels; labels are human-written verdicts
                             under ADR-008; the critic is advisory until precision
                             reaches 0.8 on 30 labelled diffs)
+${CLI} pack new <name> --source <spec>
+                           scaffold a versioned pack: pack.json, an unmeasured
+                           bench.json, and one stack rule (dry-run unless --yes;
+                           refuses a directory that already exists)
+${CLI} pack lint [dir]        validate a pack: identity, source, rules, and the
+                           bench summary (--require-measured rejects a pack with
+                           no measured ΔR; a pack vendored under .simt/packs/ is
+                           also checked against the manifest's pin)
+${CLI} pack publish [dir] [--yes]
+                           publish an npm-sourced pack to the registry
+                           (dry-run unless --yes; skips a version already live;
+                           a git-sourced pack names the tag-and-push instead)
 ${CLI} mcp                    the read-only surface as MCP tools over stdio
                            (--list prints it without reading stdin; init, sync,
                            upgrade and the installers stay CLI-only by design)`;
@@ -175,6 +192,7 @@ const FLAGS = `--json                 structured output (compact; one document,
 --task "<text>"         the task text used for capability resolution
 --paths <globs>         comma-separated path globs used for path resolution
 --root <path>           repository root (default: cwd)
+--out <path>            plugin: where the generated package lands (required)
 --surfaces <ids>        comma-separated editors to write rule files for;
                          "" means AGENTS.md only (default: every surface,
                          or the "surfaces" list in simt-dev.json)
@@ -224,12 +242,16 @@ const FLAGS = `--json                 structured output (compact; one document,
 --state <name>          plan done: target state (default: Complete)
 --level <name>          map: detail level (outline, names, signatures)
 --supersedes <spec>     decide: superseded ADR or ruling (ADR-NNN or ADR-NNN:<ruling>[:<kind>]; repeatable)
+--source <spec>         pack new: where the pack's bytes come from
+                         (npm:<package> or git+https://…; required)
+--require-measured      pack lint: reject a pack with no measured ΔR
+                         (a bench.json marked unmeasured, or missing)
 --allow-remote          local doctor / distill / review: allow non-loopback model
                          URLs (refused by default)
 --embed                 index / map / brief: compute or query optional local vector embeddings
                         (off by default unless recall@10 gains at least 10 points)
 --labels <path>         bench critic: the labelled set of historical diffs to score
-                        (default .simt-dev/critic-labels.jsonl; one human-written
+                        (default .simt/critic-labels.jsonl; one human-written
                         {sha, verdict} pair per line)
 --refresh               distill / review: regenerate a proposal that is already cached
 --local                 distill / review: propose the answer from the configured

package/src/commands/hooks.mjs

@@ -1,4 +1,4 @@
-// simt-dev hooks install | status | run
+// simt hooks install | status | run
 //
 // Three commands with one shared body. `install` writes the shims and points
 // core.hooksPath at them; `status` reports what is installed and what would

package/src/commands/index.mjs

@@ -3,7 +3,7 @@
 // Every command named in docs/plans/0002-simt-dev-cli.md section 5 is registered
 // here from day one. A command that is declared but not yet implemented exits
 // UNSUPPORTED with a pointer to its implementation step; it never silently
-// succeeds. An agent that calls `simt-dev compare` on an unreleased build must get a
+// succeeds. An agent that calls `simt compare` on an unreleased build must get a
 // failure, not an empty result it will read as "no drift".
 
 import {
@@ -34,6 +34,8 @@ import { agentHookCommand, agentHooksCommand } from './agenthook.mjs';
 import { compareCommand } from './compare.mjs';
 import { upgradeCommand } from './upgrade.mjs';
 import { mcpCommand } from './mcp.mjs';
+import { pluginCommand } from './plugin.mjs';
+import { packCommand } from './pack.mjs';
 import { installCommand } from './skillsinstall.mjs';
 import { compileCommand } from './skillscompile.mjs';
 import { listCommand as rulesList, showCommand as rulesShow, whyCommand as rulesWhy } from './rules.mjs';
@@ -91,6 +93,9 @@ const GROUPS = new Map([
   ['shared', 'plan'],
   ['lessons', 'list'],
   ['local', 'doctor'],
+  // Plan 0003 R45. The default is the read: `pack` alone lints the working
+  // directory, the way `skills` alone indexes and `graph` alone lints.
+  ['pack', 'lint'],
 ]);
 
 /**
@@ -169,6 +174,15 @@ export const IMPLEMENTED = {
   'bench critic': (args, flags) => benchCriticCommand(args, flags, COMMANDS),
   upgrade: upgradeCommand,
   mcp: mcpCommand,
+  // plan 0003 R43. A bare command: the kind is a positional, so there is no group and
+  // no default subcommand to resolve.
+  plugin: pluginCommand,
+  // Plan 0003 R45. A group, not a bare command: `new` and `publish` write (or
+  // publish) and `lint` reads, and the dispatcher routes all three through one
+  // subcommand switch the way `hooks` does.
+  'pack new': (args, flags) => packCommand('new', args, flags),
+  'pack lint': (args, flags) => packCommand('lint', args, flags),
+  'pack publish': (args, flags) => packCommand('publish', args, flags),
 };
 
 /**
@@ -228,7 +242,7 @@ export async function dispatch(argv) {
 /**
  * Normalise argv into a registry key, or null when unrecognised.
  * A group with an omitted subcommand resolves to that group's default, so
- * `simt-dev skills` is `simt-dev skills index`.
+ * `simt skills` is `simt skills index`.
  */
 function commandPath(first, second) {
   if (first === undefined) return null;
@@ -237,7 +251,7 @@ function commandPath(first, second) {
   const group = GROUPS.get(first);
   if (second === undefined) return `${first} ${group}`;
   // Reject a second token that is not a subcommand of this group, rather than
-  // silently routing `simt-dev skills nonsense` to the default subcommand.
+  // silently routing `simt skills nonsense` to the default subcommand.
   //
   // Read from IMPLEMENTED rather than from a second list. The list existed because
   // there was no way to enumerate what dispatch could run — `IMPLEMENTED` was an

package/src/commands/init.mjs

@@ -1,4 +1,4 @@
-// simt-dev init - adopt a repo into the ecosystem, or scaffold a new one.
+// simt init - adopt a repo into the ecosystem, or scaffold a new one.
 //
 // The governing idea: init never destroys hand-written work. It writes a manifest
 // and a generated region, reports every conflict it found BEFORE writing anything,
@@ -647,7 +647,7 @@ function render(payload, manifest, { npm = true, version } = {}) {
         : `            runs ${CLI} check where a pull request is merged; yours to edit after this`,
     );
   } else if (payload.ci.action === 'refresh') {
-    // init does not write it. `simt-dev ci` owns the template's own copy, and a
+    // init does not write it. `simt ci` owns the template's own copy, and a
     // second writer would be a second answer to who owns it.
     lines.push(`  ${'refresh'.padEnd(9)} ${payload.ci.file}  ${payload.ci.reason}`);
     lines.push(`            remedy: ${CLI} ci --yes   (init does not write simt-dev's own copy)`);

package/src/commands/local.mjs

@@ -30,6 +30,14 @@ function formatRoleLine(role, report) {
   return `${role.padEnd(8)} ok  ${report.model} @ ${report.url}${extra}${listed}`;
 }
 
+// `requestJson` shapes a non-OK response as "METHOD url failed (STATUS): message",
+// so the HTTP status is the reliable signal here — 401/403 mean the server is up but
+// rejected the request as unauthorised, which is a different remedy than "start it".
+function isAuthFailure(report) {
+  if (!report || typeof report.error !== 'string') return false;
+  return /failed \(40[13]\)/.test(report.error);
+}
+
 function remedyFor(result) {
   if (result.status === 'refused-remote') {
     return `set a loopback URL (http://127.0.0.1:<port>/v1) in ${MANIFEST_FILE}, or run: ${CLI} local doctor --allow-remote`;
@@ -38,6 +46,9 @@ function remedyFor(result) {
     return `fix the \`local\` configuration in ${MANIFEST_FILE}`;
   }
   if (result.status === 'unreachable') {
+    if ([result.chat, result.embed].some(isAuthFailure)) {
+      return `the server is up but rejected the request as unauthorised (401/403); set \`local.<role>.apiKey\` in ${MANIFEST_FILE} to the server's bearer token, then rerun: ${CLI} local doctor`;
+    }
     return `start the local model server at the URL in ${MANIFEST_FILE}, then rerun: ${CLI} local doctor`;
   }
   return null;

package/src/commands/mcp.mjs

@@ -1,4 +1,4 @@
-// simt-dev mcp - serve the tool surface over MCP on stdio.
+// simt mcp - serve the tool surface over MCP on stdio.
 //
 // Optional by design (plan 0002 section 5): it adds a transport, not a capability, and
 // the CLI stays the primary interface because it works in CI, in a hook and in a bare

package/src/commands/pack.mjs

@@ -0,0 +1,246 @@
+// simt pack new | lint | publish - the author side of a pack.
+//
+// A pack is vendored bytes (ADR-065): the adopting repository carries them and
+// pins a digest, and nothing renders from outside the repository. These three
+// subcommands are how a pack comes to exist, how it is judged, and how its bytes
+// become obtainable - without ever fetching at render time.
+//
+// Like every writer here, `new` and `publish` are previews by default and write
+// (or publish) only with `--yes`. `lint` is a read: it judges and reports, and
+// exits non-zero when the pack fails.
+
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI, MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+import { PACK_DIR, packNameProblem } from '../packs.mjs';
+import {
+  BENCH_JSON,
+  PACK_JSON,
+  describeSourceProblem,
+  lintPack,
+  npmPackageOf,
+  publishPack,
+  readBench,
+  scaffoldPack,
+  writeScaffold,
+} from '../packs/manage.mjs';
+import { readManifest } from '../projection/manifest.mjs';
+
+export async function packCommand(sub, args, flags) {
+  if (sub === 'new') return packNew(args, flags);
+  if (sub === 'lint') return packLint(args, flags);
+  if (sub === 'publish') return packPublish(args, flags);
+  return fail(`unknown pack subcommand ${sub ?? '(none)'}`, EXIT.USAGE, `run: ${CLI} pack lint [dir]`);
+}
+
+/**
+ * Where a lint or publish resolves its pack: the positional directory, the
+ * `--root`, or the working directory. `hooks` reads the same three in the same
+ * order, so the two commands cannot disagree about which directory was meant.
+ */
+function packDir(args, flags) {
+  return resolve(flags.root ?? args[0] ?? process.cwd());
+}
+
+/**
+ * The manifest entry that declares this pack, when the directory is a vendored
+ * copy inside an adopting repository. Lint then checks the two promises a
+ * declaration makes - version and digest - against the bytes on disk, so a
+ * pack that drifted from its pin is reported where it sits, not only in the
+ * adopting repo's gate.
+ */
+async function declaredEntry(dir) {
+  let cursor = dir;
+  for (;;) {
+    if (existsSync(join(cursor, MANIFEST_FILE)) || existsSync(join(cursor, MANIFEST_LEGACY))) {
+      const { manifest, exists, error } = await readManifest(cursor);
+      if (!exists || error !== null || manifest === null) return null;
+      const packs = Array.isArray(manifest.packs) ? manifest.packs : [];
+      const here = join(cursor, PACK_DIR);
+      if (dir === here || dir.startsWith(`${here}/`)) {
+        const name = dir.slice(here.length + 1).split('/')[0];
+        return packs.find((p) => p?.name === name) ?? null;
+      }
+      return null;
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) return null;
+    cursor = parent;
+  }
+}
+
+async function packNew(args, flags) {
+  const name = args[0];
+  if (!name) {
+    return fail(
+      'pack new needs a name',
+      EXIT.USAGE,
+      `run: ${CLI} pack new <name> --source <npm:<package>|git+https://…>`,
+    );
+  }
+  const nameProblem = packNameProblem(name);
+  if (nameProblem !== null) {
+    return fail(nameProblem, EXIT.USAGE, 'a pack name is the directory name its bytes vendor under');
+  }
+  const source = flags.source;
+  if (!source) {
+    return fail(
+      'pack new needs --source',
+      EXIT.USAGE,
+      `run: ${CLI} pack new ${name} --source <npm:<package>|git+https://…>`,
+    );
+  }
+  const sourceProblem = describeSourceProblem(source);
+  if (sourceProblem !== null) {
+    return fail(sourceProblem, EXIT.USAGE, 'a pack source names where the bytes come from: `npm:<package>` or `git+https://…`');
+  }
+
+  const dir = join(resolve(flags.root ?? process.cwd()), name);
+  const files = scaffoldPack({ name, source });
+  const { apply, dryRun } = writeMode(flags);
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'pack new',
+      dir,
+      dryRun: !apply,
+      files: files.map((f) => f.path),
+      packFile: PACK_JSON,
+      benchFile: BENCH_JSON,
+    });
+    return EXIT.OK;
+  }
+
+  if (!apply) {
+    emit(
+      [
+        `pack     ${name} -> ${dir}`,
+        `source   ${source}`,
+        '',
+        ...files.map((f) => `PLAN     ${f.path}`),
+        '',
+        dryRun ? 'DRY-RUN  no files written' : `PLAN     nothing written; apply with: ${CLI} pack new ${name} --source ${source} --yes`,
+      ].join('\n'),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return EXIT.OK;
+  }
+
+  try {
+    await writeScaffold(dir, files);
+  } catch (error) {
+    return fail(error.message, EXIT.FAIL, 'pick a name whose directory does not exist yet');
+  }
+  emit(
+    [
+      `pack     ${name} -> ${dir}`,
+      `source   ${source}`,
+      ...files.map((f) => `WRITE    ${f.path}`),
+      '',
+      `WROTE    ${files.length} scaffold file(s); write the rule, then: ${CLI} pack lint ${dir}`,
+    ].join('\n'),
+    { maxBytes: flags.maxBytes ?? 0 },
+  );
+  return EXIT.OK;
+}
+
+async function packLint(args, flags) {
+  const dir = packDir(args, flags);
+  const declared = await declaredEntry(dir);
+  const { pack, ok, findings } = await lintPack(dir, {
+    requireMeasured: flags.requireMeasured === true,
+    declared,
+  });
+
+  // The one-line answer first, because a gate that failed should say what it
+  // judged before it says why: the pack, its version, and the digest the
+  // adopting manifest would pin.
+  const headline = pack === null ? `pack     ${dir} (no ${PACK_JSON})` : `pack     ${pack.name} ${pack.version}  digest ${pack.digest}`;
+
+  if (isJson(flags)) {
+    emitJson({ ok, command: 'pack lint', dir, pack, findings });
+    return ok ? EXIT.OK : EXIT.FAIL;
+  }
+
+  const lines = [headline];
+  if (pack !== null) {
+    const summary = await summaryLine(dir);
+    if (summary !== null) lines.push(summary);
+  }
+  if (declared !== null && pack !== null) {
+    lines.push(`declared ${declared.version ?? '(no version)'}  pinned ${declared.digest ?? '(unpinned)'}`);
+  }
+  for (const f of findings) {
+    lines.push(`${f.status.toUpperCase().padEnd(24)} ${f.file}  ${f.detail}`);
+    lines.push(`                        remedy: ${f.remedy}`);
+  }
+  lines.push('', ok ? 'PASSED   the pack is well-formed' : `FAILED   ${findings.length} finding(s)`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return ok ? EXIT.OK : EXIT.FAIL;
+}
+
+/**
+ * The measured ΔR, in the pack's own words. Reported, never judged, here:
+ * judging is `lint`'s with `--require-measured`; this line is what a reader
+ * who asked \"what is this pack worth\" reads either way.
+ */
+async function summaryLine(dir) {
+  const { bench } = await readBench(dir);
+  if (bench === null) return null;
+  if (bench.measured !== true) return `measured unmeasured (no ΔR recorded in ${BENCH_JSON})`;
+  const dR = typeof bench.dR === 'number' ? (bench.dR >= 0 ? `+${bench.dR}` : `${bench.dR}`) : '(no dR)';
+  return `measured dR ${dR} over ${bench.tasks ?? '?'} tasks (${bench.run ?? 'unrecorded run'})`;
+}
+
+async function packPublish(args, flags) {
+  const dir = packDir(args, flags);
+  const { apply, dryRun } = writeMode(flags);
+  const result = await publishPack(dir, { apply });
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: result.ok,
+      command: 'pack publish',
+      dir,
+      pack: result.pack,
+      published: result.published,
+      skipped: result.skipped,
+      planned: result.planned,
+      findings: result.findings,
+    });
+    return result.ok ? EXIT.OK : EXIT.FAIL;
+  }
+
+  const name = result.pack === null ? dir : `${result.pack.name} ${result.pack.version}`;
+  const lines = [`pack     ${name}`, `source   ${result.pack?.source ?? '(unknown)'}`];
+  if (result.skipped) {
+    lines.push(`SKIPPED  ${npmPackageOf(result.pack.source)}@${result.pack.version} is already live; nothing to publish`);
+  }
+  for (const step of result.planned) lines.push(`${apply ? 'RUN      ' : 'PLAN     '}${step}`);
+  for (const f of result.findings) {
+    lines.push(`${f.status.toUpperCase().padEnd(24)} ${f.file}  ${f.detail}`);
+    lines.push(`                        remedy: ${f.remedy}`);
+  }
+  if (result.ok && !result.skipped) {
+    lines.push(
+      '',
+      apply
+        ? `PUBLISHED ${result.pack.name}@${result.pack.version}`
+        : dryRun
+          ? 'DRY-RUN  nothing published'
+          : `PLAN     nothing published; apply with: ${CLI} pack publish ${dir} --yes`,
+    );
+  } else if (result.ok) {
+    lines.push('');
+  } else {
+    lines.push('', `FAILED   ${result.findings.length} finding(s)`);
+  }
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  if (result.ok && apply && result.published) {
+    note(`note     never committed or pushed by this tool (ADR-001); the registry now has the bytes, the repos still need vendoring`);
+  }
+  return result.ok ? EXIT.OK : EXIT.FAIL;
+}