@flancer32/skill-adsm-ctx 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.5.0 — 2026-10-24
+
+- Adopt context schema `0.5.0`: require five documentation directories, including the cross-cutting Verification Layer, while preserving four ordered declarative levels. Allow an AGENTS-only verification root without placeholder specifications.
+- Define agent-driven context evolution across historical states, preserving project meaning and semantic skins. Remove CLI `upgrade` and `design`; the approved CLI commands are `init`, `validate`, and `install-skill`.
+- Keep package and schema versioning independent. Package installation never evolves existing context or promotes its metadata; record the target schema only after agent-led conformance and semantic review.
+- Consolidate the complete skill payload under `skills/adsm-ctx/`. Move optional report and semantic-skin patterns into `assets/`; remove obsolete `templates/ai/` and `templates/work/` and reserve templates for initialization.
+- Document explicit Git SSH package installation followed by `adsm-ctx install-skill <skills-root>` after each update. Keep npm installation free of lifecycle hooks and automatic agent-directory writes.
+- Initialize the canonical context and root instructions without overwriting existing files. Refine the Agent Operations boundary, navigation, and supervision guidance without imposing project-specific workflows.
+- Improve read-only validation of verification structure, context-side AGENTS sections, and documentation navigation. Align repository documentation, semantic skins, and durable verification contracts.
+- Add CI on Node.js 20 and 24, complete-payload archive and isolated installation checks, version-independence coverage, and whole-context preservation checks.
+
 ## 0.4.0 - 2026-09-23
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@ Build and evolve project cognitive context for Agent-Driven Software Management
 
 ## Overview
 
-`@flancer32/skill-adsm-ctx` is an ADSM skill package for initializing, designing, validating, auditing, compressing, and upgrading project cognitive context.
+`@flancer32/skill-adsm-ctx` is an ADSM skill package for initializing, designing, validating, auditing, compressing, and evolving project cognitive context.
 
 It manages the lifecycle of project context as its primary object. It does not define business requirements, backend architecture, browser architecture, deployment logic, or domain-specific documentation on its own.
 
@@ -15,8 +15,8 @@ The package includes:
 - the `adsm-ctx` CLI for lifecycle operations;
 - the `adsm-ctx` skill payload for AI agents;
 - reusable `ctx/` templates for bootstrapping ADSM-compatible projects;
-- optional Verification Layer documentation lifecycle support;
-- working templates for agent-produced reports.
+- mandatory Verification Layer documentation lifecycle support;
+- supporting assets for agent-produced reports.
 
 ## Purpose
 
@@ -27,10 +27,10 @@ Use this package when you need to:
 - validate whether an existing context follows expected ADSM structure;
 - audit a documentation corpus against ADSM documentation quality criteria;
 - compress a documentation corpus while preserving accepted project meaning;
-- upgrade a context when ADSM conventions evolve;
-- design, validate, audit, or compress an optional cross-cutting Verification Layer.
+- evolve a context using the skill when ADSM conventions change;
+- design, validate, audit, or compress a mandatory cross-cutting Verification Layer.
 
-This package acts as an orchestration layer. It provides generic structure, lifecycle guidance, validation, documentation quality audit guidance, documentation compression guidance, and upgrade entry points. When project-specific context is required, it should direct the agent to use specialized skills when they are available.
+This package acts as an orchestration layer. It provides generic structure, lifecycle guidance, validation, documentation quality audit guidance, documentation compression guidance, and agent-driven evolution guidance. When project-specific context is required, it should direct the agent to use specialized skills when they are available.
 
 The bundled baseline now covers both:
 
@@ -46,7 +46,7 @@ This package does not:
 - write domain-specific architecture content as if it knew the project;
 - perform automatic semantic scoring or correction of documentation quality;
 - change project meaning during documentation compression;
-- perform destructive upgrades without explicit review.
+- change accepted meaning without explicit review.
 
 ## Requirements
 
@@ -55,18 +55,15 @@ This package does not:
 
 ## Installation And Update
 
-Install the package globally once for the current user:
-
-```sh
-npm install --global @flancer32/skill-adsm-ctx
-```
-
-Install its matching agent payload into the selected skills root:
+Install the package and then explicitly install its matching agent payload:
 
 ```sh
+npm install --global git+ssh://git@github.com/flancer32/skill-adsm-ctx.git
 adsm-ctx install-skill "$HOME/.agents/skills"
 ```
 
+The second command is required after every package installation or update. npm installs only the package, dependencies, and CLI; it does not select a skills directory or modify agent configuration. Supply another skills root if your agent uses a different location.
+
 The command replaces only `$HOME/.agents/skills/adsm-ctx`; it does not modify other installed skills.
 
 Verify the runtime and payload:
@@ -79,11 +76,11 @@ test -f "$HOME/.agents/skills/adsm-ctx/SKILL.md"
 To update, update the global npm package and reinstall its payload:
 
 ```sh
-npm update --global @flancer32/skill-adsm-ctx
+npm install --global git+ssh://git@github.com/flancer32/skill-adsm-ctx.git
 adsm-ctx install-skill "$HOME/.agents/skills"
 ```
 
