From 23b495fbdac864f1df33288734a523c8c8dadfd3 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 15 May 2026 13:33:21 +0200 Subject: [PATCH] Add candidate assessment handoff contract --- .custodian-brief.md | 7 +- README.md | 1 + docs/ASSESSMENT-OPERATIONS.md | 2 + docs/CANDIDATE-HANDOFF.md | 148 ++++++++++++++++++ .../templates/CANDIDATE-ASSESSMENT-HANDOFF.md | 147 +++++++++++++++++ ...-WP-0002-assessment-operations-baseline.md | 8 +- 6 files changed, 308 insertions(+), 5 deletions(-) create mode 100644 docs/CANDIDATE-HANDOFF.md create mode 100644 docs/templates/CANDIDATE-ASSESSMENT-HANDOFF.md diff --git a/.custodian-brief.md b/.custodian-brief.md index 537e1ea..7b6c852 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -1,17 +1,16 @@ # Custodian Brief — guide-board -**Domain:** markitect -**Last synced:** 2026-05-15 10:28 UTC +**Domain:** markitect +**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` diff --git a/README.md b/README.md index 805838f..f0d061e 100644 --- a/README.md +++ b/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) diff --git a/docs/ASSESSMENT-OPERATIONS.md b/docs/ASSESSMENT-OPERATIONS.md index a1454f7..20a6622 100644 --- a/docs/ASSESSMENT-OPERATIONS.md +++ b/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. diff --git a/docs/CANDIDATE-HANDOFF.md b/docs/CANDIDATE-HANDOFF.md new file mode 100644 index 0000000..6e0cf9d --- /dev/null +++ b/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. diff --git a/docs/templates/CANDIDATE-ASSESSMENT-HANDOFF.md b/docs/templates/CANDIDATE-ASSESSMENT-HANDOFF.md new file mode 100644 index 0000000..b42b1e0 --- /dev/null +++ b/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: diff --git a/workplans/GUIDE-BOARD-WP-0002-assessment-operations-baseline.md b/workplans/GUIDE-BOARD-WP-0002-assessment-operations-baseline.md index c0720fe..d1ba945 100644 --- a/workplans/GUIDE-BOARD-WP-0002-assessment-operations-baseline.md +++ b/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