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

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