@morsa/guidance-bank 0.2.0

package/dist/core/projects/createBankIterationPrompt.js

@@ -0,0 +1,294 @@
+import { CREATE_FLOW_COMPLETED_ITERATION, requiresCreateFlowStepOutcome } from "./createFlowPhases.js";
+import { renderCreateDeriveGuidance } from "./createBankDeriveGuidance/index.js";
+import { formatGuidanceSourceStrategy, } from "./guidanceStrategies.js";
+const STABLE_CONTRACT_NOTE = `Use \`phase\` as the main guide for the current create step and treat \`iteration\` as diagnostic only. If \`creationPrompt\` is present, use it as the stable create-flow contract; this step prompt contains only the incremental instruction for the current phase.`;
+const renderExistingBankBaselineSection = (hasExistingProjectBank, currentBankSnapshot) => hasExistingProjectBank
+    ? `## Current Bank Baseline
+
+A project AI Guidance Bank already exists for this repository. Treat the current project bank as the canonical baseline and improve it instead of recreating it blindly.
+
+- Current project bank inventory: ${currentBankSnapshot.entries.length} entr${currentBankSnapshot.entries.length === 1 ? "y" : "ies"}.
+- Reuse strong existing entries
+- Prefer updating or replacing weak entries over duplicating them
+- Remove stale or overlapping entries only when there is clear evidence and the user approves destructive changes
+- Use \`list_entries\` and \`read_entry\` with \`scope: "project"\` and the current \`projectPath\` when you need the full text of an existing project-bank entry
+`
+    : "";
+const buildContinuationOutcomeInstruction = (iteration) => {
+    if (!requiresCreateFlowStepOutcome(iteration)) {
+        return "";
+    }
+    const baseInstruction = " Also provide an explicit result for this content phase: use `create_bank.apply` for changes or set `stepOutcome` to `applied` or `no_changes`.";
+    if (iteration === 3) {
+        return `${baseInstruction} If you use \`no_changes\`, use \`stepOutcomeNote\` to name the strongest remaining candidates you reviewed and why they were skipped.`;
+    }
+    if (iteration === 4) {
+        return `${baseInstruction} If you use \`no_changes\`, use \`stepOutcomeNote\` to summarize the strongest skipped or already-covered candidates and why the bank is complete enough.`;
+    }
+    return `${baseInstruction} If you use \`no_changes\`, include \`stepOutcomeNote\`.`;
+};
+const appendContinuationInstruction = (prompt, iteration) => {
+    const continuationSuffix = buildContinuationOutcomeInstruction(iteration);
+    return `${prompt}
+
+## Continuation
+
+After completing this step, call \`create_bank\` again with \`iteration: ${iteration + 1}\` and \`stepCompleted: true\`.${continuationSuffix}`;
+};
+const renderDiscoveredSourcesSection = (discoveredSources) => {
+    if (discoveredSources.length === 0) {
+        return `## Discovered Guidance Sources
+
+No repository-local or provider-project guidance sources were discovered for this project.`;
+    }
+    return `## Discovered Guidance Sources
+
+${discoveredSources
+        .map((source) => `- [${source.kind}${source.scope === "provider-project" && source.provider ? `/${source.provider}` : ""}] ${source.relativePath} (${source.entryType}, ${source.scope})`)
+        .join("\n")}`;
+};
+const renderConfirmedSourceStrategiesSection = (confirmedSourceStrategies) => {
+    if (confirmedSourceStrategies.length === 0) {
+        return `## Confirmed Source Decisions
+
+No confirmed source decisions are stored yet for this flow.`;
+    }
+    return `## Confirmed Source Decisions
+
+${confirmedSourceStrategies
+        .map((strategy) => `- ${strategy.sourceRef} -> ${formatGuidanceSourceStrategy(strategy.strategy)}${strategy.note ? ` (${strategy.note})` : ""}`)
+        .join("\n")}`;
+};
+const renderDetectedStacksSection = (detectedStacks) => detectedStacks.length === 0
+    ? `## Detected Stacks
+
+- other`
+    : `## Detected Stacks
+
+${detectedStacks.map((stack) => `- ${stack}`).join("\n")}`;
+const renderReferenceProjectsSection = (selectedReferenceProjects) => {
+    if (selectedReferenceProjects.length === 0) {
+        return `## Reference Projects
+
+No reference project banks were selected for this run.`;
+    }
+    return `## Reference Projects
+
+${selectedReferenceProjects
+        .map((project) => `- ${project.projectName}
+  - Project path: \`${project.projectPath}\`
+  - Shared stacks: ${project.sharedStacks.join(", ")}`)
+        .join("\n")}`;
+};
+const buildKickoffPrompt = ({ projectName, projectPath, projectBankPath, rulesDirectory, skillsDirectory, detectedStacks, selectedReferenceProjects, }) => `# Create Flow Kickoff
+
+${STABLE_CONTRACT_NOTE}
+
+Project:
+- \`${projectName}\`
+- \`${projectPath}\`
+
+Target AI Guidance Bank:
+- \`${projectBankPath}\`
+- Rules: \`${rulesDirectory}\`
+- Skills: \`${skillsDirectory}\`
+
+${renderDetectedStacksSection(detectedStacks)}
+
+${renderReferenceProjectsSection(selectedReferenceProjects)}
+
+What to do in this step:
+- inspect the repository and selected reference projects
+- form a candidate list for the first high-value rules and skills
+- start writing only when the evidence is already strong
+- delay external guidance import or deletion until the dedicated review step
+- treat AI Guidance Bank as durable, reusable rules-and-skills guidance across sessions
+- do not stop at a thin summary if the repository clearly supports a richer bank
+
+Step output:
+- short list of created, updated, or planned files
+- short purpose for each item
+- strongest remaining candidates or uncertainties to handle next`;
+const buildReviewExistingPrompt = (projectPath, discoveredSources) => `# Existing Guidance Review
+
+${STABLE_CONTRACT_NOTE}
+
+Review available external guidance before importing anything into AI Guidance Bank.
+
+Project path:
+- \`${projectPath}\`
+
+${renderDiscoveredSourcesSection(discoveredSources)}
+
+What to do:
+- Treat the listed repository-local and provider-project sources as the guaranteed inputs for this review
+- Skip purely empty, obsolete, or trivial sources without bothering the user
+- By default, do not expose internal strategy labels to the user
+- Treat AI Guidance Bank as the durable canonical rules-and-skills layer for the project
+- Ask for one simple confirmation:
+  - \`ok\`: make AI Guidance Bank the canonical source for this project and migrate useful guidance by the default policy
+  - \`not ok\`: leave legacy guidance untouched and do not treat it as canonical AI Guidance Bank coverage
+- When the simple confirmation is enough, advance with \`sourceReviewDecision: "ok"\` or \`sourceReviewDecision: "not_ok"\`
+- Ask a more detailed follow-up only when deletion is risky enough that the simple confirmation is not safe
+- Keep the user-facing review short and action-oriented:
+  - start with a 1-2 sentence summary of what sources were found
+  - recommend one default action
+  - end with one explicit CTA question telling the user to answer \`ok\` or \`not ok\`
+  - avoid long protocol dumps, source-strategy labels, or repeating the same source list multiple times
+
+Decision rules:
+- Treat provider-project guidance as legacy project-specific input that usually needs review or migration
+- Never delete or rewrite any original source during this review step`;
+const buildImportSelectedPrompt = (discoveredSources, confirmedSourceStrategies) => `# Import Selected Guidance
+
+${STABLE_CONTRACT_NOTE}
+
+Apply the source-level strategies the user approved for external guidance.
+
+${renderDiscoveredSourcesSection(discoveredSources)}
+
+${renderConfirmedSourceStrategiesSection(confirmedSourceStrategies)}
+
+What to do:
+- Treat the confirmed source decisions below as the internal execution plan for this import step
+- Convert approved guidance into canonical AI Guidance Bank rules and skills
+- Keep imported content durable, operational, and reusable across future sessions
+- Split entries between project scope and shared scope when appropriate
+- Assign stable ids, titles, topics, and stacks
+- Deduplicate against existing AI Guidance Bank content before writing
+- Use \`create_bank\` with an \`apply\` payload for batched canonical writes and deletions during this flow
+- In \`create_bank.apply\`, paths must be relative to the rules/skills root only; use \`topics/example.md\` or \`adding-feature\`, not \`rules/topics/example.md\` or \`skills/adding-feature\`
+- If the user simply confirmed \`ok\`, follow the default policy: make AI Guidance Bank canonical, migrate useful file-level guidance, ignore empty or container-only sources automatically, and clean up migrated legacy files when it is safe to do so after successful writes and verification
+- If the user confirmed \`not ok\`, still migrate useful guidance into the canonical AI Guidance Bank but leave the legacy sources untouched even if that creates temporary duplication
+- When replacing or deleting an existing AI Guidance Bank entry, read it first and pass its \`sha256\` back as \`baseSha256\`
+- If \`create_bank.apply\` reports a \`conflict\`, re-read the affected entry, rebuild the full final document, and retry with the fresh \`baseSha256\`
+
+Write rules:
+- Create a \`rule\` when the source describes a stable constraint, convention, or preference
+- Create a \`skill\` when the source describes a reusable workflow or task sequence
+- Prefer a small number of high-value entries over fragmented boilerplate
+- If a source duplicates existing canonical content, update or skip instead of cloning it
+
+Safety rules:
+- Do not delete, rewrite, or trim any original source unless the confirmed review decision allows cleanup and the migration was already written and verified successfully
+- If the user did not clearly approve an action for a source, leave that source untouched
+- If one source mixes project-specific and shared material, split it across scopes instead of forcing one destination
+- Do not count provider-local or provider-global guidance as existing AI Guidance Bank coverage when deciding what still needs to be written`;
+const buildDeriveFromProjectPrompt = (projectPath, detectedStacks) => `# Derive From Project
+
+${STABLE_CONTRACT_NOTE}
+
+Derive additional AI Guidance Bank entries from the real repository.
+
+Project path:
+- \`${projectPath}\`
+
+What to do:
+- Inspect the real repository directly: project structure, entrypoints, configuration, source files, and recurring implementation patterns
+- Create a focused set of high-value project rules and skills
+- Prefer stable patterns over one-off details
+- Keep AI Guidance Bank focused on durable guidance that remains useful across future sessions
+- Put reusable cross-project guidance into shared scope only when the evidence is strong
+- Review the strongest remaining candidates before a major batch
+- Treat the bank as incomplete if obvious entries are still missing without a clear skip reason
+
+Quality rules:
+- Do not rely on a server-provided file checklist; gather your own evidence from the real repository
+- Prefer patterns confirmed by multiple files, configuration, or stable architecture boundaries
+- Skip temporary, noisy, or accidental implementation details
+- If a candidate rule is high-impact and your confidence is low, ask the user before writing it
+- Apply derived changes through \`create_bank.apply\` in batches instead of a long series of one-entry write calls
+- In \`create_bank.apply\`, keep each path relative to the rules/skills root instead of prefixing it with \`rules/\` or \`skills/\`
+- If \`create_bank.apply\` reports a \`conflict\`, re-read the affected entry, rebuild the full final document, and retry with the fresh \`baseSha256\`
+- For each obvious candidate you skip, keep a short reason: already covered, weak evidence, intentionally deferred, or better suited to shared scope
+
+${renderCreateDeriveGuidance(detectedStacks)}`;
+const buildFinalizePrompt = () => `# Finalize AI Guidance Bank
+
+${STABLE_CONTRACT_NOTE}
+
+Finish the project AI Guidance Bank creation flow.
+
+What to do:
+- Deduplicate overlapping rules and skills
+- Verify scope split between shared and project entries
+- Check ids, titles, topics, and stacks for consistency
+- Keep only durable guidance that should survive across sessions; leave conversational context out
+- If confidence is low for any high-impact rule, ask the user before keeping it
+- Use \`create_bank.apply\` for the final cleanup batch when you need to replace or delete multiple entries
+- If \`create_bank.apply\` reports a \`conflict\`, re-read the affected entry, rebuild the final canonical document, and retry the cleanup batch with fresh \`baseSha256\`
+- Return a concise completion report when the bank is in a good canonical state
+- Run an explicit gap-and-coverage review before declaring the bank done
+
+Final pass checklist:
+- Remove near-duplicate entries and merge them into the clearest canonical version
+- Ensure each entry is either clearly a \`rule\` or clearly a \`skill\`
+- Ensure project overrides do not duplicate shared guidance without adding real specificity
+- Leave unresolved or low-confidence items out unless the user explicitly approves them
+- Confirm the bank is not materially poorer than the strongest project evidence from this run
+- Check the strongest applicable topic and skill candidates, then create them, merge them, or record a skip reason
+- In the final report, mention imported sources, newly derived entries, and any important skipped uncertainties or intentionally omitted candidates
+- If you finish with \`stepOutcome: "no_changes"\`, use \`stepOutcomeNote\` to summarize the strongest skipped or already-covered high-value candidates and why no further mutation was needed`;
+const buildCompletedPrompt = () => `# Create Flow Completed
+
+The iterative project AI Guidance Bank creation flow is complete.
+
+What to do:
+- Do not continue the create flow automatically
+- Re-enter the flow only if the user explicitly asks for another create pass or wants to restart parts of the review
+- Continue normal AI Guidance Bank work through the standard mutation tools when the user asks for targeted updates`;
+const CREATE_FLOW_PROMPT_BUILDERS = [
+    ({ projectName, projectPath, projectBankPath, rulesDirectory, skillsDirectory, detectedStacks, selectedReferenceProjects }) => buildKickoffPrompt({
+        projectName,
+        projectPath,
+        projectBankPath,
+        rulesDirectory,
+        skillsDirectory,
+        detectedStacks,
+        selectedReferenceProjects,
+    }),
+    ({ projectPath, discoveredSources }) => buildReviewExistingPrompt(projectPath, discoveredSources),
+    ({ discoveredSources, confirmedSourceStrategies }) => buildImportSelectedPrompt(discoveredSources, confirmedSourceStrategies),
+    ({ projectPath, detectedStacks }) => buildDeriveFromProjectPrompt(projectPath, detectedStacks),
+    () => buildFinalizePrompt(),
+    () => buildCompletedPrompt(),
+];
+export const buildReadyProjectBankPrompt = ({ updatedAt, updatedDaysAgo, }) => {
+    const updatedLine = updatedAt === null || updatedDaysAgo === null
+        ? "A project AI Guidance Bank already exists for this repository."
+        : `A project AI Guidance Bank already exists for this repository and was last updated ${updatedDaysAgo} day${updatedDaysAgo === 1 ? "" : "s"} ago (${updatedAt}).`;
+    return `# Existing Project AI Guidance Bank
+
+${updatedLine}
+
+What to do:
+- Tell the user that a project AI Guidance Bank already exists for this repository
+- Ask whether they want to improve it now instead of keeping it as-is
+- If the user wants to improve it, call \`create_bank\` again with \`iteration: 1\`
+- If the user does not want to improve it, continue normal work with the current ready bank through \`resolve_context\`
+- If you continue into later create iterations, treat the existing project bank as the canonical baseline and improve gaps, stale entries, duplicates, and weak coverage instead of recreating the bank from scratch`;
+};
+export const buildCreateBankIterationPrompt = ({ iteration, projectName, projectPath, projectBankPath, rulesDirectory, skillsDirectory, detectedStacks, selectedReferenceProjects, discoveredSources, confirmedSourceStrategies, currentBankSnapshot, hasExistingProjectBank = false, }) => {
+    const normalizedIteration = Math.min(Math.max(iteration, 0), CREATE_FLOW_COMPLETED_ITERATION);
+    const buildPrompt = CREATE_FLOW_PROMPT_BUILDERS[normalizedIteration];
+    const prompt = buildPrompt({
+        iteration,
+        projectName,
+        projectPath,
+        projectBankPath,
+        rulesDirectory,
+        skillsDirectory,
+        detectedStacks,
+        selectedReferenceProjects,
+        discoveredSources,
+        confirmedSourceStrategies,
+        currentBankSnapshot,
+        hasExistingProjectBank,
+    });
+    const promptWithBaseline = hasExistingProjectBank && normalizedIteration > 0 && normalizedIteration < CREATE_FLOW_COMPLETED_ITERATION
+        ? `${renderExistingBankBaselineSection(true, currentBankSnapshot)}\n${prompt}`
+        : prompt;
+    return normalizedIteration < CREATE_FLOW_COMPLETED_ITERATION
+        ? appendContinuationInstruction(promptWithBaseline, normalizedIteration)
+        : promptWithBaseline;
+};

