@flancer32/skill-adsm-ctx 0.2.1

package/skill/templates/ctx/docs/product/roles.md

@@ -0,0 +1,100 @@
+# Product Role Model
+
+- Path: `ctx/docs/product/roles.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe product participants and their authority at the overview level.
+
+This document defines product-role semantics only: who participates in the product world, why each role exists, what each role may control, and where responsibility boundaries are placed.
+
+Detailed role groups may be described in `ctx/docs/product/roles/`.
+
+## Level Boundary
+
+Defines:
+
+- role categories;
+- role authority principles;
+- ownership and responsibility boundaries;
+- role visibility principles;
+- role participation rules;
+- role-level invariants.
+
+Does NOT define:
+
+- authentication mechanisms, sessions, tokens, passwords, or identity storage;
+- API authorization middleware, route guards, or endpoint permissions;
+- UI screens, buttons, menus, or interaction mechanics;
+- source code roles, classes, services, policies, or implementation algorithms;
+- database tables, access-control records, or persistence structure;
+- detailed domain entity structure.
+
+## Role Categories
+
+List the major role categories in the product.
+
+For each category, describe:
+
+- purpose;
+- product authority;
+- owned product areas or objects;
+- relation to other roles;
+- detailed document, if it exists.
+
+## Core Roles
+
+List only the roles required for first-level understanding of the product.
+
+Do not describe all possible roles here when the product has a large role model.
+
+Detailed role definitions belong to dedicated role-area documents.
+
+## Authority Principles
+
+Describe product-level principles of authority.
+
+Clarify:
+
+- who may create durable product state;
+- who may change durable product state;
+- who may publish or approve product state;
+- who may delete or archive product state;
+- who may view product state;
+- what requires explicit user confirmation.
+
+Do not describe implementation-level permission checks.
+
+## Ownership Boundaries
+
+Describe what each major role category owns or must not own.
+
+Focus on product meaning and responsibility, not access-control implementation.
+
+## Participation Relations
+
+Describe how roles interact with each other in the product.
+
+Examples:
+
+- owner and participant;
+- author and reviewer;
+- provider and consumer;
+- administrator and managed user;
+- human user and AI assistant.
+
+## Role Invariants
+
+List role-level rules that must remain true regardless of architecture, storage, UI, or code.
+
+## Role Documentation Map
+
+List detailed role documents.
+
+Example:
+
+- `roles/users.md` — end-user role groups.
+- `roles/admins.md` — administrative roles.
+- `roles/external-actors.md` — external participants and systems.

package/skill/templates/ctx/docs/product/use-cases.md

@@ -0,0 +1,109 @@
+# Product Use Cases
+
+- Path: `ctx/docs/product/use-cases.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe product use cases at the overview level.
+
+This document defines product-goal semantics only: what users need to achieve, why those goals matter, what product result is expected, and which product boundaries apply.
+
+Any mention of product state in this document is product-level only.
+
+Detailed use-case groups may be described in `ctx/docs/product/use-cases/`.
+
+## Level Boundary
+
+Defines:
+
+- major user goals;
+- product-level expected outcomes;
+- use-case groups;
+- lifecycle position of use cases;
+- role participation at the product level;
+- use-case-level invariants.
+
+Does NOT define:
+
+- UI screens, forms, widgets, buttons, or interaction mechanics;
+- API routes, requests, responses, or transport protocols;
+- source code actions, services, handlers, or implementation algorithms;
+- database records, DTO fields, persistence workflows, or storage structure;
+- test cases or acceptance-test procedures;
+- detailed role permissions beyond product-level participation.
+
+## Use Case Groups
+
+List the major groups of product use cases.
+
+For each group, describe:
+
+- user goal;
+- participating roles;
+- expected product outcome;
+- related domain areas;
+- lifecycle position;
+- detailed document, if it exists.
+
+## Core Use Cases
+
+List only the use cases required for first-level understanding of the product.
+
+Do not describe the complete use-case catalog here when the product has many use cases.
+
+Detailed use-case definitions belong to dedicated use-case group documents.
+
+## Use Case Format
+
+When a use case is described in this document or in a detailed use-case document, use product-level language.
+
+Recommended fields:
+
+- goal;
+- primary role;
+- supporting roles;
+- preconditions;
+- expected outcome;
+- durable product outcome;
+- product state effect at the product level;
+- product boundaries;
+- related domain concepts;
+- related terms.
+
+Do not include UI flow, API flow, database flow, implementation steps, DTOs, commands, events, handlers, or test procedures.
+
+Do not describe database changes, API calls, events, handlers, or implementation workflows.
+
+## Lifecycle Model
+
+Describe how major use-case groups relate to the core product lifecycle.
+
+This section should help the reader understand when and why use cases occur.
+
+## Outcome Principles
+
+Describe how expected outcomes are recognized at the product level.
+
+Clarify:
+
+- what counts as a useful product result;
+- what produces a durable product outcome;
+- what has a product state effect at the product level;
+- what remains temporary or draft state;
+- what requires explicit user acceptance or confirmation.
+
+## Use Case Invariants
+
+List use-case-level rules that must remain true regardless of architecture, storage, UI, or code.
+
+## Use Case Documentation Map
+
+List detailed use-case documents.
+
+Example:
+
+- `use-cases/onboarding.md` — entry and first-use goals.
+- `use-cases/content.md` — content creation and publication goals.
+- `use-cases/administration.md` — administration and governance goals.

