coulomb/guide-board
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refinement with workplans

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-15 23:04:11 +02:00
parent 4b3f65572f
commit d73a73b455
5 changed files with 474 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@@ -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)

121
workplans/GUIDE-BOARD-WP-0004-source-lock-and-submission-package-baseline.md Normal file
View File

@@ -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.

120
workplans/GUIDE-BOARD-WP-0005-challenge-and-exclusion-handling.md Normal file
View File

@@ -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.

114
workplans/GUIDE-BOARD-WP-0006-service-artifact-access-and-durable-run-index.md Normal file
View File

@@ -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.

115
workplans/GUIDE-BOARD-WP-0007-report-and-export-maturity.md Normal file
View File

@@ -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.