@danypops/papyrus 0.55.0 → 0.57.0

package/package.json

@@ -1,10 +1,23 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./artifact": "./src/artifact/index.ts",
+    "./client": "./src/client.ts",
+    "./discussion": "./src/discussion/index.ts",
+    "./domain": "./src/domain/index.ts",
+    "./note": "./src/note/index.ts",
+    "./playbook": "./src/playbook/index.ts",
+    "./stores": "./src/stores/index.ts",
+    "./task": "./src/task/index.ts",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
   "bin": {
     "papyrus": "src/cli.ts"
   },

package/src/artifact/artifact-relationship-view.ts

@@ -1,4 +1,4 @@
-import type { DisplayGraph, DisplayGraphEdge, DisplayGraphNode } from "../domain/display-graph.ts";
+import type { DisplayGraph, DisplayGraphEdge, DisplayGraphNode } from "../display-graph/display-graph.ts";
 import { fallbackLabel } from "../task/task-relationship-view.ts";
 import type { Artifact } from "./artifact.ts";
 

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

@@ -1,22 +1,24 @@
-import type { TaskScopeSource } from "../domain/task-scope.ts";
+import type { ScopeMemberRef } from "../scope-group/scope-group.ts";
+import type { TaskScopeSource } from "../task-scope/task-scope.ts";
 
 /**
- * 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.
+ * Project scoping for Docs/Rules/Playbooks: an artifact is explicitly "none" (hidden -- never
+ * applicable, never context-injected, regardless of project), explicitly "all" (applies
+ * everywhere), or bound to a bounded, non-empty set of explicit members -- never inferred from
+ * an accidentally empty join table, which is why `mode` is its own explicit field rather than
+ * "members.length === 0 means none/all". A member is either a registered project (from the
+ * shared ProjectRegistryStore) or a scope group (from ScopeGroupStore, itself a possibly-nested
+ * collection of projects/groups) -- "explicit scope can include nested scopes". Membership is by
+ * id, never by root/name, so a registered project's root (or a group's name) can move without a
+ * best-effort string rewrite across every artifact that references it.
  */
-export type ArtifactScopeMode = "global" | "projects";
+export type ArtifactScopeMode = "none" | "all" | "explicit";
 
 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[];
+	/** Direct membership only (not expanded through nested groups) -- always empty when mode is "none"/"all", always non-empty when mode is "explicit". */
+	members: ScopeMemberRef[];
 	source: TaskScopeSource;
 }
 
