@gobing-ai/spur 0.4.23 → 0.4.25

package/spur.js

@@ -124703,40 +124703,40 @@ var init_src3 = __esm(() => {
 
 // ../../packages/app/src/services/search-zg.ts
 function buildZgArgs(req, globs) {
-  return ["query", "--hybrid", req.query, "--limit", String(req.limit), ...globs.flatMap((glob) => ["-g", glob])];
+  return [
+    "--hybrid",
+    req.query,
+    "--limit",
+    String(req.limit),
+    "--preview",
+    "short",
+    ...globs.flatMap((glob) => ["-g", glob])
+  ];
 }
 function parseZgQuery(stdout, zgVersion) {
-  if (!stdout.trim())
-    return [];
-  if (!stdout.includes("query groups (")) {
-    throw new ZgOutputError('zg query output is missing the "query groups (" header', zgVersion, stdout);
-  }
-  const countMatch = stdout.match(/^hits: (\d+)$/m);
-  if (!countMatch) {
-    throw new ZgOutputError('zg query output is missing the "hits:" count line', zgVersion, stdout);
-  }
-  const declaredCount = Number(countMatch[1] ?? "0");
   const hits = [];
   let current = null;
   const snippetLines = [];
   for (const line of stdout.split(`
 `)) {
-    if (line === "..." || !line.trim())
+    const trimmed = line.trim();
+    if (!trimmed || trimmed === "\u2026" || trimmed === "..." || GROUP_SEPARATOR_PATTERN.test(trimmed))
+      continue;
+    if (trimmed === "No matches." && hits.length === 0)
       continue;
     const header = line.match(HIT_HEADER_PATTERN);
     if (header) {
       if (current)
         flushSnippet(current, snippetLines);
-      const hitPath = header[3];
-      const start = header[4];
-      const end = header[5];
-      if (!hitPath || !start)
-        throw new ZgOutputError("zg query hit header is missing path or line fields", zgVersion, stdout);
+      if (Number(header[1]) !== hits.length + 1) {
+        throw new ZgOutputError(`zg query hit rank #${header[1]} is out of sequence`, zgVersion, stdout);
+      }
+      const start = Number(header[3]);
       current = {
         rank: hits.length + 1,
-        path: hitPath,
-        startLine: Number(start),
-        endLine: end ? Number(end) : Number(start),
+        path: header[2] ?? "",
+        startLine: start,
+        endLine: header[4] ? Number(header[4]) : start,
         snippet: "",
         route: "fuzzy",
         matchedBy: ["fuzzy"]
@@ -124745,25 +124745,23 @@ function parseZgQuery(stdout, zgVersion) {
       snippetLines.length = 0;
       continue;
     }
-    if (!current)
+    const source = current ? line.match(SOURCE_LINE_PATTERN) : null;
+    if (source) {
+      snippetLines.push(source[2] ?? "");
       continue;
-    const metadata = line.match(METADATA_PATTERN);
-    if (metadata) {
+    }
+    const metadata = current ? line.match(METADATA_PATTERN) : null;
+    if (current && metadata) {
       if (metadata[1] === "heading")
         current.heading = metadata[2] ?? "";
       if (metadata[1] === "symbol")
         current.symbol = metadata[2] ?? "";
       continue;
     }
-    const source = line.match(SOURCE_LINE_PATTERN);
-    if (source)
-      snippetLines.push(source[2] ?? "");
+    throw new ZgOutputError(`zg query output has an unrecognized line: ${line.slice(0, 80)}`, zgVersion, stdout);
   }
   if (current)
     flushSnippet(current, snippetLines);
-  if (hits.length !== declaredCount) {
-    throw new ZgOutputError(`zg query output declares hits: ${declaredCount} but ${hits.length} hit blocks were parsed`, zgVersion, stdout);
-  }
   return hits;
 }
 function flushSnippet(hit, snippetLines) {
@@ -124771,6 +124769,8 @@ function flushSnippet(hit, snippetLines) {
 `).slice(0, SNIPPET_MAX_CHARS);
 }
 function parseZgStatus(stdout) {
+  if (/^\s*Coverage\s+Unavailable\b/m.test(stdout))
+    return "missing";
   const firstLine = stdout.split(`
 `).find((line) => line.trim()) ?? "";
   const glyph = firstLine.trim().charAt(0);
@@ -124782,7 +124782,7 @@ function parseZgStatus(stdout) {
     return "unknown";
   return "ready";
 }
-var ZgOutputError, SNIPPET_MAX_CHARS = 300, HIT_HEADER_PATTERN, METADATA_PATTERN, SOURCE_LINE_PATTERN;
+var ZgOutputError, SNIPPET_MAX_CHARS = 300, HIT_HEADER_PATTERN, METADATA_PATTERN, SOURCE_LINE_PATTERN, GROUP_SEPARATOR_PATTERN;
 var init_search_zg = __esm(() => {
   ZgOutputError = class ZgOutputError extends Error {
     zgVersion;
@@ -124794,9 +124794,10 @@ var init_search_zg = __esm(() => {
       this.sample = sample.slice(0, 400);
     }
   };
-  HIT_HEADER_PATTERN = /^#(\d+) matchedBy=(fts|vector|fts\+vector) (.+?):(\d+)(?:-(\d+))?$/;
-  METADATA_PATTERN = /^(heading|heading_level|scope|symbol): (.*)$/;
-  SOURCE_LINE_PATTERN = /^(\d+)\t(.*)$/;
+  HIT_HEADER_PATTERN = /^#(\d+) (.+?):(\d+)(?:-(\d+))?$/;
+  METADATA_PATTERN = /^([a-z_]+): (.*)$/;
+  SOURCE_LINE_PATTERN = /^\s+(\d+): ?(.*)$/;
+  GROUP_SEPARATOR_PATTERN = /^-- query \d+\/\d+: .* --$/;
 });
 
 // ../../packages/app/src/services/search.ts
@@ -124814,10 +124815,10 @@ async function searchStatus(root, deps = defaultSearchDeps) {
   if (!zgPath) {
     return { rg, zg: { available: false, index: "unknown", hint: ZG_INSTALL_HINT } };
   }
-  const version = await probeVersion(deps, zgPath, ["version"]);
+  const version = await probeVersion(deps, zgPath, ["--version"]);
   let index = "unknown";
   try {
-    const result = await deps.run("zg", ["status"], { cwd: root, timeout: PROBE_TIMEOUT_MS });
+    const result = await deps.run("zg", ["--status"], { cwd: root, timeout: PROBE_TIMEOUT_MS });
     if (result.exitCode === 0)
       index = parseZgStatus(result.stdout);
   } catch {}
@@ -124959,7 +124960,7 @@ async function runFuzzy(req, limit, globs, root, status, deps) {
   if (result.timedOut)
     return { hits: null, skipped: [{ route: "fuzzy", reason: "zg-timeout" }] };
   if (result.exitCode !== 0) {
-    if (result.stderr.includes("[INDEX_MISSING]")) {
+    if (/ZG\.ENGINE\.NOT_FOUND|\[INDEX_MISSING\]/.test(result.stderr)) {
       return { hits: null, skipped: [{ route: "fuzzy", reason: "zg-index-missing", hint: ZG_INDEX_HINT }] };
     }
     return { hits: null, skipped: [{ route: "fuzzy", reason: "zg-failed" }] };
@@ -124968,13 +124969,13 @@ async function runFuzzy(req, limit, globs, root, status, deps) {
     return { hits: parseZgQuery(result.stdout, status.zg.version ?? "unknown").slice(0, limit), skipped: [] };
   } catch (error) {
     if (error instanceof ZgOutputError) {
-      const sample = `${error.zgVersion}: ${error.sample}`.slice(0, 300);
+      const sample = `${error.zgVersion}: ${error.message} | ${error.sample}`.slice(0, 300);
       return { hits: null, skipped: [{ route: "fuzzy", reason: "zg-output-error", hint: sample }] };
     }
     throw error;
   }
 }
-var RG_INSTALL_HINT = "brew install ripgrep", ZG_INSTALL_HINT = "bun add -g @zvec/zvec-grep", ZG_INDEX_HINT = "zg index --embedding local/potion-code-16m-v2", ZG_REFRESH_HINT = "zg index", SearchError, defaultSearchDeps, RG_TIMEOUT_MS = 1e4, ZG_QUERY_TIMEOUT_MS = 15000, PROBE_TIMEOUT_MS = 5000, SNIPPET_MAX_CHARS2 = 300;
+var RG_INSTALL_HINT = "brew install ripgrep", ZG_INSTALL_HINT = "bun add -g @zvec/zvec-grep", ZG_INDEX_HINT = "zg --index --embedding local/potion-code-16m-v2", ZG_REFRESH_HINT = "zg --index", SearchError, defaultSearchDeps, RG_TIMEOUT_MS = 1e4, ZG_QUERY_TIMEOUT_MS = 15000, PROBE_TIMEOUT_MS = 5000, SNIPPET_MAX_CHARS2 = 300;
 var init_search2 = __esm(() => {
   init_src3();
   init_dist5();
@@ -155545,6 +155546,7 @@ var SHARED_OPTIONS = {
   jsonProjectsResponse: ["--json", "Output JSON response"],
   jsonMessageStream: ["--json", "Output one JSON object per new message (machine-consumable)"],
   jsonServePortUrl: ["--json", "Output { port, url, pid } and exit"],
+  jsonShowBranches: ["--json", "alias of --format json (prints the raw BranchTopology object)"],
   fromFileOutcomeRows: ["--from-file <path>", "Path to JSON array of {wbs,outcome[,reason]} rows"],
   asFeature0418: [
     "--as <status>",
@@ -155564,6 +155566,7 @@ var SHARED_OPTIONS = {
   dryRunWorkflowValidate: ["--dry-run", "Validate and walk transitions without executing actions"],
   execDryRun: ["--dry-run", "Print the resolved command(s) and run nothing"],
   dryRunWorkflowClean: ["--dry-run", "List what would be cleaned without writing (applies to both scopes)"],
+  dryRunHistorySummary: ["--dry-run", "print the summary without writing the file"],
   featureTrace: ["--feature <id>", "Feature ID for traceability and Goal\u2192Background derivation"],
   featureFrontmatter: ["--feature <id>", "Set the feature_id frontmatter field (traceability edge)"],
   featureFilterEdge: ["--feature <id>", "Filter by linked feature ID (feature_id edge)"],
@@ -155580,6 +155583,7 @@ var SHARED_OPTIONS = {
     "--force",
     "Force applying reopen proposals without confirmation; also bypasses repeated-BLOCKED suppression"
   ],
+  forceBuilderPr: ["--force", "request a fresh review even when the current HEAD is already reviewed"],
   forceInitRecreate: ["--force", "Recreate files that already exist"],
   forceTaskPreflight: [
     "--force",
@@ -161004,6 +161008,98 @@ async function publishPackage(target, opts = {}) {
   }
 }
 
+// src/commands/builder/bump-ver.ts
+function registerBuilderBumpVerCommand(noun, context) {
+  noun.command("bump-ver").summary("bump a package version, commit, tag, optionally push").description([
+    "Bump one workspace package (or every released package with --all),",
+    "rewrite workspace pins, commit, and tag. A bare version bumps all:",
+    "  spur builder bump-ver 0.1.4          # every released package",
+    "  spur builder bump-ver spur 0.1.4     # one package by id",
+    "  spur builder bump-ver --check spur   # pre-publish drift guard (read-only)",
+    "--check fails (exit 1) when .claude-plugin/marketplace.json or a listed plugin.json",
+    "drifted from the package version; target defaults to the aggregate package."
+  ].join(`
+`)).option("--check", "only verify marketplace/plugin versions match the package version (no writes)").option("--all", "bump every released package in one commit with per-package + aggregate tags").option("--push", "push the branch and release tag to origin").option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).argument("[target]", "package id, or the version itself when bumping all").argument("[version]", "target semver version").action(async (target, version, options) => {
+    const args = [target, version].filter((value) => value !== undefined);
+    if (options.all === true)
+      args.push("--all");
+    if (options.push === true)
+      args.push("--push");
+    try {
+      if (options.check === true) {
+        if (version !== undefined)
+          throw new Error("bump-ver --check takes only a package id");
+        if (options.all === true || options.push === true)
+          throw new Error("bump-ver --check rejects incompatible write flags (--push/--all)");
+        const code = await checkVersionDrift(target, context.cwd, context.output, context.spurConfig);
+        if (options.json === true) {
+          context.output.write(toEnvelopeJson({ ok: code === 0, verb: "bump-ver", check: true, target: target ?? "aggregate" }, { enveloped: options.jsonEnvelope }));
+        }
+        if (code !== 0)
+          context.setExitCode(code);
+        return;
+      }
+      await bumpVer(args, context.cwd, context.output, context.spurConfig);
+      if (options.json === true) {
+        context.output.write(toEnvelopeJson({ ok: true, verb: "bump-ver", target: target ?? "all", version: version ?? "" }, { enveloped: options.jsonEnvelope }));
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (options.json === true) {
+        context.output.write(toEnvelopeJson({ ok: false, verb: "bump-ver", error: message }, {
+          enveloped: options.jsonEnvelope,
+          error: {
+            code: "INTERNAL_ERROR",
+            message,
+            details: { cliCode: "bump-ver", verb: "bump-ver" }
+          }
+        }));
+        context.setExitCode(1);
+        return;
+      }
+      context.output.error(message);
+      context.setExitCode(1);
+    }
+  });
+}
+
+// src/commands/builder/drop-tags.ts
+function registerBuilderDropTagsCommand(noun, context) {
+  noun.command("drop-tags").summary("delete release tags locally and optionally on origin").description([
+    "Delete one package release tag (or every released tag plus the aggregate",
+    "with --all / a bare version). Use --remote to also delete on origin."
+  ].join(`
+`)).option("--all", "drop every released tag plus the aggregate tag").option("--remote", "also delete the tag(s) on origin").option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).argument("[target]", "package id, or the version itself when dropping all").argument("[version]", "semver version of the tags to drop").action(async (target, version, options) => {
+    const args = [target, version].filter((value) => value !== undefined);
+    if (options.all === true)
+      args.push("--all");
+    if (options.remote === true)
+      args.push("--remote");
+    try {
+      await dropTags(args, context.cwd, context.output, context.spurConfig);
+      if (options.json === true) {
+        context.output.write(toEnvelopeJson({ ok: true, verb: "drop-tags", target: target ?? "all", version: version ?? "" }, { enveloped: options.jsonEnvelope }));
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (options.json === true) {
+        context.output.write(toEnvelopeJson({ ok: false, verb: "drop-tags", error: message }, {
+          enveloped: options.jsonEnvelope,
+          error: {
+            code: "INTERNAL_ERROR",
+            message,
+            details: { cliCode: "drop-tags", verb: "drop-tags" }
+          }
+        }));
+        context.setExitCode(1);
+        return;
+      }
+      context.output.error(message);
+      context.setExitCode(1);
+    }
+  });
+}
+
 // ../../packages/app/src/services/pr-review/index.ts
 init_src();
 import { spawnSync as spawnSync7 } from "child_process";
@@ -161997,7 +162093,7 @@ function registerBuilderPrCommand(builder, context) {
     "returns PENDING. Exit codes: 0 ok \xB7 2 hard failure \xB7 3 wait timeout",
     "(verdict PENDING \u2014 pending, never failure)."
   ].join(`
-`)).option("--force", "request a fresh review even when the current HEAD is already reviewed").option("--focus <text>", "extra review focus appended to the request").option("--no-wait", "post the request and return PENDING without polling").option("--timeout <s>", "wait budget in seconds (service default 600)").option("--interval <s>", "poll interval in seconds (service default 30)").option(...SHARED_OPTIONS.json).option("--status-file <path>", "write the one-word verdict (CLEAN | FINDINGS | PENDING | FAIL)").action((options) => {
+`)).option(...SHARED_OPTIONS.forceBuilderPr).option("--focus <text>", "extra review focus appended to the request").option("--no-wait", "post the request and return PENDING without polling").option("--timeout <s>", "wait budget in seconds (service default 600)").option("--interval <s>", "poll interval in seconds (service default 30)").option(...SHARED_OPTIONS.json).option("--status-file <path>", "write the one-word verdict (CLEAN | FINDINGS | PENDING | FAIL)").action((options) => {
     run("review", {
       ...options.force === true ? { force: true } : {},
       ...options.focus !== undefined ? { focus: options.focus } : {},
@@ -162010,6 +162106,27 @@ function registerBuilderPrCommand(builder, context) {
   });
 }
 
+// src/commands/builder/publish.ts
+function registerBuilderPublishCommand(noun, context) {
+  noun.command("publish").summary("resolve workspace/catalog ranges, build, and npm publish a package (CI)").description([
+    "CI publish for npm Trusted Publishing (OIDC): rewrite workspace:/catalog: ranges in",
+    "<dir>/package.json, run `bun run build:bundle`, `npm publish --access public`, and",
+    "restore the manifest on every exit path."
+  ].join(`
+`)).option("--otp <code>", "npm one-time password (local publishes only)").argument("<dir>", "package directory, relative to the workspace root").action(async (dir, options) => {
+    try {
+      await publishPackage(dir, {
+        repoRoot: context.cwd,
+        output: context.output,
+        ...options.otp !== undefined ? { otp: options.otp } : {}
+      });
+    } catch (err) {
+      context.output.error(err instanceof Error ? err.message : String(err));
+      context.setExitCode(1);
+    }
+  });
+}
+
 // ../../packages/app/src/services/branch-topology/render.ts
 var INDENT = "    ";
 var MERMAID_DEFAULT_BRANCH = "main";
@@ -162500,7 +162617,7 @@ function registerBuilderShowBranchesCommand(builder, context) {
     "Exit codes: 0 ok \xB7 1 usage (bad --format/--limit/--max-commits, unknown base ref,",
     "--local with --remote) \xB7 2 git failure (not a repository, git missing)."
   ].join(`
-`)).option("--format <format>", "output format: markdown | json | text (default markdown)", "markdown").option("--json", "alias of --format json (prints the raw BranchTopology object)").option("--base <ref>", "base ref to measure every branch against (default: origin/HEAD, else main)").option("--local", "only local branches").option("--remote", "only remote branches").option("--pr", "enrich rows with open pull-request state (one gh call; degrades with a warning)").option("--limit <n>", "maximum branch rows kept, most recent last-commit first (default 30)", "30").option("--max-commits <n>", "maximum commit nodes per branch line in the graph (default 3)", "3").option("--hide-contained", "drop contained branches from the graph instead of drawing their join").option("--theme <name>", "mermaid theme name for the graph init directive").action((options) => {
+`)).option("--format <format>", "output format: markdown | json | text (default markdown)", "markdown").option(...SHARED_OPTIONS.jsonShowBranches).option("--base <ref>", "base ref to measure every branch against (default: origin/HEAD, else main)").option("--local", "only local branches").option("--remote", "only remote branches").option("--pr", "enrich rows with open pull-request state (one gh call; degrades with a warning)").option("--limit <n>", "maximum branch rows kept, most recent last-commit first (default 30)", "30").option("--max-commits <n>", "maximum commit nodes per branch line in the graph (default 3)", "3").option("--hide-contained", "drop contained branches from the graph instead of drawing their join").option("--theme <name>", "mermaid theme name for the graph init directive").action((options) => {
     const format = resolveFormat(options.format, command.getOptionValueSource("format") === "cli", options.json === true, context);
     if (format === null)
       return;
@@ -162575,110 +162692,12 @@ function usageError(message, context) {
   context.setExitCode(1);
 }
 
-// src/commands/builder.ts
+// src/commands/builder/index.ts
 function registerBuilderCommand(program, context) {
   const noun = program.command("builder").summary("release plumbing: version bumps, tags, branch topology, and PR-review ops");
-  noun.command("bump-ver").summary("bump a package version, commit, tag, optionally push").description([
-    "Bump one workspace package (or every released package with --all),",
-    "rewrite workspace pins, commit, and tag. A bare version bumps all:",
-    "  spur builder bump-ver 0.1.4          # every released package",
-    "  spur builder bump-ver spur 0.1.4     # one package by id",
-    "  spur builder bump-ver --check spur   # pre-publish drift guard (read-only)",
-    "--check fails (exit 1) when .claude-plugin/marketplace.json or a listed plugin.json",
-    "drifted from the package version; target defaults to the aggregate package."
-  ].join(`
-`)).option("--check", "only verify marketplace/plugin versions match the package version (no writes)").option("--all", "bump every released package in one commit with per-package + aggregate tags").option("--push", "push the branch and release tag to origin").option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).argument("[target]", "package id, or the version itself when bumping all").argument("[version]", "target semver version").action(async (target, version, options) => {
-    const args = [target, version].filter((value) => value !== undefined);
-    if (options.all === true)
-      args.push("--all");
-    if (options.push === true)
-      args.push("--push");
-    try {
-      if (options.check === true) {
-        if (version !== undefined)
-          throw new Error("bump-ver --check takes only a package id");
-        if (options.all === true || options.push === true)
-          throw new Error("bump-ver --check rejects incompatible write flags (--push/--all)");
-        const code = await checkVersionDrift(target, context.cwd, context.output, context.spurConfig);
-        if (options.json === true) {
-          context.output.write(toEnvelopeJson({ ok: code === 0, verb: "bump-ver", check: true, target: target ?? "aggregate" }, { enveloped: options.jsonEnvelope }));
-        }
-        if (code !== 0)
-          context.setExitCode(code);
-        return;
-      }
-      await bumpVer(args, context.cwd, context.output, context.spurConfig);
-      if (options.json === true) {
-        context.output.write(toEnvelopeJson({ ok: true, verb: "bump-ver", target: target ?? "all", version: version ?? "" }, { enveloped: options.jsonEnvelope }));
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (options.json === true) {
-        context.output.write(toEnvelopeJson({ ok: false, verb: "bump-ver", error: message }, {
-          enveloped: options.jsonEnvelope,
-          error: {
-            code: "INTERNAL_ERROR",
-            message,
-            details: { cliCode: "bump-ver", verb: "bump-ver" }
-          }
-        }));
-        context.setExitCode(1);
-        return;
-      }
-      context.output.error(message);
-      context.setExitCode(1);
-    }
-  });
-  noun.command("drop-tags").summary("delete release tags locally and optionally on origin").description([
-    "Delete one package release tag (or every released tag plus the aggregate",
-    "with --all / a bare version). Use --remote to also delete on origin."
-  ].join(`
-`)).option("--all", "drop every released tag plus the aggregate tag").option("--remote", "also delete the tag(s) on origin").option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).argument("[target]", "package id, or the version itself when dropping all").argument("[version]", "semver version of the tags to drop").action(async (target, version, options) => {
-    const args = [target, version].filter((value) => value !== undefined);
-    if (options.all === true)
-      args.push("--all");
-    if (options.remote === true)
-      args.push("--remote");
-    try {
-      await dropTags(args, context.cwd, context.output, context.spurConfig);
-      if (options.json === true) {
-        context.output.write(toEnvelopeJson({ ok: true, verb: "drop-tags", target: target ?? "all", version: version ?? "" }, { enveloped: options.jsonEnvelope }));
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (options.json === true) {
-        context.output.write(toEnvelopeJson({ ok: false, verb: "drop-tags", error: message }, {
-          enveloped: options.jsonEnvelope,
-          error: {
-            code: "INTERNAL_ERROR",
-            message,
-            details: { cliCode: "drop-tags", verb: "drop-tags" }
-          }
-        }));
-        context.setExitCode(1);
-        return;
-      }
-      context.output.error(message);
-      context.setExitCode(1);
-    }
-  });
-  noun.command("publish").summary("resolve workspace/catalog ranges, build, and npm publish a package (CI)").description([
-    "CI publish for npm Trusted Publishing (OIDC): rewrite workspace:/catalog: ranges in",
-    "<dir>/package.json, run `bun run build:bundle`, `npm publish --access public`, and",
-    "restore the manifest on every exit path."
-  ].join(`
-`)).option("--otp <code>", "npm one-time password (local publishes only)").argument("<dir>", "package directory, relative to the workspace root").action(async (dir, options) => {
-    try {
-      await publishPackage(dir, {
-        repoRoot: context.cwd,
-        output: context.output,
-        ...options.otp !== undefined ? { otp: options.otp } : {}
-      });
-    } catch (err) {
-      context.output.error(err instanceof Error ? err.message : String(err));
-      context.setExitCode(1);
-    }
-  });
+  registerBuilderBumpVerCommand(noun, context);
+  registerBuilderDropTagsCommand(noun, context);
+  registerBuilderPublishCommand(noun, context);
   registerBuilderShowBranchesCommand(noun, context);
   registerBuilderPrCommand(noun, context);
 }
@@ -163114,161 +163133,35 @@ function fail2(context, options, error) {
   context.setExitCode(1);
 }
 
-// src/commands/feature.ts
+// src/commands/feature/advance.ts
 init_src4();
-init_src2();
 
-// src/commands/feature/handoff.ts
-function registerFeatureHandoffCommand(feature, context) {
-  feature.command("handoff").summary("Finalize the idea pipeline: task ordering, roster refresh and the handoff report.").description([
-    "Reads .spur/run/<runId>-idea-{task-batch,batch-create-result,task-order}.json (and the optional",
-    "-idea-ready.json), applies dependencies, refreshes the roster, checks each task and writes",
-    ".spur/run/<runId>-idea-handoff.md with one recommended next command.",
-    "Exit: 0 success; 1 failure (missing ids or inputs, a mapping or CLI error).",
-    "Flags fall back to the workflow env names: featureId, __runId, spurBin."
-  ].join(`
-`)).argument("[id]", "Feature ID (env: featureId)").option("--run-id <id>", "idea-pipeline run id (env: __runId)").option("--spur-bin <cmd>", "spur invocation for the nested task/feature calls (env: spurBin; default: this spur)").action(async (id, options) => {
-    const runId = options.runId ?? context.env.__runId;
-    if (runId && !acceptArtifactId(runId, "run id", context))
-      return;
-    await Promise.resolve().then(() => init_src4());
-    const env = context.env;
-    const outcome = await runIdeaHandoffCli({
-      __runId: options.runId ?? env.__runId,
-      ...options.spurBin === undefined && env.spurBin === undefined ? { spurArgv: resolveSpurArgv() } : {},
-      featureId: id ?? env.featureId,
-      spurBin: options.spurBin ?? env.spurBin ?? resolveSpurBin()
-    });
-    context.setExitCode(outcome.exitCode);
-  });
+// src/commands/feature/shared.ts
+init_src4();
+async function makeReceiptRunPort(context) {
+  return createFeatureReceiptRunPort(await context.getDb(), context.fs);
 }
-
-// src/commands/feature/verify.ts
-function registerFeatureVerifyCommand(feature, context) {
-  feature.command("verify").summary("Run the feature-verification pass and record its bound PASS/FAIL evidence receipt.").description([
-    "Runs the selected feature-verification definition\u2019s command once (or --cmd) and writes the",
-    "run-scoped + feature-latest receipts and .spur/run/<runId>-feature-verification.status.",
-    "Exit: 0 after a completed pass (PASS or FAIL); 1 when the pass could not run.",
-    "Without --run-id the pass opens and finalizes its own feature-lifecycle run row.",
-    "Flags fall back to the workflow env names: featureId, __runId."
-  ].join(`
-`)).argument("[id]", "Feature ID (env: featureId)").option("--run-id <id>", "workflow run id the receipt binds to (env: __runId)").option("--cmd <command>", "verification command override (env: verificationCmd)").action(async (id, options) => {
-    await Promise.resolve().then(() => init_src4());
-    const env = context.env;
-    const featureId = id || env.featureId || "";
-    try {
-      const result = await runFeatureVerification({
-        workdir: context.cwd,
-        featureId,
-        runId: options.runId || env.__runId || "",
-        cmdOverride: options.cmd || env.verificationCmd || ""
-      });
-      context.output.write(`feature verify: ${featureId} ${result.message}`);
-    } catch (err) {
-      context.output.error(`feature verify: ${String(err)}`);
-      context.setExitCode(1);
-    }
+async function makeService2(context, folderOverride) {
+  const resolved = await resolvePlanningFolders(context.fs);
+  const featuresDir = folderOverride ?? context.fs.resolve(resolved.featuresDir);
+  const tasksDir = context.fs.resolve(resolved.tasksDir);
+  const lifecycle = makeLifecycleAdapter(context, FEATURE_LIFECYCLE_PROFILE);
+  const writeService = new PlanningWriteService({
+    fs: context.fs,
+    ...lifecycle ? { lifecycle } : {},
+    emitter: makePlanningEmitter(context)
+  });
+  return new FeatureService({
+    fs: context.fs,
+    writeService,
+    featuresDir,
+    tasksDir,
+    foldersConfig: resolved.foldersConfig
   });
 }
 
-// src/commands/feature.ts
-function registerFeatureCommand(program, context) {
-  const feature = program.command("feature").summary("manage features (hierarchical IDs)");
-  feature.command("create").summary("Create a feature; allocates a hierarchical ID (DD-14) under the create-lock.").argument("<name>", "Feature name").option("--parent <id>", "Parent feature ID (child gets the next free digit 1-9)").option(...SHARED_OPTIONS.folderFeatures).option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (name, options) => {
-    const svc = await makeService2(context, options.folder);
-    try {
-      const result = await svc.create(name, options.parent);
-      if (options.json) {
-        context.output.write(toEnvelopeJson(result, { enveloped: options.jsonEnvelope }));
-      } else {
-        context.output.write(`Created feature ${result.ref.id}: ${result.ref.filePath}`);
-      }
-    } catch (err) {
-      writeJsonError(context.output, options, String(err));
-      context.setExitCode(1);
-    }
-  });
-  feature.command("show").alias("get").summary("Show a feature by ID.").argument("<id>", "Feature ID").option(...SHARED_OPTIONS.folderFeatures).option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (id, options) => {
-    const svc = await makeService2(context, options.folder);
-    try {
-      const result = await svc.show(id);
-      if (result === null) {
-        writeJsonError(context.output, options, `Feature ${id} not found`, "NOT_FOUND");
-        context.setExitCode(1);
-        return;
-      }
-      if (options.json) {
-        const { content, ...rest } = result;
-        context.output.write(toEnvelopeJson({ ...rest, content }, { enveloped: options.jsonEnvelope }));
-      } else {
-        context.output.write(result.content);
-      }
-    } catch (err) {
-      writeJsonError(context.output, options, String(err));
-      context.setExitCode(1);
-    }
-  });
-  feature.command("update").summary("Update a feature status, scalar frontmatter field, or section body.").argument("<id>", "Feature ID").argument("[status]", "New lifecycle status").addHelpText("after", [
-    "Section names are validated against the closed-world canonical set; a rejected",
-    "`--section` costs a failed write. List valid names first:",
-    "`spur task sections <wbs> list`."
-  ].join(`
-`)).option("--field <key>", "Frontmatter field to set (e.g. priority)").option("--value <value>", "New value for --field").option(...SHARED_OPTIONS.section).option(...SHARED_OPTIONS.fromFile).option(...SHARED_OPTIONS.folderFeatures).option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (id, status, options) => {
-    const svc = await makeService2(context, options.folder);
-    try {
-      let result;
-      if (options.section !== undefined) {
-        if (options.fromFile === undefined) {
-          writeJsonError(context.output, options, "--from-file is required with --section", "VALIDATION_FAILED");
-          context.setExitCode(2);
-          return;
-        }
-        result = await svc.updateSection(id, options.section, options.fromFile);
-        if (!options.json) {
-          for (const warning of result.warnings ?? []) {
-            context.output.error(warning);
-          }
-          context.output.write(`Updated section '${options.section}' in feature ${result.ref.id}`);
-        }
-      } else if (options.fromFile !== undefined) {
-        writeJsonError(context.output, options, "--section is required with --from-file", "VALIDATION_FAILED");
-        context.setExitCode(2);
-        return;
-      }
-      if (options.field !== undefined) {
-        if (options.value === undefined) {
-          writeJsonError(context.output, options, "--value is required with --field", "VALIDATION_FAILED");
-          context.setExitCode(2);
-          return;
-        }
-        result = await svc.update(id, options.field, options.value);
-        if (!options.json) {
-          context.output.write(`Updated ${options.field} on feature ${result.ref.id}`);
-        }
-      } else if (options.value !== undefined) {
-        writeJsonError(context.output, options, "--field is required with --value", "VALIDATION_FAILED");
-        context.setExitCode(2);
-        return;
-      }
-      if (status !== undefined) {
-        result = await svc.transition(id, status);
-        if (!options.json) {
-          context.output.write(`${result.ref.id}: ${result.fromStatus} \u2192 ${result.toStatus}`);
-        }
-      }
-      if (result === undefined) {
-        writeJsonError(context.output, options, "Either <status>, --field/--value, or --section/--from-file is required", "VALIDATION_FAILED");
-        context.setExitCode(2);
-        return;
-      }
-      if (options.json) {
-        context.output.write(toEnvelopeJson(result, { enveloped: options.jsonEnvelope }));
-      }
-    } catch (err) {
-      writeJsonError(context.output, options, String(err));
-      context.setExitCode(1);
-    }
-  });
+// src/commands/feature/advance.ts
+function registerFeatureAdvanceCommand(feature, context) {
   feature.command("advance").summary("Walk a feature through the legal forward lifecycle path.").argument("<id>", "Feature ID to advance").option("--to <status>", "Target status (default: 'done')").option(...SHARED_OPTIONS.folderFeatures).option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (id, options) => {
     const svc = await makeService2(context, options.folder);
     const target = options.to ?? "done";
@@ -163333,6 +163226,148 @@ function registerFeatureCommand(program, context) {
       context.setExitCode(1);
     }
   });
+}
+async function assertFeatureCheckPass(context, id, folderOverride, strict, asStatus) {
+  const resolved = await resolvePlanningFolders(context.fs);
+  const featuresDir = folderOverride ?? context.fs.resolve(resolved.featuresDir);
+  const tasksDir = context.fs.resolve(resolved.tasksDir);
+  const tasksDirs = Object.keys(resolved.foldersConfig.folders).map((p) => context.fs.resolve(p));
+  if (!tasksDirs.includes(tasksDir))
+    tasksDirs.unshift(tasksDir);
+  const entries = await context.fs.readDir(featuresDir);
+  const fileName = entries.find((name) => isFeatureFile(name, id));
+  if (fileName === undefined) {
+    throw new Error(`Feature ${id} not found`);
+  }
+  const result = await new FeatureCheckService(context.fs).check(`${featuresDir}/${fileName}`, id, {
+    strict,
+    featuresDir,
+    tasksDir,
+    tasksDirs,
+    runDir: context.fs.resolve(".spur/run"),
+    receiptRunPort: await makeReceiptRunPort(context),
+    asStatus
+  });
+  if (!result.pass) {
+    const details = result.findings.map((f) => `${f.layer} ${f.section}: ${f.message}`).join("; ");
+    throw new Error(`Feature ${id} check failed before advance${strict ? " (strict)" : ""}: ${details}`);
+  }
+}
+
+// src/commands/feature/check.ts
+init_src4();
+function registerFeatureCheckCommand(feature, context) {
+  feature.command("check").summary("Validate feature file(s) through the four-layer check (design \xA73).").argument("[id]", "Feature ID (validates all features in the folder when omitted)").option(...SHARED_OPTIONS.strictFeature).option(...SHARED_OPTIONS.asFeature0418).option(...SHARED_OPTIONS.folderFeatures).option("--fix", "repair structural findings in place (heading presence/level/order, R-item checkboxes)").option("--inventory <report>", "Cross-check the report requirement inventory against the AC covers lines (errors on uncovered items)").option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (id, options) => {
+    const resolved = await resolvePlanningFolders(context.fs);
+    const featuresDir = options.folder ?? context.fs.resolve(resolved.featuresDir);
+    const tasksDir = context.fs.resolve(resolved.tasksDir);
+    const tasksDirs = Object.keys(resolved.foldersConfig.folders).map((p) => context.fs.resolve(p));
+    if (!tasksDirs.includes(tasksDir))
+      tasksDirs.unshift(tasksDir);
+    const svc = new FeatureCheckService(context.fs);
+    const json = options.json === true;
+    const strict = options.strict === true;
+    const inventoryText = typeof options.inventory === "string" ? await Promise.resolve(context.fs.readFile(context.fs.resolve(options.inventory))).catch(() => "") : undefined;
+    try {
+      const entries = await context.fs.readDir(featuresDir);
+      const ids = id ? [id] : entries.map((n) => n.match(/^([A-Z][1-9]*)_.+\.md$/)?.[1]).filter((n) => n !== undefined);
+      const results = [];
+      for (const fid of ids) {
+        const fileName = entries.find((n) => isFeatureFile(n, fid));
+        if (!fileName) {
+          writeJsonError(context.output, options, `Feature ${fid} not found`, "NOT_FOUND");
+          context.setExitCode(1);
+          return;
+        }
+        const result = await svc.check(`${featuresDir}/${fileName}`, fid, {
+          strict,
+          featuresDir,
+          tasksDir,
+          tasksDirs,
+          runDir: context.fs.resolve(".spur/run"),
+          receiptRunPort: await makeReceiptRunPort(context),
+          severityOverrides: resolved.severityOverrides,
+          asStatus: options.as,
+          fix: options.fix === true,
+          inventory: inventoryText,
+          transitionPort: options.fix === true ? async (targetId, to) => {
+            const featureSvc = await makeService2(context, options.folder);
+            return featureSvc.transition(targetId, to);
+          } : undefined
+        });
+        results.push(result);
+        if (!json) {
+          if (result.repairs !== undefined && result.repairs.length > 0) {
+            for (const r of result.repairs) {
+              context.output.write(`  [FIX] ${r.kind} ${r.section}: ${r.detail}`);
+            }
+          }
+          context.output.write(`
+${result.id} (${result.status}): ${result.pass ? "PASS" : "FAIL"}`);
+          for (const f of result.findings) {
+            const tag = f.severity === "error" ? "ERR" : "WARN";
+            context.output.write(`  [${tag}] ${f.layer} ${f.section}: ${f.message}`);
+          }
+        }
+      }
+      if (json) {
+        context.output.write(toEnvelopeJson(results, { enveloped: options.jsonEnvelope, kind: "list" }));
+      }
+      if (results.some((r) => !r.pass))
+        context.setExitCode(1);
+    } catch (err) {
+      writeJsonError(context.output, options, String(err));
+      context.setExitCode(1);
+    }
+  });
+}
+
+// src/commands/feature/create.ts
+function registerFeatureCreateCommand(feature, context) {
+  feature.command("create").summary("Create a feature; allocates a hierarchical ID (DD-14) under the create-lock.").argument("<name>", "Feature name").option("--parent <id>", "Parent feature ID (child gets the next free digit 1-9)").option(...SHARED_OPTIONS.folderFeatures).option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (name, options) => {
+    const svc = await makeService2(context, options.folder);
+    try {
+      const result = await svc.create(name, options.parent);
+      if (options.json) {
+        context.output.write(toEnvelopeJson(result, { enveloped: options.jsonEnvelope }));
+      } else {
+        context.output.write(`Created feature ${result.ref.id}: ${result.ref.filePath}`);
+      }
+    } catch (err) {
+      writeJsonError(context.output, options, String(err));
+      context.setExitCode(1);
+    }
+  });
+}
+
+// src/commands/feature/handoff.ts
+function registerFeatureHandoffCommand(feature, context) {
+  feature.command("handoff").summary("Finalize the idea pipeline: task ordering, roster refresh and the handoff report.").description([
+    "Reads .spur/run/<runId>-idea-{task-batch,batch-create-result,task-order}.json (and the optional",
+    "-idea-ready.json), applies dependencies, refreshes the roster, checks each task and writes",
+    ".spur/run/<runId>-idea-handoff.md with one recommended next command.",
+    "Exit: 0 success; 1 failure (missing ids or inputs, a mapping or CLI error).",
+    "Flags fall back to the workflow env names: featureId, __runId, spurBin."
+  ].join(`
+`)).argument("[id]", "Feature ID (env: featureId)").option("--run-id <id>", "idea-pipeline run id (env: __runId)").option("--spur-bin <cmd>", "spur invocation for the nested task/feature calls (env: spurBin; default: this spur)").action(async (id, options) => {
+    const runId = options.runId ?? context.env.__runId;
+    if (runId && !acceptArtifactId(runId, "run id", context))
+      return;
+    await Promise.resolve().then(() => init_src4());
+    const env = context.env;
+    const outcome = await runIdeaHandoffCli({
+      __runId: options.runId ?? env.__runId,
+      ...options.spurBin === undefined && env.spurBin === undefined ? { spurArgv: resolveSpurArgv() } : {},
+      featureId: id ?? env.featureId,
+      spurBin: options.spurBin ?? env.spurBin ?? resolveSpurBin()
+    });
+    context.setExitCode(outcome.exitCode);
+  });
+}
+
+// src/commands/feature/list.ts
+init_src2();
+function registerFeatureListCommand(feature, context) {
   feature.command("list").summary("List features with optional status/priority filters.").option(...SHARED_OPTIONS.statusFilter).option(...SHARED_OPTIONS.priorityFilter).option(...SHARED_OPTIONS.folderFeatures).option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (options) => {
     const svc = await makeService2(context, options.folder);
     try {
@@ -163359,6 +163394,10 @@ function registerFeatureCommand(program, context) {
       context.setExitCode(1);
     }
   });
+}
+
+// src/commands/feature/move.ts
+function registerFeatureMoveCommand(feature, context) {
   feature.command("move").summary("Move a feature to a new parent \u2014 cascade rename of the subtree (DD-14).").argument("<id>", "Feature ID to move").option("--parent <id>", "New parent feature ID (omit to move to a top-level group)").option(...SHARED_OPTIONS.dryRunFeatureMap).option(...SHARED_OPTIONS.folderFeatures).option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (id, options) => {
     const svc = await makeService2(context, options.folder);
     try {
@@ -163379,6 +163418,11 @@ function registerFeatureCommand(program, context) {
       context.setExitCode(1);
     }
   });
+}
+
+// src/commands/feature/refresh.ts
+init_src4();
+function registerFeatureRefreshCommand(feature, context) {
   feature.command("refresh").summary("Rebuild INDEX.md and each feature ## Tasks table from task edges (docs only \u2014 no status change).").description([
     "Regenerate derived views so feature markdown matches the task graph:",
     "  \u2022 docs/features/INDEX.md (ID-encoded tree)",
@@ -163424,69 +163468,34 @@ function registerFeatureCommand(program, context) {
       context.setExitCode(1);
     }
   });
-  feature.command("check").summary("Validate feature file(s) through the four-layer check (design \xA73).").argument("[id]", "Feature ID (validates all features in the folder when omitted)").option(...SHARED_OPTIONS.strictFeature).option(...SHARED_OPTIONS.asFeature0418).option(...SHARED_OPTIONS.folderFeatures).option("--fix", "repair structural findings in place (heading presence/level/order, R-item checkboxes)").option("--inventory <report>", "Cross-check the report requirement inventory against the AC covers lines (errors on uncovered items)").option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (id, options) => {
-    const resolved = await resolvePlanningFolders(context.fs);
-    const featuresDir = options.folder ?? context.fs.resolve(resolved.featuresDir);
-    const tasksDir = context.fs.resolve(resolved.tasksDir);
-    const tasksDirs = Object.keys(resolved.foldersConfig.folders).map((p) => context.fs.resolve(p));
-    if (!tasksDirs.includes(tasksDir))
-      tasksDirs.unshift(tasksDir);
-    const svc = new FeatureCheckService(context.fs);
-    const json = options.json === true;
-    const strict = options.strict === true;
-    const inventoryText = typeof options.inventory === "string" ? await Promise.resolve(context.fs.readFile(context.fs.resolve(options.inventory))).catch(() => "") : undefined;
+}
+
+// src/commands/feature/show.ts
+function registerFeatureShowCommand(feature, context) {
+  feature.command("show").alias("get").summary("Show a feature by ID.").argument("<id>", "Feature ID").option(...SHARED_OPTIONS.folderFeatures).option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (id, options) => {
+    const svc = await makeService2(context, options.folder);
     try {
-      const entries = await context.fs.readDir(featuresDir);
-      const ids = id ? [id] : entries.map((n) => n.match(/^([A-Z][1-9]*)_.+\.md$/)?.[1]).filter((n) => n !== undefined);
-      const results = [];
-      for (const fid of ids) {
-        const fileName = entries.find((n) => isFeatureFile(n, fid));
-        if (!fileName) {
-          writeJsonError(context.output, options, `Feature ${fid} not found`, "NOT_FOUND");
-          context.setExitCode(1);
-          return;
-        }
-        const result = await svc.check(`${featuresDir}/${fileName}`, fid, {
-          strict,
-          featuresDir,
-          tasksDir,
-          tasksDirs,
-          runDir: context.fs.resolve(".spur/run"),
-          receiptRunPort: await makeReceiptRunPort(context),
-          severityOverrides: resolved.severityOverrides,
-          asStatus: options.as,
-          fix: options.fix === true,
-          inventory: inventoryText,
-          transitionPort: options.fix === true ? async (targetId, to) => {
-            const featureSvc = await makeService2(context, options.folder);
-            return featureSvc.transition(targetId, to);
-          } : undefined
-        });
-        results.push(result);
-        if (!json) {
-          if (result.repairs !== undefined && result.repairs.length > 0) {
-            for (const r of result.repairs) {
-              context.output.write(`  [FIX] ${r.kind} ${r.section}: ${r.detail}`);
-            }
-          }
-          context.output.write(`
-${result.id} (${result.status}): ${result.pass ? "PASS" : "FAIL"}`);
-          for (const f of result.findings) {
-            const tag = f.severity === "error" ? "ERR" : "WARN";
-            context.output.write(`  [${tag}] ${f.layer} ${f.section}: ${f.message}`);
-          }
-        }
+      const result = await svc.show(id);
+      if (result === null) {
+        writeJsonError(context.output, options, `Feature ${id} not found`, "NOT_FOUND");
+        context.setExitCode(1);
+        return;
       }
-      if (json) {
-        context.output.write(toEnvelopeJson(results, { enveloped: options.jsonEnvelope, kind: "list" }));
+      if (options.json) {
+        const { content, ...rest } = result;
+        context.output.write(toEnvelopeJson({ ...rest, content }, { enveloped: options.jsonEnvelope }));
+      } else {
+        context.output.write(result.content);
       }
-      if (results.some((r) => !r.pass))
-        context.setExitCode(1);
     } catch (err) {
       writeJsonError(context.output, options, String(err));
       context.setExitCode(1);
     }
   });
+}
+
+// src/commands/feature/sync.ts
+function registerFeatureSyncCommand(feature, context) {
   feature.command("sync").summary("Align feature lifecycle status with linked task states (status only \u2014 runs transition guards).").description([
     "Derive a feature status proposal from linked task statuses and apply legal hops",
     "(e.g. all tasks done \u2192 advance toward done; reopened work \u2192 reopen the feature).",
@@ -163545,165 +163554,134 @@ ${result.id} (${result.status}): ${result.pass ? "PASS" : "FAIL"}`);
       context.setExitCode(1);
     }
   });
-  registerFeatureVerifyCommand(feature, context);
-  registerFeatureHandoffCommand(feature, context);
 }
-async function makeReceiptRunPort(context) {
-  return createFeatureReceiptRunPort(await context.getDb(), context.fs);
-}
-async function makeService2(context, folderOverride) {
-  const resolved = await resolvePlanningFolders(context.fs);
-  const featuresDir = folderOverride ?? context.fs.resolve(resolved.featuresDir);
-  const tasksDir = context.fs.resolve(resolved.tasksDir);
-  const lifecycle = makeLifecycleAdapter(context, FEATURE_LIFECYCLE_PROFILE);
-  const writeService = new PlanningWriteService({
-    fs: context.fs,
-    ...lifecycle ? { lifecycle } : {},
-    emitter: makePlanningEmitter(context)
-  });
-  return new FeatureService({
-    fs: context.fs,
-    writeService,
-    featuresDir,
-    tasksDir,
-    foldersConfig: resolved.foldersConfig
+
+// src/commands/feature/update.ts
+function registerFeatureUpdateCommand(feature, context) {
+  feature.command("update").summary("Update a feature status, scalar frontmatter field, or section body.").argument("<id>", "Feature ID").argument("[status]", "New lifecycle status").addHelpText("after", [
+    "Section names are validated against the closed-world canonical set; a rejected",
+    "`--section` costs a failed write. List valid names first:",
+    "`spur task sections <wbs> list`."
+  ].join(`
+`)).option("--field <key>", "Frontmatter field to set (e.g. priority)").option("--value <value>", "New value for --field").option(...SHARED_OPTIONS.section).option(...SHARED_OPTIONS.fromFile).option(...SHARED_OPTIONS.folderFeatures).option(...SHARED_OPTIONS.json).option(...SHARED_OPTIONS.jsonEnvelope).action(async (id, status, options) => {
+    const svc = await makeService2(context, options.folder);
+    try {
+      let result;
+      if (options.section !== undefined) {
+        if (options.fromFile === undefined) {
+          writeJsonError(context.output, options, "--from-file is required with --section", "VALIDATION_FAILED");
+          context.setExitCode(2);
+          return;
+        }
+        result = await svc.updateSection(id, options.section, options.fromFile);
+        if (!options.json) {
+          for (const warning of result.warnings ?? []) {
+            context.output.error(warning);
+          }
+          context.output.write(`Updated section '${options.section}' in feature ${result.ref.id}`);
+        }
+      } else if (options.fromFile !== undefined) {
+        writeJsonError(context.output, options, "--section is required with --from-file", "VALIDATION_FAILED");
+        context.setExitCode(2);
+        return;
+      }
+      if (options.field !== undefined) {
+        if (options.value === undefined) {
+          writeJsonError(context.output, options, "--value is required with --field", "VALIDATION_FAILED");
+          context.setExitCode(2);
+          return;
+        }
+        result = await svc.update(id, options.field, options.value);
+        if (!options.json) {
+          context.output.write(`Updated ${options.field} on feature ${result.ref.id}`);
+        }
+      } else if (options.value !== undefined) {
+        writeJsonError(context.output, options, "--field is required with --value", "VALIDATION_FAILED");
+        context.setExitCode(2);
+        return;
+      }
+      if (status !== undefined) {
+        result = await svc.transition(id, status);
+        if (!options.json) {
+          context.output.write(`${result.ref.id}: ${result.fromStatus} \u2192 ${result.toStatus}`);
+        }
+      }
+      if (result === undefined) {
+        writeJsonError(context.output, options, "Either <status>, --field/--value, or --section/--from-file is required", "VALIDATION_FAILED");
+        context.setExitCode(2);
+        return;
+      }
+      if (options.json) {
+        context.output.write(toEnvelopeJson(result, { enveloped: options.jsonEnvelope }));
+      }
+    } catch (err) {
+      writeJsonError(context.output, options, String(err));
+      context.setExitCode(1);
+    }
   });
 }
-async function assertFeatureCheckPass(context, id, folderOverride, strict, asStatus) {
-  const resolved = await resolvePlanningFolders(context.fs);
-  const featuresDir = folderOverride ?? context.fs.resolve(resolved.featuresDir);
-  const tasksDir = context.fs.resolve(resolved.tasksDir);
-  const tasksDirs = Object.keys(resolved.foldersConfig.folders).map((p) => context.fs.resolve(p));
-  if (!tasksDirs.includes(tasksDir))
-    tasksDirs.unshift(tasksDir);
-  const entries = await context.fs.readDir(featuresDir);
-  const fileName = entries.find((name) => isFeatureFile(name, id));
-  if (fileName === undefined) {
-    throw new Error(`Feature ${id} not found`);
-  }
-  const result = await new FeatureCheckService(context.fs).check(`${featuresDir}/${fileName}`, id, {
-    strict,
-    featuresDir,
-    tasksDir,
-    tasksDirs,
-    runDir: context.fs.resolve(".spur/run"),
-    receiptRunPort: await makeReceiptRunPort(context),
-    asStatus
+
+// src/commands/feature/verify.ts
+function registerFeatureVerifyCommand(feature, context) {
+  feature.command("verify").summary("Run the feature-verification pass and record its bound PASS/FAIL evidence receipt.").description([
+    "Runs the selected feature-verification definition\u2019s command once (or --cmd) and writes the",
+    "run-scoped + feature-latest receipts and .spur/run/<runId>-feature-verification.status.",
+    "Exit: 0 after a completed pass (PASS or FAIL); 1 when the pass could not run.",
+    "Without --run-id the pass opens and finalizes its own feature-lifecycle run row.",
+    "Flags fall back to the workflow env names: featureId, __runId."
+  ].join(`
+`)).argument("[id]", "Feature ID (env: featureId)").option("--run-id <id>", "workflow run id the receipt binds to (env: __runId)").option("--cmd <command>", "verification command override (env: verificationCmd)").action(async (id, options) => {
+    await Promise.resolve().then(() => init_src4());
+    const env = context.env;
+    const featureId = id || env.featureId || "";
+    try {
+      const result = await runFeatureVerification({
+        workdir: context.cwd,
+        featureId,
+        runId: options.runId || env.__runId || "",
+        cmdOverride: options.cmd || env.verificationCmd || ""
+      });
+      context.output.write(`feature verify: ${featureId} ${result.message}`);
+    } catch (err) {
+      context.output.error(`feature verify: ${String(err)}`);
+      context.setExitCode(1);
+    }
   });
-  if (!result.pass) {
-    const details = result.findings.map((f) => `${f.layer} ${f.section}: ${f.message}`).join("; ");
-    throw new Error(`Feature ${id} check failed before advance${strict ? " (strict)" : ""}: ${details}`);
-  }
 }
 
-// src/commands/history.ts
-init_src4();
-init_src();
+// src/commands/feature/index.ts
+function registerFeatureCommand(program, context) {
+  const feature = program.command("feature").summary("manage features (hierarchical IDs)");
+  registerFeatureCreateCommand(feature, context);
+  registerFeatureShowCommand(feature, context);
+  registerFeatureUpdateCommand(feature, context);
+  registerFeatureAdvanceCommand(feature, context);
+  registerFeatureListCommand(feature, context);
+  registerFeatureMoveCommand(feature, context);
+  registerFeatureRefreshCommand(feature, context);
+  registerFeatureCheckCommand(feature, context);
+  registerFeatureSyncCommand(feature, context);
+  registerFeatureVerifyCommand(feature, context);
+  registerFeatureHandoffCommand(feature, context);
+}
+
+// src/commands/history/analyze.ts
 init_src2();
-init_dist28();
-init_dist7();
-import { createRequire as createRequire3 } from "module";
 
 // src/config.ts
 var CLI_CONFIG = {
   binaryName: "spur",
   binaryLabel: "spur",
-  binaryVersion: "0.4.23",
+  binaryVersion: "0.4.25",
   configDir: ".spur",
   configFile: ".spur/config.yaml",
   databaseFile: ".spur/spur.db"
 };
 
-// src/commands/history/anatomy.ts
-function spurEntryPath(argv = process.argv, execPath = process.execPath) {
-  const entry = argv[1];
-  return entry !== undefined && /\.(?:[cm]?[jt]s)$/.test(entry) ? entry : execPath;
-}
-var OPS = {
-  digest: "<artifact.json> \u2014 semantic artifact digest",
-  check: "<report.md> \u2014 report-contract structure gate (PASS/FAIL)",
-  paths: "--out <env> [--skill-dir d] ... \u2014 resolve the run paths into an env file",
-  "assert-clean": "--baseline <porcelain> [--expect <path>]... \u2014 fail on undeclared writes",
-  probe: "--artifact a --target t ... \u2014 cache disposition + provenance",
-  stamp: "--candidate c --provenance p --out o \u2014 stamp provenance frontmatter",
-  refresh: "--report r --out o \u2014 refresh a cache-hit report",
-  publish: "<candidate.md> <target.md> \u2014 atomic publish"
-};
-function registerHistoryAnatomyCommand(history, context) {
-  const run = async (argv) => {
-    for (let i = 0;i < argv.length; i++) {
-      if (argv[i] === "--run-id" && !acceptArtifactId(argv[i + 1] ?? "", "run id", context))
-        return;
-    }
-    await Promise.resolve().then(() => init_history_anatomy_cli());
-    const result = runCacheCli(argv, {
-      helper: spurEntryPath(),
-      cwd: context.cwd,
-      ...context.env.HOME !== undefined ? { home: context.env.HOME } : {}
-    });
-    writeStepText(context.output, "stdout", result.stdout);
-    writeStepText(context.output, "stderr", result.stderr);
-    context.setExitCode(result.exitCode);
-  };
-  for (const [op, synopsis] of Object.entries(OPS)) {
-    history.command(`anatomy-${op}`).summary(`history-anatomy cache op: ${synopsis}`).description(`history-anatomy cache op (ADR-079): ${op} ${synopsis}
-Exit: 0 ok, 1 usage or op failure.`).allowUnknownOption(true).allowExcessArguments(true).argument("[argv...]", "the op flags and operands (see description)").action((argv) => run([op, ...argv]));
-  }
-}
-
-// src/commands/history/summary.ts
-function registerHistorySummaryCommand(history, context) {
-  history.command("summary").summary("Daily summary report: tokens, git activity, history health, annotations").description([
-    "Generate the day\u2019s Markdown summary and write it to docs/daily/summary_<YYYYMMDD>.md",
-    "(or --output). Prompts for learnings / issues / pending unless SP_DAILY_SUMMARY_NO_PROMPT=1",
-    "(non-TTY stdin supplies the three answers as lines). Exit: 0 written, 1 generation failed."
-  ].join(`
-`)).option("--date <date>", "YYYY-MM-DD, today or yesterday (default: today)").option("--dry-run", "print the summary without writing the file").option("--output <path>", "write to a custom path").option("--no-git", "skip git history collection").option("--no-ccusage", "skip token usage collection").action(async (options) => {
-    await Promise.resolve().then(() => init_daily_summary());
-    const argv = [];
-    if (options.date !== undefined)
-      argv.push("--date", options.date);
-    if (options.dryRun === true)
-      argv.push("--dry-run");
-    if (options.output !== undefined)
-      argv.push("--output", options.output);
-    if (options.git === false)
-      argv.push("--no-git");
-    if (options.ccusage === false)
-      argv.push("--no-ccusage");
-    const code = await main(argv, {
-      out: (line) => context.output.write(line),
-      err: (line) => context.output.error(line)
-    });
-    context.setExitCode(code);
-  });
-}
-
-// src/commands/history/timeline.ts
-function registerHistoryTimelineCommand(history, context) {
-  history.command("timeline").summary("Per-prompt work/wait time and tokens from the host transcript (JSON)").description([
-    "Read the active host transcript read-only (CLAUDE_CODE_SESSION_ID under ~/.claude/projects,",
-    "PI_SESSION_FILE, or --transcript) and print one JSON timeline: a segment per operator prompt,",
-    'optional --group stages, and totals. No transcript \u2192 {"available":false,...}, exit 0.',
-    "Exit: 0 timeline (or unavailable), 2 invalid --group or unreadable transcript."
-  ].join(`
-`)).option("--transcript <path>", "transcript JSONL path (default: the active host session)").option("--group <spec>", 'sum segments into stages, e.g. "1-3,4"').action(async (options) => {
-    await Promise.resolve().then(() => init_session_timeline());
-    const argv = [];
-    if (options.transcript !== undefined)
-      argv.push("--transcript", options.transcript);
-    if (options.group !== undefined)
-      argv.push("--group", options.group);
-    const code = runSessionTimelineCli(argv, {
-      env: context.env,
-      write: (s) => writeStepText(context.output, "stdout", s),
-      writeErr: (s) => writeStepText(context.output, "stderr", s)
-    });
-    context.setExitCode(code);
-  });
-}
-
-// src/commands/history.ts
+// src/commands/history/shared.ts
+init_src4();
+init_dist7();
+import { createRequire as createRequire3 } from "module";
 function resolveCliSourceTimeout(explicit, env) {
   if (explicit !== undefined)
     return parseTimeoutInput(explicit);
@@ -163722,10 +163700,6 @@ async function resolveImportProvenance(fs) {
   } catch {}
   return { binary, importer };
 }
-function formatProvenance(provenance) {
-  return `binary: ${provenance.binary}
-importer: @gobing-ai/ts-llm-jsonl-importer@${provenance.importer}`;
-}
 var CAPABILITY_KINDS2 = new Set(["command", "subagent", "skill"]);
 function parseCapabilityOriginSpec(spec) {
   const parts = spec.split(":").map((part) => part.trim());
@@ -163749,132 +163723,42 @@ function parseCapabilityOriginSpec(spec) {
     originIdentity
   };
 }
-function registerHistoryCommand(program, context) {
-  const noun = program.command("history").summary("import and analyze coding-agent history");
-  const makeService = async (capabilityOrigins) => {
-    let taskLocator;
-    try {
-      const { foldersConfig } = await resolvePlanningFolders(context.fs);
-      taskLocator = TaskLocator.forDirs(context.fs, [
-        context.fs.resolve(foldersConfig.active_folder),
-        ...Object.keys(foldersConfig.folders ?? {}).map((f) => context.fs.resolve(f))
-      ]);
-    } catch {
-      taskLocator = undefined;
-    }
-    const provenance = await resolveImportProvenance(context.fs);
-    return new HistoryService({
-      getDb: () => context.getDb(),
-      agentConfig: context.agentConfig,
-      ...taskLocator ? { taskLocator } : {},
-      importerVersion: provenance.importer,
-      ...capabilityOrigins ? { capabilityOrigins } : {},
-      fs: context.fs,
-      cwd: context.cwd
-    });
-  };
-  noun.command("import").description("Import agent conversation JSONL. `--source all` fans out across all sources with " + "per-source failure isolation (task 0470). A single source is the n=1 case of " + "the same contract \u2014 never two import paths. For one session's evidence, use " + "`--file`; a full replay can exceed the per-source budget.").option(...SHARED_OPTIONS.sourceHistory, "all").option(...SHARED_OPTIONS.fileHistoryJsonl).option("--root <path>", "Scan a history root").option(...SHARED_OPTIONS.modeHistory).option(...SHARED_OPTIONS.dryRunHistoryScan).option("--source-timeout <ms|none>", `Per-source timeout in milliseconds or 'none' (default ${DEFAULT_SOURCE_TIMEOUT_MS} = 10 min)`).option(...SHARED_OPTIONS.jsonSupported).option(...SHARED_OPTIONS.jsonEnvelope).option("--capability-origin <spec>", "Classify skill calls against a released artifact: " + "source:skillName:artifactDigest:capabilityKind:originIdentity (repeatable).", (value, previous) => [...previous, value], []).action(async (options) => {
-    const source = options.source ?? "all";
-    if (options.file && source === "all") {
-      context.output.write(options.json ? toEnvelopeJson({ status: "error", message: '--file requires a single --source, not "all".' }, {
-        enveloped: options.jsonEnvelope,
-        error: {
-          code: "INTERNAL_ERROR",
-          message: '--file requires a single --source, not "all".',
-          details: { cliCode: "usage" }
-        }
-      }) : 'spur history import: --file requires a single --source, not "all".');
-      context.setExitCode(1);
-      return;
-    }
-    let sourceTimeout;
-    try {
-      sourceTimeout = resolveCliSourceTimeout(options.sourceTimeout, getEnvVars());
-    } catch (e) {
-      const timeoutMsg = `spur history import: ${e instanceof Error ? e.message : String(e)}`;
-      context.output.write(options.json ? toEnvelopeJson({ status: "error", message: timeoutMsg }, {
-        enveloped: options.jsonEnvelope,
-        error: { code: "INTERNAL_ERROR", message: timeoutMsg, details: { cliCode: "usage" } }
-      }) : timeoutMsg);
-      context.setExitCode(1);
-      return;
-    }
-    const mode = options.mode ?? (options.file ? "force-file" : "incremental");
-    if (mode !== "full" && mode !== "incremental" && mode !== "force-file") {
-      const modeMsg = `Invalid history import mode "${mode}". Expected one of: full, incremental, force-file`;
-      if (options.json) {
-        context.output.write(toEnvelopeJson({ status: "error", message: modeMsg }, {
-          enveloped: options.jsonEnvelope,
-          error: { code: "INTERNAL_ERROR", message: modeMsg, details: { cliCode: "usage" } }
-        }));
-      } else {
-        context.output.error(modeMsg);
-      }
-      context.setExitCode(1);
-      return;
-    }
-    if (options.file && mode === "full" && options.dryRun !== true) {
-      const unsafeMsg = "spur history import: --file <path> --mode full without --dry-run is unsafe \u2014 full mode " + "treats the file as the authoritative source for reconciliation. Preview with --dry-run, " + "or import a single file with --mode force-file.";
-      context.output.write(options.json ? toEnvelopeJson({ status: "error", message: unsafeMsg }, {
-        enveloped: options.jsonEnvelope,
-        error: { code: "INTERNAL_ERROR", message: unsafeMsg, details: { cliCode: "usage" } }
-      }) : unsafeMsg);
-      context.setExitCode(1);
-      return;
-    }
-    let capabilityOrigins;
-    if (options.capabilityOrigin.length > 0) {
-      try {
-        capabilityOrigins = options.capabilityOrigin.map(parseCapabilityOriginSpec);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        context.output.write(options.json ? toEnvelopeJson({ status: "error", message }, {
-          enveloped: options.jsonEnvelope,
-          error: { code: "INTERNAL_ERROR", message, details: { cliCode: "usage" } }
-        }) : `spur history import: ${message}`);
-        context.setExitCode(1);
-        return;
-      }
-    }
-    const svc = await makeService(capabilityOrigins);
-    let fanOut;
-    try {
-      fanOut = await svc.importAll({
-        sources: source === "all" ? undefined : [source],
-        file: options.file || undefined,
-        root: options.root || undefined,
-        mode,
-        dryRun: options.dryRun === true,
-        sourceTimeout,
-        onScope: (line) => context.output.error(line)
-      });
-    } catch (e) {
-      if (e instanceof UnsafeHistoryImporterError) {
-        const msg = `spur history import: ${e.code}: ${e.message}`;
-        context.output.write(options.json ? toEnvelopeJson({ status: "error", message: msg }, {
-          enveloped: options.jsonEnvelope,
-          error: {
-            code: "INTERNAL_ERROR",
-            message: msg,
-            details: {
-              cliCode: e.code,
-              installedVersion: e.installedVersion,
-              minSafeVersion: e.minSafeVersion
-            }
-          }
-        }) : msg);
-        context.setExitCode(1);
-        return;
-      }
-      throw e;
-    }
-    const provenance = await resolveImportProvenance(context.fs);
-    context.output.write(options.json ? toEnvelopeJson({ ...fanOut, provenance }, { enveloped: options.jsonEnvelope }) : `${formatProvenance(provenance)}
-${formatFanOutResult(fanOut)}`);
-    context.setExitCode(fanOut.exitCode);
+async function makeHistoryService(context, capabilityOrigins) {
+  let taskLocator;
+  try {
+    const { foldersConfig } = await resolvePlanningFolders(context.fs);
+    taskLocator = TaskLocator.forDirs(context.fs, [
+      context.fs.resolve(foldersConfig.active_folder),
+      ...Object.keys(foldersConfig.folders ?? {}).map((f) => context.fs.resolve(f))
+    ]);
+  } catch {
+    taskLocator = undefined;
+  }
+  const provenance = await resolveImportProvenance(context.fs);
+  return new HistoryService({
+    getDb: () => context.getDb(),
+    agentConfig: context.agentConfig,
+    ...taskLocator ? { taskLocator } : {},
+    importerVersion: provenance.importer,
+    ...capabilityOrigins ? { capabilityOrigins } : {},
+    fs: context.fs,
+    cwd: context.cwd
   });
+}
+function parseTopOrThrow(raw) {
+  if (raw === undefined)
+    return;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`--top must be a positive integer (got "${raw}")`);
+  }
+  return n;
+}
+
+// src/commands/history/analyze.ts
+function registerHistoryAnalyzeCommand(noun, context) {
   noun.command("analyze").description("Aggregate imported history with SQL and write a versioned JSON artifact (Q1-Q10 forensic query set).").option("--since <iso>", "Inclusive lower bound on message timestamp").option("--until <iso>", "Inclusive upper bound on message timestamp").option(...SHARED_OPTIONS.sourceHistory, "all").option("--session <id>", "Narrow to a single session id").option(...SHARED_OPTIONS.runHistory).option("--task <wbs>", "Narrow to a single task WBS").option("--top <n>", "Leaderboard depth for byTool/bySession", "20").option("--out <path>", "Write the artifact to this path instead of the dated reports dir").option(...SHARED_OPTIONS.jsonArtifact).option(...SHARED_OPTIONS.jsonEnvelope).action(async (options) => {
-    const svc = await makeService();
+    const svc = await makeHistoryService(context);
     const source = options.source ?? "all";
     const selector = {
       since: options.since || null,
@@ -163900,64 +163784,50 @@ ${formatFanOutResult(fanOut)}`);
       context.setExitCode(2);
     }
   });
-  noun.command("reset").description("Destructively wipe every history_* table: normalized rows, per-source ETL, board rollups, " + "daily stats, and importer checkpoints/ledger. Requires --yes. Task corpus and run " + "provenance (task_run_links) are untouched; a full `spur history import` rebuilds everything.").option("--yes", "Confirm the destructive wipe", false).option(...SHARED_OPTIONS.jsonSupported).option(...SHARED_OPTIONS.jsonEnvelope).action(async (options) => {
-    if (!options.yes) {
-      context.output.write(options.json ? toEnvelopeJson({ status: "error", message: "Refusing to wipe history tables without --yes." }, {
-        enveloped: options.jsonEnvelope,
-        error: {
-          code: "INTERNAL_ERROR",
-          message: "Refusing to wipe history tables without --yes.",
-          details: { cliCode: "usage" }
-        }
-      }) : "spur history reset: refusing to wipe history tables without --yes.");
-      context.setExitCode(1);
-      return;
-    }
-    const svc = await makeService();
-    const result = await svc.resetHistory();
-    const note = result.unknown.length > 0 ? ` WARNING: ${result.unknown.length} unlisted history_* table(s) left intact: ${result.unknown.join(", ")}` : "";
-    context.output.write(options.json ? toEnvelopeJson({
-      cleared: result.cleared,
-      skipped: result.skipped,
-      unknown: result.unknown,
-      clearedCount: result.cleared.length
-    }, { enveloped: options.jsonEnvelope }) : `cleared ${result.cleared.length} history tables` + (result.skipped.length > 0 ? ` (${result.skipped.length} not present)` : "") + note);
-  });
-  noun.command("report").description("Render a previously-generated history artifact as a spend + forensic report. " + "Never opens the database \u2014 pure renderer of the analyze JSON. " + "--task / --top narrow the already-loaded artifact client-side (0564 R3).").argument("[path]", "Artifact JSON path (defaults to the latest.json pointer)").option(...SHARED_OPTIONS.jsonParsedArtifact).option(...SHARED_OPTIONS.jsonEnvelope).option("--mode <name>", "Report mode: default | forensics (registry-resolved; unknown names fail)").option("--task <wbs>", "Narrow to a single task WBS the artifact was analyzed with").option("--top <n>", "Leaderboard depth for byTool/bySession (re-slices the artifact)").action(async (pathArg, options) => {
-    try {
-      const top = parseTopOrThrow(options.top);
-      const { report, artifactPath, resolution, artifact, banner } = runHistoryReport({
-        path: pathArg,
-        cwd: context.cwd,
-        now: new Date,
-        mode: options.mode,
-        task: options.task,
-        top
-      });
-      if (options.json) {
-        context.output.write(toEnvelopeJson(artifact, { enveloped: options.jsonEnvelope }));
-        context.setExitCode(0);
+}
+
+// src/commands/history/anatomy.ts
+function spurEntryPath(argv = process.argv, execPath = process.execPath) {
+  const entry = argv[1];
+  return entry !== undefined && /\.(?:[cm]?[jt]s)$/.test(entry) ? entry : execPath;
+}
+var OPS = {
+  digest: "<artifact.json> \u2014 semantic artifact digest",
+  check: "<report.md> \u2014 report-contract structure gate (PASS/FAIL)",
+  paths: "--out <env> [--skill-dir d] ... \u2014 resolve the run paths into an env file",
+  "assert-clean": "--baseline <porcelain> [--expect <path>]... \u2014 fail on undeclared writes",
+  probe: "--artifact a --target t ... \u2014 cache disposition + provenance",
+  stamp: "--candidate c --provenance p --out o \u2014 stamp provenance frontmatter",
+  refresh: "--report r --out o \u2014 refresh a cache-hit report",
+  publish: "<candidate.md> <target.md> \u2014 atomic publish"
+};
+function registerHistoryAnatomyCommand(history, context) {
+  const run = async (argv) => {
+    for (let i = 0;i < argv.length; i++) {
+      if (argv[i] === "--run-id" && !acceptArtifactId(argv[i + 1] ?? "", "run id", context))
         return;
-      }
-      if (resolution === "pointer") {
-        const staleBanner = stalenessBanner(artifact.generatedAt, new Date);
-        if (staleBanner !== null)
-          context.output.write(staleBanner);
-      }
-      if (banner !== null)
-        context.output.write(`${banner}
-`);
-      context.output.write(report);
-      context.output.write(`
-(artifact: ${artifactPath})
-`);
-      context.setExitCode(0);
-    } catch (e) {
-      const message = `spur history report failed: ${e.message}`;
-      context.output.write(options.json ? toEnvelopeJson({ status: "error", message }, { enveloped: options.jsonEnvelope, error: { code: "INTERNAL_ERROR", message } }) : message);
-      context.setExitCode(1);
     }
-  });
+    await Promise.resolve().then(() => init_history_anatomy_cli());
+    const result = runCacheCli(argv, {
+      helper: spurEntryPath(),
+      cwd: context.cwd,
+      ...context.env.HOME !== undefined ? { home: context.env.HOME } : {}
+    });
+    writeStepText(context.output, "stdout", result.stdout);
+    writeStepText(context.output, "stderr", result.stderr);
+    context.setExitCode(result.exitCode);
+  };
+  for (const [op, synopsis] of Object.entries(OPS)) {
+    history.command(`anatomy-${op}`).summary(`history-anatomy cache op: ${synopsis}`).description(`history-anatomy cache op (ADR-079): ${op} ${synopsis}
+Exit: 0 ok, 1 usage or op failure.`).allowUnknownOption(true).allowExcessArguments(true).argument("[argv...]", "the op flags and operands (see description)").action((argv) => run([op, ...argv]));
+  }
+}
+
+// src/commands/history/daily.ts
+init_src4();
+init_src();
+init_dist28();
+function registerHistoryDailyCommand(noun, context) {
   noun.command("daily").description("Run-once daily pipeline: import-all (fan-out, per-source isolation) \u2192 analyze \u2192 write " + "artifact \u2192 prune reports older than 90 days (task 0470 R6). Import uses checkpoint " + "resume, so a missed night self-heals on the next run with no gap and no double-count.").option("--since <iso>", "Inclusive lower bound on message timestamp for the report (not the import)").option("--until <iso>", "Inclusive upper bound on message timestamp for the report").option("--source-timeout <ms|none>", `Per-source import timeout in milliseconds or 'none' (default ${DEFAULT_SOURCE_TIMEOUT_MS} = 10 min)`).option("--root <path>", "History root override (default: per-source platform dir)").option(...SHARED_OPTIONS.jsonDaily).option(...SHARED_OPTIONS.jsonEnvelope).option("--mode <name>", "Render the artifact as a .md sidecar in this mode after analyze (e.g. forensics)").action(async (options) => {
     let sourceTimeout;
     try {
@@ -163971,7 +163841,7 @@ ${formatFanOutResult(fanOut)}`);
       context.setExitCode(1);
       return;
     }
-    const svc = await makeService();
+    const svc = await makeHistoryService(context);
     let refresh;
     try {
       refresh = parseHistoryRefreshContext(getEnvVar(HISTORY_REFRESH_CONTEXT_ENV));
@@ -164093,35 +163963,6 @@ ${formatFanOutResult(fanOut)}`);
     }
     context.output.write(options.json ? toEnvelopeJson(result, { enveloped: options.jsonEnvelope }) : formatDailyResult(result));
   });
-  registerHistoryAnatomyCommand(noun, context);
-  registerHistoryTimelineCommand(noun, context);
-  registerHistorySummaryCommand(noun, context);
-}
-function parseTopOrThrow(raw) {
-  if (raw === undefined)
-    return;
-  const n = Number(raw);
-  if (!Number.isInteger(n) || n < 1) {
-    throw new Error(`--top must be a positive integer (got "${raw}")`);
-  }
-  return n;
-}
-function formatFanOutResult(r) {
-  const lines = ["history import (fan-out)", "sources:"];
-  for (const e of r.entries) {
-    lines.push(`  ${e.source}: ${e.status} (files=${e.files} scanned, new-messages=${e.messages}, tool-calls=${e.toolCalls})`);
-  }
-  const a = r.attribution;
-  lines.push(`attribution: sessions=${a.sessionsEvaluated} links-created=${a.linksCreated} ` + `links-present=${a.linksAlreadyPresent} skipped=${a.skippedEvidence} ambiguous=${a.ambiguousEvidence}`);
-  if (r.warnings.length > 0) {
-    lines.push("warnings:");
-    for (const w of r.warnings) {
-      lines.push(`  [${w.code}] ${w.source ?? "-"}: ${w.detail}`);
-    }
-  }
-  lines.push(`exit_code: ${r.exitCode}`);
-  return lines.join(`
-`);
 }
 function formatDailyResult(r) {
   const lines = ["history daily"];
@@ -164148,6 +163989,266 @@ function formatDailyResult(r) {
 `);
 }
 
+// src/commands/history/import.ts
+init_src4();
+init_src();
+function registerHistoryImportCommand(noun, context) {
+  noun.command("import").description("Import agent conversation JSONL. `--source all` fans out across all sources with " + "per-source failure isolation (task 0470). A single source is the n=1 case of " + "the same contract \u2014 never two import paths. For one session's evidence, use " + "`--file`; a full replay can exceed the per-source budget.").option(...SHARED_OPTIONS.sourceHistory, "all").option(...SHARED_OPTIONS.fileHistoryJsonl).option("--root <path>", "Scan a history root").option(...SHARED_OPTIONS.modeHistory).option(...SHARED_OPTIONS.dryRunHistoryScan).option("--source-timeout <ms|none>", `Per-source timeout in milliseconds or 'none' (default ${DEFAULT_SOURCE_TIMEOUT_MS} = 10 min)`).option(...SHARED_OPTIONS.jsonSupported).option(...SHARED_OPTIONS.jsonEnvelope).option("--capability-origin <spec>", "Classify skill calls against a released artifact: " + "source:skillName:artifactDigest:capabilityKind:originIdentity (repeatable).", (value, previous) => [...previous, value], []).action(async (options) => {
+    const source = options.source ?? "all";
+    if (options.file && source === "all") {
+      context.output.write(options.json ? toEnvelopeJson({ status: "error", message: '--file requires a single --source, not "all".' }, {
+        enveloped: options.jsonEnvelope,
+        error: {
+          code: "INTERNAL_ERROR",
+          message: '--file requires a single --source, not "all".',
+          details: { cliCode: "usage" }
+        }
+      }) : 'spur history import: --file requires a single --source, not "all".');
+      context.setExitCode(1);
+      return;
+    }
+    let sourceTimeout;
+    try {
+      sourceTimeout = resolveCliSourceTimeout(options.sourceTimeout, getEnvVars());
+    } catch (e) {
+      const timeoutMsg = `spur history import: ${e instanceof Error ? e.message : String(e)}`;
+      context.output.write(options.json ? toEnvelopeJson({ status: "error", message: timeoutMsg }, {
+        enveloped: options.jsonEnvelope,
+        error: { code: "INTERNAL_ERROR", message: timeoutMsg, details: { cliCode: "usage" } }
+      }) : timeoutMsg);
+      context.setExitCode(1);
+      return;
+    }
+    const mode = options.mode ?? (options.file ? "force-file" : "incremental");
+    if (mode !== "full" && mode !== "incremental" && mode !== "force-file") {
+      const modeMsg = `Invalid history import mode "${mode}". Expected one of: full, incremental, force-file`;
+      if (options.json) {
+        context.output.write(toEnvelopeJson({ status: "error", message: modeMsg }, {
+          enveloped: options.jsonEnvelope,
+          error: { code: "INTERNAL_ERROR", message: modeMsg, details: { cliCode: "usage" } }
+        }));
+      } else {
+        context.output.error(modeMsg);
+      }
+      context.setExitCode(1);
+      return;
+    }
+    if (options.file && mode === "full" && options.dryRun !== true) {
+      const unsafeMsg = "spur history import: --file <path> --mode full without --dry-run is unsafe \u2014 full mode " + "treats the file as the authoritative source for reconciliation. Preview with --dry-run, " + "or import a single file with --mode force-file.";
+      context.output.write(options.json ? toEnvelopeJson({ status: "error", message: unsafeMsg }, {
+        enveloped: options.jsonEnvelope,
+        error: { code: "INTERNAL_ERROR", message: unsafeMsg, details: { cliCode: "usage" } }
+      }) : unsafeMsg);
+      context.setExitCode(1);
+      return;
+    }
+    let capabilityOrigins;
+    if (options.capabilityOrigin.length > 0) {
+      try {
+        capabilityOrigins = options.capabilityOrigin.map(parseCapabilityOriginSpec);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        context.output.write(options.json ? toEnvelopeJson({ status: "error", message }, {
+          enveloped: options.jsonEnvelope,
+          error: { code: "INTERNAL_ERROR", message, details: { cliCode: "usage" } }
+        }) : `spur history import: ${message}`);
+        context.setExitCode(1);
+        return;
+      }
+    }
+    const svc = await makeHistoryService(context, capabilityOrigins);
+    let fanOut;
+    try {
+      fanOut = await svc.importAll({
+        sources: source === "all" ? undefined : [source],
+        file: options.file || undefined,
+        root: options.root || undefined,
+        mode,
+        dryRun: options.dryRun === true,
+        sourceTimeout,
+        onScope: (line) => context.output.error(line)
+      });
+    } catch (e) {
+      if (e instanceof UnsafeHistoryImporterError) {
+        const msg = `spur history import: ${e.code}: ${e.message}`;
+        context.output.write(options.json ? toEnvelopeJson({ status: "error", message: msg }, {
+          enveloped: options.jsonEnvelope,
+          error: {
+            code: "INTERNAL_ERROR",
+            message: msg,
+            details: {
+              cliCode: e.code,
+              installedVersion: e.installedVersion,
+              minSafeVersion: e.minSafeVersion
+            }
+          }
+        }) : msg);
+        context.setExitCode(1);
+        return;
+      }
+      throw e;
+    }
+    const provenance = await resolveImportProvenance(context.fs);
+    context.output.write(options.json ? toEnvelopeJson({ ...fanOut, provenance }, { enveloped: options.jsonEnvelope }) : `${formatProvenance(provenance)}
+${formatFanOutResult(fanOut)}`);
+    context.setExitCode(fanOut.exitCode);
+  });
+}
+function formatProvenance(provenance) {
+  return `binary: ${provenance.binary}
+importer: @gobing-ai/ts-llm-jsonl-importer@${provenance.importer}`;
+}
+function formatFanOutResult(r) {
+  const lines = ["history import (fan-out)", "sources:"];
+  for (const e of r.entries) {
+    lines.push(`  ${e.source}: ${e.status} (files=${e.files} scanned, new-messages=${e.messages}, tool-calls=${e.toolCalls})`);
+  }
+  const a = r.attribution;
+  lines.push(`attribution: sessions=${a.sessionsEvaluated} links-created=${a.linksCreated} ` + `links-present=${a.linksAlreadyPresent} skipped=${a.skippedEvidence} ambiguous=${a.ambiguousEvidence}`);
+  if (r.warnings.length > 0) {
+    lines.push("warnings:");
+    for (const w of r.warnings) {
+      lines.push(`  [${w.code}] ${w.source ?? "-"}: ${w.detail}`);
+    }
+  }
+  lines.push(`exit_code: ${r.exitCode}`);
+  return lines.join(`
+`);
+}
+
+// src/commands/history/report.ts
+init_src4();
+init_src2();
+function registerHistoryReportCommand(noun, context) {
+  noun.command("report").description("Render a previously-generated history artifact as a spend + forensic report. " + "Never opens the database \u2014 pure renderer of the analyze JSON. " + "--task / --top narrow the already-loaded artifact client-side (0564 R3).").argument("[path]", "Artifact JSON path (defaults to the latest.json pointer)").option(...SHARED_OPTIONS.jsonParsedArtifact).option(...SHARED_OPTIONS.jsonEnvelope).option("--mode <name>", "Report mode: default | forensics (registry-resolved; unknown names fail)").option("--task <wbs>", "Narrow to a single task WBS the artifact was analyzed with").option("--top <n>", "Leaderboard depth for byTool/bySession (re-slices the artifact)").action(async (pathArg, options) => {
+    try {
+      const top = parseTopOrThrow(options.top);
+      const { report, artifactPath, resolution, artifact, banner } = runHistoryReport({
+        path: pathArg,
+        cwd: context.cwd,
+        now: new Date,
+        mode: options.mode,
+        task: options.task,
+        top
+      });
+      if (options.json) {
+        context.output.write(toEnvelopeJson(artifact, { enveloped: options.jsonEnvelope }));
+        context.setExitCode(0);
+        return;
+      }
+      if (resolution === "pointer") {
+        const staleBanner = stalenessBanner(artifact.generatedAt, new Date);
+        if (staleBanner !== null)
+          context.output.write(staleBanner);
+      }
+      if (banner !== null)
+        context.output.write(`${banner}
+`);
+      context.output.write(report);
+      context.output.write(`
+(artifact: ${artifactPath})
+`);
+      context.setExitCode(0);
+    } catch (e) {
+      const message = `spur history report failed: ${e.message}`;
+      context.output.write(options.json ? toEnvelopeJson({ status: "error", message }, { enveloped: options.jsonEnvelope, error: { code: "INTERNAL_ERROR", message } }) : message);
+      context.setExitCode(1);
+    }
+  });
+}
+
+// src/commands/history/reset.ts
+function registerHistoryResetCommand(noun, context) {
+  noun.command("reset").description("Destructively wipe every history_* table: normalized rows, per-source ETL, board rollups, " + "daily stats, and importer checkpoints/ledger. Requires --yes. Task corpus and run " + "provenance (task_run_links) are untouched; a full `spur history import` rebuilds everything.").option("--yes", "Confirm the destructive wipe", false).option(...SHARED_OPTIONS.jsonSupported).option(...SHARED_OPTIONS.jsonEnvelope).action(async (options) => {
+    if (!options.yes) {
+      context.output.write(options.json ? toEnvelopeJson({ status: "error", message: "Refusing to wipe history tables without --yes." }, {
+        enveloped: options.jsonEnvelope,
+        error: {
+          code: "INTERNAL_ERROR",
+          message: "Refusing to wipe history tables without --yes.",
+          details: { cliCode: "usage" }
+        }
+      }) : "spur history reset: refusing to wipe history tables without --yes.");
+      context.setExitCode(1);
+      return;
+    }
+    const svc = await makeHistoryService(context);
+    const result = await svc.resetHistory();
+    const note = result.unknown.length > 0 ? ` WARNING: ${result.unknown.length} unlisted history_* table(s) left intact: ${result.unknown.join(", ")}` : "";
+    context.output.write(options.json ? toEnvelopeJson({
+      cleared: result.cleared,
+      skipped: result.skipped,
+      unknown: result.unknown,
+      clearedCount: result.cleared.length
+    }, { enveloped: options.jsonEnvelope }) : `cleared ${result.cleared.length} history tables` + (result.skipped.length > 0 ? ` (${result.skipped.length} not present)` : "") + note);
+  });
+}
+
+// src/commands/history/summary.ts
+function registerHistorySummaryCommand(history, context) {
+  history.command("summary").summary("Daily summary report: tokens, git activity, history health, annotations").description([
+    "Generate the day\u2019s Markdown summary and write it to docs/daily/summary_<YYYYMMDD>.md",
+    "(or --output). Prompts for learnings / issues / pending unless SP_DAILY_SUMMARY_NO_PROMPT=1",
+    "(non-TTY stdin supplies the three answers as lines). Exit: 0 written, 1 generation failed."
+  ].join(`
+`)).option("--date <date>", "YYYY-MM-DD, today or yesterday (default: today)").option(...SHARED_OPTIONS.dryRunHistorySummary).option("--output <path>", "write to a custom path").option("--no-git", "skip git history collection").option("--no-ccusage", "skip token usage collection").action(async (options) => {
+    await Promise.resolve().then(() => init_daily_summary());
+    const argv = [];
+    if (options.date !== undefined)
+      argv.push("--date", options.date);
+    if (options.dryRun === true)
+      argv.push("--dry-run");
+    if (options.output !== undefined)
+      argv.push("--output", options.output);
+    if (options.git === false)
+      argv.push("--no-git");
+    if (options.ccusage === false)
+      argv.push("--no-ccusage");
+    const code = await main(argv, {
+      out: (line) => context.output.write(line),
+      err: (line) => context.output.error(line)
+    });
+    context.setExitCode(code);
+  });
+}
+
+// src/commands/history/timeline.ts
+function registerHistoryTimelineCommand(history, context) {
+  history.command("timeline").summary("Per-prompt work/wait time and tokens from the host transcript (JSON)").description([
+    "Read the active host transcript read-only (CLAUDE_CODE_SESSION_ID under ~/.claude/projects,",
+    "PI_SESSION_FILE, or --transcript) and print one JSON timeline: a segment per operator prompt,",
+    'optional --group stages, and totals. No transcript \u2192 {"available":false,...}, exit 0.',
+    "Exit: 0 timeline (or unavailable), 2 invalid --group or unreadable transcript."
+  ].join(`
+`)).option("--transcript <path>", "transcript JSONL path (default: the active host session)").option("--group <spec>", 'sum segments into stages, e.g. "1-3,4"').action(async (options) => {
+    await Promise.resolve().then(() => init_session_timeline());
+    const argv = [];
+    if (options.transcript !== undefined)
+      argv.push("--transcript", options.transcript);
+    if (options.group !== undefined)
+      argv.push("--group", options.group);
+    const code = runSessionTimelineCli(argv, {
+      env: context.env,
+      write: (s) => writeStepText(context.output, "stdout", s),
+      writeErr: (s) => writeStepText(context.output, "stderr", s)
+    });
+    context.setExitCode(code);
+  });
+}
+
+// src/commands/history/index.ts
+function registerHistoryCommand(program, context) {
+  const noun = program.command("history").summary("import and analyze coding-agent history");
+  registerHistoryImportCommand(noun, context);
+  registerHistoryAnalyzeCommand(noun, context);
+  registerHistoryResetCommand(noun, context);
+  registerHistoryReportCommand(noun, context);
+  registerHistoryDailyCommand(noun, context);
+  registerHistoryAnatomyCommand(noun, context);
+  registerHistoryTimelineCommand(noun, context);
+  registerHistorySummaryCommand(noun, context);
+}
+
 // src/commands/init.ts
 init_src4();
 init_src();
@@ -164528,13 +164629,13 @@ ${entry}
 }
 function describeZgReadiness(status) {
   if (!status.zg.available)
-    return `zg not installed (optional) \u2014 install: bun add -g @zvec/zvec-grep`;
+    return `zg not installed (optional) \u2014 install: ${ZG_INSTALL_HINT}`;
   if (status.zg.index === "ready")
     return "zg ready";
   if (status.zg.index === "stale")
-    return "zg index stale \u2014 run: zg index";
+    return `zg index stale \u2014 run: ${ZG_REFRESH_HINT}`;
   if (status.zg.index === "missing")
-    return "zg index missing \u2014 run: zg index --embedding local/potion-code-16m-v2";
+    return `zg index missing \u2014 run: ${ZG_INDEX_HINT}`;
   return "zg status unknown";
 }
 
@@ -171134,7 +171235,7 @@ init_dist5();
 import { homedir as homedir17 } from "os";
 import { basename as basename21, join as join94, relative as relative19, resolve as resolve37 } from "path";
 // ../server/package.json
-var version4 = "0.4.23";
+var version4 = "0.4.25";
 
 // ../server/src/modules/health/index.ts
 var startedAt = Date.now();