@flancer32/skill-adsm-ctx 0.2.1 → 0.3.0

package/ctx/agent/flows/cfg/pull_request/labeled/verified/profile.json

@@ -1,15 +0,0 @@
-{
-  "trigger": {
-    "event": "pull_request",
-    "action": "labeled",
-    "pullRequestLabelAdded": "adsm:verified"
-  },
-  "execution": {
-    "handler": {
-      "promptRef": "prompt.md",
-      "promptVariables": {
-        "PR_NUMBER": "event.pull_request.number"
-      }
-    }
-  }
-}

package/ctx/agent/flows/cfg/pull_request/labeled/verified/prompt.md

@@ -1,48 +0,0 @@
-You are a Codex agent working inside the repository workspace.
-
-Agent role: `merge-agent`.
-
-The repository context is mounted at `ctx/`.
-
-Your task is to merge a Pull Request only when validation evidence is complete and current.
-
-## Technical event facts
-
-Repository: {{REPOSITORY}}
-Pull Request: #{{PR_NUMBER}}
-
-## Required Pull Request read
-
-```bash
-gh pr view "{{PR_NUMBER}}" \
-  --repo "{{REPOSITORY}}" \
-  --comments \
-  --json number,title,body,labels,comments,commits,headRefName,headRefOid,baseRefName,mergeStateStatus,statusCheckRollup,url
-```
-
-## Merge preconditions
-
-Confirm all of the following:
-
-1. the Pull Request currently has `adsm:verified`;
-2. use the latest Pull Request comment whose body starts with `### Validation result`;
-3. that latest validation result exists and contains:
-
-```text
-### Validation result
-State: adsm:verified
-Head: <sha>
-```
-
-4. the `Head:` value from that latest validation comment equals the current Pull Request head SHA from `headRefOid`;
-5. the Pull Request targets `main`;
-6. required checks passed, if checks are configured;
-7. no contradictory evidence is present;
-8. the latest relevant validation result still applies to the current PR head commit.
-
-## Required outcome
-
-- merge the Pull Request only if every precondition is satisfied;
-- if merge is unsafe, post a comment explaining why, remove stale `adsm:*` Pull Request labels from the current Pull Request, then add `adsm:needs-fix`.
-
-Do not rewrite validation evidence. Do not merge when the latest validation result is missing, stale, contradictory, malformed, or bound to a different head SHA than the current Pull Request head.

package/ctx/agent/flows/deployment.md

