controlm-chain-admin 0.1.0__tar.gz

controlm_chain_admin-0.1.0/.claude/ATTRIBUTION.md

@@ -0,0 +1,41 @@
+# Attribution
+
+The skills under `.claude/skills/` were written for this project and adapt material from
+**Everything Claude Code (ECC)** by Affaan Mustafa — <https://github.com/affaan-m/everything-claude-code>,
+released under the MIT License. Adapted components:
+
+| Skill here | Adapted from ECC |
+|---|---|
+| `verify` | `skills/verification-loop` |
+| `oss-repo-standards` | `agents/opensource-packager`, `agents/opensource-sanitizer`, `rules/common/*` |
+| `python-core-tdd` | `skills/tdd-workflow`, `skills/python-testing`, `agents/python-reviewer`, `rules/python/*` |
+| `fastapi-api` | `skills/fastapi-patterns`, `agents/fastapi-reviewer`, `rules/python/fastapi.md` |
+| `react-frontend` | `skills/react-patterns`, `skills/react-testing`, `skills/vite-patterns`, `rules/react/*`, `rules/typescript/*`, `rules/web/*` |
+
+The adaptations are specific to this repository (stdlib-only core, one-core-two-adapters,
+no-real-data rule, synthetic fixtures); they are not a redistribution of ECC. ECC's licence
+text follows.
+
+## Everything Claude Code — MIT License
+
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

