harneloop 0.0.2__py3-none-any.whl

harneloop/__init__.py

@@ -0,0 +1,3 @@
+"""Harneloop core lifecycle engine."""
+
+__version__ = "0.0.1"

harneloop/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

harneloop/adapters.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .errors import HarneloopError
+from .state import read_state
+from .versioning import ensure_unit
+from .yamlio import read_yaml
+
+
+SUPPORTED_ADAPTERS = {"generic", "codex", "cursor"}
+
+
+def collect_agent_markdown(unit_root: Path) -> str:
+    sections: list[str] = []
+    unit_agent = unit_root / "UNIT_AGENT.md"
+    if unit_agent.exists():
+        sections.append(unit_agent.read_text(encoding="utf-8").strip())
+
+    agent_facing = unit_root / "agent-facing"
+    if agent_facing.exists():
+        for path in sorted(agent_facing.rglob("*.md")):
+            sections.append(path.read_text(encoding="utf-8").strip())
+
+    return "\n\n---\n\n".join(section for section in sections if section)
+
+
+def export_body(unit_root: Path, adapter: str) -> str:
+    unit_meta = read_yaml(unit_root / "unit.yaml")
+    state = read_state(unit_root)
+    instructions = collect_agent_markdown(unit_root)
+    current_version = unit_meta.get("current_version") or "none"
+
+    return "\n".join(
+        [
+            f"# {unit_meta.get('name', unit_meta.get('id', 'Harneloop Unit'))}",
+            "",
+            f"Export adapter: `{adapter}`",
+            f"Unit id: `{unit_meta.get('id', 'unknown')}`",
+            f"Current version: `{current_version}`",
+            f"Lifecycle state: `{state.get('state', 'unknown')}`",
+            "",
+            "## Harness Instructions",
+            "",
+            instructions or "No agent-facing instructions have been promoted yet.",
+            "",
+            "## Operating Rules",
+            "",
+            "- Treat these instructions as the promoted harness for this task family.",
+            "- Do not edit the source harness unit directly from this export.",
+            "- Improvements should be proposed as Harneloop candidates and promoted through evidence gates.",
+            "- Runtime traces, raw artifacts, local caches, and secrets are not part of this export.",
+        ]
+    ) + "\n"
+
+
+def export_unit(unit_root: Path, adapter: str, output: Path | None = None) -> Path:
+    unit_root = unit_root.resolve()
+    ensure_unit(unit_root)
+    if adapter not in SUPPORTED_ADAPTERS:
+        supported = ", ".join(sorted(SUPPORTED_ADAPTERS))
+        raise HarneloopError(f"Unsupported adapter `{adapter}`. Expected one of: {supported}")
+
+    export_root = (output or (unit_root / "exports" / adapter)).resolve()
+    export_root.mkdir(parents=True, exist_ok=True)
+    body = export_body(unit_root, adapter)
+
+    if adapter == "codex":
+        (export_root / "AGENTS.md").write_text(body, encoding="utf-8", newline="\n")
+    elif adapter == "cursor":
+        cursor_body = "---\ndescription: Harneloop exported harness unit\nalwaysApply: false\n---\n\n" + body
+        (export_root / "harneloop-unit.mdc").write_text(cursor_body, encoding="utf-8", newline="\n")
+    else:
+        (export_root / "UNIT_AGENT.md").write_text(body, encoding="utf-8", newline="\n")
+
+    return export_root

