Add candidate assessment handoff contract

.custodian-brief.md

@@ -1,17 +1,16 @@
 <!-- custodian-brief: generated by fix-consistency — do not edit manually -->
 # Custodian Brief — guide-board
 
-**Domain:** markitect  
+**Domain:** markitect
-**Last synced:** 2026-05-15 10:28 UTC  
+**Last synced:** 2026-05-15 11:30 UTC
 **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
 
 ## Active Workstreams
 
 ### Assessment Operations Baseline
-Progress: 1/6 done  |  workstream_id: `fc5b1573-91b2-4a19-b6a9-dd4d17057d9b`
+Progress: 2/6 done  |  workstream_id: `fc5b1573-91b2-4a19-b6a9-dd4d17057d9b`
 
 **Open tasks:**
-- · D2.2 - Candidate Repository Handoff Contract  `7d1df7d0`
 - · D2.3 - Run History And Result UX  `ce18a2dc`
 - · D2.4 - Service Job Durability Contract  `10e4003c`
 - · D2.5 - Container Smoke Acceptance  `9e2e7fa7`

README.md

@@ -51,6 +51,7 @@ See:
 - [INTENT.md](INTENT.md)
 - [docs/ARCHITECTURE-BLUEPRINT.md](docs/ARCHITECTURE-BLUEPRINT.md)
 - [docs/ASSESSMENT-OPERATIONS.md](docs/ASSESSMENT-OPERATIONS.md)
+- [docs/CANDIDATE-HANDOFF.md](docs/CANDIDATE-HANDOFF.md)
 - [docs/COMPLIANCE-EVIDENCE-PACKS.md](docs/COMPLIANCE-EVIDENCE-PACKS.md)
 - [docs/CONTAINER.md](docs/CONTAINER.md)
 - [docs/EXTENSION-SDK.md](docs/EXTENSION-SDK.md)

docs/ASSESSMENT-OPERATIONS.md

@@ -191,3 +191,5 @@ Before starting a run against candidate software, confirm:
 
 Candidate repositories should provide their own short handoff document with the
 startup command, profile path, required credentials, and expected endpoint URL.
+See `docs/CANDIDATE-HANDOFF.md` and
+`docs/templates/CANDIDATE-ASSESSMENT-HANDOFF.md` for the reusable contract.

docs/CANDIDATE-HANDOFF.md

@@ -0,0 +1,148 @@
+# Candidate Repository Handoff
+
+Status: draft
+Created: 2026-05-15
+
+## Purpose
+
+A candidate repository should provide one small handoff document when it wants a
+guide-board assessment. The handoff gives an operator the candidate-side facts
+needed to start the software, select the right guide-board profiles, supply
+credentials safely, and find candidate-specific result references.
+
+The handoff is intentionally not a guide-board internals document. It should be
+copyable into any candidate repository and understandable by someone who only
+knows how to run the candidate software.
+
+## Recommended File
+
+Use this path in the candidate repository:
+
+```text
+docs/guide-board-assessment.md
+```
+
+If the repository already has an assessment or operations documentation
+convention, keep that convention and link the guide-board handoff from the
+README.
+
+## Required Sections
+
+### Assessment Intent
+
+State which capability, standard, framework, or conformance profile is being
+prepared for assessment. Avoid certification claims unless they come from an
+official authority.
+
+Include:
+
+- candidate software name,
+- assessment purpose,
+- supported environment,
+- non-goals and known gaps.
+
+### Candidate Startup
+
+Give the exact command or service procedure needed to put the candidate into
+the expected runtime state.
+
+Include:
+
+- working directory,
+- install or environment setup command,
+- service start command,
+- health or readiness check,
+- required seeded data,
+- cleanup command if the assessment mutates state.
+
+### Assessment Endpoint Or Artifact
+
+Identify what guide-board should assess.
+
+For service assessments, include:
+
+- endpoint URL,
+- binding or protocol,
+- expected HTTP status or readiness response,
+- required headers,
+- whether the endpoint is read-only or mutation-safe.
+
+For repository or file assessments, include:
+
+- artifact path,
+- expected format,
+- generation command,
+- freshness expectation.
+
+### Guide-Board Profiles
+
+Name the target and assessment profile paths. Profiles may live in the
+candidate repo, the guide-board repo, or an extension repo.
+
+Include:
+
+- target profile path,
+- assessment profile path,
+- required extension repositories,
+- output directory recommendation,
+- check groups that are safe for normal runs,
+- check groups that need explicit human approval.
+
+### Credentials And Secrets
+
+Do not place secrets in the handoff or in committed profiles. Use references
+such as environment variables, local files outside version control, or mounted
+secret paths.
+
+Include:
+
+- credential reference names,
+- who owns the credential,
+- minimum permission needed,
+- rotation or cleanup notes,
+- redaction expectations for retained artifacts.
+
+### Expected Runtime State
+
+Describe the state the candidate must be in before the run starts.
+
+Include:
+
+- database or fixture state,
+- background workers or dependent services,
+- network assumptions,
+- destructive-operation safeguards,
+- known unsupported behavior that should be treated as expected gaps.
+
+### Run And Result Commands
+
+Provide the candidate-specific guide-board command or service payload.
+
+Include:
+
+- CLI command or local service `POST /runs` payload,
+- status check command,
+- report retrieval command,
+- expected output directory,
+- result files that should be reviewed first.
+
+### Result Handling
+
+State where candidate-specific results are tracked after a run.
+
+Include:
+
+- issue tracker or workplan mapping,
+- where to attach report links or summaries,
+- which failures are candidate bugs,
+- which failures are harness, environment, or known-gap outcomes,
+- retention expectations for raw artifacts.
+
+## Template
+
+Copy `docs/templates/CANDIDATE-ASSESSMENT-HANDOFF.md` into the candidate
+repository and replace the placeholders.
+
+The template is deliberately plain Markdown. Candidate repositories do not need
+to import guide-board code, schemas, or generated files to provide a useful
+handoff.

