guide-board/docs/EXTERNAL-EXTENSION-ACCEPTANCE.md

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:

test -f ../open-cmis-tck/extension.json

2. Validate extension discovery and manifest contracts:

PYTHONPATH=src python3 -m guide_board \
  --extension-dir ../open-cmis-tck \
  extensions validate

3. Validate the target and assessment profiles:

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:

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:

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:

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:

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:

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:

scripts/external_extension_acceptance.sh run

Override the extension, profiles, or output location when accepting another extension:

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.