@flancer32/skill-adsm-ctx 0.4.0 → 0.6.0

package/skill/templates/AGENTS.md

@@ -1,120 +0,0 @@
-# Root Level
-
-- Path: `AGENTS.md`
-- Template Version: `20260720`
-- Changed: `YYYYMMDD`
-
-## Purpose
-
-This file defines the root-level working rules for the project repository.
-
-This file is the first instruction source for every agent operating within the repository.
-
-## Level Boundary
-
-Defines:
-
-- Root-level working boundaries between the repository, the cognitive context, and the software product.
-- Repository-topology rules needed to work safely when `ctx/` may be mounted separately.
-- Root-level protection and escalation rules for this project.
-
-Does NOT define:
-
-- Product-specific meaning, requirements, or domain knowledge.
-- Implementation-level structure such as source code, runtime details, or filesystem layout.
-- Task-specific instructions, workflows, or local operational procedures.
-
-## ADSM Project Model
-
-An ADSM project consists of two interconnected spaces:
-
-- the **Cognitive Context** located in `./ctx/`
-- the **Software Product** located outside `./ctx/`
-
-The cognitive context is the long-term textual memory of the project.
-
-The cognitive context is the primary communication medium between Humans and Agents working on the project.
-
-The cognitive context is the authoritative knowledge source used by Agents when modifying the project.
-
-The software product is the implementation that must be kept consistent with the cognitive context.
-
-## Human and Agent Roles
-
-The Human defines goals, authorizes work, evaluates outcomes, and evolves the project.
-
-The Agent interprets the cognitive context, performs assigned tasks, modifies the project within task boundaries, and maintains consistency between the cognitive context and the software product.
-
-The Agent operates through text and must treat project documentation as operational memory, not as secondary commentary.
-
-## Cognitive Context
-
-The canonical execution location of the cognitive context is `./ctx/`.
-
-Project-specific knowledge, requirements, architecture, environment descriptions, and implementation guidance are defined within the cognitive context.
-
-The Agent must consult `./ctx/AGENTS.md` for project-specific instructions when `./ctx/` exists.
-
-The Agent must consult `./ctx/docs/filesystem.md` for the project filesystem structure and documentation layout when that file exists.
-
-Documentation distributed with the software product may exist outside `./ctx/`, but it does not replace, redefine, or supersede the cognitive context.
-
-## Bootstrap and Repository Topology
-
-An ADSM project may use one repository or two repositories.
-
-In a one-repository topology, the software product and the cognitive context are versioned together.
-
-In a two-repository topology, the software product and the cognitive context are independent version-controlled repositories, and the cognitive context repository is mounted under `./ctx/`.
-
-The Agent must detect whether `./ctx/` is part of the current repository or an independent repository.
-
-The Agent must preserve repository boundaries.
-
-The Agent must not mix changes between independent repositories.
-
-The Agent must not remove, replace, relocate, or unmount `./ctx/`.
-
-If `./ctx/` does not exist, the Agent may perform bootstrap operations required to create the initial cognitive context structure.
-
-After bootstrap is complete, `./ctx/AGENTS.md` becomes the entry point for project-specific instructions.
-
-## Context and Product Consistency
-
-The cognitive context is the source of truth for the project.
-
-If the cognitive context and the software product diverge, the Agent must treat the cognitive context as authoritative.
-
-The Agent must maintain consistency between the cognitive context and the software product.
-
-The Agent may modify the cognitive context when required by the assigned task and when the modification remains consistent with higher-level context constraints.
-
-The Agent may modify the software product when required by the assigned task and when the modification remains consistent with the cognitive context.
-
-## AGENTS.md Hierarchy
-
-Additional `AGENTS.md` files may exist in subdirectories.
-
-The effective working context of the agent is the aggregate of all `AGENTS.md` files located along the path from the repository root to the target directory.
-
-Rules:
-
-- deeper levels override higher levels within their scope
-- root-level invariants cannot be overridden
-- all levels must remain mutually consistent
-
-## Root File Protection
-
-This file defines root-level project control rules.
-
-The agent must not modify, replace, delete, relocate, or reinterpret this file unless explicitly instructed by the human.
-
-Violation of this rule constitutes an execution error.
-
-## Secret Handling
-
-The Agent must never read, load, print, search for, or expose secret-bearing project files, including `.env` and `.env.*` files, credentials, private keys, tokens, or secret stores. This rule applies even when a file is Git-ignored and includes broad search or command output that could reveal its contents.
-
-The Agent may use a non-secret example template such as `.env.example` only to learn the configuration shape. It must not infer or request the value of any secret.
-
-If secret data is exposed accidentally, the Agent must stop handling that value, must not repeat it, and must tell the Human that the secret should be rotated or revoked.

