@danypops/papyrus 0.45.2 → 0.46.0

package/src/rules/rules-service.ts

@@ -0,0 +1,224 @@
+/**
+ * Rule domain composition logic (create/list/show/preview/transition/update/gate), split out
+ * of the former domain-services.ts into its own per-domain file alongside
+ * docs/docs-service.ts and playbook/playbook-service.ts. Shared, kind-agnostic helpers live
+ * in ../domain-service-shared.ts.
+ */
+
+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 { ArtifactStore } from "../artifact/artifact-store.ts";
+import { RULE_TEXT_HARD_LIMIT_CHARACTERS, RULE_TEXT_SOFT_TARGET_CHARACTERS } from "../constants.ts";
+import { normalizeProjectRoot } from "../domain/task-scope.ts";
+import {
+	assertLabelsBounds,
+	assertTitleBounds,
+	assignArtifactProject,
+	type ListFilter,
+	listScoped,
+	requireContentUpdateFields,
+	requireKind,
+	runTransition,
+	type TransitionTable,
+	type UpdateContentInput,
+} from "../domain-service-shared.ts";
+
+export interface CreateRuleInput {
+	title: string;
+	body?: string;
+	condition?: string;
+	action?: string;
+	severity?: "block" | "warn" | "info";
+	subtype?: string;
+	labels?: string[];
+	extra?: Record<string, unknown>;
+	templateId?: string;
+	projectRoot?: string;
+}
+
+export type RuleTransition = "enable" | "disable";
+
+const RULE_TRANSITIONS: TransitionTable<RuleTransition, string> = {
+	enable: { from: ["draft", "deprecated"], to: "active" },
+	disable: { from: ["active"], to: "deprecated" },
+};
+
+function valueAtPath(value: unknown, path: string): unknown {
+	return path
+		.split(".")
+		.reduce<unknown>(
+			(current, segment) =>
+				typeof current === "object" && current !== null && !Array.isArray(current)
+					? (current as Record<string, unknown>)[segment]
+					: undefined,
+			value,
+		);
+}
+
+function isPresent(value: unknown): boolean {
+	return value !== undefined && value !== null && value !== "";
+}
+
+function assertTemplateConformance(artifacts: ArtifactStore, rule: Artifact): void {
+	const templateId = rule.extra.templateId;
+	if (typeof templateId !== "string" || templateId.length === 0) return;
+	const template = artifacts.get(templateId);
+	if (!template) throw new Error(`rule template "${templateId}" not found`);
+	if (template.subtype !== "artifact-template" || template.extra.targetKind !== "rule") {
+		throw new Error(`artifact "${templateId}" is not a Rule artifact template`);
+	}
+	const required = Array.isArray(template.extra.completionRequired)
+		? template.extra.completionRequired.filter((field): field is string => typeof field === "string")
+		: [];
+	for (const field of required) {
+		if (!isPresent(valueAtPath(rule, field))) {
+			throw new Error(`rule does not conform to template "${templateId}": missing completion-required field "${field}"`);
+		}
+	}
+}
+
+/**
+ * A Rule's condition+action+body is injected into every relevant turn for the rule's entire
+ * lifetime -- a permanent tax on every future turn's context budget, not a one-time cost.
+ * Rejects (rather than silently truncating or merely warning) once a rule is unambiguously
+ * bloated, since a silently-truncated rule would inject different text than what its author
+ * reviewed, and a warning nobody reads is not a bound. See RULE_TEXT_HARD_LIMIT_CHARACTERS's
+ * own comment in constants.ts for the research this threshold is grounded in.
+ */
+export function ruleCombinedLength(condition: string | undefined, action: string | undefined, body: string | undefined): number {
+	return (condition ?? "").length + (action ?? "").length + (body ?? "").length;
+}
+
+/**
+ * Non-blocking counterpart to assertRuleTextWithinBounds's hard rejection: the same combined
+ * length, informational once it crosses the soft target, so a caller doesn't have to self-police
+ * with a manual character count before every rules.create/update. Returns undefined at or under
+ * the target -- the common case, not worth a field only ever seen as "undefined" on the wire.
+ */
+export function ruleCombinedLengthWarning(combinedLength: number): string | undefined {
+	if (combinedLength <= RULE_TEXT_SOFT_TARGET_CHARACTERS) return undefined;
+	return (
+		`condition+action+body is ${combinedLength} characters, over the ${RULE_TEXT_SOFT_TARGET_CHARACTERS}-character soft target ` +
+		`(hard limit ${RULE_TEXT_HARD_LIMIT_CHARACTERS}) -- consider moving detail into a linked Doc.`
+	);
+}
+
+function assertRuleTextWithinBounds(condition: string | undefined, action: string | undefined, body: string | undefined): void {
+	const combined = ruleCombinedLength(condition, action, body);
+	if (combined > RULE_TEXT_HARD_LIMIT_CHARACTERS) {
+		throw new Error(
+			`rule condition+action+body is ${combined} characters, exceeding the ${RULE_TEXT_HARD_LIMIT_CHARACTERS}-character bound. ` +
+				"A Rule is injected into every relevant turn for its entire lifetime -- this is a permanent context-budget tax, not a one-time cost. " +
+				"Split it: keep a short Rule (the condition and the invariant itself), and move the full reasoning, examples, and research into a linked Doc.",
+		);
+	}
+}
+
+export function createRule(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	input: CreateRuleInput,
+	context?: ArtifactEventContext,
+): Artifact {
+	assertRuleTextWithinBounds(input.condition, input.action, input.body);
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const rule = artifacts.create(
+		{
+			kind: "rule",
+			status: input.templateId === undefined ? "active" : "draft",
+			title: input.title,
+			body: input.body,
+			subtype: input.subtype,
+			labels: input.labels,
+			extra: {
+				...(input.extra ?? {}),
+				...(input.condition ? { condition: input.condition } : {}),
+				...(input.action ? { action: input.action } : {}),
+				severity: input.severity ?? "info",
+				...(input.templateId === undefined ? {} : { templateId: input.templateId }),
+			},
+			templateId: input.templateId,
+		},
+		context,
+	);
+	scopes.assign(rule.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return rule;
+}
+
+export function listRules(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
+	return listScoped(artifacts, scopes, "rule", filter);
+}
+
+export function assignRuleProject(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	id: string,
+	projectRoot: string | undefined,
+): Artifact {
+	return assignArtifactProject(artifacts, scopes, id, "rule", projectRoot);
+}
+
+/**
+ * Global rules always apply; scoped workflow-run rules apply only while their run owns active
+ * focus. Both a workflow-definition target's own run scope ("skill-run", written by
+ * workflow-execution.ts's runWorkflowSteps for that target kind) and a Playbook's own run scope
+ * ("playbook-run", same call for a Playbook target) are recognized -- confirmed live that only
+ * "skill-run" was ever checked here, silently breaking Playbook-run-scoped rule injection since
+ * Playbook gained its own doc/rule structured steps.
+ */
+export function listInjectableRules(artifacts: ArtifactStore, activeTaskId?: string): Artifact[] {
+	return artifacts.query({ kind: "rule", status: "active" }).filter((rule) => {
+		if (rule.subtype === "artifact-template") return false;
+		const scope = rule.extra.scope;
+		if (scope === undefined) return true;
+		if (typeof scope !== "object" || scope === null || Array.isArray(scope)) return false;
+		const value = scope as Record<string, unknown>;
+		if ((value.type !== "skill-run" && value.type !== "playbook-run") || !Array.isArray(value.taskIds)) return false;
+		return activeTaskId !== undefined && value.taskIds.some((id) => id === activeTaskId);
+	});
+}
+
+export function showRule(artifacts: ArtifactStore, id: string): Artifact {
+	requireKind(artifacts, id, "rule");
+	return artifacts.get(id, { tree: true })!;
+}
+
+export function previewRule(artifacts: ArtifactStore, id: string): string {
+	const rule = requireKind(artifacts, id, "rule");
+	const condition = typeof rule.extra.condition === "string" ? ` (when: ${rule.extra.condition})` : "";
+	const action = rule.body || (typeof rule.extra.action === "string" ? rule.extra.action : "");
+	return `• ${rule.title}${condition}\n  ${action}`;
+}
+
+export function transitionRule(artifacts: ArtifactStore, id: string, action: RuleTransition, context?: ArtifactEventContext): Artifact {
+	const rule = requireLocallyOwnedContent(requireKind(artifacts, id, "rule"));
+	if (action === "enable" && (rule.status === "draft" || rule.status === "deprecated")) assertTemplateConformance(artifacts, rule);
+	return runTransition(artifacts, rule, "rule", action, RULE_TRANSITIONS, context);
+}
+
+export type UpdateRuleInput = UpdateContentInput;
+
+/** A Rule's body update stays under the same combined condition+action+body ceiling as creation -- a permanent per-turn injection cost doesn't get looser just because it's an edit, not a create. */
+export function updateRule(artifacts: ArtifactStore, id: string, input: UpdateRuleInput, context?: ArtifactEventContext): Artifact {
+	requireContentUpdateFields(input);
+	assertTitleBounds(input.title);
+	assertLabelsBounds(input.labels);
+	const rule = requireLocallyOwnedContent(requireKind(artifacts, id, "rule"));
+	if (input.body !== undefined) {
+		const condition = typeof rule.extra.condition === "string" ? rule.extra.condition : undefined;
+		const action = typeof rule.extra.action === "string" ? rule.extra.action : undefined;
+		assertRuleTextWithinBounds(condition, action, input.body);
+	}
+	const updated = artifacts.updateContent(id, input, context);
+	if (!updated) throw new Error(`rule "${id}" not found`);
+	return updated;
+}
+
+export function gateTaskWithRule(artifacts: ArtifactStore, ruleId: string, taskId: string, context?: ArtifactEventContext): Artifact {
+	requireLocallyOwnedContent(requireKind(artifacts, ruleId, "rule"));
+	requireKind(artifacts, taskId, "task");
+	artifacts.link({ from: ruleId, relation: "gates", to: taskId }, context);
+	return showRule(artifacts, ruleId);
+}

package/src/service.ts

@@ -15,7 +15,6 @@ import { migrateDb, openDb, schemaVersion } from "./db.ts";
 import { Discussions } from "./discussion/discussion-service.ts";
 import type { TaskEventContext } from "./domain/task-event.ts";
 import type { TaskViewMode } from "./domain/task-scope.ts";
-import { listInjectableRules } from "./domain-services.ts";
 import { createPapyrusVehicleRegistry } from "./handlers/registry.ts";
 import { logEvent } from "./log/log.ts";
 import { Logs } from "./log/log-service.ts";
@@ -31,6 +30,7 @@ import { RULES_OPERATION_NAMES, rulesOperations } from "./modules/rules.ts";
 import { SESSION_IDENTITY_OPERATION_NAMES, sessionIdentityOperations } from "./modules/session-identity.ts";
 import { TASKS_OPERATION_NAMES, tasksOperations } from "./modules/tasks.ts";
 import { NOTE_SUBTYPE, Notes } from "./note/note-service.ts";
+import { listInjectableRules } from "./rules/rules-service.ts";
 import { InvalidSessionSecretError, SessionIdentity } from "./session-identity/session-identity-service.ts";
 import type { GateRunner } from "./stores/gate-runner.ts";
 import { SQLiteDiscussionRoundStore } from "./stores/sqlite-discussion-round-store.ts";
@@ -39,6 +39,7 @@ import { SQLiteGraphProjectionStore } from "./stores/sqlite-graph-projection-sto
 import { SQLiteLogStore } from "./stores/sqlite-log-store.ts";
 import { SQLiteNoteEventStore } from "./stores/sqlite-note-event-store.ts";
 import { SQLiteSessionIdentityStore } from "./stores/sqlite-session-identity-store.ts";
+import { SQLiteTaskCreateRequestStore } from "./stores/sqlite-task-create-request-store.ts";
 import { SQLiteTaskEventStore } from "./stores/sqlite-task-event-store.ts";
 import { SQLiteTaskFocusStore } from "./stores/sqlite-task-focus-store.ts";
 import { SQLiteTaskLeaseStore } from "./stores/sqlite-task-lease-store.ts";
@@ -352,6 +353,9 @@ function handlers(
 		"tasks.plan": forwardToModule("tasks.plan"),
 		"tasks.show": forwardToModule("tasks.show"),
 		"tasks.history": forwardToModule("tasks.history"),
+		"tasks.projects": forwardToModule("tasks.projects"),
+		"tasks.resolve_project": forwardToModule("tasks.resolve_project"),
+		"tasks.register_project": forwardToModule("tasks.register_project"),
 		"tasks.scope": forwardToModule("tasks.scope"),
 		"tasks.set_scope": forwardToModule("tasks.set_scope"),
 		"tasks.assign_project": forwardToModule("tasks.assign_project"),
@@ -449,7 +453,8 @@ export function createPapyrusService(path: string): PapyrusService {
 	const events = new SQLiteTaskEventStore(db);
 	const scopes = new SQLiteTaskScopeStore(db);
 	const leases = new SQLiteTaskLeaseStore(db);
-	const tasks = new Tasks(artifacts, gates, focus, events, scopes, leases);
+	const createRequests = new SQLiteTaskCreateRequestStore(db);
+	const tasks = new Tasks(artifacts, gates, focus, events, scopes, leases, createRequests);
 	const noteEvents = new SQLiteNoteEventStore(db);
 	const notes = new Notes(artifacts, noteEvents);
 	const projections = new SQLiteGraphProjectionStore(db);

package/src/stores/sqlite-task-create-request-store.ts

@@ -0,0 +1,47 @@
+import type { Db } from "../db.ts";
+import type { TaskCreateRequestRecord, TaskCreateRequestStore } from "./task-create-request-store.ts";
+
+export class SQLiteTaskCreateRequestStore implements TaskCreateRequestStore {
+	constructor(private readonly db: Db) {}
+
+	get(scope: string, key: string, now: string): TaskCreateRequestRecord | undefined {
+		const row = this.db
+			.prepare(`
+				SELECT request_scope, idempotency_key, request_hash, response_json, created_at, expires_at
+				FROM task_create_requests
+				WHERE request_scope = ? AND idempotency_key = ? AND expires_at > ?
+			`)
+			.get(scope, key, now) as {
+			request_scope: string;
+			idempotency_key: string;
+			request_hash: string;
+			response_json: string;
+			created_at: string;
+			expires_at: string;
+		} | null;
+		return row
+			? {
+					scope: row.request_scope,
+					key: row.idempotency_key,
+					requestHash: row.request_hash,
+					responseJson: row.response_json,
+					createdAt: row.created_at,
+					expiresAt: row.expires_at,
+				}
+			: undefined;
+	}
+
+	put(record: TaskCreateRequestRecord): void {
+		this.db
+			.prepare(`
+				INSERT INTO task_create_requests
+					(request_scope, idempotency_key, request_hash, response_json, created_at, expires_at)
+				VALUES (?, ?, ?, ?, ?, ?)
+			`)
+			.run(record.scope, record.key, record.requestHash, record.responseJson, record.createdAt, record.expiresAt);
+	}
+
+	prune(now: string): number {
+		return this.db.prepare("DELETE FROM task_create_requests WHERE expires_at <= ?").run(now).changes;
+	}
+}

package/src/stores/sqlite-task-scope-store.ts

@@ -1,22 +1,68 @@
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import { TASK_PROJECT_ALIAS_MAX_COUNT } from "../constants.ts";
 import type { Db } from "../db.ts";
 import { inTransaction } from "../db.ts";
-import type { TaskProjectScope, TaskScopeSource, TaskViewMode, TaskViewPreference } from "../domain/task-scope.ts";
+import type {
+	RegisterTaskProjectInput,
+	TaskProject,
+	TaskProjectScope,
+	TaskScopeSource,
+	TaskViewMode,
+	TaskViewPreference,
+} from "../domain/task-scope.ts";
 import type { TaskScopeStore } from "./task-scope-store.ts";
 
+interface ProjectRow {
+	id: string;
+	name: string;
+	aliases_json: string;
+	project_root: string;
+	created_at: string;
+	updated_at: string;
+}
+
+function projectFromRow(row: ProjectRow): TaskProject {
+	return {
+		id: row.id,
+		name: row.name,
+		aliases: JSON.parse(row.aliases_json) as string[],
+		projectRoot: row.project_root,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+	};
+}
+
+function uniqueAliases(values: readonly string[], name: string): string[] {
+	const seen = new Set([name.trim().toLowerCase()]);
+	const aliases = values.flatMap((value) => {
+		const trimmed = value.trim();
+		const key = trimmed.toLowerCase();
+		if (!trimmed || seen.has(key)) return [];
+		seen.add(key);
+		return [trimmed];
+	});
+	if (aliases.length > TASK_PROJECT_ALIAS_MAX_COUNT) {
+		throw new Error(`project aliases cannot exceed ${TASK_PROJECT_ALIAS_MAX_COUNT} entries`);
+	}
+	return aliases;
+}
+
 export class SQLiteTaskScopeStore implements TaskScopeStore {
 	constructor(private readonly db: Db) {}
 
 	assign(taskId: string, projectRoot: string | undefined, source: TaskScopeSource): TaskProjectScope {
 		inTransaction(this.db, () => {
+			if (projectRoot !== undefined) this.registerProject({ projectRoot });
 			this.db
 				.prepare(`
-				INSERT INTO task_scopes (task_id, project_root, source, assigned_at)
-				VALUES (?, ?, ?, ?)
-				ON CONFLICT(task_id) DO UPDATE SET
-					project_root = excluded.project_root,
-					source = excluded.source,
-					assigned_at = excluded.assigned_at
-			`)
+					INSERT INTO task_scopes (task_id, project_root, source, assigned_at)
+					VALUES (?, ?, ?, ?)
+					ON CONFLICT(task_id) DO UPDATE SET
+						project_root = excluded.project_root,
+						source = excluded.source,
+						assigned_at = excluded.assigned_at
+				`)
 				.run(taskId, projectRoot ?? null, source, new Date().toISOString());
 		});
 		return { taskId, ...(projectRoot === undefined ? {} : { projectRoot }), source };
@@ -56,15 +102,108 @@ export class SQLiteTaskScopeStore implements TaskScopeStore {
 		inTransaction(this.db, () => {
 			this.db
 				.prepare(`
-				INSERT INTO task_views (project_root, mode, root_task_id, updated_at)
-				VALUES (?, ?, ?, ?)
-				ON CONFLICT(project_root) DO UPDATE SET
-					mode = excluded.mode,
-					root_task_id = excluded.root_task_id,
-					updated_at = excluded.updated_at
-			`)
+					INSERT INTO task_views (project_root, mode, root_task_id, updated_at)
+					VALUES (?, ?, ?, ?)
+					ON CONFLICT(project_root) DO UPDATE SET
+						mode = excluded.mode,
+						root_task_id = excluded.root_task_id,
+						updated_at = excluded.updated_at
+				`)
 				.run(projectRoot, mode, rootTaskId ?? null, new Date().toISOString());
 		});
 		return { projectRoot, mode, ...(rootTaskId === undefined ? {} : { rootTaskId }) };
 	}
+
+	projects(query: string | undefined, limit: number): TaskProject[] {
+		const needle = query?.trim().toLowerCase();
+		if (!needle) {
+			return (
+				this.db
+					.prepare(
+						"SELECT id, name, aliases_json, project_root, created_at, updated_at FROM task_projects ORDER BY name, project_root LIMIT ?",
+					)
+					.all(limit) as ProjectRow[]
+			).map(projectFromRow);
+		}
+		return (
+			this.db
+				.prepare(`
+					SELECT id, name, aliases_json, project_root, created_at, updated_at
+					FROM task_projects
+					WHERE instr(lower(name), ?) > 0
+						OR instr(lower(project_root), ?) > 0
+						OR EXISTS (
+							SELECT 1 FROM json_each(task_projects.aliases_json)
+							WHERE instr(lower(CAST(json_each.value AS TEXT)), ?) > 0
+						)
+					ORDER BY name, project_root
+					LIMIT ?
+				`)
+				.all(needle, needle, needle, limit) as ProjectRow[]
+		).map(projectFromRow);
+	}
+
+	matchingProjects(reference: string): TaskProject[] {
+		const needle = reference.trim().toLowerCase();
+		return (
+			this.db
+				.prepare(`
+					SELECT id, name, aliases_json, project_root, created_at, updated_at
+					FROM task_projects
+					WHERE lower(id) = ? OR lower(name) = ? OR lower(project_root) = ?
+						OR EXISTS (
+							SELECT 1 FROM json_each(task_projects.aliases_json)
+							WHERE lower(CAST(json_each.value AS TEXT)) = ?
+						)
+					ORDER BY name, project_root
+					LIMIT 11
+				`)
+				.all(needle, needle, needle, needle) as ProjectRow[]
+		).map(projectFromRow);
+	}
+
+	registerProject(input: RegisterTaskProjectInput): TaskProject {
+		return inTransaction(this.db, () => {
+			const row = (
+				input.existingId
+					? this.db
+							.prepare("SELECT id, name, aliases_json, project_root, created_at, updated_at FROM task_projects WHERE id = ?")
+							.get(input.existingId)
+					: this.db
+							.prepare("SELECT id, name, aliases_json, project_root, created_at, updated_at FROM task_projects WHERE project_root = ?")
+							.get(input.projectRoot)
+			) as ProjectRow | null;
+			const existing = row ? projectFromRow(row) : undefined;
+			const now = new Date().toISOString();
+			const name = input.name?.trim() || existing?.name || basename(input.projectRoot) || input.projectRoot;
+			const aliases = uniqueAliases(
+				[...(existing?.aliases ?? []), ...(existing && existing.name !== name ? [existing.name] : []), ...(input.aliases ?? [])],
+				name,
+			);
+			const project: TaskProject = {
+				id: existing?.id ?? randomUUID(),
+				name,
+				aliases,
+				projectRoot: input.projectRoot,
+				createdAt: existing?.createdAt ?? now,
+				updatedAt: now,
+			};
+			if (existing && existing.projectRoot !== project.projectRoot) {
+				this.db.prepare("UPDATE task_scopes SET project_root = ? WHERE project_root = ?").run(project.projectRoot, existing.projectRoot);
+				this.db.prepare("UPDATE task_views SET project_root = ? WHERE project_root = ?").run(project.projectRoot, existing.projectRoot);
+			}
+			this.db
+				.prepare(`
+					INSERT INTO task_projects (id, name, aliases_json, project_root, created_at, updated_at)
+					VALUES (?, ?, ?, ?, ?, ?)
+					ON CONFLICT(id) DO UPDATE SET
+						name = excluded.name,
+						aliases_json = excluded.aliases_json,
+						project_root = excluded.project_root,
+						updated_at = excluded.updated_at
+				`)
+				.run(project.id, project.name, JSON.stringify(project.aliases), project.projectRoot, project.createdAt, project.updatedAt);
+			return project;
+		});
+	}
 }

package/src/stores/task-create-request-store.ts

@@ -0,0 +1,45 @@
+export interface TaskCreateRequestRecord {
+	scope: string;
+	key: string;
+	requestHash: string;
+	responseJson: string;
+	createdAt: string;
+	expiresAt: string;
+}
+
+export interface TaskCreateRequestStore {
+	get(scope: string, key: string, now: string): TaskCreateRequestRecord | undefined;
+	put(record: TaskCreateRequestRecord): void;
+	prune(now: string): number;
+}
+
+export class TaskCreateIdempotencyConflictError extends Error {}
+
+export class InMemoryTaskCreateRequestStore implements TaskCreateRequestStore {
+	private readonly records = new Map<string, TaskCreateRequestRecord>();
+
+	private recordKey(scope: string, key: string): string {
+		return `${scope}\u0000${key}`;
+	}
+
+	get(scope: string, key: string, now: string): TaskCreateRequestRecord | undefined {
+		const record = this.records.get(this.recordKey(scope, key));
+		if (!record || record.expiresAt <= now) return undefined;
+		return record;
+	}
+
+	put(record: TaskCreateRequestRecord): void {
+		this.records.set(this.recordKey(record.scope, record.key), record);
+	}
+
+	prune(now: string): number {
+		let removed = 0;
+		for (const [key, record] of this.records) {
+			if (record.expiresAt <= now) {
+				this.records.delete(key);
+				removed += 1;
+			}
+		}
+		return removed;
+	}
+}

package/src/stores/task-scope-store.ts

@@ -1,4 +1,14 @@
-import type { TaskProjectScope, TaskScopeSource, TaskViewMode, TaskViewPreference } from "../domain/task-scope.ts";
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import { TASK_PROJECT_ALIAS_MAX_COUNT } from "../constants.ts";
+import type {
+	RegisterTaskProjectInput,
+	TaskProject,
+	TaskProjectScope,
+	TaskScopeSource,
+	TaskViewMode,
+	TaskViewPreference,
+} from "../domain/task-scope.ts";
 
 export interface TaskScopeStore {
 	assign(taskId: string, projectRoot: string | undefined, source: TaskScopeSource): TaskProjectScope;
@@ -6,15 +16,37 @@ export interface TaskScopeStore {
 	taskIds(projectRoot: string | undefined, limit: number): string[];
 	view(projectRoot: string): TaskViewPreference;
 	setView(projectRoot: string, mode: TaskViewMode, rootTaskId?: string): TaskViewPreference;
+	projects(query: string | undefined, limit: number): TaskProject[];
+	matchingProjects(reference: string): TaskProject[];
+	registerProject(input: RegisterTaskProjectInput): TaskProject;
+}
+
+function uniqueAliases(values: readonly string[], name: string): string[] {
+	const seen = new Set([name.trim().toLowerCase()]);
+	const aliases = values.flatMap((value) => {
+		const trimmed = value.trim();
+		const key = trimmed.toLowerCase();
+		if (!trimmed || seen.has(key)) return [];
+		seen.add(key);
+		return [trimmed];
+	});
+	if (aliases.length > TASK_PROJECT_ALIAS_MAX_COUNT) {
+		throw new Error(`project aliases cannot exceed ${TASK_PROJECT_ALIAS_MAX_COUNT} entries`);
+	}
+	return aliases;
 }
 
 export class InMemoryTaskScopeStore implements TaskScopeStore {
 	private readonly scopes = new Map<string, TaskProjectScope>();
 	private readonly views = new Map<string, TaskViewPreference>();
+	private readonly projectRows = new Map<string, TaskProject>();
 
 	assign(taskId: string, projectRoot: string | undefined, source: TaskScopeSource): TaskProjectScope {
 		const scope = { taskId, ...(projectRoot === undefined ? {} : { projectRoot }), source };
 		this.scopes.set(taskId, scope);
+		if (projectRoot !== undefined && ![...this.projectRows.values()].some((project) => project.projectRoot === projectRoot)) {
+			this.registerProject({ projectRoot });
+		}
 		return scope;
 	}
 
@@ -39,4 +71,62 @@ export class InMemoryTaskScopeStore implements TaskScopeStore {
 		this.views.set(projectRoot, view);
 		return view;
 	}
+
+	projects(query: string | undefined, limit: number): TaskProject[] {
+		const needle = query?.trim().toLowerCase();
+		return [...this.projectRows.values()]
+			.filter(
+				(project) =>
+					!needle ||
+					project.name.toLowerCase().includes(needle) ||
+					project.projectRoot.toLowerCase().includes(needle) ||
+					project.aliases.some((alias) => alias.toLowerCase().includes(needle)),
+			)
+			.sort((left, right) => left.name.localeCompare(right.name) || left.projectRoot.localeCompare(right.projectRoot))
+			.slice(0, limit);
+	}
+
+	matchingProjects(reference: string): TaskProject[] {
+		const needle = reference.trim().toLowerCase();
+		return [...this.projectRows.values()]
+			.filter(
+				(project) =>
+					project.id.toLowerCase() === needle ||
+					project.name.toLowerCase() === needle ||
+					project.projectRoot.toLowerCase() === needle ||
+					project.aliases.some((alias) => alias.toLowerCase() === needle),
+			)
+			.slice(0, 11);
+	}
+
+	registerProject(input: RegisterTaskProjectInput): TaskProject {
+		const now = new Date().toISOString();
+		const byRoot = [...this.projectRows.values()].find((project) => project.projectRoot === input.projectRoot);
+		const existing = input.existingId ? this.projectRows.get(input.existingId) : byRoot;
+		const name = input.name?.trim() || existing?.name || basename(input.projectRoot) || input.projectRoot;
+		const aliases = uniqueAliases(
+			[...(existing?.aliases ?? []), ...(existing && existing.name !== name ? [existing.name] : []), ...(input.aliases ?? [])],
+			name,
+		);
+		const project: TaskProject = {
+			id: existing?.id ?? randomUUID(),
+			name,
+			aliases,
+			projectRoot: input.projectRoot,
+			createdAt: existing?.createdAt ?? now,
+			updatedAt: now,
+		};
+		if (existing && existing.projectRoot !== project.projectRoot) {
+			for (const [taskId, scope] of this.scopes) {
+				if (scope.projectRoot === existing.projectRoot) this.scopes.set(taskId, { ...scope, projectRoot: project.projectRoot });
+			}
+			const view = this.views.get(existing.projectRoot);
+			if (view) {
+				this.views.delete(existing.projectRoot);
+				this.views.set(project.projectRoot, { ...view, projectRoot: project.projectRoot });
+			}
+		}
+		this.projectRows.set(project.id, project);
+		return project;
+	}
 }