@@ -27,24 +29,28 @@ export interface LegacyArtifactScope {
 }
 
 export interface ArtifactScopeStore {
-	/** The real, non-lossy multi-membership view. Defaults to global/unscoped for an artifact with no scope row yet. */
+	/** The real, non-lossy multi-membership view. Defaults to "all"/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. */
+	/** Single-root compatibility view over scope(): an "all"/"none" or unscoped artifact omits projectRoot; an "explicit" mode artifact with exactly one project-type membership (and no group members) resolves it back to that project's current root; anything else (zero, more than one, or any group membership) omits projectRoot, since this shape cannot represent it. */
 	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. */
+	/** Single-root compatibility shim: registers/resolves projectRoot and replaces the artifact's scope with exactly that one project membership, or setAll() 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. */
+	/** Sets an artifact to explicitly "all" (applies everywhere), clearing any membership. */
+	setAll(artifactId: string, source: TaskScopeSource): ArtifactScope;
+	/** Sets an artifact to explicitly "none" (fully hidden -- never applicable, never context-injected, regardless of project), clearing any membership. */
+	setNone(artifactId: string, source: TaskScopeSource): ArtifactScope;
+	/** Replaces an artifact's entire explicit membership set with exactly these (project and/or group) members -- must be non-empty; use setAll/setNone to clear scoping entirely. */
+	replaceMembers(artifactId: string, members: readonly ScopeMemberRef[], source: TaskScopeSource): ArtifactScope;
+	/** Adds one member to an artifact's explicit membership (idempotent), switching mode to "explicit" if it was "all"/"none". Enforces the bounded maximum membership count. */
+	addMember(artifactId: string, member: ScopeMemberRef, source: TaskScopeSource): ArtifactScope;
+	/** Removes one member from an artifact's explicit membership (idempotent). Rejects removing the last membership while mode is "explicit": a caller must explicitly call setAll/setNone instead of accidentally broadening/narrowing scope by emptying the set. */
+	removeMember(artifactId: string, member: ScopeMemberRef): ArtifactScope;
+	/** Bounded id listing for one project root's EXACT direct membership (or the "all" bucket when projectRoot is undefined) -- an unregistered root always yields an empty list. Deliberately does not expand nested groups (audit semantics, matching this method's own pre-existing "exact membership" contract) -- use appliesToProjectRoot for the applicable/injection query instead. */
 	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. */
+	/** True when artifactId's scope is "all", or "explicit" with projectId reachable from its member set (a direct project member, or transitively through a nested group member) -- false for "none". False for an unscoped artifact with no row is never returned (defaults to "all" behavior); injection call sites decide their own applicability policy beyond this raw membership fact. */
 	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. */
+	/** Root-based convenience over appliesToProject, for a caller (e.g. rules.injectable) that only has a project root, not a resolved id. An unregistered root means only an "all"-mode artifact applies; projectRoot === undefined means "no project context at all", so only "all"-mode artifacts apply either way. */
 	appliesToProjectRoot(artifactId: string, projectRoot: string | undefined): boolean;
+	/** True when any artifact's own explicit scope references this scope group as a direct member -- checked by deleteScopeGroup before allowing a group to be deleted. */
+	referencesGroup(groupId: string): boolean;
 }

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

@@ -1,30 +1,35 @@
-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";
+import { ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT } from "../constants.ts";
+import { InMemoryProjectRegistryStore } from "../project-registry/in-memory-project-registry-store.ts";
+import type { ProjectRegistryStore } from "../project-registry/project-registry-store.ts";
+import { InMemoryScopeGroupStore } from "../scope-group/in-memory-scope-group-store.ts";
+import { type ScopeMemberRef, sameScopeMember } from "../scope-group/scope-group.ts";
+import type { ScopeGroupStore } from "../scope-group/scope-group-store.ts";
+import type { TaskScopeSource } from "../task-scope/task-scope.ts";
+import type { ArtifactScope, ArtifactScopeMode, ArtifactScopeStore, LegacyArtifactScope } from "./artifact-scope-store.ts";
 
 interface Row {
-	mode: "global" | "projects";
-	projectIds: Set<string>;
+	mode: ArtifactScopeMode;
+	members: ScopeMemberRef[];
 	source: TaskScopeSource;
 }
 
 export class InMemoryArtifactScopeStore implements ArtifactScopeStore {
 	private readonly rows = new Map<string, Row>();
 	private readonly registry: InMemoryProjectRegistryStore;
+	private readonly scopeGroups: ScopeGroupStore;
 
-	// 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) {
+	// Membership is stored by project/group id, never by root/name, so a registry root move (see
+	// ProjectRegistryStore.registerProject) or a scope group rename needs no rewrite here at all --
+	// unlike InMemoryTaskScopeStore, this store never subscribes to root-move notifications.
+	constructor(registry?: ProjectRegistryStore, scopeGroups?: ScopeGroupStore) {
 		this.registry = registry instanceof InMemoryProjectRegistryStore ? registry : new InMemoryProjectRegistryStore();
+		this.scopeGroups = scopeGroups ?? new InMemoryScopeGroupStore();
 	}
 
 	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" };
+			? { artifactId, mode: row.mode, members: [...row.members], source: row.source }
+			: { artifactId, mode: "all", members: [], source: "unscoped" };
 	}
 
 	scope(artifactId: string): ArtifactScope {
@@ -34,58 +39,67 @@ export class InMemoryArtifactScopeStore implements ArtifactScopeStore {
 	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;
+		const onlyProjectMember =
+			row.mode === "explicit" && row.members.length === 1 && row.members[0]!.type === "project" ? row.members[0] : undefined;
+		const projectRoot = onlyProjectMember === undefined ? undefined : this.registry.byId(onlyProjectMember.id)?.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);
+			this.setAll(artifactId, source);
 			return { artifactId, source };
 		}
 		const project = this.registry.registerProject({ projectRoot });