-The npm package is the canonical distribution of both artifacts. Its public `adsm-ctx` launcher runs the package as an explicit TeqFW host; the `install-skill` command copies the version-matched `skill/` bundle. Do not copy only `SKILL.md` manually: the payload also needs its references and templates.
+The npm package is the canonical distribution of both artifacts. Its public `adsm-ctx` launcher runs the package as an explicit TeqFW host; the `install-skill` command copies the version-matched `skills/adsm-ctx/` bundle. Do not copy only `SKILL.md` manually: the payload also needs its references and templates.
 
 For a project-pinned CI or team workflow, install the package locally and invoke the same public launcher with npm:
 
@@ -106,12 +103,6 @@ Initialize a context in the current directory:
 adsm-ctx init
 ```
 
-Design guidance for a project context:
-
-```sh
-adsm-ctx design
-```
-
 Validate an existing project context:
 
 ```sh
@@ -124,11 +115,7 @@ Validate a specific path:
 adsm-ctx validate <project-root>
 ```
 
-Run the upgrade entry point:
-
-```sh
-adsm-ctx upgrade
-```
+For existing contexts, ask the agent to use skill `adsm-ctx` and its evolution procedure. There is no CLI evolution command.
 
 Install the bundled skill payload:
 
@@ -146,15 +133,15 @@ teq --host @flancer32/skill-adsm-ctx adsm-ctx:validate .
 
 ### `init`
 
-Creates the minimal ADSM-compatible context structure, starter documents, and `ctx/adsm.json` metadata. The metadata advertises the `verification-layer` convention capability, but initialization does not create `ctx/docs/verification/` or empty categories.
+Creates the minimal ADSM-compatible context structure, starter documents, and `ctx/adsm.json` metadata. Schema `0.5.0` creates all five documentation directories, including `ctx/docs/verification/AGENTS.md`, without empty target categories or placeholder specifications.
 
 ### `design`
 
-Provides guidance for classifying the project, choosing relevant documentation branches, and identifying when specialized ADSM skills should be used.
+The agent uses the skill questionnaire to classify the project, choose relevant documentation branches, and identify specialized skills. This is a skill mode, not a CLI command.
 
 ### `validate`
 
-Checks baseline paths, required declarative documentation levels, optional Verification Layer structure when adopted, required `AGENTS.md` files, metadata, body/skin pairing, localized skin names, redundant `Agent Document` sections in skins, local markdown document links, and other formal structural projection checks. It does not score semantic-skin length, cognitive load, or human readability; those belong to `quality-audit`. Validation reports findings without modifying project content.
+Checks baseline paths, required declarative documentation levels, mandatory Verification Layer structure, required `AGENTS.md` files, metadata, body/skin pairing, localized skin names, redundant `Agent Document` sections in skins, local markdown document links, and other formal structural projection checks. It does not score semantic-skin length, cognitive load, or human readability; those belong to `quality-audit`. Validation reports findings without modifying project content.
 
 ### `quality-audit`
 
@@ -168,21 +155,21 @@ Guides an agent through controlled rewrite of a documentation corpus to reduce s
 
 The default compression corpus is `ctx/docs/`. Operational context such as `ctx/agent/`, workflow configuration, prompt assets, generated reports, and runtime materials is outside the default corpus unless explicitly requested.
 
-### `upgrade`
+### Agent-driven evolution
 
-Checks whether context metadata exists and reports that no automatic migrations are available. Verification Layer adoption remains optional and non-destructive: upgrade does not create verification scaffolding. The command remains the entry point for future explicit migrations.
+Use [the skill evolution procedure](skills/adsm-ctx/references/context-evolution.md) for existing contexts, including unknown historical states. The agent follows discover → interpret → compare → plan → evolve → validate → finalize, preserving accepted meaning and semantic skins. Humans decide changes to accepted meaning and authority. CLI `validate` supplies deterministic findings; there is no evolution command or automatic schema promotion. The agent records target schema `0.5.0` only after structural checks and semantic review succeed, then validates again. npm versioning remains independent.
 
 ## Workflow
 
 Recommended sequence:
 
 1. Run `adsm-ctx init` in a new project repository.
-2. Run `adsm-ctx design` to shape the context for the actual project.
+2. Ask the agent to use the skill’s design questionnaire to shape the context for the actual project.
 3. Use specialized skills where the project needs domain-specific documentation.
 4. Run `adsm-ctx validate` as the deterministic preflight as the context evolves.
 5. Use the skill's `quality-audit` mode only after structural validation passes or leaves warnings only.
 6. Use the skill's `documentation-compression` mode when accepted documentation meaning is stable but the corpus has high attention cost.
-7. Run `adsm-ctx upgrade` when template conventions or schema versions change.
+7. Use the skill evolution procedure when conventions change; CLI validation supplies read-only structural findings.
 
 ## Documentation Levels
 
@@ -197,7 +184,7 @@ product
 
 Use the architecture level once product meaning is clear enough to define stable engineering guardrails.
 
-`ctx/docs/verification/` is optional and cross-cutting. It is not a fifth declarative level. Create it only when a durable verification specification exists; place that specification below the category of the declaration it primarily evaluates.
+`ctx/docs/verification/` is mandatory and cross-cutting in schema `0.5.0`. It is not a fifth declarative level. Its root may contain only `AGENTS.md`; create primary-target categories only when durable specifications exist; place that specification below the category of the declaration it primarily evaluates.
 
 The bundled architecture templates expect these top-level documents:
 
@@ -230,11 +217,11 @@ For `AGENTS.md` authoring, `Level Boundary` sections should stay compact and gua
 
 The CLI performs local filesystem operations and structural validation.
 
-The skill in `skill/SKILL.md` instructs an AI agent how to use the lifecycle modes, how to avoid inventing project content, how to audit documentation quality, how to compress documentation without changing meaning, and how to route documentation work toward specialized skills when needed.
+The skill in `skills/adsm-ctx/SKILL.md` instructs an AI agent how to use the lifecycle modes, how to avoid inventing project content, how to audit documentation quality, how to compress documentation without changing meaning, and how to route documentation work toward specialized skills when needed.
 
-Documentation quality audit uses `skill/references/documentation-quality-audit.md` and the working report template at `skill/templates/work/report/documentation-quality-audit.md`.
+Documentation quality audit uses `skills/adsm-ctx/references/documentation-quality-audit.md` and the report asset at `skills/adsm-ctx/assets/report/documentation-quality-audit.md`.
 
-Documentation compression uses `skill/references/documentation-compression.md` and the working report template at `skill/templates/work/report/documentation-compression.md`.
+Documentation compression uses `skills/adsm-ctx/references/documentation-compression.md` and the report asset at `skills/adsm-ctx/assets/report/documentation-compression.md`.
 
 The skill does not directly invoke other skills. It instructs the agent to select and use them when relevant.
 
@@ -262,7 +249,7 @@ npm test
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for the prepared, unpublished 0.4.0 release notes.
+See [CHANGELOG.md](CHANGELOG.md) for the dated release notes.
 
 ## Status
 
@@ -271,3 +258,19 @@ This repository contains a working skeleton intended as a foundation for future
 ## License
 
 Apache-2.0
+
+## Versioning And Compatibility
+
+Release `0.5.0` uses npm package `0.5.0` and context schema `0.5.0`. These numbers have independent responsibilities: the package versions CLI, validator, skill, templates, and fixes; the schema versions accepted context conventions. Package `0.5.1` may fix a validator while retaining schema `0.5.0`, requiring no context evolution.
+
+`adsm-ctx --version` identifies the installed npm package. Read `ctx/adsm.json` for a project's schema; `adsm-ctx validate <project-root>` reports recorded and supported schema versions. Compatibility follows supported requirements, not numerical equality. Current validation supports schema `0.5.0`; older labels receive evolution guidance and unknown versions require investigation.
+
+Installing or updating the package and explicitly reinstalling its skill do not promote project metadata. An agent compares actual context with the installed skill's target conventions and evolves directly when needed, preserving project meaning and skins. Humans approve changes to accepted meaning. Only after conformance and semantic review does the agent record the target schema; no intermediate CLI migrations are required.
+
+## Continuous Integration
+
+GitHub Actions runs `.github/workflows/ci.yaml` for pushes and pull requests to `main`, and on manual dispatch. Ubuntu jobs use Node.js 20 (minimum) and 24 (LTS), run `npm ci`, `npm test`, context validation, and `npm pack --dry-run`.
+
+Package tests install a real npm archive into an isolated temporary environment, exercise the installed CLI and skill installer, compare the complete payload, and preserve neighboring skills. In CI the installation test uses network-enabled dependency resolution and fails on errors instead of skipping for missing offline cache. Local offline runs may report a skip; that is incomplete installation evidence. CI does not publish packages or prove semantic correctness of project documentation.
+
+Skill resources are separated by purpose: `references/` provides guidance; `templates/AGENTS.md` and `templates/ctx/` feed deterministic, non-destructive initialization; `assets/` provides agent report and semantic-skin patterns. `init` does not copy skill assets into projects. Asset locations do not prescribe output locations; project authority and the task do. Skill assets are distinct from project-owned `ctx/assets/`.

package/bin/adsm-ctx.mjs

@@ -11,7 +11,7 @@ const require = createRequire(import.meta.url);
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const teqPath = require.resolve("@teqfw/cli/bin/teq.mjs");
 const hostName = "@flancer32/skill-adsm-ctx";
-const commandNames = new Set(["init", "design", "validate", "upgrade", "install-skill"]);
+const commandNames = new Set(["init", "validate", "install-skill"]);
 
 const args = normalizeArgs(processModule.argv.slice(2));
 const result = spawnSync(processModule.execPath, [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flancer32/skill-adsm-ctx",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Build and evolve project cognitive context for Agent-Driven Software Management (ADSM).",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,10 +9,9 @@
   },
   "types": "types.d.ts",
   "files": [
-    "skill/",
+    "skills/",
     "bin/",
     "src/",
-    "migrations/",
     "jsconfig.json",
     "README.md",
     "LICENSE",
@@ -25,13 +24,12 @@
   "scripts": {
     "start": "adsm-ctx",
     "init": "adsm-ctx init",
-    "design": "adsm-ctx design",
     "validate": "adsm-ctx validate",
-    "upgrade": "adsm-ctx upgrade",
     "install:skill": "adsm-ctx install-skill \"$HOME/.agents/skills\"",
     "test:unit": "find test/unit -name '*.test.mjs' -print0 | xargs -0 -r node --test",
     "test:integration": "find test/integration -name '*.test.mjs' -print0 | xargs -0 -r node --test",
-    "test": "npm run test:unit && npm run test:integration"
+    "test:package": "node --test test/package/*.test.mjs",
+    "test": "npm run test:unit && npm run test:integration && npm run test:package"
   },
   "dependencies": {
     "@teqfw/cli": "^2.2.0",
@@ -56,24 +54,12 @@
             "arguments": [{"name": "target-path", "kind": "string", "description": "Project root; defaults to the current working directory."}],
             "component": "Fl32_Skill_Adsm_Ctx_Cli_Command_Init$"
           },
-          {
-            "id": "adsm-ctx:design",
-            "summary": "Show ADSM context design guidance.",
-            "arguments": [{"name": "target-path", "kind": "string", "description": "Project root; defaults to the current working directory."}],
-            "component": "Fl32_Skill_Adsm_Ctx_Cli_Command_Design$"
-          },
           {
             "id": "adsm-ctx:validate",
             "summary": "Validate an ADSM context.",
             "arguments": [{"name": "target-path", "kind": "string", "description": "Project root; defaults to the current working directory."}],
             "component": "Fl32_Skill_Adsm_Ctx_Cli_Command_Validate$"
           },
-          {
-            "id": "adsm-ctx:upgrade",
-            "summary": "Upgrade an ADSM context.",
-            "arguments": [{"name": "target-path", "kind": "string", "description": "Project root; defaults to the current working directory."}],
-            "component": "Fl32_Skill_Adsm_Ctx_Cli_Command_Upgrade$"
-          },
           {
             "id": "adsm-ctx:install-skill",
             "summary": "Install the bundled agent skill payload.",

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use when initializing, designing, validating, auditing, compressing, or evolving 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
@@ -26,12 +26,14 @@ Humans own direction, accepted meaning, approval, and accountability. Agents ref
 | `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. |
