# Milestone 2 plan: persuasion-first vNext

Date: 2026-07-19
Status: complete and promoted; see `milestone_2_results.md`
Depends on: `docs/current/product_doctrine.md`
Rollback baseline: v2.6 workflow at Git tag `pre-build-week-clean-20260719`

## Outcome

Build and validate a bounded, deployment-compatible Chartsmith vNext that accepts
a chart image alone and autonomously returns one materially redesigned,
visually defect-free chart. GPT-5.6 must perform core multimodal and design
judgment, and the run artifacts must prove how it was used.

Milestone 2 is complete when the vertical slice works. It is not a general
optimization milestone and does not include the judge-facing web interface.

## Why this is a new workflow track

The v2.6 workflow was a valuable hardened baseline, but it was optimized
around conservative source-contract preservation. The newly agreed product
direction gives more weight to communication power, authored visual ideas, and
creative departure from the source while accepting small imperceptible
reconstruction error.

Editing v2.6 in place would blur the pre-Build-Week baseline and make failures
harder to diagnose. Milestone 2 will therefore:

- keep the canonical v2.6 configs and runner behavior intact during exploration;
- create an isolated workflow identified as `build_week_vnext`;
- avoid the name `v3`, which already refers to a superseded historical design;
- promote vNext to the active system only after the stop conditions pass.

The candidate artifact contract is `vnext-2026-07-19`. A workflow-version change
does not automatically require discarding compatible v2.6 artifacts.

Completion checkpoint (2026-07-19): all fixed live cases passed with GPT-5.6
provenance and vNext is promoted. Evidence and mechanism changes are recorded in
`milestone_2_results.md`.

## Architecture hypothesis

The first implementation should be the smallest workflow that expresses the
product doctrine:

1. **Perceptual reconstruction**
   - Read axes, labels, marks, relationships, uncertainty, and visible context
     from the image.
   - Record confidence and distinguish reliable structure from guessed detail.
   - Preserve the minimum epistemic-integrity floor without requiring raw data.

2. **Communication diagnosis**
   - Identify what a busy viewer sees first, what the chart appears to be trying
     to communicate, what is hard to perceive, and where the source is already
     effective.
   - Infer the strongest defensible message available in the image rather than
     treating the apparent source intent as unchangeable.

3. **Concept exploration**
   - Produce three materially different design concepts.
   - At least one concept should exploit a visual idea that is awkward to express
     as a conventional chart-library default.
   - Reject cosmetic variants and concepts whose novelty does not help the
     message.

4. **Concept selection and render contract**
   - Select one concept on communication potential, authorship, perceptual
     fidelity, and feasibility.
   - Convert it into an explicit render specification with geometry, hierarchy,
     text, spacing, and defect-risk checks.

5. **Rendering**
   - Choose the rendering mechanism that best fits the concept.
   - Permit generative imagery, deterministic drawing, or a hybrid. Do not force
     every concept through one medium.
   - Keep data-bearing geometry and typography under deterministic control when
     image generation cannot make them reliably clean.

6. **Rendered-image review and repair**
   - Inspect the actual image at full and embedded sizes.
   - Treat every production defect as a blocker.
   - Allow at most six targeted repair passes and one concept pivot in the
     bounded submission profile.

7. **Independent final comparison**
   - Compare source and final as communication artifacts, not only as data
     containers.
   - Release only when the final is materially more immediate, persuasive, and
     authored; perceptually faithful; and free of visible defects.

8. **One-result handoff**
   - Return one final image plus a concise summary of the design idea,
     reconstruction confidence, and checks performed.
   - Retain detailed artifacts for inspection without requiring the user to make
     another design decision.

## Initial execution bounds

The submission profile starts with:

- one input image and no required side information;
- three concept propositions;
- one selected concept rendered at a time;
- no more than six targeted repair passes;
- no more than one full concept pivot;
- one independent final evaluation;
- explicit termination with a failure artifact if no defect-free result can be
  produced within the bounds.

These are engineering defaults, not product preferences. The repair bound was
raised from two to six from live evidence and remains deterministic and recorded.

## Work packages

### 1. Contract and experiment isolation

- Create a vNext experiment area under `config/experiments/build_week_vnext/`.
- Define the execution plan, new artifact names, retained v2.6-compatible
  artifacts, iteration limits, and release decision.
- Record the experiment in `PROJECT_STATE.yaml` without changing the active
  workflow pointer.
- Keep an explicit active pointer so the isolated workflow path cannot be
  mistaken for an unpromoted experiment.

### 2. Invocation boundary and GPT-5.6 evidence

- Extract model execution behind a small invocation interface that supports the
  current local Codex route and a later hosted route.