package/skill/templates/work/context/semantic-skin.md

@@ -0,0 +1,27 @@
+# <Title>
+
+## Purpose
+
+One short sentence.
+
+## Mental Model
+
+One or two short paragraphs that restore the human frame.
+
+## Scope
+
+Includes:
+
+- one to three items.
+
+Excludes:
+
+- one to three items.
+
+## Invariants
+
+- normally no more than five to seven items.
+
+## Agent Document
+
+`name.md`

package/skill/templates/work/report/documentation-compression.md

@@ -0,0 +1,34 @@
+# Documentation Compression Report
+
+- Project:
+- Scope:
+- Date:
+- Agent:
+
+## Compressed Files
+
+List files modified during compression.
+
+## Preserved Authoritative Meanings
+
+List source-of-truth meanings that were preserved while wording was reduced.
+
+## Preserved Skin Meaning
+
+List matching skins read before agent-document edits and the preserved purpose, mental model, scope, and invariants.
+
+## Removed Redundancy
+
+List repeated wording, obvious descriptions, process narration, or low-density text removed.
+
+## Moved Meanings
+
+List durable meanings moved to their authoritative home and the files updated to avoid parallel definitions.
+
+## Human Decisions Required
+
+List non-editorial uncertainties, agent/skin conflicts, and skin-controlled meaning changes that could not be resolved from existing documentation.
+
+## Unresolved Risks
+
+List remaining semantic, hierarchy, or authority risks after compression.

package/skill/templates/work/report/documentation-quality-audit.md

