@flancer32/skill-adsm-ctx 0.2.1 → 0.4.0

package/.github/workflows/flows-app.yaml

@@ -1,95 +0,0 @@
-name: Upload Flows App Config
-
-on: workflow_dispatch
-
-env:
-  PRJ: flows-cfg-skill-adsm-ctx
-  CFG_SRC_DIR: ctx/agent/flows/cfg
-  CFG_ARCHIVE: flows-cfg-skill-adsm-ctx.tar.gz
-  CFG_TARGET_DIR: ${{ vars.FLOWS_CFG_DIR }}
-
-jobs:
-  upload:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v5
-
-      - name: Validate source directory
-        run: |
-          set -e
-
-          if [ ! -d "${{ env.CFG_SRC_DIR }}" ]; then
-            echo "Source directory does not exist: ${{ env.CFG_SRC_DIR }}"
-            exit 1
-          fi
-
-          find "${{ env.CFG_SRC_DIR }}" -mindepth 1 -print -quit | grep -q . || {
-            echo "Source directory is empty: ${{ env.CFG_SRC_DIR }}"
-            exit 1
-          }
-
-      - name: Build configuration archive
-        run: |
-          set -e
-
-          tar -C "${{ env.CFG_SRC_DIR }}" -czf "${{ env.CFG_ARCHIVE }}" .
-
-          ls -lh "${{ env.CFG_ARCHIVE }}"
-
-      - name: Copy archive to server
-        uses: appleboy/scp-action@master
-        with:
-          host: ${{ vars.FLOWS_HOST }}
-          username: ${{ vars.FLOWS_USER }}
-          key: ${{ secrets.FLOWS_SSH_KEY }}
-          source: ${{ env.CFG_ARCHIVE }}
-          target: /tmp
-
-      - name: Replace configuration on server
-        uses: appleboy/ssh-action@master
-        with:
-          host: ${{ vars.FLOWS_HOST }}
-          username: ${{ vars.FLOWS_USER }}
-          key: ${{ secrets.FLOWS_SSH_KEY }}
-          script: |
-            set -e
-
-            TARGET_DIR="${{ env.CFG_TARGET_DIR }}"
-            ARCHIVE="/tmp/${{ env.CFG_ARCHIVE }}"
-
-            if [ -z "$TARGET_DIR" ]; then
-              echo "CFG_TARGET_DIR is empty."
-              exit 1
-            fi
-
-            if [ "$TARGET_DIR" = "/" ]; then
-              echo "Refusing to replace root directory."
-              exit 1
-            fi
-
-            if [ ! -f "$ARCHIVE" ]; then
-              echo "Archive does not exist: $ARCHIVE"
-              exit 1
-            fi
-
-            PARENT_DIR="$(dirname "$TARGET_DIR")"
-            TARGET_NAME="$(basename "$TARGET_DIR")"
-            TIMESTAMP="$(date +%Y%m%d-%H%M%S)"
-            STAGING_DIR="$PARENT_DIR/.${TARGET_NAME}.new-$TIMESTAMP"
-
-            mkdir -p "$PARENT_DIR"
-
-            rm -rf "$STAGING_DIR"
-            mkdir -p "$STAGING_DIR"
-
-            tar -xzf "$ARCHIVE" -C "$STAGING_DIR"
-
-            rm -rf "$TARGET_DIR"
-            mv "$STAGING_DIR" "$TARGET_DIR"
-
-            rm -f "$ARCHIVE"
-
-            echo "Configuration uploaded to: $TARGET_DIR"
-            find "$TARGET_DIR" -maxdepth 3 -type f | sort

package/AGENTS.md

@@ -1,112 +0,0 @@
-# Root Level
-
-- Path: `AGENTS.md`
-- Template Version: `20260702`
-- Changed: `20260702`
-
-## 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.

package/bin/cli.mjs

