specfuse-loop 0.9.2__tar.gz → 0.9.3__tar.gz

{specfuse_loop-0.9.2/specfuse_loop.egg-info → specfuse_loop-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.9.2
+Version: 0.9.3
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0

{specfuse_loop-0.9.2 → specfuse_loop-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.9.2"
+version = "0.9.3"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"

{specfuse_loop-0.9.2 → specfuse_loop-0.9.3}/specfuse/loop/cost.py

@@ -5,22 +5,27 @@
 """One lifetime-cost reader shared by both cost-gated consumers.
 
 `wu_lifetime_cost_usd` answers "what has this work unit cost over its whole
-life," correctly on both re-arm shapes recorded in FEAT-2026-0062/PLAN.md:
-
-  * fold-ran   — a re-arm folded the prior cycle's spend into
-                 `cumulative_cost_usd`, and `re_arm_history[].prior_cost_usd`
-                 names the same money.
-  * fold-never-ran — the prior cycle's spend survives only in
-                 `re_arm_history[].prior_cost_usd`; `cumulative_cost_usd` is
-                 absent.
-
-Summing frontmatter fields cannot distinguish these shapes without replaying
-fold history, and naive summation double-counts the fold-ran shape. Instead
-this module sums `payload.cost_usd` across every `attempt_outcome` event for
-the work unit in `events.jsonl` — a source that already carries every
-dispatch cycle's cost exactly once, independent of fold shape. Frontmatter is
-used only as a fallback for the units this repo's corpus shows have no usable
-event history (see FEAT-2026-0062 criterion 9's measurement).
+life." FEAT-2026-0067 converged the fold onto one path: every re-arm now
+unconditionally folds the prior cycle's spend into `cumulative_cost_usd`
+(driven by an explicit `folded_through_re_arm` marker, not by inferring state
+from a value), so `cumulative_cost_usd` is the lifetime accumulator and
+`re_arm_history[].prior_cost_usd` is a pure audit record of what each cycle
+cost — not a second place the fold might or might not have run.
+
+Before that migration, some already-re-armed WUs had a prior cycle's spend
+survive only in `re_arm_history[].prior_cost_usd` with `cumulative_cost_usd`
+absent — a pre-migration legacy shape that this module's frontmatter fallback
+still tolerates for projects that have not run the FEAT-2026-0067 migration,
+not an ongoing design a reader needs to branch on.
+
+Summing frontmatter fields cannot distinguish "already folded" from "never
+folded" without replaying fold history, and naive summation double-counts a
+folded record. Instead this module sums `payload.cost_usd` across every
+`attempt_outcome` event for the work unit in `events.jsonl` — a source that
+already carries every dispatch cycle's cost exactly once, independent of fold
+shape. Frontmatter is used only as a fallback for the units this repo's
+corpus shows have no usable event history (see FEAT-2026-0062 criterion 9's
+measurement).
 
 Deliberately dependency-light: this module must not import `loop.py` or
 `arm_eval.py` (see `arm_eval.py`'s module docstring on the `loop -> arm_eval`

specfuse_loop-0.9.3/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.9.3

{specfuse_loop-0.9.2 → specfuse_loop-0.9.3}/specfuse/loop/data/templates/WU.template.md

@@ -62,10 +62,18 @@ AUTHOR-SET FIELDS — fill or override these at draft/arm time:
 DRIVER-OWNED FIELDS - the driver writes these at outcome time; authors leave them absent:
 <!-- driver-owned: attempts, cost_usd, input_tokens, output_tokens, duration_seconds,
      cumulative_cost_usd, cumulative_duration_seconds, cumulative_input_tokens,
-     cumulative_output_tokens, re_arm_count, re_arm_history -->
+     cumulative_output_tokens, re_arm_count, re_arm_history, folded_through_re_arm -->
 <!-- driver-stamped at dispatch (resolved execution metadata, visible in this .md):
      model, effort (override or type default), gate_set (the verification.yml set
      that is this WU's exit oracle), driver_version, started_at (UTC ISO). -->
+<!-- `folded_through_re_arm` (FEAT-2026-0067): the `re_arm_count` value already
+     folded into the `cumulative_*` accumulators. On every re-arm the driver folds
+     the prior cycle's cost/duration/token spend into `cumulative_cost_usd`,
+     `cumulative_duration_seconds`, `cumulative_input_tokens`, and
+     `cumulative_output_tokens` — unconditionally, one fold path, including a
+     re-arm whose prior cycle cost nothing. `cumulative_*` is the lifetime
+     accumulator across every re-arm; `re_arm_history[].prior_*` is a pure audit
+     record of what each cycle cost, not a second place the fold might live. -->
 <!-- Full field semantics in docs/methodology.md §2 and events.jsonl outcome payloads. -->
 
 Dependencies live in PLAN.md's `gates[].work_units[].depends_on` graph, not

{specfuse_loop-0.9.2 → specfuse_loop-0.9.3}/specfuse/loop/loop.py

@@ -105,7 +105,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.9.2"
+DRIVER_VERSION = "0.9.3"
 # Oldest scaffold layout this driver can drive. init.sh stamps the scaffold's own
 # version into `.specfuse/VERSION`; check_scaffold_version() fails loud at startup if
 # the consumer's scaffold is older than this, pointing at `specfuse upgrade`. Bump
@@ -1672,20 +1672,35 @@ def write_cost_to_wu(backend, wu: WorkUnit, cum_usage: dict) -> None:
 
 
 def detect_rearm_dispatch(wu: WorkUnit) -> bool:
-    """Return True when wu is a re-arm dispatch whose prior cycle's cost has
-    not yet been folded into the cumulative accumulators.
+    """Return True when wu is a re-arm dispatch whose prior cycle has not yet
+    been folded into the cumulative accumulators.
+
+    Reads re_arm_count and folded_through_re_arm from the WU's on-disk
+    frontmatter because load_wu does not load those fields into the
+    WorkUnit object. A fold is owed when re_arm_count > folded_through_re_arm;
+    fold_cumulative_on_rearm stamps folded_through_re_arm = re_arm_count as
+    part of the same write set it uses for the accumulators, so this is a
+    marker comparison, not an inference from a value that a fold can also
+    produce as a side effect (FEAT-2026-0067/T01).
 
-    Reads re_arm_count and cost_usd from the WU's on-disk frontmatter because
-    load_wu does not load those fields into the WorkUnit object.
     Returns False for first-time dispatches (re_arm_count absent or 0) and for
-    re-arms where cost was already folded (cost_usd == 0 after a prior fold).
+    re-arms already folded (folded_through_re_arm == re_arm_count).
+
+    Exposure left for FEAT-2026-0067/T02: a WU re-armed under the prior
+    cost_usd-based guard has no folded_through_re_arm field at all, so it
+    reads as 0 here — indistinguishable from "never folded" even when it was.
+    This WU does not add a value-inferring fallback to paper over that; T02
+    owns the migration of existing WU shapes.
     """
     fm, _ = read_frontmatter(wu.file)
     re_arm_count = fm.get("re_arm_count", 0)
-    if not isinstance(re_arm_count, int) or re_arm_count <= 0:
+    if not isinstance(re_arm_count, int) or isinstance(re_arm_count, bool) \
+            or re_arm_count <= 0:
         return False
-    cost_usd = fm.get("cost_usd", 0)
-    return isinstance(cost_usd, (int, float)) and float(cost_usd) > 0
+    folded_through = fm.get("folded_through_re_arm", 0)
+    if not isinstance(folded_through, int) or isinstance(folded_through, bool):
+        folded_through = 0
+    return re_arm_count > folded_through
 
 
 def rearm_reproduction_gate(wu: WorkUnit) -> tuple[bool, str]:
@@ -1744,6 +1759,12 @@ def fold_cumulative_on_rearm(wu: WorkUnit, backend: Backend) -> None:
 
     Backward-compatible: existing WUs with no cumulative_* fields initialise
     from 0 — no KeyError on first re-arm of a WU that pre-dates this contract.
+
+    Idempotent: a second call for the same re-arm reads cost_usd/duration_seconds/
+    input_tokens/output_tokens back as 0 (this call already reset them), so it
+    adds 0 to each cumulative_* accumulator and re-stamps the same
+    folded_through_re_arm value. Two calls for one re-arm produce the same
+    accumulators as one (FEAT-2026-0067/T01).
     """
     fm, _ = read_frontmatter(wu.file)
     prior_cost = float(fm.get("cost_usd") or 0)
@@ -1783,6 +1804,14 @@ def fold_cumulative_on_rearm(wu: WorkUnit, backend: Backend) -> None:
     backend.set_wu(wu, "input_tokens", 0)
     backend.set_wu(wu, "output_tokens", 0)
 
+    # Explicit fold marker (FEAT-2026-0067/T01): stamped in the same write set
+    # as the accumulators above so detect_rearm_dispatch can tell "folded" from
+    # "cost was zero" without inferring it from cost_usd's value.
+    re_arm_count = fm.get("re_arm_count", 0)
+    if not isinstance(re_arm_count, int) or isinstance(re_arm_count, bool):
+        re_arm_count = 0
+    backend.set_wu(wu, "folded_through_re_arm", re_arm_count)
+
 
 def gate_budget_usd(gate_file: Path) -> float | None:
     """Return the optional cumulative-cost ceiling declared on a GATE.md.

specfuse_loop-0.9.3/specfuse/loop/rearm_migration.py

@@ -0,0 +1,267 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""Stamp `folded_through_re_arm` onto every already-re-armed work unit
+(FEAT-2026-0067/T02).
+
+T01 (`detect_rearm_dispatch`, `specfuse/loop/loop.py`) reads an absent marker
+as `0`. Six WUs in this repository were folded under the pre-T01 `cost_usd >
+0` guard and carry no marker at all — indistinguishable, under T01's rule,
+from "never folded". This module closes that gap by giving every re-armed WU
+an explicit marker, without re-running the fold logic T01 owns.
+
+Two shapes, two treatments:
+
+  * **fold-ran** (`cumulative_cost_usd` present) — the fold already moved the
+    prior cycle's spend. Stamping `folded_through_re_arm = re_arm_count` is
+    the whole fix; `cumulative_*` is read, never written.
+  * **fold-never-ran** (`cumulative_cost_usd` absent, `re_arm_history[]`
+    populated) — the prior cycle's spend survives only as
+    `re_arm_history[].prior_cost_usd` / `prior_duration_seconds`. This module
+    folds those two recorded fields into `cumulative_cost_usd` /
+    `cumulative_duration_seconds` before stamping the marker, so every
+    re-armed WU ends up the same shape (PLAN.md's "converge" decision,
+    applied retroactively). No number is invented: only figures already
+    present in `re_arm_history` are summed. `prior_input_tokens` /
+    `prior_output_tokens` were never recorded on either fold-never-ran WU in
+    this repository, so `cumulative_input_tokens` / `cumulative_output_tokens`
+    are left unset rather than backfilled from `events.jsonl` — that would be
+    a second, undeclared source of truth for the same accumulator.
+
+    **A value with two meanings, read as if it had one.** `cost_usd` may be
+    folded safely by `fold_cumulative_on_rearm` because that fold runs *at
+    dispatch*, where `cost_usd` provably holds the prior cycle's spend. This
+    module runs *offline*, where `cost_usd` means "the prior cycle" **or**
+    "the current cycle" depending on whether a re-dispatch ever happened —
+    the exact defect class this feature exists to remove, reproduced by its
+    own fix. When a WU was re-armed and never re-dispatched, `cost_usd`
+    still holds the prior cycle's spend, and folding `re_arm_history`'s copy
+    of that same spend into `cumulative_cost_usd` without resetting
+    `cost_usd` double-counts it. The fold-never-ran branch below detects this
+    case — `cost_usd` agrees with the `re_arm_history` prior-cost sum within
+    `_COST_TOLERANCE_USD` — and resets `cost_usd` / `duration_seconds` to
+    `0.0` in the same write set, rather than adding a second copy of money
+    that is already accounted for in `cumulative_*`. Anyone adding a new
+    offline reader of `cost_usd` should assume it needs the same treatment.
+
+A WU never re-armed (`re_arm_count` absent or `0`) is untouched: no read,
+no write, not even a no-op frontmatter round-trip.
+
+Writes go through `specfuse.loop.loop.write_frontmatter_field`, the same
+single-key, no-reflow writer `fold_cumulative_on_rearm` uses — every other
+line in the file, marker or not, keeps its original text.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import loop as _loop
+
+_COST_TOLERANCE_USD = 0.02
+
+
+def _int_or_zero(value: object) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        return 0
+    return value
+
+
+def _classify(fm: dict) -> str:
+    """Return "not_rearmed", "fold_ran", or "fold_never_ran"."""
+    re_arm_count = fm.get("re_arm_count", 0)
+    if not isinstance(re_arm_count, int) or isinstance(re_arm_count, bool) or re_arm_count <= 0:
+        return "not_rearmed"
+    if "cumulative_cost_usd" in fm:
+        return "fold_ran"
+    return "fold_never_ran"
+
+
+def _history_sums(fm: dict) -> tuple[float, float]:
+    """Sum `prior_cost_usd` and `prior_duration_seconds` across every
+    `re_arm_history` entry. Non-numeric or missing fields contribute 0."""
+    history = fm.get("re_arm_history") or []
+    cost = 0.0
+    duration = 0.0
+    if isinstance(history, list):
+        for entry in history:
+            if not isinstance(entry, dict):
+                continue
+            pc = entry.get("prior_cost_usd")
+            if isinstance(pc, (int, float)) and not isinstance(pc, bool):
+                cost += float(pc)
+            pd = entry.get("prior_duration_seconds")
+            if isinstance(pd, (int, float)) and not isinstance(pd, bool):
+                duration += float(pd)
+    return cost, duration
+
+
+def _events_cost_before(
+    events_path: Path, wu_id: str, cutoff_iso: str
+) -> tuple[float, bool]:
+    """Sum `attempt_outcome` `cost_usd` for `wu_id` at or before `cutoff_iso`.
+
+    Returns `(total, seen)`; `seen` is False when the events file is
+    missing/unreadable or carries no matching `attempt_outcome` for this WU
+    — that means "nothing to cross-check against", not "prior cost was
+    zero", so the caller must not treat it as a disagreement. ISO-8601
+    timestamps with a fixed-offset suffix compare correctly as strings, so
+    this avoids a datetime dependency.
+    """
+    try:
+        lines = events_path.read_text().splitlines()
+    except OSError:
+        return 0.0, False
+    total = 0.0
+    seen = False
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue
+        if not isinstance(event, dict):
+            continue
+        if event.get("event_type") != "attempt_outcome":
+            continue
+        if event.get("correlation_id") != wu_id:
+            continue
+        timestamp = event.get("timestamp")
+        if not isinstance(timestamp, str) or timestamp > cutoff_iso:
+            continue
+        seen = True
+        payload = event.get("payload")
+        if not isinstance(payload, dict):
+            continue
+        cost = payload.get("cost_usd")
+        if isinstance(cost, (int, float)) and not isinstance(cost, bool):
+            total += float(cost)
+    return total, seen
+
+
+@dataclass
+class CensusResult:
+    fold_ran: list[Path] = field(default_factory=list)
+    fold_never_ran: list[Path] = field(default_factory=list)
+
+    def __str__(self) -> str:
+        return (
+            f"re-armed WUs: fold ran = {len(self.fold_ran)}"
+            f"    fold never ran = {len(self.fold_never_ran)}"
+        )
+
+
+def census(root: Path) -> CensusResult:
+    """Classify every re-armed WU under `root` by fold shape.
+
+    `root` is a directory searched recursively for `WU-*.md` files (the
+    repository's `.specfuse/features/` tree, or a fixture directory in
+    tests).
+    """
+    result = CensusResult()
+    for wu_path in sorted(Path(root).glob("**/WU-*.md")):
+        fm, _ = _loop.read_frontmatter(wu_path)
+        shape = _classify(fm)
+        if shape == "fold_ran":
+            result.fold_ran.append(wu_path)
+        elif shape == "fold_never_ran":
+            result.fold_never_ran.append(wu_path)
+    return result
+
+
+class PriorCostDisagreement(RuntimeError):
+    """Raised when a fold-never-ran WU's recorded prior cost disagrees with
+    its own `events.jsonl` total by more than a rounding tolerance."""
+
+
+@dataclass
+class MigrationOutcome:
+    path: Path
+    action: str  # "not_rearmed" | "fold_ran_stamped" | "fold_never_ran_migrated" | "already_migrated"
+
+
+def migrate_file(wu_path: Path, *, events_path: Path | None = None) -> MigrationOutcome:
+    """Migrate one WU file in place. Idempotent: a second call for an
+    already-migrated file is a no-op read, no writes.
+
+    `events_path` defaults to `events.jsonl` next to `wu_path` (the feature
+    folder layout `correlation-ids.md` documents); pass explicitly for a
+    fixture that does not follow that layout.
+    """
+    wu_path = Path(wu_path)
+    fm, _ = _loop.read_frontmatter(wu_path)
+    shape = _classify(fm)
+
+    if shape == "not_rearmed":
+        return MigrationOutcome(wu_path, "not_rearmed")
+
+    re_arm_count = _int_or_zero(fm.get("re_arm_count", 0))
+    folded_through = fm.get("folded_through_re_arm", 0)
+    if not isinstance(folded_through, int) or isinstance(folded_through, bool):
+        folded_through = 0
+
+    if shape == "fold_ran":
+        if folded_through == re_arm_count:
+            return MigrationOutcome(wu_path, "already_migrated")
+        _loop.write_frontmatter_field(wu_path, "folded_through_re_arm", re_arm_count)
+        return MigrationOutcome(wu_path, "fold_ran_stamped")
+
+    # fold_never_ran
+    if folded_through == re_arm_count and "cumulative_cost_usd" in fm:
+        return MigrationOutcome(wu_path, "already_migrated")
+
+    prior_cost, prior_duration = _history_sums(fm)
+
+    wu_id = fm.get("id")
+    history = fm.get("re_arm_history") or []
+    last_entry_ts = None
+    if isinstance(history, list):
+        for entry in history:
+            if isinstance(entry, dict) and isinstance(entry.get("timestamp"), str):
+                last_entry_ts = entry["timestamp"]
+    if isinstance(wu_id, str) and wu_id and last_entry_ts:
+        resolved_events_path = events_path or (wu_path.parent / "events.jsonl")
+        events_total, seen = _events_cost_before(
+            resolved_events_path, wu_id, last_entry_ts
+        )
+        if seen and abs(events_total - prior_cost) > _COST_TOLERANCE_USD:
+            raise PriorCostDisagreement(
+                f"{wu_path}: re_arm_history prior_cost_usd sums to "
+                f"{prior_cost:.6f} but events.jsonl attempt_outcome total "
+                f"through {last_entry_ts} is {events_total:.6f} "
+                f"(tolerance {_COST_TOLERANCE_USD})"
+            )
+
+    cost_usd = fm.get("cost_usd")
+    money_already_present = (
+        isinstance(cost_usd, (int, float))
+        and not isinstance(cost_usd, bool)
+        and abs(float(cost_usd) - prior_cost) <= _COST_TOLERANCE_USD
+    )
+
+    _loop.write_frontmatter_field(
+        wu_path, "cumulative_cost_usd", round(prior_cost, 6)
+    )
+    _loop.write_frontmatter_field(
+        wu_path, "cumulative_duration_seconds", round(prior_duration, 3)
+    )
+    if money_already_present:
+        # Never re-dispatched: `cost_usd` still holds the same spend now
+        # folded into `cumulative_cost_usd`. Reset it in this write set so
+        # the two fields don't both carry a copy of one cycle's spend.
+        _loop.write_frontmatter_field(wu_path, "cost_usd", 0.0)
+        _loop.write_frontmatter_field(wu_path, "duration_seconds", 0.0)
+    _loop.write_frontmatter_field(wu_path, "folded_through_re_arm", re_arm_count)
+    return MigrationOutcome(wu_path, "fold_never_ran_migrated")
+
+
+def migrate_repo(root: Path) -> list[MigrationOutcome]:
+    """Migrate every `WU-*.md` file under `root`. Returns one outcome per
+    file that was inspected (including untouched `not_rearmed` files, so
+    callers can audit that nothing else was written)."""
+    return [migrate_file(wu_path) for wu_path in sorted(Path(root).glob("**/WU-*.md"))]

{specfuse_loop-0.9.2 → specfuse_loop-0.9.3/specfuse_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.9.2
+Version: 0.9.3
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0

{specfuse_loop-0.9.2 → specfuse_loop-0.9.3}/specfuse_loop.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ specfuse/loop/lint_plan.py
 specfuse/loop/lint_roadmap.py
 specfuse/loop/loop.py
 specfuse/loop/plan_baseline.py
+specfuse/loop/rearm_migration.py
 specfuse/loop/scaffold.py
 specfuse/loop/validate_event.py
 specfuse/loop/data/CHANGELOG.seed.md
@@ -173,6 +174,7 @@ tests/test_feature_review_accumulation.py
 tests/test_filelock_portable.py
 tests/test_fingerprint.py
 tests/test_fix_bug_headless.py
+tests/test_fold_contract_documented.py
 tests/test_force_full_close.py
 tests/test_gate_budget.py
 tests/test_gate_budget_post_dispatch.py
@@ -263,6 +265,8 @@ tests/test_produces_semantics_unified.py
 tests/test_produces_shape.py
 tests/test_provision_labels.py
 tests/test_queue_stalled_adapter.py
+tests/test_rearm_fold_marker.py
+tests/test_rearm_migration.py
 tests/test_redaction_windows_home.py
 tests/test_resolve_base.py
 tests/test_result_block.py

specfuse_loop-0.9.3/tests/test_fold_contract_documented.py

@@ -0,0 +1,127 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""FEAT-2026-0067/T03 — the written contract agrees with the converged fold.
+
+Asserts the WU template documents `folded_through_re_arm` and the
+unconditional lifetime-accumulator contract, that both template copies stay
+byte-identical, that `cost.py`'s module docstring names the pre-migration
+fallback as legacy rather than an ongoing second shape, and that
+`wu_lifetime_cost_usd`'s behaviour is unchanged by this documentation-only WU.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from specfuse.loop import cost
+from specfuse.loop.cost import wu_lifetime_cost_usd
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+_CANONICAL_TEMPLATE = _REPO_ROOT / "specfuse/loop/data/templates/WU.template.md"
+_VENDORED_TEMPLATE = _REPO_ROOT / ".specfuse/templates/WU.template.md"
+
+
+def _write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text)
+
+
+def _write_events(path: Path, events: list[dict]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(json.dumps(e) for e in events) + "\n")
+
+
+def _attempt_outcome(correlation_id: str, cost_usd) -> dict:
+    return {
+        "correlation_id": correlation_id,
+        "event_type": "attempt_outcome",
+        "payload": {"cost_usd": cost_usd},
+    }
+
+
+class TestFoldContract(unittest.TestCase):
+    def test_template_documents_cumulative_as_lifetime(self):
+        text = _CANONICAL_TEMPLATE.read_text()
+        self.assertIn("folded_through_re_arm", text)
+        self.assertIn("every re-arm", text)
+        self.assertIn(
+            "whose prior cycle cost nothing",
+            text,
+            "template must state cumulative_* folds even a zero-cost prior cycle",
+        )
+
+    def test_vendored_template_documents_cumulative_as_lifetime(self):
+        text = _VENDORED_TEMPLATE.read_text()
+        self.assertIn("folded_through_re_arm", text)
+        self.assertIn("every re-arm", text)
+        self.assertIn("whose prior cycle cost nothing", text)
+
+    def test_template_copies_are_byte_identical(self):
+        self.assertEqual(
+            _CANONICAL_TEMPLATE.read_bytes(),
+            _VENDORED_TEMPLATE.read_bytes(),
+        )
+
+    def test_cost_docstring_names_migration_not_two_live_shapes(self):
+        doc = cost.__doc__ or ""
+        self.assertIn("FEAT-2026-0067", doc)
+        self.assertIn("pre-migration", doc)
+        self.assertNotIn("fold-never-ran", doc)
+        self.assertNotIn("fold-ran", doc)
+
+
+class TestLifetimeCostUnchanged(unittest.TestCase):
+    """Criterion 5: same reader behaviour before and after this WU's edits."""
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self.root = Path(self._tmp.name)
+        self.wu_path = self.root / "WU-07-x.md"
+        self.events_path = self.root / "events.jsonl"
+
+    def test_events_bearing_wu_unchanged(self):
+        _write(
+            self.wu_path,
+            """---
+id: FEAT-2026-0053/WU-07
+type: implementation
+status: done
+cost_usd: 4.281823
+---
+body
+""",
+        )
+        _write_events(
+            self.events_path,
+            [
+                _attempt_outcome("FEAT-2026-0053/WU-07", 1.0),
+                _attempt_outcome("FEAT-2026-0053/WU-07", 2.0),
+            ],
+        )
+        result = wu_lifetime_cost_usd(self.wu_path, self.events_path)
+        self.assertAlmostEqual(result, 3.0, delta=0.01)
+
+    def test_frontmatter_only_wu_unchanged(self):
+        _write(
+            self.wu_path,
+            """---
+id: FEAT-2026-0099/WU-01
+cost_usd: 1.5
+cumulative_cost_usd: 2.5
+---
+body
+""",
+        )
+        _write_events(self.events_path, [])
+        result = wu_lifetime_cost_usd(self.wu_path, self.events_path)
+        self.assertAlmostEqual(result, 4.0, delta=0.01)
+
+
+if __name__ == "__main__":
+    unittest.main()