workspace-hub-mission-contract-first-packet

# Workspace-Hub Mission Contract — First Packet Pattern

Use this when the user wants to revise repo missions across the workspace ecosystem and approve them one by one.

## When to use
- User asks for repo mission analysis across multiple repos
- User wants a repo-by-repo approval sequence
- You need a first approval packet before touching downstream repo missions
- The work touches llm-wiki architecture but must not prematurely decide embedded vs spinout boundaries

## Core pattern
1. Start with `workspace-hub`, not downstream repos.
2. Before creating a new GitHub issue, search for an existing open parent issue covering the control-plane / ecosystem contract.
3. If `#1525` (`Define canonical repo control-plane contract across workspace ecosystem`) is still open, reuse it instead of creating a duplicate mission issue.
4. Draft the local plan under `docs/plans/` and add the row to `docs/plans/README.md`.
5. Run adversarial review before surfacing for approval.
6. Expect the first draft to fail if verification is subjective; tighten it into deterministic checks.

## Recommended Wave-1 scope
Lock the first packet to:
- `workspace-hub` = control plane
- `digitalmodel` = engineering computation core
- `assetutilities` = shared utility substrate
- `aceengineer-website` = GTM / externalization layer

Explicitly defer `worldenergydata` to Wave 2 unless the plan intentionally expands scope.

## Critical review hardening learned in practice
Cross-provider reviewers objected to these weak patterns:
- subjective tests like “docs use consistent terminology”
- llm-wiki neutrality stated only as intent
- mixed in-scope / deferred downstream repo language
- unverified supporting report references

Fix them before trying to get approval:

### 1. Make verification deterministic
Add a concrete validation artifact, e.g.:
- `scripts/validation/check_workspace_hub_mission_contract.py`

That validator should check required / forbidden phrases across the reconciled mission docs.

### 2. Use a literal llm-wiki neutrality guardrail
Require the exact phrase:
- `repo-boundary architecture remains under evaluation per #2398`

Also forbid wording that declares llm-wiki permanently embedded or spun out.

### 3. Verify every cited local input artifact
If the plan cites a supporting report like:
- `docs/reports/2026-04-21-repo-mission-revision-sequence.md`

include it in the embedded evidence block as EXISTS.

### 4. Keep artifact map unambiguous
If one report contains multiple sections (mission contract, downstream role map, glossary, llm-wiki guardrails), list it as one artifact with named sections, not multiple artifacts pointing to the same file.

## First-packet files usually in scope
- `README.md`
- `docs/README.md`
- `docs/BUSINESS_BRAIN.md`
- `docs/WORKSPACE_HUB_REPOSITORY_OVERVIEW.md`
- new canonical report such as `docs/reports/workspace-hub-mission-contract.md`
- validator such as `scripts/validation/check_workspace_hub_mission_contract.py`

## Recommended acceptance criteria shape
Include all of these explicitly:
- canonical mission contract file exists
- deterministic validation script exists
- reconciled docs pass the validator
- `workspace-hub` control-plane role is explicit
- `digitalmodel`, `assetutilities`, and `aceengineer-website` roles are explicit
- `worldenergydata` is explicitly deferred if not in scope
- literal `#2398` neutrality phrase is present
- non-goals are explicit
- `docs/plans/README.md` row exists
- review artifacts exist

## Operational note
If the first review wave returns mixed results like Codex/Codex MAJOR and Gemini APPROVE, do not surface the plan as approval-ready. Patch the plan immediately, update the `## Adversarial Review Summary`, and rerun cross-review.