@danypops/papyrus 0.47.2 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.47.2",
+  "version": "0.48.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",

package/src/artifact/artifact-scope-store.ts

@@ -1,20 +1,50 @@
 import type { TaskScopeSource } from "../domain/task-scope.ts";
 
 /**
- * Project scoping for Docs/Rules/Playbooks, mirroring TaskScopeStore's shape (task_scopes) but
- * kept as its own table/port rather than folding non-Task kinds into Task-named
- * infrastructure. TaskScopeSource ("cwd" | "explicit" | "unscoped") is already kind-agnostic
- * and reused as-is -- no reason to redefine the same three values under a new name.
+ * Project scoping for Docs/Rules/Playbooks: an artifact is either explicitly global (applies
+ * everywhere) or bound to a bounded, non-empty set of registered project ids -- never inferred
+ * from an accidentally empty join table, which is why `mode` is its own explicit field rather
+ * than "projectIds.length === 0 means global". Membership is by project id (from the shared
+ * ProjectRegistryStore) internally, so a registered project's root can move without a
+ * best-effort string rewrite across every artifact that references it -- assign/get/ids keep
+ * taking/returning a root for compatibility with every existing caller, resolved to/from a
+ * project id under the hood.
  */
+export type ArtifactScopeMode = "global" | "projects";
+
 export interface ArtifactScope {
+	artifactId: string;
+	mode: ArtifactScopeMode;
+	/** Registered project ids this artifact applies to. Always empty when mode is "global"; always non-empty when mode is "projects". */
+	projectIds: string[];
+	source: TaskScopeSource;
+}
+
+export interface LegacyArtifactScope {
 	artifactId: string;
 	projectRoot?: string;
 	source: TaskScopeSource;
 }
 
 export interface ArtifactScopeStore {
-	assign(artifactId: string, projectRoot: string | undefined, source: TaskScopeSource): ArtifactScope;
-	get(artifactId: string): ArtifactScope | undefined;
-	/** Bounded id listing for one project (or the unscoped bucket when projectRoot is undefined). */
+	/** The real, non-lossy multi-membership view. Defaults to global/unscoped for an artifact with no scope row yet. */
+	scope(artifactId: string): ArtifactScope;
+	/** Single-root compatibility view over scope(): a global or unscoped artifact omits projectRoot; a "projects" mode artifact with exactly one membership resolves it back to that project's current root; more than one membership (only reachable through the new multi-project primitives below) omits projectRoot, since this shape cannot represent more than one. */
+	get(artifactId: string): LegacyArtifactScope | undefined;
+	/** Single-root compatibility shim: registers/resolves projectRoot and replaces the artifact's scope with exactly that one membership, or setGlobal() when projectRoot is undefined. Every existing caller (rules/docs/playbooks assign_project) keeps working unchanged. */
+	assign(artifactId: string, projectRoot: string | undefined, source: TaskScopeSource): LegacyArtifactScope;
+	/** Sets an artifact to explicitly global, clearing any project membership. */
+	setGlobal(artifactId: string, source: TaskScopeSource): ArtifactScope;
+	/** Replaces an artifact's entire project membership set with exactly these (registered) project ids -- must be non-empty; use setGlobal to clear scoping entirely. */
+	replaceProjects(artifactId: string, projectIds: readonly string[], source: TaskScopeSource): ArtifactScope;
+	/** Adds one project to an artifact's membership (idempotent -- adding an already-present id is a no-op), switching mode to "projects" if it was global. Enforces the bounded maximum membership count. */
+	addProject(artifactId: string, projectId: string, source: TaskScopeSource): ArtifactScope;
+	/** Removes one project from an artifact's membership (idempotent -- removing an absent id is a no-op). Rejects removing the last membership while mode is "projects": a caller must explicitly call setGlobal instead of accidentally broadening scope by emptying the set. */
+	removeProject(artifactId: string, projectId: string): ArtifactScope;
+	/** Bounded id listing for one project root (or the global/unscoped bucket when projectRoot is undefined) -- an unregistered root always yields an empty list, since nothing can be scoped to a project that was never registered. */
 	ids(projectRoot: string | undefined, limit: number): string[];
+	/** True when artifactId's scope includes projectId (mode "projects" and a member), or is "global" (applies everywhere). False for an unscoped artifact with no row -- matching a Rule/Doc/Playbook's default of "applies everywhere" being represented by the same "global" default scope() already returns, but injection call sites decide their own applicability policy; this is the raw membership fact only. */
+	appliesToProject(artifactId: string, projectId: string): boolean;
+	/** Root-based convenience over appliesToProject, for a caller (e.g. rules.injectable) that only has a project root, not a resolved id -- resolves the same way ids() does. An unregistered root (no project was ever registered for it) means only a global-mode artifact applies; projectRoot === undefined means "no project context at all", so only global-mode artifacts apply either way. */
+	appliesToProjectRoot(artifactId: string, projectRoot: string | undefined): boolean;
 }

