shallguard 0.1.2

ShallGuard requirement traceability, executable coverage, and review tooling
Documentation
# ShallGuard in Rust

This file completes `SKILL.md` for a Rust repository. Read `SKILL.md`
first. This file gives the command, the anchor syntax, and the rules that
exist only in Rust.

## The command

The command is `cargo shallguard <command>`. Where `SKILL.md` writes
`shallguard check`, run `cargo shallguard check`.

Install the command with the same version as the `shallguard` crate that
the repository pins:

```bash
cargo install cargo-shallguard --version <pinned-version> --locked
```

When the pinned version changes, run `cargo shallguard install-skill`
after the install. It replaces this skill with the skill of that release.

The command finds the repository with `cargo metadata`. It supports a
single package and a virtual Cargo workspace. In a virtual workspace, set
`source_root` of each document to the directory of the package that owns
the document. ShallGuard scans `src/` and `tests/` below every source root
and every prefix.

Add the `shallguard` crate as a dependency only to the crates that carry
anchors. The crate exports the anchor macros. You do not need a direct
dependency on the macro crate.

## Anchor syntax

- **Enforcement anchor.** The attribute `#[shallguard::enforces("REQ-X-NNN")]`
  on an item: a function, a struct, an enum, a const, or a static. The
  statement macro `shallguard::enforces_here!("REQ-X-NNN")` inside a block.
- **Verification anchor.** The attribute
  `#[shallguard::verifies("REQ-X-NNN", ...)]` on a test function.

Only these forms are anchors. A `REQ-...` string in a comment, in a doc
comment, or in a string literal is not an anchor.

## Rules that exist only in Rust

- **Field and variant anchors.** A struct field or an enum variant can carry
  `#[enforces("...")]`. This works only if the struct or enum itself carries
  `#[enforces]` as its **first** attribute, above any `#[derive]`. The
  container attribute can be bare or can list IDs. The container attribute
  removes the field-level anchors before the derives see them. A wrong order
  breaks the compilation.
- Use `enforces_here!("REQ-X-NNN")` for a branch, a match arm, or a sequence
  of statements. An attribute cannot reach these places. Put the macro as
  the first statement inside the block. If a match arm is a bare expression,
  wrap it in `{ }`. The macro expands to nothing.
- `#[verifies("REQ-X-NNN", ...)]` is valid only on a function with a
  recognized test attribute: `#[test]`, `#[tokio::test]`, or any attribute
  whose name ends in `test`, for example `#[my_harness::container_test]`.
  It **rejects a test with `#[ignore]`** at compile time and in the check.
- The compiler validates the format of each anchor ID. A typo like
  `REQ-HSR-002` is a compile error. The command `cargo build` is a cheap
  first sanity check.
- The citation in a `*Verified:*` line names the test file and the test
  function, for example:

  ```markdown
  *Verified:* [test] `cli:tests/session.rs` (`rejects_expired_token`)
  ```

## Comments next to anchors

There are three placements. Use one, or use the first together with the
second or the third.

**A block before the anchor.** Use it for the summary of what the item
guarantees. In a doc comment, the empty line that separates the block from
an existing comment is a line with only `///`. In a line comment, it is an
empty source line.

```rust
/// Registration of a new provider.
/// Checks for duplicates to prevent tracking corruption.
///
/// Requirements:
/// The first registration makes an eligible target `Ok`. The health
/// fact and the quality timing do not change.
#[enforces("REQ-OP-066")]
pub fn register_provider(&mut self, provider_id: ProviderId) {
```

```rust
if has_prefix {
    // The provider is ready and has a free prefix.

    // Requirements:
    // Registration is the provider-presence fact behind the operational
    // state. Health is left to the quality handlers.
    enforces_here!("REQ-OP-066");
    target.register_provider(provider_id);
}
```

**A comment after an ID inside the attribute.** Use it when an anchor
claims several requirements and each ID has its own one-line reason. Put
a comma after the last ID when a comment follows it.

**A comment above a group of IDs inside the attribute.** Use it when one
reason covers several IDs. Both forms can mix in one attribute. Only `//`
and `/* */` comments are valid inside an attribute. A `///` line inside
an attribute is a compile error. The compiler removes the comments before
the macro reads the IDs, and `rustfmt` keeps them.

```rust
#[enforces(
    // Weighted split that converges per goal and reacts to receivers
    // appearing, disappearing, and goal changes.
    "REQ-CR-008",
    "REQ-CR-009",
    // Batched per cycle. A move never drops a downstream connection.
    "REQ-OP-004",
    "REQ-EH-016", // the cap damps cascade patterns across targets
)]
pub fn get_patch(&mut self, configuration: &OptimizerConfiguration) -> Patch {
```

## Tools of the analysis pipeline

- The `coverage` command needs the tool `cargo-llvm-cov`.
- The `review` command needs the provider program: `codex`, `claude`, or
  `copilot`. The provider login and the data handling of the provider are
  outside ShallGuard.