@flancer32/skill-adsm-ctx 0.4.0 → 0.5.0

package/{skill → skills/adsm-ctx}/references/documentation-quality-audit.md

@@ -1,7 +1,7 @@
 # Documentation Quality Audit
 
-- Path: `skill/references/documentation-quality-audit.md`
-- Changed: `20260917`
+- Path: `skills/adsm-ctx/references/documentation-quality-audit.md`
+- Changed: `20261024`
 
 Use this reference when an agent must audit an existing documentation corpus as an ADSM cognitive context.
 
@@ -16,8 +16,8 @@ Audit the documentation corpus of this project against the ADSM documentation qu
 Follow this method:
 
 1. Read the applicable `AGENTS.md` hierarchy from the repository root to `ctx/docs/`, unless the user explicitly gives another documentation scope.
-2. Read `skill/references/document-projections.md` for agent/skin classification and projection drift rules.
-3. Identify the audit corpus under `ctx/docs/`, including nested documentation under `product/`, `architecture/`, `environment/`, and `code/`.
+2. Read [document-projections.md](document-projections.md) from this installed skill for agent/skin classification and projection drift rules.
+3. Identify the audit corpus under `ctx/docs/`, including nested documentation under `product/`, `architecture/`, `environment/`, `code/`, and the mandatory cross-cutting `verification/` boundary.
 4. Classify ordinary `*.md` files as agent-facing operational context documents, `*.skin.<lang>.md` files as human-facing semantic skins, and `AGENTS.md` files as local agent routing instructions.
 5. Build a compact documentation map that shows source-of-truth agent documents, refinement relationships, agent/skin pairs, orphan skins, projection drift, and duplicated responsibility areas.
 6. Evaluate the corpus against the eight ADSM documentation quality criteria and the projection-specific checks below after deterministic validation is clean or warning-only.
@@ -25,7 +25,7 @@ Follow this method:
 8. Report only evidence-backed findings, with file references and the violated criterion.
 9. Separate findings that can be fixed editorially from findings that require cross-document synchronization, upstream documentation changes, projection-drift resolution, or human decisions.
 10. Do not invent missing product facts, architecture boundaries, authority rules, workflow semantics, or implementation behavior.
-11. Use `templates/work/report/documentation-quality-audit.md` as the report structure when a file report is requested.
+11. Use [the audit report template](../assets/report/documentation-quality-audit.md) as the report structure when a file report is requested.
 
 ## Corpus Selection
 
@@ -208,7 +208,7 @@ The audit may propose correction order and candidate edits, but it must distingu
 
 ## Verification Layer Review
 
-When `ctx/docs/verification/` exists, include it in the default corpus. Review it as cross-cutting specification documentation, not a fifth declarative level and not an evidence or incident archive.
+Include mandatory `ctx/docs/verification/` in the default corpus; an AGENTS-only root contains no specifications to audit. Review it as cross-cutting specification documentation, not a fifth declarative level and not an evidence or incident archive.
 
 Check whether each durable specification:
 

package/{skill → skills/adsm-ctx}/references/orchestration-model.md

@@ -1,7 +1,7 @@
 # Orchestration Model
 
-- Path: `skill/references/orchestration-model.md`
-- Changed: `20260917`
+- Path: `skills/adsm-ctx/references/orchestration-model.md`
+- Changed: `20261024`
 
 This skill is a router and baseline manager.
 
@@ -11,7 +11,7 @@ It is responsible for:
 - the agent/skin documentation projection model;
 - lifecycle guidance;
 - baseline validation;
-- migration entry points;
+- agent-driven evolution guidance and read-only Deterministic CLI checks;
 - Verification Layer documentation lifecycle support and structural validation;
 - the reserved boundary definition for `ctx/agent/`.
 
@@ -20,9 +20,11 @@ It is not responsible for inventing specialized technical or domain documentatio
 For `ctx/agent/`, this skill may:
 
 - install only `ctx/agent/AGENTS.md` as the boundary file;
-- state that project-local subdirectories there are outside ADSM methodology;
+- explain that this branch is part of project cognitive context while its project-specific workflows are outside the reusable ADSM baseline;
 - preserve project-local materials that humans or agents maintain there for concrete tools or relationships.
 
