hemx/AGENTS.md

AGENTS.md

Authority and workflow

Repository-root INTENT.tsv and SPEC.tsv are the sole product authorities. INTENT.tsv owns PROBLEM, FOR, and OUTCOME; SPEC.tsv owns falsifiable RULE records and their INTENTS edges. Code, tests, runtime observations, public documentation, handoff.md, and history are evidence, not parallel canon. Durable behavior changes update the canonical TSV first. PLAN.md is the disposable current execution surface.

Use # intent: <id> <role> and # spec: <id> <role> with the Redgate roles impl, check, doc, and exception. Put check only on the local executable assertion or focused command that would fail for that rule. Other roles provide traceability but do not satisfy redgate check; exceptions expose debt and never make strict checks pass. Feed findings back into authority, implementation, or proof rather than weakening checks.

Run redgate list, redgate refs, redgate lint, and redgate check before completion. Broad or risky completion claims also require an independent fresh-context conformance review after deterministic checks pass.

Final handoffs include INTENT IMPACT and SPECIFICATION IMPACT: changed IDs, proof, and any unresolved gap.

Workspace ownership

The public core consists of seven packages:

hemx-core
hemx-derive
hemx-js
hemx-build
hemx-axum
hemx
hemx-test

hemx-core owns effects, typed resources, wire encoding, and fingerprints. hemx-build inspects Hemplate templates and emits generated resource metadata. hemx-derive owns macros. hemx-js owns the generic browser runtime. hemx-axum owns Axum transport. hemx is the facade. hemx-test owns public testing utilities.

Server-side Wasm uses normal hemx and the portable Hemplate runtime. Host parser and Tree-sitter dependencies must not enter its target normal dependency graph.

The public GitHub mirror is release output. Keep INTENT.tsv, SPEC.tsv, PLAN.md, .redgate/, requirement checks, and private workflow text out of it while preserving the tested product tree. Experimental browser-local host, Wasm, and synchronization work belongs in the separate private Labs repository and must not be copied into this core.

Required proof

Run the narrowest relevant test while editing. Before completion run:

redgate list
redgate refs
redgate lint
redgate check
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
cargo deny check licenses sources
cargo check -p hemx-server-wasm-test --target wasm32-unknown-unknown
cargo tree -p hemx-server-wasm-test --target wasm32-unknown-unknown --edges normal,no-proc-macro

The target tree must contain neither tree-sitter nor hemplate-parser. Publishable package changes also require archive-based cargo package --list and cargo package checks for all seven packages.

Product constraints

• The server owns effects and behavior; generated typed resources connect templates to handlers and effects.
• Raw HTML remains explicit and typed.
• Canonical wire bytes and ABI compatibility remain deterministic.
• Framework behavior stays in hemx-axum; browser runtime behavior stays in hemx-js.
• Public docs change with APIs, package boundaries, or compatibility.
• Preserve licenses; do not commit archives, target/, coverage, fuzz, mutation, local editor, or private governance output to the public mirror.