@flancer32/skill-adsm-ctx 0.2.1 → 0.3.0

package/ctx/docs/architecture/supervision.md

@@ -1,71 +0,0 @@
-# Architecture Supervision
-
-- Path: `ctx/docs/architecture/supervision.md`
-- Changed: `20260813`
-
-## Purpose
-
-Defines how one human and many agents supervise architecture-level consistency.
-
-## Human-Agent Supervision Principle
-
-Humans own architectural direction and guardrails.
-
-Agents operate within documented architectural boundaries and perform the default operating work.
-
-Architecture documentation is the authoritative medium through which the human direction-setting loop and the agent refinement and execution-support loop coordinate at the architecture level.
-
-Agents must surface architectural drift instead of silently resolving it.
-
-Major architectural boundary changes require human approval.
-
-## Human Responsibilities
-
-- own architectural direction and guardrails;
-- read semantic skins and relevant control documents frequently enough to detect drift early;
-- approve new boundaries, persistent state, and integrations;
-- resolve contradictions that architecture cannot settle from existing product knowledge.
-
-## Agent Responsibilities
-
-- refine architecture documents within existing boundaries;
-- prefer documentation updates before code when new architectural concepts appear;
-- detect and report architectural drift;
-- audit documentation corpora against declared ADSM documentation quality criteria when requested;
-- compress documentation corpora only when accepted meaning, authority homes, and scope boundaries are clear;
-- keep template-level workflow guidance separate from project-level workflow meaning;
-- check product and architecture documents before code-oriented work.
-
-## Mandatory Approval Cases
-
-Human approval is required for:
-
-- new architectural owners;
-- new persistent state;
-- new external integrations;
-- new trust boundaries;
-- new major system areas;
-- changes that resolve documentation quality findings by adding product meaning, architecture boundaries, or authority rules absent from existing context.
-- compression changes that require choosing between contradictory meanings or deleting unclear project-specific knowledge.
-
-## Drift Signals
-
-Architectural drift is present when:
-
-- implementation introduces concepts absent from product or architecture documentation;
-- architecture contradicts product roles, use cases, or domain entities;
-- template-level workflow guidance is applied as if it overruled project-defined workflow semantics;
-- documentation quality audit findings identify unresolved contradiction, missing upstream meaning, or duplicated authority across context documents;
-- documentation compression removes, weakens, or generalizes accepted project-specific meaning;
-- an agent document contradicts its matching semantic skin;
-- new durable state appears without declared ownership;
-- new integrations or boundaries appear only in code or environment artifacts.
-
-## Pre-Code Check Order
-
-Before code-oriented work, agents should check:
-
-1. `ctx/docs/product/overview.md` and related product documents for meaning and scope;
-2. matching `*.skin.<lang>.md` files where they exist;
-3. `ctx/docs/architecture/*.md` and nested architecture documents for structure, behavior, state, integrations, constraints, decisions, and supervision;
-4. downstream environment and code documents for realization rules.

package/ctx/docs/code/AGENTS.md

@@ -1,51 +0,0 @@
-# Code Documentation
-
-- Path: `ctx/docs/code/AGENTS.md`
-- Changed: `20260708`
-
-## Purpose
-
-Defines the code documentation level.
-
-Documents at this level translate architecture intent into source-level engineering invariants: what counts as product code, how architecture is expressed in implementation, and how code is tested.
-
-## Level Map
-
-- `AGENTS.md` — level definition for `ctx/docs/code/`.
-- `overview.md` — product code boundary, code responsibilities, and code invariants.
-- `testing.md` — test boundary, required coverage areas, and testing conventions.
-
-## Level Boundary
-
-Defines:
-
-- Product code boundary — what files and directories constitute executable or consumable product artifacts.
-- Code invariants — rules that govern how architecture is expressed in implementation.
-- Testing conventions — test structure, coverage expectations, and verification scope.
-
-Does NOT define:
-
-- Product meaning, domain entities, or use-case outcomes.
-- Architecture ownership, system boundaries, or integration contracts.
-- Deployment topology, runtime environment, or operational runbooks.
-
-## Relationship To Upstream Levels
-
-Code depends on architecture and environment documentation.
-
-The dependency order is:
-
-```text
-product
-  → architecture
-  → environment
-  → code
-```
-
-Code may refine realization details but must not redefine architecture structure, introduce new persistent state, create new external integrations, or bypass documented constraints.
-
-Code invariants must remain consistent with architecture decisions and environment assumptions.
-
-## Local Rules
-
-- Preserve nested code subdirectories when they improve maintainability.

