generated from coulomb/repo-seed
149 lines
3.8 KiB
Markdown
149 lines
3.8 KiB
Markdown
# 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.
|