Separated open-cmis-tck and guide-board repositories

docs/ARCHITECTURE-BLUEPRINT.md

@@ -0,0 +1,791 @@
+# Guide Board Core Architecture Blueprint
+
+Status: draft
+Created: 2026-05-07
+
+## Purpose
+
+This blueprint defines the first core architecture for `guide-board`: a
+certification and compliance preparation framework that can orchestrate
+extension-specific conformance harnesses, validators, repository-quality checks,
+and procedural evidence packs without embedding domain policy in the core.
+
+The design is based on recurring patterns from official or authority-backed
+programs such as OGC TEAM Engine, OpenID Foundation Conformance Suite, CNCF
+Kubernetes Conformance, web-platform-tests, Khronos CTS, NIST ACVP, HL7/FHIR
+Inferno, Jakarta EE TCK, OPC UA CTT, NIST SCAP/OSCAL, CIS-CAT, and OpenSSF
+Scorecard.
+
+## Research Lessons
+
+### Suite Engine
+
+Examples: OGC TEAM Engine, OpenCMIS TCK, Jakarta EE TCK.
+
+Pattern:
+
+- installable suites with their own test definitions,
+- command-line execution and sometimes web/API execution,
+- target-specific input forms or profiles,
+- raw logs plus structured result formats,
+- conformance classes or capability areas,
+- certification boundary outside normal self-testing.
+
+Architecture lesson:
+
+`guide-board` needs a runner bridge that can call external harnesses, capture
+artifacts, and normalize tool-specific result formats without making the harness
+part of the core.
+
+Sources:
+
+- [TEAM Engine](https://opengeospatial.github.io/teamengine/)
+- [TEAM Engine User Guide](https://opengeospatial.github.io/teamengine/users.html)
+- [Jakarta EE TCK Process](https://jakarta.ee/committees/specification/tckprocess/)
+- [OpenCMIS TCK package](https://chemistry.apache.org/java/javadoc/org/apache/chemistry/opencmis/tck/package-summary.html)
+
+### Hosted Or Local Certification Suite
+
+Examples: OpenID Foundation Conformance Suite, Inferno.
+
+Pattern:
+
+- open source suite,
+- hosted public/staging environments,
+- local Docker execution,
+- named test plans or test kits,
+- logs and public result pages,
+- fee or accredited-review boundary for formal certification.
+
+Architecture lesson:
+
+`guide-board` should model execution environment tiers, test plans, and
+certification submission packages separately from normal development runs.
+
+Sources:
+
+- [OpenID Conformance Suite](https://openid.net/certification/about-conformance-suite/)
+- [OpenID Certification](https://openid.net/certification/)
+- [Inferno Framework](https://inferno-framework.github.io/about/)
+- [Inferno Documentation](https://inferno-framework.github.io/docs)
+
+### Submit-Results Program
+
+Example: CNCF Kubernetes Conformance.
+
+Pattern:
+
+- vendors run the same open source conformance application used by the program,
+- result artifacts are submitted for review,
+- accepted results feed a public certification list,
+- users can rerun the same conformance application to confirm behavior.
+
+Architecture lesson:
+
+An assessment package should be a first-class artifact with source metadata,
+runner version, target identity, raw evidence, normalized results, and a review
+boundary suitable for downstream submission.
+
+Source:
+
+- [CNCF Certified Kubernetes Software Conformance](https://www.cncf.io/certification/software-conformance/)
+
+### Protocol Validation Service
+
+Example: NIST ACVP.
+
+Pattern:
+
+- authority-operated demo and production services,
+- client authentication,
+- machine-to-machine protocol,
+- generated test vectors and submitted responses,
+- validation tied to an external authority process.
+
+Architecture lesson:
+
+Some extensions will not run a local test suite. They will coordinate a session
+with an authority service. The core must support credential references, remote
+session IDs, generated inputs, submitted responses, and external verdicts.
+
+Source:
+
+- [NIST ACVP](https://pages.nist.gov/ACVP/)
+
+### Web-Scale Shared Test Repository
+
+Example: web-platform-tests.
+
+Pattern:
+
+- shared specification-linked test repository,
+- canonical manifest generation,
+- multiple test types including automated, reference, and manual tests,
+- local and public execution surfaces.
+
+Architecture lesson:
+
+`guide-board` check discovery should be manifest-driven where possible. It must
+support heterogeneous check types instead of assuming every check is a simple
+pass/fail command.
+
+Sources:
+
+- [web-platform-tests](https://web-platform-tests.org/)
+- [Writing Your Own Runner](https://web-platform-tests.org/running-tests/custom-runner.html)
+- [Running Tests from the Web](https://web-platform-tests.org/running-tests/from-web.html)
+
+### Conformance Submission Package
+
+Examples: Khronos Vulkan CTS and OpenXR CTS.
+
+Pattern:
+
+- automated and sometimes interactive test runs,
+- XML result files,
+- console output,
+- build and CTS version metadata,
+- explicit conformance statement,
+- trademark or adopter-program boundary.
+
+Architecture lesson:
+
+The guide-board assessment package should preserve both normalized evidence and
+the original submission-grade artifacts expected by an authority.
+
+Sources:
+
+- [Vulkan CTS Guide](https://docs.vulkan.org/guide/latest/vulkan_cts.html)
+- [OpenXR CTS Usage Guide](https://registry.khronos.org/OpenXR/conformance/cts_usage.html)
+
+### Restricted Tool
+
+Examples: OPC UA CTT, CIS-CAT Pro.
+
+Pattern:
+
+- official tool may be restricted to members, licensees, or controlled access,
+- tests are organized by profiles, facets, conformance units, benchmarks, or
+  controls,
+- command-line execution may exist for automation,
+- redistribution is not allowed or not appropriate.
+
+Architecture lesson:
+
+`guide-board` must represent restricted harnesses as externally supplied runtime
+assets. The registry can describe how to integrate them, but the core and
+extensions must not vendor restricted tools or proprietary standard text.
+
+Sources:
+
+- [OPC UA Compliance Test Tool](https://opcfoundation.org/developer-tools/certification-test-tools/opc-ua-compliance-test-tool-uactt/)
+- [CIS-CAT Pro Assessor](https://www.cisecurity.org/cybersecurity-tools/cis-cat-pro)
+
+### Security Configuration And Assessment Content
+
+Examples: NIST SCAP, OpenSCAP, CIS-CAT Pro.
+
+Pattern:
+
+- machine-readable security configuration content,
+- profiles or tailored benchmarks,
+- local or remote system assessment,
+- automated and manual checks,
+- reports mapped to controls.
+
+Architecture lesson:
+
+`guide-board` must support content-driven validators where the extension supplies
+policy content and a scanner, not a fixed test suite. The evidence model must
+handle manual, automated, and partially automated checks.
+
+Sources:
+
+- [NIST SCAP](https://csrc.nist.gov/Projects/Security-Content-Automation-Protocol)
+- [NIST SCAP 1.3](https://csrc.nist.gov/projects/security-content-automation-protocol/scap-releases/scap-1-3)
+- [OpenSCAP](https://www.open-scap.org/)
+
+### Assessment Data Interchange
+
+Example: NIST OSCAL.
+
+Pattern:
+
+- layered machine-readable models for controls, implementation, assessment
+  plans, assessment results, and remediation milestones,
+- multiple serializations such as JSON, XML, and YAML,
+- assessment results expressed relative to a system and controls.
+
+Architecture lesson:
+
+`guide-board` should keep its internal evidence model small, but design it so
+later OSCAL export is natural for compliance packs that need formal assessment
+interchange.
+
+Source:
+
+- [NIST OSCAL Layers and Models](https://pages.nist.gov/OSCAL/learn/concepts/layer/)
+
+### Repository Quality And Supply Chain Scoring
+
+Example: OpenSSF Scorecard.
+
+Pattern:
+
+- automated checks over source repositories,
+- score and risk level per check,
+- aggregate posture score,
+- remediation prompts,
+- CI and API integration.
+
+Architecture lesson:
+
+Repository quality packs should be normal extensions. A score is not a
+certification verdict; it is a normalized finding and trend signal.
+
+Quality gates should be core policy decisions over retained posture, not
+extension-specific verdicts. The first gate layer checks latest run status,
+unexpected finding count, and whether the latest trend regressed.
+
+Sources:
+
+- [OpenSSF Scorecard](https://openssf.org/projects/scorecard/)
+- [Scorecard documentation](https://github.com/ossf/scorecard)
+
+## Architecture Principles
+
+- The core is extension-neutral.
+- Authority, framework, and harness versions are evidence, not prose.
+- Local CLI behavior is the execution source of truth.
+- Optional service APIs wrap the same contracts used by the CLI.
+- Restricted harnesses and proprietary standards are mounted or referenced, not
+  redistributed.
+- Raw artifacts are preserved, but normalized evidence is the primary interface.
+- Every assessment package must state its certification boundary.
+- Manual, semi-automated, and fully automated checks all use the same evidence
+  model.
+- Expected gaps and waivers never suppress unexpected failures silently.
+- Extension extraction to separate repositories should be possible without
+  changing core contracts.
+
+## Core Components
+
+### Authority Catalog
+
+Tracks source authorities, framework names, versions, official URLs, licensing
+posture, access constraints, certification boundaries, and lifecycle status.
+
+### Extension Registry
+
+Discovers installed or incubating extensions. Each extension declares:
+
+- extension ID,
+- type,
+- supported frameworks,
+- source authority references,
+- profile schemas,
+- check groups,
+- runner or validator entry points,
+- normalizers,
+- mappings,
+- report fragments,
+- dependency and license posture.
+
+### Profile Registry
+
+Loads and validates target profiles and assessment profiles.
+
+Target profiles describe the subject being assessed: repository, service,
+cluster, product, API, data archive, host, organization, process, or policy set.
+
+Assessment profiles select frameworks, controls, check groups, expectations,
+waivers, output policies, and retention policies.
+
+### Assessment Planner
+
+Resolves an assessment profile into an executable run plan:
+
+- selected extensions,
+- selected check groups,
+- required credentials,
+- preflight checks,
+- dependency checks,
+- execution order,
+- isolation and timeout policy,
+- artifact retention policy.
+
+At execution time, a failing preflight blocks downstream check groups for the
+same extension so expensive or misleading harness steps are not invoked.
+
+### Runner Bridge
+
+Executes or coordinates extension checks.
+
+Supported runner kinds:
+
+- local command,
+- container command,
+- in-process validator,
+- remote protocol session,
+- hosted test-suite interaction,
+- manual evidence request,
+- imported result package.
+
+### Artifact Store
+
+Stores run artifacts by reference and checksum:
+
+- raw logs,
+- XML/JSON/HTML reports,
+- screenshots or rendered documents,
+- authority submission files,
+- request/response transcripts,
+- input forms,
+- profile snapshots,
+- source lockfiles.
+
+The first implementation builds the assessment package artifact manifest from
+runner-emitted artifact refs and computes checksums for files inside the run
+directory.
+
+### Normalizer
+
+Converts extension output into guide-board evidence records.
+
+The normalizer should preserve native identifiers such as test case IDs,
+conformance class IDs, control IDs, profile IDs, benchmark IDs, or requirement
+references.
+
+### Mapping Engine
+
+Maps evidence to:
+
+- capabilities,
+- controls,
+- conformance classes,
+- requirements,
+- policy questions,
+- repository quality dimensions,
+- scorecard dimensions.
+
+Mappings belong to extensions or assessment packs, not the core.
+
+The first implementation loads extension-owned JSON mapping sets from
+`extensions/<extension-id>/mappings/`, joins them to evidence `requirement_refs`,
+and writes normalized mapping records under each run directory.
+
+### Expectation And Waiver Engine
+
+Applies declared target posture after evidence normalization.
+
+Use expectations for known optional behavior, unsupported-by-design features, and
+accepted gaps.
+
+Use waivers for time-bounded exceptions with owner, reason, expiry, and review
+metadata.
+
+The first implementation supports assessment-profile references to JSON
+expectation and waiver sets. These policies annotate findings as expected or
+waived after evidence normalization and finding creation.
+
+### Report Builder
+
+Builds human and machine-readable outputs:
+
+- compact JSON assessment package,
+- Markdown summary,
+- extension-specific fragments,
+- submission package manifest,
+- trend summaries,
+- future OSCAL or other interchange exports.
+
+### Retention Index
+
+Keeps compact summaries over time while allowing raw artifact retention to be
+bounded by policy. The first implementation writes `retention-summary.json` for
+each run and can build a trend summary grouped by target and assessment profile.
+
+## Extension Archetypes
+
+### Executable Harness Extension
+
+Runs an external TCK, CTS, or conformance suite.
+
+Examples: `open-cmis-tck`, OGC TEAM Engine, Jakarta EE TCK, Khronos CTS.
+
+### Validator Extension
+
+Validates structured artifacts against schemas, profiles, or data-stream
+requirements.
+
+Examples: SCAP content validation, FHIR resource validation.
+
+### Protocol Service Extension
+
+Coordinates with an external authority-operated service.
+
+Example: NIST ACVP.
+
+### Hosted Suite Extension
+
+Uses a hosted or locally containerized suite with named test plans.
+
+Examples: OpenID Conformance Suite, Inferno.
+
+### Repository Quality Extension
+
+Runs checks against repository configuration, development process, supply chain
+signals, and release hygiene.
+
+Example: OpenSSF Scorecard.
+
+### Procedural Evidence Extension
+
+Guides collection of policy, process, and control evidence where no official
+executable harness exists.
+
+Examples: GDPR, SOC 2, HIPAA, NF Z 42-013, NF 461, ISO 14641, ISO 15489.
+
+### Hybrid Extension
+
+Combines automated checks, manual evidence, external auditor review, and imported
+result packages.
+
+## Core Data Contracts
+
+The first implementation should define these as simple JSON/YAML schemas before
+building complex runtime code.
+
+### `Authority`
+
+- `id`
+- `name`
+- `authority_type`
+- `source_urls`
+- `frameworks`
+- `license_posture`
+- `access_constraints`
+- `certification_boundary`
+- `lifecycle_status`
+
+### `ExtensionManifest`
+
+- `id`
+- `name`
+- `version`
+- `extension_type`
+- `supported_frameworks`
+- `profile_schemas`
+- `check_groups`
+- `runner_entrypoints`
+- `normalizers`
+- `mappings`
+- `report_fragments`
+- `dependencies`
+- `restricted_assets`
+
+### `Framework`
+
+- `id`
+- `authority_id`
+- `name`
+- `version`
+- `status`
+- `source_urls`
+- `requirement_index`
+- `profile_index`
+- `license_posture`
+
+### `TargetProfile`
+
+- `id`
+- `subject_type`
+- `subject_name`
+- `environment`
+- `scope`
+- `endpoints`
+- `artifacts`
+- `credentials_ref`
+- `declared_capabilities`
+- `known_gaps`
+
+### `AssessmentProfile`
+
+- `id`
+- `framework_refs`
+- `extension_refs`
+- `target_profile_ref`
+- `selected_check_groups`
+- `expectations_ref`
+- `waivers_ref`
+- `output_policy`
+- `retention_policy`
+
+### `CheckDefinition`
+
+- `id`
+- `extension_id`
+- `check_type`
+- `framework_refs`
+- `requirement_refs`
+- `inputs`
+- `preconditions`
+- `timeout`
+- `runner_ref`
+- `expected_artifacts`
+
+### `RunPlan`
+
+- `id`
+- `assessment_profile_snapshot`
+- `extension_snapshots`
+- `source_lock`
+- `ordered_steps`
+- `credential_refs`
+- `artifact_policy`
+- `runtime_policy`
+
+### `RawArtifact`
+
+- `id`
+- `run_id`
+- `path`
+- `media_type`
+- `producer`
+- `checksum`
+- `created_at`
+- `retention_class`
+
+### `EvidenceItem`
+
+- `id`
+- `run_id`
+- `extension_id`
+- `check_id`
+- `subject_ref`
+- `result`
+- `observations`
+- `facts`
+- `requirement_refs`
+- `artifact_refs`
+- `started_at`
+- `completed_at`
+
+### `Finding`
+
+- `id`
+- `run_id`
+- `status`
+- `severity`
+- `classification`
+- `requirement_refs`
+- `evidence_refs`
+- `expected`
+- `waiver_ref`
+- `remediation`
+
+### `Waiver`
+
+- `id`
+- `scope`
+- `requirement_refs`
+- `reason`
+- `owner`
+- `approved_by`
+- `created_at`
+- `expires_at`
+- `review_status`
+
+### `AssessmentPackage`
+
+- `id`
+- `run_id`
+- `target`
+- `frameworks`
+- `extensions`
+- `source_lock`
+- `summary`
+- `findings`
+- `evidence_refs`
+- `artifact_manifest`
+- `waivers`
+- `certification_boundary`
+- `created_at`
+
+## Result Vocabulary
+
+The evidence model should allow these statuses:
+
+- `pass`
+- `fail`
+- `warning`
+- `manual`
+- `not_applicable`
+- `skipped`
+- `expected_gap`
+- `waiver_applied`
+- `unsupported_by_design`
+- `infrastructure_error`
+- `blocked`
+- `unknown`
+
+The reporting layer should distinguish at least:
+
+- conformant evidence,
+- nonconformant evidence,
+- expected limitation,
+- waived limitation,
+- missing evidence,
+- infrastructure failure,
+- human review required.
+
+## Proposed Repository Layout
+
+```text
+guide-board/
+  INTENT.md
+  README.md
+  docs/
+    ARCHITECTURE-BLUEPRINT.md
+    schemas/
+  extensions/
+    CANDIDATES.md
+    _template/
+    sample-noop/
+  runs/
+  reports/
+  workplans/
+```
+
+`runs/` and `reports/` should be local generated outputs and ignored by default.
+Production extensions should usually live in separate repositories and be
+attached with `--extension-dir` or `GUIDE_BOARD_EXTENSION_PATHS`.
+
+## Execution Flow
+
+```text
+discover extensions
+  -> load authority catalog
+  -> validate target profile
+  -> validate assessment profile
+  -> plan run
+  -> run preflight
+  -> execute checks
+  -> collect artifacts
+  -> normalize evidence
+  -> map findings
+  -> apply expectations and waivers
+  -> build assessment package
+  -> write reports
+  -> retain summaries
+```
+
+## Run Directory Contract
+
+Each run should be reproducible from captured metadata where possible.
+
+```text
+runs/<run-id>/
+  run.json
+  retention-summary.json
+  plan.json
+  sources.lock.json
+  target-profile.snapshot.json
+  assessment-profile.snapshot.json
+  artifacts/
+  normalized/
+    evidence.json
+    findings.json
+    mappings.json
+  reports/
+    report.md
+    assessment-package.json
+  exports/
+```
+
+## Container And Service Model
+
+The local CLI should come first. Containerization should preserve the same CLI
+contracts.
+
+Recommended container model:
+
+- `guide-board-core` image contains the core CLI and schema tooling.
+- Extension dependencies are either installed by extension-specific images or
+  mounted as external assets.
+- Profiles, credentials, runs, and reports are mounted explicitly.
+- Restricted tools are mounted from licensed local paths.
+- Network access is declared per extension and per assessment profile.
+
+The baseline `Containerfile` packages the local CLI, schemas, sample profiles,
+and incubating extensions. See `docs/CONTAINER.md` for mount contracts and the
+extension-specific image path.
+
+Optional service model:
+
+- service lists extensions and profiles,
+- service validates and plans runs,
+- service starts jobs that call the CLI contracts,
+- service streams status and exposes reports,
+- service does not invent separate execution semantics.
+
+Candidate API resources:
+
+- `GET /extensions`
+- `GET /authorities`
+- `POST /profiles/validate`
+- `POST /assessments/plan`
+- `POST /runs`
+- `GET /runs/{run_id}`
+- `GET /runs/{run_id}/artifacts`
+- `GET /runs/{run_id}/reports`
+
+## Governance Model
+
+### Extension Lifecycle
+
+- `candidate`: researched and registered.
+- `incubating`: has an intent and workplan.
+- `active`: runnable through core contracts.
+- `external`: maintained outside the repo but compatible.
+- `deprecated`: retained for historical runs only.
+
+### Challenge And Exclusion Handling
+
+Use separate concepts:
+
+- authority exclusion: imported from an official TCK or program process,
+- extension challenge: local claim that a check is invalid or mis-mapped,
+- target expectation: declared optional or unsupported behavior,
+- waiver: approved and time-bounded exception,
+- defect: unexpected product or process failure.
+
+The report must make these visible separately.
+
+### Source Locking
+
+Each run should lock:
+
+- extension version,
+- framework version,
+- harness version,
+- authority source URLs,
+- test suite IDs,
+- mapping version,
+- target profile snapshot,
+- waiver snapshot.
+
+## Implementation Sequence
+
+1. Create schema drafts for the core data contracts.
+2. Add an extension manifest format and a minimal sample extension.
+3. Build the CLI commands: `extensions list`, `profile validate`, `plan`, `run`,
+   and `report`.
+4. Integrate `open-cmis-tck` through the same contracts.
+5. Add generated-output ignores for `runs/` and `reports/`.
+6. Add container design after the CLI baseline is stable.
+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/CONTAINER.md

@@ -0,0 +1,115 @@
+# Guide Board Container Baseline
+
+Status: draft
+Created: 2026-05-07
+
+## Purpose
+
+The first container image packages the local CLI contracts, schemas, bundled
+profiles, and incubating extensions. It is not a certification appliance and it
+does not include restricted third-party harnesses unless a downstream image or
+runtime mount provides them.
+
+## Image Roles
+
+Use `guide-board-core` for dependency-light checks:
+
+- extension discovery,
+- profile validation,
+- run planning,
+- sample/no-op assessments,
+- extensions whose runners use only the core Python runtime.
+
+Use extension-specific images when a harness needs additional dependencies such
+as Java, Maven, browser engines, vendor tools, or licensed test suites. Those
+images should extend `guide-board-core` or mount the core as a package, but they
+must keep restricted assets outside the public core image.
+
+## Build
+
+```sh
+podman build -t guide-board-core:local -f Containerfile .
+```
+
+Docker can be used with the same arguments.
+
+## Local Baseline Run
+
+```sh
+mkdir -p runs
+podman run --rm \
+  -v "$PWD/runs:/runs" \
+  guide-board-core:local \
+  --root /opt/guide-board run \
+  --target /opt/guide-board/profiles/targets/sample-repository.json \
+  --assessment /opt/guide-board/profiles/assessments/sample-noop.json \
+  --output-dir /runs/sample-noop
+```
+
+The run output remains on the host under `runs/sample-noop`.
+
+## External Profiles
+
+Mount project-specific profiles read-only:
+
+```sh
+podman run --rm \
+  -v "$PWD/profiles:/profiles:ro" \
+  -v "$PWD/runs:/runs" \
+  guide-board-core:local \
+  --root /opt/guide-board run \
+  --target /profiles/targets/example.json \
+  --assessment /profiles/assessments/example.json \
+  --output-dir /runs/example
+```
+
+## External Extensions
+
+Mount extension repositories separately and pass them with `--extension-dir`:
+
+```sh
+podman run --rm \
+  -v "$PWD/../open-cmis-tck:/extensions/open-cmis-tck:ro" \
+  -v "$PWD/runs:/runs" \
+  guide-board-core:local \
+  --root /opt/guide-board \
+  --extension-dir /extensions/open-cmis-tck \
+  extensions list
+```
+
+The external extension root must contain `extension.json`. The core records
+external extension paths in the run plan snapshot so evidence remains traceable.
+
+## Credentials And Restricted Assets
+
+Credentials and licensed harness material should be mounted explicitly:
+
+```text
+/credentials   runtime secrets or references
+/assets        licensed or locally provided harness assets
+/profiles      target and assessment profiles
+/runs          generated outputs
+```
+
+Assessment profiles should declare offline/network expectations. Extension
+runners should fail as `blocked` or `infrastructure_error` when required mounted
+assets are absent.
+
+## CMIS Extension Path
+
+The core image includes the incubating `open-cmis-tck` extension metadata,
+preflight runner, command wrapper, and mappings. It does not include the final
+Apache Chemistry TCK dependency graph. A future CMIS image should add Java/Maven
+and document how the OpenCMIS TCK artifacts are resolved or mounted.
+
+## Service Path
+
+A service image should call the same CLI contracts used here:
+
+- validate profiles,
+- build run plans,
+- execute runs,
+- read run metadata, evidence, reports, retention summaries, trends, and gates.
+
+The service layer may add job tracking and HTTP transport, but it should not
+create separate execution semantics.

docs/EXTENSION-SDK.md

@@ -0,0 +1,247 @@
+# 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
+
+Bundled incubating extensions live under:
+
+```text
+extensions/<extension-id>/
+  INTENT.md
+  extension.json
+  src/
+  docs/
+  schemas/
+  checks/
+  mappings/
+  profiles/
+  runners/
+  normalizers/
+  reports/
+  workplans/
+```
+
+Production extensions may also live in their own repositories. The repository
+root is then the extension root and must contain `extension.json`:
+
+```text
+open-cmis-tck/
+  INTENT.md
+  extension.json
+  src/
+  mappings/
+  profiles/
+  runners/
+  workplans/
+```
+
+Pass external extension repos to the core CLI with:
+
+```sh
+guide-board --extension-dir ../open-cmis-tck extensions list
+```
+
+Multiple `--extension-dir` values are allowed. `GUIDE_BOARD_EXTENSION_PATHS`
+may also provide an OS-path-separated list for local automation and containers.
+
+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.
+- `mappings`: mapping set IDs under `mappings/<mapping-id>.json`.
+- `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.
+- `command`: execute a manifest-declared argv without shell expansion. The core
+  writes a context JSON file and expects the command to print a JSON runner
+  result to stdout.
+- `external`: declare an external harness that the baseline core cannot execute
+  yet.
+
+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."
+}
+```
+
+Command runner example:
+
+```json
+{
+  "id": "opencmis-tck",
+  "kind": "command",
+  "module_path": null,
+  "callable": null,
+  "command": ["python3", "runners/opencmis_tck.py", "--context", "{context_json}"],
+  "description": "Checks dependency posture and prepares OpenCMIS TCK execution."
+}
+```
+
+Command placeholders:
+
+- `{context_json}`: generated context file for the current step.
+- `{root}`: repository root.
+- `{run_dir}`: current run directory.
+- `{extension_path}`: current extension directory.
+
+The command is executed with the extension directory as its working directory.
+The core does not use a shell for command runners.
+
+Runner context values are stable for bundled and external extensions:
+
+- `root`: the guide-board core root.
+- `extension_path`: the absolute path to the extension root.
+- `run_dir`: the current run output directory.
+- `plan`: the immutable run plan snapshot.
+
+## Mapping Sets
+
+Mapping sets connect normalized evidence requirement refs to capability groups,
+controls, conformance classes, quality dimensions, or other assessment targets.
+
+Each mapping set lives under:
+
+```text
+extensions/<extension-id>/mappings/<mapping-id>.json
+```
+
+and validates against:
+
+```text
+docs/schemas/mapping-set.schema.json
+```
+
+The core does not embed domain policy. It only joins evidence `requirement_refs`
+to extension-owned mappings and writes normalized mapping records to:
+
+```text
+runs/<run-id>/normalized/mappings.json
+```
+
+## Expectations And Waivers
+
+Assessment profiles may reference expectation and waiver sets:
+
+```json
+{
+  "expectations_ref": "profiles/expectations/example.json",
+  "waivers_ref": "profiles/waivers/example.json"
+}
+```
+
+Expectation sets mark known posture as expected. Waiver sets mark approved,
+time-bounded exceptions. Both are applied after findings are generated, and the
+assessment package records policy summary counts.
+
+## 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.
+
+Artifact refs must be paths relative to the run directory. After runner
+execution, the core fingerprints existing artifact refs into the assessment
+package `artifact_manifest`.
+
+If a Python runner raises an exception, the core converts that failure into
+`infrastructure_error` evidence so the assessment package remains complete.
+
+Preflight runners are gates. If an extension preflight returns `fail`, `blocked`,
+or `infrastructure_error`, downstream check groups for that extension are not
+executed; they receive `blocked` evidence with `blocked_reason:
+preflight_failed`.
+
+## 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 normalizer plug-in contracts.
+- Add extension-owned schema validation for domain-specific target profile
+  fields.

docs/schemas/assessment-package.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Assessment Package",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "run_id",
+    "target",
+    "frameworks",
+    "extensions",
+    "source_lock",
+    "summary",
+    "mapping_summary",
+    "policy_summary",
+    "findings",
+    "evidence_refs",
+    "artifact_manifest",
+    "waivers",
+    "certification_boundary",
+    "created_at"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "run_id": { "type": "string" },
+    "target": { "type": "object" },
+    "frameworks": { "type": "array", "items": { "type": "object" } },
+    "extensions": { "type": "array", "items": { "type": "object" } },
+    "source_lock": { "type": "object" },
+    "summary": { "type": "object" },
+    "mapping_summary": { "type": "object" },
+    "policy_summary": { "type": "object" },
+    "findings": { "type": "array", "items": { "type": "object" } },
+    "evidence_refs": { "type": "array", "items": { "type": "string" } },
+    "artifact_manifest": { "type": "array", "items": { "type": "object" } },
+    "waivers": { "type": "array", "items": { "type": "object" } },
+    "certification_boundary": { "type": "string" },
+    "created_at": { "type": "string" }
+  }
+}

docs/schemas/assessment-profile.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Assessment Profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "framework_refs",
+    "extension_refs",
+    "target_profile_ref",
+    "selected_check_groups",
+    "expectations_ref",
+    "waivers_ref",
+    "output_policy",
+    "retention_policy"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "framework_refs": { "type": "array", "items": { "type": "string" } },
+    "extension_refs": { "type": "array", "items": { "type": "string" } },
+    "target_profile_ref": { "type": "string" },
+    "selected_check_groups": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string" }
+      }
+    },
+    "expectations_ref": { "type": ["string", "null"] },
+    "waivers_ref": { "type": ["string", "null"] },
+    "output_policy": { "type": "object" },
+    "retention_policy": { "type": "object" },
+    "runtime_policy": { "type": "object" }
+  }
+}

docs/schemas/authority.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Authority",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "name",
+    "authority_type",
+    "source_urls",
+    "frameworks",
+    "license_posture",
+    "access_constraints",
+    "certification_boundary",
+    "lifecycle_status"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "name": { "type": "string" },
+    "authority_type": { "type": "string" },
+    "source_urls": { "type": "array", "items": { "type": "string" } },
+    "frameworks": { "type": "array", "items": { "type": "string" } },
+    "license_posture": { "type": "string" },
+    "access_constraints": { "type": "string" },
+    "certification_boundary": { "type": "string" },
+    "lifecycle_status": { "type": "string" }
+  }
+}

docs/schemas/check-definition.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Check Definition",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "extension_id",
+    "check_type",
+    "framework_refs",
+    "requirement_refs",
+    "inputs",
+    "preconditions",
+    "timeout",
+    "runner_ref",
+    "expected_artifacts"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "extension_id": { "type": "string" },
+    "check_type": { "type": "string" },
+    "framework_refs": { "type": "array", "items": { "type": "string" } },
+    "requirement_refs": { "type": "array", "items": { "type": "string" } },
+    "inputs": { "type": "object" },
+    "preconditions": { "type": "array", "items": { "type": "string" } },
+    "timeout": { "type": "integer" },
+    "runner_ref": { "type": ["string", "null"] },
+    "expected_artifacts": { "type": "array", "items": { "type": "string" } }
+  }
+}

docs/schemas/evidence-item.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Evidence Item",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "run_id",
+    "extension_id",
+    "check_id",
+    "subject_ref",
+    "result",
+    "observations",
+    "facts",
+    "requirement_refs",
+    "artifact_refs",
+    "started_at",
+    "completed_at"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "run_id": { "type": "string" },
+    "extension_id": { "type": "string" },
+    "check_id": { "type": "string" },
+    "subject_ref": { "type": "string" },
+    "result": {
+      "type": "string",
+      "enum": [
+        "pass",
+        "fail",
+        "warning",
+        "manual",
+        "not_applicable",
+        "skipped",
+        "expected_gap",
+        "waiver_applied",
+        "unsupported_by_design",
+        "infrastructure_error",
+        "blocked",
+        "unknown"
+      ]
+    },
+    "observations": { "type": "array", "items": { "type": "string" } },
+    "facts": { "type": "object" },
+    "requirement_refs": { "type": "array", "items": { "type": "string" } },
+    "artifact_refs": { "type": "array", "items": { "type": "string" } },
+    "started_at": { "type": "string" },
+    "completed_at": { "type": "string" }
+  }
+}

docs/schemas/expectation-set.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Expectation Set",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "target_profile_ref",
+    "expectations"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "target_profile_ref": { "type": "string" },
+    "expectations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "requirement_refs",
+          "check_refs",
+          "result_refs",
+          "classification_refs",
+          "expected",
+          "reason",
+          "status"
+        ],
+        "properties": {
+          "id": { "type": "string" },
+          "requirement_refs": { "type": "array", "items": { "type": "string" } },
+          "check_refs": { "type": "array", "items": { "type": "string" } },
+          "result_refs": { "type": "array", "items": { "type": "string" } },
+          "classification_refs": { "type": "array", "items": { "type": "string" } },
+          "expected": { "type": "boolean" },
+          "reason": { "type": "string" },
+          "status": { "type": "string" }
+        }
+      }
+    }
+  }
+}

docs/schemas/extension-manifest.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Extension Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "name",
+    "version",
+    "extension_type",
+    "lifecycle_status",
+    "supported_frameworks",
+    "authorities",
+    "profile_schemas",
+    "check_groups",
+    "runner_entrypoints",
+    "normalizers",
+    "mappings",
+    "report_fragments",
+    "dependencies",
+    "restricted_assets",
+    "certification_boundary"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "extension_type": {
+      "type": "string",
+      "enum": [
+        "executable_harness",
+        "validator",
+        "protocol_service",
+        "hosted_suite",
+        "repository_quality",
+        "procedural_evidence",
+        "hybrid"
+      ]
+    },
+    "lifecycle_status": {
+      "type": "string",
+      "enum": ["candidate", "incubating", "active", "external", "deprecated"]
+    },
+    "supported_frameworks": { "type": "array", "items": { "type": "string" } },
+    "authorities": { "type": "array", "items": { "type": "string" } },
+    "profile_schemas": { "type": "array", "items": { "type": "string" } },
+    "check_groups": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "name", "check_type", "requirement_refs", "runner_ref"],
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "check_type": { "type": "string" },
+          "requirement_refs": { "type": "array", "items": { "type": "string" } },
+          "runner_ref": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "preflight_runner": { "type": ["string", "null"] },
+    "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" } },
+    "dependencies": { "type": "array", "items": { "type": "string" } },
+    "restricted_assets": { "type": "array", "items": { "type": "string" } },
+    "certification_boundary": { "type": "string" }
+  }
+}

docs/schemas/finding.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Finding",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "run_id",
+    "check_id",
+    "status",
+    "severity",
+    "classification",
+    "requirement_refs",
+    "evidence_refs",
+    "expected",
+    "waiver_ref",
+    "policy_ref",
+    "remediation"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "run_id": { "type": "string" },
+    "check_id": { "type": "string" },
+    "status": { "type": "string" },
+    "severity": { "type": "string" },
+    "classification": { "type": "string" },
+    "requirement_refs": { "type": "array", "items": { "type": "string" } },
+    "evidence_refs": { "type": "array", "items": { "type": "string" } },
+    "expected": { "type": "boolean" },
+    "waiver_ref": { "type": ["string", "null"] },
+    "policy_ref": { "type": ["string", "null"] },
+    "remediation": { "type": ["string", "null"] }
+  }
+}