package/ctx/docs/code/overview.md

@@ -1,53 +0,0 @@
-# Code Overview
-
-- Path: `ctx/docs/code/overview.md`
-- Changed: `20260715`
-
-## Purpose
-
-Defines what counts as product code in this repository.
-
-## Product Code Boundary
-
-Product code includes both executable JavaScript and agent-consumed documentation artifacts.
-
-Product code includes:
-
-- `bin/` as the CLI entry points;
-- `src/` as lifecycle implementation modules;
-- `skill/SKILL.md` as the operational skill artifact;
-- `skill/references/` as supporting guidance consumed by agents;
-- `skill/templates/ctx/` as reusable initialization assets;
-- `skill/templates/work/` as working templates for agent-produced operational outputs.
-
-## Code Responsibilities
-
-- `bin/` exposes the CLI entry surface only.
-- `src/` implements CLI-backed lifecycle behavior, filesystem operations, deterministic documentation lint for `ctx/docs/**`, and upgrade logic.
-- `skill/` defines the installable agent payload that must be copied as a coherent bundle.
-
-## Service Control Files
-
-`AGENTS.md` files are service control files consumed by agents during project work.
-
-They are not the originating specification for their own format or hierarchy.
-
-Local directory rules are described in the corresponding `AGENTS.md` file for each directory.
-
-The skill and code consume and operationalize those local routing instructions directly from the applicable `AGENTS.md` hierarchy.
-
-For this product, implementation-level handling of `AGENTS.md` must preserve these rules:
-
-- `AGENTS.md` files are interpreted as operational instructions within already-declared product and architecture boundaries;
-- hierarchy resolution is derived from repository structure and upstream documentation rules, not invented ad hoc by the skill;
-- when a context-side `AGENTS.md` uses `Level Boundary`, that section is shaped as a compact guardrail rather than an exhaustive specification;
-- validation logic may check `AGENTS.md` structure and placement, but must treat `ctx/docs` as the authoritative source of those requirements.
-- validation logic may apply deterministic checks to semantic skins, but it must not impose a rigid template on ordinary agent documents.
-
-## Code Invariants
-
-- `install-skill` installs the current contents of `skill/` into the target skills root as one payload.
-- Repository self-context under `ctx/` and reusable starter context under `skill/templates/ctx/` are separate artifacts and must not be treated as interchangeable.
-- Lifecycle commands must prefer declared context and template state over inferred project-specific assumptions.
-- Deterministic validation may reject structural documentation defects, including undocumented documentation-level capacity exceptions, and assess semantic skins from the content of `Purpose`, `Mental Model`, `Scope`, and `Invariants` only: warn above 160 Unicode-aware words or 10 meaningful list items, and fail above 220 words or 14 items. Semantic document quality remains outside CLI validation.
-- Code changes that expand durable state, external integrations, or architectural boundaries require prior documentation updates.

package/ctx/docs/code/testing.md

@@ -1,26 +0,0 @@
-# Testing Overview
-
-- Path: `ctx/docs/code/testing.md`
-- Changed: `20260715`
-
-## Purpose
-
-Defines the test boundary for this repository.
-
-## Test Boundary
-
-- `test/unit/` contains targeted isolated coverage for selected modules and helpers; it does not yet mirror `src/`.
-- `test/integration/` verifies composed runtime behavior through CLI scenarios and observable lifecycle invariants.
-
-## Current Coverage
-
-- Unit coverage currently exists for bootstrap-level behavior.
-- Unit coverage now also exercises deterministic validation logic for document metadata, agent/skin pairs, skin structure checks, `Scope` block checks, local markdown link checks, Unicode-aware semantic skin compactness thresholds, and documentation-level capacity exceptions.
-- Integration coverage currently exercises end-to-end CLI behavior for `init`, `validate`, and `install-skill`.
-- Installation-oriented tests verify observable installed payload structure rather than only internal helper calls.
-
-## Coverage Intent
-
-- Unit tests should cover lifecycle services, shared helpers, CLI parsing, and skill-installation wiring in isolation.
-- Validation tests should distinguish blocking structural errors from non-blocking heuristic warnings.
-- Tests that exercise `AGENTS.md` handling should verify that validation and initialization follow requirements declared in `ctx/docs` rather than treating `AGENTS.md` as the source of its own specification.