package/dist/core/projects/createBankPrompt.js

@@ -0,0 +1,95 @@
+import { DETECTABLE_STACKS } from "../context/types.js";
+const renderDetectedStackSection = (detectedStacks) => {
+    if (detectedStacks.length === 1 && detectedStacks[0] === "other") {
+        return `## Detected Stack
+
+No specific stack signals were detected confidently. Use \`other\` as the fallback stack and infer only project-supported patterns from the codebase.`;
+    }
+    return `## Detected Stack
+
+${detectedStacks.map((stack) => `- ${stack}`).join("\n")}`;
+};
+const renderSupportedStackIdsSection = () => `## Supported Stack Ids
+
+Use only these canonical stack ids in AI Guidance Bank metadata:
+${DETECTABLE_STACKS.map((stack) => `- ${stack}`).join("\n")}
+
+If no specific stack fits confidently, use \`other\`.`;
+const renderReferenceProjectsSection = (selectedReferenceProjects) => {
+    if (selectedReferenceProjects.length === 0) {
+        return `## Reference Projects
+
+No reference project banks were selected for this run.`;
+    }
+    return `## Reference Projects
+
+${selectedReferenceProjects
+        .map((project) => `- ${project.projectName}
+  - Project path: \`${project.projectPath}\`
+  - Shared stacks: ${project.sharedStacks.join(", ")}`)
+        .join("\n")}`;
+};
+export const buildCreateBankPrompt = ({ projectName, projectPath, projectBankPath, rulesDirectory, skillsDirectory, detectedStacks, selectedReferenceProjects, }) => `# Project AI Guidance Bank Creation
+
+You are creating the canonical AI Guidance Bank for \`${projectName}\`.
+
+Project path:
+- \`${projectPath}\`
+
+Target AI Guidance Bank:
+- \`${projectBankPath}\`
+- Rules root: \`${rulesDirectory}\`
+- Skills root: \`${skillsDirectory}\`
+
+${renderDetectedStackSection(detectedStacks)}
+
+${renderSupportedStackIdsSection()}
+
+${renderReferenceProjectsSection(selectedReferenceProjects)}
+
+## Stable Contract
+
+- AI Guidance Bank is the canonical user-managed guidance layer for this project
+- AI Guidance Bank stores durable rules, skills, and reusable project guidance across sessions
+- Use \`phase\` as the primary guide during the create/improve flow; treat \`iteration\` as diagnostic only
+- Use real project code, shared AI Guidance Bank context, selected reference projects, and explicit user instructions as the main inputs
+- External repository-local or provider-project guidance must be reviewed explicitly in later steps before import
+- Provider-local skills, provider-global skills, and model-native instructions may help analysis, but they never count as canonical AI Guidance Bank coverage
+
+## Writing Contract
+
+- During the guided flow, prefer batched writes through \`create_bank.apply\`
+- Pass complete final documents, not partial markdown patches
+- \`create_bank.apply.path\` must be relative to the rules/skills root:
+  - rules: \`core/general.md\`, \`topics/architecture.md\`
+  - skills: \`adding-feature\`, \`task-based-reading\`
+- Do not prefix apply paths with \`rules/\` or \`skills/\`
+- When replacing or deleting an existing entry, read it first and pass \`baseSha256\`
+- If \`create_bank.apply\` reports a conflict, re-read the affected entry and retry with a fresh \`baseSha256\`
+- Reserve \`upsert_rule\`, \`upsert_skill\`, and \`delete_entry\` for targeted edits outside the full create/improve flow
+
+## Scope Rules
+
+- Put guidance in the project bank only when it reflects stable patterns from this repository or meaningfully refines shared guidance
+- Put clearly reusable cross-project guidance into the shared layer instead of the project layer
+- Only shared/project AI Guidance Bank entries and explicitly reviewed external sources count as canonical coverage
+
+## Coverage Expectations
+
+- Create a right-sized bank, not a thin summary
+- Consider both rules and skills
+- Build a candidate list before the first substantial write batch
+- If obvious candidates are skipped, keep a clear reason and reflect it later in \`stepOutcomeNote\`
+
+Expected Bank Density:
+- 2-6 focused rule files when project evidence supports them
+- 2-5 focused skills when reusable workflows are clearly present
+
+## Kickoff Expectations
+
+During the initial step:
+- inspect the repository and selected reference projects
+- build a broad candidate inventory before the first major write batch
+- do not import or delete external guidance yet; that happens in later review/import steps
+- do not stop after the first acceptable batch if the project clearly supports stronger canonical coverage
+`;

