@danypops/papyrus 0.45.2 → 0.46.0

package/src/domain-service-shared.ts

@@ -0,0 +1,162 @@
+/**
+ * Shared, kind-agnostic CRUD composition helpers used by docs/docs-service.ts,
+ * rules/rules-service.ts, and playbook/playbook-service.ts. Split out of the former
+ * domain-services.ts (which combined all three domains in one 849-line file) so each
+ * domain's own service file only imports the cross-domain pieces it actually needs.
+ */
+
+import type { Artifact } from "./artifact/artifact.ts";
+import type { ArtifactEventContext } from "./artifact/artifact-event.ts";
+import type { ArtifactScopeStore } from "./artifact/artifact-scope-store.ts";
+import type { ArtifactStore } from "./artifact/artifact-store.ts";
+import {
+	ARTIFACT_BODY_MAX_LENGTH,
+	ARTIFACT_LABEL_MAX_COUNT,
+	ARTIFACT_LABEL_MAX_LENGTH,
+	ARTIFACT_SCOPE_MAX_ARTIFACTS,
+	ARTIFACT_TITLE_MAX_LENGTH,
+} from "./constants.ts";
+import { normalizeProjectRoot } from "./domain/task-scope.ts";
+
+export interface UpdateContentInput {
+	title?: string;
+	body?: string;
+	labels?: string[];
+}
+
+export function requireContentUpdateFields(input: UpdateContentInput): void {
+	if (input.title === undefined && input.body === undefined && input.labels === undefined) {
+		throw new Error("update requires title, body, or labels");
+	}
+}
+
+export function assertTitleBounds(title: string | undefined): void {
+	if (title !== undefined && (title.trim().length === 0 || title.length > ARTIFACT_TITLE_MAX_LENGTH)) {
+		throw new Error(`title must be between 1 and ${ARTIFACT_TITLE_MAX_LENGTH} characters`);
+	}
+}
+
+export function assertBodyBounds(body: string | undefined): void {
+	if (body !== undefined && body.length > ARTIFACT_BODY_MAX_LENGTH)
+		throw new Error(`body cannot exceed ${ARTIFACT_BODY_MAX_LENGTH} characters`);
+}
+
+export function assertLabelsBounds(labels: string[] | undefined): void {
+	if (labels === undefined) return;
+	if (labels.length > ARTIFACT_LABEL_MAX_COUNT) throw new Error(`labels cannot exceed ${ARTIFACT_LABEL_MAX_COUNT} entries`);
+	if (labels.some((label) => label.length === 0 || label.length > ARTIFACT_LABEL_MAX_LENGTH)) {
+		throw new Error(`each label must be between 1 and ${ARTIFACT_LABEL_MAX_LENGTH} characters`);
+	}
+}
+
+export interface ListFilter {
+	status?: string;
+	text?: string;
+	limit?: number;
+	/** When supplied, results are limited to artifacts scoped to this project (or the unscoped bucket, for an empty string is not accepted -- use assignArtifactProject's own validation). */
+	projectRoot?: string;
+}
+
+/**
+ * Shared by listDocuments/listRules/listPlaybooks: when filter.projectRoot is given, resolve
+ * via ArtifactScopeStore first and post-filter by kind/status/text (mirrors Tasks.list's
+ * established scoped-listing shape); otherwise fall back to the existing unscoped query
+ * path unchanged, so every caller that predates project scoping keeps working exactly as
+ * before.
+ */
+export function listScoped(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	kind: string,
+	filter: ListFilter,
+	excludeSubtype?: string,
+): Artifact[] {
+	if (filter.projectRoot === undefined)
+		return artifacts.query({ kind, excludeSubtype, status: filter.status, text: filter.text, limit: filter.limit });
+	const limit = filter.limit ?? ARTIFACT_SCOPE_MAX_ARTIFACTS;
+	if (!Number.isInteger(limit) || limit < 1 || limit > ARTIFACT_SCOPE_MAX_ARTIFACTS) {
+		throw new Error(`list limit must be between 1 and ${ARTIFACT_SCOPE_MAX_ARTIFACTS}`);
+	}
+	const projectRoot = normalizeProjectRoot(filter.projectRoot);
+	const ids = scopes.ids(projectRoot, ARTIFACT_SCOPE_MAX_ARTIFACTS);
+	const text = filter.text?.toLowerCase();
+	return ids
+		.map((id) => artifacts.get(id))
+		.filter((artifact): artifact is Artifact => artifact?.kind === kind && artifact.subtype !== excludeSubtype)
+		.filter((artifact) => filter.status === undefined || artifact.status === filter.status)
+		.filter((artifact) => text === undefined || artifact.title.toLowerCase().includes(text) || artifact.body.toLowerCase().includes(text))
+		.sort((left, right) => right.updated_at.localeCompare(left.updated_at) || left.id.localeCompare(right.id))
+		.slice(0, limit);
+}
+
+export function requireKind(artifacts: ArtifactStore, id: string, kind: string): Artifact {
+	const artifact = artifacts.get(id);
+	if (!artifact) throw new Error(`${kind} artifact "${id}" not found`);
+	if (artifact.kind !== kind) throw new Error(`artifact "${id}" is not a ${kind}`);
+	return artifact;
+}
+
+/**
+ * Shared shape for a kind's own declarative status-transition table -- Document and Task
+ * already independently converged on this exact shape; Rule/Playbook used an inline ternary
+ * instead only because they happened to have just two states. See validateTransitionFrom's
+ * own comment for why this is split from runTransition rather than always combined.
+ */
+export type TransitionTable<Action extends string, Status extends string> = Record<Action, { from: Status[]; to: Status }>;
+
+/**
+ * The from/to-table lookup+validation half of a transition, split out from runTransition
+ * (below) so a caller with its own side effects gated on "is this action even valid from the
+ * current status" (e.g. Tasks.transition's dependency-blocking check and focus-store
+ * bookkeeping, which must run -- or not -- before the status write itself) can call this
+ * directly instead of duplicating the same lookup+throw three times. Every other caller
+ * (Document/Rule/Playbook, none of which have that ordering constraint) uses runTransition
+ * instead, which does this same check plus the write in one call.
+ */
+export function validateTransitionFrom<Action extends string, Status extends string>(
+	kind: string,
+	action: Action,
+	status: string,
+	table: TransitionTable<Action, Status>,
+): { from: Status[]; to: Status } {
+	const transition = table[action];
+	if (!transition.from.includes(status as Status)) throw new Error(`cannot ${action} ${kind} from ${status}`);
+	return transition;
+}
+
+/**
+ * Shared by transitionDocument/transitionRule/transitionPlaybook: validates the requested
+ * action is legal from the artifact's current status per its own kind's transition table, then
+ * writes the resulting status. Any authority/ownership guard (e.g. requireMutableDocument,
+ * requireLocallyOwnedContent) is the caller's own responsibility, resolved on `artifact`
+ * *before* calling this -- kept out of this primitive so it stays usable by a kind with no
+ * such guard (Rule, Playbook) without a no-op parameter every call site has to pass.
+ */
+export function runTransition<Action extends string, Status extends string>(
+	artifacts: ArtifactStore,
+	artifact: Artifact,
+	kind: string,
+	action: Action,
+	table: TransitionTable<Action, Status>,
+	context?: ArtifactEventContext,
+): Artifact {
+	const transition = validateTransitionFrom(kind, action, artifact.status, table);
+	return artifacts.setStatus(artifact.id, transition.to, context)!;
+}
+
+/** Shared by assignRuleProject/assignPlaybookProject. assignDocumentProject has its own body -- it must reject Notes via requireDocument, not the generic requireKind this helper uses. */
+export function assignArtifactProject(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	id: string,
+	kind: string,
+	projectRoot: string | undefined,
+): Artifact {
+	requireKind(artifacts, id, kind);
+	scopes.assign(
+		id,
+		projectRoot === undefined ? undefined : normalizeProjectRoot(projectRoot),
+		projectRoot === undefined ? "unscoped" : "explicit",
+	);
+	return artifacts.get(id)!;
+}