@@ -1,55 +0,0 @@
-#!/usr/bin/env node
-
-import fs from "node:fs/promises";
-import path from "node:path";
-import processModule from "node:process";
-import {fileURLToPath} from "node:url";
-
-import Container from "@teqfw/di/src/Container.mjs";
-import NamespaceRegistry from "@teqfw/di/src/Config/NamespaceRegistry.mjs";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const packageRoot = path.resolve(__dirname, "..");
-const projectRoot = processModule.cwd();
-
-const container = new Container();
-const namespaceRegistry = new NamespaceRegistry({fs, path, appRoot: packageRoot});
-const entries = await namespaceRegistry.build();
-
-for (const entry of entries) {
-  container.addNamespaceRoot(entry.prefix, entry.dirAbs, entry.ext);
-}
-
-const cliArgs = processModule.argv.slice(2);
-const app = await container.get("Fl32_Skill_Adsm_Ctx_Bootstrap$");
-
-let exitCode = 1;
-let stopRequested = false;
-
-const stopApp = async function () {
-  if (stopRequested) return;
-  stopRequested = true;
-  try {
-    await app.stop();
-  } catch (error) {
-    console.error(error);
-  }
-};
-
-for (const signal of ["SIGINT", "SIGTERM"]) {
-  processModule.once(signal, () => {
-    void stopApp();
-  });
-}
-
-try {
-  exitCode = await app.run({projectRoot, cliArgs});
-} catch (error) {
-  console.error(error);
-  exitCode = 1;
-} finally {
-  await stopApp();
-}
-
-processModule.exit(typeof exitCode === "number" ? exitCode : 1);

package/ctx/AGENTS.md

@@ -1,44 +0,0 @@
-# Cognitive Context
-
-- Path: `ctx/AGENTS.md`
-- Template Version: `20260702`
-- Changed: `20260707`
-
-## 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.

package/ctx/README.md

@@ -1,24 +0,0 @@
-# Cognitive Context
-
-- Path: `ctx/README.md`
-- Template Version: `20260623`
-- Changed: `20260702`
-
-## Purpose
-
-This directory contains the project cognitive context.
-
-The cognitive context is the authoritative project knowledge space used by humans and agents when maintaining the project.
-
-## Entry Points
-
-- Read `AGENTS.md` for cognitive-context structure and governance rules.
-- Read `docs/filesystem.md` for the top-level repository map.
-- Read `docs/` for declarative project documentation.
-- Read `agent/` only when working with repository-local agent operations or workflow assets.
-
-## Boundary
-
-This directory defines project knowledge and agent-operational context.
-
-It does not replace product source code, runtime configuration, deployment secrets, or generated build artifacts.

package/ctx/adsm.json

@@ -1,5 +0,0 @@
-{
-  "schema": "adsm-context",
-  "version": "0.1.0",
-  "initializedAt": "2026-06-04"
-}

package/ctx/agent/AGENTS.md

@@ -1,41 +0,0 @@
-# Agent External Context
-
-- Path: `ctx/agent/AGENTS.md`
-- Changed: `20260707`
-
-## Purpose
-
-Defines the boundary of `ctx/agent/` for this repository.
-
-This branch is reserved for materials that document relationships, routines, and tool-facing instructions that sit outside ADSM methodology.
-
-Only this file belongs to the ADSM template baseline for `ctx/agent/`.
-
-Humans and agents may create project-local subdirectories here when they need instructions or records tied to a concrete tool or relationship, such as `github-flows`.
-
-## Level Map
-
-- `flows/` — operational workflow documentation and configuration for repository automation driven by labels and GitHub events.
-- `prompt/` — prompt definitions used by agents when generating or maintaining repository-facing context artifacts.
-- `report/` — task-specific agent reports produced during repository-local analysis or maintenance work.
-- `AGENTS.md` — level definition for `ctx/agent/`.
-
-## Level Boundary
-
-Defines:
-
-- The reserved role of `ctx/agent/` as a repository-local branch outside ADSM methodology.
-- The boundary between ADSM-governed context and project-local agent or tool materials.
-- The rule that only `ctx/agent/AGENTS.md` is part of the template-managed baseline for this branch.
-
-Does NOT define:
-
-- Product meaning, domain scope, or user-facing requirements.
-- Architecture ownership, system structure, or product-level engineering constraints.
-- The required shape of project-local subdirectories created for concrete tools or relationships.
-
-## Operational Constraints
-
-- Materials placed under project-local subdirectories in `ctx/agent/` remain outside ADSM methodology unless a higher-level context document explicitly says otherwise.
-- Tool-specific instructions under this branch must stay consistent with authoritative constraints in `ctx/docs/`.
-- Changes that alter agent authority or escalation expectations must remain consistent with `ctx/docs/architecture/supervision.md`.