+Operational materials organize authorized work within accepted declarations in `ctx/docs/` and applicable supervision constraints. They do not independently establish product or architecture authority or override human approval and escalation requirements. Preserve existing local materials and maintain navigation against the actual filesystem; add structure only for concrete project needs.
+
 For `ctx/agent/`, this skill must not:
 
 - define or require a template-managed subdirectory structure;
@@ -33,10 +35,10 @@ When specialization is needed, the agent should use a matching available skill a
 
 Concrete tool-facing materials belong to project-local documentation, explicit human instruction, or an external specialized skill when one is available and relevant.
 
-Specialized skills may add project-specific nested documentation under the four declarative `ctx/docs` levels and may implement concrete verification methods or project-local feedback procedures. They must preserve agent/skin pairing rules, keep artifacts under `ctx/assets/**`, and treat `verification/` as optional cross-cutting documentation rather than a fifth level.
+Specialized skills may add project-specific nested documentation under the four declarative `ctx/docs` levels and may implement concrete verification methods or project-local feedback procedures. They must preserve agent/skin pairing rules, keep artifacts under `ctx/assets/**`, and treat `verification/` as mandatory cross-cutting documentation rather than a fifth level.
 
 ## Template Boundary
 
 `templates/ctx/` is the reusable initialization baseline. It may establish generic structure, starter documents, and the `ctx/agent/AGENTS.md` boundary, but it must not add project-specific facts or detailed ADSM methodology to project-facing documents.
 
-Keep only the minimal bootstrap signal needed to identify an ADSM context and route methodology work to this skill. Use `templates/work/` only as working material for agent operations; do not install those reports or optional semantic-skin patterns into project context by default.
+Keep only the minimal bootstrap signal needed to identify an ADSM context and route methodology work to this skill. Use `assets/` only as working material for agent operations; do not install those reports or optional semantic-skin patterns into project context by default.

package/{skill → skills/adsm-ctx}/references/semantic-skins.md

@@ -1,6 +1,6 @@
 # Semantic Skins
 
-- Path: `skill/references/semantic-skins.md`
+- Path: `skills/adsm-ctx/references/semantic-skins.md`
 - Changed: `20260814`
 
 A semantic skin is a compact skeletal human projection of its paired agent document.
@@ -63,3 +63,5 @@ When creating or reviewing a skin, verify that it:
 - adds no untracked facts or requirements and does not contradict its base;
 - excludes operational detail and redundant navigation; and
 - remains compact enough for human cognitive use.
+
+Use the [semantic-skin asset](../assets/context/semantic-skin.md) as an optional authoring pattern for authorized work. It is not an initialization template and does not determine the output location; place the resulting skin beside its paired project document.

package/{skill → skills/adsm-ctx}/references/specialized-skills.md

@@ -1,6 +1,6 @@
 # Specialized Skills
 
-- Path: `skill/references/specialized-skills.md`
+- Path: `skills/adsm-ctx/references/specialized-skills.md`
 - Changed: `20260917`
 
 Use specialized skills when the project context requires knowledge that should not live in this generic lifecycle skill.
@@ -30,5 +30,5 @@ Specialized skills must preserve ADSM's documentation projection model:
 - ordinary `*.md` files under `ctx/docs/**` are agent-facing operational context documents;
 - `*.skin.<lang>.md` files are human-facing semantic skins for matching agent documents;
 - nested subdirectories inside the four declarative documentation levels are allowed;
-- an adopted `ctx/docs/verification/` block remains cross-cutting; specifications use a primary declaration target rather than the mechanism or specialized skill that obtains evidence;
+- the mandatory `ctx/docs/verification/` boundary remains cross-cutting; specifications use a primary declaration target rather than the mechanism or specialized skill that obtains evidence;
 - visual, generated, rendered, and auxiliary artifacts belong under `ctx/assets/**`.

package/skills/adsm-ctx/templates/AGENTS.md

