guide-board/docs/CANDIDATE-HANDOFF.md

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:

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.