@danypops/papyrus 0.47.2 → 0.49.0

package/src/constants.ts

@@ -4,12 +4,13 @@ export const DAEMON_PORT_FILE = "port";
 export const DAEMON_TOKEN_FILE = "token";
 /** vehicle-server's own {host,port,pid} handle format -- read by Armada's readiness probe once Papyrus is service-installed, see cli.ts's papyrusServiceSpec. */
 export const DAEMON_HANDLE_FILE = "vehicle-handle.json";
+export const DAEMON_LIFECYCLE_FILE = "lifecycle.json";
 export const DAEMON_CLIENT_TIMEOUT_MS = 15_000;
 export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 27;
+export const SQLITE_SCHEMA_VERSION = 28;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -261,6 +262,8 @@ export const ARTIFACT_TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 export const TASK_SCOPE_MAX_TASKS = 1_000;
 /** Docs/Rules/Skills project scope listing bound, mirroring TASK_SCOPE_MAX_TASKS. */
 export const ARTIFACT_SCOPE_MAX_ARTIFACTS = 1_000;
+/** How many distinct registered projects a single Doc/Rule/Playbook may belong to at once, in "projects" scope mode. */
+export const ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT = 50;
 export const TASK_PROJECT_ROOT_MAX_LENGTH = 4_096;
 export const TASK_PROJECT_NAME_MAX_LENGTH = 200;
 export const TASK_PROJECT_ALIAS_MAX_COUNT = 20;

package/src/daemon/daemon-state.ts

