@jiggai/recipes 0.2.11

package/src/lib/lanes.ts

@@ -0,0 +1,63 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export type TicketLane = 'backlog' | 'in-progress' | 'testing' | 'done' | 'assignments';
+
+export class RecipesCliError extends Error {
+  code: string;
+  command?: string;
+  missingPath?: string;
+  suggestedFix?: string;
+
+  constructor(opts: { message: string; code: string; command?: string; missingPath?: string; suggestedFix?: string }) {
+    super(opts.message);
+    this.name = 'RecipesCliError';
+    this.code = opts.code;
+    this.command = opts.command;
+    this.missingPath = opts.missingPath;
+    this.suggestedFix = opts.suggestedFix;
+  }
+}
+
+async function fileExists(p: string) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure a lane dir exists, with a one-line migration hint for older workspaces.
+ *
+ * If creation fails, throws a RecipesCliError with an actionable message.
+ */
+export async function ensureLaneDir(opts: { teamDir: string; lane: TicketLane; command?: string; quiet?: boolean }) {
+  const laneDir = path.join(opts.teamDir, 'work', opts.lane);
+  const existed = await fileExists(laneDir);
+
+  if (!existed) {
+    try {
+      await fs.mkdir(laneDir, { recursive: true });
+    } catch (e: any) {
+      throw new RecipesCliError({
+        code: 'LANE_DIR_CREATE_FAILED',
+        command: opts.command,
+        missingPath: laneDir,
+        suggestedFix: `mkdir -p ${path.join('work', opts.lane)}`,
+        message:
+          `Failed to create required lane directory: ${laneDir}` +
+          (opts.command ? ` (command: ${opts.command})` : '') +
+          (e?.message ? `\nUnderlying error: ${String(e.message)}` : ''),
+      });
+    }
+
+    if (!opts.quiet) {
+      const rel = path.join('work', opts.lane);
+      console.error(`[recipes] migration: created ${rel}/ (older workspace missing this lane)`);
+    }
+  }
+
+  return { path: laneDir, created: !existed };
+}

package/src/lib/recipe-frontmatter.ts

@@ -0,0 +1,59 @@
+import YAML from 'yaml';
+
+export type CronJobSpec = {
+  id: string;
+  schedule: string;
+  message: string;
+  name?: string;
+  description?: string;
+  timezone?: string;
+  channel?: string;
+  to?: string;
+  agentId?: string;
+  enabledByDefault?: boolean;
+};
+
+export type RecipeFrontmatter = {
+  id: string;
+  kind?: string;
+  name?: string;
+  cronJobs?: CronJobSpec[];
+  [k: string]: any;
+};
+
+export function parseFrontmatter(md: string): { frontmatter: RecipeFrontmatter; body: string } {
+  if (!md.startsWith('---\n')) throw new Error('Recipe markdown must start with YAML frontmatter (---)');
+  const end = md.indexOf('\n---\n', 4);
+  if (end === -1) throw new Error('Recipe frontmatter not terminated (---)');
+  const yamlText = md.slice(4, end);
+  const body = md.slice(end + 5);
+  const frontmatter = YAML.parse(yamlText) as RecipeFrontmatter;
+  if (!frontmatter?.id) throw new Error('Recipe frontmatter must include id');
+  return { frontmatter, body };
+}
+
+export function normalizeCronJobs(frontmatter: { cronJobs?: any }): CronJobSpec[] {
+  const raw = (frontmatter as any).cronJobs;
+  if (!raw) return [];
+  if (!Array.isArray(raw)) throw new Error('frontmatter.cronJobs must be an array');
+
+  const seen = new Set<string>();
+  const out: CronJobSpec[] = [];
+
+  for (const j of raw) {
+    if (!j || typeof j !== 'object') throw new Error('cronJobs entries must be objects');
+    const id = String((j as any).id ?? '').trim();
+    if (!id) throw new Error('cronJobs[].id is required');
+    if (seen.has(id)) throw new Error(`Duplicate cronJobs[].id: ${id}`);
+    seen.add(id);
+
+    const schedule = String((j as any).schedule ?? '').trim();
+    const message = String((j as any).message ?? '').trim();
+    if (!schedule) throw new Error(`cronJobs[${id}].schedule is required`);
+    if (!message) throw new Error(`cronJobs[${id}].message is required`);
+
+    out.push({ ...j, id, schedule, message } as CronJobSpec);
+  }
+
+  return out;
+}

