---
id: GUIDE-BOARD-WP-0003
type: workplan
title: "Extension SDK Maturity"
repo: guide-board
domain: markitect
status: completed
owner: codex
planning_priority: high
planning_order: 3
created: "2026-05-15"
updated: "2026-05-15"
state_hub_workstream_id: "26aa9511-cd5c-4dd5-989c-d2838ba3b50d"
---

# GUIDE-BOARD-WP-0003: Extension SDK Maturity

## Purpose

Harden the external extension SDK now that guide-board has a repeatable
assessment operations baseline. External extension repositories should be able
to declare their own validation surfaces, normalization boundaries, and
acceptance fixtures without pushing domain logic back into the core.

## Background

`GUIDE-BOARD-WP-0002` made assessment operation repeatable for CLI, service,
container, candidate handoff, retained results, and external extension
acceptance. The next repo-level gap is SDK maturity: the core can discover
external extensions and run their entrypoints, but extension-owned validation
and normalizer contracts are still mostly prose.

## Boundary

This workplan owns extension-neutral SDK contracts and core enforcement points.
Domain-specific schemas, CMIS runner behavior, harness dependencies, and
certification interpretations remain owned by external extension repositories.

## D3.1 - Extension-Owned Profile Schema Validation

```task
id: GUIDE-BOARD-WP-0003-T001
status: done
priority: high
state_hub_task_id: "1bc729ec-683c-410e-8b47-1b13eb61da00"
```

Acceptance:

- Allow extension manifests to declare profile schema descriptors without
  breaking the existing string shorthand.
- Validate extension-owned target and assessment profile schemas during CLI
  profile validation and run planning.
- Keep extension schemas loaded from the extension root and reject schema paths
  that escape that root.
- Add focused tests and SDK documentation.

Progress:

- Extended `profile_schemas` to support descriptor objects while preserving the
  existing string shorthand.
- Applied extension-owned target and assessment schema validation in CLI profile
  validation and run planning.
- Added tests for successful extension-owned validation, validation failure, and
  schema-path root containment.
- Documented the descriptor contract in `docs/EXTENSION-SDK.md`.

## D3.2 - Normalizer Plug-in Contract

```task
id: GUIDE-BOARD-WP-0003-T002
status: done
priority: high
state_hub_task_id: "b87e68c1-6eca-4274-8e3f-6e2854c5a1e1"
```

Acceptance:

- Define how extension normalizers are declared, loaded, and invoked.
- Preserve the current runner-result contract while allowing an extension to
  normalize native result artifacts explicitly.
- Add tests that prove a normalizer can map native output into evidence.

Progress:

- Added `guide_board.normalizers.normalize_step_result`.
- Extended `normalizers` manifest entries to support Python module descriptor
  objects while preserving the existing string shorthand.
- Invoked matching normalizers after runner execution and before evidence
  writing.
- Merged normalizer result fields over runner results and recorded
  `normalizer_refs` in evidence facts.
- Added test coverage through the SDK fixture run.

## D3.3 - SDK Fixture Extension And Acceptance Tests

```task
id: GUIDE-BOARD-WP-0003-T003
status: done
priority: medium
state_hub_task_id: "f3738751-5a0d-4eaf-85b1-75e599a78060"
```

Acceptance:

- Add a compact SDK fixture extension that exercises the mature contracts.
- Keep the fixture dependency-light and suitable for unit tests.
- Cover external repo discovery, schema validation, normalizer invocation, plan
  generation, and result package shape.

Progress:

- Added `extensions/sdk-fixture`.
- Included extension-owned target and assessment schemas, fixture profiles, a
  native-output runner, a normalizer, and a mapping set.
- Added a unit test that copies the fixture as an external extension repository
  and verifies plan, evidence, mapping, and assessment package output.

## D3.4 - Extension Authoring Documentation Refresh

```task
id: GUIDE-BOARD-WP-0003-T004
status: done
priority: medium
state_hub_task_id: "3d390bd4-755b-462a-9e16-9c859990d99e"
```

Acceptance:

- Refresh `docs/EXTENSION-SDK.md` with the finalized profile-schema and
  normalizer contracts.
- Update templates or examples so extension authors can copy working shapes.
- Link the SDK maturity guidance from the assessment operations and external
  extension acceptance docs where useful.

Progress:

- Refreshed `docs/EXTENSION-SDK.md` with profile schema descriptors,
  normalizer descriptors, context fields, merge semantics, and fixture guidance.
- Linked SDK authoring contracts from `docs/ASSESSMENT-OPERATIONS.md`.
- Linked `extensions/sdk-fixture` from `docs/EXTERNAL-EXTENSION-ACCEPTANCE.md`.
- Added README references for the SDK fixture and WP3.

## Definition Of Done

- External extension repositories can declare and test domain-specific profile
  validation without core code changes.
- Normalizer plug-ins have a documented and tested core contract.
- The SDK includes a small fixture path that future extension work can reuse.
- Operator docs and authoring docs agree on the supported extension lifecycle.