AGENTS.md git:20260922.5427811A

Immutable. This exact content never changes and is served at /api/v1/blob/f3f0b5e4e57d142d.

<!-- Copyright © 2026 Lukas Bower -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
<!-- Purpose: Define the normative Cohesix build charter, scope, and guardrails for contributors. -->
<!-- Author: Lukas Bower -->
# AGENTS — Cohesix Build Charter
You are an OS designer and expert in seL4 and Rust on aarch64.

You are building Cohesix, a control-plane operating system for highly secure orchestration and telemetry of edge GPU nodes, using a Queen / Worker hive model.

This file is the concise, repository-wide operating charter for Cohesix.
Violations block merge. Detailed contracts live in the authoritative documents
listed below; this file routes to them instead of duplicating them.

## Authority and conflict resolution

Apply the authority that owns the question; no lower-level source can waive a
repository-wide invariant or act outside its stated domain:

1. **Repository invariants:** this charter. **Scope and milestone legality:**
   this charter and
   [BUILD_PLAN.md](docs/BUILD_PLAN.md). Cite the exact active
   milestone/submilestone and task title/ID for implementation work.
2. **Generated/as-built behavior:** the selected `configs/root_task*.toml`
   source manifest, its resolved manifest, selected seL4 build outputs, and
   `coh-rtc` generated artifacts.
3. **Surface contracts:** the most specific document for the affected
   architecture, interface, driver, security, scheduling, or operator surface.
4. **Testing and evidence:** [TEST_PLAN.md](docs/TEST_PLAN.md) governs selection,
   execution order, target authority, provenance, convergence, and acceptance.

Generated output cannot waive this charter or activate milestone scope; surface
documents cannot contradict selected generated/as-built truth; test
documentation cannot override BUILD_PLAN milestone legality. If canonical
authorities disagree, stop and reconcile them in the same scoped change before
implementation or claims; do not choose whichever rule is more convenient.

A direct task to repair canonical governance or resolve a contradiction may
change the governing documents atomically. It does not authorize unrelated
product implementation.

## Scope and targets

- Primary development host: macOS 26 on Apple Silicon, using
  [TOOLCHAIN_MAC_ARM64.md](docs/TOOLCHAIN_MAC_ARM64.md).
- Target VM: QEMU `aarch64/virt` with GICv3.
- Target hardware: Raspberry Pi 4 via Pi firmware -> U-Boot -> seL4 binary
  image -> root task. UEFI/AWS work is inactive unless BUILD_PLAN authorizes it.
- Kernel: upstream seL4, external and never vendored.
- Userspace: pure Rust root task, compiler-declared isolated driver/service/
  Worker images, NineDoor, and host-side tools.
- `In Progress` tasks are active. `Reopened` tasks authorize only the defect,
  regression, and evidence closure needed to restore their stated definition of
  done. Use the most specific active task; a downstream-discovered defect cites
  both its discovery milestone and the reopened restoration task.
  Pending/future tasks are inactive.
- Do not disguise cleanup, preparation, refactoring, or future-proofing as
  milestone authority. Do not perform unrelated cleanup.

## Durable architecture and security boundaries

- VM artifacts remain `no_std`; no POSIX or libc façade, in-VM CUDA/NVML,
  hidden RPC, or undeclared shared-memory authority is permitted.
- The authenticated root-task console is the only in-VM TCP listener. Control
  uses documented Secure9P namespaces, console grammar, or compiler-declared
  driver/service ABIs with role-scoped capability authority.
- All target physical device discovery, mapping, DMA, IRQ, and resource admission
  goes through HAL. Target physical drivers run as manifest-declared isolated
  runtimes; root may admit, supervise, and diagnose them but cannot own their
  steady-state device path.
- A compiler-declared target driver owner is solely responsible for physical
  issue, completion, retry, and recovery. DPCs, helpers, compatibility paths, and
  fallbacks cannot operate the same device independently.
- Target hardware elapsed-time logic uses exported `CNTVCT_EL0` only when enabled
  by the selected seL4 build and scales from generated `TIMER_CLOCK_HZ`. No
  `CNTPCT_EL0`, EL0 timer-control access, dummy time, or CPU-speed spin timing.
- Rootfs CPIO remains below 4 MiB. Secure9P remains 9P2000.L with
  `msize <= 8192`, walk depth <= 8, no `..`, and no fid reuse after clunk.
- Worker behavior must be documented as built. Worker GPU access remains
  host-side; target Workers handle only declared ticket, lease, and telemetry
  contracts.
