# Chartsmith agent operating contract

## Mandatory orientation

Read, in order:

1. `README.md`
2. `PROJECT_STATE.yaml`
3. `WORKING_AGREEMENT.md`
4. `docs/current/product_doctrine.md`
5. the relevant file under `docs/current/`

Do not infer current behavior from `docs/history/`, `archive/`, historical runs,
or `config/experiments/pre_build_week/`.

Distinguish product authority from executable authority:

- `docs/current/product_doctrine.md` defines what Chartsmith should optimize for.
- `PROJECT_STATE.yaml` defines what is implemented and active now.
- `docs/current/milestone_2_results.md` records the promoted workflow evidence.
- `docs/current/milestone_3_product_brief.md` defines the implemented
  judge-facing product.
- `config/experiments/build_week_vnext/milestone4_portfolio.yaml` is the
  authoritative ten-example portfolio;
  `docs/current/milestone_4_results.md` is its completion evidence.
- `docs/current/milestone_5_plan.md` is the approved packaging, public
  repository, showcase deployment, media, video, and submission execution plan;
  `docs/current/milestone_5_video_spec.md` defines truthful video production and
  quality requirements; `manifests/milestone5_readiness.json` records the
  external-authority boundary.

## Canonical edit surfaces

- For maintenance of the active baseline, edit workflow behavior in
  `config/chart_redesign_workflow.yaml` or
  `config/chart_evaluation_workflow.yaml`.
- The promoted product workflow is
  `config/experiments/build_week_vnext/workflow.yaml`, with
  `scripts/chartsmith_vnext.py` as its runner. Its experiment-era path is
  retained for accepted-run provenance; `PROJECT_STATE.yaml` is the promotion
  authority.
- Treat the canonical v2.6 workflows as the preserved rollback baseline; do not
  silently overwrite them while maintaining the Milestone 3 product surface.
- Edit generation logic in `scripts/render_workflow_scripts.py`.
- Never hand-edit `scripts/generated_chart_workflow.py`; regenerate it with
  `python scripts/render_workflow_scripts.py`.
- Keep the orchestrator deterministic. Use model intelligence inside bounded
  stages, not for global scheduling.
- Optimize node-local behavior first. NodePack inputs, prompts, evaluators, and
  patch boundaries live under `config/nodebench/nodes/`.
- Treat quality dimensions as continuous axes unless a documented safety or
  integrity condition is genuinely binary.
- For vNext, production integrity and the minimum epistemic floor are true hard
  gates. A cosmetic near-copy is also a product-level failure under the current
  doctrine.

## Data and output boundaries

- New runs belong under `runs/build_week/`; do not write new payloads directly
  under `runs/`.
- Existing run collections outside `runs/build_week/` are pre-build-week history.
- Do not commit bulk run payloads. Update `runs/manifest.jsonl` and curate compact
  evidence under `examples/`.
- Root-level media, downloaded pages, PDFs, and scratch captures are forbidden.
  Put durable source material under `reference/`, catalogue material under
  `references/`, or disposable acquisition evidence under an explicit archive.
- New configs must be placed in `config/evaluation/current/`,
  `config/experiments/<era>/`, `config/history/`, or `config/nodebench/`; do not
  restore the former flat config pile.

## Required validation

After workflow or runner changes:

```powershell
python scripts\render_workflow_scripts.py
python scripts\generated_chart_workflow.py validate --workflow config\chart_redesign_workflow.yaml
python scripts\generated_chart_workflow.py validate --workflow config\chart_evaluation_workflow.yaml
python scripts\validate_repo_state.py
```

After NodeBench changes:

```powershell
python scripts\nodebench.py list-nodes
python scripts\nodebench.py validate-pack --node design_proposition
python scripts\nodebench.py dry-run --node design_proposition --run-id validation-dry-run
```

Before a baseline handoff, rebuild manifests:

```powershell
python scripts\build_repo_manifests.py --snapshot-id <snapshot-id> --publish-run-manifest
```

Record current decisions in `PROJECT_STATE.yaml` and `docs/current/`; record
historical explanation in `CHANGELOG.md` or `docs/history/`.
