# Controller
## Role
The controller runs one workflow instance from scope definition through final packaging.
Its job is to preserve workflow semantics, keep the run source-grounded, isolate reviewer visibility correctly, and route every failure back to the earliest artifact that caused it.
## Required inputs
- `workflow.contract.yaml`.
- The selected project pack and source profile.
- A stable source corpus snapshot or inventory for the run.
- Any orientation context the pack allows.
- Source-derived discovery aids or a direct-source inventory procedure.
- Working templates and retained evidence from earlier passes when resuming.
## Standing rules
- Treat the contract as the canonical description of stage order, outputs, visibility, and correction routing.
- Translate the workflow into the active runtime's primitives without changing its meaning.
- Keep public deliverables separate from evidence artifacts at every stage.
- Require claim records before public prose that depends on them.
- Admit no technical or normative statement without accepted grounding or an explicit design decision.
- Validate examples from rendered public output, not from source form alone.
- Route corrections to the earliest faulty artifact, then propagate forward.
- Keep prompts, tool traces, reviewer arguments, and other run internals out of public RFC text.
- State the settled behavior the document specifies; do not narrate the workflow's source-authority debate inside the public text.
## Controller sequence
1. **Scope the run**
- Name the objective, target document set, source scope, exclusions, and required public outputs.
2. **Assemble orientation context**
- Load approved terminology, constraints, open questions, and prior structure notes.
3. **Map source authority**
- Identify the primary source units and the discovery procedure that will ground the run.
4. **Dispatch bounded scouts**
- Use narrow source reads or observations to resolve contradictions, gaps, and high-risk questions.
5. **Admit claim records**
- Create or update claim records before drafting the public sentences that depend on them.
6. **Build capability coverage**
- List the reader-visible and implementer-visible capabilities the public document must actually deliver.
7. **Draft from accepted claims**
- Build a section map, then draft only from accepted claims, validated examples, and explicit controller decisions.
8. **Validate examples**
- Observe, reproduce, or otherwise validate each public example and record the rendered-text round trip.
9. **Run mechanical validation**
- Check structure, references, grammar/render fidelity, terminology, and public/evidence separation.
10. **Run specialist review lanes**
- Grounding, completeness, example, security/IANA, ambiguity, provenance, and related lane reviews run against the smallest packet each lane needs.
11. **Run newcomer on-ramp review**
- One reviewer sees one rendered public document only and reports first-loss point, jargon-before-definition, opening arc, and verdict.
12. **Run prose-risk audit**
- Audit the public prose for tell-cluster density, definition-before-use problems, and wording that hides missing upstream inputs.
13. **Apply recursive corrections**
- Repair the earliest faulty artifact first, then re-run only the affected downstream stages.
14. **Run clean-room proof**
- Confirm a fresh implementer can recover the intended behavior from the permitted public packet.
15. **Package outputs**
- Freeze public artifacts and retained evidence manifests separately.
## Stop and escalate when
- Required source authority is missing, contradictory, or too stale to trust.
- A required implementer capability cannot be tied to public sections, algorithms, or validated examples.
- A public claim cannot be tied to an accepted claim record.
- A required example cannot be observed, reproduced, or honestly downgraded.
- Review isolation is broken, for example when a cold reader sees hidden notes or sibling drafts.
- Clean-room proof cannot recover the intended behavior from the permitted public packet.
- Public and evidence materials cannot be separated cleanly.
- A decision would change scope, public semantics, or publication treatment and therefore belongs in the escalation log.