specfuse-loop 0.6.0__tar.gz → 0.7.0__tar.gz

{specfuse_loop-0.6.0/specfuse_loop.egg-info → specfuse_loop-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.6.0
+Version: 0.7.0
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0
@@ -19,6 +19,10 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
+Provides-Extra: azure
+Requires-Dist: azure-identity>=1.15; extra == "azure"
+Requires-Dist: azure-servicebus>=7.11; extra == "azure"
+Requires-Dist: azure-monitor-query>=1.2; extra == "azure"
 Provides-Extra: dev
 Requires-Dist: PyYAML>=6.0; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"

{specfuse_loop-0.6.0 → specfuse_loop-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.6.0"
+version = "0.7.0"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -33,6 +33,15 @@ dependencies = []
 # _miniyaml compare its output against yaml.safe_load on every real file.
 # ruff/bandit/coverage are for the reference implementation's own gates.
 [project.optional-dependencies]
+# The Azure provider SDKs. Kept OUT of the runtime dependencies on purpose: the
+# package imports them lazily inside the transport factories, so `specfuse-loop`
+# installs with zero runtime dependencies and the harvester's core stays
+# provider-agnostic. Only an operator actually harvesting from Azure needs these.
+azure = [
+  "azure-identity>=1.15",
+  "azure-servicebus>=7.11",
+  "azure-monitor-query>=1.2",
+]
 dev = [
   "PyYAML>=6.0",
   "ruff>=0.6",
@@ -64,6 +73,7 @@ select = ["E4", "E7", "E9", "F", "PLW1510", "B", "BLE001", "S110", "TRY004"]
 specfuse-loop = "specfuse.loop.loop:main"
 specfuse-lint = "specfuse.loop.lint_plan:main"
 specfuse-monitor-lint = "specfuse.loop.lint_monitoring:main"
+specfuse-monitor = "specfuse.monitor.cli:main"
 specfuse-stats = "specfuse.loop.events_stats:main"
 
 [tool.setuptools.packages.find]

specfuse_loop-0.7.0/specfuse/loop/closing_requirements.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""Closing-ceremony requirement registry (FEAT-2026-0054/T01).
+
+One machine-readable home for every closing-artifact requirement that the
+post-squash guards in ``specfuse/loop/loop.py`` enforce for ``close``,
+``close-intermediate``, and ``plan-next`` work units. The guards import the
+constants and helpers below instead of spelling headings, filenames, and
+verdict values inline, so a later lint mode and skeleton writer can read
+``CLOSING_REQUIREMENTS`` and stay in lockstep with what the guards actually
+check — durable rule FEAT-2026-0070/G1-CLOSE-INTERMEDIATE.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+# --------------------------------------------------------------------------- #
+# Shared literal values — the single spelling every guard body imports        #
+# --------------------------------------------------------------------------- #
+
+VERDICT_VALUES = frozenset({"met", "met_locally", "partially_met", "not_met"})
+
+RETROSPECTIVE_FILENAME = "RETROSPECTIVE.md"
+LEARNINGS_PATH = ".specfuse/LEARNINGS.md"
+ROADMAP_PATH = ".specfuse/roadmap.md"
+DOCS_PREFIX = "docs/"
+NOTHING_GENERALIZES_PHRASE = "nothing generalizes"
+
+COST_ANALYSIS_HEADING = "Cost analysis"
+COST_ANALYSIS_HEADING_RE = re.compile(
+    r"^##+ " + re.escape(COST_ANALYSIS_HEADING), re.MULTILINE | re.IGNORECASE,
+)
+
+FAILURE_CLASS_HEADING = "Failure-class breakdown"
+FAILURE_CLASS_HEADING_LEVEL = 3
+FAILURE_CLASS_HEADING_MARKDOWN = "#" * FAILURE_CLASS_HEADING_LEVEL + " " + FAILURE_CLASS_HEADING
+FAILURE_CLASS_HEADING_RE = re.compile(
+    rf"^#{{{FAILURE_CLASS_HEADING_LEVEL}}} {re.escape(FAILURE_CLASS_HEADING)}\b",
+    re.MULTILINE,
+)
+NO_FAILURES_SENTINEL = (
+    f"{FAILURE_CLASS_HEADING_MARKDOWN}\n\n(no non-passing attempts in scope)\n"
+)
+
+GATE_SECTION_HEADING_LEVELS = "1,3"
+
+
+def gate_section_heading_re(gate_n: int) -> re.Pattern:
+    """Regex matching the `## Gate N` / `### Gate N` retrospective section."""
+    return re.compile(
+        rf"^#{{{GATE_SECTION_HEADING_LEVELS}}} Gate {gate_n}\b", re.MULTILINE,
+    )
+
+
+GATE_REVIEW_FILENAME_TEMPLATE = "GATE-{next_gate:02d}-REVIEW.md"
+
+
+def gate_review_filename(next_gate: int) -> str:
+    """Filename of the review doc a plan-next WU must draft for the next gate."""
+    return GATE_REVIEW_FILENAME_TEMPLATE.format(next_gate=next_gate)
+
+
+DEFERRAL_HEADING_TEXT = "What the loop did NOT verify"
+DEFERRAL_HEADING_RE = re.compile(rf"(?m)^#{{1,3}}\s*{re.escape(DEFERRAL_HEADING_TEXT)}.*$")
+
+AUTOCLOSE_DEBT_MARKER_RE = re.compile(r"<!--\s*specfuse:autoclose-debt\s+gate=(\d+)")
+
+
+# --------------------------------------------------------------------------- #
+# Requirement records                                                         #
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class Requirement:
+    """One closing-artifact requirement, as data.
+
+    ``applies_when`` names the condition under which the requirement fires:
+    ``always``, ``verdict_met``, ``failures_present``, or
+    ``autoclose_debt_marker``. ``phase`` is ``pre-squash`` (checked by
+    ``assert_closing_deliverables`` right after the WU's own squash) or
+    ``post-pass`` (checked by ``verify_post_pass_invariants`` after the
+    gate-boundary state flips run).
+    """
+
+    id: str
+    wu_type: str
+    phase: str
+    description: str
+    enforced_by: str
+    applies_when: str = "always"
+    file: Optional[str] = None
+    file_derivation: Optional[str] = None
+    heading: Optional[str] = None
+    heading_level: Optional[int] = None
+    frontmatter_field: Optional[str] = None
+    allowed_values: Optional[frozenset] = field(default=None)
+
+
+CLOSING_REQUIREMENTS: dict[str, list[Requirement]] = {
+    "close": [
+        Requirement(
+            id="close-a", wu_type="close", phase="pre-squash",
+            description="RETROSPECTIVE.md exists and is non-empty in the feature dir",
+            file=RETROSPECTIVE_FILENAME,
+            enforced_by="assert_retrospective_exists",
+        ),
+        Requirement(
+            id="close-b", wu_type="close", phase="pre-squash",
+            description=(
+                "LEARNINGS.md gains >=1 line in the squash, or RETROSPECTIVE.md "
+                f"says '{NOTHING_GENERALIZES_PHRASE}'"
+            ),
+            file=LEARNINGS_PATH,
+            enforced_by="assert_learnings_appended_or_noop",
+        ),
+        Requirement(
+            id="close-c", wu_type="close", phase="pre-squash",
+            description=(
+                f"A documentation deliverable ({DOCS_PREFIX}*, {ROADMAP_PATH}, "
+                f"{LEARNINGS_PATH}, or a {RETROSPECTIVE_FILENAME}) appears in "
+                "the squash diff"
+            ),
+            enforced_by="assert_doc_or_roadmap_diff",
+        ),
+        Requirement(
+            id="close-d", wu_type="close", phase="pre-squash",
+            description="verdict frontmatter field is present and in VERDICT_VALUES",
+            frontmatter_field="verdict", allowed_values=VERDICT_VALUES,
+            enforced_by="assert_verdict_well_formed",
+        ),
+        Requirement(
+            id="close-e", wu_type="close", phase="pre-squash",
+            description=f"RETROSPECTIVE.md has a '{COST_ANALYSIS_HEADING}' heading",
+            file=RETROSPECTIVE_FILENAME, heading=COST_ANALYSIS_HEADING,
+            applies_when="verdict_met",
+            enforced_by="assert_cost_analysis_section_when_met",
+        ),
+        Requirement(
+            id="close-f", wu_type="close", phase="pre-squash",
+            description=f"RETROSPECTIVE.md has a '{FAILURE_CLASS_HEADING}' heading",
+            file=RETROSPECTIVE_FILENAME, heading=FAILURE_CLASS_HEADING,
+            heading_level=FAILURE_CLASS_HEADING_LEVEL,
+            applies_when="failures_present",
+            enforced_by="assert_failure_class_breakdown_when_failures_present",
+        ),
+        Requirement(
+            id="close-g", wu_type="close", phase="post-pass",
+            description=(
+                "Predecessor auto-close debt markers are named in the terminal "
+                f"close's '{DEFERRAL_HEADING_TEXT}' section"
+            ),
+            file=RETROSPECTIVE_FILENAME,
+            applies_when="autoclose_debt_marker",
+            enforced_by="assert_autoclose_debt_reconciled",
+        ),
+        Requirement(
+            id="close-h", wu_type="close", phase="post-pass",
+            description=(
+                "Terminal gate status, roadmap row, and roadmap-archive anchor "
+                "flip when verdict=met"
+            ),
+            applies_when="verdict_met",
+            enforced_by="assert_terminal_flips_fired",
+        ),
+    ],
+    "close-intermediate": [
+        Requirement(
+            id="close-intermediate-a", wu_type="close-intermediate", phase="pre-squash",
+            description="RETROSPECTIVE.md has a 'Gate N' heading for this gate",
+            file=RETROSPECTIVE_FILENAME, heading="Gate {gate_n}",
+            enforced_by="assert_retrospective_gate_section",
+        ),
+        Requirement(
+            id="close-intermediate-b", wu_type="close-intermediate", phase="pre-squash",
+            description=(
+                "LEARNINGS.md gains >=1 line in the squash, or RETROSPECTIVE.md "
+                f"says '{NOTHING_GENERALIZES_PHRASE}'"
+            ),
+            file=LEARNINGS_PATH,
+            enforced_by="assert_learnings_appended_or_noop",
+        ),
+        Requirement(
+            id="close-intermediate-c", wu_type="close-intermediate", phase="pre-squash",
+            description=(
+                f"A documentation deliverable ({DOCS_PREFIX}*, {ROADMAP_PATH}, "
+                f"{LEARNINGS_PATH}, or a {RETROSPECTIVE_FILENAME}) appears in "
+                "the squash diff"
+            ),
+            enforced_by="assert_doc_or_roadmap_diff",
+        ),
+        Requirement(
+            id="close-intermediate-d", wu_type="close-intermediate", phase="pre-squash",
+            description=f"RETROSPECTIVE.md has a '{FAILURE_CLASS_HEADING}' heading",
+            file=RETROSPECTIVE_FILENAME, heading=FAILURE_CLASS_HEADING,
+            heading_level=FAILURE_CLASS_HEADING_LEVEL,
+            applies_when="failures_present",
+            enforced_by="assert_failure_class_breakdown_when_failures_present",
+        ),
+    ],
+    "plan-next": [
+        Requirement(
+            id="plan-next-a", wu_type="plan-next", phase="pre-squash",
+            description="GATE-(N+1)-REVIEW.md exists and is non-empty, or no next gate",
+            file_derivation=GATE_REVIEW_FILENAME_TEMPLATE,
+            enforced_by="assert_gate_review_exists",
+        ),
+        Requirement(
+            id="plan-next-b", wu_type="plan-next", phase="pre-squash",
+            description="Next gate has >=1 drafted WU in PLAN.md, or PLAN.md/roadmap is terminal",
+            enforced_by="assert_next_gate_drafted_or_terminal",
+        ),
+    ],
+}
+
+
+def all_requirements() -> list[Requirement]:
+    """Flatten CLOSING_REQUIREMENTS into a single list, registry order preserved."""
+    out: list[Requirement] = []
+    for reqs in CLOSING_REQUIREMENTS.values():
+        out.extend(reqs)
+    return out
+
+
+def requirements_for(wu_type: str) -> list[Requirement]:
+    return CLOSING_REQUIREMENTS.get(wu_type, [])

specfuse_loop-0.7.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.7.0

{specfuse_loop-0.6.0 → specfuse_loop-0.7.0}/specfuse/loop/data/monitoring.yml.example

@@ -147,14 +147,19 @@ components:
 
       # One heartbeat check, many targets — one per schedule, so a single
       # silent timer among several is still individually visible instead of
-      # being averaged away by a single host-wide heartbeat.
+      # being averaged away by a single host-wide heartbeat. `dialect` is
+      # required whenever `cron` is present — declared, never inferred, so
+      # a heartbeat check knows how many fields the expression carries
+      # without guessing. Both targets here are standard 5-field cron.
       - type: heartbeat
         targets:
           - name: nightly-reconciliation
             cron: "0 2 * * *"
+            dialect: standard-5
             timezone: Etc/UTC
           - name: hourly-cache-warm
             cron: "0 * * * *"
+            dialect: standard-5
             timezone: Etc/UTC
 
       # queue-stalled: catches a consumer that has stopped consuming — no

specfuse_loop-0.7.0/specfuse/loop/data/rules/close-discipline.md

@@ -0,0 +1,119 @@
+<!--
+Copyright 2026 Specfuse Contributors
+Licensed under the Apache License, Version 2.0. See LICENSE.
+-->
+
+# Rule: close discipline
+
+Three obligations for `close` and `close-intermediate` WUs, binding at close
+time. Sibling of [`planning-discipline.md`](planning-discipline.md) (plan/arm
+time) and of the per-WU closing obligations in
+[`result-contract.md`](result-contract.md). Provenance: FEAT-2026-0049
+(the specfuse-generator dogfood), where three gates auto-closed at
+`attempts: 0` and the one close forced to run caught two false-`done` WUs and
+an unsatisfiable predicate — 48% of the feature's spend landed after the
+terminal gate had already "auto-closed". A close that only writes prose
+verifies nothing.
+
+A close whose acceptance criteria include ANY obligation below is
+**load-bearing**: the plan author sets `auto_close_disabled: true` in that
+WU's frontmatter so the auto-close predicate cannot optimize it away (#189).
+
+## 1. Oracles re-run fresh
+
+The close re-runs every oracle the feature's acceptance criteria name — the
+full test command(s), plus any compile/execution gates — fresh, in this
+session, exit codes read directly. Never inherit a producing WU's
+self-report: `done` is a claim, the re-run is the verification. When the
+feature's criteria assert on generated artifacts, regenerate into a clean
+output directory before asserting — stale output satisfies any assertion.
+
+> **Provenance.** A WU reported `done` while its source was untouched and its
+> oracle never ran; the driver-side produces-vs-diff guard now refuses that
+> pass (specfuse-loop >= 0.3.21), but only the close's own fresh re-run
+> catches the composite: all WUs individually green while the feature-level
+> oracle fails.
+
+## 2. Hedged-verdict follow-up record
+
+On `met_locally`, the close must produce a named record — in the gate review
+or `RETROSPECTIVE.md` — with one entry per unmet criterion:
+
+- the criterion, verbatim;
+- why it is unverifiable in this environment;
+- the exact re-run condition that would upgrade the verdict to `met`.
+
+The driver (>= 0.3.21) already guarantees the surfaces stay un-flipped on a
+hedged verdict (gate `awaiting_review`, roadmap `active`, PLAN `active`);
+this record is the other half: without it, `met_locally` is a dead end —
+no artifact says what would make it `met`, and the honest hedged verdict
+degrades into a polite synonym for "unknown".
+
+## 3. Consumer-visible contract changes enumerated, human-acknowledged
+
+The close enumerates every consumer-visible addition, removal, or rename the
+feature makes across ALL its producing WUs — API surface, generated models,
+published schemas, CLI flags, whatever contract consumers depend on — and
+blocks on explicit human acknowledgment of the list. A feature with no such
+changes writes exactly: `n/a — no consumer-visible contract change` (do not
+fabricate an empty enumeration; the n/a line is the reviewed claim).
+
+A close carrying this obligation is always load-bearing
+(`auto_close_disabled: true`).
+
+> **Provenance.** A breaking removal from a generated model survived four
+> gates unreviewed because no close surface owned the breaking-change list.
+> A silent breaking change is the most expensive false-done, and it is not
+> language-specific — any generated or published contract has this surface.
+
+## 4. What the driver checks — check it before you report, not after you fail
+
+Sections 1–3 are obligations you reason about. The driver additionally
+refuses a closing WU that produces correct content in the wrong shape, and it
+refuses it *after* the WU has run — so a mismatch used to cost a full
+re-dispatch, not a re-arm.
+
+That used to mean memorizing a table of literal guard strings. It no longer
+does. Two mechanical surfaces replace the table:
+
+- **The skeleton is pre-created at dispatch.** Every `close` /
+  `close-intermediate` / `plan-next` WU starts its session with the
+  guard-required files and headings already scaffolded in place
+  (`RETROSPECTIVE.md`, the `## Gate <N>` / `## Cost analysis` /
+  `### Failure-class breakdown` sections, the `GATE-{N+1}-REVIEW.md`
+  filename) — see `precreate_dispatch_skeleton` in `specfuse/loop/loop.py`.
+  You fill the skeleton in; you do not need to remember its shape from
+  scratch.
+- **`specfuse-lint --closing` is the mandatory pre-report check.** Run it
+  before emitting your `RESULT` block. It reads the same registry the driver
+  itself checks and reports pass/fail per requirement in-session, so a format
+  mismatch is caught while you can still fix it, not after the driver refuses.
+
+The registry of record — every guard, what it requires, which WU types it
+applies to — lives in `specfuse/loop/closing_requirements.py`. That module
+and `specfuse/loop/lint_closing.py` (the `--closing` implementation) are the
+one place these requirements are enumerated; this rule does not duplicate
+them.
+
+**Migration posture.** Already-drafted features need no conversion — the
+skeleton applies at dispatch time for any WU dispatched from here forward,
+regardless of when its body was authored. Older WU bodies that restate guard
+strings inline (pre-dating this section) are inert, not wrong: the driver
+never read that prose, only the actual artifacts. Removing such prose from an
+old WU body is optional cleanup, not required migration work.
+
+> **Provenance (issue #265, FEAT-2026-0054).** Guard requirements are
+> enforced in `specfuse/loop/loop.py`'s `assert_*` functions. They were
+> briefly literal-string-documented in this rule (28% of closing-WU spend
+> going to driver-refused attempts, three undocumented guards accounting for
+> 45% of that waste) — but a second copy of the requirements drifts, so
+> FEAT-2026-0054 replaced the copy with the two mechanical surfaces above and
+> made `closing_requirements.py` the single registry both the driver and the
+> lint read.
+
+## Split with project-local rules
+
+These are the generic obligations. The concrete grounding — which command is
+the oracle, which surface is "the API", project-specific regeneration
+hazards — is per-project and belongs in that project's
+`.specfuse/rules-local/` (never touched by upgrade), referencing this rule.

{specfuse_loop-0.6.0 → specfuse_loop-0.7.0}/specfuse/loop/data/templates/WU.template.md

@@ -100,11 +100,8 @@ defect gates later.
 **Close obligations** (REQUIRED only for `close` / `close-intermediate` WUs; omit
 otherwise — see `.specfuse/rules/close-discipline.md`).
 
-> **Read `close-discipline.md` §4 before drafting a closing WU.** It lists the
-> exact strings the driver checks — heading levels, the `GATE-{N+1}-REVIEW.md`
-> filename, the `verdict:` frontmatter field. These are matched literally and
-> checked *after* the WU runs, so a mismatch costs a full re-dispatch rather than
-> a re-arm. 28% of all closing-WU spend has gone to exactly that (#265).
+> Run `specfuse-lint --closing` and confirm it exits 0 before this WU reports
+> `complete` — see `.specfuse/rules/close-discipline.md` §4.
 
 The close's acceptance criteria must cover:
 

specfuse_loop-0.7.0/specfuse/loop/data/workflows/specfuse-monitor.yml

@@ -0,0 +1,42 @@
+# specfuse-monitor.yml — GitHub Actions template for the "gh-actions" runner
+# surface (FEAT-2026-0040/T11).
+#
+# This file is a TEMPLATE. It ships under specfuse/loop/data/ and is not
+# installed into this repository's own .github/workflows/ — this repo is a
+# CLI tool with no deployable components and no monitoring.yml. Copy this
+# file into a CONSUMER project's .github/workflows/ once that project has
+# real components dialed to `runner: gh-actions` in its .specfuse/monitoring.yml.
+#
+# SECURITY POSTURE: every credential-bearing value below is a
+# ${{ secrets.* }} reference, never a literal secret. Add the named secrets
+# in the consumer repository's Settings -> Secrets and variables -> Actions
+# before enabling the schedule. See docs/concepts/monitoring-runners.md.
+name: specfuse-monitor
+
+on:
+  schedule:
+    - cron: "0 * * * *"
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  monitor:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install specfuse-loop
+        run: pip install specfuse-loop
+      - name: Run monitoring cycle
+        run: specfuse-monitor run --runner gh-actions
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ACME_TELEMETRY_PROD_API_KEY: ${{ secrets.ACME_TELEMETRY_PROD_API_KEY }}
+          ACME_BROKER_PROD_CONNECTION_STRING: ${{ secrets.ACME_BROKER_PROD_CONNECTION_STRING }}

{specfuse_loop-0.6.0 → specfuse_loop-0.7.0}/specfuse/loop/labels.py

@@ -17,6 +17,7 @@ from pathlib import Path
 from typing import Callable, Optional
 
 from specfuse.loop import escalation, gh_features
+from specfuse.monitor import issues
 
 
 @dataclass(frozen=True)
@@ -70,6 +71,18 @@ LABEL_REGISTRY: tuple[LabelSpec, ...] = (
         description="A pull request is green and waiting on a merge decision",
         consumer="escalation.py",
     ),
+    # The harvester's findings carry their own label rather than reusing
+    # `needs-human`: they are failure artifacts, not operator escalations, and a
+    # distinct label lets `gh issue list` scope to exactly that lifecycle. It was
+    # missing here until #300 — `gh issue create` rejects an unknown label, so the
+    # harvester could not file a single finding on any repository that had not had
+    # this label made by hand.
+    LabelSpec(
+        name=issues.FINDING_LABEL,
+        colour="b60205",
+        description="A failure artifact reported by specfuse-monitor",
+        consumer="monitor/issues.py",
+    ),
 )