-		this.replaceProjects(artifactId, [project.id], source);
+		this.replaceMembers(artifactId, [{ type: "project", id: project.id }], source);
 		return { artifactId, projectRoot: project.projectRoot, source };
 	}
 
-	setGlobal(artifactId: string, source: TaskScopeSource): ArtifactScope {
-		const row: Row = { mode: "global", projectIds: new Set(), source };
+	setAll(artifactId: string, source: TaskScopeSource): ArtifactScope {
+		const row: Row = { mode: "all", members: [], 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`);
+	setNone(artifactId: string, source: TaskScopeSource): ArtifactScope {
+		const row: Row = { mode: "none", members: [], source };
+		this.rows.set(artifactId, row);
+		return this.toScope(artifactId, row);
+	}
+
+	replaceMembers(artifactId: string, members: readonly ScopeMemberRef[], source: TaskScopeSource): ArtifactScope {
+		if (members.length === 0) throw new Error("replaceMembers requires at least one member; use setAll/setNone to clear scoping");
+		if (members.length > ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT) {
+			throw new Error(`an artifact cannot have more than ${ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT} scope members`);
 		}
-		const row: Row = { mode: "projects", projectIds: new Set(projectIds), source };
+		const unique = dedupeMembers(members);
+		const row: Row = { mode: "explicit", members: unique, source };
 		this.rows.set(artifactId, row);
 		return this.toScope(artifactId, row);
 	}
 
-	addProject(artifactId: string, projectId: string, source: TaskScopeSource): ArtifactScope {
+	addMember(artifactId: string, member: ScopeMemberRef, 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`);
+		const members = dedupeMembers(existing?.mode === "explicit" ? existing.members : []);
+		if (!members.some((candidate) => sameScopeMember(candidate, member)) && members.length >= ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT) {
+			throw new Error(`an artifact cannot have more than ${ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT} scope members`);
 		}
-		projectIds.add(projectId);
-		const row: Row = { mode: "projects", projectIds, source };
+		if (!members.some((candidate) => sameScopeMember(candidate, member))) members.push(member);
+		const row: Row = { mode: "explicit", members, source };
 		this.rows.set(artifactId, row);
 		return this.toScope(artifactId, row);
 	}
 
-	removeProject(artifactId: string, projectId: string): ArtifactScope {
+	removeMember(artifactId: string, member: ScopeMemberRef): 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");
+		if (existing?.mode !== "explicit" || !existing.members.some((candidate) => sameScopeMember(candidate, member))) {
+			return this.toScope(artifactId, existing);
 		}
-		const projectIds = new Set(existing.projectIds);
-		projectIds.delete(projectId);
-		const row: Row = { mode: "projects", projectIds, source: existing.source };
+		if (existing.members.length === 1) {
+			throw new Error("cannot remove the last scope member; call setAll or setNone instead of accidentally widening/hiding scope");
+		}
+		const members = existing.members.filter((candidate) => !sameScopeMember(candidate, member));
+		const row: Row = { mode: "explicit", members, source: existing.source };
 		this.rows.set(artifactId, row);
 		return this.toScope(artifactId, row);
 	}
@@ -93,7 +107,7 @@ export class InMemoryArtifactScopeStore implements ArtifactScopeStore {
 	ids(projectRoot: string | undefined, limit: number): string[] {
 		if (projectRoot === undefined) {
 			return [...this.rows.entries()]
-				.filter(([, row]) => row.mode === "global")
+				.filter(([, row]) => row.mode === "all")
 				.map(([artifactId]) => artifactId)
 				.sort()
 				.slice(0, limit);
@@ -101,23 +115,48 @@ export class InMemoryArtifactScopeStore implements ArtifactScopeStore {
 		const project = this.registry.byRoot(projectRoot);
 		if (!project) return [];
 		return [...this.rows.entries()]
-			.filter(([, row]) => row.mode === "projects" && row.projectIds.has(project.id))
+			.filter(([, row]) => row.mode === "explicit" && row.members.some((member) => member.type === "project" && member.id === project.id))
 			.map(([artifactId]) => artifactId)
 			.sort()
 			.slice(0, limit);
 	}
 
+	private expandedProjectIds(row: Row): Set<string> {
+		const result = new Set<string>();
+		for (const member of row.members) {
+			if (member.type === "project") result.add(member.id);
+			else for (const projectId of this.scopeGroups.expandToProjectIds(member.id)) result.add(projectId);
+		}
+		return result;
+	}
+
 	appliesToProject(artifactId: string, projectId: string): boolean {
 		const row = this.rows.get(artifactId);
-		if (!row || row.mode === "global") return true;
-		return row.projectIds.has(projectId);
+		if (!row || row.mode === "all") return true;
+		if (row.mode === "none") return false;
+		return this.expandedProjectIds(row).has(projectId);
 	}
 
 	appliesToProjectRoot(artifactId: string, projectRoot: string | undefined): boolean {
 		const row = this.rows.get(artifactId);
-		if (!row || row.mode === "global") return true;
+		if (!row || row.mode === "all") return true;
+		if (row.mode === "none") return false;
 		if (projectRoot === undefined) return false;
 		const project = this.registry.byRoot(projectRoot);
-		return project !== undefined && row.projectIds.has(project.id);
+		return project !== undefined && this.expandedProjectIds(row).has(project.id);
+	}
+
+	referencesGroup(groupId: string): boolean {
+		return [...this.rows.values()].some(
+			(row) => row.mode === "explicit" && row.members.some((member) => member.type === "group" && member.id === groupId),
+		);
+	}
+}
+
+function dedupeMembers(members: readonly ScopeMemberRef[]): ScopeMemberRef[] {
+	const result: ScopeMemberRef[] = [];
+	for (const member of members) {
+		if (!result.some((candidate) => sameScopeMember(candidate, member))) result.push(member);
 	}
+	return result;
 }

package/src/artifact/index.ts

@@ -0,0 +1,3 @@
+export type { Artifact, ArtifactEdge } from "./artifact.ts";
+export { projectArtifactRelationships } from "./artifact-relationship-view.ts";
+export type { ArtifactStore } from "./artifact-store.ts";

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

@@ -1,8 +1,10 @@
-import { ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT } from "../constants.ts";
+import { ARTIFACT_SCOPE_MAX_MEMBERS_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 { SQLiteProjectRegistryStore } from "../stores/sqlite-project-registry-store.ts";
+import { SQLiteProjectRegistryStore } from "../project-registry/sqlite-project-registry-store.ts";
+import type { ScopeMemberRef } from "../scope-group/scope-group.ts";
+import { SQLiteScopeGroupStore } from "../scope-group/sqlite-scope-group-store.ts";
+import type { TaskScopeSource } from "../task-scope/task-scope.ts";
 import type { ArtifactScope, ArtifactScopeMode, ArtifactScopeStore, LegacyArtifactScope } from "./artifact-scope-store.ts";
 
 interface ScopeRow {
@@ -11,22 +13,33 @@ interface ScopeRow {
 	source: TaskScopeSource;
 }
 
+interface MemberRow {
+	member_type: "project" | "group";
+	member_id: string;
+}
+
+function memberFromRow(row: MemberRow): ScopeMemberRef {
+	return row.member_type === "project" ? { type: "project", id: row.member_id } : { type: "group", id: row.member_id };
+}
+
 export class SQLiteArtifactScopeStore implements ArtifactScopeStore {
 	private readonly registry: SQLiteProjectRegistryStore;
+	private readonly scopeGroups: SQLiteScopeGroupStore;
 
-	// 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.
+	// Membership is by project/group id, not root/name -- a registry root move or scope group
+	// rename needs no rewrite of artifact_scope_members at all, unlike SQLiteTaskScopeStore's own
+	// task_scopes/task_views rewrite.
 	constructor(private readonly db: Db) {
 		this.registry = new SQLiteProjectRegistryStore(db);
+		this.scopeGroups = new SQLiteScopeGroupStore(db);
 	}
 
-	private membershipIds(artifactId: string): string[] {
+	private members(artifactId: string): ScopeMemberRef[] {
 		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);
+			this.db
+				.prepare("SELECT member_type, member_id FROM artifact_scope_members WHERE artifact_id = ? ORDER BY member_type, member_id")
+				.all(artifactId) as MemberRow[]
+		).map(memberFromRow);
 	}
 
 	private readRow(artifactId: string): ScopeRow | undefined {
@@ -38,28 +51,28 @@ export class SQLiteArtifactScopeStore implements ArtifactScopeStore {
 
 	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 };
+		if (!row) return { artifactId, mode: "all", members: [], source: "unscoped" };
+		return { artifactId, mode: row.mode, members: row.mode === "explicit" ? this.members(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]);
+		if (row.mode !== "explicit") return { artifactId, source: row.source };
+		const members = this.members(artifactId);
+		if (members.length !== 1 || members[0]!.type !== "project") return { artifactId, source: row.source };
+		const project = this.registry.matchingProjects(members[0]!.id).find((candidate) => candidate.id === members[0]!.id);
 		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);
+			this.setAll(artifactId, source);
 			return { artifactId, source };
 		}
 		return inTransaction(this.db, () => {
 			const project = this.registry.registerProject({ projectRoot });
-			this.replaceProjects(artifactId, [project.id], source);
+			this.replaceMembers(artifactId, [{ type: "project", id: project.id }], source);
 			return { artifactId, projectRoot: project.projectRoot, source };
 		});
 	}
@@ -78,58 +91,77 @@ export class SQLiteArtifactScopeStore implements ArtifactScopeStore {
 			.run(artifactId, mode, source, new Date().toISOString());
 	}
 
-	setGlobal(artifactId: string, source: TaskScopeSource): ArtifactScope {
+	setAll(artifactId: string, source: TaskScopeSource): ArtifactScope {
+		return inTransaction(this.db, () => {
+			this.upsertScopeRow(artifactId, "all", source);
+			this.db.prepare("DELETE FROM artifact_scope_members WHERE artifact_id = ?").run(artifactId);
+			return { artifactId, mode: "all", members: [], source };
+		});
+	}
+
+	setNone(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 };
+			this.upsertScopeRow(artifactId, "none", source);
+			this.db.prepare("DELETE FROM artifact_scope_members WHERE artifact_id = ?").run(artifactId);
+			return { artifactId, mode: "none", members: [], 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`);
+	replaceMembers(artifactId: string, members: readonly ScopeMemberRef[], source: TaskScopeSource): ArtifactScope {
+		if (members.length === 0) throw new Error("replaceMembers requires at least one member; use setAll/setNone to clear scoping");
+		if (members.length > ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT) {
+			throw new Error(`an artifact cannot have more than ${ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT} scope members`);
 		}
 		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 };
+			this.upsertScopeRow(artifactId, "explicit", source);
+			this.db.prepare("DELETE FROM artifact_scope_members WHERE artifact_id = ?").run(artifactId);
+			const insert = this.db.prepare("INSERT OR IGNORE INTO artifact_scope_members (artifact_id, member_type, member_id) VALUES (?, ?, ?)");
+			const seen = new Set<string>();
+			for (const member of members) {
+				const key = `${member.type}:${member.id}`;
+				if (seen.has(key)) continue;
+				seen.add(key);
+				insert.run(artifactId, member.type, member.id);
+			}
+			return { artifactId, mode: "explicit", members: this.members(artifactId), source };
 		});
 	}
 
-	addProject(artifactId: string, projectId: string, source: TaskScopeSource): ArtifactScope {
+	addMember(artifactId: string, member: ScopeMemberRef, 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`);
+			const current = this.members(artifactId);
+			const already = current.some((candidate) => candidate.type === member.type && candidate.id === member.id);
+			if (!already && current.length >= ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT) {
+				throw new Error(`an artifact cannot have more than ${ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT} scope members`);
 			}
-			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 };
+			this.upsertScopeRow(artifactId, "explicit", source);
+			this.db
+				.prepare("INSERT OR IGNORE INTO artifact_scope_members (artifact_id, member_type, member_id) VALUES (?, ?, ?)")
+				.run(artifactId, member.type, member.id);
+			return { artifactId, mode: "explicit", members: this.members(artifactId), source };
 		});
 	}
 
