@jiggai/recipes 0.3.6 → 0.3.8

package/index.ts

@@ -26,6 +26,7 @@ import {
 } from "./src/handlers/install";
 import {
   handleAssign,
+  handleCleanupClosedAssignments,
   handleDispatch,
   handleHandoff,
   handleMoveTicket,
@@ -482,6 +483,19 @@ const recipesPlugin = {
             console.log(JSON.stringify({ ok: true, moved: { from: res.from, to: res.to } }, null, 2));
           });
 
+        cmd
+          .command("cleanup-closed-assignments")
+          .description("Archive assignment stubs for tickets already in work/done (prevents done work resurfacing)")
+          .requiredOption("--team-id <teamId>", "Team id")
+          .option("--ticket <ticketNums...>", "Optional ticket numbers to target (e.g. 0050 0064)")
+          .action(async (options: { teamId?: string; ticket?: string[] }) => {
+            if (!options.teamId) throw new Error("--team-id is required");
+            const res = await handleCleanupClosedAssignments(api, {
+              teamId: options.teamId,
+              ticketNums: options.ticket,
+            });
+            console.log(JSON.stringify(res, null, 2));
+          });
 
         cmd
           .command("assign")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "ClawRecipes plugin for OpenClaw (markdown recipes -> scaffold agents/teams)",
   "main": "index.ts",
   "type": "commonjs",

package/recipes/default/business-team.md

@@ -59,6 +59,21 @@ agents:
       deny: ["exec"]
 
 templates:
+  tools: |
+    # TOOLS.md
+
+    # Agent-local notes (paths, conventions, env quirks).
+
+  status: |
+    # STATUS.md
+
+    - (empty)
+
+  notes: |
+    # NOTES.md
+
+    - (empty)
+
   lead.soul: |
     # SOUL.md
 

package/recipes/default/clinic-team.md

@@ -59,6 +59,21 @@ agents:
       deny: ["exec"]
 
 templates:
+  tools: |
+    # TOOLS.md
+
+    # Agent-local notes (paths, conventions, env quirks).
+
+  status: |
+    # STATUS.md
+
+    - (empty)
+
+  notes: |
+    # NOTES.md
+
+    - (empty)
+
   lead.soul: |
     # SOUL.md
 

package/recipes/default/construction-team.md

@@ -59,6 +59,21 @@ agents:
       deny: ["exec"]
 
 templates:
+  tools: |
+    # TOOLS.md
+
+    # Agent-local notes (paths, conventions, env quirks).
+
+  status: |
+    # STATUS.md
+
+    - (empty)
+
+  notes: |
+    # NOTES.md
+
+    - (empty)
+
   lead.soul: |
     # SOUL.md
 

package/recipes/default/crypto-trader-team.md

@@ -59,6 +59,21 @@ agents:
       deny: ["exec"]
 
 templates:
+  tools: |
+    # TOOLS.md
+
+    # Agent-local notes (paths, conventions, env quirks).
+
+  status: |
+    # STATUS.md
+
+    - (empty)
+
+  notes: |
+    # NOTES.md
+
+    - (empty)
+
   lead.soul: |
     # SOUL.md
 

package/recipes/default/financial-planner-team.md

@@ -59,6 +59,21 @@ agents:
       deny: ["exec"]
 
 templates:
+  tools: |
+    # TOOLS.md
+
+    # Agent-local notes (paths, conventions, env quirks).
+
+  status: |
+    # STATUS.md
+
+    - (empty)
+
+  notes: |
+    # NOTES.md
+
+    - (empty)
+
   lead.soul: |
     # SOUL.md
 

package/recipes/default/law-firm-team.md

@@ -59,6 +59,21 @@ agents:
       deny: ["exec"]
 
 templates:
+  tools: |
+    # TOOLS.md
+
+    # Agent-local notes (paths, conventions, env quirks).
+
+  status: |
+    # STATUS.md
+
+    - (empty)
+
+  notes: |
+    # NOTES.md
+
+    - (empty)
+
   lead.soul: |
     # SOUL.md
 

package/recipes/default/swarm-orchestrator.md

