loop-engineering-harness 1.0.0

package/template/.claude/hooks/version-gate.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""version-gate.py — PreToolUse hook on Bash (the Version Controller's commit gate).
+
+Runs beside commit-gate.py. Where commit-gate enforces *review*, this enforces
+*versioning*: a feature does not commit until all three responsibilities are
+satisfied for it. Policy in an exit code, not a checklist someone remembers.
+
+Blocks `git commit` / `gh pr create` when, for the active feature:
+  V1 (dependency)   a MAJOR dependency bump is unacknowledged
+  V2 (code)         no semver bump / CHANGELOG entry recorded for the feature
+  V3 (development)  no development-version history captured
+
+Each sub-check is individually toggleable in harness.config.json → versioning;
+the whole gate is bypassable via gates.commit_requires_version:false (a logged,
+branch-scoped decision). Non-feature commits pass through untouched.
+"""
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import harness_lib as lib  # noqa: E402
+import version_lib as ver  # noqa: E402
+
+COMMIT_RE = re.compile(r"\bgit\s+commit\b|\bgh\s+pr\s+create\b")
+
+
+def main():
+    event = lib.read_hook_input()
+    if event.get("tool_name") != "Bash":
+        lib.allow()
+    if not COMMIT_RE.search((event.get("tool_input", {}) or {}).get("command", "")):
+        lib.allow()
+
+    root = lib.project_dir(event)
+    config = lib.load_config(root)
+    if not config.get("gates", {}).get("commit_requires_version", True):
+        lib.allow()
+    vcfg = config.get("versioning", {})
+    if vcfg.get("enabled", True) is False:
+        lib.allow()
+
+    feature_dir = lib.current_feature_dir(root)
+    if not feature_dir:
+        lib.allow()
+    feature = os.path.basename(feature_dir)
+
+    # V1 — dependency: major bumps acknowledged
+    if vcfg.get("require_major_dep_ack", True):
+        deps = lib.read_json(os.path.join(feature_dir, "dependencies.json"), default={}) or {}
+        if deps.get("has_major") and not deps.get("acknowledged"):
+            majors = [c["name"] for c in deps.get("changes", []) if c.get("severity") == "major"]
+            lib.deny(
+                "Commit blocked (version): unacknowledged MAJOR dependency change in '%s' "
+                "(%s). Review the bump, then: python .claude/scripts/version.py ack-deps %s"
+                % (feature, ", ".join(majors), feature))
+
+    # V2 — code: semver bump + changelog for this feature
+    if vcfg.get("require_code_bump", True):
+        vj = lib.read_json(os.path.join(feature_dir, "version.json"), default={}) or {}
+        code_version = vj.get("code_version")
+        changelog = os.path.join(root, "CHANGELOG.md")
+        logged = False
+        if code_version and os.path.exists(changelog):
+            try:
+                logged = code_version in open(changelog, "r", encoding="utf-8", errors="ignore").read()
+            except OSError:
+                logged = False
+        if not (code_version and logged):
+            lib.deny(
+                "Commit blocked (version): feature '%s' has no recorded code version + "
+                "CHANGELOG entry. Bump it: python .claude/scripts/version.py bump %s" % (feature, feature))
+
+    # V3 — development: version history captured
+    if vcfg.get("require_dev_history", True):
+        hist = lib.read_json(os.path.join(feature_dir, "history.json"), default={}) or {}
+        if not hist.get("entries"):
+            lib.deny(
+                "Commit blocked (version): no development-version history for '%s'. "
+                "Snapshot it: python .claude/scripts/version.py snapshot %s integrated" % (feature, feature))
+
+    lib.allow()
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/version-tracker.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""version-tracker.py — PostToolUse hook on Edit|Write (dependency versioning).
+
+When a specialist edits a dependency manifest (package.json, requirements.txt,
+pyproject.toml, go.mod, Cargo.toml), recompute the change set for the active
+feature against its baseline (captured at approval) and record it in
+specs/<f>/dependencies.json. This is the producer; version-gate.py enforces that
+a major bump is acknowledged before commit.
+
+Records only — always exits 0 (a first out-of-footprint concern is the
+divergence-monitor's job; this one just keeps the dependency ledger current). If
+no baseline exists yet (feature not approved, or non-pipeline edit), it no-ops:
+the baseline must be the pre-feature state, so it is captured at approval, never
+guessed here.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import harness_lib as lib  # noqa: E402
+import version_lib as ver  # noqa: E402
+
+
+def main():
+    event = lib.read_hook_input()
+    if event.get("tool_name") not in ("Edit", "Write", "MultiEdit"):
+        lib.allow()
+
+    fpath = (event.get("tool_input", {}) or {}).get("file_path")
+    if not fpath:
+        lib.allow()
+
+    root = lib.project_dir(event)
+    config = lib.load_config(root)
+    vcfg = config.get("versioning", {})
+    if vcfg.get("enabled", True) is False:
+        lib.allow()
+    manifests = vcfg.get("manifests", ver.DEFAULT_MANIFESTS)
+    if not ver.is_manifest(os.path.basename(fpath), manifests):
+        lib.allow()
+
+    feature_dir = lib.current_feature_dir(root)
+    if not feature_dir:
+        lib.allow()
+    baseline = lib.read_json(os.path.join(feature_dir, "dependencies.baseline.json"))
+    if not baseline:
+        lib.allow()  # no pre-feature baseline captured -> nothing to diff against
+
+    current = ver.snapshot_deps(root, manifests)
+    changes = ver.diff_deps(baseline, current)
+    prev = lib.read_json(os.path.join(feature_dir, "dependencies.json"), default={}) or {}
+    lib.write_json(os.path.join(feature_dir, "dependencies.json"), {
+        "changes": changes,
+        "has_major": ver.has_major(changes),
+        "acknowledged": bool(prev.get("acknowledged")) and not ver.has_major(changes),
+    })
+
+    if ver.has_major(changes):
+        majors = [c["name"] for c in changes if c["severity"] == "major"]
+        lib.warn("Dependency versioning: MAJOR change to %s. This must be acknowledged "
+                 "before commit (version-gate) — run `python .claude/scripts/version.py "
+                 "ack-deps <feature>` once reviewed." % ", ".join(majors))
+    lib.allow()
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/version_lib.py

@@ -0,0 +1,243 @@
+"""version_lib.py — the Version Controller core (dependency + code + development).
+
+Three responsibilities, one deterministic engine (scripts do computation; files
+carry state — same ethos as the rest of the harness):
+
+  * Dependency versioning — parse manifests, diff current vs the feature's
+    baseline, classify each change major/minor/patch, flag major bumps.
+  * Code versioning — semver bump derived from a declared impact level, with a
+    CHANGELOG.md entry.
+  * Development versioning — hash-snapshot the spec artifacts at each milestone
+    so a feature's evolution (approved -> integrated -> committed) is auditable.
+
+Everything here is pure/deterministic and fails open on parse errors — a manifest
+we can't read is skipped, never crashes a hook.
+"""
+
+import hashlib
+import json
+import os
+import re
+
+_here = os.path.dirname(os.path.abspath(__file__))
+import sys
+sys.path.insert(0, _here)
+import harness_lib as lib  # noqa: E402
+
+DEFAULT_MANIFESTS = ["package.json", "requirements.txt", "pyproject.toml", "go.mod", "Cargo.toml"]
+_SEMVER = re.compile(r"(\d+)\.(\d+)(?:\.(\d+))?")
+
+
+# --------------------------------------------------------------------------- #
+# semver
+# --------------------------------------------------------------------------- #
+def parse_semver(v):
+    if not v:
+        return None
+    m = _SEMVER.search(str(v))
+    if not m:
+        return None
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))
+
+
+def classify(old, new):
+    a, b = parse_semver(old), parse_semver(new)
+    if a is None or b is None:
+        return "unknown"
+    if a[0] != b[0]:
+        return "major"
+    if a[1] != b[1]:
+        return "minor"
+    if a[2] != b[2]:
+        return "patch"
+    return "none"
+
+
+def next_version(current, level):
+    a = parse_semver(current) or (0, 0, 0)
+    if level == "major":
+        return "%d.0.0" % (a[0] + 1)
+    if level == "patch":
+        return "%d.%d.%d" % (a[0], a[1], a[2] + 1)
+    return "%d.%d.0" % (a[0], a[1] + 1)  # minor (default)
+
+
+# --------------------------------------------------------------------------- #
+# manifest parsing (best-effort, dependency-free)
+# --------------------------------------------------------------------------- #
+def _p_package_json(text):
+    out = {}
+    try:
+        data = json.loads(text)
+    except Exception:
+        return out
+    for key in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
+        for name, ver in (data.get(key) or {}).items():
+            out[name] = ver
+    return out
+
+
+def _p_requirements(text):
+    out = {}
+    for line in text.splitlines():
+        line = line.split("#", 1)[0].strip()
+        m = re.match(r"^([A-Za-z0-9._-]+)\s*(?:==|~=|>=|<=|>|<)\s*([0-9][^\s;,]*)", line)
+        if m:
+            out[m.group(1)] = m.group(2)
+    return out
+
+
+def _p_pyproject(text):
+    out = {}
+    # PEP 621 / poetry — best effort, no TOML lib
+    for m in re.finditer(r'"([A-Za-z0-9._-]+)\s*(?:==|>=|~=)\s*([0-9][^"\s,]*)"', text):
+        out[m.group(1)] = m.group(2)
+    for m in re.finditer(r'^\s*([A-Za-z0-9._-]+)\s*=\s*"[\^~]?([0-9][^"\s]*)"', text, re.M):
+        out.setdefault(m.group(1), m.group(2))
+    return out
+
+
+def _p_gomod(text):
+    out = {}
+    for m in re.finditer(r'^\s*([^\s]+/[^\s]+)\s+v(\d+\.\d+\.\d+)', text, re.M):
+        out[m.group(1)] = m.group(2)
+    return out
+
+
+def _p_cargo(text):
+    out = {}
+    for m in re.finditer(r'^\s*([A-Za-z0-9._-]+)\s*=\s*"([0-9][^"]*)"', text, re.M):
+        out[m.group(1)] = m.group(2)
+    for m in re.finditer(r'^\s*([A-Za-z0-9._-]+)\s*=\s*\{[^}]*version\s*=\s*"([0-9][^"]*)"', text, re.M):
+        out[m.group(1)] = m.group(2)
+    return out
+
+
+_PARSERS = {
+    "package.json": _p_package_json,
+    "requirements.txt": _p_requirements,
+    "pyproject.toml": _p_pyproject,
+    "go.mod": _p_gomod,
+    "Cargo.toml": _p_cargo,
+}
+
+
+def is_manifest(basename, manifests=None):
+    return basename in (manifests or DEFAULT_MANIFESTS)
+
+
+def snapshot_deps(root, manifests=None):
+    """Aggregate declared dependency versions across all manifests found in root."""
+    manifests = manifests or DEFAULT_MANIFESTS
+    deps = {}
+    for name in manifests:
+        parser = _PARSERS.get(name)
+        if not parser:
+            continue
+        path = os.path.join(root, name)
+        if not os.path.exists(path):
+            continue
+        try:
+            with open(path, "r", encoding="utf-8", errors="ignore") as fh:
+                text = fh.read()
+        except OSError:
+            continue
+        for dep, ver in parser(text).items():
+            deps["%s:%s" % (name, dep)] = ver
+    return deps
+
+
+def diff_deps(baseline, current):
+    """List of {name, from, to, kind, severity}; kind in added|removed|bumped."""
+    changes = []
+    for key in sorted(set(baseline) | set(current)):
+        old, new = baseline.get(key), current.get(key)
+        if old == new:
+            continue
+        if old is None:
+            changes.append({"name": key, "from": None, "to": new, "kind": "added", "severity": "minor"})
+        elif new is None:
+            changes.append({"name": key, "from": old, "to": None, "kind": "removed", "severity": "major"})
+        else:
+            sev = classify(old, new)
+            changes.append({"name": key, "from": old, "to": new, "kind": "bumped",
+                            "severity": sev if sev != "none" else "patch"})
+    return changes
+
+
+def has_major(changes):
+    return any(c["severity"] == "major" for c in changes)
+
+
+# --------------------------------------------------------------------------- #
+# development versioning — artifact snapshots
+# --------------------------------------------------------------------------- #
+SNAPSHOT_TARGETS = ["discovery.md", "plan.md", "task-graph.json", "approvals.json"]
+
+
+def _sha1(path):
+    try:
+        with open(path, "rb") as fh:
+            return "sha1:" + hashlib.sha1(fh.read()).hexdigest()[:16]
+    except OSError:
+        return None
+
+
+def snapshot_artifacts(spec_dir):
+    hashes = {}
+    for rel in SNAPSHOT_TARGETS:
+        h = _sha1(os.path.join(spec_dir, rel))
+        if h:
+            hashes[rel] = h
+    cdir = os.path.join(spec_dir, "contracts")
+    if os.path.isdir(cdir):
+        for name in sorted(os.listdir(cdir)):
+            h = _sha1(os.path.join(cdir, name))
+            if h:
+                hashes["contracts/" + name] = h
+    for name in sorted(os.listdir(spec_dir)) if os.path.isdir(spec_dir) else []:
+        if re.match(r"review\..*\.json$", name):
+            h = _sha1(os.path.join(spec_dir, name))
+            if h:
+                hashes[name] = h
+    return hashes
+
+
+def record_snapshot(spec_dir, milestone, now=None):
+    """Append a development-version entry to history.json; returns dev_version."""
+    hp = os.path.join(spec_dir, "history.json")
+    hist = lib.read_json(hp, default={}) or {}
+    entries = hist.setdefault("entries", [])
+    dev_version = len(entries) + 1
+    entries.append({
+        "dev_version": dev_version,
+        "milestone": milestone,
+        "at": now,
+        "artifacts": snapshot_artifacts(spec_dir),
+    })
+    hist["dev_version"] = dev_version
+    lib.write_json(hp, hist)
+    return dev_version
+
+
+# --------------------------------------------------------------------------- #
+# code versioning — VERSION + CHANGELOG
+# --------------------------------------------------------------------------- #
+def read_root_version(root):
+    p = os.path.join(root, "VERSION")
+    try:
+        with open(p, "r", encoding="utf-8") as fh:
+            return fh.read().strip() or "0.0.0"
+    except OSError:
+        return "0.0.0"
+
+
+def plan_version_impact(spec_dir):
+    """Level declared by the planner as `VERSION-IMPACT: major|minor|patch` in plan.md."""
+    try:
+        with open(os.path.join(spec_dir, "plan.md"), "r", encoding="utf-8", errors="ignore") as fh:
+            text = fh.read()
+    except OSError:
+        return None
+    m = re.search(r"VERSION-IMPACT:\s*(major|minor|patch)", text, re.I)
+    return m.group(1).lower() if m else None

package/template/.claude/scripts/approve-plan.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""approve-plan.py — write specs/<feature>/approvals.json (the autonomy boundary).
+
+This is the signature the human applies to the DRAFT PLAN PACKAGE (tasks,
+footprints, contracts, computed task-graph, token budget). After it exists and
+its hash matches plan.md, dispatch-gate G1 lets automation run — and any later
+edit to plan.md breaks the hash and re-freezes the pipeline until re-approval.
+
+    python .claude/scripts/approve-plan.py <feature> [--budget N] [--approver NAME] [--force]
+
+The plan_hash MUST be computed exactly as dispatch-gate.py computes it:
+    sha256(plan.md bytes)   — keep these two in lock-step.
+
+Approval also runs the requirements gate (req_lib): it REFUSES to sign a plan
+built on ambiguous intent, vague requirements, a broken flow, or one that has
+diverged from the acceptance criteria (uncovered ACs / scope creep). --force
+overrides and records the override in approvals.json, so the bypass is logged,
+never silent.
+"""
+import argparse
+import hashlib
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "hooks"))
+import harness_lib as lib  # noqa: E402
+import req_lib as req  # noqa: E402
+import version_lib as ver  # noqa: E402
+
+REPO = Path(os.environ.get("CLAUDE_PROJECT_DIR") or Path.cwd())
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("feature")
+    ap.add_argument("--budget", type=int, default=None,
+                    help="approved token budget for this feature (burndown ceiling)")
+    ap.add_argument("--approver", default=os.environ.get("USER") or os.environ.get("USERNAME") or "human")
+    ap.add_argument("--now", default=None, help="override timestamp (tests)")
+    ap.add_argument("--force", action="store_true",
+                    help="sign despite requirements-gate problems (logged as an override)")
+    args = ap.parse_args(argv)
+
+    spec = REPO / "specs" / args.feature
+    plan = spec / "plan.md"
+    if not plan.exists():
+        sys.stderr.write("approve-plan: %s not found — nothing to approve.\n" % plan)
+        return 1
+
+    cfg = lib.load_config(str(REPO)).get("requirements", {})
+    problems = req.check_all(str(spec), is_specialist=True, cfg=cfg)
+    if problems and not args.force:
+        sys.stderr.write(
+            "approve-plan: REFUSED — the plan is not ready to sign:\n  - "
+            + "\n  - ".join(problems)
+            + "\nResolve these with the user (re-interview / re-plan), or pass --force "
+              "to sign anyway (the override is logged in approvals.json).\n")
+        return 2
+
+    approvals = {
+        "plan_hash": hashlib.sha256(plan.read_bytes()).hexdigest(),
+        "budget": args.budget,
+        "approver": args.approver,
+        "timestamp": args.now or datetime.now(timezone.utc).isoformat(),
+    }
+    if problems and args.force:
+        approvals["forced_override"] = problems
+    (spec / "approvals.json").write_text(
+        json.dumps(approvals, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    # Version Controller: capture the pre-implementation dependency baseline and
+    # the first development-version snapshot. Both must happen at approval — the
+    # baseline is the pre-feature state, and dev history starts the moment the
+    # decomposition is signed.
+    try:
+        deps = ver.snapshot_deps(str(REPO), lib.load_config(str(REPO)).get("versioning", {}).get("manifests"))
+        lib.write_json(str(spec / "dependencies.baseline.json"), deps)
+        ver.record_snapshot(str(spec), "approved", now=approvals["timestamp"])
+    except Exception as e:  # versioning must never block an otherwise-valid approval
+        sys.stderr.write("approve-plan: version baseline/snapshot skipped (%s)\n" % e)
+
+    sys.stderr.write("approved '%s' (plan_hash %s…, budget %s)\n"
+                     % (args.feature, approvals["plan_hash"][:12], approvals["budget"]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.claude/scripts/changeset.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+"""changeset.py — print the current pending-diff fingerprint.
+
+The reviewer runs this and records the output as `changeset` in its integration
+review verdict. commit-gate.py computes the same value and only opens the gate
+when they match — so a review authorizes exactly the diff it saw, nothing later.
+
+    python .claude/scripts/changeset.py [repo_root]
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "hooks"))
+import harness_lib as lib  # noqa: E402
+
+root = os.path.abspath(sys.argv[1]) if len(sys.argv) > 1 else os.getcwd()
+cs = lib.git_changeset(root)
+print(cs if cs else "no-git")