# Milestone 4 Execution Plan

Status: complete
Authority: `BUILD_WEEK_PLAN.md`
Portfolio manifest: `config/experiments/build_week_vnext/milestone4_portfolio.yaml`

## Objective

Produce a judge-ready portfolio of ten distinct chart-image redesign journeys.
The portfolio must demonstrate range, not ten variations of one source. Every
counted example must be an accepted run of the promoted image-only, one-shot
workflow and must retain inspectable provenance, configuration, output, and
validation evidence.

Milestone 4 does not include public deployment or submission packaging. Those
remain Milestone 5 decisions.

## Portfolio Design

The ten-example target is:

1. three accepted Milestone 2 cases that already cover an ordinary chart, a
   dense chart, and an already-strong chart;
2. seven self-created synthetic sources spanning line, grouped-bar, heatmap,
   bubble-scatter, interval, funnel, and stacked-area grammars.

The Milestone 3 live-product run is valid product evidence but does not count as
an additional portfolio example because it repeats the first Milestone 2 source.

The seven new sources are generated deterministically by
`scripts/generate_milestone4_sources.py`. Each source has:

- the rendered image supplied to Chartsmith;
- the exact synthetic source data;
- a source-provenance record;
- an explicit CC0-1.0 release status; and
- a statement that the workflow receives the image alone.

The first three cases remain attributed official public figures. They retain
their source URLs and third-party attribution status rather than being
misrepresented as project-owned assets.

## Acceptance Contract

An example counts only when all of the following are true:

- the source image is distinct from every other counted source;
- the run manifest says `accepted`;
- the input and interaction contracts are `chart_image_only` and
  `one_shot_autonomous`;
- the native vNext completed-run validator passes;
- the final GPT-5.6 evaluation accepts all five release gates:
  production integrity, epistemic integrity, material communication gain,
  design authorship, and GPT-5.6 judgment provenance;
- no blocking issue remains;
- source, configuration, output, and evaluation evidence are packaged in the
  curated example directory; and
- full-size and portfolio-level visual QA reveal no clipping, overlap,
  malformed text, broken geometry, or other visible production defect.

`scripts/validate_milestone4_portfolio.py` makes this contract executable.
Counting directories or successful process exit codes is not sufficient.

## Execution Strategy

Runs are scheduled deterministically with no more than two concurrent cases.
The workflow retains its bounded review, repair, pivot, and final-evaluation
rules. A weak output is repaired, rejected, or replaced; it is never promoted
merely to reach the numerical target.

Failed attempts remain under `runs/build_week/vnext/` as evidence. A replacement
run receives a new ID, and the portfolio manifest points only to the accepted
run. Recoverable image-generation or exhausted-repair failures may be resumed
in place; workflow-contract failures are diagnosed before a clean rerun.

The reusable scheduler is `scripts/run_milestone4_portfolio.py`. It preserves
per-case logs and orchestration state under the ignored run archive.

## Evidence Packaging

`scripts/curate_milestone4_portfolio.py` creates a small tracked package for each
accepted case containing:

- input, final, and side-by-side comparison images;
- perceptual reconstruction and concept-selection artifacts;
- final evaluation and review dossier;
- run manifest and model provenance;
- source data/provenance for synthetic cases; and
- an `example_manifest.json` with source and workflow hashes, rights status,
  run identity, repairs, and release-gate outcomes.

The aggregate
`examples/build_week_vnext/portfolio_manifest.json` is the portfolio index.

## Product Integration

The judge-facing product must expose all ten examples as immediate, complete
journeys. Product metadata is projected from the authoritative portfolio
manifest rather than maintained as a separate hardcoded list. The existing
single-call comparison remains differentiation evidence but is not counted
among the ten redesigned sources.

The selector must remain legible at desktop, tablet, and mobile sizes. Each
example continues to use the same projector and presentation contract as a live
upload; curated cases do not receive a handcrafted presentation path.

## Validation and Stop Condition

Milestone 4 is complete only after:

1. the portfolio validator reports `10/10`;
2. all ten curated packages exist and the aggregate manifest reports complete;
3. all ten examples project and build in the product;
4. a visual contact sheet and responsive product QA show no visible defect;
5. current docs, project state, handoff, catalog, changelog, and completion
   manifest agree on the same ten examples; and
6. the repository checkpoint is committed with no unintended working-tree
   changes.
