@mcoda/core 0.1.19 → 0.1.21

package/dist/services/shared/ProjectGuidance.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { PathHelper } from "@mcoda/shared";
@@ -5,48 +6,226 @@ const QA_DOC_PATTERN = /(^|[\\/])(qa|e2e)([-_/]|$)/i;
 const MCODA_DOC_PATTERN = /(^|[\\/])\.mcoda([\\/]|$)/i;
 const SDS_DOC_PATTERN = /(^|[\\/])docs[\\/]+sds([\\/]|\.|$)/i;
 const FRONTMATTER_BLOCK = /^---[\s\S]*?\n---/;
+const SDS_NAME_PATTERN = /(^|\/)(sds(?:[-_. ][a-z0-9]+)?|software[-_ ]design(?:[-_ ](?:spec|specification|outline|doc))?|design[-_ ]spec(?:ification)?)(\/|[-_.]|$)/i;
+const SDS_PATH_HINT_PATTERN = /(^|\/)(docs\/sds|sds\/|software[-_ ]design|design[-_ ]spec|requirements|prd|pdr|rfp|architecture|solution[-_ ]design)/i;
+const REQUIRED_GUIDANCE_SECTIONS = [
+    "Product Context",
+    "Architecture Notes",
+    "Coding Constraints",
+    "Testing Policy",
+    "Operational Notes",
+];
+const PLACEHOLDER_PATTERNS = [
+    /\bdescribe the product domain\b/i,
+    /\blist important modules\b/i,
+    /\bdocument non-negotiable implementation rules\b/i,
+    /\bdefine required test levels\b/i,
+    /\badd deployment\/runtime constraints\b/i,
+];
+const FRONTMATTER_TRUE_VALUES = new Set(["true", "1", "yes", "on"]);
+const TREE_LIKE_PATTERN = /[├└│]|^\s*[./A-Za-z0-9_-]+\/\s*$/m;
+const MARKDOWN_FILE_EXTENSIONS = new Set([".md", ".mdx", ".markdown"]);
+const DIR_SCAN_EXCLUDES = new Set([
+    ".git",
+    ".svn",
+    ".hg",
+    ".mcoda",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "out",
+    "target",
+    ".next",
+    ".nuxt",
+    ".venv",
+    "venv",
+    "coverage",
+]);
 const DEFAULT_PROJECT_GUIDANCE_TEMPLATE = [
     "# Project Guidance",
     "",
-    "This file is loaded by mcoda agents before task execution.",
-    "Keep it concise and specific to this workspace.",
+    "This file is loaded by mcoda agents before task execution/review/QA.",
+    "SDS is the source of truth. Keep this guidance concrete and implementation-oriented.",
     "",
     "## Product Context",
-    "- Describe the product domain and user-facing goals.",
+    "- Align scope and implementation decisions with the latest SDS.",
+    "- Prefer product behavior changes over test-only deltas for implementation tasks.",
     "",
     "## Architecture Notes",
-    "- List important modules, boundaries, and integration points.",
+    "- Respect existing module/service boundaries and data contracts.",
+    "- Keep new interfaces and schemas backward-compatible unless SDS explicitly changes them.",
     "",
     "## Coding Constraints",
-    "- Document non-negotiable implementation rules.",
+    "- Avoid hardcoded environment-specific values (ports, hosts, secrets, file paths).",
+    "- Reuse existing code patterns and adapters before adding new abstractions.",
     "",
     "## Testing Policy",
-    "- Define required test levels and critical regression checks.",
+    "- Run targeted tests for touched behavior, then broader suites when required.",
+    "- Ensure implementation changes and tests evolve together.",
     "",
     "## Operational Notes",
-    "- Add deployment/runtime constraints, known caveats, and troubleshooting hints.",
+    "- Preserve observability and runtime configuration conventions already used by the project.",
+    "- Document notable rollout risks and mitigation in task summaries.",
     "",
 ].join("\n");
