feat: establish sbom nexus extraction slice

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a028f0-a42f-7582-89a8-ebaad7343834

AGENTS.md

@@ -0,0 +1,66 @@
+# 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
+```
+
+## 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.