@@ -0,0 +1,19 @@
+# Root Level
+
+- Path: `AGENTS.md`
+- Template Version: `20261024`
+- Changed: `YYYYMMDD`
+
+## Boundary
+
+This file controls repository work. `ctx/` owns project meaning and is authoritative for product and implementation decisions; consult `ctx/AGENTS.md` and task-relevant context for design or code changes. If implementation conflicts with accepted context, follow the context and report any proposed change to accepted meaning for human approval rather than silently rewriting it. Read navigation documents only when needed and avoid rereading unchanged instructions within a session. Use the `adsm-ctx` skill when available for context lifecycle work.
+
+`ctx/` may be part of this repository or a separately mounted repository. Detect its Git boundary before editing, preserve separate histories, and never remove, replace, relocate, or unmount it. If absent, create `ctx/` only when bootstrap is within the assigned scope. Deeper `AGENTS.md` files refine local rules without overriding root invariants.
+
+A task may cover multiple repositories. Coordinate affected contracts and consumers, verify their integration, and keep each Git history separate. Do not expand into unrelated repositories. The human defines scope and approves changes to accepted meaning.
+
+## Efficient Execution
+
+Classify the task before reading context or running checks. Git-only work needs Git-state checks, not product-context scans or tests. For code or context changes, inspect only relevant owners; run deterministic checks chosen by changed responsibility and risk. Capture verbose output outside the model context and inspect logs on failure or when evidence is needed. Report results, omitted coverage, and material risks concisely.
+
+Do not modify, replace, delete, or relocate this file without explicit human instruction. Do not read, search, or expose secret-bearing files or credentials; non-secret examples may describe configuration shape. If a secret is accidentally exposed, do not repeat it; notify the human that it should be rotated or revoked.

package/skills/adsm-ctx/templates/ctx/AGENTS.md

@@ -0,0 +1,46 @@
+# Cognitive Context
+
+- Path: `ctx/AGENTS.md`
+- Template Version: `20261024`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This directory contains the project's cognitive context.
+
+`docs/` holds authoritative project definitions, `agent/` holds project-local agent operations, and `assets/` holds non-authoritative supporting materials.
+
+Keep generic ADSM methodology outside the project context.
+
+## Level Map
+
+- `agent/` — project-local agent and tool materials.
+- `assets/` — visual, generated, and auxiliary documentation assets.
+- `docs/` — authoritative project documentation and constraints.
+- `AGENTS.md` — context boundary and navigation rules.
+- `README.md` — introductory context information.
+- `adsm.json` — context metadata and versioning.
+
+## Level Boundary
+
+Defines:
+
+- The boundary of the project's cognitive context.
+- Separation of authoritative documentation, agent operations, and supporting assets.
+- Navigation to the appropriate context branch.
+
+Does NOT define:
+
+- Product, architecture, environment, or code meaning; these belong under `docs/`.
+- Project-local agent workflows; these belong under `agent/`.
+- Generic ADSM methodology; use the `adsm-ctx` skill when available.
+
+## Local Reading Map
+
+- For initial project orientation, read `docs/ai-intro.md` when needed.
+- For repository topology, consult `docs/filesystem.md`.
+- For product, architecture, environment, or code work, follow `docs/AGENTS.md` and read only task-relevant documentation.
+- For project-local agent operations, follow `agent/AGENTS.md`.
+- For context lifecycle work, use the `adsm-ctx` skill when available.
+
+Read `README.md` only when additional orientation is needed. Avoid rereading unchanged context within a session.

package/{skill → skills/adsm-ctx}/templates/ctx/README.md

@@ -15,7 +15,7 @@ Detailed ADSM validation and methodology rules are intentionally kept out of thi
 ## Entry Points
 
 - Read `AGENTS.md` for cognitive-context structure and governance rules.
-- Use skill `adsm-ctx` when you need ADSM validation, upgrade, or methodology guidance.
+- Use skill `adsm-ctx` when you need ADSM validation, evolution, or methodology guidance.
 - Read `docs/filesystem.md` for the top-level repository map.
 - Read `docs/` for declarative project documentation.
 - Read `agent/` only when working with repository-local agent operations or workflow assets.

package/{skill → skills/adsm-ctx}/templates/ctx/adsm.json