package/src/artifact/in-memory-artifact-scope-store.ts

@@ -0,0 +1,123 @@
+import { ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT } from "../constants.ts";
+import type { TaskScopeSource } from "../domain/task-scope.ts";
+import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
+import { InMemoryProjectRegistryStore } from "../stores/in-memory-project-registry-store.ts";
+import type { ArtifactScope, ArtifactScopeStore, LegacyArtifactScope } from "./artifact-scope-store.ts";
+
+interface Row {
+	mode: "global" | "projects";
+	projectIds: Set<string>;
+	source: TaskScopeSource;
+}
+
+export class InMemoryArtifactScopeStore implements ArtifactScopeStore {
+	private readonly rows = new Map<string, Row>();
+	private readonly registry: InMemoryProjectRegistryStore;
+
+	// Membership is stored by project id, never by root, so a registry root move (see
+	// ProjectRegistryStore.registerProject) needs no rewrite here at all -- unlike
+	// InMemoryTaskScopeStore, this store never subscribes to root-move notifications.
+	constructor(registry?: ProjectRegistryStore) {
+		this.registry = registry instanceof InMemoryProjectRegistryStore ? registry : new InMemoryProjectRegistryStore();
+	}
+
+	private toScope(artifactId: string, row: Row | undefined): ArtifactScope {
+		return row
+			? { artifactId, mode: row.mode, projectIds: [...row.projectIds], source: row.source }
+			: { artifactId, mode: "global", projectIds: [], source: "unscoped" };
+	}
+
+	scope(artifactId: string): ArtifactScope {
+		return this.toScope(artifactId, this.rows.get(artifactId));
+	}
+
+	get(artifactId: string): LegacyArtifactScope | undefined {
+		const row = this.rows.get(artifactId);
+		if (!row) return undefined;
+		const onlyProjectId = row.mode === "projects" && row.projectIds.size === 1 ? [...row.projectIds][0] : undefined;
+		const projectRoot = onlyProjectId === undefined ? undefined : this.registry.byId(onlyProjectId)?.projectRoot;
+		return { artifactId, ...(projectRoot === undefined ? {} : { projectRoot }), source: row.source };
+	}
+
+	assign(artifactId: string, projectRoot: string | undefined, source: TaskScopeSource): LegacyArtifactScope {
+		if (projectRoot === undefined) {
+			this.setGlobal(artifactId, source);
+			return { artifactId, source };
+		}
+		const project = this.registry.registerProject({ projectRoot });
+		this.replaceProjects(artifactId, [project.id], source);
+		return { artifactId, projectRoot: project.projectRoot, source };
+	}
+
+	setGlobal(artifactId: string, source: TaskScopeSource): ArtifactScope {
+		const row: Row = { mode: "global", projectIds: new Set(), source };
+		this.rows.set(artifactId, row);
+		return this.toScope(artifactId, row);
+	}
+
+	replaceProjects(artifactId: string, projectIds: readonly string[], source: TaskScopeSource): ArtifactScope {
+		if (projectIds.length === 0) throw new Error("replaceProjects requires at least one project id; use setGlobal to clear scoping");
+		if (projectIds.length > ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
+			throw new Error(`an artifact cannot belong to more than ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} projects`);
+		}
+		const row: Row = { mode: "projects", projectIds: new Set(projectIds), source };
+		this.rows.set(artifactId, row);
+		return this.toScope(artifactId, row);
+	}
+
+	addProject(artifactId: string, projectId: string, source: TaskScopeSource): ArtifactScope {
+		const existing = this.rows.get(artifactId);
+		const projectIds = new Set(existing?.mode === "projects" ? existing.projectIds : []);
+		if (!projectIds.has(projectId) && projectIds.size >= ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
+			throw new Error(`an artifact cannot belong to more than ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} projects`);
+		}
+		projectIds.add(projectId);
+		const row: Row = { mode: "projects", projectIds, source };
+		this.rows.set(artifactId, row);
+		return this.toScope(artifactId, row);
+	}
+
+	removeProject(artifactId: string, projectId: string): ArtifactScope {
+		const existing = this.rows.get(artifactId);
+		if (existing?.mode !== "projects" || !existing.projectIds.has(projectId)) return this.toScope(artifactId, existing);
+		if (existing.projectIds.size === 1) {
+			throw new Error("cannot remove the last project membership; call setGlobal to make this artifact apply everywhere instead");
+		}
+		const projectIds = new Set(existing.projectIds);
+		projectIds.delete(projectId);
+		const row: Row = { mode: "projects", projectIds, source: existing.source };
+		this.rows.set(artifactId, row);
+		return this.toScope(artifactId, row);
+	}
+
+	ids(projectRoot: string | undefined, limit: number): string[] {
+		if (projectRoot === undefined) {
+			return [...this.rows.entries()]
+				.filter(([, row]) => row.mode === "global")
+				.map(([artifactId]) => artifactId)
+				.sort()
+				.slice(0, limit);
+		}
+		const project = this.registry.byRoot(projectRoot);
+		if (!project) return [];
+		return [...this.rows.entries()]
+			.filter(([, row]) => row.mode === "projects" && row.projectIds.has(project.id))
+			.map(([artifactId]) => artifactId)
+			.sort()
+			.slice(0, limit);
+	}
+
+	appliesToProject(artifactId: string, projectId: string): boolean {
+		const row = this.rows.get(artifactId);
+		if (!row || row.mode === "global") return true;
+		return row.projectIds.has(projectId);
+	}
+
+	appliesToProjectRoot(artifactId: string, projectRoot: string | undefined): boolean {
+		const row = this.rows.get(artifactId);
+		if (!row || row.mode === "global") return true;
+		if (projectRoot === undefined) return false;
+		const project = this.registry.byRoot(projectRoot);
+		return project !== undefined && row.projectIds.has(project.id);
+	}
+}