@@ -0,0 +1,485 @@
+---
+id: swarm-orchestrator
+name: Swarm Orchestrator
+version: 0.2.0
+description: Scaffold an OpenClaw “orchestrator” workspace that spawns coding agents in tmux + git worktrees and monitors them via a lightweight task registry.
+kind: agent
+requiredSkills: []
+cronJobs:
+  - id: swarm-monitor-loop
+    name: "Swarm monitor loop"
+    schedule: "*/10 * * * *"
+    timezone: "America/New_York"
+    message: "Reminder: swarm monitor loop — run .clawdbot/check-agents.sh to detect stuck/failed tmux agents, PR/CI state, and decide whether to notify or retry. Update .clawdbot/active-tasks.json as needed."
+    enabledByDefault: false
+  - id: swarm-cleanup-loop
+    name: "Swarm cleanup loop"
+    schedule: "17 4 * * *"
+    timezone: "America/New_York"
+    message: "Reminder: swarm cleanup loop — consider running .clawdbot/cleanup.sh to prune completed worktrees, closed PR branches, and dead tmux sessions (safe-by-default; no deletes unless explicitly enabled)."
+    enabledByDefault: false
+
+templates:
+  soul: |
+    # SOUL.md
+
+    You are an orchestration agent (“swarm orchestrator”).
+
+    You do NOT primarily write code.
+
+    Your job is to:
+    - translate business context into sharp prompts + constraints
+    - spawn focused coding agents into isolated git worktrees + tmux sessions
+    - monitor them and steer when needed
+    - only notify a human when a PR is truly ready for review
+
+    Guardrails:
+    - Keep changes small and PR-shaped.
+    - Don’t delete worktrees/branches unless the user explicitly opts in.
+    - Always use the prompt template in `.clawdbot/PROMPT_TEMPLATE.md`.
+
+  agents: |
+    # AGENTS.md
+
+    ## Operating loop
+
+    1) Read `.clawdbot/active-tasks.json`.
+    2) For each task:
+       - confirm tmux session is alive
+       - confirm branch/worktree exists
+       - if configured, check PR/CI status
+    3) Only ping the human when:
+       - a task is blocked and needs a decision
+       - a PR meets the default Definition of Done
+
+    ## Key files
+
+    - `.clawdbot/README.md` — setup + how to use
+    - `.clawdbot/CONVENTIONS.md` — default naming + how to change
+    - `.clawdbot/PROMPT_TEMPLATE.md` — required spawn prompt template
+    - `.clawdbot/TEMPLATE.md` — copy/paste helper for new tasks
+    - `.clawdbot/env.sh` — portable env configuration
+    - `.clawdbot/active-tasks.json` — task registry
+    - `.clawdbot/spawn.sh` — create worktree + start tmux session
+    - `.clawdbot/check-agents.sh` — monitor loop (token-efficient)
+    - `.clawdbot/cleanup.sh` — safe-by-default cleanup scaffold
+
+  readme: |
+    # Swarm Orchestrator
+
+    This scaffold gives you a lightweight “swarm” workflow:
+
+    - each coding agent runs in its own **git worktree** + **branch**
+    - each agent runs in its own **tmux session** (attach + steer mid-flight)
+    - a simple JSON registry (`active-tasks.json`) makes monitoring deterministic
+
+    The orchestrator’s job is to:
+    1) translate a request into a tight prompt + constraints
+    2) spawn 1+ coding agents in parallel
+    3) monitor progress until a PR is truly ready for review
+
+    ---
+
+    ## 0) Prerequisites
+
+    Required:
+    - `git`
+    - `tmux`
+    - `jq`
+
+    Optional (recommended):
+    - GitHub CLI `gh` (for PR + CI status checks)
+      - run `gh auth login` to authenticate
+
+    Quick check:
+
+    ```bash
+    command -v git  >/dev/null || echo "missing: git"
+    command -v tmux >/dev/null || echo "missing: tmux"
+    command -v jq   >/dev/null || echo "missing: jq"
+
+    # optional:
+    command -v gh   >/dev/null || echo "optional missing: gh (PR/CI monitoring)"
+    ```
+
+    ---
+
+    ## 1) One-time setup
+
+    ### 1.1 Make scripts executable (manual)
+
+    This scaffold does **not** change file permissions automatically.
+
+    Run:
+
+    ```bash
+    chmod +x .clawdbot/*.sh
+    ```
+
+    ### 1.2 Configure environment
+
+    Edit: `.clawdbot/env.sh`
+
+    Set:
+    - `SWARM_REPO_DIR` — absolute path to the repo you want agents to work on
+    - `SWARM_WORKTREE_ROOT` — absolute path where worktrees will be created
+      - recommended: a dedicated folder (NOT inside your repo folder, and NOT inside the OpenClaw workspace)
+    - `SWARM_BASE_REF` — base ref to branch from (default: `origin/main`)
+
+    Optional:
+    - `SWARM_AGENT_RUNNER` — wrapper to start your chosen coding agent CLI (Codex / Claude Code / etc.)
+
+    ---
+
+    ## 2) Conventions (defaults)
+
+    Default conventions are in:
+    - `.clawdbot/CONVENTIONS.md`
+
+    If you want to customize naming or the Definition of Done, change it there.
+
+    ---
+
+    ## 3) Spawning agents
+
+    Basic spawn:
+
+    ```bash
+    ./.clawdbot/spawn.sh <branch-slug> <codex|claude> <tmux-session> [model] [reasoning]
+    ```
+
+    Example:
+
+    ```bash
+    ./.clawdbot/spawn.sh feat/0082-attempt-a codex swarm-0082-a gpt-5.3-codex high
+    ```
+
+    Attach:
+
+    ```bash
+    tmux attach -t swarm-0082-a
+    ```
+
+    Spawning more than one agent = run `spawn.sh` multiple times with different branch slugs + tmux session names.
+
+    ---
+
+    ## 4) Task registry
+
+    File: `.clawdbot/active-tasks.json`
+
+    Keep it accurate. Monitoring should read the registry, not guess.
+
+    ---
+
+    ## 5) Monitoring
+
+    ```bash
+    ./.clawdbot/check-agents.sh
+    ```
+
+    This is intentionally simple and deterministic. Extend it to include PR/CI checks if desired.
+
+    ---
+
+    ## 6) Default Definition of Done (notify-ready)
+
+    A PR is **ready for human review** when:
+    - PR exists
+    - branch is mergeable and up to date with base
+    - CI is green (lint/types/tests as appropriate)
+    - if the PR includes **UI changes**, include screenshots in the PR description
+    - a human still performs the final review + merge decision (default gate)
+
+  conventions: |
+    # Swarm Conventions (Defaults)
+
+    These defaults are designed to be portable across users and repos.
+
+    ## Naming
+
+    ### Branch naming
+
+    Recommended:
+    - `feat/<ticket>-<slug>`
+    - `fix/<ticket>-<slug>`
+
+    Examples:
+    - `feat/0082-swarm-orchestrator`
+    - `fix/0141-login-redirect`
+
+    If you do not use tickets:
+    - `feat/<slug>` / `fix/<slug>` is fine.
+
+    ### tmux session naming
+
+    Recommended:
+    - `swarm-<ticket>-<suffix>`
+
+    Examples:
+    - `swarm-0082-a`
+    - `swarm-0082-b`
+
+    ## Directory layout
+
+    - Orchestrator workspace: OpenClaw agent workspace (scaffold output)
+    - Worktrees root: set via `SWARM_WORKTREE_ROOT` (recommended: dedicated folder outside repo + outside OpenClaw workspace)
+
+    ## Definition of Done (default)
+
+    A PR is ready for human review when:
+    - PR exists
+    - mergeable + up-to-date
+    - CI green
+    - screenshots included *only if UI changes*
+    - human gate remains (default)
+
+  promptTemplate: |
+    # Swarm Coding-Agent Prompt Template
+
+    Copy this template when spawning a coding agent.
+
+    IMPORTANT:
+    - Do not freestyle prompts.
+    - Keep scope tight.
+    - Optimize for a small, reviewable PR.
+
+    ---
+
+    ## Ticket / Goal
+
+    - Ticket (optional): <NNNN>
+    - Goal: <one sentence>
+
+    ## Context
+
+    <why this matters / user story / product intent>
+
+    ## Requirements
+
+    - <requirement 1>
+    - <requirement 2>
+
+    ## Constraints (very important)
+
+    - Keep changes small and PR-shaped.
+    - Avoid refactors unless required to meet the requirements.
+    - If you need clarification, STOP and ask.
+    - If you touch UI, screenshots are required (otherwise omit screenshots).
+
+    ## Definition of Done (default)
+
+    - Code compiles/builds.
+    - CI is green (lint/types/tests as appropriate for this repo).
+    - PR is opened with a clear description.
+    - If UI changed: include before/after screenshots in the PR description.
+    - Do NOT merge. Leave it for human review.
+
+    ## File / Area hints (optional)
+
+    - Focus files:
+      - <path>
+      - <path>
+
+    ## Suggested plan
+
+    1) <step>
+    2) <step>
+
+    ## Deliverables
+
+    - A PR implementing the requirements.
+    - Notes in the PR description: what changed + how to verify.
+
+  taskTemplate: |
+    # Swarm Task Template
+
+    Use this as a starting point for a new entry in `active-tasks.json`.
+
+    - Decide the branch name using `CONVENTIONS.md`.
+    - Decide a unique tmux session name.
+
+    ```json
+    {
+      "id": "0082-attempt-a",
+      "ticket": "0082",
+      "description": "<short description>",
+      "branch": "feat/0082-attempt-a",
+      "worktree": "feat/0082-attempt-a",
+      "tmuxSession": "swarm-0082-a",
+      "agent": "codex",
+      "model": "gpt-5.3-codex",
+      "startedAt": 0,
+      "status": "queued",
+      "notifyOnComplete": true,
+      "prUrl": null,
+      "checks": {}
+    }
+    ```
+
+  env: |
+    # .clawdbot/env.sh
+    #
+    # Configure these for your environment.
+
+    # Absolute path to the repo you want to operate on.
+    export SWARM_REPO_DIR=""
+
+    # Absolute path where worktrees will be created.
+    # Recommended: a dedicated folder (NOT inside the repo folder, NOT inside the OpenClaw workspace).
+    export SWARM_WORKTREE_ROOT=""
+
+    # Default base ref to branch from.
+    export SWARM_BASE_REF="origin/main"
+
+    # Optional: path to your agent runner wrapper.
+    # This script/command should start Codex/Claude Code/etc inside the worktree.
+    export SWARM_AGENT_RUNNER=""
+
+  activeTasks: |
+    [
+      {
+        "id": "example-task",
+        "ticket": "",
+        "description": "Replace me",
+        "repo": "",
+        "worktree": "",
+        "branch": "",
+        "tmuxSession": "",
+        "agent": "codex",
+        "model": "",
+        "startedAt": 0,
+        "status": "queued",
+        "notifyOnComplete": true,
+        "prUrl": null,
+        "checks": {}
+      }
+    ]
+
+  spawn: |
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    # shellcheck disable=SC1091
+    source "$HERE/env.sh"
+
+    if [[ -z "${SWARM_REPO_DIR:-}" || -z "${SWARM_WORKTREE_ROOT:-}" || -z "${SWARM_BASE_REF:-}" ]]; then
+      echo "Missing env. Edit $HERE/env.sh (SWARM_REPO_DIR, SWARM_WORKTREE_ROOT, SWARM_BASE_REF)." >&2
+      exit 2
+    fi
+
+    BRANCH_SLUG="${1:-}"
+    AGENT_KIND="${2:-codex}"          # codex|claude
+    TMUX_SESSION="${3:-}"
+    MODEL="${4:-}"
+    REASONING="${5:-medium}"
+
+    if [[ -z "$BRANCH_SLUG" || -z "$TMUX_SESSION" ]]; then
+      echo "Usage: $0 <branch-slug> <codex|claude> <tmux-session> [model] [reasoning]" >&2
+      exit 2
+    fi
+
+    WORKTREE_DIR="$SWARM_WORKTREE_ROOT/$BRANCH_SLUG"
+
+    echo "[swarm] Creating worktree: $WORKTREE_DIR"
+    mkdir -p "$SWARM_WORKTREE_ROOT"
+    cd "$SWARM_REPO_DIR"
+
+    git worktree add "$WORKTREE_DIR" -b "$BRANCH_SLUG" "$SWARM_BASE_REF"
+
+    echo "[swarm] Starting tmux session: $TMUX_SESSION"
+    if [[ -z "${SWARM_AGENT_RUNNER:-}" ]]; then
+      echo "SWARM_AGENT_RUNNER not set. Starting a shell in tmux; run your agent CLI manually." >&2
+      tmux new-session -d -s "$TMUX_SESSION" -c "$WORKTREE_DIR" "bash"
+    else
+      tmux new-session -d -s "$TMUX_SESSION" -c "$WORKTREE_DIR" \
+        "$SWARM_AGENT_RUNNER $AGENT_KIND ${MODEL:-} ${REASONING:-medium}"
+    fi
+
+    echo "[swarm] Done. Attach with: tmux attach -t $TMUX_SESSION"
+
+  checkAgents: |
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    REG="$HERE/active-tasks.json"
+
+    if [[ ! -f "$REG" ]]; then
+      echo "Missing $REG" >&2
+      exit 2
+    fi
+
+    echo "[swarm] Checking tmux sessions listed in active-tasks.json ..."
+
+    if ! command -v jq >/dev/null 2>&1; then
+      echo "jq is required" >&2
+      exit 2
+    fi
+
+    mapfile -t sessions < <(jq -r '.[].tmuxSession // empty' "$REG" | sort -u)
+    if [[ ${#sessions[@]} -eq 0 ]]; then
+      echo "[swarm] No tmux sessions found in registry."
+      exit 0
+    fi
+
+    for s in "${sessions[@]}"; do
+      if tmux has-session -t "$s" 2>/dev/null; then
+        echo "[ok] tmux session alive: $s"
+      else
+        echo "[dead] tmux session missing: $s"
+      fi
+    done
+
+  cleanup: |
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    echo "[swarm] Cleanup scaffold (safe-by-default)."
+    echo "- This script currently does NOT delete anything automatically."
+    echo "- Extend it to prune worktrees only after PRs are merged and branches are removed."
+
+files:
+  - path: SOUL.md
+    template: soul
+    mode: createOnly
+  - path: AGENTS.md
+    template: agents
+    mode: createOnly
+  - path: .clawdbot/README.md
+    template: readme
+    mode: createOnly
+  - path: .clawdbot/CONVENTIONS.md
+    template: conventions
+    mode: createOnly
+  - path: .clawdbot/PROMPT_TEMPLATE.md
+    template: promptTemplate
+    mode: createOnly
+  - path: .clawdbot/TEMPLATE.md
+    template: taskTemplate
+    mode: createOnly
+  - path: .clawdbot/env.sh
+    template: env
+    mode: createOnly
+  - path: .clawdbot/active-tasks.json
+    template: activeTasks
+    mode: createOnly
+  - path: .clawdbot/spawn.sh
+    template: spawn
+    mode: createOnly
+  - path: .clawdbot/check-agents.sh
+    template: checkAgents
+    mode: createOnly
+  - path: .clawdbot/cleanup.sh
+    template: cleanup
+    mode: createOnly
+
+tools:
+  profile: "coding"
+  allow: ["group:fs", "group:web", "group:runtime", "group:automation", "cron", "message"]
+  deny: []
+---
+# Swarm Orchestrator
+
+This is a workflow scaffold recipe. It creates a portable, file-first setup for running multiple coding agents in parallel using git worktrees + tmux.

package/src/handlers/scaffold.ts

@@ -34,17 +34,56 @@ export async function scaffoldAgentFromRecipe(
 ) {
   await ensureDir(opts.filesRootDir);
 
-  const templates = recipe.templates ?? {};
-  const files = recipe.files ?? [];
+  type RecipeFileMode = "createOnly" | "overwrite";
+  type RecipeFileSpec = {
+    path: string;
+    template: string;
+    mode?: RecipeFileMode;
+  };
+
+  function normalizeTemplates(input: unknown): Record<string, string> {
+    if (!input) return {};
+    if (typeof input !== "object") throw new Error("recipe.templates must be an object");
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(input as Record<string, unknown>)) {
+      if (typeof v === "string") out[k] = v;
+    }
+    return out;
+  }
+
+  function normalizeFiles(input: unknown): RecipeFileSpec[] {
+    if (!input) return [];
+    if (!Array.isArray(input)) throw new Error("recipe.files must be an array");
+
+    return input.map((raw, idx) => {
+      if (!raw || typeof raw !== "object") throw new Error(`recipe.files[${idx}] must be an object`);
+      const o = raw as Record<string, unknown>;
+      const filePath = String(o.path ?? "").trim();
+      const template = String(o.template ?? "").trim();
+      const modeRaw = o.mode != null ? String(o.mode).trim() : "";
+
+      if (!filePath) throw new Error(`recipe.files[${idx}].path is required`);
+      if (!template) throw new Error(`recipe.files[${idx}].template is required`);
+
+      const mode: RecipeFileMode | undefined =
+        modeRaw === "createOnly" || modeRaw === "overwrite" ? (modeRaw as RecipeFileMode) : undefined;
+      if (modeRaw && !mode) throw new Error(`recipe.files[${idx}].mode must be createOnly|overwrite`);
+
+      return { path: filePath, template, mode };
+    });
+  }
+
+  const templates = normalizeTemplates(recipe.templates);
+  const files = normalizeFiles(recipe.files);
   const vars = opts.vars ?? {};
 
   const fileResults: Array<{ path: string; wrote: boolean; reason: string }> = [];
   for (const f of files) {
     const raw = templates[f.template];
-    if (typeof raw !== "string") throw new Error(`Missing template: ${f.template}`);
+    if (typeof raw !== "string") throw new Error(`Missing template: ${String(f.template)}`);
     const rendered = renderTemplate(raw, vars);
     const target = path.join(opts.filesRootDir, f.path);
-    const mode = opts.update ? (f.mode ?? "overwrite") : (f.mode ?? "createOnly");
+    const mode: RecipeFileMode = opts.update ? (f.mode ?? "overwrite") : (f.mode ?? "createOnly");
     const r = await writeFileSafely(target, rendered, mode);
     fileResults.push({ path: target, wrote: r.wrote, reason: r.reason });
   }

package/src/handlers/tickets.ts

@@ -325,3 +325,59 @@ export async function handleDispatch(
   }
   return { ok: true as const, wrote: plan.files.map((f) => f.path), nudgeQueued };
 }
+
+/**
+ * Cleanup assignment stubs for tickets that are already closed (in work/done).
+ *
+ * Why: some automation/board views treat assignment stubs as active work signals.
+ * If a ticket is manually moved to done (outside `openclaw recipes move-ticket`),
+ * its `work/assignments/<num>-assigned-*.md` stubs may linger and resurface the ticket.
+ *
+ * This command archives any matching assignment stubs into `work/assignments/archive/`.
+ */
+export async function handleCleanupClosedAssignments(
+  api: OpenClawPluginApi,
+  options: { teamId: string; ticketNums?: string[] }
+): Promise<{ ok: true; teamId: string; archived: Array<{ from: string; to: string }> }> {
+  const teamId = String(options.teamId);
+  const { teamDir } = await resolveTeamContext(api, teamId);
+
+  const assignmentsDir = ticketStageDir(teamDir, "assignments");
+  const archiveDir = path.join(assignmentsDir, "archive");
+  const doneDir = ticketStageDir(teamDir, "done");
+
+  const archived: Array<{ from: string; to: string }> = [];
+  if (!(await fileExists(assignmentsDir))) return { ok: true, teamId, archived };
+  await ensureDir(archiveDir);
+
+  const ticketNumsFilter = Array.isArray(options.ticketNums) && options.ticketNums.length
+    ? new Set(options.ticketNums.map((n) => String(n).padStart(4, "0")))
+    : null;
+
+  const doneFiles = (await fileExists(doneDir)) ? await fs.readdir(doneDir) : [];
+  const doneNums = new Set(
+    doneFiles
+      .map((f) => f.match(/^([0-9]{4})-/)?.[1])
+      .filter((x): x is string => !!x)
+  );
+
+  const files = (await fs.readdir(assignmentsDir)).filter((f) => f.endsWith(".md"));
+  for (const f of files) {
+    if (f === "archive") continue;
+    if (f.startsWith("archive" + path.sep)) continue;
+    const m = f.match(/^([0-9]{4})-assigned-.*\.md$/);
+    if (!m) continue;
+    const num = m[1];
+    if (ticketNumsFilter && !ticketNumsFilter.has(num)) continue;
+
+    // If the ticket number is present in done/, this assignment is considered closed.
+    if (!doneNums.has(num)) continue;
+
+    const from = path.join(assignmentsDir, f);
+    const to = path.join(archiveDir, f);
+    await fs.rename(from, to);
+    archived.push({ from, to });
+  }
+
+  return { ok: true, teamId, archived };
+}