@@ -0,0 +1,90 @@
+# Documentation Quality Audit Report
+
+- Project:
+- Scope:
+- Date:
+- Auditor:
+
+## Corpus
+
+List audited files and any upstream files used to interpret the scope.
+
+## Documentation Map
+
+Summarize source-of-truth agent documents, refinement relationships, agent/skin pairs, orphan skins, projection drift, and duplicated responsibility areas.
+
+## Executive Result
+
+State whether the corpus is usable as ADSM cognitive context and identify the highest-risk quality problems.
+
+## Findings By Severity
+
+### Critical
+
+### High
+
+### Medium
+
+### Low
+
+## Findings By Criterion
+
+### Declarativity
+
+### Consistency
+
+### Completeness
+
+### Connectedness
+
+### Density
+
+### Compactness
+
+### Non-Redundancy
+
+### Absence Of Obvious Descriptions
+
+## Cross-Document Contradictions
+
+List contradictions that require synchronization or human decision.
+
+## Projection Drift
+
+List agent/skin conflicts, orphan skins, skins that contain agent-level operational detail, suspiciously missing skins for key human-direction documents, and assets that appear to introduce meaning not present in agent or skin documents.
+
+## Skin Review Output
+
+For each reviewed skin, state:
+
+- whether it works as a human-facing semantic layer;
+- whether it preserves the same meaning as the paired agent document;
+- whether it avoids operational overload;
+- whether it adds untracked requirements;
+- what must be changed.
+
+## Agent Review Output
+
+For each reviewed agent document, state:
+
+- whether it works as agent-facing operational context;
+- whether it reduces guessing;
+- whether current facts, future plans, requirements, prohibitions, and verification are clear;
+- whether file references are accurate;
+- whether a missing skin document is acceptable or suspicious.
+
+## Missing Context
+
+List upstream gaps that prevent safe downstream correction.
+
+## Redundancy Map
+
+List duplicated meanings and the recommended authoritative home for each one when it is evident from existing context.
+
+## Suggested Fix Order
+
+Order fixes so upstream meaning and contradictions are resolved before downstream cleanup.
+
+## Human Decisions Required
+
+List decisions that cannot be made by the agent from existing documentation.

package/src/Bootstrap/Cli.mjs

@@ -0,0 +1,62 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Bootstrap_Cli
+ * @description Parses CLI arguments for the ADSM context lifecycle application.
+ */
+
+const usage = [
+  "Usage: adsm-ctx <command> [target-path]",
+  "Commands:",
+  "  init [target-path]",
+  "  design [target-path]",
+  "  validate [target-path]",
+  "  upgrade [target-path]",
+  "  install-skill <skills-root>",
+  "  --help",
+].join("\n");
+
+export default class Cli {
+  /**
+   * @param {object} deps
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+   */
+  constructor({pathService}) {
+    /**
+     * Parses CLI arguments.
+     *
+     * @param {object} params
+     * @param {string[]} params.cliArgs
+     * @param {string} params.projectRoot
+     * @returns {{
+     *   command?: string,
+     *   errors: string[],
+     *   helpRequested: boolean,
+     *   targetPath: string,
+     *   usage: string
+     * }}
+     */
+    this.parse = function ({cliArgs = [], projectRoot}) {
+      const [command, targetArg] = cliArgs;
+      const errors = [];
+      const helpRequested = !command || command === "--help" || command === "-h";
+      const targetPath = targetArg ? pathService.resolve(targetArg) : projectRoot;
+
+      if (!helpRequested) {
+        const supported = new Set(["init", "design", "validate", "upgrade", "install-skill"]);
+        if (!supported.has(command)) {
+          errors.push(`Unknown command: ${command}`);
+        }
+        if (command === "install-skill" && !targetArg) {
+          errors.push("Usage: adsm-ctx install-skill <skills-root>");
+        }
+      }
+
+      return {command, errors, helpRequested, targetPath, usage};
+    };
+  }
+}
+
+export const __deps__ = Object.freeze({
+  pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
+});

package/src/Bootstrap.mjs

