@morsa/guidance-bank 0.2.0

package/dist/mcp/tools/registerResolveContextTool.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { CREATE_FLOW_PHASES } from "../../core/projects/createFlowPhases.js";
+import { resolveGuidanceBankContext } from "../../core/context/resolveContextService.js";
+import { resolveProjectIdentity } from "../../core/projects/identity.js";
+import { ValidationError } from "../../shared/errors.js";
+import { AbsoluteProjectPathSchema, SessionRefSchema } from "./sharedSchemas.js";
+import { writeToolAuditEvent } from "./auditUtils.js";
+const ResolveContextArgsSchema = z
+    .object({
+    projectPath: AbsoluteProjectPathSchema,
+    sessionRef: SessionRefSchema,
+})
+    .strict();
+export const registerResolveContextTool = (server, options) => {
+    server.registerTool("resolve_context", {
+        title: "Resolve AI Guidance Bank Context",
+        description: "Resolve the primary AI Guidance Bank context for the current repository. AI Guidance Bank is the durable local rules-and-skills layer for reusable project guidance. Call this at the start of work in a project, and again when the working directory changes materially.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+        inputSchema: {
+            projectPath: AbsoluteProjectPathSchema,
+            sessionRef: SessionRefSchema,
+        },
+        outputSchema: {
+            text: z.string(),
+            creationState: z.enum(["unknown", "postponed", "declined", "creating", "ready"]).optional(),
+            postponedUntil: z.string().nullable().optional(),
+            requiredAction: z.enum(["upgrade_bank", "create_bank", "continue_create_bank", "sync_bank"]).optional(),
+            recommendedAction: z.enum(["create_bank"]).optional(),
+            createFlowPhase: z.enum(CREATE_FLOW_PHASES).optional(),
+            nextIteration: z.number().int().nonnegative().optional(),
+            bankRoot: z.string().optional(),
+            sourceRoot: z.string().optional(),
+            expectedStorageVersion: z.number().int().positive().optional(),
+            storageVersion: z.number().int().positive().optional(),
+            detectedStacks: z.array(z.string()).optional(),
+            rulesCatalog: z
+                .array(z.object({
+                scope: z.enum(["shared", "project"]),
+                kind: z.literal("rules"),
+                path: z.string(),
+                title: z.string(),
+                topics: z.array(z.string()),
+                description: z.string().nullable().optional(),
+            }))
+                .optional(),
+            skillsCatalog: z
+                .array(z.object({
+                scope: z.enum(["shared", "project"]),
+                kind: z.literal("skills"),
+                path: z.string(),
+                title: z.string(),
+                topics: z.array(z.string()),
+                description: z.string().nullable().optional(),
+            }))
+                .optional(),
+            referenceProjects: z
+                .array(z.object({
+                projectId: z.string(),
+                projectName: z.string(),
+                projectPath: z.string(),
+                projectBankPath: z.string(),
+                detectedStacks: z.array(z.string()),
+                sharedStacks: z.array(z.string()),
+            }))
+                .optional(),
+        },
+    }, async (args) => {
+        const parsedArgs = ResolveContextArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid arguments for tool resolve_context: ${z.prettifyError(parsedArgs.error)}`,
+                    },
+                ],
+            };
+        }
+        try {
+            const identity = resolveProjectIdentity(parsedArgs.data.projectPath);
+            const resolvedContext = await resolveGuidanceBankContext({
+                repository: options.repository,
+                projectPath: parsedArgs.data.projectPath,
+            });
+            await writeToolAuditEvent({
+                auditLogger: options.auditLogger,
+                sessionRef: parsedArgs.data.sessionRef,
+                tool: "resolve_context",
+                action: "resolve",
+                projectId: identity.projectId,
+                projectPath: identity.projectPath,
+                details: {
+                    creationState: resolvedContext.creationState ?? null,
+                    requiredAction: resolvedContext.requiredAction ?? null,
+                    recommendedAction: resolvedContext.recommendedAction ?? null,
+                    createFlowPhase: resolvedContext.createFlowPhase ?? null,
+                },
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(resolvedContext, null, 2),
+                    },
+                ],
+                structuredContent: resolvedContext,
+            };
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: error.message,
+                        },
+                    ],
+                };
+            }
+            throw error;
+        }
+    });
+};

package/dist/mcp/tools/registerSetProjectStateTool.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { computeProjectBankPostponedUntil, createProjectBankState, updateProjectBankState, } from "../../core/bank/project.js";
+import { PROJECT_CREATION_STATES } from "../../core/bank/types.js";
+import { resolveProjectIdentity } from "../../core/projects/identity.js";
+import { AbsoluteProjectPathSchema, SessionRefSchema } from "./sharedSchemas.js";
+import { writeToolAuditEvent } from "./auditUtils.js";
+const BaseSetProjectStateArgsSchema = z
+    .object({
+    projectPath: AbsoluteProjectPathSchema,
+    sessionRef: SessionRefSchema,
+    creationState: z
+        .enum(PROJECT_CREATION_STATES)
+        .describe("Project AI Guidance Bank creation state to persist for this repository."),
+    postponeDays: z.number().int().positive().optional(),
+    postponedUntil: z.iso.datetime().optional(),
+})
+    .strict();
+const SetProjectStateArgsSchema = BaseSetProjectStateArgsSchema.superRefine((value, ctx) => {
+    if (value.postponeDays !== undefined && value.postponedUntil !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Use either postponeDays or postponedUntil, not both.",
+            path: ["postponedUntil"],
+        });
+    }
+    if (value.creationState === "postponed") {
+        return;
+    }
+    if (value.postponeDays !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "postponeDays is only valid when creationState is postponed.",
+            path: ["postponeDays"],
+        });
+    }
+    if (value.postponedUntil !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "postponedUntil is only valid when creationState is postponed.",
+            path: ["postponedUntil"],
+        });
+    }
+});
+export const registerSetProjectStateTool = (server, options) => {
+    server.registerTool("set_project_state", {
+        title: "Set Project AI Guidance Bank State",
+        description: "Persist project-level AI Guidance Bank state such as declined creation, so the agent can avoid asking the user repeatedly.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+        inputSchema: {
+            projectPath: AbsoluteProjectPathSchema,
+            sessionRef: SessionRefSchema,
+            creationState: z
+                .enum(PROJECT_CREATION_STATES)
+                .describe("Project AI Guidance Bank creation state to persist for this repository."),
+            postponeDays: z.number().int().positive().optional(),
+            postponedUntil: z.iso.datetime().optional(),
+        },
+        outputSchema: {
+            projectId: z.string(),
+            projectName: z.string(),
+            projectPath: z.string(),
+            creationState: z.enum(PROJECT_CREATION_STATES),
+            postponedUntil: z.string().nullable(),
+        },
+    }, async (args) => {
+        const parsedArgs = SetProjectStateArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid arguments for tool set_project_state: ${z.prettifyError(parsedArgs.error)}`,
+                    },
+                ],
+            };
+        }
+        const identity = resolveProjectIdentity(parsedArgs.data.projectPath);
+        const existingState = await options.repository.readProjectStateOptional(identity.projectId);
+        const now = new Date();
+        const postponedUntil = parsedArgs.data.creationState === "postponed"
+            ? (parsedArgs.data.postponedUntil ??
+                computeProjectBankPostponedUntil(now, parsedArgs.data.postponeDays))
+            : null;
+        const nextState = existingState === null
+            ? createProjectBankState(parsedArgs.data.creationState, { postponedUntil }, now)
+            : updateProjectBankState(existingState, parsedArgs.data.creationState, { postponedUntil }, now);
+        await options.repository.writeProjectState(identity.projectId, nextState);
+        await writeToolAuditEvent({
+            auditLogger: options.auditLogger,
+            sessionRef: parsedArgs.data.sessionRef,
+            tool: "set_project_state",
+            action: "set_state",
+            projectId: identity.projectId,
+            projectPath: identity.projectPath,
+            details: {
+                creationState: nextState.creationState,
+                postponedUntil: nextState.postponedUntil,
+            },
+        });
+        const payload = {
+            projectId: identity.projectId,
+            projectName: identity.projectName,
+            projectPath: identity.projectPath,
+            creationState: nextState.creationState,
+            postponedUntil: nextState.postponedUntil,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(payload, null, 2),
+                },
+            ],
+            structuredContent: payload,
+        };
+    });
+};

