diff --git a/README.md b/README.md index f9a5da3..00e7f6b 100644 --- a/README.md +++ b/README.md @@ -64,3 +64,7 @@ See: - [workplans/GUIDE-BOARD-WP-0001-bootstrapping.md](workplans/GUIDE-BOARD-WP-0001-bootstrapping.md) - [workplans/GUIDE-BOARD-WP-0002-assessment-operations-baseline.md](workplans/GUIDE-BOARD-WP-0002-assessment-operations-baseline.md) - [workplans/GUIDE-BOARD-WP-0003-extension-sdk-maturity.md](workplans/GUIDE-BOARD-WP-0003-extension-sdk-maturity.md) +- [workplans/GUIDE-BOARD-WP-0004-source-lock-and-submission-package-baseline.md](workplans/GUIDE-BOARD-WP-0004-source-lock-and-submission-package-baseline.md) +- [workplans/GUIDE-BOARD-WP-0005-challenge-and-exclusion-handling.md](workplans/GUIDE-BOARD-WP-0005-challenge-and-exclusion-handling.md) +- [workplans/GUIDE-BOARD-WP-0006-service-artifact-access-and-durable-run-index.md](workplans/GUIDE-BOARD-WP-0006-service-artifact-access-and-durable-run-index.md) +- [workplans/GUIDE-BOARD-WP-0007-report-and-export-maturity.md](workplans/GUIDE-BOARD-WP-0007-report-and-export-maturity.md) diff --git a/workplans/GUIDE-BOARD-WP-0004-source-lock-and-submission-package-baseline.md b/workplans/GUIDE-BOARD-WP-0004-source-lock-and-submission-package-baseline.md new file mode 100644 index 0000000..d65e513 --- /dev/null +++ b/workplans/GUIDE-BOARD-WP-0004-source-lock-and-submission-package-baseline.md @@ -0,0 +1,121 @@ +--- +id: GUIDE-BOARD-WP-0004 +type: workplan +title: "Source Lock And Submission Package Baseline" +repo: guide-board +domain: markitect +status: active +owner: codex +planning_priority: high +planning_order: 4 +created: "2026-05-15" +updated: "2026-05-15" +state_hub_workstream_id: "6dd2832b-d1d9-43bc-ad5c-d16f399930dc" +--- + +# GUIDE-BOARD-WP-0004: Source Lock And Submission Package Baseline + +## Purpose + +Make guide-board assessment packages source-complete enough for serious review. +Runs already snapshot target and assessment profiles and preserve normalized +evidence. The next maturity layer is a stronger source lock and a submission +package manifest that records which framework, extension, harness, mapping, +profile, waiver, and artifact sources produced the assessment. + +## Background + +The architecture blueprint calls out source locking as part of credible +assessment evidence. A reviewer should be able to distinguish a normal local run +from a package that is ready to hand to another team, auditor, authority, or +certification-preparation process. This does not turn guide-board into a +certification body; it makes the evidence boundary clearer and more portable. + +## Boundary + +This workplan owns extension-neutral source lock fields and package manifest +generation. Extension-specific harness version detection, authority-specific +submission rules, and licensed or restricted assets remain extension-owned. + +## D4.1 - Source Lock Schema And Capture + +```task +id: GUIDE-BOARD-WP-0004-T001 +status: todo +priority: high +state_hub_task_id: "d5a7a18f-941b-47b8-9992-2cb54bc5ad06" +``` + +Acceptance: + +- Extend the source lock contract beyond framework and extension IDs. +- Capture stable references for framework versions, extension versions, mapping + sets, target profile snapshots, assessment profile snapshots, expectation + sets, waiver sets, and authority source URLs when available. +- Keep the schema backward-compatible with existing retained runs. +- Add tests for source lock shape and retained run compatibility. + +## D4.2 - Harness And Extension Metadata Hooks + +```task +id: GUIDE-BOARD-WP-0004-T002 +status: todo +priority: high +state_hub_task_id: "7abd5a66-5784-41b9-a361-6572290923cc" +``` + +Acceptance: + +- Define how extensions and runner or normalizer results can report harness + versions, test suite IDs, adapter versions, source URLs, and native result + identifiers. +- Persist this metadata in run plans, evidence facts, source locks, or package + manifests without inventing domain-specific fields in the core. +- Preserve current runner and normalizer contracts for extensions that do not + provide this metadata yet. +- Cover the SDK fixture and at least one no-metadata extension path in tests. + +## D4.3 - Submission Package Manifest + +```task +id: GUIDE-BOARD-WP-0004-T003 +status: todo +priority: medium +state_hub_task_id: "c54273d6-1fc2-4444-92cf-74f2a5e614ec" +``` + +Acceptance: + +- Add a machine-readable submission package manifest under each run report + directory. +- Include package identity, source lock references, report paths, normalized + evidence paths, artifact manifest entries, checksums where available, and the + certification boundary. +- Keep the manifest useful for both executable harnesses and procedural evidence + packs. +- Document how this differs from an authority-specific final submission. + +## D4.4 - Documentation And Acceptance Tests + +```task +id: GUIDE-BOARD-WP-0004-T004 +status: todo +priority: medium +state_hub_task_id: "ad37baeb-973c-4399-96d0-c9cb7fc6b761" +``` + +Acceptance: + +- Update assessment operations, extension SDK, and architecture docs with the + source lock and submission package contracts. +- Add tests that run a sample or SDK fixture assessment and assert the source + lock and manifest outputs. +- Include compatibility notes for older retained runs. +- Keep the output paths aligned with existing CLI and service result retrieval. + +## Definition Of Done + +- Every new run writes a richer source lock and submission package manifest. +- Extension-provided harness metadata has a stable path into the package. +- Older retained runs remain readable. +- Operators and extension authors know what the package can and cannot claim. diff --git a/workplans/GUIDE-BOARD-WP-0005-challenge-and-exclusion-handling.md b/workplans/GUIDE-BOARD-WP-0005-challenge-and-exclusion-handling.md new file mode 100644 index 0000000..719832f --- /dev/null +++ b/workplans/GUIDE-BOARD-WP-0005-challenge-and-exclusion-handling.md @@ -0,0 +1,120 @@ +--- +id: GUIDE-BOARD-WP-0005 +type: workplan +title: "Challenge And Exclusion Handling" +repo: guide-board +domain: markitect +status: active +owner: codex +planning_priority: high +planning_order: 5 +created: "2026-05-15" +updated: "2026-05-15" +state_hub_workstream_id: "fb11e1c7-6c0c-4ec7-a163-da98b2fe9f8f" +--- + +# GUIDE-BOARD-WP-0005: Challenge And Exclusion Handling + +## Purpose + +Represent authority exclusions, extension challenges, target expectations, +waivers, and defects as distinct review concepts. Guide-board already supports +expectations and waivers, but real assessments also need a way to record that a +test was excluded by an authority, challenged as invalid or mis-mapped, or +identified as a target defect. + +## Background + +Conformance work often includes dispute and exclusion paths. A failed check may +be a product issue, a harness issue, an unsupported optional feature, a known +waived risk, an authority-approved exclusion, or a local challenge awaiting +review. Reports need to make those distinctions visible instead of flattening +everything into pass, fail, blocked, or waived. + +## Boundary + +This workplan owns guide-board's generic challenge and exclusion model. It does +not decide authority-specific challenge rules, certification program policy, or +whether a challenge is valid. Extensions may provide authority-specific fields, +but the core should preserve them without embedding domain policy. + +## D5.1 - Challenge And Exclusion Data Contracts + +```task +id: GUIDE-BOARD-WP-0005-T001 +status: todo +priority: high +state_hub_task_id: "6ff4e6f7-bce6-4e7f-a5af-e0c67cfa7e55" +``` + +Acceptance: + +- Define schemas for authority exclusions and extension challenges. +- Distinguish challenge/exclusion records from expectations and waivers. +- Support links to requirement refs, check IDs, evidence IDs, authority source + refs, owners, review status, rationale, expiry or review dates, and native + challenge IDs where available. +- Keep the data contract usable by executable harnesses, hosted suites, and + procedural packs. + +## D5.2 - Policy Application And Finding Annotation + +```task +id: GUIDE-BOARD-WP-0005-T002 +status: todo +priority: high +state_hub_task_id: "fd384bd3-40c4-4344-8b7d-cb123dbf2cac" +``` + +Acceptance: + +- Load challenge and exclusion references from assessment profiles. +- Annotate findings and evidence with challenge or exclusion state without + silently hiding unexpected failures. +- Preserve separate counts for expected findings, waived findings, challenged + findings, authority exclusions, and unresolved defects. +- Add tests that prove challenge and exclusion records affect reporting without + corrupting gate semantics. + +## D5.3 - Report Visibility And Review Workflow + +```task +id: GUIDE-BOARD-WP-0005-T003 +status: todo +priority: medium +state_hub_task_id: "791071c0-8a9a-462b-83b3-75548bb8524f" +``` + +Acceptance: + +- Show challenge, exclusion, waiver, expectation, and defect distinctions in + Markdown and JSON assessment packages. +- Make unresolved review items easy to find in retained run summaries. +- Provide CLI history or report helpers that expose review state for the latest + run. +- Document how an operator should treat challenged or excluded findings. + +## D5.4 - Tests And Documentation + +```task +id: GUIDE-BOARD-WP-0005-T004 +status: todo +priority: medium +state_hub_task_id: "43b966da-af8d-479b-93bd-6b6741fdab37" +``` + +Acceptance: + +- Add schema tests and policy tests for challenges and exclusions. +- Add a sample or SDK fixture scenario that produces at least one challenged or + excluded finding. +- Update assessment operations, extension SDK, and compliance evidence pack docs. +- Keep certification boundary language explicit. + +## Definition Of Done + +- The core has separate, tested concepts for expectations, waivers, challenges, + authority exclusions, and defects. +- Reports surface those concepts without overstating certification conclusions. +- Retained summaries expose unresolved review work. +- Extension authors know how to supply authority-specific challenge metadata. diff --git a/workplans/GUIDE-BOARD-WP-0006-service-artifact-access-and-durable-run-index.md b/workplans/GUIDE-BOARD-WP-0006-service-artifact-access-and-durable-run-index.md new file mode 100644 index 0000000..33c01d6 --- /dev/null +++ b/workplans/GUIDE-BOARD-WP-0006-service-artifact-access-and-durable-run-index.md @@ -0,0 +1,114 @@ +--- +id: GUIDE-BOARD-WP-0006 +type: workplan +title: "Service Artifact Access And Durable Run Index" +repo: guide-board +domain: markitect +status: active +owner: codex +planning_priority: medium +planning_order: 6 +created: "2026-05-15" +updated: "2026-05-15" +state_hub_workstream_id: "ba008283-1631-467b-868e-1052c3870ab9" +--- + +# GUIDE-BOARD-WP-0006: Service Artifact Access And Durable Run Index + +## Purpose + +Move the local service beyond in-memory job visibility while preserving the CLI +as the execution source of truth. Operators and future UI clients should be able +to discover retained runs, retrieve reports, inspect artifacts, and recover +after service restarts without needing private knowledge of the run directory. + +## Background + +WP2 intentionally kept service job state in memory and documented run +directories as the durable source. That is a good baseline, but the service +already wraps run start, status, and report retrieval. The next step is to expose +the durable run history and artifact paths directly through service contracts. + +## Boundary + +This workplan owns local service API and durable run index behavior. It should +not change CLI run semantics, introduce a database dependency, or create a +distributed execution service. Any durable index must be reconstructable from +existing run artifacts. + +## D6.1 - Durable Run Index Design + +```task +id: GUIDE-BOARD-WP-0006-T001 +status: todo +priority: high +state_hub_task_id: "4d392fc5-6a1c-46f7-9cbf-6c02bbd744c6" +``` + +Acceptance: + +- Decide whether the service needs a separate durable index file or can rely on + retained run summaries with helper scans. +- Define reconstruction behavior after service restart. +- Preserve compatibility with existing `retention-summary.json` and run + directory layout. +- Document the operational tradeoff and failure modes. + +## D6.2 - Service Run History And Artifact Endpoints + +```task +id: GUIDE-BOARD-WP-0006-T002 +status: todo +priority: high +state_hub_task_id: "8f209920-6b14-4d6f-bfa1-8f1d03bcdbf1" +``` + +Acceptance: + +- Add service endpoints for retained run listing, latest run selection, report + path lookup, and artifact manifest access. +- Keep endpoint responses aligned with existing CLI `runs` commands. +- Avoid serving arbitrary filesystem paths outside configured run directories. +- Add tests for successful retrieval and path-safety failures. + +## D6.3 - Restart Recovery And Compatibility + +```task +id: GUIDE-BOARD-WP-0006-T003 +status: todo +priority: medium +state_hub_task_id: "0857e7d8-3d23-4426-b7fa-73362d7041a0" +``` + +Acceptance: + +- Prove that a service restart can still expose retained run reports and + artifacts. +- Keep in-memory job status semantics clear for currently running jobs. +- Add compatibility handling for older run directories that lack newer manifest + files. +- Update service durability documentation with examples. + +## D6.4 - Container And Service Acceptance Tests + +```task +id: GUIDE-BOARD-WP-0006-T004 +status: todo +priority: medium +state_hub_task_id: "900a70fa-65ff-4815-9c0c-31f0da4019f0" +``` + +Acceptance: + +- Add focused service tests for durable run lookup and artifact/report retrieval. +- Extend container or scripted acceptance to prove mounted run directories remain + readable through service contracts. +- Document service endpoint usage in local and container modes. +- Keep tests dependency-light. + +## Definition Of Done + +- The local service can expose retained runs and artifacts after restart. +- Endpoint behavior matches CLI run history semantics. +- Filesystem access is constrained to intended run outputs. +- Operators have documented recovery and artifact retrieval paths. diff --git a/workplans/GUIDE-BOARD-WP-0007-report-and-export-maturity.md b/workplans/GUIDE-BOARD-WP-0007-report-and-export-maturity.md new file mode 100644 index 0000000..771fd86 --- /dev/null +++ b/workplans/GUIDE-BOARD-WP-0007-report-and-export-maturity.md @@ -0,0 +1,115 @@ +--- +id: GUIDE-BOARD-WP-0007 +type: workplan +title: "Report And Export Maturity" +repo: guide-board +domain: markitect +status: active +owner: codex +planning_priority: medium +planning_order: 7 +created: "2026-05-15" +updated: "2026-05-15" +state_hub_workstream_id: "ef9351d2-e99c-470e-aeec-f17aa51eae14" +--- + +# GUIDE-BOARD-WP-0007: Report And Export Maturity + +## Purpose + +Improve guide-board's human and machine-readable reporting so assessment output +is easier to review, compare, and hand off. The current JSON assessment package +and Markdown report are useful baselines. The next layer should support +extension report fragments, portable export formats, and stronger trend and gate +summaries. + +## Background + +Real assessment consumers need different report surfaces. Engineers need concise +run feedback, product teams need readiness summaries, compliance reviewers need +traceable evidence and boundaries, and external systems may need portable JSON +or later OSCAL-style interchange. This workplan keeps those surfaces derived +from the same evidence package. + +## Boundary + +This workplan owns generic report and export mechanics. It does not implement +authority-specific final submission formats unless they can be represented as +extension-provided fragments or exporters. + +## D7.1 - Report Fragment Plug-in Contract + +```task +id: GUIDE-BOARD-WP-0007-T001 +status: todo +priority: high +state_hub_task_id: "bf3fe163-b06d-4c2e-9b45-31721864e1f2" +``` + +Acceptance: + +- Define how extensions declare Markdown or structured report fragments. +- Load fragments safely from extension roots and include them in run reports + without allowing arbitrary file access. +- Give fragments access to the assessment package, evidence, mappings, policy + summary, and source lock data. +- Add a fixture fragment and tests. + +## D7.2 - Portable Export Formats + +```task +id: GUIDE-BOARD-WP-0007-T002 +status: todo +priority: high +state_hub_task_id: "fda51e62-98aa-408e-a057-4db40fe7c644" +``` + +Acceptance: + +- Add one or more portable export outputs derived from the assessment package. +- Start with a stable JSON export manifest before considering OSCAL or other + external interchange formats. +- Preserve certification boundary and source lock references in each export. +- Document which exports are generic and which must remain extension-owned. + +## D7.3 - Trend And Gate Report Improvements + +```task +id: GUIDE-BOARD-WP-0007-T003 +status: todo +priority: medium +state_hub_task_id: "33c3089a-9d5e-4605-89c4-a1e070bc12ad" +``` + +Acceptance: + +- Improve retained trend and gate outputs for human review. +- Surface status changes, unexpected finding deltas, mapping target changes, and + unresolved review items. +- Keep machine-readable gate summaries stable for automation. +- Add CLI report helpers or Markdown summaries where useful. + +## D7.4 - Golden Fixtures And Documentation + +```task +id: GUIDE-BOARD-WP-0007-T004 +status: todo +priority: medium +state_hub_task_id: "66669f68-6728-4484-9ec9-267ffe025027" +``` + +Acceptance: + +- Add golden fixture outputs for reports and exports. +- Document report fragment and export authoring in the extension SDK. +- Update assessment operations with report/export retrieval examples. +- Ensure report text remains clear about preparation evidence versus formal + certification. + +## Definition Of Done + +- Extensions can contribute report fragments through a documented contract. +- The core emits portable export artifacts derived from the assessment package. +- Trend and gate summaries are more useful to humans without breaking + automation. +- Golden fixtures guard report and export shape.