package/skill/templates/ai/AGENTS.md

@@ -1,59 +0,0 @@
-# AGENTS.md
-
-- Path: `ai/AGENTS.md`
-- Template Version: `20260609`
-- Changed: `YYYYMMDD`
-
-## Purpose
-
-This file defines the `ai/` level for agent-facing package documentation included in the distributable package.
-
-The `ai/` directory provides a compact machine-oriented interface for agents that need to understand and use the package correctly.
-
-## Level Boundary
-
-This level defines:
-
-- what documents exist in `ai/`;
-- what each document is for;
-- how an agent should navigate this directory.
-
-This level does not define:
-
-- repository organization;
-- development workflow and testing strategy;
-- behavior not described by the documents in `ai/`.
-
-## Level Map
-
-- `AGENTS.md` — entry point for this level; defines scope and navigation.
-- `concepts.md` — core concepts and architectural model.
-- `container.md` — container responsibilities and dependency resolution behavior.
-- `dependency-id.md` — syntax and semantics of dependency identifiers.
-- `extensions.md` — supported extension points and customization mechanisms.
-- `package-api.ts` — machine-readable description of the public programmatic interface.
-- `usage.md` — minimal usage scenarios and integration examples.
-
-## Reading Guide
-
-Read documents by task:
-
-- for API usage, start with `package-api.ts`, then `usage.md`;
-- for dependency addressing, read `dependency-id.md`;
-- for runtime behavior, read `container.md`;
-- for extension work, read `extensions.md`;
-- for architectural orientation, read `concepts.md`.
-
-If the task is broad or unclear, read in this order:
-
-1. `AGENTS.md`
-2. `package-api.ts`
-3. `usage.md`
-4. `concepts.md`
-5. remaining documents as needed
-
-## Authority
-
-The documents in `ai/` define the supported agent-facing usage semantics of the package.
-
-Agents should rely on these documents for package use and should treat behaviors not described here as undefined.

package/skill/templates/ctx/AGENTS.md

@@ -1,45 +0,0 @@
-# Cognitive Context
-
-- Path: `ctx/AGENTS.md`
-- Template Version: `20260702`
-- Changed: `YYYYMMDD`
-
-## Purpose
-
-This file marks `ctx/` as the project cognitive context.
-
-Use this branch for project knowledge and keep detailed ADSM methodology outside the project-facing context.
-
-## Bootstrap Marker
-
-- This context follows ADSM conventions.
-- Use skill `adsm-ctx` for structure validation, upgrade logic, and methodology rules.
-
-## Level Map
-
-- `agent/` — project-local agent and tool materials outside the reusable ADSM baseline.
-- `assets/` — visual, generated, rendered, or auxiliary artifacts that support documentation without defining authoritative meaning.
-- `docs/` — project-facing documentation and constraints.
-- `AGENTS.md` — level definition for `ctx/`.
-- `README.md` — short entry note for the cognitive context.
-- `adsm.json` — context metadata for versioning and upgrade eligibility.
-
-## Level Boundary
-
-Defines:
-
-- `ctx/` as the project cognitive context boundary.
-- The split between project-facing documentation and project-local agent materials.
-- The local entry points agents should read before deeper work.
-
-Does NOT define:
-
-- Product-specific meaning that belongs in subordinate product and architecture documents.
-- Implementation structure outside the cognitive context.
-- Detailed ADSM methodology that belongs to the skill and its references.
-
-## Local Reading Map
-
-- Read `README.md` for a short entry note.
-- Read `docs/filesystem.md` for the top-level repository map.
-- Read `docs/` for project documentation.

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