@@ -3,7 +3,14 @@ import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { LOOPBACK_HOST, removeDaemonHandle, writeDaemonHandle } from "@danypops/vehicle-server/paths";
-import { DAEMON_DIR_ENV, DAEMON_HANDLE_FILE, DAEMON_HOST, DAEMON_PORT_FILE, DAEMON_TOKEN_FILE } from "../constants.ts";
+import {
+	DAEMON_DIR_ENV,
+	DAEMON_HANDLE_FILE,
+	DAEMON_HOST,
+	DAEMON_LIFECYCLE_FILE,
+	DAEMON_PORT_FILE,
+	DAEMON_TOKEN_FILE,
+} from "../constants.ts";
 
 export interface DaemonHandle {
 	baseUrl: string;
@@ -48,6 +55,11 @@ export function vehicleHandlePath(dir: string): string {
 	return join(dir, DAEMON_HANDLE_FILE);
 }
 
+/** Where the structured daemon lifecycle event log (@danypops/vehicle-server's daemon-lifecycle.ts) persists start/stop/already_running history across restarts -- see daemon.ts's diagnose wiring. */
+export function lifecyclePath(dir: string): string {
+	return join(dir, DAEMON_LIFECYCLE_FILE);
+}
+
 /** vehicle-server's own {host,port,pid} handle format, distinct from this file's port/token pair -- Armada's readiness probe (createHandleReadinessProbe) reads exactly this shape. */
 export function writeVehicleHandle(dir: string, port: number, pid: number = process.pid): void {
 	writeDaemonHandle(vehicleHandlePath(dir), { host: LOOPBACK_HOST, port, pid });

package/src/daemon/daemon.ts

@@ -1,4 +1,8 @@
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
+import { createNodeAtomicJsonFsAdapter } from "@danypops/vehicle-server/atomic-json";
+import { readLaunchProvenance } from "@danypops/vehicle-server/daemon";
+import { diagnoseDaemon, openDaemonLifecycleLog } from "@danypops/vehicle-server/daemon-lifecycle";
 import { acquireDaemonLock, releaseDaemonLock } from "@danypops/vehicle-server/paths";
 import { PushChannel } from "@danypops/vehicle-server/push-channel";
 import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, dbPath, WAL_CHECKPOINT_INTERVAL_MS } from "../constants.ts";
@@ -8,6 +12,7 @@ import {
 	clearDaemonPort,
 	clearVehicleHandle,
 	daemonStateDir,
+	lifecyclePath,
 	loadOrCreateToken,
 	writeDaemonPort,
 	writeVehicleHandle,
@@ -35,14 +40,26 @@ const TASK_READ_ONLY_OPERATIONS = new Set([
 ]);
 
 /** Start the supervised, long-running Papyrus service. */
-export function serveMain(): void {
+export async function serveMain(): Promise<void> {
 	const stateDir = daemonStateDir();
 	const lockPath = join(stateDir, "daemon.lock");
+	const instanceId = randomUUID();
+	const provenance = readLaunchProvenance();
+	const lifecycleLog = openDaemonLifecycleLog({ path: lifecyclePath(stateDir), fs: createNodeAtomicJsonFsAdapter() });
+	const recordLifecycle = async (type: "started" | "already_running" | "stopped", reason?: string): Promise<void> => {
+		try {
+			await lifecycleLog.record({ instanceId, pid: process.pid, type, provenance, reason });
+		} catch (error) {
+			logEvent("error", "lifecycle_log_record_failed", { message: error instanceof Error ? error.message : String(error) });
+		}
+	};
 	const lock = acquireDaemonLock(lockPath);
 	if (!lock.acquired) {
 		logEvent("info", "already_running", { holderPid: lock.holderPid });
+		await recordLifecycle("already_running", lock.holderPid === null ? undefined : `holder pid ${lock.holderPid}`);
 		return;
 	}
+	const startedAt = new Date().toISOString();
 	const token = loadOrCreateToken(stateDir);
 	const service = createPapyrusService(dbPath());
 	const pushChannel = new PushChannel({ token });
@@ -55,6 +72,7 @@ export function serveMain(): void {
 			}
 		},
 		logger: vehicleLogger(),
+		diagnose: () => diagnoseDaemon({ lifecycleLog, current: { instanceId, pid: process.pid, startedAt, provenance } }),
 	});
 	const server = Bun.serve({
 		hostname: DAEMON_HOST,
@@ -110,7 +128,7 @@ export function serveMain(): void {
 		}
 	}, DB_OPTIMIZE_INTERVAL_MS);
 	let stopping = false;
-	const shutdown = () => {
+	const shutdown = (signal: string) => {
 		if (stopping) return;
 		stopping = true;
 		clearInterval(checkpointTimer);
@@ -123,12 +141,13 @@ export function serveMain(): void {
 		service.close();
 		// .finally() re-throws rather than handling a rejection -- catching it first turns a bare
 		// unhandled-rejection warning into a real, queryable shutdown-failure log line.
-		void server
-			.stop(true)
+		void recordLifecycle("stopped", signal)
+			.then(() => server.stop(true))
 			.catch((error) => logEvent("error", "server_stop_failed", { message: error instanceof Error ? error.message : String(error) }))
 			.finally(() => process.exit(0));
 	};
-	process.on("SIGINT", shutdown);
-	process.on("SIGTERM", shutdown);
+	process.on("SIGINT", () => shutdown("SIGINT"));
+	process.on("SIGTERM", () => shutdown("SIGTERM"));
 	logEvent("info", "listening", { host: DAEMON_HOST, port: server.port });
+	await recordLifecycle("started");
 }

package/src/db.ts

@@ -233,10 +233,17 @@ CREATE INDEX IF NOT EXISTS graph_projection_identities_artifact_idx ON graph_pro
 CREATE TABLE IF NOT EXISTS artifact_scopes (
 	artifact_id   TEXT PRIMARY KEY REFERENCES artifacts(id),
 	project_root  TEXT,
+	mode          TEXT NOT NULL DEFAULT 'global' CHECK (mode IN ('global', 'projects')),
 	source        TEXT NOT NULL CHECK (source IN ('cwd', 'explicit', 'unscoped')),
 	assigned_at   TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS artifact_scopes_project_idx ON artifact_scopes(project_root, artifact_id);
+CREATE TABLE IF NOT EXISTS artifact_scope_projects (
+	artifact_id  TEXT NOT NULL REFERENCES artifacts(id) ON DELETE CASCADE,
+	project_id   TEXT NOT NULL REFERENCES task_projects(id),
+	PRIMARY KEY (artifact_id, project_id)
+);
+CREATE INDEX IF NOT EXISTS artifact_scope_projects_project_idx ON artifact_scope_projects(project_id, artifact_id);
 CREATE TABLE IF NOT EXISTS log_sources (
 	id            TEXT PRIMARY KEY,
 	label         TEXT NOT NULL,
@@ -843,6 +850,54 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			`);
 		},
 	},
+	{
+		version: 28,
+		name: "artifact-multi-project-scope",
+		// See artifact/artifact-scope-store.ts. Replaces the single-project_root shape with an
+		// explicit global/projects mode plus a bounded, non-empty many-to-many membership table,
+		// keyed by the same registered project ids Tasks already use (task_projects, see version 26)
+		// rather than a raw root string -- so a project rename/move never needs a best-effort
+		// string rewrite across every artifact scoped to it. Preserves every row: NULL project_root
+		// becomes explicit global mode (the column's own new DEFAULT already covers a fresh
+		// bootstrap; this branch back-fills it for an upgrading database); a non-NULL project_root
+		// becomes projects mode with exactly one membership, registering that root in task_projects
+		// first if no Task ever used it either.
+		up: (db) => {
+			const existing = new Set((db.prepare("PRAGMA table_info(artifact_scopes)").all() as Array<{ name: string }>).map((row) => row.name));
+			if (!existing.has("mode")) {
+				db.exec("ALTER TABLE artifact_scopes ADD COLUMN mode TEXT NOT NULL DEFAULT 'global' CHECK (mode IN ('global', 'projects'))");
+			}
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS artifact_scope_projects (
+					artifact_id  TEXT NOT NULL REFERENCES artifacts(id) ON DELETE CASCADE,
+					project_id   TEXT NOT NULL REFERENCES task_projects(id),
+					PRIMARY KEY (artifact_id, project_id)
+				);
+				CREATE INDEX IF NOT EXISTS artifact_scope_projects_project_idx ON artifact_scope_projects(project_id, artifact_id);
+			`);
+			const scoped = db.prepare("SELECT artifact_id, project_root FROM artifact_scopes WHERE project_root IS NOT NULL").all() as Array<{
+				artifact_id: string;
+				project_root: string;
+			}>;
+			const findProject = db.prepare("SELECT id FROM task_projects WHERE project_root = ?");
+			const insertProject = db.prepare(
+				"INSERT INTO task_projects (id, name, aliases_json, project_root, created_at, updated_at) VALUES (?, ?, '[]', ?, ?, ?)",
+			);
+			const setProjectsMode = db.prepare("UPDATE artifact_scopes SET mode = 'projects' WHERE artifact_id = ?");
+			const insertMembership = db.prepare("INSERT OR IGNORE INTO artifact_scope_projects (artifact_id, project_id) VALUES (?, ?)");
+			for (const row of scoped) {
+				const found = findProject.get(row.project_root) as { id: string } | null;
+				let projectId = found?.id;
+				if (!projectId) {
+					projectId = randomUUID();
+					const now = new Date().toISOString();
+					insertProject.run(projectId, basename(row.project_root) || row.project_root, row.project_root, now, now);
+				}
+				setProjectsMode.run(row.artifact_id);
+				insertMembership.run(row.artifact_id, projectId);
+			}
+		},
+	},
 ];
 
 /**

package/src/domain/project-registry.ts

@@ -0,0 +1,58 @@
+/**
+ * A registered project identity, shared across every artifact kind (Tasks, Docs, Rules,
+ * Playbooks) rather than owned by Tasks alone -- extracted so a Doc/Rule/Playbook can resolve
+ * and register against the exact same id/name/alias/root space a Task already does, instead of
+ * each domain inventing its own project catalog.
+ */
+export interface Project {
+	id: string;
+	name: string;
+	aliases: string[];
+	projectRoot: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface RegisterProjectInput {
+	projectRoot: string;
+	name?: string;
+	aliases?: string[];
+	existingId?: string;
+}
+
+export class ProjectNotFoundError extends Error {}
+export class ProjectAmbiguousError extends Error {}
+
+export interface ProjectReferenceLookup {
+	matchingProjects(reference: string): Project[];
+	projects(query: string | undefined, limit: number): Project[];
+}
+
+/**
+ * Same bounded, fail-closed exact-reference resolution Tasks' own resolveProject already uses
+ * (case-insensitive exact id/name/alias/root, zero matches is an error with up to 10 bounded
+ * candidates, more than one match is an error listing every match up to 10) -- extracted here so
+ * a non-Task domain (Rules, and later Docs/Playbooks) gets the identical contract instead of a
+ * hand-rolled approximation. Tasks' own TaskProjectNotFoundError/TaskProjectAmbiguousError are
+ * deliberately left as they are (a working, tested path with its own established call sites);
+ * this is for every domain that never had project-reference resolution before.
+ */
+export function resolveProjectReference(registry: ProjectReferenceLookup, reference: string): Project {
+	const matches = registry.matchingProjects(reference);
+	if (matches.length === 0) {
+		const candidates = registry.projects(reference, 10);
+		const fallback = candidates.length === 0 ? registry.projects(undefined, 10) : candidates;
+		const suffix =
+			fallback.length === 0 ? "" : ` Candidates: ${fallback.map((project) => `${project.name} (${project.projectRoot})`).join(", ")}`;
+		throw new ProjectNotFoundError(`no project named or aliased "${reference}" is registered.${suffix}`);
+	}
+	if (matches.length > 1) {
+		throw new ProjectAmbiguousError(
+			`project reference "${reference}" is ambiguous: ${matches
+				.slice(0, 10)
+				.map((project) => `${project.name} (${project.projectRoot})`)
+				.join(", ")}`,
+		);
+	}
+	return matches[0]!;
+}

package/src/domain/task-scope.ts

@@ -1,5 +1,6 @@
 import { basename, isAbsolute, normalize } from "node:path";
 import { TASK_PROJECT_ROOT_MAX_LENGTH } from "../constants.ts";
+import type { Project, RegisterProjectInput } from "./project-registry.ts";
 
 export type TaskViewMode = "project" | "graph" | "all";
 export type TaskScopeSource = "cwd" | "explicit" | "unscoped";
@@ -10,21 +11,10 @@ export interface TaskProjectScope {
 	source: TaskScopeSource;
 }
 
-export interface TaskProject {
-	id: string;
-	name: string;
-	aliases: string[];
-	projectRoot: string;
-	createdAt: string;
-	updatedAt: string;
-}
+/** Task's own name for the shared, kind-neutral Project identity -- see project-registry.ts. Kept as a type alias so every existing Task-scope call site keeps working unchanged. */
+export type TaskProject = Project;
 
-export interface RegisterTaskProjectInput {
-	projectRoot: string;
-	name?: string;
-	aliases?: string[];
-	existingId?: string;
-}
+export type RegisterTaskProjectInput = RegisterProjectInput;
 
 export interface TaskViewPreference {
 	projectRoot: string;

package/src/handlers/registry.ts

@@ -12,6 +12,7 @@ import type { ArtifactTrashStore } from "../artifact/artifact-trash-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
 import type { Discussions } from "../discussion/discussion-service.ts";
 import type { Notes } from "../note/note-service.ts";
+import type { ProjectRegistryStore } from "../ports/project-registry-store.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";
@@ -34,6 +35,7 @@ export interface PapyrusVehicleDeps {
 	tasks: Tasks;
 	discussions: Discussions;
 	sessionIdentity: SessionIdentity;
+	projectRegistry: ProjectRegistryStore;
 }
 
 export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleRegistry {
@@ -48,7 +50,7 @@ export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleR
 	// session_id, a correlation id, not a secret -- see session-identity-service.ts).
 	registry.setExposeHandlerFailureDetails(true);
 	registerNotesVehicleOperations(registry, deps.notes, deps.artifacts);
-	registerRulesVehicleOperations(registry, deps.artifacts, deps.scopes);
+	registerRulesVehicleOperations(registry, deps.artifacts, deps.scopes, deps.projectRegistry);
 	registerDocsVehicleOperations(registry, deps.artifacts, deps.scopes, deps.authority);
 	registerPlaybooksVehicleOperations(registry, {
 		artifacts: deps.artifacts,

package/src/handlers/rules.ts

@@ -8,12 +8,20 @@ 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 { rulesOperations } from "../modules/rules.ts";
+import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
 import { listRules } from "../rules/rules-service.ts";
 import { booleanProp, createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "rules";
 
-/** Resolves a rule's id from either an explicit id or its title, widened past project_root when unscoped-vs-scoped search finds nothing. */
+/**
+ * Resolves a rule's id from either an explicit id or its title. When project_root is given and
+ * the project-scoped search finds nothing, widens only to a rule that actually APPLIES to this
+ * project (global, or explicitly scoped to it via appliesToProjectRoot) -- never to a same-named
+ * rule that belongs to a different project. A prior version widened to every rule of that name
+ * across every project unconditionally once the scoped search came up empty, silently leaking a
+ * name-based mutation across project boundaries.
+ */
 function resolveRuleId(
 	artifacts: ArtifactStore,
 	scopes: ArtifactScopeStore,
@@ -27,7 +35,9 @@ function resolveRuleId(
 		artifacts,
 		name,
 		() => listRules(artifacts, scopes, { text: name, projectRoot }),
-		projectRoot === undefined ? undefined : () => listRules(artifacts, scopes, { text: name }),
+		projectRoot === undefined
+			? undefined
+			: () => artifacts.query({ kind: "rule", text: name }).filter((rule) => scopes.appliesToProjectRoot(rule.id, projectRoot)),
 	);
 }
 
@@ -42,8 +52,13 @@ function resolveTaskId(artifacts: ArtifactStore, _projectRoot: string | undefine
 	return resolveArtifactIdWidened(artifacts, name, () => artifacts.query({ kind: "task", text: name }));
 }
 
-export function registerRulesVehicleOperations(registry: VehicleRegistry, artifacts: ArtifactStore, scopes: ArtifactScopeStore): void {
-	const moduleOperations = new Map(rulesOperations(artifacts, scopes).map((op) => [op.name, op]));
+export function registerRulesVehicleOperations(
+	registry: VehicleRegistry,
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	projectRegistry: ProjectRegistryStore,
+): void {
+	const moduleOperations = new Map(rulesOperations(artifacts, scopes, projectRegistry).map((op) => [op.name, op]));
 	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
 	const define = createOperationDefiner(registry, OWNER, "rules", ["rules:read", "rules:write"], call);
 
@@ -62,6 +77,7 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 			extra: { type: "object" } as unknown as { type: string },
 			template_id: stringProp,
 			project_root: stringProp,
+			projects: { type: "array" } as unknown as { type: string },
 			actor: stringProp,
 			source: stringProp,
 			session_id: stringProp,
@@ -153,6 +169,77 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, undefined, input.id, input.name) }),
 	);
 
+	define(
+		"scope",
+		"Shows a Rule's real project scope: global (applies everywhere) or the bounded set of registered projects it applies to.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"set_global",
+		"Makes a Rule apply in every project, clearing any project membership. The only way to widen an active project-bound Rule back to global -- removing its last membership through remove_project is rejected instead.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"add_project",
+		"Adds one registered project (exact id, name, alias, or root) to a Rule's membership, switching it from global to project-bound if it was global. Idempotent if the project is already a member.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			project: { ...stringProp, description: "Exact project id, name, alias, or registered root to add." },
+			project_root: stringProp,
+			actor: stringProp,
+			source: stringProp,
+			session_id: stringProp,
+		},
+		["project"],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"remove_project",
+		"Removes one registered project from a Rule's membership. Rejected while it is the Rule's only remaining membership -- call set_global first if the Rule should stop being project-bound entirely.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			project: { ...stringProp, description: "Exact project id, name, alias, or registered root to remove." },
+			project_root: stringProp,
+			actor: stringProp,
+			source: stringProp,
+			session_id: stringProp,
+		},
+		["project"],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"replace_projects",
+		"Replaces a Rule's entire project membership with exactly this bounded, non-empty list of registered project references (id/name/alias/root). Use set_global instead to clear scoping entirely.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			projects: { type: "array", description: "Non-empty list of exact project id/name/alias/root references." } as unknown as {
+				type: string;
+			},
+			project_root: stringProp,
+			actor: stringProp,
+			source: stringProp,
+			session_id: stringProp,
+		},
+		["projects"],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
 	define(
 		"update",
 		"Changes a Rule's title/body/labels (at least one required). Body updates still enforce the same combined condition+action+body context-tax bound as creation. The response includes combinedLength and a non-blocking warning once it exceeds the ~600-character soft target.",

package/src/modules/rules.ts

@@ -15,14 +15,20 @@ 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 type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
 import {
+	addRuleProject,
 	assignRuleProject,
 	createRule,
 	gateTaskWithRule,
 	listRules,
 	previewRule,
+	removeRuleProject,
+	replaceRuleProjects,
 	ruleCombinedLength,
 	ruleCombinedLengthWarning,
+	ruleScope,
+	setRuleGlobal,
 	showRule,
 	transitionRule,
 	updateRule,
@@ -71,10 +77,19 @@ export const RULES_OPERATION_NAMES = [
 	"rules.disable",
 	"rules.gate",
 	"rules.assign_project",
+	"rules.scope",
+	"rules.set_global",
+	"rules.add_project",
+	"rules.remove_project",
+	"rules.replace_projects",
 	"rules.update",
 ] as const;
 
-export function rulesOperations(artifacts: ArtifactStore, scopes: ArtifactScopeStore): OperationDefinition[] {
+export function rulesOperations(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+): OperationDefinition[] {
 	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
 		name,
 		moduleId: MODULE_ID,
@@ -97,8 +112,10 @@ export function rulesOperations(artifacts: ArtifactStore, scopes: ArtifactScopeS
 						extra: input.extra as Record<string, unknown> | undefined,
 						templateId: optionalString(input, "template_id") ?? optionalString(input, "templateId"),
 						projectRoot: optionalString(input, "project_root"),
+						projectReferences: input.projects as string[] | undefined,
 					},
 					eventContext(input),
+					registry,
 				),
 			),
 		),
@@ -125,6 +142,17 @@ export function rulesOperations(artifacts: ArtifactStore, scopes: ArtifactScopeS
 		define("rules.assign_project", (input: OperationInput) =>
 			assignRuleProject(artifacts, scopes, string(input, "id"), optionalString(input, "project_root")),
 		),
+		define("rules.scope", (input: OperationInput) => ruleScope(artifacts, scopes, string(input, "id"))),
+		define("rules.set_global", (input: OperationInput) => setRuleGlobal(artifacts, scopes, string(input, "id"))),
+		define("rules.add_project", (input: OperationInput) =>
+			addRuleProject(artifacts, scopes, registry, string(input, "id"), string(input, "project")),
+		),
+		define("rules.remove_project", (input: OperationInput) =>
+			removeRuleProject(artifacts, scopes, registry, string(input, "id"), string(input, "project")),
+		),
+		define("rules.replace_projects", (input: OperationInput) =>
+			replaceRuleProjects(artifacts, scopes, registry, string(input, "id"), (input.projects as string[] | undefined) ?? []),
+		),
 		define("rules.update", (input: OperationInput) =>
 			withRuleLengthInfo(
 				updateRule(

package/src/ops.ts

@@ -496,6 +496,7 @@ export function purgeDueArtifacts(db: Db, now: () => string = () => new Date().t
 			db.prepare("DELETE FROM task_scopes WHERE task_id = ?").run(id);
 			db.prepare("DELETE FROM task_views WHERE root_task_id = ?").run(id);
 			db.prepare("DELETE FROM graph_projection_identities WHERE artifact_id = ?").run(id);
+			db.prepare("DELETE FROM artifact_scope_projects WHERE artifact_id = ?").run(id);
 			db.prepare("DELETE FROM artifact_scopes WHERE artifact_id = ?").run(id);
 			db.prepare("DELETE FROM task_events WHERE task_id = ?").run(id);
 			db.prepare("DELETE FROM note_events WHERE note_id = ?").run(id);

package/src/ports/project-registry-store.ts

@@ -0,0 +1,13 @@
+import type { Project, RegisterProjectInput } from "../domain/project-registry.ts";
+
+/**
+ * Kind-neutral project identity, shared by Task scope and every non-Task artifact scope
+ * (Docs/Rules/Playbooks) rather than each domain keeping its own catalog. TaskScopeStore
+ * composes one of these for its own `projects`/`matchingProjects`/`registerProject` methods
+ * instead of implementing project bookkeeping itself; ArtifactScopeStore does the same.
+ */
+export interface ProjectRegistryStore {
+	projects(query: string | undefined, limit: number): Project[];
+	matchingProjects(reference: string): Project[];
+	registerProject(input: RegisterProjectInput): Project;
+}