generated from coulomb/repo-seed
151 lines
5.0 KiB
Markdown
151 lines
5.0 KiB
Markdown
---
|
|
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.
|