guide-board/INTENT.md

INTENT

Project Name

guide-board

Purpose

guide-board is a certification and compliance preparation framework. It helps teams turn claims about standards support, regulatory posture, and repository quality into structured evidence that can be reviewed, repeated, compared, and used during assessments.

The project provides the core evidence model, orchestration contracts, extension layout, and reporting surface. Domain-specific standards, regulations, and conformance tools live in extensions. An extension may wrap an executable test harness, validate machine-readable artifacts, guide procedural evidence collection, or combine several of those approaches.

The first extension is open-cmis-tck, which packages CMIS compatibility testing around Apache Chemistry OpenCMIS TCK execution. It is the first concrete use case, not the boundary of the project.

guide-board does not issue certifications, provide audit assurance, replace legal counsel, or act as a certification body. It supports preparation and execution by making evidence, assumptions, gaps, and mappings explicit.

Product Thesis

Compliance work is useful when it is evidence-driven, source-aware, and honest about uncertainty. A team should be able to say what it claims, which authority or standard that claim comes from, what evidence supports it, which gaps are known, which checks were not applicable, and which conclusions still require human or accredited review.

guide-board exists to make that process repeatable.

Primary Use Case

Given a target system or repository, a selected assessment profile, and one or more extensions, guide-board should:

1. load target and assessment profile configuration,
2. resolve the relevant extension and authority metadata,
3. run preflight checks before expensive or regulated checks,
4. execute harnesses, validators, or evidence collection steps,
5. preserve raw artifacts where useful,
6. normalize results into a stable evidence model,
7. map evidence to capabilities, controls, conformance classes, or requirements,
8. distinguish pass, fail, expected gap, waiver, unsupported by design, and infrastructure error,
9. write compact JSON and Markdown assessment reports,
10. retain run summaries for comparison over time.

Intended Users

• Engineering teams preparing technical conformance evidence.
• Product owners tracking certification and compliance readiness.
• Compliance and quality teams coordinating evidence across repositories.
• Integration teams validating customer or partner systems against declared standards.
• Automated agents that need structured evidence before changing scorecards, release gates, or repository quality posture.

Core Concepts

• Authority: the standards body, regulator, certification program, or project that defines requirements or tests.
• Framework: a named standard, regulation, profile, certification program, or quality policy.
• Extension: a domain-specific package that knows how to gather and normalize evidence for one framework or family of frameworks.
• Target profile: the system, repository, service, artifact, or process being assessed.
• Check: an executable, validator, probe, manual evidence request, or procedural step.
• Evidence: raw and normalized material produced by a check.
• Mapping: the relationship between evidence and a capability, control, conformance class, requirement, or scorecard dimension.
• Expectation: a declared posture for an optional capability, known gap, accepted risk, or unsupported-by-design feature.
• Waiver: a time-bounded and reviewable exception that prevents expected gaps from hiding unexpected failures.
• Assessment package: the normalized result set, human report, source metadata, raw artifact pointers, and decision boundary.

Extension Model

Extensions live under extensions/<extension-id>/ while incubating in this repository. Each extension should have its own INTENT.md so it can later become a separate repository without losing product boundaries.

An extension may provide:

• source and authority metadata,
• target profile schemas,
• harness installation notes,
• preflight probes,
• runners or validator adapters,
• normalization rules,
• control or capability mappings,
• report fragments,
• workplans,
• sample profiles and fixtures.

The core must stay extension-neutral. It should know how to orchestrate, normalize, map, retain, and report evidence, but it should not embed CMIS, healthcare, identity, geospatial, cryptographic, privacy, or records-management policy directly.

Scope

In scope:

• extension registry and lifecycle,
• target and assessment profile contracts,
• authority and source metadata,
• check orchestration,
• local CLI-first execution,
• optional service API for local or containerized operation,
• normalized evidence, finding, waiver, and report schemas,
• compact historical result retention,
• extension adapters for official or widely used conformance harnesses,
• procedural evidence packs for frameworks that do not have official executable test harnesses.

Out of scope:

• issuing certifications,
• claiming audit assurance,
• replacing accredited certification bodies or qualified auditors,
• replacing legal, privacy, security, or records-management counsel,
• redistributing proprietary standards text or restricted test suites without a license,
• hiding source/version uncertainty,
• embedding target-project domain knowledge in the core.

First Extension

The first extension is extensions/open-cmis-tck/.

It should wrap selected Apache Chemistry OpenCMIS TCK checks against a configured CMIS Browser Binding endpoint, normalize the output, map results to CMIS capability groups, and produce guide-board-compatible evidence reports.

Initial Candidate Families

Initial candidate extensions are registered in extensions/CANDIDATES.md. They include official or authority-backed conformance harness patterns from OGC, the OpenID Foundation, CNCF Kubernetes, W3C/WHATWG 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, OpenSSF Scorecard, and CMIS/OpenCMIS.

The point of studying these candidates is not to implement everything at once. It is to make the core architecture fit the real shapes of conformance work: profile selection, source versioning, harness setup, raw artifact retention, normalization, requirement mapping, challenge/waiver handling, and certification submission boundaries.

Success Criteria

guide-board is useful when it can:

• run from a clean checkout with a documented local baseline,
• register extensions without changing core code,
• run at least one extension end to end,
• preserve raw evidence without making raw logs the primary interface,
• produce compact machine-readable and human-readable reports,
• identify expected gaps separately from unexpected failures,
• track authority names, framework versions, harness versions, and source links,
• support later containerized execution without changing assessment contracts,
• help teams prepare for certifications and compliance assessments without overstating what the tool itself can certify.

Design Principles

• Keep the core small, boring, and extension-neutral.
• Treat official source metadata as part of the evidence.
• Make unsupported or untested areas explicit.
• Prefer local, inspectable execution before distributed service operation.
• Preserve raw artifacts by reference, not as the main product interface.
• Separate evidence collection from certification conclusions.
• Design for both executable harnesses and procedural compliance evidence.
• Make later extension extraction to separate repositories straightforward.