package/dist/mcp/tools/registerSyncBankTool.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { SyncService } from "../../core/sync/syncService.js";
+import { resolveProjectIdentity } from "../../core/projects/identity.js";
+import { ValidationError } from "../../shared/errors.js";
+import { AbsoluteProjectPathSchema, SessionRefSchema } from "./sharedSchemas.js";
+import { writeToolAuditEvent } from "./auditUtils.js";
+const SyncBankArgsSchema = z
+    .object({
+    action: z.enum(["run", "postpone"]).describe("Run an explicit sync now or postpone the sync reminder."),
+    projectPath: AbsoluteProjectPathSchema,
+    sessionRef: SessionRefSchema,
+})
+    .strict();
+export const registerSyncBankTool = (server, options) => {
+    server.registerTool("sync_bank", {
+        title: "Sync AI Guidance Bank",
+        description: "Run an explicit reconcile pass for the current project's durable AI Guidance Bank entries. Use this when the user asks to resync the bank or when import or migration flows need a fresh inventory.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+        inputSchema: {
+            action: z.enum(["run", "postpone"]).describe("Run an explicit sync now or postpone the sync reminder."),
+            projectPath: AbsoluteProjectPathSchema,
+            sessionRef: SessionRefSchema,
+        },
+        outputSchema: {
+            action: z.enum(["run", "postpone"]),
+            bankRoot: z.string(),
+            projectPath: z.string(),
+            detectedStacks: z.array(z.string()),
+            projectState: z.enum(["unknown", "postponed", "declined", "creating", "ready"]),
+            postponedUntil: z.string().nullable(),
+            projectManifestUpdated: z.boolean(),
+            validatedEntries: z.object({
+                shared: z.object({
+                    rules: z.number().int().nonnegative(),
+                    skills: z.number().int().nonnegative(),
+                }),
+                project: z.object({
+                    rules: z.number().int().nonnegative(),
+                    skills: z.number().int().nonnegative(),
+                }),
+            }),
+            externalGuidanceSources: z.array(z.object({
+                kind: z.enum(["agents", "cursor", "claude", "codex"]),
+                path: z.string(),
+            })),
+        },
+    }, async (args) => {
+        const parsedArgs = SyncBankArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid arguments for tool sync_bank: ${z.prettifyError(parsedArgs.error)}`,
+                    },
+                ],
+            };
+        }
+        try {
+            const identity = resolveProjectIdentity(parsedArgs.data.projectPath);
+            const syncService = new SyncService();
+            const result = parsedArgs.data.action === "run"
+                ? await syncService.run({
+                    bankRoot: options.repository.rootPath,
+                    projectPath: parsedArgs.data.projectPath,
+                })
+                : await syncService.postpone({
+                    bankRoot: options.repository.rootPath,
+                    projectPath: parsedArgs.data.projectPath,
+                });
+            await writeToolAuditEvent({
+                auditLogger: options.auditLogger,
+                sessionRef: parsedArgs.data.sessionRef,
+                tool: "sync_bank",
+                action: "sync",
+                projectId: identity.projectId,
+                projectPath: identity.projectPath,
+                details: {
+                    mode: parsedArgs.data.action,
+                    projectState: result.projectState,
+                    postponedUntil: result.postponedUntil,
+                },
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: error.message,
+                        },
+                    ],
+                };
+            }
+            throw error;
+        }
+    });
+};

package/dist/mcp/tools/registerUpgradeBankTool.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { UpgradeService } from "../../core/upgrade/upgradeService.js";
+import { ValidationError } from "../../shared/errors.js";
+import { SessionRefSchema } from "./sharedSchemas.js";
+import { writeToolAuditEvent } from "./auditUtils.js";
+const UpgradeBankArgsSchema = z
+    .object({
+    sessionRef: SessionRefSchema,
+})
+    .strict();
+export const registerUpgradeBankTool = (server, options) => {
+    server.registerTool("upgrade_bank", {
+        title: "Upgrade AI Guidance Bank",
+        description: "Upgrade AI Guidance Bank to the current storage version, migrate the bank root when needed, remove legacy MCP registrations, and reapply the current integrations.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+        inputSchema: {
+            sessionRef: SessionRefSchema,
+        },
+        outputSchema: {
+            status: z.enum(["upgraded", "already_current"]),
+            bankRoot: z.string(),
+            sourceRoot: z.string(),
+            migratedBankRoot: z.boolean(),
+            previousStorageVersion: z.number().int().positive(),
+            storageVersion: z.number().int().positive(),
+            enabledProviders: z.array(z.string()),
+        },
+    }, async (args) => {
+        const parsedArgs = UpgradeBankArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid arguments for tool upgrade_bank: ${z.prettifyError(parsedArgs.error)}`,
+                    },
+                ],
+            };
+        }
+        try {
+            const upgradeService = new UpgradeService();
+            const result = await upgradeService.run({
+                bankRoot: options.repository.rootPath,
+            });
+            await writeToolAuditEvent({
+                auditLogger: options.auditLogger,
+                sessionRef: parsedArgs.data.sessionRef,
+                tool: "upgrade_bank",
+                action: "upgrade",
+                projectId: "bank",
+                projectPath: result.bankRoot,
+                details: {
+                    sourceRoot: result.sourceRoot,
+                    migratedBankRoot: result.migratedBankRoot,
+                    previousStorageVersion: result.previousStorageVersion,
+                    storageVersion: result.storageVersion,
+                    enabledProviders: result.enabledProviders,
+                },
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: error.message,
+                        },
+                    ],
+                };
+            }
+            throw error;
+        }
+    });
+};

