Feat/06 inventory cli skeleton

.agents/rules/code-style.md

@@ -0,0 +1,24 @@
+## Code Style Rules
+
+These are enforced by `rustfmt` and Clippy — do not fight them:
+
+- **Formatting**: `cargo fmt` defaults (4 spaces, 100-column soft width).
+  Run `cargo fmt --check` before committing.
+- **Lints**: `cargo clippy --all-targets -- -D warnings` must be clean. Fix
+  lints — do not suppress them without a strong, documented reason.
+- **File length**: keep source files cohesive and modular (target `<= 500
+  LOC` per file); extract helpers or modules when approaching the limit.
+- **Module boundaries**: keep them tidy — the single crate splits into
+  `crates/` when `record` lands, so code that will move together should
+  already live together.
+- **No dead code**: remove it or gate it behind the ticket that needs it.
+  No commented-out code blocks and no leftover debug output.
+
+Forbidden patterns:
+
+- No redundant comments that restate the code
+- No `todo!`/`unimplemented!` in merged code unless the tracking ticket is
+  named next to it
+- No `panic!`/`unwrap!`/`expect!` on production paths that handle external
+  input — return a diagnostic and exit non-zero instead (`expect` is fine
+  in tests and for truly invariant serialization)

.agents/rules/development-commands.md

@@ -0,0 +1,29 @@
+## Development Commands
+
+Run all commands from the **repo root** unless otherwise specified.
+
+```bash
+# Check formatting (must pass)
+cargo fmt --check
+
+# Lint with warnings denied (must pass)
+cargo clippy --all-targets -- -D warnings
+
+# Run the full test suite (must pass)
+cargo test
+
+# Run a single test by name
+cargo test <name>
+
+# Build the binary
+cargo build
+
+# Run inventory against the current directory
+cargo run -- inventory
+
+# Run inventory against another manifest
+cargo run -- inventory --manifest-path <path/to/Cargo.toml>
+```
+
+The installed binary is named `cargo-buildtrace`, so `cargo buildtrace
+inventory` works once it is on `PATH`.

.agents/rules/git-conventions.md

@@ -0,0 +1,45 @@
+## Git Conventions
+
+- Branch naming: `feat/<short-description>`, `fix/<short-description>`,
+  `chore/<short-description>`. When working a tracker ticket, prefix the
+  ticket number: `feat/06-inventory-cli-skeleton`.
+- Work on short-lived branches, one ticket per branch. Merge to `main` when
+  the gates pass. Tiny doc or chore commits may go direct to `main`.
+- Local-only files (`plan.md`, `CONTEXT.md`, `docs/adr/`, `docs/agents/`,
+  `.scratch/`) are gitignored — never force-add them.
+- Never commit secrets, API keys, `.env` files, or `target/` output.
+
+### Commit Messages
+
+Commits use the Conventional Commits format unless the user asks otherwise:
+
+```text
+type: subject
+type(scope): subject
+```
+
+Rules:
+
+- Keep the commit type lowercase: `feat`, `fix`, `chore`, `refactor`,
+  `docs`, `style`, `test`, `perf`, `ci`, `build`, `revert`
+- Write a short subject after the colon, imperative mood, under 100 characters
+- Use the body to explain what changed and why when helpful
+- Reference the local tracker ticket in the body, e.g.
+  `.scratch/v0-0-1-minimal-release/issues/06-inventory-cli-skeleton.md`
+
+Type guide:
+
+- `feat` - a new feature is introduced with the changes
+- `fix` - a bug fix has occurred
+- `chore` - changes that do not relate to a fix or feature and do not modify
+  `src` or test files
+- `refactor` - refactored code that neither fixes a bug nor adds a feature
+- `docs` - updates to documentation such as the `README` or other markdown
+  files
+- `style` - changes that do not affect the meaning of the code, usually
+  formatting-related
+- `test` - including new tests or correcting previous tests
+- `perf` - performance improvements
+- `ci` - continuous integration related changes
+- `build` - changes that affect the build system or external dependencies
+- `revert` - reverts a previous commit

.agents/rules/technology-stack.md

@@ -0,0 +1,13 @@
+## Technology Stack
+
+| Layer | Technology |
+|---|---|
+| Language | Rust, edition 2024 |
+| CLI | `clap` (derive) — binary name `cargo-buildtrace` so `cargo buildtrace` dispatch works |
+| Serialization | `serde` + `serde_json` |
+| Cargo metadata | `cargo_metadata` (metadata only — never execute dependency code) |
+| Formatter | `rustfmt` via `cargo fmt` |
+| Linter | Clippy via `cargo clippy -- -D warnings` |
+| Testing | `cargo test` (in-module units, `tests/` integration, snapshots) |
+| CI | GitHub Actions (`validate.yml`: fmt, clippy, build, test) |
+| Platform | Linux-first; `inventory` itself stays portable (no `ptrace` in v0.0.1) |

.agents/rules/testing.md

@@ -0,0 +1,15 @@
+## Testing
+
+- Unit tests are **mandatory** for every feature. They live in-module under
+  `#[cfg(test)]` and go through the highest seam possible (the inventory
+  function over a manifest path, not internals).
+- Integration tests live in `tests/` and drive the built binary against
+  self-contained path-only fixture workspaces: one with a build script, one
+  with a proc macro, one with neither.
+- Snapshot tests pin the human table and JSON report output.
+- Required coverage per feature: the no-execution guarantee (running
+  inventory leaves no build artifacts from dependency code) and determinism
+  (repeated runs are byte-identical).
+- No real network endpoints in any test, ever.
+- `cargo test` must pass with no special privileges before a task counts as
+  done.

AGENTS.md

@@ -9,3 +9,22 @@ Issues are tracked locally as Markdown files under `.scratch/`. See `docs/agents
 ### Domain docs
 
 This is a single-context repository using `CONTEXT.md` and `docs/adr/`. See `docs/agents/domain.md`.
+
+## Guidelines
+
+BuildTrace is a Linux-first Cargo build capability recorder and policy-diff tool.
+
+- **Facts over assumptions**: inspect source code and verify contracts directly. Do not rely on unverified assumptions.
+- **Layout**: single `buildtrace` crate now; split into `crates/` when `record` lands. Keep module boundaries tidy so the split stays mechanical.
+- **Gates**: `cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test` must pass before a task counts as done.
+- **Local-only files**: `plan.md`, `CONTEXT.md`, `docs/adr/`, `docs/agents/`, and `.scratch/` stay untracked. Never commit them.
+- **Clean git hygiene**: never commit secrets, API keys, `.env` files, or gitignored build output.
+
+## Workspace Rules
+
+- [Development commands](./.agents/rules/development-commands.md)
+- [Git conventions](./.agents/rules/git-conventions.md)
+- [Testing](./.agents/rules/testing.md)
+- [Code style](./.agents/rules/code-style.md)
+- [Technology stack](./.agents/rules/technology-stack.md)
+