specfuse-loop 0.22.0__tar.gz → 0.22.2__tar.gz

{specfuse_loop-0.22.0/specfuse_loop.egg-info → specfuse_loop-0.22.2}/PKG-INFO

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

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2}/pyproject.toml

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

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2}/specfuse/agent/providers/bugs.py

@@ -788,7 +788,18 @@ class BugsProvider:
                 label_written=result.label_written,
             )
 
-        return ActionOutcome(status=STATUS_ESCALATED, detail=detail, escalation=escalation)
+        # #3372: only a session that produced NO outcome marker can have an
+        # environmental cause — a dispatch that failed, an empty result, a
+        # crash. `outcome_named` is exactly that distinction, already carried
+        # from the session's own text (#3343). A `refused` is `/fix-bug`
+        # reading the issue and judging it out of scope; three of those say the
+        # queue holds three feature-scoped issues, not that anything is broken.
+        return ActionOutcome(
+            status=STATUS_ESCALATED,
+            detail=detail,
+            escalation=escalation,
+            environmental=not result.outcome_named,
+        )
 
     def reconcile(self, item: ActionItem, outcome: ActionOutcome) -> None:
         return None

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2}/specfuse/agent/run.py

@@ -220,6 +220,24 @@ class ActionOutcome:
     #: same shape as `NON_JUDGE_MODULES` and
     #: `DEPENDENCY_MANIFEST_NAMED_UNCOVERED`.
     escalation_waived: str = ""
+    #: Whether this escalation could have an environmental cause (#3372).
+    #:
+    #: Only an outcome reached WITHOUT reading the item can be about the run's
+    #: environment: a dispatch that failed, a session that produced no outcome
+    #: marker, a crash. An outcome reached BY reading the item is a judgement
+    #: about that item — `/fix-bug`'s `refused` says the work is not bug-sized,
+    #: `ci_not_green` and `pr_not_found` are facts about that issue's PR — and
+    #: three in a row says the queue holds three such issues, not that anything
+    #: is broken.
+    #:
+    #: #3343's breaker counted every escalation and stopped a run that was
+    #: working: two fixes merged, one held on red CI, six correctly declined,
+    #: 19 items never reached, and an escalation asserting an environment
+    #: cause a human then had to disprove.
+    #:
+    #: **Defaults False so a provider must opt in.** A provider that says
+    #: nothing never trips the breaker, rather than tripping it by omission.
+    environmental: bool = False
 
 
 class ActionProvider(Protocol):
