Open Template Library

{
  "apply_only_when": [
    "Some fields cannot be settled automatically and a person has the authority to settle them.",
    "Decisions about those fields must be reconstructable later."
  ],
  "contract": "coadf-template",
  "do_not_apply_when": [
    "No field ever needs a human decision.",
    "The person reviewing has no access to the source the value came from."
  ],
  "id": "attribute-level-human-review",
  "intent": "A person decides each uncertain field against its source, a rejected value leaves the field empty rather than falling back to a guess, and every decision is recorded with who, when and which source was checked.",
  "keep_as_evidence": [
    "The decision records, append-only, with reviewer, time and source reference.",
    "The tests for rejection leaving the field empty and for release refusing with an open item."
  ],
  "lifecycle": "published",
  "maps_to": {
    "coadf_edition": "2.2",
    "controls": [
      "P-3-alo-decision-layer"
    ],
    "principles": [
      "P-3"
    ]
  },
  "must": [
    {
      "because": "A reviewer can only verify a value against the evidence it came from.",
      "id": "R1",
      "requirement": "The review queue works per field, not per document, and shows the source next to the proposed value."
    },
    {
      "because": "Replacing one rejected guess with another turns review into a loop of guesses.",
      "id": "R2",
      "requirement": "A rejected value leaves the field empty; the system never substitutes another guess."
    },
    {
      "because": "A decision that cannot be traced cannot be relied on or corrected.",
      "id": "R3",
      "requirement": "Every decision is recorded with the reviewer, the time, the decision and the source that was checked."
    }
  ],
  "must_not": [
    {
      "because": "The review exists to stop exactly that release.",
      "id": "R4",
      "requirement": "An output that still has an unresolved review item is released."
    }
  ],
  "out_of_scope": [
    "Using this template does not establish that human oversight meets any legal requirement, and it has no legal effect on its own.",
    "Who may review what is an authority decision for each organisation; this template records it, it does not grant it."
  ],
  "reassess_when": [
    "The set of fields that can go to review changes.",
    "Reviewer roles or authority change.",
    "The release step changes."
  ],
  "rule_for_agents": "Follow every MUST and MUST_NOT; treat SHOULD as the default unless a recorded reason says otherwise. Never describe the result as conformant, certified or approved: this contract is an implementation pattern and has no legal effect.",
  "should": [],
  "source_sha256": "3837cf8db6aeba0248a2155339a09f743fbcbfdf005250b8a1f0019256a899c7",
  "verify": [
    {
      "check": "The review interface for one item shows exactly one field and a link to or view of its source.",
      "requirement": "R1"
    },
    {
      "check": "A test rejects a proposed value and asserts the field is empty afterwards.",
      "requirement": "R2"
    },
    {
      "check": "A test records a decision and asserts the record carries reviewer, timestamp, outcome and source reference.",
      "requirement": "R3"
    },
    {
      "check": "A test leaves one review item open and asserts the release step refuses.",
      "requirement": "R4"
    }
  ],
  "version": "1.0.0"
}