@@ -1,36 +0,0 @@
-# Agent External Context
-
-- Path: `ctx/agent/AGENTS.md`
-- Template Version: `20260702`
-- Changed: `YYYYMMDD`
-
-## Purpose
-
-This file marks `ctx/agent/` as a project-local branch for agent and tool materials.
-
-## Bootstrap Marker
-
-- This branch exists in an ADSM-managed context.
-- Use skill `adsm-ctx` for methodology rules about the boundary of `ctx/agent/`.
-
-## Level Map
-
-- `AGENTS.md` — boundary definition for `ctx/agent/`.
-
-## Level Boundary
-
-Defines:
-
-- `ctx/agent/` as the local branch for project-specific agent and tool materials.
-- The boundary between the reusable ADSM baseline and project-local operational content.
-- The rule that only this file belongs to the template-managed baseline for `ctx/agent/`.
-
-Does NOT define:
-
-- Product meaning or user-facing project requirements.
-- Architecture ownership or code-level implementation constraints.
-- The required shape of future project-local subdirectories under `ctx/agent/`.
-
-## Local Rule
-
-Project-specific subdirectories and files under `ctx/agent/` are local project material rather than part of the reusable template baseline.

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

@@ -1,58 +0,0 @@
-# Project Documentation
-
-- Path: `ctx/docs/AGENTS.md`
-- Template Version: `20260702`
-- Changed: `YYYYMMDD`
-
-## Purpose
-
-This branch holds project-facing documentation.
-
-The installed template should describe the project, not restate detailed ADSM methodology.
-
-## Bootstrap Marker
-
-- This documentation baseline follows ADSM conventions.
-- Use skill `adsm-ctx` for structure validation, document-shape discipline, and methodology rules.
-
-## Level Map
-
-- `architecture/` — project architecture documents.
-- `code/` — code-level constraints and testing guidance.
-- `environment/` — runtime and infrastructure assumptions.
-- `product/` — product meaning, roles, and use cases.
-- `verification/` — optional cross-cutting verification specifications; create it only with a real durable specification.
-- `AGENTS.md` — entry note for `ctx/docs/`.
-- `ai-intro.md` — compact agent orientation for the concrete project.
-- `filesystem.md` — top-level repository map.
-
-## Level Boundary
-
-Defines:
-
-- The declarative documentation boundary for the project.
-- The documentation dependency chain from product to code.
-- The optional Verification Layer as a cross-cutting relation, never a fifth declarative level.
-- The local entry points used to orient agents within `ctx/docs/`.
-
-Does NOT define:
-
-- Project-local agent operations under `ctx/agent/`.
-- Product source files or runtime assets outside documentation.
-- Detailed ADSM methodology beyond the bootstrap routing marker.
-
-## Documentation Rules
-
-- Use explicit line breaks to keep each durable statement easy to scan.
-- Use section separators only where they improve navigation or clarify a level boundary.
-- Keep documents compact and avoid long uninterrupted blocks of text.
-- Keep project-facing documents below `5,000` tokens unless a longer document preserves a load-bearing distinction.
-- Treat ordinary `*.md` files as agent-facing operational context documents.
-- Treat `*.skin.<lang>.md` files as human-facing semantic skins for matching agent documents with the same basename and directory.
-- Read a matching skin before changing an agent document.
-- Report a human decision if a requested agent-document change would violate the matching skin.
-- Keep project-specific nested subdirectories inside `product/`, `architecture/`, `environment/`, and `code/` when they improve maintainability.
-- Create `verification/` only when it contains a durable specification. Its root requires `AGENTS.md`; create primary-target categories only on demand.
-- Keep each documentation level to no more than nine direct directories and nine direct ordinary files, excluding `AGENTS.md` and paired `*.skin.<lang>.md` files, where practical.
-- When a level deliberately exceeds either value, add a `## Documentation Capacity Exception` section to that level's `AGENTS.md` that states the exception and its reason.
-- Put visual, generated, rendered, or auxiliary artifacts under `ctx/assets/**`.

package/src/Cli/Command/Design.mjs

@@ -1,17 +0,0 @@
-// @ts-check
-
-import processModule from "node:process";
-
-/** @namespace Fl32_Skill_Adsm_Ctx_Cli_Command_Design */
-export default class Design {
-  constructor({config, design}) {
-    this.id = "adsm-ctx:design";
-    this.summary = "Show ADSM context design guidance.";
-    this.lifetime = "finite";
-    this.execute = async function ({args}) {
-      processModule.stdout.write(`${await design.execute({targetPath: args["target-path"] ?? config.cwd})}\n`);
-    };
-  }
-}
-
-export const __deps__ = Object.freeze({default: Object.freeze({config: "TeqFw_Cli_Config$", design: "Fl32_Skill_Adsm_Ctx_Design_Service$"})});

