generated from coulomb/repo-seed
148 lines
4.1 KiB
Markdown
148 lines
4.1 KiB
Markdown
# External Extension Acceptance
|
|
|
|
Status: draft
|
|
Created: 2026-05-15
|
|
|
|
## Purpose
|
|
|
|
This document defines the repeatable acceptance path for a guide-board
|
|
extension that lives outside the core repository. It proves that guide-board can
|
|
discover the extension, validate candidate profiles, build a traceable run plan,
|
|
execute the selected checks, and review retained results without moving
|
|
domain-specific harness logic into the core.
|
|
|
|
`open-cmis-tck` is the first concrete example. CMIS-specific profiles, runners,
|
|
runtime dependencies, and harness behavior remain owned by that extension
|
|
repository.
|
|
|
|
For a dependency-light SDK reference extension that can be copied into a
|
|
temporary external repository, see `extensions/sdk-fixture`.
|
|
|
|
## Acceptance Stages
|
|
|
|
Run these stages from the guide-board repository.
|
|
|
|
1. Confirm the extension repository shape:
|
|
|
|
```sh
|
|
test -f ../open-cmis-tck/extension.json
|
|
```
|
|
|
|
2. Validate extension discovery and manifest contracts:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m guide_board \
|
|
--extension-dir ../open-cmis-tck \
|
|
extensions validate
|
|
```
|
|
|
|
3. Validate the target and assessment profiles:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m guide_board \
|
|
--extension-dir ../open-cmis-tck \
|
|
profile validate-target \
|
|
../open-cmis-tck/profiles/targets/kontextual-cmis-compat.json
|
|
|
|
PYTHONPATH=src python3 -m guide_board \
|
|
--extension-dir ../open-cmis-tck \
|
|
profile validate-assessment \
|
|
../open-cmis-tck/profiles/assessments/cmis-browser-baseline.json
|
|
```
|
|
|
|
4. Generate and retain a run plan:
|
|
|
|
```sh
|
|
mkdir -p /tmp/guide-board-external-extension-acceptance
|
|
PYTHONPATH=src python3 -m guide_board \
|
|
--extension-dir ../open-cmis-tck \
|
|
plan \
|
|
--target ../open-cmis-tck/profiles/targets/kontextual-cmis-compat.json \
|
|
--assessment ../open-cmis-tck/profiles/assessments/cmis-browser-baseline.json \
|
|
--output /tmp/guide-board-external-extension-acceptance/plan.json
|
|
```
|
|
|
|
5. Execute a live run when the candidate endpoint and extension runtime
|
|
dependencies are available:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m guide_board \
|
|
--extension-dir ../open-cmis-tck \
|
|
run \
|
|
--target ../open-cmis-tck/profiles/targets/kontextual-cmis-compat.json \
|
|
--assessment ../open-cmis-tck/profiles/assessments/cmis-browser-baseline.json \
|
|
--output-dir /tmp/guide-board-external-extension-acceptance/open-cmis-tck-baseline
|
|
```
|
|
|
|
6. Review retained results:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m guide_board runs report \
|
|
--runs-dir /tmp/guide-board-external-extension-acceptance \
|
|
--target kontextual-cmis-compat \
|
|
--assessment cmis-browser-baseline
|
|
```
|
|
|
|
The run directory should contain:
|
|
|
|
```text
|
|
run.json
|
|
plan.json
|
|
retention-summary.json
|
|
normalized/evidence.json
|
|
normalized/findings.json
|
|
normalized/mappings.json
|
|
reports/assessment-package.json
|
|
reports/report.md
|
|
artifacts/
|
|
```
|
|
|
|
## Scripted Acceptance
|
|
|
|
The scripted path keeps the same commands in one place:
|
|
|
|
```sh
|
|
scripts/external_extension_acceptance.sh plan
|
|
```
|
|
|
|
The default `plan` mode validates the extension and profiles, then writes a run
|
|
plan under `/tmp/guide-board-external-extension-acceptance`. It does not contact
|
|
the candidate system.
|
|
|
|
Use `run` mode for the live acceptance after the candidate endpoint and harness
|
|
dependencies are ready:
|
|
|
|
```sh
|
|
scripts/external_extension_acceptance.sh run
|
|
```
|
|
|
|
Override the extension, profiles, or output location when accepting another
|
|
extension:
|
|
|
|
```sh
|
|
GUIDE_BOARD_ACCEPT_EXTENSION_DIR=../example-extension \
|
|
GUIDE_BOARD_ACCEPT_TARGET=../example-extension/profiles/targets/example.json \
|
|
GUIDE_BOARD_ACCEPT_ASSESSMENT=../example-extension/profiles/assessments/example.json \
|
|
GUIDE_BOARD_ACCEPT_OUTPUT_DIR=/tmp/guide-board-example-extension \
|
|
scripts/external_extension_acceptance.sh plan
|
|
```
|
|
|
|
## Ownership Boundary
|
|
|
|
Guide-board owns:
|
|
|
|
- extension discovery,
|
|
- extension manifest validation,
|
|
- target and assessment profile validation,
|
|
- run plan construction,
|
|
- run artifact layout,
|
|
- retained run summary and report lookup.
|
|
|
|
The external extension repository owns:
|
|
|
|
- domain-specific target and assessment profiles,
|
|
- harness adapters and runtime dependencies,
|
|
- credentials or restricted asset instructions,
|
|
- check group behavior,
|
|
- interpretation of domain-specific evidence.
|