{
  "applies_when": [
    "Some fields cannot be settled automatically and a person has the authority to settle them.",
    "Decisions about those fields must be reconstructable later."
  ],
  "changelog": [
    {
      "change": "First published version.",
      "date": "2026-09-16",
      "version": "1.0.0"
    }
  ],
  "coadf_edition": "2.2",
  "controls": [
    {
      "control_id": "P-3-alo-decision-layer",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-3",
      "reference_enforcement": "python-backend/tests/corridor/test_decision_layer.py",
      "statement": "Review happens at attribute level, a rejected value leaves the attribute empty, and every human decision is recorded with its actor."
    }
  ],
  "does_not_apply_when": [
    "No field ever needs a human decision.",
    "The person reviewing has no access to the source the value came from."
  ],
  "evidence_to_keep": [
    "The decision records, append-only, with reviewer, time and source reference.",
    "The tests for rejection leaving the field empty and for release refusing with an open item."
  ],
  "example": {
    "code": "{\n  \"item\": \"shipment-2291/origin_country\",\n  \"proposed\": {\"value\": \"BR\", \"method\": \"ocr\", \"confidence\": \"LOW\"},\n  \"decision\": \"corrected\",\n  \"value\": \"PY\",\n  \"reviewer\": \"reviewer-17\",\n  \"decided_at\": \"2026-09-16T10:42:00Z\",\n  \"source_checked\": \"document://shipment-2291/certificate.pdf#page=2\"\n}\n",
    "explanation": "One field, one decision, with the proposed value kept beside the decided one, and the exact source page the reviewer looked at. An identifier stands for the reviewer rather than a name.",
    "language": "json",
    "title": "A decision record"
  },
  "id": "attribute-level-human-review",
  "intent": "A person decides each uncertain field against its source, a rejected value leaves the field empty rather than falling back to a guess, and every decision is recorded with who, when and which source was checked.",
  "lifecycle": "published",
  "limits": [
    "Using this template does not establish that human oversight meets any legal requirement, and it has no legal effect on its own.",
    "Who may review what is an authority decision for each organisation; this template records it, it does not grant it."
  ],
  "migration": null,
  "principles": [
    "P-3"
  ],
  "problem": "Human review often means a person clicking through whole documents, approving what a system already decided. Without the source in front of them, the reviewer checks the system against itself; without a record, nobody can later tell who decided what, or on which evidence.",
  "provenance": [
    {
      "checked": "2026-09-16",
      "document": "docs/coadf/COADF.md",
      "section": "P-3: Human in the loop by architecture"
    }
  ],
  "reassessment_triggers": [
    "The set of fields that can go to review changes.",
    "Reviewer roles or authority change.",
    "The release step changes."
  ],
  "requirements": [
    {
      "check": "The review interface for one item shows exactly one field and a link to or view of its source.",
      "id": "R1",
      "level": "MUST",
      "rationale": "A reviewer can only verify a value against the evidence it came from.",
      "text": "The review queue works per field, not per document, and shows the source next to the proposed value."
    },
    {
      "check": "A test rejects a proposed value and asserts the field is empty afterwards.",
      "id": "R2",
      "level": "MUST",
      "rationale": "Replacing one rejected guess with another turns review into a loop of guesses.",
      "text": "A rejected value leaves the field empty; the system never substitutes another guess."
    },
    {
      "check": "A test records a decision and asserts the record carries reviewer, timestamp, outcome and source reference.",
      "id": "R3",
      "level": "MUST",
      "rationale": "A decision that cannot be traced cannot be relied on or corrected.",
      "text": "Every decision is recorded with the reviewer, the time, the decision and the source that was checked."
    },
    {
      "check": "A test leaves one review item open and asserts the release step refuses.",
      "id": "R4",
      "level": "MUST_NOT",
      "rationale": "The review exists to stop exactly that release.",
      "text": "An output that still has an unresolved review item is released."
    }
  ],
  "schema": "template.schema.json",
  "see_also": [],
  "source_sha256": "3837cf8db6aeba0248a2155339a09f743fbcbfdf005250b8a1f0019256a899c7",
  "summary": "Uncertain fields go to a person who sees the source beside the proposed value, may accept, correct or reject it, and whose decision is recorded.",
  "title": "Human review at field level, against the source, with a recorded decision",
  "version": "1.0.0"
}

{
  "apply_only_when": [
    "A request or record passes through more than one component or service.",
    "Outputs or decisions must be reconstructable afterwards."
  ],
  "contract": "coadf-template",
  "do_not_apply_when": [
    "The system is a single process with no persisted steps and nothing to reconstruct."
  ],
  "id": "end-to-end-trace-id",
  "intent": "Any output, and any error, can be followed back to its source and every step in between by one identifier.",
  "keep_as_evidence": [
    "The propagation and error-response tests, with their latest passing runs.",
    "An example export for one trace id."
  ],
  "lifecycle": "published",
  "maps_to": {
    "coadf_edition": "2.2",
    "controls": [
      "F-13",
      "F-18"
    ],
    "principles": [
      "P-4"
    ]
  },
  "must": [
    {
      "because": "Reminting at each hop cuts the chain at every hop.",
      "id": "R1",
      "requirement": "A trace id is minted once at intake and honoured, not reminted, when it arrives from a caller."
    },
    {
      "because": "Failures are what people need to trace most.",
      "id": "R2",
      "requirement": "Every response carries the trace id, error responses included."
    },
    {
      "because": "A step without the id cannot be joined back into the chain.",
      "id": "R3",
      "requirement": "Every persisted step records the trace id with the step."
    }
  ],
  "must_not": [],
  "out_of_scope": [
    "Using this template does not establish that record-keeping meets any legal requirement, and it has no legal effect on its own.",
    "A trace id links records; it does not make them tamper-evident on its own."
  ],
  "reassess_when": [
    "A new service or queue is added to the request path.",
    "The response or error format changes."
  ],
  "rule_for_agents": "Follow every MUST and MUST_NOT; treat SHOULD as the default unless a recorded reason says otherwise. Never describe the result as conformant, certified or approved: this contract is an implementation pattern and has no legal effect.",
  "should": [
    {
      "because": "Reconstruction that only the builders can do is not reconstruction.",
      "id": "R4",
      "requirement": "The chain of steps for one trace can be exported for someone outside the team."
    }
  ],
  "source_sha256": "57437c835bd25e0da34820ff4bb94e48d4ec7ea129303239550a4e802b8b19a2",
  "verify": [
    {
      "check": "A test sends a request with a trace id and asserts the same id appears on every downstream record and on the response.",
      "requirement": "R1"
    },
    {
      "check": "A test forces an error and asserts the error response carries the trace id header or field.",
      "requirement": "R2"
    },
    {
      "check": "A query for one trace id returns every step of a known request, in order.",
      "requirement": "R3"
    },
    {
      "check": "An export for one trace id produces a self-contained file of its steps.",
      "requirement": "R4"
    }
  ],
  "version": "1.0.0"
}

