@moretea-labs/forge 1.5.0-rc.1

package/scripts/migrate-requirement-portfolio.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+import { existsSync, mkdirSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { spawnSync } from 'child_process';
+import { listIssues } from '../src/cli/controller/issue-store';
+import {
+  REQUIREMENT_PORTFOLIO_MIGRATION_ID,
+  applyRequirementPortfolioMigration,
+  previewRequirementPortfolioMigration,
+} from '../src/cli/controller/requirement-portfolio-migration';
+import { resolveRepoPreferredControllerHome } from '../src/cli/repositories/controller-home';
+import { backupControlPlaneDatabase } from '../src/runtime/control-plane/persistence/sqlite-store';
+
+interface Args {
+  repoRoot: string;
+  repoId?: string;
+  controllerHome?: string;
+  sourceRevision?: string;
+  backupPath?: string;
+  apply: boolean;
+  json: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = { repoRoot: process.cwd(), apply: false, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--apply') args.apply = true;
+    else if (value === '--json') args.json = true;
+    else if (value === '--repo') args.repoRoot = resolve(argv[++index] ?? '');
+    else if (value === '--repo-id') args.repoId = argv[++index];
+    else if (value === '--controller-home') args.controllerHome = resolve(argv[++index] ?? '');
+    else if (value === '--source-revision') args.sourceRevision = argv[++index];
+    else if (value === '--backup-path') args.backupPath = resolve(argv[++index] ?? '');
+    else throw new Error(`unknown argument: ${value}`);
+  }
+  return args;
+}
+
+function gitHead(repoRoot: string): string {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' });
+  if (result.status !== 0) throw new Error(`unable to resolve Git HEAD: ${String(result.stderr).trim()}`);
+  return String(result.stdout).trim();
+}
+
+function resolveRepoId(explicit: string | undefined, issues: ReturnType<typeof listIssues>): string {
+  if (explicit?.trim()) return explicit.trim();
+  const ids = [...new Set(issues.map((issue) => issue.repoId).filter((value): value is string => Boolean(value)))];
+  if (ids.length !== 1) throw new Error(`--repo-id is required; discovered ${ids.length} repository identities`);
+  return ids[0];
+}
+
+function main(): void {
+  const args = parseArgs(process.argv.slice(2));
+  const issues = listIssues(args.repoRoot, { includeEphemeral: false });
+  const repoId = resolveRepoId(args.repoId, issues);
+  const controllerHome = resolveRepoPreferredControllerHome(args.repoRoot, args.controllerHome);
+  const sourceRevision = args.sourceRevision?.trim() || gitHead(args.repoRoot);
+  const input = { controllerHome, repoId, sourceRevision, issues };
+  let backupPath: string | undefined;
+  let result;
+  if (args.apply) {
+    backupPath = args.backupPath ?? join(controllerHome, 'backups', `${REQUIREMENT_PORTFOLIO_MIGRATION_ID}-${sourceRevision.slice(0, 12)}.sqlite`);
+    if (!existsSync(backupPath)) {
+      mkdirSync(dirname(backupPath), { recursive: true });
+      backupControlPlaneDatabase(controllerHome, backupPath);
+    }
+    result = applyRequirementPortfolioMigration(input);
+  } else {
+    result = previewRequirementPortfolioMigration(input);
+  }
+  const output = { ...result, controllerHome, repoRoot: args.repoRoot, backupPath, writesApplied: args.apply };
+  if (args.json) console.log(JSON.stringify(output, null, 2));
+  else {
+    console.log(`[requirement-portfolio] ${result.status}: ${result.requirementCount} Requirements, ${result.planCount} Plans, ${result.sourceIssueCount} source Issues.`);
+    if (!args.apply) console.log('[requirement-portfolio] Preview only; pass --apply to write SQLite authority.');
+    if (backupPath) console.log(`[requirement-portfolio] Backup: ${backupPath}`);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/scripts/migrate-workflow-docs.ts

@@ -0,0 +1,413 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+
+type Mode = "dry-run" | "apply";
+
+type MigrationRecord = {
+  source: string;
+  target: string;
+  action: "archive" | "rewrite" | "append" | "skip";
+  note: string;
+};
+
+type MigrationSummary = {
+  repo: string;
+  mode: Mode;
+  migrated: MigrationRecord[];
+  skipped: string[];
+  manual_followups: string[];
+};
+
+function parseArgs(argv: string[]) {
+  let repo = process.cwd();
+  let mode: Mode = "dry-run";
+  let format: "json" | "text" = "text";
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--repo") {
+      repo = argv[i + 1] ? resolve(argv[i + 1]) : repo;
+      i += 1;
+      continue;
+    }
+    if (arg === "--apply") {
+      mode = "apply";
+      continue;
+    }
+    if (arg === "--dry-run") {
+      mode = "dry-run";
+      continue;
+    }
+    if (arg === "--format") {
+      format = argv[i + 1] === "json" ? "json" : "text";
+      i += 1;
+    }
+  }
+
+  return { repo, mode, format };
+}
+
+function ensureDir(path: string, mode: Mode) {
+  if (mode === "apply") {
+    mkdirSync(path, { recursive: true });
+  }
+}
+
+function appendIfMissing(target: string, marker: string, block: string, mode: Mode) {
+  const existing = existsSync(target) ? readFileSync(target, "utf-8") : "";
+  if (existing.includes(marker)) return false;
+  if (mode === "apply") {
+    ensureDir(dirname(target), mode);
+    const next = existing ? `${existing.trimEnd()}\n\n${block}\n` : `${block}\n`;
+    writeFileSync(target, next);
+  }
+  return true;
+}
+
+function hasCanonicalTodoHeader(content: string): boolean {
+  return /^# Deferred Goal Ledger\s*$/m.test(content) && /^\> \*\*Status\*\*:\s*Backlog\s*$/m.test(content);
+}
+
+function writeCanonicalTodo(target: string, mode: Mode) {
+  if (existsSync(target)) return;
+  const content = [
+    "# Deferred Goal Ledger",
+    "",
+    "> **Status**: Backlog",
+    "> **Updated**: (migration)",
+    "> **Scope**: Medium/long-term goals deferred from active plan execution",
+    "",
+    "Current plan tasks live in the active plan's `## Task Breakdown`.",
+    "Do not duplicate that execution checklist here. Record only work intentionally deferred beyond this slice, with the tradeoff and revisit trigger.",
+    "",
+    "## Deferred Goals",
+    "",
+    "| Goal | Why Deferred | Tradeoff | Revisit Trigger |",
+    "|------|--------------|----------|-----------------|",
+    "| (none) | No deferred medium/long-term goal recorded yet. | Keep migrated workflow state bounded. | Add a row when a real follow-up is postponed. |",
+  ].join("\n");
+  if (mode === "apply") {
+    ensureDir(dirname(target), mode);
+    writeFileSync(target, `${content}\n`);
+  }
+}
+
+function normalizeLegacyTodo(target: string, archivePath: string, mode: Mode) {
+  if (!existsSync(target)) return false;
+
+  const existing = readFileSync(target, "utf-8");
+  if (hasCanonicalTodoHeader(existing)) return false;
+
+  const content = [
+    "# Deferred Goal Ledger",
+    "",
+    "> **Status**: Backlog",
+    "> **Updated**: (migration)",
+    "> **Scope**: Medium/long-term goals deferred from active plan execution",
+    "",
+    "Current plan tasks live in the active plan's `## Task Breakdown`.",
+    "Do not duplicate that execution checklist here. Record only work intentionally deferred beyond this slice, with the tradeoff and revisit trigger.",
+    "",
+    "## Deferred Goals",
+    "",
+    "| Goal | Why Deferred | Tradeoff | Revisit Trigger |",
+    "|------|--------------|----------|-----------------|",
+    "| Review archived legacy checklist | Legacy tasks/todos.md contained execution checklist content before migration. | Preserve user-authored task text in tasks/archive instead of guessing which items still matter. | Open the archive and promote real follow-up work into a new plan or a deferred-goal row. |",
+  ].join("\n");
+
+  if (mode === "apply") {
+    ensureDir(dirname(target), mode);
+    ensureDir(dirname(archivePath), mode);
+    if (!existsSync(archivePath)) {
+      writeFileSync(archivePath, `${existing.trimEnd()}\n`);
+    }
+    writeFileSync(target, `${content}\n`);
+  }
+
+  return true;
+}
+
+function migrateLegacySingularTodo(source: string, target: string, archivePath: string, mode: Mode) {
+  if (!existsSync(source)) return false;
+
+  const existing = readFileSync(source, "utf-8");
+  const content = hasCanonicalTodoHeader(existing)
+    ? existing.trimEnd()
+    : [
+        "# Deferred Goal Ledger",
+        "",
+        "> **Status**: Backlog",
+        "> **Updated**: (migration)",
+        "> **Scope**: Medium/long-term goals deferred from active plan execution",
+        "",
+        "Current plan tasks live in the active plan's `## Task Breakdown`.",
+        "Do not duplicate that execution checklist here. Record only work intentionally deferred beyond this slice, with the tradeoff and revisit trigger.",
+        "",
+        "## Deferred Goals",
+        "",
+        "| Goal | Why Deferred | Tradeoff | Revisit Trigger |",
+        "|------|--------------|----------|-----------------|",
+        "| Review archived legacy checklist | Legacy tasks/todo.md contained execution checklist content before migration. | Preserve user-authored task text in tasks/archive instead of guessing which items still matter. | Open the archive and promote real follow-up work into a new plan or a deferred-goal row. |",
+      ].join("\n");
+
+  if (mode === "apply") {
+    ensureDir(dirname(target), mode);
+    ensureDir(dirname(archivePath), mode);
+    if (!existsSync(archivePath)) {
+      writeFileSync(archivePath, `${existing.trimEnd()}\n`);
+    }
+    if (!existsSync(target)) {
+      writeFileSync(target, `${content}\n`);
+    }
+    renameSync(source, `${source}.migrated.bak`);
+  }
+
+  return true;
+}
+
+function writeResearchReadme(target: string, mode: Mode) {
+  if (existsSync(target)) return;
+  const content = [
+    "# Research Reports",
+    "",
+    "Durable research reports live in this directory as dated Markdown files.",
+    "",
+    "Use `YYYYMMDD-topic.md` names for new reports. Keep task-local implementation",
+    "decisions in `tasks/notes/`, and keep repeated correction-derived rules in",
+    "`tasks/lessons.md`.",
+  ].join("\n");
+  if (mode === "apply") {
+    ensureDir(dirname(target), mode);
+    writeFileSync(target, `${content}\n`);
+  }
+}
+
+function migrateLegacyResearch(source: string, archivePath: string, mode: Mode) {
+  if (!existsSync(source)) return false;
+
+  const existing = readFileSync(source, "utf-8");
+  if (existing.includes("**Canonical Surface**: `docs/researches/`")) return false;
+
+  const tombstone = [
+    "# Research Notes Moved",
+    "",
+    "> **Status**: Retired tombstone",
+    "> **Canonical Surface**: `docs/researches/`",
+    "> **Legacy Archive**: `docs/researches/legacy-research-notes.md`",
+    "",
+    "Durable research reports now live under `docs/researches/*.md`. This file is",
+    "kept only as a transition pointer for older tooling and historical links; do",
+    "not add new findings here.",
+  ].join("\n");
+
+  if (mode === "apply") {
+    ensureDir(dirname(archivePath), mode);
+    if (!existsSync(archivePath)) {
+      writeFileSync(archivePath, `${existing.trimEnd()}\n`);
+    }
+    writeFileSync(source, `${tombstone}\n`);
+  }
+
+  return true;
+}
+
+function writeResearchReport(target: string, marker: string, title: string, body: string, mode: Mode) {
+  const block = [`# ${title}`, "", marker, "", body.trimEnd()].join("\n");
+  return appendIfMissing(target, marker, block, mode);
+}
+
+export function migrate(repo: string, mode: Mode): MigrationSummary {
+  const summary: MigrationSummary = {
+    repo,
+    mode,
+    migrated: [],
+    skipped: [],
+    manual_followups: [],
+  };
+
+  const planDoc = join(repo, "docs", "plan.md");
+  const todoDoc = join(repo, "docs", "TODO.md");
+  const progressDoc = join(repo, "docs", "PROGRESS.md");
+  const tasksTodo = join(repo, "tasks", "todos.md");
+  const legacySingularTasksTodo = join(repo, "tasks", "todo.md");
+  const tasksResearch = join(repo, "tasks", "research.md");
+  const researchDir = join(repo, "docs", "researches");
+  const researchReadme = join(researchDir, "README.md");
+  const legacyResearchArchive = join(researchDir, "legacy-research-notes.md");
+  const legacyProgressResearch = join(researchDir, "legacy-progress-import.md");
+  const plansArchive = join(repo, "plans", "archive");
+  const tasksArchive = join(repo, "tasks", "archive");
+  const legacyPlanArchive = join(plansArchive, "legacy-docs-plan.md");
+  const legacyTodoArchive = join(tasksArchive, "legacy-docs-TODO.md");
+  const legacyProgressArchive = join(tasksArchive, "legacy-docs-PROGRESS.md");
+  const legacyTasksTodoArchive = join(tasksArchive, "legacy-tasks-todo.md");
+  const legacyContractDoc = join(repo, "docs", "contract.md");
+  const legacyReviewDoc = join(repo, "docs", "review.md");
+  const legacyHandoffDoc = join(repo, "docs", "handoff.md");
+  const rootHandoffDoc = join(repo, "HANDOFF.md");
+
+  ensureDir(plansArchive, mode);
+  ensureDir(tasksArchive, mode);
+  if (migrateLegacySingularTodo(legacySingularTasksTodo, tasksTodo, legacyTasksTodoArchive, mode)) {
+    summary.migrated.push({
+      source: "tasks/todo.md",
+      target: "tasks/todos.md",
+      action: "rewrite",
+      note: "Archived legacy singular todo content and normalized tasks/todos.md to the deferred-goal ledger.",
+    });
+  }
+  writeCanonicalTodo(tasksTodo, mode);
+  if (normalizeLegacyTodo(tasksTodo, legacyTasksTodoArchive, mode)) {
+    summary.migrated.push({
+      source: "tasks/todos.md",
+      target: "tasks/todos.md",
+      action: "rewrite",
+      note: "Archived legacy task checklist content and normalized tasks/todos.md to the deferred-goal ledger.",
+    });
+  }
+  ensureDir(researchDir, mode);
+  writeResearchReadme(researchReadme, mode);
+  if (migrateLegacyResearch(tasksResearch, legacyResearchArchive, mode)) {
+    summary.migrated.push({
+      source: "tasks/research.md",
+      target: "docs/researches/legacy-research-notes.md",
+      action: "archive",
+      note: "Archived legacy singleton research notes and left a tombstone pointer.",
+    });
+  }
+
+  // NOTE: The "<!-- forge: legacy-docs-import ... -->" markers below are
+  // data markers written into migrated repos and used by appendIfMissing as the
+  // idempotency key, so renaming them would re-import already-migrated legacy docs.
+  // Keep the marker string stable.
+  if (existsSync(planDoc)) {
+    const content = readFileSync(planDoc, "utf-8");
+    const archiveBlock = [
+      "# Legacy Plan Import",
+      "",
+      "<!-- forge: legacy-docs-import docs/plan.md -->",
+      "",
+      "Original `docs/plan.md` content was archived during migration.",
+      "",
+      "## Imported Content",
+      "",
+      content.trimEnd(),
+    ].join("\n");
+
+    if (mode === "apply" && !existsSync(legacyPlanArchive)) {
+      writeFileSync(legacyPlanArchive, `${archiveBlock}\n`);
+    }
+    if (mode === "apply") {
+      renameSync(planDoc, `${planDoc}.migrated.bak`);
+    }
+    summary.migrated.push({
+      source: "docs/plan.md",
+      target: "plans/archive/legacy-docs-plan.md",
+      action: "archive",
+      note: "Archived uncertain legacy plan content for manual review.",
+    });
+    summary.manual_followups.push("Review plans/archive/legacy-docs-plan.md and create a canonical plan if the content is still active.");
+  }
+
+  if (existsSync(todoDoc)) {
+    const content = readFileSync(todoDoc, "utf-8").trimEnd();
+    const hadCanonicalTodo = existsSync(tasksTodo);
+
+    if (!hadCanonicalTodo) {
+      writeCanonicalTodo(tasksTodo, mode);
+    }
+
+    if (mode === "apply" && !existsSync(legacyTodoArchive)) {
+      writeFileSync(legacyTodoArchive, `${content}\n`);
+      renameSync(todoDoc, `${todoDoc}.migrated.bak`);
+    }
+    summary.migrated.push({
+      source: "docs/TODO.md",
+      target: "tasks/todos.md",
+      action: hadCanonicalTodo ? "skip" : "rewrite",
+      note: hadCanonicalTodo
+        ? "Archived the legacy todo without rewriting the existing deferred-goal ledger."
+        : "Created the deferred-goal ledger and archived the legacy todo for manual plan triage.",
+    });
+    summary.manual_followups.push(
+      "Review tasks/archive/legacy-docs-TODO.md and promote any still-relevant work into a new plan instead of rehydrating it into tasks/todos.md."
+    );
+  }
+
+  if (existsSync(progressDoc)) {
+    const content = readFileSync(progressDoc, "utf-8").trimEnd();
+    if (!readFileSync(progressDoc, "utf-8").includes("milestone checkpoints only")) {
+      writeResearchReport(
+        legacyProgressResearch,
+        "<!-- forge: legacy-docs-import docs/PROGRESS.md -->",
+        "Legacy Progress Import",
+        ["Imported from a legacy execution log stored in `docs/PROGRESS.md`.", "", content].join("\n"),
+        mode
+      );
+    }
+
+    if (mode === "apply") {
+      if (!existsSync(legacyProgressArchive)) {
+        writeFileSync(legacyProgressArchive, `${content}\n`);
+      }
+      renameSync(progressDoc, `${progressDoc}.migrated.bak`);
+    }
+    summary.migrated.push({
+      source: "docs/PROGRESS.md",
+      target: "tasks/archive/legacy-docs-PROGRESS.md",
+      action: "archive",
+      note: "Archived legacy progress notes; docs/PROGRESS.md is no longer a generated workflow surface.",
+    });
+  }
+
+  const archiveDoc = (sourcePath: string, archiveName: string, note: string) => {
+    if (!existsSync(sourcePath)) return;
+    const target = join(tasksArchive, archiveName);
+    if (mode === "apply" && !existsSync(target)) {
+      writeFileSync(target, `${readFileSync(sourcePath, "utf-8").trimEnd()}\n`);
+      renameSync(sourcePath, `${sourcePath}.migrated.bak`);
+    }
+    summary.migrated.push({
+      source: sourcePath.replace(`${repo}/`, ""),
+      target: target.replace(`${repo}/`, ""),
+      action: "archive",
+      note,
+    });
+    summary.manual_followups.push(`Review ${target.replace(`${repo}/`, "")} and re-home any still-relevant content.`);
+  };
+
+  archiveDoc(legacyContractDoc, "legacy-docs-contract.md", "Archived legacy contract notes for manual triage.");
+  archiveDoc(legacyReviewDoc, "legacy-docs-review.md", "Archived legacy review notes for manual triage.");
+  archiveDoc(legacyHandoffDoc, "legacy-docs-handoff.md", "Archived legacy handoff notes for manual triage.");
+  archiveDoc(rootHandoffDoc, "legacy-root-HANDOFF.md", "Archived root handoff notes for manual triage.");
+
+  return summary;
+}
+
+function renderText(summary: MigrationSummary): string {
+  const lines = [
+    `[migrate-docs] repo: ${summary.repo}`,
+    `[migrate-docs] mode: ${summary.mode}`,
+  ];
+
+  for (const item of summary.migrated) {
+    lines.push(`[migrate-docs] ${item.source} -> ${item.target} (${item.action})`);
+    lines.push(`[migrate-docs] note: ${item.note}`);
+  }
+  for (const followup of summary.manual_followups) {
+    lines.push(`[migrate-docs] follow-up: ${followup}`);
+  }
+  if (summary.migrated.length === 0) {
+    lines.push("[migrate-docs] no legacy documents detected");
+  }
+  return lines.join("\n");
+}
+
+const { repo, mode, format } = parseArgs(process.argv.slice(2));
+const summary = migrate(repo, mode);
+
+if (format === "json") {
+  console.log(JSON.stringify(summary, null, 2));
+} else {
+  console.log(renderText(summary));
+}

package/scripts/new-plan.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null)"; then
+  cd "$REPO_ROOT"
+elif [[ "$SCRIPT_DIR" == */.ai/harness/scripts ]]; then
+  cd "$SCRIPT_DIR/../../.."
+else
+  cd "$SCRIPT_DIR/.."
+fi
+
+usage() {
+  cat <<'USAGE_EOF'
+Usage: scripts/new-plan.sh --slug <slug> [--title <title>]
+USAGE_EOF
+}
+
+normalize_slug() {
+  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g'
+}
+
+escape_sed_replacement() {
+  printf '%s' "$1" | sed -e 's/[\/&]/\\&/g'
+}
+
+slug=""
+title=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --slug)
+      [[ -n "${2:-}" ]] || { echo "Error: --slug requires a value" >&2; usage; exit 1; }
+      slug="$2"
+      shift 2
+      ;;
+    --title)
+      [[ -n "${2:-}" ]] || { echo "Error: --title requires a value" >&2; usage; exit 1; }
+      title="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$slug" ]]; then
+  echo "--slug is required" >&2
+  usage
+  exit 1
+fi
+
+slug="$(normalize_slug "$slug")"
+if [[ -z "$slug" ]]; then
+  echo "Slug is empty after normalization" >&2
+  exit 1
+fi
+
+if [[ -z "$title" ]]; then
+  title="$slug"
+fi
+
+timestamp="$(date +%Y%m%d-%H%M)"
+mkdir -p plans plans/archive .claude/templates
+
+template_file=".claude/templates/plan.template.md"
+if [[ ! -f "$template_file" ]]; then
+  cat > "$template_file" <<'PLAN_TEMPLATE_EOF'
+# Plan: {{TITLE}}
+
+> **Status**: Draft
+> **Created**: {{TIMESTAMP}}
+> **Slug**: {{SLUG}}
+> **Spec**: `docs/spec.md`
+> **Research**: See `docs/researches/`
+> **Task Contract**: `tasks/contracts/{{ARTIFACT_STEM}}.contract.md`
+> **Task Review**: `tasks/reviews/{{ARTIFACT_STEM}}.review.md`
+> **Implementation Notes**: `tasks/notes/{{ARTIFACT_STEM}}.notes.md`
+
+## Agentic Routing
+- Selected route:
+- Routing reason:
+- Due diligence:
+  - P1 map:
+  - P2 trace:
+  - P3 decision rationale:
+
+## Workflow Inventory
+Complete this inventory before implementation. If any line is unknown, keep the plan in Draft and fill it before projection.
+
+- Active plan: `{{PLAN_FILE}}`
+- Sprint contract: `tasks/contracts/{{ARTIFACT_STEM}}.contract.md`
+- Sprint review: `tasks/reviews/{{ARTIFACT_STEM}}.review.md`
+- Implementation notes: `tasks/notes/{{ARTIFACT_STEM}}.notes.md`
+- Deferred-goal ledger: `tasks/todos.md`
+- Current checks: `.ai/harness/checks/latest.json`
+- Run snapshots: `.ai/harness/runs/`
+- Scope authority: `tasks/contracts/{{ARTIFACT_STEM}}.contract.md` `allowed_paths`
+- Concurrency rule: `.ai/harness/active-plan` selects the active plan for this worktree when present; `.ai/harness/active-worktree` records the owning worktree; `.claude/.active-plan` is a legacy fallback during transition. If another worktree already owns active work, open or switch to the matching worktree instead of serializing unrelated plans.
+- Execution isolation: approved contract-level work projects through `scripts/plan-to-todo.sh --plan {{PLAN_FILE}}` and may start `scripts/contract-worktree.sh start --plan {{PLAN_FILE}}`.
+
+## Approach
+### Strategy
+### Trade-offs
+| Option | Pros | Cons | Decision |
+|--------|------|------|----------|
+
+## Detailed Design
+### File Changes
+| File | Action | Description |
+|------|--------|-------------|
+
+### Code Snippets
+### Data Flow
+
+## Risk Assessment
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+
+## Task Contracts
+- Contract file: `tasks/contracts/{{ARTIFACT_STEM}}.contract.md`
+- Review file: `tasks/reviews/{{ARTIFACT_STEM}}.review.md`
+- Implementation notes file: `tasks/notes/{{ARTIFACT_STEM}}.notes.md`
+- Template: `.claude/templates/contract.template.md`
+- Verification command: `bash scripts/verify-contract.sh --contract tasks/contracts/{{ARTIFACT_STEM}}.contract.md --strict`
+- Active plan rule: `.ai/harness/active-plan` is authoritative for this worktree when present; `.ai/harness/active-worktree` records the owning worktree; `.claude/.active-plan` is a legacy fallback during transition. Do not infer active execution from the latest non-archived plan.
+
+## Handoff
+
+- Checks file: `.ai/harness/checks/latest.json`
+- Session handoff: `.ai/harness/handoff/current.md`
+
+## Evidence Contract
+
+- **State/progress path**:
+- **Verification evidence**:
+- **Evaluator rubric**:
+- **Stop condition**:
+- **Rollback surface**:
+
+## Annotations
+<!-- [NOTE]: prefixed inline. Claude processes all and revises. -->
+
+## Task Breakdown
+- [ ] ...
+PLAN_TEMPLATE_EOF
+fi
+
+base_name="plan-${timestamp}-${slug}.md"
+plan_file="plans/${base_name}"
+counter=2
+while [[ -f "$plan_file" ]]; do
+  plan_file="plans/plan-${timestamp}-${slug}-v${counter}.md"
+  counter=$((counter + 1))
+done
+artifact_stem="$(basename "$plan_file" .md | sed -E 's/^plan-//')"
+
+slug_esc="$(escape_sed_replacement "$slug")"
+artifact_stem_esc="$(escape_sed_replacement "$artifact_stem")"
+title_esc="$(escape_sed_replacement "$title")"
+timestamp_esc="$(escape_sed_replacement "$timestamp")"
+
+sed \
+  -e "s/{{SLUG}}/${slug_esc}/g" \
+  -e "s/{{ARTIFACT_STEM}}/${artifact_stem_esc}/g" \
+  -e "s/{{TITLE}}/${title_esc}/g" \
+  -e "s/{{TIMESTAMP}}/${timestamp_esc}/g" \
+  -e "s|{{PLAN_FILE}}|${plan_file}|g" \
+  "$template_file" \
+  | sed \
+    -e "s|tasks/contracts/${slug_esc}\\.contract\\.md|tasks/contracts/${artifact_stem_esc}.contract.md|g" \
+    -e "s|tasks/reviews/${slug_esc}\\.review\\.md|tasks/reviews/${artifact_stem_esc}.review.md|g" \
+    -e "s|tasks/notes/${slug_esc}\\.notes\\.md|tasks/notes/${artifact_stem_esc}.notes.md|g" \
+    > "$plan_file"
+
+echo "Created plan: $plan_file"