+| Evolution | Follow [the agent evolution procedure](references/context-evolution.md): discover, interpret, compare, plan, evolve, validate, finalize. The agent applies authorized changes; deterministic validation never rewrites context or promotes metadata. |
 | `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.
+`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. npm installation never installs the skill into an agent directory; run this command explicitly after each package installation or update.
+
+Context design is performed by the agent using the questionnaire and references; there is no CLI `design` command.
 
 ## Non-Negotiable Boundaries
 
@@ -40,9 +42,23 @@ Humans own direction, accepted meaning, approval, and accountability. Agents ref
 - 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.
+- Preserve the four ordered declarative documentation levels under `ctx/docs/`: `product`, `architecture`, `environment`, and `code`. Require the cross-cutting `verification/` boundary 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`.
 
+## Evolution Authority
+
+The existing context supplies accepted project meaning; this installed skill supplies target ADSM conventions. Evolution is agent reasoning across arbitrary historical states, not an autonomous version migration. Humans control changes to accepted meaning and authority. The agent updates schema metadata only after target conformance checks and semantic consistency review succeed.
+
 ## 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.
+Finish with explicit validation results, Verification Layer structure and specification presence when relevant, specialization gaps, human decisions, and any preserved project-specific content. Use `templates/AGENTS.md` and `templates/ctx/` for initialization; use skill `assets/` only for authorized agent-guided document or report work.
+
+The current target is schema `0.5.0`. npm package updates and context evolution are separate: package patches may retain the same supported schema. Inspect project metadata and actual conformance against this installed skill; never infer compatibility or promote metadata from package-version equality. See [context evolution](references/context-evolution.md) for the decision procedure.
+
+## Resource Ownership
+
+- `references/` contains methodology, instructions, and agent guidance.
+- `templates/AGENTS.md` and `templates/ctx/` are the deterministic, non-destructive project initialization sources.
+- `assets/` contains supporting [semantic-skin patterns](assets/context/semantic-skin.md), [audit report patterns](assets/report/documentation-quality-audit.md), and [compression report patterns](assets/report/documentation-compression.md). Initialization never copies them into a project. Use them for authorized work; choose the resulting document's location from project rules and the task, not from the asset path.
+
+Skill `assets/` belongs to this skill payload. Project `ctx/assets/` belongs to the managed project's context and holds visual, generated, or auxiliary artifacts. Ownership and purpose distinguish these boundaries; semantic skins themselves belong beside their agent documents under project documentation.

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

@@ -1,6 +1,6 @@
 # AGENTS Hierarchy
 
-- Path: `skill/references/agents-hierarchy.md`
+- Path: `skills/adsm-ctx/references/agents-hierarchy.md`
 - Changed: `20260715`
 
 This reference operationalizes `AGENTS.md` handling for ADSM contexts.

package/skills/adsm-ctx/references/context-evolution.md

@@ -0,0 +1,55 @@
+# Agent-Driven Context Evolution
+
+- Path: `skills/adsm-ctx/references/context-evolution.md`
+- Changed: `20261024`
+
+Evolution brings an existing cognitive context into conformance with the installed skill's target conventions through agent inspection and reasoning. The starting point is the actual context, not an assumed version-to-version file transformation. Use this procedure for methodology, organization, authority relationships, projection rules, and schema changes, including contexts predating known schema versions. Evolution is a skill-guided agent activity and has no CLI command.
+
+## Target And Responsibilities
+
+The current target is context schema `adsm-context` version `0.5.0`, independent of the npm package version. Require five documentation directories: `product/`, `architecture/`, `environment/`, `code/`, and `verification/`, each with `AGENTS.md`. Exactly four form the ordered hierarchy product → architecture → environment → code. The cross-cutting verification root may contain only `AGENTS.md`; create primary-target categories only for actual durable specifications. Keep specifications distinct from observations, evidence records, and operational feedback state. Use [document-projections.md](document-projections.md) for projection, links, assets, and capacity conventions.
+
+The skill defines target conventions and this procedure. The agent interprets the existing context, compares, applies authorized changes, checks consistency, and finalizes metadata. CLI `init` creates missing baseline files, including verification routing and initial metadata, without overwriting existing files. CLI `validate` is read-only: it never creates verification files, replaces documents, changes skins, or promotes metadata. There is no CLI evolution command. Humans control accepted project meaning, authority, and approval of changes beyond the agent's existing authorization.
+
+## 1. Discover
+
+Inspect applicable `AGENTS.md` instructions, the existing context and metadata, filesystem types, Git boundaries, and current worktree changes. Identify separately mounted `ctx/` and keep each history in place. Do not remove, replace, relocate, or unmount it. Do not traverse unrelated repositories or secret-bearing files. Resolve unsafe links, nested repository ownership, or missing permissions before editing affected paths.
+
+Read `ctx/adsm.json` and compare it with the target conventions above. Run `adsm-ctx validate <project-root>` for deterministic findings; validation does not evolve anything. Missing, malformed, unknown, or future metadata is an investigation finding, not permission to relabel the context or initialize over it.
+
+## 2. Interpret
+
+Locate authoritative product intent, architecture decisions and rationale, environment assumptions, implementation constraints, and all matching semantic skins. Read skins before changing their agent documents. Separate durable declarations and specifications from evidence and operational state. Retain project-specific knowledge, nested organization, and relevant historical decisions. Consult [semantic-skins.md](semantic-skins.md) for controlled projections and [specialized-skills.md](specialized-skills.md) when a branch needs specialized interpretation.
+
+## 3. Compare
+
+Compare actual structure and meaning with current target conventions, even when the recorded version is unknown or already `0.5.0`. Inventory structural, documentary, projection, and authority differences. Run `adsm-ctx validate <project-root>` and distinguish mechanical findings from semantic inconsistencies. A current version is not proof of conformance; green structure does not establish semantic correctness, verification coverage, or runtime correctness.
+
+For example, `0.1.0` and `0.2.0` may lack `verification/AGENTS.md` or describe verification as optional. Inspect their actual documents instead of applying a fixed replacement. Unknown historical layouts require investigation and explicit reporting of what cannot yet be interpreted safely.
+
+## 4. Plan
+
+Classify proposed changes as structural, editorial, semantic, or requiring human approval. Identify the authoritative owner and dependent documents for each change. Establish product meaning before architecture, then environment and code; include matching projections and local routing. Use existing authorization for routine structural or editorial changes that preserve meaning. Escalate when target conventions conflict with an accepted project decision, a skin invariant, or authority relationships. Do not treat a newer generic template as permission to override accepted meaning. Keep unresolved decisions explicit and leave affected changes pending.
+
+## 5. Evolve
+
+Apply authorized changes in documentation dependency order. Add missing required boundaries from canonical templates only after inspecting the destination; adapt routing to the actual project instead of replacing custom instructions. For `0.5.0`, add missing `verification/AGENTS.md`, update the documentation Level Map, and reconcile optional-adoption wording with accepted declarations and skins. Preserve existing specifications and project directories; create no placeholder specifications or empty target categories.
+
+Restructure or clarify only within authorization. Preserve intent, constraints, rationale, history, and projection meaning. Update linked consumers when moving a document and preserve one canonical authority home. Use deterministic helpers only for bounded, agent-selected operations; they do not decide semantic changes. Reinspect on partial failure, report completed work and unresolved differences, and preserve the previous schema label while work remains incomplete.
+
+## 6. Validate
+
+Run deterministic validation and inspect every error and warning. Assess semantic consistency across declarations, decisions, projections, and local instructions separately. Confirm preserved project-specific knowledge and correct Git boundaries. If the context still bears a known older schema label, the validator's version finding is expected: establish that all other target requirements pass before promotion. Never ignore malformed metadata, unknown-version ambiguity, or unresolved semantic conflicts as merely a version mismatch. Obtain required human decisions before finalizing.
+
+## 7. Finalize
+
+Only after target structural requirements and semantic consistency are satisfied, update `ctx/adsm.json` to version `0.5.0`, preserving meaningful metadata fields. A version edit records successful evolution; it does not perform it. Do not promote partially evolved contexts. Run validation again against the final metadata; investigate any failure and retain or restore the prior label if conformance is not established. Do not overwrite an unknown future schema based on this package's older target conventions.
+
+Report changes and rationale, preserved content, deterministic results, semantic review scope and limits, remaining warnings, human decisions, and relevant Git histories. On a repeat request, compare the actual state again and make only necessary authorized changes. Repeated CLI validation remain read-only regardless of context state.
+
+
+## Package Updates And Schema Compatibility
+
+A package update replaces the npm implementation; explicitly rerun `adsm-ctx install-skill <skills-root>` to replace its bundled agent guidance. This does not change any context schema metadata and does not imply context evolution is required. Schema versions describe accepted context conventions; package versions describe implementation releases. Package `0.5.1` may support schema `0.5.0` unchanged. Never infer compatibility from numerical equality.
+
+Read the current schema from the project's `ctx/adsm.json`; identify this installed skill's target from Target Conventions above, not the npm version shown by `adsm-ctx --version`. Compare actual context with those conventions and use `validate` to check recorded and supported schema labels plus structural findings. If already conforming to the same schema, no evolution is needed merely because the package changed. Classify structural repairs separately from semantic changes; use the seven phases above for needed evolution and obtain human approval for changes to accepted meaning or authority. Older or intermediate labels, including `0.3.0`, do not require sequential migrations; investigate actual state and evolve directly toward the understood target. Never relabel an older context based solely on package installation.

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

@@ -1,7 +1,7 @@
 # Context Lifecycle
 
-- Path: `skill/references/context-lifecycle.md`
-- Changed: `20260917`
+- Path: `skills/adsm-ctx/references/context-lifecycle.md`
+- Changed: `20261024`
 
 `adsm-ctx` manages six lifecycle modes for project cognitive context.
 
@@ -13,26 +13,33 @@ The skill manages generic lifecycle structure. It does not define a project's bu
 
 - `init` creates the baseline. Create the root `AGENTS.md`, `ctx/` baseline, starter documents, and `ctx/adsm.json` only where they are missing. Use `templates/ctx/`; create placeholders rather than project facts when context is unknown.
 - `design` shapes context for the actual project. Classify the project, choose justified generic branches and nested structure, decide whether semantic skins are needed, and route specializations. Use [design-questionnaire.md](design-questionnaire.md) and [specialized-skills.md](specialized-skills.md).
-- `validate` checks formal structural integrity without destructive edits. Check baseline paths, context metadata, the four declarative documentation levels, optional Verification Layer adoption, local `AGENTS.md` placement, document headers, agent/skin pairs, reversible skin naming, redundant `Agent Document` sections, local document links, and `ctx/assets/**` exclusion. Do not score semantic compactness, cognitive load, or word counts.
+- `validate` checks formal structural integrity without destructive edits. Check baseline paths, context metadata, the four declarative documentation levels, mandatory Verification Layer structure, local `AGENTS.md` placement, document headers, agent/skin pairs, reversible skin naming, redundant `Agent Document` sections, local document links, and `ctx/assets/**` exclusion. Do not score semantic compactness, cognitive load, or word counts.
 - `quality-audit` guides semantic documentation review. It is report-only by default; use [documentation-quality-audit.md](documentation-quality-audit.md) after validation.
 - `documentation-compression` guides controlled documentation rewrite that preserves accepted meaning. Use [documentation-compression.md](documentation-compression.md); do not treat it as an automatic semantic rewrite.
-- `upgrade` is the non-destructive migration entry point. The current implementation checks for metadata and reports that no automatic migrations are available; preserve project-specific content and use [upgrade-policy.md](upgrade-policy.md) when explicit migrations exist.
+- Evolution is agent-driven context interpretation and authorized change across historical states, methodology, organization, authority, and projections. Follow [the evolution procedure](context-evolution.md). There is no evolution CLI command; use `validate` for deterministic findings.
 
-The lifecycle is iterative. A project may return to `design`, `validate`, `quality-audit`, `documentation-compression`, and `upgrade` many times after initialization.
+The lifecycle is iterative. A project may return to `design`, `validate`, `quality-audit`, `documentation-compression`, and evolution many times after initialization.
 
 `quality-audit` is an agent-guided mode. It is not a CLI semantic scoring command.
 
 `documentation-compression` is an agent-guided rewrite mode. It is not a CLI semantic scoring command and must not change project meaning.
 
-The package-level `adsm-ctx install-skill <skills-root>` command installs the version-matched skill payload into an agent skills root.
+The package-level `adsm-ctx install-skill <skills-root>` command installs the version-matched skill payload into an explicitly supplied agent skills root. After installation or update, run:
+
+```sh
+npm install --global git+ssh://git@github.com/flancer32/skill-adsm-ctx.git
+adsm-ctx install-skill "$HOME/.agents/skills"
+```
+
+The second command is required; npm lifecycle hooks do not install or update agent skills.
 
 It is not a context lifecycle mode.
 
 All lifecycle modes that operate on `ctx/docs/` use the documentation projection model in [document-projections.md](document-projections.md).
 
-The lifecycle must preserve ADSM's four ordered declarative documentation levels under `ctx/docs/` while allowing project-specific nested subdirectories inside them and an optional cross-cutting Verification Layer as defined in [document-projections.md](document-projections.md).
+The lifecycle must preserve ADSM's four ordered declarative documentation levels under `ctx/docs/` while allowing project-specific nested subdirectories inside them and a mandatory cross-cutting Verification Layer as defined in [document-projections.md](document-projections.md).
 
-Validation, audit, compression, and upgrade work must recognize agent documents, semantic skins, agent/skin pairs, orphan skins, projection drift, and `ctx/assets/**` as non-authoritative artifact space.
+Validation, audit, compression, and evolution work must recognize agent documents, semantic skins, agent/skin pairs, orphan skins, projection drift, and `ctx/assets/**` as non-authoritative artifact space.
 
 When a repository provides a deterministic validation command, validation work must discover and run it. Report errors and warnings separately; warning-only output is not a clean result. Clear structural errors before a quality audit.
 
@@ -49,7 +56,7 @@ The Software Evolution Loop is broader than Verification. Architecture defines b
 - Establish product meaning before architecture, then architecture before environment or code constraints. Lower levels refine but do not create upstream meaning.
 - Keep `ctx/docs/filesystem.md` limited to root-level repository navigation. Describe lower structure only in the appropriate local `AGENTS.md` files.
 - Preserve project-local materials under `ctx/agent/`; this skill defines only its boundary `AGENTS.md` and never invents tool instructions, workflows, labels, events, prompts, profiles, or agent roles.
-- Use only `product/`, `architecture/`, `environment/`, and `code/` as ordered ADSM declarative levels. `verification/` may be an optional cross-cutting documentation block, never a fifth level; nested structure remains project-specific.
+- Use only `product/`, `architecture/`, `environment/`, and `code/` as ordered ADSM declarative levels. `verification/` is a mandatory cross-cutting documentation block, never a fifth level; nested structure remains project-specific.
 - Keep each documentation level within nine direct directories and nine direct ordinary files, excluding `AGENTS.md` and paired `*.skin.<lang>.md` files, where practical. When a level deliberately exceeds either value, its local `AGENTS.md` must explicitly record a `Documentation Capacity Exception` and the reason.
 - Place visual, generated, rendered, and auxiliary artifacts under `ctx/assets/**`; they cannot introduce authoritative project meaning.
 - Read a matching semantic skin before changing its agent document. Report projection drift or a required human decision when a change would alter skin-controlled meaning.
@@ -59,3 +66,7 @@ The Software Evolution Loop is broader than Verification. Architecture defines b
 Use the baseline architecture branch to translate accepted product intent into stable engineering structure. Typical template documents are `overview.md`, `structure.md`, `behavior.md`, `state.md`, `integration.md`, `constraints.md`, `checklists.md`, `decisions.md`, and `supervision.md`.
 
 Refine those documents or add justified nested structure, but do not introduce architectural owners, durable state, external integrations, system boundaries, or product behavior without the required upstream documentation and human approval. When architecture exposes a load-bearing product capability, invariant, or authority boundary absent from product documentation, update the product layer first or report the gap. Prefer updating documentation before code when a new architectural concept appears.
+
+Package updates replace implementation and explicitly installed skill files; context evolution changes a project toward supported conventions. These are separate operations. A package-only update requires no evolution when the context already conforms to the supported schema; compare project metadata and actual requirements using [context evolution](context-evolution.md).
+
+Design is agent-performed guidance using the questionnaire and specialized-skill routing; no CLI design command is provided.

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

@@ -1,7 +1,7 @@
 # Design Questionnaire
 
-- Path: `skill/references/design-questionnaire.md`
-- Changed: `20260917`
+- Path: `skills/adsm-ctx/references/design-questionnaire.md`
+- Changed: `20261024`
 
 Use this questionnaire at the start of `design` mode to classify the project and decide which specialized ADSM skills may be relevant.
 
@@ -53,4 +53,4 @@ Use this questionnaire at the start of `design` mode to classify the project and
 
 ## Verification Design Guidance
 
-Do not create `ctx/docs/verification/` merely because these questions were asked. When a durable specification is justified, place it under the category of its primary declaration target, link secondary targets instead of duplicating it, and route concrete test execution, monitoring, signal transport, or distributed feedback work to a specialized skill or project-local design.
+Keep the mandatory `ctx/docs/verification/AGENTS.md` boundary even when no specifications are justified. Asking these questions does not justify creating target categories or placeholder specifications. When a durable specification is justified, place it under the category of its primary declaration target, link secondary targets instead of duplicating it, and route concrete test execution, monitoring, signal transport, or distributed feedback work to a specialized skill or project-local design.

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

@@ -1,9 +1,9 @@
 # Documentation Projections
 
-- Path: `skill/references/document-projections.md`
-- Changed: `20260917`
+- Path: `skills/adsm-ctx/references/document-projections.md`
+- Changed: `20261024`
 
-Use this reference whenever an agent initializes, designs, validates, audits, compresses, or upgrades ADSM documentation under `ctx/docs/`.
+Use this reference whenever an agent initializes, designs, validates, audits, compresses, or evolves ADSM documentation under `ctx/docs/`.
 
 ## Core Model
 
@@ -100,7 +100,7 @@ Projection drift includes:
 
 Validation should report structural drift such as orphan skins.
 
-Audit, compression, and upgrade work should report semantic drift when it can be evidenced from the documents.
+Audit, compression, and evolution work should report semantic drift when it can be evidenced from the documents.
 
 ## Documentation Levels And Verification Layer
 
@@ -120,9 +120,9 @@ Their meanings remain:
 - `environment` — accepted runtime and deployment conditions;
 - `code` — accepted implementation and engineering constraints.
 
-`ctx/docs/verification/` is an optional cross-cutting documentation block. It relates declarations to observations of reality, but is not a fifth refinement level and does not change declaration authority.
+`ctx/docs/verification/` is a mandatory cross-cutting documentation block. It relates declarations to observations of reality, but is not a fifth refinement level and does not change declaration authority.
 
-Create the block only when the project has a durable verification specification. Its root requires `AGENTS.md`; direct categories are optional `product/`, `architecture/`, `environment/`, and `code/`. Create a category only when a durable specification exists beneath it. Do not initialize empty categories or placeholder specifications.
+Require the block in schema `0.5.0`, even when it contains only `AGENTS.md`. Its root requires `AGENTS.md`; direct categories are optional `product/`, `architecture/`, `environment/`, and `code/`. Create a category only when a durable specification exists beneath it. Do not initialize empty categories or placeholder specifications.
 
 A verification specification has one canonical home selected by its **primary verification target**: the declaration or bounded declaration group whose truth it chiefly evaluates. It may link to secondary declarations, executable tests, monitors, environments, dependencies, and other contexts. Mechanism, test framework, source path, CI job, endpoint, reporting context, and current Responsible Context do not determine placement.
 
@@ -202,7 +202,7 @@ Do not use `AGENTS.md` as a replacement for agent documents or skins.
 
 Documentation quality audit should:
 
-- recursively include ordinary `*.md` agent documents under the four declarative levels and under an adopted `verification/` block;
+- recursively include ordinary `*.md` agent documents under the four declarative levels and under the mandatory `verification/` block;
 - classify `*.skin.<lang>.md` files as human-facing semantic skins;
 - detect agent/skin document groups by same basename and directory;
 - report orphan skins;
@@ -217,7 +217,7 @@ Deterministic validation should:
 - require every `*.skin.<lang>.md` file to have a paired non-skin `*.md` document and an explicit valid language marker;
 - require an explicit valid language marker, reversible paired-base resolution, and no redundant `Agent Document` section;
 - verify local markdown document links under `ctx/docs/**`;
-- accept absence of `ctx/docs/verification/`, but when it is present require its `AGENTS.md`, recognized primary-target category directories, and at least one durable specification in every created category;
+- require `ctx/docs/verification/AGENTS.md`, accept an AGENTS-only root, and require recognized primary-target categories with at least one durable specification in every created category;
 - keep verification category placement and evidence sufficiency as semantic audit work rather than claiming them from directory shape;
 - warn when a documentation level contains more than nine direct directories or more than nine direct ordinary files (excluding `AGENTS.md` and paired `*.skin.<lang>.md` files), and require an explicit `Documentation Capacity Exception` in that level's `AGENTS.md`;
 - keep ordinary agent-document shape checks minimal instead of imposing a rigid body template.
@@ -238,9 +238,9 @@ When compressing an agent document with a matching skin, preserve the skin's pur
 
 When an agent document contains human-facing semantic framing that should be preserved independently for human supervision, recommend extracting a matching skin unless the human has not authorized that migration.
 
-## Upgrade Rules
+## Evolution Rules
 
-Upgrades should:
+Follow [the agent evolution procedure](context-evolution.md). Deterministic CLI checks do not change context or metadata. Agent evolution should:
 
 - preserve existing agent documents and project-specific nested subdirectories;
 - add or recommend skins only where human semantic control is clear;

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

@@ -1,7 +1,7 @@
 # Documentation Compression
 
-- Path: `skill/references/documentation-compression.md`
-- Changed: `20260917`
+- Path: `skills/adsm-ctx/references/documentation-compression.md`
+- Changed: `20261024`
 
 Use this reference when an agent must compress an existing ADSM cognitive documentation corpus while preserving accepted project meaning.
 
@@ -16,7 +16,7 @@ Compress the project cognitive documentation corpus under `ctx/docs/`.
 Follow this method:
 
 1. Read the applicable `AGENTS.md` hierarchy from the repository root to the target documentation scope. For the default scope, this means the hierarchy from the repository root to `ctx/docs/`.
-2. Read `skill/references/document-projections.md` for agent/skin classification and projection drift rules.
+2. Read [document-projections.md](document-projections.md) from this installed skill for agent/skin classification and projection drift rules.
 3. Use `ctx/docs/` as the default corpus unless the human explicitly provides another scope.
 4. Exclude operational context outside `ctx/docs/` by default, including `ctx/agent/`, workflow configuration, prompt assets, generated reports, runtime materials, and `ctx/assets/**`.
 5. Treat ordinary `*.md` files as agent-facing operational context documents and `*.skin.<lang>.md` files as human-facing semantic skins.
@@ -28,13 +28,13 @@ Follow this method:
 11. Avoid inventing, weakening, generalizing, or silently deleting project-specific knowledge.
 12. Update `Changed` attributes for every modified context document.
 13. Report non-editorial uncertainty and skin contradictions as human decisions instead of resolving them by rewrite.
-14. Use `templates/work/report/documentation-compression.md` as the report structure when a file report is requested.
+14. Use [the compression report template](../assets/report/documentation-compression.md) as the report structure when a file report is requested.
 
 ## Corpus Selection
 
 The default corpus is `ctx/docs/`.
 
-Documentation compression is intended for declarative project documentation under the four ADSM levels: product, architecture, environment, and code, plus an adopted optional Verification Layer when it is in scope.
+Documentation compression is intended for declarative project documentation under the four ADSM levels: product, architecture, environment, and code, plus the mandatory Verification Layer when it is in scope.
 
 Do not include operational context outside `ctx/docs/` by default, including `ctx/agent/`, generated reports, prompt assets, workflow configuration, runtime materials, `ctx/assets/**`, or other agent-operation artifacts.