@danypops/papyrus 0.11.0 → 0.11.2

package/README.md

@@ -168,6 +168,7 @@ papyrus tasks pause --json
 papyrus tasks unpause --json
 papyrus tasks clear-focus --json
 papyrus tasks update <id> --title "Revised title" --body "Revised body" --json
+papyrus tasks update <id> --status todo --reason "created with legacy default" --json
 papyrus tasks start <id> --json
 papyrus tasks submit <id> --json
 papyrus tasks complete <id> --json
@@ -201,7 +202,7 @@ Papyrus also injects an Alef-style reconciliation block at `before_agent_start`
 
 After assembling each system-prompt addition, Papyrus emits a versioned `papyrus.context-injection.v1` observation on Pi's shared extension event bus. It contains only exact byte/character sizes, Rule count, a labeled token estimate, prompt share, sequence, and a SHA-256 payload fingerprint; Rule/Task text, prompts, project paths, and credentials are never included. Jittor can persist and assess these observations without Papyrus maintaining a second telemetry store.
 
-Task edits mutate the existing Papyrus-owned Task identity and append an `updated` event; title, body, and labels can be revised without canceling the Task or creating a replacement. Lifecycle, relationships, gates, checklist metadata, scope, and focus remain intact.
+Task edits mutate the existing Papyrus-owned Task identity and append an `updated` event; title, body, and labels can be revised without canceling the Task or creating a replacement. Lifecycle, relationships, gates, checklist metadata, scope, and focus remain intact. The same `update` action provides a narrowly guarded recovery for Tasks accidentally created terminal by a legacy default: `status=todo` requires an audit reason, cannot be combined with content edits, only applies when `created` is the sole lifecycle event, and appends `creation_recovered` rather than rewriting history.
 
 ## Why
 

package/extension/src/domain-tools.ts

@@ -32,7 +32,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, contain. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, contain. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/cli.ts

