# 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 and evidence needed for active claims; apply the retention rules below to older run data. Do not reset, clean, switch branches or overwrite artifacts to simplify a task. 2. Read the relevant [BUILD_PLAN](docs/BUILD_PLAN.md) 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](CONTRIBUTING.md) for atomic changes and validation, and [Coding Guidelines](docs/CODING_GUIDELINES.md) 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. | Work | Required starting points | | --- | --- | | Host tools, Python or UI | [HOST_TOOLS](docs/HOST_TOOLS.md), affected surface contract, focused host checks in [TEST_PLAN](docs/TEST_PLAN.md) | | Root, service or Worker runtime | [ARCHITECTURE](docs/ARCHITECTURE.md), [ROLES_AND_SCHEDULING](docs/ROLES_AND_SCHEDULING.md), exact-profile target convergence | | Drivers, timers, DMA or physical Pi | [DRIVERS](docs/DRIVERS.md), [HARDWARE_BRINGUP](docs/HARDWARE_BRINGUP.md), fresh Pi evidence for physical claims | | Generated contracts or protocols | Selected `configs/root_task*.toml`, resolved manifest, compiler IR and [INTERFACES](docs/INTERFACES.md) | | Docs, policy or overall release | [CONTRIBUTING validation](CONTRIBUTING.md#5-validate-locally), [TEST_PLAN](docs/TEST_PLAN.md); no unrelated Rust build for documentation-only work | ## 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](docs/TOOLCHAIN_MAC_ARM64.md). 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](CONTRIBUTING.md#documentation-and-metadata). 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](docs/USERLAND_AND_CLI.md). 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](docs/CODING_GUIDELINES.md#safety-and-risk-controls), 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](CONTRIBUTING.md#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](CONTRIBUTING.md#script-lifecycle) 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](docs/CODING_GUIDELINES.md#test-discipline) before changing tests; TEST_PLAN owns commands and acceptance, not those simulations. ## Convergence, acceptance, and audit closure - Use [CONTRIBUTING validation](CONTRIBUTING.md#5-validate-locally) 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. ## Artifact retention and disk cleanup - While a test, review or release candidate is active, retain its exact inputs, failed attempts and accepted evidence at the original source, artifact and target identity. Never delete or rewrite data that a current claim needs. - After publication, retain an accessible authoritative release copy, documentation, approvals and a compact record of the final result, limitations and identity hashes. Keep raw captures only when that compact record or a cited claim cannot be checked without them. Historical attempts, duplicate staging trees and copied target artifacts do not need indefinite retention merely because they were generated under `out/` or named `evidence/`. A discarded run cannot be reused for a later claim. - Generated builds, caches, downloaded test models and temporary environments may be removed when idle and reproducible from retained source and manifests. Inspect contents before deleting a broad directory: `out/` can also contain unique records, and a model directory can contain a unique trained adapter. - Use a worktree-specific sparse checkout to omit obsolete tracked build or release copies from an old local checkout. Do not stage their deletion on a historical branch or rewrite Git history merely to reclaim local disk space. - If the sole proof for a published claim is being removed, first replace it with a verifiable compact record or narrow the claim in the owning document. Confirm release files have another retained copy, check for active processes and unrelated changes, and report what was removed and what remains. ## Task record Use the unchanged fields in [CONTRIBUTING's task record](CONTRIBUTING.md#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](docs/SECURITY.md) for trust boundaries; [SECURE9P](docs/SECURE9P.md) and [INTERFACES](docs/INTERFACES.md) for protocols; [BENCHMARKS](docs/BENCHMARKS.md) for measurement; [API_GUIDELINES](docs/API_GUIDELINES.md) for public APIs. Read linked contracts when their surface is affected; do not duplicate them here.