@dreki-gg/taskman 0.2.2 → 0.4.0

package/README.md

@@ -46,6 +46,15 @@ taskman <command> --help  # flags + arguments for one command
 duplicate it (so it cannot drift). Every command prints human text by default
 and accepts `--json` for machine consumption.
 
+Create a plan from any harness (handoff/tasks accept an inline value, a
+`--*-file <path>`, or piped stdin):
+
+```bash
+echo "$MARKDOWN" | taskman create-plan --name my-plan --title "My Plan" \
+  --handoff-file - --tasks '[{"description":"do it"}]'
+taskman create-handoff --plan my-plan --file HANDOFF.md   # write/replace prose
+```
+
 A typical execution loop:
 
 ```bash

package/dist/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { N as readInitiativesManifest, P as upsertInitiativeEntry, S as initiativeRollup, T as reconcileInitiativeForPlan, V as upsertPlanEntry, X as makePlanRuntime, _ as applyInitiativeReconcile, a as filterPlans, b as collectPlanDrift, d as setTaskStatus, g as resolvePlanByName, i as loadInitiativeListItems, l as sortPlans, m as loadPlanData, n as formatInitiativeList, o as formatPlanList, s as loadPlanListItems, t as filterInitiatives, u as appendDeferredTask, v as applyReconcile, y as collectInitiativeDrift, z as readPlansManifest } from "./initiatives-Ij_teFl_.mjs";
+import { J as writeTasksJsonl, N as readInitiativesManifest, P as upsertInitiativeEntry, S as initiativeRollup, T as reconcileInitiativeForPlan, V as upsertPlanEntry, W as saveHandoff, X as makePlanRuntime, _ as applyInitiativeReconcile, a as filterPlans, b as collectPlanDrift, d as setTaskStatus, f as nextTaskId, g as resolvePlanByName, i as loadInitiativeListItems, l as sortPlans, m as loadPlanData, n as formatInitiativeList, o as formatPlanList, p as toKebabCase, s as loadPlanListItems, t as filterInitiatives, u as appendDeferredTask, v as applyReconcile, y as collectInitiativeDrift, z as readPlansManifest } from "./initiatives-AtmFo2DU.mjs";
 import { Effect } from "effect";
+import { readFile } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 import { Command } from "commander";
 //#region src/cli/runtime.ts
@@ -253,6 +254,143 @@ async function closeInitiativeCommand(status, name, opts) {
 	}, `Initiative ${name} → ${s}${opts.reason ? ` (${opts.reason})` : ""}.`);
 }
 //#endregion
+//#region src/cli/input.ts
+/**
+* Content resolution for CLI commands that accept markdown / JSON payloads from
+* a foreign harness: an inline string, a file path, or piped stdin.
+*/
+/** Read all of stdin as a UTF-8 string (used when neither inline nor file is given). */
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+/**
+* Resolve payload content from, in priority order: an inline value, a `--file`
+* path (or `-` for stdin), else piped stdin. Throws `CliError` when nothing is
+* provided and stdin is a TTY (no piped input).
+*/
+async function resolveContent(inline, file, label) {
+	if (inline !== void 0) return inline;
+	if (file !== void 0 && file !== "-") try {
+		return await readFile(file, "utf8");
+	} catch {
+		throw new CliError(`Could not read ${label} file: ${file}`);
+	}
+	if (process.stdin.isTTY) throw new CliError(`No ${label} provided. Pass it inline, via --${label}-file, or on stdin.`);
+	return readStdin();
+}
+//#endregion
+//#region src/cli/commands/create-plan.ts
+/**
+* `taskman create-plan` — create a plan from a foreign harness.
+*
+* The CLI sibling of plan-mode's `submit_plan` tool: writes tasks.jsonl,
+* HANDOFF.md, and a plans.jsonl registry entry in one transaction, then
+* re-projects the parent initiative (when linked). Handoff/tasks payloads come
+* from inline values, files, or stdin so any harness can drive it.
+*/
+/** Parse and validate the `--tasks` JSON payload into TaskInput[]. */
+function parseTasks(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new CliError("--tasks must be a JSON array of { description, ... } objects.");
+	}
+	if (!Array.isArray(parsed) || parsed.length === 0) throw new CliError("--tasks must be a non-empty JSON array.");
+	return parsed.map((entry, i) => {
+		if (typeof entry !== "object" || entry === null) throw new CliError(`Task at index ${i} is not an object.`);
+		const { description } = entry;
+		if (typeof description !== "string" || description.trim() === "") throw new CliError(`Task at index ${i} is missing a "description".`);
+		const t = entry;
+		return {
+			id: t.id,
+			description: t.description,
+			details: t.details,
+			depends_on: t.depends_on
+		};
+	});
+}
+/** Assign explicit IDs where given, generate t-NNN for the rest. */
+function assignIds(inputs, now) {
+	const ids = inputs.map((t) => t.id).filter((id) => Boolean(id));
+	const records = [];
+	for (const input of inputs) {
+		const id = input.id ?? nextTaskId(ids);
+		if (!input.id) ids.push(id);
+		records.push({
+			_type: "task",
+			id,
+			description: input.description.slice(0, 60),
+			details: input.details ?? "",
+			status: "pending",
+			depends_on: input.depends_on,
+			created_at: now,
+			updated_at: now
+		});
+	}
+	return records;
+}
+async function createPlanCommand(opts) {
+	if (!opts.name) throw new CliError("--name is required.");
+	if (!opts.title) throw new CliError("--title is required.");
+	const planName = toKebabCase(opts.name);
+	const planDir = `.plans/${planName}`;
+	const initiative = opts.initiative ? toKebabCase(opts.initiative) : void 0;
+	const dependsOnPlans = opts.dependsOn ? opts.dependsOn.split(",").map((s) => toKebabCase(s.trim())).filter(Boolean) : void 0;
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const handoff = await resolveContent(opts.handoff, opts.handoffFile, "handoff");
+	const tasks = assignIds(parseTasks(await resolveContent(opts.tasks, opts.tasksFile, "tasks")), now);
+	const meta = {
+		_type: "meta",
+		title: opts.title,
+		plan_name: planName,
+		created_at: now
+	};
+	const unknownInitiative = await runPlanIO(Effect.gen(function* () {
+		yield* writeTasksJsonl(planDir, meta, tasks);
+		yield* saveHandoff(planDir, handoff);
+		yield* upsertPlanEntry(planName, {
+			status: "in-progress",
+			title: opts.title,
+			initiative,
+			depends_on: dependsOnPlans
+		});
+		yield* reconcileInitiativeForPlan(planName);
+		if (!initiative) return false;
+		return !(yield* readInitiativesManifest()).some((entry) => entry.name === initiative);
+	}));
+	const linkSuffix = initiative ? ` Linked to initiative "${initiative}"${unknownInitiative ? " (no initiatives.jsonl entry yet — create it with submit_initiative)" : ""}.` : "";
+	emit(Boolean(opts.json), {
+		plan_name: planName,
+		plan_dir: planDir,
+		task_count: tasks.length,
+		task_ids: tasks.map((t) => t.id),
+		initiative: initiative ?? null,
+		depends_on: dependsOnPlans ?? null,
+		unknown_initiative: unknownInitiative
+	}, `Plan "${opts.title}" saved with ${tasks.length} tasks in ${planDir}.${linkSuffix}`);
+}
+//#endregion
+//#region src/cli/commands/create-handoff.ts
+/**
+* `taskman create-handoff [content]` — write/replace HANDOFF.md for a plan.
+*
+* Lets a foreign harness hand off markdown without going through the plan-mode
+* extension: content comes from an inline argument, `--file <path>`, or stdin.
+*/
+async function createHandoffCommand(content, opts) {
+	const { planName, planDir } = await resolvePlanDir(opts.plan);
+	const markdown = await resolveContent(content, opts.file, "handoff");
+	await runPlanIO(saveHandoff(planDir, markdown));
+	emit(Boolean(opts.json), {
+		plan_name: planName,
+		path: `${planDir}/HANDOFF.md`,
+		bytes: Buffer.byteLength(markdown)
+	}, `Wrote HANDOFF.md (${Buffer.byteLength(markdown)} bytes) for ${planName}.`);
+}
+//#endregion
 //#region src/cli.ts
 /**
 * `taskman` CLI — drive the `.plans/` task ledger from any Node harness.
@@ -279,6 +417,8 @@ function buildProgram() {
 	program.command("update-task").description("Set a task status (done|skipped|blocked|pending)").argument("<id>", "task id, e.g. t-001").argument("<status>", "done|skipped|blocked|pending").option("--plan <name>", "plan to target").option("--notes <text>", "notes recorded on the task").option("--json", "machine-readable JSON output").action((id, status, opts) => updateTaskCommand(id, status, opts));
 	program.command("add-task").description("Append a deferred follow-up task").argument("<description>", "short task label").requiredOption("--reason <text>", "why this follow-up matters").option("--plan <name>", "plan to target").option("--details <text>", "fuller implementation notes").option("--json", "machine-readable JSON output").action((description, opts) => addTaskCommand(description, opts));
 	program.command("reconcile").description("Detect (and with --apply, repair) status drift").option("--apply", "repair safe in-progress→done drift").option("--json", "machine-readable JSON output").action((opts) => reconcileCommand(opts));
+	program.command("create-plan").description("Create a plan (tasks.jsonl + HANDOFF.md + registry entry) from any harness").requiredOption("--name <name>", "short kebab-case plan name").requiredOption("--title <title>", "human-readable plan title").option("--handoff <text>", "HANDOFF.md markdown (inline)").option("--handoff-file <path>", "read HANDOFF.md markdown from a file (\"-\" for stdin)").option("--tasks <json>", "tasks as an inline JSON array of { description, ... }").option("--tasks-file <path>", "read the tasks JSON array from a file (\"-\" for stdin)").option("--initiative <name>", "parent initiative name to link this plan to").option("--depends-on <names>", "comma-separated plan names this plan depends on").option("--json", "machine-readable JSON output").action((opts) => createPlanCommand(opts));
+	program.command("create-handoff").description("Write/replace HANDOFF.md for a plan from any harness").argument("[content]", "HANDOFF.md markdown (inline); else use --file or stdin").option("--plan <name>", "plan to target").option("--file <path>", "read markdown from a file (\"-\" for stdin)").option("--json", "machine-readable JSON output").action((content, opts) => createHandoffCommand(content, opts));
 	program.command("close").description("Set a plan lifecycle status").argument("<status>", "done|superseded|abandoned|in-progress").option("--plan <name>", "plan to target").option("--reason <text>", "why (recorded in the registry)").option("--json", "machine-readable JSON output").action((status, opts) => closePlanCommand(status, opts));
 	program.command("close-initiative").description("Set an initiative lifecycle status").argument("<status>", "done|superseded|abandoned|in-progress").argument("<name>", "initiative name").option("--reason <text>", "why (recorded in the registry)").option("--json", "machine-readable JSON output").action((status, name, opts) => closeInitiativeCommand(status, name, opts));
 	return program;

package/dist/index.d.mts

@@ -301,12 +301,36 @@ interface FileSystemService {
 }
 declare const FileSystem_base: Context.TagClass<FileSystem, "PlanMode/FileSystem", FileSystemService>;
 declare class FileSystem extends FileSystem_base {}
+/**
+ * Build a node-backed filesystem service whose relative paths resolve against
+ * `root`. All storage programs use relative `.plans/...` paths, so prefixing a
+ * root relocates the entire plan registry coherently (manifests, plan dirs,
+ * handoffs) to another working directory.
+ *
+ * `resolve(root, p)` is a no-op for already-absolute paths and reproduces the
+ * default `process.cwd()` behaviour exactly when `root === process.cwd()`, so
+ * the common (no-target) path is unchanged.
+ */
+declare function makeNodeFileSystemService(root: string): FileSystemService;
+/**
+ * Default service: relative paths resolve against the current working directory
+ * at call time. `resolve('.', p)` is equivalent to `resolve(process.cwd(), p)`,
+ * so this matches the historical behaviour of passing raw relative paths to fs.
+ */
 declare const nodeFileSystemService: FileSystemService;
 //#endregion
 //#region src/effects/runtime.d.ts
-declare function makeRuntimeLayer(): Layer.Layer<FileSystem>;
-/** Build a bridge that runs storage programs against the live filesystem layer. */
-declare function makePlanRuntime(): <A, E>(program: Effect.Effect<A, E, FileSystem>) => Promise<A>;
+/**
+ * Build the live filesystem layer. Pass `root` to relocate the whole `.plans/`
+ * registry under another working directory; omit it for the default (relative
+ * paths resolve against the current working directory).
+ */
+declare function makeRuntimeLayer(root?: string): Layer.Layer<FileSystem>;
+/**
+ * Build a bridge that runs storage programs against the live filesystem layer.
+ * Pass `root` to target an external working directory's `.plans/` registry.
+ */
+declare function makePlanRuntime(root?: string): <A, E>(program: Effect.Effect<A, E, FileSystem>) => Promise<A>;
 type RunPlanIO = ReturnType<typeof makePlanRuntime>;
 //#endregion
 //#region src/storage/task-storage.d.ts
@@ -679,4 +703,4 @@ declare function toKebabCase(name: string): string;
  */
 declare function nextTaskId(existingIds: readonly string[]): string;
 //#endregion
-export { AddTaskInput, type ExecPendingConfig, ExecPendingConfigSchema, FileSystem, type FileSystemService, InitiativeDriftRow, initiatives_d_exports as InitiativeListing, type InitiativeManifestEntry, InitiativeManifestEntrySchema, InitiativeMemberRow, InitiativeRollup, type InitiativeStatus, InitiativeStatusSchema, type InitiativeUpsert, JsonlParseError, JsonlValidationError, MissingMetaRecord, type PlanData, PlanDriftRow, plans_d_exports as PlanListing, type PlanManifestEntry, PlanManifestEntrySchema, PlanReadError, PlanReadiness, type PlanStatus, PlanStatusSchema, PlanStorageError, type PlanUpsert, PlanWriteError, ResolvedPlanName, type RunPlanIO, type TaskMeta, TaskMetaSchema, TaskNotFound, type TaskOrigin, TaskOriginSchema, type TaskRecord, TaskRecordSchema, type TaskStatus, TaskStatusSchema, TasksFileNotFound, TasksLineSchema, TasksSnapshot, type ThinkingLevel, UpdatedTaskResult, activeTasksResolved, appendDeferredTask, applyInitiativeReconcile, applyInitiativeUpsert, applyPlanUpsert, applyReconcile, causeMessage, collectInitiativeDrift, collectPlanDrift, computePlanReadiness, decodeExecPendingConfig, decodeInitiativeManifestEntry, decodePlanManifestEntry, decodeTaskMeta, decodeTaskRecord, decodeTasksLine, deferredTasks, errorMessage, initiativeRollup, isInitiativeFinalizable, isPlanFinalizable, isTerminalStatus, loadHandoff, loadPlanData, makePlanRuntime, makeRuntimeLayer, membersOf, mutateInitiativesManifest, mutatePlansManifest, nextTaskId, nodeFileSystemService, normalizePlanName, reactivateForExecution, readInitiativesManifest, readPlansManifest, readTasksJsonl, reconcileInitiativeForPlan, reconcileInitiativeStatus, reconcilePlanStatus, resolvePlanByName, saveHandoff, saveInitiative, setTaskStatus, toKebabCase, toNativeError, updateTask, upsertInitiativeEntry, upsertPlanEntry, withFileLock, writeFileAtomic, writeInitiativesManifest, writePlansManifest, writeTasksJsonl };
+export { AddTaskInput, type ExecPendingConfig, ExecPendingConfigSchema, FileSystem, type FileSystemService, InitiativeDriftRow, initiatives_d_exports as InitiativeListing, type InitiativeManifestEntry, InitiativeManifestEntrySchema, InitiativeMemberRow, InitiativeRollup, type InitiativeStatus, InitiativeStatusSchema, type InitiativeUpsert, JsonlParseError, JsonlValidationError, MissingMetaRecord, type PlanData, PlanDriftRow, plans_d_exports as PlanListing, type PlanManifestEntry, PlanManifestEntrySchema, PlanReadError, PlanReadiness, type PlanStatus, PlanStatusSchema, PlanStorageError, type PlanUpsert, PlanWriteError, ResolvedPlanName, type RunPlanIO, type TaskMeta, TaskMetaSchema, TaskNotFound, type TaskOrigin, TaskOriginSchema, type TaskRecord, TaskRecordSchema, type TaskStatus, TaskStatusSchema, TasksFileNotFound, TasksLineSchema, TasksSnapshot, type ThinkingLevel, UpdatedTaskResult, activeTasksResolved, appendDeferredTask, applyInitiativeReconcile, applyInitiativeUpsert, applyPlanUpsert, applyReconcile, causeMessage, collectInitiativeDrift, collectPlanDrift, computePlanReadiness, decodeExecPendingConfig, decodeInitiativeManifestEntry, decodePlanManifestEntry, decodeTaskMeta, decodeTaskRecord, decodeTasksLine, deferredTasks, errorMessage, initiativeRollup, isInitiativeFinalizable, isPlanFinalizable, isTerminalStatus, loadHandoff, loadPlanData, makeNodeFileSystemService, makePlanRuntime, makeRuntimeLayer, membersOf, mutateInitiativesManifest, mutatePlansManifest, nextTaskId, nodeFileSystemService, normalizePlanName, reactivateForExecution, readInitiativesManifest, readPlansManifest, readTasksJsonl, reconcileInitiativeForPlan, reconcileInitiativeStatus, reconcilePlanStatus, resolvePlanByName, saveHandoff, saveInitiative, setTaskStatus, toKebabCase, toNativeError, updateTask, upsertInitiativeEntry, upsertPlanEntry, withFileLock, writeFileAtomic, writeInitiativesManifest, writePlansManifest, writeTasksJsonl };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { $ as nodeFileSystemService, A as reactivateForExecution, B as reconcilePlanStatus, C as isInitiativeFinalizable, Ct as TasksFileNotFound, D as activeTasksResolved, E as reconcileInitiativeStatus, Et as toNativeError, F as writeInitiativesManifest, G as saveInitiative, H as writePlansManifest, I as applyPlanUpsert, J as writeTasksJsonl, K as readTasksJsonl, L as isTerminalStatus, M as mutateInitiativesManifest, N as readInitiativesManifest, O as deferredTasks, P as upsertInitiativeEntry, Q as FileSystem, R as mutatePlansManifest, S as initiativeRollup, St as TaskNotFound, T as reconcileInitiativeForPlan, Tt as errorMessage, U as loadHandoff, V as upsertPlanEntry, W as saveHandoff, X as makePlanRuntime, Y as withFileLock, Z as makeRuntimeLayer, _ as applyInitiativeReconcile, _t as JsonlParseError, at as PlanStatusSchema, b as collectPlanDrift, bt as PlanReadError, c as plans_exports, ct as TaskRecordSchema, d as setTaskStatus, dt as decodeExecPendingConfig, et as writeFileAtomic, f as nextTaskId, ft as decodeInitiativeManifestEntry, g as resolvePlanByName, gt as decodeTasksLine, h as normalizePlanName, ht as decodeTaskRecord, it as PlanManifestEntrySchema, j as applyInitiativeUpsert, k as isPlanFinalizable, lt as TaskStatusSchema, m as loadPlanData, mt as decodeTaskMeta, nt as InitiativeManifestEntrySchema, ot as TaskMetaSchema, p as toKebabCase, pt as decodePlanManifestEntry, q as updateTask, r as initiatives_exports, rt as InitiativeStatusSchema, st as TaskOriginSchema, tt as ExecPendingConfigSchema, u as appendDeferredTask, ut as TasksLineSchema, v as applyReconcile, vt as JsonlValidationError, w as membersOf, wt as causeMessage, x as computePlanReadiness, xt as PlanWriteError, y as collectInitiativeDrift, yt as MissingMetaRecord, z as readPlansManifest } from "./initiatives-Ij_teFl_.mjs";
-export { ExecPendingConfigSchema, FileSystem, initiatives_exports as InitiativeListing, InitiativeManifestEntrySchema, InitiativeStatusSchema, JsonlParseError, JsonlValidationError, MissingMetaRecord, plans_exports as PlanListing, PlanManifestEntrySchema, PlanReadError, PlanStatusSchema, PlanWriteError, TaskMetaSchema, TaskNotFound, TaskOriginSchema, TaskRecordSchema, TaskStatusSchema, TasksFileNotFound, TasksLineSchema, activeTasksResolved, appendDeferredTask, applyInitiativeReconcile, applyInitiativeUpsert, applyPlanUpsert, applyReconcile, causeMessage, collectInitiativeDrift, collectPlanDrift, computePlanReadiness, decodeExecPendingConfig, decodeInitiativeManifestEntry, decodePlanManifestEntry, decodeTaskMeta, decodeTaskRecord, decodeTasksLine, deferredTasks, errorMessage, initiativeRollup, isInitiativeFinalizable, isPlanFinalizable, isTerminalStatus, loadHandoff, loadPlanData, makePlanRuntime, makeRuntimeLayer, membersOf, mutateInitiativesManifest, mutatePlansManifest, nextTaskId, nodeFileSystemService, normalizePlanName, reactivateForExecution, readInitiativesManifest, readPlansManifest, readTasksJsonl, reconcileInitiativeForPlan, reconcileInitiativeStatus, reconcilePlanStatus, resolvePlanByName, saveHandoff, saveInitiative, setTaskStatus, toKebabCase, toNativeError, updateTask, upsertInitiativeEntry, upsertPlanEntry, withFileLock, writeFileAtomic, writeInitiativesManifest, writePlansManifest, writeTasksJsonl };
+import { $ as makeNodeFileSystemService, A as reactivateForExecution, B as reconcilePlanStatus, C as isInitiativeFinalizable, Ct as TaskNotFound, D as activeTasksResolved, Dt as toNativeError, E as reconcileInitiativeStatus, Et as errorMessage, F as writeInitiativesManifest, G as saveInitiative, H as writePlansManifest, I as applyPlanUpsert, J as writeTasksJsonl, K as readTasksJsonl, L as isTerminalStatus, M as mutateInitiativesManifest, N as readInitiativesManifest, O as deferredTasks, P as upsertInitiativeEntry, Q as FileSystem, R as mutatePlansManifest, S as initiativeRollup, St as PlanWriteError, T as reconcileInitiativeForPlan, Tt as causeMessage, U as loadHandoff, V as upsertPlanEntry, W as saveHandoff, X as makePlanRuntime, Y as withFileLock, Z as makeRuntimeLayer, _ as applyInitiativeReconcile, _t as decodeTasksLine, at as PlanManifestEntrySchema, b as collectPlanDrift, bt as MissingMetaRecord, c as plans_exports, ct as TaskOriginSchema, d as setTaskStatus, dt as TasksLineSchema, et as nodeFileSystemService, f as nextTaskId, ft as decodeExecPendingConfig, g as resolvePlanByName, gt as decodeTaskRecord, h as normalizePlanName, ht as decodeTaskMeta, it as InitiativeStatusSchema, j as applyInitiativeUpsert, k as isPlanFinalizable, lt as TaskRecordSchema, m as loadPlanData, mt as decodePlanManifestEntry, nt as ExecPendingConfigSchema, ot as PlanStatusSchema, p as toKebabCase, pt as decodeInitiativeManifestEntry, q as updateTask, r as initiatives_exports, rt as InitiativeManifestEntrySchema, st as TaskMetaSchema, tt as writeFileAtomic, u as appendDeferredTask, ut as TaskStatusSchema, v as applyReconcile, vt as JsonlParseError, w as membersOf, wt as TasksFileNotFound, x as computePlanReadiness, xt as PlanReadError, y as collectInitiativeDrift, yt as JsonlValidationError, z as readPlansManifest } from "./initiatives-AtmFo2DU.mjs";
+export { ExecPendingConfigSchema, FileSystem, initiatives_exports as InitiativeListing, InitiativeManifestEntrySchema, InitiativeStatusSchema, JsonlParseError, JsonlValidationError, MissingMetaRecord, plans_exports as PlanListing, PlanManifestEntrySchema, PlanReadError, PlanStatusSchema, PlanWriteError, TaskMetaSchema, TaskNotFound, TaskOriginSchema, TaskRecordSchema, TaskStatusSchema, TasksFileNotFound, TasksLineSchema, activeTasksResolved, appendDeferredTask, applyInitiativeReconcile, applyInitiativeUpsert, applyPlanUpsert, applyReconcile, causeMessage, collectInitiativeDrift, collectPlanDrift, computePlanReadiness, decodeExecPendingConfig, decodeInitiativeManifestEntry, decodePlanManifestEntry, decodeTaskMeta, decodeTaskRecord, decodeTasksLine, deferredTasks, errorMessage, initiativeRollup, isInitiativeFinalizable, isPlanFinalizable, isTerminalStatus, loadHandoff, loadPlanData, makeNodeFileSystemService, makePlanRuntime, makeRuntimeLayer, membersOf, mutateInitiativesManifest, mutatePlansManifest, nextTaskId, nodeFileSystemService, normalizePlanName, reactivateForExecution, readInitiativesManifest, readPlansManifest, readTasksJsonl, reconcileInitiativeForPlan, reconcileInitiativeStatus, reconcilePlanStatus, resolvePlanByName, saveHandoff, saveInitiative, setTaskStatus, toKebabCase, toNativeError, updateTask, upsertInitiativeEntry, upsertPlanEntry, withFileLock, writeFileAtomic, writeInitiativesManifest, writePlansManifest, writeTasksJsonl };

package/dist/{initiatives-Ij_teFl_.mjs → initiatives-AtmFo2DU.mjs}

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
 import { Context, Data, Effect, Either, Layer, Option, Schema } from "effect";
 import { mkdir, open, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
 import { createWriteStream } from "node:fs";
-import { dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
 //#region src/errors.ts
 /**
@@ -220,48 +220,67 @@ async function syncDirectory(dir) {
 * all failure modes typed (`PlanReadError` / `PlanWriteError`).
 */
 var FileSystem = class extends Context.Tag("PlanMode/FileSystem")() {};
-const nodeFileSystemService = {
-	readFileString: (path) => Effect.tryPromise({
-		try: () => readFile(path, "utf-8"),
-		catch: (cause) => new PlanReadError({
-			path,
-			cause
-		})
-	}),
-	writeFileString: (path, data) => Effect.tryPromise({
-		try: () => writeFile(path, data, "utf-8"),
-		catch: (cause) => new PlanWriteError({
-			path,
-			cause
-		})
-	}),
-	writeFileAtomic: (path, data) => writeFileAtomic(path, data),
-	makeDir: (path) => Effect.tryPromise({
-		try: async () => {
-			await mkdir(path, { recursive: true });
-		},
-		catch: (cause) => new PlanWriteError({
-			path,
-			cause
-		})
-	}),
-	listDirectories: (path) => Effect.tryPromise({
-		try: async () => {
-			return (await readdir(path, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-		},
-		catch: (cause) => new PlanReadError({
-			path,
-			cause
-		})
-	}),
-	removeFile: (path) => Effect.tryPromise({
-		try: () => unlink(path),
-		catch: (cause) => new PlanWriteError({
-			path,
-			cause
+/**
+* Build a node-backed filesystem service whose relative paths resolve against
+* `root`. All storage programs use relative `.plans/...` paths, so prefixing a
+* root relocates the entire plan registry coherently (manifests, plan dirs,
+* handoffs) to another working directory.
+*
+* `resolve(root, p)` is a no-op for already-absolute paths and reproduces the
+* default `process.cwd()` behaviour exactly when `root === process.cwd()`, so
+* the common (no-target) path is unchanged.
+*/
+function makeNodeFileSystemService(root) {
+	const at = (path) => resolve(root, path);
+	return {
+		readFileString: (path) => Effect.tryPromise({
+			try: () => readFile(at(path), "utf-8"),
+			catch: (cause) => new PlanReadError({
+				path,
+				cause
+			})
+		}),
+		writeFileString: (path, data) => Effect.tryPromise({
+			try: () => writeFile(at(path), data, "utf-8"),
+			catch: (cause) => new PlanWriteError({
+				path,
+				cause
+			})
+		}),
+		writeFileAtomic: (path, data) => writeFileAtomic(at(path), data),
+		makeDir: (path) => Effect.tryPromise({
+			try: async () => {
+				await mkdir(at(path), { recursive: true });
+			},
+			catch: (cause) => new PlanWriteError({
+				path,
+				cause
+			})
+		}),
+		listDirectories: (path) => Effect.tryPromise({
+			try: async () => {
+				return (await readdir(at(path), { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+			},
+			catch: (cause) => new PlanReadError({
+				path,
+				cause
+			})
+		}),
+		removeFile: (path) => Effect.tryPromise({
+			try: () => unlink(at(path)),
+			catch: (cause) => new PlanWriteError({
+				path,
+				cause
+			})
 		})
-	})
-};
+	};
+}
+/**
+* Default service: relative paths resolve against the current working directory
+* at call time. `resolve('.', p)` is equivalent to `resolve(process.cwd(), p)`,
+* so this matches the historical behaviour of passing raw relative paths to fs.
+*/
+const nodeFileSystemService = makeNodeFileSystemService(".");
 //#endregion
 //#region src/effects/runtime.ts
 /**
@@ -271,12 +290,21 @@ const nodeFileSystemService = {
 * through the `runPlanIO` bridge so the imperative pi event handlers keep their
 * `await fn(...)` shape.
 */
-function makeRuntimeLayer() {
-	return Layer.succeed(FileSystem, nodeFileSystemService);
+/**
+* Build the live filesystem layer. Pass `root` to relocate the whole `.plans/`
+* registry under another working directory; omit it for the default (relative
+* paths resolve against the current working directory).
+*/
+function makeRuntimeLayer(root) {
+	const service = root === void 0 ? nodeFileSystemService : makeNodeFileSystemService(root);
+	return Layer.succeed(FileSystem, service);
 }
-/** Build a bridge that runs storage programs against the live filesystem layer. */
-function makePlanRuntime() {
-	const layer = makeRuntimeLayer();
+/**
+* Build a bridge that runs storage programs against the live filesystem layer.
+* Pass `root` to target an external working directory's `.plans/` registry.
+*/
+function makePlanRuntime(root) {
+	const layer = makeRuntimeLayer(root);
 	return function runPlanIO(program) {
 		return Effect.runPromise(program.pipe(Effect.provide(layer)));
 	};
@@ -1250,4 +1278,4 @@ function parseInitiativeFilter(raw) {
 	return "all";
 }
 //#endregion
-export { nodeFileSystemService as $, reactivateForExecution as A, reconcilePlanStatus as B, isInitiativeFinalizable as C, TasksFileNotFound as Ct, activeTasksResolved as D, reconcileInitiativeStatus as E, toNativeError as Et, writeInitiativesManifest as F, saveInitiative as G, writePlansManifest as H, applyPlanUpsert as I, writeTasksJsonl as J, readTasksJsonl as K, isTerminalStatus$1 as L, mutateInitiativesManifest as M, readInitiativesManifest as N, deferredTasks as O, upsertInitiativeEntry as P, FileSystem as Q, mutatePlansManifest as R, initiativeRollup as S, TaskNotFound as St, reconcileInitiativeForPlan as T, errorMessage as Tt, loadHandoff as U, upsertPlanEntry as V, saveHandoff as W, makePlanRuntime as X, withFileLock as Y, makeRuntimeLayer as Z, applyInitiativeReconcile as _, JsonlParseError as _t, filterPlans as a, PlanStatusSchema as at, collectPlanDrift as b, PlanReadError as bt, plans_exports as c, TaskRecordSchema as ct, setTaskStatus as d, decodeExecPendingConfig as dt, writeFileAtomic as et, nextTaskId as f, decodeInitiativeManifestEntry as ft, resolvePlanByName as g, decodeTasksLine as gt, normalizePlanName as h, decodeTaskRecord as ht, loadInitiativeListItems as i, PlanManifestEntrySchema as it, applyInitiativeUpsert as j, isPlanFinalizable as k, sortPlans as l, TaskStatusSchema as lt, loadPlanData as m, decodeTaskMeta as mt, formatInitiativeList as n, InitiativeManifestEntrySchema as nt, formatPlanList as o, TaskMetaSchema as ot, toKebabCase as p, decodePlanManifestEntry as pt, updateTask as q, initiatives_exports as r, InitiativeStatusSchema as rt, loadPlanListItems as s, TaskOriginSchema as st, filterInitiatives as t, ExecPendingConfigSchema as tt, appendDeferredTask as u, TasksLineSchema as ut, applyReconcile as v, JsonlValidationError as vt, membersOf as w, causeMessage as wt, computePlanReadiness as x, PlanWriteError as xt, collectInitiativeDrift as y, MissingMetaRecord as yt, readPlansManifest as z };
+export { makeNodeFileSystemService as $, reactivateForExecution as A, reconcilePlanStatus as B, isInitiativeFinalizable as C, TaskNotFound as Ct, activeTasksResolved as D, toNativeError as Dt, reconcileInitiativeStatus as E, errorMessage as Et, writeInitiativesManifest as F, saveInitiative as G, writePlansManifest as H, applyPlanUpsert as I, writeTasksJsonl as J, readTasksJsonl as K, isTerminalStatus$1 as L, mutateInitiativesManifest as M, readInitiativesManifest as N, deferredTasks as O, upsertInitiativeEntry as P, FileSystem as Q, mutatePlansManifest as R, initiativeRollup as S, PlanWriteError as St, reconcileInitiativeForPlan as T, causeMessage as Tt, loadHandoff as U, upsertPlanEntry as V, saveHandoff as W, makePlanRuntime as X, withFileLock as Y, makeRuntimeLayer as Z, applyInitiativeReconcile as _, decodeTasksLine as _t, filterPlans as a, PlanManifestEntrySchema as at, collectPlanDrift as b, MissingMetaRecord as bt, plans_exports as c, TaskOriginSchema as ct, setTaskStatus as d, TasksLineSchema as dt, nodeFileSystemService as et, nextTaskId as f, decodeExecPendingConfig as ft, resolvePlanByName as g, decodeTaskRecord as gt, normalizePlanName as h, decodeTaskMeta as ht, loadInitiativeListItems as i, InitiativeStatusSchema as it, applyInitiativeUpsert as j, isPlanFinalizable as k, sortPlans as l, TaskRecordSchema as lt, loadPlanData as m, decodePlanManifestEntry as mt, formatInitiativeList as n, ExecPendingConfigSchema as nt, formatPlanList as o, PlanStatusSchema as ot, toKebabCase as p, decodeInitiativeManifestEntry as pt, updateTask as q, initiatives_exports as r, InitiativeManifestEntrySchema as rt, loadPlanListItems as s, TaskMetaSchema as st, filterInitiatives as t, writeFileAtomic as tt, appendDeferredTask as u, TaskStatusSchema as ut, applyReconcile as v, JsonlParseError as vt, membersOf as w, TasksFileNotFound as wt, computePlanReadiness as x, PlanReadError as xt, collectInitiativeDrift as y, JsonlValidationError as yt, readPlansManifest as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/taskman",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Standalone task-management engine + CLI over a .plans/ JSONL ledger — the plan-mode core, usable from any Node harness",
   "keywords": [
     "tasks",

package/skills/taskman/core/SKILL.md

@@ -2,13 +2,14 @@
 name: taskman/core
 description: >
   Drive the taskman CLI and engine over a .plans/ JSONL ledger — plans,
-  initiatives, and tasks. Load when running `taskman` commands (status, list,
-  update-task, add-task, reconcile, close), tracking plan/task progress across
-  sessions or harnesses, or calling @dreki-gg/taskman as a library. Covers the
-  status-is-a-projection model, stateless plan resolution, and reconcile.
+  initiatives, and tasks. Load when running `taskman` commands (create-plan,
+  create-handoff, status, list, update-task, add-task, reconcile, close),
+  tracking plan/task progress across sessions or harnesses, or calling
+  @dreki-gg/taskman as a library. Covers the status-is-a-projection model,
+  stateless plan resolution, and reconcile.
 type: core
 library: "@dreki-gg/taskman"
-library_version: "0.2.1"
+library_version: "0.4.0"
 sources:
   - "dreki-gg/pi-extensions:packages/taskman/README.md"
   - "dreki-gg/pi-extensions:packages/taskman/src/cli.ts"
@@ -65,6 +66,23 @@ taskman add-task "handle empty input" --reason "found gap while implementing"
 taskman reconcile --apply       # repair safe (in-progress→done) drift
 ```
 
+### Creating plans from any harness
+
+Plans don't have to originate in plan-mode's `submit_plan` tool. The CLI creates
+the same durable artifacts (tasks.jsonl + HANDOFF.md + registry entry) so a
+foreign harness can seed the ledger directly. Handoff/task payloads accept an
+inline value, a `--*-file <path>`, or piped stdin.
+
+```bash
+echo "$MARKDOWN" | taskman create-plan --name my-plan --title "My Plan" \
+  --handoff-file - --tasks '[{"description":"do it"}]'   # tasks get t-NNN ids
+taskman create-handoff --plan my-plan --file HANDOFF.md   # write/replace prose
+```
+
+Use `--initiative <name>` to link the plan (create the initiative first) and
+`--depends-on a,b` for plan-level ordering. Task creation here is plan setup —
+distinct from `add-task`, which records a *deferred* follow-up (see below).
+
 ### Machine-readable output
 
 Every command prints human text by default and accepts `--json`: