# Milestone 5 Execution Plan

Status: ready for execution
Prepared: 2026-07-20 HKT
Authority: `BUILD_WEEK_PLAN.md`
Readiness record: `manifests/milestone5_readiness.json`

## Objective

Turn the completed local Chartsmith product into a judge-ready, externally
accessible, compliant OpenAI Build Week submission without reopening product
architecture or implying that precomputed examples are live generation.

Milestone 5 packages, publishes, deploys, demonstrates, and submits the work
completed in Milestones 1 through 4. It is not another workflow-optimization
milestone.

## Deadline

The official submission deadline is July 21, 2026 at 5:00 PM PDT, equivalent to
July 22, 2026 at 8:00 AM HKT.

Official sources:

- `https://openai.devpost.com/`
- `https://openai.devpost.com/details/faqs`

No submission change is possible after the deadline.

## User Decisions and External Authority

The following decisions are approved:

- repository visibility: public;
- intended repository: `sseo0817/chartsmith`;
- code license: MIT;
- third-party material: separately attributed and excluded from the MIT grant;
- deployment: public ten-example showcase;
- hosted live generation: not part of the submission deployment;
- genuine generation: remains available through the documented local product;
- entrant: solo;
- category: Work and Productivity;
- narration: AI voice;
- Devpost: account created and hackathon joined.

The GitHub connector and local GitHub CLI are authenticated as `sseo0817`.
The existing Sites project in `app/web/.openai/hosting.json` must be reused.

## Submission Story

The judge-facing story is:

> From one chart image, Chartsmith autonomously reconstructs the message,
> explores three materially different visual ideas, selects and renders one,
> independently inspects the actual image, repairs visible or epistemic
> problems, and releases one stronger visual story.

The submission must demonstrate:

1. the power of a well-designed visualization compared with a naive source;
2. why the complete workflow produces consequences beyond a direct single call;
3. meaningful GPT-5.6 use in reconstruction, concept judgment, review, repair,
   and release;
4. meaningful Codex collaboration throughout Build Week;
5. the ten-example range and retained evidence;
6. honest separation between the public showcase and local live generation.

## Workstream 1: Repository Packaging

Codex will:

1. perform a publication and secret-safety audit;
2. add an MIT `LICENSE` for project-owned code;
3. add third-party notices and explicit asset-license boundaries;
4. ensure the README contains:
   - the product thesis and immediate visual proof;
   - public showcase and repository links;
   - setup and one-command local product instructions;
   - the image-only input and one-shot interaction contract;
   - how Codex and GPT-5.6 were used;
   - architecture and evidence links;
   - known limitations;
   - prior work versus Build Week work;
5. ensure screenshots and sample data are appropriately licensed and tracked;
6. run the complete repository and product validation suite;
7. commit a publication-ready source state.

The repository must not expose ignored run payloads, credentials, local-only
paths in the product, private user data, or unreviewed third-party material.

## Workstream 2: Public Repository

After packaging passes:

1. create the public GitHub repository `sseo0817/chartsmith`;
2. add it as the local remote;
3. push the exact validated main-branch state and tags needed for provenance;
4. verify the repository URL without relying on an authenticated session;
5. verify that a clean checkout can follow the documented setup and tests.

The public remote is an external write. It is authorized by the recorded user
decision, but no repository is created during plan preparation.

## Workstream 3: Public Showcase

The showcase will:

- load all ten accepted journeys immediately;
- present source, final result, intermediate stages, review, and repair;
- preserve the fair direct-call comparison;
- remain responsive and visually defect-free;
- state clearly that full generation runs locally;
- never simulate a hosted workflow or present a curated example as a live run.

Execution order:

1. prepare and validate the exact deployable source;
2. push that exact source state to GitHub;
3. package a Sites archive from the pushed commit;
4. save a Sites version referencing that commit;
5. deploy the approved public version;
6. inspect deployment status to a terminal success state;
7. verify the production URL on desktop and mobile;
8. verify imagery, metadata, console output, links, and offline upload messaging.

The registered project ID is authoritative in
`app/web/.openai/hosting.json`; it must not be recreated or substituted.

## Workstream 4: Project Media

Codex will prepare a compact media set in 3:2 landscape format, PNG or JPG, with
each file below 5 MB:

1. submission thumbnail;
2. source-to-redesign hero;
3. ten-example portfolio range;
4. complete seven-stage product journey;
5. concrete review-and-repair evidence.

Media will use genuine Chartsmith outputs and product captures. It will avoid
tiny machine text, local paths, raw JSON, and claims not supported by retained
artifacts.

The first prepared asset is:

`docs/current/assets/chartsmith-devpost-thumbnail.png`

## Workstream 5: Demo Video

Detailed production authority, tooling, editorial, output, and QA requirements
are defined in `docs/current/milestone_5_video_spec.md`.

Target duration: 2 minutes 35 seconds to 2 minutes 50 seconds.
Hard maximum: 3 minutes.
Language: English.
Narration: AI voice, calm and direct rather than promotional.