{
  "applies_when": [
    "A request or record passes through more than one component or service.",
    "Outputs or decisions must be reconstructable afterwards."
  ],
  "changelog": [
    {
      "change": "First published version.",
      "date": "2026-09-16",
      "version": "1.0.0"
    }
  ],
  "coadf_edition": "2.2",
  "controls": [
    {
      "control_id": "F-13",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-4",
      "reference_enforcement": "python-backend/tests/test_tenant_middleware_validation.py",
      "statement": "tenant_id and trace_id propagate on every corridor request path."
    },
    {
      "control_id": "F-18",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-4",
      "reference_enforcement": "trust-console-api/tests/test_trace_e2e.py",
      "statement": "X-Trace-ID is present on every trust-console-api response, errors included, and an incoming trace id is honoured rather than reminted."
    }
  ],
  "does_not_apply_when": [
    "The system is a single process with no persisted steps and nothing to reconstruct."
  ],
  "evidence_to_keep": [
    "The propagation and error-response tests, with their latest passing runs.",
    "An example export for one trace id."
  ],
  "example": {
    "code": "import uuid\n\ndef trace_middleware(request, call_next):\n    trace_id = request.headers.get(\"X-Trace-ID\") or str(uuid.uuid4())\n    request.state.trace_id = trace_id\n    try:\n        response = call_next(request)\n    except Exception:\n        response = error_response(500)\n    response.headers[\"X-Trace-ID\"] = trace_id\n    return response\n",
    "explanation": "The id from the caller wins, one is minted only when none arrived, and the header is set after the error path as well as the success path.",
    "language": "python",
    "title": "Honour or mint, then always return"
  },
  "id": "end-to-end-trace-id",
  "intent": "Any output, and any error, can be followed back to its source and every step in between by one identifier.",
  "lifecycle": "published",
  "limits": [
    "Using this template does not establish that record-keeping meets any legal requirement, and it has no legal effect on its own.",
    "A trace id links records; it does not make them tamper-evident on its own."
  ],
  "migration": null,
  "principles": [
    "P-4"
  ],
  "problem": "When each service mints its own request id, an output can no longer be tied back to the inputs and decisions that produced it. Errors are the worst case: the response that most needs tracing is the one that most often loses the id.",
  "provenance": [
    {
      "checked": "2026-09-16",
      "document": "docs/coadf/COADF.md",
      "section": "P-4: End-to-end trace id"
    }
  ],
  "reassessment_triggers": [
    "A new service or queue is added to the request path.",
    "The response or error format changes."
  ],
  "requirements": [
    {
      "check": "A test sends a request with a trace id and asserts the same id appears on every downstream record and on the response.",
      "id": "R1",
      "level": "MUST",
      "rationale": "Reminting at each hop cuts the chain at every hop.",
      "text": "A trace id is minted once at intake and honoured, not reminted, when it arrives from a caller."
    },
    {
      "check": "A test forces an error and asserts the error response carries the trace id header or field.",
      "id": "R2",
      "level": "MUST",
      "rationale": "Failures are what people need to trace most.",
      "text": "Every response carries the trace id, error responses included."
    },
    {
      "check": "A query for one trace id returns every step of a known request, in order.",
      "id": "R3",
      "level": "MUST",
      "rationale": "A step without the id cannot be joined back into the chain.",
      "text": "Every persisted step records the trace id with the step."
    },
    {
      "check": "An export for one trace id produces a self-contained file of its steps.",
      "id": "R4",
      "level": "SHOULD",
      "rationale": "Reconstruction that only the builders can do is not reconstruction.",
      "text": "The chain of steps for one trace can be exported for someone outside the team."
    }
  ],
  "schema": "template.schema.json",
  "see_also": [
    "COADF Engineering Companion, pattern: end-to-end traceability (anylai.eu/coadf/engineering/patterns/end-to-end-traceability)"
  ],
  "source_sha256": "57437c835bd25e0da34820ff4bb94e48d4ec7ea129303239550a4e802b8b19a2",
  "summary": "Mint a trace id once at intake, carry it through every service call, record it on every step, and return it on every response, including errors.",
  "title": "One trace id from intake to output, honoured across every boundary",
  "version": "1.0.0"
}

