| name | trust-architecture-automation |
| description | Use when adding, installing, running, or reviewing automated architecture mapping and bug-finding tools in trust-platform, including architecture-doctor, generated software maps, diagram claim checks, cargo-deny/audit/machete/geiger/coverage/mutation/fuzz/Miri/sanitizer/perf gates, and CI evidence for architectural drift. |
trust-platform Architecture Automation
Use this skill for work that must replace hand-checked architecture claims with automated evidence.
Use trust-test-authoring first whenever the automation change adds or changes a gate, test,
mutation/fuzz claim, or proof-bearing behavior.
Required posture
- Treat source-derived facts as truth; treat diagrams as views that must be checked.
- Do not trust a
.puml claim unless it is generated from or verified against code facts.
- Prefer repo-specific doctor checks for project semantics; generic tools only supply raw facts.
- If a tool cannot be installed or run, record the exact blocker and the fallback.
- In trust-platform checkouts on a Raspberry Pi or other slow local host, use the remote builder for broad/full validation first, especially
just test-all.
- Ask before starting expensive local commands such as workspace
cargo test, cargo test -p trust-runtime ..., local just test, local just clippy, local just test-all, or heavy architecture/perf tools.
- Cheap local checks are allowed when narrowly scoped, for example formatting, small touched-crate tests,
cargo test -p xtask, architecture-doctor checks for the touched area, and static inspections.
Standard workflow
- Read
docs/internal/testing/checklists/architecture-automation-tooling.md.
- For every new doctor/gate behavior, bug fix, or intentional behavior change, add the smallest focused self-test or known-bad fixture first and run it to the expected behavior assertion failure. Implement only the minimum change, then rerun the same test until green; harness, dependency, timeout, and unrelated failures do not count as red evidence.
- For architecture changes, generate or update the software map before reviewing diagrams.
- Run the architecture doctor for the touched area before declaring implementation complete.
- Regenerate diagrams only after factual checks pass.
- Run the relevant static/test/perf tools and record the focused red-green evidence plus broader evidence.
Tool groups
- Code map:
cargo metadata, guppy, cargo tree, cargo-modules, rustdoc JSON, ra_ap_syntax, ast-grep, tree-sitter, and cargo-call-stack where it applies.
- Doctor checks: repo-specific
cargo xtask architecture-doctor, Semgrep/Dylint for simple forbidden patterns.
- Static/supply chain:
cargo deny, cargo audit, cargo machete, cargo udeps, cargo geiger, cargo about, cargo semver-checks, cargo public-api.
- Test adequacy:
cargo nextest, cargo llvm-cov, cargo mutants, cargo fuzz, property tests.
- Deep bug checks: Miri, sanitizers, loom, Valgrind/rr when relevant.
- Perf/size: Criterion,
trust-runtime bench, cargo bloat, cargo llvm-lines, cargo build --timings, flamegraph/perf.
Minimum acceptance for architecture-sensitive work
- A generated/checkable fact exists for each claim that previously drifted.
- The architecture doctor fails on the known-bad pattern before the fix and passes after.
- Diagrams pass both render drift and semantic claim checks.
- Any skipped tool has a documented reason and a follow-up item.
Issue #51 class of checks
For initializer/parser/HIR/runtime work, the doctor must check:
parse_var_initializer call sites are limited to initializer-aware contexts.- HIR owns source initializer metadata and never stores runtime
Value.
- Runtime owns lowered initializer records and materializes through the initializer service.
- VM local/static initializer behavior stays symmetric with normal runtime startup.
- Cross-project imports translate initializer IDs instead of dropping defaults.
- No
_initializer discard or default_initializer: None regression silently reappears.
