@flancer32/skill-adsm-ctx 0.2.1

package/ctx/docs/architecture/decisions.md

@@ -0,0 +1,118 @@
+# Architecture Decisions
+
+- Path: `ctx/docs/architecture/decisions.md`
+- Changed: `20260813`
+
+## Purpose
+
+Records durable architecture decisions for the skill product.
+
+## A1. Generic Orchestration First
+
+Decision:
+The skill stays generic and manages cognitive-context lifecycle rather than project-specific implementation domains.
+
+Rejected alternative:
+Encode browser, backend, deployment, or domain-specific architecture directly into the baseline skill.
+
+Reasoning:
+Project specialization belongs in dedicated skills or project context, not in the generic lifecycle baseline.
+
+## A2. Architecture Is A Separate Level
+
+Decision:
+Architecture remains a distinct documentation level between product and environment.
+
+Rejected alternative:
+Fold structural guidance into product documents or jump directly from product documents to code-oriented constraints.
+
+Reasoning:
+The working group needs a stable place for engineering boundaries, state ownership, integrations, and supervision rules.
+
+## A3. Live Context And Installed Templates Stay Separate
+
+Decision:
+This repository's own `ctx/` documents the product, while `skill/templates/ctx/` provides reusable starter context for other projects.
+
+Rejected alternative:
+Treat the repository context and the installable template payload as the same artifact.
+
+Reasoning:
+The product needs self-documentation and reusable output, but those artifacts serve different consumers and change for different reasons.
+
+## A4. Documentation Precedes Structural Change
+
+Decision:
+New architectural concepts are documented before downstream code or environment changes.
+
+Rejected alternative:
+Allow architecture to emerge only from implementation diffs.
+
+Reasoning:
+ADSM uses documentation as an operational interface; architecture drift must be visible before it is encoded.
+
+## A5. Boundary Expansion Requires Human Approval
+
+Decision:
+Agents may refine architecture inside existing guardrails, but expanding owners, persistent state, integrations, or system boundaries requires human approval.
+
+Rejected alternative:
+Permit autonomous architectural expansion when implementation seems straightforward.
+
+Reasoning:
+Those changes alter the supervision burden and must remain under human control.
+
+## A6. Documentation Quality Audit Is Agent-Guided
+
+Decision:
+Documentation quality audit is implemented as agent guidance over the declarative project documentation corpus under `ctx/docs/`, not as CLI semantic scoring.
+
+Rejected alternative:
+Encode documentation quality scoring as an automatic CLI validation command over the whole cognitive context.
+
+Reasoning:
+The quality criteria require semantic reading, evidence-backed findings, and separation of editorial issues from missing human decisions. Operational context such as agent workflows, prompts, and runtime configuration may exist under `ctx/`, but it is not part of the default documentation quality corpus.
+
+## A7. Documentation Compression Is Controlled Rewrite
+
+Decision:
+Documentation compression is implemented as agent guidance over the declarative project documentation corpus under `ctx/docs/`, not as automatic semantic scoring or broad context rewriting.
+
+Rejected alternative:
+Let compression freely summarize the whole cognitive context or treat operational context as part of the default corpus.
+
+Reasoning:
+Compression changes text directly and therefore needs stronger authority discipline than audit. The default scope remains `ctx/docs/`, and accepted project meaning must be preserved while redundancy and low-density wording are reduced.
+
+## A8. Agent/Skin Projection Defines Document Control
+
+Decision:
+Documents under `ctx/docs/**` are agent-facing operational context documents by default, and human semantic control is expressed through optional matching `*.skin.<lang>.md` files.
+
+Rejected alternative:
+Use document metadata markers as the primary semantic-control mechanism.
+
+Reasoning:
+The working model of this product is one human and many agents. Agent-first is the normal operating mode, but human control needs a stronger semantic projection than a metadata marker. A `*.skin.<lang>.md` file provides an explicit control surface for the matching agent document without turning that document into a human-oriented summary.
+
+## A9. The Skill Enforces ADSM Discipline
+
+Decision:
+Project documentation templates should focus on governing a project, while ADSM conformance rules are enforced by the skill itself.
+
+Rejected alternative:
+Embed most ADSM discipline directly into project-facing document templates and make project documents explain the methodology to themselves.
+
+Reasoning:
+Project cognitive context should spend attention on product and architecture control, not on repeated methodological self-description. Installed templates should carry only the minimal bootstrap signal that the context follows ADSM and that structural validation belongs to skill `adsm-ctx`. The skill is the correct place for template discipline, audit logic, compression rules, and other ADSM conformance checks.
+
+## A10. `AGENTS.md` Is A Control Surface, Not A Spec Origin
+
+Decision:
+`AGENTS.md` files are service control files for agent work. Their own requirements originate in declarative documents under `ctx/docs/`, then are operationalized by the skill.
+
+Rejected alternative:
+Let `AGENTS.md` files define the normative rules for the `AGENTS.md` hierarchy, structure, and authoring format by themselves.
+
+Reasoning:
+Allowing `AGENTS.md` to legislate its own format mixes specification with execution control. The specification layer must stay in `ctx/docs/`; the skill may then detail and validate it; individual `AGENTS.md` files only execute that already-declared model in local project work.

