up

src/AirGap/AGENTS.md

@@ -0,0 +1,42 @@
+# AirGap Module · AGENTS Charter
+
+## Working Directory
+- `src/AirGap/**` (Controller, Importer, Time). Do not edit other modules without sprint note.
+
+## Roles
+- **Controller engineer (ASP.NET Core)**: seal/unseal state machine, status APIs, Authority scope enforcement.
+- **Importer engineer**: bundle verification (TUF/DSSE), catalog repositories, object-store loaders.
+- **Time engineer**: time anchor parsing/verification (Roughtime, RFC3161), staleness calculators.
+- **QA/Automation**: API + storage tests (Mongo2Go/in-memory), deterministic ordering, sealed/offline paths.
+- **Docs/Runbooks**: keep air-gap ops guides, scaffolds, and schemas aligned with behavior.
+
+## Required Reading (treat as read before DOING)
+- `docs/README.md`, `docs/07_HIGH_LEVEL_ARCHITECTURE.md`, `docs/modules/platform/architecture-overview.md`
+- `docs/modules/airgap/airgap-mode.md` (if present)
+- Prep/Scaffold docs:
+  - `docs/airgap/controller-scaffold.md`
+  - `docs/airgap/prep/2025-11-20-controller-scaffold-prep.md`
+  - `docs/airgap/importer-scaffold.md`
+  - `docs/airgap/time-anchor-scaffold.md`
+  - `docs/airgap/prep/2025-11-20-staleness-drift-prep.md`
+  - `docs/airgap/sealed-startup-diagnostics.md`
+  - `docs/airgap/bundle-repositories.md`
+  - `docs/airgap/time-api.md`, `docs/airgap/time-config-sample.json`
+
+## Working Agreements
+- Offline-first: no egress in sealed mode; fixtures use local files only.
+- Determinism: stable ordering, UTC ISO-8601 timestamps, fixed seeds for tests, deterministic hashing.
+- Tenancy/scopes: enforce Authority scopes (`airgap:seal`, `airgap:status:read`, importer scopes) on every API.
+- Validation: prefer `$jsonSchema`/FluentValidation; fail closed on trust-root mismatch.
+- Logging/Telemetry: structured logs; counters/histograms prefixed `airgap.*`; tag `tenant`, `sealed`, `result`.
+- Cross-module edits require sprint note; otherwise stay within `src/AirGap`.
+
+## Testing Rules
+- Use Mongo2Go/in-memory stores; no network.
+- Cover sealed/unsealed transitions, staleness budgets, trust-root failures, deterministic ordering.
+- API tests via WebApplicationFactory; importer tests use local fixture bundles (no downloads).
+
+## Delivery Discipline
+- Update sprint tracker statuses (`TODO → DOING → DONE/BLOCKED`); log decisions in Execution Log and Decisions & Risks.
+- When contracts/schemas change, update docs under `docs/airgap/**` and link from sprint Decisions & Risks.
+- If a decision is needed, mark BLOCKED in the sprint and record the decision ask; continue with other unblocked work.