controlm_chain_admin-0.1.0/.claude/skills/bootstrap/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: bootstrap
+description: Set up controlm-chain-admin where only PyPI is reachable (no GitHub), then build a new chain repository from the full exports of every environment, step by step, with the conventions agreed for environments, constants and exceptions. Use when someone says «instalar na empresa», «set up at work», «criar o repositório de dados», «começar do zero», «bootstrap», or opens this source for the first time on a new machine.
+---
+
+# bootstrap — the code from PyPI, the data repository from the exports
+
+Two separate directories, never one inside the other:
+
+- **the code**: this project, unpacked from its source distribution, to run and adjust;
+- **the data**: a new git repository with the chains of one application, built from the
+  exports. It holds real data and never mixes with the code.
+
+Ask the person before anything that is hard to undo (pushing, deleting, `--apply` on many
+files) and number every question so they can answer «1 sim, 2 não».
+
+## Part A — the code
+
+1. Check what the machine has: `python --version` (3.11 or newer), `git --version`, and
+   whether `pip download` reaches PyPI (or the company mirror). npm is only needed to change
+   the web UI; the built UI already ships in the package.
+2. Unpack the source and make it a git repository of its own (adjustments made here stay
+   here; the next version brings them back from upstream):
+
+   ```bash
+   pip download controlm-chain-admin==<version> --no-deps --no-binary :all:
+   tar -xzf controlm_chain_admin-<version>.tar.gz
+   cd controlm_chain_admin-<version>
+   git init -b main && git add -A && git commit -m "chore: controlm-chain-admin <version>"
+   python -m venv .venv
+   .venv/bin/pip install -e ".[dev,web]"          # Windows: .venv\Scripts\pip ...
+   ```
+
+3. Create `.claude/no-real-data.patterns` (git-ignored, one regular expression per line) with
+   the names that must never enter this code: the company, its domains, the application
+   code, machine and user prefixes. Ask the person for them. The gate scans for them.
+4. Run the gate once: `PATH="$PWD/.venv/bin:$PATH" .claude/skills/verify/verify.sh` (on
+   Windows from Git Bash, with `.venv/Scripts`). Without npm the frontend steps are skipped.
+5. From here on the project rules apply (`CLAUDE.md`): TDD, English in the code, no real data
+   in this directory, not even in tests.
+
+## Part B — the data repository
+
+### 1. What the exports say
+
+Put the full exports in `exports/<env>/` of the new data directory (they are big: look at
+them with scripts and counts, never whole). Then ask, numbered, what the exports do not say:
+
+1. the application (`APPLICATION` of its folders) and the environments with their letters,
+   e.g. `test=T,uat=U,bench=B,prod=P`;
+2. the bare prefixes of the letter rule (the application code, `RQ_`, `RC_`) and which of
+   them carry the letter on their first token only (`--leading-only RQ_,RC_`: resources such
+   as `URQ_P77_AGGREGATION`);
+3. which environment is production (default `prod`).
+
+### 2. Production first: it is the trunk
+
+```bash
+mkdir chains && cd chains && git init -b main
+ctmchain init --application <APP> --envs test=T,uat=U,bench=B,prod=P \
+    --prefixes P77,RQ_,RC_ --leading-only RQ_,RC_
+ctmchain import ../exports/prod/<prod>.xml --env prod --dedupe-jobnames
+ctmchain export --env prod --jobnames original -o /tmp/prod-check.xml
+cmp /tmp/prod-check.xml ../exports/prod/<prod>.xml && echo "prod: byte for byte"
+git add -A && git commit -m "chore: production baseline"
+```
+
+This first commit is the only one made on `main` by hand: from now on `main` mirrors
+production and every change goes through a release.
+
+### 3. The other environments, one release
+
+```bash
+ctmchain release start baseline
+ctmchain receive ../exports/uat/<uat>.xml --full        # preview: the decisions
+```
+
+A full export of an environment other than production leaves production alone by default.
+Read the decisions with the person, by section, before `--apply`:
+
+- **groups** (the same difference in many jobs, or a machine, user, mail or variable): a new
+  constant with a value per environment. Give them readable names with
+  `--choose 'group:...=new:<name>'`, or in the *Import* page of `ctmchain serve`.
+- **exceptions** (a value that differs in one job), **children** (conditions or ON blocks
+  that differ: ignored by default), **removed / added / absent** (jobs and folders only one
+  environment has or lacks).
+
+Then `--apply`, `ctmchain export --env uat` to look at the result, and commit. Same for bench
+and test. Receiving the same export again shows what still differs.
+
+### 4. The conventions agreed for these chains
+
+- **Machines**: neutral names by order, `node.bat1` (first) and `node.bat2` (second); each
+  environment has its own machines behind them.
+- **Users**: `user.<role>_user_proc`, e.g. `user.batch_user_proc`, `user.per_user_proc`. A
+  value that fits none: ask whether it is an existing one (`use:<name>`) or a new one (e.g.
+  `user.lala_user_proc`).
+- **Mails, transfer (CFT) settings, variables such as the environment code**: one value per
+  environment (a constant), which a single job may still change (an exception).
+- **Time windows, MAXWAIT, calendars, file age limits**: the same everywhere; a difference is
+  an exception for that job, after asking.
+- **TASKTYPE Dummy, another CMDLINE in one environment**: exceptions of that environment.
+- **Dirty names** (another environment's letter in a condition, a resource of another
+  environment, a letter in place of the application's first letter): not fixed on the way
+  in. `ctmchain validate` lists them with suggested fixes, to correct in later releases.
+
+### 5. Close the baseline
+
+```bash
+ctmchain release installed prod     # nothing to install: the baseline only describes them
+ctmchain release close
+```
+
+Then the everyday flow of the data repository's own `CLAUDE.md` (written by `init`):
+deliveries through `ctmchain receive`, a full prod export now and then to catch up with
+production, releases installed environment by environment.

controlm_chain_admin-0.1.0/.claude/skills/fastapi-api/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: fastapi-api
+description: Standards for the local FastAPI server of controlm-chain-admin (src/controlm_chain_admin/web, the [web] extra, `ctmchain serve`). Use for any change to API routers, schemas, dependencies, error handling, OpenAPI metadata or API tests, and when someone asks to «criar endpoint», «expor na API», «servir», or review the API. Thin handlers over the core, typed errors, TestClient tests, OpenAPI snapshot.
+---
+
+# fastapi-api
+
+Adapted from Everything Claude Code `fastapi-patterns`, `fastapi-reviewer` and
+`rules/python/fastapi.md` (MIT, see `.claude/ATTRIBUTION.md`). Architecture: `DESIGN.md` §11.
+
+## Structure
+
+```text
+src/controlm_chain_admin/web/
+  app.py            # create_app(settings) -> FastAPI; lifespan loads ChainRepo; mounts static SPA
+  settings.py       # repo path, host (127.0.0.1), port, token, open_browser
+  deps.py           # get_repo() (reloads when files changed), require_token()
+  errors.py         # ONE exception handler: core typed errors -> HTTP status + {"error","message","detail"}
+  schemas/          # Pydantic v2 response/request models, one module per resource
+  routers/          # repo.py folders.py jobs.py links.py validate.py changes.py
+  static/           # built SPA (web/dist), served at "/" (not committed)
+```
+
+## Rules
+
+- **Handlers are thin**: parse → call one `core` function → return a schema. No loops over
+  folders, no name logic, no file access in a router. If a handler needs a rule, the rule goes
+  to `core` and the CLI gets it too.
+- The core is synchronous and in-memory, so handlers are plain `def` (FastAPI runs them in a
+  threadpool). Use `async def` only for handlers that await something. Never block an `async`
+  handler with file or subprocess calls.
+- `response_model` on every endpoint; separate request, response and list schemas; schemas
+  mirror `core` dataclasses (build them with `model_validate(dataclasses.asdict(...))` or
+  `from_attributes`), never expose internals the UI does not need.
+- Pagination (`limit`, `offset`) on every list endpoint even if the UI does not use it yet.
+- Errors: `core` typed errors map in `errors.py` only — `NotFound` 404, `NameCollision`/
+  `LiteralCollision` 409, `UnresolvedConstant`/`DanglingLink` 422, unexpected 500 with a log
+  line and no stack trace in the body. Every error response has the same shape.
+- Mutations (`POST/PUT/DELETE`) are `/api/changes/*`: preview returns a `ChangeSet`, apply takes
+  the same `ChangeSet` back. Both require the `X-Ctmchain-Token` header checked by
+  `require_token`. `GET` endpoints are read-only and need no token.
+- Bind `127.0.0.1` by default; `--host` must be explicit; CORS off (same origin: the SPA is
+  served by the same app). Log the request line, never request bodies.
+- OpenAPI: `title`, `version` from the package, a tag per router with a description, every
+  endpoint has `summary` and documented error responses. The schema is the frontend contract
+  (`web/` generates TypeScript types from it), so changing it is a visible diff.
+- Configuration via `settings.py` (pydantic-settings) with env prefix `CTMCHAIN_`; no reading
+  `os.environ` in routers.
+
+## Tests (TDD, like everything else)
+
+- `tests/web/conftest.py` builds a fixture chain repo in `tmp_path`, overrides `get_repo` with
+  `app.dependency_overrides`, clears it after the test, and yields a `TestClient`.
+- One test module per router; assert status, body shape and the exact values from the
+  fixture; one negative test per error mapping; one test proving a mutation without the token
+  is 401 and with the token returns the preview.
+- `tests/web/test_openapi.py` compares `app.openapi()` with
+  `tests/web/openapi.snapshot.json`; updating the snapshot is a deliberate commit.
+- No network, no real data, no sleeping; the server is never started in tests.
+
+## Verify
+
+1. `pytest tests/web -q` green, including the OpenAPI snapshot.
+2. Checklist (from `fastapi-reviewer`): no logic in handlers · `response_model` everywhere ·
+   one error handler, consistent error shape · token on every mutation · no `async def`
+   doing blocking work · list endpoints paginated · settings only via `settings.py` ·
+   no secrets, hosts or real names in code or snapshot · docs tags and summaries present.
+3. Start it once by hand: `ctmchain serve --repo <fixture repo> --no-browser`, open
+   `/docs`, call two endpoints, stop it.
+4. Finish with the `verify` skill and paste its report in the PR.

controlm_chain_admin-0.1.0/.claude/skills/oss-repo-standards/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: oss-repo-standards
+description: Open-source repository standards for controlm-chain-admin — README structure, community health files, Conventional Commits, Keep a Changelog, SemVer, issue/PR templates, Trusted Publishing release, naming conventions, bilingual mkdocs. Use when creating or editing README, CONTRIBUTING, CHANGELOG, docs, pyproject metadata, GitHub workflows or templates, when naming a module, command or JSON key, or when someone asks whether the repo «segue os padrões open source».
+---
+
+# oss-repo-standards
+
+Adapted from Everything Claude Code `opensource-packager`, `opensource-sanitizer` and
+`rules/common` (MIT, see `.claude/ATTRIBUTION.md`), and from the author's `xmldiffreport`.
+
+## Files every release must have
+
+| File | Standard |
+|---|---|
+| `README.md` | See structure below |
+| `LICENSE` | MIT, copyright line with year and author |
+| `CONTRIBUTING.md` | how to set up, run tests, TDD rule, commit format, PR checklist, where to ask |
+| `CODE_OF_CONDUCT.md` | Contributor Covenant 2.1 with a contact address |
+| `SECURITY.md` | supported versions, private reporting channel, response time |
+| `CHANGELOG.md` | Keep a Changelog 1.1: `## [Unreleased]` on top, sections Added/Changed/Fixed/Removed, compare links |
+| `.github/ISSUE_TEMPLATE/bug_report.md`, `feature_request.md`, `.github/PULL_REQUEST_TEMPLATE.md` | PR template includes the `verify` report and the TDD checkbox |
+| `.github/workflows/ci.yml`, `release.yml`, `docs.yml` | CI on push/PR (lint + test matrix 3.11–3.13, macOS/Windows), release on `v*` tags with PyPI Trusted Publishing (OIDC, environment `pypi`), docs to GitHub Pages |
+| `.editorconfig`, `.pre-commit-config.yaml` | ruff, ruff-format, end-of-file, trailing whitespace |
+| `pyproject.toml` | name, version (single source), description, readme, `requires-python`, license, authors, keywords, classifiers (Development Status, Intended Audience, License, OS, Python versions, Topic, Typing :: Typed), `[project.urls]` Homepage/Documentation/Repository/Issues/Changelog, `[project.scripts] ctmchain` |
+| `mkdocs.yml` | mkdocs-material, `mkdocs-static-i18n` with `en` default and `pt`, every page has a `.pt.md` twin |
+
+## README structure (in this order)
+
+1. Title, one-line tagline, badges: Docs, CI, PyPI version, Python versions, License.
+2. Documentation links (English and Português).
+3. One paragraph: what it is, for whom, the problem it solves (Control-M XML exports are hard
+   to manage; JSON in git, links as first-class, environment-neutral base).
+4. Why not X: short comparison with the Control-M UI, Automation API JSON, raw XML + git.
+5. Install (`pip install controlm-chain-admin`, `[web]` extra) and requirements.
+6. Quickstart: `init`, `distinct`, `import`, `validate`, `export`, `serve` in 10 lines, with
+   the synthetic fixture so the reader can run it without real data.
+7. Concepts in a small table (chain repository, base, environment, link, constant, override).
+8. Status / roadmap pointer to `BACKLOG.md`, Contributing pointer, Licence.
+
+No real data in any example: application `P77`, hosts `srvu-p77-*`, addresses `@example.com`.
+
+## Conventions
+
+- **Commits**: Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`,
+  `ci:`), imperative, ≤ 72 chars subject, body explains why. Breaking change → `!` and footer.
+- **Versions**: SemVer; `0.x` while the JSON layout may change; tag `vX.Y.Z` = release.
+- **Branches**: `main` protected by CI; short-lived `feat/<topic>`, `fix/<topic>`.
+- **Python names**: package `controlm_chain_admin`, modules and functions `snake_case`,
+  classes `PascalCase`, constants `UPPER_SNAKE`, private `_leading_underscore`.
+- **CLI**: command `ctmchain`, subcommands kebab-case (`rename-job`), flags `--kebab-case`.
+- **JSON keys**: attributes mirrored from Control-M XML keep their exact XML name
+  (`JOBNAME`, `SUB_APPLICATION`) for fidelity; keys that belong to this tool are
+  `snake_case` (`envs`, `links`, `cleanup`, `external`).
+- **Docs**: English first, Portuguese twin, same headings; code blocks copy-pasteable.
+- **Issues/PRs**: labels `bug`, `enhancement`, `docs`, `good first issue`; PR title in
+  Conventional Commits form.
+
+## Verify
+
+1. Run `.claude/skills/oss-repo-standards/check_repo.sh`; it lists missing files/sections and
+   checks the last 20 commit subjects against Conventional Commits. All items `OK` or an
+   accepted `TODO` with the backlog story that will add it.
+2. `gh api repos/{owner}/{repo}/community/profile --jq .health_percentage` must be `100`
+   once the files exist.
+3. Read the README top to bottom as a stranger: can they install and run the quickstart in
+   five minutes without asking anything? Every command copy-pasteable and tested.
+4. Grep the docs for anything that looks like real data (see `verify`'s no-real-data phase).
+5. Finish with the `verify` skill and paste its report in the PR.

controlm_chain_admin-0.1.0/.claude/skills/oss-repo-standards/check_repo.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# check_repo.sh — open-source hygiene checklist for controlm-chain-admin. Prints OK/MISSING per item.
+set -uo pipefail
+cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+MISSING=0
+ok()   { printf 'OK       %s\n' "$1"; }
+miss() { printf 'MISSING  %s\n' "$1"; MISSING=$((MISSING+1)); }
+has_file() { [ -e "$1" ] && ok "$1" || miss "$1"; }
+has_section() { [ -f "$1" ] && grep -qiE "$2" "$1" && ok "$1: $3" || miss "$1: $3"; }
+
+echo "== community files"
+for f in README.md LICENSE CONTRIBUTING.md CODE_OF_CONDUCT.md SECURITY.md CHANGELOG.md \
+         .github/ISSUE_TEMPLATE/bug_report.md .github/ISSUE_TEMPLATE/feature_request.md \
+         .github/PULL_REQUEST_TEMPLATE.md .github/workflows/ci.yml .github/workflows/release.yml \
+         .editorconfig .pre-commit-config.yaml pyproject.toml mkdocs.yml; do has_file "$f"; done
+
+echo "== README sections"
+has_section README.md 'img.shields.io|badge' "badges"
+has_section README.md '^## .*(install|instala)' "Install section"
+has_section README.md '^## .*(quick ?start|usage|getting started)' "Quickstart section"
+has_section README.md 'contribut' "Contributing pointer"
+has_section README.md '^## .*licen[cs]e|MIT' "Licence"
+
+echo "== changelog / metadata"
+has_section CHANGELOG.md '^## \[Unreleased\]' "Unreleased section"
+has_section pyproject.toml '^\[project.urls\]' "project.urls"
+has_section pyproject.toml 'classifiers' "classifiers"
+has_section pyproject.toml 'ctmchain *=' "ctmchain script"
+has_section mkdocs.yml 'i18n' "bilingual docs (mkdocs-static-i18n)"
+has_section .github/workflows/release.yml 'id-token: *write' "Trusted Publishing (OIDC)"
+
+echo "== commits (last 20 subjects, Conventional Commits)"
+BAD="$(git log -20 --format=%s 2>/dev/null | grep -vE '^(feat|fix|docs|test|refactor|chore|ci|build|perf|style|revert)(\([a-z0-9/_-]+\))?!?: .+' || true)"
+if [ -z "$BAD" ]; then ok "all recent subjects follow Conventional Commits"; else printf 'MISSING  non-conventional subjects:\n%s\n' "$BAD" | sed 's/^/         /'; MISSING=$((MISSING+1)); fi
+
+echo "== GitHub community profile"
+if command -v gh >/dev/null && gh repo view --json nameWithOwner --jq .nameWithOwner >/dev/null 2>&1; then
+  REPO="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
+  PCT="$(gh api "repos/$REPO/community/profile" --jq .health_percentage 2>/dev/null || echo '?')"
+  [ "$PCT" = "100" ] && ok "community profile 100%" || printf 'INFO     community profile: %s%%\n' "$PCT"
+else
+  echo "INFO     gh not available or not a GitHub repo; skipped"
+fi
+
+echo; [ $MISSING -eq 0 ] && echo "RESULT: OK" || { echo "RESULT: $MISSING item(s) missing"; exit 1; }

controlm_chain_admin-0.1.0/.claude/skills/python-core-tdd/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: python-core-tdd
+description: TDD and coding standards for the Python core and CLI of controlm-chain-admin (src/controlm_chain_admin, tests/). Use for any change to Python code — new feature, bug fix, refactor — and when someone asks to «implementar», «corrigir», «testar» or «refatorar» the core, the parser, the serializer, links, validate or the CLI. Enforces test-first, stdlib-only core, one-core-two-adapters, coverage gate.
+---
+
+# python-core-tdd
+
+Adapted from Everything Claude Code `tdd-workflow`, `python-testing`, `python-reviewer` and
+`rules/python` (MIT, see `.claude/ATTRIBUTION.md`). Architecture rules come from `DESIGN.md` §11.
+
+## The loop (every change, no exceptions)
+
+1. **Red** — write the test in `tests/` that describes the behaviour; run it; it must fail for
+   the right reason (not an import error). Name it after the behaviour:
+   `test_export_reproduces_bytes_for_untouched_folder`.
+2. **Green** — write the smallest code that passes. No extra features.
+3. **Refactor** — remove duplication, name things, keep functions < 50 lines; tests stay green.
+4. **Commit** test and code together (`feat:`/`fix:`/`test:`), the test file visible in the diff.
+
+A bug fix starts with a failing regression test that reproduces it. If a test must change,
+the behaviour changed on purpose and the commit message says so.
+
+## Test layout
+
+```text
+tests/
+  conftest.py                 # fixture_repo, fixture_xml, tmp chain repos
+  fixtures/
+    build_fixtures.py         # deterministic synthetic export of application P77
+    p77_export.xml            # committed output of the generator
+  unit/test_<module>.py       # pure functions, one module per file
+  integration/test_cli_*.py   # CLI through main(argv), tmp repo, exit codes
+  realdata/test_roundtrip.py  # @pytest.mark.realdata, skipped unless CTMCHAIN_DATA_REPO is set
+```
+
+- Arrange / Act / Assert, one behaviour per test, `pytest.mark.parametrize` for tables.
+- Fixtures over setup code; `tmp_path` for every file write; never write inside the repo.
+- Byte-level assertions for the serializer (`assert out == original_bytes`), not string
+  "looks like" checks. Compare with a filtered original when applications are skipped.
+- `realdata` tests read the private clone path from `CTMCHAIN_DATA_REPO`, never a hardcoded
+  path, and never print real values on failure beyond counts and positions.
+- Coverage gate: `fail_under = 90` in `pyproject.toml` for `controlm_chain_admin`; adapters
+  (`cli.py`, `web/`) count too, so keep them thin.
+
+## Architecture rules (checked in review)
+
+- `core/` imports only the standard library. Third-party code lives in `web/` (`[web]` extra)
+  or dev tooling.
+- `core` functions take a loaded `ChainRepo` and parameters, return frozen dataclasses
+  (`ChangeSet`, `Report`, resolved nodes) or raise typed errors (`UnresolvedConstant`,
+  `DanglingLink`, `NameCollision`, `LiteralCollision`). Nothing in `core` prints or exits.
+- `cli.py` only parses arguments, calls one `core` function, renders (`text|md|json`), maps
+  errors to exit codes (0 ok, 1 findings, 2 usage, 3 error).
+- Writes go through `ops.apply(repo, change)`: all files or none; the preview is the same
+  object the user saw.
+- Immutability by default: `@dataclass(frozen=True)`, tuples, `Mapping`; build new objects
+  instead of mutating. Document order is kept with lists, never with dict insertion assumptions.
+- Determinism: no `datetime.now()` or randomness in model code; the export comment timestamp
+  is a parameter.
+
+## Style
+
+- Python ≥ 3.11, `from __future__ import annotations` not needed; use `X | None`.
+- Type annotations on every public signature; `mypy src` clean; no `Any` without a comment.
+- `ruff` (line 99; rules E, F, I, UP, B, SIM, C4, RUF) and `ruff format`; no `print` in
+  `core`; `logging` for diagnostics; `pathlib` for paths; `with` for every file.
+- Docstrings in English on public modules, classes and functions: one line what, then why if
+  non-obvious. Comments explain intent, not mechanics.
+- Errors: catch specific exceptions; never `except: pass`; messages name the folder/job
+  identity, never dump a whole element.
+- Encoding: read and write bytes explicitly as UTF-8; never let the platform default decide.
+
+## Verify
+
+1. `pytest -q` green; `pytest -m realdata` green locally when the change touches parsing,
+   serialization or links.
+2. `ruff check . && ruff format --check . && mypy src` clean.
+3. Checklist: test written first (test file in the diff) · no third-party import under
+   `core/` · no `print`/`sys.exit` outside `cli.py` · new behaviour has a byte- or
+   value-level assertion · errors typed · no real data in tests or fixtures · functions
+   < 50 lines, files < 800 lines · CHANGELOG `Unreleased` updated for user-visible changes.
+4. Finish with the `verify` skill and paste its report in the PR.

controlm_chain_admin-0.1.0/.claude/skills/react-frontend/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: react-frontend
+description: Standards for the read-only web UI of controlm-chain-admin (web/, Vite + React + TypeScript + shadcn/ui, TanStack Query, React Flow). Use for any change to .ts/.tsx files, components, pages, API client, tests or the Vite build, and when someone asks to «criar página», «mostrar na UI», «componente», «grafo» or review the frontend. Test-first with Vitest + Testing Library + MSW, OpenAPI-generated types, accessibility, no template look.
+---
+
+# react-frontend
+
+Adapted from Everything Claude Code `react-patterns`, `react-testing`, `vite-patterns`,
+`rules/react`, `rules/typescript` and `rules/web` (MIT, see `.claude/ATTRIBUTION.md`).
+
+## Stack and structure
+
+```text
+web/
+  package.json            # scripts: dev, build, lint, typecheck, test, test:e2e, gen:api
+  vite.config.ts          # /api proxy to http://127.0.0.1:<port> in dev; outDir dist (git-ignored)
+  src/
+    app/                  # router, providers (QueryClient, theme), layout shell
+    features/<area>/      # folders/, folder-graph/, job-detail/, validate/ — components + hooks + tests side by side
+    components/ui/        # shadcn/ui primitives (generated, do not hand-edit)
+    lib/api/              # client.ts (fetch wrapper), types.gen.ts (openapi-typescript output), queries.ts
+    lib/                  # utils, formatters
+  tests/e2e/              # Playwright smoke against the built app served by ctmchain serve
+```
+
+- TypeScript `strict`; no `any` (use `unknown` and narrow); types for the API come only from
+  `npm run gen:api` (openapi-typescript over the FastAPI schema). Never hand-write an API type.
+- Server state only in TanStack Query (`useQuery`/`useSuspenseQuery` with query keys per
+  resource); UI state local with `useState`; derived state computed in render, never duplicated.
+- Components: `PascalCase.tsx`, props as `type Props = {...}` destructured in the signature,
+  hooks `useX` in `use-x.ts`, boolean props `isX/hasX/canX`, handlers `handleX`, prop `onX`.
+- Imports: react, third-party, `@/` absolute, relative; `import type` for types.
+- Graph: React Flow (`@xyflow/react`) with `dagre` layout computed in a hook; nodes are
+  jobs, folder entry/exit pseudo-nodes for folder-level conditions, edge data carries the link
+  (name, ODATE, AND_OR, cleanup, docond, external). Selection drives the inspector panel.
+- Read-only phase: no forms that mutate; every mutation UI comes later through
+  `/api/changes/*` with preview → apply.
+
+## Design quality (not a default template)
+
+- Hierarchy on purpose: the chain graph and the job's execution attributes are the focus;
+  metadata recedes. Attributes grouped (identity, scheduling, execution, notifications,
+  resources, variables, ON/DO), not a 75-row flat table.
+- Intentional hover/focus/selected states on nodes, edges and rows; keyboard navigation in
+  lists and graph (Tab to nodes, Enter opens, Esc closes the inspector).
+- Both light and dark themes read as finished; colour is never the only carrier of meaning
+  (external links and findings also get an icon or label).
+- Empty, loading and error states designed for every query; no spinner-only screens.
+
+## Tests (TDD)
+
+- Vitest + React Testing Library + `@testing-library/user-event` (`userEvent.setup()` once per
+  test, always `await`); MSW for `/api/*` with handlers built from fixture JSON, never mocking
+  TanStack Query or React internals.
+- Query by role, then label, then text; `data-testid` only for the graph canvas.
+- `findBy*`/`waitFor` for async, never timers; no snapshot tests of components.
+- Accessibility: `vitest-axe` on every page component; no violations.
+- Playwright smoke (`test:e2e`): build, start `ctmchain serve` on a fixture repo, open the
+  folder list, open one folder graph, open one job, see the validate page. Runs in CI on
+  Linux only.
+- Coverage ≥ 80% for `features/` and `lib/`; `components/ui` excluded.
+
+## Verify
+
+1. `npm run lint && npm run typecheck && npm test -- --run --coverage && npm run build`.
+2. `npm run gen:api` produces no diff (types in sync with the API snapshot).
+3. Checklist: tests written first · no `any`, no `console.log` · no hand-written API types ·
+   roles/labels queryable · axe clean · empty/loading/error states present · keyboard works ·
+   both themes checked · bundle report has no unexpected large chunk · no real data in
+   fixtures or MSW handlers.
+4. Finish with the `verify` skill and paste its report in the PR.

controlm_chain_admin-0.1.0/.claude/skills/verify/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: verify
+description: End-of-part quality gate for controlm-chain-admin. Runs lint, types, tests with coverage, the no-real-data scan and a diff review, then writes a PASS/FAIL report. Use at the end of every backlog story, before opening a PR, after a refactor, or whenever someone asks to «verificar», «validar», «está ok?», «run the gate» or «check before PR».
+---
+
+# verify — the common gate
+
+Adapted from Everything Claude Code `verification-loop` (MIT, see `.claude/ATTRIBUTION.md`).
+Every area skill (`python-core-tdd`, `fastapi-api`, `react-frontend`, `oss-repo-standards`)
+ends by invoking this one. The report goes into the PR description.
+
+## 1. Run the script
+
+```bash
+.claude/skills/verify/verify.sh            # whole repo
+.claude/skills/verify/verify.sh --python   # only the Python gate
+.claude/skills/verify/verify.sh --web      # only the frontend gate
+```
+
+The script detects what exists (`pyproject.toml`, `web/package.json`) and runs, in order:
+
+| Phase | Python | Frontend |
+|---|---|---|
+| Lint | `ruff check .` and `ruff format --check .` | `npm run lint` |
+| Types | `mypy src` | `npm run typecheck` |
+| Tests | `pytest --cov=controlm_chain_admin --cov-fail-under=<gate>` | `npm test -- --run --coverage` |
+| Build | `python -m build` (when `build` is installed) | `npm run build` |
+| No real data | `git ls-files` grepped with the patterns in `.claude/no-real-data.patterns` (local, git-ignored) | same |
+| Debug leftovers | `breakpoint()`, `pdb` in `src/` | `console.log` in `web/src/` |
+| Diff | `git diff --stat` against the base branch | same |
+
+A phase that fails stops the gate with `FAIL`; fix it before continuing. The no-real-data
+patterns file is deliberately not in the repository; when it is missing the phase reports
+`SKIPPED (no patterns file)` and the maintainer must run the gate locally before merging.
+
+## 2. Review the diff by hand
+
+After the script passes, read `git diff <base>...HEAD` and answer, per file:
+
+- Is every change intended and within the story's scope?
+- Does each new behaviour have a test that was written first (test file in the same commit)?
+- Are errors handled explicitly, with typed errors from `core`, never swallowed?
+- Is anything duplicated that `core` already provides?
+- Does any string look like real data (job names with a real application prefix, hostnames,
+  user names, e-mail addresses, internal URLs)?
+
+## 3. Write the report
+
+```text
+VERIFICATION REPORT — <story id> — <date>
+Lint:          PASS/FAIL
+Types:         PASS/FAIL (n errors)
+Tests:         PASS/FAIL (x/y passed, z% coverage, gate g%)
+Build:         PASS/FAIL/SKIPPED
+No real data:  PASS/FAIL/SKIPPED
+Debug left:    PASS/FAIL
+Diff:          n files, +a/−b, reviewed by hand: yes/no
+Overall:       READY / NOT READY for PR
+Issues:
+1. ...
+```
+
+`READY` requires every phase `PASS` (or `SKIPPED` only for Build and, locally run later, No
+real data) and the hand review done. Never report `READY` from memory: paste the script output.

controlm_chain_admin-0.1.0/.claude/skills/verify/verify.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# verify.sh — the controlm-chain-admin quality gate. Prints a PASS/FAIL report, exits 1 on FAIL.
+# Usage: .claude/skills/verify/verify.sh [--python] [--web] [--base <git-ref>]
+set -uo pipefail
+
+ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+RUN_PY=1; RUN_WEB=1; BASE="origin/main"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --python) RUN_WEB=0 ;;
+    --web) RUN_PY=0 ;;
+    --base) BASE="$2"; shift ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+declare -a REPORT=(); FAIL=0
+record() { REPORT+=("$(printf '%-14s %s' "$1:" "$2")"); case "$2" in FAIL*) FAIL=1 ;; esac; }
+run() { # run <label> <command...>; keeps the last 25 lines of output on failure
+  local label="$1"; shift
+  local out; out="$("$@" 2>&1)"; local rc=$?
+  if [ $rc -eq 0 ]; then record "$label" "PASS"; else record "$label" "FAIL (exit $rc)"; printf -- '--- %s\n%s\n' "$label" "$(printf '%s\n' "$out" | tail -25)"; fi
+  return $rc
+}
+
+# ---------------------------------------------------------------- Python
+if [ $RUN_PY -eq 1 ] && [ -f pyproject.toml ]; then
+  run "Lint (ruff)" ruff check . && run "Format (ruff)" ruff format --check . || true
+  [ -d src ] && run "Types (mypy)" mypy src || true
+  GATE="$(sed -n 's/^fail_under *= *\([0-9]*\).*/\1/p' pyproject.toml | head -1)"; GATE="${GATE:-90}"
+  run "Tests (pytest)" pytest -q --cov=controlm_chain_admin --cov-report=term-missing --cov-fail-under="$GATE" || true
+  if python3 -c "import build" 2>/dev/null; then run "Build (wheel)" python3 -m build --outdir /tmp/ctmchain-build-check || true; else record "Build (wheel)" "SKIPPED (pip install build)"; fi
+  if [ -d src ] && grep -rnE "breakpoint\(\)|import pdb|pdb\.set_trace" src >/dev/null 2>&1; then record "Debug left (py)" "FAIL"; grep -rnE "breakpoint\(\)|import pdb|pdb\.set_trace" src; else record "Debug left (py)" "PASS"; fi
+elif [ $RUN_PY -eq 1 ]; then
+  record "Python" "SKIPPED (no pyproject.toml)"
+fi
+
+# ---------------------------------------------------------------- Frontend
+if [ $RUN_WEB -eq 1 ] && [ -f web/package.json ]; then
+  if [ ! -d web/node_modules ]; then
+    record "Frontend" "SKIPPED (web/node_modules missing: run npm ci in web/)"
+  else
+    run "Lint (web)" npm --prefix web run --silent lint || true
+    run "Types (web)" npm --prefix web run --silent typecheck || true
+    run "Tests (web)" npm --prefix web run --silent test:run -- --coverage || true
+    run "Build (web)" npm --prefix web run --silent build || true
+  fi
+  if grep -rn "console.log" web/src >/dev/null 2>&1; then record "Debug left (web)" "FAIL"; grep -rn "console.log" web/src | head; else record "Debug left (web)" "PASS"; fi
+elif [ $RUN_WEB -eq 1 ]; then
+  record "Frontend" "SKIPPED (no web/package.json)"
+fi
+
+# ---------------------------------------------------------------- No real data
+PATTERNS=".claude/no-real-data.patterns"
+if [ -f "$PATTERNS" ]; then
+  HITS="$(git ls-files -z | xargs -0 grep -nIiE -f "$PATTERNS" -- 2>/dev/null | grep -v "^${PATTERNS}:" || true)"
+  if [ -n "$HITS" ]; then record "No real data" "FAIL ($(printf '%s\n' "$HITS" | wc -l | tr -d ' ') hits)"; printf '%s\n' "$HITS" | head -20; else record "No real data" "PASS"; fi
+else
+  record "No real data" "SKIPPED (no $PATTERNS; run locally before merging)"
+fi
+
+# ---------------------------------------------------------------- Diff
+if git rev-parse --verify -q "$BASE" >/dev/null; then
+  record "Diff vs $BASE" "$(git diff --shortstat "$BASE"...HEAD 2>/dev/null | sed 's/^ *//' || echo 'n/a')"
+else
+  record "Diff" "base $BASE not found (use --base)"
+fi
+
+echo; echo "VERIFICATION REPORT — $(date +%Y-%m-%d) — $(git rev-parse --short HEAD 2>/dev/null || echo 'no commits')"
+printf '%s\n' "${REPORT[@]}"
+if [ $FAIL -eq 1 ]; then echo "Overall:       NOT READY"; exit 1; else echo "Overall:       READY (hand review of the diff still required)"; fi