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.