@@ -1003,12 +1021,22 @@ def run_agent(
                 # #3343: an escalation whose cause keeps repeating is not about
                 # the item. Counted here rather than in a provider, because only
                 # the run can see that the SAME thing failed N times.
-                signature = failure_signature(item, outcome)
-                if signature == last_failure_signature:
-                    consecutive_identical_failures += 1
+                #
+                # #3372: but only an outcome the provider marks `environmental`
+                # can have an environmental cause. A per-item judgement —
+                # `refused`, `ci_not_green`, `pr_not_found` — RESETS the count
+                # rather than being ignored: a lane still reaching verdicts on
+                # items is not one whose environment is broken.
+                if not outcome.environmental:
+                    last_failure_signature = None
+                    consecutive_identical_failures = 0
                 else:
-                    last_failure_signature = signature
-                    consecutive_identical_failures = 1
+                    signature = failure_signature(item, outcome)
+                    if signature == last_failure_signature:
+                        consecutive_identical_failures += 1
+                    else:
+                        last_failure_signature = signature
+                        consecutive_identical_failures = 1
 
                 if consecutive_identical_failures >= IDENTICAL_FAILURE_LIMIT:
                     run_reason = (

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2}/specfuse/agent/severity_backfill.py

@@ -37,7 +37,11 @@ from typing import Callable, Optional
 
 from specfuse.agent.invoke import run_claude
 from specfuse.agent.triage_invoke import build_invocation, classify_severity
-from specfuse.loop.labels import read_severity_rubric
+from specfuse.loop.labels import (
+    list_existing_labels,
+    read_severity_rubric,
+    severity_label_projection,
+)
 
 from specfuse.loop import triage
 from specfuse.loop.build_provenance import warn_if_out_of_tree
@@ -50,7 +54,13 @@ def _default_runner(argv: list, check: bool = False):
     return subprocess.run(argv, check=check, capture_output=True, text=True)
 
 
-def apply_severity_backfill(runner: Callable, repo: str, decisions: list) -> list:
+def apply_severity_backfill(
+    runner: Callable,
+    repo: str,
+    decisions: list,
+    *,
+    label_projection: "dict | None" = None,
+) -> list:
     """Record each decision in `decisions` against its GitHub issue, marker
     first, label second.
 
@@ -65,6 +75,13 @@ def apply_severity_backfill(runner: Callable, repo: str, decisions: list) -> lis
     amended marker in place -- the marker is the authoritative record, the
     label a projection re-derived from it (`PLAN.md`'s "Record
     precedence").
+
+    `label_projection` maps a vocabulary value to the label this repository
+    spells it with (`labels.severity_label_projection`, #3353). The marker
+    always records the vocabulary value, so it stays comparable across
+    repositories; only the label takes the operator's own word. Absent or
+    missing a value, the vocabulary label is written -- the behaviour before
+    the projection existed.
     """
     results = []
     for decision in decisions:
@@ -104,7 +121,9 @@ def apply_severity_backfill(runner: Callable, repo: str, decisions: list) -> lis
             continue
         row["marker_written"] = True
 
-        label = triage.severity_label_for(severity)
+        label = (label_projection or {}).get(
+            severity, triage.severity_label_for(severity)
+        )
         try:
             runner(
                 ["gh", "issue", "edit", str(number), "--repo", repo, "--add-label", label],
@@ -156,7 +175,14 @@ def run_backfill(
     once `apply_severity_backfill` has run over it, that function's own
     `skipped`/`marker_written`/`label_written` fields.
     """
-    rubric = read_severity_rubric(working_dir, runner=runner, repo=repo)
+    # One `gh label list` feeds both the rubric and the write-side
+    # projection (#3353): the once-per-run listing this run is asserted on.
+    existing, _listing_reason = list_existing_labels(
+        working_dir, runner=runner, repo=repo
+    )
+    rubric = read_severity_rubric(
+        working_dir, runner=runner, repo=repo, existing=existing
+    )
     if not rubric:
         return {
             "rubric": {},
@@ -201,7 +227,14 @@ def run_backfill(
         decisions.append({"number": number, "body": body, "severity": severity})
 
     if apply and decisions:
-        write_results = apply_severity_backfill(runner, repo, decisions)
+        # A property of the repository's label set, not of any one issue
+        # (#3353) -- derived from the listing already read above.
+        projection = severity_label_projection(
+            [item.get("name", "") for item in (existing or [])]
+        )
+        write_results = apply_severity_backfill(
+            runner, repo, decisions, label_projection=projection
+        )
         by_number = {result["number"]: result for result in write_results}
         for row in rows:
             result = by_number.get(row["number"])

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2}/specfuse/loop/agent_policy.py

@@ -46,6 +46,7 @@ __all__ = (
     "SEVERITY_VALUES",
     "read_severity_label",
     "resolve_severity_aliases",
+    "resolve_required_checks",
     "DEFAULT_SEVERITY_ALIASES",
     "AUTOMERGE_VALUES",
     "GATE_REVIEW_VALUES",
@@ -295,6 +296,45 @@ def resolve_max_items(flag: "int | None",
     return _positive_int_budget(path, "max_items_per_day")
 
 
+def resolve_required_checks(path: "str | Path | None" = None) -> tuple:
+    """`rules.bugs.required_checks` as a tuple of check names, or `()` (#3373).
+
+    The names that must be **present and passing** before the bug lane may
+    auto-merge. Empty when absent or unusable, so a deployment that never
+    declared it behaves exactly as before: any `success` conclusion is accepted.
+
+    Why it exists. `evaluate_merge_guardrails` accepted any `success`, and a
+    repository whose PR job is a deliberate fast lane — excluding a test group
+    that guards committed expectations — gave a `success` that **could not
+    fail** on that class of defect. A bug-lane PR merged under `automerge: "on"`
+    and left `main` red for an hour.
+
+    The split those repositories rely on assumes every change already passed
+    the full gate set before its PR opened. That holds for driver work-unit
+    PRs and does **not** hold for bug-lane PRs, where a headless session
+    chooses which tests to run. This key is how a repository points the lane at
+    the complete check rather than the fast one.
+
+    A string is accepted as a one-element list — the common single-check case —
+    and anything else unusable resolves to `()`. Requiring nothing is the
+    pre-existing behaviour; inventing a requirement from a malformed value
+    would block every merge on a typo.
+    """
+    try:
+        policy = load_policy(path)
+    except (FileNotFoundError, OSError):
+        return ()
+    rules = policy.get("rules") if isinstance(policy, dict) else None
+    bugs = rules.get("bugs") if isinstance(rules, dict) else None
+    raw = bugs.get("required_checks") if isinstance(bugs, dict) else None
+    if isinstance(raw, str):
+        name = raw.strip()
+        return (name,) if name else ()
+    if not isinstance(raw, list):
+        return ()
+    return tuple(str(n).strip() for n in raw if str(n).strip())
+
+
 def resolve_max_open_prs(path: "str | Path | None" = None) -> "int | None":
     """`budgets.max_open_prs`, or None when unset or unusable (#3340).
 
@@ -323,10 +363,21 @@ def describe_budget_sources(**caps) -> str:
     that is not capped: the operator cannot tell which of the two they have.
     Each value is a `(value, source)` pair, source being `flag`, `policy` or
     `none`.
+
+    `max_items` carries an explicit `per run` (#3340). The policy key it comes
+    from is named `max_items_per_day` and is applied per run -- enforcing it
+    across a day needs state that survives a process. Printing `max_items=62
+    (policy)` against that key invites the reading the name suggests, and the
+    wrong reading is the unsafe one: a day of runs can exceed the number the
+    operator believes they set. Only this cap is annotated, because only this
+    one has a name promising something wider than it delivers; an unset cap
+    prints `unbounded` and needs no qualifier.
     """
     parts = []
     for name, (value, source) in sorted(caps.items()):
-        parts.append(f"{name}={'unbounded' if value is None else value} ({source})")
+        rendered = "unbounded" if value is None else str(value)
+        qualifier = " per run" if name == "max_items" and value is not None else ""
+        parts.append(f"{name}={rendered} ({source}{qualifier})")
     return "budgets: " + ", ".join(parts)
 
 

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2}/specfuse/loop/bug_lane_run.py

@@ -38,6 +38,7 @@ from typing import Any, Callable, Optional
 
 from specfuse.loop.agent_policy import (
     bug_lane_ci_wait_seconds,
+    resolve_required_checks,
     bug_lane_limits,
     resolve_bug_automerge,
 )
@@ -197,7 +198,40 @@ _BUCKET_PENDING = "pending"
 _CI_FAILING = "fail"
 
 
-def _read_ci_conclusion_once(runner: Callable, repo: str, pr_number: int) -> str:
+def _required_checks_verdict(rows: list, required) -> str:
+    """`""` when every required check is present and passing, else why not.
+
+    A required check that **never ran** is the case #3373 is about: the
+    repository's PR job was green and the check that would have caught the
+    defect was not in the list at all. It is not a failure — nothing failed —
+    and it is equally not the green the operator asked the lane to require.
+
+    A required check that was **skipped** is treated the same way. Skipping is
+    not a failure in general, which is why `_BUCKETS_OK` tolerates it, but a
+    check an operator named as required and that did not run cannot establish
+    what it was required to establish.
+    """
+    if not required:
+        return ""
+    by_name = {}
+    for row in rows:
+        name = row.get("name")
+        if isinstance(name, str):
+            by_name[name] = str(row.get("bucket") or "").lower()
+    for name in required:
+        bucket = by_name.get(name)
+        if bucket is None:
+            return f"required check never ran: {name}"
+        if bucket == _BUCKET_PENDING:
+            return _CI_PENDING
+        if bucket != "pass":
+            return f"required check not passing: {name} ({bucket})"
+    return ""
+
+
+def _read_ci_conclusion_once(
+    runner: Callable, repo: str, pr_number: int, required=()
+) -> str:
     """One `gh pr checks` read, mapped through `bucket`.
 
     `_CI_PENDING` when any check is queued or running, or when no check is
@@ -244,6 +278,14 @@ def _read_ci_conclusion_once(runner: Callable, repo: str, pr_number: int) -> str
 
     if _BUCKET_PENDING in buckets:
         return _CI_PENDING
+
+    # #3373: the operator's own list, checked before the aggregate verdict.
+    # A repository whose PR job deliberately excludes a test group can point
+    # the lane at the complete check instead of the fast one.
+    verdict = _required_checks_verdict(rows, required)
+    if verdict:
+        return verdict
+
     if buckets <= _BUCKETS_OK:
         return "success"
     return _CI_FAILING
@@ -258,6 +300,7 @@ def pr_ci_conclusion(
     clock: Callable = time.monotonic,
     deadline_seconds: float = CI_WAIT_SECONDS,
     poll_seconds: float = CI_POLL_SECONDS,
+    required_checks=(),
 ) -> str:
     """Wait for `pr_number`'s CI to reach a conclusion, then return it.
 
@@ -284,7 +327,9 @@ def pr_ci_conclusion(
     """
     started = clock()
     while True:
-        conclusion = _read_ci_conclusion_once(runner, repo, pr_number)
+        conclusion = _read_ci_conclusion_once(
+            runner, repo, pr_number, required_checks
+        )
         if conclusion != _CI_PENDING:
             return conclusion
         if clock() - started >= deadline_seconds:
@@ -720,6 +765,11 @@ def run_bug_lane(
     ci_conclusion = pr_ci_conclusion(
         runner, repo, pr_number,
         sleep=ci_sleep, clock=ci_clock, deadline_seconds=deadline_seconds,
+        # #3373: the checks this repository says must be green before the lane
+        # may merge unattended. Empty unless declared, so behaviour is
+        # unchanged for anyone who has not pointed the lane at a complete
+        # check.
+        required_checks=resolve_required_checks(policy_path),
     )
     state_reader = GitHubMergeCapState(runner=runner, repo=repo, now=now)
 

specfuse_loop-0.22.2/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.22.2

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2}/specfuse/loop/labels.py

@@ -402,11 +402,75 @@ def _ensure_severity_labels(target, *, runner, repo=None) -> list:
     return failed
 
 
+def severity_label_projection(label_names, *, aliases: Optional[dict] = None) -> dict:
+    """`{severity_value: label_name}` for the values a repository spells in its
+    own word (#3353), given the `severity:*` labels it defines.
+
+    `severity_aliases` (#3349) are honoured by the `min_severity` floor, which
+    reads an aliased label through `read_severity_label`. The classifier
+    FEAT-2026-0113 added answers in the published vocabulary instead, so the
+    write path projected `severity:high` at a repository whose issues all say
+    `severity:major` -- both spellings in circulation, and nothing reporting
+    the asymmetry.
+
+    This is the write-side half. The classifier is deliberately left answering
+    in the vocabulary so the marker's `severity=` field stays comparable across
+    repositories; only the *label* takes the repository's own word.
+
+    Pure over *label_names* rather than listing them itself, so the one caller
+    that needs both this and `read_severity_rubric` pays for a single
+    `gh label list` -- the once-per-run listing that run is asserted on.
+
+    Entries appear only where the projection actually differs, so an empty
+    result means "write the vocabulary label" and callers need no special case.
+    Two bounds keep it honest:
+
+    * **A label the repository does not define is never projected.** The
+      shipped `DEFAULT_SEVERITY_ALIASES` name words (`blocker`, `urgent`,
+      `trivial`) most repositories have never created; projecting one would
+      write a label that does not exist.
+    * **An in-vocabulary label always wins.** A repository defining both
+      `severity:high` and `severity:major` gets no entry for `high` -- the same
+      precedence `read_severity_rubric` applies when it builds the rubric.
+
+    Two aliases onto one value is the operator's own ambiguity. The lowest
+    label name sorts first, so a run is at least reproducible; defining the
+    vocabulary label is what removes the ambiguity.
+    """
+    prefix = agent_policy.SEVERITY_LABEL_PREFIX
+    try:
+        severity_names = sorted(
+            name for name in label_names if name.startswith(prefix)
+        )
+    except TypeError:
+        return {}
+
+    in_vocabulary = {
+        name[len(prefix):] for name in severity_names
+        if name[len(prefix):] in agent_policy.SEVERITY_VALUES
+    }
+
+    aliases = aliases if aliases is not None else agent_policy.resolve_severity_aliases()
+    projection: dict = {}
+    for name in severity_names:
+        word = name[len(prefix):]
+        if word in agent_policy.SEVERITY_VALUES:
+            continue
+        mapped = aliases.get(word.strip().lower())
+        if mapped not in agent_policy.SEVERITY_VALUES:
+            continue
+        if mapped in in_vocabulary or mapped in projection:
+            continue
+        projection[mapped] = name
+    return projection
+
+
 def read_severity_rubric(
     target: str | Path,
     *,
     runner: Optional[Callable] = None,
     repo: Optional[str] = None,
+    existing: Optional[list] = None,
 ) -> dict:
     """`{severity_value: description}` from the repo's own `severity:*` labels,
     or specfuse's `DEFAULT_SEVERITY_RUBRIC` when it has defined none (#3352).
@@ -428,7 +492,11 @@ def read_severity_rubric(
     """
     runner = runner if runner is not None else _default_runner
 
-    existing, _reason = list_existing_labels(target, runner=runner, repo=repo)
+    # `existing` lets a caller that already listed the repository's labels pass
+    # them in rather than pay for a second `gh label list` (#3353). Absent, the
+    # listing happens here exactly as it always did.
+    if existing is None:
+        existing, _reason = list_existing_labels(target, runner=runner, repo=repo)
     if existing is None:
         return {}
 

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2}/specfuse/loop/loop.py

@@ -125,7 +125,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.22.0"
+DRIVER_VERSION = "0.22.2"
 # 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

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.22.0 → specfuse_loop-0.22.2}/specfuse_loop.egg-info/SOURCES.txt

@@ -367,6 +367,7 @@ tests/test_heartbeat.py
 tests/test_heartbeat_adapter.py
 tests/test_human_output_rule.py
 tests/test_human_work_unit.py
+tests/test_hygiene_boundary_guidance.py
 tests/test_hyphenated_gate_name.py
 tests/test_init_integration.py
 tests/test_installed_copy_driver_e2e.py
@@ -469,6 +470,7 @@ tests/test_notify_sla.py
 tests/test_operator_escalation_rule.py
 tests/test_oracle_set_declared.py
 tests/test_oracle_unrunnable_attribution.py
+tests/test_per_run_item_cap_disclosure.py
 tests/test_pick_feature_skill.py
 tests/test_pin_honesty_and_integrity.py
 tests/test_pin_marker_not_inherited.py
@@ -476,6 +478,7 @@ tests/test_pin_marker_spawn_sites.py
 tests/test_plan_baseline.py
 tests/test_planned_cost_lint.py
 tests/test_planning_cost_floor.py
+tests/test_plugin_prose_cross_refs.py
 tests/test_plugin_qualified_dispatch.py
 tests/test_policy_budgets_applied.py
 tests/test_policy_proposals.py
@@ -516,6 +519,7 @@ tests/test_replan_note_collision.py
 tests/test_replan_trigger.py
 tests/test_replan_turn_contract.py
 tests/test_replay_spin.py
+tests/test_required_checks.py
 tests/test_resolve_base.py
 tests/test_restart_cap_counts_progress.py
 tests/test_result_block.py
@@ -553,6 +557,7 @@ tests/test_severity_backfill_end_to_end.py
 tests/test_severity_backfill_limit.py
 tests/test_severity_backfill_marker.py
 tests/test_severity_backfill_run.py
+tests/test_severity_label_projection.py
 tests/test_severity_rubric.py
 tests/test_shipped_templates_parse.py
 tests/test_skill_discovery_links.py

specfuse_loop-0.22.2/tests/test_hygiene_boundary_guidance.py

@@ -0,0 +1,88 @@
+# Copyright 2026 Specfuse Contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+"""The authoring rule teaches the reword the lint asks for (#3357).
+
+`lint_plan` WARNs when a work unit declares a `produces:` path that also matches
+one of its own Do-not-touch patterns, and since #3357 that warning names the
+fix: reword the boundary to name the *surfaces* it protects rather than the file
+this unit also produces.
+
+The shape that trips it is not an edge case. A hygiene unit exists to make a
+bounded fix inside a file a previous unit built, so it has to declare that file
+in `produces:` *and* protect almost all of it — and §7 of the authoring skill,
+which is where an author is told how to write a hygiene unit, said to name the
+broken file in `produces:` without saying anything about how to word the
+boundary. The author met the warning with no guidance in the rule that
+generated the shape.
+
+Worse than unhelpful: FEAT-2026-0113's `T08H` wrote "every other function in
+`specfuse/loop/triage.py`", which read literally forbids editing the one
+function that unit existed to fix. It passed only because the acceptance
+criteria named the target unambiguously, so the boundary and the criteria
+contradicted each other and only the criteria were load-bearing.
+
+This guards the pairing rather than the prose: whatever wording either side
+uses, the authoring rule must teach surface-naming, so the lint's recommended
+fix and the rule that produces the shape cannot drift apart again.
+"""
+
+from __future__ import annotations
+
+import re
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILL = REPO_ROOT / "plugins/specfuse/skills/authoring-work-units/SKILL.md"
+MIRROR = REPO_ROOT / ".specfuse/skills/authoring-work-units/SKILL.md"
+LINT = REPO_ROOT / "specfuse/loop/lint_plan.py"
+
+
+def _section_7(text: str) -> str:
+    """§7, the hygiene-work-unit section, up to the next top-level heading."""
+    match = re.search(r"^## 7\. .*?$(.*?)(?=^## \d+\. )", text, re.S | re.M)
+    assert match, "authoring skill has no '## 7.' section"
+    return match.group(1)
+
+
+class HygieneBoundaryGuidance(unittest.TestCase):
+
+    def test_the_lint_still_recommends_naming_surfaces(self):
+        # If this fails the lint changed its advice, and the rule below is
+        # now teaching the wrong reword rather than merely a stale one.
+        self.assertIn("surfaces it protects", LINT.read_text(encoding="utf-8"))
+
+    def test_section_7_tells_the_author_how_to_word_the_boundary(self):
+        body = _section_7(SKILL.read_text(encoding="utf-8"))
+
+        self.assertIn(
+            "surface", body.lower(),
+            "§7 tells an author to put the broken file in `produces:`, which is "
+            "exactly the shape that trips the Do-not-touch collision warning. "
+            "It must also tell them to word the boundary by naming the "
+            "surfaces it protects, or the rule generates a warning it gives no "
+            "way to answer (#3357).",
+        )
+
+    def test_section_7_warns_against_the_whole_file_wording(self):
+        body = _section_7(SKILL.read_text(encoding="utf-8")).lower()
+
+        self.assertTrue(
+            "every other function in" in body or "whole file" in body,
+            "§7 must show the wording that actually went wrong — a boundary "
+            "phrased over a whole file contradicts the criteria of a unit that "
+            "exists to edit one function in it (FEAT-2026-0113/T08H).",
+        )
+
+    def test_the_mirrored_copy_agrees(self):
+        # plugins/ is canonical; .specfuse/ is the synced scaffold copy.
+        self.assertEqual(
+            SKILL.read_text(encoding="utf-8"),
+            MIRROR.read_text(encoding="utf-8"),
+            "plugins/ and .specfuse/ copies of the authoring skill diverged — "
+            "run scripts/sync-scaffold.sh",
+        )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

specfuse_loop-0.22.2/tests/test_per_run_item_cap_disclosure.py

@@ -0,0 +1,80 @@
+# Copyright 2026 Specfuse Contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+"""`max_items_per_day` is enforced per run, and now says so (#3340).
+
+Most of #3340 landed: budgets resolve from the policy when no flag is given,
+`max_open_prs` gates bug-lane dispatch, and the run opens with a line naming
+each effective cap and its source.
+
+One expectation was left. The policy key is named `max_items_per_day` and is
+applied *per run* -- enforcing it across runs within a day needs state that
+survives a process, which is a feature, not this fix. `resolve_max_items`
+records that honestly in its docstring, but a docstring is not a surface an
+operator reads. The issue offered the alternative explicitly: enforce it across
+runs, **or** document it as per-run.
+
+So the operator-facing surfaces carry it. A run that prints `max_items=62
+(policy)` against a policy whose key says `per_day` invites exactly the wrong
+reading -- and the wrong reading is the unsafe one, since a day of runs can
+exceed the number the operator believes they set.
+"""
+
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+from specfuse.loop import agent_policy
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILL = REPO_ROOT / "plugins/specfuse/skills/derive-agent-policy/SKILL.md"
+
+
+class PerRunItemCapDisclosure(unittest.TestCase):
+
+    def test_the_run_line_says_the_item_cap_is_per_run(self):
+        line = agent_policy.describe_budget_sources(
+            max_items=(62, "policy"),
+            max_tokens=(2800000, "policy"),
+            max_minutes=(None, "none"),
+        )
+
+        self.assertIn("per run", line)
+
+    def test_a_flag_sourced_item_cap_says_it_too(self):
+        # The cap is per-run whoever set it; the policy key's name is what
+        # misleads, but a flag run is bounded the same way.
+        line = agent_policy.describe_budget_sources(max_items=(5, "flag"))
+
+        self.assertIn("per run", line)
+
+    def test_other_caps_are_not_annotated(self):
+        # Only the item cap has a name that promises something wider than it
+        # delivers. Annotating the rest would be noise.
+        line = agent_policy.describe_budget_sources(
+            max_tokens=(2800000, "policy"),
+            max_open_prs=(3, "policy"),
+        )
+
+        self.assertNotIn("per run", line)
+
+    def test_an_absent_item_cap_is_not_annotated(self):
+        line = agent_policy.describe_budget_sources(max_items=(None, "none"))
+
+        self.assertIn("unbounded", line)
+        self.assertNotIn("per run", line)
+
+    def test_the_drafting_skill_discloses_the_semantics(self):
+        body = SKILL.read_text(encoding="utf-8")
+
+        self.assertIn(
+            "per run", body,
+            "/derive-agent-policy drafts `max_items_per_day` into an "
+            "operator's policy file. It must say that the key is applied per "
+            "run, or the operator writes a number believing it bounds a day "
+            "(#3340).",
+        )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()