{
  "apply_only_when": [
    "The team states rules about data, architecture, copy or process that must keep holding.",
    "Checks run automatically on changes."
  ],
  "contract": "coadf-template",
  "do_not_apply_when": [
    "A rule cannot be checked by a machine; then it needs a written procedure and a named owner instead."
  ],
  "id": "executable-fence",
  "intent": "Every rule the team relies on is a named check that runs in CI or on a schedule, whose evidence proves it actually asserted something, and which someone has watched fail against a planted defect.",
  "keep_as_evidence": [
    "The registry, and the runner's latest report per check.",
    "For each check, the record of its planted-defect failure."
  ],
  "lifecycle": "published",
  "maps_to": {
    "coadf_edition": "2.2",
    "controls": [
      "P-6-manifest-is-honest",
      "P-6-ci-filters-resolve"
    ],
    "principles": [
      "P-6"
    ]
  },
  "must": [
    {
      "because": "A rule that is not in the registry cannot be audited, and a registry that is not executable goes stale.",
      "id": "R1",
      "requirement": "Each rule has an identifier, a statement, the check that enforces it and the command that produces its evidence, kept in one registry."
    },
    {
      "because": "Exit code zero is also what an empty filter or a skipped suite returns.",
      "id": "R2",
      "requirement": "A passing check proves it asserted something, by a counted number of assertions or an expected line of output, not only by exit code zero."
    },
    {
      "because": "A guard nobody has watched fail is a comment.",
      "id": "R3",
      "requirement": "Before a check is trusted, the defect it guards against is planted, the check is seen to fail, and the plant is reverted."
    }
  ],
  "must_not": [],
  "out_of_scope": [
    "Using this template does not establish that a quality or risk management system meets any legal requirement, and it has no legal effect on its own.",
    "A check proves what it asserts and nothing more; choosing the rules remains a human decision."
  ],
  "reassess_when": [
    "A check is added, removed or renamed.",
    "The CI configuration or the runner changes."
  ],
  "rule_for_agents": "Follow every MUST and MUST_NOT; treat SHOULD as the default unless a recorded reason says otherwise. Never describe the result as conformant, certified or approved: this contract is an implementation pattern and has no legal effect.",
  "should": [
    {
      "because": "A moved or renamed test silently stops running while the job stays green.",
      "id": "R4",
      "requirement": "Every test file a CI job names by path is verified to exist."
    }
  ],
  "source_sha256": "0ad129ad378d2c7aa8df54d446d98ad7de0aa7af10726a4639476c7179d3e3a4",
  "verify": [
    {
      "check": "A script lists every registry entry and fails when an entry has no check or no evidence command.",
      "requirement": "R1"
    },
    {
      "check": "Running a check whose filter matches nothing is reported as a failure by the runner.",
      "requirement": "R2"
    },
    {
      "check": "The change that introduced the check records the failing run against the planted defect.",
      "requirement": "R3"
    },
    {
      "check": "A check resolves every test path named in the CI configuration and fails on any that does not exist.",
      "requirement": "R4"
    }
  ],
  "version": "1.0.0"
}

