# SBOM Nexus — Agent Instructions

## Repository identity

**Purpose:** Dedicated SBOM capture, history, evaluation, and bounded catch-up service.

**Domain:** infotech

**Repo slug:** sbom-nexus

**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`

**Workplan prefix:** `SBOM-WP-`

Read `INTENT.md`, `SCOPE.md`, and `ProductRequirementsDocument.md` before
changing product or ownership boundaries. Repository/build evidence is scan
input; SBOM Nexus is authoritative for normalized snapshot history and
freshness evaluation.

## State Hub integration

Use the REST API at `http://127.0.0.1:8000` (remote tunnel `:18000`) for
coordination. The canonical health endpoint is `/state/health`. If loopback is
blocked by a sandbox, retry with approved elevated network access before
declaring it unavailable.

At session start:

```bash
cat .custodian-brief.md
curl -s 'http://127.0.0.1:8000/messages/?to_agent=sbom-nexus&unread_only=true'
ls workplans/
```

At session close, update file-backed task states, run `statehub
fix-consistency`, and record a progress event. Workplan files are authority;
State Hub is a replaceable projection.

## Commands

```bash
uv sync --dev
uv run pytest
uv run ruff check src tests
uv run sbom-nexus scan .
uv run sbom-nexus serve --reload
make migrate
```

## Architecture constraints

- Keep scanner/parsers independent of HTTP and persistence.
- Every ingest attempt creates an immutable snapshot with an explicit outcome.
- Store both last-attempt and last-success timestamps; do not overload success.
- Preserve the legacy State Hub API only through tested compatibility handlers.
- Catch-up must be deterministic and bounded to 1..25 targets.
- Do not turn simple licence substring matching into an unqualified legal claim.
- Do not add repository control or recurrence here; integrate with Repo Manager
  and Activity Core.
- Never store credentials in repository files, snapshots, logs, or workplans.

## Workplan convention

Workplans live at `workplans/SBOM-WP-NNNN-<slug>.md`. Status values are
`proposed | ready | active | blocked | backlog | finished | archived`; task
status values are `wait | todo | progress | done | cancel`. Before finishing a
workplan, turn actionable residuals into a follow-up workplan or intake.