claw/docs/superpowers/specs/2026-04-19-boundary-family-real-sample-entry-roadmap-design.md

Boundary Family Real-Sample Entry Roadmap Design

Date: 2026-04-19 Status: Draft Upstream Validation Layer: real_sample_validation_records_2026-04-18.json Upstream Entry Rules: boundary_runtime_entry_rules_2026-04-18.json

1. Intent

This design defines the next bounded roadmap after the mainline real-sample anchors are closed.

The current mainline state is:

1. G1-E = executed-pass
2. G2 = executed-pass
3. G3 = executed-pass

So the next roadmap should not reopen mainline contract correction.

The next bounded question is narrower:

Which boundary family, if any, is allowed to enter real-sample execution scope next?

2. Problem Statement

The repo already has boundary families established at the fixture and family-asset layer:

1. G6 = host_bridge_workflow
2. G7 = multi_endpoint_inventory
3. G8 = local_doc_pipeline

But none of them has been promoted into real-sample execution scope.

At this point the strongest risk is not lack of family assets.

It is lack of a bounded admission rule for moving a boundary family from:

1. hold-as-boundary

to:

2. real-sample-entry-candidate

Without a dedicated roadmap, any next step is likely to drift into:

1. accidental boundary implementation
2. premature runtime-platform work
3. reopening deferred families

3. Scope Boundary

This roadmap is limited to boundary-family entry decision work.

It may include:

1. comparing G6 / G7 / G8 against explicit real-sample entry criteria
2. selecting at most one boundary family as the next execution candidate
3. producing a bounded recommendation and follow-up plan

It must not include:

1. implementing new runtime-platform capabilities
2. executing a real sample for more than one boundary family
3. opening G4 / G5
4. reopening G1-E / G2 / G3
5. broadening into a new all-family migration program

4. Current Decision Inputs

The current repo state already gives the key decision inputs:

1. G6 requires host-bridge execution semantics beyond repo-local coverage
2. G7 requires real multi-endpoint aggregation verification
3. G8 requires local document pipeline runtime and attachment handling

These are not implementation tasks yet.

They are admission constraints.

5. Roadmap Goal

The goal of this roadmap is not to make a boundary family pass immediately.

The goal is to produce one bounded and defensible next execution target:

1. select exactly one next boundary family
2. explain why it is first
3. explain why the other two remain held
4. define the minimum real-sample entry slice for the selected family

6. Preferred Outcome

The preferred outcome is:

1. one selected boundary family
2. one bounded real-sample execution plan for that family
3. the other boundary families explicitly remain hold-as-boundary

An acceptable fallback outcome is:

1. no boundary family is admitted yet
2. a new bounded roadmap is required for runtime-platform prerequisites first

7. Acceptance Logic

This roadmap is successful when:

1. the next post-mainline step is no longer ambiguous
2. only one next-family direction is opened
3. boundary-family expansion pressure is kept bounded
4. deferred families remain untouched

8. Out of Scope

The following are explicitly out of scope:

1. new scene-generator family work
2. new canonical answers
3. new mainline contract correction
4. login recovery implementation
5. host runtime or transport implementation beyond decision-level scoping