@morsa/guidance-bank 0.2.0

package/dist/core/bank/layout.js

@@ -0,0 +1,159 @@
+import path from "node:path";
+export const resolveBankPaths = (root) => ({
+    root,
+    manifestFile: path.join(root, "manifest.json"),
+    auditDirectory: path.join(root, "audit"),
+    auditEventsFile: path.join(root, "audit", "events.ndjson"),
+    sharedDirectory: path.join(root, "shared"),
+    sharedRulesDirectory: path.join(root, "shared", "rules"),
+    sharedSkillsDirectory: path.join(root, "shared", "skills"),
+    projectsDirectory: path.join(root, "projects"),
+    mcpDirectory: path.join(root, "mcp"),
+    integrationsDirectory: path.join(root, "integrations"),
+    mcpServerConfigFile: path.join(root, "mcp", "server.json"),
+    integrationFile: (providerId) => path.join(root, "integrations", `${providerId}.json`),
+    projectDirectory: (projectId) => path.join(root, "projects", projectId),
+    projectManifestFile: (projectId) => path.join(root, "projects", projectId, "manifest.json"),
+    projectStateFile: (projectId) => path.join(root, "projects", projectId, "state.json"),
+    projectRulesDirectory: (projectId) => path.join(root, "projects", projectId, "rules"),
+    projectSkillsDirectory: (projectId) => path.join(root, "projects", projectId, "skills"),
+});
+export const createStarterFiles = (paths) => [
+    {
+        filePath: path.join(paths.sharedRulesDirectory, "core", "README.md"),
+        content: `# Core Rules
+
+Store shared, provider-agnostic rules here.
+
+- Use subdirectories to cluster rules by topic.
+- Keep each rule as a separate markdown file.
+`,
+    },
+    {
+        filePath: path.join(paths.sharedRulesDirectory, "core", "general.md"),
+        content: `---
+id: shared-general-behavior
+kind: rule
+title: General Behavior
+stacks: []
+topics: [general]
+---
+
+# General Behavior
+
+- Apply these rules as user-level guidance across repositories unless the local project clearly conflicts.
+- Keep changes tightly scoped and prefer existing project patterns over generic rewrites.
+- Before non-trivial work, form a short plan and validate assumptions from the real codebase.
+- Run the most relevant checks for touched areas, or state clearly why they could not be run.
+`,
+    },
+    {
+        filePath: path.join(paths.sharedRulesDirectory, "stacks", "README.md"),
+        content: `# Stack Rules
+
+Store stack-specific rules here.
+
+Examples:
+- nodejs/
+- typescript/
+- react/
+`,
+    },
+    {
+        filePath: path.join(paths.sharedRulesDirectory, "stacks", "nodejs", "runtime.md"),
+        content: `---
+id: shared-nodejs-runtime
+kind: rule
+title: Node.js Runtime
+stacks: [nodejs]
+topics: [runtime]
+---
+
+# Node.js Runtime
+
+- Respect the existing package manager and lockfile already present in the repository.
+- Prefer stable CLI scripts from package.json over ad-hoc commands when available.
+- Keep runtime and tooling changes backwards compatible unless the task explicitly requires a breaking change.
+`,
+    },
+    {
+        filePath: path.join(paths.sharedRulesDirectory, "stacks", "typescript", "strict-mode.md"),
+        content: `---
+id: shared-typescript-strict-mode
+kind: rule
+title: TypeScript Strict Mode
+stacks: [typescript]
+topics: [typing]
+---
+
+# TypeScript Strict Mode
+
+- Preserve strict typing and avoid weakening types with \`any\`, broad casts, or unchecked fallbacks.
+- Prefer narrowing and explicit domain types when changing shared interfaces or data contracts.
+- Run a typecheck after TypeScript changes when the project has a supported typecheck command.
+`,
+    },
+    {
+        filePath: path.join(paths.sharedRulesDirectory, "topics", "README.md"),
+        content: `# Topic Rules
+
+Store thematic shared rule groups here.
+
+Examples:
+- architecture/
+- styling/
+- routing/
+`,
+    },
+    {
+        filePath: path.join(paths.sharedRulesDirectory, "providers", "README.md"),
+        content: `# Provider Rules
+
+Store provider-specific rule variations here.
+
+Examples:
+- codex/
+- cursor/
+- claude-code/
+`,
+    },
+    {
+        filePath: path.join(paths.sharedSkillsDirectory, "README.md"),
+        content: `# Skills
+
+Store each skill in its own folder with a single \`SKILL.md\` file.
+
+Examples:
+- task-based-reading/SKILL.md
+- adding-feature/SKILL.md
+`,
+    },
+    {
+        filePath: path.join(paths.sharedSkillsDirectory, "shared", "task-based-reading", "SKILL.md"),
+        content: `---
+id: shared-task-based-reading
+kind: skill
+title: Task-Based Reading
+name: task-based-reading
+description: Use when starting work in an unfamiliar repository and you need to identify the minimum relevant files quickly.
+stacks: []
+topics: [reading, discovery]
+---
+
+# Task-Based Reading
+
+## When to use
+- Starting work in a new repository or feature area.
+- The task is broad and you need to reduce file-reading noise.
+
+## Workflow
+1. Read the repository README and the nearest package/config files first.
+2. Identify the feature entrypoint, then follow imports and route registration files.
+3. Read only the minimum rules and skills relevant to the current task before editing.
+
+## Do not
+- Read the entire repository before narrowing scope.
+- Infer architecture from one file when surrounding routing or config files are available.
+`,
+    },
+];

