agentplane 0.2.3 → 0.2.4

package/assets/AGENTS.md

@@ -6,7 +6,7 @@ default_initiator: ORCHESTRATOR
 
 # PURPOSE
 
-This document defines the **behavioral policy** for Codex-style agents operating in this repository (CLI + VS Code extension).
+This document defines the **behavioral policy** for agents operating in an agentplane-managed development workspace.
 Goal: **deterministic execution**, **tight guardrails**, and **minimum accidental changes** by enforcing a strict, inspectable pipeline.
 
 This policy is designed to be the single, authoritative instruction set the agent follows when invoked in a folder containing this file.
@@ -26,17 +26,13 @@ If two sources conflict, prefer the higher-priority source.
 
 ## CLI invocation
 
-All commands in this policy are written as `agentplane ...`.
+All commands in this policy are written as `agentplane ...` and MUST use the `agentplane` CLI available on `PATH`.
 
-- If you are working inside the agentplane repository checkout, prefer the **repo-local CLI entrypoint** over any system-installed binary.
-- Otherwise (packaged install), `agentplane ...` refers to the available `agentplane` binary.
-
-If the preferred entrypoint fails (missing deps/build), treat any bootstrap step (`bun install`, `npm install`, `bun run build`, etc.)
-as **network and/or outside-repo** activity and request explicit approval before proceeding.
+Do not use repository-relative entrypoints (for example `node .../bin/agentplane.js`) in instructions or automation.
 
 ## Scope boundary
 
-- All operations must remain within the repository unless explicitly approved (see Approval Gates + Overrides).
+- All operations must remain within the workspace unless explicitly approved (see Approval Gates + Overrides).
 - Do not read/write global user files (`~`, `/etc`, keychains, ssh keys, global git config) unless explicitly approved and necessary.
 
 ## Agent roles (authority boundaries)
@@ -48,18 +44,34 @@ as **network and/or outside-repo** activity and request explicit approval before
 
 No other role may assume another role’s authority.
 
+## Execution agents (registry)
+
+Execution agents are defined by JSON files under `.agentplane/agents/*.json`. The file basename (without `.json`) is the agent ID (e.g. `CODER`, `TESTER`, `REVIEWER`, `DOCS`).
+
+**Contract (downstream task assignment):**
+
+- Every downstream task created by PLANNER MUST set `owner` to an existing execution agent ID from `.agentplane/agents/*.json`.
+- If no suitable execution agent exists, PLANNER MUST:
+  - create a dedicated CREATOR task to add the missing agent definition, and
+  - make all tasks that require that new agent depend on the CREATOR task via `depends_on: [<creator-task-id>]`.
+
+**Enforcement status:**
+
+- Current: warn-only in CLI (`task new` / `task update`) when `owner` does not exist in `.agentplane/agents`.
+- Planned: upgrade to lint/CI gate once the workflow is stable.
+
 ## Definitions (remove ambiguity)
 
-- **Read-only inspection**: commands that may read repo state but must not change tracked files or commit history.
+- **Read-only inspection**: commands that may read workspace state but must not change tracked files or commit history.
   Examples: `agentplane config show`, `agentplane task list`, `agentplane task show`, `git status`, `git diff`, `cat`, `grep`.
-- **Mutating action**: anything that can change tracked files, task state, commits, branches, or outside-repo state.
+- **Mutating action**: anything that can change tracked files, task state, commits, branches, or outside-workspace state.
   Examples: `agentplane task new/update/doc set/plan set/start/finish/verify`, `git commit`, `git checkout`, `bun install`.
 
 If unsure whether an action mutates state, treat it as mutating.
 
 ## Truthfulness & safety (hard invariants)
 
-- Never invent facts about repo state. Prefer inspection over guessing.
+- Never invent facts about workspace state. Prefer inspection over guessing.
 - Never modify `.agentplane/tasks.json` manually. It is an **export-only snapshot** generated via `agentplane task export`.
 - Never expose raw internal chain-of-thought. Use structured artifacts instead (see OUTPUT CONTRACTS).
 
