Add external extension acceptance path

docs/ASSESSMENT-OPERATIONS.md

@@ -62,6 +62,9 @@ PYTHONPATH=src python3 -m guide_board \
 
 The same extension roots can be provided through `GUIDE_BOARD_EXTENSION_PATHS`
 when a wrapper script or container entrypoint should keep commands shorter.
+For the repeatable external extension acceptance path, including validation,
+planning, live execution, and retained result review, see
+`docs/EXTERNAL-EXTENSION-ACCEPTANCE.md`.
 
 ## CLI Results
 

docs/EXTERNAL-EXTENSION-ACCEPTANCE.md

@@ -0,0 +1,144 @@
+# 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.