guide-board/workplans/GUIDE-BOARD-WP-0004-source-lock-and-submission-package-baseline.md

---
id: GUIDE-BOARD-WP-0004
type: workplan
title: "Source Lock And Submission Package Baseline"
repo: guide-board
domain: markitect
status: completed
owner: codex
planning_priority: high
planning_order: 4
created: "2026-05-15"
updated: "2026-05-16"
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: done
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.

Progress:

- Added `docs/schemas/source-lock.schema.json`.
- Expanded run-plan source locks with framework, extension, mapping-set,
  profile snapshot, policy-ref, authority, and metadata-hook records.
- Preserved the original `framework_refs` and `extension_refs` fields for
  retained-run compatibility.
- Added tests for source-lock shape and older retained summary compatibility.

## D4.2 - Harness And Extension Metadata Hooks

```task
id: GUIDE-BOARD-WP-0004-T002
status: done
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.

Progress:

- Added optional manifest metadata for extensions, authorities, frameworks,
  runner entrypoints, and normalizers.
- Preserved runner and normalizer returned `metadata` and requirement refs.
- Recorded merged metadata under evidence `facts.source_metadata`.
- Updated `sdk-fixture` to exercise harness, test-suite, adapter, source URL,
  and native result metadata while keeping `sample-noop` as a no-metadata path.

## D4.3 - Submission Package Manifest

```task
id: GUIDE-BOARD-WP-0004-T003
status: done
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.

Progress:

- Added `docs/schemas/submission-package.schema.json`.
- Wrote `reports/submission-package.json` for each run.
- Included package identity, source lock checksum, report paths, normalized
  output paths, profile snapshots, artifact manifest entries, reported
  metadata, and the certification boundary.
- Exposed the submission manifest path in CLI/service run results and retained
  report refs.

## D4.4 - Documentation And Acceptance Tests

```task
id: GUIDE-BOARD-WP-0004-T004
status: done
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.

Progress:

- Updated assessment operations, extension SDK, architecture blueprint, and
  README references.
- Added focused unit assertions for the sample and SDK fixture assessment
  outputs.
- Kept retained run listing compatible with older `retention-summary.json`
  files that do not reference a submission manifest.

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