package/dist/core/projects/createFlowPhases.js

@@ -0,0 +1,28 @@
+export const CREATE_FLOW_PHASES = [
+    "sync_required",
+    "ready_to_improve",
+    "kickoff",
+    "review_existing_guidance",
+    "import_selected_guidance",
+    "derive_from_project",
+    "finalize",
+    "completed",
+];
+export const CREATE_ITERATION_PHASES = [
+    "kickoff",
+    "review_existing_guidance",
+    "import_selected_guidance",
+    "derive_from_project",
+    "finalize",
+    "completed",
+];
+export const CREATE_FLOW_COMPLETED_ITERATION = CREATE_ITERATION_PHASES.length - 1;
+const CREATE_FLOW_OUTCOME_REQUIRED_PHASES = [
+    "import_selected_guidance",
+    "derive_from_project",
+    "finalize",
+];
+export const getCreateFlowPhase = (iteration) => CREATE_ITERATION_PHASES[Math.min(Math.max(iteration, 0), CREATE_FLOW_COMPLETED_ITERATION)];
+export const getNextCreateFlowIteration = (iteration) => iteration < CREATE_FLOW_COMPLETED_ITERATION ? iteration + 1 : null;
+export const isCreateFlowComplete = (iteration) => iteration >= CREATE_FLOW_COMPLETED_ITERATION;
+export const requiresCreateFlowStepOutcome = (iteration) => CREATE_FLOW_OUTCOME_REQUIRED_PHASES.includes(getCreateFlowPhase(iteration));

