specfuse-loop 0.2.0__py3-none-any.whl

specfuse/loop/validate_event.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""Validate component-repo event log entries against the orchestrator's event schema.
+
+This is the component-repo copy of the orchestrator's scripts/validate-event.py.
+Per binding rules (rules/never-touch.md), schema files are NOT duplicated into
+component repos. Instead, this script resolves the schema root from the
+orchestrator at runtime.
+
+Schema-root resolution (first match wins):
+    1. SPECFUSE_SCHEMA_ROOT — absolute path to orchestrator/shared/schemas/
+    2. Relative sibling-repo fallback: this file at .specfuse/scripts/ →
+       <repo>/.specfuse/ → <repo> → <parent> → <parent>/orchestrator/shared/schemas/.
+       Works when the orchestrator and component repos sit as siblings under
+       the same parent directory (the standard local-dev layout).
+
+Supported invocation patterns (only two):
+
+    # Stdin — pipe a single event or a JSONL file:
+    echo '{"timestamp": "...", ...}' | python3 .specfuse/scripts/validate-event.py
+    cat events/FEAT-2026-0001.jsonl | python3 .specfuse/scripts/validate-event.py
+    python3 .specfuse/scripts/validate-event.py --stdin   # explicit alias
+
+    # File — pass a path to a .jsonl file:
+    python3 .specfuse/scripts/validate-event.py --file events/FEAT-2026-0001.jsonl
+
+Exit codes:
+    0 — every event validated successfully
+    1 — at least one event failed validation (details on stderr)
+    2 — setup error (missing dependency, schema not found, bad input, etc.)
+
+This script is the normative gate for appending to events/*.jsonl per
+rules/verify-before-report.md §3 and the pr-submission / verification /
+escalation component-agent skills.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+try:
+    from jsonschema import Draft202012Validator
+except ImportError:
+    sys.stderr.write(
+        "error: the 'jsonschema' package is required.\n"
+        "       install it with: pip install 'jsonschema>=4.0'\n"
+    )
+    sys.exit(2)
+
+
+def _resolve_schema_root() -> Path:
+    """Return the orchestrator shared/schemas/ directory.
+
+    Order:
+        1. $SPECFUSE_SCHEMA_ROOT (absolute path)
+        2. Sibling-repo fallback relative to this file's location:
+           .specfuse/scripts/validate-event.py
+             .parent  = .specfuse/scripts
+             .parent  = .specfuse
+             .parent  = <component-repo>
+             .parent  = <workspace parent>
+           Then / "orchestrator" / "shared" / "schemas".
+    """
+    env = os.environ.get("SPECFUSE_SCHEMA_ROOT")
+    if env:
+        return Path(env).expanduser().resolve()
+
+    return (
+        Path(__file__).resolve().parent.parent.parent.parent
+        / "orchestrator"
+        / "shared"
+        / "schemas"
+    )
+
+
+SCHEMA_ROOT = _resolve_schema_root()
+SCHEMA_PATH = SCHEMA_ROOT / "event.schema.json"
+PER_TYPE_SCHEMA_DIR = SCHEMA_ROOT / "events"
+
+
+def load_validator() -> Draft202012Validator:
+    if not SCHEMA_PATH.is_file():
+        sys.stderr.write(
+            f"error: schema not found at {SCHEMA_PATH}\n"
+            "       set SPECFUSE_SCHEMA_ROOT to the absolute path of\n"
+            "       orchestrator/shared/schemas/ (or place the orchestrator\n"
+            "       repo as a sibling of this component repo).\n"
+        )
+        sys.exit(2)
+    with SCHEMA_PATH.open("r", encoding="utf-8") as f:
+        schema = json.load(f)
+    Draft202012Validator.check_schema(schema)
+    return Draft202012Validator(schema)
+
+
+_PER_TYPE_CACHE: dict[str, Draft202012Validator | None] = {}
+
+
+def load_per_type_validator(event_type: str) -> Draft202012Validator | None:
+    """Return a per-type payload validator if one exists, else None.
+
+    Per-type schemas are additive: an event type without a schema file in
+    PER_TYPE_SCHEMA_DIR validates against the top-level envelope alone,
+    preserving the Phase 1 freeze contract for component-agent emissions
+    whose per-type schemas have not been authored.
+    """
+    if event_type in _PER_TYPE_CACHE:
+        return _PER_TYPE_CACHE[event_type]
+
+    schema_file = PER_TYPE_SCHEMA_DIR / f"{event_type}.schema.json"
+    if not schema_file.is_file():
+        _PER_TYPE_CACHE[event_type] = None
+        return None
+
+    try:
+        with schema_file.open("r", encoding="utf-8") as f:
+            schema = json.load(f)
+    except (OSError, json.JSONDecodeError) as exc:
+        sys.stderr.write(f"error: failed to read per-type schema {schema_file}: {exc}\n")
+        sys.exit(2)
+
+    try:
+        Draft202012Validator.check_schema(schema)
+    except Exception as exc:  # jsonschema raises SchemaError, keep generic
+        sys.stderr.write(f"error: invalid per-type schema {schema_file}: {exc}\n")
+        sys.exit(2)
+
+    validator = Draft202012Validator(schema)
+    _PER_TYPE_CACHE[event_type] = validator
+    return validator
+
+
+def format_error(source: str, line_number: int, path: str, message: str) -> str:
+    location = f"{source}:{line_number}" if line_number else source
+    prefix = f"{location}"
+    if path:
+        prefix += f" at {path}"
+    return f"{prefix}: {message}"
+
+
+def validate_line(
+    validator: Draft202012Validator,
+    source: str,
+    line_number: int,
+    raw: str,
+) -> list[str]:
+    try:
+        event = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return [format_error(source, line_number, "", f"invalid JSON — {exc.msg} (line {exc.lineno}, col {exc.colno})")]
+
+    errors: list[str] = []
+    for err in sorted(validator.iter_errors(event), key=lambda e: list(e.absolute_path)):
+        path = "/".join(str(p) for p in err.absolute_path) or "(root)"
+        errors.append(format_error(source, line_number, path, err.message))
+
+    # Per-type payload validation. Applied only when the top-level envelope
+    # is valid enough to name the event_type and the payload is a dict;
+    # otherwise the top-level errors above are the signal.
+    event_type = event.get("event_type") if isinstance(event, dict) else None
+    payload = event.get("payload") if isinstance(event, dict) else None
+    if isinstance(event_type, str) and isinstance(payload, dict):
+        per_type = load_per_type_validator(event_type)
+        if per_type is not None:
+            for err in sorted(per_type.iter_errors(payload), key=lambda e: list(e.absolute_path)):
+                sub_path = "/".join(str(p) for p in err.absolute_path) or "(root)"
+                path = f"payload/{sub_path}" if sub_path != "(root)" else "payload"
+                errors.append(format_error(source, line_number, path, err.message))
+
+    return errors
+
+
+def iter_lines_from_file(path: Path) -> list[tuple[int, str]]:
+    if not path.is_file():
+        sys.stderr.write(f"error: file not found: {path}\n")
+        sys.exit(2)
+    lines: list[tuple[int, str]] = []
+    with path.open("r", encoding="utf-8") as f:
+        for lineno, raw in enumerate(f, start=1):
+            stripped = raw.strip()
+            if stripped:
+                lines.append((lineno, stripped))
+    return lines
+
+
+def iter_lines_from_stdin() -> list[tuple[int, str]]:
+    data = sys.stdin.read()
+    if not data.strip():
+        sys.stderr.write("error: no input on stdin\n")
+        sys.exit(2)
+    lines: list[tuple[int, str]] = []
+    for lineno, raw in enumerate(data.splitlines(), start=1):
+        stripped = raw.strip()
+        if stripped:
+            lines.append((lineno, stripped))
+    return lines
+
+
+_UNSUPPORTED_HINT = (
+    "Supported invocation patterns:\n"
+    "  cat events/FEAT-XXXX-NNNN.jsonl | .specfuse/scripts/validate-event.py     # stdin\n"
+    "  .specfuse/scripts/validate-event.py --stdin                                 # stdin (explicit)\n"
+    "  .specfuse/scripts/validate-event.py --file events/FEAT-XXXX-NNNN.jsonl    # file\n"
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate events against the orchestrator's event schema.",
+        epilog=_UNSUPPORTED_HINT,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--file",
+        type=Path,
+        metavar="PATH",
+        help="Path to a .jsonl file of events to validate.",
+    )
+    parser.add_argument(
+        "--stdin",
+        action="store_true",
+        default=False,
+        help="Explicitly read events from stdin (same behaviour as omitting --file).",
+    )
+
+    # Reject unsupported positional arguments before parsing flags.
+    # argparse would otherwise accept them silently.
+    known, unknown = parser.parse_known_args()
+    if unknown:
+        sys.stderr.write(
+            f"error: unsupported argument(s): {' '.join(unknown)}\n\n"
+            + _UNSUPPORTED_HINT
+        )
+        return 2
+
+    args = known
+
+    if args.file is not None and args.stdin:
+        sys.stderr.write(
+            "error: --file and --stdin are mutually exclusive.\n\n"
+            + _UNSUPPORTED_HINT
+        )
+        return 2
+
+    validator = load_validator()
+
+    if args.file is not None:
+        source = str(args.file)
+        entries = iter_lines_from_file(args.file)
+    else:
+        # Both explicit --stdin and the no-flag default route here.
+        source = "<stdin>"
+        entries = iter_lines_from_stdin()
+
+    all_errors: list[str] = []
+    for lineno, raw in entries:
+        all_errors.extend(validate_line(validator, source, lineno, raw))
+
+    if all_errors:
+        for msg in all_errors:
+            sys.stderr.write(msg + "\n")
+        sys.stderr.write(
+            f"\n{len(all_errors)} validation error(s) across {len(entries)} event(s).\n"
+        )
+        return 1
+
+    sys.stdout.write(
+        f"ok: {len(entries)} event(s) validated against {SCHEMA_PATH.name}"
+        f" (with per-type payload schemas under {PER_TYPE_SCHEMA_DIR.name}/ where present)\n"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

specfuse_loop-0.2.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: specfuse-loop
+Version: 0.2.0
+Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
+Author: Specfuse contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/specfuse/loop
+Project-URL: Source, https://github.com/specfuse/loop
+Keywords: specfuse,agents,planning,ralph,gate-cycle
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: dev
+Requires-Dist: PyYAML>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Requires-Dist: coverage>=7.0; extra == "dev"
+Requires-Dist: jsonschema>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Specfuse Loop
+
+**For engineers using AI coding agents** — a local-first driver that structures features as verified, work-unit sequences so each agent session runs focused on one task instead of accumulating context drift.
+
+A small, local-first executor for the **Plan + Work Unit** pattern in a single
+repository. You plan a feature as a sequence of *gates*, each a batch of
+self-contained *work units* with explicit acceptance criteria and verification.
+The loop dispatches each work unit to a fresh agent session, verifies the result
+itself, commits one squashed commit per unit, and stops at each gate so you can
+reflect — with the next gate already drafted and waiting for your review.
+
+Specfuse Loop is one of three independently-adoptable projects under the Specfuse
+methodology suite:
+
+- **`specfuse/codegen`** — deterministic source code from OpenAPI / AsyncAPI /
+  Arazzo specifications.
+- **`specfuse/loop`** — *this project*. Single-repo, spec-optional, lightweight.
+  You author the task graph directly; no specification and no agent-coordination
+  overhead are required.
+- **`specfuse/orchestrator`** — multi-repo, spec-first, agent coordination across
+  many component repositories.
+
+Use any one without the others. The loop and the orchestrator share the same
+gate-cycle methodology (see [`docs/methodology.md`](docs/methodology.md)); the
+loop is the lightweight surface for work that lives in one repo and may have no
+formal specification.
+
+## Why it exists
+
+AI coding agents do well on narrow, well-scoped work and poorly on large, vague
+work. The loop's bet is that the leverage is in the *planning*: if you remove
+ambiguity up front — crisp work units with hard boundaries and machine-checkable
+verification — then execution can run with a fresh agent per unit, re-grounding
+from durable files each time rather than accumulating context drift. It is the
+[Ralph loop](docs/concepts/ralph-lineage.md) idea applied at work-unit granularity, with
+the planning rigor Ralph's bare task list lacks.
+
+## How it works (in one minute)
+
+- A **feature** lives in `.specfuse/features/FEAT-YYYY-NNNN-slug/`, with a
+  `PLAN.md` (the task graph: gate order, work-unit membership, dependencies),
+  one `GATE-NN.md` per gate, and one `WU-*.md` per work unit (frontmatter + the
+  prompt body a fresh session receives). The loop also handles *orchestrated*
+  features dispatched by the Specfuse Orchestrator, identified by
+  `INIT-YYYY-NNNN/FNN` IDs — the loop treats both namespaces identically; only
+  the ID root differs. Use `.specfuse/scripts/gh_features.py` to discover a
+  target repo's open `specfuse:feature` issues as feature candidates; use
+  `.specfuse/scripts/adopt_feature.py <repo> <issue-number>` (or the
+  interactive `/adopt-feature` skill) to scaffold a dispatchable feature
+  folder from a picked issue.
+- The **driver** (`.specfuse/scripts/loop.py`) walks the current gate's ready
+  work units, dispatches each as a fresh `claude -p` session, runs the unit's
+  verification itself as the exit oracle, and commits one squashed,
+  trailer-carrying commit per unit. A failed gate is retried with a fresh
+  session carrying the failure evidence, up to three attempts, then escalated.
+- Each gate ends with a **closing sequence** so reflection, a durable
+  cross-feature `LEARNINGS.md`, documentation, and *drafting the next gate* all
+  happen systematically. Non-terminal gates use a two-WU form
+  (`close-intermediate` + `plan-next`); the terminal gate uses a single `close`
+  WU. A legacy four-WU form (`retrospective → lessons → docs → plan-next`) is
+  accepted but emits a lint warning.
+- The gate is the **human boundary.** The driver runs unattended within a gate
+  and stops at it; you review the next gate's draft and arm it. (Under automatic
+  mode, safe gates can self-arm; the dangerous edges always pull you back in —
+  see the methodology doc.)
+
+## Quickstart
+
+In a target single-repo project:
+
+**Contributing to this repo?** Run `./scripts/install-hooks.sh` once after
+cloning to enable the pre-push hook (runs `scripts/smoke-test.sh` — same
+checks CI runs — before each `git push`). Bypass with `git push --no-verify`.
+
+The driver installs from PyPI and the skills from the Claude Code marketplace:
+
+```bash
+pip install specfuse-loop                       # the driver: `specfuse-loop` on PATH
+# in Claude Code: skills under the /specfuse: namespace
+#   /plugin marketplace add specfuse/specfuse
+#   /plugin install specfuse@specfuse
+
+# scaffold a target repo's .specfuse/ state (templates, rules, verification.yml)
+./init.sh /path/to/your-project                 # legacy installer (v1.0; removed in v1.1)
+
+cd /path/to/your-project
+$EDITOR .specfuse/verification.yml              # match the `code` gates to your stack
+# author your first feature folder under .specfuse/features/ from .specfuse/templates/
+specfuse-loop --dry-run                          # or: python .specfuse/scripts/loop.py --dry-run
+specfuse-loop
+```
+
+> **Distribution (FEAT-2026-0019).** Code ships via pip (`specfuse-loop`), the
+> `specfuse` umbrella CLI bridges pip ↔ plugin (`specfuse upgrade`), and Claude
+> assets ship via the [`specfuse/specfuse`](https://github.com/specfuse/specfuse)
+> marketplace. `init.sh` remains the scaffold bootstrap (laying down `.specfuse/`
+> state) until pip-native scaffolding lands; it prints a deprecation banner.
+
+> **One driver per working tree.** The driver holds an exclusive advisory lock on
+> `.specfuse/.loop.lock` for the duration of a run; a second driver targeting the
+> same checkout exits immediately with a clear error message. To run two features
+> in parallel, use separate `git worktree` checkouts — each gets its own lock.
+> `--dry-run` is exempt and may run alongside a live driver.
+
+This repository is also a **self-demonstrating reference installation**: its own
+`.specfuse/` contains a worked example feature
+(`features/FEAT-2026-0001-health-endpoint/`). From the repo root you can run:
+
+```bash
+python .specfuse/scripts/lint_plan.py .specfuse/features/FEAT-2026-0001-health-endpoint
+python .specfuse/scripts/loop.py --dry-run
+```
+
+## Layout
+
+```
+specfuse-loop/
+├── LICENSE  NOTICE  CONTRIBUTING.md  README.md  .gitignore
+├── init.sh                      scaffold .specfuse/ into a target repo
+├── docs/
+│   ├── getting-started.md       narrated first-feature + operator walkthrough
+│   ├── methodology.md           the gate-cycle contract (shared with the orchestrator)
+│   ├── skills.md                the skills catalog, ordered by lifecycle phase
+│   ├── concepts/                why it exists; orchestrator mapping
+│   │   ├── ralph-lineage.md     the Ralph / Gas Town lineage
+│   │   └── architecture-addendum-gates-and-iterative-planning.md
+│   └── dev/                     internal working notes (not user-facing)
+└── .specfuse/                   canonical scaffold + worked example
+    ├── README.md
+    ├── roadmap.template.md  verification.yml.example  LEARNINGS.md
+    ├── rules/result-contract.md
+    ├── skills/verification/SKILL.md
+    ├── scripts/{loop.py, lint_plan.py, gh_features.py, adopt_feature.py, gh_backend.py}
+    ├── templates/{PLAN,GATE,WU}.template.md
+    └── features/FEAT-2026-0001-health-endpoint/   (the worked example)
+```
+
+`init.sh` also ships the durable docs — `methodology.md`, `skills.md`, and
+`concepts/` — into a target's `.specfuse/docs/`, so an initialized repo is
+self-documenting without this checkout.
+
+## Status
+
+Early but exercised. The driver, linter, parsing, dependency ordering, draft/arm
+gating, the deterministic auto-close predicate, and verification wiring are all
+tested, and the loop dogfoods itself — its own `.specfuse/features/` holds 20+
+features taken through the full gate cycle, including multi-gate features whose
+forward-design model (each gate's `plan-next` drafts the next) has held across
+four consecutive gates.
+
+What works today: single-feature and orchestrator-dispatched features; adopting a
+GitHub `specfuse:feature` issue into a dispatchable folder; GitHub issue-label
+state transitions for adopted features; per-gate auto-close on clean runs with a
+full-ceremony fallback when a gate goes off-plan; and a single-driver working-tree
+lock so two drivers can't corrupt one checkout.
+
+Expect rough edges. The interfaces (WU contract, RESULT block, correlation-ID
+scheme, `verification.yml` shape) are stable; tooling around them is still
+hardening.
+
+## License
+
+Apache License 2.0. See [`LICENSE`](LICENSE).

specfuse_loop-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+specfuse/loop/__init__.py,sha256=frUlkSvjwLR3vbEefjM_F5v_xviBHWknIYzFR_3PzrI,164
+specfuse/loop/_miniyaml.py,sha256=r9T7WIfMnlyBEz7hmpR9RylvXR3JWPoOJ2b8Cxr_hnY,18876
+specfuse/loop/adopt_feature.py,sha256=5RBJh4clbqQqsZwW0f695-2O3FiEqC0m5ASo-HC0Lp0,6824
+specfuse/loop/gate_eval.py,sha256=MvN1N_ovmBiyb8wU2liZrccAo3S8bwVIAepGck3m9_s,17742
+specfuse/loop/gh_backend.py,sha256=VoqotYeXp8VoqQ26zpG8EpZF80nbPiuZeQPwd8g9AlQ,2938
+specfuse/loop/gh_features.py,sha256=J4qX8HjINNriIU1SDClRySK6dZuoByOJ2MVidf6x6sk,2946
+specfuse/loop/lint_plan.py,sha256=h-7zgbThcKXRSxE3vkFw8xcNv7mpRkeGptvKexYmZ8g,27120
+specfuse/loop/loop.py,sha256=iKjt2kdFbCcdiVSjDoAY62VX4kKnCWcV9ZH-zt8nsCc,157705
+specfuse/loop/validate_event.py,sha256=52j8nHeXPJfl7q7xvIPGgtjKAsg8-sdD3HFbXBEKp4M,9914
+specfuse_loop-0.2.0.dist-info/licenses/LICENSE,sha256=de-gfE0q-xTYImzwC3dj3S7BxVhanf6RmIGjo_7y3aw,11357
+specfuse_loop-0.2.0.dist-info/licenses/NOTICE,sha256=J_H84W_ngPiGIfdakJshaXWn0C24fjXFahUK0hHy_uw,232
+specfuse_loop-0.2.0.dist-info/METADATA,sha256=pQt2cF3lGPBnTF1vGxcdxzFYEZyd1N-DFxob1DWoZtk,9742
+specfuse_loop-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+specfuse_loop-0.2.0.dist-info/entry_points.txt,sha256=gXi5PRPgZAt9DQgNq4Hr4dwkiaM7EmRdpCuYaqgOMjk,103
+specfuse_loop-0.2.0.dist-info/top_level.txt,sha256=fYXn5BMet9jdLKtleDZBPli5yrZByhMqabq0q9cO1qk,9
+specfuse_loop-0.2.0.dist-info/RECORD,,

specfuse_loop-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

specfuse_loop-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+specfuse-lint = specfuse.loop.lint_plan:main
+specfuse-loop = specfuse.loop.loop:main