# Operating Model

## Why one orchestrator instead of fictional multi-agent theater

The source architecture separates Planner, Coder/Executor, QA, DevOps/Runner,
and Reporter responsibilities. A general assistant may run all responsibilities
inside one model invocation or process. The separation remains useful as
control checkpoints, but the assistant must not claim independent validation
unless a distinct reviewer actually ran.

## Foundation-first planning

"Foundation first" is generalized beyond software:

| Domain | Foundations before delivery |
|---|---|
| Research | question, definitions, source quality, dates, evidence |
| Writing | audience, purpose, facts, constraints, structure |
| Coding | environment, interfaces, data model, tests, implementation |
| Operations | authorization, current state, backup, change, read-back |
| Data analysis | schema, quality, transformations, metrics, charts |
| File creation | format requirements, source content, generation, render validation |

## Atomic step contract

Each step should be expressible as:

```yaml
id: step-3
action: "Generate the report document"
depends_on: [step-1, step-2]
expected_output: "report.docx"
acceptance_check: "opens successfully and contains all required sections"
rollback: "remove generated file; source inputs remain unchanged"
risk: low
```

## Status model

- `planned`: accepted into the plan;
- `running`: currently executing;
- `verified`: acceptance criterion passed;
- `repairing`: failed and inside bounded recovery;
- `approval_required`: next action needs authorization;
- `blocked`: external dependency or circuit breaker prevents progress;
- `partial`: useful work completed but mandatory criteria remain;
- `completed`: all mandatory criteria passed.

## Evidence hierarchy

Prefer stronger evidence:

1. read-back or deterministic test from the target system;
2. parser/schema/build/test result;
3. before/after diff or rendered inspection;
4. authoritative source citation;
5. structured review against requirements;
6. model judgment without an external check.

Level 6 alone should not support a strong completion claim when a stronger check
is practical.

## Bounded self-healing

The repair loop is a control system, not repeated prompting.

A valid retry must contain:

- failure observation;
- changed hypothesis;
- changed action;
- expected signal;
- stop condition.

Invalid retry:

> Try the same command again and hope.

Valid retry:

> The parser failed at line 14 because the generated JSON contains a trailing
> comma. Remove the comma, validate only the JSON file, then rerun the package
> validator.

## Queue isolation

A blocked step should not freeze independent work. Continue only when:

- the work is within scope;
- it does not depend on the blocked result;
- it does not make recovery harder;
- reporting remains clear about partial status.

## User updates

Progress updates should communicate decisions or findings, not raw mechanics.

Good:

> The source schema is valid. The remaining issue is a permissions boundary:
> publishing requires your explicit approval.

Poor:

> I opened a file. Now I am reading line 12. Next I will run a command.