@taprootio/trellis 0.1.1 → 0.2.0

package/SPEC.md

@@ -1,6 +1,6 @@
 # Trellis Backlog Spec
 
-**Version:** 2.3.0 · **Status:** stable
+**Version:** 2.4.0 · **Status:** stable
 
 Trellis is a tool-agnostic convention for running a software backlog as plain
 files in a git repository. Work items are Markdown files with YAML front-matter;
@@ -62,7 +62,8 @@ configured width — e.g. with prefix `AB` and width 4, `AB0042`.
 
 - The id MUST match the item's filename (`AB0042` ⇄ `AB0042.md`).
 - Ids are assigned monotonically from the `nextId` published in the generated
-  `backlog.json` (§8.2).
+  `backlog.json` (§8.2); `nextId` is `max(highest-existing + 1, nextIdFloor)` when a
+  `nextIdFloor` is configured (§7).
 - An id is permanent and globally unique across all three directories. It MUST
   NOT be reused, even after an item is removed.
 
@@ -216,12 +217,18 @@ custom **effort scale** for display.
 | `priorities` | ordered priority names, highest first |
 | `effort` | canonical values, or the effort-scale object (§6.1) |
 | `tasksDir` | optional backlog-root path, repo-relative; defaults to `trellis/` |
+| `nextIdFloor` | optional; floors the next organically-assigned id — `nextId` = max(floor, highest+1) — so hand-created tasks begin above a reserved band (must fit `idWidth`) |
 
 `tasksDir` locates the task tree and the generated artifacts; omit it to accept
 the `trellis/` default. The config file itself stays at `trellis/backlog.config.json`
 regardless (§2) — its location is **not** governed by `tasksDir`, so the spec
 example above omits the key.
 
+`nextIdFloor` reserves the low id range: when set, the next organically-assigned id
+is `max(nextIdFloor, highest-existing + 1)`, so newly created tasks begin above a
+reserved band (e.g. one populated by an import) while ids within the band remain
+available. Absent, the next id is the historical `highest + 1`.
+
 **Configurable** per repo: everything in the table above, including the backlog
 root via `tasksDir`. **Fixed** by the spec: the `trellis/backlog.config.json`
 config location, the in-root layout (`active/`, `completed/tasks/`, `removed/`,

package/docs/import.md

@@ -54,13 +54,34 @@ failure**, so a refused import leaves the target exactly as it was.
 ### What the importer guarantees
 
 - **The source tree is read-only** — items are copied out, never moved or deleted.
-- **Ids are assigned fresh-sequentially** from the target's next id, so an import
-  is safe even into a non-empty backlog. Colliding source ids are deduped by
-  construction, and every `depends_on` is rewritten through the id map. A
-  dependency on a collided (ambiguous) or unknown source id is a hard error.
+- **Ids are assigned fresh-sequentially** from the target's next id by default (with
+  `--preserve-ids`, sound source ids are kept — see below), so an import is safe even
+  into a non-empty backlog. Colliding source ids are deduped by construction, and every
+  `depends_on` is rewritten through the id map. A dependency on a collided (ambiguous)
+  or unknown source id is a hard error.
 - **A real run leaves the backlog `--check`-green**, or rolls back to the
   pre-import state if anything fails.
 
