@taprootio/trellis 0.1.0

package/scripts/trellis-import.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// Trellis import CLI — a thin wrapper over the engine in src/import.mjs.
+//
+//   node scripts/trellis-import.mjs <source> (--profile <name> | --mapping <file>) [flags]
+//
+// Imports an existing backlog (at <source>) into the target Trellis repo using a
+// declarative mapping — either a built-in named profile (--profile, see
+// src/profiles.mjs) or your own mapping file (--mapping, see src/import.mjs for the
+// shape). DRY-RUN BY DEFAULT — it prints the plan, the id map, and per-field
+// warnings without writing; pass --apply to actually write items and regenerate.
+// The source tree is never modified. Logic lives in src/import.mjs and
+// src/profiles.mjs so the MCP import tool and `init --import` share it; this stays
+// dependency-free.
+
+import { resolve } from "node:path";
+import { applyImport } from "../src/import.mjs";
+import { optionToken, requiredValue, resolveRepoRoot, showHelp, usageError } from "../src/cli.mjs";
+import { loadProfile, loadMappingFile, listProfiles } from "../src/profiles.mjs";
+
+const HELP = `trellis import — import an existing backlog into Trellis
+
+Usage:
+  trellis import <source> (--profile <name> | --mapping <file>) [flags]
+
+Flags:
+  --profile <name>   built-in source-mapping profile (see --list-profiles)
+  --mapping <file>   declarative mapping file (JSON) describing the source schema
+  --target <dir>     target Trellis repo (default: ".")
+  --apply            write items and regenerate (default: dry-run, write nothing)
+  --dry-run          report the plan only (the default)
+  --list-profiles    list the built-in profiles and exit
+  -h, --help         show this help
+
+Provide exactly one of --profile or --mapping. The source tree is read-only; ids
+are assigned fresh-sequentially from the target's next id, colliding source ids are
+deduped, and depends_on is rewritten accordingly. Relative <source> paths resolve
+against the target repo.
+`;
+
+function parseArgs(argv) {
+  const opts = {};
+  let source;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const { key, inline } = optionToken(a);
+    switch (key) {
+      case "-h": case "--help": opts.help = true; break;
+      case "--apply": opts.apply = true; break;
+      case "--dry-run": opts.dryRun = true; break;
+      case "--list-profiles": opts.listProfiles = true; break;
+      case "--profile": {
+        const next = requiredValue(argv, i, inline, "--profile");
+        opts.profile = next.value;
+        i = next.index;
+        break;
+      }
+      case "--mapping": {
+        const next = requiredValue(argv, i, inline, "--mapping");
+        opts.mapping = next.value;
+        i = next.index;
+        break;
+      }
+      case "--target": case "--repo": {
+        const next = requiredValue(argv, i, inline, key);
+        opts.target = next.value;
+        i = next.index;
+        break;
+      }
+      default:
+        if (a.startsWith("-")) usageError(`Unknown flag: ${a}`);
+        if (source === undefined) source = a;
+        else usageError(`Unexpected extra argument: ${a}`);
+    }
+  }
+  return { source, opts };
+}
+
+function report(targetRoot, summary, dryRun) {
+  if (summary.errors.length) {
+    const wrote = summary.created.length || summary.generated.length;
+    console.error(wrote ? `Import of ${targetRoot} did not complete:` : `Refused to import into ${targetRoot} — wrote nothing:`);
+    for (const e of summary.errors) console.error(`  - ${e}`);
+    // Even on refusal, the id map + warnings help the user fix the mapping — e.g.
+    // see which source ids collided behind an ambiguous depends_on.
+    if (summary.idMap.length) {
+      console.error("  id map:");
+      for (const m of summary.idMap) console.error(`    ${m.sourceId} (${m.sourceFile}) → ${m.newId}`);
+    }
+    for (const w of summary.warnings) console.warn(`  warning: ${w}`);
+    return;
+  }
+  const c = summary.counts || { total: 0, active: 0, completed: 0, removed: 0 };
+  const verb = dryRun ? "Would import" : "Imported";
+  console.log(`${verb} ${c.total} item${c.total === 1 ? "" : "s"} into ${targetRoot}${dryRun ? " (dry run)" : ""}`);
+  console.log(`  counts: ${c.active} active, ${c.completed} completed, ${c.removed} removed`);
+  const pv = summary.provenance;
+  if (pv && (pv.gitDated || pv.dateDefaulted || pv.effortEstimated)) {
+    const parts = [];
+    if (pv.gitDated) parts.push(`${pv.gitDated} git-dated`);
+    if (pv.dateDefaulted) parts.push(`${pv.dateDefaulted} date-defaulted`);
+    if (pv.effortEstimated) parts.push(`${pv.effortEstimated} effort-estimated`);
+    console.log(`  estimated: ${parts.join(", ")}`);
+  }
+  if (summary.idMap.length) {
+    console.log("  id map:");
+    for (const m of summary.idMap) console.log(`    ${m.sourceId} (${m.sourceFile}) → ${m.newId}`);
+  }
+  if (summary.generated.length) console.log(`  ${dryRun ? "regenerate" : "generated"} (${summary.generated.length}): ${summary.generated.join(", ")}`);
+  for (const w of summary.warnings) console.log(`  warning: ${w}`);
+  if (!dryRun) console.log(`Done. Review ${summary.root}/, then commit.`);
+  else console.log("Dry run — nothing written. Re-run with --apply to write.");
+}
+
+const { source, opts } = parseArgs(process.argv.slice(2));
+if (opts.help) showHelp(HELP);
+
+if (opts.listProfiles) {
+  const profiles = listProfiles();
+  if (!profiles.length) { console.log("No built-in profiles found."); process.exit(0); }
+  console.log("Built-in profiles:");
+  for (const p of profiles) console.log(`  ${p.name}${p.description ? ` — ${p.description}` : ""}`);
+  process.exit(0);
+}
+
+if (!source) { console.error("error: a <source> path is required\n"); process.stdout.write(HELP); process.exit(2); }
+// Exactly one of --profile / --mapping (XOR via boolean coercion).
+if (!!opts.profile === !!opts.mapping) {
+  console.error("error: provide exactly one of --profile <name> or --mapping <file.json>");
+  process.exit(2);
+}
+
+const { mapping, error } = opts.profile ? loadProfile(opts.profile) : loadMappingFile(opts.mapping);
+if (error) { console.error(`error: ${error}`); process.exit(2); }
+
+const targetRoot = resolveRepoRoot(opts.target);
+const sourceRoot = resolve(targetRoot, source); // relative <source> resolves against the target repo
+const dryRun = opts.dryRun || !opts.apply; // dry-run by default; --apply writes, but an explicit --dry-run always wins
+
+const { summary } = applyImport(targetRoot, sourceRoot, mapping, { dryRun });
+report(targetRoot, summary, dryRun);
+process.exit(summary.errors.length ? 1 : 0);

