@taprootio/trellis 0.1.0

package/docs/import.md

@@ -0,0 +1,273 @@
+# Importing an existing backlog
+
+Trellis can import a backlog that already exists on a *foreign* schema — a folder
+of Markdown files with their own front-matter, bold-inline metadata, or header
+lines — and convert it into conformant Trellis items. The conversion is driven by
+a declarative **mapping**; a reusable, named mapping is a **profile**.
+
+This guide has two parts: [onboarding a repo that already has a
+backlog](#onboard-a-repo-that-already-has-a-backlog), and the [mapping/profile
+schema reference](#the-mapping-schema).
+
+## Onboard a repo that already has a backlog
+
+### One command: `init --import`
+
+If the repo is not yet a Trellis backlog, scaffold and import in one step:
+
+```
+npx @taprootio/trellis init --import planning/old-backlog --profile yaml-frontmatter
+```
+
+This scaffolds the Trellis layout (config, `trellis/` tree, generated indexes, CI
+check, AGENTS block, playbooks), then imports the backlog at the given path. A
+relative `<path>` resolves against the repo being onboarded. Add `--dry-run` to
+preview the scaffold without writing; to preview the import plan itself (counts,
+id map, warnings), run `trellis import --dry-run` once the repo is initialized.
+
+Use `--mapping <file.json>` instead of `--profile <name>` to supply your own
+mapping. Provide exactly one of the two.
+
+### Two steps: `init`, then `import`
+
+If the repo is already initialized (or you want to import again later), run the
+importer on its own. It is **dry-run by default** — it prints the plan, the id
+map, and per-field warnings without writing — so you can review before committing
+to a write:
+
+```
+npx @taprootio/trellis import planning/old-backlog --profile yaml-frontmatter            # preview
+npx @taprootio/trellis import planning/old-backlog --profile yaml-frontmatter --apply    # write
+```
+
+`trellis import --list-profiles` lists the built-in profiles. The target defaults
+to `.`; pass `--target <dir>` to import into another repo.
+
+### Over MCP
+
+The same operation is exposed as the MCP `import` tool, so an MCP-aware client can
+onboard a backlog without a shell. It takes `source`, exactly one of `profile` or
+`mapping` (an inline mapping object), and an optional `apply` flag. Like the CLI it
+is **dry-run unless `apply: true`**, and it regenerates and **rolls back on any
+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.
+- **A real run leaves the backlog `--check`-green**, or rolls back to the
+  pre-import state if anything fails.
+
+### Add the adoption tracker after import
+
+When onboarding a repo that already has a backlog, import the legacy backlog
+before creating any new Trellis task for the adoption work itself. Trellis assigns
+imported ids from the target's current `nextId`, so an early "Adopt Trellis" item
+would consume the first id and shift every imported task up by one. Import first,
+review the id map, then create and work the adoption tracker at the next id.
+
+### After adopting: reconcile guidance, then retire the source
+
+Importing copies items into Trellis but leaves two things for you to finish the
+adoption — both deliberately **report-first**, so nothing author-written is lost.
+
+**Reconcile stale guidance.** Every `trellis init` run scans a small set of root
+guidance files (`AGENTS.md`, `AI_GUIDELINES.md`, `CLAUDE.md`) for pre-Trellis backlog
+instructions — an "AI Backlog" section, a reference to the old backlog path — and
+prints them as a `reconcile` checklist:
+
+```
+  reconcile (1) — pre-Trellis backlog guidance to rewrite by hand (init left these untouched):
+    - AI_GUIDELINES.md: has a "AI Backlog" section that looks like pre-Trellis backlog guidance — rewrite it to point at trellis/
+```
+
+`init` **only ever reports** here — it appends its own marked block and never edits or
+deletes your prose. The surgical rewrite (point the section at `trellis/`, drop the old
+field names) is the onboarding agent's job; the checklist just says where to look. The
+scan skips Trellis's own appended block and any section that already points at the new
+root, so it won't flag guidance you've already migrated.
+
+**Retire the old source tree.** The importer never touches the source, so after you have
+imported, **reviewed, and committed** the result, the legacy tree is still on disk. Once
+you're satisfied, retire it history-preservingly:
+
+```
+npx @taprootio/trellis init --retire-source planning/old-backlog --dry-run   # list what would go
+npx @taprootio/trellis init --retire-source planning/old-backlog             # stage the removal
+```
+
+This runs `git rm -r` on the path — git keeps the files' history — and **stages** the
+deletion for you to review (`git status`) and commit. It does not scaffold, import, or
+commit, and it **cannot be combined with `--import`**: retirement is a separate, later
+step so the source is intact if an import ever rolls back. The path must be inside the
+repo and already tracked by git (commit the import first).
+
+## The mapping schema
+
+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).
+
+```json
+{
+  "description": "optional, human-only",
+  "sources": {
+    "active":    { "dirs": ["active"],    "file": "*.md" },
+    "completed": { "dirs": ["completed"], "file": "*.md" },
+    "removed":   { "dirs": ["removed"],   "file": "*.md" }
+  },
+  "fields": {
+    "title":      { "from": "h1" },
+    "priority":   { "from": "inline", "label": "Priority" },
+    "milestone":  { "from": "inline", "label": "Milestone" },
+    "effort":     { "from": "inline", "label": "Effort", "fallback": { "from": "inline", "label": "Size" } },
+    "owner":      { "from": "inline", "label": "Owner" }
+  },
+  "remap":    { "priority": { "P1": "High" }, "milestone": { "Pre-Launch": "Alpha" }, "effort": { "S": 1, "M": 3, "L": 8 }, "owner": { "Jane Doe": "jane" } },
+  "defaults": { "milestone": "Alpha", "priority": "Low", "effort": 1 },
+  "summary":  { "strategy": "firstSentence" }
+}
+```
+
+### `sources` (required)
+
+One entry per source **status** — at least one of `active`, `completed`,
+`removed`. Each has `dirs` (a non-empty list of source-relative directories; no
+absolute paths or `..` segments) and an optional `file` glob (default `*.md`,
+`*`-only). An item's status is determined by **which source directory it is in** —
+see [the directory caveat](#caveats).
+
+### `fields` (required)
+
+How to locate each field on a source item. Recognized fields: `id`, `title`,
+`priority`, `effort`, `milestone`, `summary`, `depends_on`, `owner`,
+`collaborators`, `completed_on`, `removed_on`, `removed_reason`. Each maps to an
+**extractor**:
+
+| extractor | reads |
+| --- | --- |
+| `{ "from": "yaml", "key": "k" }` | front-matter key `k` |
+| `{ "from": "inline", "label": "L" }` | a bold metadata line `**L:** value` |
+| `{ "from": "header", "label": "L" }` | a header line `L: value` |
+| `{ "from": "h1" }` | the first `# Heading` |
+| `{ "from": "filename", "pattern": "^(\\d+)" }` | the filename (no extension); `pattern`'s first capture group if given |
+| `{ "from": "const", "value": "v" }` | the literal `v` |
+
+Any extractor may carry a `"fallback": { … }` extractor, tried when the primary
+yields nothing (e.g. `completed_on` from a `Completed:` line, falling back to
+`Created:`). Defaults: `id` → filename, `title` → `h1`. `summary` is
+[synthesized](#how-fields-are-resolved) when absent. `owner` is a single roster
+handle; `collaborators` is a list (an inline `[a, b]`, a `-` block, or a
+comma/semicolon-separated value), resolved the same way as `owner`.
+
+The `title` field accepts one extra option, `"stripIdPrefix": true`: when the
+resolved title begins with the item's **own** source id followed by a separator —
+whitespace, optionally around a single `. : - – —` — that leading token is dropped,
+so a foreign `# 001 README Truth Pass` (source id `001`) imports as `README Truth
+Pass`. The cleaned title also heads the rebuilt body. It is matched **exactly**
+against the source id and only when a real whitespace break follows, so id `04` never
+bites into a `047 …` title, an unbroken `001README` is left intact, and a genuinely
+number-leading title (`2024 Roadmap` under a different id) is untouched. Off by
+default; the [`taproot-ai-backlog`](../profiles/taproot-ai-backlog.json) profile
+(numeric-prefix filenames) sets it on.
+
+### `remap` (optional)
+
+Resolve foreign values to the target's configured vocabulary, by field
+(`priority`, `milestone`, `effort`, `owner`). Keys are matched case-insensitively. A
+milestone that mixes maturity gates with feature areas (which the spec disallows — see
+SPEC §7.1) **must** be remapped to a single maturity axis; an unmapped value on an
+active item is a hard error, never a silent guess. `remap.owner` maps a source assignee
+(e.g. a display name or legacy username) to a roster `handle` (SPEC §7.2) and applies
+to **both** `owner` and `collaborators` — they share one identity space. `remap.effort`
+maps a foreign size token (`S`/`M`/`L`, or an off-scale number) to a canonical effort
+value (SPEC §6); paired with an `effort` extractor that falls back to a `Size:` label,
+that is how a legacy `**Size:**` field becomes Trellis effort.
+
+### `defaults` (optional)
+
+Fill a field when the source has no value for it — chiefly the historical
+descriptive metadata (`milestone`, `priority`, `effort`, and `removed_reason`)
+that header-style legacy closed items lack but the schema still requires on
+completed/removed items (SPEC §5.1). A defaulted value is treated like an
+extracted one. `defaults.owner` is the fallback owner for **active** items whose
+source owner doesn't resolve to an active roster member (closed items keep their
+historical owner instead). `defaults.completed_on` / `defaults.removed_on` are an
+optional **floor** for a close date with no header that git can't recover (see
+[Import-time git and provenance](#import-time-git-and-provenance)); a defaulted close
+date is flagged in the import summary.
+
+### `summary` (optional)
+
+`{ "strategy": "firstSentence" }` (default) synthesizes a missing summary from the
+first prose sentence, skipping headings and metadata-shaped lines; `"title"` uses
+the title.
+
+### How fields are resolved
+
+- **Active items** are validated in full against the target config: priority,
+  milestone, and effort must resolve, or the import is refused with an actionable
+  error.
+- **Closed items** (completed/removed) keep their enum values as a *historical*
+  snapshot — those are not re-validated against the current config (SPEC §5.1,
+  §8.3) — but the metadata must be **present** (from the source or `defaults`).
+- **Close dates** (`completed_on`/`removed_on`) resolve through a fallback chain when
+  the field is **absent**: the date header/field → the source file's **last git commit
+  date** (read at import time from the *source* repo) → an optional `defaults.<field>`
+  floor → a hard error. A field that is **present but malformed** (e.g. an impossible
+  `2024-02-31`) is refused outright — never papered over by git or a floor. A
+  git-derived or defaulted date is flagged, never silently passed as authored — see
+  [Import-time git and provenance](#import-time-git-and-provenance).
+- **Owners and collaborators** resolve against the target's `team.json` roster
+  (SPEC §7.2). On an **active** item the resolution chain is: `remap.owner` (or a
+  direct case-insensitive handle match) → `defaults.owner` → **unassigned, with a
+  warning** — an owner that resolves to no active member is dropped, never invented.
+  An unresolved collaborator is likewise dropped with a warning. On a **closed**
+  item the value is historical: a member who has since gone inactive keeps their
+  canonical handle; a handle absent from the roster is kept (after `remap.owner`) only
+  if it is a valid handle — a former member — and otherwise dropped with a warning, so
+  a non-handle value can never corrupt the stored item. Carrying owners therefore requires the target
+  repo to have a `team.json` (with no roster, every owner drops or carries as
+  above); curating the roster can stay a manual post-import step.
+
+### Import-time git and provenance
+
+Some legacy backlogs don't record everything the schema needs — most commonly a
+closed item with no date header, or an item whose effort lives under a `Size:` label
+or isn't recorded at all. The importer fills these as faithfully as it can and
+**reports what it inferred**, so nothing passes as authored history:
+
+- **Git is read at import time only.** When a close date has no header, the importer
+  reads the source file's last commit date from the *source* repo's git. This is the
+  one-time importer's privilege; the deterministic generator and `--check` never read
+  git (SPEC §8.4), so the gate stays reproducible.
+- **It degrades, never fails on git alone.** Missing git, a non-repo or shallow
+  source, or an uncommitted file all make the lookup return nothing — the chain then
+  falls to a `defaults.<field>` floor if configured, and only errors if neither git
+  nor a floor yields a date. The importer never invents a close date out of nothing.
+- **Inferred values are flagged.** A git-derived or floor-defaulted close date, and a
+  **closed** item whose effort fell back to `defaults.effort` (no `Effort:`/`Size:`
+  signal), each emit a per-item warning and increment a count in the import summary
+  (`N git-dated, M effort-estimated`). Provenance lives in that report — reviewed
+  before `--apply` — not in a new front-matter field: volatile git-derived data stays
+  out of the gated item files (SPEC §8.4). A higher-quality per-item effort estimate
+  is a job for the onboarding agent, not the dependency-free importer.
+
+### Caveats
+
+- **Remap targets are the *target* repo's vocabulary.** The built-in profiles map
+  to the default Trellis vocabulary (`Alpha → Beta → v1 → Future`, `High`/`Medium`/
+  `Low`, Fibonacci effort). If your target repo configures a different vocabulary,
+  edit the profile's `remap` (and `defaults`) to match it.
+- **Status comes from the source *directory*, not a per-item field.** The engine
+  routes items by which `sources.{active,completed,removed}.dirs` directory they
+  live in. A source that keeps everything in one folder with a `Status:` field is
+  not directly importable today; split it into per-status directories first, or
+  point each status at the directory that holds those items.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@taprootio/trellis",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Trellis — a tool-agnostic toolkit for file-based backlogs; dogfoods its own conventions.",
+  "keywords": [
+    "backlog",
+    "tasks",
+    "task-management",
+    "project-management",
+    "cli",
+    "mcp",
+    "file-based",
+    "git",
+    "trellis"
+  ],
+  "homepage": "https://github.com/taprootio/trellis#readme",
+  "bugs": "https://github.com/taprootio/trellis/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taprootio/trellis.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "trellis": "./scripts/trellis.mjs",
+    "trellis-mcp": "./scripts/trellis-mcp.mjs"
+  },
+  "files": [
+    "scripts/",
+    "src/",
+    "profiles/",
+    "templates/",
+    "docs/import.md",
+    "README.md",
+    "SPEC.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "trellis": "node scripts/trellis.mjs",
+    "backlog:readme": "node scripts/backlog-readme.mjs",
+    "backlog:check": "node scripts/backlog-readme.mjs --check",
+    "trellis:init": "node scripts/trellis-init.mjs",
+    "trellis:import": "node scripts/trellis-import.mjs",
+    "trellis:history": "node scripts/trellis-history.mjs",
+    "pr-title:lint": "node scripts/pr-title-lint.mjs",
+    "trellis:mcp": "node scripts/trellis-mcp.mjs",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}

package/profiles/taproot-ai-backlog.json

@@ -0,0 +1,28 @@
+{
+  "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).",
+  "sources": {
+    "active": { "dirs": ["active"], "file": "*.md" },
+    "completed": { "dirs": ["completed"], "file": "*.md" },
+    "removed": { "dirs": ["removed"], "file": "*.md" }
+  },
+  "fields": {
+    "id": { "from": "filename", "pattern": "^(\\d+)" },
+    "title": { "from": "h1", "stripIdPrefix": true },
+    "priority": { "from": "inline", "label": "Priority" },
+    "effort": { "from": "inline", "label": "Effort", "fallback": { "from": "inline", "label": "Size" } },
+    "milestone": { "from": "inline", "label": "Milestone" },
+    "owner": { "from": "inline", "label": "Owner" },
+    "collaborators": { "from": "inline", "label": "Collaborators" },
+    "depends_on": { "from": "inline", "label": "Depends on" },
+    "completed_on": { "from": "header", "label": "Completed", "fallback": { "from": "header", "label": "Created" } },
+    "removed_on": { "from": "header", "label": "Removed" },
+    "removed_reason": { "from": "header", "label": "Reason" }
+  },
+  "remap": {
+    "priority": { "P1": "High", "P2": "Medium", "P3": "Low" },
+    "milestone": { "Pre-Launch": "Alpha", "MCP Servers": "Beta", "Post-Launch": "v1", "Back-Burner": "Future", "Legal Research": "Future" },
+    "owner": { "Jane Doe": "jane", "John Smith": "john" }
+  },
+  "defaults": { "milestone": "Alpha", "priority": "Low", "effort": 1 },
+  "summary": { "strategy": "firstSentence" }
+}

package/profiles/yaml-frontmatter.json

@@ -0,0 +1,23 @@
+{
+  "description": "Generic backlog where each item carries complete YAML front-matter (title, priority, milestone, effort, summary, depends_on, dates) under active/, completed/, and removed/ directories, in standard Trellis vocabulary. Exercises the `yaml` extractor with no remap or defaults — the differently-shaped second source that keeps the profile schema from over-fitting Taproot.",
+  "sources": {
+    "active": { "dirs": ["active"], "file": "*.md" },
+    "completed": { "dirs": ["completed"], "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/backlog-readme.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Trellis backlog CLI — a thin wrapper over the reusable core in src/backlog.mjs.
+//
+//   node scripts/backlog-readme.mjs                    # rewrite generated files in cwd
+//   node scripts/backlog-readme.mjs --check             # fail if any generated file is stale
+//   node scripts/backlog-readme.mjs --target <repo>     # operate on another repo
+//
+// Logic lives in src/backlog.mjs so the MCP server can share it. This stays
+// dependency-free on purpose (see SPEC.md §5 / the front-matter parser).
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { relative } from "node:path";
+import { loadConfig, readBacklog, generateArtifacts } from "../src/backlog.mjs";
+import { optionToken, requiredValue, resolveRepoRoot, showHelp, usageError } from "../src/cli.mjs";
+
+const HELP = `trellis generate/check — validate and regenerate Trellis artifacts
+
+Usage:
+  trellis generate [--target <repo>]
+  trellis check [--target <repo>]
+  node scripts/backlog-readme.mjs [--check] [--target <repo>]
+
+Flags:
+  --target <repo>  repo root to operate on (default: cwd)
+  --repo <repo>    alias for --target
+  --check          validate only; fail if generated files are stale
+  -h, --help       show this help
+`;
+
+function parseArgs(argv) {
+  const opts = { target: process.cwd(), check: false };
+  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 "--check": opts.check = true; 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}`);
+        usageError(`Unexpected argument: ${a}`);
+    }
+  }
+  return opts;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.help) showHelp(HELP);
+
+const repoRoot = resolveRepoRoot(opts.target);
+const isCheck = opts.check;
+const rel = (p) => relative(repoRoot, p);
+
+function die(errors) {
+  console.error("Backlog validation failed:\n" + errors.map((e) => "  - " + e).join("\n"));
+  process.exit(1);
+}
+
+const { cfg, warnings, errors: cfgErrors } = loadConfig(repoRoot);
+for (const w of warnings) console.warn(`warning: ${w}`);
+if (cfgErrors.length) die(cfgErrors);
+
+const data = readBacklog(repoRoot, cfg);
+if (data.errors.length) die(data.errors);
+
+const { files, nextId, errors } = generateArtifacts(repoRoot, cfg, data);
+if (errors.length) die(errors);
+
+if (isCheck) {
+  const stale = files.filter((f) => (existsSync(f.path) ? readFileSync(f.path, "utf8") : "") !== f.content);
+  if (stale.length) {
+    for (const f of stale) console.error(`${rel(f.path)} is stale - run: npx @taprootio/trellis generate`);
+    process.exit(1);
+  }
+  console.log("Backlog check OK.");
+} else {
+  for (const f of files) writeFileSync(f.path, f.content);
+  console.log(`Backlog OK: ${data.active.length} active, ${data.completed.length} completed, ${data.removed.length} removed. Next id: ${nextId}`);
+}

package/scripts/pr-title-lint.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// PR-title lint CLI — a thin wrapper over src/pr-title.mjs, run by the
+// pr-title workflow on every pull_request.
+//
+//   PR_TITLE="TRL0016: add the lint" node scripts/pr-title-lint.mjs
+//   PR_TITLE="DEMO0001: add the lint" trellis pr-title --repo <target>
+//
+// Reads the title from $PR_TITLE (set from the pull_request event title) and the
+// id vocabulary from the target repo's backlog.config.json, then exits non-zero on any
+// violation. Logic lives in src/pr-title.mjs so it stays dependency-free and
+// `node --test`-able.
+
+import { loadConfig } from "../src/backlog.mjs";
+import { optionToken, requiredValue, resolveRepoRoot, showHelp, usageError } from "../src/cli.mjs";
+import { lintPrTitle } from "../src/pr-title.mjs";
+
+const HELP = `trellis pr-title — lint a pull request title
+
+Usage:
+  PR_TITLE="TASK0001: concise title" trellis pr-title [--repo <target>]
+
+Flags:
+  --repo <target>    repo root whose Trellis id vocabulary should be used (default: cwd)
+  --target <target>  alias for --repo
+  -h, --help         show this help
+`;
+
+function parseArgs(argv) {
+  const opts = { repo: process.cwd() };
+  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 "--repo": case "--target": {
+        const next = requiredValue(argv, i, inline, key);
+        opts.repo = next.value;
+        i = next.index;
+        break;
+      }
+      default:
+        if (a.startsWith("-")) usageError(`Unknown flag: ${a}`);
+        usageError(`Unexpected argument: ${a}`);
+    }
+  }
+  return opts;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.help) showHelp(HELP);
+
+const repoRoot = resolveRepoRoot(opts.repo);
+
+const { cfg, warnings, errors: cfgErrors } = loadConfig(repoRoot);
+for (const w of warnings) console.log(`warning: ${w}`);
+if (cfgErrors.length) {
+  console.error("Cannot lint the PR title:\n" + cfgErrors.map((e) => "  - " + e).join("\n"));
+  process.exit(1);
+}
+
+const title = process.env.PR_TITLE ?? "";
+const { ok, errors } = lintPrTitle(title, cfg);
+if (!ok) {
+  console.error(`PR title does not conform to the standard:\n  title: ${JSON.stringify(title)}`);
+  for (const e of errors) console.error("  - " + e);
+  console.error("\nSee .github/pull_request_template.md / trellis/playbooks/pr-draft.md.");
+  process.exit(1);
+}
+console.log(`PR title OK: ${title}`);

package/scripts/trellis-history.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// Trellis history CLI — a thin wrapper over the deriver in src/history.mjs.
+//
+//   node scripts/trellis-history.mjs [<id>] [--repo <path>] [--json] [--write [--out <file>]]
+//
+// Reconstructs per-task change history from git (SPEC §8.4 — a derived, NON-gated
+// report). With an <id>, shows that task's history; without, the whole repo. `--write`
+// materializes history.json for a static viewer / site build. This report is volatile
+// (commit times, authors) and is deliberately NOT part of `backlog:check` and NOT
+// produced by `backlog:readme` — git, not Trellis, is the authoritative record. Logic
+// lives in src/history.mjs so the MCP `history` tool shares it; this stays
+// dependency-free.
+
+import { loadConfig } from "../src/backlog.mjs";
+import { optionToken, requiredValue, resolveRepoRoot, showHelp, usageError } from "../src/cli.mjs";
+import { deriveTaskHistory, deriveAllHistory, materializeHistory, HistoryError } from "../src/history.mjs";
+
+const HELP = `trellis history — git-derived per-task history
+
+Usage:
+  trellis history [<id>] [flags]
+
+Flags:
+  --repo <path>   repo root to derive from (default: cwd)
+  --json          emit structured JSON instead of a human summary
+  --write         materialize history.json (whole repo) for a static viewer / CI build
+  --out <file>    output path for --write (default: <tasksDir>/history.json)
+  -h, --help      show this help
+
+With <id>: that task's entries (newest-first). Without: the whole repo. Entries are
+{ id, commit, date, author, subject, reason }; reason is the Trellis-Reason commit
+trailer when present, else the subject. This report is NOT gated by backlog:check.
+`;
+
+function parseArgs(argv) {
+  const opts = {};
+  let id;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const { key, inline } = optionToken(a);
+    // A value-taking flag must get a real value: not missing, not empty, and (for the
+    // space-separated form) not the next flag — so `--out --json` errors instead of
+    // silently swallowing `--json` as the path. Use `--out=<value>` to force an
+    // unusual value that begins with `-`.
+    switch (key) {
+      case "-h": case "--help": opts.help = true; break;
+      case "--json": opts.json = true; break;
+      case "--write": opts.write = true; break;
+      case "--repo": case "--target": {
+        const next = requiredValue(argv, i, inline, key);
+        opts.repo = next.value;
+        i = next.index;
+        break;
+      }
+      case "--out": {
+        const next = requiredValue(argv, i, inline, "--out");
+        opts.out = next.value;
+        i = next.index;
+        break;
+      }
+      default:
+        if (a.startsWith("-")) usageError(`Unknown flag: ${a}`);
+        if (id === undefined) id = a;
+        else usageError(`Unexpected extra argument: ${a}`);
+    }
+  }
+  return { id, opts };
+}
+
+const shortSha = (s) => s.slice(0, 9);
+const shortDate = (s) => s.slice(0, 10);
+
+function printTaskHuman(id, entries) {
+  if (!entries.length) { console.log(`${id}: no recorded history (not committed yet).`); return; }
+  console.log(`${id} — ${entries.length} entr${entries.length === 1 ? "y" : "ies"} (newest first):`);
+  for (const e of entries) {
+    console.log(`  ${shortDate(e.date)}  ${shortSha(e.commit)}  ${e.author}`);
+    console.log(`      ${e.subject}`);
+    if (e.reason !== e.subject) console.log(`      reason: ${e.reason}`);
+  }
+}
+
+function printAllHuman(tasks) {
+  const ids = Object.keys(tasks);
+  const entryCount = ids.reduce((n, k) => n + tasks[k].length, 0);
+  console.log(`History — ${ids.length} task${ids.length === 1 ? "" : "s"}, ${entryCount} entr${entryCount === 1 ? "y" : "ies"}:`);
+  for (const id of ids) {
+    const es = tasks[id];
+    if (!es.length) { console.log(`  ${id}  (no recorded history)`); continue; }
+    const last = es[0];
+    console.log(`  ${id}  ${es.length} entr${es.length === 1 ? "y" : "ies"}  last: ${shortDate(last.date)} ${last.author} — ${last.subject}`);
+  }
+}
+
+const { id, opts } = parseArgs(process.argv.slice(2));
+if (opts.help) showHelp(HELP);
+
+const repoRoot = resolveRepoRoot(opts.repo);
+const { cfg, warnings, errors } = loadConfig(repoRoot);
+for (const w of warnings) console.warn(`warning: ${w}`);
+if (errors.length) { console.error(`error: config: ${errors.join("; ")}`); process.exit(2); }
+
+try {
+  if (opts.write) {
+    // Materializing is whole-repo by nature (keyed by every id); an id would imply a
+    // partial file, so refuse it rather than silently ignore.
+    if (id !== undefined) { console.error("error: --write materializes the whole repo; omit the <id>"); process.exit(2); }
+    const res = materializeHistory(repoRoot, cfg, { out: opts.out });
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+    } else {
+      console.log(`Wrote ${res.path} — ${res.taskCount} task${res.taskCount === 1 ? "" : "s"}, ${res.entryCount} entr${res.entryCount === 1 ? "y" : "ies"} (${res.bytes} bytes).`);
+      console.log("This is a regenerable, non-gated cache (git is authoritative); it is gitignored — regenerate at build time.");
+    }
+  } else if (id !== undefined) {
+    const { entries } = deriveTaskHistory(repoRoot, cfg, id);
+    if (opts.json) process.stdout.write(JSON.stringify({ id, entries }, null, 2) + "\n");
+    else printTaskHuman(id, entries);
+  } else {
+    const all = deriveAllHistory(repoRoot, cfg);
+    if (opts.json) process.stdout.write(JSON.stringify(all, null, 2) + "\n");
+    else printAllHuman(all.tasks);
+  }
+} catch (e) {
+  if (e instanceof HistoryError) { console.error(`error: ${e.message}`); process.exit(1); }
+  throw e;
+}