package/ctx/docs/environment/AGENTS.md

@@ -1,50 +0,0 @@
-# Environment Documentation
-
-- Path: `ctx/docs/environment/AGENTS.md`
-- Changed: `20260708`
-
-## Purpose
-
-Defines the environment documentation level.
-
-Documents at this level describe the runtime environment, infrastructural prerequisites, and operational assumptions required for system operation.
-
-## Level Map
-
-- `AGENTS.md` — level definition for `ctx/docs/environment/`.
-- `overview.md` — runtime assumptions, execution surfaces, external prerequisites, and operational constraints.
-
-## Level Boundary
-
-Defines:
-
-- Runtime environment assumptions — language runtime, filesystem model, and execution surfaces.
-- External prerequisites — required tooling, minimum versions, and expected infrastructure.
-- Operational constraints — conditions under which the system must remain valid regardless of deployment context.
-
-Does NOT define:
-
-- Product meaning, domain entities, or use-case outcomes.
-- Architecture structure, system boundaries, or state ownership.
-- Source-level implementation details, testing conventions, or code invariants.
-
-## Relationship To Upstream Levels
-
-Environment depends on architecture documentation and feeds into code.
-
-The dependency order is:
-
-```text
-product
-  → architecture
-  → environment
-  → code
-```
-
-Environment may add operational precision and constraints but must not redefine architecture structure or introduce new product capabilities.
-
-Code-level documents must respect environment assumptions as non-negotiable prerequisites.
-
-## Local Rules
-
-- Preserve nested environment subdirectories when they improve maintainability.

package/ctx/docs/environment/overview.md

@@ -1,33 +0,0 @@
-# Environment Overview
-
-- Path: `ctx/docs/environment/overview.md`
-- Changed: `20260702`
-
-## Purpose
-
-Defines the runtime environment assumptions for this repository.
-
-## Runtime Assumptions
-
-- Node.js executes the CLI, lifecycle logic, and automated tests.
-- The package operates on local filesystem paths in the current repository or in explicitly provided target directories.
-- The package must not depend on hardcoded absolute paths at runtime.
-
-## Execution Surfaces
-
-- local CLI execution runs through `node` and the installed `adsm-ctx` entry point;
-- package installation provides the CLI and bundled `skill/` payload to the host machine;
-- agent-skill installation copies the packaged skill payload into the inter-agent skills root under `~/.agents/skills`;
-- repository automation runs against a checked-out repository and uses the repository-local `ctx/` as its context source.
-
-## External Prerequisites
-
-- Node.js `>=20` is required by the package contract.
-- npm is the expected package-installation surface for local development and global installation.
-- The repository is expected to be available as a writable working tree when lifecycle commands or workflow automation modify files.
-
-## Operational Environment Constraints
-
-- Runtime behavior must remain valid whether the repository is executed from a developer checkout or from a globally installed package.
-- Installation and validation flows must work with relative target paths supplied by the caller.
-- Automation assumptions that depend on concrete tools, events, labels, or trusted actors belong to project-local materials under `ctx/agent/` rather than to the ADSM baseline.

package/ctx/docs/filesystem.md

@@ -1,44 +0,0 @@
-# Filesystem Structure
-
-- Path: `ctx/docs/filesystem.md`
-- Changed: `20260707`
-
-## Purpose
-
-Defines the declarative structure of the skill repository at the top level only and establishes repository boundaries as a navigation model.
-
-## Root Structure
-
-- `.github/` — GitHub automation definitions, including the workflow that publishes `github-flows` application configuration.
-- `bin/` — executable entry points for local lifecycle tooling.
-- `ctx/` — cognitive context containing declarative documentation for this repository itself.
-- `migrations/` — future migration definitions for context upgrades.
-- `skill/` — installable skill payload consumed by agents.
-- `src/` — implementation logic for CLI-backed lifecycle operations and shared helpers.
-- `test/` — executable tests for CLI and lifecycle behavior.
-
-## Root Files
-
-- `.gitignore` — version-control exclusion rules.
-- `AGENTS.md` — root-level ADSM invariants.
-- `jsconfig.json` — JavaScript language-service configuration.
-- `LICENSE` — license definition.
-- `README.md` — public human-facing documentation for the package.
-- `package-lock.json` — npm dependency lockfile.
-- `package.json` — package metadata, scripts, and CLI registration.
-- `types.d.ts` — project-local type declarations.
-
-## Scope Rule
-
-This document describes only top-level directories and root-level files.
-
-Subdirectory structure, including anything inside `ctx/`, must be described in the corresponding lower-level documentation and service-control files when needed.
-
-`AGENTS.md` files may describe local operational boundaries, but the normative rules for their structure belong to the declarative documentation under `ctx/docs/`.
-
-## Product Boundary
-
-- `skill/` and `src/` are product artifacts of this repository.
-- `skill/templates/ctx/` is the reusable template baseline installed into other projects.
-- `skill/templates/work/` contains working templates for agent operations and is not installed into project `ctx/` by default.
-- `ctx/` documents this repository as a skill product.

