fstagni · Oct 21, 2026 · aldbr · Oct 21, 2026 · aldbr · Oct 21, 2026
@@ -1,17 +1,43 @@
 # DIRAC Agent Guidelines
 
+## Environment setup
+- Unit tests and linters require an editable install, with DIRACCommon installed first (dependency resolution):
+  ```bash
+  pip install -e ./dirac-common[testing]
+  pip install -e .[server,testing]
+  ```
+
 ## Build/Lint/Test Commands
-- **Build**: `pip install -e .`
-- **Lint**: `ruff check src/ && pylint src/`
-- **Test**: `pytest tests/`
-- **Single test**: `pytest src/DIRAC/path/to/test.py::test_function`
+- **Unit tests**: `pytest` from the repo root. Configuration is in `pytest.ini`, which picks up `src/DIRAC/**/tests/Test_*.py` and ignores `tests/`.
+- **Slow tests** are skipped by default; include them with `pytest --runslow`.
+- **Single test**: `pytest src/DIRAC/<System>/tests/Test_foo.py::TestClass::test_method`
+- **Lint**: `pre-commit run --all-files` (black, flynt, pyupgrade, bandit, …). CI also runs `pylint -j 0 -E src/` (errors only) and `ruff check src/`.
+- **Type check**: `mypy` (configured in `pyproject.toml`).
+- **Integration/System tests** (`tests/Integration`, `tests/System`): **not runnable standalone** — CI deploys them in containers against a full DIRAC server. Don't attempt to run or fix them locally.
+
+## Repo layout
+- One directory per system under `src/DIRAC/` (`WorkloadManagementSystem`, `DataManagementSystem`, …), plus cross-cutting `Core/`, `Resources/`, `Interfaces/`.
+- Unit tests live beside the code, named `Test_*.py` (e.g. `src/DIRAC/Core/Utilities/tests/Test_*.py`).
+- `tests/` at the repo root is integration/system/CI material only.
+- **Changelog**: user-visible PRs add an entry to `release.notes` under the in-development version heading, grouped by `*<System>`, prefixed `NEW:`/`CHANGE:`/`FIX:`, with the PR number — see existing entries for the format.
+- **Python compatibility**: code must stay Python 3.9+ compatible (pre-commit runs `pyupgrade --py39-plus`). Exception: `src/DIRAC/Resources/Computing/BatchSystems/*`, `PilotWrapper.py` and `tests/Integration/WorkloadManagementSystem/Test_GenerateAndExecutePilotWrapper.py` keep Python 2 compatibility (black py27 target) — don't reformat them by hand; pre-commit handles them.
 
 ## Code Style Guidelines
-- **Formatting**: Use `black` with line length 120 (configured in pyproject.toml)
+- **Formatting**: `black` (via pre-commit); line length 120 (configured in `pyproject.toml`)
 - **Imports**: Absolute imports only; sort with `isort` (black profile)
 - **Naming**: CamelCase for classes, snake_case for functions/variables
 - **Types**: Use type hints; run `mypy` for strict checking
 - **Error handling**: Return `S_OK(result)` or `S_ERROR(message)` from DIRAC.Core.Utilities.ReturnValues
 - **Logging**: Use `gLogger.info/warn/error` (from DIRAC import gLogger)
 - **Docstrings**: Follow Google/NumPy style where present
 - **Security**: Never log secrets; validate inputs