package/src/lib/remove-team.ts

@@ -0,0 +1,200 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export type CronJob = {
+  id: string;
+  name?: string;
+  enabled?: boolean;
+  schedule?: any;
+  payload?: { kind?: string; message?: string };
+  delivery?: any;
+  agentId?: string;
+};
+
+export type CronStore = {
+  version: number;
+  jobs: CronJob[];
+};
+
+export type RemoveTeamPlan = {
+  teamId: string;
+  workspaceDir: string;
+  openclawConfigPath: string;
+  cronJobsPath: string;
+  agentsToRemove: string[];
+  cronJobsExact: Array<{ id: string; name?: string }>;
+  cronJobsAmbiguous: Array<{ id: string; name?: string; reason: string }>;
+  notes: string[];
+};
+
+export type RemoveTeamResult = {
+  ok: true;
+  plan: RemoveTeamPlan;
+  removed: {
+    workspaceDir: "deleted" | "missing";
+    agentsRemoved: number;
+    cronJobsRemoved: number;
+  };
+};
+
+export function stampTeamId(teamId: string) {
+  return `recipes.teamId=${teamId}`;
+}
+
+export function isProtectedTeamId(teamId: string) {
+  const t = teamId.trim().toLowerCase();
+  return t === "development-team" || t === "main";
+}
+
+export async function fileExists(p: string) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function loadCronStore(cronJobsPath: string): Promise<CronStore> {
+  const raw = await fs.readFile(cronJobsPath, "utf8");
+  const data = JSON.parse(raw) as CronStore;
+  if (!data || typeof data !== "object" || !Array.isArray((data as any).jobs)) {
+    throw new Error(`Invalid cron store: ${cronJobsPath}`);
+  }
+  return data;
+}
+
+export async function saveCronStore(cronJobsPath: string, store: CronStore) {
+  await fs.writeFile(cronJobsPath, JSON.stringify(store, null, 2) + "\n", "utf8");
+}
+
+export async function loadOpenClawConfig(openclawConfigPath: string): Promise<any> {
+  const raw = await fs.readFile(openclawConfigPath, "utf8");
+  // NOTE: openclaw.json is JSON5 in some deployments; but we avoid adding dependency here.
+  // The main plugin already depends on json5; callers may parse using that. For remove-team, keep strict JSON.
+  return JSON.parse(raw);
+}
+
+export async function saveOpenClawConfig(openclawConfigPath: string, cfg: any) {
+  await fs.writeFile(openclawConfigPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+
+export function findAgentsToRemove(cfgObj: any, teamId: string) {
+  const list = cfgObj?.agents?.list;
+  if (!Array.isArray(list)) return [] as string[];
+  const prefix = `${teamId}-`;
+  return list
+    .map((a: any) => String(a?.id ?? ""))
+    .filter((id: string) => id && id.startsWith(prefix));
+}
+
+export function planCronJobRemovals(jobs: CronJob[], teamId: string) {
+  const stamp = stampTeamId(teamId);
+  const exact: Array<{ id: string; name?: string }> = [];
+  const ambiguous: Array<{ id: string; name?: string; reason: string }> = [];
+
+  for (const j of jobs) {
+    const msg = String(j?.payload?.message ?? "");
+    const name = String(j?.name ?? "");
+
+    // Exact: message contains the stamp.
+    if (msg.includes(stamp)) {
+      exact.push({ id: j.id, name: j.name });
+      continue;
+    }
+
+    // Ambiguous: name mentions teamId (helpful for manual review).
+    if (name.includes(teamId) || msg.includes(teamId)) {
+      ambiguous.push({ id: j.id, name: j.name, reason: "mentions-teamId" });
+    }
+  }
+
+  return { exact, ambiguous };
+}
+
+export async function buildRemoveTeamPlan(opts: {
+  teamId: string;
+  workspaceRoot: string; // e.g. ~/.openclaw/workspace
+  openclawConfigPath: string; // e.g. ~/.openclaw/openclaw.json
+  cronJobsPath: string; // e.g. ~/.openclaw/cron/jobs.json
+  cfgObj: any;
+  cronStore?: CronStore | null;
+}) {
+  const teamId = opts.teamId.trim();
+  const workspaceDir = path.resolve(path.join(opts.workspaceRoot, "..", `workspace-${teamId}`));
+
+  const notes: string[] = [];
+  if (isProtectedTeamId(teamId)) notes.push(`protected-team:${teamId}`);
+
+  const agentsToRemove = findAgentsToRemove(opts.cfgObj, teamId);
+
+  const jobs = (opts.cronStore?.jobs ?? []) as CronJob[];
+  const cron = planCronJobRemovals(jobs, teamId);
+
+  const plan: RemoveTeamPlan = {
+    teamId,
+    workspaceDir,
+    openclawConfigPath: opts.openclawConfigPath,
+    cronJobsPath: opts.cronJobsPath,
+    agentsToRemove,
+    cronJobsExact: cron.exact,
+    cronJobsAmbiguous: cron.ambiguous,
+    notes,
+  };
+
+  return plan;
+}
+
+export async function executeRemoveTeamPlan(opts: {
+  plan: RemoveTeamPlan;
+  includeAmbiguous?: boolean;
+  cfgObj: any;
+  cronStore: CronStore;
+}) {
+  const { plan } = opts;
+  const teamId = plan.teamId;
+
+  if (isProtectedTeamId(teamId)) {
+    throw new Error(`Refusing to remove protected team: ${teamId}`);
+  }
+
+  // 1) Delete workspace dir
+  const workspaceExists = await fileExists(plan.workspaceDir);
+  if (workspaceExists) {
+    await fs.rm(plan.workspaceDir, { recursive: true, force: true });
+  }
+
+  // 2) Remove agents from config
+  const list = opts.cfgObj?.agents?.list;
+  const before = Array.isArray(list) ? list.length : 0;
+  if (Array.isArray(list)) {
+    const remove = new Set(plan.agentsToRemove);
+    opts.cfgObj.agents.list = list.filter((a: any) => !remove.has(String(a?.id ?? "")));
+  }
+  const after = Array.isArray(opts.cfgObj?.agents?.list) ? opts.cfgObj.agents.list.length : 0;
+
+  // 3) Remove cron jobs from store
+  const exactIds = new Set(plan.cronJobsExact.map((j) => j.id));
+  const ambiguousIds = new Set(plan.cronJobsAmbiguous.map((j) => j.id));
+
+  const removeIds = new Set<string>([...exactIds]);
+  if (opts.includeAmbiguous) {
+    for (const id of ambiguousIds) removeIds.add(id);
+  }
+
+  const beforeJobs = opts.cronStore.jobs.length;
+  opts.cronStore.jobs = opts.cronStore.jobs.filter((j) => !removeIds.has(j.id));
+  const afterJobs = opts.cronStore.jobs.length;
+
+  const result: RemoveTeamResult = {
+    ok: true,
+    plan,
+    removed: {
+      workspaceDir: workspaceExists ? "deleted" : "missing",
+      agentsRemoved: Math.max(0, before - after),
+      cronJobsRemoved: Math.max(0, beforeJobs - afterJobs),
+    },
+  };
+
+  return result;
+}

package/src/lib/scaffold-templates.ts

@@ -0,0 +1,7 @@
+export function renderTeamMd(teamId: string) {
+  return `# ${teamId}\n\nShared workspace for this agent team.\n\n## Workflow\n- Stages: backlog → in-progress → testing → done\n- Backlog: work/backlog/\n- In progress: work/in-progress/\n- Testing / QA: work/testing/\n- Done: work/done/\n\n## QA verification\nBefore moving a ticket from work/testing/ → work/done/, record verification results.\n- Template: notes/QA_CHECKLIST.md\n- Preferred: create work/testing/<ticket>.testing-verified.md\n\n## Folders\n- inbox/ — requests\n- outbox/ — deliverables\n- shared-context/ — curated shared context + append-only agent outputs\n- shared/ — legacy shared artifacts (back-compat)\n- notes/ — plan + status + templates\n- work/ — working files\n`;
+}
+
+export function renderTicketsMd(teamId: string) {
+  return `# Tickets — ${teamId}\n\n## Workflow\n- Stages: backlog → in-progress → testing → done\n- Backlog tickets live in work/backlog/\n- In-progress tickets live in work/in-progress/\n- Testing / QA tickets live in work/testing/\n- Done tickets live in work/done/\n\n### QA handoff (dev → test)\nWhen development is complete:\n- Move the ticket file to work/testing/\n- Assign to test (set \`Owner: test\`)\n- Add clear test instructions / repro steps\n\n### QA verification (test → done)\nBefore moving a ticket to done, QA must record verification.\n- Template: notes/QA_CHECKLIST.md\n- Preferred: create work/testing/<ticket>.testing-verified.md\n\n## Naming\n- Filename ordering is the queue: 0001-..., 0002-...\n\n## Required fields\nEach ticket should include:\n- Title\n- Context\n- Requirements\n- Acceptance criteria\n- Owner (dev/devops/lead/test)\n- Status (queued/in-progress/testing/done)\n\n## Example\n\n\`\`\`md\n# 0001-example-ticket\n\nOwner: dev\nStatus: queued\n\n## Context\n...\n\n## Requirements\n- ...\n\n## Acceptance criteria\n- ...\n\n## How to test\n- ...\n\`\`\`\n`;
+}

package/src/lib/shared-context.ts

@@ -0,0 +1,52 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+async function ensureDir(p: string) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+async function exists(p: string) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeCreateOnlyOrOverwrite(filePath: string, content: string, mode: 'createOnly' | 'overwrite') {
+  if (mode === 'createOnly' && (await exists(filePath))) return { wrote: false as const };
+  await fs.writeFile(filePath, content, 'utf8');
+  return { wrote: true as const };
+}
+
+export async function ensureSharedContextScaffold(opts: { teamDir: string; teamId: string; overwrite: boolean }) {
+  const { teamDir, teamId, overwrite } = opts;
+  const sharedContextDir = path.join(teamDir, 'shared-context');
+  const outputsDir = path.join(sharedContextDir, 'agent-outputs');
+  const feedbackDir = path.join(sharedContextDir, 'feedback');
+  const kpisDir = path.join(sharedContextDir, 'kpis');
+  const calendarDir = path.join(sharedContextDir, 'calendar');
+
+  await Promise.all([
+    // Back-compat alias: keep shared/ folder.
+    ensureDir(path.join(teamDir, 'shared')),
+    ensureDir(sharedContextDir),
+    ensureDir(outputsDir),
+    ensureDir(feedbackDir),
+    ensureDir(kpisDir),
+    ensureDir(calendarDir),
+  ]);
+
+  const prioritiesPath = path.join(sharedContextDir, 'priorities.md');
+  const prioritiesMd = `# Priorities — ${teamId}\n\n- (empty)\n\n## Notes\n- Lead curates this file.\n- Non-lead roles should append updates to shared-context/agent-outputs/ instead.\n`;
+
+  const mode = overwrite ? 'overwrite' : 'createOnly';
+  const wrote = await writeCreateOnlyOrOverwrite(prioritiesPath, prioritiesMd, mode);
+
+  return {
+    sharedContextDir,
+    prioritiesPath,
+    wrotePriorities: wrote.wrote,
+  };
+}

package/src/lib/ticket-finder.ts

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+async function fileExists(p: string) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export type TicketLane = 'backlog' | 'in-progress' | 'testing' | 'done';
+
+export function laneDir(teamDir: string, lane: TicketLane) {
+  return path.join(teamDir, 'work', lane);
+}
+
+export function allLaneDirs(teamDir: string) {
+  return [
+    laneDir(teamDir, 'backlog'),
+    laneDir(teamDir, 'in-progress'),
+    laneDir(teamDir, 'testing'),
+    laneDir(teamDir, 'done'),
+  ];
+}
+
+export function parseTicketArg(ticketArg: string) {
+  const ticketNum = ticketArg.match(/^\d{4}$/)
+    ? ticketArg
+    : (ticketArg.match(/^(\d{4})-/)?.[1] ?? null);
+  return { ticketArg, ticketNum };
+}
+
+export async function findTicketFile(opts: {
+  teamDir: string;
+  ticket: string;
+  lanes?: TicketLane[];
+}) {
+  const lanes = opts.lanes ?? ['backlog', 'in-progress', 'testing', 'done'];
+  const { ticketArg, ticketNum } = parseTicketArg(String(opts.ticket));
+
+  for (const lane of lanes) {
+    const dir = laneDir(opts.teamDir, lane);
+    if (!(await fileExists(dir))) continue;
+    const files = await fs.readdir(dir);
+    for (const f of files) {
+      if (!f.endsWith('.md')) continue;
+      if (ticketNum && f.startsWith(`${ticketNum}-`)) return path.join(dir, f);
+      if (!ticketNum && f.replace(/\.md$/, '') === ticketArg) return path.join(dir, f);
+    }
+  }
+
+  return null;
+}
+
+export function parseOwnerFromMd(md: string): string | null {
+  const m = md.match(/^Owner:\s*(.+)\s*$/m);
+  return m?.[1]?.trim() ?? null;
+}

package/src/lib/ticket-workflow.ts

@@ -0,0 +1,153 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { ensureLaneDir } from './lanes';
+
+async function fileExists(p: string) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureDir(p: string) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+export async function findTicketFile(teamDir: string, ticketArg: string) {
+  const stageDir = (stage: string) => path.join(teamDir, 'work', stage);
+  const searchDirs = [stageDir('backlog'), stageDir('in-progress'), stageDir('testing'), stageDir('done')];
+
+  const ticketNum = ticketArg.match(/^\d{4}$/) ? ticketArg : (ticketArg.match(/^(\d{4})-/)?.[1] ?? null);
+
+  for (const dir of searchDirs) {
+    if (!(await fileExists(dir))) continue;
+    const files = await fs.readdir(dir);
+    for (const f of files) {
+      if (!f.endsWith('.md')) continue;
+      if (ticketNum && f.startsWith(`${ticketNum}-`)) return path.join(dir, f);
+      if (!ticketNum && f.replace(/\.md$/, '') === ticketArg) return path.join(dir, f);
+    }
+  }
+  return null;
+}
+
+export async function takeTicket(opts: { teamDir: string; ticket: string; owner?: string; overwriteAssignment: boolean }) {
+  const teamDir = opts.teamDir;
+  const owner = (opts.owner ?? 'dev').trim() || 'dev';
+  const ownerSafe = owner.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/(^-|-$)/g, '') || 'dev';
+
+  const srcPath = await findTicketFile(teamDir, opts.ticket);
+  if (!srcPath) throw new Error(`Ticket not found: ${opts.ticket}`);
+  if (srcPath.includes(`${path.sep}work${path.sep}done${path.sep}`)) throw new Error('Cannot take a done ticket (already completed)');
+
+  const inProgressDir = (await ensureLaneDir({ teamDir, lane: 'in-progress', command: 'openclaw recipes take' })).path;
+
+  const filename = path.basename(srcPath);
+  const destPath = path.join(inProgressDir, filename);
+
+  const m = filename.match(/^(\d{4})-(.+)\.md$/);
+  const ticketNumStr = m?.[1] ?? (opts.ticket.match(/^\d{4}$/) ? opts.ticket : '0000');
+  const slug = m?.[2] ?? 'ticket';
+
+  const assignmentsDir = path.join(teamDir, 'work', 'assignments');
+  await ensureDir(assignmentsDir);
+  const assignmentPath = path.join(assignmentsDir, `${ticketNumStr}-assigned-${ownerSafe}.md`);
+  const assignmentRel = path.relative(teamDir, assignmentPath);
+
+  const patch = (md: string) => {
+    let out = md;
+    if (out.match(/^Owner:\s.*$/m)) out = out.replace(/^Owner:\s.*$/m, `Owner: ${ownerSafe}`);
+    else out = out.replace(/^(# .+\n)/, `$1\nOwner: ${ownerSafe}\n`);
+
+    if (out.match(/^Status:\s.*$/m)) out = out.replace(/^Status:\s.*$/m, 'Status: in-progress');
+    else out = out.replace(/^(# .+\n)/, `$1\nStatus: in-progress\n`);
+
+    if (out.match(/^Assignment:\s.*$/m)) out = out.replace(/^Assignment:\s.*$/m, `Assignment: ${assignmentRel}`);
+    else out = out.replace(/^Owner:.*$/m, (line) => `${line}\nAssignment: ${assignmentRel}`);
+
+    return out;
+  };
+
+  const alreadyInProgress = srcPath === destPath;
+
+  const md = await fs.readFile(srcPath, 'utf8');
+  const nextMd = patch(md);
+  await fs.writeFile(srcPath, nextMd, 'utf8');
+
+  if (!alreadyInProgress) {
+    await fs.rename(srcPath, destPath);
+  }
+
+  const assignmentMd = `# Assignment — ${ticketNumStr}-${slug}\n\nAssigned: ${ownerSafe}\n\n## Ticket\n${path.relative(teamDir, destPath)}\n\n## Notes\n- Created by: openclaw recipes take\n`;
+
+  const assignmentExists = await fileExists(assignmentPath);
+  if (assignmentExists && !opts.overwriteAssignment) {
+    // createOnly
+  } else {
+    await fs.writeFile(assignmentPath, assignmentMd, 'utf8');
+  }
+
+  return { srcPath, destPath, moved: !alreadyInProgress, assignmentPath };
+}
+
+export async function handoffTicket(opts: { teamDir: string; ticket: string; tester?: string; overwriteAssignment: boolean }) {
+  const teamDir = opts.teamDir;
+  const tester = (opts.tester ?? 'test').trim() || 'test';
+  const testerSafe = tester.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/(^-|-$)/g, '') || 'test';
+
+  const srcPath = await findTicketFile(teamDir, opts.ticket);
+  if (!srcPath) throw new Error(`Ticket not found: ${opts.ticket}`);
+  if (srcPath.includes(`${path.sep}work${path.sep}done${path.sep}`)) throw new Error('Cannot handoff a done ticket (already completed)');
+
+  const testingDir = (await ensureLaneDir({ teamDir, lane: 'testing', command: 'openclaw recipes handoff' })).path;
+
+  const filename = path.basename(srcPath);
+  const destPath = path.join(testingDir, filename);
+
+  const m = filename.match(/^(\d{4})-(.+)\.md$/);
+  const ticketNumStr = m?.[1] ?? (opts.ticket.match(/^\d{4}$/) ? opts.ticket : '0000');
+  const slug = m?.[2] ?? 'ticket';
+
+  const assignmentsDir = path.join(teamDir, 'work', 'assignments');
+  await ensureDir(assignmentsDir);
+  const assignmentPath = path.join(assignmentsDir, `${ticketNumStr}-assigned-${testerSafe}.md`);
+  const assignmentRel = path.relative(teamDir, assignmentPath);
+
+  const patch = (md: string) => {
+    let out = md;
+    if (out.match(/^Owner:\s.*$/m)) out = out.replace(/^Owner:\s.*$/m, `Owner: ${testerSafe}`);
+    else out = out.replace(/^(# .+\n)/, `$1\nOwner: ${testerSafe}\n`);
+
+    if (out.match(/^Status:\s.*$/m)) out = out.replace(/^Status:\s.*$/m, 'Status: testing');
+    else out = out.replace(/^(# .+\n)/, `$1\nStatus: testing\n`);
+
+    if (out.match(/^Assignment:\s.*$/m)) out = out.replace(/^Assignment:\s.*$/m, `Assignment: ${assignmentRel}`);
+    else out = out.replace(/^Owner:.*$/m, (line) => `${line}\nAssignment: ${assignmentRel}`);
+
+    return out;
+  };
+
+  const alreadyInTesting = srcPath === destPath;
+
+  const md = await fs.readFile(srcPath, 'utf8');
+  const nextMd = patch(md);
+  await fs.writeFile(srcPath, nextMd, 'utf8');
+
+  if (!alreadyInTesting) {
+    await fs.rename(srcPath, destPath);
+  }
+
+  const assignmentMd = `# Assignment — ${ticketNumStr}-${slug}\n\nAssigned: ${testerSafe}\n\n## Ticket\n${path.relative(teamDir, destPath)}\n\n## Notes\n- Created by: openclaw recipes handoff\n`;
+
+  const assignmentExists = await fileExists(assignmentPath);
+  if (assignmentExists && !opts.overwriteAssignment) {
+    // createOnly: leave as-is
+  } else {
+    await fs.writeFile(assignmentPath, assignmentMd, 'utf8');
+  }
+
+  return { srcPath, destPath, moved: !alreadyInTesting, assignmentPath };
+}