package/dist/core/bank/lifecycle.js

@@ -0,0 +1,24 @@
+export const isProjectBankPostponedUntilActive = (projectState, now = new Date()) => {
+    if (!projectState?.postponedUntil) {
+        return false;
+    }
+    return new Date(projectState.postponedUntil).getTime() > now.getTime();
+};
+export const isProjectBankSyncPostponed = (projectState, now = new Date()) => isProjectBankPostponedUntilActive(projectState, now);
+export const requiresProjectBankSync = (projectState, expectedStorageVersion) => projectState?.lastSyncedStorageVersion !== expectedStorageVersion;
+export const getProjectBankContinuationIteration = (projectState) => (projectState?.createIteration ?? 0) + 1;
+export const resolveProjectBankLifecycleStatus = ({ projectManifest, projectState, expectedStorageVersion, now = new Date(), }) => {
+    if (projectState?.creationState === "declined") {
+        return "creation_declined";
+    }
+    if (projectManifest === null) {
+        return "missing";
+    }
+    if (projectState?.creationState === "creating") {
+        return "creation_in_progress";
+    }
+    if (requiresProjectBankSync(projectState, expectedStorageVersion) && !isProjectBankPostponedUntilActive(projectState, now)) {
+        return "sync_required";
+    }
+    return "ready";
+};

package/dist/core/bank/manifest.js

@@ -0,0 +1,37 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { CURRENT_STORAGE_VERSION, PROVIDER_IDS } from "./types.js";
+const ProviderIdSchema = z.enum(PROVIDER_IDS);
+export const MemoryBankManifestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    storageVersion: z.union([z.literal(1), z.literal(2)]),
+    bankId: z.uuid(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+    enabledProviders: z.array(ProviderIdSchema),
+    defaultMcpTransport: z.literal("stdio"),
+})
+    .strict();
+const providerOrder = new Map(PROVIDER_IDS.map((providerId, index) => [providerId, index]));
+export const sortProviders = (providerIds) => [...new Set(providerIds)].sort((left, right) => (providerOrder.get(left) ?? 0) - (providerOrder.get(right) ?? 0));
+export const createManifest = (enabledProviders, now = new Date()) => {
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: 1,
+        storageVersion: CURRENT_STORAGE_VERSION,
+        bankId: randomUUID(),
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        enabledProviders: sortProviders(enabledProviders),
+        defaultMcpTransport: "stdio",
+    };
+};
+export const updateManifest = (manifest, enabledProviders, now = new Date(), options) => ({
+    ...manifest,
+    ...(options?.storageVersion ? { storageVersion: options.storageVersion } : {}),
+    updatedAt: now.toISOString(),
+    enabledProviders: sortProviders(enabledProviders),
+});
+export const parseManifest = (value) => MemoryBankManifestSchema.parse(value);
+export const isCurrentStorageVersion = (storageVersion) => storageVersion === CURRENT_STORAGE_VERSION;