@@ -70,7 +82,7 @@ If unsure whether an action mutates state, treat it as mutating.
 - “Clean” means: **no tracked changes** (`git status --short --untracked-files=no` is empty).
 - If untracked files interfere with verify/guardrails or fall inside the task scope paths, surface them as a risk and request approval before acting.
 
-## Approval gates (network vs outside-repo)
+## Approval gates (network vs outside-workspace)
 
 ### Network
 
@@ -85,15 +97,20 @@ Network use includes (non-exhaustive):
 - `git fetch`, `git pull`
 - calling external HTTP APIs or remote services
 
-### Outside-repo
+### Outside-workspace
 
-Outside-repo reading/writing is **always prohibited** unless the user explicitly approves it (regardless of `require_network`).
+Outside-workspace reading/writing is **always prohibited** unless the user explicitly approves it (regardless of `require_network`).
 
-Outside-repo includes (non-exhaustive):
+Outside-workspace includes (non-exhaustive):
 
-- reading/writing outside the repo (`~`, `/etc`, global configs)
+- reading/writing outside the workspace (`~`, `/etc`, global configs)
 - modifying keychains, ssh keys, credential stores
-- any tool that mutates outside-repo state
+- any tool that mutates outside-workspace state
+
+### Interactive vs non-interactive runs (approvals mechanics)
+
+- Interactive: the user can approve prompts (for example network use) during the run.
+- Non-interactive (CI, scripted runs): approvals MUST be expressed via flags/config up front (for example `--yes`). If an approval is required and not granted, stop and request explicit user instruction.
 
 ---
 
@@ -139,13 +156,18 @@ This is the required substitute for raw chain-of-thought.
 
 Preflight is **read-only inspection**. It is allowed before user approval.
 
-Before any planning or execution, ORCHESTRATOR must run:
+Before any planning or execution, ORCHESTRATOR must:
 
-1. `agentplane config show`
-2. `agentplane quickstart` (CLI instructions)
-3. `agentplane task list`
-4. `git status --short --untracked-files=no`
-5. `git rev-parse --abbrev-ref HEAD`
+1. Determine whether the current directory is an initialized agentplane workspace (e.g. `.agentplane/config.json` exists).
+2. Attempt git inspection:
+   - `git status --short --untracked-files=no`
+   - `git rev-parse --abbrev-ref HEAD`
+3. If the workspace is initialized, also run:
+   - `agentplane config show`
+   - `agentplane quickstart` (CLI instructions)
+   - `agentplane task list`
+
+If a command fails because the workspace is not initialized or not a git repo, record that fact in the Preflight Summary instead of guessing or proceeding with mutating actions.
 
 Then report a **Preflight Summary** (do not dump full config or quickstart text).
 
@@ -156,6 +178,8 @@ You MUST explicitly state:
 - Config loaded: yes/no
 - CLI instructions loaded: yes/no
 - Task list loaded: yes/no
+- Workspace initialized: yes/no
+- Git repository detected: yes/no
 - Working tree clean (tracked-only): yes/no
 - Current git branch: `<name>`
 - `workflow_mode`: `direct` / `branch_pr` / unknown
@@ -163,7 +187,7 @@ You MUST explicitly state:
   - `require_plan`: true/false/unknown
   - `require_verify`: true/false/unknown
   - `require_network`: true/false/unknown
-- Outside-repo: not needed / needed (if needed, requires explicit user approval)
+- Outside-workspace: not needed / needed (if needed, requires explicit user approval)
 
 Do not output the full contents of config or quickstart unless the user explicitly asks.
 
@@ -175,7 +199,7 @@ Do not output the full contents of config or quickstart unless the user explicit
 - ORCHESTRATOR starts by producing a top-level plan + task decomposition.
 - **Before explicit user approval, do not perform mutating actions.**
   - Allowed: read-only inspection (including preflight).
-  - Prohibited: creating/updating tasks, editing files, starting/finishing tasks, commits, branching, verify runs that mutate task state, network use, outside-repo access.
+  - Prohibited: creating/updating tasks, editing files, starting/finishing tasks, commits, branching, verify runs that mutate task state, network use, outside-workspace access.
 
 ---
 
@@ -195,7 +219,7 @@ ORCHESTRATOR MUST produce:
 - **Decomposition**
   - Atomic tasks assignable to existing agents
 - **Approvals**