@@ -1,116 +0,0 @@
-# Deployment And Operation
-
-- Path: `ctx/agent/flows/deployment.md`
-- Changed: `20260610`
-
-## Runtime User
-
-The workflow is intended to run under the server user `agentess`.
-
-This documentation describes the concrete deployment binding for that `agentess` server environment. It is not a generic deployment template.
-
-## Workspace Layout
-
-Recommended host paths:
-
-- repository checkout: `/home/agentess/work/flancer32/skill-adsm-ctx`
-- `github-flows` workspace root: `/home/agentess/var/github-flows`
-- effective configuration directory: `/home/agentess/var/github-flows/cfg`
-
-`github-flows` resolves profile fragments from `workspaceRoot/cfg/`.
-
-## Configuration Placement
-
-Source configuration tree:
-
-- `/home/agentess/work/flancer32/skill-adsm-ctx/ctx/agent/flows/cfg`
-
-Deployment must copy, bind-mount, or otherwise expose that tree at:
-
-- `/home/agentess/var/github-flows/cfg`
-
-The profile tree is self-contained. Each stage profile resolves `promptRef` relative to its own directory.
-
-## Context Source
-
-The workflow uses the repository checkout as-is.
-
-- `ctx/` must already exist inside the checked-out repository;
-- runtime setup must validate the presence of `ctx/AGENTS.md` and `ctx/docs/`;
-- runtime setup must not delete repository `ctx/` and must not replace it from another repository or archive.
-
-This project uses one repository for both the product and its cognitive context. There is no separate `ctx` repository in this deployment model.
-
-## Environment Pattern
-
-Keep operational secrets outside the repository in a service environment file, for example:
-
-- `/home/agentess/.config/github-flows/app.env`
-
-Typical variables:
-
-- `GITHUB_TOKEN` for `gh`
-- `OPENAI_API_KEY` for Codex
-- `GITHUB_FLOWS_WEBHOOK_SECRET` for webhook admission
-- `LOG_LEVEL`
-
-Do not commit secrets or tokens into this repository.
-
-## Authentication Expectations
-
-`gh` authentication:
-
-- the `agentess` user must have a valid GitHub CLI login in `/home/agentess/.config/gh`;
-- the token must allow repository read/write operations required by this workflow.
-
-Codex authentication:
-
-- the `agentess` user must have a valid Codex configuration in `/home/agentess/.codex`;
-- the root profile mounts both `~/.codex` and `~/.config/gh` into the agent container.
-- the current root profile expects direct host access to `/home/agentess/.codex` and `/home/agentess/.config/gh`.
-
-## Event Attribute Contract
-
-Package-owned routing fields:
-
-- `event`
-- `repository`
-- `action`
-- `actorLogin`
-
-Host-provided routing fields required by this workflow:
-
-- `issueLabelAdded`
-- `pullRequestLabelAdded`
-- `pullRequestMerged`
-
-The host application must expose those three additional attributes for the current admitted event.
-
-## Required Webhook Events
-
-- `issues.opened`
-- `issues.labeled`
-- `pull_request.labeled`
-- `pull_request.closed`
-
-## Required GitHub Permissions
-
-- read issues
-- write issue comments
-- manage labels
-- create branches
-- push commits
-- create Pull Requests
-- read Pull Requests
-- read checks
-- merge Pull Requests
-- close issues
-
-## Execution Assumptions
-
-- the agent runs in Docker through `github-flows`;
-- the repository is available inside the container at `/workspace/repo`;
-- `ctx/` is already present in the repository checkout and is used directly;
-- the shared root profile uses `codex exec` with `gpt-5.4` and `model_reasoning_effort=medium`;
-- the implementation and fix stage profiles override the handler args to use `gpt-5.4-mini` with `model_reasoning_effort=low`;
-- direct pushes to `main` are prohibited.

package/ctx/agent/flows/labels.md

