@flancer32/skill-adsm-ctx 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.4.0 - 2026-09-23
+
+### Added
+
+- Added optional, capability-based Verification Layer support, with specifications grouped by the primary product, architecture, environment, or code target.
+- Added validation for verification block structure, populated categories, metadata capabilities, and adoption without a declared capability; older and unadopted contexts remain valid.
+- Added guidance for verification evidence, re-verification, Responsible Context, and the Software Evolution Loop across the bundled skill and project context.
+
+### Changed
+
+- Kept the four ordered declarative documentation levels and defined `verification/` as an optional cross-cutting block rather than another authority level.
+- Raised the context metadata baseline to `0.2.0` and updated initialization templates to advertise `verification-layer` without creating empty scaffolding.
+- Updated design, validation, upgrade, audit, and documentation guidance to preserve existing contexts and require explicit, durable verification specifications before adoption.
+- Reconciled product and architecture documents, semantic skins, README, and tests around the boundary between declarative context and operational evidence.
+- Clarified that the package does not execute tests, collect monitoring data, persist feedback state, or coordinate distributed incidents; refreshed the dependency lockfile.
+
 ## 0.3.0 - 2026-08-14
 
 ### Changed

package/README.md

@@ -14,7 +14,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.
+- reusable `ctx/` templates for bootstrapping ADSM-compatible projects;
+- optional Verification Layer documentation lifecycle support;
 - working templates for agent-produced reports.
 
 ## Purpose
@@ -26,7 +27,8 @@ 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.
+- upgrade a context when ADSM conventions evolve;
+- design, validate, audit, or compress an optional 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.
 
@@ -144,7 +146,7 @@ teq --host @flancer32/skill-adsm-ctx adsm-ctx:validate .
 
 ### `init`
 
-Creates the minimal ADSM-compatible context structure, starter documents, and `ctx/adsm.json` metadata.
+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.
 
 ### `design`
 
@@ -152,7 +154,7 @@ Provides guidance for classifying the project, choosing relevant documentation b
 
 ### `validate`
 
-Checks baseline paths, required documentation levels, required `AGENTS.md` files, metadata, body/skin pairing, localized skin names, local markdown document links, and structural projection checks. When the repository provides a deterministic validator, run it and report errors and warnings separately. Validation reports findings without modifying project content.
+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.
 
 ### `quality-audit`
 