package/src/artifact/sqlite-artifact-scope-store.ts

@@ -1,45 +1,166 @@
+import { ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT } from "../constants.ts";
 import type { Db } from "../db.ts";
 import { inTransaction } from "../db.ts";
 import type { TaskScopeSource } from "../domain/task-scope.ts";
-import type { ArtifactScope, ArtifactScopeStore } from "./artifact-scope-store.ts";
+import { SQLiteProjectRegistryStore } from "../stores/sqlite-project-registry-store.ts";
+import type { ArtifactScope, ArtifactScopeMode, ArtifactScopeStore, LegacyArtifactScope } from "./artifact-scope-store.ts";
+
+interface ScopeRow {
+	artifact_id: string;
+	mode: ArtifactScopeMode;
+	source: TaskScopeSource;
+}
 
 export class SQLiteArtifactScopeStore implements ArtifactScopeStore {
-	constructor(private readonly db: Db) {}
+	private readonly registry: SQLiteProjectRegistryStore;
 
-	assign(artifactId: string, projectRoot: string | undefined, source: TaskScopeSource): ArtifactScope {
-		inTransaction(this.db, () => {
-			this.db
-				.prepare(`
-				INSERT INTO artifact_scopes (artifact_id, project_root, source, assigned_at)
-				VALUES (?, ?, ?, ?)
+	// Membership is by project id, not root -- a registry root move (see
+	// SQLiteProjectRegistryStore.registerProject) needs no rewrite of artifact_scope_projects at
+	// all, unlike SQLiteTaskScopeStore's own task_scopes/task_views rewrite.
+	constructor(private readonly db: Db) {
+		this.registry = new SQLiteProjectRegistryStore(db);
+	}
+
+	private membershipIds(artifactId: string): string[] {
+		return (
+			this.db.prepare("SELECT project_id FROM artifact_scope_projects WHERE artifact_id = ? ORDER BY project_id").all(artifactId) as Array<{
+				project_id: string;
+			}>
+		).map((row) => row.project_id);
+	}
+
+	private readRow(artifactId: string): ScopeRow | undefined {
+		const row = this.db
+			.prepare("SELECT artifact_id, mode, source FROM artifact_scopes WHERE artifact_id = ?")
+			.get(artifactId) as ScopeRow | null;
+		return row ?? undefined;
+	}
+
+	scope(artifactId: string): ArtifactScope {
+		const row = this.readRow(artifactId);
+		if (!row) return { artifactId, mode: "global", projectIds: [], source: "unscoped" };
+		return { artifactId, mode: row.mode, projectIds: row.mode === "projects" ? this.membershipIds(artifactId) : [], source: row.source };
+	}
+
+	get(artifactId: string): LegacyArtifactScope | undefined {
+		const row = this.readRow(artifactId);
+		if (!row) return undefined;
+		if (row.mode !== "projects") return { artifactId, source: row.source };
+		const ids = this.membershipIds(artifactId);
+		if (ids.length !== 1) return { artifactId, source: row.source };
+		const project = this.registry.matchingProjects(ids[0]!).find((candidate) => candidate.id === ids[0]);
+		return { artifactId, ...(project ? { projectRoot: project.projectRoot } : {}), source: row.source };
+	}
+
+	assign(artifactId: string, projectRoot: string | undefined, source: TaskScopeSource): LegacyArtifactScope {
+		if (projectRoot === undefined) {
+			this.setGlobal(artifactId, source);
+			return { artifactId, source };
+		}
+		return inTransaction(this.db, () => {
+			const project = this.registry.registerProject({ projectRoot });
+			this.replaceProjects(artifactId, [project.id], source);
+			return { artifactId, projectRoot: project.projectRoot, source };
+		});
+	}
+
+	private upsertScopeRow(artifactId: string, mode: ArtifactScopeMode, source: TaskScopeSource): void {
+		this.db
+			.prepare(`
+				INSERT INTO artifact_scopes (artifact_id, project_root, mode, source, assigned_at)
+				VALUES (?, NULL, ?, ?, ?)
 				ON CONFLICT(artifact_id) DO UPDATE SET
-					project_root = excluded.project_root,
+					project_root = NULL,
+					mode = excluded.mode,
 					source = excluded.source,
 					assigned_at = excluded.assigned_at
 			`)
-				.run(artifactId, projectRoot ?? null, source, new Date().toISOString());
+			.run(artifactId, mode, source, new Date().toISOString());
+	}
+
+	setGlobal(artifactId: string, source: TaskScopeSource): ArtifactScope {
+		return inTransaction(this.db, () => {
+			this.upsertScopeRow(artifactId, "global", source);
+			this.db.prepare("DELETE FROM artifact_scope_projects WHERE artifact_id = ?").run(artifactId);
+			return { artifactId, mode: "global", projectIds: [], source };
+		});
+	}
+
+	replaceProjects(artifactId: string, projectIds: readonly string[], source: TaskScopeSource): ArtifactScope {
+		if (projectIds.length === 0) throw new Error("replaceProjects requires at least one project id; use setGlobal to clear scoping");
+		if (projectIds.length > ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
+			throw new Error(`an artifact cannot belong to more than ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} projects`);
+		}
+		return inTransaction(this.db, () => {
+			this.upsertScopeRow(artifactId, "projects", source);
+			this.db.prepare("DELETE FROM artifact_scope_projects WHERE artifact_id = ?").run(artifactId);
+			const insert = this.db.prepare("INSERT OR IGNORE INTO artifact_scope_projects (artifact_id, project_id) VALUES (?, ?)");
+			const unique = [...new Set(projectIds)];
+			for (const projectId of unique) insert.run(artifactId, projectId);
+			return { artifactId, mode: "projects", projectIds: unique, source };
+		});
+	}
+
+	addProject(artifactId: string, projectId: string, source: TaskScopeSource): ArtifactScope {
+		return inTransaction(this.db, () => {
+			const current = this.membershipIds(artifactId);
+			if (!current.includes(projectId) && current.length >= ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
+				throw new Error(`an artifact cannot belong to more than ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} projects`);
+			}
+			this.upsertScopeRow(artifactId, "projects", source);
+			this.db.prepare("INSERT OR IGNORE INTO artifact_scope_projects (artifact_id, project_id) VALUES (?, ?)").run(artifactId, projectId);
+			return { artifactId, mode: "projects", projectIds: this.membershipIds(artifactId), source };
 		});
-		return { artifactId, ...(projectRoot === undefined ? {} : { projectRoot }), source };
 	}
 
-	get(artifactId: string): ArtifactScope | undefined {
-		const row = this.db.prepare("SELECT artifact_id, project_root, source FROM artifact_scopes WHERE artifact_id = ?").get(artifactId) as {
-			artifact_id: string;
-			project_root: string | null;
-			source: TaskScopeSource;
-		} | null;
-		return row
-			? { artifactId: row.artifact_id, ...(row.project_root === null ? {} : { projectRoot: row.project_root }), source: row.source }
-			: undefined;
+	removeProject(artifactId: string, projectId: string): ArtifactScope {
+		return inTransaction(this.db, () => {
+			const row = this.readRow(artifactId);
+			const current = row?.mode === "projects" ? this.membershipIds(artifactId) : [];
+			if (row?.mode !== "projects" || !current.includes(projectId)) return this.scope(artifactId);
+			if (current.length === 1) {
+				throw new Error("cannot remove the last project membership; call setGlobal to make this artifact apply everywhere instead");
+			}
+			this.db.prepare("DELETE FROM artifact_scope_projects WHERE artifact_id = ? AND project_id = ?").run(artifactId, projectId);
+			return { artifactId, mode: "projects", projectIds: this.membershipIds(artifactId), source: row.source };
+		});
 	}
 
 	ids(projectRoot: string | undefined, limit: number): string[] {
-		const rows =
-			projectRoot === undefined
-				? this.db.prepare("SELECT artifact_id FROM artifact_scopes WHERE project_root IS NULL ORDER BY artifact_id LIMIT ?").all(limit)
-				: this.db
-						.prepare("SELECT artifact_id FROM artifact_scopes WHERE project_root = ? ORDER BY artifact_id LIMIT ?")
-						.all(projectRoot, limit);
-		return (rows as Array<{ artifact_id: string }>).map((row) => row.artifact_id);
+		if (projectRoot === undefined) {
+			return (
+				this.db.prepare("SELECT artifact_id FROM artifact_scopes WHERE mode = 'global' ORDER BY artifact_id LIMIT ?").all(limit) as Array<{
+					artifact_id: string;
+				}>
+			).map((row) => row.artifact_id);
+		}
+		const project = this.db.prepare("SELECT id FROM task_projects WHERE project_root = ?").get(projectRoot) as { id: string } | null;
+		if (!project) return [];
+		return (
+			this.db
+				.prepare(`
+					SELECT asp.artifact_id AS artifact_id
+					FROM artifact_scope_projects asp
+					JOIN artifact_scopes s ON s.artifact_id = asp.artifact_id AND s.mode = 'projects'
+					WHERE asp.project_id = ?
+					ORDER BY asp.artifact_id
+					LIMIT ?
+				`)
+				.all(project.id, limit) as Array<{ artifact_id: string }>
+		).map((row) => row.artifact_id);
+	}
+
+	appliesToProject(artifactId: string, projectId: string): boolean {
+		const row = this.readRow(artifactId);
+		if (!row || row.mode === "global") return true;
+		return this.membershipIds(artifactId).includes(projectId);
+	}
+
+	appliesToProjectRoot(artifactId: string, projectRoot: string | undefined): boolean {
+		const row = this.readRow(artifactId);
+		if (!row || row.mode === "global") return true;
+		if (projectRoot === undefined) return false;
+		const project = this.db.prepare("SELECT id FROM task_projects WHERE project_root = ?").get(projectRoot) as { id: string } | null;
+		return project !== null && this.membershipIds(artifactId).includes(project.id);
 	}
 }

package/src/cli/rules-command.ts

@@ -113,6 +113,93 @@ const assignProjectCommand = buildCommand({
 	docs: { brief: "Reassign a Rule's project scope, or unscope it" },
 });
 
+interface CliArtifactScope {
+	artifactId: string;
+	mode: string;
+	projectIds: string[];
+	source: string;
+}
+
+function renderScope(scope: CliArtifactScope): string {
+	return scope.mode === "global" ? "global (applies to every project)" : `projects: ${scope.projectIds.join(", ")}`;
+}
+
+const scopeCommand = buildCommand({
+	func: async function (this: RulesContext, _flags: Record<string, never>, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("rules.scope", { id });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Rule id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Show a Rule's real project scope" },
+});
+
+const setGlobalCommand = buildCommand({
+	func: async function (this: RulesContext, _flags: Record<string, never>, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("rules.set_global", { id });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Rule id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Make a Rule apply in every project" },
+});
+
+const addProjectCommand = buildCommand({
+	func: async function (this: RulesContext, _flags: Record<string, never>, id: string, project: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("rules.add_project", { id, project });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Rule id", parse: String, placeholder: "id" },
+				{ brief: "Project id/name/alias/root to add", parse: String, placeholder: "project" },
+			],
+		},
+	},
+	docs: { brief: "Add one project to a Rule's membership" },
+});
+
+const removeProjectCommand = buildCommand({
+	func: async function (this: RulesContext, _flags: Record<string, never>, id: string, project: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("rules.remove_project", { id, project });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Rule id", parse: String, placeholder: "id" },
+				{ brief: "Project id/name/alias/root to remove", parse: String, placeholder: "project" },
+			],
+		},
+	},
+	docs: { brief: "Remove one project from a Rule's membership" },
+});
+
+const replaceProjectsCommand = buildCommand({
+	func: async function (this: RulesContext, flags: { projectsJson: string[] }, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("rules.replace_projects", {
+			id,
+			projects: flags.projectsJson,
+		});
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {
+			projectsJson: {
+				brief: "JSON string array of project id/name/alias/root references",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+			},
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Rule id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Replace a Rule's entire project membership" },
+});
+
 const showCommand = buildCommand({
 	func: async function (this: RulesContext, _flags: Record<string, never>, id: string) {
 		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("rules.show", { id });
@@ -204,6 +291,11 @@ const app = buildApplication(
 			create: createCommand,
 			list: listCommand,
 			"assign-project": assignProjectCommand,
+			scope: scopeCommand,
+			"set-global": setGlobalCommand,
+			"add-project": addProjectCommand,
+			"remove-project": removeProjectCommand,
+			"replace-projects": replaceProjectsCommand,
 			show: showCommand,
 			preview: previewCommand,
 			enable: buildEnableDisableCommand("enable"),

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { execFileSync } from "node:child_process";
-import { copyFileSync, existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createNodeServiceInstallDeps, generateSystemdUnit, installUserService, type ServiceSpec } from "@danypops/vehicle-server/service";
 import { runArtifactCli } from "./cli/artifact-command.ts";
@@ -294,7 +294,15 @@ export function runIdMigrationCli(args: string[]): string {
 		try {
 			result = verifyIdMigration(mirror, plan);
 		} finally {
+			// openDb() always opens a file-backed database in WAL mode, including this mirror
+			// (produced by VACUUM INTO with no WAL of its own until this very open). Fold it back
+			// into the main file and drop the sidecars before copying just the main file below --
+			// the same reasoning already applied to target's own sidecars a few lines down. Copying
+			// the main file while leaving a newer -wal/-shm pair for a now-deleted identity behind
+			// produces a file SQLite reopens as a malformed image, not merely a stale one.
+			mirror.exec("PRAGMA wal_checkpoint(TRUNCATE)");
 			mirror.close();
+			for (const sidecar of [`${mirrorPath}-wal`, `${mirrorPath}-shm`]) if (existsSync(sidecar)) unlinkSync(sidecar);
 		}
 		if (!result.ok) {
 			throw new Error(
@@ -316,7 +324,18 @@ export function runIdMigrationCli(args: string[]): string {
 			copyFileSync(target, backupPath);
 			for (const sidecar of [`${target}-wal`, `${target}-shm`]) if (existsSync(sidecar)) unlinkSync(sidecar);
 		}
-		copyFileSync(mirrorPath, target);
+		// A plain copyFileSync(mirrorPath, target) overwrites target's own file content in place --
+		// confirmed live to reopen as "database disk image is malformed" even though both the
+		// checkpointed target and the checkpointed mirror are independently completely healthy
+		// right before this copy: something about SQLite's own handling of a path/inode this
+		// process already opened earlier in the same run (target was just opened above to
+		// checkpoint it) survives closing that connection. Copying to a fresh staging path (a new
+		// inode, never opened by this process) and swapping it into place with an atomic rename
+		// sidesteps that entirely -- renameSync never fails partway the way a corrupted in-place
+		// overwrite can.
+		const staging = `${target}.promoting`;
+		copyFileSync(mirrorPath, staging);
+		renameSync(staging, target);
 		const result2 = { target, backupPath };
 		if (json) return JSON.stringify(result2);
 		return [

package/src/constants.ts

@@ -9,7 +9,7 @@ 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 +261,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/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);
+			}
+		},
+	},
 ];
 
 /**