-	removeProject(artifactId: string, projectId: string): ArtifactScope {
+	removeMember(artifactId: string, member: ScopeMemberRef): 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);
+			const current = row?.mode === "explicit" ? this.members(artifactId) : [];
+			const already = current.some((candidate) => candidate.type === member.type && candidate.id === member.id);
+			if (row?.mode !== "explicit" || !already) 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");
+				throw new Error("cannot remove the last scope member; call setAll or setNone instead of accidentally widening/hiding scope");
 			}
-			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 };
+			this.db
+				.prepare("DELETE FROM artifact_scope_members WHERE artifact_id = ? AND member_type = ? AND member_id = ?")
+				.run(artifactId, member.type, member.id);
+			return { artifactId, mode: "explicit", members: this.members(artifactId), source: row.source };
 		});
 	}
 
 	ids(projectRoot: string | undefined, limit: number): string[] {
 		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<{
+				this.db.prepare("SELECT artifact_id FROM artifact_scopes WHERE mode = 'all' ORDER BY artifact_id LIMIT ?").all(limit) as Array<{
 					artifact_id: string;
 				}>
 			).map((row) => row.artifact_id);
@@ -139,28 +171,45 @@ export class SQLiteArtifactScopeStore implements ArtifactScopeStore {
 		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
+					SELECT asm.artifact_id AS artifact_id
+					FROM artifact_scope_members asm
+					JOIN artifact_scopes s ON s.artifact_id = asm.artifact_id AND s.mode = 'explicit'
+					WHERE asm.member_type = 'project' AND asm.member_id = ?
+					ORDER BY asm.artifact_id
 					LIMIT ?
 				`)
 				.all(project.id, limit) as Array<{ artifact_id: string }>
 		).map((row) => row.artifact_id);
 	}
 
+	private expandedProjectIds(artifactId: string): Set<string> {
+		const result = new Set<string>();
+		for (const member of this.members(artifactId)) {
+			if (member.type === "project") result.add(member.id);
+			else for (const projectId of this.scopeGroups.expandToProjectIds(member.id)) result.add(projectId);
+		}
+		return result;
+	}
+
 	appliesToProject(artifactId: string, projectId: string): boolean {
 		const row = this.readRow(artifactId);
-		if (!row || row.mode === "global") return true;
-		return this.membershipIds(artifactId).includes(projectId);
+		if (!row || row.mode === "all") return true;
+		if (row.mode === "none") return false;
+		return this.expandedProjectIds(artifactId).has(projectId);
 	}
 
 	appliesToProjectRoot(artifactId: string, projectRoot: string | undefined): boolean {
 		const row = this.readRow(artifactId);
-		if (!row || row.mode === "global") return true;
+		if (!row || row.mode === "all") return true;
+		if (row.mode === "none") return false;
 		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);
+		return project !== null && this.expandedProjectIds(artifactId).has(project.id);
+	}
+
+	referencesGroup(groupId: string): boolean {
+		return (
+			this.db.prepare("SELECT 1 FROM artifact_scope_members WHERE member_type = 'group' AND member_id = ? LIMIT 1").get(groupId) !== null
+		);
 	}
 }