# Chartsmith Build Week Plan

Date: 2026-07-19
Status: Milestones 1, 2, and 3 complete; public deployment and submission packaging remain
Submission deadline: 2026-07-22 08:00 HKT

Collaboration and decision ownership are defined in `WORKING_AGREEMENT.md`.
Codex owns derivable planning and execution; user input is reserved for genuine
preference, authority, risk, or user-only-information boundaries.

## Product Objective

Finish Chartsmith as an autonomous, persuasion-first chart redesign product:

> Give Chartsmith a chart image alone. It uses Codex orchestration and GPT-5.6
> judgment to infer the chart's evidence and communication opportunity, invent a
> materially stronger visual treatment, repair every visible production defect,
> and return one confident final chart.

The final experience must be testable by judges, require no design expertise from
the user, and make the Build Week extension distinguishable from earlier
Chartsmith work. Exact data recovery is not the product promise; perceptual
credibility and a minimum epistemic floor remain required.

The authoritative product preferences and boundaries are in
`docs/current/product_doctrine.md`.

## Operating Decision

Preserve the current v2.6 pipeline as the pre-Build-Week baseline:

1. evidence extraction;
2. parallel numerical/source-contract and message/intent understanding;
3. one integrated design proposition;
4. computational scaffold generation;
5. a deterministic candidate state machine with review, repair, pivot, selection, and release gates;
6. independent final evaluation.

Develop a bounded `build_week_vnext` workflow alongside it. Do not mutate the
baseline in place and do not reuse the historical `v3` name. Promote vNext only
after small-case, source/final visual evidence shows that it satisfies the
product doctrine.

NodeBench remains useful engineering infrastructure, but broad node optimization
is not on the Build Week critical path. Improvement will use a small number of
cases, deep visual review, mechanism-level diagnosis, and one coherent change at
a time.

## Milestone 1: AI-Clean Pre-Build-Week Baseline

Status: completed and tagged `pre-build-week-clean-20260719`.

### Objective

Turn the current loose research workspace into an AI-operable repository with one unambiguous active system, explicit historical boundaries, versioned run provenance, and durable machine-readable navigation.

"Clean" does not mean minimizing the number of files or making the repository pleasant to browse manually. It means a future Codex task can determine, with a small and deterministic set of reads:

- what the current product is;
- which files are authoritative;
- which files are generated and must not be edited directly;
- which documents describe current decisions;
- which configurations are historical experiments;
- which workflow and artifact-contract version produced any run;
- which runs are current evidence, old evidence, fixtures, or incomplete;
- what validation must pass before a change is considered safe.

### Verified Starting Problems at Milestone Start

The following were the cleanup inputs, not current defects:

- The root contains 79 PNG files plus PDFs, HTML captures, and temporary acquisition artifacts from early research.
- `config/` contains 42 immediate files mixing active workflows, quality-model backups, stability variants, evaluation corpora, retry configs, and older experiments.
- `runs/` contains 157 immediate run directories plus nested experiment collections. Naming conventions span several workflow eras.
- The only file in `docs/` describes the older v3 pipeline and is not the active execution plan.
- `HANDOFF.md` is a June 19 operational snapshot, not the current Build Week plan.
- The active generator declares artifact contract `v2.6`; the separate evaluator declares `v2.5`. This must be reconciled or explicitly documented as compatible.
- Compatibility-only stage definitions remain in the active workflow YAML. They are not active execution-plan steps but can confuse an agent reading by stage inventory alone.
- The visible `.git` path is currently an empty OneDrive reparse directory, so the workspace is not functioning as a Git checkout.
- The documented bundled Python runtime currently lacks PyYAML, while the installed Python 3.12 environment has PyYAML 6.0.3.

### AI-Clean Design Principles

1. **One canonical state declaration**
   - A root `PROJECT_STATE.yaml` will identify active workflows, contract versions, generated files, supported commands, current examples, known blockers, and the latest validated baseline.
   - This file will be concise and machine-readable.

2. **One human-and-agent front door**
   - A root `README.md` will explain the product and route agents to `PROJECT_STATE.yaml`, current architecture, operations, examples, and history.
   - A root `AGENTS.md` will contain repository-specific edit rules and validation requirements.

3. **Every durable artifact has a lifecycle class**
   - `active`: part of the supported product.
   - `generated`: derived from an authoritative source and never hand-edited.
   - `example`: curated input/output evidence for the supported product.
   - `experiment`: potentially useful comparison evidence, but not production state.
   - `historical`: retained to explain an earlier version or decision.
   - `cache` or `scratch`: reproducible/non-authoritative material that may be excluded from Git.
   - `unknown`: temporarily quarantined until provenance can be established.