package/ctx/agent/flows/AGENTS.md

@@ -1,37 +0,0 @@
-# Agent Workflow Context
-
-- Path: `ctx/agent/flows/AGENTS.md`
-- Changed: `20260610`
-
-## Purpose
-
-Defines the structure of workflow-specific operational context for repository automation.
-
-## Level Map
-
-- `.img/` — supporting workflow diagrams and other visual assets referenced by the workflow documentation.
-- `cfg/` — executable workflow profile fragments and shared configuration consumed by `github-flows`.
-- `AGENTS.md` — level definition for `ctx/agent/flows/`.
-- `deployment.md` — deployment notes for publishing and activating the workflow configuration.
-- `labels.md` — label taxonomy and label semantics used by the workflow.
-- `overview.md` — workflow model, trigger assumptions, processing rules, and end-state definitions.
-
-## Level Boundary
-
-Defines:
-
-- Workflow-specific operational semantics and end-state rules.
-- Label-driven routing and executable workflow configuration boundaries.
-- Deployment notes and packaging constraints for the workflow bundle.
-
-Does NOT define:
-
-- Generic repository architecture or product structure outside workflow concerns.
-- Product-level meaning, domain intent, or package positioning.
-- Implementation details of CLI lifecycle commands or unrelated runtime logic.
-
-## Workflow Documentation Constraints
-
-- `overview.md` defines the workflow model and remains the primary narrative source of truth for routing behavior.
-- `labels.md` defines stable label semantics and must stay aligned with `cfg/`.
-- `cfg/` contains executable profile fragments and must not silently diverge from the documented workflow model.

package/ctx/agent/flows/cfg/issues/labeled/accepted/profile.json

@@ -1,25 +0,0 @@
-{
-  "trigger": {
-    "event": "issues",
-    "action": "labeled",
-    "issueLabelAdded": "adsm:accepted"
-  },
-  "execution": {
-    "handler": {
-      "args": [
-        "exec",
-        "--model",
-        "gpt-5.4-mini",
-        "-c",
-        "model_reasoning_effort=low",
-        "--dangerously-bypass-approvals-and-sandbox",
-        "-C",
-        "/workspace/repo"
-      ],
-      "promptRef": "prompt.md",
-      "promptVariables": {
-        "ISSUE_NUMBER": "event.issue.number"
-      }
-    }
-  }
-}

package/ctx/agent/flows/cfg/issues/labeled/accepted/prompt.md