docs/schemas/framework.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Framework",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "authority_id",
+    "name",
+    "version",
+    "status",
+    "source_urls",
+    "requirement_index",
+    "profile_index",
+    "license_posture"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "authority_id": { "type": "string" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "status": { "type": "string" },
+    "source_urls": { "type": "array", "items": { "type": "string" } },
+    "requirement_index": { "type": "array", "items": { "type": "string" } },
+    "profile_index": { "type": "array", "items": { "type": "string" } },
+    "license_posture": { "type": "string" }
+  }
+}

docs/schemas/gate-summary.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Gate Summary",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "created_at",
+    "trend_summary_ref",
+    "status",
+    "policy",
+    "group_count",
+    "passed_groups",
+    "failed_groups",
+    "groups"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "created_at": { "type": "string" },
+    "trend_summary_ref": { "type": "string" },
+    "status": { "type": "string" },
+    "policy": { "type": "object" },
+    "group_count": { "type": "integer" },
+    "passed_groups": { "type": "integer" },
+    "failed_groups": { "type": "integer" },
+    "groups": { "type": "array", "items": { "type": "object" } }
+  }
+}

docs/schemas/mapping-set.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Mapping Set",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "extension_id",
+    "framework_refs",
+    "mappings"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "extension_id": { "type": "string" },
+    "framework_refs": { "type": "array", "items": { "type": "string" } },
+    "mappings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "requirement_ref",
+          "target_type",
+          "target_id",
+          "label",
+          "description"
+        ],
+        "properties": {
+          "requirement_ref": { "type": "string" },
+          "target_type": { "type": "string" },
+          "target_id": { "type": "string" },
+          "label": { "type": "string" },
+          "description": { "type": "string" }
+        }
+      }
+    }
+  }
+}