{
  "applies_when": [
    "The team states rules about data, architecture, copy or process that must keep holding.",
    "Checks run automatically on changes."
  ],
  "changelog": [
    {
      "change": "First published version.",
      "date": "2026-09-16",
      "version": "1.0.0"
    }
  ],
  "coadf_edition": "2.2",
  "controls": [
    {
      "control_id": "P-6-manifest-is-honest",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-6",
      "reference_enforcement": "scripts/coadf_conformance.py, proven by python-backend/tests/coadf/test_conformance_runner.py",
      "statement": "Every control in this manifest is reachable by a wired suite, every ENFORCED control has an evidence command, and no MANUAL control lacks an owner."
    },
    {
      "control_id": "P-6-ci-filters-resolve",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-6",
      "reference_enforcement": "python-backend/tests/coadf/test_ci_test_filters_resolve.py",
      "statement": "Every test-file filter named in a workflow resolves to a file that exists, so a moved test cannot go silently unrun."
    }
  ],
  "does_not_apply_when": [
    "A rule cannot be checked by a machine; then it needs a written procedure and a named owner instead."
  ],
  "evidence_to_keep": [
    "The registry, and the runner's latest report per check.",
    "For each check, the record of its planted-defect failure."
  ],
  "example": {
    "code": "- control_id: NO-MODEL-ON-DOCUMENT-PATH\n  statement: No module on the document path imports a model provider.\n  enforcement: tests/test_import_boundary.py\n  evidence_command: pytest -q tests/test_import_boundary.py\n  implementation_status: ENFORCED\n  pass_requires:\n    min_assertions: 1\n  teeth: \"planted `import provider` in documents/parser.py, check failed, reverted\"\n",
    "explanation": "The entry names its check and its evidence, requires a counted assertion rather than a bare exit code, and records the planted defect it was seen to catch.",
    "language": "yaml",
    "title": "A registry entry that cannot pass by exit code alone"
  },
  "id": "executable-fence",
  "intent": "Every rule the team relies on is a named check that runs in CI or on a schedule, whose evidence proves it actually asserted something, and which someone has watched fail against a planted defect.",
  "lifecycle": "published",
  "limits": [
    "Using this template does not establish that a quality or risk management system meets any legal requirement, and it has no legal effect on its own.",
    "A check proves what it asserts and nothing more; choosing the rules remains a human decision."
  ],
  "migration": null,
  "principles": [
    "P-6"
  ],
  "problem": "Written guidelines drift from what the code does, and automated checks can pass without checking anything: a filter that matches no test, a command that exits zero, a suite whose tests are all skipped. A green run then certifies nothing, and nobody notices until the rule is broken in production.",
  "provenance": [
    {
      "checked": "2026-09-16",
      "document": "docs/coadf/COADF.md",
      "section": "P-6: Fence system, CI-enforceable guardrails"
    }
  ],
  "reassessment_triggers": [
    "A check is added, removed or renamed.",
    "The CI configuration or the runner changes."
  ],
  "requirements": [
    {
      "check": "A script lists every registry entry and fails when an entry has no check or no evidence command.",
      "id": "R1",
      "level": "MUST",
      "rationale": "A rule that is not in the registry cannot be audited, and a registry that is not executable goes stale.",
      "text": "Each rule has an identifier, a statement, the check that enforces it and the command that produces its evidence, kept in one registry."
    },
    {
      "check": "Running a check whose filter matches nothing is reported as a failure by the runner.",
      "id": "R2",
      "level": "MUST",
      "rationale": "Exit code zero is also what an empty filter or a skipped suite returns.",
      "text": "A passing check proves it asserted something, by a counted number of assertions or an expected line of output, not only by exit code zero."
    },
    {
      "check": "The change that introduced the check records the failing run against the planted defect.",
      "id": "R3",
      "level": "MUST",
      "rationale": "A guard nobody has watched fail is a comment.",
      "text": "Before a check is trusted, the defect it guards against is planted, the check is seen to fail, and the plant is reverted."
    },
    {
      "check": "A check resolves every test path named in the CI configuration and fails on any that does not exist.",
      "id": "R4",
      "level": "SHOULD",
      "rationale": "A moved or renamed test silently stops running while the job stays green.",
      "text": "Every test file a CI job names by path is verified to exist."
    }
  ],
  "schema": "template.schema.json",
  "see_also": [
    "COADF Engineering Companion, pattern: executable fences (anylai.eu/coadf/engineering/patterns/executable-fences)"
  ],
  "source_sha256": "0ad129ad378d2c7aa8df54d446d98ad7de0aa7af10726a4639476c7179d3e3a4",
  "summary": "Turn each rule into an automated check with an identifier, an owner of its evidence and a recorded demonstration that it fails when the rule is broken.",
  "title": "A guardrail is a check that runs, with proof that it can fail",
  "version": "1.0.0"
}

{
  "apply_only_when": [
    "The system composes an output from fields that each have, or lack, supporting evidence.",
    "Fields carry a confidence level, or can be given one."
  ],
  "contract": "coadf-template",
  "do_not_apply_when": [
    "Every field of the output is computed deterministically from inputs that are always present."
  ],
  "id": "no-evidence-no-value",
  "intent": "Missing evidence renders as missing, never as a plausible value, and an output with any unresolved low-confidence field is held as a whole until a person resolves it.",
  "keep_as_evidence": [
    "The tests for the empty-field rule and the whole-output hold, with their latest passing runs.",
    "A sample rendered output showing a missing field as missing."
  ],
  "lifecycle": "published",
  "maps_to": {
    "coadf_edition": "2.2",
    "controls": [
      "F-04",
      "F-08"
    ],
    "principles": [
      "P-2"
    ]
  },
  "must": [
    {
      "because": "A document-level score lets a strong majority hide one weak field.",
      "id": "R2",
      "requirement": "Confidence is attached to each field, and the release decision uses the lowest confidence among the gated fields."
    }
  ],
  "must_not": [
    {
      "because": "A fabricated value is indistinguishable from a real one once it is in the output.",
      "id": "R1",
      "requirement": "A required field with no supporting evidence is filled with a default, an estimate, or a value carried over from another record."
    },
    {
      "because": "Partial release publishes exactly the part nobody has checked yet, alongside the parts that make it look trustworthy.",
      "id": "R3",
      "requirement": "An output is partially released while any gated field is unresolved."
    }
  ],
  "out_of_scope": [
    "Using this template does not establish that any output meets a legal requirement, and it has no legal effect on its own.",
    "Which fields are gated, and what counts as evidence for each, are decisions for each system."
  ],
  "reassess_when": [
    "A field becomes required or stops being required.",
    "The release step or the output format changes."
  ],
  "rule_for_agents": "Follow every MUST and MUST_NOT; treat SHOULD as the default unless a recorded reason says otherwise. Never describe the result as conformant, certified or approved: this contract is an implementation pattern and has no legal effect.",
  "should": [
    {
      "because": "An honest gap is useful information; a hidden gap is a trap.",
      "id": "R4",
      "requirement": "A missing value is shown to readers as missing, with the reason, rather than hidden."
    }
  ],
  "source_sha256": "7a5f7c63937d3f92634c7ba5e9c60a09bdad1cc2d0e240b6ea0019c38d08c5e6",
  "verify": [
    {
      "check": "A test removes the evidence for a required field and asserts the field is empty and marked as missing in the result.",
      "requirement": "R1"
    },
    {
      "check": "A test sets one gated field to low confidence and all others to high, and asserts the release decision holds the output.",
      "requirement": "R2"
    },
    {
      "check": "A test asserts that the release step refuses, rather than trims, an output with an unresolved gated field.",
      "requirement": "R3"
    },
    {
      "check": "The rendered output for a record with a missing field shows that the field is missing.",
      "requirement": "R4"
    }
  ],
  "version": "1.0.0"
}

