Appendix A — Agent patterns

Appendix A - 24. Epic Definition-of-Done (Final-Opus trust-nothing re-run)

The Structure of Epic Definition-of-Done (Final-Opus trust-nothing re-run) — its shape at a glance:

The gate trusts nothing recorded: it re-runs the owned pins and lints against the substrate as it stands now and checks each cited commit is reachable, closing only when the re-derived verdict is green.

flowchart LR
  Claims[/Phase markers, prior claims/] -.->|distrusted| Gate{DoD re-run at HEAD}
  Pins[(Owned pins + lints)] -->|re-run now| Gate
  Commits[(Cited commits)] -->|reachability / patch-id| Gate
  Gate -->|all green| Close([Epic closes])
  Gate -->|any red| Hold([Close refused])

Accessible description: the definition-of-done gate distrusts recorded phase markers, re-runs the Epic's owned pins and lints at HEAD, and checks each cited commit is reachable; the Epic closes only when the re-derived verdict is green and is held otherwise.

Projected from the catalogue entry governance-doc-controls / Epic Definition-of-Done (Final-Opus trust-nothing re-run).

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — An Epic-close gate mandating a "trust nothing" Final-Opus review that re-runs every owned pin test and lint at HEAD, rather than trusting phase markers or prior claims, so an Epic cannot close on stale or rotted assertions.

Motivation

An Epic spanning many dispatches accumulates claims (phase markers, "lints pass," pin-test counts), and those claims rot as sibling Epic sweeps churn the substrate underneath them. Close on the stale claims and you ship an Epic whose defenses no longer actually hold (empirically: 7/7 back-catalogue Epics self-marked DONE had quality-of-defense gaps). The failure is a premature/false close, and it recurs at every Epic boundary.

Applicability

Structure

The Structure diagram appears at the top of this page.

Sample Code

The gate re-derives the verdict from the substrate rather than reading it off markers. It re-runs every owned pin and lint at HEAD and verifies each cited commit is reachable; a missing commit forces a logged override, not a silent pass.

def close_epic(owned_pins, owned_lints, cited_commits, is_reachable, override_reason=None) -> int:
    findings = []
    for pin in owned_pins:            # re-run at HEAD — do NOT trust the recorded "passed" marker
        if pin.run() != "pass":
            findings.append(f"owned pin {pin.name} is red at HEAD")
    for lint in owned_lints:
        if lint.run():
            findings.append(f"owned lint {lint.name} finds violations at HEAD")
    for sha in cited_commits:
        if not is_reachable(sha) and not override_reason:
            findings.append(f"cited commit {sha} is unreachable and no override was given")
    if findings:
        for f in findings:
            print(f"DOD BLOCK: {f}")
        return 1                       # close refused
    return 0                           # atomically rewrite status, move to closed, regenerate the index

Consequences

Example use within DocAble

Contents
⇐ Beginning of this partNext part ⇒Next chapter ›⇤ BeginningEnd ⇥Index
© James C. Davis, 2026–present