package/ctx/docs/product/AGENTS.md

@@ -1,51 +0,0 @@
-# Product Documentation
-
-- Path: `ctx/docs/product/AGENTS.md`
-- Changed: `20260708`
-
-## Purpose
-
-Defines the product documentation level.
-
-Documents at this level describe the system as a product: its meaning, purpose, scope, domain language, user roles, product boundaries, and product-level invariants.
-
-## Level Map
-
-- `AGENTS.md` — level definition for `ctx/docs/product/`.
-- `domain.md` — product domain model; describes the product world, domain areas, business entities, ownership, and semantic relations, not storage structure.
-- `glossary.md` — product terminology; defines stable product terms and prevents terminology drift.
-- `overview.md` — product identity, scope, boundaries, and product-level orientation.
-- `roles.md` — user role model; describes role categories, authority, permissions, ownership boundaries, and responsibility boundaries.
-- `use-cases.md` — product use cases; describes user goals and expected outcomes, not UI, API, or implementation flows.
-
-## Product Knowledge Model
-
-Product knowledge is organized through complementary agent documents:
-
-- `domain.md` — the product world.
-- `roles.md` — product participants and authority.
-- `use-cases.md` — user goals and expected outcomes.
-- `glossary.md` — product language.
-- `overview.md` — product identity, scope, and boundaries.
-
-Together these models provide the primary understanding of the product.
-
-If an agent document grows too large to maintain, move operational detail into a natural product subdocument or nested subdirectory.
-
-## Local Rules
-
-- Preserve nested product subdirectories when they improve maintainability.
-
-## Level Boundary
-
-Defines:
-
-- Product identity, scope, and explicit exclusions.
-- Product language, roles, and authority boundaries.
-- Product-level user goals, expected outcomes, and durable invariants.
-
-Does NOT define:
-
-- Architectural structure, system decomposition, or integration boundaries.
-- Execution environment, deployment topology, or code-level implementation constraints.
-- Agent workflow behavior, repository operations, or methodological rules above this level.

package/ctx/docs/product/domain.md