4. **Directory placement is not the only source of truth**
   - Moves will be accompanied by manifests containing IDs, versions, source paths, dates, status, and replacement paths.
   - An agent must not need to infer provenance from a directory name alone.

5. **Archive before delete**
   - No run, config, or source asset will be removed merely because it appears old or duplicated.
   - First hash, classify, and dependency-scan it.
   - Exact duplicates may be consolidated only after references have been rewritten and validation passes.

6. **Runs are indexed by provenance**
   - Each retained run should expose workflow version, artifact-contract version, model routing, source chart ID, completion status, final decision, and whether it is approved as current evidence.
   - Runs missing this information will be classified as `unknown` or `legacy-unversioned`, not silently treated as current.

7. **Current docs contain decisions only**
   - Current documentation will state accepted architecture and operating contracts.
   - Superseded proposals, discussion notes, and old handoffs will move to history with clear status banners.
   - A current document must not mix accepted behavior with future ideas unless future work is explicitly labeled.

8. **Do not reorganize executable code for aesthetics**
   - The first cleanup should reduce ambiguity without introducing broad import/path churn.
   - A later `scripts/` to `src/` packaging change is allowed only if it materially improves deployment, testing, or API reuse.

### Proposed Target Structure

The exact migration may adjust after the manifest audit, but the intended information architecture is:

```text
chartsmith/
  README.md
  AGENTS.md
  PROJECT_STATE.yaml
  BUILD_WEEK_PLAN.md
  CHANGELOG.md
  requirements.txt

  app/
    web/                         # Build Week product surface

  config/
    active/
      generator.yaml
      evaluator.yaml
      quality_model.yaml
      manifest.yaml
    evaluation/
      current/
      corpora/
    nodebench/
    experiments/                # Non-promoted configurations

  chartsmith/                    # Reusable runtime package, if justified
  scripts/                       # Thin commands and retained operational tools

  examples/
    catalog.yaml
    inputs/
    expected/
    evidence/

  docs/
    current/
      architecture.md
      artifact_contract.md
      operations.md
      evaluation.md
    history/
      decisions/
      handoffs/
      workflow_versions/

  references/
    design_inspiration/
    source_material/

  runs/
    manifest.jsonl
    build_week/
    pre_build_week/
      v2_6/
      v2_5/
      v3/
      legacy_unversioned/
    fixtures/

  archive/
    pre_build_week/
      root_acquisition_artifacts/
      configs/
      scratch/
```

The stable logical names in `PROJECT_STATE.yaml` and manifests are more important than these exact directory names.

### Migration Sequence

#### 1. Recover source control and freeze inventory

- Repair this workspace as a real Git checkout or create a verified clone/copy for Build Week work.
- Record hashes, sizes, timestamps, and current paths before moving files.
- Capture the pre-cleanup tree and validation results.
- Create the Build Week branch and an immutable pre-cleanup tag or commit.

#### 2. Establish canonical metadata

- Create `PROJECT_STATE.yaml`.
- Create `AGENTS.md`.
- Create the root `README.md`.
- Declare the authoritative generator, evaluator, quality model, generated runner, NodeBench pack, and supported Python environment.
- Mark generated files and compatibility-only sections explicitly.

#### 3. Classify before moving

- Produce a file inventory with lifecycle class and rationale.
- Produce a run manifest by inspecting run-local metadata and artifacts, not only directory names.
- Produce a config manifest identifying active, experimental, superseded, backup, retry-only, and unknown files.
- Scan code and documentation references to every proposed move.

#### 4. Separate active and historical surfaces

- Move root acquisition images, screenshots, PDFs, and temporary HTML into an archived source-acquisition area.
- Move superseded architecture notes and handoffs under `docs/history/` with status banners.
- Move non-active configuration variants into versioned experiment/history locations.
- Keep only supported configs at the active front door.
- Separate pre-Build-Week runs by verified artifact contract and status.
- Keep current curated examples outside the general run archive.

#### 5. Reconcile contracts and executable paths

- Decide whether generator v2.6 and evaluator v2.5 are intentionally compatible; align version declarations if they are one contract.
- Regenerate the generated runner from its source.
- Remove or isolate compatibility-only workflow stages only after confirming no supported command or fixture depends on them.
- Fix dependency installation and eliminate machine-specific setup assumptions where practical.

#### 6. Validate the cleaned baseline