+
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked in this repository's GitHub Issues (use the `gh` CLI). See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+Single-context: `GLOSSARY.md` at the repo root + `docs/adr/`. See `docs/agents/domain.md`. Use the glossary's vocabulary (e.g. "Job" not "task", "Agent" only for server-side agents, "Pilot" for placeholder jobs) — see `GLOSSARY.md` for the _Avoid_ lists.
@@ -0,0 +1,113 @@
+# DIRAC
+
+DIRAC is a framework for distributed computing: a layer between user communities (Virtual Organizations) and heterogeneous grid/cloud resources, providing job execution, data management, and resource status under a common interface.
+
+Grid acronyms (CE, SE, LFN, PFN, WMS, VO, ...) are expanded in `docs/source/UserGuide/glossary.rst`.
+
+## Language
+
+### Workload management
+
+**Job**:
+The unit of user work submitted to DIRAC: a description stored in the job database and executed on a grid resource, carrying a major/minor status state machine.
+_Avoid_: task (that is a Transformation concept)
+
+**Pilot**:
+A short placeholder job submitted to a Computing Element that starts before any user work exists and pulls a real Job via the Matcher.
+
+**JobAgent**:
+The agent running inside a pilot on a worker node that matches itself against the central Matcher and locally executes the Payload.
+_Avoid_: agent (ambiguous with the server-side Agent)
+
+**Payload**:
+The user application actually executed inside a pilot's JobWrapper.
+_Avoid_: application
+
+**JobWrapper**:
+The per-job harness that resolves input data, runs the Payload under a Watchdog, uploads the output sandbox, and reports job parameters and status.
+
+**Watchdog**:
+The monitor thread tracking CPU/memory/time of the running Payload and enforcing limits and signals.
+
+**Matcher**:
+The WMS service assigning waiting Jobs to Pilots, selecting from Task Queues.
+
+**Task Queue (TQ)**:
+A named queue of Jobs awaiting matching, with configurable shares between communities; unrelated to a Transformation Task.
+
+**Sandbox**:
+The small input/output files of a Job held by the central SandboxStore, as opposed to bulk input data managed by the DMS.
+
+**Optimizer**:
+A plugin in the chain processing freshly submitted Jobs before scheduling (job path, sanity, scheduling, input data).
+
+### Data management
+
+**StorageElement (SE)**:
+A logical storage endpoint abstracting one or more protocol plug-ins; can be administratively banned for read/write operations.
+
+**FileCatalog**:
+The logical namespace mapping LFNs to Replicas; writes go through the Master catalog plug-in to keep multiple catalogs consistent.
+
+**LFN**:
+Logical File Name: the globally unique path of a file in the FileCatalog.
+_Avoid_: path
+
+**PFN**:
+Physical File Name: the concrete URL of a Replica on a StorageElement.
+
+**Replica**:
+A copy of an LFN stored on one specific StorageElement.
+
+**Request**:
+A persistent, failover-safe container of Operations executed asynchronously by agents; the fault-tolerant path for all data operations.
+
+**Operation**:
+One unit of data work within a Request (e.g. ReplicateAndRegister, PhysicalRemoval), itself holding Files.
+
+### Transformation system
+
+**Transformation**:
+A reusable recipe that automates production of Tasks over input data, turning high-level data processing into Jobs or Requests.
+
+**Task**:
+One instantiation produced by a Transformation, mapped onto a WMS Job or an RMS Request.
+_Avoid_: job (a Task maps to a Job, it is not one)
+
+### Resources and status
+
+**Site**:
+A grid site: one of the two element families of the resource topology, disjoint from Resource.
+
+**Resource**:
+A concrete service instance (CE, SE, catalog, ...): the second element family of the topology.
+
+**Element**:
+The umbrella term for a Site or a Resource in the resource topology.
+
+**Policy**:
+A rule evaluating a status (Active/Degraded/Banned/Probing) for Sites and Resources; propagation pushes status changes down the topology.
+
+### Infrastructure
+
+**ComputingElement (CE)**:
+The base class abstracting a compute resource: generates the CE description used for job matching and evaluates available CPU slots.
+
+**Proxy**:
+A short-lived X.509 credential, optionally VOMS-extended for a Virtual Organization.
+
+**Shifter**:
+A named privileged identity (e.g. JobSubmission, Production) whose Proxy is assumed server-side on behalf of the community.
+
+**Agent**:
+A server-side daemon running a periodic `execute()` cycle as part of a System.
+_Avoid_: conflating with the worker-node JobAgent
+
+**Service**:
+A long-running RPC server component of a System (Tornado or DISET based).
+
+**System**:
+A subsystem bundling Agents, Services and databases (WMS, DMS, RMS, RSS, Framework, ...).
+
+**Configuration (CS)**:
+The central distributed configuration tree read via `gConfig`; sections like `/LocalSite` and `/Resources/Computing` are load-bearing for matching and credentials.
@@ -0,0 +1,14 @@
+# Agent-facing configuration lives in-repo and targets the upstream tracker
+
+Engineering skills operating on this repository (issue tracking, triage, ticketing, review) read their configuration from `docs/agents/`, which is committed to the upstream repository `DIRACGrid/DIRAC` — not kept as per-clone setup — and every skill treats the upstream repository's issue tracker as the single source of tracked work. We decided this because agents running in any contributor's clone must behave identically and post to the tracker where the project's issues actually live (the fork clones carry no issues), and because glossary/ADR/tracker conventions only pay off as shared, versioned artifacts.
+
+## Considered options
+
+- **Repoint each clone's `origin` at upstream** (with a separate push remote for the fork): cleanest for `gh`'s default repo inference, but rejected because contributors keep an origin-fork convention across all their repositories.
+- **Per-clone local configuration only**: rejected because it defeats the purpose — the conventions would not reach other contributors' agents.
+
+## Consequences
+
+- `docs/agents/issue-tracker.md` documents the upstream-tracker workflow and is generic in the upstream copy.
+- Fork clones (where `origin` is the contributor's fork) pin every `gh` call with `-R DIRACGrid/DIRAC`; their local `issue-tracker.md` carries the pin, and once the tracked upstream version is pulled, the local divergence is held with `git update-index --skip-worktree docs/agents/issue-tracker.md`.
+- Whether triage labels exist upstream and whether external PRs are a triage surface are maintainer decisions, recorded separately in `docs/agents/triage-labels.md` when adopted.
@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`GLOSSARY.md`** at the repo root, or
+- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── GLOSSARY.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `GLOSSARY-MAP.md` at the root):
+
+```
+/
+├── GLOSSARY-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── GLOSSARY.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── GLOSSARY.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_
@@ -0,0 +1,46 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --json number,title,body,labels,comments`.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Make an issue a sub-issue of a parent**: `gh issue create --parent <parent> ...`, or `gh issue edit <parent> --add-sub-issue <child>` afterwards (`gh` 2.94+). Older `gh`: `gh api --method POST repos/<owner>/<repo>/issues/<parent>/sub_issues -F sub_issue_id=<child-db-id>` (database id, as in **Blocking** below). Without sub-issues, put `Part of #<parent>` at the top of the child body.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone. _(Fork clones: pass `-R DIRACGrid/DIRAC` explicitly, since `gh` resolves to the fork.)_
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, author_association, labels: [.labels[].name]}'`.
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Read it as in **Read an issue** above.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (see **Make an issue a sub-issue of a parent**). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.