phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/dotfiles_profile_plugin.py

@@ -0,0 +1,96 @@
+"""Dotfiles profile plugin: dotfiles-domain phase-loop CLI commands.
+
+DECOUPLE SL-1 moves the dotfiles-specific subcommands (`adoption-bundle`,
+`sync-skills`, `build-bundle`, `hotfix`) out of the generic CLI and behind this
+profile-command plugin. The generic ``phase_loop_runtime.cli`` registers NONE of
+them at import; they appear only when this plugin is loaded -- either via the
+``phase_loop_runtime.profile_commands`` entry-point group (declared by a profile
+distribution) or via the explicit ``PHASE_LOOP_PROFILE_PLUGINS`` opt-in used in
+source-mode runs and tests.
+
+This module is the dotfiles *profile*: it is allowed to depend on dotfiles-domain
+runtime modules. Decoupling means the generic CLI no longer imports them, not that
+they cease to exist.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from argparse import _SubParsersAction
+
+
+# Default canonical skill-bundle source roots advertised by `build-bundle --help`.
+# Imported lazily inside register to keep `import phase_loop_runtime.cli` clean.
+
+
+def register_profile_commands(subparsers: "_SubParsersAction") -> None:
+    """Register the dotfiles-domain subcommands on an existing subparsers action.
+
+    Each subparser carries the shared common args (via the generic CLI helper) and
+    a ``func`` default that the generic dispatcher invokes as
+    ``func(repo=repo, args=args, as_json=as_json)``.
+    """
+    from . import cli
+    from .build_bundle import DEFAULT_SOURCES
+
+    def _add_common(sub: argparse.ArgumentParser, name: str) -> None:
+        cli._add_common_subparser_args(sub, name=name)
+
+    # adoption-bundle -------------------------------------------------------
+    adoption = subparsers.add_parser("adoption-bundle")
+    adoption.description = "Check or refresh the committed dotfiles adoption bundle."
+    adoption.add_argument("adoption_bundle_action", choices=("status", "refresh"))
+    _add_common(adoption, "adoption-bundle")
+    adoption.set_defaults(command="adoption-bundle", func=_adoption_bundle_dispatch)
+
+    # sync-skills -----------------------------------------------------------
+    sync = subparsers.add_parser("sync-skills")
+    sync.description = "Audit or repair harness-local phase-loop bridge skills for manual reentry."
+    sync.add_argument("--harness", action="append", default=[], choices=("codex", "claude", "gemini", "opencode"))
+    sync.add_argument("--check", action="store_true")
+    sync.add_argument("--apply", action="store_true")
+    _add_common(sync, "sync-skills")
+    sync.set_defaults(command="sync-skills", func=cli._sync_skills_command)
+
+    # build-bundle ----------------------------------------------------------
+    build = subparsers.add_parser("build-bundle")
+    build.description = "Regenerate the harness-neutral phase-loop skills bundle from canonical harness roots."
+    build.add_argument(
+        "--source",
+        action="append",
+        help=(
+            "Canonical source root. Repeat for claude, codex, gemini, and opencode. "
+            "Defaults: " + ", ".join(DEFAULT_SOURCES.values())
+        ),
+    )
+    build.add_argument("--destination", default="vendor/phase-loop-skills")
+    build.add_argument("--apply", action="store_true", help="Write generated bundle files. Without --apply, this command is read-only.")
+    build.add_argument("--force", action="store_true", help="Rewrite generated outputs even when content is unchanged.")
+    _add_common(build, "build-bundle")
+    build.set_defaults(command="build-bundle", func=cli._build_bundle_command)
+
+    # hotfix ----------------------------------------------------------------
+    hotfix = subparsers.add_parser("hotfix")
+    hotfix.description = "Run a bounded emergency hotfix through runner-owned verification evidence."
+    hotfix.add_argument("--reason", help="Non-secret reason recorded in the hotfix closeout event.")
+    hotfix.add_argument("--plan", help="Path to a hotfix stub containing a verification_command field.")
+    hotfix.add_argument("--init-stub", help="Write a minimal hotfix stub and exit without executing.")
+    _add_common(hotfix, "hotfix")
+    hotfix.set_defaults(command="hotfix", func=cli._hotfix_command)
+
+
+# --- dispatch ------------------------------------------------------------
+# sync-skills/build-bundle/hotfix bind set_defaults(func=...) straight to the
+# cli._*_command handlers (signatures already match the generic dispatcher's
+# func(repo=, args=, as_json=) convention). Only adoption-bundle needs an adapter,
+# to map the positional adoption_bundle_action -> the handler's `action` kwarg.
+
+
+def _adoption_bundle_dispatch(*, repo, args, as_json):
+    from . import cli
+
+    return cli._adoption_bundle_command(
+        repo=repo, action=args.adoption_bundle_action, as_json=as_json
+    )

phase_loop_runtime/events.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import replace
+from pathlib import Path
+
+from .closeout import phase_loop_closeout_diagnostic
+from .git_topology import attach_git_topology, collect_git_topology
+from .models import LoopEvent, WorkUnitEventMetadata
+from .runtime_paths import ensure_phase_loop_excluded, phase_loop_event_file, phase_loop_event_read_files
+
+
+def event_path(repo: Path) -> Path:
+    return phase_loop_event_file(repo)
+
+
+def event_read_paths(repo: Path) -> tuple[Path, ...]:
+    return phase_loop_event_read_files(repo)
+
+
+def append_event(repo: Path, event: LoopEvent) -> None:
+    ensure_phase_loop_excluded(repo)
+    event = _event_with_closeout_metadata(event)
+    event = attach_git_topology(repo, event)
+    path = event_path(repo)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _append_jsonl(path, event.to_json())
+
+
+def append_work_unit_event(repo: Path, event: WorkUnitEventMetadata, *, roadmap: Path | None = None) -> None:
+    ensure_phase_loop_excluded(repo)
+    payload = event.to_json()
+    closeout = _extract_work_unit_closeout(payload)
+    if closeout is not None:
+        payload["metadata"] = _pipeline_metadata(closeout)
+    payload.update(
+        {
+            "repo": str(repo),
+            "roadmap": str(roadmap or ""),
+            "phase": event.identity.phase,
+            "action": "work_unit",
+            "status": event.status,
+            "source": "work_unit_ledger",
+            "schema_version": 2,
+            "git_topology": collect_git_topology(repo),
+        }
+    )
+    path = event_path(repo)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _append_jsonl(path, payload)
+
+
+def _append_jsonl(path: Path, payload: dict) -> None:
+    encoded = (json.dumps(payload, sort_keys=True) + "\n").encode("utf-8")
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o666)
+    try:
+        os.write(fd, encoded)
+    finally:
+        os.close(fd)
+
+
+def read_events(repo: Path) -> list[dict]:
+    events: list[dict] = []
+    for path in event_read_paths(repo):
+        if not path.exists():
+            continue
+        with path.open(encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if not line:
+                    continue
+                event = json.loads(line)
+                event.setdefault("schema_version", 1)
+                events.append(event)
+    return events
+
+
+def read_work_unit_events(repo: Path, work_unit_id: str | None = None) -> list[dict]:
+    records: list[dict] = []
+    for event in read_events(repo):
+        if event.get("event_kind") != "work_unit":
+            continue
+        work_unit = event.get("work_unit")
+        if not isinstance(work_unit, dict):
+            metadata = event.get("metadata")
+            work_unit = metadata.get("work_unit") if isinstance(metadata, dict) else None
+        if not isinstance(work_unit, dict):
+            continue
+        if work_unit_id is not None and work_unit.get("work_unit_id") != work_unit_id:
+            continue
+        records.append(event)
+    return records
+
+
+def _event_with_closeout_metadata(event: LoopEvent) -> LoopEvent:
+    metadata = dict(event.metadata or {})
+    closeout = _extract_closeout(metadata)
+    if closeout is None:
+        return event
+    metadata.update(_pipeline_metadata(closeout))
+    return replace(event, metadata=metadata)
+
+
+def _extract_closeout(metadata: dict) -> dict | None:
+    closeout = metadata.get("phase_loop_closeout")
+    if not isinstance(closeout, dict):
+        terminal = metadata.get("terminal_summary")
+        closeout = terminal.get("phase_loop_closeout") if isinstance(terminal, dict) else None
+    if isinstance(closeout, dict) and phase_loop_closeout_diagnostic(closeout) is None:
+        return closeout
+    return None
+
+
+def _extract_work_unit_closeout(payload: dict) -> dict | None:
+    work_unit = payload.get("work_unit")
+    if not isinstance(work_unit, dict):
+        return None
+    closeout_summary = work_unit.get("closeout_summary")
+    closeout = closeout_summary.get("phase_loop_closeout") if isinstance(closeout_summary, dict) else None
+    if isinstance(closeout, dict) and phase_loop_closeout_diagnostic(closeout) is None:
+        return closeout
+    return None
+
+
+def _pipeline_metadata(closeout: dict) -> dict:
+    source_bundle = closeout.get("source_bundle") if isinstance(closeout.get("source_bundle"), dict) else {}
+    artifacts = closeout.get("artifacts") if isinstance(closeout.get("artifacts"), dict) else {}
+    verification = closeout.get("verification") if isinstance(closeout.get("verification"), dict) else {}
+    blocker = closeout.get("blocker") if isinstance(closeout.get("blocker"), dict) else {}
+    impact = closeout.get("source_truth_impact") if isinstance(closeout.get("source_truth_impact"), dict) else {}
+    return {
+        "phase_loop_closeout": closeout,
+        "phase_alias": closeout.get("phase_alias") or closeout.get("phase"),
+        "pipeline_phase_id": source_bundle.get("phase_id") or closeout.get("pipeline_phase_id"),
+        "source_bundle_path": source_bundle.get("path") or closeout.get("source_bundle_path"),
+        "source_bundle_sha256": source_bundle.get("sha256") or closeout.get("source_bundle_sha256"),
+        "pipeline_mode": source_bundle.get("pipeline_mode"),
+        "verification_status": verification.get("status") or closeout.get("verification_status"),
+        "changed_paths": artifacts.get("changed_paths") or closeout.get("changed_paths") or [],
+        "evidence_refs": artifacts.get("evidence_refs") or closeout.get("evidence_refs") or [],
+        "blocker_class": blocker.get("blocker_class"),
+        "source_truth_impact": impact,
+        "canonical_refresh_recommended": impact.get("canonical_refresh_recommended", False),
+        "canonical_refresh_reason_codes": impact.get("canonical_refresh_reason_codes") or [],
+        "changed_path_boundaries": impact.get("changed_path_boundaries") or [],
+        "changed_path_categories": sorted(
+            {
+                str(item.get("category"))
+                for item in impact.get("changed_path_boundaries") or []
+                if isinstance(item, dict) and item.get("category")
+            }
+        ),
+    }

phase_loop_runtime/events_migration.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .runtime_paths import phase_loop_event_file
+
+
+@dataclass(frozen=True)
+class MigrationResult:
+    migrated: int
+    already_migrated: int
+    backup: str | None = None
+    dry_run: bool = False
+
+    def to_json(self) -> dict[str, object]:
+        if self.dry_run:
+            return {
+                "would_migrate": self.migrated,
+                "already_migrated": self.already_migrated,
+            }
+        return {
+            "migrated": self.migrated,
+            "already_migrated": self.already_migrated,
+            "backup": self.backup,
+        }
+
+
+class MigrationError(RuntimeError):
+    pass
+
+
+def migrate_ledger(repo: Path, *, dry_run: bool, backup_suffix: str) -> MigrationResult:
+    repo = Path(repo).expanduser().resolve()
+    event_path = phase_loop_event_file(repo)
+    source = event_path.read_text(encoding="utf-8") if event_path.exists() else ""
+    lines = source.splitlines()
+    trailing_newline = source.endswith("\n")
+
+    parsed: list[dict | None] = []
+    for index, line in enumerate(lines, start=1):
+        if not line.strip():
+            parsed.append(None)
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise MigrationError(f"malformed JSONL at line {index}: {exc.msg}") from exc
+        if not isinstance(event, dict):
+            raise MigrationError(f"malformed JSONL at line {index}: expected object")
+        parsed.append(event)
+
+    migrated = 0
+    already_migrated = 0
+    rewritten_lines = list(lines)
+    for index, event in enumerate(parsed):
+        if event is None:
+            continue
+        if _is_executor_closeout(event, action="executor.closeout"):
+            already_migrated += 1
+            continue
+        if not _is_executor_closeout(event, action="run"):
+            continue
+        migrated += 1
+        rewritten = dict(event)
+        rewritten["action"] = "executor.closeout"
+        rewritten_lines[index] = json.dumps(rewritten, separators=(",", ":"))
+
+    if dry_run:
+        return MigrationResult(migrated=migrated, already_migrated=already_migrated, dry_run=True)
+
+    backup_path = event_path.with_name(event_path.name + backup_suffix)
+    if migrated == 0:
+        backup = str(backup_path) if backup_path.exists() else None
+        return MigrationResult(migrated=0, already_migrated=already_migrated, backup=backup)
+    if backup_path.exists():
+        raise MigrationError(f"backup path already exists: {backup_path}")
+
+    event_path.parent.mkdir(parents=True, exist_ok=True)
+    backup_path.write_text(source, encoding="utf-8")
+    tmp_path = event_path.with_name(event_path.name + ".tmp-def4-migrate")
+    output = "\n".join(rewritten_lines)
+    if trailing_newline and output:
+        output += "\n"
+    tmp_path.write_text(output, encoding="utf-8")
+    os.replace(tmp_path, event_path)
+    return MigrationResult(migrated=migrated, already_migrated=already_migrated, backup=str(backup_path))
+
+
+def _is_executor_closeout(event: dict, *, action: str) -> bool:
+    if event.get("action") != action:
+        return False
+    metadata = event.get("metadata")
+    return isinstance(metadata, dict) and isinstance(metadata.get("executor_closeout_event"), dict)