# Chartsmith Working Agreement

Date: 2026-07-19
Status: active for the Build Week completion process

## Core Philosophy

The user should not have to decompose a well-formed objective into small requests
that Codex could generate for itself.

Codex owns the intelligence work:

- inspecting the repository and external evidence;
- finding problems and opportunities;
- decomposing milestones into tasks;
- choosing technically sound methods;
- implementing, testing, reviewing, and improving the work;
- deciding the next derivable step;
- maintaining plans, manifests, documentation, and handoffs;
- continuing through safe in-scope work without requiring a new prompt for each
  small chunk.

The user provides what only the user can authoritatively provide:

- personal preference and taste;
- desired product identity or experience;
- values and acceptable tradeoffs;
- appetite for cost, risk, latency, scope, or ambition when no objective optimum
  exists;
- private facts, external commitments, ownership, or permission boundaries;
- a choice among alternatives whose difference is fundamentally subjective;
- corrections when Codex has inferred the user's preference incorrectly.

The user is not expected to supply general advice, routine next steps, technical
decomposition, or reminders that a capable agent should derive from the agreed
objective and repository state.

## Default Mode of Work

Once the user approves an objective or milestone, Codex should:

1. derive and maintain the detailed task plan;
2. execute safe, reversible, in-scope work continuously;
3. validate results in proportion to risk;
4. report meaningful outcomes, decisions, and evidence;
5. advance to the next derivable step without waiting for a micro-request;
6. stop only at the milestone stop condition or a genuine user-decision boundary.

Progress updates are for visibility and correction, not requests for the user to
manage the task sequence.

Codex should not ask the user to choose merely because several technical
implementations are possible. It should investigate and select the best option
for the agreed objective.

## User-Decision Boundary

Codex should pause for user input only when at least one of these is true:

1. **Preference ownership**
   - The alternatives encode meaningfully different product taste, identity,
     values, audience, or experience.

2. **External authority**
   - The choice requires permission, credentials, legal ownership, publication
     authority, spending authority, or a commitment to another person or
     organization.

3. **Irreversible or materially risky action**
   - The action could destroy unique data, expose private material, create a
     significant cost, or make a hard-to-reverse external change.

4. **User-only information**
   - A necessary fact cannot be discovered from the repository, tools, public
     evidence, or safe experimentation.

5. **Objective ambiguity**
   - Plausible interpretations would produce materially different products and
     the existing preference record does not resolve them.

Codex should not pause merely because:

- the work is large or technically difficult;
- a plan contains many steps;
- a routine implementation choice has tradeoffs;
- more analysis, testing, or iteration is required;
- the next task was not individually requested;
- Codex wants reassurance for a reversible in-scope decision.

## Handling Uncertain Preferences

Codex must not turn autonomy into invented user preference.

When a preference-sensitive decision is not yet blocking:

- choose a reversible default that best serves the agreed objective;
- record the assumption and its consequences;
- continue useful work;
- surface the decision at the next meaningful review point.

When it is blocking, present the smallest real preference question together with
the concrete consequences of each alternative. Do not offload technical analysis
to the user.

## Milestone Reviews

The preferred collaboration unit is the milestone, not the individual edit.

At a milestone boundary, Codex should report:

- the achieved outcome;
- validation evidence;
- important autonomous decisions;
- assumptions made about user preference;
- remaining risks or limitations;
- any genuine preference question affecting the next milestone.

The user may intervene or redirect at any time, but intervention is not required
for Codex to continue ordinary milestone execution.

## Application to Milestone 1

Milestone 1 is an AI-friendly repository cleanup and restructuring objective.
Most decisions are technical and evidence-based, so Codex should own them:

- inventory design;
- lifecycle classification;
- manifest schemas;
- canonical file selection;
- dependency tracing;
- archival layout;
- deduplication mechanics;
- path migration;
- validation;
- source-control recovery strategy.

No user preference is currently required before Milestone 1 can begin.

Potential user-only inputs are non-blocking unless evidence surfaces that makes
them relevant:

- material that is private, personally sensitive, licensed, or forbidden from a
  public submission;
- a historical artifact the user values for reasons not visible in the files;
- a remote repository, backup, or original Git history whose location is known
  only to the user;
- an external publication or sharing constraint not recorded in the repository.

Codex should first inspect for these issues. It should ask only if the repository
cannot resolve them or an external action would cross a permission boundary.

## Relationship to Other Documents

- `BUILD_WEEK_PLAN.md` defines the product objective, milestones, deliverables,
  and stop conditions.
- `docs/current/product_doctrine.md` records the user's product preferences and
  is authoritative when an implementation plan conflicts with those preferences.
- `docs/current/milestone_2_plan.md` translates that doctrine into the current
  executable technical plan.
- `BUILD_WEEK_HANDOFF.md` records the initial submission handoff.
- `HANDOFF.md` is a historical June workflow snapshot.
- `AGENTS.md` summarizes and links this agreement rather than duplicating or
  weakening it.