package/dist/core/bank/project.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { PROJECT_CREATION_STATES, } from "./types.js";
+import { DETECTABLE_STACKS } from "../context/types.js";
+import { GUIDANCE_SOURCE_STRATEGIES } from "../projects/guidanceStrategies.js";
+const ProjectCreationStateSchema = z.enum(PROJECT_CREATION_STATES);
+const DetectableStackSchema = z.enum(DETECTABLE_STACKS);
+const GuidanceSourceStrategySchema = z.enum(GUIDANCE_SOURCE_STRATEGIES);
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const ConfirmedGuidanceSourceStrategySchema = z
+    .object({
+    sourceRef: z.string().trim().min(1),
+    strategy: GuidanceSourceStrategySchema,
+    note: z.string().trim().min(1).nullable(),
+})
+    .strict();
+export const DEFAULT_PROJECT_BANK_POSTPONE_DAYS = 1;
+export const computeProjectBankPostponedUntil = (now, postponeDays = DEFAULT_PROJECT_BANK_POSTPONE_DAYS) => new Date(now.getTime() + postponeDays * MS_PER_DAY).toISOString();
+export const ProjectBankManifestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    projectId: z.string().min(1),
+    projectName: z.string().min(1),
+    projectPath: z.string().min(1),
+    detectedStacks: z.array(DetectableStackSchema).default([]),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+})
+    .strict();
+export const ProjectBankStateSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    creationState: ProjectCreationStateSchema,
+    createIteration: z.number().int().nonnegative().nullable().default(null),
+    sourceStrategies: z.array(ConfirmedGuidanceSourceStrategySchema).default([]),
+    postponedUntil: z.iso.datetime().nullable(),
+    lastSyncedAt: z.iso.datetime().nullable(),
+    lastSyncedStorageVersion: z.number().int().positive().nullable(),
+    updatedAt: z.iso.datetime(),
+})
+    .strict();
+export const createProjectBankManifest = (projectId, projectName, projectPath, detectedStacks, now = new Date()) => {
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: 1,
+        projectId,
+        projectName,
+        projectPath,
+        detectedStacks: [...detectedStacks],
+        createdAt: timestamp,
+        updatedAt: timestamp,
+    };
+};
+export const createProjectBankState = (creationState, options, now = new Date()) => ({
+    schemaVersion: 1,
+    creationState,
+    createIteration: options?.createIteration ?? null,
+    sourceStrategies: options?.sourceStrategies ?? [],
+    postponedUntil: creationState === "postponed"
+        ? (options?.postponedUntil ?? computeProjectBankPostponedUntil(now))
+        : (options?.postponedUntil ?? null),
+    lastSyncedAt: options?.lastSyncedAt ?? null,
+    lastSyncedStorageVersion: options?.lastSyncedStorageVersion ?? null,
+    updatedAt: now.toISOString(),
+});
+export const updateProjectBankState = (state, creationState, options, now = new Date()) => ({
+    ...state,
+    creationState,
+    postponedUntil: creationState === "postponed"
+        ? (options?.postponedUntil ?? computeProjectBankPostponedUntil(now))
+        : null,
+    updatedAt: now.toISOString(),
+});
+export const setProjectBankCreateIteration = (state, createIteration, now = new Date()) => ({
+    ...state,
+    createIteration,
+    updatedAt: now.toISOString(),
+});
+export const setProjectBankSourceStrategies = (state, sourceStrategies, now = new Date()) => ({
+    ...state,
+    sourceStrategies,
+    updatedAt: now.toISOString(),
+});
+export const markProjectBankSynced = (state, storageVersion, now = new Date()) => ({
+    ...state,
+    postponedUntil: null,
+    lastSyncedAt: now.toISOString(),
+    lastSyncedStorageVersion: storageVersion,
+    updatedAt: now.toISOString(),
+});
+export const postponeProjectBankSync = (state, postponeDays, now = new Date()) => {
+    const postponedUntil = new Date(now);
+    postponedUntil.setDate(postponedUntil.getDate() + postponeDays);
+    return {
+        ...state,
+        postponedUntil: postponedUntil.toISOString(),
+        updatedAt: now.toISOString(),
+    };
+};
+export const updateProjectBankManifest = (manifest, detectedStacks, now = new Date()) => ({
+    ...manifest,
+    detectedStacks: [...detectedStacks],
+    updatedAt: now.toISOString(),
+});
+export const parseProjectBankManifest = (value) => ProjectBankManifestSchema.parse(value);
+export const parseProjectBankState = (value) => ProjectBankStateSchema.parse(value);

package/dist/core/bank/types.js

@@ -0,0 +1,6 @@
+export const PROVIDER_IDS = ["codex", "cursor", "claude-code"];
+export const STORAGE_VERSIONS = [1, 2];
+export const CURRENT_STORAGE_VERSION = 2;
+export const ENTRY_KINDS = ["rules", "skills"];
+export const ENTRY_SCOPES = ["shared", "project"];
+export const PROJECT_CREATION_STATES = ["unknown", "postponed", "declined", "creating", "ready"];

