generated from coulomb/repo-seed
342 lines
11 KiB
Markdown
342 lines
11 KiB
Markdown
---
|
|
id: GUIDE-BOARD-WP-0001
|
|
type: workplan
|
|
title: "Guide Board Bootstrapping"
|
|
repo: guide-board
|
|
domain: markitect
|
|
status: completed
|
|
owner: codex
|
|
planning_priority: high
|
|
planning_order: 1
|
|
created: "2026-05-07"
|
|
updated: "2026-05-15"
|
|
supersedes:
|
|
- "OPEN-CMIS-TCK-WP-0001"
|
|
state_hub_workstream_id: "1d812b7d-74f0-4d71-86a7-0f390b22daf7"
|
|
---
|
|
|
|
# GUIDE-BOARD-WP-0001: Guide Board Bootstrapping
|
|
|
|
## Purpose
|
|
|
|
Rename and reshape the repository from a CMIS-specific TCK harness into
|
|
`guide-board`: a certification and compliance preparation framework with
|
|
extension-based conformance and evidence packs.
|
|
|
|
The first concrete extension remains `open-cmis-tck`, but the root project now
|
|
owns the generic architecture for profiles, checks, evidence, mappings, waivers,
|
|
reports, retention, and eventual local/containerized operation.
|
|
|
|
## Background
|
|
|
|
The repository began as `open-cmis-tck`, a focused CMIS compatibility test
|
|
facility. That is still valuable, but the larger product opportunity is a
|
|
generic helper for standards enforcement, certification preparation, compliance
|
|
readiness, and repository quality management.
|
|
|
|
Comparable official or authority-backed conformance programs show recurring
|
|
patterns:
|
|
|
|
- a source authority and explicit framework version,
|
|
- a target or product profile,
|
|
- an executable harness, validator, protocol, or procedural test kit,
|
|
- setup and preflight requirements,
|
|
- raw artifacts and machine-readable results,
|
|
- conformance classes, profiles, controls, or requirement mappings,
|
|
- challenge, waiver, exclusion, or known-gap handling,
|
|
- a clear boundary between self-testing and formal certification.
|
|
|
|
`guide-board` should encode those patterns once, while letting extensions provide
|
|
domain-specific logic.
|
|
|
|
## Target Architecture
|
|
|
|
```text
|
|
authority catalog
|
|
-> extension registry
|
|
-> target profile
|
|
-> assessment profile
|
|
-> preflight checks
|
|
-> runner / validator / evidence collector
|
|
-> raw artifacts
|
|
-> normalized evidence
|
|
-> capability / control / requirement mapping
|
|
-> expectations and waivers
|
|
-> assessment package
|
|
-> reports and exports
|
|
-> retention and trend summaries
|
|
```
|
|
|
|
## Boundary
|
|
|
|
This project is a preparation and evidence framework. It does not issue
|
|
certifications, provide audit assurance, replace accredited assessors, replace
|
|
legal counsel, or redistribute restricted standards and test suites without a
|
|
license.
|
|
|
|
## D1.1 - Repository Identity
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T001
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "77559888-1601-4afb-8370-495365685e22"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Root `INTENT.md` identifies the project as `guide-board`.
|
|
- Root README introduces guide-board and points to the extension model.
|
|
- The old CMIS-only framing no longer controls the root project.
|
|
- Certification and audit boundaries are explicit.
|
|
|
|
## D1.2 - Extension Layout
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T002
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "555d6d5e-5d44-4c48-b409-b86bf5750bca"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- `extensions/open-cmis-tck/INTENT.md` exists.
|
|
- The CMIS workplan is moved under the extension.
|
|
- Extension docs can later be extracted into a separate repository.
|
|
- The root project remains extension-neutral.
|
|
|
|
## D1.3 - Candidate Harness Registry
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T003
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "35db0770-d081-464f-80a3-7fcb89efdca4"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- `extensions/CANDIDATES.md` registers important official or authority-backed
|
|
harness candidates.
|
|
- Candidates include CMIS/OpenCMIS, OGC TEAM Engine, OpenID Foundation
|
|
Conformance Suite, CNCF Kubernetes Conformance, web-platform-tests, Khronos
|
|
CTS, NIST ACVP, ONC/HL7 FHIR Inferno, Jakarta EE TCK, OPC UA CTT, NIST
|
|
SCAP/OpenSCAP, NIST OSCAL, CIS-CAT Pro, and OpenSSF Scorecard.
|
|
- Candidate notes capture authority, harness pattern, value, and access
|
|
constraints.
|
|
- Non-harness compliance packs are separated from executable conformance harness
|
|
candidates.
|
|
|
|
## D1.4 - Core Architecture Blueprint
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T004A
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "503cb054-e8a7-42e6-a171-e57c7188d835"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- `docs/ARCHITECTURE-BLUEPRINT.md` captures core concepts, precedent lessons,
|
|
component boundaries, extension archetypes, execution flow, run directory
|
|
contract, and governance model.
|
|
- The blueprint distinguishes executable harnesses, validators,
|
|
protocol-driven services, hosted suites, repository quality scanners, and
|
|
procedural evidence collectors.
|
|
- The blueprint names the next schema and CLI implementation sequence.
|
|
|
|
## D1.5 - Core Contract Schemas
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T004
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "a989702f-cc55-4751-8304-75ee2375f8ec"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Define schema drafts for authority metadata, extension manifests, target
|
|
profiles, assessment profiles, checks, evidence, findings, waivers, mappings,
|
|
reports, and retention summaries.
|
|
- Schemas distinguish executable harnesses, validators, protocol-driven services,
|
|
and procedural evidence collectors.
|
|
- Schemas include source URL, source version, harness version, license/access
|
|
posture, and certification boundary fields.
|
|
- Expectation and waiver set schemas support explicit policy application after
|
|
findings are generated.
|
|
|
|
## D1.6 - Local CLI Baseline
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T005
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "f22f8cc7-27f4-4377-bb61-3e4ac2040475"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Provide a local CLI entry point for listing extensions, validating profiles,
|
|
planning an assessment, running checks, and writing reports.
|
|
- CLI operation works before any service API is introduced.
|
|
- CLI can execute a no-op/sample extension to prove core contracts independent
|
|
of CMIS.
|
|
- The baseline executor writes the run directory contract, normalized evidence,
|
|
an assessment package, and a Markdown report.
|
|
- The assessment package includes a fingerprinted artifact manifest for
|
|
runner-emitted raw artifacts.
|
|
- The baseline executor applies expectation and waiver policy refs from
|
|
assessment profiles and reports policy summary counts.
|
|
- Failed extension preflight evidence gates downstream check groups so later
|
|
runners are not invoked against an invalid target posture.
|
|
|
|
## D1.7 - Extension SDK Skeleton
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T006
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "3c757929-a5e4-4c11-bbf1-6d7f26def93e"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Define how an extension declares metadata, supported frameworks, profile
|
|
schemas, check groups, runner commands, normalizers, and report fragments.
|
|
- Provide a minimal extension template.
|
|
- Extension ownership boundaries make later extraction to a separate repository
|
|
straightforward.
|
|
- Python module runner contracts are documented in `docs/EXTENSION-SDK.md`.
|
|
- Manifest-declared command runners execute without shell expansion and return
|
|
normalized evidence through the same runner result contract.
|
|
- Runner artifact refs are constrained to the run directory and fingerprinted in
|
|
the assessment package artifact manifest.
|
|
- Extension-owned mapping sets connect evidence requirement refs to capability,
|
|
control, conformance, or quality targets.
|
|
|
|
## D1.8 - CMIS Seed Extension Integration
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T007
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "455f92b0-1d2b-43d0-aa61-464d9dc83a62"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- `open-cmis-tck` runs through the guide-board core contracts rather than a
|
|
bespoke root-level harness.
|
|
- CMIS output normalizes into the same evidence model used by other extensions.
|
|
- CMIS capability mappings are extension-owned.
|
|
|
|
Progress:
|
|
|
|
- `open-cmis-tck` declares runner entry points through `extension.json`.
|
|
- The CMIS Browser Binding preflight runner executes through the generic runner
|
|
bridge and produces normalized evidence.
|
|
- The OpenCMIS Java/Maven TCK wrapper executes through the command runner bridge
|
|
and currently reports dependency or configuration blockers as structured
|
|
evidence.
|
|
- CMIS requirement refs map to extension-owned capability groups in
|
|
`normalized/mappings.json` and the Markdown report.
|
|
- The core now supports external extension repositories via `--extension-dir`
|
|
and `GUIDE_BOARD_EXTENSION_PATHS`; `open-cmis-tck` has been split into its own
|
|
extension repo.
|
|
- Split-repo guide-board CLI discovery, planning, and run smoke tests work with
|
|
`open-cmis-tck` as an external extension.
|
|
|
|
## D1.9 - Containerized Execution Design
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T008
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "21e5c1e0-b02e-408d-a657-1771750e9b30"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Document a container model that mounts profiles, extension data, credentials,
|
|
and output directories explicitly.
|
|
- Runner images can include extension dependencies without polluting the core.
|
|
- Restricted or license-gated harnesses are represented as mounted external
|
|
assets, not redistributed guide-board content.
|
|
|
|
Progress:
|
|
|
|
- Added a dependency-light `guide-board-core` `Containerfile`.
|
|
- Added `.dockerignore` to keep local run outputs and development artifacts out
|
|
of the image build context.
|
|
- Added `docs/CONTAINER.md` with mount contracts for profiles, credentials,
|
|
runs, and restricted harness assets.
|
|
- Documented the extension-specific image path for CMIS Java/Maven/OpenCMIS TCK
|
|
dependencies.
|
|
|
|
## D1.10 - Optional Local Service API
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T009
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "58bd6ec6-2cf3-450f-95a7-b695aaf80609"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- A local API can list extensions, validate profiles, start assessment runs,
|
|
inspect run status, and fetch reports.
|
|
- Long-running jobs are tracked without blocking the API process.
|
|
- CLI remains the source of truth for execution semantics.
|
|
|
|
Progress:
|
|
|
|
- Added dependency-light local HTTP service module and `guide-board serve`.
|
|
- Added endpoints for health, extension listing, profile validation, planning,
|
|
asynchronous run jobs, job inspection, and report retrieval.
|
|
- Documented service and container modes in `docs/LOCAL-SERVICE-API.md` and
|
|
`docs/CONTAINER.md`.
|
|
- Added lifecycle tests that start the API, run the sample assessment as a
|
|
background job, and fetch generated reports.
|
|
|
|
## D1.11 - Compliance Evidence Pack Strategy
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0001-T010
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "2f845860-ade9-4d31-91c7-cb1c69dc4e1b"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Define how non-harness frameworks such as GDPR, SOC 2, HIPAA, NF Z 42-013,
|
|
NF 461, ISO 14641, and ISO 15489 should be represented.
|
|
- Separate official source metadata from internal interpretation.
|
|
- Avoid redistributing proprietary standard text.
|
|
- Provide a reviewable evidence-request and waiver model suitable for auditor
|
|
collaboration.
|
|
|
|
Progress:
|
|
|
|
- Added `docs/COMPLIANCE-EVIDENCE-PACKS.md`.
|
|
- Added `docs/schemas/evidence-request-set.schema.json`.
|
|
- Added `extensions/_template/evidence-request-set.json`.
|
|
- Documented evidence request sets in the extension SDK and architecture
|
|
blueprint.
|
|
|
|
## Definition Of Done
|
|
|
|
- The repository identity is `guide-board`.
|
|
- CMIS is represented as the first extension, not the root product.
|
|
- The root architecture is broad enough for official conformance harnesses and
|
|
procedural evidence packs.
|
|
- The root architecture blueprint is documented and linked from README.
|
|
- At least one extension can be run through local CLI contracts.
|
|
- Candidate extensions are registered with authority, source, access, and
|
|
architecture notes.
|
|
- The project has a clear path from local baseline to containerized service.
|