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.