package/ctx/docs/architecture/integration.md

@@ -0,0 +1,31 @@
+# Architecture Integration
+
+- Path: `ctx/docs/architecture/integration.md`
+- Changed: `20260707`
+
+## Purpose
+
+Defines the major integration boundaries of the skill product.
+
+## External Integrations
+
+- local project filesystem — target of context initialization, validation, and upgrade work;
+- package installation environment — distribution surface for the CLI and reusable templates;
+- agent skill host — installation target for the bundled skill payload;
+- source-control workflow — durable channel for reviewing and propagating template changes.
+
+## Internal Contracts
+
+- lifecycle operations consume declared repository context before making structure decisions;
+- reusable templates provide the baseline artifact set for initialized projects;
+- skill installation connects the CLI `install-skill` command, the source `skill/` payload, and the caller-provided skills root;
+- documentation quality audit guidance connects the source prompt in `skill/references/documentation-quality-audit.md`, the working report template in `skill/templates/work/report/`, and agent-produced audit reports;
+- documentation compression guidance connects the source prompt in `skill/references/documentation-compression.md`, the working report template in `skill/templates/work/report/`, and agent-produced compression reports;
+- repository `ctx/` documents the product and governs changes to templates and implementation;
+- specialization routing hands project-specific architecture work to dedicated skills when they exist.
+
+## Integration Boundaries
+
+- This document defines contract surfaces, not endpoint schemas or DTOs.
+- External integrations must remain explicit in architecture before they appear in implementation.
+- New integrations that affect project boundaries require supervision updates and human approval.

package/ctx/docs/architecture/overview.md

@@ -0,0 +1,76 @@
+# Architecture Overview
+
+- Path: `ctx/docs/architecture/overview.md`
+- Changed: `20260708`
+
+## Purpose
+
+Defines architecture-level orientation for this skill product.
+
+## Architecture Role
+
+At this level, product intent is translated into stable engineering structure.
+
+This level answers:
+
+- what is structurally built;
+- how the system behaves internally;
+- where state is owned;
+- what integrations exist;
+- what constraints must not be violated;
+- why key architectural decisions were made;
+- how human and agents supervise architectural consistency.
+
+This document answers those questions briefly and identifies the related architecture documents that hold more detail.
+
+## Architectural Style
+
+The product uses a documentation-first lifecycle architecture with separate surfaces for lifecycle execution, guidance, reusable templates, and supervision.
+
+## Major Areas
+
+- lifecycle orchestration for `init`, `design`, `validate`, `quality-audit`, `documentation-compression`, and `upgrade`;
+- skill payload installation for agent skill hosts;
+- agent-facing audit and compression guidance;
+- semantic-skin-ready control surfaces for orientation, constraints, and checklists;
+- reusable product-level and architecture-level context templates;
+- reserved `ctx/agent/` boundary for project-local materials outside ADSM methodology;
+- repository context that governs the package itself;
+- migration and validation boundaries that preserve project-specific content;
+- specialization routing boundary.
+
+## Related Bodies
+
+- Read `structure.md` when the question is "what are the main architectural areas and boundaries?"
+- Read `behavior.md` when the question is "how do those areas work together through major internal flows?"
+- Read `checklists.md` when the question is "which fast human checks should I run before concluding that agent work drifted?"
+- Read `state.md` when the question is "where is authoritative state owned, persisted, changed, and derived?"
+- Read `integration.md` when the question is "which external systems and internal contract boundaries matter?"
+- Read `constraints.md` when the question is "which architectural options are forbidden or non-negotiable?"
+- Read `decisions.md` when the question is "why was this architecture chosen over other durable alternatives?"
+- Read `supervision.md` when the question is "what may agents change, what requires approval, and what signals drift?"
+
+## Product Dependency
+
+This level depends on product documentation.
+
+Product documentation defines what this skill is and what it is responsible for.
+
+Architecture defines how that product intent is realized structurally.
+
+The expected dependency is:
+
+```text
+product
+  → architecture
+  → environment
+  → code
+```
+
+Architecture must not redefine product meaning, invent missing product behavior, or normalize product contradictions silently.
+
+## Human-Agent Use
+
+The architecture level is an operational interface between one human and many agents.
+
+The human owns direction and guardrails. Agents may refine architecture within those guardrails and must report drift instead of deciding past the declared boundary.

package/ctx/docs/architecture/state.md