package/dist/core/projects/discoverCurrentProjectBank.js

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { parseCanonicalRuleDocument, parseCanonicalSkillDocument } from "../bank/canonicalEntry.js";
+const sha256 = (content) => createHash("sha256").update(content).digest("hex");
+export const discoverCurrentProjectBank = async (repository, projectId, exists) => {
+    if (!exists) {
+        return {
+            exists: false,
+            entries: [],
+        };
+    }
+    const [ruleEntries, skillEntries] = await Promise.all([
+        repository.listLayerEntries("project", "rules", projectId),
+        repository.listLayerEntries("project", "skills", projectId),
+    ]);
+    const [ruleSnapshots, skillSnapshots] = await Promise.all([
+        Promise.all(ruleEntries.map(async ({ path }) => {
+            const content = await repository.readLayerEntry("project", "rules", path, projectId);
+            const document = parseCanonicalRuleDocument(content);
+            return {
+                kind: "rules",
+                scope: "project",
+                path,
+                id: document.frontmatter.id,
+                sha256: sha256(content),
+            };
+        })),
+        Promise.all(skillEntries.map(async ({ path }) => {
+            const content = await repository.readLayerEntry("project", "skills", path, projectId);
+            const document = parseCanonicalSkillDocument(content);
+            return {
+                kind: "skills",
+                scope: "project",
+                path,
+                id: document.frontmatter.id,
+                sha256: sha256(content),
+            };
+        })),
+    ]);
+    return {
+        exists: true,
+        entries: [...ruleSnapshots, ...skillSnapshots].sort((left, right) => left.path.localeCompare(right.path)),
+    };
+};