package/dist/core/context/contextEntryResolver.js

@@ -0,0 +1,140 @@
+import { parseCanonicalRuleDocument, parseCanonicalSkillDocument } from "../bank/canonicalEntry.js";
+import { ValidationError } from "../../shared/errors.js";
+const normalizeCatalogEntryPath = (kind, layer, entryPath) => {
+    if (kind !== "skills") {
+        return entryPath;
+    }
+    const normalizedEntryPath = entryPath.replaceAll("\\", "/");
+    const scopePrefix = `${layer}/`;
+    return normalizedEntryPath.startsWith(scopePrefix)
+        ? normalizedEntryPath.slice(scopePrefix.length)
+        : normalizedEntryPath;
+};
+const isDocumentationFile = (entryPath) => {
+    const normalizedEntryPath = entryPath.replaceAll("\\", "/").toLowerCase();
+    return normalizedEntryPath.endsWith("/readme.md") || normalizedEntryPath === "readme.md";
+};
+const matchesStacks = (entryStacks, detectedStacks) => {
+    if (entryStacks.length === 0) {
+        return {
+            selected: true,
+            reason: "Always-on canonical entry.",
+        };
+    }
+    for (const stack of entryStacks) {
+        if (detectedStacks.includes(stack)) {
+            return {
+                selected: true,
+                reason: `Matches canonical stack metadata: ${stack}.`,
+            };
+        }
+    }
+    return {
+        selected: false,
+        reason: "",
+    };
+};
+const parseRuleEntry = (layer, entryPath, content) => {
+    try {
+        return parseCanonicalRuleDocument(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown canonical rule parsing error.";
+        throw new ValidationError(`Invalid canonical rule at ${layer}/${entryPath}: ${message}`);
+    }
+};
+const parseSkillEntry = (layer, entryPath, content) => {
+    try {
+        return parseCanonicalSkillDocument(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown canonical skill parsing error.";
+        throw new ValidationError(`Invalid canonical skill at ${layer}/${entryPath}: ${message}`);
+    }
+};
+export const loadResolvedContextEntries = async (repository, layer, kind, detectedStacks, projectId) => {
+    const entries = await repository.listLayerEntries(layer, kind, projectId);
+    const selectedEntries = [];
+    for (const entry of entries) {
+        if (isDocumentationFile(entry.path)) {
+            continue;
+        }
+        const content = await repository.readLayerEntry(layer, kind, entry.path, projectId);
+        const metadata = kind === "rules"
+            ? parseRuleEntry(layer, entry.path, content).frontmatter
+            : parseSkillEntry(layer, entry.path, content).frontmatter;
+        const selection = matchesStacks(metadata.stacks, detectedStacks);
+        if (!selection.selected) {
+            continue;
+        }
+        selectedEntries.push({
+            layer,
+            path: entry.path,
+            reason: selection.reason,
+            content,
+            metadata,
+        });
+    }
+    return selectedEntries;
+};
+export const assertUniqueResolvedEntryIds = (entries, layer, kind) => {
+    const pathsById = new Map();
+    for (const entry of entries) {
+        const existingPaths = pathsById.get(entry.metadata.id) ?? [];
+        existingPaths.push(entry.path);
+        pathsById.set(entry.metadata.id, existingPaths);
+    }
+    for (const [entryId, entryPaths] of pathsById) {
+        if (entryPaths.length > 1) {
+            throw new ValidationError(`Duplicate canonical ${kind.slice(0, -1)} id "${entryId}" in ${layer} layer: ${entryPaths.join(", ")}`);
+        }
+    }
+};
+export const mergeResolvedLayerEntries = (sharedEntries, projectEntries) => {
+    const mergedEntries = new Map();
+    for (const entry of sharedEntries) {
+        mergedEntries.set(entry.metadata.id, entry);
+    }
+    for (const entry of projectEntries) {
+        mergedEntries.set(entry.metadata.id, entry);
+    }
+    return [...mergedEntries.values()].sort((left, right) => {
+        const titleComparison = left.metadata.title.localeCompare(right.metadata.title);
+        if (titleComparison !== 0) {
+            return titleComparison;
+        }
+        return left.path.localeCompare(right.path);
+    });
+};
+const stripFrontmatter = (content) => content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/u, "");
+const toPreview = (content) => {
+    const body = stripFrontmatter(content);
+    const lines = body
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"));
+    const previewSource = lines[0] ?? null;
+    if (previewSource === null) {
+        return null;
+    }
+    return previewSource.length > 180 ? `${previewSource.slice(0, 177)}...` : previewSource;
+};
+export const selectAlwaysOnRules = (entries) => entries
+    .filter((entry) => entry.metadata.kind === "rule" && entry.metadata.stacks.length === 0)
+    .map((entry) => ({
+    scope: entry.layer,
+    path: entry.path,
+    id: entry.metadata.id,
+    title: entry.metadata.title,
+    topics: [...entry.metadata.topics],
+    content: entry.content,
+}));
+export const excludeAlwaysOnRules = (entries) => entries.filter((entry) => !(entry.metadata.kind === "rule" && entry.metadata.stacks.length === 0));
+export const buildResolvedContextCatalog = (kind, entries) => entries.map((entry) => ({
+    scope: entry.layer,
+    kind,
+    path: normalizeCatalogEntryPath(kind, entry.layer, entry.path),
+    title: entry.metadata.title,
+    topics: [...entry.metadata.topics],
+    description: entry.metadata.kind === "skill" ? entry.metadata.description : toPreview(entry.content),
+}));

package/dist/core/context/contextTextRenderer.js

@@ -0,0 +1,116 @@
+import { DEFAULT_PROJECT_BANK_POSTPONE_DAYS } from "../bank/project.js";
+const renderPostponeDays = (days) => `${days} day${days === 1 ? "" : "s"}`;
+const renderScopedEntryPath = (scope, entryPath) => entryPath.startsWith(`${scope}/`) ? entryPath : `${scope}/${entryPath}`;
+const renderAlwaysOnRules = (rules) => {
+    if (rules.length === 0) {
+        return `## Always-On Rules
+
+No always-on rules matched for this repository.`;
+    }
+    const blocks = rules.map((rule) => `### ${renderScopedEntryPath(rule.scope, rule.path)}
+
+${rule.content.trim()}`);
+    return `## Always-On Rules
+
+${blocks.join("\n\n")}`;
+};
+const renderCatalogSummary = (title, entries) => {
+    if (entries.length === 0) {
+        return `- ${title}: none matched.`;
+    }
+    const previewPaths = entries.slice(0, 3).map((entry) => renderScopedEntryPath(entry.scope, entry.path));
+    const previewSuffix = entries.length > 3 ? `, +${entries.length - 3} more` : "";
+    return `- ${title}: ${entries.length} entries. Examples: ${previewPaths.join(", ")}${previewSuffix}.`;
+};
+const renderReferenceProjects = (projectPaths) => projectPaths.map((projectPath, index) => `${index + 1}. ${projectPath}`).join("\n");
+export const buildReadyContextText = ({ projectPath, detectedStacks, alwaysOnRules, rulesCatalog, skillsCatalog, }) => {
+    const detectedStacksLine = detectedStacks.length > 0
+        ? `Detected stack signals: ${detectedStacks.join(", ")}.`
+        : "No stable stack signals were detected automatically.";
+    return `Use the following AI Guidance Bank context catalog as the primary user-managed context and guidance layer for this repository.
+
+Repository: ${projectPath}
+${detectedStacksLine}
+
+AI Guidance Bank stores durable rules, skills, and reusable project guidance for this repository.
+
+Always-on rules are expanded inline below. Other canonical entries are listed in the structured rule and skill catalogs; call \`read_entry\` when you need the full canonical document.
+
+${renderAlwaysOnRules(alwaysOnRules)}
+
+## Catalog Summary
+
+${renderCatalogSummary("Rules", rulesCatalog)}
+${renderCatalogSummary("Skills", skillsCatalog)}`;
+};
+export const buildUpgradeRequiredContextText = ({ bankRoot, sourceRoot, storageVersion, expectedStorageVersion, }) => `AI Guidance Bank update is required before resolving repository context.
+
+Current AI Guidance Bank source:
+- \`${sourceRoot}\`
+
+Target AI Guidance Bank root:
+- \`${bankRoot}\`
+
+Storage version:
+- current: ${storageVersion}
+- expected: ${expectedStorageVersion}
+
+What to do:
+- Ask the user whether to update AI Guidance Bank now
+- If the user agrees, call \`upgrade_bank\`
+- After the upgrade finishes, call \`resolve_context\` again
+- Do not start project-bank creation, sync, or normal repository-context work until the bank-level update is complete`;
+export const buildSharedFallbackContextText = ({ projectPath, detectedStacks, alwaysOnRules, rulesCatalog, skillsCatalog, }) => {
+    const detectedStacksLine = detectedStacks.length > 0
+        ? `Detected stack signals: ${detectedStacks.join(", ")}.`
+        : "No stable stack signals were detected automatically.";
+    return `Shared AI Guidance Bank context is available even though this repository does not have a project-specific bank yet.
+
+Repository: ${projectPath}
+${detectedStacksLine}
+
+These entries come from the shared layer only. Project-specific entries will appear after a project bank is created.
+
+AI Guidance Bank stores durable rules, skills, and reusable shared guidance.
+
+${renderAlwaysOnRules(alwaysOnRules)}
+
+## Catalog Summary
+
+${renderCatalogSummary("Rules", rulesCatalog)}
+${renderCatalogSummary("Skills", skillsCatalog)}`;
+};
+export const buildMissingContextText = ({ referenceProjectPaths, creationState, postponedUntil, sharedContextText, }) => {
+    const referenceSection = referenceProjectPaths.length > 0
+        ? `\n\nBefore creating a new project AI Guidance Bank, offer these existing project banks as optional reference bases:\n${renderReferenceProjects(referenceProjectPaths)}`
+        : "";
+    const userInteractionSection = creationState === "postponed"
+        ? `No project AI Guidance Bank exists for this repository yet, and AI Guidance Bank creation was previously postponed until ${postponedUntil}. Continue the current task normally and do not ask again about project-bank creation until that time has passed. If the user explicitly asks for AI Guidance Bank setup or project-bank editing before then, call \`create_bank\`.`
+        : `No project AI Guidance Bank exists for this repository yet. Continue the current task normally, but in every useful final response append one short explicit closing question about project-bank creation until the user chooses one of these outcomes: create now, postpone, or decline. Use this question shape: "Create the project AI Guidance Bank now, or postpone the question for ${renderPostponeDays(DEFAULT_PROJECT_BANK_POSTPONE_DAYS)} or longer?" If the user wants to postpone but does not give a duration, store a ${renderPostponeDays(DEFAULT_PROJECT_BANK_POSTPONE_DAYS)} postponement by calling \`set_project_state\` with \`creationState: "postponed"\`.`;
+    const sharedSection = sharedContextText ? `\n\n${sharedContextText}` : "";
+    return `${userInteractionSection}${referenceSection}${sharedSection}
+
+Internal next steps after the user answers:
+- If the user wants to create it, call \`create_bank\`.
+- If the user wants to postpone the question for later, record that choice with \`set_project_state\` using \`creationState: "postponed"\` and include either \`postponeDays\` or \`postponedUntil\`. If the user gives no duration, default to ${renderPostponeDays(DEFAULT_PROJECT_BANK_POSTPONE_DAYS)}.
+- If the user does not want to be asked again, record that choice with \`set_project_state\` using \`creationState: "declined"\`.
+- After the user decision is recorded, call \`resolve_context\` again.`;
+};
+export const buildCreatingContextText = ({ phase, nextIteration, }) => `Continue the create flow at phase \`${phase}\`. Use \`phase\` as the primary guide, treat \`iteration\` as diagnostic only, and prefer \`create_bank.apply\` for batched writes inside the guided flow. Call \`create_bank\` with \`iteration: ${nextIteration}\` and \`stepCompleted: true\` after the current step is actually complete.`;
+export const buildDeclinedContextText = () => "Project AI Guidance Bank creation was previously declined for this repository. Do not ask again unless the user explicitly requests AI Guidance Bank creation. If the user later wants to create it, call `create_bank` and then call `resolve_context` again.";
+export const buildSyncRequiredContextText = ({ postponedUntil, }) => {
+    const postponeLine = postponedUntil
+        ? `A previous sync was postponed until ${postponedUntil}, but that deferral has now expired.`
+        : "This project AI Guidance Bank has not been synced to the current AI Guidance Bank storage version yet.";
+    return `Project AI Guidance Bank synchronization is required before using the project-specific bank.
+
+${postponeLine}
+
+Sync only reconciles the existing project bank with the current AI Guidance Bank storage version. It does not create a new bank and does not replace the normal create or improve flow.
+
+Ask the user whether to synchronize the project AI Guidance Bank now or postpone it.
+- If the user wants to sync now, call \`sync_bank\` with \`action: "run"\`.
+- If the user wants to postpone, call \`sync_bank\` with \`action: "postpone"\`.
+- After that, call \`resolve_context\` again.
+- If the user later wants to create or improve project-specific content, continue with \`create_bank\` after synchronization is no longer required.`;
+};