sbom-nexus/AGENTS.md

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:

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

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.