# 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.