@flancer32/skill-adsm-ctx 0.2.1

package/ctx/agent/flows/cfg/pull_request/labeled/needs-fix/prompt.md

@@ -0,0 +1,79 @@
+You are a Codex agent working inside the repository workspace.
+
+Agent role: `fix-agent`.
+
+The repository context is mounted at `ctx/`.
+
+Your task is to address the latest validation feedback on the existing Pull Request branch.
+
+## 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,files,comments,commits,headRefName,baseRefName,url
+```
+
+Read the latest `### Validation result` comment before changing files.
+
+Inspect `package.json` scripts first. Prefer existing test, lint, check, or validation scripts. Do not invent new validation commands.
+
+## Required outcome
+
+1. read the latest validation result and only the comments needed to understand it;
+2. inspect only the relevant context and source files;
+3. continue on the same Pull Request branch, not a new branch and not a new Pull Request;
+4. make the minimal necessary fix for the reported problems;
+5. update tests only when needed;
+6. run the relevant validation commands again;
+7. avoid unrelated refactoring;
+8. change any repository files that are required to resolve the reported problem;
+9. push the updated commits to the same Pull Request branch;
+10. post a concise fix summary comment on the Pull Request;
+11. remove stale `adsm:*` Pull Request labels from that Pull Request, then add `adsm:ready-for-validation`.
+
+## 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: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 this Pull Request, the next workflow label after a successful fix is exactly `adsm:ready-for-validation`.
+
+Do not change issue labels unless this prompt explicitly requires it.
+
+Simple command pattern:
+
+```bash
+gh pr edit "{{PR_NUMBER}}" --repo "{{REPOSITORY}}" --remove-label "adsm:needs-fix"
+gh pr edit "{{PR_NUMBER}}" --repo "{{REPOSITORY}}" --add-label "adsm:ready-for-validation"
+```
+
+## Clarification and blocking rules
+
+- if a directly related internal blocker prevents completion, explain it in a Pull Request comment and leave the Pull Request in `adsm:needs-fix` for manual follow-up;
+- if you discover that the source issue still lacks the context needed to proceed safely, explain it in the source issue, remove stale `adsm:*` issue labels from the current source issue, then add `adsm:needs-clarification` with one specific follow-up question; keep the Pull Request in `adsm:needs-fix` until clarification arrives.
+
+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.
+
+Do not open a new Pull Request. Do not push directly to `main`.
+If no validation command exists, say that clearly in the fix summary instead of claiming validation ran.

package/ctx/agent/flows/cfg/pull_request/labeled/ready-for-validation/profile.json

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

package/ctx/agent/flows/cfg/pull_request/labeled/ready-for-validation/prompt.md

@@ -0,0 +1,72 @@
+You are a Codex agent working inside the repository workspace.
+
+Agent role: `validation-agent`.
+
+The repository context is mounted at `ctx/`.
+
+Your task is to validate a Pull Request that has been marked ready for validation.
+
+Make an evidence-based validation decision from the Pull Request diff, linked issue, comments, current PR head, and relevant `ctx/` context.
+
+## 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,files,comments,commits,headRefName,headRefOid,baseRefName,url
+```
+
+Identify the linked source issue from the Pull Request body or comments.
+
+## Validation contract
+
+1. inspect the diff;
+2. run available tests and validation commands;
+3. verify the implementation against the source issue and `ctx/`;
+4. verify that the validation result applies to the current PR head commit;
+5. decide exactly one state:
+   - `adsm:verified`
+   - `adsm:needs-fix`
+
+## Required comment
+
+Post one Pull Request comment with this exact heading:
+
+```markdown
+### Validation result
+```
+
+The comment must contain exactly one state line:
+
+```text
+State: adsm:verified
+```
+
+or
+
+```text
+State: adsm:needs-fix
+```
+
+The comment must also contain exactly one head line with the current Pull Request head SHA:
+
+```text
+Head: <current-pr-head-sha>
+```
+
+Use the current `headRefOid` value from the Pull Request you just read.
+
+Do not include more than one `State:` line.
+Do not include more than one `Head:` line.
+
+Before applying the next workflow label, remove all existing stale `adsm:*` labels from the current Pull Request. Keep unrelated labels unchanged.
+
+After posting the comment, replace `adsm:ready-for-validation` with the corresponding Pull Request label.
+
+Do not merge the Pull Request in this stage.

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

@@ -0,0 +1,15 @@
+{
+  "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

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

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

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

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