@danypops/papyrus 0.50.2 → 0.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.50.2",
+  "version": "0.51.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/cli/playbooks-command.ts

@@ -53,6 +53,7 @@ const createCommand = buildCommand({
 			extraJson?: Record<string, unknown>;
 			argumentsJson?: unknown[] | Record<string, unknown>;
 			projectRoot?: string;
+			projectsJson?: string[];
 		},
 	) {
 		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("playbooks.create", {
@@ -65,6 +66,7 @@ const createCommand = buildCommand({
 			extra: flags.extraJson,
 			arguments: flags.argumentsJson,
 			project_root: flags.projectRoot,
+			projects: flags.projectsJson,
 		});
 		render.call(this, artifact, `Created playbook: ${artifactLabel(artifact)}`);
 	},
@@ -91,18 +93,29 @@ const createCommand = buildCommand({
 				optional: true,
 			},
 			projectRoot: { brief: "Project scope", kind: "parsed", parse: String, placeholder: "path", optional: true },
+			projectsJson: {
+				brief: "JSON string array of project id/name/alias/root references, taking precedence over --project-root",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
 		},
 	},
 	docs: { brief: "Create a Playbook" },
 });
 
 const listCommand = buildCommand({
-	func: async function (this: PlaybooksContext, flags: { status?: string; text?: string; limit?: number; projectRoot?: string }) {
+	func: async function (
+		this: PlaybooksContext,
+		flags: { status?: string; text?: string; limit?: number; projectRoot?: string; applicable?: boolean },
+	) {
 		const rows = await this.client.call<Record<string, unknown>, CliArtifact[]>("playbooks.list", {
 			status: flags.status,
 			text: flags.text,
 			limit: flags.limit,
 			project_root: flags.projectRoot,
+			applicable: flags.applicable,
 		});
 		render.call(this, rows, rows.length === 0 ? "No playbooks found." : rows.map((row) => artifactLabel(row)).join("\n"));
 	},
@@ -112,6 +125,11 @@ const listCommand = buildCommand({
 			text: { brief: "Substring match against title/body", kind: "parsed", parse: String, placeholder: "text", optional: true },
 			limit: { brief: "Maximum playbooks to return", kind: "parsed", parse: numberParser, optional: true },
 			projectRoot: { brief: "Project scope", kind: "parsed", parse: String, placeholder: "path", optional: true },
+			applicable: {
+				brief: "With --project-root: list global Playbooks plus Playbooks applicable to it, instead of exact membership",
+				kind: "boolean",
+				optional: true,
+			},
 		},
 	},
 	docs: { brief: "List Playbooks" },
@@ -213,6 +231,93 @@ const assignProjectCommand = buildCommand({
 	docs: { brief: "Reassign a Playbook'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: PlaybooksContext, _flags: Record<string, never>, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("playbooks.scope", { id });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Playbook id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Show a Playbook's real project scope" },
+});
+
+const setGlobalCommand = buildCommand({
+	func: async function (this: PlaybooksContext, _flags: Record<string, never>, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("playbooks.set_global", { id });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Playbook id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Make a Playbook apply in every project" },
+});
+
+const addProjectCommand = buildCommand({
+	func: async function (this: PlaybooksContext, _flags: Record<string, never>, id: string, project: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("playbooks.add_project", { id, project });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Playbook id", parse: String, placeholder: "id" },
+				{ brief: "Project id/name/alias/root to add", parse: String, placeholder: "project" },
+			],
+		},
+	},
+	docs: { brief: "Add one project to a Playbook's membership" },
+});
+
+const removeProjectCommand = buildCommand({
+	func: async function (this: PlaybooksContext, _flags: Record<string, never>, id: string, project: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("playbooks.remove_project", { id, project });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Playbook id", parse: String, placeholder: "id" },
+				{ brief: "Project id/name/alias/root to remove", parse: String, placeholder: "project" },
+			],
+		},
+	},
+	docs: { brief: "Remove one project from a Playbook's membership" },
+});
+
+const replaceProjectsCommand = buildCommand({
+	func: async function (this: PlaybooksContext, flags: { projectsJson: string[] }, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("playbooks.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: "Playbook id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Replace a Playbook's entire project membership" },
+});
+
 const updateCommand = buildCommand({
 	func: async function (this: PlaybooksContext, flags: { title?: string; body?: string; labelsJson?: string[] }, id: string) {
 		if (flags.title === undefined && flags.body === undefined && flags.labelsJson === undefined)
@@ -275,6 +380,11 @@ const app = buildApplication(
 			enable: buildEnableDisableCommand("enable"),
 			disable: buildEnableDisableCommand("disable"),
 			"assign-project": assignProjectCommand,
+			scope: scopeCommand,
+			"set-global": setGlobalCommand,
+			"add-project": addProjectCommand,
+			"remove-project": removeProjectCommand,
+			"replace-projects": replaceProjectsCommand,
 			update: updateCommand,
 			contain: buildPairedIdCommand(
 				"playbooks.contain",

package/src/handlers/playbooks.ts

@@ -24,6 +24,7 @@ import type { ArtifactStore } from "../artifact/artifact-store.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 { 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";
@@ -56,6 +57,7 @@ export interface PlaybooksVehicleDeps {
 	artifactScopes: ArtifactScopeStore;
 	tasks: Tasks;
 	sessionIdentity: SessionIdentity;
+	projectRegistry: ProjectRegistryStore;
 }
 
 /** Unscoped resolution -- a Playbook is commonly cross-project (e.g. a lab-deploy playbook), matching the hand-rolled tool's own resolutionRequest choice. */
@@ -66,9 +68,12 @@ function resolvePlaybookId(artifacts: ArtifactStore, scopes: ArtifactScopeStore,
 }
 
 export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, deps: PlaybooksVehicleDeps): void {
-	const { artifacts, events, scopes, artifactScopes, tasks, sessionIdentity } = deps;
+	const { artifacts, events, scopes, artifactScopes, tasks, sessionIdentity, projectRegistry } = deps;
 	const moduleOperations = new Map(
-		playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity }).map((op) => [op.name, op]),
+		playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity, registry: projectRegistry }).map((op) => [
+			op.name,
+			op,
+		]),
 	);
 	/**
 	 * Every playbooks.* action funnels through here. invoke's own module handler re-runs
@@ -101,6 +106,7 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 			extra: { type: "object" },
 			template_id: stringProp,
 			project_root: stringProp,
+			projects: { type: "array" },
 			actor: stringProp,
 			source: stringProp,
 			session_id: stringProp,
@@ -114,9 +120,9 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 
 	define(
 		"list",
-		"Lists Playbooks matching an optional status/text filter, scoped to project_root when given. Returns a lean summary (no body/steps) by default -- pass full: true for the complete artifact.",
+		"Lists Playbooks matching an optional status/text filter. project_root alone scopes to EXACT membership in that project (audit semantics); project_root plus applicable:true instead lists every Playbook APPLICABLE to it (global Playbooks plus Playbooks whose membership includes it) -- what pi-papyrus's before_agent_start uses to inject only relevant Playbooks. Returns a lean summary (no body/steps) by default -- pass full: true for the complete artifact.",
 		"read",
-		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, full: booleanProp },
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, applicable: booleanProp, full: booleanProp },
 		[],
 		(input) => input,
 	);
@@ -200,6 +206,63 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
 	);
 
+	define(
+		"scope",
+		"Shows a Playbook's real project scope: global (applies everywhere) or the bounded set of registered projects it applies to.",
+		"read",
+		{ id: stringProp, name: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"set_global",
+		"Makes a Playbook apply in every project, clearing any project membership. The only way to widen a project-bound Playbook back to global -- removing its last membership through remove_project is rejected instead.",
+		"local-write",
+		{ id: stringProp, name: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"add_project",
+		"Adds one registered project (exact id, name, alias, or root) to a Playbook'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"],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"remove_project",
+		"Removes one registered project from a Playbook's membership. Rejected while it is the Playbook's only remaining membership -- call set_global first if the Playbook 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"],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"replace_projects",
+		"Replaces a Playbook'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." },
+		},
+		["projects"],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
 	define(
 		"update",
 		"Changes a Playbook's title/body/labels (at least one required). Refused for a read-only external projection.",

package/src/handlers/registry.ts

@@ -59,6 +59,7 @@ export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleR
 		artifactScopes: deps.scopes,
 		tasks: deps.tasks,
 		sessionIdentity: deps.sessionIdentity,
+		projectRegistry: deps.projectRegistry,
 	});
 	registerTasksVehicleOperations(registry, { tasks: deps.tasks, artifacts: deps.artifacts, sessionIdentity: deps.sessionIdentity });
 	registerDiscussVehicleOperations(registry, deps.discussions, deps.artifacts);

package/src/modules/playbooks.ts

@@ -16,18 +16,24 @@ import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { OperationDefinition } from "../module-registry.ts";
 import { invokePlaybook } from "../playbook/playbook-execution.ts";
 import {
+	addPlaybookProject,
 	assignPlaybookProject,
 	containPlaybook,
 	createPlaybook,
 	dependPlaybook,
 	listPlaybooks,
 	playbookInvocation,
+	playbookScope,
+	removePlaybookProject,
+	replacePlaybookProjects,
+	setPlaybookGlobal,
 	showPlaybook,
 	transitionPlaybook,
 	uncontainPlaybook,
 	undependPlaybook,
 	updatePlaybook,
 } from "../playbook/playbook-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";
@@ -47,12 +53,24 @@ const eventContextFor = (input: OperationInput, source: string) => {
 	return { ...context, source: context.source ?? source };
 };
 
-const artifactFilter = (input: OperationInput) => ({
-	status: optionalString(input, "status"),
-	text: optionalString(input, "text"),
-	limit: optionalNumber(input, "limit"),
-	projectRoot: optionalString(input, "project_root"),
-});
+/**
+ * applicable=true switches project_root's meaning from exact-membership audit listing to
+ * applicable listing (global Playbooks plus Playbooks whose membership includes it) -- see
+ * ListFilter's own doc comment on projectRoot vs applicableToProjectRoot. Used by pi-papyrus's
+ * before_agent_start to inject only Playbooks applicable to ctx.cwd, not every active Playbook
+ * across every project.
+ */
+const artifactFilter = (input: OperationInput) => {
+	const projectRoot = optionalString(input, "project_root");
+	const applicable = optionalBoolean(input, "applicable") === true;
+	if (applicable && projectRoot === undefined) throw new Error("applicable requires project_root");
+	return {
+		status: optionalString(input, "status"),
+		text: optionalString(input, "text"),
+		limit: optionalNumber(input, "limit"),
+		...(applicable ? { applicableToProjectRoot: projectRoot } : { projectRoot }),
+	};
+};
 
 /** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. */
 export const PLAYBOOKS_OPERATION_NAMES = [
@@ -64,6 +82,11 @@ export const PLAYBOOKS_OPERATION_NAMES = [
 	"playbooks.enable",
 	"playbooks.disable",
 	"playbooks.assign_project",
+	"playbooks.scope",
+	"playbooks.set_global",
+	"playbooks.add_project",
+	"playbooks.remove_project",
+	"playbooks.replace_projects",
 	"playbooks.update",
 	"playbooks.contain",
 	"playbooks.uncontain",
@@ -81,6 +104,7 @@ export interface PlaybooksModuleDeps {
 	tasks: Tasks;
 	/** Guards the same session_secret check tasks.focus's own operation enforces (guardFocusMutation in modules/tasks.ts) -- invoke's internal tasks.focus() call goes straight through the Tasks class, bypassing that operation wrapper entirely, so the check must be applied here instead of silently skipped. */
 	sessionIdentity: SessionIdentity;
+	registry: ProjectRegistryStore;
 }
 
 export function playbooksOperations({
@@ -90,6 +114,7 @@ export function playbooksOperations({
 	artifactScopes,
 	tasks,
 	sessionIdentity,
+	registry,
 }: PlaybooksModuleDeps): OperationDefinition[] {
 	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
 		name,
@@ -113,8 +138,10 @@ export function playbooksOperations({
 					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,
 			),
 		),
 		define("playbooks.list", (input: OperationInput) => {
@@ -133,7 +160,13 @@ export function playbooksOperations({
 					runId: optionalString(input, "run_id") ?? optionalString(input, "runId"),
 					arguments: input.arguments as Record<string, unknown> | undefined,
 				},
-				{ events, scopes, projectRoot: optionalString(input, "project_root"), context: eventContextFor(input, "playbook-run") },
+				{
+					events,
+					scopes,
+					artifactScopes,
+					projectRoot: optionalString(input, "project_root"),
+					context: eventContextFor(input, "playbook-run"),
+				},
 			);
 			if ("missingArguments" in result) return result;
 			const focusContext = eventContextFor(input, "playbook-run");
@@ -150,6 +183,17 @@ export function playbooksOperations({
 		define("playbooks.assign_project", (input: OperationInput) =>
 			assignPlaybookProject(artifacts, artifactScopes, string(input, "id"), optionalString(input, "project_root")),
 		),
+		define("playbooks.scope", (input: OperationInput) => playbookScope(artifacts, artifactScopes, string(input, "id"))),
+		define("playbooks.set_global", (input: OperationInput) => setPlaybookGlobal(artifacts, artifactScopes, string(input, "id"))),
+		define("playbooks.add_project", (input: OperationInput) =>
+			addPlaybookProject(artifacts, artifactScopes, registry, string(input, "id"), string(input, "project")),
+		),
+		define("playbooks.remove_project", (input: OperationInput) =>
+			removePlaybookProject(artifacts, artifactScopes, registry, string(input, "id"), string(input, "project")),
+		),
+		define("playbooks.replace_projects", (input: OperationInput) =>
+			replacePlaybookProjects(artifacts, artifactScopes, registry, string(input, "id"), (input.projects as string[] | undefined) ?? []),
+		),
 		define("playbooks.update", (input: OperationInput) =>
 			updatePlaybook(
 				artifacts,

package/src/playbook/playbook-service.ts

@@ -25,9 +25,10 @@
 import type { Artifact } from "../artifact/artifact.ts";
 import { requireLocallyOwnedContent } from "../artifact/artifact.ts";
 import type { ArtifactEventContext } from "../artifact/artifact-event.ts";
-import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
+import type { ArtifactScope, ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import {
+	ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT,
 	ARTIFACT_TITLE_MAX_LENGTH,
 	PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH,
 	PLAYBOOK_ARGUMENT_MAX_COUNT,
@@ -43,6 +44,7 @@ import {
 	type BlueprintInputType,
 	validateArgumentValue,
 } from "../domain/blueprint-definition.ts";
+import { resolveProjectReference } from "../domain/project-registry.ts";
 import { normalizeProjectRoot } from "../domain/task-scope.ts";
 import {
 	assertBodyBounds,
@@ -57,6 +59,7 @@ import {
 	type TransitionTable,
 	type UpdateContentInput,
 } from "../domain-service-shared.ts";
+import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
 
 export interface PlaybookArgument {
 	name: string;
@@ -220,6 +223,8 @@ export interface CreatePlaybookInput {
 	extra?: Record<string, unknown>;
 	templateId?: string;
 	projectRoot?: string;
+	/** Bounded exact registered project references (id/name/alias/root) -- fail-closed unlike projectRoot's auto-register-by-root legacy form. Takes precedence over projectRoot when both are given. */
+	projectReferences?: string[];
 }
 
 export type PlaybookTransition = "enable" | "disable";
@@ -235,7 +240,11 @@ export function createPlaybook(
 	scopes: ArtifactScopeStore,
 	input: CreatePlaybookInput,
 	context?: ArtifactEventContext,
+	registry?: ProjectRegistryStore,
 ): Artifact {
+	if (input.projectReferences !== undefined && input.projectReferences.length > 0 && registry === undefined) {
+		throw new Error("projectReferences requires a project registry");
+	}
 	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
 	const declaredArguments = validatePlaybookArguments(input.arguments);
 	const declaredSteps = validatePlaybookSteps(input.steps);
@@ -258,7 +267,15 @@ export function createPlaybook(
 		},
 		context,
 	);
-	scopes.assign(playbook.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	if (input.projectReferences !== undefined && input.projectReferences.length > 0) {
+		if (input.projectReferences.length > ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
+			throw new Error(`projectReferences may include at most ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} entries`);
+		}
+		const ids = input.projectReferences.map((reference) => resolveProjectReference(registry!, reference).id);
+		scopes.replaceProjects(playbook.id, ids, "explicit");
+	} else {
+		scopes.assign(playbook.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	}
 	return playbook;
 }
 
@@ -275,6 +292,65 @@ export function assignPlaybookProject(
 	return assignArtifactProject(artifacts, scopes, id, "playbook", projectRoot);
 }
 
+/**
+ * The multi-project scope surface playbooks.assign_project cannot express -- mirrors
+ * docs.ts's own docScope/setDocGlobal/addDocProject/removeDocProject/replaceDocProjects (which
+ * itself mirrors rules.ts's original). id is resolved through requireKind so these reject the
+ * same way against a non-Playbook or unknown id as every other playbooks.* mutation; the
+ * project REFERENCE (name/alias/root) is resolved through the shared registry's
+ * resolveProjectReference, so an unknown or ambiguous project fails closed with bounded
+ * candidates rather than silently creating a new registration.
+ */
+export function playbookScope(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string): ArtifactScope {
+	requireKind(artifacts, id, "playbook");
+	return scopes.scope(id);
+}
+
+export function setPlaybookGlobal(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string): ArtifactScope {
+	requireKind(artifacts, id, "playbook");
+	return scopes.setGlobal(id, "explicit");
+}
+
+export function replacePlaybookProjects(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	id: string,
+	projectReferences: readonly string[],
+): ArtifactScope {
+	requireKind(artifacts, id, "playbook");
+	if (projectReferences.length === 0) throw new Error("projectReferences must be non-empty; use playbooks.set_global to clear scoping");
+	if (projectReferences.length > ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
+		throw new Error(`projectReferences may include at most ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} entries`);
+	}
+	const ids = projectReferences.map((reference) => resolveProjectReference(registry, reference).id);
+	return scopes.replaceProjects(id, ids, "explicit");
+}
+
+export function addPlaybookProject(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	id: string,
+	projectReference: string,
+): ArtifactScope {
+	requireKind(artifacts, id, "playbook");
+	const project = resolveProjectReference(registry, projectReference);
+	return scopes.addProject(id, project.id, "explicit");
+}
+
+export function removePlaybookProject(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	id: string,
+	projectReference: string,
+): ArtifactScope {
+	requireKind(artifacts, id, "playbook");
+	const project = resolveProjectReference(registry, projectReference);
+	return scopes.removeProject(id, project.id);
+}
+
 export function showPlaybook(artifacts: ArtifactStore, id: string): Artifact {
 	requireKind(artifacts, id, "playbook");
 	return artifacts.get(id, { tree: true })!;

package/src/playbook/workflow-execution.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { Artifact } from "../artifact/artifact.ts";
+import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { requireAtomicArtifactStore } from "../artifact/atomic-artifact-store.ts";
 import {
@@ -150,8 +151,28 @@ function executionGraph(tasks: Artifact[], definition: BlueprintDefinition, ids:
 	return { nodes, rootIds: nodes.filter((node) => node.parentIds.length === 0).map((node) => node.task.id) };
 }
 
-/** projectRoot is optional -- skills.run always supplies one (workflow-definition runs are always project-scoped today), while a Playbook invocation may legitimately be ad hoc/cross-project (e.g. a lab-deploy playbook not tied to any one repo), landing its tasks in the same "unscoped" bucket Tasks.create already supports for a caller that omits projectRoot entirely. */
-export type WorkflowRunHistory = { events: TaskEventStore; scopes: TaskScopeStore; projectRoot?: string; context?: TaskEventContext };
+/**
+ * projectRoot is optional -- skills.run always supplies one (workflow-definition runs are always
+ * project-scoped today), while a Playbook invocation may legitimately be ad hoc/cross-project
+ * (e.g. a lab-deploy playbook not tied to any one repo), landing its tasks in the same
+ * "unscoped" bucket Tasks.create already supports for a caller that omits projectRoot entirely.
+ *
+ * artifactScopes is optional for the same reason: a caller with no Doc/Rule project-scoping
+ * concept at all (a bare workflow-definition run with no ArtifactScopeStore wired) still works
+ * unchanged, generated Docs/Rules simply staying unscoped/global like every artifact created
+ * before project scoping existed. When supplied, a generated Doc/Rule inherits the SAME
+ * destination projectRoot a generated Task already does via `scopes` -- the real fix for a
+ * previously-confirmed gap: generated Docs/Rules bypassed ArtifactScopeStore entirely, so a
+ * playbook invoked with a destination project still injected its own generated Rules into every
+ * other project's context.
+ */
+export type WorkflowRunHistory = {
+	events: TaskEventStore;
+	scopes: TaskScopeStore;
+	artifactScopes?: ArtifactScopeStore;
+	projectRoot?: string;
+	context?: TaskEventContext;
+};
 
 /**
  * Public entry point: wraps one complete pipeline run (including every nested sub-pipeline
@@ -307,8 +328,8 @@ export function materializeWorkflowDefinition(
 		throw new TaskExecutionBoundExceededError(`workflow run exceeds ${TASK_EXECUTION_MAX_EDGES} relationships`);
 	}
 
-	const docs = rendered.blueprints.docs.map((blueprint) =>
-		artifacts.create({
+	const docs = rendered.blueprints.docs.map((blueprint) => {
+		const doc = artifacts.create({
 			id: ids.get(blueprint.ref),
 			kind: "doc",
 			title: blueprint.title,
@@ -316,10 +337,12 @@ export function materializeWorkflowDefinition(
 			subtype: blueprint.subtype,
 			labels: withRunLabel(blueprint.labels, labelPrefix, runId),
 			extra: { ...(blueprint.extra ?? {}), [extraKey]: { id: runId, ownerId, ref: blueprint.ref } },
-		}),
-	);
-	const rules = rendered.blueprints.rules.map((blueprint) =>
-		artifacts.create({
+		});
+		history?.artifactScopes?.assign(doc.id, projectRoot, projectRoot ? "cwd" : "unscoped");
+		return doc;
+	});
+	const rules = rendered.blueprints.rules.map((blueprint) => {
+		const rule = artifacts.create({
 			id: ids.get(blueprint.ref),
 			kind: "rule",
 			title: blueprint.title,
@@ -331,10 +354,15 @@ export function materializeWorkflowDefinition(
 				...(blueprint.action ? { action: blueprint.action } : {}),
 				...(blueprint.severity ? { severity: blueprint.severity } : {}),
 				[extraKey]: { id: runId, ownerId, ref: blueprint.ref },
+				// extra.scope is run-gating only (listInjectableRules' passesRunScope) -- an
+				// independent AND-condition alongside project-membership (appliesToProjectRoot,
+				// assigned just below), never a replacement for it.
 				scope: { type: labelPrefix, runId, taskIds },
 			},
-		}),
-	);
+		});
+		history?.artifactScopes?.assign(rule.id, projectRoot, projectRoot ? "cwd" : "unscoped");
+		return rule;
+	});
 	const tasks = rendered.blueprints.tasks.map((blueprint) => {
 		const task = artifacts.create({
 			id: ids.get(blueprint.ref),

package/src/service.ts

@@ -441,6 +441,11 @@ function handlers(
 		"playbooks.enable": forwardToModule("playbooks.enable"),
 		"playbooks.disable": forwardToModule("playbooks.disable"),
 		"playbooks.assign_project": forwardToModule("playbooks.assign_project"),
+		"playbooks.scope": forwardToModule("playbooks.scope"),
+		"playbooks.set_global": forwardToModule("playbooks.set_global"),
+		"playbooks.add_project": forwardToModule("playbooks.add_project"),
+		"playbooks.remove_project": forwardToModule("playbooks.remove_project"),
+		"playbooks.replace_projects": forwardToModule("playbooks.replace_projects"),
 		"playbooks.update": forwardToModule("playbooks.update"),
 		"playbooks.contain": forwardToModule("playbooks.contain"),
 		"playbooks.uncontain": forwardToModule("playbooks.uncontain"),
@@ -505,7 +510,9 @@ export function createPapyrusService(path: string): PapyrusService {
 	moduleRegistry.registerAll(tasksOperations(tasks, artifacts, sessionIdentity));
 	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority, projectRegistry));
 	moduleRegistry.registerAll(rulesOperations(artifacts, artifactScopes, projectRegistry));
-	moduleRegistry.registerAll(playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity }));
+	moduleRegistry.registerAll(
+		playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity, registry: projectRegistry }),
+	);
 	moduleRegistry.registerAll(graphProjectionOperations(artifacts, projections, authority));
 	const registry = handlers(artifacts, gates, tasks, notes, events, scopes, artifactScopes, () => migrateDb(db), moduleRegistry, authority);
 	const state = (): SchemaState => {