package/src/Cli/Command/Upgrade.mjs

@@ -1,19 +0,0 @@
-// @ts-check
-
-import processModule from "node:process";
-
-/** @namespace Fl32_Skill_Adsm_Ctx_Cli_Command_Upgrade */
-export default class Upgrade {
-  constructor({config, upgrade}) {
-    this.id = "adsm-ctx:upgrade";
-    this.summary = "Upgrade an ADSM context.";
-    this.lifetime = "finite";
-    this.execute = async function ({args}) {
-      const result = await upgrade.execute({targetPath: args["target-path"] ?? config.cwd});
-      processModule.stdout.write(`${result.message}\n`);
-      if (!result.ok) throw new Error(result.message);
-    };
-  }
-}
-
-export const __deps__ = Object.freeze({default: Object.freeze({config: "TeqFw_Cli_Config$", upgrade: "Fl32_Skill_Adsm_Ctx_Upgrade_Service$"})});

package/src/Design/Service.mjs

@@ -1,38 +0,0 @@
-// @ts-check
-
-/**
- * @namespace Fl32_Skill_Adsm_Ctx_Design_Service
- * @description Provides design guidance for shaping project-specific ADSM context structure.
- */
-
-export default class Service {
-  constructor() {
-    /**
-     * Produces design guidance for a target project.
-     *
-     * @param {object} params
-     * @param {string} params.targetPath
-     * @returns {Promise<string>}
-     */
-    this.execute = async function ({targetPath}) {
-      return [
-        `Design mode for ${targetPath}`,
-        "",
-        "Use this mode to shape project cognitive context without inventing project-specific facts.",
-        "Read `skill/references/design-questionnaire.md` before deciding which specialized ADSM skills may be relevant.",
-        "",
-        "Recommended agent workflow:",
-        "1. Identify the project class from existing repository signals or user input.",
-        "2. Keep ADSM's four ordered declarative documentation levels under ctx/docs/: product, architecture, environment, and code.",
-        "3. Add ctx/docs/verification/ only when a durable verification specification is justified; it is cross-cutting, not a fifth level.",
-        "4. Place each verification specification under the category of its primary declaration target and link secondary targets instead of duplicating it.",
-        "5. Add only project-specific substructure that is justified by the project; nested directories are allowed.",
-        "6. Treat ordinary *.md files as agent-facing operational context documents and add *.skin.<lang>.md files only where human semantic control is needed.",
-        "7. Place visual, generated, rendered, or auxiliary artifacts under ctx/assets/ instead of ctx/docs/.",
-        "8. Detect whether specialized ADSM skills are needed for browser, backend, data, deployment, verification execution, monitoring, or other areas.",
-        "9. If a specialized skill is available, use it for that branch after the generic structure is in place.",
-        "10. If no specialized skill is available, record the specialization gap and avoid inventing details.",
-      ].join("\n");
-    };
-  }
-}

package/src/Upgrade/Service.mjs

@@ -1,44 +0,0 @@
-// @ts-check
-
-/**
- * @namespace Fl32_Skill_Adsm_Ctx_Upgrade_Service
- * @description Provides the baseline non-destructive upgrade entry point without automatic migrations.
- */
-
-export default class Service {
-  /**
-   * @param {object} deps
-   * @param {typeof import("node:fs")} deps.fs
-   * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
-   */
-  constructor({fs, pathService}) {
-    /**
-     * Checks for context metadata and reports the current migration availability.
-     *
-     * @param {object} params
-     * @param {string} params.targetPath
-     * @returns {Promise<{message: string, ok: boolean}>}
-     */
-    this.execute = async function ({targetPath}) {
-      const projectRoot = pathService.resolve(targetPath);
-      const metadataPath = pathService.join(projectRoot, "ctx", "adsm.json");
-
-      if (!fs.existsSync(metadataPath)) {
-        return {
-          message: "No ADSM context metadata found. Run `adsm-ctx init` before upgrade.",
-          ok: false,
-        };
-      }
-
-      return {
-        message: "No automatic migrations are available. Verification Layer adoption is optional and must not create empty scaffolding.",
-        ok: true,
-      };
-    };
-  }
-}
-
-export const __deps__ = Object.freeze({
-  fs: "node:fs",
-  pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
-});