docs/schemas/raw-artifact.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Raw Artifact",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "run_id",
+    "path",
+    "media_type",
+    "producer",
+    "checksum",
+    "created_at",
+    "retention_class"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "run_id": { "type": "string" },
+    "path": { "type": "string" },
+    "media_type": { "type": "string" },
+    "producer": { "type": "string" },
+    "checksum": { "type": "string" },
+    "created_at": { "type": "string" },
+    "retention_class": { "type": "string" }
+  }
+}

docs/schemas/retention-summary.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Retention Summary",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "run_id",
+    "target_profile_ref",
+    "assessment_profile_ref",
+    "created_at",
+    "summary",
+    "report_refs",
+    "artifact_retention"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "run_id": { "type": "string" },
+    "target_profile_ref": { "type": "string" },
+    "assessment_profile_ref": { "type": "string" },
+    "created_at": { "type": "string" },
+    "summary": { "type": "object" },
+    "report_refs": { "type": "array", "items": { "type": "string" } },
+    "artifact_retention": { "type": "object" }
+  }
+}

docs/schemas/run-plan.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Run Plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "assessment_profile_snapshot",
+    "target_profile_snapshot",
+    "extension_snapshots",
+    "source_lock",
+    "profile_paths",
+    "ordered_steps",
+    "credential_refs",
+    "artifact_policy",
+    "runtime_policy"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "assessment_profile_snapshot": { "type": "object" },
+    "target_profile_snapshot": { "type": "object" },
+    "extension_snapshots": { "type": "array", "items": { "type": "object" } },
+    "source_lock": { "type": "object" },
+    "profile_paths": { "type": "object" },
+    "ordered_steps": { "type": "array", "items": { "type": "object" } },
+    "credential_refs": { "type": "array", "items": { "type": "string" } },
+    "artifact_policy": { "type": "object" },
+    "runtime_policy": { "type": "object" }
+  }
+}

