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

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

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

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

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

{specfuse_loop-0.28.2 → specfuse_loop-0.29.0}/specfuse/agent/diagnose_invoke.py

@@ -23,7 +23,7 @@ from __future__ import annotations
 
 from specfuse.agent.invoke import build_claude_argv
 from specfuse.monitor.diagnose_cli import AnalysisParseError, render_headless
-from specfuse.monitor.diagnosis import FIX_SCOPES
+from specfuse.monitor.diagnosis import FIX_SCOPES, SEVERITY_RUBRIC
 
 __all__ = ("AnalysisParseError", "build_invocation", "read_result")
 
@@ -69,7 +69,11 @@ def build_invocation(
         "partial evidence gets a low number.\n"
         f"- fix_scope: exactly one of {', '.join(FIX_SCOPES)} -- do not "
         "invent or default this value; if none plainly fits, say so in "
-        "candidate_fix and still pick the closest of the three.\n\n"
+        "candidate_fix and still pick the closest of the three.\n"
+        "- severity (optional): how serious the finding is, judged from its "
+        "evidence against this rubric; omit it if you cannot tell:\n"
+        + "".join(f"  - {line}\n" for line in SEVERITY_RUBRIC)
+        + "\n"
         "Do not post anything and do not run `gh issue comment` yourself; "
         "the caller renders and posts the diagnosis this session produces."
     )

{specfuse_loop-0.28.2 → specfuse_loop-0.29.0}/specfuse/agent/providers/findings_autofix.py

@@ -7,7 +7,8 @@ confidence threshold, `fix_scope` routing, fingerprint rate limit, and daily
 cap all stay in `specfuse.monitor.autofix`/`autofix_state`, read only
 through `run_autofix`.
 
-`advertise` returns one `kind="finding-autofix"` item per open snapshot
+`advertise` returns, most severe diagnosis first (stable within a severity),
+one `kind="finding-autofix"` item per open snapshot
 issue carrying `specfuse.monitor.issues.FINDING_LABEL` that already has a
 diagnosis comment -- the mirror of T10's filter, read the same way via
 `gh issue view N --json body,comments` and `specfuse.monitor.diagnosis.parse`.
@@ -63,6 +64,7 @@ from specfuse.monitor.issues import FINDING_LABEL
 
 _ITEM_ID_PREFIX = "finding-autofix-"
 _DEFAULT_MONITORING_CONFIG_PATH = ".specfuse/monitoring.yml"
+_SEVERITY_ORDER = ("critical", "high", "medium", "low")
 _FAILING_OUTCOMES = ("refused", "could_not_proceed")
 
 
@@ -91,6 +93,24 @@ def _has_diagnosis(comments: list) -> bool:
     return False
 
 
+def _latest_diagnosis(comments: list):
+    latest = None
+    for comment in comments or []:
+        body = comment.get("body", "") if isinstance(comment, dict) else ""
+        try:
+            diagnosis = parse(body)
+        except DiagnosisParseError:
+            continue
+        if diagnosis is not None:
+            latest = diagnosis
+    return latest
+
+
+def _severity_rank(diagnosis) -> int:
+    severity = diagnosis.severity if diagnosis is not None else None
+    return _SEVERITY_ORDER.index(severity) if severity in _SEVERITY_ORDER else len(_SEVERITY_ORDER)
+
+
 def _known_components(monitoring_config: Any) -> set:
     components = monitoring_config.get("components") if isinstance(monitoring_config, dict) else None
     if not isinstance(components, list):
@@ -171,6 +191,7 @@ class FindingsAutofixProvider:
         known_components = _known_components(monitoring_config)
 
         items = []
+        ranks = {}
         for issue in snapshot.issues:
             if FINDING_LABEL not in issue.labels:
                 continue
@@ -183,7 +204,8 @@ class FindingsAutofixProvider:
             if component is None or component not in known_components:
                 continue
 
-            if not _has_diagnosis(comments):
+            diagnosis = _latest_diagnosis(comments)
+            if diagnosis is None:
                 continue
 
             item_id = f"{_ITEM_ID_PREFIX}{issue.number}"
@@ -192,6 +214,7 @@ class FindingsAutofixProvider:
                 "component": component,
                 "monitoring_config": monitoring_config,
             }
+            ranks[item_id] = _severity_rank(diagnosis)
             items.append(
                 ActionItem(
                     item_id=item_id,
@@ -200,6 +223,7 @@ class FindingsAutofixProvider:
                     queue_key=None,
                 )
             )