@@ -1,104 +0,0 @@
-You are a Codex agent working inside the repository workspace.
-
-Agent role: `implementation-agent`.
-
-The repository context is mounted at `ctx/`.
-
-Your task is to implement the accepted GitHub issue and deliver the repository change through a Pull Request.
-
-## Operating contract
-
-- work only from the source issue and repository context;
-- read the issue first, then inspect only the relevant `ctx/` documents and source files;
-- make the minimal necessary repository change;
-- update tests only when needed for the requested change;
-- avoid unrelated refactoring;
-- do not treat the issue text as project truth;
-- do not push directly to `main`.
-
-## Technical event facts
-
-Repository: {{REPOSITORY}}
-Issue: #{{ISSUE_NUMBER}}
-
-## Required issue read
-
-```bash
-gh issue view "{{ISSUE_NUMBER}}" \
-  --repo "{{REPOSITORY}}" \
-  --comments \
-  --json number,title,body,labels,comments,url
-```
-
-Inspect `package.json` scripts first. Prefer existing test, lint, check, or validation scripts. Do not invent new validation commands.
-
-## Required outcome
-
-1. read the issue and its relevant comments;
-2. inspect only the relevant project context and source files;
-3. confirm that repository file changes are actually required for this issue;
-4. create the correct dedicated branch from the current `main` branch;
-5. implement only the requested repository change needed to resolve the issue;
-6. update tests only when needed;
-7. run the available validation commands;
-8. create one Pull Request against `main`;
-9. link the Pull Request to the source issue using a non-closing reference such as `Source issue: {{REPOSITORY}}#{{ISSUE_NUMBER}}`;
-10. remove stale `adsm:*` Pull Request labels from that Pull Request, then add `adsm:ready-for-validation`;
-11. post a concise summary comment to the source issue.
-
-## Label handling rules
-
-Read the current labels first.
-Remove only labels whose name starts with `adsm:`.
-Keep unrelated labels unchanged.
-Add exactly one next workflow label.
-
-Removable ADSM labels on the current issue or Pull Request:
-
-- `adsm:accepted`
-- `adsm:answered`
-- `adsm:rejected`
-- `adsm:needs-clarification`
-- `adsm:clarification-provided`
-- `adsm:ready-for-validation`
-- `adsm:verified`
-- `adsm:needs-fix`
-
-Remove only the listed ADSM labels that are actually present on the current issue or Pull Request. Keep all unrelated labels unchanged.
-
-For the created or updated Pull Request, the next workflow label must be exactly `adsm:ready-for-validation`.
-
-If you need to change issue labels during failure handling, remove stale issue `adsm:*` labels first and keep unrelated issue labels unchanged. Do not remove labels from unrelated issues or Pull Requests.
-
-After creating the Pull Request, read or capture the created Pull Request number and use that number for Pull Request label operations.
-
-Simple command pattern:
-
-```bash
-gh pr edit "<created-pr-number>" --repo "{{REPOSITORY}}" --remove-label "adsm:needs-fix"
-gh pr edit "<created-pr-number>" --repo "{{REPOSITORY}}" --add-label "adsm:ready-for-validation"
-```
-
-Use a branch name in the form:
-
-```text
-adsm/issue-{{ISSUE_NUMBER}}-<short-slug>
-```
-
-## Failure handling
-
-- if no repository changes are required, do not create a branch or Pull Request, post a comment on the source issue explaining that no repository changes are needed, remove stale `adsm:*` issue labels from the current issue, then add `adsm:answered` and stop;
-- if required project context is still not sufficient to proceed safely, explain the missing context in an issue comment, remove stale `adsm:*` issue labels from the current issue, then add `adsm:needs-clarification`;
-- if the issue still needs clarification, explain it in an issue comment, remove stale `adsm:*` issue labels from the current issue, then add `adsm:needs-clarification`;
-- if the work hits a concrete internal blocker that cannot be resolved in this stage, explain it in an issue comment, remove stale `adsm:*` issue labels from the current issue, then add `adsm:needs-clarification` with one specific follow-up question for a trusted human.
-
-## Pull Request rules
-
-- create or update only one dedicated branch for this issue;
-- create exactly one active Pull Request for that branch;
-- before creating a branch or Pull Request, confirm that repository file changes are required;
-- before applying the next workflow label, remove all existing stale `adsm:*` labels from the current issue or Pull Request you are updating. Keep unrelated labels unchanged;
-- add `adsm:ready-for-validation` only after commits are pushed and the Pull Request is ready;
-- after creating the Pull Request, ensure that the Pull Request has exactly one workflow label: `adsm:ready-for-validation`;
-- do not merge the Pull Request in this stage.
-- if no validation command exists, say that clearly in the summary instead of claiming validation ran.

