AGENTS — Cohesix Build Charter

Cohesix is a Rust/seL4 control-plane OS for bounded, capability-scoped orchestration and telemetry of edge GPU nodes, using a Queen / Worker hive model. This charter sets repository-wide invariants; the linked owners supply mandatory detail for the affected work. A prose requirement is not evidence that CI enforces it.

Start here

1. Confirm the requested branch, worktree changes, affected component and exact host/target profile. Preserve unrelated edits, logs and immutable evidence; do not reset, clean, switch branches or overwrite artifacts to simplify a task.
2. Read the relevant BUILD_PLAN task and selected manifest. Implementation must cite its exact active milestone/submilestone and task ID. Read applicable local instructions and the contracts below, not every document.
3. Follow CONTRIBUTING for atomic changes and validation, and Coding Guidelines for Rust and test discipline. Reuse an applicable repository skill or maintained entry point; neither can waive the charter, task scope or evidence requirements.
4. Choose the validation lane before editing. Use the Test Plan’s action catalog and changed-path selection; report commands, results, proof limits and blockers.

Authority and conflict resolution

Use the authority that owns the question; lower-level guidance cannot waive repository invariants or act outside its domain:

1. This charter owns invariants; it and BUILD_PLAN own milestone legality.
2. The selected source/resolved manifest, seL4 build outputs and coh-rtc artifacts own generated/as-built behavior.
3. The most specific architecture, interface, driver, security, scheduling or operator document owns that surface’s contract.
4. TEST_PLAN owns test selection, execution order, target authority, provenance, convergence and acceptance.

Generated output cannot activate scope or waive this charter. Surface documents cannot contradict selected as-built truth; test documents cannot override milestone legality. Stop and reconcile conflicting canonical authorities in the same scoped change, rather than choosing the convenient rule. A direct task to repair governance may change those documents atomically, not unrelated product code.

Scope and targets

• Primary development host: Apple Silicon/macOS 26 under TOOLCHAIN_MAC_ARM64. Confirm the actual environment.
• VM: QEMU aarch64/virt, GICv3. Hardware: Pi 4 firmware -> U-Boot -> seL4 -> root. UEFI/AWS work is inactive unless BUILD_PLAN authorizes it. seL4 stays external.
• In Progress tasks are active. Reopened permits only the stated defect, regression and evidence restoration. Cite both discovery and restoration tasks for downstream-discovered defects. Pending/future tasks are inactive.
• Cleanup, refactoring, preparation or future-proofing creates no scope authority.

Durable architecture and security boundaries

• VM artifacts remain pure Rust and no_std: no POSIX/libc facade, in-VM CUDA/NVML, hidden RPC or undeclared shared-memory authority. GPU access remains host-side; target Workers serve only their declared ticket, lease and telemetry contracts.
• The authenticated console is the sole in-VM TCP listener. Control uses documented Secure9P namespaces, console grammar or compiler-declared driver/service ABIs with role-scoped capabilities.
• Physical discovery, mapping, DMA, IRQ and admission go through HAL. Manifest- declared isolated runtimes own steady-state devices; root admits, supervises and diagnoses. Only the declared owner may issue, complete, retry or recover device operations; helpers and fallbacks cannot become competing owners.
• Target elapsed time uses exported CNTVCT_EL0 only when the selected seL4 build enables it, scaled by generated TIMER_CLOCK_HZ. No CNTPCT_EL0, EL0 timer control, dummy time or CPU-speed spin timing.
• Rootfs CPIO stays below 4 MiB. Secure9P stays 9P2000.L: msize <= 8192, walk depth <= 8, no .., and no fid reuse after clunk.
• Validate nested lengths, counts, offsets, arithmetic and resource limits before the allocation, copy, indexing or work they control. Outer bounds do not validate inner fields. Return typed deterministic errors; never hard-code secrets.
• Without authenticated cohsh/TCP, prioritise serial, then local-seat USB input, then HDMI feedback. With authenticated cohsh/TCP, give its response flush bounded priority without starving physical input, emergency diagnostics or fatal status.
• Under load, preserve command liveness and bounded ACK/ERR/END on every active surface. Reduce only nonessential mirroring, redraws, progress, verbose telemetry and large tails. Report bounded, rate-limited idle/busy/high-load/overload status and the strongest known blocker to serial/local-seat operators.
• Preserve seL4 semantics, manifest fidelity and deterministic bounds. Prevent stack overflow and memory corruption; reuse existing bounded diagnostics.

Compiler truth, interfaces, and documentation