@@ -1,63 +0,0 @@
-# Product Domain
-
-- Path: `ctx/docs/product/domain.md`
-- Changed: `20260813`
-
-## Domain Purpose
-
-The domain of this product is ADSM project cognitive context lifecycle management.
-
-The skill manages the structure, validation, audit, compression, upgrade, and agent-facing guidance for project cognitive context without inventing project-specific product meaning.
-
-## Core Domain Objects
-
-- **ADSM context** — the project cognitive context mounted under `ctx/`; it is the durable communication medium between humans and agents.
-- **Skill payload** — the installable `skill/` bundle consumed by an agent skill host as `adsm-ctx`.
-- **Skills root** — the caller-provided directory under which `install-skill` installs the bundled skill payload.
-- **Documentation level** — one of the four top-level documentation branches under `ctx/docs/`: `product/`, `architecture/`, `environment/`, and `code/`.
-- **Project-specific nested substructure** — directories and documents inside a documentation level; it is chosen by the project and is not fixed by ADSM.
-- **Agent document** — an ordinary `*.md` file under `ctx/docs/**`; it contains operational project knowledge in a form optimized for agent interpretation and maintenance.
-- **Semantic skin** — a short `*.skin.<lang>.md` file under `ctx/docs/**`; it captures human-facing semantic invariants for the matching agent document.
-- **Agent/skin pair** — an agent document and skin with the same basename in the same directory, such as `domain.md` and `domain.skin.en.md`.
-- **Projection drift** — conflict between an agent document and its skin, an orphan skin without a matching agent document, or an artifact that introduces authoritative meaning not present in agent or skin documents.
-- **AGENTS.md local routing file** — a short service-control file that tells agents how to read, edit, and route work in its local directory scope.
-- **ctx/assets artifact space** — the place for visual, generated, rendered, or auxiliary artifacts that may illustrate meaning but must not define authoritative project knowledge.
-- **Lifecycle mode** — a skill operation such as `init`, `design`, `validate`, `quality-audit`, `documentation-compression`, or `upgrade`.
-- **Human decision / escalation** — a required human intervention when an agent detects projection drift, missing upstream meaning, a skin conflict, or an unsafe change in controlled meaning.
-
-## Core Relations
-
-- An ADSM context contains project-facing documentation under `ctx/docs/` and project-local agent materials under `ctx/agent/`.
-- The skill payload is installed separately from initialized project context and must remain a coherent copy of `skill/`.
-- The skills root is an external installation target and is not a project cognitive context.
-- `ctx/docs/` contains exactly four top-level documentation levels by ADSM convention: `product/`, `architecture/`, `environment/`, and `code/`.
-- Each documentation level may contain project-specific nested substructure when that improves maintainability.
-- Agent documents carry operational detail by default.
-- Skins govern matching agent documents only when human semantic control is needed.
-- Agents must read a matching skin before changing its matching agent document.
-- An agent-document change that violates its skin requires a human decision.
-- Assets may support agent and skin documents visually, but those documents remain the source of authoritative meaning.
-- `AGENTS.md` routes local agent behavior; it does not replace agent documents, skins, or product meaning.
-
-## Lifecycle Behavior
-
-- `init` creates a minimal ADSM-compatible context baseline.
-- `design` shapes documentation levels and project-specific substructure without guessing project meaning.
-- `validate` reports structural and deterministic projection-model findings, including lightweight document-shape and local-link checks for `ctx/docs/**`, without destructive edits.
-- `quality-audit` evaluates agent documents, skins, and their alignment against ADSM quality criteria.
-- `documentation-compression` rewrites agent documents for density only when accepted meaning and skin-controlled meaning are preserved.
-- `upgrade` migrates existing contexts to current conventions while preserving project-specific content.
-- `install-skill` installs the current skill payload into a caller-provided skills root; it is a package-support operation, not a context lifecycle mode.
-
-## Domain Invariants
-
-- The skill remains generic and orchestration-oriented.
-- ADSM defines the four top-level documentation levels, not a rigid internal tree below them.
-- Ordinary `*.md` files are agent-facing operational context documents by default.
-- `*.skin.<lang>.md` files are optional semantic control surfaces, not summaries.
-- Deterministic validation may require paired agent documents, required skin sections, `Scope` subblocks, valid local markdown links, and compactness thresholds for skins.
-- `overview.md` has no special methodology-level status.
-- `README.md` is not required inside `ctx/docs/`.
-- `agents-files.md` is not required.
-- Human decisions are required when agents would need to invent project meaning, weaken a skin, or silently resolve projection drift.
-- Skill payload installation must not alter a target project's `ctx/` content.

package/ctx/docs/product/domain.skin.en.md

@@ -1,40 +0,0 @@
-# Product Domain Skin
-
-- Path: `ctx/docs/product/domain.skin.en.md`
-- Changed: `20260813`
-
-## Purpose
-
-This skin preserves the stable domain objects and relations for ADSM context lifecycle management.
-
-## Mental Model
-
-ADSM context uses agent-facing operational documents by default, while optional skins preserve the human semantic frame for selected key documents.
-
-## Scope
-
-Includes:
-
-- the stable domain objects and relations behind the ADSM context lifecycle;
-- the distinction between agent documents, skins, assets, and `AGENTS.md` routing files;
-- the optional nature of `*.skin.<lang>.md` pairing.
-
-Excludes:
-
-- low-level implementation behavior;
-- validation internals;
-- CLI command wording.
-
-## Invariants
-
-- ADSM context uses agent-facing operational documents by default.
-- ADSM defines four top-level documentation levels: `product/`, `architecture/`, `environment/`, and `code/`.
-- Humans control meaning through optional matching `*.skin.<lang>.md` files.
-- Agent documents carry operational detail; skins control semantic invariants.
-- Project-specific nested substructure is allowed inside each documentation level.
-- `AGENTS.md` files are local routing files, not full documentation artifacts.
-- `ctx/assets/**` contains artifacts that illustrate meaning but do not define it.
-
-## Agent Document
-
-`domain.md`

