docs: add ADR and SGHFA standards architecture reference

[justinlietz93]

Motivation

• Capture the current Prometheus_VDM pipeline inventory and explicit gaps in proposal/approval, provenance, gate, and artifact-chain enforcement.
• Provide a concrete target architecture (“Standards‑Governed Hexagonal Falsification Architecture”, SGHFA) so future work can be migrated to a provable, proposal‑first, hash‑anchored pipeline.
• Produce an actionable migration plan and an enforceable standards document to guide contributors and CI/governance changes.

Description

• Added docs/ADR_CURRENT_TO_TARGET_SGHFA.md which inventories the existing pipeline (proposal/prereg/approval touchpoints, validation/gates, provenance, CI), documents gaps vs. the target, and supplies a detailed current→target migration plan.
• Added STANDARDS_GOVERNED_HEXAGONAL_FALSIFICATION_ARCHITECTURE.md as the canonical, living standards reference that defines inviolable principles, required hexagonal layers (experiment_control, execution_pipeline, theory_core, infrastructure_adapters, governance_automation), explicit domain contracts (e.g., ProposalDocument, PredictionEnvelope, ContradictionReport), required ports (e.g., ApprovalPort, ProvenancePort, ValidationGatePort), mandatory workflow sequence, enforcement matrix, and glossary.
• Both files are documentation-only, committed to the current branch and prepared as a PR; no runtime code or behavior was modified.

Testing

• Performed repository sanity and commit steps to validate the change: ran git status --short, git add + git commit -m "docs: add current-to-target ADR and SGHFA architecture standard", and inspected the new files with nl/sed; all commands completed successfully.
• No unit/integration tests were changed or required because this is a docs-only update; therefore no domain tests were executed against modified code.
• CI will run on merge per repository policies (existing workflows include derivation-guard, preflight smoke tests, and provenance-index generation).

---

Codex Task

Summary by Sourcery

Add a canonical standards document defining the Standards-Governed Hexagonal Falsification Architecture (SGHFA) and an ADR documenting the current Prometheus_VDM pipeline and its migration path to the target architecture.

Documentation:

• Introduce STANDARDS_GOVERNED_HEXAGONAL_FALSIFICATION_ARCHITECTURE.md as the authoritative, living architecture and governance standard for VDM falsification pipelines.
• Add ADR_CURRENT_TO_TARGET_SGHFA.md to capture the current pipeline inventory, identify gaps against SGHFA, and outline an incremental migration plan.

[sourcery-ai]

Reviewer's Guide

Adds two documentation-only architecture references: a canonical standards document defining the Standards-Governed Hexagonal Falsification Architecture (SGHFA) for Prometheus_VDM and an ADR that inventories the current pipeline, analyzes gaps, and lays out a migration plan to that target architecture.

Sequence diagram for SGHFA mandatory falsification workflow

sequenceDiagram
  actor Scientist
  participant experiment_control
  participant execution_pipeline
  participant ApprovalPort
  participant PredictorPort
  participant ValidationGatePort
  participant ProvenancePort
  participant ArtifactRegistryPort
  participant ContradictionReporterPort
  participant CanonResolverPort

  Scientist->>experiment_control: Submit_run_request_with_ProposalDocument
  experiment_control->>execution_pipeline: startRun(proposal_id)

  execution_pipeline->>ProvenancePort: appendLedgerEntry(stage_name=Proposal, input_hashes, output_hashes, parent_hash)
  ProvenancePort-->>execution_pipeline: ProvenanceLedgerEntry

  execution_pipeline->>ApprovalPort: validateApproval(ApprovalArtifact)
  ApprovalPort-->>execution_pipeline: ApprovalArtifact

  execution_pipeline->>CanonResolverPort: resolveThresholds(canon_anchor_ids)
  CanonResolverPort-->>execution_pipeline: resolved_threshold_values

  execution_pipeline->>PredictorPort: buildPredictionEnvelope(prereg_id, approval_id, canon_anchor_refs)
  PredictorPort-->>execution_pipeline: PredictionEnvelope

  execution_pipeline->>ProvenancePort: recordExecution(run_id, spec_hash, git_commit, tree_hash, seeds, runtime_hardware)
  ProvenancePort-->>execution_pipeline: ExecutionReceipt

  execution_pipeline->>ArtifactRegistryPort: registerArtifacts(run_id, artifact_descriptors, parent_manifest_hash)
  ArtifactRegistryPort-->>execution_pipeline: ArtifactManifest

  execution_pipeline->>ValidationGatePort: evaluateGates(ExecutionReceipt, PredictionEnvelope)
  ValidationGatePort-->>execution_pipeline: GateEvaluation_set

  alt all_gates_pass
    execution_pipeline->>ProvenancePort: appendLedgerEntry(stage_name=PassRouting, input_hashes, output_hashes, parent_hash)
    ProvenancePort-->>execution_pipeline: ProvenanceLedgerEntry
  else any_gate_or_provenance_failure
    execution_pipeline->>ContradictionReporterPort: emitContradiction(run_id, failed_gate_ids, evidence_artifact_pointers, severity)
    ContradictionReporterPort-->>execution_pipeline: ContradictionReport
    execution_pipeline->>ProvenancePort: appendLedgerEntry(stage_name=ContradictionRouting, input_hashes, output_hashes, parent_hash)
    ProvenancePort-->>execution_pipeline: ProvenanceLedgerEntry
  end

  execution_pipeline-->>experiment_control: Run_result_summary
  experiment_control-->>Scientist: Publish_pass_package_or_ContradictionReport