@@ -0,0 +1,108 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Bootstrap
+ * @description TeqFW root CLI application component for ADSM context lifecycle operations.
+ */
+
+export default class Bootstrap {
+  /**
+   * @param {object} deps
+   * @param {Fl32_Skill_Adsm_Ctx_Bootstrap_Cli} deps.cli
+   * @param {Fl32_Skill_Adsm_Ctx_Design_Service} deps.design
+   * @param {Fl32_Skill_Adsm_Ctx_Init_Service} deps.init
+   * @param {Fl32_Skill_Adsm_Ctx_Skill_Installer} deps.installer
+   * @param {Fl32_Skill_Adsm_Ctx_Upgrade_Service} deps.upgrade
+   * @param {Fl32_Skill_Adsm_Ctx_Validate_Service} deps.validate
+   */
+  constructor({cli, design, init, installer, upgrade, validate}) {
+    let stopping = false;
+
+    /**
+     * Runs the CLI application once.
+     *
+     * @param {object} params
+     * @param {string[]} params.cliArgs
+     * @param {string} params.projectRoot
+     * @returns {Promise<number>}
+     */
+    this.run = async ({cliArgs = [], projectRoot}) => {
+      const parsed = cli.parse({cliArgs, projectRoot});
+
+      if (parsed.helpRequested) {
+        process.stderr.write(`${parsed.usage}\n`);
+        return 0;
+      }
+
+      if (parsed.errors.length > 0) {
+        process.stderr.write(`${parsed.errors.join("\n")}\n`);
+        process.stderr.write(`${parsed.usage}\n`);
+        return 2;
+      }
+
+      if (parsed.command === "init") {
+        const result = await init.execute({targetPath: parsed.targetPath});
+        process.stdout.write(`${formatInitReport(result)}\n`);
+        return 0;
+      }
+
+      if (parsed.command === "design") {
+        process.stdout.write(`${await design.execute({targetPath: parsed.targetPath})}\n`);
+        return 0;
+      }
+
+      if (parsed.command === "validate") {
+        const result = await validate.execute({targetPath: parsed.targetPath});
+        process.stdout.write(`${validate.format({result})}\n`);
+        return result.ok ? 0 : 1;
+      }
+
+      if (parsed.command === "upgrade") {
+        const result = await upgrade.execute({targetPath: parsed.targetPath});
+        process.stdout.write(`${result.message}\n`);
+        return result.ok ? 0 : 1;
+      }
+
+      if (parsed.command === "install-skill") {
+        const targetDir = await installer.execute({targetRoot: parsed.targetPath});
+        process.stdout.write(`Installed skill payload to ${targetDir}\n`);
+        return 0;
+      }
+
+      process.stderr.write(`${parsed.usage}\n`);
+      return 2;
+    };
+
+    /**
+     * Stops the application.
+     *
+     * @returns {Promise<void>}
+     */
+    this.stop = async () => {
+      if (stopping) return;
+      stopping = true;
+    };
+  }
+}
+
+/**
+ * @param {{ctxRoot: string, created: string[], skipped: string[]}} result
+ * @returns {string}
+ */
+function formatInitReport(result) {
+  const lines = [
+    `Initialized ADSM context in ${result.ctxRoot}`,
+    ...result.created.map((entry) => `Created: ${entry}`),
+    ...result.skipped.map((entry) => `Skipped: ${entry}`),
+  ];
+  return lines.join("\n");
+}
+
+export const __deps__ = Object.freeze({
+  cli: "Fl32_Skill_Adsm_Ctx_Bootstrap_Cli$",
+  design: "Fl32_Skill_Adsm_Ctx_Design_Service$",
+  init: "Fl32_Skill_Adsm_Ctx_Init_Service$",
+  installer: "Fl32_Skill_Adsm_Ctx_Skill_Installer$",
+  upgrade: "Fl32_Skill_Adsm_Ctx_Upgrade_Service$",
+  validate: "Fl32_Skill_Adsm_Ctx_Validate_Service$",
+});

package/src/Design/Service.mjs

@@ -0,0 +1,36 @@
+// @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 top-level documentation levels under ctx/docs/: product, architecture, environment, and code.",
+        "3. Add only project-specific substructure that is justified by the project; nested directories are allowed.",
+        "4. Treat ordinary *.md files as agent-facing operational context documents and add *.skin.<lang>.md files only where human semantic control is needed.",
+        "5. Place visual, generated, rendered, or auxiliary artifacts under ctx/assets/ instead of ctx/docs/.",
+        "6. Detect whether specialized ADSM skills are needed for browser, backend, data, deployment, or other areas.",
+        "7. If a specialized skill is available, use it for that branch after the generic structure is in place.",
+        "8. If no specialized skill is available, record the specialization gap and avoid inventing details.",
+      ].join("\n");
+    };
+  }
+}