# Milestone 3 executable plan

Date: 2026-07-19
Status: completed locally; see `milestone_3_results.md`
Depends on: promoted Milestone 2 `build_week_vnext`
Product brief: `milestone_3_product_brief.md`

## Objective

Build the judge-facing product surface for Chartsmith without redesigning the
promoted core workflow.

A first-time judge must be able to understand the product immediately, explore
complete examples without waiting, upload a real chart, follow meaningful
intermediate results during a long run, and inspect one final redesign without
repository knowledge.

## Stop condition

Milestone 3 is complete when:

- an immediate curated-example path demonstrates the source, intermediate work,
  final result, and Chartsmith's value;
- a chart-image upload starts a genuine one-shot workflow;
- validated stage artifacts appear progressively as polished user-facing
  presentations;
- a user can leave and return to an in-progress or completed run;
- the final screen clearly demonstrates communication gain and production
  integrity;
- at least one honest single-call baseline comparison provides evidence for the
  system's additional value;
- failure, resume, and long-running states are understandable and recoverable;
- the application passes functional, visual, accessibility, and fresh-setup
  validation in the selected deployment environment.

Submission packaging and public publication may follow in a separate milestone
or finalization pass. Public deployment requires the deferred authority
decisions recorded in the product brief.

## Fixed product decisions

- Image-only input remains fully supported.
- One run returns one authored result and asks for no design decisions.
- The source/final transformation is the primary visual story.
- Progress exposes meaningful intermediate results, not only stage names.
- Intermediate content is written and designed for users; canonical machine
  artifacts remain behind the presentation layer.
- Curated examples include their intermediate journeys and load immediately.
- The result explanation is confident, concise, and honest about meaningful
  uncertainty.
- Detailed provenance and review evidence are inspectable but secondary.
- The promoted workflow and release gates remain the execution authority.

## System boundary

Milestone 3 adds a product layer around the existing runner:

```text
browser
  -> product UI
  -> application API
  -> durable run/job controller
  -> promoted Chartsmith runner and model invocation boundary
  -> canonical run artifacts
  -> artifact projector
  -> user-facing stage events and result views
```

The product layer must not create an alternative redesign workflow. A UI status
is derived from a validated canonical artifact or explicit runner state.

### Responsibilities

**Product UI**

- upload validation and source preview;
- immediate examples;
- run timeline and current activity;
- stage presentation cards;
- candidate and repair images;
- final source/redesign comparison;
- recoverable failure and resume states;
- expandable evidence and provenance.

**Application API and job controller**

- create stable run IDs;
- accept safe image uploads;
- launch at most the configured amount of work;
- persist state independently of a browser connection;
- expose completed stages and new events;
- resume or report interrupted runs;
- prevent duplicate launches and unbounded model cost;
- never expose secrets, local paths, or raw internal exceptions.

**Artifact projector**

- read contracted Milestone 2 artifacts without modifying them;
- convert them into a stable, versioned presentation model;
- summarize machine fields in user-facing language;
- attach only artifacts that have completed validation;
- distinguish inferred information, uncertainty, review findings, and final
  release status;
- support both live runs and curated examples through the same presentation
  contract.

**Promoted workflow**

- remain authoritative for reconstruction, concepts, rendering, review, repair,
  final evaluation, and provenance;
- continue writing canonical artifacts under its artifact contract;
- expose progress through artifact completion or a minimal event adapter;
- change only when an integration defect prevents safe product use.

## User-facing stage contract

The application should use a small stable vocabulary independent of internal
file names:

1. `received`
2. `understanding`
3. `exploring`
4. `rendering`
5. `inspecting`
6. `repairing` when required
7. `finalizing`
8. `complete`, `needs_attention`, or `failed`

Each stage event should contain:

- stable run and stage identifiers;
- state and completion timestamp;
- user-facing title and short narrative;
- validated presentation data;
- zero or more safe image/artifact references;
- whether additional work is in progress;
- an optional recovery action.

Raw prompts, model responses, JSON paths, tokens, stack traces, and machine-local
paths are excluded from the default contract.

## Work packages

### 1. Preflight and architecture freeze

- Verify which existing runner boundaries can emit progress without changing
  workflow semantics.
- Verify hosted GPT-5.6 and GPT Image invocation options, runtime requirements,
  expected costs, concurrency, and timeout constraints.
- Select the smallest deployment-compatible frontend, API, worker, and durable
  state architecture.
- Record the deployment decision and its evidence before implementation.
- Keep the choice reversible until authority and hosting constraints are known.

Exit: one documented architecture, threat boundary, dependency list, and local
development command.

### 2. Presentation model and artifact projector

- Define a versioned presentation schema for runs, stages, concepts, review
  findings, repairs, and final results.
