phase-loop-runtime 0.7.9__tar.gz → 0.7.10__tar.gz

{phase_loop_runtime-0.7.9 → phase_loop_runtime-0.7.10}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.9
+Version: 0.7.10
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
-Author: ViperJuice
+Author-email: ViperJuice <viperjuice@users.noreply.github.com>
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/ViperJuice/agent-harness
 Project-URL: Repository, https://github.com/ViperJuice/agent-harness

{phase_loop_runtime-0.7.9 → phase_loop_runtime-0.7.10}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phase-loop-runtime"  # PyPI dist name; NOT "agent-harness" (an unrelated third-party PyPI project)
-version = "0.7.9"
+version = "0.7.10"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "Apache-2.0"
-authors = [{ name = "ViperJuice" }]
+authors = [{ name = "ViperJuice", email = "viperjuice@users.noreply.github.com" }]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",

{phase_loop_runtime-0.7.9 → phase_loop_runtime-0.7.10}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.9"
+__version__ = "0.7.10"

{phase_loop_runtime-0.7.9 → phase_loop_runtime-0.7.10}/src/phase_loop_runtime/_contract_docs/phase-loop/protocol.md

@@ -728,7 +728,7 @@ Completion reconcile:
 
 `phase-loop reconcile --phase <ALIAS> [--closeout-commit <SHA>]
 [--repair-summary <text>] [--verification-status passed]
-[--verification-log <path>] [--recovery-mode]`
+[--verification-log <path> | --closeout-artifact <path>] [--recovery-mode]`
 
 This synthesizes a v28-shape `manual_repair` event for the named phase,
 recording the current `HEAD` (or the supplied SHA) as the closeout commit and
@@ -743,14 +743,33 @@ to one CLI call. Use only as a recovery tool when the executor's work is
 correct but ownership classification or lane-evidence gaps left the runner
 blocked; do not use to bypass legitimate verification failures.
 
-When completion reconcile uses `--verification-status passed`, it must also
-provide `--verification-log <path>` pointing at the runner-owned
-`verification.json` artifact for the run. The runner validates the artifact
-schema, the sibling `verification.log` SHA-256 against `log_sha256`, and every
-command, env-refresh, and suite exit code before appending a completion repair
-event. Remediation output and event metadata include only the artifact path,
-validation code, and exit summary; raw verification log output is never copied
-into reconcile metadata.
+When completion reconcile uses `--verification-status passed`, it must provide
+runner evidence via **either** `--verification-log <path>` **or**
+`--closeout-artifact <path>` (mutually exclusive). `--verification-log` points at
+the runner-owned `verification.json` artifact for the run; the runner validates
+the artifact schema, the sibling `verification.log` SHA-256 against `log_sha256`,
+and every command, env-refresh, and suite exit code before appending a completion
+repair event. Remediation output and event metadata include only the artifact
+path, validation code, and exit summary; raw verification log output is never
+copied into reconcile metadata.
+
+`--closeout-artifact <path>` (ah#90) is an artifact-backed **recovery** path for
+rehydrating a phase whose committed closeout evidence survives but whose ephemeral
+`.phase-loop/runs/verification.json` does not (e.g. after an interrupted session).
+It adopts a **git-tracked, committed** closeout markdown as recovery evidence
+labeled `provenance=tracked_closeout_artifact`, and requires `--closeout-commit`
+and `--repair-summary`. The artifact is bound before acceptance: the resolved
+`--closeout-commit` must name a real commit reachable from `HEAD` (the index `:0`,
+tree-ish, and orphan commits are rejected), the path must be a non-empty regular
+**blob** at that commit (a directory, symlink, or gitlink is rejected), and its
+basename or content must reference the phase. This is an **audit anchor +
+provenance label** for an explicit, operator-reasoned manual recovery — NOT a
+runner verification pass and NOT an authorization gate; it never satisfies a phase
+that hard-requires runner verification (RG / `IF-0-RG-1`). The recorded
+`manual_repair` carries `evidence_provenance=tracked_closeout_artifact`, and
+`phase-loop status` surfaces it (`Closeout verification: passed (recovery
+evidence: tracked_closeout_artifact)`) so consumers can distinguish a recovery
+from a runner pass.
 
 Blocked-state recovery:
 

phase_loop_runtime-0.7.10/src/phase_loop_runtime/_contract_docs/runtime/verification-evidence-contract.md

@@ -0,0 +1,60 @@
+# Verification Evidence Contract
+
+VC freezes the additive verification evidence artifact for future runner wiring. Until a later phase consumes it, the only producer is `phase_loop_runtime.verification_evidence.run_verification`.
+
+`run_verification(repo, run_dir, commands, suite_command, env_refresh, timeout_s, operational_exemptions=None, python_pin=None, phase_alias=None) -> VerificationResult` writes two sibling files under the supplied run directory. The optional `phase_alias` is the LIVE run alias (ah#85). `verification.json`'s `phase_alias` resolves in strict precedence order: the operator env override (`PHASE_LOOP_PHASE_ALIAS` / `PHASE_ALIAS`) wins if set, else the supplied `phase_alias` (the live run alias) if provided, else `.phase-loop/state.json:current_phase`, else `"unknown"`. Threading the live alias on the execute path keeps the artifact from mis-attributing the phase after a mid-run roadmap amendment changes `current_phase`; the env override remains the highest-priority operator escape-hatch.
+
+- `verification.json`
+- `verification.log`
+
+`verification.json` uses schema version 2 and contains exactly these top-level fields:
+
+- `schema_version`
+- `run_id`
+- `phase_alias`
+- `commands`
+- `env_refresh`
+- `suite`
+- `started_at`
+- `finished_at`
+- `log_sha256`
+
+Each `commands[]` item contains `argv`, `cwd`, `exit_code`, `duration_s`, and `log_offset`. `env_refresh`, when present, contains `triggered`, `manifests`, `install_argv`, and `exit_code`. `suite`, when present, contains `argv`, `exit_code`, and `duration_s`.
+
+**Schema v2 (agent-harness#209), additive.** Every stage (`commands[]`, `env_refresh`, `suite`) may additionally carry `log_end_offset` (the exclusive byte end of that stage's output in `verification.log`) and `failure_kind` (the runner-OBSERVED failure origin, one of `timeout` / `error` / `nonzero_exit`), and `env_refresh`/`suite` additionally carry their own `log_offset` (start). These fields are captured at execution time and omitted when null; `failure_kind` is never re-derived from `exit_code` downstream (a child that itself returns 124/127 stays `nonzero_exit`, not `timeout`/`error`). **v1 back-compat:** a v1 artifact (without these fields) still loads — the missing fields default to `None`. `load_verification_artifact` accepts `schema_version` in `{1, 2}`.
+
+`verification.log` stores raw combined stdout and stderr from the recorded subprocesses. `log_offset` is the start byte offset for each stage's output and `log_end_offset` (v2) is its exclusive end. `log_sha256` is the SHA-256 digest of the final log bytes.
+
+**Failure diagnostics (verdict layer, non-frozen).** `validate_verification_artifact` returns `VerificationArtifactValidation`; its `to_json()` includes a `diagnostics` list. On the `nonzero_exit` verdict (where the log is already sha-authenticated), it carries one entry per failing stage — in declared order `commands` → `env_refresh` → `suite` — each `{role, index, argv, exit_code, failure_kind, raw_tail, truncated, diagnostic_status}`. `raw_tail` is a bounded (`DIAGNOSTIC_TAIL_BYTES`) tail sliced from the stage's exact `[log_offset, log_end_offset)` region; `diagnostic_status` is `missing_output` when a failing stage produced no captured bytes (still emitted, with typed context — a failed verdict is never diagnostic-empty). Diagnostics are NOT built on the `log_sha256_mismatch` / `missing_log` integrity branches (an unauthenticated log's tail could be forged); those block on the integrity failure, which is the more severe reason.
+
+**Diagnostic offset-integrity (threat model).** Each failing stage's `raw_tail` is sliced from its recorded `[log_offset, log_end_offset)` region, validated fail-closed against its execution-order neighbours' recorded offsets (`prev.log_end_offset <= log_offset <= log_end_offset <= next.log_offset`, bounded by `[0, len(log)]`); any violation yields an empty tail, never a slice into an adjacent stage. This makes a **single-field** offset tamper (which produces an inconsistent chain) fail closed. The stage-offset table itself is not covered by `log_sha256` (only the log bytes are), so a **multi-field** tamper that keeps the chain internally consistent could reshuffle *which* authenticated log bytes appear in *which* diagnostic. That is deliberately out of scope: every byte involved is already in the SHA-authenticated `verification.log` at the same trust level (an editor of `verification.json` can already read it), and the reshuffle never changes the pass/fail verdict — the authoritative gate is the per-stage `exit_code`, which is checked independently. Signing the offset table would be a separate hardening.
+
+**Redaction posture.** `raw_tail` is a bounded excerpt of bytes ALREADY persisted in full in `verification.log` at the same trust level (a red test suite already writes its output there). Surfacing the tail into the closeout record (which downstream prompts may read) is a real but modest egress widening, not a new capture path. The `DIAGNOSTIC_TAIL_BYTES` cap bounds record size, not disclosure (a secret is tiny) — closeout-diagnostic redaction is a separate, out-of-scope follow-up.
+
+The JSON artifact is written atomically by creating a same-directory temporary file and replacing `verification.json`. Re-running identical command inputs rewrites the same artifact shape and log content, except for timestamps and durations.
+
+Command failures, missing executables, and timeouts are evidence data. They are represented by nonzero `exit_code` values and do not make `run_verification` raise. Programmer errors, such as a missing repo or a run directory outside the repo, raise before evidence is written.
+
+The plan-time validator API is `validate_verification_commands(repo, commands) -> list[ValidationFinding]`. It is read-only and returns structured findings for empty argv, unresolved `argv[0]`, explicit repo-relative path references that do not exist, and cwd/path references that resolve outside the repo.
+
+`load_verification_artifact(path)` validates the persisted artifact and returns `VerificationResult`.
+
+Evidence marked `evidence: operational` can be recorded for operator inspection, but it cannot mark runner-executed verification as passed. A later runner phase must still reduce actual command exit data before claiming verification success.
+
+## Hotfix Consumers
+
+`phase-loop hotfix --init-stub <path>` writes a minimal stub with `objective`
+and `verification_command` fields without creating a run directory.
+
+`phase-loop hotfix --reason <text> --plan <stub-path>` is an emergency
+consumer of the same IF-0-VC-1 evidence path. It creates
+`.phase-loop/runs/<ts>-hotfix-<slug>/`, runs dependency-manifest env refresh,
+the stub verification command, and the effective suite command through
+`run_verification`, then validates the resulting artifact before ledger
+closeout. A passed hotfix event must include `work_unit: hotfix`, the redacted
+reason, plan stub, `verification_artifact_path`, `verification_log_path`, and
+the artifact validation summary. A missing, malformed, tampered, or nonzero
+artifact blocks the hotfix closeout instead of reporting `passed`.
+
+Use hotfix for a single bounded change with no interface freeze. Anything that
+changes interfaces, roadmap scope, or downstream work uses a roadmap phase.

{phase_loop_runtime-0.7.9 → phase_loop_runtime-0.7.10}/src/phase_loop_runtime/advisor_board/harness_mapping.py

@@ -64,15 +64,17 @@ _CODEX_EFFORT: dict[str, str] = {
     "max": "xhigh",
 }
 
-# canonical effort -> grok ``--reasoning-effort`` token. The grok CLI accepts
-# ``none, minimal, low, medium, high, xhigh, max`` (verified via ``grok --help`` /
-# an out-of-range probe), so canonical ``max`` maps straight to grok's own ``max``
-# ceiling — the panel's grok seat runs at grok-4.5's maximum reasoning.
+# canonical effort -> grok ``--reasoning-effort`` token. The grok CLI accepts ONLY
+# ``high | medium | low`` (verified via an out-of-range probe: ``--reasoning-effort max``
+# -> ``unknown effort level 'max'; use one of: high, medium, low``). So canonical ``max``
+# CLAMPS to grok's own ``high`` ceiling — the panel's grok seat runs at grok-4.5's maximum
+# reasoning. (ah#222: a prior literal ``max`` made the grok leg ERROR on every default panel
+# run.) The grokexec/launcher grok effort path is separate (capability_registry) — not fixed here.
 _GROK_EFFORT: dict[str, str] = {
     "low": "low",
     "medium": "medium",
     "high": "high",
-    "max": "max",
+    "max": "high",  # grok has no 'max'/'xhigh'; its ceiling is 'high'
 }
 
 # canonical effort -> the ``(Word)`` token agy/gemini bakes into the model name

{phase_loop_runtime-0.7.9 → phase_loop_runtime-0.7.10}/src/phase_loop_runtime/capability_registry.py

@@ -494,9 +494,15 @@ DEFAULT_PROVIDER_POLICY_CAPABILITIES = {
         supported_efforts=_ALL_EFFORTS,
         unsupported_policy_behavior=_FAIL_CLOSED,
         default_effort="medium",
-        effort_map={effort: effort for effort in _ALL_EFFORTS},
+        # ah#224: grok's `--reasoning-effort` accepts ONLY high/medium/low (a SUBSET of
+        # NORMALIZED_EFFORT_LEVELS). The live clamp is at the CLI boundary
+        # (`launcher._grok_cli_effort`, mirroring codex's `max->xhigh`), which keeps grok
+        # effort-eligible in this layer (all normalized levels remain valid REQUESTS,
+        # translated at emit time). This map is defense-in-depth for the policy-layer
+        # fallback path; it is kept accurate (not identity) rather than lying.
+        effort_map={"minimal": "low", "xhigh": "high", "max": "high"},
         notes=(
-            "grok's `--reasoning-effort` CLI flag accepts a superset of NORMALIZED_EFFORT_LEVELS (its own set adds `none`), so every normalized effort passes through directly with no clamp.",
+            "grok's `--reasoning-effort` CLI flag accepts ONLY high/medium/low (a subset of NORMALIZED_EFFORT_LEVELS); minimal/xhigh/max are clamped to a valid token at the CLI boundary by launcher._grok_cli_effort (like codex's max->xhigh).",
         ),
     ),
     "gemini-api": ProviderPolicyCapability(

{phase_loop_runtime-0.7.9 → phase_loop_runtime-0.7.10}/src/phase_loop_runtime/classifier.py

@@ -16,6 +16,7 @@ from .discovery import (
 )
 from .models import PHASE_STATUSES
 from .provenance import phase_provenance_map, roadmap_sha256, status_provenance_matches
+from .runtime_paths import roadmap_paths_match
 from .state import load_state
 
 
@@ -29,7 +30,7 @@ def classify_phase(repo: Path, roadmap: Path, phase: str) -> str:
         return "unknown"
 
     state = load_state(repo)
-    if state and Path(state.roadmap).expanduser().resolve() == roadmap.resolve() and state.phases.get(phase) in PHASE_STATUSES:
+    if state and roadmap_paths_match(state.repo, state.roadmap, repo, roadmap)[0] and state.phases.get(phase) in PHASE_STATUSES:
         status = state.phases[phase]
         current_phase_sha = phase_provenance_map(roadmap).get(phase)
         entry_phase_sha = state.phase_sha256.get(phase)