Planned narrative:

1. **0:00-0:20 — problem and thesis**
   - busy audiences need a chart's point immediately;
   - one chart image is sufficient input.
2. **0:20-0:55 — transformation**
   - source versus final;
   - authored communication gain.
3. **0:55-1:35 — system value**
   - reconstruction, three concepts, selection, rendering, inspection, repair;
   - one concrete defect or semantic issue caught by review.
4. **1:35-2:05 — Codex and GPT-5.6**
   - how Codex helped restructure, implement, run, diagnose, and harden;
   - how GPT-5.6 operates inside the product.
5. **2:05-2:30 — range and evidence**
   - ten distinct examples and 26 repairs;
   - fair direct-call comparison.
6. **2:30-2:45 — honest boundary and close**
   - public showcase, local genuine engine;
   - one chart image, one stronger story.

Codex will prepare:

- final script;
- shot list and truthful capture sources;
- AI narration;
- captions;
- edited MP4;
- duration, audio, and visual QA.

No copyrighted music is required. The video must show a working product and
specifically explain both Codex collaboration and GPT-5.6 integration.

Codex is authorized to install local open-source or no-additional-cost media
tools, renderer packages, codecs, browser-capture helpers, and QA utilities.
Paid services, new external accounts, credentials, and usage-billed APIs remain
outside this authorization and require a separate user decision.

## Workstream 6: Devpost Package

Codex will prepare:

- elevator pitch;
- Markdown project story grounded in the user's own motivation;
- Built With tags;
- public showcase and code links;
- media upload order and captions;
- video URL field once the user supplies it;
- prior-work disclosure;
- known limitations;
- final compliance and link checklist.

The user will:

1. review and adjust the project story so it remains in their own voice;
2. upload the supplied media to Devpost;
3. upload the finished MP4 to YouTube as **Public** and provide the URL;
4. run `/feedback` in the primary Codex task and provide the Session ID;
5. review the rules and attestations;
6. approve and click the final Devpost submission action.

## Execution Order

The run must follow this dependency chain:

1. publication/security audit;
2. repository packaging and validation;
3. publication-ready commit;
4. public GitHub repository and verified push;
5. showcase source preparation from that pushed commit;
6. saved Sites version and public deployment;
7. production browser QA;
8. final project media from production and retained evidence;
9. video script, capture, narration, edit, and QA;
10. user YouTube upload;
11. `/feedback` Session ID;
12. final Devpost assembly and user submission.

Repository and deployment links must exist before the final video and Devpost
package are frozen.

## Guardrails

- Freeze workflow architecture; fix only submission-breaking defects.
- Preserve the deterministic vNext workflow and v2.6 rollback baseline.
- Do not restart broad NodeBench or portfolio optimization.
- Do not expose credentials, private paths, ignored run payloads, or local logs.
- Do not license third-party figures as project-owned material.
- Do not claim public live generation.
- Do not present curated examples as live runs.
- Do not publish a version that differs from the validated pushed commit.
- Do not allow visible product defects in screenshots, media, video, or the
  production site.
- Do not submit AI-written personal narrative without user review.

## Validation Contract

Before publication:

- secret and tracked-file audit passes;
- `python scripts/validate_repo_state.py`;
- `python scripts/validate_milestone4_portfolio.py`;
- `python -m unittest discover -s tests`;
- web lint, test, and production build;
- catalog evidence check;
- whitespace and clean-worktree checks.

After GitHub publication:

- repository is publicly reachable;
- expected commit is the remote default branch head;
- README images and links work;
- clean-checkout setup and validation succeed.

After showcase deployment:

- deployment reaches a terminal success state;
- public URL returns successfully without authentication;
- desktop and 390-pixel mobile layouts have no overflow or visible defect;
- all ten examples and their images load;
- browser console has no errors;
- metadata and social image resolve correctly;
- live-upload boundary is truthful.

Before submission:

- media files meet format, size, and aspect requirements;
- video is public, English, voiced, and no longer than three minutes;
- repository, showcase, and video links resolve publicly;
- story discloses pre-existing work and Build Week changes;
- `/feedback` Session ID is recorded;
- all Devpost required fields are complete.

## Stop Condition

Milestone 5 is complete only when:

1. the public GitHub repository is reachable and reproducible;
2. the public showcase is deployed and verified;
3. the media package is uploaded or ready with exact paths and captions;
4. the public YouTube demo link is verified;
5. the `/feedback` Session ID is recorded;
6. the final Devpost entry is submitted before the deadline;
7. completion evidence and `PROJECT_STATE.yaml` record the published URLs,
   submission state, validation results, and final commit;
8. the local worktree is clean and the final source state is recoverable.

## Readiness

The milestone is ready to run. No unresolved technical-design question blocks
execution.

Remaining user-only actions are account-bound:

- YouTube public upload;
- `/feedback`;
- final personal review and Devpost submission.

No external publication or deployment has been performed by this preparation
step.