@@ -1,6 +1,6 @@
 {
   "schema": "adsm-context",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "capabilities": [
     "verification-layer"
   ],

package/skills/adsm-ctx/templates/ctx/agent/AGENTS.md

@@ -0,0 +1,32 @@
+# Agent Operations
+
+- Path: `ctx/agent/AGENTS.md`
+- Template Version: `20261024`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This branch holds project-specific operational materials used by agents and their tools, such as instructions, prompts, workflow definitions, reports, or tool documentation. These are optional examples, not required document types or directories.
+
+## Level Map
+
+- `AGENTS.md` — agent operations boundary and local navigation.
+
+## Level Boundary
+
+Defines:
+
+- The project-local home for organizing and performing authorized agent work.
+- A project-specific structure beneath this branch; only this file belongs to the reusable initialization baseline.
+
+Does NOT define:
+
+- Authoritative product, architecture, environment, or code declarations; these belong under `ctx/docs/`.
+- A standard workflow, tool choice, agent role, or required operational subdirectory.
+
+## Working Rules
+
+- Follow the applicable `AGENTS.md` hierarchy and task-relevant materials listed in the Level Map before acting.
+- Keep operational instructions consistent with accepted declarations in `ctx/docs/` and applicable supervision constraints. They cannot grant authority to change accepted meaning or bypass approval and escalation requirements; surface conflicts to the human.
+- Preserve existing project-specific materials. Add materials only for concrete project needs, without speculative directory scaffolding.
+- Keep the Level Map synchronized with the actual filesystem, listing directories first and sorting each group alphabetically. Follow local instructions in the relevant subdirectory.

package/skills/adsm-ctx/templates/ctx/docs/AGENTS.md

@@ -0,0 +1,64 @@
+# Project Documentation
+
+- Path: `ctx/docs/AGENTS.md`
+- Template Version: `20261024`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This directory contains authoritative project declarations and navigation documents.
+
+ADSM defines four ordered declarative levels: product → architecture → environment → code. Lower levels refine upstream meaning without redefining it. Accepted declarations constrain every valid implementation.
+
+A mandatory cross-cutting Verification Layer relates declarations to bounded observations of reality. It is not a fifth declarative level and does not establish independent authority over project meaning.
+
+## Level Map
+
+- `architecture/` — system structure, behavior, state ownership, and integration boundaries.
+- `code/` — implementation constraints and engineering conventions.
+- `environment/` — runtime conditions, infrastructure, and deployment constraints.
+- `product/` — product meaning, domain, roles, and expected outcomes.
+- `verification/` — durable verification specifications; cross-cutting, outside the authority chain.
+- `AGENTS.md` — documentation boundary and working rules.
+- `ai-intro.md` — initial project orientation for agents.
+- `filesystem.md` — top-level repository navigation.
+
+Keep this map aligned with the actual project structure. Add optional branches only when adopted.
+
+## Level Boundary
+
+Defines:
+
+- Accepted project declarations and their dependency order.
+- Rules for reading, refining, and maintaining declarative knowledge.
+- Boundaries between declarations, verification specifications, and supporting materials.
+
+Does NOT define:
+
+- Agent operations and workflows under `ctx/agent/`.
+- Executable product artifacts, runtime state, or operational evidence.
+- Generic ADSM methodology; use the `adsm-ctx` skill when available.
+
+## Local Reading Map
+
+- For unfamiliar projects, consult `ai-intro.md`.
+- For repository topology, consult `filesystem.md` when needed.
+- For project declarations, follow the relevant level's `AGENTS.md` and read its task-relevant documents.
+- For lower-level changes, consult the upstream declarations needed to establish their meaning and constraints.
+- For Verification Layer work, follow `verification/AGENTS.md`.
+- For context lifecycle, validation, audit, compression, or evolution, use the `adsm-ctx` skill when available.
+
+Avoid unnecessary full-context scans and repeated reading of unchanged documents.
+
+## Documentation Rules
+
+- Preserve the authority order: product → architecture → environment → code. Report missing or conflicting upstream meaning rather than inventing or silently changing it downstream.
+- Keep each durable declaration in its appropriate authoritative document. Preserve consistency across dependent levels.
+- Ordinary `*.md` documents are agent-facing and written in English by default. Optional `*.skin.<lang>.md` files provide human-facing semantic projections.
+- Before editing an agent document, read all matching skins. Preserve their meaning and invariants; report projection drift or required human decisions instead of silently resolving conflicts.
+- Keep documents explicit, focused, and maintainable. Preserve meaningful nested structure and do not sacrifice requirements or precision for brevity.
+- Keep each declarative level within nine direct directories and nine direct ordinary files where practical, excluding `AGENTS.md` and matching skins. Record intentional excess under `## Documentation Capacity Exception` in that level's `AGENTS.md`.
+- Require `verification/AGENTS.md`; the root may contain only this file. Create primary-target categories only for actual durable specifications.
+- Place verification specifications under their primary declarative targets and link secondary declarations. Keep specifications distinct from actual evidence and operational feedback state. Neither evidence nor assessments may redefine accepted meaning.
+- Keep visual, generated, rendered, and auxiliary artifacts under `ctx/assets/**`; they must not introduce authoritative project meaning.
+- Maintain `Path` and `Changed` attributes in stable documents. Delegate detailed methodology and lifecycle procedures to the `adsm-ctx` skill.

package/{skill → skills/adsm-ctx}/templates/ctx/docs/code/testing.md

@@ -14,4 +14,4 @@ List the main test layers, directories, and intended verification scope.
 
 ## Verification Target Boundary
 
-Keep executable test organization, framework conventions, fixtures, and isolation in this code-level document. When a project adopts `ctx/docs/verification/`, its durable specification states the observed declared expectation and primary target; the executable mechanism remains governed here.
+Keep executable test organization, framework conventions, fixtures, and isolation in this code-level document. When a project adds a durable specification under the mandatory `ctx/docs/verification/` boundary, that specification states the observed declared expectation and primary target; the executable mechanism remains governed here.

package/skills/adsm-ctx/templates/ctx/docs/verification/AGENTS.md

@@ -0,0 +1,31 @@
+# Verification Layer
+
+- Path: `ctx/docs/verification/AGENTS.md`
+- Changed: `20261024`
+
+## Purpose
+
+This mandatory cross-cutting boundary holds durable verification specifications. It is not a fifth declarative authority level. Product → architecture → environment → code remains the ordered hierarchy; humans control accepted meaning.
+
+## Level Map
+
+- `AGENTS.md` — verification boundary and local routing.
+
+## Navigation And Editing
+
+The root may contain only `AGENTS.md` when no specifications exist. Create `product/`, `architecture/`, `environment/`, or `code/` only when an actual durable specification belongs there. Route each specification by its primary declarative target, linking secondary targets rather than duplicating it. Preserve useful project-specific nesting and add local routing instructions as needed.
+
+Read applicable declarations and matching semantic skins before editing. Preserve traceability, applicability, interpretation bounds, and blind spots. Escalate conflicting accepted meaning to the human.
+
+## Level Boundary
+
+Defines:
+
+- The home and primary-target routing of durable verification specifications.
+- Specification applicability, traceability, and interpretation limits.
+
+Does NOT define:
+
+- A fifth declarative authority level or changes to accepted declarations.
+- Actual observations, evidence records, or operational feedback state; keep these outside this boundary.
+- Verification coverage or runtime correctness merely from structural conformance.

package/src/Init/Service.mjs

@@ -5,29 +5,8 @@
  * @description Initializes the baseline ADSM context structure in a target project directory.
  */
 
-const templateRoot = new URL("../../skill/templates/ctx/", import.meta.url);
-const rootAgentsTemplate = [
-  "# Root Level",
-  "",
-  "- Path: `AGENTS.md`",
-  "- Changed: `20260702`",
-  "",
-  "## Purpose",
-  "",
-  "Marks the repository root and points agents to the project cognitive context in `ctx/`.",
-  "",
-  "## Bootstrap Exception",
-  "",
-  "- `init` and other bootstrap operations may create the initial `ctx/` structure when it does not exist yet.",
-  "- This repository uses an ADSM-managed cognitive context.",
-  "- Use skill `adsm-ctx` for context validation, upgrades, and methodology rules.",
-  "",
-  "## Cognitive Context Entry",
-  "",
-  "- Read `ctx/AGENTS.md` before modifying project files after the context exists.",
-  "- Treat `ctx/` as the source of truth for project context after bootstrap is complete.",
-  "",
-].join("\n");
+const templateRoot = new URL("../../skills/adsm-ctx/templates/ctx/", import.meta.url);
+const rootAgentsTemplate = new URL("../../skills/adsm-ctx/templates/AGENTS.md", import.meta.url);
 
 export default class Service {
   /**
@@ -81,7 +60,7 @@ export default class Service {
 function ensureRootAgents({created, fs, pathService, projectRoot, skipped}) {
   const filePath = pathService.join(projectRoot, "AGENTS.md");
   if (!fs.existsSync(filePath)) {
-    fs.writeFileSync(filePath, rootAgentsTemplate);
+    fs.writeFileSync(filePath, fs.readFileSync(rootAgentsTemplate, "utf8").replaceAll("YYYYMMDD", new Date().toISOString().slice(0, 10).replaceAll("-", "")));
     created.push("AGENTS.md");
   } else {
     skipped.push("AGENTS.md");
@@ -127,10 +106,10 @@ function writeMetadata({created, fs, metadata, pathService, projectRoot, skipped
   }
 }
 
-export const __deps__ = Object.freeze({
+export const __deps__ = Object.freeze({default: Object.freeze({
   copyDirectory: "Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory$",
   fs: "node:fs",
   metadata: "Fl32_Skill_Adsm_Ctx_Shared_Metadata$",
   pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
   url: "node:url",
-});
+})});

package/src/Shared/Constants.mjs

@@ -8,7 +8,7 @@
 export default class Constants {
   constructor() {
     this.CONTEXT_SCHEMA = "adsm-context";
-    this.CONTEXT_VERSION = "0.2.0";
+    this.CONTEXT_VERSION = "0.5.0";
     this.VERIFICATION_CAPABILITY = "verification-layer";
     this.CONTEXT_CAPABILITIES = Object.freeze([this.VERIFICATION_CAPABILITY]);
     this.VERIFICATION_BLOCK = "verification";
@@ -23,6 +23,8 @@ export default class Constants {
       "ctx/docs/architecture",
       "ctx/docs/environment",
       "ctx/docs/code",
+      "ctx/docs/verification",
+      "ctx/docs/verification/AGENTS.md",
       "ctx/adsm.json",
       "ctx/AGENTS.md",
       "ctx/docs/AGENTS.md",

package/src/Skill/Installer.mjs

@@ -5,7 +5,7 @@
  * @description Installs the bundled skill payload into a target skills directory.
  */
 
-const sourceRoot = new URL("../../skill/", import.meta.url);
+const sourceRoot = new URL("../../skills/adsm-ctx/", import.meta.url);
 
 export default class Installer {
   /**
@@ -39,9 +39,9 @@ export default class Installer {
   }
 }
 
-export const __deps__ = Object.freeze({
+export const __deps__ = Object.freeze({default: Object.freeze({
   copyDirectory: "Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory$",
   fs: "node:fs",
   pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
   url: "node:url",
-});
+})});

package/src/Validate/Service.mjs

@@ -59,11 +59,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 +84,7 @@ export default class Validate {
       return {
         errorCount,
         findings,
-        metadata: metadataResult.ok ? metadataResult.metadata : null,
+        metadata: metadataResult.metadata,
         missingPaths,
         ok: errorCount === 0,
         projectRoot,
@@ -111,7 +122,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}`,
       ];
@@ -209,9 +221,11 @@ 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: ["0.1.0", "0.2.0", "0.3.0"].includes(parsed.version)
+          ? `Legacy schema ${parsed.version}; use skill adsm-ctx for agent-driven context evolution. Target schema: ${constants.CONTEXT_VERSION}.`
+          : `Unsupported metadata version: ${parsed.version}; investigate with skill adsm-ctx before changing schema metadata.`,
         path: "ctx/adsm.json",
         ruleId: "metadata-version",
         severity: "error",
@@ -252,7 +266,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"}`,
@@ -424,7 +438,7 @@ 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
@@ -529,15 +543,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};
 }
 
@@ -830,8 +835,58 @@ function normalizeRelativeSegments(parts) {
   return result;
 }
 
-export const __deps__ = Object.freeze({
+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$",
-});
+})});
+
+/** Checks context-side routing sections; root repository instructions have a separate shape. */
+function inspectAgentsHierarchy({fs, pathService, projectRoot}) {
+  const findings = [];
+  const root = pathService.join(projectRoot, "ctx");
+  if (!fs.existsSync(root)) return findings;
+  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;
+}

package/types.d.ts

@@ -1,17 +1,13 @@
 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_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_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_Init_Service = import("./src/Init/Service.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Shared_Constants = 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_Metadata = import("./src/Shared/Metadata.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Shared_Path = 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_Validate_Service = import("./src/Validate/Service.mjs").default;
 }
 

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.