package/src/handlers/docs.ts

@@ -7,7 +7,7 @@ import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
-import { listDocuments } from "../domain-services.ts";
+import { listDocuments } from "../docs/docs-service.ts";
 import { docsOperations } from "../modules/docs.ts";
 import { booleanProp, createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 

package/src/handlers/playbooks.ts

@@ -21,9 +21,9 @@
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
-import { listPlaybooks } from "../domain-services.ts";
 import { playbooksOperations } from "../modules/playbooks.ts";
 import type { PlaybookInvocationResult, PlaybookMissingArguments } from "../playbook/playbook-execution.ts";
+import { listPlaybooks } from "../playbook/playbook-service.ts";
 import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
 import type { TaskEventStore } from "../stores/task-event-store.ts";
 import type { TaskScopeStore } from "../stores/task-scope-store.ts";
@@ -92,8 +92,10 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 			steps: { type: "array" },
 			tools: { type: "array" },
 			arguments: { type: "array" },
+			subtype: stringProp,
 			labels: { type: "array" },
 			extra: { type: "object" },
+			template_id: stringProp,
 			project_root: stringProp,
 			actor: stringProp,
 			source: stringProp,

package/src/handlers/rules.ts

@@ -7,8 +7,8 @@
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
-import { listRules } from "../domain-services.ts";
 import { rulesOperations } from "../modules/rules.ts";
+import { listRules } from "../rules/rules-service.ts";
 import { booleanProp, createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "rules";
@@ -49,7 +49,7 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 
 	define(
 		"create",
-		"Creates a Rule -- a standing constraint injected into the agent system prompt while active. project_root is optional (omitted = unscoped). The response includes combinedLength (condition+action+body character count) and a non-blocking warning once it exceeds the ~600-character soft target (hard-rejected past 4000).",
+		"Creates a Rule -- a standing constraint injected into the agent system prompt while active. Plain Rules start active; a template_id creates an inert draft that must pass the template's completionRequired fields through rules.enable. project_root is optional (omitted = unscoped). The response includes combinedLength (condition+action+body character count) and a non-blocking warning once it exceeds the ~600-character soft target (hard-rejected past 4000).",
 		"local-write",
 		{
 			title: stringProp,
@@ -57,8 +57,10 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 			condition: stringProp,
 			rule_action: stringProp,
 			severity: { type: "string", enum: ["block", "warn", "info"] },
+			subtype: stringProp,
 			labels: { type: "array" } as unknown as { type: string },
 			extra: { type: "object" } as unknown as { type: string },
+			template_id: stringProp,
 			project_root: stringProp,
 			actor: stringProp,
 			source: stringProp,
@@ -100,7 +102,7 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 
 	define(
 		"enable",
-		"Enables a Rule so it starts injecting into the agent system prompt.",
+		"Enables a Rule so it starts injecting into the agent system prompt. A template-derived draft is enabled only after every field path in its source template's completionRequired array is present.",
 		"local-write",
 		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
 		[],

package/src/handlers/shared.ts

@@ -18,6 +18,7 @@ import type { Artifact } from "../artifact/artifact.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { PlaybookCompositionError } from "../playbook/playbook-definition.ts";
 import { InvalidSessionSecretError } from "../session-identity/session-identity-service.ts";
+import { TaskCreateIdempotencyConflictError } from "../stores/task-create-request-store.ts";
 import { TaskDependencyCycleError, TaskExecutionBoundExceededError, type TaskExecutionPlan } from "../task/task-execution.ts";
 
 /**
@@ -112,6 +113,17 @@ export function classifyTaskExecutionBounds<T>(run: () => T): T {
 	}
 }
 
+export function classifyTaskCreateIdempotency<T>(run: () => T): T {
+	try {
+		return run();
+	} catch (error) {
+		if (error instanceof TaskCreateIdempotencyConflictError) {
+			throw new VehicleError("idempotency-key-conflict", error.message, { category: "conflict" });
+		}
+		throw error;
+	}
+}
+
 /** A self-dependency or dependency-cycle rejection (tasks.depend/undepend/create) is an ordinary, expected validation failure, not an unexpected crash. */
 export function classifyTaskDependencyCycles<T>(run: () => T): T {
 	try {
@@ -235,7 +247,10 @@ export function buildWorkflowRunContent(
 	return { type: "text", text };
 }
 
-export type OperationSchemaProperties = Record<string, { type: string; enum?: readonly string[] }>;
+export type OperationSchemaProperties = Record<
+	string,
+	{ type: string; enum?: readonly string[]; description?: string; [key: string]: unknown }
+>;
 
 export type DefineOperation = (
 	action: string,

package/src/handlers/tasks.ts

@@ -19,17 +19,21 @@
  *
  * remove/remove_subtree/restore are not duplicated here -- see ./artifact-trash-vehicle.ts.
  */
-import type { VehicleLimits } from "@danypops/vehicle-core";
+import { VehicleError, type VehicleLimits } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
-import { GATE_TIMEOUT_MAX_MS } from "../constants.ts";
+import { GATE_TIMEOUT_MAX_MS, TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH } from "../constants.ts";
+import { PROOF_TYPES } from "../domain/checklist.ts";
+import { GATE_TYPES } from "../domain/gate.ts";
 import type { TaskViewMode } from "../domain/task-scope.ts";
 import { tasksOperations } from "../modules/tasks.ts";
 import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
 import type { TaskExecutionPlan } from "../task/task-execution.ts";
-import type { TaskCompletion, Tasks } from "../task/task-service.ts";
+import { type TaskCompletion, TaskProjectAmbiguousError, TaskProjectNotFoundError, type Tasks } from "../task/task-service.ts";
 import {
+	booleanProp,
 	classifySessionAuthorization,
+	classifyTaskCreateIdempotency,
 	classifyTaskDependencyCycles,
 	classifyTaskExecutionBounds,
 	createOperationDefiner,
@@ -68,9 +72,63 @@ const GATE_OPERATION_LIMITS: VehicleLimits = {
 	maxResponseBytes: 262_144,
 };
 
-const objectProp = { type: "object" } as unknown as { type: string };
-const arrayProp = { type: "array" } as unknown as { type: string };
-const _boolProp = { type: "boolean" } as unknown as { type: string };
+const objectProp = { type: "object" } as const;
+const arrayProp = { type: "array" } as const;
+const _boolProp = { type: "boolean" } as const;
+
+const gateProp = {
+	type: "array",
+	description: "Validation gates run by tasks.run_gates and tasks.complete.",
+	items: {
+		type: "object",
+		properties: {
+			type: { type: "string", enum: GATE_TYPES, description: "Gate evaluator." },
+			target: { type: "string", minLength: 1, description: "Path, command, text target, or test command." },
+			expect: { type: "string", description: "Optional expected text/result." },
+			timeoutMs: { type: "integer", minimum: 1_000, maximum: GATE_TIMEOUT_MAX_MS, description: "Command/test timeout override." },
+		},
+		required: ["type", "target"],
+		additionalProperties: false,
+	},
+	examples: [
+		[{ type: "file-exists", target: "dist/index.js" }],
+		[{ type: "command", target: "bun run typecheck", timeoutMs: 60_000 }],
+		[{ type: "contains", target: "README.md", expect: "Retry semantics" }],
+		[{ type: "test", target: "bun test" }],
+	],
+} as const;
+
+const checklistProp = {
+	type: "object",
+	description: "Map from completion criterion text to one or more typed proof references. An empty map clears the checklist.",
+	additionalProperties: {
+		type: "object",
+		properties: {
+			proof: {
+				type: "array",
+				minItems: 1,
+				items: {
+					type: "object",
+					properties: {
+						type: { type: "string", enum: PROOF_TYPES },
+						target: { type: "string", minLength: 1 },
+						expect: { type: "string" },
+					},
+					required: ["type", "target"],
+					additionalProperties: false,
+				},
+			},
+		},
+		required: ["proof"],
+		additionalProperties: false,
+	},
+	examples: [
+		{
+			"tests pass": { proof: [{ type: "test", target: "bun test", expect: "0 failures" }] },
+			"documentation updated": { proof: [{ type: "file", target: "README.md" }] },
+		},
+	],
+} as const;
 
 export interface TasksVehicleDeps {
 	tasks: Tasks;
@@ -147,6 +205,9 @@ const readSchemaProps = {
 	labels: arrayProp,
 };
 
+/** list-only: opts into full Artifact bodies instead of the lean summarizeArtifact() default (modules/tasks.ts). */
+const listSchemaProps = { ...readSchemaProps, full: booleanProp };
+
 /** Same gate/checklist narrative lines the removed tool built client-side. */
 function completionContentText(labels: Map<string, string>, result: TaskCompletion): string {
 	const gates = result.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n");
@@ -190,10 +251,26 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	 */
 	const call = (name: string, input: Record<string, unknown>): unknown =>
 		classifySessionAuthorization(() =>
-			classifyTaskExecutionBounds(() => classifyTaskDependencyCycles(() => moduleOperations.get(name)!.execute(input))),
+			classifyTaskCreateIdempotency(() =>
+				classifyTaskExecutionBounds(() => classifyTaskDependencyCycles(() => moduleOperations.get(name)!.execute(input))),
+			),
 		);
 	const define = createOperationDefiner(registry, OWNER, "tasks", ["tasks:read", "tasks:write"], call);
 
+	const resolveProject = (reference: string) => {
+		try {
+			return tasks.resolveProject(reference);
+		} catch (error) {
+			if (error instanceof TaskProjectNotFoundError) {
+				throw new VehicleError("task-project-not-found", error.message, { category: "not_found" });
+			}
+			if (error instanceof TaskProjectAmbiguousError) {
+				throw new VehicleError("task-project-ambiguous", error.message, { category: "conflict" });
+			}
+			throw error;
+		}
+	};
+
 	/** Shared by every action taking a single id/name: resolves root_task_name first, then name -> id against the final scope. */
 	const resolveIdAndScope = (input: Record<string, unknown>): Record<string, unknown> => {
 		const projectRoot = input.project_root as string | undefined;
@@ -217,14 +294,21 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			status: stringProp,
 			labels: arrayProp,
 			extra: objectProp,
-			gates: arrayProp,
-			checklist: objectProp,
+			gates: gateProp,
+			checklist: checklistProp,
 			template_id: stringProp,
 			parent_id: stringProp,
 			parent_name: stringProp,
 			depends_on: arrayProp,
 			depends_on_names: arrayProp,
 			project_root: stringProp,
+			idempotency_key: {
+				type: "string",
+				minLength: 1,
+				maxLength: TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH,
+				description:
+					"Optional retry key, scoped by caller and canonical project root. Reusing it with the same payload returns the original response; a different payload is rejected.",
+			},
 			session_id: stringProp,
 		},
 		["title", "project_root"],
@@ -240,6 +324,12 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			const dependsOn = resolveArrayField(artifacts, tasks, filter, input.depends_on, input.depends_on_names);
 			return { ...input, ...(parentId ? { parent_id: parentId } : {}), ...(dependsOn ? { depends_on: dependsOn } : {}) };
 		},
+		(input, context) =>
+			call("tasks.create", {
+				...input,
+				idempotency_key: input.idempotency_key ?? context.idempotencyKey,
+				idempotency_caller: context.principal?.id ?? "anonymous",
+			}),
 	);
 
 	define(
@@ -263,9 +353,9 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 
 	define(
 		"list",
-		"Lists Tasks matching an optional status/text/labels filter, scoped to project_root. project_root is required (no ambient cwd server-side).",
+		"Lists Tasks matching an optional status/text/labels filter, scoped to project_root. project_root is required (no ambient cwd server-side). Returns a lean summary (no body/extra) unless full: true is passed.",
 		"read",
-		readSchemaProps,
+		listSchemaProps,
 		["project_root"],
 		(input) => {
 			const rootTaskId = resolveRootTaskId(artifacts, tasks, input.project_root as string, input.root_task_id, input.root_task_name);
@@ -336,6 +426,35 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		resolveIdAndScope,
 	);
 
+	define(
+		"projects",
+		"Lists registered Task project scopes with stable ids, names, aliases, and canonical roots. Use resolve_project before a task operation when the user supplied a human project name.",
+		"read",
+		{ query: stringProp, limit: numberProp },
+		[],
+		(input) => input,
+	);
+
+	define(
+		"resolve_project",
+		"Resolves one case-insensitive exact Task project id, name, alias, or canonical root. Fails closed on unknown or ambiguous references and returns the canonical project_root for subsequent task operations.",
+		"read",
+		{ name: stringProp },
+		["name"],
+		(input) => input,
+		(input) => resolveProject(input.name as string),
+	);
+
+	define(
+		"register_project",
+		"Registers a Task project name and aliases. Pass project to update/rename/move an existing registration while preserving its stable id and old name as an alias.",
+		"local-write",
+		{ project_root: stringProp, name: stringProp, aliases: arrayProp, project: stringProp },
+		["project_root"],
+		(input) => input,
+		(input) => call("tasks.register_project", input),
+	);
+
 	define(
 		"scope",
 		"Describes the current task-view scope selection for project_root.",
@@ -527,7 +646,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		"set_checklist",
 		"Replaces a Task's evidence-bearing checklist (proof requirements) in full.",
 		"local-write",
-		{ id: stringProp, name: stringProp, checklist: objectProp, project_root: stringProp },
+		{ id: stringProp, name: stringProp, checklist: checklistProp, project_root: stringProp },
 		["checklist"],
 		resolveIdAndScope,
 	);
@@ -535,7 +654,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		"set_gates",
 		"Replaces a Task's gate commands in full. Each gate is {type, target, expect?, timeoutMs?} -- timeoutMs overrides the default per-type command timeout (30s)/test timeout (60s) for a legitimately slower gate, up to a bounded ceiling.",
 		"local-write",
-		{ id: stringProp, name: stringProp, gates: arrayProp, project_root: stringProp },
+		{ id: stringProp, name: stringProp, gates: gateProp, project_root: stringProp },
 		["gates"],
 		resolveIdAndScope,
 	);
@@ -633,7 +752,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 
 	define(
 		"claim",
-		"Claims this Task's lease under owner (defaults to session_id). Throws if a different owner already holds one.",
+		"Claims this Task's lease under owner (defaults to session_id). Returns taskName (the reusable artifact alias) and taskTitle instead of exposing its backend UUID. Throws if a different owner already holds one.",
 		"local-write",
 		{
 			id: stringProp,
@@ -653,7 +772,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	);
 	define(
 		"heartbeat_lease",
-		"Extends this Task's lease -- needs the exact owner/token claim() returned.",
+		"Extends this Task's lease -- needs the exact owner/token claim() returned and returns the reusable taskName plus taskTitle.",
 		"local-write",
 		{
 			id: stringProp,
@@ -683,7 +802,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	);
 	define(
 		"lease",
-		"Shows this Task's current lease, if any.",
+		"Shows this Task's current lease, if any, identified by reusable taskName plus taskTitle rather than its backend UUID.",
 		"read",
 		{ id: stringProp, name: stringProp, project_root: stringProp },
 		[],

package/src/index.ts

@@ -24,7 +24,7 @@ export type { DisplayGraph, DisplayGraphEdge, DisplayGraphNode, RenderedGraph }
 export type { GateResult } from "./domain/gate.ts";
 export type { NoteHistoryPage } from "./domain/note-event.ts";
 export type { TaskEvent, TaskHistoryPage } from "./domain/task-event.ts";
-export type { TaskLease } from "./domain/task-lease.ts";
+export type { TaskLease, TaskLeaseView } from "./domain/task-lease.ts";
 export type { TaskViewSelection } from "./domain/task-scope.ts";
 export { NOTE_DISPOSITIONS } from "./note/note-service.ts";
 export type { PlaybookInvocationResult, PlaybookMissingArguments } from "./playbook/playbook-execution.ts";

package/src/modules/docs.ts

@@ -3,7 +3,7 @@
  * (step 5, continued, of the incremental refactor in
  * reducing-papyrus-consumer-change-amplification-with-modules--pvdo).
  *
- * Imports only src/domain-services.ts's Doc functions, which are already generic
+ * Imports only src/docs/docs-service.ts's Doc functions, which are already generic
  * ArtifactStore-based with no other module's concrete class dependency.
  */
 
@@ -20,7 +20,7 @@ import {
 	showDocument,
 	transitionDocument,
 	updateDocument,
-} from "../domain-services.ts";
+} from "../docs/docs-service.ts";
 import type { OperationDefinition } from "../module-registry.ts";
 import { type OperationInput, optionalBoolean, optionalNumber, optionalString, string } from "./operation-input.ts";
 

package/src/modules/notes.ts

@@ -7,8 +7,8 @@
  * table via NOTE_SUBTYPE) and has exactly six operations — the smallest real module to
  * prove the OperationRegistry shape against before extracting Tasks or Docs.
  *
- * This module does not import another module's infrastructure (src/task-service.ts,
- * src/domain-services.ts, etc.) — only its own src/note-service.ts and the shared
+ * This module does not import another module's infrastructure (src/task/task-service.ts,
+ * src/docs/docs-service.ts, etc.) — only its own src/note/note-service.ts and the shared
  * OperationInput parsing helpers, matching the "module code does not import another
  * module's infrastructure" constraint.
  */

package/src/modules/playbooks.ts

@@ -6,13 +6,15 @@
  * declare Doc/Rule blueprints and typed arguments and nested pipeline calls. playbooks.invoke
  * recycles the shared blueprint materialization engine (playbook/playbook-execution.ts compiles a
  * Playbook's steps and composition tree into a BlueprintDefinition, then hands off to
- * playbook/workflow-execution.ts's shared core). See domain-services.ts's Playbook section and
+ * playbook/workflow-execution.ts's shared core). See playbook/playbook-service.ts and
  * playbook/playbook-definition.ts for the full rationale.
  */
 
 import { summarizeArtifact } from "../artifact/artifact.ts";
 import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+import { invokePlaybook } from "../playbook/playbook-execution.ts";
 import {
 	assignPlaybookProject,
 	containPlaybook,
@@ -25,9 +27,7 @@ import {
 	uncontainPlaybook,
 	undependPlaybook,
 	updatePlaybook,
-} from "../domain-services.ts";
-import type { OperationDefinition } from "../module-registry.ts";
-import { invokePlaybook } from "../playbook/playbook-execution.ts";
+} from "../playbook/playbook-service.ts";
 import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
 import type { TaskEventStore } from "../stores/task-event-store.ts";
 import type { TaskScopeStore } from "../stores/task-scope-store.ts";
@@ -108,8 +108,10 @@ export function playbooksOperations({
 					steps: input.steps,
 					tools: input.tools as string[] | undefined,
 					arguments: input.arguments,
+					subtype: optionalString(input, "subtype"),
 					labels: input.labels as string[] | undefined,
 					extra: input.extra as Record<string, unknown> | undefined,
+					templateId: optionalString(input, "template_id") ?? optionalString(input, "templateId"),
 					projectRoot: optionalString(input, "project_root"),
 				},
 				eventContext(input),

package/src/modules/rules.ts

@@ -14,6 +14,7 @@
 import { type Artifact, summarizeArtifact } from "../artifact/artifact.ts";
 import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import type { OperationDefinition } from "../module-registry.ts";
 import {
 	assignRuleProject,
 	createRule,
@@ -25,8 +26,7 @@ import {
 	showRule,
 	transitionRule,
 	updateRule,
-} from "../domain-services.ts";
-import type { OperationDefinition } from "../module-registry.ts";
+} from "../rules/rules-service.ts";
 import { type OperationInput, optionalBoolean, optionalNumber, optionalString, string } from "./operation-input.ts";
 
 const MODULE_ID = "rules";
@@ -92,8 +92,10 @@ export function rulesOperations(artifacts: ArtifactStore, scopes: ArtifactScopeS
 						condition: optionalString(input, "condition"),
 						action: optionalString(input, "rule_action") ?? optionalString(input, "governance_action"),
 						severity: optionalString(input, "severity") as "block" | "warn" | "info" | undefined,
+						subtype: optionalString(input, "subtype"),
 						labels: input.labels as string[] | undefined,
 						extra: input.extra as Record<string, unknown> | undefined,
+						templateId: optionalString(input, "template_id") ?? optionalString(input, "templateId"),
 						projectRoot: optionalString(input, "project_root"),
 					},
 					eventContext(input),