package/ctx/docs/product/glossary.md

@@ -1,31 +0,0 @@
-# Product Glossary
-
-- Path: `ctx/docs/product/glossary.md`
-- Changed: `20260813`
-
-## Terms
-
-- **ADSM** — Agent-Driven Software Management.
-- **Agent External Context** — the reserved `ctx/agent/` branch used for project-local materials about tools, relationships, or routines that sit outside ADSM methodology.
-- **Agent Skill Host** — the environment that loads installed agent skill payloads.
-- **Bootstrap Marker** — the minimal text left in installed project-facing templates to identify the context as ADSM-managed and direct agents to skill `adsm-ctx` for validation and methodology rules.
-- **Cognitive Context** — the declarative project context mounted under `ctx/`.
-- **Agent Document** — an ordinary `*.md` document under `ctx/docs/**`; agent documents are optimized primarily for agent routing, interpretation, and execution without guessing.
-- **Agent/Skin Pair** — an agent document and its matching semantic skin in the same directory with the same basename, such as `domain.md` and `domain.skin.en.md`.
-- **Documentation Compression** — agent-performed controlled rewrite of a project documentation corpus that reduces attention cost while preserving accepted project meaning.
-- **Documentation Quality Audit** — agent-performed review of a documentation corpus against ADSM documentation quality criteria, producing evidence-backed findings rather than automatic semantic scoring.
-- **Documentation Quality Criterion** — one of the ADSM corpus quality dimensions used during documentation quality audit: declarativity, consistency, completeness, connectedness, density, compactness, non-redundancy, or absence of obvious descriptions.
-- **Projection Drift** — a conflict between an agent document and matching skin, an orphan skin without a matching agent document, or an asset that introduces meaning not present in agent or skin documents.
-- **Semantic Skin** — a short `*.skin.<lang>.md` document that acts as a human-facing semantic control surface for the matching agent document.
-- **Human Supervisor** — the human role that sets goals and guardrails, reviews outcomes, and intervenes when agent work drifts from expected product or architecture boundaries.
-- **Lifecycle Mode** — one of `init`, `design`, `validate`, `quality-audit`, `documentation-compression`, or `upgrade`.
-- **Specialized Skill** — a separate skill that may help produce or refine a domain-specific context branch, but is not the only valid source of project-specific semantics.
-- **Skill Payload** — the bundled contents of `skill/` installed into an agent skill host as `adsm-ctx`.
-- **Skills Root** — the caller-provided installation root under which the skill payload is installed.
-- **Specialization Gap** — a required context area for which no specialized skill is available.
-- **Audit Finding** — a documented discovery produced during a documentation quality audit, including criterion, severity, location, issue, evidence, impact, suggested action, and decision status.
-- **Working Report Template** — an agent-facing output template used during skill operations such as audit, compression, and validation and not installed into project `ctx/` by default.
-- **Context Template** — a reusable starter artifact from `skill/templates/ctx/` that provides the baseline cognitive-context structure for downstream projects while keeping ADSM methodology in the skill and references rather than in project-facing template text.
-- **Validation Finding** — a documented structural discrepancy produced during context validation, reporting missing or malformed expected files against the ADSM baseline.
-- **Migration** — a controlled, non-destructive transformation of project cognitive context from one convention version to another, preserving project-specific content.
-- **Specialization Support** — the capability to detect, route toward, or integrate with specialized skills for project-specific documentation branches.

package/ctx/docs/product/overview.md

