Automation Orchestrator Design · 07 Final Report — AUTOMATION_ORCHESTRATOR_DESIGN_READY

doc 7 of 7 · 2026-05-20 · STOP gate

outcome              : A — AUTOMATION_ORCHESTRATOR_DESIGN_READY
production_mutation  : NONE
stop_route           : GPT / User

1. Outcome

Result A — AUTOMATION_ORCHESTRATOR_DESIGN_READY. A complete, v0.5-grounded design has been authored for the one-command automatic cut orchestrator. The design preserves every safety invariant proven in the Constitution cycle (survey-first, fail-closed, fresh review_decision per phase, in-txn atomicity, KB-as-SSOT) while collapsing the ≥ 20 stop-routed macros of v0.5 into one supervised 60-minute run with exactly 3 sovereign-gate stops (cut authz, lifecycle authz, failure escalation).

docs_authored      : 7 (this folder)
new_modules_planned: 11 + CLI extensions
reused_modules     : 8 v0.5-proven modules (cutplan, prod_iu_adapter,
                                            prod_iu_adapter_canonical,
                                            ledger_v2_canonical_cut,
                                            ledger_v2_canonical_verify,
                                            signing, idempotency, dryrun)
sovereign_stops    : 3 (down from ≥ 20 in v0.5)
internal_gates     : 11 (auto-pass with KB receipt)
rollout_macros     : 6 (O1..O6)
production_mutation: NONE

2. Gate roll-up

Gate	Subject	Outcome	KB doc
G1	Operational goal + user input model	PASS	doc 01
G2	End-to-end state machine + persistence + resume	PASS	doc 02
G3	Phase orchestration + internal/sovereign gates	PASS	doc 03
G4	Artifact / report / idempotency model	PASS	doc 04
G5	Batch / overnight / error / resume model	PASS	doc 05
G6	Implementation roadmap + module plan	PASS	doc 06
G7	Reporting	PASS	this

3. Answers to the 10 brief-surfaced design questions

DQ_1_writer_locus:
  answer  : fn_iu_create remains the canonical writer; adapter
            prod_iu_adapter_canonical is the only IU writer path.
  bearing : preserves v0.5 ratification + 60-IU evidence.

DQ_2_signing_lane_evolution:
  answer  : OPTION "swap forward for next document".
            StubSigning stays for v0.5 ratifications; real crypto via
            SigningProvider interface, swapped in macro O6.
  bearing : avoids replaying signed v0.5 rows; sovereign architectural
            call deferred to its own macro.

DQ_3_lifecycle_loop_completeness:
  answer  : MVP supports draft→enacted only.
            supersede/retire/restore raise STOP_NOT_IMPLEMENTED.
  bearing : matches v0.5 fn_iu_enact which only fully implements 'enact'.

DQ_4_governance_role_topology:
  answer  : reuse directus SECDEF probe for read-side governance access
            in v0.6; introduce cutter_orchestrator role only if O2 reveals
            a contention point.
  bearing : no new role for MVP ⇒ less drift surface.

DQ_5_backup_rollback_atomicity:
  answer  : GPG-encrypted narrow pg_dump per document; sha-pinned;
            never auto-restored; emergency revert is a separate sovereign
            macro using sql/lifecycle/rollback_runbook.sql (already
            ratified in repo).
  bearing : matches v0.5 backup sha 076213737cac…+ ba0ef355e7… patterns.

DQ_6_review_decision_creation_policy:
  answer  : a NEW review_decision row per (document, phase). SG_1 and
            SG_2 each require fresh sovereign-issued UUIDs.
            Batch mode pre-batches sovereign approvals but does NOT
            collapse them into one row.
  bearing : preserves Phase 7 doctrine literally.

DQ_7_idempotency_replay:
  answer  : 3 layers (sidecar key / DB UNIQUE / module recorders).
            Replay is no-op if all 3 agree; otherwise STOP_REPLAY_CONFLICT.
  bearing : reuses existing UNIQUE constraints + LegBAlreadyRecorded
            / VerifyAlreadyRecorded exceptions.

DQ_8_dryrun_production_separation:
  answer  : `--mode dryrun` is default; `--mode live` requires the SG_1
            approval doc. Cutwrite stays db-isolated-dryrun ONLY (per
            v0.5 W-3 doctrine); cutprod_canonical owns the live write.
  bearing : preserves W-3 / W-4 separation.

DQ_9_stop_route_policy:
  answer  : STOP only at (sovereign-gate, invariant fail, drift, replay
            conflict, overrun, refused input, KB upload fail, lock busy,
            backup public key missing, grant delta, not-implemented).
            Auto-continue otherwise. NO silent retry that changes
            authority.
  bearing : doc 03 §6; full STOP enumeration.