docs/schemas/target-profile.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Target Profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "subject_type",
+    "subject_name",
+    "environment",
+    "scope",
+    "endpoints",
+    "artifacts",
+    "credentials_ref",
+    "declared_capabilities",
+    "known_gaps"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "subject_type": { "type": "string" },
+    "subject_name": { "type": "string" },
+    "environment": { "type": "string" },
+    "scope": { "type": "array", "items": { "type": "string" } },
+    "endpoints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "url", "binding"],
+        "properties": {
+          "id": { "type": "string" },
+          "url": { "type": "string" },
+          "binding": { "type": "string" }
+        }
+      }
+    },
+    "artifacts": { "type": "array", "items": { "type": "string" } },
+    "credentials_ref": { "type": ["string", "null"] },
+    "declared_capabilities": { "type": "array", "items": { "type": "string" } },
+    "known_gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "requirement_refs", "reason", "status"],
+        "properties": {
+          "id": { "type": "string" },
+          "requirement_refs": { "type": "array", "items": { "type": "string" } },
+          "reason": { "type": "string" },
+          "status": { "type": "string" }
+        }
+      }
+    }
+  }
+}

docs/schemas/trend-summary.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Trend Summary",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "created_at",
+    "runs_dir",
+    "run_count",
+    "groups"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "created_at": { "type": "string" },
+    "runs_dir": { "type": "string" },
+    "run_count": { "type": "integer" },
+    "groups": { "type": "array", "items": { "type": "object" } }
+  }
+}