@@ -1,112 +0,0 @@
-# Product Overview
-
-- Path: `ctx/docs/product/overview.md`
-- Changed: `20260708`
-
-## Product Identity
-
-This product is an ADSM skill package for building and evolving project cognitive context.
-
-It serves a human-and-agent working group in which agents perform most lifecycle work and humans set guardrails, inspect results, and correct drift.
-
-## Product Mission
-
-Provide a generic, reusable foundation for project cognitive context management without inventing project-specific knowledge.
-
-## Product Scope
-
-The product is responsible for:
-
-- creating baseline context structure;
-- installing the bundled skill payload into a configured agent skills root;
-- providing reusable product-level and architecture-level templates with only minimal ADSM bootstrap markers;
-- validating structural conformance and lightweight deterministic document shape under `ctx/docs/`;
-- guiding agent-performed quality audits of documentation corpora against ADSM documentation quality criteria;
-- guiding agent-performed documentation compression of `ctx/docs/` corpora without changing accepted project meaning;
-- guiding context design and upgrade decisions;
-- reserving the `ctx/agent/` boundary file while leaving project-local tool materials outside the ADSM baseline.
-
-This scope is intentionally stated as stable product orientation, with operational detail left to the matching domain, roles, use-case, and glossary documents.
-
-## Product Areas
-
-- lifecycle tooling;
-- skill payload installation;
-- agent-facing guidance and routing documents;
-- audit and compression guidance;
-- reusable product and architecture context templates;
-- semantic control surfaces for high-level orientation and drift diagnosis;
-- reserved boundary support for `ctx/agent/`;
-- repository self-documentation.
-
-## Core Lifecycle
-
-The primary lifecycle is:
-
-1. initialize baseline context;
-2. design project-specific structure;
-3. validate the resulting context;
-4. audit documentation quality when corpus-level supervision is needed;
-5. compress documentation when accepted meaning is stable but attention cost is high;
-6. upgrade the context when conventions evolve.
-
-Operationally, agents perform most of this lifecycle work. Humans intervene mainly to set boundaries, approve expansion, and correct unexpected agent interpretation.
-
-Skill payload installation is a package-support capability that enables agents to use this lifecycle guidance.
-
-It is not itself a context lifecycle mode.
-
-## Product Boundaries
-
-### In Scope
-
-- generic ADSM context lifecycle management;
-- installation of the bundled `skill/` payload into a caller-provided agent skills root;
-- minimal template markers that identify an installed context as ADSM-managed and point agents to skill `adsm-ctx` for validation and methodology rules;
-- agent guidance for documentation quality audit and controlled documentation compression;
-- structural management of the `ctx/agent/` boundary file without prescribing project-local subdirectories;
-- orchestration toward specialized skills;
-- non-destructive structure validation and upgrade support.
-
-### Out of Scope
-
-- product-specific requirements definition;
-- embedding detailed ADSM conformance rules directly into downstream project-facing templates;
-- automatic semantic scoring or automatic semantic correction of project documentation quality;
-- changing project meaning during documentation compression;
-- authoritative tool-specific instructions, workflow meaning, event semantics, or project-specific flow rules;
-- specialized browser, backend, data, or deployment documentation logic;
-- implementation of business-domain documentation as guessed content.
-
-## MVP Boundary
-
-The current version provides a working skeleton with executable CLI commands, bundled skill installation, bundled templates, baseline validation, documentation quality audit guidance, documentation compression guidance, and upgrade hooks.
-
-The documentation quality audit and documentation compression capabilities are agent-guidance capabilities, not CLI validation capabilities.
-
-`validate` is the deterministic preflight for the documentation corpus.
-
-It may reject structural defects such as broken pairing, missing required skin sections, missing `Scope` subblocks, or broken local markdown links, and it may emit heuristic warnings when a semantic skin grows beyond compact supervision thresholds.
-
-## Product Invariants
-
-- Project cognitive context is the main managed object.
-- The skill must remain generic and orchestration-oriented.
-- Agents perform the default operating work; humans provide guardrails and correction.
-- Project documents should govern the project itself; ADSM conformance checking belongs to the skill.
-- `AGENTS.md` files are service control files for agent work inside a project and must not act as the originating specification for ADSM rules about themselves.
-- Installed project-facing templates may contain only the minimal ADSM bootstrap signal needed to identify the context and route validation to skill `adsm-ctx`.
-- The skill defines only the `ctx/agent/` boundary file; project-local tool materials under that branch remain outside the ADSM baseline.
-- Skill payload installation copies the current `skill/` bundle as a coherent agent-consumed payload and must not modify project context.
-- Documentation quality audits must report evidence-backed findings and must not silently invent or correct project meaning.
-- Deterministic validation may check skin structure and compactness heuristics, but ordinary agent documents remain minimally constrained.
-- Documentation compression must preserve accepted project meaning while reducing attention cost.
-- Specialized skills may help formulate tool-specific semantics, but they are optional support rather than the only valid source of such semantics.
-- Missing specialization must be reported, not guessed around.
-
-## Related Bodies
-
-- Read `domain.md` for the product domain boundary.
-- Read `roles.md` for participating roles.
-- Read `use-cases.md` for lifecycle-oriented user goals.
-- Read `glossary.md` for stable terminology.