specfuse-loop 0.29.0__tar.gz → 0.30.0__tar.gz

{specfuse_loop-0.29.0/specfuse_loop.egg-info → specfuse_loop-0.30.0}/PKG-INFO

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

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/pyproject.toml

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

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/agent/invoke.py

@@ -112,13 +112,24 @@ def _parse_envelope(raw: str) -> tuple:
     return result_text, (usage if usage else None)
 
 
+#: Every token field `budgets.max_tokens_per_run` is compared against (#3522).
+SPEND_TOKEN_FIELDS = (
+    "input_tokens",
+    "output_tokens",
+    "cache_read_input_tokens",
+    "cache_creation_input_tokens",
+)
+
+
 def usage_spend(usage: Optional[dict]) -> int:
-    """`spend` for `ActionOutcome`: input + output tokens, cache reads
-    excluded -- matching the driver's own cost line (`loop.py:7300-7302`).
+    """`spend` for `ActionOutcome`: all four usage token fields, cache reads
+    and cache creation included (#3522). With prompt caching nearly all of a
+    headless session's input is cache traffic, so leaving it out reported a
+    small fraction of the real volume and `max_tokens_per_run` never bound.
     Zero for a `None` usage, never a `KeyError`."""
     if not usage:
         return 0
-    return int(usage.get("input_tokens", 0)) + int(usage.get("output_tokens", 0))
+    return sum(int(usage.get(key, 0)) for key in SPEND_TOKEN_FIELDS)
 
 
 def run_claude(

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/agent/providers/triage.py

@@ -303,7 +303,8 @@ class TriageProvider:
 
         rubric = self._rubric_for_run()
         argv, prompt = build_invocation(
-            number, title, body, self._repo, self._working_dir, rubric=rubric
+            number, title, body, self._repo, self._working_dir, rubric=rubric,
+            comments=row.get("comments") or [],
         )
         invoked = run_claude(argv, prompt, runner=self._runner)
         spend = usage_spend(invoked.usage)
@@ -368,6 +369,9 @@ class TriageProvider:
                 "category": category,
                 "confidence": confidence,
                 "severity": severity,
+                # #3521: without the issue's labels `apply_triage` cannot see
+                # a person's `severity:*` label, and adds a second one beside it.
+                "labels": row.get("labels") or [],
             }
         ]
         results = apply_triage(
@@ -391,11 +395,14 @@ class TriageProvider:
                 spend=spend,
             )
 
-        return ActionOutcome(
-            status=STATUS_COMPLETED,
-            detail=f"issue #{number} triaged as {row_result.get('category')}",
-            spend=spend,
-        )
+        detail = f"issue #{number} triaged as {row_result.get('category')}"
+        if row_result.get("severity_conflict"):
+            detail += (
+                f"; severity label left as "
+                f"{', '.join(row_result['severity_conflict'])} "
+                f"(triage judged {severity})"
+            )
+        return ActionOutcome(status=STATUS_COMPLETED, detail=detail, spend=spend)
 
     def reconcile(self, item: ActionItem, outcome: ActionOutcome) -> None:
         return None

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/agent/run.py

@@ -62,6 +62,7 @@ from specfuse.loop.build_provenance import warn_if_out_of_tree
 from specfuse.loop.escalation import (
     CREATED_NUMBER_UNKNOWN,
     annotate_escalation,
+    clear_closed_escalation_labels,
     emit_escalation,
 )
 
@@ -198,8 +199,8 @@ class ActionOutcome:
     `spend` is real tokens, not a proxy — a provider that dispatches a
     headless `claude` session reports it through
     `specfuse.agent.invoke.usage_spend(invoke_result.usage)`
-    (FEAT-2026-0108/T01): input plus output tokens, cache reads excluded, so
-    it lines up with the driver's own cost line. It defaults to zero so a
+    (FEAT-2026-0108/T01): all four usage token fields, cache reads and cache
+    creation included (#3522). It defaults to zero so a
     provider that dispatches nothing, or whose session reported no usage
     envelope, leaves the run's total spend untouched. `escalation`, when set
     on a `STATUS_ESCALATED` outcome, is recorded — on `target_issue` when the
@@ -299,6 +300,10 @@ class RunSummary:
     #: re-run, because a triage-only run otherwise looks like a bug lane that
     #: declined everything.
     newly_triaged_bugs_undispatched: tuple = ()
+    #: `(number, reason)` for bugs this run triaged that the severity floor
+    #: holds back (#3521). Kept apart from the re-run list above: a re-run
+    #: would not dispatch them either, so the summary names the floor instead.
+    newly_triaged_bugs_below_floor: tuple = ()
 
 
 def _bug_marked_numbers(snapshot: AgentSnapshot) -> set:
@@ -306,6 +311,30 @@ def _bug_marked_numbers(snapshot: AgentSnapshot) -> set:
     return {issue.number for issue in snapshot.issues if issue.triage_category == "bug"}
 
 
+def _split_by_severity_floor(numbers, snapshot: AgentSnapshot,
+                             policy_path: Optional[str]) -> tuple:
+    """`(re-runnable, [(number, reason), ...])` for bugs triaged and never
+    dispatched (#3521).
+
+    Reads the floor exactly as `BugsProvider.advertise` does, so a bug this
+    returns as held back is one the next run's lane would skip too -- telling
+    the operator to re-run for it was a promise the lane would not keep.
+    """
+    floor = agent_policy.resolve_min_severity(policy_path)
+    aliases = agent_policy.resolve_severity_aliases(policy_path)
+    labels_by_number = {issue.number: issue.labels for issue in snapshot.issues}
+    rerun, held = [], []
+    for number in numbers:
+        severity, via = agent_policy.read_severity_label(
+            labels_by_number.get(number), aliases)
+        ok, why = agent_policy.meets_severity_floor(severity, floor, via=via)
+        if ok:
+            rerun.append(number)
+        else:
+            held.append((number, why))
+    return rerun, held
+
+
 def _refresh_snapshot(
     previous: AgentSnapshot,
     *,
@@ -838,6 +867,13 @@ def run_agent(
             policy_path=policy_path,
             features_root=features_root,
         )
+        # #3523: a closed issue keeps no escalation labels the lane wrote.
+        cleared = clear_closed_escalation_labels(runner, repo)
+        if cleared:
+            report(
+                "cleared needs-human from closed escalated issue(s): "
+                + ", ".join(f"#{number}" for number in cleared)
+            )
         bugs_preempt = _resolve_bugs_preempt(policy_path)
         report(
             f"snapshot: {len(snapshot.issues)} open issues, "
@@ -1179,6 +1215,10 @@ def run_agent(
             for number in _bug_marked_numbers(snapshot) - bugs_marked_at_start
             if f"bug-{number}" not in handled_ids
         )
+        newly_triaged, below_floor = _split_by_severity_floor(
+            newly_triaged, snapshot, policy_path)
+        for number, why in below_floor:
+            report(f"#{number} newly triaged as bug, not dispatched — {why}")
         if newly_triaged:
             report(
                 f"{len(newly_triaged)} issue(s) newly triaged as bug and not "
@@ -1200,6 +1240,7 @@ def run_agent(
             escalations=tuple(escalations),
             wip_refs=tuple(wip_refs),
             newly_triaged_bugs_undispatched=tuple(newly_triaged),
+            newly_triaged_bugs_below_floor=tuple(below_floor),
         )
     finally:
         lock_fd.close()
@@ -1229,6 +1270,8 @@ def _format_summary(summary: RunSummary) -> str:
             f"    {len(summary.newly_triaged_bugs_undispatched)} newly triaged "
             f"as bug, not dispatched — re-run to fix them: {numbers}"
         )
+    for number, why in summary.newly_triaged_bugs_below_floor:
+        lines.append(f"    #{number} newly triaged as bug, not dispatched — {why}")
     return "\n".join(lines)
 
 

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/agent/triage_invoke.py

@@ -47,6 +47,7 @@ def build_invocation(
     model: str = "sonnet",
     effort: str = "medium",
     rubric: Optional[dict] = None,
+    comments: Optional[list] = None,
 ):
     """Build argv and prompt text for a headless triage-classification
     session against one issue. Returns a `(argv, prompt)` tuple; runs
@@ -60,6 +61,12 @@ def build_invocation(
     session -- and the marker instruction grows a third `severity=` field.
     The prompt is built from `rubric`'s own mapping alone; it holds no copy
     of any shipped default definitions.
+
+    `comments` is the issue's comment list as `gh issue list --json comments`
+    returns it (#3520): a maintainer often routes an issue -- folds it into a
+    feature, marks it a duplicate -- in a comment, and a classifier reading
+    the body alone labels it `bug` anyway. No comments leaves the prompt
+    byte-identical to the one built without them.
     """
     argv = build_claude_argv(model, effort)
     if rubric:
@@ -88,6 +95,7 @@ def build_invocation(
         f"Issue number: {issue_number}\n"
         f"Issue title: {title}\n\n"
         f"Issue body:\n{body}\n\n"
+        f"{_comments_block(comments)}"
         "Classify this issue into exactly one of the categories: "
         f"{', '.join(CATEGORIES)}.\n\n"
         f"{marker_instruction}"
@@ -95,6 +103,23 @@ def build_invocation(
     return argv, prompt
 
 
+def _comments_block(comments: Optional[list]) -> str:
+    if not comments:
+        return ""
+    rendered = []
+    for comment in comments:
+        author = (comment.get("author") or {}).get("login") or "unknown"
+        association = comment.get("authorAssociation") or "NONE"
+        rendered.append(f"--- @{author} ({association}):\n{comment.get('body') or ''}")
+    return (
+        "Issue comments, oldest first:\n"
+        + "\n\n".join(rendered)
+        + "\n\nIf a maintainer comment already routes this issue -- folds it "
+        "into a feature or another issue, or marks it a duplicate -- classify "
+        "it by that decision, not by the body alone.\n\n"
+    )
+
+
 def classify_result(result_text: str) -> Optional[tuple]:
     """Return the `(category, confidence)` pair a classification session's
     output names, or `None` if the output carries no parseable triage

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/loop/arm_eval.py

@@ -104,6 +104,7 @@ JUDGE_MODULES = tuple(
         "agent_policy.py",       # automerge dial, diff/merge caps, test paths
         "cost.py",               # spend, read by budget_projection
         "gate_commands.py",      # resolves which commands a gate must pass
+        "gen_contract.py",       # IS a `code` gate in component repos; an edit can turn a red contract green
         # What a work unit or a close must satisfy.
         "closing_requirements.py",
         "criteria_state.py",
@@ -157,6 +158,8 @@ NON_JUDGE_MODULES = {
     "learnings_query.py": "reads LEARNINGS.md for planning context",
     "lint_monitoring.py": "lints monitoring.yml, which no arm/close/merge "
         "verdict reads",
+    "layout.py": "resolves layout.yml for lint_roadmap and skills; no arm/"
+        "close/merge verdict reads it",
     "lint_roadmap.py": "lints roadmap.md, which no arm/close/merge verdict reads",
     "notify.py": "delivery of a message about a decision already made",
     "notify_escalation.py": "as notify.py",

specfuse_loop-0.30.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.30.0

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/loop/data/docs/concepts/autonomy-stop-classes.md

@@ -48,6 +48,13 @@ cleared by editing driver code; it clears by changing the plan's numbers.
 file under a judge-path surface — paths that would let a work unit edit its
 own verification.
 
+**Does not cover the terminal gate.** The class reads only the successor
+gate's drafted units. A terminal gate has no successor, so what its own units
+change is never checked; a single-gate feature is never checked at all. The
+terminal close goes straight to the judge, and no judge-path check sits on
+that path (#3542). A feature that edits a judge surface in its last gate should
+run under `review`.
+
 **Fires when:** a drafted WU's `produces:` list contains a path matching one
 of `JUDGE_PATHS` — `.specfuse/verification.yml`, `.specfuse/hooks/`,
 `.specfuse/rules/`, `.github/workflows/`, or `pyproject.toml` (matched

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/loop/data/docs/methodology.md

@@ -26,8 +26,8 @@ on both surfaces.
   both stay resumable: a human flips the feature back to `active` when the
   obstacle clears. Both are distinct from `abandoned` (dead) and `done`
   (complete).
-  - `blocked` — cannot proceed because a **named** dependency is unmet: an ADR
-    awaiting approval, or an upstream `FEAT-YYYY-NNNN` that must complete first.
+  - `blocked` — cannot proceed because a **named** dependency is unmet: a decision
+    awaiting approval (ADR or decision entry, per `layout.yml`), or an upstream `FEAT-YYYY-NNNN` that must complete first.
     A blocked feature always names and links its blocker, so the roadmap shows
     the dependency at a glance. Only `planned` or `active` may be blocked.
   - `deferred` — a *voluntary* park with no named blocker, pending an external
@@ -795,9 +795,12 @@ untouched** — the same eight stop classes, the same `would_arm`, the same
 single flip site. What changed is what an armed gate is armed *on*. Before the
 judge, an `auto` feature let the session that did the work write the verdict
 that advanced the feature; now a fresh evaluator that never sees that session's
-prose writes it, and can only lower it. The `judge_editing` stop class still
-vetoes any gate that edited the loop's own driver, so a feature that changes
-the machinery keeps its human checkpoint regardless of this default.
+prose writes it, and can only lower it. The `judge_editing` stop class vetoes
+arming a successor gate whose drafted units would edit a judge surface. It
+does **not** cover the terminal gate's own units, so a single-gate feature,
+or the last gate of any feature, that edits the loop's verdict machinery
+reaches its close with no human checkpoint under `auto` (#3542). Choose
+`review` for such a feature.
 
 Tighten to `review` when the judge cannot do its job — a feature whose criteria
 are not judgeable from the evidence bundle (see `judge_disabled` in §3), or one

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/loop/data/docs/skills.md

@@ -49,7 +49,7 @@ roadmap ──/pick-feature──▶ active ──/draft-feature──▶ gate 1
 - **`/roadmap-add`** — add a new feature row to the roadmap before it's ready to
   pick.
 - **`/block-feature`** — flip a roadmap feature to `blocked` (or clear it) with a
-  linked `**Blocked by.**` blocker — an ADR awaiting approval or an upstream
+  linked `**Blocked by.**` blocker — a decision awaiting approval (ADR or decision entry, per `layout.yml`) or an upstream
   FEAT-ID that must complete first. Writes the row status, the detail block, and
   PLAN frontmatter, keeping intra-page feature links resolvable.
   `/block-feature FEAT-ID --unblock` clears the block and restores the status.

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/loop/data/roadmap.template.md

@@ -34,6 +34,7 @@ links to it.
 A `blocked` feature's detail section carries a `**Blocked by.**` block — blank
 line above it, one linked blocker per clause:
 
+<!-- layout:decisions-example -->
 **Blocked by.** [ADR-0007: event-schema versioning](../docs/adr/0007-event-schema-versioning.md) — awaiting approval; [FEAT-2026-0011](#feat-2026-0011) — scoring data must land first.
 
 Each blocker is a Markdown link: an ADR points at its `.md` file (kept under
@@ -41,6 +42,7 @@ Each blocker is a Markdown link: an ADR points at its `.md` file (kept under
 `../docs/adr/…`); a feature dependency points at the blocking
 feature's roadmap anchor (`#feat-yyyy-nnnn`). When every blocker clears, a human
 flips `blocked` → `active` (or `planned`) and removes the `**Blocked by.**` block.
+<!-- /layout:decisions-example -->
 
 ## Notes
 

{specfuse_loop-0.29.0 → specfuse_loop-0.30.0}/specfuse/loop/escalation.py

@@ -523,6 +523,71 @@ def annotate_escalation(
     return issue_number
 
 
+#: How many closed `needs-human` issues one sweep reads. Cleared issues drop
+#: the label, so the set stays small once a repository has been swept once.
+_CLOSED_SWEEP_LIMIT = 100
+
+
+def clear_closed_escalation_labels(
+    runner: Callable, repo: str, *, limit: int = _CLOSED_SWEEP_LIMIT
+) -> list:
+    """Remove the lane's escalation labels from closed issues (#3523).
+
+    An escalated issue that a person then fixed and closed kept
+    ``needs-human`` and its category label: it looked parked to anyone
+    filtering by label, and reopened, the bug lane would skip it. Only an
+    issue carrying this module's escalation marker (body or comment) is
+    touched -- the labels on it are the lane's own -- and only
+    ``needs-human`` plus ``CATEGORY_LABELS`` are removed. Best-effort like
+    every other label projection here: an unreadable listing or a failed edit
+    clears nothing and never raises. Returns the numbers cleared.
+    """
+    try:
+        result = runner(
+            [
+                "gh", "issue", "list",
+                "--repo", repo,
+                "--label", NEEDS_HUMAN_LABEL,
+                "--state", "closed",
+                "--limit", str(limit),
+                "--json", "number,body,comments,labels",
+            ],
+            check=False,
+        )
+    except Exception:  # noqa: BLE001 - a sweep failure must not stop the run
+        return []
+    if getattr(result, "returncode", 1) != 0 or not getattr(result, "stdout", None):
+        return []
+    try:
+        issues = json.loads(result.stdout)
+    except ValueError:
+        return []
+    marker_prefix = _CORRELATION_MARKER_TEMPLATE.split("{", 1)[0]
+    cleared = []
+    for issue in issues if isinstance(issues, list) else ():
+        if not isinstance(issue, dict) or "number" not in issue:
+            continue
+        texts = [issue.get("body") or ""] + [
+            comment.get("body") or ""
+            for comment in issue.get("comments") or []
+            if isinstance(comment, dict)
+        ]
+        if not any(marker_prefix in text for text in texts):
+            continue
+        names = {
+            label.get("name")
+            for label in issue.get("labels") or []
+            if isinstance(label, dict)
+        }
+        to_remove = sorted(names & (CATEGORY_LABELS | {NEEDS_HUMAN_LABEL}))
+        argv = ["gh", "issue", "edit", str(issue["number"]), "--repo", repo]
+        for label in to_remove:
+            argv += ["--remove-label", label]
+        if _try_run(runner, argv):
+            cleared.append(issue["number"])
+    return cleared
+
+
 def _try_run(runner: Callable, argv: list) -> bool:
     """Run *argv*, swallowing any failure. Returns whether it succeeded.