@@ -1,108 +0,0 @@
-# Workflow Labels
-
-- Path: `ctx/agent/flows/labels.md`
-- Changed: `20260610`
-
-## Label Rules
-
-- Current workflow labels mark active processing state.
-- Terminal outcome labels classify the final result of a closed issue.
-- One open issue or Pull Request should have at most one current workflow `adsm:*` label.
-- A closed issue should keep exactly one terminal outcome `adsm:*` label.
-- Comments explain decisions; labels trigger the next event-driven stage.
-- Issue labels and Pull Request labels do not imply that transitions stay on the same object.
-- When a stage applies the next workflow label, it must first remove stale current workflow `adsm:*` labels from that same current object and keep unrelated labels unchanged.
-- When a terminal outcome label is applied, stale current workflow labels must be removed from that issue.
-- `adsm:needs-clarification` blocks issue-side progress until trusted human input is provided.
-- `adsm:needs-fix` blocks Pull Request-side progress until another fix iteration is delivered.
-
-## Current Workflow Labels
-
-| Label                         | Applies To   | Stage Trigger                                                               | Valid Previous States                                           | Valid Next States                                                          | Class            |
-| ----------------------------- | ------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------- |
-| `adsm:accepted`               | Issue        | `issues.labeled` via `issueLabelAdded=adsm:accepted`                        | `issues.opened`, `adsm:clarification-provided`                  | Pull Request `adsm:ready-for-validation`, issue `adsm:needs-clarification` | Transitional     |
-| `adsm:needs-clarification`    | Issue        | none; manual blocking state only                                            | `issues.opened`, `adsm:clarification-provided`, `adsm:accepted` | `adsm:clarification-provided`, `adsm:answered`, `adsm:rejected`            | Blocking, manual |
-| `adsm:clarification-provided` | Issue        | `issues.labeled` via `issueLabelAdded=adsm:clarification-provided`          | `adsm:needs-clarification`                                      | `adsm:accepted`, `adsm:answered`, `adsm:needs-clarification`, `adsm:rejected` | Transitional  |
-| `adsm:ready-for-validation`   | Pull Request | `pull_request.labeled` via `pullRequestLabelAdded=adsm:ready-for-validation` | none, `adsm:needs-fix`                                          | `adsm:verified`, `adsm:needs-fix`                                          | Transitional     |
-| `adsm:verified`               | Pull Request | `pull_request.labeled` via `pullRequestLabelAdded=adsm:verified`            | `adsm:ready-for-validation`                                     | merged                                                                     | Transitional     |
-| `adsm:needs-fix`              | Pull Request | `pull_request.labeled` via `pullRequestLabelAdded=adsm:needs-fix`           | `adsm:ready-for-validation`                                     | `adsm:ready-for-validation`                                                | Blocking         |
-
-## Terminal Outcome Labels
-
-| Label            | Applies To | Stage Trigger               | Valid Previous States                                     | Valid Next States | Class            |
-| ---------------- | ---------- | --------------------------- | --------------------------------------------------------- | ----------------- | ---------------- |
-| `adsm:answered`  | Issue      | none; terminal outcome only | `issues.opened`, `adsm:needs-clarification`, `adsm:clarification-provided` | none              | Terminal outcome |
-| `adsm:rejected`  | Issue      | none; terminal outcome only | `issues.opened`, `adsm:needs-clarification`, `adsm:clarification-provided` | none              | Terminal outcome |
-| `adsm:completed` | Issue      | none; terminal outcome only | merged Pull Request finalization                          | none              | Terminal outcome |
-
-## State Notes
-
-- `adsm:accepted` is used only when the issue requires repository changes that must be delivered through a Pull Request.
-- `adsm:answered` is used when the issue is fully completed by an issue comment and repository changes are not required.
-- `adsm:rejected` is used when the issue is outside this repository boundary or must not be executed.
-- `adsm:needs-clarification` is used when the workflow cannot safely continue without trusted human input.
-- `adsm:clarification-provided` is a resume marker and must replace, not accompany, `adsm:needs-clarification`.
-- Validation comments for `adsm:ready-for-validation` must record the chosen state and the current Pull Request head SHA.
-- `adsm:verified` is merge permission, not proof of merge completion.
-- Merge completion is detected by `pull_request.closed` with `pullRequestMerged=true`.
-- `adsm:completed` is used after a linked Pull Request is merged, finalization posts the closing summary, and the source issue is closed.
-
-## Repository Label Setup
-
-Create the current workflow labels and terminal outcome labels in the repository with:
-
-```bash
-gh label create "adsm:accepted" \
-  --repo "flancer32/skill-adsm-ctx" \
-  --color "0E8A16" \
-  --description "Issue accepted for repository changes through a Pull Request." \
-  --force
-
-gh label create "adsm:answered" \
-  --repo "flancer32/skill-adsm-ctx" \
-  --color "0E8A16" \
-  --description "Issue answered without repository changes." \
-  --force
-
-gh label create "adsm:rejected" \
-  --repo "flancer32/skill-adsm-ctx" \
-  --color "B60205" \
-  --description "Issue rejected as out of scope or unsuitable." \
-  --force
-
-gh label create "adsm:completed" \
-  --repo "flancer32/skill-adsm-ctx" \
-  --color "0E8A16" \
-  --description "Issue completed after a linked Pull Request was merged." \
-  --force
-
-gh label create "adsm:needs-clarification" \
-  --repo "flancer32/skill-adsm-ctx" \
-  --color "C2E0C6" \
-  --description "Issue waits for trusted user clarification." \
-  --force
-
-gh label create "adsm:clarification-provided" \
-  --repo "flancer32/skill-adsm-ctx" \
-  --color "1D76DB" \
-  --description "Clarification added and ready for issue re-evaluation." \
-  --force
-
-gh label create "adsm:ready-for-validation" \
-  --repo "flancer32/skill-adsm-ctx" \
-  --color "5319E7" \
-  --description "Pull Request ready for validation." \
-  --force
-
-gh label create "adsm:verified" \
-  --repo "flancer32/skill-adsm-ctx" \
-  --color "0E8A16" \
-  --description "Pull Request validated and safe to merge." \
-  --force
-
-gh label create "adsm:needs-fix" \
-  --repo "flancer32/skill-adsm-ctx" \
-  --color "E99695" \
-  --description "Pull Request requires another fix iteration." \
-  --force
-```