@@ -168,7 +170,7 @@ The default compression corpus is `ctx/docs/`. Operational context such as `ctx/
 
 ### `upgrade`
 
-Reads context metadata and reports or applies non-destructive migrations when available. The initial implementation provides the migration mechanism and reports when no migrations apply.
+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.
 
 ## Workflow
 
@@ -195,6 +197,8 @@ 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.
+
 The bundled architecture templates expect these top-level documents:
 
 - `overview.md`
@@ -258,7 +262,7 @@ npm test
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for the prepared, unpublished 0.3.0 release notes.
+See [CHANGELOG.md](CHANGELOG.md) for the prepared, unpublished 0.4.0 release notes.
 
 ## Status
 

package/migrations/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flancer32/skill-adsm-ctx",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Build and evolve project cognitive context for Agent-Driven Software Management (ADSM).",
   "license": "Apache-2.0",
   "type": "module",

package/skill/SKILL.md

@@ -22,6 +22,7 @@ Humans own direction, accepted meaning, approval, and accountability. Agents ref
 | --- | --- |
 | `init` baseline | [context-lifecycle.md](references/context-lifecycle.md); use the `templates/ctx/` baseline. |
 | `design` or new branch | [context-lifecycle.md](references/context-lifecycle.md), [design-questionnaire.md](references/design-questionnaire.md), and [specialized-skills.md](references/specialized-skills.md). |
+| Verification Layer or Software Evolution Loop | [document-projections.md](references/document-projections.md), [context-lifecycle.md](references/context-lifecycle.md), [documentation-quality-audit.md](references/documentation-quality-audit.md), and [specialized-skills.md](references/specialized-skills.md). |
 | `validate` structure | [context-lifecycle.md](references/context-lifecycle.md), [document-projections.md](references/document-projections.md), and the repository-provided deterministic validator when available. Report errors and warnings separately. |
 | `quality-audit` | Run `validate` first; then load [documentation-quality-audit.md](references/documentation-quality-audit.md). Report findings; do not rewrite project meaning. |
 | `documentation-compression` | Load [documentation-compression.md](references/documentation-compression.md). Rewrite only with authorization and preserve accepted meaning. |
@@ -39,9 +40,9 @@ 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.
-- Use only the four ADSM top-level documentation levels under `ctx/docs/`; allow justified nested project structure within them.
+- Preserve the four ordered declarative documentation levels under `ctx/docs/`: `product`, `architecture`, `environment`, and `code`. Allow an optional cross-cutting `verification/` block only as defined in [document-projections.md](references/document-projections.md); it is never a fifth level.
 - Keep each documentation level to no more than nine direct directories and nine direct ordinary files, excluding `AGENTS.md` and paired `*.skin.<lang>.md` files, where practical; an intentional excess must be stated explicitly in that level's `AGENTS.md`.
 
 ## Completion
 
-Finish with explicit validation results, 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 adoption state when relevant, specialization gaps, human decisions, and any preserved project-specific content. Use the relevant templates under `templates/ctx/` for initialization and `templates/work/` only when a working report is requested.

package/skill/references/context-lifecycle.md

@@ -1,7 +1,7 @@
 # Context Lifecycle
 
 - Path: `skill/references/context-lifecycle.md`
-- Changed: `20260814`
+- Changed: `20260917`
 
 `adsm-ctx` manages six lifecycle modes for project cognitive context.
 
@@ -13,10 +13,10 @@ 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 structural integrity without destructive edits. Check baseline paths, context metadata, the four top-level documentation levels, local `AGENTS.md` placement, document headers, agent/skin pairs, reversible skin naming, compactness, local document links, and `ctx/assets/**` exclusion.
+- `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.
 - `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` migrates context non-destructively. Read metadata first, preserve project-specific content, and use [upgrade-policy.md](upgrade-policy.md) for safe boundaries.
+- `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.
 
 The lifecycle is iterative. A project may return to `design`, `validate`, `quality-audit`, `documentation-compression`, and `upgrade` many times after initialization.
 
@@ -30,18 +30,26 @@ 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 top-level documentation levels under `ctx/docs/` while allowing project-specific nested subdirectories inside those levels.
+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).
 
 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.
 
 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.
 
+## Verification Layer And Software Evolution
+
+Verification defines the relation between an accepted declaration and a bounded observation of reality. A signal may arise from an active check, passive runtime observation, or an external report. It becomes an observation only after enough context identifies what was observed, against which applicable expectation, and in what relevant state.
+
+An observation supports an assessment such as conformity, deviation, ambiguity, contradiction, or insufficient evidence. A deviation is not a cause. Localization hypotheses remain revisable until targeted evidence supports them. A Responsible Context advances the loop within its authority; resolution feedback alone does not close it. Where closure is required, obtain a new applicable re-verification of the relevant original expectation.
+
+The Software Evolution Loop is broader than Verification. Architecture defines boundaries and ownership; supervision defines acceptable uncertainty and required independence; project-local workflow owns routing and operational feedback state; specialized skills provide concrete verification, monitoring, transport, or distributed feedback procedures. `adsm-ctx` provides methodology and documentation lifecycle support, not a runtime coordination system.
+
 ## Shared Boundaries
 
 - 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 ADSM top-level documentation levels. Nested structure within them remains project-specific.
+- 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.
 - 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.

package/skill/references/design-questionnaire.md

@@ -1,7 +1,7 @@
 # Design Questionnaire
 
 - Path: `skill/references/design-questionnaire.md`
-- Changed: `20260610`
+- Changed: `20260917`
 
 Use this questionnaire at the start of `design` mode to classify the project and decide which specialized ADSM skills may be relevant.
 
@@ -42,3 +42,15 @@ Use this questionnaire at the start of `design` mode to classify the project and
 - If the project includes a browser-based web application, look for a browser documentation skill such as `skill-adsm-doc-web-browser`.
 - If the project includes other specialized areas, choose the matching skill when available.
 - If a relevant specialized skill is unavailable, still create the justified ADSM structure, preserve any project-defined semantics, and record the missing specialization as a gap instead of inventing unsupported details.
+
+## Verification Questions
+
+11. Which declared outcomes, boundaries, conditions, or code properties have high practical consequence if wrong?
+12. Which broad observations provide useful early detection, and which blind spots need narrower diagnostics?
+13. Which signals may arrive actively, passively, or from external reporters, and what provenance is available?
+14. Which observations can the current agent perform directly, and which require another Responsible Context, human action, or specialized tooling?
+15. Does supervision require independent evidence or an independent actor for any concern?
+
+## 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.

package/skill/references/document-projections.md

@@ -1,7 +1,7 @@
 # Documentation Projections
 
 - Path: `skill/references/document-projections.md`
-- Changed: `20260814`
+- Changed: `20260917`
 
 Use this reference whenever an agent initializes, designs, validates, audits, compresses, or upgrades ADSM documentation under `ctx/docs/`.
 
@@ -102,9 +102,9 @@ 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.
 
-## Documentation Levels And Substructure
+## Documentation Levels And Verification Layer
 
-ADSM defines only four top-level documentation levels under `ctx/docs/`:
+ADSM defines exactly four ordered declarative documentation levels under `ctx/docs/`:
 
 ```text
 ctx/docs/product/
@@ -113,32 +113,47 @@ ctx/docs/environment/
 ctx/docs/code/
 ```
 
-Their meanings:
+Their meanings remain:
 
-- `product` — product meaning;
-- `architecture` — engineering structure;
-- `environment` — runtime and deployment context;
-- `code` — implementation mapping.
+- `product` — accepted product meaning;
+- `architecture` — accepted engineering structure;
+- `environment` — accepted runtime and deployment conditions;
+- `code` — accepted implementation and engineering constraints.
 
-ADSM may provide baseline templates and recommendations, but it must not impose a rigid internal subtree inside those levels.
+`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.
 
-Project-specific nested subdirectories are allowed and should be used when they improve maintainability.
+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.
+
+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.
+
+A specification should state, when relevant:
+
+- the primary target and traceability to its declaration;
+- the expected observable corridor;
+- approach and acquisition mode;
+- applicability and prerequisites;
+- bounded interpretation, reach, and blind spots;
+- lifecycle role and follow-up, including re-verification when required; and
+- available access or authority for obtaining the observation.
+
+A verification specification is durable documentation. An evidence record records an actual observation and its provenance. Operational Feedback State retains unresolved routing or continuation state. Do not confuse either operational object with a declaration or durable verification specification.
+
+Project-specific nesting by risk area, product area, subsystem, use case, integration, or operational surface is allowed inside a primary-target category. It must preserve one canonical specification.
 
 Valid examples:
 
 ```text
 ctx/docs/product/domain/ingress.md
-ctx/docs/product/domain/memory.md
 ctx/docs/architecture/runtime/agent-execution.md
 ctx/docs/environment/deployment/vps.md
 ctx/docs/code/modules/orchestrator.md
+ctx/docs/verification/product/authentication.md
+ctx/docs/verification/architecture/boundaries/adapter-isolation.md
 ```
 
-Flat files remain allowed when suitable.
-
-Do not require flat prefixed names such as `domain-ingress.md` when nested directories are clearer.
+Flat files remain allowed when suitable. Do not require flat prefixed names when nested directories are clearer.
 
-Each of the four documentation levels should contain no more than nine direct subdirectories and no more than nine direct ordinary files. The service-control file `AGENTS.md` and all matching `*.skin.<lang>.md` files are excluded, so an agent document and all of its skins count as one document group. This is a maintainability recommendation, not a reason to collapse meaningful structure.
+Each of the four declarative levels should contain no more than nine direct subdirectories and nine direct ordinary files. The service-control file `AGENTS.md` and all matching `*.skin.<lang>.md` files are excluded, so an agent document and all of its skins count as one document group. This is a maintainability recommendation, not a reason to collapse meaningful structure.
 
 When a level deliberately exceeds either value, its own `AGENTS.md` must include a `## Documentation Capacity Exception` section that explicitly records the intentional exception and its reason. Deterministic validation warns about the exceeded recommendation and reports an error when this explicit local declaration is absent.
 
@@ -187,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 top-level documentation levels;
+- recursively include ordinary `*.md` agent documents under the four declarative levels and under an adopted `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;
@@ -202,6 +217,8 @@ 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;
+- 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.
 
@@ -230,3 +247,4 @@ Upgrades should:
 - report orphan skins and agent/skin conflicts;
 - avoid introducing required `README.md` files inside `ctx/docs/`;
 - keep assets under `ctx/assets/**`.
+- preserve primary verification target, applicability, reach, blind spots, and the distinction between specification and evidence when verification documentation is in scope.

package/skill/references/documentation-compression.md

@@ -1,7 +1,7 @@
 # Documentation Compression
 
 - Path: `skill/references/documentation-compression.md`
-- Changed: `20260708`
+- Changed: `20260917`
 
 Use this reference when an agent must compress an existing ADSM cognitive documentation corpus while preserving accepted project meaning.
 
@@ -34,7 +34,7 @@ Follow this method:
 
 The default corpus is `ctx/docs/`.
 
-Documentation compression is intended for declarative project documentation: product, architecture, environment, code, and other project documentation levels under `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.
 
 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.
 
@@ -77,6 +77,7 @@ Safe compression may:
 Safe compression preserves:
 
 - product intent and scope;
+- verification primary targets, applicable bounds, blind spots, and the distinction between durable specification, actual evidence, and operational feedback state;
 - domain terms and relationships;
 - role and authority boundaries;
 - architecture boundaries and decisions;

package/skill/references/documentation-quality-audit.md

@@ -1,7 +1,7 @@
 # Documentation Quality Audit
 
 - Path: `skill/references/documentation-quality-audit.md`
-- Changed: `20260814`
+- Changed: `20260917`
 
 Use this reference when an agent must audit an existing documentation corpus as an ADSM cognitive context.
 
@@ -205,3 +205,18 @@ The audit must not:
 - mark a corpus incomplete merely because it does not document out-of-scope concerns.
 
 The audit may propose correction order and candidate edits, but it must distinguish proposals from accepted project knowledge.
+
+## Verification Layer Review
+
+When `ctx/docs/verification/` exists, include it in the default corpus. Review it as cross-cutting specification documentation, not a fifth declarative level and not an evidence or incident archive.
+
+Check whether each durable specification:
+
+- names a primary verification target and links to the authoritative declaration;
+- states an observable expectation and applicable state or prerequisites;
+- distinguishes observation method from the declaration being evaluated;
+- identifies reach, blind spots, and limits on the conclusion;
+- avoids duplicated specifications for the same expectation; and
+- distinguishes detection, localization, resolution feedback, and re-verification.
+
+Report a human decision when supervision, acceptable uncertainty, required independence, Responsible Context routing, evidence retention, or operational feedback-state ownership is missing. Do not infer these policies from test framework, directory name, issue tracker, or a passing result.

package/skill/references/orchestration-model.md

@@ -1,7 +1,7 @@
 # Orchestration Model
 
 - Path: `skill/references/orchestration-model.md`
-- Changed: `20260715`
+- Changed: `20260917`
 
 This skill is a router and baseline manager.
 
@@ -12,9 +12,10 @@ It is responsible for:
 - lifecycle guidance;
 - baseline validation;
 - migration entry points;
+- Verification Layer documentation lifecycle support and structural validation;
 - the reserved boundary definition for `ctx/agent/`.
 
-It is not responsible for inventing specialized technical or domain documentation.
+It is not responsible for inventing specialized technical or domain documentation, executing verification, receiving signals, persisting evidence or Operational Feedback State, or coordinating distributed feedback loops.
 
 For `ctx/agent/`, this skill may:
 
@@ -32,7 +33,7 @@ When specialization is needed, the agent should use a matching available skill a
 
 Concrete tool-facing materials belong to project-local documentation, explicit human instruction, or an external specialized skill when one is available and relevant.
 
-Specialized skills may add project-specific nested documentation under the four top-level `ctx/docs` levels, but they must preserve agent/skin pairing rules and keep artifacts under `ctx/assets/**`.
+Specialized skills may add project-specific nested documentation under the four declarative `ctx/docs` levels and may implement concrete verification methods or project-local feedback procedures. They must preserve agent/skin pairing rules, keep artifacts under `ctx/assets/**`, and treat `verification/` as optional cross-cutting documentation rather than a fifth level.
 
 ## Template Boundary
 

package/skill/references/specialized-skills.md

@@ -1,7 +1,7 @@
 # Specialized Skills
 
 - Path: `skill/references/specialized-skills.md`
-- Changed: `20260708`
+- Changed: `20260917`
 
 Use specialized skills when the project context requires knowledge that should not live in this generic lifecycle skill.
 
@@ -11,6 +11,8 @@ Examples of specialization signals:
 - backend application architecture;
 - data or persistence modeling;
 - deployment and runtime environment design;
+- browser, backend, data, security, monitoring, or other concrete verification methods;
+- signal transport, external-report handling, or distributed feedback procedures;
 - tool-specific agent instructions or workflow design for a concrete execution engine or host platform.
 
 Tool-specific specialization signals include:
@@ -27,5 +29,6 @@ Specialized skills must preserve ADSM's documentation projection model:
 
 - ordinary `*.md` files under `ctx/docs/**` are agent-facing operational context documents;
 - `*.skin.<lang>.md` files are human-facing semantic skins for matching agent documents;
-- nested subdirectories inside the four top-level documentation levels are allowed;
+- nested subdirectories inside the four declarative documentation levels are allowed;
+- an adopted `ctx/docs/verification/` block remains cross-cutting; specifications use a primary declaration target rather than the mechanism or specialized skill that obtains evidence;
 - visual, generated, rendered, and auxiliary artifacts belong under `ctx/assets/**`.

package/skill/references/upgrade-policy.md

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

package/skill/templates/ctx/adsm.json

@@ -1,6 +1,9 @@
 {
   "schema": "adsm-context",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "capabilities": [
+    "verification-layer"
+  ],
   "notes": [
     "Initial context created from the canonical adsm-ctx template set."
   ]

package/skill/templates/ctx/docs/AGENTS.md

@@ -21,6 +21,7 @@ The installed template should describe the project, not restate detailed ADSM me
 - `code/` — code-level constraints and testing guidance.
 - `environment/` — runtime and infrastructure assumptions.
 - `product/` — product meaning, roles, and use cases.
+- `verification/` — optional cross-cutting verification specifications; create it only with a real durable specification.
 - `AGENTS.md` — entry note for `ctx/docs/`.
 - `ai-intro.md` — compact agent orientation for the concrete project.
 - `filesystem.md` — top-level repository map.
@@ -31,6 +32,7 @@ Defines:
 
 - The declarative documentation boundary for the project.
 - The documentation dependency chain from product to code.
+- The optional Verification Layer as a cross-cutting relation, never a fifth declarative level.
 - The local entry points used to orient agents within `ctx/docs/`.
 
 Does NOT define:
@@ -50,6 +52,7 @@ Does NOT define:
 - Read a matching skin before changing an agent document.
 - Report a human decision if a requested agent-document change would violate the matching skin.
 - Keep project-specific nested subdirectories inside `product/`, `architecture/`, `environment/`, and `code/` when they improve maintainability.
+- Create `verification/` only when it contains a durable specification. Its root requires `AGENTS.md`; create primary-target categories only on demand.
 - 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.
 - When a level deliberately exceeds either value, add a `## Documentation Capacity Exception` section to that level's `AGENTS.md` that states the exception and its reason.
 - Put visual, generated, rendered, or auxiliary artifacts under `ctx/assets/**`.

package/skill/templates/ctx/docs/code/testing.md

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

package/src/Design/Service.mjs

@@ -23,13 +23,15 @@ export default class Service {
         "",
         "Recommended agent workflow:",
         "1. Identify the project class from existing repository signals or user input.",
-        "2. Keep ADSM's four top-level documentation levels under ctx/docs/: product, architecture, environment, and code.",
-        "3. Add only project-specific substructure that is justified by the project; nested directories are allowed.",
-        "4. Treat ordinary *.md files as agent-facing operational context documents and add *.skin.<lang>.md files only where human semantic control is needed.",
-        "5. Place visual, generated, rendered, or auxiliary artifacts under ctx/assets/ instead of ctx/docs/.",
-        "6. Detect whether specialized ADSM skills are needed for browser, backend, data, deployment, or other areas.",
-        "7. If a specialized skill is available, use it for that branch after the generic structure is in place.",
-        "8. If no specialized skill is available, record the specialization gap and avoid inventing details.",
+        "2. Keep ADSM's four ordered declarative documentation levels under ctx/docs/: product, architecture, environment, and code.",
+        "3. Add ctx/docs/verification/ only when a durable verification specification is justified; it is cross-cutting, not a fifth level.",
+        "4. Place each verification specification under the category of its primary declaration target and link secondary targets instead of duplicating it.",
+        "5. Add only project-specific substructure that is justified by the project; nested directories are allowed.",
+        "6. Treat ordinary *.md files as agent-facing operational context documents and add *.skin.<lang>.md files only where human semantic control is needed.",
+        "7. Place visual, generated, rendered, or auxiliary artifacts under ctx/assets/ instead of ctx/docs/.",
+        "8. Detect whether specialized ADSM skills are needed for browser, backend, data, deployment, verification execution, monitoring, or other areas.",
+        "9. If a specialized skill is available, use it for that branch after the generic structure is in place.",
+        "10. If no specialized skill is available, record the specialization gap and avoid inventing details.",
       ].join("\n");
     };
   }

package/src/Shared/Constants.mjs

@@ -8,7 +8,11 @@
 export default class Constants {
   constructor() {
     this.CONTEXT_SCHEMA = "adsm-context";
-    this.CONTEXT_VERSION = "0.1.0";
+    this.CONTEXT_VERSION = "0.2.0";
+    this.VERIFICATION_CAPABILITY = "verification-layer";
+    this.CONTEXT_CAPABILITIES = Object.freeze([this.VERIFICATION_CAPABILITY]);
+    this.VERIFICATION_BLOCK = "verification";
+    this.VERIFICATION_TARGETS = Object.freeze(["product", "architecture", "environment", "code"]);
     this.DOC_LEVEL_MAX_DIRECTORIES = 9;
     this.DOC_LEVEL_MAX_FILES = 9;
     this.REQUIRED_PATHS = Object.freeze([

package/src/Shared/Metadata.mjs

@@ -20,6 +20,7 @@ export default class Metadata {
       return {
         schema: constants.CONTEXT_SCHEMA,
         version: constants.CONTEXT_VERSION,
+        capabilities: [...(constants.CONTEXT_CAPABILITIES ?? [])],
       };
     };
   }

package/src/Upgrade/Service.mjs

@@ -2,7 +2,7 @@
 
 /**
  * @namespace Fl32_Skill_Adsm_Ctx_Upgrade_Service
- * @description Provides the baseline non-destructive upgrade entry point for ADSM context lifecycle.
+ * @description Provides the baseline non-destructive upgrade entry point without automatic migrations.
  */
 
 export default class Service {
@@ -13,7 +13,7 @@ export default class Service {
    */
   constructor({fs, pathService}) {
     /**
-     * Runs the upgrade entry point.
+     * Checks for context metadata and reports the current migration availability.
      *
      * @param {object} params
      * @param {string} params.targetPath
@@ -31,7 +31,7 @@ export default class Service {
       }
 
       return {
-        message: "No migrations are currently available for this context.",
+        message: "No automatic migrations are available. Verification Layer adoption is optional and must not create empty scaffolding.",
         ok: true,
       };
     };

package/src/Validate/Service.mjs

@@ -31,7 +31,7 @@ export default class Validate {
      *     ruleId: string,
      *     severity: "error" | "warning"
      *   }[],
-     *   metadata: {schema: string, version: string, initializedAt?: string} | null,
+     *   metadata: {capabilities?: string[], schema: string, version: string, initializedAt?: string} | null,
      *   missingPaths: string[],
      *   ok: boolean,
      *   projectRoot: string,
@@ -40,7 +40,8 @@ export default class Validate {
      *     bodies: string[],
      *     orphanSkins: string[],
      *     pairs: {body: string, skin: string}[],
-     *     skins: string[]
+     *     skins: string[],
+     *     verification: {categories: string[], present: boolean}
      *   },
      *   warningCount: number
      * }>}
@@ -54,10 +55,16 @@ export default class Validate {
         ruleId: "required-path",
         severity: "error",
       }));
-      const metadata = readMetadata({constants, fs, pathService, projectRoot});
-      const projection = inspectProjection({constants, fs, pathService, projectRoot});
+      const metadataResult = readMetadata({constants, fs, pathService, projectRoot});
+      const projection = inspectProjection({
+        constants,
+        fs,
+        metadata: metadataResult.metadata,
+        pathService,
+        projectRoot,
+      });
 
-      if (!metadata.ok) findings.push(metadata.finding);
+      findings.push(...metadataResult.findings);
       findings.push(...projection.findings);
 
       const errorCount = findings.filter((entry) => entry.severity === "error").length;
@@ -66,7 +73,7 @@ export default class Validate {
       return {
         errorCount,
         findings,
-        metadata: metadata.ok ? metadata.metadata : null,
+        metadata: metadataResult.ok ? metadataResult.metadata : null,
         missingPaths,
         ok: errorCount === 0,
         projectRoot,
@@ -180,54 +187,80 @@ function parseSkinFilename(file) {
  * }}
  */
 function readMetadata({constants, fs, pathService, projectRoot}) {
+  const findings = [];
   const metadataPath = pathService.join(projectRoot, "ctx", "adsm.json");
   if (!fs.existsSync(metadataPath)) {
-    return {
-      ok: false,
-      finding: createFinding({
-        message: "Missing ctx/adsm.json",
-        path: "ctx/adsm.json",
-        ruleId: "metadata-file",
-        severity: "error",
-      }),
-    };
+    findings.push(createFinding({
+      message: "Missing ctx/adsm.json",
+      path: "ctx/adsm.json",
+      ruleId: "metadata-file",
+      severity: "error",
+    }));
+    return {findings, metadata: null, ok: false};
   }
 
   try {
     const parsed = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
     if (parsed.schema !== constants.CONTEXT_SCHEMA) {
-      return {
-        ok: false,
-        finding: createFinding({
-          message: `Unexpected schema: ${parsed.schema}`,
-          path: "ctx/adsm.json",
-          ruleId: "metadata-schema",
-          severity: "error",
-        }),
-      };
+      findings.push(createFinding({
+        message: `Unexpected schema: ${parsed.schema}`,
+        path: "ctx/adsm.json",
+        ruleId: "metadata-schema",
+        severity: "error",
+      }));
     }
     if (!parsed.version) {
-      return {
-        ok: false,
-        finding: createFinding({
-          message: "Missing metadata version",
+      findings.push(createFinding({
+        message: "Missing metadata version",
+        path: "ctx/adsm.json",
+        ruleId: "metadata-version",
+        severity: "error",
+      }));
+    }
+
+    if (Object.hasOwn(parsed, "capabilities")) {
+      if (!Array.isArray(parsed.capabilities)) {
+        findings.push(createFinding({
+          message: "Metadata capabilities must be an array of unique strings",
           path: "ctx/adsm.json",
-          ruleId: "metadata-version",
+          ruleId: "metadata-capabilities",
           severity: "error",
-        }),
-      };
+        }));
+      } else {
+        const seen = new Set();
+        for (const capability of parsed.capabilities) {
+          if (typeof capability !== "string" || capability.length === 0 || seen.has(capability)) {
+            findings.push(createFinding({
+              message: "Metadata capabilities must be an array of unique non-empty strings",
+              path: "ctx/adsm.json",
+              ruleId: "metadata-capabilities",
+              severity: "error",
+            }));
+            break;
+          }
+          seen.add(capability);
+          if (!(constants.CONTEXT_CAPABILITIES ?? []).includes(capability)) {
+            findings.push(createFinding({
+              message: `Unknown context capability: ${capability}`,
+              path: "ctx/adsm.json",
+              ruleId: "metadata-capability-unknown",
+              severity: "warning",
+            }));
+          }
+        }
+      }
     }
-    return {ok: true, metadata: parsed};
+
+    const ok = findings.every((entry) => entry.severity !== "error");
+    return {findings, metadata: ok ? parsed : null, ok};
   } catch (error) {
-    return {
-      ok: false,
-      finding: createFinding({
-        message: `Invalid metadata JSON: ${error instanceof Error ? error.message : "Unknown error"}`,
-        path: "ctx/adsm.json",
-        ruleId: "metadata-json",
-        severity: "error",
-      }),
-    };
+    findings.push(createFinding({
+      message: `Invalid metadata JSON: ${error instanceof Error ? error.message : "Unknown error"}`,
+      path: "ctx/adsm.json",
+      ruleId: "metadata-json",
+      severity: "error",
+    }));
+    return {findings, metadata: null, ok: false};
   }
 }
 
@@ -253,7 +286,7 @@ function readMetadata({constants, fs, pathService, projectRoot}) {
  *   }
  * }}
  */
-function inspectProjection({constants, fs, pathService, projectRoot}) {
+function inspectProjection({constants, fs, metadata, pathService, projectRoot}) {
   const docsRoot = pathService.join(projectRoot, "ctx", "docs");
   const assetsRoot = pathService.join(projectRoot, "ctx", "assets");
   const findings = [];
@@ -303,6 +336,26 @@ function inspectProjection({constants, fs, pathService, projectRoot}) {
     pathService,
     projectRoot,
   }));
+  const verification = inspectVerificationBlock({
+    constants,
+    docsEntryMap,
+    fs,
+    pathService,
+    projectRoot,
+  });
+  findings.push(...verification.findings);
+  if (
+    verification.summary.present
+    && metadata
+    && !metadata.capabilities?.includes(constants.VERIFICATION_CAPABILITY)
+  ) {
+    findings.push(createFinding({
+      message: `Verification block is present without declared ${constants.VERIFICATION_CAPABILITY} capability`,
+      path: "ctx/adsm.json",
+      ruleId: "verification-capability-undocumented",
+      severity: "warning",
+    }));
+  }
 
   const markdownFiles = [];
   for (const file of listFiles({fs, pathService, root: docsRoot, prefix: "ctx/docs"})) {
@@ -365,10 +418,129 @@ function inspectProjection({constants, fs, pathService, projectRoot}) {
       orphanSkins,
       pairs,
       skins,
+      verification: verification.summary,
     },
   };
 }
 