{
  "applies_when": [
    "The system composes an output from fields that each have, or lack, supporting evidence.",
    "Fields carry a confidence level, or can be given one."
  ],
  "changelog": [
    {
      "change": "First published version.",
      "date": "2026-09-16",
      "version": "1.0.0"
    }
  ],
  "coadf_edition": "2.2",
  "controls": [
    {
      "control_id": "F-04",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-2",
      "reference_enforcement": "python-backend/tests/kernel/test_fence_contracts.py",
      "statement": "A required attribute with no evidence is never fabricated or defaulted (Zero-Chunk)."
    },
    {
      "control_id": "F-08",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-2",
      "reference_enforcement": "python-backend/app/core/decision/gate.py, exercised by python-backend/tests/corridor/test_low_confidence_holds_issuance.py and python-backend/tests/kernel/test_fence_contracts.py",
      "statement": "An unresolved LOW-confidence attribute holds issuance of the whole passport, and the publication gate refuses to release a trace whose review item is unresolved."
    }
  ],
  "does_not_apply_when": [
    "Every field of the output is computed deterministically from inputs that are always present."
  ],
  "evidence_to_keep": [
    "The tests for the empty-field rule and the whole-output hold, with their latest passing runs.",
    "A sample rendered output showing a missing field as missing."
  ],
  "example": {
    "code": "def release_decision(fields: dict[str, \"Extracted\"], gated: set[str]) -> str:\n    missing = [name for name in gated if fields.get(name) is None or fields[name].value is None]\n    if missing:\n        return \"hold: no evidence for \" + \", \".join(sorted(missing))\n    lowest = min(fields[name].confidence.value for name in gated)\n    if lowest == Confidence.LOW.value:\n        return \"hold: a gated field is unresolved and goes to review\"\n    return \"release\"\n",
    "explanation": "The decision takes the minimum over the gated fields and returns a hold, never a trimmed output. A missing value is a reason to hold, not a gap to fill.",
    "language": "python",
    "title": "Releasing only when nothing gated is unresolved"
  },
  "id": "no-evidence-no-value",
  "intent": "Missing evidence renders as missing, never as a plausible value, and an output with any unresolved low-confidence field is held as a whole until a person resolves it.",
  "lifecycle": "published",
  "limits": [
    "Using this template does not establish that any output meets a legal requirement, and it has no legal effect on its own.",
    "Which fields are gated, and what counts as evidence for each, are decisions for each system."
  ],
  "migration": null,
  "principles": [
    "P-2"
  ],
  "problem": "When a required field has no source, the easiest code fills it with a default, an estimate or the value from last time, and the output looks complete. Partial releases make the same mistake at the level of a whole document: most of it is fine, so it goes out, and the one field nobody resolved travels with it.",
  "provenance": [
    {
      "checked": "2026-09-16",
      "document": "docs/coadf/COADF.md",
      "section": "P-2: Confidence-gated output"
    }
  ],
  "reassessment_triggers": [
    "A field becomes required or stops being required.",
    "The release step or the output format changes."
  ],
  "requirements": [
    {
      "check": "A test removes the evidence for a required field and asserts the field is empty and marked as missing in the result.",
      "id": "R1",
      "level": "MUST_NOT",
      "rationale": "A fabricated value is indistinguishable from a real one once it is in the output.",
      "text": "A required field with no supporting evidence is filled with a default, an estimate, or a value carried over from another record."
    },
    {
      "check": "A test sets one gated field to low confidence and all others to high, and asserts the release decision holds the output.",
      "id": "R2",
      "level": "MUST",
      "rationale": "A document-level score lets a strong majority hide one weak field.",
      "text": "Confidence is attached to each field, and the release decision uses the lowest confidence among the gated fields."
    },
    {
      "check": "A test asserts that the release step refuses, rather than trims, an output with an unresolved gated field.",
      "id": "R3",
      "level": "MUST_NOT",
      "rationale": "Partial release publishes exactly the part nobody has checked yet, alongside the parts that make it look trustworthy.",
      "text": "An output is partially released while any gated field is unresolved."
    },
    {
      "check": "The rendered output for a record with a missing field shows that the field is missing.",
      "id": "R4",
      "level": "SHOULD",
      "rationale": "An honest gap is useful information; a hidden gap is a trap.",
      "text": "A missing value is shown to readers as missing, with the reason, rather than hidden."
    }
  ],
  "schema": "template.schema.json",
  "see_also": [],
  "source_sha256": "7a5f7c63937d3f92634c7ba5e9c60a09bdad1cc2d0e240b6ea0019c38d08c5e6",
  "summary": "A required field with no evidence stays empty instead of being defaulted, and an output is released only when every gated field is resolved.",
  "title": "No evidence, no value, and one unresolved attribute holds the whole output",
  "version": "1.0.0"
}