package/ctx/agent/flows/overview.md

@@ -1,82 +0,0 @@
-# GitHub Flows Workflow
-
-- Path: `ctx/agent/flows/overview.md`
-- Changed: `20260610`
-
-## Purpose
-
-This workflow turns trusted GitHub issues in `flancer32/skill-adsm-ctx` into either terminal issue answers or reviewed repository changes through Pull Requests.
-
-The workflow is private, label-driven, and agent-executed through `github-flows`.
-
-## Private Project Assumptions
-
-- The repository is private and operated by three trusted users only.
-- Workflow routing accepts events only from `flancer64`, `viktor-gusev`, and `adsm-agentess`.
-- Repository changes are implemented directly in this repository, including `ctx/` when the issue requires context updates.
-- The checked-out repository is the only workflow context source. The workflow uses the repository-local `ctx/` directory and does not fetch or mount context from another repository during runtime.
-- The workflow uses native GitHub events as stage boundaries and does not model cross-event state inside `github-flows`.
-
-## Trigger Model
-
-`github-flows` provides package-owned trigger attributes:
-
-- `event`
-- `repository`
-- `action`
-- `actorLogin`
-
-This workflow also depends on host-provided event attributes:
-
-- `sizeLess10K`
-- `sizeLess100K`
-- `sizeLess1M`
-- `sizeLess2M`
-- `issueLabelAdded`
-- `issueLabelRemoved`
-- `issueAuthorRequestedNoAgent`
-- `pullRequestLabelAdded`
-- `pullRequestLabelRemoved`
-- `pullRequestMerged`
-
-These extra attributes are part of the host application contract, not the package-owned base schema.
-
-## Processing Model
-
-![GitHub Flows Workflow](./.img/flancer32-skill-adsm-ctx-github-flows.png)
-
-The workflow starts from a source issue. Admission may result in repository-change processing, answer-only completion, rejection, or clarification. Current workflow labels drive active processing. Terminal outcome labels classify closed issues. `adsm:accepted` means repository changes are required; it starts implementation that creates a Pull Request. `adsm:answered` means the issue is completed by a comment and no repository changes are required. `adsm:rejected` means the issue is closed as out of scope or unsuitable. `adsm:completed` means the issue is closed after the linked Pull Request is merged and finalization finishes. Clarification stays on the issue, while fix iterations stay on the Pull Request.
-
-Cross-object transitions:
-
-- `adsm:accepted` is an issue label. Its successful implementation outcome is not another issue label. It is a new Pull Request labeled `adsm:ready-for-validation`.
-- `adsm:answered` and `adsm:rejected` are issue outcome labels only. They are terminal and do not create a branch or Pull Request.
-- `adsm:ready-for-validation`, `adsm:needs-fix`, and `adsm:verified` are Pull Request labels only.
-- After a merged Pull Request is detected, finalization returns to the linked source issue, posts the closing summary there, applies `adsm:completed`, and closes that issue.
-
-## Workflow Rules
-
-- An issue is an input request, not a specification.
-- Admission for `issues.opened` is intentionally minimal in this private workflow.
-- Admission should first decide whether the issue belongs to this repository.
-- If the issue belongs to this repository, admission should choose `adsm:answered` when a comment fully resolves it without repository changes, and `adsm:accepted` only when repository changes are required.
-- `adsm:rejected` is used when the issue does not belong to this repository or must not be executed.
-- `adsm:needs-clarification` is used when the workflow cannot safely continue without trusted human input.
-- Comments provide evidence; labels drive transitions.
-- Validation evidence on Pull Requests must record both the validation state and the current Pull Request head SHA.
-- Agents must not push directly to `main`.
-- Repository implementation must happen on a dedicated branch and must be delivered through a Pull Request.
-
-## Agent Policy
-
-- `issues.opened`, `issues.labeled: adsm:clarification-provided`, `pull_request.labeled: adsm:ready-for-validation`, `pull_request.labeled: adsm:verified`, and `pull_request.closed` run with `gpt-5.4` and `model_reasoning_effort=medium`.
-- `issues.labeled: adsm:accepted` and `pull_request.labeled: adsm:needs-fix` run with `gpt-5.4-mini` and `model_reasoning_effort=low`.
-- The policy is encoded in `execution.handler.args` inside the profile fragments. The shared root defines the medium-reasoning command; implementation and fix fragments override it with the low-reasoning command.
-
-## End States
-
-A successful run ends in one of two ways:
-
-- the issue is answered by comment only, labeled `adsm:answered`, and closed without a branch or Pull Request;
-- the issue is rejected, labeled `adsm:rejected`, and closed without a branch or Pull Request;
-- a reviewed Pull Request is merged into `main`, a final source-issue comment links that Pull Request and summarizes the outcome, the source issue is labeled `adsm:completed`, and the linked source issue is closed.

