first extension execution path

docs/ARCHITECTURE-BLUEPRINT.md

@@ -771,3 +771,5 @@ Each run should lock:
 7. Add optional service API around the CLI job model.
 8. Add OSCAL export and procedural evidence-pack support after the internal
    evidence model proves itself with executable extensions.
+
+The first extension SDK contract is documented in `docs/EXTENSION-SDK.md`.

docs/EXTENSION-SDK.md

@@ -0,0 +1,145 @@
+# Guide Board Extension SDK
+
+Status: draft
+Created: 2026-05-07
+
+## Purpose
+
+This document defines the first extension integration contract for `guide-board`.
+It is intentionally small: extensions declare metadata in `extension.json`, the
+core discovers them, and runners can produce normalized evidence through a stable
+dictionary contract.
+
+## Extension Layout
+
+Incubating extensions live under:
+
+```text
+extensions/<extension-id>/
+  INTENT.md
+  extension.json
+  src/
+  docs/
+  schemas/
+  checks/
+  mappings/
+  profiles/
+  runners/
+  normalizers/
+  reports/
+  workplans/
+```
+
+Only `INTENT.md` and `extension.json` are required for discovery. Additional
+folders appear as the extension grows.
+
+## Manifest Contract
+
+`extension.json` must validate against:
+
+```text
+docs/schemas/extension-manifest.schema.json
+```
+
+The key runtime fields are:
+
+- `id`: must match the extension directory name.
+- `extension_type`: one of the supported archetypes from the architecture
+  blueprint.
+- `supported_frameworks`: framework IDs this extension can contribute evidence
+  for.
+- `check_groups`: named groups that assessment profiles can select.
+- `preflight_runner`: optional runner ID used before selected check groups.
+- `runner_entrypoints`: concrete runner declarations.
+- `certification_boundary`: explicit statement of what the extension does not
+  certify.
+
+## Runner Entry Points
+
+Runner entry points currently support these kinds:
+
+- `python_module`: load a Python file from the extension directory and call a
+  function.
+- `external`: declare an external harness that the baseline core cannot execute
+  yet.
+- `command`: reserved for future command execution.
+
+Example:
+
+```json
+{
+  "id": "cmis-browser-preflight",
+  "kind": "python_module",
+  "module_path": "src/open_cmis_tck/preflight.py",
+  "callable": "run",
+  "command": null,
+  "description": "Checks whether the CMIS Browser Binding endpoint is reachable."
+}
+```
+
+## Python Runner Contract
+
+A Python runner receives one context object and returns one result object.
+
+```python
+def run(context: dict) -> dict:
+    return {
+        "result": "pass",
+        "observations": ["Observed the expected condition."],
+        "facts": {"key": "value"},
+        "artifact_refs": [],
+    }
+```
+
+Context fields:
+
+- `root`: repository root path as a string.
+- `run_dir`: output run directory path as a string.
+- `run_id`: current run ID.
+- `plan`: full run plan snapshot.
+- `step`: the step being executed.
+- `target_profile`: target profile snapshot.
+- `assessment_profile`: assessment profile snapshot.
+- `extension_path`: extension directory path as a string.
+- `runner`: manifest runner declaration.
+
+Result fields:
+
+- `result`: one of the guide-board evidence result statuses.
+- `observations`: human-readable observations.
+- `facts`: structured facts extracted by the runner.
+- `artifact_refs`: references to raw artifacts written by the runner.
+
+If a Python runner raises an exception, the core converts that failure into
+`infrastructure_error` evidence so the assessment package remains complete.
+
+## Result Statuses
+
+Initial statuses:
+
+- `pass`
+- `fail`
+- `warning`
+- `manual`
+- `not_applicable`
+- `skipped`
+- `expected_gap`
+- `waiver_applied`
+- `unsupported_by_design`
+- `infrastructure_error`
+- `blocked`
+- `unknown`
+
+## Current Extension Examples
+
+- `sample-noop`: no runner, used to validate the core contracts.
+- `open-cmis-tck`: provides a Python CMIS Browser Binding preflight runner and
+  declares the future external OpenCMIS TCK runner.
+
+## Next SDK Steps
+
+- Add command runner support with explicit allow/deny controls.
+- Add artifact helper APIs for extension-generated raw files.
+- Add normalizer and mapping plug-in contracts.
+- Add extension-owned schema validation for domain-specific target profile
+  fields.

docs/schemas/extension-manifest.schema.json

@@ -60,7 +60,25 @@
       }
     },
     "preflight_runner": { "type": ["string", "null"] },
-    "runner_entrypoints": { "type": "array", "items": { "type": "string" } },
+    "runner_entrypoints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind"],
+        "properties": {
+          "id": { "type": "string" },
+          "kind": {
+            "type": "string",
+            "enum": ["python_module", "command", "external"]
+          },
+          "module_path": { "type": ["string", "null"] },
+          "callable": { "type": ["string", "null"] },
+          "command": { "type": ["array", "null"], "items": { "type": "string" } },
+          "description": { "type": ["string", "null"] }
+        }
+      }
+    },
     "normalizers": { "type": "array", "items": { "type": "string" } },
     "mappings": { "type": "array", "items": { "type": "string" } },
     "report_fragments": { "type": "array", "items": { "type": "string" } },