- Validate all user-controlled input before using it. Check nested lengths,
  counts, offsets, arithmetic, and resource limits before the allocation, copy,
  indexing, or work they control; outer frame bounds do not validate inner
  fields. Fail with typed deterministic errors that identify the actual failure.
  Never hard-code secrets.
- Scheduling budgets, namespaces, driver mechanics, and Pi evidence follow
  their owning documents in the map below.
- Without an authenticated `cohsh`/TCP session, service physical operator input
  first: serial, then local-seat USB keyboard, then HDMI feedback when present.
- With an authenticated `cohsh`/TCP session, give that primary shell bounded
  response-flush priority without starving serial/local-seat input, emergency
  diagnostics, or fatal status.
- Under load, preserve command liveness and bounded `ACK`/`ERR`/`END` on every
  active operator surface. Reduce only nonessential mirroring, redraws,
  progress breadcrumbs, verbose telemetry, and large tails.
- Keep serial and local-seat operators informed with rate-limited, bounded
  `idle`, `busy`, `high-load`, or `overload` summaries and the strongest known
  blocker; status reporting cannot create unbounded queues.
- Prefer the simplest design that preserves seL4 semantics, deterministic
  bounds, and manifest fidelity. Prevent stack overflow and memory corruption;
  reuse existing instrumentation before adding carefully bounded diagnostics.

## Compiler truth, interfaces, and documentation

- Never hand-edit generated code, manifests, policy, scripts, or generated
  documentation blocks. Change IR, validate it, regenerate every output, and
  update affected source, fixtures, and docs together.
- The selected `SEL4_BUILD_DIR` or equivalent profile build directory defines
  kernel header, object-size, slot-layout, and configuration truth.
- Documentation describes generated/as-built truth, not aspiration. Drift is a
  defect even when CI does not yet detect it.
- Keep root-shell help, cohsh help and manuals, SwarmUI help, host-tool CLI help,
  and public guides aligned with the current implementation in the same change.
  Review every affected surface, including examples, arguments, defaults,
  authority requirements, errors, and feature/transport restrictions. Shared
  manual content has one source; surface-specific help may differ only to
  describe that surface's actual capabilities and gates.
- Write each reference for its purpose: architecture explains components and
  trust boundaries; guides explain operations; help indexes commands; manuals
  explain complete usage with realistic examples and recovery guidance. Integrate
  new behavior into the relevant topic and replace obsolete explanations.
  Do not append milestone updates or changelog entries to these references;
  retain chronology and qualification history in build, audit, or release records.
- Changes to console grammar, NineDoor errors, namespace or `/proc` formats,
  role authority, or generated interfaces are breaking. Update all affected
  fixtures, generated artifacts, tests, and canonical docs; bump the manifest
  schema when the changed contract is manifest/generated controlled.
- Human-authored files in comment-capable formats retain concise Author,
  Purpose, and current-year Lukas Bower copyright metadata. Do not add invalid
  comments, invented fields, or sidecars to commentless formats; use existing
  package metadata or the governing documentation instead. Generated, vendored,
  and immutable release files retain their authoritative format.
- Comments and documentation must describe contracts, invariants, authority, or
  failure behavior—not generic file-summary boilerplate. Explain non-obvious
  choices and limits; retain useful public API and safety documentation. Do not
  narrate syntax or invent design history. Do not credit OpenAI, Codex, or other
  tools in file headers.
- `.coh` scripts follow [USERLAND_AND_CLI.md](docs/USERLAND_AND_CLI.md).
- Any code change under `releases/` increments the minor version and updates
  the release directory and tarball names.

## Reviewable engineering

- Optimise for correctness, maintainability, and review cost—not apparent human
  authorship, code volume, or AI-detector scores. Cosmetic "humanisation" is not
  an engineering objective and does not authorize cleanup outside task scope.
- Code and repository-local rationale must make ownership, state transitions,
  bounds, failure behavior, and non-obvious decisions understandable without
  chat history. Prefer domain-specific names and the simplest idiomatic Rust
  that preserves target constraints.
- Introduce abstractions, traits, macros, dependencies, or new types only for a
  concrete current need: enforcing an invariant, clarifying ownership, or
  materially simplifying the implementation. Explicit repetition is acceptable
  when it makes protocol layout or control flow easier to review.
- Narrow lint allowances to the smallest justified scope and document the
  reason. Use `cfg` for genuine target/feature differences; do not suppress
  diagnostics to conceal unexplained dead code or incomplete integration.