package/dist/mcp/tools/registerUpsertRuleTool.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { ENTRY_SCOPES } from "../../core/bank/types.js";
+import { AbsoluteProjectPathSchema, SessionRefSchema } from "./sharedSchemas.js";
+import { writeEntryAuditEvent } from "./auditUtils.js";
+import { buildInvalidToolArgsResult, buildStructuredToolResult, readEntryBeforeMutation, resolveScopedMutationContext, } from "./entryMutationHelpers.js";
+const UpsertRuleArgsSchema = z
+    .object({
+    scope: z.enum(ENTRY_SCOPES).describe("Write target: shared user-level rules or project-specific rules."),
+    projectPath: AbsoluteProjectPathSchema,
+    sessionRef: SessionRefSchema,
+    path: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Rule file path relative to the selected rules root, for example topics/architecture.md."),
+    content: z
+        .string()
+        .min(1)
+        .describe("Full markdown content for the thematic rule file, including canonical frontmatter."),
+})
+    .strict();
+export const registerUpsertRuleTool = (server, options) => {
+    server.registerTool("upsert_rule", {
+        title: "Create Or Update AI Guidance Bank Rule File",
+        description: "Create or update a thematic rule file in the shared or project AI Guidance Bank layer. If scope is ambiguous, the agent should ask the user before writing.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+        inputSchema: {
+            scope: z.enum(ENTRY_SCOPES).describe("Write target: shared user-level rules or project-specific rules."),
+            projectPath: AbsoluteProjectPathSchema,
+            sessionRef: SessionRefSchema,
+            path: z
+                .string()
+                .trim()
+                .min(1)
+                .describe("Rule file path relative to the selected rules root, for example topics/architecture.md."),
+            content: z
+                .string()
+                .min(1)
+                .describe("Full markdown content for the thematic rule file, including canonical frontmatter."),
+        },
+        outputSchema: {
+            status: z.enum(["created", "updated"]),
+            scope: z.enum(ENTRY_SCOPES),
+            projectId: z.string(),
+            projectName: z.string(),
+            projectPath: z.string(),
+            path: z.string(),
+            absolutePath: z.string(),
+        },
+    }, async (args) => {
+        const parsedArgs = UpsertRuleArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return buildInvalidToolArgsResult("upsert_rule", parsedArgs.error);
+        }
+        const mutationContext = await resolveScopedMutationContext({
+            repository: options.repository,
+            projectPath: parsedArgs.data.projectPath,
+            scope: parsedArgs.data.scope,
+            missingProjectMessage: "Project AI Guidance Bank does not exist yet. Call create_bank before writing project-scoped rules.",
+        });
+        if ("isError" in mutationContext) {
+            return mutationContext;
+        }
+        const { identity, projectId } = mutationContext;
+        const beforeContent = await readEntryBeforeMutation({
+            repository: options.repository,
+            scope: parsedArgs.data.scope,
+            kind: "rules",
+            path: parsedArgs.data.path,
+            ...(projectId ? { projectId } : {}),
+        });
+        const result = await options.repository.upsertRule(parsedArgs.data.scope, parsedArgs.data.path, parsedArgs.data.content, projectId);
+        await writeEntryAuditEvent({
+            auditLogger: options.auditLogger,
+            sessionRef: parsedArgs.data.sessionRef,
+            tool: "upsert_rule",
+            action: "upsert",
+            scope: parsedArgs.data.scope,
+            kind: "rules",
+            projectId: identity.projectId,
+            projectPath: identity.projectPath,
+            path: result.path,
+            beforeContent,
+            afterContent: parsedArgs.data.content,
+        });
+        const payload = {
+            status: result.status,
+            scope: parsedArgs.data.scope,
+            projectId: identity.projectId,
+            projectName: identity.projectName,
+            projectPath: identity.projectPath,
+            path: result.path,
+            absolutePath: result.absolutePath,
+        };
+        return buildStructuredToolResult(payload);
+    });
+};