-  - Whether network and/or outside-repo actions will be needed
+  - Whether network and/or outside-workspace actions will be needed
   - Any requested overrides (see Override Protocol)
 - **Verification criteria**
   - What will be considered "done" + checks to run
@@ -210,7 +234,7 @@ ORCHESTRATOR MUST produce:
 - PLANNER creates any additional tasks from the approved decomposition.
 - Task IDs are referenced in comments/notes for traceability.
 
-**Task tracking is mandatory** for any work that changes repo state. Exceptions require explicit user approval (Override Protocol).
+**Task tracking is mandatory** for any work that changes workspace state. Exceptions require explicit user approval (Override Protocol).
 
 ---
 
@@ -220,7 +244,7 @@ Overrides exist to let the user intentionally relax guardrails **in a controlled
 
 ## Hard invariants (cannot be overridden)
 
-- No fabricated repo facts.
+- No fabricated workspace facts.
 - No raw chain-of-thought.
 - No manual editing of `.agentplane/tasks.json` (exports are generated, not edited).
 
@@ -229,7 +253,7 @@ Overrides exist to let the user intentionally relax guardrails **in a controlled
 Common overridable guardrails:
 
 - **Network**: allow network access even when `require_network=true`.
-- **Outside-repo**: allow reading/writing outside the repo (scoped).
+- **Outside-workspace**: allow reading/writing outside the workspace (scoped).
 - **Pipeline**: skip/relax steps (e.g., skip task tracking for analysis-only; skip exports).
 - **Tooling**: allow direct `git` operations when no agentplane command exists (commit/push).
 - **Force flags**: allow `--force` status transitions / dependency bypass.
@@ -258,7 +282,7 @@ Any approved override MUST be recorded:
 
 ## Golden rule
 
-If an agent changes repo state, that work must be traceable to a task ID and a filled task README.
+If an agent changes workspace state, that work must be traceable to a task ID and a filled task README.
 
 ## Scaffold is mandatory
 
@@ -372,7 +396,9 @@ If config sets `agents.approvals.require_plan=true`:
 
 # COMMIT WORKFLOW
 
-- Commits and pushes must go through `agentplane` commands (no direct `git commit`/`git push`) unless explicitly overridden.
+Default: commits and pushes should go through `agentplane` commands (instead of direct `git commit`/`git push`) to enforce policy and allowlists.
+
+Override: direct git operations are allowed only with explicit user approval, and must be logged under the task `## Notes` → `### Approvals / Overrides`.
 
 ## Commit message semantics (canonical)
 
@@ -483,7 +509,7 @@ Re-approval is required if any of the following becomes true:
 
 - Scope expands beyond the approved in-scope paths/artifacts.
 - New tasks are needed that were not in the approved decomposition.
-- Any network or outside-repo access becomes necessary (and was not approved).
+- Any network or outside-workspace access becomes necessary (and was not approved).
 - Verification criteria change materially.
 - Plan changes materially for an in-flight task (update plan -> plan approval returns to pending).
 - Guardrails require `--force` to proceed.

package/assets/framework.manifest.json

