codetrellis 0.0.0-stage → 0.3.0

package/src/backend/services/plan-templates.js

@@ -0,0 +1,1164 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var plan_templates_exports = {};
+__export(plan_templates_exports, {
+  PLAN_TEMPLATES: () => PLAN_TEMPLATES,
+  getTemplate: () => getTemplate,
+  listTemplates: () => listTemplates,
+  substitutePlaceholders: () => substitutePlaceholders
+});
+module.exports = __toCommonJS(plan_templates_exports);
+var import_node_fs = __toESM(require("node:fs"));
+var import_confined_fs = require("./confined-fs");
+var import_node_path = __toESM(require("node:path"));
+var import_node_os = __toESM(require("node:os"));
+var import_yaml = require("yaml");
+const MASS_REFACTOR_OVERVIEW = `# Mass refactor \u2014 executive overview
+
+This plan is a **deep-mode** plan (Phase 12 \xA7A): instead of a flat
+list of tasks, it's broken into six phases that run mostly in
+sequence. Each phase has its own scope, prerequisites, git
+checkpoint, and acceptance criteria \u2014 bind tasks to a phase via
+\`update_task(..., phase_uid)\` and pull the next available task with
+\`get_next_task(plan_uid, phase_uid?)\`.
+
+## Why the swf shape
+
+This template mirrors swf's \`docs/oms/002-oms-integration/\`
+structure so multiple agents working in parallel can share rich
+context: a numbered overview, one doc per phase, plus cross-cutting
+patterns / testing / security guidance. Read the relevant
+phase doc + the patterns + testing docs before claiming a task.
+
+## How to operate
+
+1. Read the executive overview (this doc) end-to-end.
+2. Read the phase doc for the phase you're about to work in.
+3. Skim **Patterns** + **Testing strategy**; they apply across phases.
+4. \`get_next_task(plan_uid, phase_uid)\` to pick a task.
+5. \`claim_task(plan_uid, task_uid)\` then \`update_task(..., 'in_progress')\`.
+6. Implement, then \`get_drift_report(plan_uid)\` before marking done.
+
+## Out of scope
+
+(fill this in \u2014 what this refactor explicitly does NOT touch)
+`;
+const PHASE_DOC_BODY = (n, title) => `# ${String(n).padStart(2, "0")} \u2014 ${title}
+
+## Scope
+
+(what this phase covers \u2014 e.g. backend models, routes, frontend types)
+
+## Prerequisites
+
+(what must be done before this phase starts)
+
+## Plan of attack
+
+1.
+2.
+3.
+
+## Backend changes
+
+### Models
+
+### Routes / handlers
+
+### Services
+
+## Frontend changes
+
+### Types
+
+### API client
+
+### Components
+
+## Testing
+
+### Unit
+
+### Integration
+
+### Manual smoke
+
+## Acceptance criteria
+
+- [ ]
+- [ ]
+- [ ]
+
+## Git checkpoint
+
+Tag: \`<your-prefix>-${String(n).padStart(2, "0")}-${title.toLowerCase().replace(/[^a-z0-9]+/g, "-")}\`
+`;
+const PATTERNS_DOC = `# Patterns to follow
+
+## Code style
+
+-
+
+## Naming
+
+-
+
+## File organisation
+
+-
+
+# Anti-patterns to avoid
+
+-
+`;
+const TESTING_DOC = `# Testing strategy
+
+## Coverage targets
+
+| Area | Target | Notes |
+|---|---|---|
+| Models | 90% line | Core data layer |
+| Routes | 80% endpoint | Each endpoint must have \u22651 happy path + \u22651 error path |
+| UI components | Smoke render | Snapshot is fine |
+
+## Per-phase strategy
+
+- **01 Foundation** \u2014 types compile, lints clean, no functional tests required yet
+- **02 Data layer** \u2014 model unit tests + a migration round-trip test
+- **03 API** \u2014 route integration tests covering happy + auth + error paths
+- **04 Frontend** \u2014 component smoke tests + e2e for critical flows
+- **05 Integration** \u2014 e2e covering the full cross-system flow
+- **06 Cutover** \u2014 pre/post-deploy smoke; rollback rehearsal
+
+## Fixtures / mocks
+
+-
+`;
+const SECURITY_DOC = `# Security threat model
+
+## Surface area changes
+
+(what new attack surface this refactor introduces)
+
+## Sensitive data paths
+
+(which paths handle credentials / PII / financial data)
+
+## Do-not-touch
+
+(files, endpoints, secrets that must not be modified by this plan)
+
+## Per-phase checks
+
+- **01 Foundation** \u2014
+- **02 Data layer** \u2014
+- **03 API** \u2014 auth on every new endpoint; rate limits where applicable
+- **04 Frontend** \u2014 XSS-safe rendering; avoid leaking IDs in URLs
+- **05 Integration** \u2014
+- **06 Cutover** \u2014 rotate any new secrets before turning on traffic
+`;
+const ARCHITECTURE_DOC = `# Architecture overview
+
+## Components touched by this refactor
+
+| Component | Role | Phase that changes it |
+|---|---|---|
+|  |  |  |
+
+## Data flow
+
+(diagram or prose \u2014 how data moves between the components above)
+
+## New connections this introduces
+
+-
+
+## Connections this removes
+
+-
+
+## Boundaries
+
+(what's the contract between the touched components and everything else)
+`;
+const NEW_FEATURE_REQUIREMENTS = `# Requirements \u2014 {{feature}}
+
+## What this feature does
+
+(one-paragraph description in plain language)
+
+## User stories
+
+- As a [user type], I want to [goal] so that [benefit]
+- ...
+
+## Success criteria
+
+- [ ]
+- [ ]
+
+## Out of scope
+
+(what this feature explicitly does NOT do \u2014 anti-scope)
+
+## Open questions
+
+-
+`;
+const NEW_FEATURE_DESIGN = `# Design \u2014 {{feature}}
+
+## High-level approach
+
+(2-3 sentences on the chosen approach + why)
+
+## New files / modules
+
+| Path | Role |
+|---|---|
+| | |
+
+## Modified files
+
+| Path | Change |
+|---|---|
+| | |
+
+## Data model changes
+
+(new tables / columns / types \u2014 link to migration if applicable)
+
+## API surface
+
+| Method | Path | Purpose |
+|---|---|---|
+| | | |
+
+## UI surface
+
+(screens / components affected)
+`;
+const NEW_FEATURE_UX = `# UX journey \u2014 {{feature}}
+
+## Entry point
+
+(how the user discovers / triggers this feature)
+
+## Happy path
+
+1.
+2.
+3.
+
+## Empty / loading / error states
+
+| State | What user sees |
+|---|---|
+| First-time / empty | |
+| Loading | |
+| Error | |
+
+## Cross-references
+
+(other features / screens that link to this one or are linked from it)
+`;
+const NEW_FEATURE_TESTING = `# Testing \u2014 {{feature}}
+
+## Unit
+
+-
+
+## Integration
+
+-
+
+## Manual / e2e
+
+| Scenario | Steps | Expected |
+|---|---|---|
+| | | |
+`;
+const BUG_FIX_REPORT = `# Bug \u2014 {{bug}}
+
+## Symptom
+
+(what the user sees that's wrong)
+
+## Reproduction
+
+1.
+2.
+3.
+
+**Expected**:
+**Actual**:
+
+## Affected area
+
+{{area}}
+
+## First reported
+
+(date / version / customer)
+
+## Severity
+
+- [ ] Blocker \u2014 production down or data loss
+- [ ] High \u2014 common path broken
+- [ ] Medium \u2014 workaround exists
+- [ ] Low \u2014 cosmetic
+`;
+const BUG_FIX_ROOT_CAUSE = `# Root cause hypothesis
+
+## Suspected files / functions
+
+- {{area}}
+
+## Why it happens
+
+(one-paragraph hypothesis \u2014 disprove if possible)
+
+## Why we didn't catch it
+
+(missing test? missing type guard? missing review checklist?)
+
+## Related code
+
+(grep / xref hits \u2014 places that look similar and might also be broken)
+`;
+const BUG_FIX_REGRESSION = `# Regression test
+
+## Test that would have caught this
+
+(unit / integration / e2e \u2014 and where in the suite it should live)
+
+## Test fixture
+
+\`\`\`
+(input)
+\`\`\`
+
+\`\`\`
+(expected output)
+\`\`\`
+
+## Other tests to add or strengthen
+
+(if the bug class suggests a missing pattern of coverage)
+`;
+const LIB_MIG_OVERVIEW = `# Library migration \u2014 {{from_library}} \u2192 {{to_library}}
+
+## Why migrate
+
+(perf / maintenance / sunset / API improvements / bundle size \u2014 be specific)
+
+## Risk profile
+
+| Dimension | Old | New | Risk |
+|---|---|---|---|
+| Maintenance status | | | |
+| Bundle size | | | |
+| Breaking changes | | | |
+| Type safety | | | |
+
+## Migration strategy
+
+- [ ] **Big bang** \u2014 replace everywhere at once. Choose only if blast radius is small.
+- [ ] **Adapter** \u2014 wrap old behind a thin adapter, swap implementations one callsite at a time. Default for non-trivial migrations.
+- [ ] **Strangler** \u2014 both old and new live side-by-side; flag-flip per code path. For very large or risky migrations.
+
+## Rollback plan
+
+(what triggers rollback, how to roll back, what's lost)
+`;
+const LIB_MIG_COMPAT = `# Compatibility matrix \u2014 {{from_library}} vs {{to_library}}
+
+| {{from_library}} API | {{to_library}} equivalent | Notes |
+|---|---|---|
+| | | |
+| | | |
+
+## Behaviours that change
+
+(silent semantic differences \u2014 places where calling code "looks the same" but does something subtly different)
+
+## Behaviours that disappear
+
+(deprecated APIs with no replacement \u2014 list each callsite that needs custom handling)
+`;
+const LIB_MIG_ROLLOUT = `# Rollout plan
+
+## Order of callsites
+
+(why this order \u2014 usually: smallest / lowest-risk first, hottest path last)
+
+| Order | Callsite | Owner | Notes |
+|---|---|---|---|
+| 1 | | | |
+| 2 | | | |
+
+## Verification per step
+
+(what test confirms the migrated callsite still works \u2014 and that the rest of the app didn't regress)
+
+## Coexistence
+
+(can old and new run in the same process? if not, what's the cut?)
+`;
+const PERF_BUDGET = `# Performance budget \u2014 {{target_metric}}
+
+## Goal
+
+Target **{{target_metric}} \u2264 {{target_value}}** on the {{benchmark}} workload.
+
+## Why this metric
+
+(p95 latency? cold-start time? bundle size? memory under load? \u2014 pick the one that matters to users and explain)
+
+## Out of scope
+
+(metrics that this pass explicitly does NOT optimise; tradeoffs we'll accept)
+`;
+const PERF_BASELINE = `# Baseline measurements
+
+## Reproducer
+
+\`\`\`bash
+(exact command / steps to measure \u2014 must be repeatable on a clean machine)
+\`\`\`
+
+## Current numbers
+
+| Run | {{target_metric}} | Notes |
+|---|---|---|
+| 1 | | |
+| 2 | | |
+| 3 | | |
+| **Median** | | |
+
+## Hardware / env
+
+(machine, OS, node version, etc.)
+
+## Sub-metrics
+
+(CPU? memory? syscalls? \u2014 anything that helps narrow the hotspot before profiling)
+`;
+const PERF_HOTSPOTS = `# Hotspot inventory
+
+## Profiler output
+
+(paste flame graph / sampled stack \u2014 at minimum, top-10 by self-time)
+
+## Suspect functions / files
+
+| Function / file | Why suspected | Estimated win |
+|---|---|---|
+| | | |
+
+## Anti-suspects
+
+(places that look hot but are likely not \u2014 saves wasted optimisation effort)
+
+## Picked first
+
+(which hotspot we're tackling first + why \u2014 usually highest estimated win \xD7 lowest risk)
+`;
+const PERF_VERIFY = `# Verification
+
+## Re-measurement script
+
+(same command as baseline \u2014 copy-paste-able)
+
+## Acceptance
+
+| Run | {{target_metric}} | \u0394 vs baseline | Notes |
+|---|---|---|---|
+| 1 | | | |
+| 2 | | | |
+| 3 | | | |
+| **Median** | | | |
+
+## Regression guard
+
+(microbenchmark / CI assertion that fails if the metric backslides above the new ceiling \u2014 without this, the win decays in 2 sprints)
+
+## What we didn't do
+
+(optimisations considered but skipped \u2014 and why; future-you will want this list)
+`;
+const FROM_TICKET_INTAKE = `# Intake
+
+What the ticket says, and what it leaves unsaid.
+
+## The ask, in the requester's words
+
+<paste the ticket description verbatim \u2014 do not paraphrase it here, a
+paraphrase loses the thing you will argue about later>
+
+## What this actually touches
+
+Fill this in from the graph, not from the ticket. A ticket describes
+intent; the graph knows which files and which services the intent lands
+on. This section is the reason the plan exists rather than the ticket
+being worked directly.
+
+- Systems:
+- Files / symbols:
+- Cross-system edges crossed (HTTP, SQL):
+
+## Contradictions found
+
+Where the ticket and the codebase disagree. "No API changes" next to a
+story that rewrites a route file belongs here, and belongs here BEFORE
+anyone starts.
+
+## Questions for the requester
+
+Answer these before building, not after.
+`;
+const FROM_TICKET_ACCEPTANCE = `# Acceptance criteria
+
+Copied from the ticket, one checkbox each, in the requester's words.
+
+Keeping the requester's wording matters: this is the list they will
+check against, and a helpfully-reworded criterion is one nobody agreed
+to.
+
+- [ ] <criterion>
+
+## Out of scope
+
+What the ticket explicitly does NOT cover. Writing it down is what stops
+the plan quietly growing.
+`;
+const ANALYSIS_GUIDE = `# How we do the {{report}}
+
+> The guide an agent reads before it starts, and a new analyst reads on day one.
+> Replace each prompt with how your team actually does it.
+
+## Who it is for
+
+> The audience, what they decide with it, and what they already know.
+
+## Sources we trust
+
+> Which systems or files are the source of truth for each figure, and which are not.
+
+## House rules
+
+> Rounding, units, currency, period definitions, how to label a restatement.
+
+## What "done" looks like
+
+> Each task's acceptance criteria say it precisely \u2014 this is the short version.
+`;
+const ANALYSIS_MATERIALS = `# Materials
+
+Attach what this {{report}} is built from \u2014 record each file as a **material** on this page:
+
+- the source data for {{period}} (exports, ledgers, the workbook itself);
+- last period's report, for comparison and tone;
+- the style guide or template the output must follow.
+
+An agent reads these through \`read_material\` and cites the exact place \u2014 the sheet and cell,
+the page, the line \u2014 for every figure it uses.
+`;
+const REFACTOR_DESCRIPTION = `## What are you refactoring?
+
+> Describe the code you want to change. What module, class, or pattern is being restructured?
+
+## Why refactor now?
+
+> What's wrong with the current structure? Is it causing bugs, slowing development, or creating confusion?
+
+## From \u2192 To
+
+> What does the current structure look like? What should it look like after?
+
+## Constraints
+
+> What must NOT change? Public APIs? Database schemas? Test expectations?
+`;
+const API_CHANGE_DESCRIPTION = `## Endpoint(s)
+
+> Which endpoints are changing? Method, path, purpose.
+
+## Current contract
+
+> What does the API accept/return today?
+
+## New contract
+
+> What should it accept/return after?
+
+## Consumers
+
+> Who calls this API? Frontend components? Other services? External clients?
+
+## Migration strategy
+
+> How do you handle existing clients? Versioning? Deprecation period?
+`;
+const PLAN_TEMPLATES = [
+  {
+    id: "from-ticket",
+    label: "From a ticket",
+    shortDescription: "Intake scaffold for work arriving from Jira, Linear or an issue tracker.",
+    longDescription: "For work that starts outside CodeTrellis. An agent holding both your tracker's MCP server and this one can fill it in one turn \u2014 see `create_plan_from_external`, which builds the nested plan directly from a fetched epic. The template is the manual path, and the shape that path produces: an intake page that records what the ticket says AND what the graph says it touches, acceptance criteria in the requester's own words, and two phases that keep clarification separate from building. Use `{{ticket}}` for the key and `{{summary}}` for the title.",
+    defaultTitle: "{{ticket}}: {{summary}}",
+    defaultPlanDescription: "Work arriving from a tracker. Read the intake page first \u2014 especially the contradictions section \u2014 and get the open questions answered before starting Phase 2.",
+    placeholders: [
+      { key: "ticket", label: "Ticket key", default: "PROJ-000" },
+      { key: "summary", label: "Ticket summary", default: "<what the ticket asks for>" }
+    ],
+    phases: [
+      {
+        phaseNumber: 1,
+        title: "Clarify",
+        scope: "Map the ticket onto the codebase. Which systems does it touch, which files, does it cross a service boundary nobody mentioned? Answer the open questions. No implementation.",
+        acceptanceCriteria: "- [ ] Intake page lists the real files and systems, taken from the graph\n- [ ] Acceptance criteria transcribed in the requester's words\n- [ ] Contradictions between the ticket and the codebase written down\n- [ ] Open questions answered by the requester, not guessed at\n"
+      },
+      {
+        phaseNumber: 2,
+        title: "Deliver",
+        scope: "Build against the acceptance criteria. Each criterion should map to something in the diff.",
+        prerequisites: "Phase 1 questions answered and contradictions resolved.",
+        acceptanceCriteria: "- [ ] Every acceptance criterion is checked off and traceable to a change\n- [ ] Drift report against the plan: clean\n- [ ] Ticket status written back (get_external_sync_state, then your tracker's MCP)\n"
+      }
+    ],
+    docs: [
+      { key: "intake", orderHint: "00", docType: "requirements", title: "Intake", body: FROM_TICKET_INTAKE },
+      { key: "acceptance", orderHint: "01", docType: "acceptance_criteria", title: "Acceptance criteria", body: FROM_TICKET_ACCEPTANCE }
+    ]
+  },
+  {
+    id: "mass-refactor",
+    label: "Mass refactor (swf-style)",
+    shortDescription: "6-phase modernization with executive overview, per-phase docs, patterns/testing/security guidance.",
+    longDescription: `Models swf's \`docs/oms/002-oms-integration/\` shape: 1 executive overview + 6 numbered phase docs + 1 architecture overview + cross-cutting patterns / testing / security. Each phase is a first-class checkpoint with scope, prereqs, git checkpoint, and acceptance criteria \u2014 built for multiple agents working in parallel on a long migration.`,
+    defaultTitle: "Mass refactor: {name}",
+    defaultPlanDescription: "Deep-mode plan with phases. Read the executive overview first, then the phase doc you're about to work in.",
+    phases: [
+      { phaseNumber: 1, title: "Foundation", scope: "Set up shared types, packages, lint config, CI gates. No behavior changes yet.", acceptanceCriteria: "- [ ] Types compile across all packages\n- [ ] Lint and CI pass on the new structure\n" },
+      { phaseNumber: 2, title: "Data layer", scope: "New / migrated models, schema migrations, seed data.", prerequisites: "Phase 01 complete.", acceptanceCriteria: "- [ ] Migrations run forward and reverse cleanly\n- [ ] Model unit tests cover happy + edge cases\n" },
+      { phaseNumber: 3, title: "API", scope: "New / refactored endpoints, auth wiring, error handling.", prerequisites: "Phase 02 data layer in place.", acceptanceCriteria: "- [ ] Every new endpoint has auth\n- [ ] Integration tests cover happy + auth + error paths\n" },
+      { phaseNumber: 4, title: "Frontend", scope: "Types, API client, components, screens.", prerequisites: "Phase 03 endpoints stable.", acceptanceCriteria: "- [ ] Components compile and lint\n- [ ] Critical-flow e2e passes\n" },
+      { phaseNumber: 5, title: "Integration", scope: "End-to-end cross-system flows, sync / orchestration jobs.", prerequisites: "Phases 02\u201304 deployable to staging.", acceptanceCriteria: "- [ ] Full cross-system flow passes in staging\n- [ ] Drift report clean against the plan\n" },
+      { phaseNumber: 6, title: "Cutover", scope: "Feature flags off \u2192 on, traffic migration, decommission of the old path.", prerequisites: "Phase 05 integration green for at least 24h.", acceptanceCriteria: "- [ ] Old path code-paths removed\n- [ ] Rollback rehearsed and documented\n" }
+    ],
+    docs: [
+      { key: "overview", orderHint: "00", docType: "executive_summary", title: "00 \u2014 Executive overview", body: MASS_REFACTOR_OVERVIEW },
+      { key: "arch", orderHint: "00.5", docType: "architecture", title: "Architecture overview", body: ARCHITECTURE_DOC },
+      { key: "phase1", orderHint: "01", docType: "architecture", title: "01 \u2014 Foundation", body: PHASE_DOC_BODY(1, "Foundation") },
+      { key: "phase2", orderHint: "02", docType: "architecture", title: "02 \u2014 Data layer", body: PHASE_DOC_BODY(2, "Data layer") },
+      { key: "phase3", orderHint: "03", docType: "architecture", title: "03 \u2014 API", body: PHASE_DOC_BODY(3, "API") },
+      { key: "phase4", orderHint: "04", docType: "architecture", title: "04 \u2014 Frontend", body: PHASE_DOC_BODY(4, "Frontend") },
+      { key: "phase5", orderHint: "05", docType: "architecture", title: "05 \u2014 Integration", body: PHASE_DOC_BODY(5, "Integration") },
+      { key: "phase6", orderHint: "06", docType: "architecture", title: "06 \u2014 Cutover", body: PHASE_DOC_BODY(6, "Cutover") },
+      { key: "patterns", orderHint: "90", docType: "patterns", title: "Patterns", body: PATTERNS_DOC },
+      { key: "testing", orderHint: "91", docType: "testing", title: "Testing strategy", body: TESTING_DOC },
+      { key: "security", orderHint: "92", docType: "security", title: "Security threat model", body: SECURITY_DOC }
+    ]
+  },
+  {
+    id: "new-feature",
+    label: "New feature",
+    shortDescription: "Three-phase scaffold for adding a feature: design \u2192 implementation \u2192 testing.",
+    longDescription: 'Lighter than mass-refactor \u2014 for net-new features. Seeds a requirements doc, design doc, UX journey, and testing plan, plus three phases that map cleanly to "decide \u2192 build \u2192 ship". Use the `{{feature}}` placeholder to give the plan a name in one place.',
+    defaultTitle: "Feature: {{feature}}",
+    defaultPlanDescription: "Add a new feature. Read the requirements + design docs first, then pick up tasks from the Implementation phase.",
+    placeholders: [
+      { key: "feature", label: "Feature name", default: "<the feature>" }
+    ],
+    phases: [
+      {
+        phaseNumber: 1,
+        title: "Design",
+        scope: "Lock down requirements, design, and UX journey. No code yet.",
+        acceptanceCriteria: "- [ ] Requirements doc complete (success criteria + out-of-scope filled in)\n- [ ] Design doc lists every new / modified file\n- [ ] UX journey covers happy path + empty / loading / error states\n"
+      },
+      {
+        phaseNumber: 2,
+        title: "Implementation",
+        scope: "Build the feature against the design doc. Backend first if there's a data layer, then API, then UI.",
+        prerequisites: "Phase 1 design signed off.",
+        acceptanceCriteria: "- [ ] Every file listed in the design doc exists\n- [ ] Lints + typechecks clean\n- [ ] Drift report against the plan: clean\n"
+      },
+      {
+        phaseNumber: 3,
+        title: "Testing & polish",
+        scope: "Tests for every path in the testing doc, accessibility pass, copy review, telemetry hooks if applicable.",
+        prerequisites: "Phase 2 implementation complete and self-tested.",
+        acceptanceCriteria: '- [ ] Unit + integration tests for every callout in the testing doc\n- [ ] Manual happy path passes on a clean install\n- [ ] No new "(TODO)" or "(fix me)" comments left in the diff\n'
+      }
+    ],
+    docs: [
+      { key: "requirements", orderHint: "00", docType: "acceptance_criteria", title: "Requirements", body: NEW_FEATURE_REQUIREMENTS },
+      { key: "design", orderHint: "01", docType: "architecture", title: "Design", body: NEW_FEATURE_DESIGN },
+      { key: "ux", orderHint: "02", docType: "ux_ui", title: "UX journey", body: NEW_FEATURE_UX },
+      { key: "testing", orderHint: "03", docType: "testing", title: "Testing", body: NEW_FEATURE_TESTING }
+    ]
+  },
+  {
+    id: "bug-fix",
+    label: "Bug fix",
+    shortDescription: "Lean two-phase template: investigate \u2192 fix-with-regression-test.",
+    longDescription: 'Built for "something is wrong, find it, fix it, prove it stays fixed". Three docs (bug report, root-cause hypothesis, regression test) and two phases. Use `{{bug}}` for the short description and `{{area}}` to point investigators at the suspected module.',
+    defaultTitle: "Bug: {{bug}}",
+    defaultPlanDescription: "Reproduce, root-cause, fix, and add a regression test. Don't mark done without the regression test.",
+    placeholders: [
+      { key: "bug", label: "Bug summary", default: "<one-line description>" },
+      { key: "area", label: "Suspected area", default: "<file or module to start in>" }
+    ],
+    phases: [
+      {
+        phaseNumber: 1,
+        title: "Investigate",
+        scope: "Reproduce reliably, identify the root cause, decide the fix shape.",
+        acceptanceCriteria: "- [ ] Reliable reproduction documented\n- [ ] Root cause confirmed (not just hypothesised)\n- [ ] Fix approach agreed (with one alternative considered + rejected)\n"
+      },
+      {
+        phaseNumber: 2,
+        title: "Fix + regression",
+        scope: "Apply the fix, write a regression test that fails on the bug and passes on the fix, ship.",
+        prerequisites: "Phase 1 root cause confirmed.",
+        acceptanceCriteria: '- [ ] Fix applied, scoped to the root cause\n- [ ] Regression test fails on `git stash` of the fix and passes with it\n- [ ] No nearby suspects left untouched (check the "related code" section)\n'
+      }
+    ],
+    docs: [
+      { key: "report", orderHint: "00", docType: "executive_summary", title: "Bug report", body: BUG_FIX_REPORT },
+      { key: "rootcause", orderHint: "01", docType: "research", title: "Root cause", body: BUG_FIX_ROOT_CAUSE },
+      { key: "regression", orderHint: "02", docType: "testing", title: "Regression test", body: BUG_FIX_REGRESSION }
+    ]
+  },
+  {
+    id: "library-migration",
+    label: "Library migration",
+    shortDescription: "Four-phase scaffold for swapping a dependency: audit \u2192 adapter \u2192 per-callsite \u2192 decommission.",
+    longDescription: "For replacing or upgrading a dependency that touches many callsites. Strategy is configurable (big-bang vs adapter vs strangler \u2014 picked in the overview doc). Use `{{from_library}}` and `{{to_library}}` placeholders. The compatibility matrix doc forces you to think through silent-semantic-change traps before code touches any callsite.",
+    defaultTitle: "Migrate {{from_library}} \u2192 {{to_library}}",
+    defaultPlanDescription: "Replace a dependency without breaking anything. The compatibility matrix is the most important doc \u2014 fill it in honestly before touching any callsite.",
+    placeholders: [
+      { key: "from_library", label: "From (current library)", default: "<old-lib>" },
+      { key: "to_library", label: "To (new library)", default: "<new-lib>" }
+    ],
+    phases: [
+      {
+        phaseNumber: 1,
+        title: "Audit",
+        scope: "Inventory every callsite of {{from_library}}, document API differences, pick a migration strategy.",
+        acceptanceCriteria: "- [ ] Compatibility matrix complete\n- [ ] Migration strategy chosen + documented\n- [ ] Rollback plan written\n"
+      },
+      {
+        phaseNumber: 2,
+        title: "Adapter / scaffolding",
+        scope: 'If the strategy is "adapter," build the adapter layer + tests. If "strangler," set up the flag plumbing. If "big bang," skip \u2014 but reconsider the strategy.',
+        prerequisites: "Phase 1 audit complete.",
+        acceptanceCriteria: "- [ ] Adapter / flag plumbing in place\n- [ ] One pilot callsite migrated through the adapter and proven equivalent\n"
+      },
+      {
+        phaseNumber: 3,
+        title: "Per-callsite migration",
+        scope: "Walk the rollout-plan order. One callsite per task; tests for each before moving on.",
+        prerequisites: "Phase 2 pilot green.",
+        acceptanceCriteria: "- [ ] Every callsite migrated\n- [ ] Per-callsite verification passing\n- [ ] No regressions in the rest of the suite\n"
+      },
+      {
+        phaseNumber: 4,
+        title: "Decommission",
+        scope: "Remove the adapter, drop {{from_library}} from package.json, prove no leftover imports.",
+        prerequisites: "Phase 3 complete + at least 24h of staging soak.",
+        acceptanceCriteria: "- [ ] `{{from_library}}` removed from dependencies\n- [ ] `grep` for `{{from_library}}` in src/ returns nothing meaningful\n- [ ] Bundle size measured before / after\n"
+      }
+    ],
+    docs: [
+      { key: "overview", orderHint: "00", docType: "executive_summary", title: "Migration overview", body: LIB_MIG_OVERVIEW },
+      { key: "compat", orderHint: "01", docType: "architecture", title: "Compatibility matrix", body: LIB_MIG_COMPAT },
+      { key: "rollout", orderHint: "02", docType: "rollout", title: "Rollout plan", body: LIB_MIG_ROLLOUT }
+    ]
+  },
+  {
+    id: "perf-pass",
+    label: "Performance pass",
+    shortDescription: "Measure \u2192 identify \u2192 fix \u2192 verify, with a regression guard at the end.",
+    longDescription: 'Forces you to measure first and verify last. Four phases that match the only good way to do perf work: baseline measurement, hotspot identification, fix, then re-measurement + a regression guard so the win doesn\'t silently decay. Use `{{target_metric}}` (e.g. "p95 cold-start time") and `{{target_value}}` (e.g. "<400 ms") to set the budget up front.',
+    defaultTitle: "Perf pass: {{target_metric}}",
+    defaultPlanDescription: "Don't optimise without measuring. The baseline is the contract; the regression guard is the win.",
+    placeholders: [
+      { key: "target_metric", label: "Target metric", default: "p95 latency" },
+      { key: "target_value", label: "Target value", default: "<400 ms" },
+      { key: "benchmark", label: "Benchmark workload", default: "production-replay" }
+    ],
+    phases: [
+      {
+        phaseNumber: 1,
+        title: "Baseline",
+        scope: "Lock the metric, lock the workload, capture current numbers reproducibly.",
+        acceptanceCriteria: "- [ ] Reproducer command documented\n- [ ] Median of \u22653 runs recorded\n- [ ] Sub-metrics captured (CPU / memory / syscalls etc.)\n"
+      },
+      {
+        phaseNumber: 2,
+        title: "Identify hotspots",
+        scope: "Profile, surface the suspects, pick the highest-leverage hotspot first.",
+        prerequisites: "Phase 1 baseline locked.",
+        acceptanceCriteria: "- [ ] Profile output captured + reviewed\n- [ ] Top suspects ranked by estimated win\n- [ ] First hotspot picked with a written estimate\n"
+      },
+      {
+        phaseNumber: 3,
+        title: "Fix",
+        scope: "Apply the optimisation. One hotspot per task. Don't rewrite anything that wasn't in the suspect list.",
+        prerequisites: "Phase 2 hotspot picked.",
+        acceptanceCriteria: `- [ ] Fix is scoped to the picked hotspot
+- [ ] Local micro-benchmark shows the expected win
+- [ ] No new abstraction layers added "while we're in here"
+`
+      },
+      {
+        phaseNumber: 4,
+        title: "Verify + guard",
+        scope: "Re-measure on the same reproducer, write a regression guard so future commits can't silently undo the win.",
+        prerequisites: "Phase 3 fix landed.",
+        acceptanceCriteria: `- [ ] Re-measured median meets {{target_value}}
+- [ ] Regression guard wired (microbenchmark in CI / perf assertion)
+- [ ] "What we didn't do" list filled in for future-us
+`
+      }
+    ],
+    docs: [
+      { key: "budget", orderHint: "00", docType: "constraints", title: "Performance budget", body: PERF_BUDGET },
+      { key: "baseline", orderHint: "01", docType: "research", title: "Baseline measurements", body: PERF_BASELINE },
+      { key: "hotspots", orderHint: "02", docType: "research", title: "Hotspot inventory", body: PERF_HOTSPOTS },
+      { key: "verify", orderHint: "03", docType: "testing", title: "Verification", body: PERF_VERIFY }
+    ]
+  },
+  {
+    id: "analysis-report",
+    label: "Analysis report",
+    shortDescription: "Gather \u2192 Analyse \u2192 Draft \u2192 Review, with a guide, the materials, and criteria for each step.",
+    longDescription: "A playbook for a report built from data \u2014 a quarterly pack, a board paper, a regional review. The guide page says how your team does it; the materials page holds what it is built from; four steps carry acceptance criteria that show each kind of evidence once: a recorded output, a figure that cites its cell, the analysis code, its tests, and a person's sign-off. Publish your own version of this plan as a template once it fits how you work.",
+    defaultTitle: "{{report}} \u2014 {{period}}",
+    defaultPlanDescription: "Read the guide first, then the materials. Every figure in the draft cites the place it came from; the Review step is signed off by a person.",
+    placeholders: [
+      { key: "report", label: "Report", default: "Quarterly report" },
+      { key: "period", label: "Period", default: "Q3" }
+    ],
+    phases: [],
+    docs: [],
+    items: [
+      { kind: "object", title: "Guide \u2014 how we do the {{report}}", body: ANALYSIS_GUIDE },
+      { kind: "object", title: "Materials", body: ANALYSIS_MATERIALS },
+      {
+        kind: "action",
+        title: "Gather",
+        body: "Collect the {{period}} source data and record each file as a material. Note anything missing or late.",
+        criteria: [
+          { text: "Every source file used for {{period}} is recorded as a material", kind: "artefact" }
+        ]
+      },
+      {
+        kind: "action",
+        title: "Analyse",
+        body: "Work the figures. Any calculation is a script in the repo, not a hand edit in a copy of the data.",
+        criteria: [
+          { text: "Every figure in the analysis cites the sheet and cell it came from", kind: "citation" },
+          { text: "The analysis script is committed where the plan says", kind: "code" },
+          { text: "The analysis script's tests pass", kind: "test" }
+        ]
+      },
+      {
+        kind: "action",
+        title: "Draft",
+        body: "Write the {{report}} to the house style in the guide, and record it as this step's output.",
+        criteria: [
+          { text: "The draft {{report}} is recorded as an output", kind: "artefact" }
+        ]
+      },
+      {
+        kind: "action",
+        title: "Review",
+        body: "The report owner reads the draft against the materials and signs it off \u2014 on the desktop or the phone.",
+        criteria: [
+          { text: "Reviewed and approved by the report owner", kind: "manual" }
+        ]
+      }
+    ]
+  },
+  {
+    id: "refactor",
+    label: "Refactor",
+    shortDescription: "Rename, move, or restructure existing code.",
+    longDescription: "A light, three-step refactor: prepare, migrate, verify. For a long multi-agent modernisation, use Mass refactor instead.",
+    defaultTitle: "Refactor: {name}",
+    defaultPlanDescription: REFACTOR_DESCRIPTION,
+    phases: [],
+    docs: [],
+    items: [
+      { kind: "object", title: "Context & Analysis", body: "## Current structure\n\n> Describe the existing code\n\n## Problems\n\n> What specific issues exist?" },
+      { kind: "action", title: "Phase 1: Prepare", body: "Set up any scaffolding, create new files, update imports that need to change." },
+      { kind: "action", title: "Phase 2: Migrate", body: "Move/rename the core code. Update all callers." },
+      {
+        kind: "action",
+        title: "Phase 3: Verify & Clean up",
+        body: "Run tests, remove old code, update docs.",
+        criteria: [{ text: "The test suite passes after the move", kind: "test" }]
+      }
+    ]
+  },
+  {
+    id: "api-change",
+    label: "API change",
+    shortDescription: "Add, modify, or deprecate API endpoints.",
+    longDescription: "The contract first, then the handlers, then every consumer \u2014 and the tests and docs that describe it.",
+    defaultTitle: "API change: {name}",
+    defaultPlanDescription: API_CHANGE_DESCRIPTION,
+    phases: [],
+    docs: [],
+    items: [
+      { kind: "object", title: "API Design", body: "## Endpoints\n\n| Method | Path | Change |\n|--------|------|--------|\n| | | |\n\n## Request/Response schemas\n\n> ..." },
+      { kind: "action", title: "Backend changes", body: "Update route handlers, validation, database queries." },
+      { kind: "action", title: "Update consumers", body: "Update all clients/callers of the changed endpoints." },
+      { kind: "action", title: "Tests & documentation", body: "Update API tests and any API documentation." }
+    ]
+  }
+];
+function listTemplates(projectRoot) {
+  const all = collectTemplates(projectRoot);
+  return all.map((t) => {
+    const tplAny = t;
+    const isV2 = Array.isArray(tplAny.items) && tplAny.items.length > 0;
+    return {
+      id: t.id,
+      label: t.label,
+      shortDescription: t.shortDescription,
+      longDescription: t.longDescription,
+      defaultTitle: t.defaultTitle,
+      source: t.source ?? "builtin",
+      placeholders: t.placeholders,
+      phaseCount: t.phases.length,
+      docCount: t.docs.length,
+      ...isV2 ? { version: 2, itemCount: countTemplateItems(tplAny.items), criteriaCount: countTemplateCriteria(tplAny.items) } : {}
+    };
+  });
+}
+function countTemplateCriteria(items) {
+  let count = 0;
+  for (const item of items) {
+    if (Array.isArray(item.criteria)) count += item.criteria.length;
+    if (Array.isArray(item.children)) count += countTemplateCriteria(item.children);
+  }
+  return count;
+}
+function countTemplateItems(items) {
+  let count = 0;
+  for (const item of items) {
+    count++;
+    if (Array.isArray(item.children)) {
+      count += countTemplateItems(item.children);
+    }
+  }
+  return count;
+}
+function getTemplate(id, projectRoot) {
+  return collectTemplates(projectRoot).find((t) => t.id === id) ?? null;
+}
+function collectTemplates(projectRoot) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const t of PLAN_TEMPLATES) {
+    byId.set(t.id, { ...t, source: "builtin" });
+  }
+  for (const t of loadTemplatesFromDir(import_node_path.default.join(import_node_os.default.homedir(), ".codetrellis", "templates"), "user")) {
+    byId.set(t.id, t);
+  }
+  if (projectRoot) {
+    for (const t of loadTemplatesFromDir(import_node_path.default.join(projectRoot, ".codetrellis", "templates"), "project")) {
+      byId.set(t.id, t);
+    }
+  }
+  return [...byId.values()];
+}
+function loadTemplatesFromDir(dir, source) {
+  if (!import_node_fs.default.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of safeReaddir(dir)) {
+    const tplDir = import_node_path.default.join(dir, entry);
+    let stat;
+    try {
+      stat = import_node_fs.default.statSync(tplDir);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+    const yamlPath = import_node_path.default.join(tplDir, "template.yaml");
+    if (!import_node_fs.default.existsSync(yamlPath)) continue;
+    try {
+      const tpl = readTemplate(tplDir, source);
+      if (tpl) out.push(tpl);
+    } catch (err) {
+      console.warn(`[Templates] Failed to load ${tplDir}:`, err instanceof Error ? err.message : err);
+    }
+  }
+  return out;
+}
+function readTemplate(tplDir, source) {
+  const yamlPath = import_node_path.default.join(tplDir, "template.yaml");
+  const raw = (0, import_yaml.parse)(import_node_fs.default.readFileSync(yamlPath, "utf-8"));
+  if (!raw || typeof raw !== "object") return null;
+  if (!raw.id || !raw.label) return null;
+  const docs = [];
+  for (const d of raw.docs ?? []) {
+    if (!d) continue;
+    let body = typeof d.body === "string" ? d.body : "";
+    if (!body && typeof d.bodyPath === "string") {
+      try {
+        body = (0, import_confined_fs.readTextWithin)(tplDir, d.bodyPath, "template doc bodyPath");
+      } catch {
+        body = "";
+      }
+    }
+    docs.push({
+      docType: String(d.docType ?? "custom"),
+      title: String(d.title ?? ""),
+      body,
+      orderHint: typeof d.orderHint === "string" ? d.orderHint : void 0,
+      parentKey: typeof d.parentKey === "string" ? d.parentKey : void 0,
+      key: typeof d.key === "string" ? d.key : void 0
+    });
+  }
+  const phases = (raw.phases ?? []).map((p) => ({
+    phaseNumber: Number(p.phaseNumber ?? 1),
+    title: String(p.title ?? ""),
+    scope: typeof p.scope === "string" ? p.scope : void 0,
+    prerequisites: typeof p.prerequisites === "string" ? p.prerequisites : void 0,
+    acceptanceCriteria: typeof p.acceptanceCriteria === "string" ? p.acceptanceCriteria : void 0,
+    status: p.status,
+    tasks: Array.isArray(p.tasks) ? p.tasks : void 0
+  }));
+  const placeholders = (raw.placeholders ?? []).filter((p) => p && typeof p.key === "string").map((p) => ({
+    key: String(p.key),
+    label: typeof p.label === "string" ? p.label : void 0,
+    default: typeof p.default === "string" ? p.default : void 0
+  }));
+  const result = {
+    id: String(raw.id),
+    label: String(raw.label),
+    shortDescription: String(raw.shortDescription ?? ""),
+    longDescription: String(raw.longDescription ?? ""),
+    defaultTitle: String(raw.defaultTitle ?? raw.label),
+    defaultPlanDescription: String(raw.defaultPlanDescription ?? ""),
+    phases,
+    docs,
+    placeholders: placeholders.length ? placeholders : void 0,
+    source
+  };
+  if (Array.isArray(raw.items) && raw.items.length > 0) {
+    result.items = resolveItemBodyPaths(raw.items, tplDir);
+  }
+  return result;
+}
+function resolveItemBodyPaths(items, tplDir) {
+  return items.map((item) => {
+    const resolved = { ...item };
+    if (!resolved.body && typeof resolved.bodyPath === "string") {
+      try {
+        resolved.body = (0, import_confined_fs.readTextWithin)(tplDir, resolved.bodyPath, "template item bodyPath");
+      } catch {
+        resolved.body = "";
+      }
+    }
+    if (Array.isArray(resolved.children)) {
+      resolved.children = resolveItemBodyPaths(resolved.children, tplDir);
+    }
+    return resolved;
+  });
+}
+function safeReaddir(dir) {
+  try {
+    return import_node_fs.default.readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+function substitutePlaceholders(template, values) {
+  const sub = (s) => {
+    if (typeof s !== "string") return s;
+    return s.replace(/\{\{(\w+)\}\}/g, (_, k) => values[k] ?? `{{${k}}}`);
+  };
+  return {
+    ...template,
+    label: sub(template.label) ?? template.label,
+    defaultTitle: sub(template.defaultTitle) ?? template.defaultTitle,
+    defaultPlanDescription: sub(template.defaultPlanDescription) ?? template.defaultPlanDescription,
+    phases: template.phases.map((p) => ({
+      ...p,
+      title: sub(p.title) ?? p.title,
+      scope: sub(p.scope),
+      prerequisites: sub(p.prerequisites),
+      acceptanceCriteria: sub(p.acceptanceCriteria),
+      tasks: p.tasks?.map((t) => ({
+        ...t,
+        description: sub(t.description) ?? t.description,
+        affectedFiles: t.affectedFiles?.map((f) => sub(f) ?? f)
+      }))
+    })),
+    docs: template.docs.map((d) => ({
+      ...d,
+      title: sub(d.title) ?? d.title,
+      body: sub(d.body) ?? d.body
+    })),
+    // V2 items — substitute placeholders recursively
+    ...template.items ? { items: substituteItemPlaceholders(template.items, sub) } : {}
+  };
+}
+function substituteItemPlaceholders(items, sub) {
+  return items.map((item) => {
+    const result = { ...item };
+    if (typeof result.title === "string") result.title = sub(result.title) ?? result.title;
+    if (typeof result.body === "string") result.body = sub(result.body) ?? result.body;
+    if (typeof result.scopePath === "string") result.scopePath = sub(result.scopePath) ?? result.scopePath;
+    if (Array.isArray(result.criteria)) {
+      result.criteria = result.criteria.map((c) => {
+        if (typeof c === "string") return sub(c) ?? c;
+        if (c && typeof c === "object" && typeof c.text === "string") {
+          return { ...c, text: sub(c.text) };
+        }
+        return c;
+      });
+    }
+    if (Array.isArray(result.children)) {
+      result.children = substituteItemPlaceholders(result.children, sub);
+    }
+    return result;
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PLAN_TEMPLATES,
+  getTemplate,
+  listTemplates,
+  substitutePlaceholders
+});