- Keep prompts, images, model ID, reasoning configuration, timestamps, attempts,
  and completion status in run metadata.
- Route GPT-5.6 through the core perceptual reconstruction, concept judgment, and
  final visual review stages so its contribution is material rather than
  decorative.
- Validate failure and retry behavior without hiding partial artifacts.

### 3. Doctrine-aligned stages

- Implement the architecture hypothesis with the fewest distinct model calls
  that preserve clear contracts.
- Remove conservative language that makes source-grammar preservation the
  default outcome.
- Make a near-copy or generic library-style polish an explicit review failure.
- Preserve the minimum epistemic-integrity floor and confidence record.

### 4. Flexible rendering and production-integrity gate

- Make rendering medium a consequence of the selected concept.
- Add deterministic compositing or typography/geometry overlays where they
  materially improve reliability.
- Create a concrete production-defect checklist covering crop, overlap,
  annotation placement, margins, line wrapping, type, alignment, and embedded
  readability.
- Require the repair loop to name the exact defect and make a targeted change.

### 5. Small-case deep review

Use two deliberately contrasting development cases:

- **Case A: simple but visually ordinary** — exposes whether Chartsmith produces
  a genuinely authored communication idea rather than a polished near-copy.
- **Case B: structurally denser** — exposes whether image-only reconstruction,
  hierarchy, and creative authority remain coherent when the chart is harder to
  read.

Before promotion, add one challenge case whose source is already visually strong.
The purpose is not to reward returning it unchanged; it is to test whether
Chartsmith can add a meaningful idea without damaging what already works.

For each case, produce a compact review dossier containing:

1. first-read assessment of the source;
2. reconstruction facts, uncertainties, and confidence;
3. concepts considered and the selection argument;
4. source/final comparison at full and embedded sizes;
5. production-defect inspection;
6. the single largest remaining failure;
7. a mechanism-level explanation of why it happened;
8. one proposed workflow improvement;
9. the result on the originating and contrasting case;
10. keep, revise, or revert decision.

Do not start a broad corpus run. A score table may summarize judgment, but it
must not replace visual evidence or the causal diagnosis.

### 6. Promotion and handoff

- Run repository and workflow validation.
- Confirm the supported image-only command completes without user intervention.
- Confirm model provenance names GPT-5.6 in the artifacts.
- Confirm the final images pass full-size and embedded-size defect inspection.
- Record source/final evidence and the promotion rationale.
- Only then update the canonical workflow pointers, current architecture,
  operations, examples catalog, and changelog.

## Evaluation policy

### Hard gates

- input is an image with no required raw data or design prompt;
- the run is one-shot and terminates within its recorded bounds;
- output and required artifacts are present and openable;
- no visible production defect remains at either inspection size;
- no gross ranking, trend, sign, category, unit, or uncertainty error is visible;
- GPT-5.6 materially participated and is recorded;
- the final is not a cosmetic near-copy or generic default-chart restyle.

### Comparative judgment axes

- speed of comprehension;
- clarity of the primary message;
- persuasive force for a busy audience;
- visual hierarchy and attention control;
- design authorship and purposeful interestingness;
- fit between the visual idea and the subject;
- perceptual fidelity and honest handling of uncertainty;
- memorability;
- restraint: every added element earns its place.

These axes are comparative and continuous. Promotion depends on the whole visual
argument, not an arbitrary aggregate-score delta.

## Stop conditions

Milestone 2 succeeds when:

- the deployment-compatible vNext path accepts an image alone and autonomously
  returns one final chart;
- two contrasting development cases complete, and the challenge case is reviewed
  before promotion;
- each promoted example is materially more communicative and authored than its
  source, passes the epistemic floor, and has zero visible production defects;
- GPT-5.6 usage and bounded execution are evident in run artifacts;
- a fresh task can run the supported command from current documentation;
- vNext is either promoted with evidence or retained as an explicit no-go without
  disturbing the v2.6 baseline.

Stop and diagnose rather than expanding the batch if these conditions do not
pass. A failed concept is evidence for a focused mechanism change, not a reason
to restart gradient-style workflow search.

## Out of scope

- the judge-facing web application, which is Milestone 3;
- high-stakes numerical guarantees or mandatory raw-data ingestion;
- broad NodeBench or prompt-patch optimization;
- large stability corpora before the small cases are convincing;
- user-managed concept selection;
- repository-wide code packaging unrelated to the vertical slice.

## User-decision status

No additional product-preference input is required to begin. Codex owns the
technical choices inside this plan and should pause only if implementation
reveals a genuinely preference-sensitive fork or an external authority boundary.