docs/templates/CANDIDATE-ASSESSMENT-HANDOFF.md

@@ -0,0 +1,147 @@
+# Guide-Board Assessment Handoff
+
+Status: draft
+Updated: YYYY-MM-DD
+
+## Assessment Intent
+
+- Candidate software:
+- Assessment purpose:
+- Framework or extension:
+- Environment:
+- Non-goals:
+- Known gaps:
+
+## Candidate Startup
+
+Working directory:
+
+```sh
+cd /path/to/candidate
+```
+
+Install or prepare:
+
+```sh
+# command here
+```
+
+Start service or generate artifact:
+
+```sh
+# command here
+```
+
+Readiness check:
+
+```sh
+# command here
+```
+
+Cleanup:
+
+```sh
+# command here, if needed
+```
+
+## Assessment Endpoint Or Artifact
+
+- Kind: service endpoint | repository | file artifact | other
+- URL or path:
+- Protocol or binding:
+- Expected readiness response:
+- Mutation safety:
+- Required headers:
+
+## Guide-Board Profiles
+
+- Guide-board repository:
+- Extension repositories:
+- Target profile:
+- Assessment profile:
+- Recommended output directory:
+- Normal check groups:
+- Approval-required check groups:
+
+## Credentials And Secrets
+
+- Credential reference:
+- Credential owner:
+- Minimum permission:
+- Secret location:
+- Rotation or cleanup:
+- Artifact redaction notes:
+
+## Expected Runtime State
+
+- Required seeded data:
+- Required dependent services:
+- Network assumptions:
+- Destructive-operation safeguards:
+- Expected known gaps:
+
+## CLI Run
+
+```sh
+cd /path/to/guide-board
+PYTHONPATH=src python3 -m guide_board \
+  --extension-dir /path/to/extension \
+  run \
+  --target /path/to/target-profile.json \
+  --assessment /path/to/assessment-profile.json \
+  --output-dir /path/to/output-dir
+```
+
+## Local Service Run
+
+Start guide-board service:
+
+```sh
+cd /path/to/guide-board
+PYTHONPATH=src python3 -m guide_board \
+  --extension-dir /path/to/extension \
+  serve --host 127.0.0.1 --port 8080
+```
+
+Start assessment:
+
+```sh
+curl -sf -X POST http://127.0.0.1:8080/runs \
+  -H "Content-Type: application/json" \
+  -d '{
+    "target": "/path/to/target-profile.json",
+    "assessment": "/path/to/assessment-profile.json",
+    "output_dir": "/path/to/output-dir"
+  }'
+```
+
+Check status:
+
+```sh
+curl -sf http://127.0.0.1:8080/runs/JOB_ID
+```
+
+Fetch reports:
+
+```sh
+curl -sf http://127.0.0.1:8080/runs/JOB_ID/reports
+```
+
+## Result Review
+
+Review first:
+
+- `reports/report.md`
+- `reports/assessment-package.json`
+- `normalized/evidence.json`
+- `normalized/findings.json`
+- `retention-summary.json`
+
+Candidate tracking:
+
+- Workplan or issue tracker:
+- Where report summaries are recorded:
+- Candidate bug criteria:
+- Known-gap criteria:
+- Harness or environment issue criteria:
+- Raw artifact retention:

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

@@ -72,7 +72,7 @@ Progress:
 
 ```task
 id: GUIDE-BOARD-WP-0002-T002
-status: todo
+status: done
 priority: high
 state_hub_task_id: "7d1df7d0-49cd-487f-a507-9e558a90af31"
 ```
@@ -87,6 +87,12 @@ Acceptance:
 - 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
 
 ```task