package/ctx/agent/prompt/cli/ai-intro.md

@@ -1,141 +0,0 @@
-# Generate AI Intro
-
-- Path: `ctx/agent/prompt/cli/ai-intro.md`
-- Changed: `20260422`
-
-## Purpose
-
-Defines the prompt for generating `ctx/docs/ai-intro.md` in ADSM projects when the agent works in CLI mode with direct access to the project files.
-
-The prompt is intended for agents such as Codex or Claude that can inspect repository content before writing the target document.
-
-## Prompt Role
-
-This prompt defines the expected purpose, scope, structure, and size of `ctx/docs/ai-intro.md`.
-
-It is not a template for the final document text. It is a declarative task definition that tells the agent what kind of document must be produced.
-
-## Prompt
-
-Generate the document `ctx/docs/ai-intro.md`.
-
-Assume that the project follows the common ADSM structure. General ADSM and TeqFW conventions are already defined elsewhere and do not need to be restated in detail unless they are necessary to position this specific project.
-
-Before writing, inspect the project files that define public and private project identity. Use the repository content as the source of truth. Prefer project-specific documents and published product materials over assumptions.
-
-The generated `ctx/docs/ai-intro.md` must be the first project-specific reading for AI agents entering the repository. Its role is to position the project in the broader software landscape rather than to explain the internal architecture in detail.
-
-The document must answer the following questions:
-
-- what kind of software product this project is;
-- which problem space it addresses;
-- what role it plays relative to adjacent classes of systems;
-- who the primary audience or users of the project are;
-- which technologies, platforms, and runtime assumptions define its technical family;
-- which methodological base shapes the project;
-- which distinctions make this project different from superficially similar tools;
-- what the project must not be confused with.
-
-The generated document must not duplicate `ctx/docs/AGENTS.md`. It must not restate level structure, hierarchy rules, mandatory-constraint language, or other context-governance mechanics except where a brief reference is necessary to position the project. The generated document must complement `ctx/docs/AGENTS.md`, not compete with it.
-
-The generated document must also avoid detailed explanation of internal architecture, component decomposition, directory maps, execution pipelines, configuration schema, or implementation contracts. Those concerns belong to the specialized documents under `ctx/docs/`.
-
-The generated document must remain declarative. It must describe identity, role, boundaries, and classification. Procedural instructions, workflows, and step-by-step reading guides must be absent or minimal.
-
-## Source Basis
-
-The generated document should be derived from the project's own artifacts, including where relevant:
-
-- `ctx/docs/` for normative project meaning;
-- `README.md`;
-- published documentation under `docs/`;
-- agent-facing published documentation under `ai/`;
-- package metadata such as `package.json`;
-- other repository-level materials that define the public role of the project.
-
-Project-specific facts must be taken from the repository rather than inferred from generic ADSM expectations.
-
-## Output Purpose
-
-The generated `ctx/docs/ai-intro.md` must give an AI agent fast orientation before deeper reading.
-
-After reading it, the agent should understand:
-
-- what kind of thing this repository defines in the world of software;
-- where the project sits relative to libraries, applications, frameworks, platforms, and automation systems;
-- what technical and methodological family the project belongs to;
-- which architectural misclassifications would lead to incorrect implementation decisions.
-
-The document is an orientation layer, not a detailed specification.
-
-## Output Constraints
-
-The generated document must:
-
-- use the standard document attribute block directly under the title;
-- use the canonical path `ctx/docs/ai-intro.md`;
-- follow the declarative style used by the cognitive context;
-- use only relative links to other documents;
-- remain readable as a compact introduction rather than a full survey.
-
-The generated document must not:
-
-- duplicate `ctx/docs/AGENTS.md`;
-- redefine product, architecture, environment, or code contracts already defined in specialized documents;
-- become a repository map;
-- become an implementation walkthrough;
-- become an onboarding checklist;
-- become a marketing text;
-- become a generic explanation of ADSM or TeqFW detached from the current project.
-
-## Volume Constraints
-
-The generated document should usually be between `700` and `1100` words.
-
-Recommended target size is `800` to `1000` words.
-
-The document should be shortened if it starts repeating statements better defined elsewhere. It should be expanded only when the project has unusual positioning that cannot be understood within a smaller text.
-
-## Recommended Structure
-
-The generated document should normally include sections equivalent to the following:
-
-1. `Purpose`
-2. `Project Type`
-3. `Problem Space`
-4. `Product Role In The Ecosystem`
-5. `Primary Audience`
-6. `Technology Base`
-7. `Methodological Base`
-8. `Distinguishing Characteristics`
-9. `What This Project Is Not`
-10. `External Reading Angle`
-11. `Boundary`
-
-Section titles may vary slightly if the project requires different wording, but the same informational shape must be preserved.
-
-## Section Intent
-
-The generated sections should satisfy the following intentions:
-
-- `Purpose` states why `ai-intro.md` exists.
-- `Project Type` classifies the product at the highest level.
-- `Problem Space` states the narrow problem the project solves.
-- `Product Role In The Ecosystem` positions it relative to neighboring software categories.
-- `Primary Audience` identifies who uses or integrates the project.
-- `Technology Base` identifies language, platform, packaging, runtime, and major technical assumptions.
-- `Methodological Base` identifies the project-governing method or architectural family only insofar as it helps classify the project.
-- `Distinguishing Characteristics` states the project choices that matter most for identity.
-- `What This Project Is Not` prevents common misclassification.
-- `External Reading Angle` points to a few high-value follow-up documents using relative links only.
-- `Boundary` states what the document does not define.
-
-## Acceptance Model
-
-The generated `ctx/docs/ai-intro.md` is valid when it:
-
-- gives a correct high-level picture of the project;
-- remains specific to the current repository;
-- avoids restating internal documentation structure in detail;
-- helps an AI agent classify the project correctly before reading deeper documents;
-- preserves declarative style and compact scope.

