dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/coverage.py

@@ -0,0 +1,387 @@
+r"""coverage — the cheap, NON-GIT fan-out coverage fold for a self-reporting fleet (docs/197 §7(1)).
+
+> **An HONEST AGGREGATOR, not a label factory.** It folds N already-adjudicated
+> `result_state` terminal-state verdicts (each minted by `verify-result`, the
+> §7(1) keystone) against the workflow-DECLARED expected count N, into ONE coverage
+> headline + a per-class breakdown. It mints **ZERO** new ground-truth labels —
+> every per-worker DEAD/HEALTHY fact it counts was already decided by
+> `result_state.classify_terminal`; this batches them into one coverage answer the
+> synthesizer can read. That honesty is load-bearing: re-counting the N
+> already-adjudicated verdicts as "N new labels" would be the consistency-not-
+> grounding sin (the docs/179 design law). The data-multiplier in the docs/179 set
+> is `firing_label` (it JOINS a firing to a git outcome to DECIDE a previously-unknown
+> label); `coverage` is the `fleet_roll` sibling — a fold over an already-labeled set.
+
+What it IS — the win that is real (and narrow)
+==============================================
+
+The dominant ultracode subagent is a **pure-text research/read worker that produces
+no git commits**, so `completion.classify` (which folds `declared − git-ancestry-
+verified` over an `intent_ledger`) returns INDETERMINATE for it — there is no ledger.
+The only fossil a read-only worker leaves is its transcript's terminal record. So
+`coverage` is the form of "is the fan-out actually done?" that works on the cheap
+rung `result_state` already provides, and it earns its keep two narrow, defensible
+ways:
+
+  1. It makes the denominator **`declared` (a separate, workflow-authored integer)**,
+     NOT `len(returns)`. The pervasive laundering bug is `failed = N − survivors.length`
+     and `results.filter(Boolean)` (89/114 real scripts): a harness-synthesized death
+     returns a non-null error string that survives the filter, so a 4-of-7 fan-out is
+     silently banked as 7/7. Because `declared` is independent of the survivor list, a
+     short survivor list CANNOT read as FULL here — the laundering is structurally
+     impossible.
+  2. It **surfaces a count the prior pipeline discarded** — `unaccounted` (declared
+     slots that produced neither a HEALTHY return nor a witnessed death) — and hands
+     the whole partition to the synthesizer as legible text, instead of `log()`-ing it
+     and throwing it away (today's behavior, the follow-up #1 premise).
+
+Both are "better denominator hygiene," not a new per-datum label. Stated honestly so
+the module ships in agreement with docs/179, not in contradiction with it.
+
+The fold-mints-data law (docs/179) — applied, and the honest ruling
+===================================================================
+
+The two facts the fold touches: **declared N** (workflow-authored) and the **multiset
+of `result_state` terminal-states** (harness-authored, via the `model=='<synthetic>'`
+gate). They were not compared at the fold before — but the comparison is *arithmetic*
+(`healthy == declared?`), and it decides NO new truth value about any worker: each
+worker's DEAD/HEALTHY was already adjudicated by `result_state`. So this is the
+`fleet_roll` case (fold an already-labeled set → one headline + breakdown, 0 new
+labels), NOT the `firing_label` case (join two facts to DECIDE an unknown label). The
+`unaccounted`/`absent` surfacing is exactly what `fleet_roll.absent` does without
+claiming to mint data. See [[project-dos-fold-mints-data-law]].
+
+The byte-author law / advisory floor / reuse notes
+==================================================
+
+The `healthy` count is grounded TRANSITIVELY: it derives from `result_state`'s
+`model=='<synthetic>'` gate, a byte the Claude Code HARNESS — not the worker —
+authored, so a worker cannot forge its slot HEALTHY when the harness killed it
+(the docs/138 grounding-not-consistency invariant). BUT the pure core can only be as
+grounded as the verdicts handed in: if a caller asserts terminal-states directly
+(the CLI `--states` path) instead of letting `coverage_from_transcripts` run
+`result_state.verify_transcript`, the count is **workflow-asserted, not harness-
+grounded**. The CLI stamps that distinction (`grounded: false` vs `true`) so a
+consumer knows whether the denominator was re-grounded; the pure `classify_coverage`
+counts whatever states it is given and never re-grounds (it is pure — no I/O).
+
+ADVISORY (PDP, not PEP — the docs/197 §6.5 / docs/99 line): it REPORTS a coverage
+verdict + a synthesizer-legible `prompt_line`; it never re-runs a dead worker
+(re-dispatch of the dead slot's OWN unit is the conductor's act) and never re-prompts
+the synthesizer mid-plan (the −9 pp DEFER derail). It also does NOT judge the
+CORRECTNESS of a HEALTHY return — a 7/7 FULL coverage of seven WRONG answers is still
+FULL; coverage certifies the denominator, never the values. Whether a healthy finding
+is true is `effect_witness` / `believe_under_floor`'s job (the witness-routing rung,
+docs/197 §7(2)).
+
+⚓ Kernel discipline (the litmus): a PURE verdict + a boundary reader. It imports only
+the sibling kernel module `result_state` (+ stdlib) — NOT `resume`/`intent_ledger`/
+`scope_source` (those are `completion`'s git-ledger imports; folding them in would drag
+git concepts into the pure-text path). Names no host, resolves nothing against
+`__file__`, takes no lease. The transcript I/O is the caller's boundary
+(`coverage_from_transcripts`, which delegates to `result_state.verify_transcript`),
+exactly the `liveness.classify` over `git_delta` shape, one rung over. It mirrors
+`completion`'s SHAPE (a `str`-enum verdict + frozen `*Verdict` + `to_dict` +
+`fraction`-style legibility), but shares no body — a new leaf, the third sibling of
+the "is the fan-out done, or only declared done?" family.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from typing import Optional, Sequence, Union
+
+from dos.result_state import ResultStateVerdict, TerminalClass, TerminalState
+
+
+# ───────────────────────────── the coverage verdict ───────────────────────────
+class Coverage(str, enum.Enum):
+    """The typed coverage verdict — five states, mutually exclusive.
+
+    `str`-valued so it round-trips a `--json` token / exit-code map without a lookup
+    table (the `Completion` / `Resume` / `Liveness` idiom). The asymmetry maps to the
+    consumer's action:
+
+      * FULL        — every declared worker returned a real result; fold all.
+      * UNDERFILLED — a sub-quorum returned (0 < healthy < declared); fold WITH a
+                      caveat, count the gap in the denominator.
+      * STARVED     — nothing real came back (healthy == 0, declared > 0); do NOT
+                      synthesize — there is no real material to fold.
+      * OVERFILLED  — more healthy returns than declared (healthy > declared): a
+                      dispatch/glob bug (a re-dispatch double-counted, a stale glob).
+                      Surfaced, never silently reported as FULL with `fraction > 1`.
+      * EMPTY       — nothing was fanned out (declared == 0). Degenerate, NOT an error.
+    """
+
+    FULL = "FULL"
+    UNDERFILLED = "UNDERFILLED"
+    STARVED = "STARVED"
+    OVERFILLED = "OVERFILLED"
+    EMPTY = "EMPTY"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+    @property
+    def foldable(self) -> bool:
+        """True iff there is real material to synthesize from (everything but STARVED).
+
+        OVERFILLED is foldable (there ARE healthy results — too many, but real); the
+        caveat is about the count mismatch, not the absence of material."""
+        return self is not Coverage.STARVED
+
+    @property
+    def should_caveat(self) -> bool:
+        """True iff the synthesis prompt MUST carry a coverage caveat (not FULL/EMPTY)."""
+        return self in (Coverage.UNDERFILLED, Coverage.STARVED, Coverage.OVERFILLED)
+
+
+@dataclass(frozen=True)
+class CoveragePolicy:
+    """Knobs for the coverage verdict — policy, not mechanism (the `ResumePolicy` split).
+
+    ``min_quorum`` is a LEGIBILITY-only flag: when set, `to_dict` reports
+    ``quorum_met = healthy/declared >= min_quorum``. It NEVER changes the verdict —
+    "is 4/7 acceptable?" is host policy the synthesizer/conductor decides; coverage
+    only reports the fraction + an advisory flag. FULL stays strict equality. The
+    default is generic (no host tuning); a workspace could declare its own in a future
+    `dos.toml [coverage]` seam (like the planned `[liveness]`/`[completion]`).
+    """
+
+    min_quorum: Optional[float] = None
+
+
+DEFAULT_COVERAGE_POLICY = CoveragePolicy()
+
+
+@dataclass(frozen=True)
+class ReturnState:
+    """One declared worker slot's witnessed terminal-state — the minimal datum the fold
+    counts. `state` is a `result_state.TerminalState` (the rung coverage trusts);
+    `agent_id` is optional legibility only (a per-slot breakdown). Nothing else about
+    the return is load-bearing here — the CORRECTNESS of a HEALTHY return is
+    `effect_witness`'s job, not coverage's."""
+
+    state: TerminalState
+    agent_id: str = ""
+
+
+@dataclass(frozen=True)
+class CoverageVerdict:
+    """The single verdict `classify_coverage` returns, with the partition echoed back.
+
+    `declared` is the workflow-authored denominator (independent of the survivor list —
+    the laundering fix). `healthy`/`dead`/`unreadable` partition the WITNESSED slots;
+    `unaccounted` is the declared slots that produced no witnessed verdict at all (the
+    surfaced-discarded count). `dead_classes` is the `result_state.TerminalClass`
+    breakdown of the deaths — populated only when full `ResultStateVerdict`s were
+    counted (the harness-grounded path), so the reason text can say "rate-limit" vs
+    "quota" honestly; empty when bare `TerminalState`s were counted. `to_dict` is the
+    `--json` shape (incl. the synthesizer-legible `prompt_line`)."""
+
+    state: Coverage
+    declared: int
+    healthy: int
+    dead: int
+    unreadable: int
+    reason: str
+    dead_classes: tuple[tuple[str, int], ...] = ()
+    quorum_met: Optional[bool] = None
+
+    @property
+    def unaccounted(self) -> int:
+        """Declared slots that produced no witnessed verdict (declared − the witnessed
+        partition). Floored at 0 — an over-fill is reported via OVERFILLED, never as a
+        negative `unaccounted`."""
+        return max(0, self.declared - self.healthy - self.dead - self.unreadable)
+
+    @property
+    def fraction(self) -> Optional[float]:
+        """healthy / declared — the coverage fraction, or None when nothing was declared.
+        A legibility aid; never load-bearing for the verdict. May exceed 1.0 only in the
+        OVERFILLED case (reported so the dispatch bug is visible, not hidden)."""
+        return (self.healthy / self.declared) if self.declared else None
+
+    @property
+    def prompt_line(self) -> str:
+        """The deterministic sentence a workflow interpolates VERBATIM into its synthesis
+        prompt — the whole point of the module (the laundering fix is legible coverage,
+        not a `log()`-ed one). Generated from the REAL `(dead, unreadable, unaccounted)`
+        partition (Fix 2/3): it NEVER asserts a death that was not witnessed — an
+        unreadable slot is reported as "could not be read", a missing slot as "did not
+        return a transcript", and only `dead`/`dead_classes` license the word "died"."""
+        d = self.declared
+        if self.state is Coverage.EMPTY:
+            return "No workers were fanned out (declared == 0); there is nothing to fold."
+        if self.state is Coverage.FULL:
+            return (f"All {self.healthy} of {d} fan-out workers returned a real result; "
+                    f"this is full coverage.")
+        # Build the gap clause from the actual partition, never a hardcoded "died".
+        parts = []
+        if self.dead:
+            cls = self._dead_class_phrase()
+            parts.append(f"{self.dead} died on a harness-authored terminal{cls}")
+        if self.unreadable:
+            parts.append(f"{self.unreadable} could not be read (NOT a witnessed death)")
+        if self.unaccounted:
+            parts.append(f"{self.unaccounted} did not return a transcript")
+        gap = "; ".join(parts) if parts else "the missing slots are unaccounted"
+        if self.state is Coverage.STARVED:
+            # 0 healthy — but the reason text must reflect WHY (deaths vs unreadable vs
+            # missing), because the right operator action differs (re-dispatch a death;
+            # fix the read path for unreadable; locate the transcripts for missing).
+            return (f"COVERAGE FAILURE: 0 of {d} fan-out workers returned a real result "
+                    f"({gap}). There is no real material to synthesize. Do NOT fabricate "
+                    f"findings; report the fan-out as failed and act on the gap above "
+                    f"(re-dispatch deaths; fix the read path for unreadable; locate "
+                    f"missing transcripts).")
+        if self.state is Coverage.OVERFILLED:
+            return (f"COVERAGE ANOMALY: {self.healthy} workers returned a real result but "
+                    f"only {d} were declared — more results than expected (a re-dispatch "
+                    f"double-count or a stale transcript glob). Treat the count as "
+                    f"unreliable and reconcile the dispatch before trusting coverage.")
+        # UNDERFILLED
+        return (f"COVERAGE CAVEAT: only {self.healthy} of {d} fan-out workers returned a "
+                f"real result ({gap}). Treat the findings below as a SUB-QUORUM SAMPLE "
+                f"({self.healthy}/{d}), not an exhaustive survey; do not state or imply "
+                f"full coverage, and flag the gap above.")
+
+    def _dead_class_phrase(self) -> str:
+        """A short ' (rate-limit/quota/...)' phrase from `dead_classes`, or '' when the
+        deaths were counted from bare TerminalStates (no class detail). The ONLY license
+        to name a death cause — never asserted from an unreadable/missing slot."""
+        if not self.dead_classes:
+            return ""
+        names = "/".join(c.lower().replace("_", "-") for c, _ in self.dead_classes)
+        return f" ({names})"
+
+    def to_dict(self) -> dict:
+        return {
+            "state": self.state.value,
+            "declared": self.declared,
+            "healthy": self.healthy,
+            "dead": self.dead,
+            "unreadable": self.unreadable,
+            "unaccounted": self.unaccounted,
+            "fraction": (round(self.fraction, 4) if self.fraction is not None else None),
+            "foldable": self.state.foldable,
+            "should_caveat": self.state.should_caveat,
+            "dead_classes": [list(c) for c in self.dead_classes],
+            "quorum_met": self.quorum_met,
+            "prompt_line": self.prompt_line,
+            "reason": self.reason,
+        }
+
+
+# ───────────────────────────── the pure fold ──────────────────────────────────
+_Return = Union[ReturnState, ResultStateVerdict, TerminalState]
+
+
+def _as_state(r: _Return) -> tuple[TerminalState, Optional[TerminalClass]]:
+    """Coerce one return element to `(TerminalState, TerminalClass | None)`. PURE.
+
+    Accepts a bare `TerminalState`, a full `ResultStateVerdict` (carries the class
+    detail), or a `ReturnState` wrapper. Any other type raises `TypeError` — the CLI
+    maps it to a contract error (exit 2), never silently miscounts."""
+    if isinstance(r, TerminalState):
+        return (r, None)
+    if isinstance(r, ResultStateVerdict):
+        return (r.state, r.cls)
+    if isinstance(r, ReturnState):
+        return (r.state, None)
+    raise TypeError(
+        f"coverage: a return must be a TerminalState, ResultStateVerdict, or "
+        f"ReturnState, not {type(r).__name__}"
+    )
+
+
+def classify_coverage(
+    declared: int,
+    returns: Sequence[_Return],
+    policy: CoveragePolicy = DEFAULT_COVERAGE_POLICY,
+) -> CoverageVerdict:
+    """Fold the witnessed terminal-states against the declared count. PURE — no I/O.
+
+    Counts each return's `result_state` terminal-state into `{healthy, dead,
+    unreadable}` (an UNREADABLE return is LIVE-not-dead — the fail-safe floor
+    inherited from `result_state`: a read fault must NEVER be counted a death), then
+    decides the coverage state from `healthy` vs `declared`:
+
+        declared <= 0                       → EMPTY        (nothing fanned out)
+        healthy  >  declared                → OVERFILLED   (dispatch/glob bug)
+        healthy  == declared (declared > 0) → FULL
+        healthy  == 0        (declared > 0) → STARVED
+        0 < healthy < declared              → UNDERFILLED
+
+    `dead` is SYNTHETIC or EMPTY (both carry `result_state` `.dead == True`).
+    `unaccounted` (declared slots with no witnessed verdict) falls out as
+    `declared − healthy − dead − unreadable` and rides UNDERFILLED/STARVED.
+
+    ADVISORY (docs/197 §6.5): it mints a coverage verdict; the consumer decides what to
+    do (fold-with-caveat / don't-fold / re-dispatch). It never re-runs a worker and
+    never judges the correctness of a healthy return (that is `effect_witness`).
+    """
+    healthy = dead = unreadable = 0
+    cls_counts: dict[str, int] = {}
+    for r in returns:
+        state, cls = _as_state(r)
+        if state is TerminalState.HEALTHY:
+            healthy += 1
+        elif state is TerminalState.UNREADABLE:
+            unreadable += 1  # FAIL-SAFE: live, NOT a witnessed death.
+        else:  # SYNTHETIC or EMPTY — result_state.dead == True.
+            dead += 1
+            if cls is not None and cls is not TerminalClass.NONE:
+                cls_counts[cls.value] = cls_counts.get(cls.value, 0) + 1
+
+    if declared <= 0:
+        state, reason = Coverage.EMPTY, "nothing was fanned out (declared == 0)"
+    elif healthy > declared:
+        state = Coverage.OVERFILLED
+        reason = (f"{healthy} healthy returns but only {declared} declared — more "
+                  f"results than expected (a dispatch/glob bug)")
+    elif healthy == declared:
+        state, reason = Coverage.FULL, f"all {declared} declared worker(s) returned a real result"
+    elif healthy == 0:
+        state = Coverage.STARVED
+        reason = f"0 of {declared} declared worker(s) returned a real result — nothing to synthesize"
+    else:
+        state = Coverage.UNDERFILLED
+        reason = f"{healthy} of {declared} declared worker(s) returned a real result (sub-quorum)"
+
+    quorum_met: Optional[bool] = None
+    if policy.min_quorum is not None and declared > 0:
+        quorum_met = (healthy / declared) >= policy.min_quorum
+
+    return CoverageVerdict(
+        state=state,
+        declared=declared,
+        healthy=healthy,
+        dead=dead,
+        unreadable=unreadable,
+        reason=reason,
+        dead_classes=tuple(sorted(cls_counts.items())),
+        quorum_met=quorum_met,
+    )
+
+
+# ───────────────────────────── boundary I/O ───────────────────────────────────
+def coverage_from_transcripts(
+    declared: int,
+    paths: Sequence[str],
+    policy: CoveragePolicy = DEFAULT_COVERAGE_POLICY,
+) -> CoverageVerdict:
+    """Fold a list of subagent transcript paths into a coverage verdict. NOT pure.
+
+    Reads each path via `result_state.verify_transcript` at the boundary (a missing /
+    garbled file yields UNREADABLE, which counts LIVE — the fail-safe floor), then
+    folds the verdicts with the pure `classify_coverage`. This is the HARNESS-GROUNDED
+    path: coverage itself runs the `model=='<synthetic>'` classification, so the
+    `healthy`/`dead` counts cannot be forged by a self-reporting workflow (the CLI
+    stamps `grounded: true` for this path). The `git_delta`/`liveness` "I/O at the
+    boundary, data to the pure core" discipline.
+    """
+    from dos import result_state
+    verdicts = [result_state.verify_transcript(str(p)) for p in paths]
+    return classify_coverage(declared, verdicts, policy)

