CR-012/PR-012a: DAG-2026 foundation — single-source flag, DagSettings, ground-truth addendum

[quantamixsol]

Public port of the DAG-2026 foundation, cherry-picked after the private PR merged.

Private PR: quantamixsol/research-development-graqle#339 — APPROVED by the Research Team (rounds 1, 2+3, and the C1–C3 conditional approval), merged 2026-09-14 as f4a53b87.
Cherry-picked commits (feature commits only, never the merge commit): 93adcced, 5204add5, df543444, 8828d6e0, 5aa4ae78 → replayed here as be70039d, b143035e, a25a94ba, d6fb4229, ffe77e01.

What this is

The foundation layer for the Decision Assurance Gate programme (ADR-RT-004). It ships configuration plumbing and types only — no gate logic, no routing, no scoring.

• graqle.assurance package — is_dag_enabled() (single-source flag reader; positive allowlist 1|true|yes|on, anything else OFF), DagSettings (one typed home for every DAG configuration symbol, GRAQLE_DAG_* prefix, frozen, unknown names rejected), ConfigurationError, load_dag_settings() (environment > private file at GRAQLE_DAG_SECRETS_PATH > safe default; cached only on success), config_version() (deterministic fingerprint; private values never in clear), config_provenance(), validate_flag_consistency().
• GraqleConfig.assurance — enabled is derived from the environment flag and is read-only. Setting assurance.enabled in graqle.yaml raises ConfigurationError before environment interpolation.
• .env.example at the repo root — every DAG variable NAME with placeholders. No tuning values.
• docs/dag/ground-truth-addendum.md — the charter-correction record, plus an operator section covering CSPRNG salt generation and rotation, the Kubernetes defaultMode: 0400 requirement, and the Windows residual.

Three statements the Research Team asked for explicitly

1. The flag is off by default. GRAQLE_DAG_ENABLED defaults to unset, which resolves to OFF.
2. No behaviour change — 0.83.0 parity. With the flag off, nothing in this package alters SDK behaviour. The only always-on change is an additive, derived assurance section on GraqleConfig.
3. GovernanceMiddleware.check() is untouched. Verified by diff guard: graqle/core/governance.py, graqle/governance/*, graqle/intelligence/governance/drace.py and graqle/core/rbac.py are all byte-identical to master on this branch.

Verification on this branch

ruff check graqle/assurance tests/test_assurance tests/test_docs   → All checks passed
pytest tests/test_assurance tests/test_docs tests/test_config \
       tests/test_public_api tests/test_packaging -q                → 395 passed, 3 skipped

Rebased onto current master after CR-README-02 (#259) landed, so the diff is exactly the nine PR-012a paths and nothing else. CHANGELOG.md is deliberately unchanged: master already carries the ## Unreleased — 0.84.0 (DAG-2026 CR-012 foundation) block, and the released ## 0.84.0 section must not be disturbed.

Version note

This does not ship in a new version. Per the Research-Team ruling, the DAG foundation is released only once the gate vocabulary (PR-012b: GateOutcome, the reason-code registry, GateVerdict, trace schema v3) lands alongside it. The published 0.84.0 artifact does not contain this code, and the CHANGELOG entry stays under Unreleased until a version carries it.

🤖 Generated with Claude Code

[github-actions]

🛡️ GraQle PR Guardian

💥 Blast Radius: 9 modules affected

Module	Files Changed	Risk Level	Impact Radius
.env.example	1	🟡 T2	1
docs	1	🟡 T2	1
graqle	3	🟠 T3	3
tests	4	🟡 T2	4

Total blast radius: 9

---

🏛️ Governance Verdict

🚫 FAIL

• T3: 1 file(s) require explicit approval.

---

🔍 SHACL Violations

No SHACL violations detected. ✅

---

🔐 Approval Requirements

This PR requires approval from: T3

• A registered Tech Lead or Governance Admin must approve.

❌ Approval requirement NOT yet satisfied.

---

Metric	Value
Blast Radius	9
Files Analyzed	9
Blocked	1
SHACL Violations	0
Verdict	FAIL

---

_{🔬 Powered by GraQle PR Guardian v0.1.0 · Scan completed 2026-09-15T06:35:27.775398+00:00}