http service with health, extension listing, profile validation, run planning, async run jobs, job inspection, and report retrieval

docs/COMPLIANCE-EVIDENCE-PACKS.md

@@ -0,0 +1,141 @@
+# Compliance Evidence Pack Strategy
+
+Status: draft
+Created: 2026-05-07
+
+## Purpose
+
+Compliance evidence packs cover frameworks where guide-board cannot rely on an
+official executable harness. They help prepare and perform assessments by
+organizing evidence requests, expected artifacts, reviewer workflow, waivers,
+and run reports. They do not replace auditors, accredited certification bodies,
+legal counsel, or official standard text.
+
+Examples include GDPR, SOC 2, HIPAA, NF Z 42-013, NF 461, ISO 14641, ISO 15489,
+and similar procedural or control-oriented frameworks.
+
+## Core Boundary
+
+Guide-board should keep four layers separate:
+
+- Official source metadata: authority, framework version, source URL, access
+  constraints, and citation references.
+- Internal interpretation: locally authored control themes, evidence request
+  wording, review roles, and acceptance criteria.
+- Target evidence: artifacts, attestations, screenshots, logs, policy files,
+  architecture documents, operational records, and interview notes.
+- Assessment result: normalized evidence, findings, waivers, trend summaries,
+  and quality gates.
+
+The core may store references to official clauses, controls, or articles, but it
+must not redistribute proprietary standard text. Extension authors are
+responsible for confirming source licensing and citation posture.
+
+## Extension Shape
+
+Compliance packs are ordinary extensions with `extension_type` set to
+`procedural_evidence` or `hybrid`.
+
+Recommended extension layout:
+
+```text
+<extension-id>/
+  INTENT.md
+  extension.json
+  evidence-requests/
+    <request-set-id>.json
+  mappings/
+    <mapping-set-id>.json
+  profiles/
+  reports/
+  workplans/
+```
+
+The manifest should declare:
+
+- framework IDs in `supported_frameworks`,
+- authority IDs in `authorities`,
+- manual or procedural `check_groups`,
+- mapping sets that map request requirement refs to controls or assessment
+  themes,
+- a certification boundary that states the pack is preparation support only.
+
+## Evidence Request Sets
+
+An evidence request set is a reviewable catalog of questions and artifacts. It
+validates against:
+
+```text
+docs/schemas/evidence-request-set.schema.json
+```
+
+Each request should include:
+
+- stable request ID,
+- requirement refs or internal control refs,
+- request type, such as document, interview, configuration sample, operational
+  record, attestation, system export, or mixed evidence,
+- requested artifact classes,
+- reviewer roles,
+- acceptance criteria,
+- confidentiality level,
+- renewal or freshness expectations.
+
+Requests should be phrased as collection guidance, not as legal conclusions.
+
+## Waivers And Expected Gaps
+
+Evidence packs use the same expectation and waiver model as executable
+extensions.
+
+Use expectations for:
+
+- not-applicable scope boundaries,
+- unsupported-by-design target posture,
+- evidence that is intentionally deferred until a later assessment phase.
+
+Use waivers for:
+
+- approved exceptions,
+- compensating-control situations,
+- temporary missing evidence,
+- auditor-reviewed deviations.
+
+Every waiver should include owner, reason, approval status, and expiry.
+
+## Framework Notes
+
+GDPR packs should emphasize processing inventory, lawful basis records, data
+subject rights, subprocessors, transfer posture, breach response, and privacy
+governance without providing legal advice.
+
+SOC 2 packs should organize evidence by trust-service criteria references,
+control ownership, system boundaries, change management, security operations,
+vendor management, and incident response.
+
+HIPAA packs should separate administrative, physical, and technical safeguard
+evidence from policy interpretation and should clearly mark protected-health
+information handling constraints.
+
+NF Z 42-013, NF 461, ISO 14641, and ISO 15489 packs should focus on records
+management, archival integrity, traceability, retention, reversibility,
+auditability, and governance evidence. Proprietary standard text should be
+referenced only by stable IDs or user-provided licensed material.
+
+## Output Model
+
+Compliance packs should produce the same guide-board outputs as harness
+extensions:
+
+- normalized evidence,
+- findings,
+- mapping records,
+- assessment packages,
+- retention summaries,
+- trend summaries,
+- gate summaries.
+
+Manual requests can initially result in `manual`, `blocked`, `not_applicable`,
+or `expected_gap` evidence. Later pack-specific runners may import spreadsheets,
+document inventories, ticket exports, cloud configuration snapshots, or auditor
+review files and normalize them into the same evidence model.