@flancer32/skill-adsm-ctx 0.2.1

package/src/Validate/Service.mjs

@@ -0,0 +1,879 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Validate_Service
+ * @description Validates baseline ADSM context structure, metadata, and documentation projection shape.
+ */
+
+const REQUIRED_SKIN_SECTIONS = Object.freeze([
+  "Purpose",
+  "Mental Model",
+  "Scope",
+  "Invariants",
+  "Agent Document",
+]);
+
+const LINK_PATTERN = /\[[^\]]+\]\(([^)]+)\)/g;
+const EXPLICIT_SKIN_FILENAME = /^(.*)\.skin\.([a-z]{2}(?:-[A-Za-z0-9]+)?)\.md$/;
+const LEGACY_SKIN_FILENAME = /^(.*)\.skin\.md$/;
+const MALFORMED_SKIN_FILENAME = /^(.*)\.skin\.([^.]+)\.md$/;
+
+export default class Validate {
+  /**
+   * @param {object} deps
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} deps.constants
+   * @param {typeof import("node:fs")} deps.fs
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+   */
+  constructor({constants, fs, pathService}) {
+    /**
+     * Validates context structure.
+     *
+     * @param {object} params
+     * @param {string} params.targetPath
+     * @returns {Promise<{
+     *   errorCount: number,
+     *   findings: {
+     *     message: string,
+     *     path: string,
+     *     ruleId: string,
+     *     severity: "error" | "warning"
+     *   }[],
+     *   metadata: {schema: string, version: string, initializedAt?: string} | null,
+     *   missingPaths: string[],
+     *   ok: boolean,
+     *   projectRoot: string,
+     *   projection: {
+     *     assets: string[],
+     *     bodies: string[],
+     *     orphanSkins: string[],
+     *     pairs: {body: string, skin: string}[],
+     *     skins: string[]
+     *   },
+     *   warningCount: number
+     * }>}
+     */
+    this.execute = async function ({targetPath}) {
+      const projectRoot = pathService.resolve(targetPath);
+      const missingPaths = constants.REQUIRED_PATHS.filter((entry) => !fs.existsSync(pathService.join(projectRoot, entry)));
+      const findings = missingPaths.map((entry) => createFinding({
+        message: `Missing: ${entry}`,
+        path: entry,
+        ruleId: "required-path",
+        severity: "error",
+      }));
+      const metadata = readMetadata({constants, fs, pathService, projectRoot});
+      const projection = inspectProjection({constants, fs, pathService, projectRoot});
+
+      if (!metadata.ok) findings.push(metadata.finding);
+      findings.push(...projection.findings);
+
+      const errorCount = findings.filter((entry) => entry.severity === "error").length;
+      const warningCount = findings.filter((entry) => entry.severity === "warning").length;
+
+      return {
+        errorCount,
+        findings,
+        metadata: metadata.ok ? metadata.metadata : null,
+        missingPaths,
+        ok: errorCount === 0,
+        projectRoot,
+        projection: projection.summary,
+        warningCount,
+      };
+    };
+
+    /**
+     * Formats validation result for CLI output.
+     *
+     * @param {object} params
+     * @param {{
+     *   errorCount: number,
+     *   findings: {
+     *     message: string,
+     *     path: string,
+     *     ruleId: string,
+     *     severity: "error" | "warning"
+     *   }[],
+     *   metadata: {version: string} | null,
+     *   ok: boolean,
+     *   projectRoot: string,
+     *   warningCount: number
+     * }} params.result
+     * @returns {string}
+     */
+    this.format = function ({result}) {
+      const status = result.errorCount > 0
+        ? "ADSM context validation failed."
+        : result.warningCount > 0
+          ? "ADSM context validation passed with warnings."
+          : "ADSM context validation passed.";
+
+      const lines = [
+        status,
+        `Project root: ${result.projectRoot}`,
+        `Context version: ${result.metadata?.version ?? "unknown"}`,
+        `Errors: ${result.errorCount}`,
+        `Warnings: ${result.warningCount}`,
+      ];
+
+      if (result.findings.length > 0) {
+        lines.push(...result.findings.map((entry) =>
+          `- ${entry.severity.toUpperCase()} ${entry.ruleId} ${entry.path}: ${entry.message}`
+        ));
+      }
+
+      return lines.join("\n");
+    };
+  }
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.message
+ * @param {string} params.path
+ * @param {string} params.ruleId
+ * @param {"error" | "warning"} params.severity
+ * @returns {{message: string, path: string, ruleId: string, severity: "error" | "warning"}}
+ */
+function createFinding({message, path, ruleId, severity}) {
+  return {message, path, ruleId, severity};
+}
+
+/**
+ * Classifies a semantic-skin filename and derives its canonical agent document.
+ *
+ * @param {string} file
+ * @returns {{body: string, language: string | null, markerError: string | null} | null}
+ */
+function parseSkinFilename(file) {
+  const explicitMatch = file.match(EXPLICIT_SKIN_FILENAME);
+  if (explicitMatch) {
+    return {body: `${explicitMatch[1]}.md`, language: explicitMatch[2], markerError: null};
+  }
+
+  const legacyMatch = file.match(LEGACY_SKIN_FILENAME);
+  if (legacyMatch) {
+    return {
+      body: `${legacyMatch[1]}.md`,
+      language: null,
+      markerError: `Skin language marker is required: ${file} must use <name>.skin.<lang>.md`,
+    };
+  }
+
+  const malformedMatch = file.match(MALFORMED_SKIN_FILENAME);
+  if (malformedMatch) {
+    return {
+      body: `${malformedMatch[1]}.md`,
+      language: null,
+      markerError: `Invalid skin language marker: ${file} must use a lowercase ISO 639-1 code`,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * @param {object} params
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} params.constants
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.projectRoot
+ * @returns {{
+ *   ok: false,
+ *   finding: {message: string, path: string, ruleId: string, severity: "error" | "warning"}
+ * } | {
+ *   ok: true,
+ *   metadata: {schema: string, version: string, initializedAt?: string}
+ * }}
+ */
+function readMetadata({constants, fs, pathService, projectRoot}) {
+  const metadataPath = pathService.join(projectRoot, "ctx", "adsm.json");
+  if (!fs.existsSync(metadataPath)) {
+    return {
+      ok: false,
+      finding: createFinding({
+        message: "Missing ctx/adsm.json",
+        path: "ctx/adsm.json",
+        ruleId: "metadata-file",
+        severity: "error",
+      }),
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+    if (parsed.schema !== constants.CONTEXT_SCHEMA) {
+      return {
+        ok: false,
+        finding: createFinding({
+          message: `Unexpected schema: ${parsed.schema}`,
+          path: "ctx/adsm.json",
+          ruleId: "metadata-schema",
+          severity: "error",
+        }),
+      };
+    }
+    if (!parsed.version) {
+      return {
+        ok: false,
+        finding: createFinding({
+          message: "Missing metadata version",
+          path: "ctx/adsm.json",
+          ruleId: "metadata-version",
+          severity: "error",
+        }),
+      };
+    }
+    return {ok: true, metadata: parsed};
+  } catch (error) {
+    return {
+      ok: false,
+      finding: createFinding({
+        message: `Invalid metadata JSON: ${error instanceof Error ? error.message : "Unknown error"}`,
+        path: "ctx/adsm.json",
+        ruleId: "metadata-json",
+        severity: "error",
+      }),
+    };
+  }
+}
+
+/**
+ * @param {object} params
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} params.constants
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.projectRoot
+ * @returns {{
+ *   findings: {
+ *     message: string,
+ *     path: string,
+ *     ruleId: string,
+ *     severity: "error" | "warning"
+ *   }[],
+ *   summary: {
+ *     assets: string[],
+ *     bodies: string[],
+ *     orphanSkins: string[],
+ *     pairs: {body: string, skin: string}[],
+ *     skins: string[]
+ *   }
+ * }}
+ */
+function inspectProjection({constants, fs, pathService, projectRoot}) {
+  const docsRoot = pathService.join(projectRoot, "ctx", "docs");
+  const assetsRoot = pathService.join(projectRoot, "ctx", "assets");
+  const findings = [];
+  const bodies = [];
+  const skins = [];
+  const assets = fs.existsSync(assetsRoot) ? listFiles({fs, pathService, root: assetsRoot, prefix: "ctx/assets"}) : [];
+
+  if (!fs.existsSync(docsRoot)) {
+    return {findings, summary: {assets, bodies, orphanSkins: [], pairs: [], skins: []}};
+  }
+
+  let docsEntries = [];
+  try {
+    docsEntries = listEntries({fs, root: docsRoot});
+  } catch (error) {
+    findings.push(createFinding({
+      message: `Unreadable documentation root (${error instanceof Error ? error.message : "Unknown error"})`,
+      path: "ctx/docs",
+      ruleId: "docs-root-readable",
+      severity: "error",
+    }));
+    return {findings, summary: {assets, bodies, orphanSkins: [], pairs: [], skins: []}};
+  }
+  const docsEntryMap = new Map(docsEntries.map((entry) => [entry.name, entry]));
+  for (const level of constants.DOC_LEVELS) {
+    const entry = docsEntryMap.get(level);
+    if (!entry) {
+      findings.push(createFinding({
+        message: `Missing documentation level: ctx/docs/${level}`,
+        path: `ctx/docs/${level}`,
+        ruleId: "doc-level",
+        severity: "error",
+      }));
+    } else if (!entry.isDirectory()) {
+      findings.push(createFinding({
+        message: `Documentation level is not a directory: ctx/docs/${level}`,
+        path: `ctx/docs/${level}`,
+        ruleId: "doc-level",
+        severity: "error",
+      }));
+    }
+  }
+  findings.push(...validateDocumentationLevelCapacity({
+    constants,
+    docsEntryMap,
+    fs,
+    pathService,
+    projectRoot,
+  }));
+
+  const markdownFiles = [];
+  for (const file of listFiles({fs, pathService, root: docsRoot, prefix: "ctx/docs"})) {
+    if (!file.endsWith(".md")) continue;
+    markdownFiles.push(file);
+    if (file.endsWith("/AGENTS.md") || file === "ctx/docs/AGENTS.md") continue;
+    if (parseSkinFilename(file)) {
+      skins.push(file);
+    } else {
+      bodies.push(file);
+    }
+  }
+
+  const bodySet = new Set(bodies);
+  const orphanSkins = [];
+  const pairs = [];
+  for (const skin of skins) {
+    const skinInfo = parseSkinFilename(skin);
+    const body = skinInfo.body;
+    if (bodySet.has(body)) {
+      pairs.push({body, skin});
+    } else {
+      orphanSkins.push(skin);
+      findings.push(createFinding({
+        message: `Orphan semantic skin: ${skin}`,
+        path: skin,
+        ruleId: "skin-paired-agent-document",
+        severity: "error",
+      }));
+    }
+  }
+
+  for (const file of markdownFiles) {
+    const absolutePath = pathService.join(projectRoot, ...file.split("/"));
+    let text = "";
+    try {
+      text = fs.readFileSync(absolutePath, "utf8");
+    } catch (error) {
+      findings.push(createFinding({
+        message: `Unreadable document (${error instanceof Error ? error.message : "Unknown error"})`,
+        path: file,
+        ruleId: "document-readable",
+        severity: "error",
+      }));
+      continue;
+    }
+    findings.push(...validateDocumentMetadata({file, text}));
+    findings.push(...validateLocalMarkdownLinks({file, fs, pathService, projectRoot, text}));
+    const skinInfo = parseSkinFilename(file);
+    if (skinInfo) {
+      findings.push(...validateSkinDocument({bodySet, constants, file, skinInfo, text}));
+    }
+  }
+
+  return {
+    findings,
+    summary: {
+      assets,
+      bodies,
+      orphanSkins,
+      pairs,
+      skins,
+    },
+  };
+}
+
+/**
+ * Warns when a documentation level exceeds the recommended direct-entry capacity
+ * and requires its local AGENTS.md to make an intentional exception explicit.
+ *
+ * @param {object} params
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} params.constants
+ * @param {Map<string, {name: string, isDirectory: () => boolean, isFile: () => boolean}>} params.docsEntryMap
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.projectRoot
+ * @returns {{message: string, path: string, ruleId: string, severity: "error" | "warning"}[]}
+ */
+function validateDocumentationLevelCapacity({constants, docsEntryMap, fs, pathService, projectRoot}) {
+  const findings = [];
+  for (const level of constants.DOC_LEVELS) {
+    const levelEntry = docsEntryMap.get(level);
+    if (!levelEntry?.isDirectory()) continue;
+
+    const levelPath = `ctx/docs/${level}`;
+    let entries = [];
+    try {
+      entries = listEntries({fs, root: pathService.join(projectRoot, ...levelPath.split("/"))});
+    } catch (error) {
+      findings.push(createFinding({
+        message: `Unreadable documentation level (${error instanceof Error ? error.message : "Unknown error"})`,
+        path: levelPath,
+        ruleId: "doc-level-capacity",
+        severity: "error",
+      }));
+      continue;
+    }
+
+    const directoryCount = entries.filter((entry) => entry.isDirectory()).length;
+    const fileCount = entries.filter((entry) => entry.isFile() && entry.name !== "AGENTS.md" && !parseSkinFilename(entry.name)).length;
+    const exceeded = [];
+    if (directoryCount > constants.DOC_LEVEL_MAX_DIRECTORIES) {
+      exceeded.push(`${directoryCount} directories (recommended maximum ${constants.DOC_LEVEL_MAX_DIRECTORIES})`);
+    }
+    if (fileCount > constants.DOC_LEVEL_MAX_FILES) {
+      exceeded.push(`${fileCount} files (recommended maximum ${constants.DOC_LEVEL_MAX_FILES})`);
+    }
+    if (exceeded.length === 0) continue;
+
+    findings.push(createFinding({
+      message: `Documentation level exceeds recommended capacity: ${exceeded.join(", ")}`,
+      path: levelPath,
+      ruleId: "doc-level-capacity",
+      severity: "warning",
+    }));
+
+    const agentsPath = pathService.join(projectRoot, ...levelPath.split("/"), "AGENTS.md");
+    let agentsText = "";
+    try {
+      agentsText = fs.readFileSync(agentsPath, "utf8");
+    } catch (error) {
+      findings.push(createFinding({
+        message: `Missing readable Documentation Capacity Exception in ${levelPath}/AGENTS.md`,
+        path: `${levelPath}/AGENTS.md`,
+        ruleId: "doc-level-capacity-exception",
+        severity: "error",
+      }));
+      continue;
+    }
+    if (extractSectionBody({sectionName: "Documentation Capacity Exception", text: agentsText}).trim().length === 0) {
+      findings.push(createFinding({
+        message: `Documentation Capacity Exception must be explicit in ${levelPath}/AGENTS.md`,
+        path: `${levelPath}/AGENTS.md`,
+        ruleId: "doc-level-capacity-exception",
+        severity: "error",
+      }));
+    }
+  }
+  return findings;
+}
+
+/**
+ * @param {object} params
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.root
+ * @param {string} params.prefix
+ * @returns {string[]}
+ */
+function listFiles({fs, pathService, root, prefix}) {
+  const result = [];
+  for (const entry of listEntries({fs, root})) {
+    const childPath = pathService.join(root, entry.name);
+    const childPrefix = `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      result.push(...listFiles({fs, pathService, root: childPath, prefix: childPrefix}));
+    } else if (entry.isFile()) {
+      result.push(childPrefix);
+    }
+  }
+  return result.sort();
+}
+
+/**
+ * @param {object} params
+ * @param {typeof import("node:fs")} params.fs
+ * @param {string} params.root
+ * @returns {{name: string, isDirectory: () => boolean, isFile: () => boolean}[]}
+ */
+function listEntries({fs, root}) {
+  return fs.readdirSync(root, {withFileTypes: true});
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.file
+ * @param {{body: string, language: string | null, markerError: string | null}} params.skinInfo
+ * @param {string} params.text
+ * @returns {{message: string, path: string, ruleId: string, severity: "error" | "warning"}[]}
+ */
+function validateDocumentMetadata({file, text}) {
+  const findings = [];
+  const pathMatch = text.match(/^- Path: `([^`]+)`$/m);
+  if (!pathMatch) {
+    findings.push(createFinding({
+      message: `Missing Path attribute: ${file}`,
+      path: file,
+      ruleId: "doc-header-path-changed",
+      severity: "error",
+    }));
+  } else if (pathMatch[1] !== file) {
+    findings.push(createFinding({
+      message: `Path mismatch: ${file} declares ${pathMatch[1]}`,
+      path: file,
+      ruleId: "doc-header-path-changed",
+      severity: "error",
+    }));
+  }
+
+  const changedMatch = text.match(/^- Changed: `([^`]+)`$/m);
+  if (!changedMatch) {
+    findings.push(createFinding({
+      message: `Missing Changed attribute: ${file}`,
+      path: file,
+      ruleId: "doc-header-path-changed",
+      severity: "error",
+    }));
+  } else if (!/^\d{8}$/.test(changedMatch[1])) {
+    findings.push(createFinding({
+      message: `Invalid Changed attribute: ${file} declares ${changedMatch[1]}`,
+      path: file,
+      ruleId: "doc-header-path-changed",
+      severity: "error",
+    }));
+  }
+
+  return findings;
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.file
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.projectRoot
+ * @param {string} params.text
+ * @returns {{message: string, path: string, ruleId: string, severity: "error" | "warning"}[]}
+ */
+function validateLocalMarkdownLinks({file, fs, pathService, projectRoot, text}) {
+  const findings = [];
+  for (const [, rawLink] of text.matchAll(LINK_PATTERN)) {
+    const normalized = normalizeLocalMarkdownLink({file, link: rawLink});
+    if (!normalized) continue;
+
+    const resolvedPath = pathService.join(projectRoot, ...normalized.path.split("/"));
+    if (!fs.existsSync(resolvedPath)) {
+      findings.push(createFinding({
+        message: `Missing linked document: ${rawLink} resolves to ${normalized.path}`,
+        path: file,
+        ruleId: "local-link-exists",
+        severity: "error",
+      }));
+      continue;
+    }
+
+    if (normalized.fragment) {
+      findings.push(createFinding({
+        message: `Link anchor was not validated: ${rawLink}`,
+        path: file,
+        ruleId: "local-link-exists",
+        severity: "warning",
+      }));
+    }
+  }
+  return findings;
+}
+
+/**
+ * @param {object} params
+ * @param {Set<string>} params.bodySet
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} params.constants
+ * @param {string} params.file
+ * @param {string} params.text
+ * @returns {{message: string, path: string, ruleId: string, severity: "error" | "warning"}[]}
+ */
+function validateSkinDocument({bodySet, constants, file, skinInfo, text}) {
+  const findings = [];
+  if (skinInfo.markerError) {
+    findings.push(createFinding({
+      message: skinInfo.markerError,
+      path: file,
+      ruleId: "skin-language-marker",
+      severity: "error",
+    }));
+  }
+  const headings = extractLevelTwoHeadings(text);
+  for (const section of REQUIRED_SKIN_SECTIONS) {
+    if (!headings.includes(section)) {
+      findings.push(createFinding({
+        message: `Missing skin section "${section}": ${file}`,
+        path: file,
+        ruleId: "skin-required-sections",
+        severity: "error",
+      }));
+    }
+  }
+
+  const scopeText = extractSectionBody({sectionName: "Scope", text});
+  if (scopeText) {
+    if (!/^Includes:\s*$/m.test(scopeText)) {
+      findings.push(createFinding({
+        message: `Missing Includes: block in Scope: ${file}`,
+        path: file,
+        ruleId: "skin-scope-includes-excludes",
+        severity: "error",
+      }));
+    }
+    if (!/^Excludes:\s*$/m.test(scopeText)) {
+      findings.push(createFinding({
+        message: `Missing Excludes: block in Scope: ${file}`,
+        path: file,
+        ruleId: "skin-scope-includes-excludes",
+        severity: "error",
+      }));
+    }
+  }
+
+  const declaredReference = extractAgentDocumentReference(text);
+  if (!declaredReference) {
+    findings.push(createFinding({
+      message: `Missing Agent Document reference: ${file}`,
+      path: file,
+      ruleId: "skin-agent-document-reference",
+      severity: "error",
+    }));
+    findings.push(...validateSkinMetrics({constants, file, text}));
+    return findings;
+  }
+
+  const expectedReference = skinInfo.body;
+  const normalizedReference = normalizeAgentDocumentReference({reference: declaredReference, skinFile: file});
+  if (normalizedReference !== expectedReference) {
+    findings.push(createFinding({
+      message: `Skin agent document mismatch: ${file} references ${normalizedReference} but expected ${expectedReference}`,
+      path: file,
+      ruleId: "skin-agent-document-reference",
+      severity: "error",
+    }));
+  }
+  if (!bodySet.has(normalizedReference)) {
+    findings.push(createFinding({
+      message: `Missing paired agent document: ${file} references ${normalizedReference}`,
+      path: file,
+      ruleId: "skin-paired-agent-document",
+      severity: "error",
+    }));
+  }
+
+  findings.push(...validateSkinMetrics({constants, file, text}));
+  return findings;
+}
+
+/**
+ * @param {object} params
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} params.constants
+ * @param {string} params.file
+ * @param {string} params.text
+ * @returns {{message: string, path: string, ruleId: string, severity: "error" | "warning"}[]}
+ */
+function validateSkinMetrics({constants, file, text}) {
+  const findings = [];
+  const metricText = extractSkinMetricText(text);
+  const wordCount = countWords(metricText);
+  const listCount = countMeaningfulListItems(metricText);
+
+  if (wordCount > constants.SKIN_WORD_ERROR) {
+    findings.push(createFinding({
+      message: `Skin word count ${wordCount} exceeds limit ${constants.SKIN_WORD_ERROR}`,
+      path: file,
+      ruleId: "skin-size-word-count",
+      severity: "error",
+    }));
+  } else if (wordCount > constants.SKIN_WORD_WARN) {
+    findings.push(createFinding({
+      message: `Skin word count ${wordCount} exceeds warning threshold ${constants.SKIN_WORD_WARN}`,
+      path: file,
+      ruleId: "skin-size-word-count",
+      severity: "warning",
+    }));
+  }
+
+  if (listCount > constants.SKIN_LIST_ERROR) {
+    findings.push(createFinding({
+      message: `Skin list count ${listCount} exceeds limit ${constants.SKIN_LIST_ERROR}`,
+      path: file,
+      ruleId: "skin-size-list-count",
+      severity: "error",
+    }));
+  } else if (listCount > constants.SKIN_LIST_WARN) {
+    findings.push(createFinding({
+      message: `Skin list count ${listCount} exceeds warning threshold ${constants.SKIN_LIST_WARN}`,
+      path: file,
+      ruleId: "skin-size-list-count",
+      severity: "warning",
+    }));
+  }
+
+  return findings;
+}
+
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractLevelTwoHeadings(text) {
+  return [...text.matchAll(/^##\s+(.+)$/gm)].map((match) => match[1].trim());
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.sectionName
+ * @param {string} params.text
+ * @returns {string}
+ */
+function extractSectionBody({sectionName, text}) {
+  const lines = text.split("\n");
+  const body = [];
+  let insideSection = false;
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!insideSection) {
+      if (line === `## ${sectionName}`) insideSection = true;
+      continue;
+    }
+    if (line.startsWith("## ")) break;
+    body.push(rawLine);
+  }
+  return body.join("\n");
+}
+
+/**
+ * @param {string} text
+ * @returns {string | null}
+ */
+function extractAgentDocumentReference(text) {
+  const lines = text.split("\n");
+  let insideSection = false;
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!insideSection) {
+      if (line === "## Agent Document") insideSection = true;
+      continue;
+    }
+    if (line.startsWith("## ")) break;
+    if (line.length > 0) return line;
+  }
+  return null;
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.reference
+ * @param {string} params.skinFile
+ * @returns {string}
+ */
+function normalizeAgentDocumentReference({reference, skinFile}) {
+  let value = reference.trim();
+  const codeMatch = value.match(/^`(.+)`$/);
+  if (codeMatch) value = codeMatch[1].trim();
+  const linkMatch = value.match(/^\[[^\]]+\]\(([^)]+)\)$/);
+  if (linkMatch) value = linkMatch[1].trim();
+  if (value.startsWith("./")) value = value.slice(2);
+  if (value.startsWith("ctx/docs/")) return value;
+
+  const skinParts = skinFile.split("/");
+  skinParts.pop();
+  skinParts.push(value);
+  return normalizeRelativeSegments(skinParts).join("/");
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.file
+ * @param {string} params.link
+ * @returns {{fragment: string | null, path: string} | null}
+ */
+function normalizeLocalMarkdownLink({file, link}) {
+  const trimmed = link.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith("http://") || trimmed.startsWith("https://") || trimmed.startsWith("mailto:")) return null;
+
+  const [rawPath, fragment = ""] = trimmed.split("#");
+  if (!rawPath.endsWith(".md")) return null;
+
+  let path = rawPath;
+  if (path.startsWith("./")) path = path.slice(2);
+
+  if (path.startsWith("ctx/docs/")) {
+    return {fragment: fragment || null, path: normalizeRelativeSegments(path.split("/")).join("/")};
+  }
+
+  const parts = file.split("/");
+  parts.pop();
+  parts.push(...path.split("/"));
+  return {
+    fragment: fragment || null,
+    path: normalizeRelativeSegments(parts).join("/"),
+  };
+}
+
+/**
+ * @param {string[]} parts
+ * @returns {string[]}
+ */
+function normalizeRelativeSegments(parts) {
+  const result = [];
+  for (const part of parts) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      if (result.length > 0) result.pop();
+      continue;
+    }
+    result.push(part);
+  }
+  return result;
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function stripFencedCodeBlocks(text) {
+  return text.replace(/```[\s\S]*?```/g, "");
+}
+
+/**
+ * Extracts semantic skin content while excluding metadata, headings, and the
+ * Agent Document reference.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function extractSkinMetricText(text) {
+  return ["Purpose", "Mental Model", "Scope", "Invariants"]
+    .map((sectionName) => extractSectionBody({sectionName, text}))
+    .join("\n")
+    .replace(/^\s{0,3}#{1,6}\s+.*$/gm, "")
+    .replace(/^\s*(?:Includes|Excludes):\s*$/gm, "");
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function stripSkinPresentation(text) {
+  return stripFencedCodeBlocks(text)
+    .split("\n")
+    .filter((line) => !/^#/.test(line.trim()))
+    .filter((line) => !/^- (?:Path|Changed): `[^`]+`$/.test(line.trim()))
+    .join("\n");
+}
+
+/**
+ * @param {string} text
+ * @returns {number}
+ */
+function countWords(text) {
+  const matches = stripFencedCodeBlocks(text).match(/(?:\p{L}[\p{L}\p{M}\p{N}'’_-]*|\p{N}+)/gu);
+  return matches ? matches.length : 0;
+}
+
+/**
+ * @param {string} text
+ * @returns {number}
+ */
+function countMeaningfulListItems(text) {
+  return [...stripFencedCodeBlocks(text).matchAll(/^\s*(?:[-*+]|\d+[.)])\s+(.+)$/gmu)]
+    .filter((match) => countWords(match[1]) > 0)
+    .length;
+}
+
+export const __deps__ = Object.freeze({
+  constants: "Fl32_Skill_Adsm_Ctx_Shared_Constants$",
+  fs: "node:fs",
+  pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
+});