Add candidate assessment handoff 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.