harneloop/attempts.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .errors import HarneloopError
+from .locking import file_lock, harness_lock_path
+from .runs import read_run, write_run
+from .state import now_iso, update_state
+from .versioning import ensure_unit
+from .yamlio import read_yaml, write_yaml
+
+
+def normalize_list(value: list[str] | tuple[str, ...] | None) -> list[str]:
+    return [item for item in (value or []) if item]
+
+
+def attempts_root(unit_root: Path) -> Path:
+    return unit_root / "attempts"
+
+
+def next_attempt_id(unit_root: Path) -> str:
+    root = attempts_root(unit_root)
+    root.mkdir(parents=True, exist_ok=True)
+    existing: list[int] = []
+    for path in root.iterdir():
+        if path.is_dir() and path.name.startswith("attempt-"):
+            try:
+                existing.append(int(path.name.removeprefix("attempt-")))
+            except ValueError:
+                continue
+    return f"attempt-{(max(existing, default=0) + 1):04d}"
+
+
+def attempt_path(unit_root: Path, attempt_id: str) -> Path:
+    path = attempts_root(unit_root) / attempt_id
+    if not path.exists():
+        raise HarneloopError(f"Attempt plan does not exist: {attempt_id}")
+    return path
+
+
+def read_attempt(unit_root: Path, attempt_id: str) -> dict[str, Any]:
+    return read_yaml(attempt_path(unit_root, attempt_id) / "attempt.yaml")
+
+
+def write_attempt(unit_root: Path, attempt_id: str, data: dict[str, Any]) -> dict[str, Any]:
+    write_yaml(attempt_path(unit_root, attempt_id) / "attempt.yaml", data)
+    write_observations_markdown(unit_root, attempt_id, data)
+    return data
+
+
+def create_attempt_plan(
+    unit_root: Path,
+    goal: str,
+    method: str,
+    action: list[str] | tuple[str, ...] | None = None,
+    expected_artifact: list[str] | tuple[str, ...] | None = None,
+    success_check: list[str] | tuple[str, ...] | None = None,
+    note: list[str] | tuple[str, ...] | None = None,
+) -> dict[str, Any]:
+    unit_root = unit_root.resolve()
+    ensure_unit(unit_root)
+    if not goal.strip():
+        raise HarneloopError("Attempt goal cannot be empty")
+    if not method.strip():
+        raise HarneloopError("Attempt method cannot be empty")
+
+    with file_lock(harness_lock_path(unit_root, "attempts")):
+        attempt_id = next_attempt_id(unit_root)
+        root = attempts_root(unit_root) / attempt_id
+        root.mkdir(parents=True, exist_ok=False)
+        data: dict[str, Any] = {
+            "schema_version": "0.1",
+            "id": attempt_id,
+            "goal": goal,
+            "method": method,
+            "actions": normalize_list(action),
+            "expected_artifacts": normalize_list(expected_artifact),
+            "success_checks": normalize_list(success_check),
+            "notes": normalize_list(note),
+            "observations": [],
+            "conclusions": [],
+            "created_at": now_iso(),
+        }
+        write_attempt(unit_root, attempt_id, data)
+    update_state(
+        unit_root,
+        reason="attempt_plan_created",
+        next_action=f"Execute `{attempt_id}` with the target agent/tools, then start a run and capture artifacts.",
+    )
+    return data
+
+
+def add_attempt_observation(
+    unit_root: Path,
+    attempt_id: str,
+    summary: str,
+    outcome: str = "unknown",
+    run_id: str | None = None,
+    finding: list[str] | tuple[str, ...] | None = None,
+) -> dict[str, Any]:
+    if not summary.strip():
+        raise HarneloopError("Observation summary cannot be empty")
+    unit_root = unit_root.resolve()
+    with file_lock(harness_lock_path(unit_root, f"attempt-{attempt_id}")):
+        data = read_attempt(unit_root, attempt_id)
+        observations = data.get("observations") or []
+        observation = {
+            "id": f"observation-{len(observations) + 1:04d}",
+            "summary": summary,
+            "outcome": outcome,
+            "run_id": run_id,
+            "findings": normalize_list(finding),
+            "created_at": now_iso(),
+        }
+        data["observations"] = [*observations, observation]
+        write_attempt(unit_root, attempt_id, data)
+    update_state(
+        unit_root,
+        reason="attempt_observation_added",
+        next_action="Use observations to create evidence, candidate changes, or another attempt plan.",
+    )
+    return observation
+
+
+VALID_CONCLUSION_OUTCOMES = {"pass", "partial", "fail", "inconclusive"}
+VALID_CONCLUSION_DECISIONS = {"accept", "create_candidate", "rerun", "request_input", "stop"}
+VALID_CONFIDENCE = {"low", "medium", "high"}
+
+
+def conclude_attempt(
+    unit_root: Path,
+    attempt_id: str,
+    *,
+    run_id: str,
+    outcome: str,
+    decision: str,
+    summary: str,
+    confidence: str,
+    question: str | None = None,
+) -> dict[str, Any]:
+    if outcome not in VALID_CONCLUSION_OUTCOMES:
+        raise HarneloopError(f"Invalid attempt outcome: {outcome}")
+    if decision not in VALID_CONCLUSION_DECISIONS:
+        raise HarneloopError(f"Invalid attempt decision: {decision}")
+    if confidence not in VALID_CONFIDENCE:
+        raise HarneloopError(f"Invalid conclusion confidence: {confidence}")
+    if not summary.strip():
+        raise HarneloopError("Attempt conclusion summary cannot be empty")
+    if decision == "request_input" and not (question or "").strip():
+        raise HarneloopError("The `request_input` decision requires a concrete question")
+    if decision == "accept" and outcome != "pass":
+        raise HarneloopError("Only a passing attempt can be accepted without further work")
+
+    unit_root = unit_root.resolve()
+    run = read_run(unit_root, run_id)
+    if run.get("status") == "running":
+        raise HarneloopError(f"Run must be finished before evaluation: {run_id}")
+    if run.get("attempt_id") != attempt_id:
+        raise HarneloopError(f"Run `{run_id}` is not linked to attempt `{attempt_id}`")
+
+    with file_lock(harness_lock_path(unit_root, f"attempt-{attempt_id}")):
+        data = read_attempt(unit_root, attempt_id)
+        expected = data.get("expected_artifacts") or []
+        captured = {artifact.get("kind") for artifact in (run.get("artifacts") or [])}
+        missing = [kind for kind in expected if kind not in captured]
+        if outcome == "pass" and missing:
+            missing_text = ", ".join(missing)
+            raise HarneloopError(f"Passing conclusion is missing expected artifacts: {missing_text}")
+
+        conclusions = data.get("conclusions") or []
+        conclusion = {
+            "id": f"conclusion-{len(conclusions) + 1:04d}",
+            "run_id": run_id,
+            "outcome": outcome,
+            "decision": decision,
+            "summary": summary.strip(),
+            "confidence": confidence,
+            "captured_artifact_kinds": sorted(kind for kind in captured if kind),
+            "missing_expected_artifacts": missing,
+            "question": (question or "").strip() or None,
+            "created_at": now_iso(),
+        }
+        data["conclusions"] = [*conclusions, conclusion]
+        write_attempt(unit_root, attempt_id, data)
+
+    run["evaluation_status"] = "completed"
+    run["evaluation_outcome"] = outcome
+    write_run(unit_root, run_id, run)
+
+    if decision == "accept":
+        update_state(
+            unit_root,
+            state="satisfied",
+            reason="current_harness_accepted",
+            next_action="No candidate is needed for the current evidence. Resume only for broader tests or a changed goal.",
+        )
+    elif decision == "create_candidate":
+        update_state(
+            unit_root,
+            state="active",
+            reason="candidate_change_needed",
+            next_action=f"Create a candidate from conclusion `{conclusion['id']}` and retest it.",
+        )
+    elif decision == "rerun":
+        update_state(
+            unit_root,
+            state="active",
+            reason="attempt_rerun_needed",
+            next_action="Revise the attempt or evidence plan and run it again before changing the harness.",
+        )
+    elif decision == "request_input":
+        update_state(
+            unit_root,
+            state="waiting",
+            reason="user_input_required",
+            next_action=question.strip(),
+            resume_condition="The user provides or delegates the requested context or evidence.",
+        )
+    else:
+        update_state(
+            unit_root,
+            state="stopped",
+            reason="attempt_conclusion_stopped",
+            next_action="Resume only when the documented stopping reason changes.",
+        )
+    return conclusion
+
+
+def write_observations_markdown(unit_root: Path, attempt_id: str, data: dict[str, Any]) -> None:
+    lines = [
+        f"# Observations For {attempt_id}",
+        "",
+        f"Goal: {data.get('goal')}",
+        "",
+    ]
+    observations = data.get("observations") or []
+    if not observations:
+        lines.append("No observations recorded yet.")
+    for observation in observations:
+        lines.extend(
+            [
+                f"## {observation.get('id')}",
+                "",
+                f"- Outcome: `{observation.get('outcome')}`",
+                f"- Run: `{observation.get('run_id') or 'none'}`",
+                f"- Summary: {observation.get('summary')}",
+            ]
+        )
+        findings = observation.get("findings") or []
+        if findings:
+            lines.extend(["", "Findings:"])
+            lines.extend(f"- {item}" for item in findings)
+        lines.append("")
+    (attempt_path(unit_root, attempt_id) / "OBSERVATIONS.md").write_text(
+        "\n".join(lines).rstrip() + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )

harneloop/candidate.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .errors import HarneloopError
+from .locking import file_lock, harness_lock_path
+from .state import now_iso, update_state
+from .yamlio import read_yaml, write_yaml
+
+
+CANDIDATE_PLANES = {"target_harness", "evaluation", "infrastructure", "mixed"}
+VALIDATION_TIERS = ("structural", "targeted", "representative", "full")
+VALIDATION_TIER_RANK = {tier: index for index, tier in enumerate(VALIDATION_TIERS)}
+OPEN_CANDIDATE_STATUSES = {"draft", "accumulating", "ready", "validating", "needs_rebase"}
+TERMINAL_CANDIDATE_STATUSES = {"promoted", "rejected"}
+ALLOWED_STATUS_TRANSITIONS = {
+    "draft": {"accumulating", "ready", "rejected"},
+    "accumulating": {"ready", "rejected"},
+    "ready": {"accumulating", "validating", "rejected"},
+    "validating": {"accumulating", "ready", "rejected"},
+    "needs_rebase": {"rejected"},
+}
+
+
+def validate_plane(plane: str) -> str:
+    if plane not in CANDIDATE_PLANES:
+        supported = ", ".join(sorted(CANDIDATE_PLANES))
+        raise HarneloopError(f"Unknown candidate plane `{plane}`. Expected one of: {supported}")
+    return plane
+
+
+def validate_tier(validation_tier: str) -> str:
+    if validation_tier not in VALIDATION_TIER_RANK:
+        supported = ", ".join(VALIDATION_TIERS)
+        raise HarneloopError(f"Unknown validation tier `{validation_tier}`. Expected one of: {supported}")
+    return validation_tier
+
+
+def candidate_path(unit_root: Path, candidate_id: str) -> Path:
+    path = unit_root.resolve() / "candidates" / candidate_id
+    if not path.exists():
+        raise HarneloopError(f"Candidate does not exist: {candidate_id}")
+    return path
+
+
+def read_candidate(unit_root: Path, candidate_id: str) -> dict[str, object]:
+    return read_yaml(candidate_path(unit_root, candidate_id) / "candidate.yaml")
+
+
+def list_candidates(unit_root: Path, include_closed: bool = True) -> list[dict[str, object]]:
+    candidates_root = unit_root.resolve() / "candidates"
+    if not candidates_root.exists():
+        return []
+    records = [read_yaml(path / "candidate.yaml") for path in sorted(candidates_root.glob("cand-*")) if path.is_dir()]
+    records = [record for record in records if record]
+    if not include_closed:
+        records = [record for record in records if record.get("status") in OPEN_CANDIDATE_STATUSES]
+    return records
+
+
+def active_candidate_ids(unit_root: Path) -> list[str]:
+    return [str(record["id"]) for record in list_candidates(unit_root, include_closed=False)]
+
+
+def _sync_candidate_state(unit_root: Path, focused_candidate: str | None, reason: str, next_action: str) -> None:
+    active = active_candidate_ids(unit_root)
+    focused = focused_candidate if focused_candidate in active else (active[-1] if active else None)
+    update_state(
+        unit_root,
+        state="active",
+        active_candidates=active,
+        active_candidate=focused,
+        reason=reason,
+        next_action=next_action,
+    )
+
+
+def next_candidate_id(unit_root: Path) -> str:
+    candidates_root = unit_root / "candidates"
+    candidates_root.mkdir(parents=True, exist_ok=True)
+    existing = []
+    for path in candidates_root.iterdir():
+        if path.is_dir() and path.name.startswith("cand-"):
+            try:
+                existing.append(int(path.name.removeprefix("cand-")))
+            except ValueError:
+                continue
+    return f"cand-{(max(existing, default=0) + 1):04d}"
+
+
+def create_candidate(
+    unit_root: Path,
+    summary: str,
+    kind: str = "mixed",
+    *,
+    plane: str | None = None,
+    validation_tier: str = "targeted",
+) -> Path:
+    unit_root = unit_root.resolve()
+    if not (unit_root / "unit.yaml").exists():
+        raise HarneloopError(f"Not a Harneloop harness unit: {unit_root}")
+    selected_plane = validate_plane(plane or (kind if kind in CANDIDATE_PLANES else "mixed"))
+    selected_tier = validate_tier(validation_tier)
+
+    with file_lock(harness_lock_path(unit_root, "candidates")):
+        candidate_id = next_candidate_id(unit_root)
+        candidate_root = unit_root / "candidates" / candidate_id
+        candidate_root.mkdir(parents=True, exist_ok=False)
+        for directory in ["changes", "validation", "evidence"]:
+            (candidate_root / directory).mkdir(parents=True, exist_ok=True)
+
+        unit_meta = read_yaml(unit_root / "unit.yaml")
+        write_yaml(
+            candidate_root / "candidate.yaml",
+            {
+                "schema_version": "0.2",
+                "id": candidate_id,
+                "base_version": unit_meta.get("current_version"),
+                "kind": kind,
+                "plane": selected_plane,
+                "validation_tier": selected_tier,
+                "status": "accumulating",
+                "summary": summary,
+                "created_at": now_iso(),
+                "changes": {"mode": "overlay", "path": "changes/"},
+                "evidence_required": ["rationale", "validation_notes"],
+            },
+        )
+        (candidate_root / "rationale.md").write_text(
+            f"# Rationale\n\n{summary}\n", encoding="utf-8", newline="\n"
+        )
+        (candidate_root / "notes.md").write_text("# Notes\n", encoding="utf-8", newline="\n")
+
+    _sync_candidate_state(
+        unit_root,
+        focused_candidate=candidate_id,
+        reason="candidate_created",
+        next_action=f"Accumulate related changes in `{candidate_id}` and mark it ready when its validation is sufficient.",
+    )
+    return candidate_root
+
+
+def set_candidate_status(unit_root: Path, candidate_id: str, status: str) -> dict[str, object]:
+    if status not in set().union(*ALLOWED_STATUS_TRANSITIONS.values()):
+        supported = ", ".join(sorted(set().union(*ALLOWED_STATUS_TRANSITIONS.values())))
+        raise HarneloopError(f"Unsupported candidate status `{status}`. Expected one of: {supported}")
+    unit_root = unit_root.resolve()
+    with file_lock(harness_lock_path(unit_root, f"candidate-{candidate_id}")):
+        path = candidate_path(unit_root, candidate_id) / "candidate.yaml"
+        record = read_yaml(path)
+        current = str(record.get("status", "draft"))
+        allowed = ALLOWED_STATUS_TRANSITIONS.get(current, set())
+        if status not in allowed:
+            raise HarneloopError(f"Candidate `{candidate_id}` cannot transition from `{current}` to `{status}`")
+        record["status"] = status
+        record["status_updated_at"] = now_iso()
+        write_yaml(path, record)
+
+    _sync_candidate_state(
+        unit_root,
+        focused_candidate=candidate_id if status != "rejected" else None,
+        reason=f"candidate_{status}",
+        next_action=(
+            f"Validate and promote `{candidate_id}` when its required evidence is attached."
+            if status in {"ready", "validating"}
+            else "Continue the remaining candidate work or create another coherent candidate."
+        ),
+    )
+    return record
+
+
+def rebase_candidate(unit_root: Path, candidate_id: str) -> dict[str, object]:
+    unit_root = unit_root.resolve()
+    with file_lock(harness_lock_path(unit_root, f"candidate-{candidate_id}")):
+        path = candidate_path(unit_root, candidate_id) / "candidate.yaml"
+        record = read_yaml(path)
+        status = str(record.get("status", "draft"))
+        if status in TERMINAL_CANDIDATE_STATUSES:
+            raise HarneloopError(f"Closed candidate cannot be rebased: {candidate_id}")
+        current_version = read_yaml(unit_root / "unit.yaml").get("current_version")
+        previous_base = record.get("base_version")
+        if previous_base == current_version and status != "needs_rebase":
+            raise HarneloopError(f"Candidate `{candidate_id}` already uses the current base version")
+        history = list(record.get("rebase_history") or [])
+        history.append({"from": previous_base, "to": current_version, "rebased_at": now_iso()})
+        record["base_version"] = current_version
+        record["status"] = "accumulating"
+        record["rebase_history"] = history
+        record["status_updated_at"] = now_iso()
+        write_yaml(path, record)
+
+    _sync_candidate_state(
+        unit_root,
+        focused_candidate=candidate_id,
+        reason="candidate_rebased",
+        next_action=f"Revalidate `{candidate_id}` against base version `{current_version or 'none'}` before promotion.",
+    )
+    return record
+
+
+def mark_parallel_candidates_needing_rebase(unit_root: Path, promoted_id: str, new_version: str) -> list[str]:
+    stale: list[str] = []
+    for record in list_candidates(unit_root, include_closed=False):
+        candidate_id = str(record.get("id"))
+        if candidate_id == promoted_id or record.get("base_version") == new_version:
+            continue
+        with file_lock(harness_lock_path(unit_root, f"candidate-{candidate_id}")):
+            path = candidate_path(unit_root, candidate_id) / "candidate.yaml"
+            current = read_yaml(path)
+            if current.get("status") not in OPEN_CANDIDATE_STATUSES:
+                continue
+            current["status"] = "needs_rebase"
+            current["status_updated_at"] = now_iso()
+            write_yaml(path, current)
+        stale.append(candidate_id)
+    return stale