docs/schemas/waiver-set.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Waiver Set",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "target_profile_ref",
+    "waivers"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "target_profile_ref": { "type": "string" },
+    "waivers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "scope",
+          "requirement_refs",
+          "check_refs",
+          "result_refs",
+          "classification_refs",
+          "reason",
+          "owner",
+          "approved_by",
+          "created_at",
+          "expires_at",
+          "review_status"
+        ],
+        "properties": {
+          "id": { "type": "string" },
+          "scope": { "type": "string" },
+          "requirement_refs": { "type": "array", "items": { "type": "string" } },
+          "check_refs": { "type": "array", "items": { "type": "string" } },
+          "result_refs": { "type": "array", "items": { "type": "string" } },
+          "classification_refs": { "type": "array", "items": { "type": "string" } },
+          "reason": { "type": "string" },
+          "owner": { "type": "string" },
+          "approved_by": { "type": ["string", "null"] },
+          "created_at": { "type": "string" },
+          "expires_at": { "type": ["string", "null"] },
+          "review_status": { "type": "string" }
+        }
+      }
+    }
+  }
+}

docs/schemas/waiver.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guide Board Waiver",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "scope",
+    "requirement_refs",
+    "reason",
+    "owner",
+    "approved_by",
+    "created_at",
+    "expires_at",
+    "review_status"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "scope": { "type": "string" },
+    "requirement_refs": { "type": "array", "items": { "type": "string" } },
+    "reason": { "type": "string" },
+    "owner": { "type": "string" },
+    "approved_by": { "type": ["string", "null"] },
+    "created_at": { "type": "string" },
+    "expires_at": { "type": ["string", "null"] },
+    "review_status": { "type": "string" }
+  }
+}