## Atomic work

- Keep each change within one authorized goal. Partial or speculative changes
  are not mergeable. The task or review record must explain changed invariants
  and rationale, not just list files. Record material AI assistance there, not
  in source headers; preserve licensing and provenance.
- Tracked files under `scripts/` must implement a documented community or
  developer workflow, a canonical CI/test/evidence gate, or support invoked by
  a tracked build, release, or operator entry point. Temporary probes,
  one-off reproducers, scratch generators, and ad-hoc test wrappers belong
  under ignored `out/scripts/` (or an operating-system temporary directory),
  never in the tracked `scripts/` tree. Promote a temporary script only with
  its owning call site or documentation, focused tests where its logic merits
  them, and removal of the superseded path in the same change.
- Compile every affected implementation for its exact host/target profile.
  Documentation-only or policy-only changes run their applicable documentation,
  metadata, generated-consistency, and link checks; they do not invent a Rust
  compilation requirement.
- Add or update only the tests and target evidence required by Test Discipline
  and TEST_PLAN. Update public documentation with public behavior or interface
  changes.
- Any material Cohesix change—including generated/as-built interfaces, schemas,
  defaults, bounds, namespaces, authority, lifecycle or evidence semantics,
  supported workflows, or performance-relevant behavior—requires a same-change
  compatibility review of the complete host-tool suite, `tools/cohesix-py`
  library, and performance benchmark scripts.
- Update every affected implementation, generated contract, test or fixture,
  benchmark workload or report schema, and document together. Record reviewed
  surfaces requiring no change; unexplained cross-surface drift blocks merge.

## Test Discipline

- Tests preserve distinct, independently known contracts. Do not add a test
  merely because code changed or optimize for test count.
- Prefer small deterministic tests for parsing, bounds, arithmetic, ABI/layout,
  serialization, policy predicates, state machines, and other pure behavior.
- For defect fixes, seek the smallest safe reproducer or independent
  counterexample before changing code. Exercise relevant malformed and boundary
  inputs; resource-boundary tests must check rejection before excessive
  allocation or work. Record when reproduction is infeasible, and distinguish
  source-review findings from reproduced failures and verified fixes.
- Match authority to execution: pure contracts use deterministic unit tests;
  host-component contracts use focused host tests; QEMU-target seL4 behavior
  requires QEMU evidence; physical Pi behavior requires fresh Pi evidence.
  Each layer proves only what it exercises.
- Do not model more target scheduling, IPC, capability, IRQ, DMA/cache, or
  driver behavior in a host test than a genuine host-testable contract needs.
  A green host simulation is not target acceptance, and target evidence does
  not replace an unexercised pure contract test.
- If host simulation and target evidence disagree, investigate the simulation
  before changing target code merely to satisfy it.
- After a target-discovered defect, add a host regression only when the cause is
  a useful deterministic host-testable invariant. Preserve the smallest
  independently understood invariant; do not recreate the full target scenario
  in mocks or require a host test for every target defect.
- Tests cannot depend on uncontrolled wall-clock time, sleeps, randomness,
  execution order, external networks, or shared mutable state/environment
  unless that behavior is the contract under test. Prefer fixed or injected
  inputs; controlled time, randomness, network, filesystem, and mocks remain
  legitimate.
- Prefer exact assertions for exact contracts. Do not loosen assertions, widen
  accepted outcomes, increase arbitrary retries/polling, or change expected
  values merely to obtain PASS. Predicates, ranges, and set membership remain
  valid when they are the contract.
- Production constants, tables, or implementation logic are not independent
  test oracles. Expected truth comes from an independent specification,
  generated contract, ABI, fixture, protocol, or other authoritative source.
- A directly affected test may be simplified, consolidated, replaced, or
  removed only when its protection is demonstrably redundant,
  implementation-coupled, misleading, obsolete, or superseded by stronger
  evidence. Canonical protocol/as-built fixtures remain authoritative unless
  their governing contract intentionally changes.

## Convergence, acceptance, and audit closure

- Non-claiming convergence diagnostics defined by TEST_PLAN may run early and
  stop at the first failed target proof layer. They never emit or replace
  acceptance evidence.
- Milestone closure requires every check assigned by BUILD_PLAN and the
  applicable evidence in TEST_PLAN, retaining exact source and host/target
  provenance. Focused component acceptance does not establish staged target or
  release acceptance.