• Never hand-edit generated code, manifests, policy, scripts or documentation blocks. Change IR, validate, regenerate every output and update affected implementations, fixtures and docs together. The selected SEL4_BUILD_DIR owns kernel headers, object sizes, slot layout and configuration truth.
• Documentation describes as-built behavior, not aspiration; drift is a defect. Keep affected CLI/UI help, manuals and public guides aligned. Shared manual content has one source; only genuine surface differences justify variation.
• Write *.md documents in plain English for community readers. Lead with what readers need to understand or do, and explain unfamiliar terms in context. Use technical jargon when it conveys a precise contract; preserve exact command names, schemas, invariants and evidence boundaries.
• Console grammar, NineDoor errors, namespaces, /proc formats, role authority and generated-interface changes are breaking. Update all affected surfaces; bump the manifest schema when the contract is manifest/generated controlled.
• Follow documentation and metadata rules. Explain contracts and non-obvious decisions, not syntax or invented history. Keep useful API/safety documentation; do not credit tools in source headers.
• .coh grammar is owned by USERLAND_AND_CLI. Code changes under releases/ increment the minor version and update directory and tarball names; do not rewrite immutable release evidence.

Code Review Rules

• Report actionable correctness, security, reliability and compatibility issues. Identify the failure condition, affected path and impact; distinguish demonstrated failures from risks. Leave mechanical style to tooling; avoid speculative rewrites.
• Optimise for correctness, maintainability and review cost, not apparent human authorship, code volume or detector scores. Code and repository-local rationale must explain ownership, state transitions, bounds and failures without chat history.
• Use the simplest idiomatic Rust preserving target constraints. Add abstractions, traits, macros, dependencies or types only for a current invariant, ownership boundary or material simplification. Explicit protocol/control-flow repetition is acceptable when easier to review. Narrow and justify lint allowances; use cfg for genuine profile differences, not suppression to hide unfinished work.
• Use unambiguous composite identity/deduplication/correlation encodings and preserve persisted meaning when formats change.
• Distinguish success, already-satisfied state, deterministic refusal and uncertain outcome using provider contracts and observations. Never invent transition evidence or blindly replay uncertain side effects.
• Keep terminal execution separate from pending recovery/result delivery. Preserve those obligations durably across restarts and retention; retry delivery, not effects.
• Safe APIs must uphold internal unsafe preconditions. Every unsafe block and trait implementation needs a precise safety argument, not a ceremonial comment. Apply the full Rust safety rules, including Send/Sync evidence, transmute equivalence and the unchanged risk ratchet.

Atomic work

• One authorised goal per complete change. No speculative or unrelated cleanup. Follow the task record and explain changed invariants and rationale; record material AI assistance there, preserving provenance.
• Only maintained workflows/gates or invoked support belong in tracked scripts/. Scratch probes belong in ignored out/scripts/ or temporary storage. Follow script lifecycle rules before promotion.
• Any material behavior, interface, schema, bound, authority, lifecycle, evidence, workflow or performance change requires a complete host-tool, tools/cohesix-py and benchmark compatibility review. Use the generated inventory; record unaffected surfaces, and update all affected implementations, contracts, tests and docs together.

Test Discipline

• Preserve distinct independently known contracts, not test counts. Cover relevant malformed/boundary inputs; never weaken expectations, add arbitrary retries or change truth to obtain PASS. Seek a safe minimal reproducer for defects.
• Match proof to execution: pure tests for pure contracts, host tests for host behavior, QEMU for seL4 VM behavior and fresh Pi evidence for physical behavior. Mocks cannot accept a target. Do not recreate the target in host simulations.
• Apply the complete Test Discipline before changing tests; TEST_PLAN owns commands and acceptance, not those simulations.

Convergence, acceptance, and audit closure

• Use CONTRIBUTING validation for iteration, merge, documentation-only and release obligations. All existing merge baseline, generated-consistency, risk and target gates remain required; relocation is no waiver.
• Non-claiming convergence may stop at the first failed proof layer; it never supplies acceptance. Component/milestone closure requires BUILD_PLAN checks and applicable TEST_PLAN evidence. Staged/release claims require the complete applicable staged, pressure, repeatability, hardware, due-diligence and promotion evidence with exact source/image/target identity. A green health-check CI is not that proof.
• Individual changes, commits, merges and component/milestone acceptance need no human sign-off. Reviews may be agent-led; required independent technical review, safety arguments, tests, evidence and scope/exception controls remain mandatory.
• Only an overall Cohesix release requires explicit approval by a named human release owner before publication or promotion. Approval covers the assembled release’s exact source/artifacts, evidence, limitations and residual risks, not separate approval of every change. AI and automated checks cannot provide it.
• Preserve historical approvals at their original scope; never fabricate approvals or verification. Make evidence accessible and disclose unexecuted or blocked checks.

Task record

Use the unchanged fields in CONTRIBUTING’s task record. Planner, Builder and Auditor are contribution roles; Queen and Workers are system roles. BUILD_PLAN must explicitly introduce any additional role.

Authoritative document map

In addition to the task routes above, consult the relevant owners: SECURITY for trust boundaries; SECURE9P and INTERFACES for protocols; BENCHMARKS for measurement; API_GUIDELINES for public APIs. Read linked contracts when their surface is affected; do not duplicate them here.