package/ctx/assets/.gitkeep

@@ -1 +0,0 @@
-

package/ctx/docs/AGENTS.md

@@ -1,121 +0,0 @@
-# Project Documentation
-
-- Path: `ctx/docs/AGENTS.md`
-- Changed: `20260813`
-
-## Purpose
-
-Defines the structure of project-level declarative documentation organized by ADSM levels.
-
-Documents at this level describe the system as a design object, including meaning, structure, environment, and implementation constraints.
-
-## Level Map
-
-- `architecture/` — structural form of the system, architectural entities, boundaries, and interaction model.
-- `code/` — engineering invariants governing how architecture is expressed in source code.
-- `environment/` — runtime environment and infrastructural prerequisites required for system operation.
-- `product/` — system meaning, domain entities, and product-level invariants.
-- `AGENTS.md` — level definition for `ctx/docs/`.
-- `ai-intro.md` — entry document for AI agents that positions the project in the broader software landscape and gives initial project understanding.
-- `filesystem.md` — declarative description of top-level repository directories and root-level files, defining repository boundaries and serving as a navigation map.
-
-## Level Boundary
-
-Defines:
-
-- System meaning and domain intent through the documentation dependency chain rooted in `product`.
-- System realization guardrails through `architecture`, `environment`, and `code`.
-- Mandatory declarative constraints that bound any valid implementation.
-
-All statements defined at this level and below are mandatory constraints for any valid implementation.
-
-Violation of these constraints constitutes an incorrect result, regardless of functional correctness.
-
-Does NOT define:
-
-- Agent operations, workflow execution, or prompt-routing assets under `ctx/agent/`.
-- Concrete implementation artifacts such as `src/`, `bin/`, `test/`, or other product files.
-- Ad hoc task instructions that bypass or override the documentation dependency order.
-
-## Documentation Rules
-
-- Use explicit line breaks to keep each durable statement easy to scan.
-- Keep agent documents dense, explicit, and maintainable.
-- Keep skin documents compact, human-readable, and easy to supervise.
-- Split large agent-document areas into natural nested subdocuments instead of over-compressing them for human readability.
-- Preserve project-specific nested subdirectories under the four top-level documentation levels.
-- Keep each documentation level to no more than nine direct directories and nine direct ordinary files, excluding `AGENTS.md` and all matching `*.skin.<lang>.md` files, where practical.
-- When a level deliberately exceeds either value, its `AGENTS.md` must include a `## Documentation Capacity Exception` section that states the exception and its reason.
-
-## Level Order
-
-Documentation levels form a strict dependency order:
-
-```
-product
-↓
-architecture
-↓
-environment
-↓
-code
-```
-
-`architecture` translates product intent into stable engineering structure.
-
-Lower levels may refine but must not redefine statements established at higher levels.
-
-Lower levels may increase explicitness, constraint, and operational precision, but must not introduce new meaning absent from higher levels.
-
-They must not add new product capabilities, invariants, authority, or semantic boundaries unless those are first named upstream.
-
-## Documentation As A Cognitive Interface
-
-Project documentation is the cognitive interface through which humans and agents cooperate across the documentation levels.
-
-- It communicates human goals, constraints, and decisions to agents.
-- It communicates agent findings, inconsistencies, and refinements back to humans.
-- It connects the human direction-setting and result-evaluation loop with the agent refinement and execution-support loop.
-- It must keep agent documents precise for agent execution and skin documents concise for human semantic control.
-- It must support the full dependency order from product through architecture, environment, and code.
-
-## Project Versus Skill Responsibility
-
-Documents under `ctx/docs/` should primarily govern project development rather than explain or enforce ADSM on their own.
-
-- Project documentation should define product meaning, architecture, constraints, decisions, and other load-bearing project knowledge.
-- The skill should enforce ADSM structure, document-shape discipline, audit criteria, and compression rules.
-- When a project document can either explain ADSM or help govern the project, prefer the project-governing content and leave ADSM conformance work to the skill.
-
-## Documentation Projection Model
-
-Documents under `ctx/docs/` are agent-facing operational context documents by default and are written in English unless a more specific rule applies.
-
-Human-facing semantic skins use the explicit `*.skin.<lang>.md` suffix, with lowercase ISO 639-1 language codes such as `en`, `ru`, or `es`.
-
-An unmarked `*.skin.md` file is invalid. One agent document and all skins with the same basename and directory form one document group.
-
-Agents must read every matching skin before changing its matching agent document.
-
-If a requested agent-document change would violate a skin, report a human decision instead of silently rewriting meaning.
-
-If an agent document and its skin conflict, treat the conflict as projection drift and request a human decision before changing controlled meaning.
-
-`overview.md` has no methodology-level status; it is an ordinary agent document unless paired with one or more `overview.skin.<lang>.md` files.
-
-`AGENTS.md` files remain short local reading, editing, and routing instructions for agents.
-
-`AGENTS.md` files are not full documentation artifacts and must not replace agent documents or semantic skins.
-
-Visual, generated, rendered, or auxiliary artifacts belong under `ctx/assets/**` and must not introduce authoritative project meaning.
-
-## Document Attributes
-
-Documents under `ctx/docs/` use:
-
-```md
-- Path: `ctx/docs/{{subdir}}/file.md`
-- Changed: `YYYYMMDD`
-```
-
-All stable documents use `Path` and `Changed` attributes.