package/dist/core/projects/discoverExistingGuidance.js

@@ -0,0 +1,99 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { discoverProviderProjectGuidance } from "./providerProjectGuidance.js";
+const fileCandidates = [
+    { kind: "agents", relativePath: "AGENTS.md" },
+    { kind: "claude-md", relativePath: "CLAUDE.md" },
+    { kind: "claude-md", relativePath: "claude.md" },
+    { kind: "copilot", relativePath: "copilot-instructions.md" },
+    { kind: "copilot", relativePath: ".github/copilot-instructions.md" },
+];
+const directoryCandidates = [
+    { kind: "cursor", relativePath: ".cursor" },
+    { kind: "claude", relativePath: ".claude" },
+    { kind: "codex", relativePath: ".codex" },
+];
+const pathExists = async (targetPath) => {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const listFilesRecursively = async (directoryPath) => {
+    const directoryEntries = await fs.readdir(directoryPath, { withFileTypes: true });
+    const filePaths = [];
+    for (const directoryEntry of directoryEntries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const entryPath = path.join(directoryPath, directoryEntry.name);
+        if (directoryEntry.isDirectory()) {
+            filePaths.push(...(await listFilesRecursively(entryPath)));
+            continue;
+        }
+        if (directoryEntry.isFile()) {
+            filePaths.push(entryPath);
+        }
+    }
+    return filePaths;
+};
+export const discoverExistingGuidance = async (projectPath) => {
+    const resolvedProjectPath = path.resolve(projectPath);
+    const discoveredSources = [];
+    for (const candidate of fileCandidates) {
+        const candidatePath = path.join(resolvedProjectPath, candidate.relativePath);
+        if (!(await pathExists(candidatePath))) {
+            continue;
+        }
+        discoveredSources.push({
+            kind: candidate.kind,
+            entryType: "file",
+            scope: "repository-local",
+            provider: null,
+            path: candidatePath,
+            relativePath: candidate.relativePath,
+        });
+    }
+    for (const candidate of directoryCandidates) {
+        const candidatePath = path.join(resolvedProjectPath, candidate.relativePath);
+        if (!(await pathExists(candidatePath))) {
+            continue;
+        }
+        discoveredSources.push({
+            kind: candidate.kind,
+            entryType: "directory",
+            scope: "repository-local",
+            provider: null,
+            path: candidatePath,
+            relativePath: candidate.relativePath,
+        });
+        const nestedFilePaths = await listFilesRecursively(candidatePath);
+        for (const nestedFilePath of nestedFilePaths) {
+            discoveredSources.push({
+                kind: candidate.kind,
+                entryType: "file",
+                scope: "repository-local",
+                provider: null,
+                path: nestedFilePath,
+                relativePath: path.relative(resolvedProjectPath, nestedFilePath),
+            });
+        }
+    }
+    const providerProjectSources = await discoverProviderProjectGuidance(resolvedProjectPath);
+    for (const source of providerProjectSources) {
+        const kind = source.provider === "codex"
+            ? "codex-project"
+            : source.provider === "cursor"
+                ? "cursor-project"
+                : "claude-project";
+        discoveredSources.push({
+            kind,
+            entryType: source.entryType,
+            scope: "provider-project",
+            provider: source.provider,
+            path: source.path,
+            relativePath: source.relativePath,
+        });
+    }
+    return discoveredSources.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+};

package/dist/core/projects/discoverProjectEvidence.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+const topLevelDirectoryCandidates = ["src", "app", "pages", "lib", "server", "packages", "scripts", "test", "tests", "docs"];
+const configFileCandidates = [
+    "package.json",
+    "tsconfig.json",
+    "tsconfig.app.json",
+    "tsconfig.base.json",
+    "angular.json",
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "eslint.config.cjs",
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "next.config.ts",
+    "next.config.js",
+    "next.config.mjs",
+];
+const rootDocCandidates = ["README.md", "README.mdx", "docs.md"];
+const pathExists = async (targetPath) => {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const listMarkdownFilesRecursively = async (directoryPath) => {
+    const directoryEntries = await fs.readdir(directoryPath, { withFileTypes: true });
+    const filePaths = [];
+    for (const directoryEntry of directoryEntries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const entryPath = path.join(directoryPath, directoryEntry.name);
+        if (directoryEntry.isDirectory()) {
+            filePaths.push(...(await listMarkdownFilesRecursively(entryPath)));
+            continue;
+        }
+        if (directoryEntry.isFile() && /\.(md|mdx)$/iu.test(directoryEntry.name)) {
+            filePaths.push(entryPath);
+        }
+    }
+    return filePaths;
+};
+export const discoverProjectEvidence = async (projectPath) => {
+    const resolvedProjectPath = path.resolve(projectPath);
+    const topLevelDirectories = [];
+    const evidenceFiles = [];
+    for (const directoryName of topLevelDirectoryCandidates) {
+        const candidatePath = path.join(resolvedProjectPath, directoryName);
+        if (await pathExists(candidatePath)) {
+            topLevelDirectories.push(directoryName);
+        }
+    }
+    for (const fileName of configFileCandidates) {
+        const candidatePath = path.join(resolvedProjectPath, fileName);
+        if (await pathExists(candidatePath)) {
+            evidenceFiles.push({
+                kind: "config",
+                relativePath: fileName,
+            });
+        }
+    }
+    for (const fileName of rootDocCandidates) {
+        const candidatePath = path.join(resolvedProjectPath, fileName);
+        if (await pathExists(candidatePath)) {
+            evidenceFiles.push({
+                kind: "doc",
+                relativePath: fileName,
+            });
+        }
+    }
+    const docsDirectoryPath = path.join(resolvedProjectPath, "docs");
+    if (await pathExists(docsDirectoryPath)) {
+        const docsFilePaths = await listMarkdownFilesRecursively(docsDirectoryPath);
+        for (const docsFilePath of docsFilePaths.slice(0, 12)) {
+            evidenceFiles.push({
+                kind: "doc",
+                relativePath: path.relative(resolvedProjectPath, docsFilePath),
+            });
+        }
+    }
+    return {
+        topLevelDirectories: topLevelDirectories.sort((left, right) => left.localeCompare(right)),
+        evidenceFiles: evidenceFiles.sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
+    };
+};

package/dist/core/projects/discoverRecentCommits.js

@@ -0,0 +1,28 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export const discoverRecentCommits = async (projectPath) => {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", projectPath, "log", "-n", "5", "--pretty=format:%h%x09%s"], {
+            cwd: projectPath,
+        });
+        return stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => {
+            const [shortHash, ...subjectParts] = line.split("\t");
+            if (!shortHash) {
+                return null;
+            }
+            return {
+                shortHash,
+                subject: subjectParts.join("\t"),
+            };
+        })
+            .filter((commit) => commit !== null && commit.subject.length > 0);
+    }
+    catch {
+        return [];
+    }
+};