@@ -0,0 +1,89 @@
+{
+  "schema_version": 1,
+  "files": [
+    {
+      "path": "AGENTS.md",
+      "source_path": "AGENTS.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/CODER.json",
+      "source_path": "agents/CODER.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/CREATOR.json",
+      "source_path": "agents/CREATOR.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/DOCS.json",
+      "source_path": "agents/DOCS.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/INTEGRATOR.json",
+      "source_path": "agents/INTEGRATOR.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/ORCHESTRATOR.json",
+      "source_path": "agents/ORCHESTRATOR.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/PLANNER.json",
+      "source_path": "agents/PLANNER.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/REDMINE.json",
+      "source_path": "agents/REDMINE.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/REVIEWER.json",
+      "source_path": "agents/REVIEWER.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/TESTER.json",
+      "source_path": "agents/TESTER.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/UPDATER.json",
+      "source_path": "agents/UPDATER.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/UPGRADER.json",
+      "source_path": "agents/UPGRADER.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    }
+  ]
+}

package/dist/adapters/clock/system-clock-adapter.d.ts

@@ -0,0 +1,5 @@
+import type { ClockPort } from "../../ports/clock-port.js";
+export declare class SystemClockAdapter implements ClockPort {
+    nowIso(): string;
+}
+//# sourceMappingURL=system-clock-adapter.d.ts.map

package/dist/adapters/clock/system-clock-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-clock-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/clock/system-clock-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,qBAAa,kBAAmB,YAAW,SAAS;IAClD,MAAM,IAAI,MAAM;CAGjB"}

package/dist/adapters/clock/system-clock-adapter.js

@@ -0,0 +1,5 @@
+export class SystemClockAdapter {
+    nowIso() {
+        return new Date().toISOString();
+    }
+}

package/dist/adapters/fs/node-fs-adapter.d.ts

@@ -0,0 +1,15 @@
+import type { FileStat, FileSystemPort } from "../../ports/fs-port.js";
+export declare class NodeFileSystemAdapter implements FileSystemPort {
+    readFileText(path: string): Promise<string>;
+    readFileBytes(path: string): Promise<Buffer>;
+    writeFileText(path: string, text: string): Promise<void>;
+    writeFileBytes(path: string, bytes: Buffer): Promise<void>;
+    mkdirp(path: string): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    lstat(path: string): Promise<FileStat>;
+    rm(path: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    symlink(target: string, path: string): Promise<void>;
+    copyFileStream(src: string, dest: string): Promise<void>;
+}
+//# sourceMappingURL=node-fs-adapter.d.ts.map

package/dist/adapters/fs/node-fs-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/fs/node-fs-adapter.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAY,MAAM,wBAAwB,CAAC;AAQjF,qBAAa,qBAAsB,YAAW,cAAc;IACpD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3C,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAKtC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG/D"}

package/dist/adapters/fs/node-fs-adapter.js

@@ -0,0 +1,47 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { lstat, mkdir, readdir, readFile, readlink, rm, symlink, writeFile, } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+function toKind(st) {
+    if (st.isSymbolicLink())
+        return "symlink";
+    if (st.isDirectory())
+        return "dir";
+    return "file";
+}
+export class NodeFileSystemAdapter {
+    async readFileText(path) {
+        return await readFile(path, "utf8");
+    }
+    async readFileBytes(path) {
+        return await readFile(path);
+    }
+    async writeFileText(path, text) {
+        await writeFile(path, text, "utf8");
+    }
+    async writeFileBytes(path, bytes) {
+        await writeFile(path, bytes);
+    }
+    async mkdirp(path) {
+        await mkdir(path, { recursive: true });
+    }
+    async readdir(path) {
+        return await readdir(path);
+    }
+    async lstat(path) {
+        const st = await lstat(path);
+        return { kind: toKind(st), mtimeMs: st.mtimeMs };
+    }
+    async rm(path) {
+        await rm(path, { recursive: true, force: true });
+    }
+    async readlink(path) {
+        return await readlink(path);
+    }
+    async symlink(target, path) {
+        await symlink(target, path);
+    }
+    // Utility for large copies without buffering the entire file.
+    async copyFileStream(src, dest) {
+        await pipeline(createReadStream(src), createWriteStream(dest));
+    }
+}

package/dist/adapters/git/git-context-adapter.d.ts

@@ -0,0 +1,21 @@
+import type { GitPort } from "../../ports/git-port.js";
+import type { GitContext } from "../../commands/shared/git-context.js";
+export declare class GitContextAdapter implements GitPort {
+    private readonly inner;
+    constructor(inner: GitContext);
+    statusChangedPaths(): Promise<string[]>;
+    statusStagedPaths(): Promise<string[]>;
+    statusUnstagedTrackedPaths(): Promise<string[]>;
+    headCommit(): Promise<string>;
+    headHashSubject(): Promise<{
+        hash: string;
+        subject: string;
+    }>;
+    stage(paths: string[]): Promise<void>;
+    commit(opts: {
+        message: string;
+        body?: string;
+        env?: NodeJS.ProcessEnv;
+    }): Promise<void>;
+}
+//# sourceMappingURL=git-context-adapter.d.ts.map

package/dist/adapters/git/git-context-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-context-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/git/git-context-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAEvE,qBAAa,iBAAkB,YAAW,OAAO;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;gBAEvB,KAAK,EAAE,UAAU;IAI7B,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIvC,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAItC,0BAA0B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAI/C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7B,eAAe;;;;IAIf,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,MAAM,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzF"}

package/dist/adapters/git/git-context-adapter.js

@@ -0,0 +1,27 @@
+export class GitContextAdapter {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    statusChangedPaths() {
+        return this.inner.statusChangedPaths();
+    }
+    statusStagedPaths() {
+        return this.inner.statusStagedPaths();
+    }
+    statusUnstagedTrackedPaths() {
+        return this.inner.statusUnstagedTrackedPaths();
+    }
+    headCommit() {
+        return this.inner.headCommit();
+    }
+    headHashSubject() {
+        return this.inner.headHashSubject();
+    }
+    stage(paths) {
+        return this.inner.stage(paths);
+    }
+    commit(opts) {
+        return this.inner.commit(opts);
+    }
+}

package/dist/adapters/index.d.ts

@@ -0,0 +1,13 @@
+import type { CommandContext } from "../commands/shared/task-backend.js";
+import { SystemClockAdapter } from "./clock/system-clock-adapter.js";
+import { NodeFileSystemAdapter } from "./fs/node-fs-adapter.js";
+import { GitContextAdapter } from "./git/git-context-adapter.js";
+import { TaskBackendAdapter } from "./task-backend/task-backend-adapter.js";
+export type Adapters = {
+    fs: NodeFileSystemAdapter;
+    git: GitContextAdapter;
+    tasks: TaskBackendAdapter;
+    clock: SystemClockAdapter;
+};
+export declare function buildAdapters(ctx: CommandContext): Adapters;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAE5E,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,EAAE,qBAAqB,CAAC;IAC1B,GAAG,EAAE,iBAAiB,CAAC;IACvB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,kBAAkB,CAAC;CAC3B,CAAC;AAEF,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,QAAQ,CAO3D"}

package/dist/adapters/index.js

@@ -0,0 +1,12 @@
+import { SystemClockAdapter } from "./clock/system-clock-adapter.js";
+import { NodeFileSystemAdapter } from "./fs/node-fs-adapter.js";
+import { GitContextAdapter } from "./git/git-context-adapter.js";
+import { TaskBackendAdapter } from "./task-backend/task-backend-adapter.js";
+export function buildAdapters(ctx) {
+    return {
+        fs: new NodeFileSystemAdapter(),
+        git: new GitContextAdapter(ctx.git),
+        tasks: new TaskBackendAdapter(ctx),
+        clock: new SystemClockAdapter(),
+    };
+}

package/dist/adapters/task-backend/task-backend-adapter.d.ts

@@ -0,0 +1,12 @@
+import type { TaskData } from "../../backends/task-backend.js";
+import type { TaskBackendPort } from "../../ports/task-backend-port.js";
+import type { CommandContext } from "../../commands/shared/task-backend.js";
+export declare class TaskBackendAdapter implements TaskBackendPort {
+    private readonly ctx;
+    constructor(ctx: CommandContext);
+    listTasks(): Promise<TaskData[]>;
+    getTask(id: string): Promise<TaskData | null>;
+    writeTask(task: TaskData): Promise<void>;
+    exportTasksJson(path: string): Promise<void>;
+}
+//# sourceMappingURL=task-backend-adapter.d.ts.map

package/dist/adapters/task-backend/task-backend-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-backend-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/task-backend/task-backend-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAE5E,qBAAa,kBAAmB,YAAW,eAAe;IACxD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;gBAEzB,GAAG,EAAE,cAAc;IAI/B,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIhC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAI7C,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO7C"}

package/dist/adapters/task-backend/task-backend-adapter.js

@@ -0,0 +1,22 @@
+export class TaskBackendAdapter {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    listTasks() {
+        return this.ctx.taskBackend.listTasks();
+    }
+    getTask(id) {
+        return this.ctx.taskBackend.getTask(id);
+    }
+    writeTask(task) {
+        return this.ctx.taskBackend.writeTask(task);
+    }
+    exportTasksJson(path) {
+        const backend = this.ctx.taskBackend;
+        if (!backend.exportTasksJson) {
+            throw new Error("Backend does not support exportTasksJson");
+        }
+        return backend.exportTasksJson(path);
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"local-backend.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/local-backend.ts"],"names":[],"mappings":"AAqBA,OAAO,EAiBL,KAAK,WAAW,EAChB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB,qBAAa,YAAa,YAAW,WAAW;IAC9C,EAAE,SAAW;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;gBAEN,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAKrD,cAAc,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB3E,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IA4EhC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAoBjD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC;IAKzD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO3C,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAyExC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB1E,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAoF/D,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIzD"}
+{"version":3,"file":"local-backend.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/local-backend.ts"],"names":[],"mappings":"AAqBA,OAAO,EAiBL,KAAK,WAAW,EAChB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB,qBAAa,YAAa,YAAW,WAAW;IAC9C,EAAE,SAAW;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;gBAEN,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAKrD,cAAc,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB3E,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IA2FhC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAoBjD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC;IAKzD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO3C,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAyExC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB1E,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAoF/D,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIzD"}

package/dist/backends/task-backend/local-backend.js

@@ -43,75 +43,80 @@ export class LocalBackend {
         const cachedIndex = await loadTaskIndex(indexPath);
         const cachedByPath = new Map();
         if (cachedIndex) {
-            for (const entry of cachedIndex.tasks) {
-                cachedByPath.set(entry.readmePath, entry);
+            for (const [readmePath, taskId] of Object.entries(cachedIndex.byPath)) {
+                const entry = cachedIndex.byId[taskId];
+                if (entry)
+                    cachedByPath.set(readmePath, entry);
             }
         }
-        const nextIndex = [];
+        const nextById = {};
+        const nextByPath = {};
         const seen = new Set();
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            const readme = path.join(this.root, entry.name, "README.md");
+        // Deterministic ordering helps both users and tests; keep I/O bounded to avoid storms.
+        const dirs = entries
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .toSorted();
+        const results = await mapLimit(dirs, 32, async (dirName) => {
+            const readme = path.join(this.root, dirName, "README.md");
             let stats;
             try {
                 stats = await stat(readme);
             }
             catch {
-                continue;
+                return null;
             }
             if (!stats.isFile())
-                continue;
+                return null;
             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;
+                return { task: cached.task, index: cached, mtimeMs: stats.mtimeMs, readme };
             }
             let text = "";
             try {
                 text = await readFile(readme, "utf8");
             }
             catch {
-                continue;
+                return null;
             }
             let parsed;
             try {
                 parsed = parseTaskReadme(text);
             }
             catch {
-                continue;
+                return null;
             }
             const fm = parsed.frontmatter;
             if (!isRecord(fm) || Object.keys(fm).length === 0)
-                continue;
-            const taskId = (typeof fm.id === "string" ? fm.id : entry.name).trim();
-            if (taskId) {
-                validateTaskId(taskId);
-                if (seen.has(taskId)) {
-                    throw new Error(`Duplicate task id in local backend: ${taskId}`);
-                }
-                seen.add(taskId);
-            }
+                return null;
+            const taskId = (typeof fm.id === "string" ? fm.id : dirName).trim();
             const task = taskRecordToData({
                 id: taskId,
                 frontmatter: fm,
                 body: parsed.body,
                 readmePath: readme,
             });
-            tasks.push(task);
-            nextIndex.push(buildTaskIndexEntry(task, readme, stats.mtimeMs));
+            return { task, index: null, mtimeMs: stats.mtimeMs, readme };
+        });
+        for (const res of results) {
+            if (!res)
+                continue;
+            const taskId = res.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(res.task);
+            if (taskId) {
+                const entry = res.index ?? buildTaskIndexEntry(res.task, res.readme, res.mtimeMs);
+                nextById[taskId] = entry;
+                nextByPath[entry.readmePath] = taskId;
+            }
         }
         try {
-            await saveTaskIndex(indexPath, { schema_version: 1, tasks: nextIndex });
+            await saveTaskIndex(indexPath, { schema_version: 2, byId: nextById, byPath: nextByPath });
         }
         catch {
             // Best-effort cache; ignore failures.