+### Preserve source ids (`--preserve-ids`)
+
+By default an import assigns fresh ids. With `--preserve-ids`, an item **keeps its own
+id** when it matches the target format exactly (`<idPrefix><idWidth digits>`) and is
+still free — so a same-prefix migration (a repo already Trellis-shaped, or one sharing
+the target's prefix) keeps its identities. Anything that can't keep its id — a
+collision (two sources claim one id: the first keeps it, the rest are reassigned) or a
+mismatched prefix/width — is reassigned into the **gap just above the imported range**,
+and every remap is reported.
+
+A configured **`nextIdFloor`** (SPEC §7) is recorded in `backlog.config.json` so the
+next *organically-created* id begins above the imported band: `nextId` becomes
+`max(floor, highest+1)`. The floor is auto-derived to the next multiple of 1000 above
+the band, or set explicitly with `--id-floor <N>`; the gap between the imported max and
+the floor is deliberate room to resolve collisions.
+
+`depends_on` is rewritten either way. Body **prose** is copied verbatim, so when an id
+changes the importer **warns** for any item whose text still names the old id — fix
+those by hand (the importer never rewrites prose).
+
 ### Add the adoption tracker after import
 
 When onboarding a repo that already has a backlog, import the legacy backlog
@@ -110,10 +131,15 @@ repo and already tracked by git (commit the import first).
 A mapping is a JSON object. A profile is the same object shipped under
 [`profiles/`](../profiles) and addressed by name; an optional top-level
 `description` documents it and is ignored by the engine. The worked examples below
-are the two built-in profiles:
-[`taproot-ai-backlog`](../profiles/taproot-ai-backlog.json) (bold-inline + header
-style) and [`yaml-frontmatter`](../profiles/yaml-frontmatter.json) (full YAML
-front-matter).
+are the three built-in profiles:
+[`taproot-ai-backlog`](../profiles/taproot-ai-backlog.json) (a historical bold-inline +
+header-style reference), [`yaml-frontmatter`](../profiles/yaml-frontmatter.json) (full
+YAML front-matter under flat `active/`, `completed/`, `removed/`), and
+[`trellis`](../profiles/trellis.json) (a **Trellis-shaped** backlog — YAML front-matter
+under `active/`, `completed/tasks/`, `removed/` — for adopting, splitting, or merging
+Trellis repos). Source discovery skips the generator's own `index.md` / `README.md`
+artifacts, so importing a Trellis-shaped tree never picks up a generated index as a
+task.
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/trellis",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Trellis — a tool-agnostic toolkit for file-based backlogs; dogfoods its own conventions.",
   "keywords": [

package/profiles/taproot-ai-backlog.json

@@ -1,5 +1,5 @@
 {
-  "description": "Taproot's planning/ai-backlog: bold-inline (**Field:**) metadata on active items, header-style (Created:/Completed:) closed items, numeric-prefix filenames whose id also leads the H1 (stripped from the title via `title.stripIdPrefix`), P1–P3 priorities, and milestones that mix maturity gates with feature areas. Effort falls back to a `Size:` label; a closed item lacking a date header is dated from the source file's last commit at import time — both are reported in the import summary. The `remap.owner` entries are placeholders — edit them to your target repo's roster handles (team.json). The proven reference profile (TRL0009 imports it).",
+  "description": "Taproot's planning/ai-backlog: bold-inline (**Field:**) metadata on active items, header-style (Created:/Completed:) closed items, numeric-prefix filenames whose id also leads the H1 (stripped from the title via `title.stripIdPrefix`), P1–P3 priorities, and milestones that mix maturity gates with feature areas. Effort falls back to a `Size:` label; a closed item lacking a date header is dated from the source file's last commit at import time — both are reported in the import summary. The `remap.owner` entries are placeholders — edit them to your target repo's roster handles (team.json). A historical bold-inline reference (Taproot's pre-migration ai-backlog; TRL0009 imported it) that documents and exercises the `from: inline` extractor; live Trellis-shaped repos import via the `trellis` profile.",
   "sources": {
     "active": { "dirs": ["active"], "file": "*.md" },
     "completed": { "dirs": ["completed"], "file": "*.md" },

package/profiles/trellis.json

@@ -0,0 +1,23 @@
+{
+  "description": "Import a Trellis-shaped backlog into a Trellis repo: standard YAML front-matter items under active/, completed/tasks/, and removed/ (Trellis's own output layout), with the generator's index.md / README.md artifacts skipped. For adopting, splitting, or merging Trellis backlogs. Carries no remap or defaults — it assumes the target's vocabulary (milestones, priorities, effort) already matches the source's; configure the target's milestones at init, or supply a --mapping override, if they differ.",
+  "sources": {
+    "active": { "dirs": ["active"], "file": "*.md" },
+    "completed": { "dirs": ["completed/tasks"], "file": "*.md" },
+    "removed": { "dirs": ["removed"], "file": "*.md" }
+  },
+  "fields": {
+    "id": { "from": "yaml", "key": "id", "fallback": { "from": "filename" } },
+    "title": { "from": "yaml", "key": "title", "fallback": { "from": "h1" } },
+    "priority": { "from": "yaml", "key": "priority" },
+    "effort": { "from": "yaml", "key": "effort" },
+    "milestone": { "from": "yaml", "key": "milestone" },
+    "summary": { "from": "yaml", "key": "summary" },
+    "owner": { "from": "yaml", "key": "owner" },
+    "collaborators": { "from": "yaml", "key": "collaborators" },
+    "depends_on": { "from": "yaml", "key": "depends_on" },
+    "completed_on": { "from": "yaml", "key": "completed_on" },
+    "removed_on": { "from": "yaml", "key": "removed_on" },
+    "removed_reason": { "from": "yaml", "key": "removed_reason" }
+  },
+  "summary": { "strategy": "firstSentence" }
+}

package/scripts/trellis-import.mjs

@@ -28,13 +28,17 @@ Flags:
   --target <dir>     target Trellis repo (default: ".")
   --apply            write items and regenerate (default: dry-run, write nothing)
   --dry-run          report the plan only (the default)
+  --preserve-ids     keep a source id that fits the target format (else reassign)
+  --id-floor <N>     floor the organic next id (default: auto — next 1000 above the band)
   --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.
+Provide exactly one of --profile or --mapping. The source tree is read-only. By
+default ids are assigned fresh-sequentially from the target's next id (colliding
+source ids deduped). With --preserve-ids, a source id matching the target format is
+kept, collisions/mismatches are reassigned into the gap above the imported band, and a
+nextIdFloor is recorded so organically-created ids begin above it. depends_on is
+rewritten either way. Relative <source> paths resolve against the target repo.
 `;
 
 function parseArgs(argv) {
@@ -48,6 +52,15 @@ function parseArgs(argv) {
       case "--apply": opts.apply = true; break;
       case "--dry-run": opts.dryRun = true; break;
       case "--list-profiles": opts.listProfiles = true; break;
+      case "--preserve-ids": opts.preserveIds = true; break;
+      case "--id-floor": {
+        const next = requiredValue(argv, i, inline, "--id-floor");
+        const num = Number(next.value);
+        if (!Number.isInteger(num) || num < 0) usageError("--id-floor must be a non-negative integer");
+        opts.idFloor = num;
+        i = next.index;
+        break;
+      }
       case "--profile": {
         const next = requiredValue(argv, i, inline, "--profile");
         opts.profile = next.value;
@@ -101,6 +114,11 @@ function report(targetRoot, summary, dryRun) {
     if (pv.effortEstimated) parts.push(`${pv.effortEstimated} effort-estimated`);
     console.log(`  estimated: ${parts.join(", ")}`);
   }
+  if (summary.preserved || (summary.reassigned && summary.reassigned.length)) {
+    console.log(`  ids: ${summary.preserved} preserved, ${summary.reassigned.length} reassigned`);
+    for (const r of summary.reassigned) console.log(`    reassigned ${r.sourceId} → ${r.newId}`);
+  }
+  if (summary.idFloor != null) console.log(`  nextIdFloor: ${summary.idFloor}${dryRun ? " (would set)" : " (recorded in config)"}`);
   if (summary.idMap.length) {
     console.log("  id map:");
     for (const m of summary.idMap) console.log(`    ${m.sourceId} (${m.sourceFile}) → ${m.newId}`);
@@ -136,6 +154,6 @@ 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 });
+const { summary } = applyImport(targetRoot, sourceRoot, mapping, { dryRun, preserveIds: opts.preserveIds, idFloor: opts.idFloor });
 report(targetRoot, summary, dryRun);
 process.exit(summary.errors.length ? 1 : 0);

package/scripts/trellis-init.mjs

@@ -32,6 +32,8 @@ Flags:
   --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)
+  --preserve-ids        with --import, keep a source id that fits the target format (else reassign)
+  --id-floor <N>        with --import, floor the organic next id (default: auto — next 1000 above the band)
   --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
@@ -79,6 +81,13 @@ function parseArgs(argv) {
       case "--import": opts.import = next(); break;
       case "--profile": opts.profile = next(); break;
       case "--mapping": opts.mapping = next(); break;
+      case "--preserve-ids": opts.preserveIds = true; break;
+      case "--id-floor": {
+        const v = Number(next());
+        if (!Number.isInteger(v) || v < 0) { console.error("--id-floor must be a non-negative integer"); process.exit(2); }
+        opts.idFloor = v;
+        break;
+      }
       case "--retire-source": opts.retireSource = next(); break;
       case "--prefix": opts.prefix = next(); break;
       case "--id-width": opts.idWidth = Number(next()); break;
@@ -278,7 +287,7 @@ if (opts.import) {
     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 });
+  const { summary: imp } = applyImport(targetRoot, importSource, mapping, { dryRun: false, preserveIds: opts.preserveIds, idFloor: opts.idFloor });
   reportImport(targetRoot, imp);
   process.exit(imp.errors.length ? 1 : 0);
 }

package/scripts/trellis-mcp.mjs

@@ -116,13 +116,15 @@ export const TOOLS = {
     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).",
+    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; preserved/reassigned/idFloor under preserveIds).",
     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)"),
+      preserveIds: z.boolean().optional().describe("keep a source id that matches the target format exactly (else assign fresh); collisions/mismatches are reassigned into the gap above the imported band"),
+      idFloor: z.number().int().min(0).optional().describe("with preserveIds, the floor for the organic next id recorded in config; default auto — next 1000 above the imported band"),
     },
   },
   history: {

package/src/backlog.mjs

@@ -12,7 +12,7 @@ import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join, relative, isAbsolute } from "node:path";
 
 // Spec version this tool implements (SemVer major.minor); see SPEC.md §9.
-export const SPEC_VERSION = "2.3";
+export const SPEC_VERSION = "2.4";
 
 // The backlog root defaults to `trellis/` and is overridable per repo via the
 // config's `tasksDir` key (SPEC §2/§7). The config file itself lives at a FIXED
@@ -72,6 +72,15 @@ export function loadConfig(repoRoot) {
   const errors = [];
   if (typeof cfg.idPrefix !== "string" || !cfg.idPrefix) errors.push("config: `idPrefix` must be a non-empty string");
   if (!Number.isInteger(cfg.idWidth) || cfg.idWidth < 1) errors.push("config: `idWidth` must be a positive integer");
+  // Optional (TRL0032): floors the *organic* next id (max(floor, max+1)) so freshly
+  // created tasks begin above an imported band; must fit idWidth.
+  if (cfg.nextIdFloor != null) {
+    if (!Number.isInteger(cfg.nextIdFloor) || cfg.nextIdFloor < 0) {
+      errors.push("config: `nextIdFloor` must be a non-negative integer when present");
+    } else if (Number.isInteger(cfg.idWidth) && cfg.idWidth >= 1 && cfg.nextIdFloor >= 10 ** cfg.idWidth) {
+      errors.push(`config: \`nextIdFloor\` (${cfg.nextIdFloor}) must be < 10^idWidth (${10 ** cfg.idWidth}) to fit ${cfg.idWidth} digits`);
+    }
+  }
   if (!Array.isArray(cfg.milestones) || cfg.milestones.length === 0) errors.push("config: `milestones` must be a non-empty array");
   if (!Array.isArray(cfg.priorities) || cfg.priorities.length === 0) errors.push("config: `priorities` must be a non-empty array");
   const effortValues = Array.isArray(cfg.effort) ? cfg.effort : cfg.effort && cfg.effort.values;