package/dist/mcp/tools/registerUpsertSkillTool.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { ENTRY_SCOPES } from "../../core/bank/types.js";
+import { AbsoluteProjectPathSchema, SessionRefSchema } from "./sharedSchemas.js";
+import { writeEntryAuditEvent } from "./auditUtils.js";
+import { buildInvalidToolArgsResult, buildStructuredToolResult, readEntryBeforeMutation, resolveScopedMutationContext, } from "./entryMutationHelpers.js";
+const UpsertSkillArgsSchema = z
+    .object({
+    scope: z.enum(ENTRY_SCOPES).describe("Write target: shared user-level skills or project-specific skills."),
+    projectPath: AbsoluteProjectPathSchema,
+    sessionRef: SessionRefSchema,
+    path: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Skill folder path relative to the selected skills root, for example adding-feature or stacks/angular/adding-feature."),
+    content: z
+        .string()
+        .min(1)
+        .describe("Full markdown content for the skill SKILL.md file, including canonical frontmatter."),
+})
+    .strict();
+export const registerUpsertSkillTool = (server, options) => {
+    server.registerTool("upsert_skill", {
+        title: "Create Or Update AI Guidance Bank Skill",
+        description: "Create or update a skill folder with a single SKILL.md file in the shared or project AI Guidance Bank layer. If scope is ambiguous, the agent should ask the user before writing.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+        inputSchema: {
+            scope: z.enum(ENTRY_SCOPES).describe("Write target: shared user-level skills or project-specific skills."),
+            projectPath: AbsoluteProjectPathSchema,
+            sessionRef: SessionRefSchema,
+            path: z
+                .string()
+                .trim()
+                .min(1)
+                .describe("Skill folder path relative to the selected skills root, for example adding-feature or stacks/angular/adding-feature."),
+            content: z
+                .string()
+                .min(1)
+                .describe("Full markdown content for the skill SKILL.md file, including canonical frontmatter."),
+        },
+        outputSchema: {
+            status: z.enum(["created", "updated"]),
+            scope: z.enum(ENTRY_SCOPES),
+            projectId: z.string(),
+            projectName: z.string(),
+            projectPath: z.string(),
+            path: z.string(),
+            filePath: z.string(),
+            absolutePath: z.string(),
+        },
+    }, async (args) => {
+        const parsedArgs = UpsertSkillArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return buildInvalidToolArgsResult("upsert_skill", parsedArgs.error);
+        }
+        const mutationContext = await resolveScopedMutationContext({
+            repository: options.repository,
+            projectPath: parsedArgs.data.projectPath,
+            scope: parsedArgs.data.scope,
+            missingProjectMessage: "Project AI Guidance Bank does not exist yet. Call create_bank before writing project-scoped skills.",
+        });
+        if ("isError" in mutationContext) {
+            return mutationContext;
+        }
+        const { identity, projectId } = mutationContext;
+        const beforeContent = await readEntryBeforeMutation({
+            repository: options.repository,
+            scope: parsedArgs.data.scope,
+            kind: "skills",
+            path: parsedArgs.data.path,
+            ...(projectId ? { projectId } : {}),
+        });
+        const result = await options.repository.upsertSkill(parsedArgs.data.scope, parsedArgs.data.path, parsedArgs.data.content, projectId);
+        await writeEntryAuditEvent({
+            auditLogger: options.auditLogger,
+            sessionRef: parsedArgs.data.sessionRef,
+            tool: "upsert_skill",
+            action: "upsert",
+            scope: parsedArgs.data.scope,
+            kind: "skills",
+            projectId: identity.projectId,
+            projectPath: identity.projectPath,
+            path: result.path,
+            beforeContent,
+            afterContent: parsedArgs.data.content,
+        });
+        const payload = {
+            status: result.status,
+            scope: parsedArgs.data.scope,
+            projectId: identity.projectId,
+            projectName: identity.projectName,
+            projectPath: identity.projectPath,
+            path: result.path,
+            filePath: result.filePath,
+            absolutePath: result.absolutePath,
+        };
+        return buildStructuredToolResult(payload);
+    });
+};

package/dist/mcp/tools/sharedSchemas.js

@@ -0,0 +1,13 @@
+import path from "node:path";
+import { z } from "zod";
+export const AbsoluteProjectPathSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .refine((value) => path.isAbsolute(value), "Project path must be absolute.")
+    .describe("Absolute path to the current repository or working directory.");
+export const SessionRefSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .describe("Required agent session reference for audit logging and traceability.");