55-Decision & Change Log Template v1.0 | Chapter 4 Decision Process & State Machine

Home ／ Docs-Technical WhitePaper ／ 55-Decision & Change Log Template v1.0

Chapter 4 Decision Process & State Machine

I. Chapter Goals & Applicability (Mandatory)

• Establish a controlled state machine from Propose → Review → Decide → Implement → Verify → Archive/Rollback; all transitions are driven by gates, each defined by quantifiable metrics, thresholds, and observation windows.
• Applies to cross-volume theoretical calibers, parameter/data-contract changes, method/process updates, and implementation binding—any decision/change requiring traceability and replayability.

II. State Definitions (Mandatory)

• Draft: DR created; content not yet review-ready.
• Review: multi-role parallel review; collect consistency/risk/impact opinions.
• Approved: decision rendered; scope, exceptions, and exit conditions defined.
• Implemented: implementation underway or finished; verification and regression artifacts submitted.
• Verified: verification passed; release/switch criteria satisfied.
• Archived: archiving completed; audit artifacts exported; read-only for citation.
• RolledBack: controlled rollback branch; recovery completed with a restoration report.

III. Events & Triggers (Mandatory)

• Propose: enter Draft; triggered by Requester.
• RequestReview: enter Review; fired after completeness gate passes.
• Approve: enter Approved; fired by Approver/Owner, after consistency/risk gates pass.
• Implement: enter Implemented; resources locked and plan approved.
• Verify: enter Verified; verification and regression gates satisfied.
• Archive: enter Archived; audit done and exports ready.
• Rollback: from Implemented/Verified to RolledBack; triggered by thresholds or adjudication.

IV. State Machine (ASCII Overview)

Draft ──RequestReview──▶ Review ──Approve──▶ Approved ──Implement──▶ Implemented

▲ │ │ │

│ └──────────Reject/Revise◀────────────────┘ │

│ │

└─────────────────────────────────────◀─────────────────────────────────────┘

Implemented ──Verify▶ Verified ──Archive▶ Archived

│ │

└──Rollback(trigger)▶ RolledBack ──(post-check)──▶ Draft/Review/Approved

V. Entry/Exit Conditions & Gates (Mandatory, copy-ready)

VI. Timeouts & Escalation (Mandatory)

• Review timeout: when review_sla expires, auto-escalate to Approver/Owner for forced adjudication or revert to Draft.
• Implemented timeout: when implement_sla expires without key milestones, trigger risk re-check; enter Rollback if necessary.
• Verified timeout: if archive_sla expires unarchived, auto-create a temporary release record and notify Auditor.

VII. Parallel Review & Conflict Handling (Mandatory)

• Parallel model: multiple Reviewers allowed; aggregation policy is strong-veto + minimum N approvals (N configured per volume/project).
• Conflict resolution: if consistency_ok=false, auto-revert to Draft and generate a diff list; if scope-only conflict, allow a second countersign round in Review.

VIII. Rollback Branch & Restoration Loop (Mandatory)

1. Trigger patterns: gate_accuracy<threshold@window, gate_latency>threshold@window, incident_level≥X, data_drift>threshold.
2. Minimal rollback steps:
   • Pause new traffic or switch back to the previous version;
   • Restore prior snapshots of parameters/calibers/data contracts;
   • Run restoration verification and restoration regression;
   • Produce RollbackReport and re-deployment conditions (gate list).
3. After restoration, return the DR to Draft/Review/Approved as dictated by the post-mortem.

IX. Audit Trail & Exports (Mandatory)

• Audit elements: timestamps, actors, from→to, gate outcomes, evidence references, and artifact hashes for all transitions.
• Exports: yaml/json/pdf; PDF contains signature page and gate assertions; YAML/JSON enable automated audit and replay.

X. Machine-Readable State Machine (YAML; JSON equivalent, copy-ready)

sign_chain:

states: ["Draft","Review","Approved","Implemented","Verified","Archived","RolledBack"]

transitions:

- { from: "Draft", to: "Review",

gate: ["completeness_check","see_refs_present"] }

- { from: "Review", to: "Approved",

gate: ["consistency_ok","risk_accepted","impact_covered"] }

- { from: "Approved", to: "Implemented",

gate: ["plan_ready","resources_locked","rollback_plan_ready"] }

- { from: "Implemented", to: "Verified",

gate: ["regression_ok","gate_accuracy>=0.99@7d","gate_latency<=2h@7d"] }

- { from: "Verified", to: "Archived",

gate: ["audit_ok","export_artifacts_present"] }

- { from: "Implemented", to: "RolledBack",

gate: ["trigger_threshold","incident_level>=2","rollback_plan_ready"] }

- { from: "Verified", to: "RolledBack",

gate: ["slo_breach","data_drift>0.03","rollback_plan_ready"] }

audit_trail:

required: ["timestamp","actor","from","to","gate","evidence_hash","notes"]

XI. Gate Naming & Policy (Mandatory)

• Naming pattern: gate_<metric><comparator><threshold>@<window>, e.g., gate_accuracy>=0.99@7d, gate_latency<=2h@7d.
• Evidence policy: each gate must specify data source, statistical method, confidence/interval, and script locator (script@commit).
• Failure policy: hard (block forward progress) vs soft (allow forward with Approver signature).

XII. Role Responsibility Mapping in the FSM (Mandatory)

XIII. Example Configuration Snippet (copy-ready)

gates:

completeness_check: true

see_refs_present: true

consistency_ok: true

risk_accepted: true

impact_covered: ["performance","cost","time","risk","dependencies"]

plan_ready: true

resources_locked: true

regression_ok: { suite: ["cmb_set_v3","arrive_time_check.py@a1b2c3"] }

gate_accuracy: ">=0.99@7d"

gate_latency: "<=2h@7d"

audit_ok: true

export_artifacts_present: ["yaml","json","pdf"]

triggers:

trigger_threshold: ["gate_accuracy<0.98@7d","incident_level>=2"]

data_drift: ">0.03@14d"

slo_breach:

availability: "<99.0%@24h"

XIV. Citation & Cross-Reference Style (Mandatory)

1. Fixed in-text format: “See 《 vX.Y》 Ch.x S/P/M/I…” with anchors preferred over whole volumes.
2. Align with the DR: provide a machine-readable references.see list, e.g.
   • "EFT.WP.Core.Terms v1.0:P10-3"
   • "EFT.WP.Core.Equations v1.1:S20-1"
   • "EFT.WP.Core.Metrology v1.0:check_dim"
   • "EFT.WP.Core.DataSpec v1.0:I30-2"