+        items.sort(key=lambda item: ranks[item.item_id])
         return items
 
     def execute(self, item: ActionItem) -> ActionOutcome:

{specfuse_loop-0.28.2 → specfuse_loop-0.29.0}/specfuse/agent/providers/findings_diagnose.py

@@ -7,8 +7,9 @@
 `AgentSnapshot` cannot answer.
 
 `advertise` returns one `kind="finding-diagnose"` item per open snapshot
-issue carrying `specfuse.monitor.issues.FINDING_LABEL` that has no diagnosis
-comment yet. The snapshot's `IssueSummary` carries no body, so this
+issue carrying `specfuse.monitor.issues.FINDING_LABEL` that needs a diagnosis:
+none yet, a monitor reopen comment newer than its latest diagnosis, or the
+`rediagnose` label (#3487). The snapshot's `IssueSummary` carries no body, so this
 provider reads each candidate's body and comments itself with
 `gh issue view N --json body,comments` -- the same read
 `autofix_run._read_finding_issue` performs and the same softening of "the
@@ -25,8 +26,8 @@ The rendered comment body is `diagnosis.render`'s, unaltered -- this module
 holds no heading template and no marker string of its own. An unparseable
 analysis result posts nothing: `execute` escalates with the parse error's
 own message and never retries, defaults a field, or posts a partial body.
-This provider performs no git mutation and no label write of its own; a
-diagnosis is a comment.
+This provider performs no git mutation. Its only label write is the
+`severity:<value>` label of a diagnosis that carries a severity.
 """
 
 from __future__ import annotations
@@ -51,14 +52,16 @@ from specfuse.agent.run import (
     _default_runner,
 )
 from specfuse.agent.state import AgentSnapshot
+from specfuse.loop.agent_policy import SEVERITY_LABEL_PREFIX
 from specfuse.monitor.diagnosis import DiagnosisParseError, parse
-from specfuse.monitor.issues import FINDING_LABEL
+from specfuse.monitor.issues import FINDING_LABEL, REDIAGNOSE_LABEL, is_reopen_comment
 
 _ITEM_ID_PREFIX = "finding-diagnose-"
 _DEFAULT_MONITORING_CONFIG_PATH = ".specfuse/monitoring.yml"
 _DIAGNOSE_DIAL_AUTO = "auto"
 
 
+
 def _read_issue(runner: Callable, repo: str, issue_number: int) -> dict:
     result = runner(
         ["gh", "issue", "view", str(issue_number), "--repo", repo, "--json", "body,comments"],
@@ -73,15 +76,25 @@ def _read_issue(runner: Callable, repo: str, issue_number: int) -> dict:
     return parsed if isinstance(parsed, dict) else {}
 
 
-def _already_diagnosed(comments: list) -> bool:
-    for comment in comments or []:
+def _is_diagnosis(body: str) -> bool:
+    try:
+        return parse(body) is not None
+    except DiagnosisParseError:
+        return False
+
+
+def _needs_diagnosis(comments: list) -> bool:
+    """True when the finding has no diagnosis yet, or the monitor reopened it
+    after its latest diagnosis (#3487: a regression after a fix is diagnosed
+    again, once per reopen). `gh issue view` lists comments oldest first."""
+    last_diagnosis = last_reopen = -1
+    for index, comment in enumerate(comments or []):
         body = comment.get("body", "") if isinstance(comment, dict) else ""
-        try:
-            if parse(body) is not None:
-                return True
-        except DiagnosisParseError:
-            continue
-    return False
+        if _is_diagnosis(body):
+            last_diagnosis = index
+        elif is_reopen_comment(body):
+            last_reopen = index
+    return last_diagnosis < 0 or last_reopen > last_diagnosis
 
 
 def _unparseable_diagnosis_payload(number: int, error: str) -> EscalationPayload:
@@ -168,11 +181,15 @@ class FindingsDiagnoseProvider:
             if dial != _DIAGNOSE_DIAL_AUTO:
                 continue
 
-            if _already_diagnosed(comments):
+            relabelled = REDIAGNOSE_LABEL in issue.labels
+            if not relabelled and not _needs_diagnosis(comments):
                 continue
 
             item_id = f"{_ITEM_ID_PREFIX}{issue.number}"
-            self._rows[item_id] = {"number": issue.number, "title": issue.title, "body": body}
+            self._rows[item_id] = {
+                "number": issue.number, "title": issue.title, "body": body,
+                "relabelled": relabelled, "labels": tuple(issue.labels),
+            }
             items.append(
                 ActionItem(
                     item_id=item_id,
@@ -221,11 +238,59 @@ class FindingsDiagnoseProvider:
             ],
             check=False,
         )
+        self._label_severity(number, rendered, row.get("labels", ()))
+        if row.get("relabelled"):
+            # Consume the request so the next run does not diagnose again.
+            self._runner(
+                ["gh", "issue", "edit", str(number), "--repo", self._repo,
+                 "--remove-label", REDIAGNOSE_LABEL],
+                check=False,
+            )
         return ActionOutcome(
             status=STATUS_COMPLETED,
             detail=f"issue #{number} diagnosed",
             spend=spend,
         )
 
+    def _read_labels(self, number: int) -> set:
+        result = self._runner(
+            ["gh", "issue", "view", str(number), "--repo", self._repo, "--json", "labels"],
+            check=False,
+        )
+        if getattr(result, "returncode", 1) != 0 or not getattr(result, "stdout", None):
+            return set()
+        try:
+            parsed = json.loads(result.stdout)
+        except ValueError:
+            return set()
+        entries = parsed.get("labels") if isinstance(parsed, dict) else None
+        return {
+            e["name"] for e in entries or []
+            if isinstance(e, dict) and isinstance(e.get("name"), str)
+        }
+
+    def _label_severity(self, number: int, rendered: str, labels) -> None:
+        """Give the finding exactly one `severity:<value>` label, replacing any
+        previous one. No severity on the diagnosis, no label write."""
+        diagnosis = parse(rendered)
+        severity = diagnosis.severity if diagnosis is not None else None
+        if severity is None:
+            return
+        wanted = f"{SEVERITY_LABEL_PREFIX}{severity}"
+        self._runner(
+            ["gh", "label", "create", wanted, "--force", "--repo", self._repo],
+            check=False,
+        )
+        current = set(labels) | self._read_labels(number)
+        stale = [
+            label for label in sorted(current)
+            if label.startswith(SEVERITY_LABEL_PREFIX) and label != wanted
+        ]
+        argv = ["gh", "issue", "edit", str(number), "--repo", self._repo]
+        for label in stale:
+            argv += ["--remove-label", label]
+        argv += ["--add-label", wanted]
+        self._runner(argv, check=False)
+
     def reconcile(self, item: ActionItem, outcome: ActionOutcome) -> None:
         return None

specfuse_loop-0.29.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.29.0

specfuse_loop-0.29.0/specfuse/loop/data/docs/concepts/monitoring-runners.md

@@ -0,0 +1,199 @@
+# Where the monitoring cycle runs — the `runner` dial and its surfaces
+
+`.specfuse/monitoring.yml` gives every component a `runner` dial: `local`,
+`gh-actions`, or `in-cluster`. The dial says *where that component's
+diagnose/autofix cycle executes* — it is a routing decision, not a feature
+flag, and it does not gate any code path inside the cycle itself. This
+document covers the two surfaces FEAT-2026-0040 ships and states plainly
+what is still missing.
+
+What happens to a finding after it is filed — diagnosis, the autofix decision,
+the fix — and which processes must be scheduled for it is in
+[`monitoring-to-fix.md`](monitoring-to-fix.md).
+`specfuse monitor run` does not diagnose anything itself: when it files or
+updates findings for a component set to `diagnose: auto`, its summary prints one
+line saying those findings wait for `specfuse agent run` (specfuse-agent).
+
+## The two shipped surfaces
+
+**Local.** An operator, or a cron entry on a machine they control, runs
+`specfuse monitor run`. This is the recommended starting point — the
+schema's own `monitoring.yml.example` advises starting every component at
+`runner: local` before loosening any dial. Nothing extra to install — the
+`specfuse` suite already carries it (`pipx install specfuse`, which
+hard-depends on the `specfuse-loop` distribution this CLI ships in). The CLI
+reads `.specfuse/monitoring.yml` from the current working directory the same
+way on this surface as any other.
+
+**GitHub Actions.** A shipped, scheduled workflow template runs the same
+cycle in CI. It lives at
+`specfuse/loop/data/workflows/specfuse-monitor.yml` in the `specfuse-loop`
+distribution — this is a *template*, not a workflow this repository runs
+itself (this repository is a CLI tool with no deployable components and
+will never carry a real `monitoring.yml`; see `verification.yml`). To use
+it in a consumer project:
+
+1. Copy `specfuse-monitor.yml` into that project's own `.github/workflows/`.
+   You already have it if `specfuse` is installed — it ships inside the
+   `specfuse_loop` package data, so
+   `python -c "import specfuse.loop, pathlib; print(pathlib.Path(specfuse.loop.__file__).parent / 'data/workflows/specfuse-monitor.yml')"`
+   prints its path. It is also readable from this repository's
+   `specfuse/loop/data/workflows/`.
+2. Add the secrets it references — one per credential-bearing environment
+   variable named in that project's `.specfuse/monitoring.yml` (`api_key`,
+   `connection_string`, etc.), plus a token with permission to file issues
+   (`GITHUB_TOKEN` is sufficient for issues in the same repository) — under
+   the consumer repository's Settings → Secrets and variables → Actions.
+   Every value the template consumes is a `${{ secrets.* }}` reference; it
+   never embeds a literal credential.
+3. Dial the components that should run here to `runner: gh-actions` in that
+   project's `.specfuse/monitoring.yml`.
+
+The template declares both `on.schedule` (a cron expression) and
+`on.workflow_dispatch`, so it can be triggered by hand while debugging, not
+only on its schedule. It requests exactly `permissions: {issues: write,
+contents: read}` — least privilege for filing issues, nothing more — rather
+than inheriting the default write-all token.
+
+## The dial routes, and skips are reported, not silent
+
+`specfuse monitor run` takes a `--runner` flag naming which surface this
+invocation *is* (defaulting to `local`). It enumerates only the components
+whose `runner` matches that flag; every other component is named in the run
+summary along with the surface it belongs to, so a skipped component is
+visible, not silently unmonitored. A component whose `runner` value isn't
+one of `local` / `gh-actions` / `in-cluster` is a clear error naming the bad
+value and the supported set — a typo'd dial must fail loudly, not run
+nothing.
+
+## `in-cluster` is out of scope here
+
+`in-cluster` is a valid schema value today, but no runner surface
+implements it in this feature. A component dialed to `runner: in-cluster`
+is reported by `specfuse monitor run` as unhandled by design — naming
+**FEAT-2026-0043**, which owns that surface — and is neither dropped
+silently nor treated as an error. Do not dial a component to `in-cluster`
+expecting it to be monitored until that feature ships.
+
+## The harvest window
+
+Each run reads only what is new since the previous one. The window for an
+environment starts at its watermark (the time the previous non-dry run
+started, kept in `.specfuse/monitor-watermarks/<env>.json`) and ends at this
+run's start. With no readable watermark (a first run, a fresh CI runner, a new
+operator) it starts 24 hours back instead, and the run summary says so.
+
+The window applies to the checks that read event history: `error-logs` and
+`http-5xx` filter on `ingestion_time()`, so a row stamped just before the
+previous run but ingested after it is read by the next run rather than lost
+between the two. Three check types are deliberately not bounded by it:
+
+- `heartbeat` needs the most recent heartbeat however old it is;
+- `http-status-regression` compares the windows around each deployment and
+  carries its own fixed lookback;
+- `invariant` runs the operator's query as written. A query that reads event
+  history should bound itself (for example `| where TimeGenerated > ago(1h)`);
+  otherwise every matching row in retention is a finding, deduplicated only by
+  `fingerprint_by`.
+
+A run in which any check errored leaves the watermark where it was, so the
+next run retries the same window.
+
+The watermark directory is local runtime state, not something to commit.
+`specfuse init` adds `.specfuse/monitor-watermarks/` to a new project's
+`.gitignore`, and `specfuse upgrade` adds it to a project initialised earlier
+(it appends any snippet line the file lacks, leaving your own lines alone). On a CI
+runner the directory starts empty every run — the shipped workflow template
+does not cache it — so each run there reads the 24-hour fallback window.
+
+## What `--dry-run` does and does not gate
+
+`--dry-run` performs the read-only `fetch_failures()` calls against real
+telemetry/broker transports — it is not an offline mode. It gates only the
+writes: the watermark file and every `gh` invocation. If you point a dry
+run at a production telemetry backend, it will consume that backend's read
+quota exactly as a real run would.
+
+## What a finding is, and how its issue is kept
+
+Every finding is one GitHub issue per fingerprint. The fingerprint is the
+`specfuse:finding` marker in the issue body, and it is the only thing that
+identifies a finding: nothing a finding *carries* (its title, its context, the
+time it was seen, a dead-lettered message's id) enters it.
+
+### A recurrence reopens; it never refiles, and nothing is ever closed
+
+On each run, a fingerprint is matched against issues in three states:
+
+- **Open** — the issue is updated, as before.
+- **Closed within the last 90 days** — the issue is **reopened** with exactly one
+  comment carrying the new occurrence count and the first and last time it was
+  seen, in UTC. No second issue is filed, so the earlier diagnosis and any
+  "reopen if…" note stay attached to the finding.
+- **Absent, or closed longer ago than 90 days** — a new issue is filed. After 90
+  quiet days that is the honest reading, and the bound keeps the listing under
+  GitHub's 100-row limit.
+
+The monitor **reopens, never closes.** Closing on silence would erase the evidence
+of an intermittent fault, so closing stays a human decision, and no code in
+`specfuse/monitor` issues a close. A finding-meta marker the monitor cannot fully
+understand (a hand-edited or truncated one) reads as absent rather than failing
+the run.
+
+### A finding that goes quiet is annotated, once
+
+An open finding whose fingerprint has not been seen for **7 days** gets one
+comment naming it a candidate for close, and a marker in its body so the comment
+is not repeated. The monitor only does this for a component every one of whose
+checks ran without error in that cycle — a broken check never makes a finding
+look quiet — and it still closes nothing. If the fingerprint fires again, the
+issue's body is rewritten without the marker, so a later quiet period is
+annotated again. The pass reuses the cycle's own issue listing; `--dry-run`
+prints the issues it would annotate.
+
+### `dlq`: closing an issue means "acknowledged"
+
+A dead-lettered message stays in the queue until someone resubmits or purges it,
+so it is seen on every run. The `dlq` finding records the message ids it has seen.
+A closed `dlq` issue whose recorded ids cover every message currently in the queue
+**stays closed**, with no write at all — closing it means "acknowledged, replay
+pending". A message id the issue has not recorded **reopens** it, with a comment
+naming that message. Messages are only ever peeked; the monitor never receives,
+completes or abandons one.
+
+### `heartbeat`: a schedule that has not emitted yet is not silent
+
+A target whose latest expected firing precedes the component's earliest observed
+heartbeat is *pending its first firing*, and produces no `silent-schedule`
+finding. A target that has emitted before and then missed a firing still does, and
+a component with no heartbeat at all files nothing.
+
+### What a finding contains
+
+The title reads `<component>: <failure class> in <where>`, with no fingerprint.
+Each issue carries the labels `component:<name>` and `check:<type>` (created on
+first use). Every body states the occurrence count, when it was first seen (the earliest
+occurrence the run's rows show; for `dlq`, the message's enqueued time) and when
+the issue was last updated (UTC), what was seen in this run (count, first, last, and the instances), and the
+**Observed** line. Per check, the sections after **Observed** are:
+
+| check | sections |
+| --- | --- |
+| `error-logs` | Where (top in-app stack frame), Request (route and result code), Logger (category and message template), Likely client abort, Samples, Reproduce |
+| `http-5xx` | Exception (type, message), Where, Dependency (target, type, result code, duration), Duration, Samples, Reproduce |
+| `dlq` | Message (id, sequence number, subject, enqueued time, delivery count), Dead-letter reason, or the Exception message and top stack frames when the reason is blank, Body shape (the top-level keys, never the values), Peek it |
+| `heartbeat` | Schedule (cron, dialect, timezone, expected firing), Last run (the function's last execution and result), Host last seen, a Host silent line when the component sent no request telemetry across the expected firing, and Earliest heartbeat (the component's first heartbeat, which the grace rule measures from) |
+| `queue-stalled` | Queue (oldest active message age, depth, `stall_after`), Where |
+
+A section with nothing to say is left out rather than printed empty. A
+`queue-stalled` finding cannot show when the subscription last completed a
+message: Service Bus runtime properties carry no completion time (their
+`accessed_at_utc` changes on sends as well as receives, so it would mislead),
+and reading one from the messages themselves would mean receiving them, which
+the check never does.
+
+Each check still issues exactly one query. Every correlation (an exception to its
+request, a request to its dependency, a schedule to its host's liveness) is a join
+inside that query. The **Reproduce** and **Peek it** sections are text for a
+human to run, built from configuration and sample ids, and the monitor never runs
+them. Every section is redacted before it leaves the machine.