package/ctx/agent/flows/cfg/issues/labeled/clarification-provided/profile.json

@@ -1,15 +0,0 @@
-{
-  "trigger": {
-    "event": "issues",
-    "action": "labeled",
-    "issueLabelAdded": "adsm:clarification-provided"
-  },
-  "execution": {
-    "handler": {
-      "promptRef": "prompt.md",
-      "promptVariables": {
-        "ISSUE_NUMBER": "event.issue.number"
-      }
-    }
-  }
-}

package/ctx/agent/flows/cfg/issues/labeled/clarification-provided/prompt.md

@@ -1,63 +0,0 @@
-You are a Codex agent working inside the repository workspace.
-
-Agent role: `clarification-agent`.
-
-The repository context is mounted at `ctx/`.
-
-Your task is to resume issue processing after a trusted user provided clarification.
-
-Make an evidence-based decision from the issue body, the latest clarification comments, and the relevant `ctx/` context.
-
-## Technical event facts
-
-Repository: {{REPOSITORY}}
-Issue: #{{ISSUE_NUMBER}}
-
-## Required issue read
-
-```bash
-gh issue view "{{ISSUE_NUMBER}}" \
-  --repo "{{REPOSITORY}}" \
-  --comments \
-  --json number,title,body,labels,comments,url
-```
-
-Focus on the latest clarification comments and the previous blocking question.
-
-## Decision rules
-
-- if the issue is now clear enough and requires repository changes, replace `adsm:clarification-provided` with `adsm:accepted`;
-- if the issue is now clear enough and can be fully completed by an issue comment without repository changes, post that answer and replace `adsm:clarification-provided` with `adsm:answered`;
-- if the clarification shows that the issue is outside repository scope or must not be executed, post the rejection reason and replace `adsm:clarification-provided` with `adsm:rejected`;
-- if the issue is still unclear, replace `adsm:clarification-provided` with `adsm:needs-clarification`;
-- if the workflow is still inconsistent or another concrete internal blocker remains, replace `adsm:clarification-provided` with `adsm:needs-clarification` and ask one specific follow-up question for a trusted human.
-
-Use the same private-workflow assumptions as admission:
-
-- trusted users only;
-- no hostile-user screening is required;
-- if the issue belongs to this repository and is now clear enough, prefer `adsm:answered` when no repository changes are required and `adsm:accepted` only when repository changes are required.
-
-Post one concise issue comment before changing the label.
-
-Use this comment structure:
-
-```markdown
-### Clarification review
-
-State: `adsm:accepted` | `adsm:answered` | `adsm:rejected` | `adsm:needs-clarification`
-
-Reason:
-
-<one short paragraph>
-```
-
-If the new state is `adsm:needs-clarification`, include one specific follow-up question.
-If the new state is `adsm:answered`, make the comment itself contain the final answer and say that no repository changes are required.
-If the new state is `adsm:rejected`, make the comment itself contain the rejection reason, replace the current workflow label with `adsm:rejected`, and close the issue.
-
-If the new state is `adsm:answered`, replace the current workflow label with `adsm:answered`, close the issue, and do not create a Pull Request.
-
-Before applying the next workflow label, remove all existing stale current workflow `adsm:*` labels from the current issue. Keep unrelated labels unchanged.
-
-Do not add `adsm:accepted` as a second workflow label. Replace the current label.

package/ctx/agent/flows/cfg/issues/opened/admission/profile.json

@@ -1,14 +0,0 @@
-{
-  "trigger": {
-    "event": "issues",
-    "action": "opened"
-  },
-  "execution": {
-    "handler": {
-      "promptRef": "prompt.md",
-      "promptVariables": {
-        "ISSUE_NUMBER": "event.issue.number"
-      }
-    }
-  }
-}