tmk241
60 lines
3.4 KiB
Markdown
60 lines
3.4 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```console
|
|
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.
|