agentplane 0.1.3 → 0.1.5

package/README.md

@@ -5,53 +5,83 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/basilisk-labs/agentplane/blob/main/LICENSE)
 [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-3c873a.svg)](https://github.com/basilisk-labs/agentplane/blob/main/docs/user/prerequisites.mdx)
 
-Agent Plane is an offline-first CLI for running policy-driven agent workflows inside real repositories.
-It turns "AI magic" into a predictable process with approvals, role boundaries, and audit-friendly artifacts.
+Agent Plane is a policy-driven framework for running LLM agents inside real repositories. It turns "AI magic" into an engineering process: explicit approvals, role boundaries, and a reproducible execution pipeline. The goal is simple: make agents boring, safe, and auditable.
 
-## Features
+## Why Agent Plane
 
-- Policy-first execution with explicit approvals and guardrails.
-- Role-based workflows for teams: ORCHESTRATOR, PLANNER, CREATOR, INTEGRATOR, etc.
-- Two workflow modes: `direct` (single checkout) and `branch_pr` (worktrees + integration).
-- Task tracking, verification, and exports baked in.
-- Recipes for repeatable setup and automation.
+- You want agents that behave predictably inside real repos.
+- You need human approvals, clear roles, and traceable artifacts.
+- You want guardrails by default, not optional add-ons.
+- You want an offline-first CLI that keeps state local and inspectable.
 
-## Install
+## 5-minute start
+
+Install and initialize the CLI:
 
 ```bash
 npm install -g agentplane
+agentplane init
+agentplane quickstart
 ```
 
-Or run without installing:
+Create your first task and run the workflow:
 
 ```bash
-npx agentplane --help
+agentplane task new --title "First task" --description "Describe the change" --priority med --owner ORCHESTRATOR --tag docs
+agentplane verify <task-id>
+agentplane finish <task-id>
 ```
 
-## Requirements
+Prefer `npx` instead of a global install?
 
-- Node.js >= 20
+```bash
+npx agentplane init
+npx agentplane quickstart
+```
 
-## Quickstart
+## What gets installed automatically
 
-Initialize a repository:
+- `.agentplane/` is created with config, tasks, agents, and caches.
+- `AGENTS.md` is created if missing and defines the policy/guardrails.
+- Built-in agent definitions are copied into `.agentplane/agents/`.
+- Optional recipes can install additional agents when you run `agentplane recipes install ...`.
 
-```bash
-npx agentplane init
+## Guardrails and artifacts
+
+- Approval gates for plans and network access (configured in `.agentplane/config.json`).
+- Role boundaries (ORCHESTRATOR, PLANNER, CODER, INTEGRATOR, etc.).
+- Agent definitions in `.agentplane/agents/`.
+- Task records in `.agentplane/tasks/` with a snapshot export in `.agentplane/tasks.json`.
+- A visible, reproducible pipeline:
+
+```text
+Preflight -> Plan -> Approval -> Tasks -> Verify -> Finish -> Export
 ```
 
-See the built-in quickstart guide:
+## Features
+
+- Policy-first execution with explicit approvals and guardrails.
+- Role-based workflows for teams: ORCHESTRATOR, PLANNER, CREATOR, INTEGRATOR, etc.
+- Two workflow modes: `direct` (single checkout) and `branch_pr` (worktrees + integration).
+- Task tracking, verification, and exports baked in.
+- Recipes for repeatable setup and automation.
+
+## Install
 
 ```bash
-npx agentplane quickstart
+npm install -g agentplane
 ```
 
-Switch workflow mode if you need a structured team flow:
+Or run without installing:
 
 ```bash
-npx agentplane config set workflow_mode branch_pr
+npx agentplane --help
 ```
 
+## Requirements
+
+- Node.js >= 20
+
 ## Common Commands
 
 ```bash
@@ -73,15 +103,6 @@ agentplane recipes list
 - Project layout: https://github.com/basilisk-labs/agentplane/blob/main/docs/developer/project-layout.mdx
 - Recipes: https://github.com/basilisk-labs/agentplane/tree/main/agentplane-recipes
 
-## How it works
-
-Agent Plane expects a repository policy file (`AGENTS.md`) plus a project config (`.agentplane/config.json`).
-Together, they define role boundaries, approval gates, and the execution pipeline:
-
-```text
-Preflight -> Plan -> Approval -> Tasks -> Verify -> Finish -> Export
-```
-
 ## Support
 
 - Issues: https://github.com/basilisk-labs/agentplane/issues

package/dist/agents/agents-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-template.d.ts","sourceRoot":"","sources":["../../src/agents/agents-template.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;AAElD,KAAK,aAAa,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAwC5D,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAanE;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,MAAM,CASvF"}

package/dist/{agents-template.js → agents/agents-template.js}

@@ -1,8 +1,8 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-const AGENTS_TEMPLATE_URL = new URL("../assets/AGENTS.md", import.meta.url);
-const AGENTS_DIR_URL = new URL("../assets/agents/", import.meta.url);
+const AGENTS_TEMPLATE_URL = new URL("../../assets/AGENTS.md", import.meta.url);
+const AGENTS_DIR_URL = new URL("../../assets/agents/", import.meta.url);
 const HEADING_RE = /^(#+)\s+(.*)$/;
 function ensureTrailingNewline(text) {
     return text.endsWith("\n") ? text : `${text}\n`;

package/dist/{task-backend.d.ts → backends/task-backend.d.ts}

@@ -1,6 +1,9 @@
 import { type AgentplaneConfig, type ResolvedProject, type TaskRecord } from "@agentplaneorg/core";
-export declare function extractTaskDoc(body: string): string;
-export declare function mergeTaskDoc(body: string, doc: string): string;
+type ExtractTaskDoc = (body: string) => string;
+type MergeTaskDoc = (body: string, doc: string) => string;
+declare const extractTaskDoc: ExtractTaskDoc;
+declare const mergeTaskDoc: MergeTaskDoc;
+export { extractTaskDoc, mergeTaskDoc };
 export type TaskData = {
     id: string;
     title: string;
@@ -171,5 +174,4 @@ export declare function loadTaskBackend(opts: {
     config: AgentplaneConfig;
     backendConfigPath: string;
 }>;
-export {};
 //# sourceMappingURL=task-backend.d.ts.map

package/dist/backends/task-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-backend.d.ts","sourceRoot":"","sources":["../../src/backends/task-backend.ts"],"names":[],"mappings":"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"}

package/dist/{task-backend.js → backends/task-backend.js}

@@ -1,15 +1,16 @@
-import { createHash, randomInt } from "node:crypto";
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { canonicalizeJson, loadConfig, parseTaskReadme, renderTaskReadme, resolveProject, taskReadmePath, } from "@agentplaneorg/core";
-import { loadDotEnv } from "./env.js";
-const ID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-const TASK_ID_RE = new RegExp(String.raw `^\d{12}-[${ID_ALPHABET}]{4,}$`);
-const DOC_SECTION_HEADER = "## Summary";
-const DOC_SECTION_HEADER_RE = /^##\s+Summary(?:\s|$|#)/;
-const AUTO_SUMMARY_HEADER = "## Changes Summary (auto)";
+import { atomicWriteFile as atomicWriteFileCore, canonicalizeJson, docChanged, extractTaskDoc as extractTaskDocCore, generateTaskId as generateTaskIdCore, loadConfig, mergeTaskDoc as mergeTaskDocCore, parseTaskReadme, renderTaskReadme, resolveProject, TASK_ID_ALPHABET, taskReadmePath, } from "@agentplaneorg/core";
+import { loadDotEnv } from "../shared/env.js";
+import { buildTaskIndexEntry, loadTaskIndex, resolveTaskIndexPath, saveTaskIndex, } from "./task-index.js";
+const TASK_ID_RE = new RegExp(String.raw `^\d{12}-[${TASK_ID_ALPHABET}]{4,}$`);
 const DEFAULT_DOC_UPDATED_BY = "agentplane";
 const DOC_VERSION = 2;
+const atomicWriteFile = atomicWriteFileCore;
+const extractTaskDoc = extractTaskDocCore;
+const mergeTaskDoc = mergeTaskDocCore;
+const generateTaskId = generateTaskIdCore;
 function nowIso() {
     return new Date().toISOString();
 }
@@ -35,20 +36,26 @@ function firstNonEmptyString(...values) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function normalizeDoc(text) {
-    return (text ?? "")
-        .split("\n")
-        .map((line) => line.replaceAll(/\s+$/gu, ""))
-        .join("\n")
-        .trim();
-}
-function docChanged(existing, updated) {
-    return normalizeDoc(existing) !== normalizeDoc(updated);
+function normalizeUpdatedBy(value) {
+    if (typeof value !== "string")
+        return "";
+    const trimmed = value.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed.toLowerCase() === DEFAULT_DOC_UPDATED_BY.toLowerCase())
+        return "";
+    return trimmed;
 }
 function ensureDocMetadata(task, updatedBy) {
     task.doc_version = DOC_VERSION;
     task.doc_updated_at = nowIso();
-    task.doc_updated_by = updatedBy ?? DEFAULT_DOC_UPDATED_BY;
+    const explicit = normalizeUpdatedBy(updatedBy);
+    if (updatedBy !== undefined) {
+        task.doc_updated_by =
+            explicit || resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY);
+        return;
+    }
+    task.doc_updated_by = resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY);
 }
 function lastCommentAuthor(comments) {
     if (!Array.isArray(comments))
@@ -69,92 +76,36 @@ function lastCommentAuthor(comments) {
 }
 function resolveDocUpdatedByFromFrontmatter(frontmatter, updatedBy, fallback) {
     if (updatedBy !== undefined) {
-        const trimmed = updatedBy.trim();
-        return trimmed.length > 0 ? trimmed : fallback;
+        const explicit = normalizeUpdatedBy(updatedBy);
+        if (explicit)
+            return explicit;
     }
     const author = lastCommentAuthor(frontmatter.comments);
     if (author)
         return author;
-    const existing = frontmatter.doc_updated_by;
-    if (typeof existing === "string") {
-        const trimmed = existing.trim();
-        if (trimmed)
-            return trimmed;
-    }
-    return fallback;
+    const existing = normalizeUpdatedBy(frontmatter.doc_updated_by);
+    if (existing)
+        return existing;
+    const owner = normalizeUpdatedBy(frontmatter.owner);
+    if (owner)
+        return owner;
+    const fallbackValue = normalizeUpdatedBy(fallback);
+    return fallbackValue || fallback;
 }
 function resolveDocUpdatedByFromTask(task, fallback) {
     const author = lastCommentAuthor(task.comments);
     if (author)
         return author;
-    const existing = task.doc_updated_by;
-    if (typeof existing === "string") {
-        const trimmed = existing.trim();
-        if (trimmed)
-            return trimmed;
-    }
-    return fallback;
-}
-function isDocSectionHeader(line) {
-    return DOC_SECTION_HEADER_RE.test(line.trim());
-}
-export function extractTaskDoc(body) {
-    if (!body)
-        return "";
-    const lines = body.split("\n");
-    let startIdx = null;
-    for (const [idx, line] of lines.entries()) {
-        if (isDocSectionHeader(line)) {
-            startIdx = idx;
-            break;
-        }
-    }
-    if (startIdx === null)
-        return "";
-    if (lines[startIdx]?.trim() !== DOC_SECTION_HEADER) {
-        lines[startIdx] = DOC_SECTION_HEADER;
-    }
-    let endIdx = lines.length;
-    for (let idx = startIdx + 1; idx < lines.length; idx++) {
-        if (lines[idx]?.trim() === AUTO_SUMMARY_HEADER) {
-            endIdx = idx;
-            break;
-        }
-    }
-    return lines.slice(startIdx, endIdx).join("\n").trimEnd();
-}
-export function mergeTaskDoc(body, doc) {
-    const docText = String(doc ?? "").replaceAll(/^\n+|\n+$/g, "");
-    if (docText) {
-        const lines = body ? body.split("\n") : [];
-        let prefixIdx = null;
-        for (const [idx, line] of lines.entries()) {
-            if (isDocSectionHeader(line)) {
-                prefixIdx = idx;
-                break;
-            }
-        }
-        const prefixText = prefixIdx === null ? "" : lines.slice(0, prefixIdx).join("\n").trimEnd();
-        let autoIdx = null;
-        for (const [idx, line] of lines.entries()) {
-            if (line.trim() === AUTO_SUMMARY_HEADER) {
-                autoIdx = idx;
-                break;
-            }
-        }
-        const autoBlock = autoIdx === null ? "" : lines.slice(autoIdx).join("\n").trimEnd();
-        const parts = [];
-        if (prefixText) {
-            parts.push(prefixText, "");
-        }
-        parts.push(docText.trimEnd());
-        if (autoBlock) {
-            parts.push("", autoBlock);
-        }
-        return `${parts.join("\n").trimEnd()}\n`;
-    }
-    return body;
+    const existing = normalizeUpdatedBy(task.doc_updated_by);
+    if (existing)
+        return existing;
+    const owner = normalizeUpdatedBy(task.owner);
+    if (owner)
+        return owner;
+    const fallbackValue = normalizeUpdatedBy(fallback);
+    return fallbackValue || fallback;
 }
+export { extractTaskDoc, mergeTaskDoc };
 function validateTaskId(taskId) {
     if (TASK_ID_RE.test(taskId))
         return;
@@ -192,6 +143,14 @@ function toStringArray(value) {
         return [];
     return value.filter((v) => typeof v === "string");
 }
+function normalizeDependsOn(value) {
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === "string" && v.trim() !== "[]");
+    }
+    if (typeof value === "string" && value.trim() === "[]")
+        return [];
+    return [];
+}
 function normalizePriority(value) {
     const raw = toStringSafe(value).trim().toLowerCase();
     if (!raw)
@@ -229,7 +188,7 @@ export function taskRecordToData(record) {
         status: typeof fm.status === "string" ? fm.status : "TODO",
         priority: typeof fm.priority === "string" || typeof fm.priority === "number" ? fm.priority : "",
         owner: typeof fm.owner === "string" ? fm.owner : "",
-        depends_on: toStringArray(fm.depends_on),
+        depends_on: normalizeDependsOn(fm.depends_on),
         tags: toStringArray(fm.tags),
         verify: toStringArray(fm.verify),
         commit,
@@ -263,7 +222,7 @@ function taskDataToExport(task) {
             : [],
         doc_version: task.doc_version ?? DOC_VERSION,
         doc_updated_at: task.doc_updated_at ?? "",
-        doc_updated_by: task.doc_updated_by ?? DEFAULT_DOC_UPDATED_BY,
+        doc_updated_by: resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY),
         dirty: Boolean(task.dirty),
         id_source: task.id_source ?? "generated",
     };
@@ -286,7 +245,7 @@ export function buildTasksExportSnapshotFromTasks(tasks) {
 export async function writeTasksExportFromTasks(opts) {
     const snapshot = buildTasksExportSnapshotFromTasks(opts.tasks);
     await mkdir(path.dirname(opts.outputPath), { recursive: true });
-    await writeFile(opts.outputPath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+    await atomicWriteFile(opts.outputPath, `${JSON.stringify(snapshot, null, 2)}\n`);
 }
 export class LocalBackend {
     id = "local";
@@ -301,40 +260,64 @@ export class LocalBackend {
         if (length < 4)
             throw new Error(invalidLengthMessage(length, 4));
         const attempts = Math.max(1, opts.attempts);
-        for (let i = 0; i < attempts; i++) {
-            const now = new Date();
-            const yyyy = String(now.getUTCFullYear()).padStart(4, "0");
-            const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
-            const dd = String(now.getUTCDate()).padStart(2, "0");
-            const hh = String(now.getUTCHours()).padStart(2, "0");
-            const min = String(now.getUTCMinutes()).padStart(2, "0");
-            let suffix = "";
-            for (let j = 0; j < length; j++) {
-                suffix += ID_ALPHABET[randomInt(0, ID_ALPHABET.length)];
-            }
-            const taskId = `${yyyy}${mm}${dd}${hh}${min}-${suffix}`;
-            const readmePath = taskReadmePath(this.root, taskId);
-            try {
-                await readFile(readmePath, "utf8");
-                continue;
-            }
-            catch (err) {
-                const code = err?.code;
-                if (code === "ENOENT")
-                    return taskId;
-                throw err;
-            }
-        }
-        throw new Error("Failed to generate a unique task id (exhausted attempts)");
+        return await generateTaskId({
+            length,
+            attempts,
+            isAvailable: async (taskId) => {
+                const readmePath = taskReadmePath(this.root, taskId);
+                try {
+                    await readFile(readmePath, "utf8");
+                    return false;
+                }
+                catch (err) {
+                    const code = err?.code;
+                    if (code === "ENOENT")
+                        return true;
+                    throw err;
+                }
+            },
+        });
     }
     async listTasks() {
         const tasks = [];
         const entries = await readdir(this.root, { withFileTypes: true }).catch(() => []);
+        const indexPath = resolveTaskIndexPath(this.root);
+        const cachedIndex = await loadTaskIndex(indexPath);
+        const cachedByPath = new Map();
+        if (cachedIndex) {
+            for (const entry of cachedIndex.tasks) {
+                cachedByPath.set(entry.readmePath, entry);
+            }
+        }
+        const nextIndex = [];
         const seen = new Set();
         for (const entry of entries) {
             if (!entry.isDirectory())
                 continue;
             const readme = path.join(this.root, entry.name, "README.md");
+            let stats;
+            try {
+                stats = await stat(readme);
+            }
+            catch {
+                continue;
+            }
+            if (!stats.isFile())
+                continue;
+            const cached = cachedByPath.get(readme);
+            if (cached?.mtimeMs === stats.mtimeMs) {
+                const taskId = cached.task.id.trim();
+                if (taskId) {
+                    validateTaskId(taskId);
+                    if (seen.has(taskId)) {
+                        throw new Error(`Duplicate task id in local backend: ${taskId}`);
+                    }
+                    seen.add(taskId);
+                }
+                tasks.push(cached.task);
+                nextIndex.push(cached);
+                continue;
+            }
             let text = "";
             try {
                 text = await readFile(readme, "utf8");
@@ -367,6 +350,13 @@ export class LocalBackend {
                 readmePath: readme,
             });
             tasks.push(task);
+            nextIndex.push(buildTaskIndexEntry(task, readme, stats.mtimeMs));
+        }
+        try {
+            await saveTaskIndex(indexPath, { schema_version: 1, tasks: nextIndex });
+        }
+        catch {
+            // Best-effort cache; ignore failures.
         }
         return tasks;
     }
@@ -445,11 +435,11 @@ export class LocalBackend {
             payload.doc_updated_at = nowIso();
         }
         if (payload.doc_updated_by === undefined || payload.doc_updated_by === "") {
-            payload.doc_updated_by = this.updatedBy;
+            payload.doc_updated_by = resolveDocUpdatedByFromTask(task, this.updatedBy);
         }
         await mkdir(path.dirname(readme), { recursive: true });
         const text = renderTaskReadme(payload, body || "");
-        await writeFile(readme, text.endsWith("\n") ? text : `${text}\n`, "utf8");
+        await atomicWriteFile(readme, text.endsWith("\n") ? text : `${text}\n`);
     }
     async setTaskDoc(taskId, doc, updatedBy) {
         const readme = taskReadmePath(this.root, taskId);
@@ -467,7 +457,7 @@ export class LocalBackend {
             frontmatter.doc_version = DOC_VERSION;
         }
         const next = renderTaskReadme(frontmatter, body);
-        await writeFile(readme, next.endsWith("\n") ? next : `${next}\n`, "utf8");
+        await atomicWriteFile(readme, next.endsWith("\n") ? next : `${next}\n`);
     }
     async touchTaskDocMetadata(taskId, updatedBy) {
         const readme = taskReadmePath(this.root, taskId);
@@ -478,7 +468,7 @@ export class LocalBackend {
         frontmatter.doc_updated_at = nowIso();
         frontmatter.doc_updated_by = resolveDocUpdatedByFromFrontmatter(frontmatter, updatedBy, this.updatedBy);
         const next = renderTaskReadme(frontmatter, parsed.body || "");
-        await writeFile(readme, next.endsWith("\n") ? next : `${next}\n`, "utf8");
+        await atomicWriteFile(readme, next.endsWith("\n") ? next : `${next}\n`);
     }
     async writeTasks(tasks) {
         for (const task of tasks) {
@@ -505,11 +495,11 @@ export class RedmineBackend {
     issueCache = new Map();
     reverseStatus = new Map();
     constructor(settings, opts) {
-        const envUrl = firstNonEmptyString(process.env.CODEXSWARM_REDMINE_URL);
-        const envApiKey = firstNonEmptyString(process.env.CODEXSWARM_REDMINE_API_KEY);
-        const envProjectId = firstNonEmptyString(process.env.CODEXSWARM_REDMINE_PROJECT_ID);
-        const envAssignee = (process.env.CODEXSWARM_REDMINE_ASSIGNEE_ID ?? "").trim();
-        const envOwner = firstNonEmptyString(process.env.CODEXSWARM_REDMINE_OWNER, process.env.CODEXSWARM_REDMINE_OWNER_AGENT);
+        const envUrl = firstNonEmptyString(process.env.AGENTPLANE_REDMINE_URL);
+        const envApiKey = firstNonEmptyString(process.env.AGENTPLANE_REDMINE_API_KEY);
+        const envProjectId = firstNonEmptyString(process.env.AGENTPLANE_REDMINE_PROJECT_ID);
+        const envAssignee = (process.env.AGENTPLANE_REDMINE_ASSIGNEE_ID ?? "").trim();
+        const envOwner = firstNonEmptyString(process.env.AGENTPLANE_REDMINE_OWNER, process.env.AGENTPLANE_REDMINE_OWNER_AGENT);
         this.baseUrl = firstNonEmptyString(envUrl, settings.url).replaceAll(/\/+$/gu, "");
         this.apiKey = firstNonEmptyString(envApiKey, settings.api_key);
         this.projectId = firstNonEmptyString(envProjectId, settings.project_id);
@@ -547,7 +537,11 @@ export class RedmineBackend {
             const cached = await this.cache.listTasks();
             existingIds = new Set(cached.map((task) => toStringSafe(task.id)).filter(Boolean));
         }
-        return generateTaskId(existingIds, length, attempts);
+        return await generateTaskId({
+            length,
+            attempts,
+            isAvailable: (taskId) => !existingIds.has(taskId),
+        });
     }
     async listTasks() {
         try {
@@ -1239,26 +1233,6 @@ export class RedmineBackend {
         throw lastError instanceof Error ? lastError : new RedmineUnavailable("Redmine unavailable");
     }
 }
-function generateTaskId(existingIds, length, attempts) {
-    if (length < 4)
-        throw new Error(invalidLengthMessage(length, 4));
-    for (let i = 0; i < attempts; i++) {
-        const now = new Date();
-        const yyyy = String(now.getUTCFullYear()).padStart(4, "0");
-        const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
-        const dd = String(now.getUTCDate()).padStart(2, "0");
-        const hh = String(now.getUTCHours()).padStart(2, "0");
-        const min = String(now.getUTCMinutes()).padStart(2, "0");
-        let suffix = "";
-        for (let j = 0; j < length; j++) {
-            suffix += ID_ALPHABET[randomInt(0, ID_ALPHABET.length)];
-        }
-        const candidate = `${yyyy}${mm}${dd}${hh}${min}-${suffix}`;
-        if (!existingIds.has(candidate))
-            return candidate;
-    }
-    throw new Error("Failed to generate a unique task id (exhausted attempts)");
-}
 async function loadBackendConfig(configPath) {
     try {
         const raw = JSON.parse(await readFile(configPath, "utf8"));
@@ -1279,14 +1253,23 @@ function resolveMaybeRelative(root, input) {
         return null;
     return path.isAbsolute(raw) ? raw : path.join(root, raw);
 }
+function normalizeBackendConfig(raw) {
+    if (!isRecord(raw)) {
+        return { id: "local", version: 1, settings: {} };
+    }
+    const id = toStringSafe(raw.id).trim() || "local";
+    const version = typeof raw.version === "number" ? raw.version : 1;
+    const settings = isRecord(raw.settings) ? raw.settings : {};
+    return { id, version, settings };
+}
 export async function loadTaskBackend(opts) {
     const resolved = await resolveProject({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
     const loaded = await loadConfig(resolved.agentplaneDir);
     const backendConfigPath = path.join(resolved.gitRoot, loaded.config.tasks_backend.config_path);
     const backendConfig = await loadBackendConfig(backendConfigPath);
-    const backendIdRaw = toStringSafe(backendConfig?.id).trim();
-    const backendId = backendIdRaw.length > 0 ? backendIdRaw : "local";
-    const settings = isRecord(backendConfig?.settings) ? backendConfig?.settings : {};
+    const normalized = normalizeBackendConfig(backendConfig);
+    const backendId = normalized.id;
+    const settings = normalized.settings;
     if (backendId === "redmine") {
         await loadDotEnv(resolved.gitRoot);
         const cacheDirRaw = resolveMaybeRelative(resolved.gitRoot, settings.cache_dir);

package/dist/backends/task-index.d.ts

@@ -0,0 +1,16 @@
+import type { TaskData } from "./task-backend.js";
+export declare const TASK_INDEX_SCHEMA_VERSION = 1;
+export type TaskIndexEntry = {
+    task: TaskData;
+    readmePath: string;
+    mtimeMs: number;
+};
+export type TaskIndexFile = {
+    schema_version: 1;
+    tasks: TaskIndexEntry[];
+};
+export declare function resolveTaskIndexPath(tasksDir: string): string;
+export declare function loadTaskIndex(indexPath: string): Promise<TaskIndexFile | null>;
+export declare function saveTaskIndex(indexPath: string, index: TaskIndexFile): Promise<void>;
+export declare function buildTaskIndexEntry(task: TaskData, readmePath: string, mtimeMs: number): TaskIndexEntry;
+//# sourceMappingURL=task-index.d.ts.map

package/dist/backends/task-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-index.d.ts","sourceRoot":"","sources":["../../src/backends/task-index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAG3C,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,cAAc,EAAE,CAAC,CAAC;IAClB,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU7D;AAuBD,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAkBpF;AAED,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAM1F;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,QAAQ,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,cAAc,CAMhB"}