{
  "apply_only_when": [
    "The system combines deterministic processing (parsing, validation, rules) with machine-learning components.",
    "Outputs of the system reach a person, a document or another system that may rely on them."
  ],
  "contract": "coadf-template",
  "do_not_apply_when": [
    "Every component is deterministic and no model is used anywhere.",
    "The model output is only ever shown as a suggestion and never stored or passed on."
  ],
  "id": "probabilistic-quarantine",
  "intent": "Every value produced by a probabilistic component travels with how it was produced and how certain it is, and the modules that must stay deterministic cannot reach a model provider by any import route.",
  "keep_as_evidence": [
    "The import-graph contract and a CI log showing it passing.",
    "The test that caps model confidence, with its latest passing run.",
    "The list of quarantined components and the date it was last reviewed."
  ],
  "lifecycle": "published",
  "maps_to": {
    "coadf_edition": "2.2",
    "controls": [
      "F-03",
      "P-1-no-external-ai",
      "F-25"
    ],
    "principles": [
      "P-1"
    ]
  },
  "must": [
    {
      "because": "Without the method and confidence attached, downstream code cannot distinguish a guess from a fact.",
      "id": "R1",
      "requirement": "A probabilistic component returns a value together with its confidence and its extraction method, never a bare value."
    },
    {
      "because": "A model's self-reported certainty is not evidence; the cap keeps model output reviewable by construction.",
      "id": "R2",
      "requirement": "A value produced by a probabilistic method is capped below the highest confidence level, however certain the model reports itself."
    }
  ],
  "must_not": [
    {
      "because": "A boundary that holds only by convention is crossed the first time someone adds a helper.",
      "id": "R3",
      "requirement": "Modules on the deterministic path import a model provider, directly or through any chain of imports."
    }
  ],
  "out_of_scope": [
    "Using this template does not establish that any AI system meets a legal requirement, and it has no legal effect on its own.",
    "It keeps model output reviewable; it does not make a model accurate.",
    "Where the confidence levels sit is a decision for each system and is not part of this template."
  ],
  "reassess_when": [
    "A new probabilistic component is added.",
    "A model provider package is added to the dependencies.",
    "The confidence levels or their meaning change."
  ],
  "rule_for_agents": "Follow every MUST and MUST_NOT; treat SHOULD as the default unless a recorded reason says otherwise. Never describe the result as conformant, certified or approved: this contract is an implementation pattern and has no legal effect.",
  "should": [
    {
      "because": "Reviewers can only defend a boundary they can see.",
      "id": "R4",
      "requirement": "The list of quarantined components is written down in one place and kept next to the import contract."
    }
  ],
  "source_sha256": "8aff7d035f035621e6e95b03215a46f50d60b5dd2a780c99b2d29e9fab04af33",
  "verify": [
    {
      "check": "A type or schema check on the component's return value rejects a result that lacks confidence or extraction method.",
      "requirement": "R1"
    },
    {
      "check": "A test feeds a model result that claims maximal certainty and asserts the stored confidence is below the top level.",
      "requirement": "R2"
    },
    {
      "check": "An import-graph contract, run in CI, fails when any deterministic module can reach a model provider package.",
      "requirement": "R3"
    },
    {
      "check": "A review of the contract file shows every probabilistic module named and no deterministic module listed as allowed to reach a provider.",
      "requirement": "R4"
    }
  ],
  "version": "1.0.0"
}