Loading

Entity relationship diagram for SGHFA artifacts and provenance chain

erDiagram
  ProposalDocument {
    string proposal_id
    string title
    string domain
    string proposal_hash
  }

  PreRegistrationRecord {
    string prereg_id
    string proposal_id
    string prereg_hash
  }

  ApprovalArtifact {
    string approval_id
    string proposal_id
    string prereg_id
    string approval_hash
  }

  PredictionEnvelope {
    string prediction_id
    string prereg_id
    string approval_id
    string prediction_hash
  }

  ExecutionReceipt {
    string run_id
    string execution_hash
  }

  GateEvaluation {
    string gate_id
    string run_id
    boolean passed
    string gate_hash
  }

  ContradictionReport {
    string contradiction_id
    string run_id
    string contradiction_hash
  }

  ArtifactManifest {
    string manifest_id
    string run_id
    string parent_hash
  }

  ProvenanceLedgerEntry {
    string entry_id
    string stage_name
    string parent_hash
  }

  ProposalDocument ||--o{ PreRegistrationRecord : has
  ProposalDocument ||--o{ ApprovalArtifact : referenced_by

  PreRegistrationRecord ||--o{ ApprovalArtifact : constrained_by
  PreRegistrationRecord ||--o{ PredictionEnvelope : source_for

  ApprovalArtifact ||--o{ PredictionEnvelope : authorizes
  ApprovalArtifact ||--o{ ExecutionReceipt : enables

  PredictionEnvelope ||--o{ ExecutionReceipt : precedes

  ExecutionReceipt ||--o{ GateEvaluation : produces
  ExecutionReceipt ||--o{ ArtifactManifest : indexed_by
  ExecutionReceipt ||--o{ ContradictionReport : may_generate

  ArtifactManifest ||--o{ ProvenanceLedgerEntry : summarized_by

  ProvenanceLedgerEntry ||--|| ProvenanceLedgerEntry : parent_child_chain

Loading

Class diagram for SGHFA domain contracts and ports

classDiagram
  class ProposalDocument {
    +string proposal_id
    +string title
    +string domain
    +list hypotheses
    +list canon_anchor_refs
    +string proposal_hash
  }

  class PreRegistrationRecord {
    +string prereg_id
    +string proposal_id
    +string variables
    +string controls
    +string pass_fail_criteria
    +string spec_refs
    +string salted_provenance
    +string prereg_hash
  }

  class ApprovalArtifact {
    +string proposal_id
    +string prereg_id
    +string tag
    +string approved_by
    +datetime approved_at
    +string approval_key
    +string script_scope
    +string approval_hash
  }

  class PredictionEnvelope {
    +string prediction_id
    +string prereg_id
    +string approval_id
    +string metric_envelopes
    +string thresholds
    +string confidence_metadata
    +string prediction_hash
  }

  class ExecutionReceipt {
    +string run_id
    +string spec_hash
    +string git_commit
    +string tree_hash
    +string seeds
    +string runtime_hardware
    +string execution_hash
  }

  class GateEvaluation {
    +string gate_id
    +list canon_anchor_refs
    +string measured_values
    +string threshold_values
    +bool passed
    +string gate_hash
  }

  class ContradictionReport {
    +string run_id
    +list failed_gate_ids
    +list evidence_artifact_pointers
    +string severity
    +string contradiction_hash
  }

  class ArtifactManifest {
    +string manifest_id
    +list artifact_entries
    +string parent_hash
  }

  class ProvenanceLedgerEntry {
    +string stage_name
    +string actor
    +datetime timestamp
    +list input_hashes
    +list output_hashes
    +string parent_hash
  }

  class PredictorPort {
    <<interface>>
    +PredictionEnvelope buildPredictionEnvelope(string prereg_id, string approval_id, list canon_anchor_refs)
  }

  class ApprovalPort {
    <<interface>>
    +ApprovalArtifact validateApproval(ApprovalArtifact approval_artifact)
  }

  class ValidationGatePort {
    <<interface>>
    +list evaluateGates(ExecutionReceipt execution_receipt, PredictionEnvelope prediction_envelope)
  }

  class ProvenancePort {
    <<interface>>
    +ExecutionReceipt recordExecution(string run_id, string spec_hash, string git_commit, string tree_hash, string seeds, string runtime_hardware)
    +ProvenanceLedgerEntry appendLedgerEntry(string stage_name, list input_hashes, list output_hashes, string parent_hash)
  }

  class ArtifactRegistryPort {
    <<interface>>
    +ArtifactManifest registerArtifacts(string run_id, list artifact_descriptors, string parent_manifest_hash)
  }

  class ContradictionReporterPort {
    <<interface>>
    +ContradictionReport emitContradiction(string run_id, list failed_gate_ids, list evidence_artifact_pointers, string severity)
  }

  class CanonResolverPort {
    <<interface>>
    +string resolveConstant(string canon_anchor_id)
    +string resolveEquation(string canon_anchor_id)
    +string resolveThreshold(string canon_anchor_id)
  }

  ProposalDocument "1" --> "*" PreRegistrationRecord : referenced_by
  PreRegistrationRecord "1" --> "1" ApprovalArtifact : approved_into
  ApprovalArtifact "1" --> "1" PredictionEnvelope : enables
  PredictionEnvelope "1" --> "*" GateEvaluation : evaluated_by
  ExecutionReceipt "1" --> "*" GateEvaluation : produces
  ExecutionReceipt "1" --> "*" ArtifactManifest : indexed_by
  ArtifactManifest "1" --> "*" ProvenanceLedgerEntry : chained_by
  ExecutionReceipt "1" --> "*" ContradictionReport : may_generate

  PredictorPort --> PredictionEnvelope
  PredictorPort --> PreRegistrationRecord

  ApprovalPort --> ApprovalArtifact
  ApprovalPort --> ProposalDocument
  ApprovalPort --> PreRegistrationRecord

  ValidationGatePort --> GateEvaluation
  ValidationGatePort --> PredictionEnvelope
  ValidationGatePort --> ExecutionReceipt

  ProvenancePort --> ExecutionReceipt
  ProvenancePort --> ProvenanceLedgerEntry

  ArtifactRegistryPort --> ArtifactManifest

  ContradictionReporterPort --> ContradictionReport

  CanonResolverPort --> ProposalDocument
  CanonResolverPort --> PreRegistrationRecord
  CanonResolverPort --> GateEvaluation

Loading

File-Level Changes

Change	Details	Files
Introduce SGHFA canonical standards document defining mandatory architecture, contracts, ports, workflow, and governance requirements for the Prometheus_VDM falsification pipeline.	Document inviolable principles for proposal-first, approval-gated, prediction-before-run, hash-anchored, contradiction-reporting workflows. Define required clean/hexagonal layers (experiment_control, execution_pipeline, theory_core, infrastructure_adapters, governance_automation) and their responsibilities and dependency rules. Specify explicit domain contracts (ProposalDocument, PreRegistrationRecord, ApprovalArtifact, PredictionEnvelope, ExecutionReceipt, GateEvaluation, ContradictionReport, ArtifactManifest, ProvenanceLedgerEntry) and required ports (PredictorPort, ApprovalPort, ValidationGatePort, ProvenancePort, ArtifactRegistryPort, ContradictionReporterPort, CanonResolverPort). Standardize the mandatory workflow sequence from proposal through provenance publish, including an enforcement matrix for proposals/prereg/approval, prediction, validation gates, contradiction handling, and provenance/hash guarantees. Set governance and quality requirements (architecture boundaries, file size, coverage, schema validation, canon linkage, provenance, CI policies, security checks) plus guidance for safely extending metrics, validators, artifacts, and experiments, and define contributor compliance and review procedures with migration guidance and glossary.	STANDARDS_GOVERNED_HEXAGONAL_FALSIFICATION_ARCHITECTURE.md
Add an ADR documenting the current Prometheus_VDM pipeline architecture, its gaps relative to SGHFA, and an incremental migration plan.	Inventory the as-is workflow stages, validation/falsification logic, provenance and hashing, canonical registry usage, and current division of responsibilities across Derivation and CI tooling. Perform a gap analysis against the SGHFA target, focusing on architectural boundaries, explicit contracts, provenance/hash-chain completeness, preregistration/approval/contradiction automation, and canon anchor-only value usage. Summarize the SGHFA target state as applied to this repository, emphasizing proposal-driven workflows, explicit ports, canonical anchor registry usage, end-to-end provenance, automated contradiction handling, and governance hard gates. Define a concrete migration plan: introduce explicit contracts, a canonical anchor resolver service, standardized orchestration, a unified gate registry, per-run artifact manifests and hash chain, normalized contradiction reporting, stronger CI governance, and incremental domain backfill. Capture expected consequences, costs/risks, and new constraints imposed on execution, canon usage, validation gates, and artifact provenance.	docs/ADR_CURRENT_TO_TARGET_SGHFA.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.