@flancer32/skill-adsm-ctx 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.6.0 — 2026-11-04
+
+- Use two-part context schema versions aligned to the npm package major and minor; target schema `0.6`, retaining it for package patches.
+- Clarify development policy and project testing versus product verification in the skill and initialization templates. Evolve existing contexts through agent inspection and human decisions.
+- Report unsupported schema versions uniformly without automatic migration; preserve context and metadata during validation.
+- Align TeqFW dependencies and JSDoc contracts, and improve repository context navigation.
+
+## 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,19 +4,21 @@ 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.
 
 This package is developed according to the [ADSM methodology](http://fly.wiredgeese.com/flancer/leanpub/adsm-en/).
 
+ADSM defaults to **Rapid Evolution by Default, Reliability by Requirement**: deliver essential functionality in short feedback cycles, fail visibly, avoid unrequired compatibility, and verify according to contracts and risk. Humans control acceptable risk and can set a different project policy; accepted context, security, integrity, and explicit invariants remain binding. New projects receive a concise policy in their root `AGENTS.md`; existing projects are not rewritten. See the bundled [skill guidance](skills/adsm-ctx/SKILL.md#development-policy) for details.
+
 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 +29,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 +48,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 +57,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 +78,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 +105,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 +117,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 +135,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.6` 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 +157,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.6` only after structural checks and semantic review succeed, then validates again. The package major and minor match the two-part schema version.
 
 ## 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 +186,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.6`. 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 +219,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.
 
@@ -254,15 +243,26 @@ Run the CLI directly from the repository:
 npm exec -- adsm-ctx --help
 ```
 
-Run the tests:
+Run the fast local project smoke check (context structure and skill/package conventions):
 
 ```sh
 npm test
 ```
 
+Run product verification and the remaining suites, or select a focused suite:
+
+```sh
+npm run verify
+npm run test:unit
+npm run test:integration
+npm run test:package
+```
+
+The smoke check does not establish product conformity or semantic context correctness. The verification specifications under `ctx/docs/verification/` identify the observed contracts and their limits. The package installation scenario uses a temporary installation and may skip locally when its offline dependency cache is unavailable; a skip is not evidence of successful installation.
+
 ## 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 +271,19 @@ This repository contains a working skeleton intended as a foundation for future
 ## License
 
 Apache-2.0
+
+## Versioning And Compatibility
+
+Package `0.6.0` targets context schema `0.6`. Schema versions use major.minor; npm package versions use major.minor.patch with matching major and minor. Package patch `0.6.1` retains schema `0.6`; a new minor establishes a new schema target. Changes in context conventions require a new minor.
+
+`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.6`; all other versions are unsupported and 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`, `npm run verify`, 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.6.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,13 @@
   "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": "node bin/adsm-ctx.mjs validate . && node --test test/package/skill.test.mjs",
+    "verify": "npm run test:unit && npm run test:integration && npm run test:package"
   },
   "dependencies": {
     "@teqfw/cli": "^2.2.0",
@@ -56,24 +55,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/skills/adsm-ctx/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: adsm-ctx
+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
+
+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.
+
+## Development Policy
+
+ADSM defaults to **Rapid Evolution by Default, Reliability by Requirement**. Plan short hypothesis → implementation → execution → feedback cycles around essential functionality. Prefer simple working solutions; add abstractions or defensive machinery for concrete requirements or observed problems. Fail fast and visibly on unexpected conditions and contract violations rather than hiding them with speculative retries, repairs, or fallbacks.
+
+Accepted cognitive context defines the target; code and tests converge on it, and historical behavior is not independent architectural authority. Breaking software interfaces is acceptable by default; retain compatibility, migrations, or legacy layers only when required. Preserve decisions explaining accepted and rejected directions. Verify the happy path and essential contracts with sufficient fast feedback; add regression coverage and stronger checks for observed defects, meaningful risks, or explicit requirements.
+
+Humans decide acceptable risks and reliability guarantees; project-specific accepted context can strengthen or replace this default. Never silently compromise security, integrity, or accepted invariants. This software compatibility default does not authorize rewriting consumer contexts or bypassing context-schema evolution and human approval.
+
+## 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). |
+| Project testing, Verification Layer, or Software Evolution Loop | [testing-and-verification.md](references/testing-and-verification.md), [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. |
+| 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. 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
+
+- 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`. 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 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.6`. The npm package major and minor match this two-part schema version; package patches retain the same schema. Package updates and context evolution remain separate. 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,7 +1,7 @@
 # AGENTS Hierarchy
 
-- Path: `skill/references/agents-hierarchy.md`
-- Changed: `20260715`
+- Path: `skills/adsm-ctx/references/agents-hierarchy.md`
+- Changed: `20261104`
 
 This reference operationalizes `AGENTS.md` handling for ADSM contexts.
 
@@ -32,6 +32,8 @@ Repository-root and context-side files are not identical:
 - the repository-root `AGENTS.md` controls root work and may use a lighter shape;
 - context-side `AGENTS.md` files under `ctx/` must contain `Purpose`, `Level Map`, and `Level Boundary`.
 
+The root template states the skill's Rapid Evolution development default concisely and routes agents to the skill for its meaning. Accepted project context may strengthen or replace that default under human authority; deeper instructions must preserve the root's security, integrity, and accepted-context boundaries. Initialization does not overwrite existing root instructions.
+
 For skill operation:
 
 - interpret `AGENTS.md` as local control files inside already-declared boundaries;

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

@@ -0,0 +1,59 @@
+# Agent-Driven Context Evolution
+
+- Path: `skills/adsm-ctx/references/context-evolution.md`
+- Changed: `20261104`
+
+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.
+
+Apply the skill's Rapid Evolution default to planning and verification: work toward accepted target meaning in small feedback cycles, without preserving obsolete software behavior by default. This does not make existing context or schema disposable: investigate actual conventions, preserve accepted meaning and decisions, and obtain human approval for semantic or authority changes. Do not automatically rewrite consumer projects when the skill or root template changes. Required reliability and verification remain controlled by humans and applicable project context.
+
+## Target And Responsibilities
+
+The current target is context schema `adsm-context` version `0.6`, matching the npm package major and minor. 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.
+
+For schema `0.6`, assess the rapid-evolution development default and the distinction between project testing and product verification against the actual project instructions, testing documentation, and accepted decisions. The default is replaceable by project policy; do not override a project's accepted policy or copy template text blindly. Reconcile testing guidance with the project's ecosystem and existing requirements, with human decisions for changes to accepted meaning.
+
+## 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.6`. 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.6`, 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 an unsupported 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.6`, 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.6.1` targets schema `0.6` 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. Unsupported labels require investigation; no version-specific migration is provided. 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.