work

src/Excititor/AGENTS.md

@@ -0,0 +1,44 @@
+# Excititor · AGENTS Charter (Air-Gap & Trust Connectors)
+
+## Module Scope & Working Directory
+- Working directory: `src/Excititor/**` (WebService, Worker, __Libraries, __Tests, connectors, scripts). No cross-module edits unless explicitly noted in sprint Decisions & Risks.
+- Mission (current sprint): air-gap parity for evidence chunks, trust connector wiring, and attestation verification aligned to Evidence Locker contract.
+
+## Roles
+- **Backend engineer (ASP.NET Core / Mongo):** chunk ingestion/export, attestation verifier, trust connector.
+- **Air-Gap/Platform engineer:** sealed-mode switches, offline bundles, deterministic cache/path handling.
+- **QA automation:** WebApplicationFactory + Mongo2Go tests for chunk APIs, attestations, and trust connector; deterministic ordering/hashes.
+- **Docs/Schema steward:** keep chunk API, attestation plan, and trust connector docs in sync with behavior; update schemas and samples.
+
+## Required Reading (treat as read before DOING)
+- `docs/README.md`
+- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
+- `docs/modules/platform/architecture-overview.md`
+- `docs/modules/excititor/architecture.md`
+- `docs/modules/excititor/attestation-plan.md`
+- `docs/modules/excititor/operations/chunk-api-user-guide.md`
+- `docs/modules/excititor/schemas/vex-chunk-api.yaml`
+- `docs/modules/evidence-locker/attestation-contract.md`
+
+## Working Agreements
+- Determinism: canonical JSON ordering; stable pagination; UTC ISO-8601 timestamps; sort chunk edges deterministically.
+- Offline-first: default sealed-mode must not reach external networks; connectors obey allowlist; feature flags default safe.
+- Attestation: DSSE/Envelope per contract; always include tenant/source identifiers; validation fixtures required.
+- Tenant safety: enforce tenant headers/guards on every API; no cross-tenant leakage.
+- Logging/metrics: structured logs; meters under `StellaOps.Excititor.*`; tag `tenant`, `source`, `result`.
+- Cross-module edits: require sprint note; otherwise, stay within Excititor working dir.
+
+## Testing Rules
+- Use Mongo2Go/in-memory fixtures; avoid network.
+- API tests in `StellaOps.Excititor.WebService.Tests`; worker/connectors in `StellaOps.Excititor.Worker.Tests`; shared fixtures in `__Tests`.
+- Tests must assert determinism (ordering/hashes), tenant enforcement, and sealed-mode behavior.
+
+## Delivery Discipline
+- Update sprint tracker status (`TODO → DOING → DONE/BLOCKED`) for each task; mirror changes in Execution Log and Decisions & Risks.
+- When changing contracts (API/attestation schemas), update docs and samples and link from sprint Decisions & Risks.
+- If a decision is needed, mark the task BLOCKED and record the decision ask—do not pause work.
+
+## Tooling/Env Notes
+- .NET 10 with preview features enabled; Mongo driver ≥ 3.x.
+- Signing/verifier hooks rely on Evidence Locker contract fixtures under `docs/modules/evidence-locker/`.
+- Sealed-mode tests should run with `EXCITITOR_SEALED=1` (env var) to enforce offline code paths.