dos/dangling_intent.py

@@ -0,0 +1,287 @@
+"""DI — the dangling-intent verdict: *did the agent stop right after admitting unfinished work?*
+
+docs/150 (the steelman of docs/149). docs/149 measured that **~92 % of real EnterpriseOps-Gym
+failures are "the action never happened"** — Premature Completion, the model declaring done and
+stopping with required rows unwritten — and concluded DOS could not own it byte-cleanly, because
+the `completion` verdict's inputs (`declared − verified`) are both forgeable here (no git ancestry,
+no env-authored per-step checkpoint, the declared scope is the agent's own). That conclusion is
+**cracked, not overturned**, by one observation docs/149 §3 over-generalized past:
+
+> docs/149 wrote "`verified` = the agent's own narration → forgeable." That is true **only toward
+> "I'm done."** A self-report of *incompleteness* — "Now I need to allocate the personnel…" right
+> before stopping — is an **admission against interest**: no premature-completing agent benefits
+> from falsely confessing unfinished work. It is the one self-report class DOS *already* believes
+> — `resume` keeps a `STEP_CLAIMED`-but-unverified step IN the residual (it trusts the agent only
+> when the agent admits *more* work, never when it claims *less*). So the against-interest axis is
+> not forgeable-in-favor, and a verdict over it is not the §5a mirror-verifier.
+
+The byte-clean question (over two surfaces, one with an env-authored corroborator)
+==================================================================================
+
+  > Does the agent's LAST authored turn contain a fixed, task-INDEPENDENT
+  > committed-future-intent discourse marker ("I need to", "I still have to", "next I will",
+  > "I was unable to", "I cannot … yet") — AND did NO env-authored tool result land after it?
+
+It is **not a planner**: the cue set is an English-discourse-marker grammar writable having read
+*zero task prompts*. The litmus the verb→tool-table mechanisms FAILED (they had to read *this
+task's* prose to know "allocate" → `add_group_member` not `add_new_user_group`): this verdict is
+**invariant under task-swap**. It never reads a domain noun, never enumerates a step-list, never
+decides what the agent *should* do next. It does not even need to know what the unfinished step
+*is* — only that a standing-obligation envelope was emitted at the moment of stopping. Key on the
+first-person-future-intent *envelope*, NEVER on content ("manager", "members", "allocate"); the
+instant it keys on a domain noun it has become a planner and is dead (the load-bearing knife-edge).
+
+It is **not a satisfaction predicate**: it reads no DB, never asks "is the work correct / enough".
+And the agent-authored surface (the narration) is corroborated by an **env-authored absence** — the
+gym writes a tool `result` only when a tool actually executed, so "no result after the terminal
+turn" is a non-forgeable byte (the `precursor_gate` existence-of-a-result rung). That corroborator
+drives the dominant false-positive (named-it-then-did-it) toward zero by construction: a marker
+followed by a real subsequent call is ABSTAIN, not a fire.
+
+The honest forgeable hole, named (the `arg_provenance` discipline)
+==================================================================
+
+This reads ONE agent-authored surface, so it is **forgeable by SUPPRESSION**: an agent trained
+against the gate simply stops narrating "I need to…" and the signal goes quiet. Acceptable ONLY
+because suppression degrades to **false-DONE → baseline** (the safe fail-toward-done direction),
+and because the value is on *today's* uncoached cheap models that narrate their abandoned plans —
+not on an adversary optimizing against the gate. It catches the **honest-but-premature** stopper;
+it is blind to the **silent** stopper (stops with no narration — the majority of the measured 92 %)
+and to the **adversarial** one. That is a forgeable hole stated plainly, exactly as
+`arg_provenance` names its false-SUPPORTED miss. The recall ceiling is the *narrating* subset —
+measured ~15-30 % of the missing-row failures (`replay_dangling.py`).
+
+Advisory only — it never supplies the plan (DETECT, not FIX)
+============================================================
+
+The verdict maps to `Intervention.WARN` and nothing harder (the type has no other rung). On a fire
+the consumer re-surfaces **the agent's own abandoned sentence** ("your final message says you still
+needed to X, and no tool ran after — continue or confirm"). It authors **no directive and no step**
+— so it cannot inject the foreign instruction that caused the −9 pp derailment (docs/143: a
+verifier-authored directive on a correct path). Its worst case is replaying a sentence the agent
+already wrote (a one-turn iteration tax), never a derailment. It does not and structurally cannot
+tell the model *what* call to make — that is the +14-35 pp planner lever, forfeit by doctrine. So
+the claim is exactly "DOS can byte-cleanly DETECT a slice of premature completion," never "DOS can
+fix it."
+
+⚓ Pure kernel, I/O on the edge (the dos idiom — mirrors `claim_extract.extract_claims`,
+`liveness.classify`, `precursor_gate.classify_call`): `classify_stop(StopEvidence, policy) ->
+DanglingVerdict` is a frozen datum in, a frozen verdict out. The boundary reader gathers the
+terminal narration (`claim_extract.assistant_text_from_transcript`) and counts env-authored tool
+results after it AT THE CALL EDGE; the kernel never reads a file, a clock, or a DB.
+"""
+
+from __future__ import annotations
+
+import enum
+import re
+from dataclasses import dataclass
+
+
+# ---------------------------------------------------------------------------
+# The typed verdict — two-valued (the EvidenceStance REFUTED/NO_SIGNAL shape).
+# ---------------------------------------------------------------------------
+class Dangling(str, enum.Enum):
+    """The dangling-intent verdict — two states. `str`-valued so it round-trips a CLI token / JSON.
+
+      DANGLING_INTENT — the agent's last authored turn declared a committed-future obligation AND
+                        no env-authored tool result landed after it. The one actionable rung — a
+                        consumer re-surfaces the agent's own sentence (WARN). NOT a claim the work
+                        is incomplete in truth — only that the agent SAID so and then stopped.
+      ABSTAIN         — the fail-safe zero: no future-intent marker in the terminal turn, OR a real
+                        tool result followed it (the agent named a step and then DID act), OR the
+                        cue set is empty. Honest no-signal; never a block, always fail-toward-done.
+    """
+
+    DANGLING_INTENT = "DANGLING_INTENT"
+    ABSTAIN = "ABSTAIN"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+# ---------------------------------------------------------------------------
+# The cue grammar — task-INDEPENDENT first-person-future-intent markers.
+# ---------------------------------------------------------------------------
+# Each cue is a regex matched casefold against the terminal narration. They key ONLY on the
+# first-person committed-future / unfulfilled-intent ENVELOPE — never a domain noun. This is the
+# difference between a fixed grammar (writable having read zero task prompts) and a planner (per-task
+# prose reasoning). A host may override/extend via `dos.toml [dangling.cues]` (config-as-data); an
+# EMPTY set ABSTAINs everything (fail-toward-done). Kept deliberately conservative: a missed marker
+# is a safe ABSTAIN; the bias is to under-fire (the `arg_provenance` posture).
+DEFAULT_CUES: tuple[str, ...] = (
+    r"\bi (?:still )?need to\b",
+    r"\bi (?:still )?have to\b",
+    r"\bi (?:will|'ll) (?:now |then )?(?:need to |have to |proceed to )",
+    r"\bnext,? i (?:will|'ll|need|have|should)\b",
+    r"\bi should (?:now |next )?(?:proceed|continue|identify|create|add|assign|update)\b",
+    r"\bi was unable to\b",
+    r"\bi (?:have|haven't|had) not (?:yet )?(?:been able|completed|finished|done)\b",
+    r"\bi cannot .{0,40}\byet\b",
+    r"\b(?:still|yet) to be (?:done|completed|added|assigned|created)\b",
+    r"\bremains? to be (?:done|completed|added|assigned)\b",
+    r"\bto (?:do|complete|finish) this,? i (?:need|will|have|must)\b",
+    r"\bnow,? to\b.{0,40}\bi (?:need|will|must|have to)\b",
+)
+
+# Words that, when they immediately wrap a cue, mark it as a COMPLETED report, not an open one —
+# "I needed to X, which I have now done" must NOT fire. A conservative negative guard (the cue
+# itself is the primary signal; this only suppresses an obvious past-tense-resolved phrasing).
+_RESOLVED_GUARD_RE = re.compile(
+    r"\b(?:have|has|already|now) (?:been )?(?:done|completed|finished|created|added|assigned|set up)\b",
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True)
+class DanglingPolicy:
+    """The cue grammar + knobs — mechanism is kernel, the cue list is config (the `ProvenancePolicy`
+    / `StreamPolicy` seam). Defaults GENERIC; a host declares its own in `dos.toml [dangling]`.
+
+      cues          — the committed-future-intent marker regexes (casefold). EMPTY → ABSTAIN-all
+                      (the fail-toward-done floor: no cues declared = no accusation possible).
+      tail_chars    — only the LAST `tail_chars` of the terminal narration are scanned (an open
+                      obligation declared in the MIDDLE of a long turn that then continues to act is
+                      not a *terminal* dangle; the signal is "ended ON the admission"). 0 = whole turn.
+    """
+
+    cues: tuple[str, ...] = DEFAULT_CUES
+    tail_chars: int = 600
+
+    def __post_init__(self) -> None:
+        if self.tail_chars < 0:
+            raise ValueError("tail_chars must be >= 0")
+
+
+DEFAULT_POLICY = DanglingPolicy()
+
+
+# ---------------------------------------------------------------------------
+# Frozen input — the pure datum the boundary gathers and hands in.
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class StopEvidence:
+    """Everything `classify_stop` needs, gathered by the CALLER at the stop event. No I/O inside.
+
+      final_turn_text     — the agent's LAST authored narration (the terminal `ai_message` /
+                            `model_response`), read at the boundary by
+                            `claim_extract.assistant_text_from_transcript`. Agent-authored — but
+                            distrusted on the AGAINST-INTEREST axis only.
+      results_after_turn  — the count of env-authored tool `result` entries that landed AFTER the
+                            terminal turn. The ENV-AUTHORED corroborator: the gym writes a result
+                            only when a tool actually executed, so >0 means the agent named a step
+                            and then ACTED → ABSTAIN (not a terminal dangle). Defaults 0 (the common
+                            stop case: the last turn is narration with nothing after it).
+    """
+
+    final_turn_text: str
+    results_after_turn: int = 0
+
+    def __post_init__(self) -> None:
+        if self.results_after_turn < 0:
+            raise ValueError("results_after_turn must be >= 0")
+
+
+# ---------------------------------------------------------------------------
+# Frozen verdict — advisory only.
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class DanglingVerdict:
+    """The verdict `classify_stop` returns — typed state + the matched cue for the WARN string.
+
+    `matched_cue` is the offending marker text (the substring that fired) so the consumer's WARN can
+    quote the agent's OWN words back ("your final message says: '<…>' — and no tool ran after").
+    `reason` is the one-line operator summary. Advisory: never raises, never blocks the stop.
+    """
+
+    verdict: Dangling
+    matched_cue: str
+    reason: str
+
+    @property
+    def is_dangling(self) -> bool:
+        return self.verdict is Dangling.DANGLING_INTENT
+
+    def to_dict(self) -> dict:
+        return {
+            "verdict": self.verdict.value,
+            "matched_cue": self.matched_cue,
+            "reason": self.reason,
+        }
+
+
+# ---------------------------------------------------------------------------
+# The pure verdict.
+# ---------------------------------------------------------------------------
+def _find_cue(text: str, policy: DanglingPolicy) -> str:
+    """The first committed-future-intent cue that matches the (tail of the) text, or "" if none.
+    Suppressed when an obvious resolved-guard phrase wraps it (named-it-then-did-it in one turn)."""
+    if not policy.cues:
+        return ""
+    scan = text if policy.tail_chars == 0 else text[-policy.tail_chars:]
+    low = scan.casefold()
+    for cue in policy.cues:
+        m = re.search(cue, low)
+        if not m:
+            continue
+        s, e = m.start(), m.end()
+        # The resolved-guard is checked ONLY within the cue's OWN sentence — clipped at the nearest
+        # sentence terminator on each side. This is the "I needed to X, which I have now done"
+        # same-clause shape; it must NOT reach back into a PRIOR completed sentence ("the group has
+        # been created. Now I need to allocate…") and wrongly suppress a genuine LATER dangle (the
+        # real-example bug). The cue itself is the primary signal; this only kills an obvious
+        # in-clause past-tense resolution.
+        sent_start = max((scan.rfind(c, 0, s) for c in ".!?\n"), default=-1) + 1
+        nxt = [scan.find(c, e) for c in ".!?\n"]
+        nxt = [i for i in nxt if i >= 0]
+        sent_end = min(nxt) + 1 if nxt else len(scan)
+        sentence = scan[sent_start:sent_end]
+        if _RESOLVED_GUARD_RE.search(sentence):
+            continue
+        return scan[s:e].strip()
+    return ""
+
+
+def classify_stop(
+    ev: StopEvidence, policy: DanglingPolicy = DEFAULT_POLICY
+) -> DanglingVerdict:
+    """Classify whether the agent stopped right after admitting unfinished work. PURE — no I/O.
+
+    The ladder, top to bottom:
+      1. ABSTAIN — a real tool result landed AFTER the terminal turn (`results_after_turn > 0`): the
+         agent named a step and then ACTED, so this is not a terminal dangle. The env-authored
+         corroborator wins first — it is the non-forgeable byte that kills the named-it-then-did-it
+         false positive.
+      2. ABSTAIN — no committed-future-intent cue in the terminal narration (or an empty cue set):
+         the agent did not admit unfinished work. The fail-toward-done floor.
+      3. DANGLING_INTENT — a cue fired AND nothing executed after: the agent's own last words admit
+         an open obligation and the run stopped. The one actionable rung (advisory WARN).
+
+    Advisory: the verdict REPORTS; the consumer re-surfaces the agent's own sentence (never a
+    directive, never a forced continue — the docs/143 −9 pp channel is unreachable by type).
+    """
+    # 1. the env-authored corroborator first: acted-after → not a terminal dangle.
+    if ev.results_after_turn > 0:
+        return DanglingVerdict(
+            verdict=Dangling.ABSTAIN,
+            matched_cue="",
+            reason=(
+                f"{ev.results_after_turn} tool result(s) landed after the terminal turn — the "
+                f"agent named a step and then acted, not a dangling stop"
+            ),
+        )
+    cue = _find_cue(ev.final_turn_text or "", policy)
+    if not cue:
+        return DanglingVerdict(
+            verdict=Dangling.ABSTAIN,
+            matched_cue="",
+            reason="no committed-future-intent marker in the terminal turn — clean stop (or no cues)",
+        )
+    return DanglingVerdict(
+        verdict=Dangling.DANGLING_INTENT,
+        matched_cue=cue,
+        reason=(
+            f"the terminal turn admits an open obligation ({cue!r}) and no tool ran after — the "
+            f"agent stopped right after saying it still had work (an admission against interest)"
+        ),
+    )