AGENTS.md · diff

git:20260927.3f3d4f6 to git:20261026.58a7444

27 added, 2 removed. Audit A to A.

# 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.

+ 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.