- Validate active generator and evaluator YAML.
- Compile active Python modules.
- Validate the active NodePack.
- Run a no-model workflow dry run.
- Open at least two migrated historical runs through their manifests and verify every referenced artifact resolves.
- Run one small supported example if credentials and time allow.
- Verify that an agent starting only from `README.md`, `AGENTS.md`, and `PROJECT_STATE.yaml` can identify the correct edit and validation surfaces.

### Milestone 1 Deliverables

- Working Git history with a recoverable pre-cleanup snapshot.
- `README.md`, `AGENTS.md`, and `PROJECT_STATE.yaml`.
- Current architecture and operations documentation.
- File, config, and run manifests.
- Active/historical separation for configs, docs, root assets, and runs.
- Reconciled artifact-contract declarations.
- Reproducible environment and passing baseline validations.
- A dated `pre-build-week-clean` commit/tag that becomes the base for Build Week implementation.

### Milestone 1 Stop Condition

Stop cleanup when:

- the canonical active system can be identified from three front-door files;
- no current command depends on an unclassified root or archived file;
- all retained runs are classified or explicitly marked unknown;
- active validations pass;
- the cleaned state is committed and recoverable.

Do not spend Build Week time perfecting historical taxonomy beyond what is needed to prevent active-state ambiguity.

## Milestone 2: Deployable GPT-5.6 Vertical Slice

The executable plan is `docs/current/milestone_2_plan.md`.

Status: completed and promoted. Completion evidence is
`docs/current/milestone_2_results.md`.

- Create an isolated persuasion-first vNext while preserving v2.6 as the baseline.
- Accept a chart image alone and require no user design decisions.
- Use GPT-5.6 materially for perceptual reconstruction, concept judgment, and
  final visual review, with model evidence in run artifacts.
- Explore three materially different concepts and select one authored direction.
- Permit generative, deterministic, or hybrid rendering according to the concept.
- Enforce bounded repair with zero visible production defects at release.
- Learn through two deeply reviewed contrasting cases plus one pre-promotion
  challenge case, not a large-batch optimization run.

Stop when the deployment-compatible vNext path autonomously returns one
materially better, defect-free chart from image-only input on the planned cases,
or when a documented no-go diagnosis shows why it cannot yet be promoted.

## Milestone 3: Judge-Friendly Product Interface

Status: completed locally. Public deployment remains deferred by user decision.

The product direction is `docs/current/milestone_3_product_brief.md`. The
executable plan is `docs/current/milestone_3_plan.md`.

- Provide immediate curated examples and a real chart-upload path.
- Show original and redesigned charts.
- Show progress through the deterministic workflow using polished intermediate
  results, not machine logs or stage labels alone.
- Show a compact explanation of the design idea, reconstruction confidence, and
  production-integrity result.
- Provide inspectable artifacts without making the main result screen an audit report.
- Demonstrate the system's value beyond a direct single model call through
  observable process evidence and at least one fair controlled comparison.

Stop when a first-time judge can understand and test the product without repository knowledge.

Completion evidence: `docs/current/milestone_3_results.md`.

## Milestone 4: Submission Examples and Quality Proof

Status: complete. Completion evidence:
`docs/current/milestone_4_results.md`.

Prepare:

1. a simple source transformed by a strong authored visual idea;
2. a structurally dense image-only reconstruction and redesign;
3. an already-strong source that Chartsmith improves without damaging it.

Prefer self-created, synthetic, public-domain, or clearly licensed inputs. Each example must include provenance, configuration, output, and validation evidence.

The completed portfolio expands the minimum three-case requirement to ten
distinct accepted journeys: three attributed official public figures and seven
self-created CC0 synthetic sources.

## Milestone 5: Package, Deploy, and Submit

Status: ready for execution. Executable plan:
`docs/current/milestone_5_plan.md`.

- Public or correctly shared repository.
- License, setup, screenshots, architecture, known limitations, and Build Week changelog.
- Hosted product and verified links.
- Narrated demo of three minutes or less.
- Saved `/feedback` Session ID.
- Completed submission checklist and Devpost entry.

## Build Week Guardrails

- Preserve deterministic orchestration and the recoverable v2.6 baseline.
- Treat production integrity and the minimum epistemic floor as hard gates.
- Treat communication power, authorship, interestingness, perceptual fidelity,
  and memorability as continuous comparative judgments.
- Do not allow conservative source preservation to produce a cosmetic near-copy.
- Do not restart broad NodeBench optimization during the submission push.
- Do not delete historical evidence before manifests and a recoverable snapshot exist.
- Do not present precomputed examples as live generation.
- Once the supported vertical slice, examples, deployment, and submission materials pass, freeze architecture and address only submission-breaking defects.
