Decision Assurance Framework (DAF) is a local-first Python decision-support framework that turns structured decision records into policy-checked routes, bounded calculations, evidence-linked reports, and an explicit typed human-decision handoff (HumanDecisionHandoff).
Status: v0.1 source-only milestone. The published
v0.1.0milestone contains the structured P0/P1 workflow, one directly demonstrated Codex-subscription-native synthetic consultation, 40 registered calculation Tools, three scripted-fake wiring scenarios, privacy gates, audit records, andHumanDecisionHandoff; those capabilities are implemented and locally tested. Separately, this source tree contains one exact authenticated Codex CLI boundary for the repository-owned synthetic P1 B3 case and route. Before this exact audited tree is merged to Publicmain, the boundary is an unregistered candidate; when the tree is present on Publicmain, it is source-registered only. It is not inv0.1.0and, in either state, remains fail-closed and live-unqualified, with no accepted live result after two separately authorized historical independent-analyst attempts failed closed. No general authenticated production provider, protected persistence, P2 case continuation, independently validated decision quality, package-index distribution, hosted CI, or hosted deployment is provided.
DAF is intended for researchers, engineers, and careful individual decision makers who want a reviewable analysis trail without delegating the final decision or a real-world action to software. It is not a hosted service, autonomous agent, or general-purpose optimization solver.
Decision analyses often mix user values, uncertain facts, model assumptions, numerical calculations, LLM-generated text, private context, and actions that only a human should authorize. Without explicit boundaries, it is easy to treat a plausible narrative as evidence, run an inapplicable model, expose unnecessary context, or lose the link between a recommendation and its inputs.
DAF separates those responsibilities. Python owns canonical records, policy, routing, calculation contracts, evidence admission, audit metadata, and state transitions. A trusted Codex session may reconstruct natural language and perform bounded qualitative analysis. A human reviews the exact report candidate and remains the authority for the decision and every external effect.
- Validates versioned JSON records for cases, routes, agent artifacts, Tool requests and results, quantitative verification, evidence, reports, and human decisions.
- Deterministically routes explicit case attributes and records selected and excluded Skills, agent roles, Tools, approvals, budgets, and stop conditions.
- Provides 40 allowlisted Tools for bounded decision analysis, probability, sensitivity, multicriteria analysis, optimization, formal checks, game theory, and behavioral transformations.
- Runs a Tool only after schema, policy, unit-declaration, and applicability checks; local workers enforce bounded execution and record reproduction metadata.
- Records Tool artifacts as provenance, but requires artifact-bound quantitative verification before they may support a material numerical claim or enter a completed report.
- Minimizes structured context through a purpose allowlist, rejects P3, and requires exact single-use consent for the limited Python-API P2 export path.
- Produces a hash-bound P0/P1 report candidate and requires a later typed human decision to finalize exactly that reviewed
HumanDecisionHandoff; finalization does not execute the selected action. - Provides a process-local typed admission contract that binds exact minimized P0/P1 Context Broker output, caller-mediated procedural AgentTask/AgentResult identities, one applicable declared-exact material registered Tool and verifier projection or a verifier-backed typed qualitative fallback, reporting, and the human-decision handoff to one expiring, single-use Python-owned root. It attests none of provider execution, host transcript, provider/model identity, or independent Subagent isolation.
- Makes that contract usable through one bounded process-local
daf-mcpsession. The STDIO process owns exactly one active routing handle, derives task order and later-role sources, retains the exact bundle and pending handoff internally, and clears its minimized views on terminal cleanup. The handle is not authentication or a credential. - Exposes a local CLI, an optional trusted-local STDIO MCP adapter, generated JSON Schemas, compatibility checks, roadmap validation, and a history-aware publication scanner.
- Natural-language intake and qualitative orchestration use the repository's
run-decision-assuranceCodex Skill in a trusted subscription project session; Python itself starts from structured records. The v0.1 milestone directly demonstrates this procedural surface with one repository-owned synthetic P0 case and separated current-session Subagents. - The bounded agent controller is exercised generally by
ScriptedFakeAgentProvider. A separate identity-pinnedAuthenticatedCodexCliAgentProviderboundary in this source tree is limited to one exact repository-owned synthetic P1 B3 session; before this exact audited tree is merged to Publicmainit is an unregistered candidate, and when the tree is present on Publicmainit is source-registered only. It is not inv0.1.0. Two historical independent-analyst attempts were separately authorized and spent: the first under an at-most-two ordered-call goal that terminated after that attempt with its red-team allowance unused, and the second under a later one-call goal. Both failed closed before the Tool/verifier and red-team waves, and no live result was accepted. The latest retained safe code,provider_tool_event:independent-analyst, identifies neither the live JSONL subtype nor the initiating cause. Provider identity1.0.1observability and cleanup hardening describes source behavior of that exact boundary, remains live-unqualified, does not establish authenticated success or a fix of that historical cause, and adds no evidence to DAF-ROADMAP-006. - The evaluation harness includes typed mock/replay paths, a no-call Codex admission boundary, and a zero-call B2/B3 comparison-protocol checker. It does not provide real B2-B5 comparative evidence.
- P2 context preview/export exists as a narrow Python API, but no typed resume receipt or P2 case continuation exists.
- The offline release verifier checks a fixed local profile with complete process-tree cleanup before step advance, repository-external unique pytest basetemps, one shared deadline per candidate snapshot, and durable no-overwrite terminal file output when
--outputis supplied. The report remains self-attested, and the repository does not contain an accepted offline dependency bundle or reproducible-build proof.
DAF is advice-only. The human decision boundary never authorizes the product runtime to perform an external effect.
- No autonomous purchasing, trading, email, GitHub, release, deployment, or other external effect.
- No general authenticated production agent provider for caller-selected cases, routes, models, tiers, or durable sessions. The exact bounded Codex CLI boundary is present in this source tree; before this exact audited tree is merged to Public
mainit is an unregistered candidate, and when the tree is present on Publicmainit is source-registered only. It is not inv0.1.0and, in either state, remains fail-closed and live-unqualified after two separately authorized historical independent-analyst attempts failed closed without an accepted live result. Both live-call authorities expired, and retry, replacement, continuation, red-team execution, or any further provider/model call requires new authority. The separate opt-in saved-auth B0/B1 evaluation adapter is not a decision provider or quality-evidence path. - No GUI, web application, public service, REST API, durable multi-user store, or local-user authentication.
- No claim that a structured model represents the real world, that a recommendation is optimal for a user, or that same-model agreement is independent evidence.
- No causal-effect estimation, reinforcement learning, CFR, active-inference fitting, general mechanism design, or unrestricted solver/plugin system.
The canonical status label MVP_COMPLETE_WITH_NON_BLOCKING_LIMITATIONS refers only to the bounded local MVP. It does not mean the product or roadmap is complete. See implementation status, known limitations, and the canonical roadmap.
| Component | Current responsibility | Authority it does not have |
|---|---|---|
| Python runtime | Schemas, state, policy, routing, calculation gates, verification, ledger admission, audit metadata, and handoff binding | It does not infer ordinary language, choose user values, or execute a chosen real-world action. |
| Trusted Codex session | Optional natural-language reconstruction, bounded qualitative analysis, challenge, and synthesis through repository Skills | Its output cannot override Python policy or become independent evidence merely through role agreement. |
| Scripted fake provider | Exercises the fixed synthetic controller lifecycle | It is not a model call and is not eligible evidence of agent quality. |
| Human decision maker | Reviews the exact report and supplies the final typed decision | DAF does not act on that decision. |
flowchart TD
A["Natural-language request in a trusted Codex session, or structured JSON"] --> B["Validated CaseRecord"]
B --> C["Python policy, privacy, route, and budget gates"]
C --> D["Bounded qualitative procedure and applicable local Tools"]
D --> E["Artifact-bound quantitative verification"]
E --> F["Claim-Evidence Ledger and report candidate"]
F --> G["Exact HumanDecisionHandoff"]
G --> H["Human decision or expert referral"]
H --> I["DecisionRecord; no external effect"]
No single currently supported real-provider command traverses the entire chain. run-decision-assurance is Codex-procedural composition over Python interfaces; daf case run starts from a structured bundle; and daf synthetic run uses fixed fake-provider output.
| Requirement | Current support |
|---|---|
| Python | CPython 3.12 or 3.13 (>=3.12,<3.14). The Windows bootstrap below assumes the optional Python Launcher (py); otherwise substitute the exact path to a compliant interpreter. |
| Operating system | The post-environment workflow is verified on Windows 11. The code is intended to be portable, but the native POSIX link-boundary matrix is not yet verified. |
| Runtime packages | Pydantic 2.x, NumPy 2.x, and SciPy 1.x; exact ranges are in pyproject.toml. |
| Optional packages | z3-solver for the two formal Tools; mcp for daf-mcp; pytest and hypothesis for development. |
| Network | The Quickstart, structured case/Tool paths, and fixed synthetic scenarios make no network call after installation. Installation and the separately approved supply-chain refresh may use package hosts; the opt-in saved-auth B0/B1 evaluation adapter may invoke Codex. |
| LLM/API credentials | Not required for the structured CLI or synthetic scenarios. Ordinary-language use requires a trusted Codex session. No general authenticated provider path is supported. |
| GPU | Not required. |
| Git/GitHub CLI | Git is needed for cloning and for a complete history-aware publication scan. GitHub CLI is not a DAF runtime dependency. |
| Paid service | None for the structured CLI. The ordinary-language project workflow requires access to a trusted Codex subscription session under its own terms. |
Do not place credentials, real personal fixtures, a Private Vault, or conversation archives in the repository. Review the repository before trusting its .codex/, .agents/, or AGENTS.md project instructions.
The first public product version, package metadata, runtime version, and
annotated Git tag are all 0.1.0 / v0.1.0. The annotated tag and the
source-only GitHub Release are published. The Release is non-draft,
non-prerelease, and has no attached assets.
Earlier package values through 3.0.0 were private development compatibility
epochs, not public releases.
The exact pre-public 3.0.0 package, 6.0.0 persisted/generated schema, and
3.0.0 release-evidence set remains directly readable as non-authoritative
history. Current internal compatibility is persisted and generated schema
6.3.0 with release evidence 3.3.0; exact 3.2.0 and 3.1.0 evidence
remain non-authoritative regeneration-only historical readers.
v0.1.0 is a source-only GitHub Release governed by
release/source-release-contract.json
and release/v0.1.0.md. It is not a PyPI or other
package-index publication and does not provide a wheel or sdist. A Git clone
followed by an editable installation is the supported workflow. Generated
source archives omit .git; history-aware checks and daf synthetic run
therefore require a repository checkout.
The shortest path verified on the reviewed Windows host uses repository-owned synthetic data and makes no model or network call after installation. The post-environment Windows commands were executed directly; the py bootstrap requires a separately installed Windows Python Launcher.
git clone https://github.com/guriguri215-lang/decision-assurance-framework.git
Set-Location decision-assurance-framework
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\daf.exe doctor
.\.venv\Scripts\daf.exe case validate tests\fixtures_synthetic\case_standard.json
.\.venv\Scripts\daf.exe tool check decision.expected_value --input examples\expected-value-input.json --data-class P1
.\.venv\Scripts\daf.exe --json tool run decision.expected_value --input examples\expected-value-input.json --output runtime\expected-value-result.json --data-class P1git clone https://github.com/guriguri215-lang/decision-assurance-framework.git
cd decision-assurance-framework
python3.12 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/daf doctor
.venv/bin/daf case validate tests/fixtures_synthetic/case_standard.json
.venv/bin/daf tool check decision.expected_value --input examples/expected-value-input.json --data-class P1
.venv/bin/daf --json tool run decision.expected_value --input examples/expected-value-input.json --output runtime/expected-value-result.json --data-class P1Expected stable fields from the final command are:
{
"status": "success",
"result": {
"tool_id": "decision.expected_value",
"status": "success",
"output": {
"best_alternatives": ["reversible_trial"],
"best_value": 5.6,
"expected_values": {
"full_commitment": 5.4,
"reversible_trial": 5.6
}
},
"exact": true
}
}Timestamps, run IDs, durations, and hashes may differ. Output files under runtime/ are caller-managed local artifacts, are Git-ignored, and are not protected persistence.
The Tool command replaces an existing output at the same path; choose a new path when preserving an earlier result matters.
Open the cloned repository in a trusted Codex subscription session and state a
fully specified P0/P1 decision in ordinary language. The project
run-decision-assurance Skill should trigger automatically; it can also be
invoked explicitly as $run-decision-assurance. Review its proposed
classification before Python routing. Route-selected Subagents receive
separate minimized task payloads, and their agreement is never counted as a
vote or independent evidence.
The tracked v0.1 demonstration is
examples/codex-native-v0.1.0-case.md.
It validates the canonical case, previews one P0 Broker summary, runs
decision.expected_value through the bounded worker, binds the current-session
quantitative review, admits the report through the Claim-Evidence Ledger, and
stops at HumanDecisionHandoff. The companion synthetic finalization known
answer tests typed completion separately; it is not the live participant's
choice and performs no external effect. See
usage workflows.
examples/expected-value-input.json is a finite, synthetic payoff model:
{
"alternatives": ["reversible_trial", "full_commitment"],
"states": ["low_demand", "high_demand"],
"values": [[4.0, 8.0], [1.0, 12.0]],
"probabilities": [0.6, 0.4],
"maximize": true,
"value_unit": "synthetic_value"
}The calculation verifies only this declared model. It does not determine whether the alternatives, probabilities, values, or unit are appropriate for a real decision.
Create a structured report candidate that stops at an exact human gate:
.\.venv\Scripts\daf.exe --json case run examples\case-run-bundle.json --output runtime\pending-case.jsonThe stable status is blocked_pending_approval. Review report_markdown and human_decision_handoff before using daf case finalize; the complete non-overwriting handoff procedure is in usage workflows.
Exercise the fixed synthetic controller lifecycle:
.\.venv\Scripts\daf.exe --json synthetic run expected-value-p1-v1 --approve-high-cost --approve-completionThe three supported scenario IDs are expected-value-p1-v1, minimax-regret-p1-v1, and milp-one-hot-p0-v1. They cover only the exact repository-owned fixtures. The expected-value and minimax profiles have separate Python verification; the fixed MILP keeps SciPy's result as exact=false and uses a separate exact eight-assignment enumeration certificate for that fixture only.
- Validate and route a structured, low-sensitivity P0/P1 decision before analysis.
- Compare finite alternatives with an explicitly supplied expected-value, regret, multicriteria, sensitivity, probability, or bounded optimization model.
- Produce a report whose material claims point to admitted evidence and whose numerical claims point to a verified Tool result.
- Use a trusted Codex project session to reconstruct an ordinary-language P0/P1 decision, run bounded challenge roles, and stop at a human decision boundary.
- Expose the P0/P1 Tool catalog and one continuous procedural-session lifecycle to a trusted local STDIO MCP client with explicit structured classification.
Potential future applications that require unimplemented work include real-provider B2/B3 comparison, resumable P2 cases, protected long-lived decision records, and hosted or multi-user operation.
The public entry points are daf and the optional daf-mcp. DAF does not
auto-register MCP with Codex: install .[mcp], add the repository
environment's absolute Python interpreter as the user-managed local daf
STDIO server, and start a fresh trusted project session as documented in
Usage Workflows.
daf --help lists case, route, Tool, context, policy, audit, evaluation,
roadmap, compatibility, dependency, publication, and verification commands.
The CLI reads explicit JSON inputs and can write JSON artifacts. Tool outputs
replace an existing path; case-run and case-finalize outputs refuse an existing
path.
| Exit code | Meaning |
|---|---|
0 |
Success, or a valid P0/P1 report candidate awaiting human review |
2 |
Invalid input |
3 |
Policy denial or unavailable approval |
4 |
Capability unavailable or bounded partial result |
5 |
Suppressed numerical or internal failure |
--json is accepted before or after subcommands. daf-mcp is for one trusted
local STDIO client only; it accepts explicit P0/P1 classifications and rejects
P2/P3. Its additive procedural operations own one active in-memory session and
execute no provider call or product external effect. The older isolated MCP
case and Tool operations remain available but do not provide equivalent
procedural provenance. Python modules are implementation interfaces, not a
declared stable public library API, and may change between repository
revisions.
| Class | Meaning | Repository | Codex/export boundary |
|---|---|---|---|
| P0 | Public | Allowed | Allowed as needed |
| P1 | Internal | Purpose-limited safe artifacts only | Minimized fields only |
| P2 | Sensitive personal | Never; Private Vault only | Exact unexpired destination/purpose/field/payload/session-bound consent; no case continuation |
| P3 | Secret or credential | Never | Never exportable |
The Context Broker accepts structured values from a trusted local caller and does not recursively browse the Private Vault. A Vault must resolve outside the repository. Purpose policy 1.0.0 currently permits only summary for decision_analysis; new purposes or fields require a reviewed policy version.
The Python publication guard, not .gitignore or a Git hook, is authoritative for repository export. It scans the current candidate and enumerable Git history for disallowed paths and content. This is a repository policy control, not proof of host isolation, secret erasure, or freedom from every vulnerability. Report vulnerabilities through SECURITY.md; do not put credentials, exploit details, or P2/P3 material in a public issue. No response SLA is promised.
The repository contains unit, integration, regression, security-boundary, property, known-answer, schema-generation, CLI, compatibility, and failure-mode tests. The 40-Tool catalog has broad known-answer, property, boundary, and selected cross-check coverage; this is not a claim that every registered Tool has its own direct successful known-answer execution case. The fixed release verifier runs eleven local checks, including the complete test suite, schema and compatibility checks, roadmap synchronization, repository-language and Markdown-link checks, Git history enumeration, and publication scanning. Its subprocess supervisor contains the whole process tree, and its two pytest steps explicitly override the project default with distinct system-temporary basetemps outside the repository.
Run the current evidence locally:
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe scripts\verify_check.py markdown-links
.\.venv\Scripts\daf.exe roadmap sync-check
.\.venv\Scripts\daf.exe compatibility inspect
.\.venv\Scripts\daf.exe publish scan .
.\.venv\Scripts\daf.exe --json verify releaseHistorical local results are recorded in test evidence, but counts from an older revision are not a guarantee for this checkout. A source-only GitHub Release exists for v0.1.0, but there is no hosted CI result, package-index publication, wheel or sdist distribution, reproducible-build proof, external security audit, independent model-quality study, or expert validation of real decision outcomes. A passing self-attested local report establishes only the checks it names.
- Input quality and user-supplied assumptions bound the usefulness of every result.
- The framework checks structured contracts; it cannot validate user preferences, real-world causal structure, data completeness, or domain truth.
- Deterministic hashes and explicit seeds improve traceability, but wall-clock metadata, generated identifiers, optional LLM output, and unavailable dependency bundles limit whole-session reproducibility.
- SciPy LP, MILP, and zero-sum outputs are numerical and
exact=false; only specifically documented bounded certificates are exact. - Tool workers have fixed process, time, and memory contracts; scalability beyond the bounded tests is not characterized.
- The executable controller's exact synthetic P1 B3 Codex CLI boundary described above is present in this source tree. Before this exact audited tree is merged to Public
mainit is an unregistered candidate; when the tree is present on Publicmainit is source-registered only. It is not inv0.1.0. Two historical live attempts failed closed without an accepted result; the boundary remains fail-closed and live-unqualified and never makes same-model roles independent evidence. - Runtime authorities are process-local. Caller-managed JSON is not authenticated, encrypted, access-controlled, or protected durable storage.
- The procedural session opens Tool roots only for declared-exact, non-high-cost Tools whose materiality agrees with the routed quantitative verifier. Numerical Tools declared
exact=false, high-cost Tool roots, and inconsistent Tool/verifier combinations require another supported path or a later contract. - The procedural input filter rejects bounded syntactic absolute-path forms; it is not a semantic sensitive-data classifier. Callers must still exclude every private path and private value.
- P2 preview/export does not provide a typed receipt, checkpoint, idempotent resume, or case continuation. P3 is rejected.
- The reviewed host is Windows 11. Native POSIX link-boundary behavior remains unverified, and platform-specific skips must not be counted as passes.
- There is no GUI, hosted API, installer, package-index publication, wheel/sdist distribution, hosted CI, active offline dependency bundle, or documented backward-compatible public Python API. The v0.1 contract is source-only.
- Application deletion cannot prove physical-media, swap, crash-dump, transcript, or independent-backup erasure.
See known limitations and unresolved findings for the governed detail.
src/decision_assurance/ Python authority: schemas, policy, routing, Tools, orchestration, reporting
tests/ Unit, integration, regression, and security-boundary tests
schemas/ Generated JSON Schema views of Python models
examples/ Synthetic JSON inputs for documented CLI paths
evals/ Synthetic evaluation fixture, rubric, and manifest
docs/ Architecture, security, privacy, usage, roadmap, ADR, and review evidence
roadmap/backlog.json Canonical machine-readable product backlog
release/ Declared inputs, v0.1 notes, and source-release contract
.agents/ and .codex/ Trusted-session Skills and bounded role configuration
- Usage workflows and synthetic sample report
- Architecture overview and implementation plan
- Implementation status and canonical roadmap
- Security threat model, privacy governance, and publishing and maintenance
- Deterministic Tool catalog
- Evaluation harness
- Architecture decisions
- Review evidence and unresolved findings
| Status | Scope |
|---|---|
| Implemented | Canonical records, structured P0/P1 coordinator, routing, registered Tools, evidence ledger, reports, HumanDecisionHandoff, audit chain, compatibility/schema checks, and publication guard |
| Partial | Private context, maintenance isolation, evaluation harness, Codex integration, offline release supply chain, and bounded agent-controller wiring |
| Planned, deferred, or unresolved | Real provider execution and evaluation, advanced mathematical methods pending complete structure, semantic units, P2 receipt/resume, protected persistence, verified network maintenance, native POSIX boundary verification, and distribution/CI evidence |
| Rejected for the MVP | Autonomous product external effects |
The machine-readable source is roadmap/backlog.json; docs/roadmap.md is its synchronized rendering.
Read CONTRIBUTING.md, SUPPORT.md, and SECURITY.md before opening an issue. Issues are for reproducible bugs and documentation gaps, not vulnerabilities or support commitments. Do not submit real private data, credentials, prompts, provider responses, or conversation archives. No response SLA is promised.
DAF is available under the MIT License. The license does not provide a warranty of decision quality, fitness for a particular purpose, security, or correctness of user-supplied models.