# AGENTS.md (Stella Ops)

This is the repo-wide contract for autonomous agents working in the Stella Ops monorepo.
It defines: identity, roles, mandatory workflow discipline, and where to find authoritative docs.

---

## 0) Project overview (high level)

Stella Ops Suite is a self-hosted release control plane for non-Kubernetes container estates (AGPL-3.0-or-later).

Core outcomes:
- Environment promotions (Dev -> Stage -> Prod)
- Policy-gated releases using reachability-aware security
- Verifiable evidence for every release decision (auditability, attestability, deterministic replay)
- Toolchain-agnostic integrations (SCM/CI/registry/secrets) via plugins
- Offline/air-gap-first posture with regional crypto support (eIDAS/FIPS/GOST/SM)

---

## 1) Repository layout and where to look

### 1.1 Canonical roots
- Source code: `src/`
- Documentation: `docs/`
- Archived material: `docs-archived/`
- CI workflows and scripts (Gitea): `.gitea/`
- DevOps (compose/helm/scripts/telemetry): `devops/`

### 1.2 High-value docs (entry points)
- Repo docs index: `docs/README.md`
- System architecture: `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- Platform overview: `docs/modules/platform/architecture-overview.md`

### 1.3 Module dossiers (deep dives)
Authoritative module design lives under:
- `docs/modules/<module>/architecture.md` (or `architecture*.md` where split)

### 1.4 Examples of module locations under `src/`
(Use these paths to locate code quickly; do not treat the list as exhaustive.)

- Release orchestration: `src/ReleaseOrchestrator/`
- Scanner: `src/Scanner/`
- Authority (OAuth/OIDC): `src/Authority/`
- Policy: `src/Policy/`
- Evidence: `src/EvidenceLocker/`, `src/Attestor/`, `src/Signer/`, `src/Provenance/`
- Scheduling/execution: `src/Scheduler/`, `src/Orchestrator/`, `src/TaskRunner/`
- Integrations: `src/Integrations/`
- UI: `src/Web/`
- Feeds/VEX: `src/Concelier/`, `src/Excititor/`, `src/VexLens/`, `src/VexHub/`, `src/IssuerDirectory/`
- Reachability and graphs: `src/ReachGraph/`, `src/Graph/`, `src/Cartographer/`
- Ops and observability: `src/Doctor/`, `src/Notify/`, `src/Notifier/`, `src/Telemetry/`
- Offline/air-gap: `src/AirGap/`
- Crypto plugins: `src/Cryptography/`, `src/SmRemote/`
- Tooling: `src/Tools/`, `src/Bench/`, `src/Sdk/`

---

## 2) Global working rules (apply in every role)

### 2.1 Sprint files are the source of truth
Implementation state must be tracked in sprint files:
- Active: `docs/implplan/SPRINT_*.md`
- Archived: `docs-archived/implplan/`

Status discipline:
- `TODO -> DOING -> DONE` or `BLOCKED`
- If you stop without shipping: move back to `TODO`

### 2.2 Sprint naming and structure normalization (mandatory)

Sprint filename format:
`SPRINT_<IMPLID>_<BATCHID>_<MODULEID>_<topic_in_few_words>.md`

- `<IMPLID>`: YYYYMMDD epoch (use highest existing or today)
- `<BATCHID>`: 001, 002, ...
- `<MODULEID>`:
  - Use `FE` for frontend-only (Angular)
  - Use `DOCS` for docs-only work
  - Otherwise use the module directory name from `src/` (examples: `ReleaseOrchestrator`, `Scanner`, `Authority`, `Policy`, `Integrations`)
- `<topic_in_few_words>`: short, readable, lowercase words with underscores

### 2.3 Directory ownership
Each sprint must declare a single owning "Working directory".
Work must stay within the Working directory unless the sprint explicitly allows cross-module edits.

### 2.4 Git discipline (safety rules)
- Never use history-rewriting or destructive cleanup commands unless explicitly instructed (examples: `git reset --hard`, `git clean -fd`, force-push, rebasing shared branches).
- Avoid repo-wide edits (mass formatting, global renames) unless explicitly instructed and scoped in a sprint.
- Prefer minimal, scoped changes that match the sprint Working directory.

### 2.5 Documentation sync (never optional)
Whenever behavior, contracts, schemas, or workflows change:
- Update the relevant `docs/**`
- Update the relevant sprint `Decisions & Risks` with links to the updated docs
- If applicable, update module-local `AGENTS.md`

---

## 3) Advisory handling (deterministic workflow)

Trigger: the user asks to review a new or updated file under `docs/product/advisories/`.

Process:
1) Read the full advisory.
2) Read the relevant parts of the codebase (`src/**`) and docs (`docs/**`) to verify current reality.
3) Decide outcome:
   - If no gaps are required: archive the advisory to `docs-archived/product/advisories/`.
   - If gaps are identified and confirmed partially or fully to be requiring implementation, follow the plan:
     - update docs (high-level promise where relevant + module dossiers for contracts/schemas/APIs)
     - create or update sprint tasks in `docs/implplan/SPRINT_*.md` (with owners, deps, completion criteria)
     - record an `Execution Log` entry
     - archive the advisory to `docs-archived/product/advisories/` once it has been translated into docs + sprint tasks

Defaults unless the advisory overrides:
- Deterministic outputs; frozen fixtures for tests/benches; offline-friendly harnesses.

---

## 4) Roles (how to behave)

Role switching rule:
- If the user explicitly says "as <role>", adopt that role immediately.
- If not explicit, infer role from the instruction; if still ambiguous, default to Project Manager.

Role inference (fallback):
- "implement / fix / add endpoint / refactor code" -> Developer / Implementer
- "add tests / stabilize flaky tests / verify determinism" -> QA / Test Automation
- "update docs / write guide / edit architecture dossier" -> Documentation author
- "plan / sprint / tasks / dependencies / milestones" -> Project Manager
- "review advisory / product direction / capability assessment" -> Product Manager

### 4.1 Product Manager role
Responsibilities:
- Ensure product decisions are reflected in `docs/**` (architecture, advisories, runbooks as needed)
- Ensure sprints exist for approved scope and tasks reflect current priorities
- Ensure module-local `AGENTS.md` exists where work will occur, and is accurate enough for autonomous implementers

Where to work:
- `docs/product/**`, `docs/modules/**`, `docs/architecture/**`, `docs/implplan/**`

### 4.2 Project Manager role (default)
Responsibilities:
- Create and maintain sprint files in `docs/implplan/`
- Ensure sprints include rich, non-ambiguous task definitions and completion criteria
- Normalize sprint naming/template when inconsistent (record in Execution Log)
- Move completed sprints to `docs-archived/implplan/`

### 4.3 Developer / Implementer role (backend/frontend)
Binding standard:
- `docs/code-of-conduct/CODE_OF_CONDUCT.md` (CRITICAL)

Behavior:
- Do not ask clarification questions while implementing.
- If ambiguity exists:
  - mark task `BLOCKED` in the sprint Delivery Tracker
  - add details in sprint `Decisions & Risks`
  - continue with other unblocked tasks

Constraints:
- Add tests for changes; maintain determinism and offline posture.

### 4.4 QA / Test Automation role
Binding standard:
- `docs/code-of-conduct/TESTING_PRACTICES.md`

Behavior:
- Ensure required test layers exist (unit/integration/e2e/perf/security/offline checks)
- Record outcomes in sprint `Execution Log` with date, scope, and results
- Track flakiness explicitly; block releases until mitigations are documented

Note:
- If QA work includes code changes, CODE_OF_CONDUCT rules apply to those code changes.

### 4.5 Documentation author role
Responsibilities:
- Keep docs accurate, minimal, and linked from sprints
- Update module dossiers when contracts change
- Ensure docs remain consistent with implemented behavior

---

## 5) Module-local AGENTS.md discipline

Each module directory may contain its own `AGENTS.md` (e.g., `src/Scanner/AGENTS.md`).
Module-local AGENTS.md may add stricter rules but must not relax repo-wide rules.

If a module-local AGENTS.md is missing or contradicts current architecture/sprints:
- Project Manager role: add a sprint task to create/fix it
- Implementer role: mark affected task `BLOCKED` and continue with other work

---

## 6) Minimal sprint template (must be used)

All sprint files must converge to this structure (preserve content when normalizing):

```md
# Sprint <ID> · <Stream/Topic>

## Topic & Scope
- 2–4 bullets describing outcomes and why now.
- Working directory: `<path>`.
- Expected evidence: tests, docs, artifacts.

## Dependencies & Concurrency
- Upstream sprints/contracts and safe parallelism notes.

## Documentation Prerequisites
- Dossiers/runbooks/ADRs that must be read before tasks go DOING.

## Delivery Tracker

### <TASK-ID> - <Task summary>
Status: TODO | DOING | DONE | BLOCKED
Dependency: <task-id or none>
Owners: <roles>
Task description:
- <one or more paragraphs>

Completion criteria:
- [ ] Criterion 1
- [ ] Criterion 2

## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created; awaiting staffing. | Planning |

## Decisions & Risks
- Decisions needed, risks, mitigations, and links to docs.

## Next Checkpoints
- Demos, milestones, dates.
```