-export const getDefaultProjectGuidanceTemplate = () => DEFAULT_PROJECT_GUIDANCE_TEMPLATE;
-export const resolveWorkspaceProjectGuidancePath = (workspaceRoot, mcodaDir) => {
-    const resolvedMcodaDir = mcodaDir ?? PathHelper.getWorkspaceDir(workspaceRoot);
-    return path.join(resolvedMcodaDir, "docs", "project-guidance.md");
+const normalizePathSeparators = (value) => value.replace(/\\/g, "/");
+const dedupe = (values) => {
+    const seen = new Set();
+    const output = [];
+    for (const value of values) {
+        const normalized = normalizePathSeparators(value);
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        output.push(value);
+    }
+    return output;
 };
-const guidanceCandidates = (workspaceRoot, mcodaDir) => {
-    return [
-        resolveWorkspaceProjectGuidancePath(workspaceRoot, mcodaDir),
-        path.join(workspaceRoot, "docs", "project-guidance.md"),
-    ];
+const normalizeProjectKey = (value) => {
+    const trimmed = (value ?? "").trim();
+    if (!trimmed)
+        return undefined;
+    const normalized = trimmed
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return normalized || undefined;
 };
-export const isDocContextExcluded = (value, allowQaDocs = false) => {
-    if (!value)
-        return false;
-    const normalized = value.replace(/\\/g, "/");
-    if (MCODA_DOC_PATTERN.test(normalized))
-        return true;
-    if (!allowQaDocs && QA_DOC_PATTERN.test(normalized))
-        return true;
-    return false;
+const sha256 = (content) => createHash("sha256").update(content).digest("hex");
+const readTextFile = async (targetPath) => {
+    try {
+        return await fs.readFile(targetPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+};
+const trimSection = (value, maxLines = 10) => {
+    const lines = value
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 0)
+        return "";
+    return lines.slice(0, maxLines).join("\n");
+};
+const toBullets = (value, maxItems = 6) => {
+    const lines = value
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .filter((line) => !line.startsWith("```"));
+    const bullets = [];
+    for (const line of lines) {
+        let normalized = line.replace(/^[-*]\s+/, "").trim();
+        normalized = normalized.replace(/^\d+\.\s+/, "").trim();
+        if (!normalized)
+            continue;
+        if (normalized.length > 180)
+            normalized = `${normalized.slice(0, 177)}...`;
+        bullets.push(`- ${normalized}`);
+        if (bullets.length >= maxItems)
+            break;
+    }
+    return bullets;
+};
+const extractFencedTreeBlock = (content) => {
+    const fenceRegex = /```(?:text|md|markdown|tree)?\s*\n([\s\S]*?)\n```/gi;
+    for (const match of content.matchAll(fenceRegex)) {
+        const block = (match[1] ?? "").trim();
+        if (!block)
+            continue;
+        if (!TREE_LIKE_PATTERN.test(block))
+            continue;
+        const normalized = block.split(/\r?\n/).slice(0, 40).join("\n").trim();
+        if (normalized)
+            return normalized;
+    }
+    return undefined;
+};
+const parseHeadingSections = (content) => {
+    const lines = content.split(/\r?\n/);
+    const sections = [];
+    let currentHeading = "";
+    let currentBody = [];
+    const flush = () => {
+        if (!currentHeading)
+            return;
+        sections.push({ heading: currentHeading, body: currentBody.join("\n").trim() });
+    };
+    for (const line of lines) {
+        const match = line.match(/^\s{0,3}#{1,6}\s+(.+?)\s*$/);
+        if (match) {
+            flush();
+            currentHeading = match[1]?.trim() ?? "";
+            currentBody = [];
+            continue;
+        }
+        if (currentHeading)
+            currentBody.push(line);
+    }
+    flush();
+    return sections;
+};
+const findSectionByHeading = (sections, patterns) => {
+    for (const section of sections) {
+        const heading = section.heading.trim();
+        if (!heading)
+            continue;
+        if (patterns.some((pattern) => pattern.test(heading))) {
+            const body = trimSection(section.body, 14);
+            if (body)
+                return body;
+        }
+    }
+    return undefined;
+};
+const extractIntroParagraph = (content) => {
+    const stripped = content
+        .replace(FRONTMATTER_BLOCK, "")
+        .replace(/```[\s\S]*?```/g, "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const first = stripped.find((line) => !line.startsWith("#"));
+    if (!first)
+        return undefined;
+    if (first.length <= 200)
+        return first;
+    return `${first.slice(0, 197)}...`;
+};
+const buildGuidanceFrontmatter = (metadata) => {
+    const lines = ["---", "mcoda_guidance: true"];
+    if (metadata.projectKey)
+        lines.push(`project_key: ${metadata.projectKey}`);
+    if (metadata.sdsSource)
+        lines.push(`sds_source: ${metadata.sdsSource}`);
+    if (metadata.sdsSha256)
+        lines.push(`sds_sha256: ${metadata.sdsSha256}`);
+    if (metadata.generatedAt)
+        lines.push(`generated_at: ${metadata.generatedAt}`);
+    lines.push("---");
+    return lines.join("\n");
+};
+const parseFrontmatterPairs = (frontmatter) => {
+    const lines = frontmatter
+        .split(/\r?\n/)
+        .slice(1, -1)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const pairs = {};
+    for (const line of lines) {
+        const idx = line.indexOf(":");
+        if (idx <= 0)
+            continue;
+        const key = line.slice(0, idx).trim().toLowerCase();
+        const value = line.slice(idx + 1).trim().replace(/^["']|["']$/g, "");
+        if (!key)
+            continue;
+        pairs[key] = value;
+    }
+    return pairs;
 };
 const extractFrontmatter = (content) => {
     if (!content)
@@ -57,6 +236,25 @@ const extractFrontmatter = (content) => {
     const match = trimmed.match(FRONTMATTER_BLOCK);
     return match ? match[0] : undefined;
 };
+const parseGuidanceFrontmatter = (content) => {
+    if (!content)
+        return undefined;
+    const frontmatter = extractFrontmatter(content);
+    if (!frontmatter)
+        return undefined;
+    const pairs = parseFrontmatterPairs(frontmatter);
+    const markerValue = (pairs.mcoda_guidance ?? "").toLowerCase();
+    const mcodaGuidance = FRONTMATTER_TRUE_VALUES.has(markerValue);
+    if (!mcodaGuidance)
+        return undefined;
+    return {
+        mcodaGuidance,
+        projectKey: pairs.project_key || undefined,
+        sdsSource: pairs.sds_source || undefined,
+        sdsSha256: pairs.sds_sha256 || undefined,
+        generatedAt: pairs.generated_at || undefined,
+    };
+};
 const hasSdsFrontmatter = (content) => {
     if (!content)
         return false;
@@ -71,6 +269,260 @@ const hasSdsFrontmatter = (content) => {
         return true;
     return false;
 };
+const listMarkdownFiles = async (root, maxDepth = 5) => {
+    const output = [];
+    const walk = async (current, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries = [];
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const entryPath = path.join(current, entry.name);
+            const relative = normalizePathSeparators(path.relative(root, entryPath));
+            if (!relative)
+                continue;
+            if (entry.isDirectory()) {
+                if (DIR_SCAN_EXCLUDES.has(entry.name))
+                    continue;
+                await walk(entryPath, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const ext = path.extname(entry.name).toLowerCase();
+            if (!MARKDOWN_FILE_EXTENSIONS.has(ext))
+                continue;
+            output.push(relative);
+        }
+    };
+    await walk(root, 0);
+    return output;
+};
+const defaultSdsCandidates = (workspaceRoot, projectKey) => {
+    const slug = normalizeProjectKey(projectKey);
+    const candidates = [
+        "docs/sds.md",
+        "docs/sds/sds.md",
+        "docs/sds/index.md",
+        "docs/software-design-specification.md",
+        "sds.md",
+    ];
+    if (slug) {
+        candidates.unshift(`docs/sds/${slug}.md`);
+        candidates.unshift(`docs/${slug}-sds.md`);
+    }
+    return candidates.map((entry) => normalizePathSeparators(path.join(workspaceRoot, entry)));
+};
+const scoreSdsPath = (relativePath, projectKey) => {
+    const normalized = normalizePathSeparators(relativePath).toLowerCase();
+    const fileName = path.basename(normalized);
+    const project = normalizeProjectKey(projectKey);
+    let score = 0;
+    if (normalized === "docs/sds.md")
+        score += 120;
+    if (normalized === "docs/sds/sds.md")
+        score += 110;
+    if (normalized.startsWith("docs/sds/"))
+        score += 90;
+    if (SDS_NAME_PATTERN.test(fileName))
+        score += 40;
+    if (SDS_PATH_HINT_PATTERN.test(normalized))
+        score += 25;
+    if (project && normalized.includes(project))
+        score += 20;
+    return score;
+};
+const hasSdsContentSignals = (content, relativePath) => {
+    if (SDS_DOC_PATTERN.test(relativePath))
+        return true;
+    if (hasSdsFrontmatter(content))
+        return true;
+    if (/^\s*#\s*(software\s+design\s+specification|sds)\b/im.test(content))
+        return true;
+    if (/\bnon-functional requirements\b/i.test(content))
+        return true;
+    if (/\bfolder tree\b/i.test(content))
+        return true;
+    return false;
+};
+const findSdsContext = async (workspaceRoot, projectKey) => {
+    const preferred = defaultSdsCandidates(workspaceRoot, projectKey);
+    const docsRoot = path.join(workspaceRoot, "docs");
+    const markdownFiles = await listMarkdownFiles(docsRoot, 6).catch(() => []);
+    const fuzzyAbsolute = markdownFiles
+        .filter((file) => SDS_NAME_PATTERN.test(file) || SDS_PATH_HINT_PATTERN.test(file))
+        .map((file) => path.join(docsRoot, file));
+    const candidates = dedupe([...preferred, ...fuzzyAbsolute]);
+    let best;
+    for (const absolutePath of candidates) {
+        const content = await readTextFile(absolutePath);
+        if (!content)
+            continue;
+        const relativePath = normalizePathSeparators(path.relative(workspaceRoot, absolutePath));
+        let score = scoreSdsPath(relativePath, projectKey);
+        if (hasSdsContentSignals(content, relativePath))
+            score += 50;
+        if (score <= 0)
+            continue;
+        const context = {
+            absolutePath,
+            relativePath,
+            content,
+            hash: sha256(content),
+        };
+        if (!best || score > best.score) {
+            best = { context, score };
+        }
+    }
+    return best?.context;
+};
+const buildSdsDerivedTemplate = (sds, projectKey) => {
+    const sections = parseHeadingSections(sds.content);
+    const intro = extractIntroParagraph(sds.content);
+    const productContext = findSectionByHeading(sections, [/overview/i, /introduction/i, /scope/i, /goals?/i, /product/i]) ?? intro ?? "";
+    const architecture = findSectionByHeading(sections, [/architecture/i, /services?/i, /components?/i, /modules?/i]);
+    const constraints = findSectionByHeading(sections, [/constraints?/i, /security/i, /compliance/i, /standards?/i]);
+    const testing = findSectionByHeading(sections, [/testing/i, /\bqa\b/i, /verification/i, /validation/i]);
+    const operations = findSectionByHeading(sections, [/operations?/i, /deployment/i, /runbook/i, /observability/i, /monitoring/i]);
+    const folderSection = findSectionByHeading(sections, [/folder tree/i, /repo structure/i, /project structure/i]);
+    const treeBlock = extractFencedTreeBlock(folderSection ?? sds.content);
+    const generatedAt = new Date().toISOString();
+    const frontmatter = buildGuidanceFrontmatter({
+        projectKey: normalizeProjectKey(projectKey),
+        sdsSource: sds.relativePath,
+        sdsSha256: sds.hash,
+        generatedAt,
+    });
+    const productBullets = toBullets(productContext || `SDS source: ${sds.relativePath}`);
+    const architectureBullets = toBullets(architecture || "Follow the module and service boundaries specified in the SDS architecture section.");
+    const constraintsBullets = toBullets(constraints ||
+        "Do not add undocumented dependencies. Keep interfaces, schemas, and naming aligned with SDS and OpenAPI artifacts.");
+    const testingBullets = toBullets(testing ||
+        "For every implementation change, update tests that cover behavior and regression risk, then run the smallest relevant suite before broad test runs.");
+    const operationsBullets = toBullets(operations ||
+        "Keep runtime configuration environment-driven, avoid hardcoded ports/hosts, and preserve existing logging/telemetry conventions.");
+    const lines = [
+        frontmatter,
+        "",
+        "# Project Guidance",
+        "",
+        `This guidance is generated from SDS source \`${sds.relativePath}\` and is intended to keep implementation/review/QA aligned.`,
+        "",
+        "## Product Context",
+        ...(productBullets.length > 0 ? productBullets : [`- SDS source: ${sds.relativePath}`]),
+        "",
+        "## Architecture Notes",
+        ...(architectureBullets.length > 0
+            ? architectureBullets
+            : ["- Follow SDS-defined service boundaries and data contracts."]),
+        "",
+        "## Coding Constraints",
+        ...(constraintsBullets.length > 0
+            ? constraintsBullets
+            : ["- Match SDS/OpenAPI contracts and avoid introducing undocumented behavior."]),
+        "",
+        "## Testing Policy",
+        ...(testingBullets.length > 0 ? testingBullets : ["- Run targeted tests first, then broader suites where relevant."]),
+        "",
+        "## Operational Notes",
+        ...(operationsBullets.length > 0
+            ? operationsBullets
+            : ["- Keep runtime settings configurable and align with existing deployment/observability practices."]),
+        "",
+        "## Folder Tree Baseline",
+        treeBlock ? "```text" : `- Refer to folder tree defined in \`${sds.relativePath}\`.`,
+        ...(treeBlock ? [treeBlock, "```"] : []),
+        "",
+    ];
+    return lines.join("\n");
+};
+const validateGuidanceContent = (content) => {
+    const warnings = [];
+    for (const section of REQUIRED_GUIDANCE_SECTIONS) {
+        const matcher = new RegExp(`^##\\s+${section.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&")}\\s*$`, "im");
+        if (!matcher.test(content)) {
+            warnings.push(`missing_section:${section}`);
+        }
+    }
+    for (const placeholder of PLACEHOLDER_PATTERNS) {
+        if (placeholder.test(content)) {
+            warnings.push("placeholder_text_detected");
+            break;
+        }
+    }
+    return warnings;
+};
+const detectGuidanceStaleness = async (workspaceRoot, content) => {
+    const metadata = parseGuidanceFrontmatter(content);
+    if (!metadata) {
+        return { stale: false, warnings: [] };
+    }
+    const warnings = [];
+    if (!metadata.sdsSource || !metadata.sdsSha256) {
+        warnings.push("guidance_missing_sds_metadata");
+        return { stale: false, warnings, metadata };
+    }
+    const absoluteSource = path.isAbsolute(metadata.sdsSource)
+        ? metadata.sdsSource
+        : path.join(workspaceRoot, metadata.sdsSource);
+    const sourceContent = await readTextFile(absoluteSource);
+    if (!sourceContent) {
+        warnings.push(`guidance_sds_source_missing:${metadata.sdsSource}`);
+        return { stale: true, warnings, metadata };
+    }
+    const currentHash = sha256(sourceContent);
+    if (currentHash !== metadata.sdsSha256) {
+        warnings.push(`guidance_stale_sds_hash:${metadata.sdsSource}`);
+        return { stale: true, warnings, metadata };
+    }
+    return { stale: false, warnings, metadata };
+};
+const resolveGuidanceTemplate = async (workspaceRoot, options) => {
+    if (options.template && options.template.trim()) {
+        return { template: options.template.trim(), source: "custom" };
+    }
+    const sds = await findSdsContext(workspaceRoot, options.projectKey);
+    if (sds) {
+        return { template: buildSdsDerivedTemplate(sds, options.projectKey), source: "sds", sds };
+    }
+    return { template: getDefaultProjectGuidanceTemplate().trim(), source: "default" };
+};
+export const getDefaultProjectGuidanceTemplate = () => DEFAULT_PROJECT_GUIDANCE_TEMPLATE;
+export const resolveWorkspaceProjectGuidancePath = (workspaceRoot, mcodaDir, projectKey) => {
+    const resolvedMcodaDir = mcodaDir ?? PathHelper.getWorkspaceDir(workspaceRoot);
+    const normalizedProject = normalizeProjectKey(projectKey);
+    if (normalizedProject) {
+        return path.join(resolvedMcodaDir, "docs", "projects", normalizedProject, "project-guidance.md");
+    }
+    return path.join(resolvedMcodaDir, "docs", "project-guidance.md");
+};
+const guidanceCandidates = (workspaceRoot, mcodaDir, projectKey) => {
+    const normalizedProject = normalizeProjectKey(projectKey);
+    const repoProjectPath = normalizedProject
+        ? path.join(workspaceRoot, "docs", "projects", normalizedProject, "project-guidance.md")
+        : undefined;
+    return dedupe([
+        resolveWorkspaceProjectGuidancePath(workspaceRoot, mcodaDir, normalizedProject),
+        resolveWorkspaceProjectGuidancePath(workspaceRoot, mcodaDir),
+        repoProjectPath,
+        path.join(workspaceRoot, "docs", "project-guidance.md"),
+    ].filter((entry) => Boolean(entry)));
+};
+export const isDocContextExcluded = (value, allowQaDocs = false) => {
+    if (!value)
+        return false;
+    const normalized = value.replace(/\\/g, "/");
+    if (MCODA_DOC_PATTERN.test(normalized))
+        return true;
+    if (!allowQaDocs && QA_DOC_PATTERN.test(normalized))
+        return true;
+    return false;
+};
 export const normalizeDocType = (params) => {
     const raw = (params.docType ?? "DOC").trim();
     const normalizedType = raw ? raw.toUpperCase() : "DOC";
@@ -87,25 +539,43 @@ export const normalizeDocType = (params) => {
     const reason = [inSdsPath ? null : "path_not_sds", frontmatter ? null : "frontmatter_missing"].filter(Boolean).join("|");
     return { docType: "DOC", downgraded: true, reason: reason || "not_sds" };
 };
-export const loadProjectGuidance = async (workspaceRoot, mcodaDir) => {
-    for (const candidate of guidanceCandidates(workspaceRoot, mcodaDir)) {
+export const loadProjectGuidance = async (workspaceRoot, mcodaDir, options = {}) => {
+    const candidates = guidanceCandidates(workspaceRoot, mcodaDir, options.projectKey);
+    for (const candidate of candidates) {
         try {
             const content = (await fs.readFile(candidate, "utf8")).trim();
             if (!content)
                 continue;
-            return { content, source: candidate };
+            const validationWarnings = validateGuidanceContent(content);
+            const staleness = await detectGuidanceStaleness(workspaceRoot, content);
+            const metadata = staleness.metadata;
+            const warnings = [...validationWarnings, ...staleness.warnings];
+            return {
+                content,
+                source: candidate,
+                warnings: warnings.length > 0 ? warnings : undefined,
+                stale: staleness.stale,
+                projectKey: metadata?.projectKey,
+                sdsSource: metadata?.sdsSource,
+                sdsSha256: metadata?.sdsSha256,
+                generatedAt: metadata?.generatedAt,
+            };
         }
         catch {
             // ignore missing file
         }
     }
-    console.warn(`[project-guidance] no project guidance found; searched: ${guidanceCandidates(workspaceRoot, mcodaDir).join(", ")}`);
+    console.warn(`[project-guidance] no project guidance found; searched: ${candidates.join(", ")}`);
     return null;
 };
 export const ensureProjectGuidance = async (workspaceRoot, options = {}) => {
-    const targetPath = resolveWorkspaceProjectGuidancePath(workspaceRoot, options.mcodaDir);
+    const normalizedProject = normalizeProjectKey(options.projectKey);
+    const targetPath = resolveWorkspaceProjectGuidancePath(workspaceRoot, options.mcodaDir, normalizedProject);
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
     const force = Boolean(options.force);
+    const resolvedTemplate = await resolveGuidanceTemplate(workspaceRoot, options);
+    const template = resolvedTemplate.template.trim();
+    const payload = template.length > 0 ? `${template}\n` : "";
     let existed = false;
     try {
         await fs.access(targetPath);
@@ -118,15 +588,46 @@ export const ensureProjectGuidance = async (workspaceRoot, options = {}) => {
         try {
             const existing = (await fs.readFile(targetPath, "utf8")).trim();
             if (existing.length > 0) {
-                return { path: targetPath, status: "existing" };
+                const validationWarnings = validateGuidanceContent(existing);
+                const staleness = await detectGuidanceStaleness(workspaceRoot, existing);
+                const warnings = [...validationWarnings, ...staleness.warnings];
+                const metadata = staleness.metadata;
+                if (staleness.stale && metadata?.mcodaGuidance) {
+                    await fs.writeFile(targetPath, payload, "utf8");
+                    return {
+                        path: targetPath,
+                        status: "overwritten",
+                        warnings: warnings.length > 0 ? warnings : undefined,
+                        stale: true,
+                        source: resolvedTemplate.source,
+                        projectKey: normalizedProject,
+                        sdsSource: resolvedTemplate.sds?.relativePath,
+                        sdsSha256: resolvedTemplate.sds?.hash,
+                    };
+                }
+                return {
+                    path: targetPath,
+                    status: "existing",
+                    warnings: warnings.length > 0 ? warnings : undefined,
+                    stale: staleness.stale,
+                    source: metadata?.mcodaGuidance ? "sds" : "custom",
+                    projectKey: metadata?.projectKey,
+                    sdsSource: metadata?.sdsSource,
+                    sdsSha256: metadata?.sdsSha256,
+                };
             }
         }
         catch {
             // fall through and write template
         }
     }
-    const template = (options.template ?? getDefaultProjectGuidanceTemplate()).trim();
-    const payload = template.length > 0 ? `${template}\n` : "";
     await fs.writeFile(targetPath, payload, "utf8");
-    return { path: targetPath, status: existed ? "overwritten" : "created" };
+    return {
+        path: targetPath,
+        status: existed ? "overwritten" : "created",
+        source: resolvedTemplate.source,
+        projectKey: normalizedProject,
+        sdsSource: resolvedTemplate.sds?.relativePath,
+        sdsSha256: resolvedTemplate.sds?.hash,
+    };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/core",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Core services and APIs for the mcoda CLI.",
   "type": "module",
   "main": "dist/index.js",
@@ -32,11 +32,11 @@
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
     "yaml": "^2.4.2",
-    "@mcoda/shared": "0.1.19",
-    "@mcoda/db": "0.1.19",
-    "@mcoda/agents": "0.1.19",
-    "@mcoda/generators": "0.1.19",
-    "@mcoda/integrations": "0.1.19"
+    "@mcoda/shared": "0.1.21",
+    "@mcoda/db": "0.1.21",
+    "@mcoda/agents": "0.1.21",
+    "@mcoda/generators": "0.1.21",
+    "@mcoda/integrations": "0.1.21"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",