artifact-store/workplans/ARTIFACT-STORE-WP-0005-guide-board-pilot.md

id, type, title, repo, domain, status, owner, topic_slug, planning_priority, planning_order, created, updated

id	type	title	repo	domain	status	owner	topic_slug	planning_priority	planning_order	created	updated
ARTIFACT-STORE-WP-0005	workplan	Guide-Board Pilot Ingestion	artifact-store	stack	planned	codex	stack	high	5	2026-05-15	2026-05-15

ARTIFACT-STORE-WP-0005: Guide-Board Pilot Ingestion

Purpose

Wire the first real producer end-to-end. A guide-board CMIS assessment run directory is registered as one artifact package, its files are stored through a configured backend, retention is applied, and Statehub records a stable package id and summary without storing bytes itself. This is the pilot success criterion in INTENT.md.

Constraints

• WP-0001 — WP-0004 must be done.
• docs/ARCHITECTURE-BLUEPRINT.md guide-board manifest fields.
• No guide-board-specific code lives in artifactstore.registry; pilot-specific glue lives in artifactstore.pilots.guide_board or in a separate small package.

Prerequisites

• WP-0001, WP-0002, WP-0003 done. WP-0004 only required for the production target; local FS is sufficient for the pilot test.

D5.1 - Pilot Metadata Schema Registration

id: ARTIFACT-STORE-WP-0005-T001
status: todo
priority: high
state_hub_task_id: "eb822821-353c-4cd2-95bf-acb2f084b7ea"

Acceptance:

• A JSON Schema for guide-board.run.v1 package metadata is checked in under schemas/guide-board.run.v1.json.
• A bootstrap script registers it via POST /metadata-schemas (an endpoint added in this workplan).
• Required keys: run_id, target_profile_ref, assessment_profile_ref, result_status, source_commits (object of slug → SHA), report_paths, evidence_counts, finding_counts.

D5.2 - Pilot Ingest Helper (CLI + Library Function)

id: ARTIFACT-STORE-WP-0005-T002
status: todo
priority: high

Acceptance:

• artifactstore guide-board ingest <run-dir> walks a guide-board run directory, builds the package metadata from run.json and retention-summary.json, uploads every file declared in the assessment package manifest (and the manifest itself), and finalises the package.
• Library entry point pilots.guide_board.ingest_run(path, ...) exposes the same behaviour for embedding.
• Output: the package id (UUID) and the package manifest digest (blake3:<hex>).

D5.3 - Fixture-Based Test

id: ARTIFACT-STORE-WP-0005-T003
status: todo
priority: high

Acceptance:

• A trimmed-down guide-board run fixture (under 1 MB total) lives in tests/fixtures/guide-board/ with realistic file shapes: run.json, retention-summary.json, reports/assessment-package.json, reports/report.md, one scorecard, one log-review summary, and a couple of raw artifact files.
• The test runs the CLI / library helper end-to-end against an in-memory SQLite + tempdir local backend, then verifies:
  1. package id returned,
  2. manifest digest stable across two runs of the same fixture,
  3. every file downloadable with correct bytes,
  4. retention class applied as configured.

D5.4 - Statehub Linkage Recipe

id: ARTIFACT-STORE-WP-0005-T004
status: todo
priority: medium

Acceptance:

• docs/OPERATOR.md (or a new docs/pilots/guide-board.md) documents the exact POST /progress/ or record_decision call shape Statehub clients should use to link a guide-board run to its artifact-store package id and manifest digest.
• A reference Statehub client snippet is checked in, parameterised by env vars.

D5.5 - Operator Smoke Procedure For The Real Producer

id: ARTIFACT-STORE-WP-0005-T005
status: todo
priority: medium

Acceptance:

• A documented procedure ingests a real (non-fixture) guide-board run produced from ~/guide-board / ~/open-cmis-tck.
• Procedure includes: starting make dev, registering the schema, running the ingest CLI, verifying the manifest, and recording the package id in Statehub.
• Procedure runs end-to-end on a developer workstation under 5 minutes.

Success criteria

• A real guide-board CMIS run is ingested with one CLI invocation.
• The package manifest lists every stored file with both digests and the canonical CBOR digest of the manifest itself.
• Statehub records the package id and summary; no artifact bytes live in Statehub.
• Retention can be extended on the package without touching bytes.
• The pilot path validates the storage adapter swap: the same command works against local and against s3 (if WP-0004 done).