+/**
+ * Inspects optional Verification Layer adoption without treating it as a fifth
+ * declarative documentation level.
+ *
+ * @param {object} params
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} params.constants
+ * @param {Map<string, {name: string, isDirectory: () => boolean, isFile: () => boolean}>} params.docsEntryMap
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.projectRoot
+ * @returns {{
+ *   findings: {message: string, path: string, ruleId: string, severity: "error" | "warning"}[],
+ *   summary: {categories: string[], present: boolean}
+ * }}
+ */
+function inspectVerificationBlock({constants, docsEntryMap, fs, pathService, projectRoot}) {
+  const findings = [];
+  const summary = {categories: [], present: false};
+  const entry = docsEntryMap.get(constants.VERIFICATION_BLOCK);
+  if (!entry) return {findings, summary};
+
+  summary.present = true;
+  const verificationPath = `ctx/docs/${constants.VERIFICATION_BLOCK}`;
+  if (!entry.isDirectory()) {
+    findings.push(createFinding({
+      message: `Verification block is not a directory: ${verificationPath}`,
+      path: verificationPath,
+      ruleId: "verification-block",
+      severity: "error",
+    }));
+    return {findings, summary};
+  }
+
+  let entries = [];
+  try {
+    entries = listEntries({
+      fs,
+      root: pathService.join(projectRoot, ...verificationPath.split("/")),
+    });
+  } catch (error) {
+    findings.push(createFinding({
+      message: `Unreadable verification block (${error instanceof Error ? error.message : "Unknown error"})`,
+      path: verificationPath,
+      ruleId: "verification-block-readable",
+      severity: "error",
+    }));
+    return {findings, summary};
+  }
+
+  const agentsEntry = entries.find((candidate) => candidate.name === "AGENTS.md");
+  if (!agentsEntry?.isFile()) {
+    findings.push(createFinding({
+      message: `Verification block requires ${verificationPath}/AGENTS.md`,
+      path: `${verificationPath}/AGENTS.md`,
+      ruleId: "verification-agents",
+      severity: "error",
+    }));
+  }
+
+  const targets = constants.VERIFICATION_TARGETS ?? constants.DOC_LEVELS;
+  for (const child of entries) {
+    if (child.name === "AGENTS.md") continue;
+    if (!targets.includes(child.name)) {
+      if (child.isDirectory()) {
+        findings.push(createFinding({
+          message: `Unsupported verification category: ${child.name}`,
+          path: `${verificationPath}/${child.name}`,
+          ruleId: "verification-category",
+          severity: "error",
+        }));
+      }
+      continue;
+    }
+
+    if (!child.isDirectory()) {
+      findings.push(createFinding({
+        message: `Verification category is not a directory: ${child.name}`,
+        path: `${verificationPath}/${child.name}`,
+        ruleId: "verification-category",
+        severity: "error",
+      }));
+      continue;
+    }
+
+    summary.categories.push(child.name);
+    const categoryPath = `${verificationPath}/${child.name}`;
+    const documents = listFiles({
+      fs,
+      pathService,
+      prefix: categoryPath,
+      root: pathService.join(projectRoot, ...categoryPath.split("/")),
+    }).filter((file) => (
+      file.endsWith(".md")
+      && !file.endsWith("/AGENTS.md")
+      && !parseSkinFilename(file)
+    ));
+    if (documents.length === 0) {
+      findings.push(createFinding({
+        message: `Verification category has no durable specification: ${categoryPath}`,
+        path: categoryPath,
+        ruleId: "verification-empty-category",
+        severity: "error",
+      }));
+    }
+  }
+
+  if (summary.categories.length === 0) {
+    findings.push(createFinding({
+      message: `Verification block has no populated primary-target category: ${verificationPath}`,
+      path: verificationPath,
+      ruleId: "verification-empty-block",
+      severity: "error",
+    }));
+  }
+
+  return {findings, summary};
+}
+
 /**
  * Warns when a documentation level exceeds the recommended direct-entry capacity
  * and requires its local AGENTS.md to make an intentional exception explicit.
@@ -578,6 +750,14 @@ function validateSkinDocument({bodySet, constants, file, skinInfo, text}) {
       severity: "error",
     }));
   }
+  if (/^#{1,6}\s+Agent Document\s*#*\s*$/mi.test(text)) {
+    findings.push(createFinding({
+      message: "Redundant Agent Document section: skin pairing is derived from its filename",
+      path: file,
+      ruleId: "skin-redundant-agent-document-section",
+      severity: "error",
+    }));
+  }
   return findings;
 }
 
@@ -650,64 +830,6 @@ function normalizeRelativeSegments(parts) {
   return result;
 }
 
-/**
- * @param {string} text
- * @returns {string}
- */
-function stripFencedCodeBlocks(text) {
-  return text.replace(/```[\s\S]*?```/g, "");
-}
-
-/**
- * Extracts all human-facing skin content while excluding metadata and headings.
- *
- * @param {string} text
- * @returns {string}
- */
-function extractSkinMetricText(text) {
-  return stripSkinPresentation(text);
-}
-
-/**
- * @param {string} text
- * @returns {string}
- */
-function stripSkinPresentation(text) {
-  let insideLegacyReference = false;
-  return stripFencedCodeBlocks(text)
-    .split("\n")
-    .filter((line) => {
-      const trimmed = line.trim();
-      if (/^##\s+Agent Document\s*$/.test(trimmed)) {
-        insideLegacyReference = true;
-        return false;
-      }
-      if (insideLegacyReference && /^##\s+/.test(trimmed)) insideLegacyReference = false;
-      return !insideLegacyReference && !/^#/.test(trimmed) && !/^- (?:Path|Changed): `[^`]+`$/.test(trimmed);
-    })
-    .join("\n")
-    .replace(/^\s*(?:Includes|Excludes):\s*$/gmu, "");
-}
-
-/**
- * @param {string} text
- * @returns {number}
- */
-function countWords(text) {
-  const matches = stripFencedCodeBlocks(text).match(/(?:\p{L}[\p{L}\p{M}\p{N}'’_-]*|\p{N}+)/gu);
-  return matches ? matches.length : 0;
-}
-
-/**
- * @param {string} text
- * @returns {number}
- */
-function countMeaningfulListItems(text) {
-  return [...stripFencedCodeBlocks(text).matchAll(/^\s*(?:[-*+]|\d+[.)])\s+(.+)$/gmu)]
-    .filter((match) => countWords(match[1]) > 0)
-    .length;
-}
-
 export const __deps__ = Object.freeze({
   constants: "Fl32_Skill_Adsm_Ctx_Shared_Constants$",
   fs: "node:fs",