@flancer32/skill-adsm-ctx 0.4.0 → 0.6.0

package/src/Validate/Service.mjs

@@ -21,30 +21,9 @@ export default class Validate {
     /**
      * 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: {capabilities?: string[], 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[],
-     *     verification: {categories: string[], present: boolean}
-     *   },
-     *   warningCount: number
-     * }>}
+     * @param {object} deps
+     * @param {string} deps.targetPath
+     * @returns {Promise<Fl32_Skill_Adsm_Ctx_Validate_Result>}
      */
     this.execute = async function ({targetPath}) {
       const projectRoot = pathService.resolve(targetPath);
@@ -59,11 +38,22 @@ export default class Validate {
       const projection = inspectProjection({
         constants,
         fs,
-        metadata: metadataResult.metadata,
+        metadata: metadataResult.ok ? metadataResult.metadata : null,
         pathService,
         projectRoot,
       });
 
+      for (const entry of constants.REQUIRED_PATHS) {
+        const absolute = pathService.join(projectRoot, entry);
+        if (!fs.existsSync(absolute) || typeof fs.statSync !== "function") continue;
+        const stat = fs.statSync(absolute);
+        const file = entry.endsWith(".md") || entry.endsWith(".json");
+        if (file ? !stat.isFile() : !stat.isDirectory()) findings.push(createFinding({
+          message: `Required path has wrong filesystem type: ${entry}`,
+          path: entry, ruleId: "required-path-type", severity: "error",
+        }));
+      }
+      findings.push(...inspectAgentsHierarchy({fs, pathService, projectRoot}));
       findings.push(...metadataResult.findings);
       findings.push(...projection.findings);
 
@@ -73,7 +63,7 @@ export default class Validate {
       return {
         errorCount,
         findings,
-        metadata: metadataResult.ok ? metadataResult.metadata : null,
+        metadata: metadataResult.metadata,
         missingPaths,
         ok: errorCount === 0,
         projectRoot,
@@ -85,20 +75,8 @@ export default class Validate {
     /**
      * 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
+     * @param {object} deps
+     * @param {Fl32_Skill_Adsm_Ctx_Validate_Result} deps.result
      * @returns {string}
      */
     this.format = function ({result}) {
@@ -111,7 +89,8 @@ export default class Validate {
       const lines = [
         status,
         `Project root: ${result.projectRoot}`,
-        `Context version: ${result.metadata?.version ?? "unknown"}`,
+        `Context schema version: ${result.metadata?.version ?? "unknown"}`,
+        `Supported context schema version: ${constants.CONTEXT_VERSION}`,
         `Errors: ${result.errorCount}`,
         `Warnings: ${result.warningCount}`,
       ];
@@ -128,12 +107,12 @@ export default class Validate {
 }
 
 /**
- * @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"}}
+ * @param {object} deps
+ * @param {string} deps.message
+ * @param {string} deps.path
+ * @param {string} deps.ruleId
+ * @param {Fl32_Skill_Adsm_Ctx_Finding_Severity} deps.severity
+ * @returns {Fl32_Skill_Adsm_Ctx_Finding}
  */
 function createFinding({message, path, ruleId, severity}) {
   return {message, path, ruleId, severity};
@@ -143,7 +122,7 @@ function createFinding({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}
+ * @returns {Fl32_Skill_Adsm_Ctx_SkinInfo_Optional}
  */
 function parseSkinFilename(file) {
   const explicitMatch = file.match(EXPLICIT_SKIN_FILENAME);
@@ -173,18 +152,12 @@ function parseSkinFilename(file) {
 }
 
 /**
- * @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}
- * }}
+ * @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
+ * @param {string} deps.projectRoot
+ * @returns {Fl32_Skill_Adsm_Ctx_Metadata_ReadResult}
  */
 function readMetadata({constants, fs, pathService, projectRoot}) {
   const findings = [];
@@ -209,9 +182,9 @@ function readMetadata({constants, fs, pathService, projectRoot}) {
         severity: "error",
       }));
     }
-    if (!parsed.version) {
+    if (parsed.version !== constants.CONTEXT_VERSION) {
       findings.push(createFinding({
-        message: "Missing metadata version",
+        message: `Unsupported metadata version: ${parsed.version}; target schema: ${constants.CONTEXT_VERSION}. Investigate with skill adsm-ctx before changing schema metadata.`,
         path: "ctx/adsm.json",
         ruleId: "metadata-version",
         severity: "error",
@@ -252,7 +225,7 @@ function readMetadata({constants, fs, pathService, projectRoot}) {
     }
 
     const ok = findings.every((entry) => entry.severity !== "error");
-    return {findings, metadata: ok ? parsed : null, ok};
+    return {findings, metadata: parsed, ok};
   } catch (error) {
     findings.push(createFinding({
       message: `Invalid metadata JSON: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -265,26 +238,13 @@ function readMetadata({constants, fs, pathService, projectRoot}) {
 }
 
 /**
- * @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[]
- *   }
- * }}
+ * @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
+ * @param {string} deps.projectRoot
+ * @param {Fl32_Skill_Adsm_Ctx_Metadata_Optional} deps.metadata
+ * @returns {Fl32_Skill_Adsm_Ctx_Projection_Result}
  */
 function inspectProjection({constants, fs, metadata, pathService, projectRoot}) {
   const docsRoot = pathService.join(projectRoot, "ctx", "docs");
@@ -424,19 +384,16 @@ function inspectProjection({constants, fs, metadata, pathService, projectRoot})
 }
 
 /**
- * Inspects optional Verification Layer adoption without treating it as a fifth
+ * Inspects the cross-cutting Verification Layer without treating it as a fifth
  * declarative documentation level.
  *
- * @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 {{
- *   findings: {message: string, path: string, ruleId: string, severity: "error" | "warning"}[],
- *   summary: {categories: string[], present: boolean}
- * }}
+ * @param {object} deps
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} deps.constants
+ * @param {Fl32_Skill_Adsm_Ctx_DirectoryEntryMap} deps.docsEntryMap
+ * @param {typeof import("node:fs")} deps.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+ * @param {string} deps.projectRoot
+ * @returns {Fl32_Skill_Adsm_Ctx_Verification_Result}
  */
 function inspectVerificationBlock({constants, docsEntryMap, fs, pathService, projectRoot}) {
   const findings = [];
@@ -529,15 +486,6 @@ function inspectVerificationBlock({constants, docsEntryMap, fs, pathService, pro
     }
   }
 
-  if (summary.categories.length === 0) {
-    findings.push(createFinding({
-      message: `Verification block has no populated primary-target category: ${verificationPath}`,
-      path: verificationPath,
-      ruleId: "verification-empty-block",
-      severity: "error",
-    }));
-  }
-
   return {findings, summary};
 }
 
@@ -545,13 +493,13 @@ function inspectVerificationBlock({constants, docsEntryMap, fs, pathService, pro
  * 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"}[]}
+ * @param {object} deps
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} deps.constants
+ * @param {Fl32_Skill_Adsm_Ctx_DirectoryEntryMap} deps.docsEntryMap
+ * @param {typeof import("node:fs")} deps.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+ * @param {string} deps.projectRoot
+ * @returns {Array<Fl32_Skill_Adsm_Ctx_Finding>}
  */
 function validateDocumentationLevelCapacity({constants, docsEntryMap, fs, pathService, projectRoot}) {
   const findings = [];
@@ -617,12 +565,12 @@ function validateDocumentationLevelCapacity({constants, docsEntryMap, fs, pathSe
 }
 
 /**
- * @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[]}
+ * @param {object} deps
+ * @param {typeof import("node:fs")} deps.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+ * @param {string} deps.root
+ * @param {string} deps.prefix
+ * @returns {Array<string>}
  */
 function listFiles({fs, pathService, root, prefix}) {
   const result = [];
@@ -639,21 +587,20 @@ function listFiles({fs, pathService, root, prefix}) {
 }
 
 /**
- * @param {object} params
- * @param {typeof import("node:fs")} params.fs
- * @param {string} params.root
- * @returns {{name: string, isDirectory: () => boolean, isFile: () => boolean}[]}
+ * @param {object} deps
+ * @param {typeof import("node:fs")} deps.fs
+ * @param {string} deps.root
+ * @returns {Array<Fl32_Skill_Adsm_Ctx_DirectoryEntry>}
  */
 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"}[]}
+ * @param {object} deps
+ * @param {string} deps.file
+ * @param {string} deps.text
+ * @returns {Array<Fl32_Skill_Adsm_Ctx_Finding>}
  */
 function validateDocumentMetadata({file, text}) {
   const findings = [];
@@ -695,13 +642,13 @@ function validateDocumentMetadata({file, text}) {
 }
 
 /**
- * @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"}[]}
+ * @param {object} deps
+ * @param {string} deps.file
+ * @param {typeof import("node:fs")} deps.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+ * @param {string} deps.projectRoot
+ * @param {string} deps.text
+ * @returns {Array<Fl32_Skill_Adsm_Ctx_Finding>}
  */
 function validateLocalMarkdownLinks({file, fs, pathService, projectRoot, text}) {
   const findings = [];
@@ -733,12 +680,13 @@ function validateLocalMarkdownLinks({file, fs, pathService, projectRoot, text})
 }
 
 /**
- * @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"}[]}
+ * @param {object} deps
+ * @param {Fl32_Skill_Adsm_Ctx_StringSet} deps.bodySet
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} deps.constants
+ * @param {string} deps.file
+ * @param {Fl32_Skill_Adsm_Ctx_SkinInfo} deps.skinInfo
+ * @param {string} deps.text
+ * @returns {Array<Fl32_Skill_Adsm_Ctx_Finding>}
  */
 function validateSkinDocument({bodySet, constants, file, skinInfo, text}) {
   const findings = [];
@@ -762,9 +710,9 @@ function validateSkinDocument({bodySet, constants, file, skinInfo, text}) {
 }
 
 /**
- * @param {object} params
- * @param {string} params.sectionName
- * @param {string} params.text
+ * @param {object} deps
+ * @param {string} deps.sectionName
+ * @param {string} deps.text
  * @returns {string}
  */
 function extractSectionBody({sectionName, text}) {
@@ -784,10 +732,10 @@ function extractSectionBody({sectionName, text}) {
 }
 
 /**
- * @param {object} params
- * @param {string} params.file
- * @param {string} params.link
- * @returns {{fragment: string | null, path: string} | null}
+ * @param {object} deps
+ * @param {string} deps.file
+ * @param {string} deps.link
+ * @returns {Fl32_Skill_Adsm_Ctx_Validate_Link_Optional}
  */
 function normalizeLocalMarkdownLink({file, link}) {
   const trimmed = link.trim();
@@ -814,8 +762,8 @@ function normalizeLocalMarkdownLink({file, link}) {
 }
 
 /**
- * @param {string[]} parts
- * @returns {string[]}
+ * @param {Array<string>} parts
+ * @returns {Array<string>}
  */
 function normalizeRelativeSegments(parts) {
   const result = [];
@@ -830,8 +778,70 @@ function normalizeRelativeSegments(parts) {
   return result;
 }
 
-export const __deps__ = Object.freeze({
+/**
+ * Checks context-side routing sections; root repository instructions have a separate shape.
+ * @param {object} deps
+ * @param {typeof import("node:fs")} deps.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+ * @param {string} deps.projectRoot
+ * @returns {Array<Fl32_Skill_Adsm_Ctx_Finding>}
+ */
+function inspectAgentsHierarchy({fs, pathService, projectRoot}) {
+  const findings = [];
+  const root = pathService.join(projectRoot, "ctx");
+  if (!fs.existsSync(root)) return findings;
+  /**
+   * @param {string} directory
+   * @param {string} relative
+   * @returns {void}
+   */
+  const visit = (directory, relative) => {
+    let entries;
+    try { entries = listEntries({fs, root: directory}); }
+    catch (error) {
+      findings.push(createFinding({message: `Cannot inspect context routing: ${error.message}`, path: relative, ruleId: "agents-readable", severity: "error"}));
+      return;
+    }
+    for (const entry of entries) {
+      const absolute = pathService.join(directory, entry.name);
+      const file = `${relative}/${entry.name}`;
+      if (entry.isDirectory()) visit(absolute, file);
+      else if (entry.isFile() && entry.name === "AGENTS.md") {
+        let text;
+        try { text = fs.readFileSync(absolute, "utf8"); }
+        catch (error) {
+          findings.push(createFinding({message: `Cannot read context AGENTS.md: ${error.message}`, path: file, ruleId: "agents-readable", severity: "error"}));
+          continue;
+        }
+        // Ignore fenced examples so sample headings cannot satisfy the document structure.
+        const headings = new Set();
+        let fence = null;
+        for (const line of text.split(/\r?\n/)) {
+          const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+          if (marker) {
+            if (!fence) fence = marker[1];
+            else if (marker[1][0] === fence[0] && marker[1].length >= fence.length) fence = null;
+            continue;
+          }
+          if (fence) continue;
+          const heading = /^ {0,3}##[ \t]+(.+?)[ \t]*$/.exec(line);
+          if (heading) headings.add(heading[1].replace(/[ \t]+#+[ \t]*$/, ""));
+        }
+        for (const section of ["Purpose", "Level Map", "Level Boundary"]) {
+          if (!headings.has(section)) findings.push(createFinding({
+            message: `Missing required section: ## ${section}. Add it to this context-side AGENTS.md.`,
+            path: file, ruleId: "agents-required-section", severity: "error",
+          }));
+        }
+      }
+    }
+  };
+  visit(root, "ctx");
+  return findings;
+}
+
+export const __deps__ = Object.freeze({default: Object.freeze({
   constants: "Fl32_Skill_Adsm_Ctx_Shared_Constants$",
   fs: "node:fs",
   pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
-});
+})});

package/types.d.ts

@@ -1,18 +1,45 @@
 declare global {
-  type Fl32_Skill_Adsm_Ctx_Cli_Command_Design = import("./src/Cli/Command/Design.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Cli_Command_Init = import("./src/Cli/Command/Init.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Cli_Command_Init__Class = typeof import("./src/Cli/Command/Init.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Cli_Command_InstallSkill = import("./src/Cli/Command/InstallSkill.mjs").default;
-  type Fl32_Skill_Adsm_Ctx_Cli_Command_Upgrade = import("./src/Cli/Command/Upgrade.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Cli_Command_InstallSkill__Class = typeof import("./src/Cli/Command/InstallSkill.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Cli_Command_Validate = import("./src/Cli/Command/Validate.mjs").default;
-  type Fl32_Skill_Adsm_Ctx_Design_Service = import("./src/Design/Service.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Cli_Command_Validate__Class = typeof import("./src/Cli/Command/Validate.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Cli_Config = {cwd: string};
+  type Fl32_Skill_Adsm_Ctx_DirectoryEntry = {name: string; isDirectory: () => boolean; isFile: () => boolean};
+  type Fl32_Skill_Adsm_Ctx_DirectoryEntryMap = {get: (name: string) => Fl32_Skill_Adsm_Ctx_DirectoryEntry | undefined};
+  type Fl32_Skill_Adsm_Ctx_Finding = {message: string; path: string; ruleId: string; severity: "error" | "warning"};
+  type Fl32_Skill_Adsm_Ctx_Finding_Severity = "error" | "warning";
+  type Fl32_Skill_Adsm_Ctx_Init_Result = {created: Array<string>; ctxRoot: string; projectRoot: string; skipped: Array<string>};
   type Fl32_Skill_Adsm_Ctx_Init_Service = import("./src/Init/Service.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Init_Service__Class = typeof import("./src/Init/Service.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Metadata = {schema: string; version: string; capabilities?: Array<string>; initializedAt?: string};
+  type Fl32_Skill_Adsm_Ctx_Metadata_Optional = Fl32_Skill_Adsm_Ctx_Metadata | null;
+  type Fl32_Skill_Adsm_Ctx_Metadata_ReadResult = {findings: Array<Fl32_Skill_Adsm_Ctx_Finding>; metadata: Fl32_Skill_Adsm_Ctx_Metadata | null; ok: boolean};
+  type Fl32_Skill_Adsm_Ctx_Metadata_Value = {schema: string; version: string; capabilities: Array<string>};
+  type Fl32_Skill_Adsm_Ctx_Projection = {assets: Array<string>; bodies: Array<string>; orphanSkins: Array<string>; pairs: Array<Fl32_Skill_Adsm_Ctx_Projection_Pair>; skins: Array<string>; verification?: Fl32_Skill_Adsm_Ctx_Verification_Summary};
+  type Fl32_Skill_Adsm_Ctx_Projection_Pair = {body: string; skin: string};
+  type Fl32_Skill_Adsm_Ctx_Projection_Result = {findings: Array<Fl32_Skill_Adsm_Ctx_Finding>; summary: Fl32_Skill_Adsm_Ctx_Projection};
   type Fl32_Skill_Adsm_Ctx_Shared_Constants = import("./src/Shared/Constants.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Shared_Constants__Class = typeof import("./src/Shared/Constants.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory = import("./src/Shared/CopyDirectory.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory__Class = typeof import("./src/Shared/CopyDirectory.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Shared_Metadata = import("./src/Shared/Metadata.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Shared_Metadata__Class = typeof import("./src/Shared/Metadata.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Shared_Path = import("./src/Shared/Path.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Shared_Path__Class = typeof import("./src/Shared/Path.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Skill_Installer = import("./src/Skill/Installer.mjs").default;
-  type Fl32_Skill_Adsm_Ctx_Upgrade_Service = import("./src/Upgrade/Service.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Skill_Installer__Class = typeof import("./src/Skill/Installer.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_SkinInfo = {body: string; language: string | null; markerError: string | null};
+  type Fl32_Skill_Adsm_Ctx_SkinInfo_Optional = Fl32_Skill_Adsm_Ctx_SkinInfo | null;
+  type Fl32_Skill_Adsm_Ctx_StringSet = {has: (value: string) => boolean};
+  type Fl32_Skill_Adsm_Ctx_Validate_Link = {fragment: string | null; path: string};
+  type Fl32_Skill_Adsm_Ctx_Validate_Link_Optional = Fl32_Skill_Adsm_Ctx_Validate_Link | null;
+  type Fl32_Skill_Adsm_Ctx_Validate_Result = {errorCount: number; findings: Array<Fl32_Skill_Adsm_Ctx_Finding>; metadata: Fl32_Skill_Adsm_Ctx_Metadata | null; missingPaths: Array<string>; ok: boolean; projectRoot: string; projection: Fl32_Skill_Adsm_Ctx_Projection; warningCount: number};
   type Fl32_Skill_Adsm_Ctx_Validate_Service = import("./src/Validate/Service.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Validate_Service__Class = typeof import("./src/Validate/Service.mjs").default;
+  type Fl32_Skill_Adsm_Ctx_Verification_Result = {findings: Array<Fl32_Skill_Adsm_Ctx_Finding>; summary: Fl32_Skill_Adsm_Ctx_Verification_Summary};
+  type Fl32_Skill_Adsm_Ctx_Verification_Summary = {categories: Array<string>; present: boolean};
 }
 
 export {};

package/migrations/README.md

@@ -1,13 +0,0 @@
-# Migrations
-
-This directory is reserved for explicit context migrations. The `verification-layer` convention is capability-based and optional: it does not require a migration, `ctx/docs/verification/`, empty categories, or placeholder specifications. `adsm-ctx upgrade` therefore preserves existing contexts and reports that no automatic migrations are available.
-
-Each migration should be:
-
-- versioned;
-- non-destructive by default;
-- explicit about prerequisites and post-upgrade manual steps.
-
-## Verification Layer Compatibility
-
-Contexts without `capabilities`, with context version `0.1.0`, or without `ctx/docs/verification/` remain valid. A project may add a structurally complete Verification Layer when it has a durable specification; it should then advertise the `verification-layer` capability in `ctx/adsm.json`. Malformed adopted structure is a validation error, while absence is not.

package/skill/SKILL.md

@@ -1,48 +0,0 @@
----
-name: adsm-ctx
-description: Use when initializing, designing, validating, auditing, compressing, or upgrading ADSM project cognitive context. This skill orchestrates generic context lifecycle work and routes agents toward specialized skills when project-specific context branches are needed.
----
-
-# ADSM Context Lifecycle
-
-Manage the lifecycle of an ADSM project cognitive context. Manage generic context structure, documentation projections, lifecycle checks, and the `ctx/agent/` boundary; do not invent project-specific product, architecture, technical, or tool-workflow meaning.
-
-Humans own direction, accepted meaning, approval, and accountability. Agents refine, check consistency, maintain documentation, and report decisions that require human authority.
-
-## Start Here
-
-1. Identify the target repository and the requested lifecycle mode.
-2. Read the applicable `AGENTS.md` hierarchy. If `ctx/` exists, read `ctx/AGENTS.md` and `ctx/docs/filesystem.md` before deeper context work.
-3. Read [document-projections.md](references/document-projections.md) for any work under `ctx/docs/`; for skin work, also read [semantic-skins.md](references/semantic-skins.md).
-4. Use the routing table below, then load only the references needed for the requested mode.
-
-## Route The Request
-
-| Request or mode | Load or run |
-| --- | --- |
-| `init` baseline | [context-lifecycle.md](references/context-lifecycle.md); use the `templates/ctx/` baseline. |
-| `design` or new branch | [context-lifecycle.md](references/context-lifecycle.md), [design-questionnaire.md](references/design-questionnaire.md), and [specialized-skills.md](references/specialized-skills.md). |
-| Verification Layer or Software Evolution Loop | [document-projections.md](references/document-projections.md), [context-lifecycle.md](references/context-lifecycle.md), [documentation-quality-audit.md](references/documentation-quality-audit.md), and [specialized-skills.md](references/specialized-skills.md). |
-| `validate` structure | [context-lifecycle.md](references/context-lifecycle.md), [document-projections.md](references/document-projections.md), and the repository-provided deterministic validator when available. Report errors and warnings separately. |
-| `quality-audit` | Run `validate` first; then load [documentation-quality-audit.md](references/documentation-quality-audit.md). Report findings; do not rewrite project meaning. |
-| `documentation-compression` | Load [documentation-compression.md](references/documentation-compression.md). Rewrite only with authorization and preserve accepted meaning. |
-| `upgrade` | Load [upgrade-policy.md](references/upgrade-policy.md) and [context-lifecycle.md](references/context-lifecycle.md). Apply only safe, explicit migrations. |
-| `AGENTS.md` or local context routing | Load [agents-hierarchy.md](references/agents-hierarchy.md). |
-| `ctx/agent/`, templates, or generic ownership boundary | Load [orchestration-model.md](references/orchestration-model.md). |
-| Browser, backend, data, deployment, or concrete tool workflow | Load [specialized-skills.md](references/specialized-skills.md), then use a matching available specialized skill. |
-
-`adsm-ctx install-skill <skills-root>` installs this payload from the globally installed npm package into a skills root; it is not a lifecycle mode.
-
-## Non-Negotiable Boundaries
-
-- Treat the cognitive context as the managed object and do not invent project facts, requirements, architecture, tool semantics, or authority boundaries.
-- Preserve the documentation order: product → architecture → environment → code. Escalate upstream gaps instead of introducing meaning downstream.
-- Read a matching `*.skin.<lang>.md` before editing its agent document. Report projection drift or a required human decision instead of silently changing skin-controlled meaning.
-- Keep `ctx/agent/` project-local: install only its boundary `AGENTS.md`; do not impose tool-specific structure, labels, prompts, roles, or executable profiles.
-- Keep assets under `ctx/assets/**`; they may illustrate, but never define, authoritative meaning.
-- Preserve the four ordered declarative documentation levels under `ctx/docs/`: `product`, `architecture`, `environment`, and `code`. Allow an optional cross-cutting `verification/` block only as defined in [document-projections.md](references/document-projections.md); it is never a fifth level.
-- Keep each documentation level to no more than nine direct directories and nine direct ordinary files, excluding `AGENTS.md` and paired `*.skin.<lang>.md` files, where practical; an intentional excess must be stated explicitly in that level's `AGENTS.md`.
-
-## Completion
-
-Finish with explicit validation results, Verification Layer adoption state when relevant, specialization gaps, human decisions, and any preserved project-specific content. Use the relevant templates under `templates/ctx/` for initialization and `templates/work/` only when a working report is requested.

package/skill/references/upgrade-policy.md

@@ -1,29 +0,0 @@
-# Upgrade Policy
-
-- Path: `skill/references/upgrade-policy.md`
-- Changed: `20260917`
-
-Upgrades must be non-destructive by default.
-
-## Verification Layer Compatibility
-
-The `verification-layer` context convention capability is optional. Existing contexts without `capabilities`, with context version `0.1.0`, or without `ctx/docs/verification/` remain valid.
-
-Safe adoption may add `"verification-layer"` to `ctx/adsm.json` and add a structurally complete verification block only when the project has a real durable specification. It must not create `verification/`, empty categories, placeholder specifications, or copied specifications merely because an upgrade ran.
-
-Partial adoption is valid. Structural validation distinguishes absence from malformed adoption. An adopted block requires its root `AGENTS.md`; each created primary-target category must be a directory containing a durable specification. Unknown or unsupported categories and malformed capability metadata are validation findings.
-
-## General Upgrade Boundaries
-
-Safe upgrade behavior includes:
-
-- adding missing files and directories only when migration rules explicitly require them;
-- updating metadata when rules are explicit;
-- preserving project-authored content unless replacement is proven safe;
-- detecting agent/skin pairs, orphan skins, and projection drift according to `skill/references/document-projections.md`;
-- preserving project-specific nested subdirectories and adopted verification specifications;
-- keeping visual, generated, rendered, and auxiliary artifacts under `ctx/assets/**`.
-
-Unsafe cases should be reported for manual follow-up instead of applied automatically.
-
-Upgrade must not introduce required `README.md` files inside `ctx/docs/`, automatically rewrite human-controlled skins when meaning is unclear, or claim that adoption provides verification coverage or runtime conformity.