@@ -75,7 +75,7 @@ const USAGE = `Usage:
   papyrus tasks scope [project|all|graph <root-id>] [--json]
   papyrus tasks assign-project <id> [project-root] [--json]
   papyrus tasks focus <id> [--json]
-  papyrus tasks update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--json]
+  papyrus tasks update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--status todo --reason <reason>] [--json]
   papyrus tasks complete <id> [--json]
   papyrus tasks start <id> [--json]
   papyrus tasks submit <id> [--json]
@@ -237,16 +237,21 @@ export async function runNoteCli(args: string[], client: TaskCliClient, projectR
 export async function runTaskCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
 	const json = args.includes("--json");
 	const positional: string[] = [];
-	const updateInput: { title?: string; body?: string; labels?: string[] } = {};
+	const updateInput: { title?: string; body?: string; labels?: string[]; status?: "todo" } = {};
+	let reason: string | undefined;
 	for (let index = 0; index < args.length; index++) {
 		const argument = args[index]!;
 		if (argument === "--json") continue;
-		if (argument === "--title" || argument === "--body" || argument === "--labels-json") {
+		if (argument === "--title" || argument === "--body" || argument === "--labels-json" || argument === "--status" || argument === "--reason") {
 			const value = args[++index];
 			if (value === undefined) throw new Error(`${argument} requires a value`);
 			if (argument === "--title") updateInput.title = value;
 			else if (argument === "--body") updateInput.body = value;
-			else {
+			else if (argument === "--reason") reason = value;
+			else if (argument === "--status") {
+				if (value !== "todo") throw new Error("--status only supports todo for accidental creation recovery");
+				updateInput.status = value;
+			} else {
 				const parsed = JSON.parse(value) as unknown;
 				if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== "string")) throw new Error("--labels-json requires a JSON string array");
 				updateInput.labels = parsed as string[];
@@ -256,6 +261,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 		positional.push(argument);
 	}
 	const [action, id, dependencyId] = positional;
+	if (reason !== undefined && action !== "update") throw new Error("--reason is only supported by tasks update");
 	let result: unknown;
 	let human: string;
 	switch (action) {
@@ -291,8 +297,12 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 		}
 		case "update": {
 			if (!id || dependencyId) throw new Error("tasks update requires exactly one task id");
-			if (Object.keys(updateInput).length === 0) throw new Error("tasks update requires --title, --body, or --labels-json");
-			const artifact = await client.call<Record<string, unknown>, CliArtifact>("tasks.update", { id, ...updateInput, actor: "user", source: "cli" });
+			if (Object.keys(updateInput).length === 0) throw new Error("tasks update requires --title, --body, --labels-json, or --status todo");
+			if (updateInput.status !== undefined && !reason?.trim()) throw new Error("tasks update --status requires --reason");
+			if (reason !== undefined && updateInput.status === undefined) throw new Error("tasks update --reason requires --status todo");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("tasks.update", {
+				id, ...updateInput, ...(reason ? { reason } : {}), actor: "user", source: "cli",
+			});
 			result = artifact;
 			human = `Updated: ${artifactLabel(artifact)}`;
 			break;

package/src/constants.ts

@@ -142,6 +142,22 @@ export const SEED_STATUSES = [
 	{ name: "deprecated", kind: "skill" },
 ] as const;
 
+/**
+ * The initial status a newly created artifact of a kind gets when no caller-supplied
+ * status is given. This must be an explicit, named mapping — never derived from row order
+ * in the `statuses` table (SEED_STATUSES' listed order, or a migration's insertion order,
+ * is not a semantic guarantee; a migrated database can freely have a different physical
+ * row order for the same logical status set). Deriving "the default" from "whichever row
+ * happens to be first by rowid" was the root cause of a real production defect where
+ * migrated databases created new Tasks as done instead of todo.
+ */
+export const DEFAULT_STATUS_BY_KIND: Readonly<Record<string, string>> = {
+	doc: "draft",
+	task: "todo",
+	rule: "active",
+	skill: "active",
+};
+
 /**
  * Universal relation names — any kind can link to any kind.
  *

package/src/domain/task-event.ts

@@ -9,6 +9,7 @@ export type TaskLifecycleStatus = "todo" | "in-progress" | "review" | "rejected"
 
 export const TASK_EVENT_TYPES = [
 	"created",
+	"creation_recovered",
 	"updated",
 	"started",
 	"submitted",

package/src/ops.ts

@@ -6,6 +6,7 @@ import { createRequire } from "node:module";
 import { exec } from "node:child_process";
 import type { Db } from "./db.ts";
 import { inTransaction } from "./db.ts";
+import { DEFAULT_STATUS_BY_KIND } from "./constants.ts";
 import type { Artifact, ArtifactQuery, CreateArtifactInput, UpdateArtifactInput } from "./domain/artifact.ts";
 import type { Gate, GateResult, GateRunOptions } from "./domain/gate.ts";
 export type { Artifact } from "./domain/artifact.ts";
@@ -102,9 +103,13 @@ function slugify(s: string): string {
 }
 
 function defaultStatusFor(db: Db, kind: string): string {
-	// First-inserted status per kind (seed order defines the default)
-	const row = db.prepare("SELECT name FROM statuses WHERE kind = ? ORDER BY rowid LIMIT 1").get(kind) as { name: string } | null;
-	return row?.name ?? "draft";
+	// Explicit per-kind mapping, never row order -- see DEFAULT_STATUS_BY_KIND's doc comment
+	// for the production defect this replaced (row order is not a semantic guarantee).
+	const candidate = DEFAULT_STATUS_BY_KIND[kind];
+	if (candidate === undefined) throw new Error(`no default status is configured for kind "${kind}"`);
+	const exists = db.prepare("SELECT 1 FROM statuses WHERE kind = ? AND name = ?").get(kind, candidate);
+	if (!exists) throw new Error(`configured default status "${candidate}" for kind "${kind}" is not a registered status`);
+	return candidate;
 }
 
 function rowToArtifact(row: Record<string, unknown>): Artifact {

package/src/service.ts

@@ -269,6 +269,7 @@ function handlers(
 			...(input["title"] !== undefined ? { title: optionalString(input, "title")! } : {}),
 			...(input["body"] !== undefined ? { body: optionalString(input, "body")! } : {}),
 			...(input["labels"] !== undefined ? { labels: optionalStringArray(input, "labels")! } : {}),
+			...(input["status"] !== undefined ? { status: string(input, "status") as "todo" } : {}),
 		}, eventContext(input)),
 		"tasks.list": (input) => tasks.list(taskFilter(input)),
 		"tasks.graph": (input) => tasks.graph(taskFilter(input)),

package/src/task-service.ts

@@ -24,6 +24,7 @@ export interface UpdateTaskInput {
 	title?: string;
 	body?: string;
 	labels?: string[];
+	status?: "todo";
 }
 
 export interface TaskFilter {
@@ -148,7 +149,7 @@ export class Tasks {
 				title: input.title,
 				body: input.body,
 				subtype: input.subtype,
-				status: input.status,
+				status: input.status ?? "todo",
 				labels: input.labels,
 				extra,
 				templateId: input.templateId,
@@ -161,9 +162,39 @@ export class Tasks {
 		});
 	}
 
+	private recoverCreation(id: string, context: TaskEventContext): Artifact {
+		if (!context.reason?.trim()) throw new Error("creation recovery requires an audit reason");
+		return this.events.atomic(() => {
+			const task = this.require(id);
+			if (task.status !== "done" && task.status !== "canceled") throw new Error(`cannot recover task creation from ${task.status}`);
+			const history = this.events.history(id, { direction: "asc", limit: 2 });
+			const created = history.events[0];
+			if (history.events.length !== 1 || history.nextCursor !== undefined || created?.type !== "created" || created.toStatus !== task.status) {
+				throw new Error("task was not terminal at creation");
+			}
+			const recovered = this.artifacts.setStatus(id, "todo");
+			if (!recovered) throw new Error(`task "${id}" not found`);
+			this.appendEvent({
+				taskId: id,
+				type: "creation_recovered",
+				fromStatus: task.status as TaskStatus,
+				toStatus: "todo",
+				evidence: { result: "terminal-at-creation" },
+			}, context);
+			return recovered;
+		});
+	}
+
 	update(id: string, input: UpdateTaskInput, context: TaskEventContext = {}): Artifact {
+		if (input.status !== undefined) {
+			if (input.status !== "todo") throw new Error("task status updates only support recovering creation to todo");
+			if (input.title !== undefined || input.body !== undefined || input.labels !== undefined) {
+				throw new Error("task creation recovery cannot be combined with content updates");
+			}
+			return this.recoverCreation(id, context);
+		}
 		const fields = (["title", "body", "labels"] as const).filter((field) => input[field] !== undefined);
-		if (fields.length === 0) throw new Error("task update requires title, body, or labels");
+		if (fields.length === 0) throw new Error("task update requires title, body, or labels; status todo is only valid for creation recovery");
 		if (input.title !== undefined && (input.title.trim().length === 0 || input.title.length > TASK_TITLE_MAX_LENGTH)) {
 			throw new Error(`title must be between 1 and ${TASK_TITLE_MAX_LENGTH} characters`);
 		}