@@ -564,7 +573,10 @@ export function nextId(ids, cfg) {
     const n = Number(id.slice(cfg.idPrefix.length));
     if (Number.isFinite(n) && n > max) max = n;
   }
-  return cfg.idPrefix + String(max + 1).padStart(cfg.idWidth, "0");
+  // `nextIdFloor` (TRL0032) reserves the low range for an imported band: the next
+  // organically-created id is max(max+1, floor). Absent floor ⇒ the historical max+1.
+  const floor = Number.isInteger(cfg.nextIdFloor) && cfg.nextIdFloor > 0 ? cfg.nextIdFloor : 0;
+  return cfg.idPrefix + String(Math.max(max + 1, floor)).padStart(cfg.idWidth, "0");
 }
 
 // ------------------------------------------------------------- rendering

package/src/import.mjs

@@ -49,7 +49,6 @@ import {
   resolveEffort,
   findMember,
   isValidHandle,
-  nextId,
   parseFrontMatter,
   paths,
   composeFile,
@@ -187,19 +186,26 @@ function resolveEnum(raw, remap, allowed, label) {
 // First-sentence (or title) synthesis for a missing summary (SPEC §5.1: summary is
 // required and feeds the README). Skips the H1, blank lines, and metadata-shaped
 // lines (bold `**Field:**`, list bullets, short `Key: value` headers) so it lands
-// on real prose, then takes that line's first sentence, single-lined. A heuristic —
-// summary is descriptive, not correctness-critical — that fails safe to the title.
+// on real prose, then flows that first prose paragraph and takes its first sentence,
+// single-lined (a wrapped sentence isn't cut at the newline). A heuristic — summary is
+// descriptive, not correctness-critical — that fails safe to the title.
 function synthSummary(body, title, strategy) {
   if (strategy === "title") return title;
   const isMeta = (l) => l.startsWith("**") || /^[-*+]\s/.test(l) || /^[A-Za-z][\w ()/-]{0,30}:\s+\S/.test(l);
-  for (const line of body.split("\n")) {
-    const l = line.trim();
-    if (!l || l.startsWith("#") || isMeta(l)) continue;
-    const m = l.match(/^(.+?[.!?])(\s|$)/);
-    const s = (m ? m[1] : l).replace(/\s+/g, " ").trim();
-    if (s) return s;
-  }
-  return title;
+  const lines = body.split("\n");
+  let i = 0;
+  while (i < lines.length) { const l = lines[i].trim(); if (l && !l.startsWith("#") && !isMeta(l)) break; i++; }
+  if (i >= lines.length) return title;
+  // Flow the soft-wrapped lines of the first prose paragraph into one string so a
+  // sentence that wraps across lines isn't truncated at the newline; the paragraph
+  // ends at a blank line, a heading, or a metadata-shaped line.
+  const para = [];
+  for (; i < lines.length; i++) { const l = lines[i].trim(); if (!l || l.startsWith("#") || isMeta(l)) break; para.push(l); }
+  const flowed = para.join(" ").replace(/\s+/g, " ").trim();
+  const m = flowed.match(/^(.+?[.!?])(\s|$)/);
+  // First sentence if the paragraph terminates one; else fall back to the first prose
+  // line (unchanged from prior behavior), single-lined.
+  return (m ? m[1] : para[0]).replace(/\s+/g, " ").trim() || title;
 }
 
 // Rebuild a source file's prose as a Trellis body: drop a leading YAML block and a
@@ -215,6 +221,14 @@ function buildBody(raw, newId, title) {
 }
 
 // --------------------------------------------------------------- discovery
+// The source-relative PATHS the Trellis generator owns (SPEC §8): a source that is
+// itself a Trellis backlog carries these alongside its tasks, so never select one as an
+// importable item — a `*.md` glob would otherwise pull them in and fail validation.
+// Matched by PATH, not basename, so a real task that merely happens to be named
+// `active/index.md` still imports.
+const GENERATED_ARTIFACTS = new Set(["README.md", "completed/index.md", "removed/index.md"]);
+const isGeneratedArtifact = (rel) => GENERATED_ARTIFACTS.has(rel.split(/[/\\]/).join("/"));
+
 function listFiles(dir, re) {
   if (!existsSync(dir)) return null; // null = dir absent (a warning), [] = present-but-empty
   return readdirSync(dir)
@@ -235,7 +249,11 @@ function discoverSources(sourceRoot, mapping, warnings) {
       const dir = join(sourceRoot, d);
       const files = listFiles(dir, re);
       if (files === null) { warnings.push(`source dir not found, skipped: ${d}`); continue; }
-      for (const f of files) hits.push({ status, dir, file: join(dir, f), basename: f.replace(/\.[^.]+$/, ""), rel: relative(sourceRoot, join(dir, f)) });
+      for (const f of files) {
+        const rel = relative(sourceRoot, join(dir, f));
+        if (isGeneratedArtifact(rel)) continue; // a Trellis generated artifact at its known path — not a task
+        hits.push({ status, dir, file: join(dir, f), basename: f.replace(/\.[^.]+$/, ""), rel });
+      }
     }
     hits.sort((a, b) => a.rel.localeCompare(b.rel));
     out.push(...hits);
@@ -299,11 +317,11 @@ export function planImport(targetRoot, sourceRoot, mapping, opts = {}) {
   const sources = discoverSources(sourceRoot, mapping, warnings);
   if (!sources.length) warnings.push("no source items matched — check `sources.dirs` and the `file` pattern");
 
-  // Fresh-sequential id allocation from the target's current nextId.
   const fields = mapping.fields;
   const idEx = fields.id || { from: "filename" };
-  let n = Number(nextId(data.ids, cfg).slice(cfg.idPrefix.length));
   const fmtId = (num) => cfg.idPrefix + String(num).padStart(cfg.idWidth, "0");
+  const numOf = (id) => Number(id.slice(cfg.idPrefix.length));
+  const preserve = opts.preserveIds === true;
 
   const errors = [];
   const items = [];
@@ -314,13 +332,44 @@ export function planImport(targetRoot, sourceRoot, mapping, opts = {}) {
   const gitDate = opts.gitDate || ((rel) => gitCommitDate(sourceRoot, rel));
   const bySourceId = new Map(); // source id → [newId, …]; >1 ⇒ a collision (ambiguous for deps)
 
-  for (const src of sources) {
+  // Pre-pass: read each source and extract its source id, then assign a target id.
+  // Preserve mode (opt-in) keeps a source id that matches the target format exactly and
+  // is still free; collisions, format mismatches, and every id in the default mode are
+  // assigned fresh from the gap ABOVE the imported band. Allocation is floor-agnostic —
+  // the configured `nextIdFloor` governs only the organic next id (SPEC §7).
+  const parsed = sources.map((src) => {
     const raw = readFileSync(src.file, "utf8");
     const ctx = { raw, basename: src.basename, yaml: parseFrontMatter(raw, src.rel, []) || {} };
-    const newId = fmtId(n++);
     const sourceId = String(runExtractor(idEx, ctx) ?? src.basename).trim();
-    const at = bySourceId.get(sourceId) || []; at.push(newId); bySourceId.set(sourceId, at);
+    return { src, raw, ctx, sourceId, newId: null };
+  });
+  const exactRe = new RegExp(`^${escRe(cfg.idPrefix)}\\d{${cfg.idWidth}}$`);
+  const used = new Set(data.ids);
+  let maxBand = 0;
+  for (const id of data.ids) { const x = numOf(id); if (Number.isFinite(x) && x > maxBand) maxBand = x; }
+  const reassigned = []; // {sourceId, newId} — items whose id changed under preserve mode
+  if (preserve) {
+    for (const p of parsed) {
+      if (exactRe.test(p.sourceId) && !used.has(p.sourceId)) {
+        p.newId = p.sourceId; used.add(p.sourceId); maxBand = Math.max(maxBand, numOf(p.sourceId));
+      }
+    }
+  }
+  // Non-preserve mode seeds from the organic next id (honoring nextIdFloor, SPEC §7);
+  // preserve mode fills the gap above the imported band (floor-agnostic), so reassigned
+  // collisions/mismatches stay with the band rather than jumping to the floor.
+  const floorSeed = Number.isInteger(cfg.nextIdFloor) && cfg.nextIdFloor > 0 ? cfg.nextIdFloor : 0;
+  let n = preserve ? maxBand + 1 : Math.max(maxBand + 1, floorSeed);
+  for (const p of parsed) {
+    if (p.newId) continue;
+    while (used.has(fmtId(n))) n++;
+    p.newId = fmtId(n); used.add(p.newId); n++;
+    if (preserve) reassigned.push({ sourceId: p.sourceId, newId: p.newId });
+  }
+  for (const p of parsed) { const at = bySourceId.get(p.sourceId) || []; at.push(p.newId); bySourceId.set(p.sourceId, at); }
 
+  for (const p of parsed) {
+    const { src, raw, ctx, sourceId, newId } = p;
     const ierr = (m) => errors.push(`${src.rel}: ${m}`);
     const isActive = src.status === "active";
 
@@ -515,10 +564,29 @@ export function planImport(targetRoot, sourceRoot, mapping, opts = {}) {
     it.fm.depends_on = out;
   }
 
+  // Prose-ref report (preserve mode): depends_on is rewritten through the id map, but
+  // body prose is copied verbatim, so warn when an imported body still names an id that
+  // was reassigned (report-only — never rewrite prose).
+  for (const { sourceId: oldId, newId } of reassigned) {
+    const re = new RegExp(`\\b${escRe(oldId)}\\b`);
+    // Skip the canonical H1 (buildBody re-heads it with the NEW id); only prose refs matter.
+    for (const it of items) if (re.test(it.body.replace(/^#[^\n]*\n?/, ""))) warnings.push(`${it.sourceRel}: body still names "${oldId}" (reassigned to ${newId}) — update the prose`);
+  }
+  // New-id floor (preserve mode): reserve the imported band so the ORGANIC next id
+  // begins above it. Auto-derive to the next multiple of 1000 above the band unless
+  // `--id-floor` overrides; skip with a warning if it wouldn't fit idWidth.
+  let idFloor = null;
+  if (preserve) {
+    const want = opts.idFloor != null ? opts.idFloor : (Math.floor(maxBand / 1000) + 1) * 1000;
+    if (want >= 10 ** cfg.idWidth) warnings.push(`nextIdFloor ${want} does not fit idWidth ${cfg.idWidth} (max ${10 ** cfg.idWidth - 1}) — floor not set`);
+    else { idFloor = want; cfg.nextIdFloor = want; }
+  }
+
   const counts = { active: 0, completed: 0, removed: 0, total: items.length };
   for (const it of items) counts[it.status]++;
   const idMap = items.map((it) => ({ sourceFile: it.sourceRel, sourceId: it.sourceId, newId: it.newId, status: it.status }));
-  return { cfg, root, items, idMap, counts, provenance, warnings, errors };
+  const preserved = preserve ? parsed.filter((p) => p.newId === p.sourceId).length : 0;
+  return { cfg, root, items, idMap, counts, provenance, warnings, errors, preserved, reassigned, idFloor };
 }
 
 // The four generated-artifact paths, repo-relative under the backlog root.
@@ -531,13 +599,16 @@ function generatedRels(root) {
 // the backlog is --check-green. On ANY failure, roll back (remove the new items,
 // restore the artifacts) so a rejected import leaves the target exactly as it was.
 // `dryRun` returns the plan without writing. The source tree is never written.
-export function applyImport(targetRoot, sourceRoot, mapping, { dryRun = false, gitDate } = {}) {
-  const summary = { imported: [], created: [], generated: [], idMap: [], counts: null, provenance: null, root: null, warnings: [], errors: [] };
-  const plan = planImport(targetRoot, sourceRoot, mapping, { gitDate });
+export function applyImport(targetRoot, sourceRoot, mapping, { dryRun = false, gitDate, preserveIds = false, idFloor } = {}) {
+  const summary = { imported: [], created: [], generated: [], idMap: [], counts: null, provenance: null, root: null, preserved: 0, reassigned: [], idFloor: null, warnings: [], errors: [] };
+  const plan = planImport(targetRoot, sourceRoot, mapping, { gitDate, preserveIds, idFloor });
   summary.idMap = plan.idMap;
   summary.counts = plan.counts;
   summary.provenance = plan.provenance;
   summary.root = plan.root;
+  summary.preserved = plan.preserved;
+  summary.reassigned = plan.reassigned;
+  summary.idFloor = plan.idFloor;
   summary.warnings = plan.warnings;
   if (plan.errors.length) { summary.errors.push(...plan.errors); return { summary }; }
 
@@ -551,17 +622,26 @@ export function applyImport(targetRoot, sourceRoot, mapping, { dryRun = false, g
   const p = paths(targetRoot, plan.cfg);
   const artifacts = [p.readme, p.completedIndex, p.removedIndex, p.backlogJson];
   const priorArtifacts = artifacts.map((path) => ({ path, before: existsSync(path) ? readFileSync(path, "utf8") : null }));
+  // Persisting nextIdFloor mutates the config; snapshot it for rollback.
+  const priorConfig = plan.idFloor != null ? readFileSync(p.config, "utf8") : null;
   const written = [];
   try {
     for (const it of plan.items) {
       const abs = join(targetRoot, it.targetRel);
-      // Fresh ids never collide with existing items; a pre-existing target file
-      // would mean a corrupt plan, so refuse rather than clobber.
+      // A preserved id could match an existing item; a pre-existing target file means a
+      // corrupt plan (preservation checks the target's ids first), so refuse to clobber.
       if (existsSync(abs)) throw new Error(`refusing to overwrite existing ${it.targetRel}`);
       mkdirSync(dirname(abs), { recursive: true });
       writeFileSync(abs, composeFile(it.fm, it.body));
       written.push(abs);
     }
+    // Record the new-id floor before regenerating so backlog.json's nextId (and every
+    // future organic id) begins above the imported band; plan.cfg already carries it.
+    if (plan.idFloor != null) {
+      const obj = JSON.parse(priorConfig);
+      obj.nextIdFloor = plan.idFloor;
+      writeFileSync(p.config, JSON.stringify(obj, null, 2) + "\n");
+    }
     const data = readBacklog(targetRoot, plan.cfg);
     if (data.errors.length) throw new Error(`imported backlog is invalid: ${data.errors.join("; ")}`);
     const { files, errors } = generateArtifacts(targetRoot, plan.cfg, data);
@@ -577,6 +657,7 @@ export function applyImport(targetRoot, sourceRoot, mapping, { dryRun = false, g
     for (const a of priorArtifacts) {
       try { a.before === null ? rmSync(a.path, { force: true }) : writeFileSync(a.path, a.before); } catch { /* best-effort */ }
     }
+    if (priorConfig != null) { try { writeFileSync(p.config, priorConfig); } catch { /* best-effort */ } }
     summary.errors.push(e.message);
     return { summary };
   }

package/src/init.mjs

@@ -224,12 +224,14 @@ function configContent(o) {
   ) + "\n";
 }
 
-// The team roster stub (SPEC §7.2): one example active member showing the shape
-// (`handle`/`name`/optional `email`/`status`). Authored, not generated; left for the
-// repo to edit. An unused roster keeps the scaffold --check-green (no task owns it).
+// The team roster stub (SPEC §7.2): one INACTIVE placeholder member showing the shape
+// (`handle`/`name`/optional `email`/`status`) without reading like a real teammate —
+// an inactive member can't own active items, so it's clearly a stub to replace or
+// delete rather than live config. Authored, not generated; left for the repo to edit.
+// An unused roster keeps the scaffold --check-green (no task owns it).
 function teamContent() {
   return JSON.stringify(
-    { members: [{ handle: "example", name: "Example Member", email: "example@example.com", status: "active" }] },
+    { members: [{ handle: "example", name: "Example teammate (replace or delete)", email: "you@example.com", status: "inactive" }] },
     null,
     2,
   ) + "\n";

package/src/mcp.mjs

@@ -407,8 +407,9 @@ export function importOp(repoRoot, args = {}) {
   // lives in the repo being onboarded); an absolute path is used as-is.
   const src = args.source.trim();
   const source = isAbsolute(src) ? src : join(repoRoot, src);
+  if (args.idFloor != null && (!Number.isInteger(args.idFloor) || args.idFloor < 0)) throw new TrellisError("`idFloor` must be a non-negative integer");
   const dryRun = !args.apply;
-  const { summary } = applyImport(repoRoot, source, mapping, { dryRun });
+  const { summary } = applyImport(repoRoot, source, mapping, { dryRun, preserveIds: args.preserveIds === true, idFloor: args.idFloor });
   if (summary.errors.length) throw new TrellisError(summary.errors.join("; "), "import_failed");
   return { ...summary, dryRun };
 }