package/scripts/trellis-init.mjs

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+// Trellis init CLI — a thin wrapper over the scaffolder in src/init.mjs.
+//
+//   node scripts/trellis-init.mjs [target] [flags]
+//
+// Onboards the target repo (default ".") to the Trellis layout. Vocabulary comes
+// from flags with sensible defaults; when run interactively with the prefix or
+// milestones omitted, it prompts for them. Idempotent — existing files are never
+// clobbered (use --force to overwrite). With `--import <path>` it then imports an
+// existing backlog via a named profile or a mapping file — the onboard-a-repo-that-
+// already-has-a-backlog on-ramp — reusing src/import.mjs and src/profiles.mjs. All
+// logic lives under src/, so this stays free of third-party dependencies.
+
+import { dirname, join, resolve, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { DEFAULTS, applyScaffold, resolveOptions, validateOptions, retireSource, shouldPromptVocab } from "../src/init.mjs";
+import { applyImport } from "../src/import.mjs";
+import { loadProfile, loadMappingFile } from "../src/profiles.mjs";
+
+const HELP = `trellis init — scaffold the Trellis backlog into a repo
+
+Usage:
+  trellis init [target] [flags]
+
+Flags:
+  --prefix <P>          id prefix (default: ${DEFAULTS.prefix})
+  --id-width <N>        zero-padded id digits (default: ${DEFAULTS.idWidth})
+  --milestones <a,b,c>  ordered maturity milestones (default: ${DEFAULTS.milestones.join(",")})
+  --priorities <a,b,c>  ordered priorities, highest first (default: ${DEFAULTS.priorities.join(",")})
+  --effort <1,2,3>      canonical effort values (default: ${DEFAULTS.effort.join(",")})
+  --import <path>       after scaffolding, import an existing backlog at <path>
+  --profile <name>      source-mapping profile for --import (trellis import --list-profiles)
+  --mapping <file>      mapping file (JSON) for --import (alternative to --profile)
+  --retire-source <p>   history-preservingly git-rm an imported source tree at <p>
+                        (a separate, later step — see below; cannot combine with --import)
+  --force               overwrite existing files instead of skipping
+  --dry-run             report what would change without writing
+  -h, --help            show this help
+
+With --import, provide exactly one of --profile or --mapping; a relative <path>
+resolves against the target repo. --dry-run previews the scaffold without writing;
+preview the import plan itself with "trellis import --dry-run" on the initialized repo.
+
+--retire-source removes the old source tree once the import is green and committed:
+it stages a "git rm -r <p>" (history preserved) and leaves the deletion for you to
+review and commit — it does not scaffold, import, or commit. Run it on its own, after
+the import, never in the same command (--dry-run lists the files without touching git).
+`;
+
+const sourceRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+function parseArgs(argv) {
+  const opts = {};
+  const csv = (s) => (s == null ? [] : s.split(",").map((x) => x.trim()).filter(Boolean));
+  let target = ".";
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const eq = a.indexOf("=");
+    const key = a.startsWith("--") && eq !== -1 ? a.slice(0, eq) : a;
+    const inline = a.startsWith("--") && eq !== -1 ? a.slice(eq + 1) : null;
+    // Read a flag's value. `--flag=value` always uses the inline value; with the space
+    // form, a following OPTION-looking token (anything starting with `-`, e.g. `--dry-run`
+    // or `-h`) means the value was OMITTED — do not swallow it. So `--retire-source -h` is
+    // a missing path (help wins / a clean usage error), never a path literally named "-h"
+    // with the real intent silently dropped onto a staged `git rm`. To pass a value that
+    // genuinely starts with `-`, use the inline form (`--flag=-x`) or, for a path, `./-x`.
+    const next = () => {
+      if (inline !== null) return inline;
+      const v = argv[i + 1];
+      if (v === undefined || v.startsWith("-")) return undefined;
+      i++;
+      return v;
+    };
+    switch (key) {
+      case "-h": case "--help": opts.help = true; break;
+      case "--force": opts.force = true; break;
+      case "--dry-run": opts.dryRun = true; break;
+      case "--import": opts.import = next(); break;
+      case "--profile": opts.profile = next(); break;
+      case "--mapping": opts.mapping = next(); break;
+      case "--retire-source": opts.retireSource = next(); break;
+      case "--prefix": opts.prefix = next(); break;
+      case "--id-width": opts.idWidth = Number(next()); break;
+      case "--milestones": opts.milestones = csv(next()); break;
+      case "--priorities": opts.priorities = csv(next()); break;
+      // Keep non-numeric tokens as NaN (don't filter) so a typo like
+      // `--effort 1,abc,3` is rejected by validateOptions, not silently dropped.
+      case "--effort": opts.effort = csv(next()).map(Number); break;
+      default:
+        if (a.startsWith("-")) { console.error(`Unknown flag: ${a}`); process.exit(2); }
+        target = a;
+    }
+  }
+  return { target, opts };
+}
+
+async function promptMissing(opts) {
+  // Prompt for the two the task calls out (prefix, milestones) only when one is missing
+  // on an interactive, non-dry, non-retire run — see shouldPromptVocab (keyed on flag
+  // presence so a valueless --retire-source doesn't prompt before erroring).
+  if (!shouldPromptVocab(opts, process.stdin.isTTY)) return;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    if (!opts.prefix) {
+      const a = (await rl.question(`ID prefix [${DEFAULTS.prefix}]: `)).trim();
+      if (a) opts.prefix = a;
+    }
+    if (!opts.milestones) {
+      const a = (await rl.question(`Milestones [${DEFAULTS.milestones.join(",")}]: `)).trim();
+      if (a) opts.milestones = a.split(",").map((x) => x.trim()).filter(Boolean);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function report(targetRoot, summary, dryRun) {
+  // Fatal errors → never claim success. "Refused" if nothing was written;
+  // "did not complete" if some files landed before a fatal generate failure.
+  if (summary.errors.length) {
+    const wroteSomething = summary.created.length || summary.appended.length || summary.generated.length;
+    console.error(wroteSomething
+      ? `Scaffold of ${targetRoot} did not complete:`
+      : `Refused to scaffold ${targetRoot} — wrote nothing:`);
+    for (const e of summary.errors) console.error(`  - ${e}`);
+    return;
+  }
+  const verb = dryRun ? "Would scaffold" : "Scaffolded";
+  console.log(`${verb} Trellis into ${targetRoot}${dryRun ? " (dry run)" : ""}`);
+  const line = (label, items) => { if (items.length) console.log(`  ${label} (${items.length}): ${items.join(", ")}`); };
+  line(dryRun ? "create" : "created", summary.created);
+  line(dryRun ? "append" : "appended", summary.appended);
+  line(dryRun ? "regenerate" : "generated", summary.generated);
+  line("skipped", summary.skipped);
+  // Remaining warnings are benign (e.g. a missing copy source) — the scaffold
+  // still completed, so they do not change the exit code.
+  for (const w of summary.warnings) console.warn(`  warning: ${w}`);
+  // Reconciliation checklist (TRL0027): stale backlog guidance for the agent to
+  // rewrite. Advisory and report-only — init never edited these — so, like warnings,
+  // it does not affect the exit code.
+  if (summary.reconcile && summary.reconcile.length) {
+    console.log(`  reconcile (${summary.reconcile.length}) — pre-Trellis backlog guidance to rewrite by hand (init left these untouched):`);
+    for (const r of summary.reconcile) console.log(`    - ${r.file}: ${r.note}`);
+  }
+  if (!dryRun) {
+    console.log(`Done. For a fresh backlog, add a task under ${summary.root}/active/, then \`npx @taprootio/trellis generate\`.`);
+    console.log(`If you are importing an existing backlog, run \`npx @taprootio/trellis import ...\` before creating any new task so imported ids keep the first available range.`);
+    console.log(`Then enable branch protection so the \`backlog\` check gates merges — see trellis/branch-protection.md.`);
+  }
+}
+
+// Usage errors for the --import on-ramp, validated before any write: --profile /
+// --mapping only make sense with --import, and --import needs exactly one of them.
+function importFlagErrors(opts) {
+  const errors = [];
+  const hasProfile = !!opts.profile, hasMapping = !!opts.mapping;
+  if (!opts.import) {
+    if (hasProfile || hasMapping) errors.push("--profile/--mapping only apply with --import <path>");
+    return errors;
+  }
+  if (hasProfile === hasMapping) errors.push("--import requires exactly one of --profile <name> or --mapping <file>");
+  return errors;
+}
+
+// --retire-source is a separate, later step — never automatic mid-import (TRL0027), so
+// it cannot share a run with --import. Keyed on the flag's PRESENCE (not a truthy
+// value): a valueless `--retire-source` (trailing flag, or `--retire-source=`) must be
+// a usage error, not a silent fall-through to scaffolding.
+function retireFlagErrors(opts) {
+  if (!("retireSource" in opts)) return [];
+  const errors = [];
+  if (!opts.retireSource || !String(opts.retireSource).trim()) errors.push("--retire-source requires a path");
+  if (opts.import) errors.push("--retire-source cannot be combined with --import — retire the source in a separate run after the import is committed");
+  return errors;
+}
+
+// Concise report for the follow-on import (mirrors the trellis import CLI). Fatal
+// errors never claim success; otherwise echo counts + the id map so the user can
+// review before committing.
+function reportImport(targetRoot, summary) {
+  if (summary.errors.length) {
+    const wrote = summary.created.length || summary.generated.length;
+    console.error(wrote ? `Import into ${targetRoot} did not complete:` : `Refused to import into ${targetRoot} — wrote nothing:`);
+    for (const e of summary.errors) console.error(`  - ${e}`);
+    for (const w of summary.warnings) console.warn(`  warning: ${w}`);
+    return;
+  }
+  const c = summary.counts || { total: 0, active: 0, completed: 0, removed: 0 };
+  console.log(`Imported ${c.total} item${c.total === 1 ? "" : "s"} (${c.active} active, ${c.completed} completed, ${c.removed} removed).`);
+  const pv = summary.provenance;
+  if (pv && (pv.gitDated || pv.dateDefaulted || pv.effortEstimated)) {
+    const parts = [];
+    if (pv.gitDated) parts.push(`${pv.gitDated} git-dated`);
+    if (pv.dateDefaulted) parts.push(`${pv.dateDefaulted} date-defaulted`);
+    if (pv.effortEstimated) parts.push(`${pv.effortEstimated} effort-estimated`);
+    console.log(`  estimated: ${parts.join(", ")}`);
+  }
+  if (summary.idMap.length) {
+    console.log("  id map:");
+    for (const m of summary.idMap) console.log(`    ${m.sourceId} (${m.sourceFile}) → ${m.newId}`);
+  }
+  for (const w of summary.warnings) console.warn(`  warning: ${w}`);
+  console.log(`Done. Review ${summary.root}/, then commit.`);
+}
+
+// Report for --retire-source. A refusal (errors) never claims success; otherwise echo
+// the staged-but-uncommitted removal and steer the user to review + commit.
+function reportRetire(summary, dryRun) {
+  if (summary.errors.length) {
+    console.error(`Refused to retire ${summary.path ? `"${summary.path}"` : "the source"} — nothing changed:`);
+    for (const e of summary.errors) console.error(`  - ${e}`);
+    return;
+  }
+  const n = summary.removed.length;
+  const files = `${n} tracked file${n === 1 ? "" : "s"}`;
+  if (dryRun) {
+    // List the files: a dry run stages nothing, so there is no `git status` to inspect —
+    // the report is the only place the user sees exactly what would be removed.
+    console.log(`Would retire "${summary.path}" — git rm ${files} (dry run, nothing changed):`);
+    for (const f of summary.removed) console.log(`    ${f}`);
+    return;
+  }
+  console.log(`Retired "${summary.path}" — staged the removal of ${files} with git rm.`);
+  console.log("Review with `git status`, then commit. Git preserves the history.");
+}
+
+const { target, opts } = parseArgs(process.argv.slice(2));
+if (opts.help) { process.stdout.write(HELP); process.exit(0); }
+
+await promptMissing(opts);
+
+// Scaffold vocabulary is irrelevant to a retire-only run (it never scaffolds), so don't
+// validate it there — mirrors promptMissing, which also skips on retire.
+if (!("retireSource" in opts)) {
+  const optErrors = validateOptions(resolveOptions(opts));
+  if (optErrors.length) {
+    for (const e of optErrors) console.error(`error: ${e}`);
+    process.exit(2);
+  }
+}
+
+const flagErrors = [...importFlagErrors(opts), ...retireFlagErrors(opts)];
+if (flagErrors.length) {
+  for (const e of flagErrors) console.error(`error: ${e}`);
+  process.exit(2);
+}
+
+const targetRoot = resolve(target);
+const dryRun = !!opts.dryRun;
+
+// --retire-source: a deliberate, standalone step run after the import is committed. It
+// does not scaffold or import — it stages a history-preserving `git rm` of the source.
+// Keyed on presence (a valueless flag was already rejected by retireFlagErrors).
+if ("retireSource" in opts) {
+  const { summary: ret } = retireSource(targetRoot, opts.retireSource, { dryRun });
+  reportRetire(ret, dryRun);
+  process.exit(ret.errors.length ? 1 : 0);
+}
+
+const { summary } = applyScaffold(targetRoot, opts, { dryRun }, sourceRoot);
+report(targetRoot, summary, dryRun);
+// A failed scaffold (refusal or generate failure) is fatal and blocks any import.
+if (summary.errors.length) process.exit(1);
+
+// --import on-ramp: scaffold, then import an existing backlog in one command.
+if (opts.import) {
+  const { mapping, error } = opts.profile ? loadProfile(opts.profile) : loadMappingFile(opts.mapping);
+  if (error) { console.error(`error: ${error}`); process.exit(2); }
+  const importSource = isAbsolute(opts.import) ? opts.import : resolve(targetRoot, opts.import);
+  if (dryRun) {
+    // A dry run scaffolds nothing, so there is no initialized target to plan the
+    // import against — report intent and point at `trellis import --dry-run` (which
+    // previews the full plan against an initialized repo) rather than computing a
+    // misleading plan here against a non-existent backlog.
+    const via = opts.profile ? `profile ${opts.profile}` : `mapping ${opts.mapping}`;
+    console.log(`Would then import from ${importSource} using ${via}.`);
+    console.log("Re-run without --dry-run to scaffold and import, or run `npx @taprootio/trellis import --dry-run` on the initialized repo to preview the import plan.");
+    process.exit(0);
+  }
+  const { summary: imp } = applyImport(targetRoot, importSource, mapping, { dryRun: false });
+  reportImport(targetRoot, imp);
+  process.exit(imp.errors.length ? 1 : 0);
+}
+
+// A benign warning (e.g. a missing copy source) on a completed scaffold exits 0.
+process.exit(0);

package/scripts/trellis-mcp.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// Trellis MCP server — exposes the backlog operations as MCP tools over stdio.
+//
+//   node scripts/trellis-mcp.mjs [--repo <path>]
+//
+// The tools are thin adapters over src/mcp.mjs (which is dependency-free and
+// unit-tested); the @modelcontextprotocol SDK and the transport live only in this
+// entry point. Each tool resolves a repo root — the per-call `repoRoot` arg, else
+// the server's default (`--repo`, else cwd) — so one server can serve any repo the
+// client points at.
+//
+// stdout is the JSON-RPC channel: all diagnostics go to stderr.
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { optionToken, requiredValue, resolveRepoRoot, usageError } from "../src/cli.mjs";
+import { OPS, TrellisError } from "../src/mcp.mjs";
+import { RESOURCES, PROMPTS, listResources, readResource, buildPrompt } from "../src/prompts.mjs";
+
+// Server implementation version (distinct from the spec version; packaging and
+// real versioning are TRL0010).
+const SERVER_VERSION = "0.1.0";
+
+function parseArgs(argv) {
+  let repo;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const { key, inline } = optionToken(a);
+    if (key === "--repo" || key === "--target") {
+      const next = requiredValue(argv, i, inline, key);
+      repo = next.value;
+      i = next.index;
+    } else if (a === "-h" || a === "--help") {
+      return { help: true };
+    } else {
+      usageError(`Unknown argument: ${a}`);
+    }
+  }
+  return { repo: resolveRepoRoot(repo) };
+}
+
+const HELP = `trellis mcp — serve the Trellis backlog operations over MCP (stdio)
+
+Usage:
+  trellis mcp [--repo <path>]
+
+Options:
+  --repo <path>   default repo root for tools that omit \`repoRoot\`, and the repo
+                  served for prompts and resources (default: cwd)
+  -h, --help      show this help
+
+Tools:     ${Object.keys(OPS).join(", ")}
+Prompts:   ${PROMPTS.map((p) => p.name).join(", ")}
+Resources: ${RESOURCES.map((r) => r.uri).join(", ")}
+`;
+
+const repoRootArg = { repoRoot: z.string().optional().describe("repo root to operate on; defaults to the server's --repo / cwd") };
+
+// name → { description, inputSchema (a zod raw shape) }. The handler for each is
+// OPS[name]; every tool also accepts the shared optional `repoRoot`. Exported so a
+// test can assert the served metadata stays repo-agnostic without booting the server.
+export const TOOLS = {
+  list_tasks: {
+    description: "List backlog tasks (the backlog.json shape), optionally filtered by status or milestone.",
+    inputSchema: {
+      ...repoRootArg,
+      status: z.enum(["active", "completed", "removed"]).optional().describe("only tasks with this status"),
+      milestone: z.string().optional().describe("only tasks in this milestone"),
+    },
+  },
+  get_task: {
+    description: "Get one task by id: its structured entry plus the raw Markdown body and file path.",
+    inputSchema: { ...repoRootArg, id: z.string().describe("task id using this repo's configured id prefix and width") },
+  },
+  next_id: {
+    description: "The id a newly created task would receive.",
+    inputSchema: { ...repoRootArg },
+  },
+  create_task: {
+    description: "Create an active task: assigns the next id, writes the item file, then regenerates and validates.",
+    inputSchema: {
+      ...repoRootArg,
+      title: z.string().describe("one-line title"),
+      summary: z.string().describe("one-sentence summary for the index"),
+      milestone: z.string().describe("a configured milestone"),
+      priority: z.string().describe("a configured priority"),
+      effort: z.union([z.number(), z.string()]).describe("a canonical effort number, or a label from the active effort scale"),
+      depends_on: z.array(z.string()).optional().describe("ids this task depends on"),
+      owner: z.string().optional().describe("owner handle; must be an active member of the team roster (team.json)"),
+      collaborators: z.array(z.string()).optional().describe("collaborator handles; each must be an active roster member"),
+      body: z.string().optional().describe("Markdown body; Scope/Notes/Risks are scaffolded if omitted"),
+    },
+  },
+  move_task: {
+    description: "Move an active task to completed or removed: updates front-matter, prepends a closeout note, regenerates and validates.",
+    inputSchema: {
+      ...repoRootArg,
+      id: z.string().describe("active task id to move"),
+      to: z.enum(["completed", "removed"]).describe("target status"),
+      reason: z.string().optional().describe("required when removing: why, and any trigger to revisit"),
+      note: z.string().optional().describe("closeout note prepended to the body"),
+      date: z.string().optional().describe("ISO close date (YYYY-MM-DD); defaults to today"),
+      owner: z.string().optional().describe("override the owner on close (historical; pass empty to clear)"),
+      collaborators: z.array(z.string()).optional().describe("override collaborators on close (historical)"),
+    },
+  },
+  validate: {
+    description: "Validate the backlog (config, items, markers); read-only. Returns { ok, errors, warnings }.",
+    inputSchema: { ...repoRootArg },
+  },
+  regenerate: {
+    description: "Rewrite any stale generated artifact. Returns { changed, nextId, counts }.",
+    inputSchema: { ...repoRootArg },
+  },
+  import: {
+    description: "Import an existing backlog into this repo via a named profile or an inline mapping. Dry-run by default; pass apply:true to write items and regenerate (rolls back on any failure). Returns the import summary (counts, idMap, created, generated).",
+    inputSchema: {
+      ...repoRootArg,
+      source: z.string().describe("path to the source backlog to import; a relative path resolves against the target repo"),
+      profile: z.string().optional().describe("name of a built-in source-mapping profile (alternative to `mapping`)"),
+      mapping: z.record(z.string(), z.any()).optional().describe("inline mapping object describing the source schema (alternative to `profile`)"),
+      apply: z.boolean().optional().describe("write items and regenerate; omit or false for a dry-run (the default)"),
+    },
+  },
+  history: {
+    description: "Read-only git-derived task history (SPEC §8.4). With an id → { id, entries }; omit id → { generated, tasks } keyed by id. Each entry is { id, commit, date, author, subject, reason } newest-first, where reason is the Trellis-Reason commit trailer when present, else the subject. Derived from git (requires a work tree); volatile and non-authoritative — never part of backlog:check, never writes.",
+    inputSchema: {
+      ...repoRootArg,
+      id: z.string().optional().describe("a task id; omit to derive the whole repo"),
+    },
+  },
+};
+
+export function registerTools(server, defaultRoot) {
+  for (const [name, def] of Object.entries(TOOLS)) {
+    server.registerTool(name, { description: def.description, inputSchema: def.inputSchema }, (args = {}) => {
+      try {
+        const root = args.repoRoot ? resolveRepoRoot(args.repoRoot) : defaultRoot;
+        const result = OPS[name](root, args);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], structuredContent: result };
+      } catch (e) {
+        const msg = e instanceof TrellisError ? e.message : `unexpected error: ${e.message}`;
+        return { content: [{ type: "text", text: msg }], isError: true };
+      }
+    });
+  }
+}
+
+// Resources serve the server's default repo (a static uri carries no per-call
+// repoRoot). Only the resources whose backing file exists at boot are advertised,
+// so the list never offers what this repo can't serve (e.g. SPEC.md is absent in
+// onboarded repos until TRL0010). Returns the count registered.
+function registerResources(server, defaultRoot) {
+  const available = new Set(listResources(defaultRoot).filter((r) => r.available).map((r) => r.uri));
+  const byUri = new Map(RESOURCES.map((r) => [r.uri, r]));
+  for (const uri of available) {
+    const r = byUri.get(uri);
+    server.registerResource(
+      r.name,
+      r.uri,
+      { title: r.title, description: r.description, mimeType: r.mimeType },
+      () => {
+        const { uri: u, mimeType, text } = readResource(defaultRoot, r.uri);
+        return { contents: [{ uri: u, mimeType, text }] };
+      },
+    );
+  }
+  return available.size;
+}
+
+// Prompts are bound to the server's repo, exactly like resources — deliberately
+// NOT given a per-call `repoRoot` override. A prompt's text points at the
+// `trellis://…` resources, which resolve to `defaultRoot`; letting a prompt build
+// against a different repo would make those pointers reference the wrong repo's
+// conventions. Per-repo addressing across the whole surface (tools, prompts, AND
+// resources, with root scoping) is TRL0019. A failed build (bad id, missing
+// playbook) throws a TrellisError, which the SDK surfaces as the prompt's get error.
+function registerPrompts(server, defaultRoot) {
+  for (const p of PROMPTS) {
+    const argsSchema = {};
+    for (const a of p.arguments) {
+      argsSchema[a.name] = a.required ? z.string().describe(a.description) : z.string().optional().describe(a.description);
+    }
+    server.registerPrompt(p.name, { title: p.title, description: p.description, argsSchema }, (args = {}) =>
+      buildPrompt(defaultRoot, p.name, args),
+    );
+  }
+}
+
+// True when this module is the process entry point. Resolve argv[1] through
+// realpath first: `import.meta.url` is already symlink-resolved, so a bin-style /
+// symlinked launch (npx, node_modules/.bin) would otherwise miss and the server
+// would silently never boot. Guarded so a plain import (e.g. a test inspecting
+// TOOLS) neither parses argv nor opens the stdio transport.
+function isEntryPoint() {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(argv1)).href;
+  } catch {
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+
+  const server = new McpServer({ name: "trellis", version: SERVER_VERSION });
+  registerTools(server, opts.repo);
+  const resourceCount = registerResources(server, opts.repo);
+  registerPrompts(server, opts.repo);
+
+  await server.connect(new StdioServerTransport());
+  console.error(`trellis-mcp ready (repo: ${opts.repo}; ${Object.keys(OPS).length} tools, ${PROMPTS.length} prompts, ${resourceCount} resources)`);
+}