guide-board/workplans/GUIDE-BOARD-WP-0003-extension-sdk-maturity.md

id, type, title, repo, domain, status, owner, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	repo	domain	status	owner	planning_priority	planning_order	created	updated	state_hub_workstream_id
GUIDE-BOARD-WP-0003	workplan	Extension SDK Maturity	guide-board	markitect	completed	codex	high	3	2026-05-15	2026-05-15	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

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

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

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

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.