- Build projections for every contracted Milestone 2 artifact.
- Handle missing, partial, failed, resumed, and old-contract artifacts safely.
- Generate the same presentation model for live and curated runs.
- Add contract fixtures from all three accepted Milestone 2 cases.

Exit: all accepted examples project deterministically without raw JSON leaking
into user-facing fields.

### 3. Durable run service

- Add upload validation, safe filenames, size/type limits, and run isolation.
- Launch the existing workflow through its supported invocation boundary.
- Persist stage state and make refresh/reconnect safe.
- Stream or poll completed presentation events.
- Support explicit recovery where the runner supports resume.
- Bound concurrency, retries, resource usage, and model spending.

Exit: a browser can disconnect, reconnect, and recover the same run without
duplicating work.

### 4. Judge-facing interface

- Build the opening transformation story around the power of visualization.
- Provide an immediately discoverable example path and real upload path.
- Present source and final charts at useful scales.
- Present completed intermediate stages as readable visual cards.
- Highlight autonomous concept selection without asking the user to choose.
- Show candidates, inspection findings, and repairs when they exist.
- Keep final rationale concise and detailed evidence expandable.
- Support desktop and practical mobile layouts, keyboard navigation, readable
  contrast, reduced motion, and useful alternative text.

Exit: an unfamiliar reviewer can describe what Chartsmith does after a brief
unassisted session.

### 5. Curated example journeys

- Package the ordinary, dense, and already-strong accepted cases.
- Write concise user-facing stage narratives grounded in their canonical
  artifacts.
- Include repairs that visibly demonstrate the value of inspection.
- Verify source rights and attribution before publication.
- Avoid committing unnecessary bulk run payloads.

Exit: three immediate examples exercise the same presentation contract as live
runs and contain no broken or machine-local references.

### 6. Differentiation evidence

- Define a fair, minimal single-call baseline protocol.
- Run it on at least one representative input using the same source image and a
  non-sabotaged objective.
- Preserve the prompt, model provenance, output, and evaluation evidence.
- Compare the baseline and Chartsmith result on communication, authorship,
  production integrity, and epistemic integrity.
- Use the evidence in the product or submission only to the extent justified by
  the observed result.

Exit: the value claim is evidence-backed and avoids claiming that workflow
complexity is inherently superior.

### 7. Failure and safety hardening

- Test malformed and oversized uploads.
- Test backend timeout, model refusal, generation failure, interrupted repair,
  exhausted bounds, and browser reconnect.
- Prevent arbitrary file access, unsafe artifact serving, injection through
  filenames or model-authored text, and credential disclosure.
- Ensure partial candidates are never labeled final.
- Make every failure state tell the user what was preserved and what can happen
  next.

Exit: expected failures are contained, comprehensible, and do not corrupt other
runs.

### 8. Validation and handoff

- Run unit and contract tests.
- Run the three examples through the product surface.
- Complete at least one genuine upload-to-final product run.
- Visually inspect every major screen and responsive state.
- Test fresh setup and deployment instructions.
- Update `README.md`, `PROJECT_STATE.yaml`, operations, architecture, known
  limitations, and Build Week evidence.
- Record implemented-versus-planned boundaries and validation evidence.

Exit: all milestone stop conditions have explicit evidence.

## Review criteria

### Product comprehension

- The source/final difference is visible without reading an essay.
- The interface communicates the power of visualization rather than generic AI
  image generation.
- The reason for multiple stages is evident from their useful outputs.

### Progress quality

- There is always a truthful current state.
- Completed stages offer something worth reading or inspecting.
- No default screen exposes machine-oriented artifacts.
- Repair history demonstrates quality control without overwhelming the result.

### Visual quality

- Source, candidates, and final charts are shown without cropping or unintended
  resampling artifacts.
- Layout, typography, spacing, and responsive behavior meet the same
  zero-visible-defect expectation as generated charts.
- Loading and transition treatments do not distract from the visual evidence.

### Reliability and integrity

- Only a successful final evaluation can mark a run complete.
- Refreshing or reconnecting cannot duplicate expensive work.
- Intermediate inferences are not presented as verified source facts.
- Provenance remains traceable from UI presentation to canonical run artifacts.

## Known risks to resolve during preflight

- A local Codex CLI execution path may not be suitable for the selected hosted
  environment.
- Individual model stages may still be long enough to require current-activity
  copy in addition to completed intermediate results.
- Generative and repair loops make completion time variable.
- Hosted execution requires cost, concurrency, timeout, storage, and secret
  boundaries.
- Model-authored presentation content requires safe rendering and length limits.
- Source images and examples require explicit rights review before publication.
- The submission deadline limits the amount of product breadth that can be
  justified beyond the fixed vertical slice.

## Deferred user-decision boundary

No further preference input is required to begin local implementation.

Before public deployment or submission actions, request only the unresolved
external authority needed at that point: accounts, spending limit, repository
visibility, publication permission, licensing confirmation, and submission
identity or links.