DQ_10_observability_persistence:
  answer  : KB + filesystem JSON sidecar. NO new DB table in v0.6.
            Revisit in v0.7 only if sidecar fleet management becomes a
            burden.
  bearing : avoids unconstrained schema growth on cutter_governance.*.

4. State after this design macro

repo_root          : /Users/nmhuyen/iu-cutter-build/repo/iu-cutter
branch             : feature/constitution-snapshot-mark-dryrun
feature_head       : 0a64a61   (UNCHANGED — this is design-only)
main_head          : 0a64a61   (UNCHANGED — this is design-only)
working_tree       : clean
remote             : absent
tags               : none
production_mutation: NONE this macro
deploy_triggered   : NO
push_executed      : NO

5. KB folder index

knowledge/dev/laws/dieu44-trien-khai/v0.5-automation-orchestrator-design/

1. 01-operational-goal-and-user-input-model-2026-05-20.md
2. 02-end-to-end-state-machine-2026-05-20.md
3. 03-phase-orchestration-and-gates-2026-05-20.md
4. 04-artifact-report-and-idempotency-model-2026-05-20.md
5. 05-batch-overnight-error-resume-model-2026-05-20.md
6. 06-implementation-roadmap-and-module-plan-2026-05-20.md
7. 07-final-automation-orchestrator-design-report-2026-05-20.md (this)

6. Forbidden surface — final attestation

Forbidden	Status
Production mutation	NOT DONE
Deploy / restart	NOT DONE
Push / tag	NOT DONE
Source_document / source_version mutation	NOT DONE
Execute CUT / VERIFY / enact	NOT DONE
Hardcode secrets	NOT DONE
Replace StubSigning with real crypto	NOT DONE (deferred to O6)
Author large implementation code	NOT DONE (only contracts + pseudocode)
Modify the v0.5-ratified code path	NOT DONE

7. Most load-bearing design decisions (single-glance summary)

#	Decision	Rationale (one line)
1	User input = cutter orchestrate cut --document-id X	Operation-first; everything else discoverable.
2	3 sovereign gates (SG_1 cut authz, SG_2 lifecycle authz, SG_3 failure)	Matches the only points where v0.5 truly needed sovereign authority.
3	11 internal gates auto-pass with KB receipt	Removes the "stop between every step" overhead.
4	JSON sidecar + fcntl lock for state	No new DB table; resume-safe; cheap.
5	RunContext.context_pins instead of module-level PINs	Per-document runtime values, not hardcoded constants.
6	StubSigning kept; real crypto in O6	Avoids replaying v0.5 signed rows; sovereign ruling deferred.
7	Pre-batched sovereign approvals for overnight	Preserves "fresh review_decision per phase" doctrine; sovereign signs ahead of time.
8	Phase 6 global serialization across batch lanes	Prevents pg_dump IO saturation + double-write surprises.
9	Quarantine policy is the overnight default	A single bad doc doesn't waste a 6 h batch.
10	KB upload is a green-light gate	KB-as-SSOT: a run that didn't upload its phase doc didn't happen.

8. Macro budget vs v0.5 actual

v0.5_actual:
  macros_total            : ≈ 22 separate stop-routed macros
  wall_clock_total        : multi-day (each macro ≤ 60 min ; many days)
  sovereign_interventions : ≈ 22 (one per macro)

v0.6_target_per_document:
  orchestrator_macros     : 1 (single supervised run)
  wall_clock_per_doc      : ≤ 60 min hard-cap
  sovereign_interventions : 2 (SG_1 + SG_2) ; +1 only on failure
  overnight_throughput    : ≤ 5 docs per night (batch + quarantine)

A 30× reduction in sovereign cognitive overhead, with the same audit trail granularity (KB folder per document + per-phase doc + sovereign approval docs).

9. Authorized next macros (sovereign-sequenced)

recommended_next: O1 — AUTHORING-ONLY (module skeletons + contracts)
  effort_floor   : medium-high
  duration       : ≤ 60 min
  no_execution   : YES (compiles + tests skip until O2)
  scope_bound    : exactly the 11 + 2 modules in doc 06 §1

alternatives:
  - amend_design : sovereign asks for refinement (this doc rev 2+)
  - defer        : opt other paths (R-2/R-3/R-4 from prior closeouts) first
  - drop         : sovereign rules orchestrator out of scope (v0.6 stays
                    macro-style; not recommended given v0.5 fatigue)

10. STOP

This macro halts here. Routing back to GPT / User. No code authored, no production touched, no deploy, no push, no tag. Memory updated with this closeout for future reference.

final_outcome : A — AUTOMATION_ORCHESTRATOR_DESIGN_READY
next_action   : STOP → GPT / User