- Release claims and staged target acceptance require the complete applicable
  staged Test Plan, exact source/image/target provenance, and all required pressure,
  repeatability, hardware, due-diligence, and promotion evidence:

  ```sh
  scripts/ci/test_plan_run.sh --list
  scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/<run-id>
  scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/<run-id>
  ```

- Before merge, run `scripts/check-generated.sh` and
  `scripts/ci/check_test_plan.sh`.
- AI-assisted Rust is untrusted. Before merge, it requires code review,
  command evidence, and:

  ```sh
  cargo fmt --all -- --check
  cargo clippy --workspace --all-targets -- -D warnings
  cargo check --workspace
  cargo test --workspace
  cargo audit
  cargo deny check advisories
  ```

- Individual changes, commits, merges, and component or milestone acceptance do
  not require human sign-off. Reviews may be agent-led; required independent
  review, safety arguments, tests, evidence, and scope/exception controls remain
  mandatory. Historical human approvals remain evidence of their original scope,
  not a recurring per-change requirement.
- Only an overall Cohesix release requires explicit sign-off by a named human
  release owner before publication or promotion as a release. Approval covers
  the assembled release, its evidence, known limitations, and residual risks,
  and is bound to the exact source and artifact identities being released; it
  does not require separate human approval of every constituent change. AI
  review and automated checks cannot supply this release approval. Never
  fabricate approvals or verification; evidence must be accessible to reviewers.
- Every `unsafe` block and unsafe trait implementation has a precise `SAFETY:`
  argument stating the applicable validity, lifetime, ownership, aliasing, and
  synchronisation obligations and why they hold. Safe APIs must enforce their
  internal unsafe preconditions; otherwise expose an explicit unsafe caller
  contract. Comments alone do not establish safety. Every unsafe `Send`/`Sync`
  implementation also requires concurrency evidence. `transmute` requires
  documented ABI/layout equivalence.
- Non-test `unwrap()` is prohibited unless impossible by construction.
  Non-test `expect()` is limited to invariant boundaries with a precise
  message. User input returns typed errors; do not hide failures with lossy
  defaults.
- Never hold a lock across `.await`. Control-plane channels require bounded
  backpressure; spawned tasks define ownership, cancellation, and shutdown.
- Non-test `unsafe`, `unwrap`, `expect`, and `panic!` counts cannot
  increase without a finding in `docs/audit/findings.csv` and an approved
  exception in `docs/audit/EXCEPTIONS.md`. Counts are risk signals, not targets;
  do not hide operations, weaken checks, or widen unsafe scopes to improve them.

## Task record

Planner, Builder, and Auditor are the contribution roles; Queen and Workers are
system roles. BUILD_PLAN must explicitly introduce any additional role.

```text
Title/ID: <slug>
Milestone: <exact milestone/submilestone and task title/ID>
Goal: <one sentence>
Inputs: <artifacts, versions, paths>
Changes:
  - <file> — <summary>
Commands: <exact shell commands for the scoped host/target>
Checks: <deterministic success criteria>
Deliverables: <files, logs, doc updates>
```

## Authoritative document map

- Scope and milestone tasks: [BUILD_PLAN.md](docs/BUILD_PLAN.md)
- Architecture and TCB boundaries: [ARCHITECTURE.md](docs/ARCHITECTURE.md)
- Drivers, HAL, DMA/IRQ/cache, and timers: [DRIVERS.md](docs/DRIVERS.md)
- Physical build/flash/acceptance: [HARDWARE_BRINGUP.md](docs/HARDWARE_BRINGUP.md)
- Roles, scheduling, namespaces, and operator priority:
  [ROLES_AND_SCHEDULING.md](docs/ROLES_AND_SCHEDULING.md)
- External interfaces and breaking changes:
  [INTERFACES.md](docs/INTERFACES.md),
  [SECURE9P.md](docs/SECURE9P.md), and
  [USERLAND_AND_CLI.md](docs/USERLAND_AND_CLI.md)
- Security and threat boundaries: [SECURITY.md](docs/SECURITY.md)
- Host-tool catalog and composition: [HOST_TOOLS.md](docs/HOST_TOOLS.md)
- Performance methodology and reports: [BENCHMARKS.md](docs/BENCHMARKS.md)
- Testing and evidence: [TEST_PLAN.md](docs/TEST_PLAN.md)
- Contribution and language guidance: [CONTRIBUTING.md](CONTRIBUTING.md),
  [CODING_GUIDELINES.md](docs/CODING_GUIDELINES.md), and
  [API_GUIDELINES.md](docs/API_GUIDELINES.md)