guide-board/workplans/GUIDE-BOARD-WP-0002-assessment-operations-baseline.md

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

id	type	title	repo	domain	status	owner	planning_priority	planning_order	created	updated	state_hub_workstream_id
GUIDE-BOARD-WP-0002	workplan	Assessment Operations Baseline	guide-board	markitect	completed	codex	high	2	2026-05-15	2026-05-15	fc5b1573-91b2-4a19-b6a9-dd4d17057d9b

GUIDE-BOARD-WP-0002: Assessment Operations Baseline

Purpose

Turn the bootstrapped framework into an operator-ready assessment tool. The next layer should make it obvious how a candidate software repository or operator starts an assessment, follows status, retrieves results, and packages evidence without needing to understand guide-board internals.

Background

GUIDE-BOARD-WP-0001 established the core contracts: schemas, extension discovery, profile validation, planning, execution, service transport, container baseline, retention summaries, and the first external extension path with open-cmis-tck.

The next gap is operational clarity. A user should be able to start from a candidate system and know:

• what target and assessment profiles are required,
• which command or HTTP endpoint starts the run,
• how status differs between service jobs and assessment outcomes,
• where reports, normalized evidence, raw artifacts, and retention summaries are written,
• what a candidate repository should document when it wants to be assessed.

Boundary

This workplan owns generic guide-board assessment operation. It may reference open-cmis-tck as a concrete example, but CMIS-specific harness behavior, target profiles, and runtime dependencies remain owned by the external open-cmis-tck extension repository.

D2.1 - Assessment Operations Runbook

id: GUIDE-BOARD-WP-0002-T001
status: done
priority: high
state_hub_task_id: "4592bb4f-096a-49e4-8785-06f9c3f619ac"

Acceptance:

• Add a generic operator document for CLI and local service assessment flows.
• Document start, status, report retrieval, output directories, and result states.
• Include the external-extension shape without making CMIS the root product.
• Link the runbook from README.

Progress:

• Added docs/ASSESSMENT-OPERATIONS.md.
• Linked the runbook from README.

D2.2 - Candidate Repository Handoff Contract

id: GUIDE-BOARD-WP-0002-T002
status: done
priority: high
state_hub_task_id: "7d1df7d0-49cd-487f-a507-9e558a90af31"

Acceptance:

• Define the minimal instruction file a candidate repository should provide when it wants guide-board assessment support.
• Cover required endpoint/profile facts, credential references, startup command, expected runtime state, and where candidate-specific results should be referenced.
• Provide a template that candidate repos can copy without importing guide-board internals.

Progress:

• Added docs/CANDIDATE-HANDOFF.md.
• Added docs/templates/CANDIDATE-ASSESSMENT-HANDOFF.md.
• Linked the handoff contract from README and the assessment operations guide.

D2.3 - Run History And Result UX

id: GUIDE-BOARD-WP-0002-T003
status: done
priority: medium
state_hub_task_id: "ce18a2dc-7cc9-4fff-9272-5333b6118030"

Acceptance:

• Make it easy to find the latest run for a target and assessment pair.
• Document or add commands for listing run reports and opening the latest report paths.
• Preserve the existing run directory contract and retention summary model.

Progress:

• Added guide_board.retention.select_retained_run.
• Added guide_board.retention.retained_run_report_paths.
• Added guide-board runs latest and guide-board runs report.
• Documented the new commands in docs/ASSESSMENT-OPERATIONS.md.

D2.4 - Service Job Durability Contract

id: GUIDE-BOARD-WP-0002-T004
status: done
priority: medium
state_hub_task_id: "10e4003c-dc11-4a8e-aecc-7815559ac439"

Acceptance:

• Decide whether local service job state remains intentionally in-memory or gains a small durable index.
• If in-memory remains the baseline, document restart semantics and the durable fallback through run directories.
• If durable indexing is added, keep it dependency-light and reconstructable from retained run artifacts.

Decision:

• Keep local service job state intentionally in-memory for the baseline.
• Treat run directories and retention-summary.json as the durable recovery source.

Progress:

• Added docs/SERVICE-JOB-DURABILITY.md.
• Linked the contract from README, the local service API docs, and the assessment operations guide.

D2.5 - Container Smoke Acceptance

id: GUIDE-BOARD-WP-0002-T005
status: done
priority: medium
state_hub_task_id: "9e2e7fa7-8a97-4f07-9925-e637e0366003"

Acceptance:

• Add or document a reproducible container smoke check for the bundled sample assessment.
• Verify mounted output directories receive run artifacts.
• Keep restricted or extension-specific harness assets outside the core image.

Progress:

• Added scripts/container_smoke.sh.
• Documented the smoke check in docs/CONTAINER.md.
• Verified the smoke check with Docker; mounted outputs received run metadata, normalized evidence, mappings, findings, assessment package, and Markdown report.

D2.6 - External Extension Acceptance Path

id: GUIDE-BOARD-WP-0002-T006
status: done
priority: high
state_hub_task_id: "65fbf1df-caef-40f6-abee-8308daf27fbc"

Acceptance:

• Define a repeatable acceptance path for an external extension repository.
• Use open-cmis-tck as the first example without moving CMIS-specific logic back into the core.
• Cover extension validation, target/assessment profile validation, plan generation, run execution, and result review.

Progress:

• Added docs/EXTERNAL-EXTENSION-ACCEPTANCE.md.
• Added scripts/external_extension_acceptance.sh.
• Verified open-cmis-tck extension validation, profile validation, and plan generation in scripted plan mode.

Definition Of Done

• The repo has a clear assessment operations guide.
• Candidate repositories know what handoff information to provide.
• Operators can start runs, inspect status, and retrieve results through CLI or local service.
• The service and container baselines have documented operational limits.
• The next external extension acceptance workflow is repeatable.