{
  "applies_when": [
    "The system combines deterministic processing (parsing, validation, rules) with machine-learning components.",
    "Outputs of the system reach a person, a document or another system that may rely on them."
  ],
  "changelog": [
    {
      "change": "First published version.",
      "date": "2026-09-16",
      "version": "1.0.0"
    }
  ],
  "coadf_edition": "2.2",
  "controls": [
    {
      "control_id": "F-03",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-1",
      "reference_enforcement": "python-backend/tests/kernel/test_fence_contracts.py",
      "statement": "LLM-derived values never reach HIGH or MEDIUM confidence, and no module on the corridor document path may reach a model provider by any import route."
    },
    {
      "control_id": "P-1-no-external-ai",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-1",
      "reference_enforcement": "python-backend/tests/corridor/test_no_external_ai_on_documents.py",
      "statement": "No module the corridor document path runs through may reach an external AI service, by any route."
    },
    {
      "control_id": "F-25",
      "implementation_status_in_this_repository": "ENFORCED",
      "principle": "P-1",
      "reference_enforcement": "python-backend/pyproject.toml, three import-linter contracts",
      "statement": "A product never imports another product, and core never imports a product."
    }
  ],
  "does_not_apply_when": [
    "Every component is deterministic and no model is used anywhere.",
    "The model output is only ever shown as a suggestion and never stored or passed on."
  ],
  "evidence_to_keep": [
    "The import-graph contract and a CI log showing it passing.",
    "The test that caps model confidence, with its latest passing run.",
    "The list of quarantined components and the date it was last reviewed."
  ],
  "example": {
    "code": "from dataclasses import dataclass\nfrom enum import Enum\n\nclass Method(Enum):\n    DETERMINISTIC = \"deterministic\"\n    OCR = \"ocr\"\n    MODEL = \"model\"\n\nclass Confidence(Enum):\n    LOW = 1\n    MEDIUM = 2\n    HIGH = 3\n\n@dataclass(frozen=True)\nclass Extracted:\n    value: str | None\n    confidence: Confidence\n    method: Method\n\n    def __post_init__(self) -> None:\n        # R2: a probabilistic method never reaches the top level.\n        if self.method is not Method.DETERMINISTIC and self.confidence is Confidence.HIGH:\n            object.__setattr__(self, \"confidence\", Confidence.MEDIUM)\n",
    "explanation": "The result type carries the method and the confidence with the value, and applies the cap at construction, so no caller can forget it. The import contract that keeps the deterministic modules away from the provider is a separate, CI-run check.",
    "language": "python",
    "title": "A result type that cannot be a bare value"
  },
  "id": "probabilistic-quarantine",
  "intent": "Every value produced by a probabilistic component travels with how it was produced and how certain it is, and the modules that must stay deterministic cannot reach a model provider by any import route.",
  "lifecycle": "published",
  "limits": [
    "Using this template does not establish that any AI system meets a legal requirement, and it has no legal effect on its own.",
    "It keeps model output reviewable; it does not make a model accurate.",
    "Where the confidence levels sit is a decision for each system and is not part of this template."
  ],
  "migration": null,
  "principles": [
    "P-1"
  ],
  "problem": "A system that mixes deterministic code and probabilistic models tends to let a model's output travel as if it were a parsed fact. Once a bare value leaves the model, nothing downstream can tell it apart from a value read out of a signed document, and the review that should have happened never does.",
  "provenance": [
    {
      "checked": "2026-09-16",
      "document": "docs/coadf/COADF.md",
      "section": "P-1: Deterministic first, probabilistic quarantined"
    }
  ],
  "reassessment_triggers": [
    "A new probabilistic component is added.",
    "A model provider package is added to the dependencies.",
    "The confidence levels or their meaning change."
  ],
  "requirements": [
    {
      "check": "A type or schema check on the component's return value rejects a result that lacks confidence or extraction method.",
      "id": "R1",
      "level": "MUST",
      "rationale": "Without the method and confidence attached, downstream code cannot distinguish a guess from a fact.",
      "text": "A probabilistic component returns a value together with its confidence and its extraction method, never a bare value."
    },
    {
      "check": "A test feeds a model result that claims maximal certainty and asserts the stored confidence is below the top level.",
      "id": "R2",
      "level": "MUST",
      "rationale": "A model's self-reported certainty is not evidence; the cap keeps model output reviewable by construction.",
      "text": "A value produced by a probabilistic method is capped below the highest confidence level, however certain the model reports itself."
    },
    {
      "check": "An import-graph contract, run in CI, fails when any deterministic module can reach a model provider package.",
      "id": "R3",
      "level": "MUST_NOT",
      "rationale": "A boundary that holds only by convention is crossed the first time someone adds a helper.",
      "text": "Modules on the deterministic path import a model provider, directly or through any chain of imports."
    },
    {
      "check": "A review of the contract file shows every probabilistic module named and no deterministic module listed as allowed to reach a provider.",
      "id": "R4",
      "level": "SHOULD",
      "rationale": "Reviewers can only defend a boundary they can see.",
      "text": "The list of quarantined components is written down in one place and kept next to the import contract."
    }
  ],
  "schema": "template.schema.json",
  "see_also": [
    "COADF Engineering Companion, pattern: probabilistic boundary (anylai.eu/coadf/engineering/patterns/probabilistic-boundary)"
  ],
  "source_sha256": "8aff7d035f035621e6e95b03215a46f50d60b5dd2a780c99b2d29e9fab04af33",
  "summary": "Keep machine-learning components in bounded tasks whose output carries its own uncertainty, and make it structurally impossible for the deterministic path to call a model provider.",
  "title": "Quarantine probabilistic components behind an explicit boundary",
  "version": "1.0.0"
}