@@ -0,0 +1,50 @@
+# Architecture State
+
+- Path: `ctx/docs/architecture/state.md`
+- Changed: `20260707`
+
+## Purpose
+
+Defines state ownership and sources of truth for the skill product.
+
+## Sources Of Truth
+
+- `ctx/` is the declarative source of truth for this repository as a product.
+- `skill/` is the source of truth for the installed agent skill payload.
+- `skill/templates/ctx/` is the source of truth for installed starter context artifacts and their minimal ADSM bootstrap markers.
+- `skill/templates/work/` is the source of truth for working templates used by agents during skill operations.
+- `ctx/adsm.json` is the durable metadata source for context versioning and upgrade eligibility.
+
+## State Categories
+
+- authoritative durable state — versioned context documents, templates, metadata, and repository content that define the product and its reusable baseline;
+- derived state — installed copies, validation findings, and generated reports that are produced from authoritative durable state;
+- transient state — process-local execution data used during a command or agent run.
+
+## Ownership Boundaries
+
+- `ctx/` owns the declared meaning and architectural rules of this repository as a product.
+- `skill/` owns the installable agent-consumed skill payload.
+- `skill/templates/ctx/` owns the reusable baseline to be installed into downstream projects, including the minimal markers that route structural validation back to the skill.
+- `skill/templates/work/` owns reusable working output structures that are not installed into project `ctx/` by default.
+- `ctx/adsm.json` owns durable context-version metadata and upgrade eligibility.
+
+Derived and transient state may reflect those sources, but they do not replace them as sources of truth.
+
+## Ownership Rules
+
+- The human owns product direction, architectural guardrails, and approval for boundary expansion.
+- Agents may refine durable documentation within existing boundaries.
+- Agents must not create new persistent state categories or new state owners without updating architecture documents and obtaining human approval.
+
+## State Authority
+
+- Authoritative state may be changed only through deliberate repository updates under the declared supervision model.
+- Derived state may be regenerated, but must stay traceable to an authoritative source.
+- Persistence responsibility must stay explicit whenever durable state is introduced or reorganized.
+
+## State Change Discipline
+
+- Product documents establish meaning.
+- Architecture documents establish ownership and authority.
+- Environment and code documents may refine realization details without taking ownership away from architecture.

package/ctx/docs/architecture/structure.md

@@ -0,0 +1,38 @@
+# Architecture Structure
+
+- Path: `ctx/docs/architecture/structure.md`
+- Changed: `20260707`
+
+## Purpose
+
+Defines the major architectural blocks and responsibility boundaries of the skill product.
+
+## Architectural Blocks
+
+- lifecycle orchestration surface — exposes the `init`, `design`, `validate`, `quality-audit`, `documentation-compression`, and `upgrade` capabilities as the main system behavior boundary;
+- skill payload installation surface — copies the current `skill/` bundle into a caller-provided skills root as the `adsm-ctx` payload;
+- `AGENTS.md` control surface — provides the service-control hierarchy used by agents during project work, while remaining subordinate to the declarative specifications in `ctx/docs/`;
+- reusable template bundle — provides starter `ctx/` artifacts for downstream projects, including product and architecture documentation templates with only minimal ADSM bootstrap markers;
+- documentation quality audit guidance boundary — provides the agent-facing audit prompt and working report template for evaluating documentation corpora without adding CLI-based semantic scoring;
+- documentation compression guidance boundary — provides the agent-facing rewrite prompt and working report template for reducing `ctx/docs/` corpus size without changing accepted project meaning;
+- `ctx/agent/` boundary definition — provides only the reserved branch boundary file for project-local materials that sit outside ADSM methodology;
+- repository self-documentation — keeps the skill product governed by its own cognitive context;
+- migration and validation boundary — checks structural conformance and applies safe convention upgrades;
+- specialization routing boundary — identifies when project-specific skills must take over narrower documentation branches.
+
+## Responsibility Boundaries
+
+- Product documentation defines the meaning and scope of the skill.
+- Architecture defines stable engineering areas and their contracts.
+- `AGENTS.md` files carry operational control inside those declared boundaries but do not define the boundaries on their own.
+- Environment defines runtime prerequisites.
+- Code defines implementation of the declared structure.
+
+## Structural Exclusions
+
+This document does not list:
+
+- source files or directories as architecture blocks;
+- classes, functions, or modules;
+- database tables or DTOs;
+- endpoint-level API details.

package/ctx/docs/architecture/supervision.md

@@ -0,0 +1,71 @@
+# 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

@@ -0,0 +1,51 @@
+# 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

@@ -0,0 +1,53 @@
+# 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

@@ -0,0 +1,26 @@
+# 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

@@ -0,0 +1,50 @@
+# 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

@@ -0,0 +1,33 @@
+# 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

@@ -0,0 +1,44 @@
+# 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.