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

phase_loop_runtime/_contract_docs/phase-loop/runtime-boundary.md

@@ -0,0 +1,289 @@
+# Phase-Loop Runtime Boundary
+
+This document defines the stable public interface for the phase-loop runtime. Components not listed here are considered internal and subject to change without notice.
+
+Path ownership for the dotfiles-hosted harness substrate is recorded in
+`docs/phase-loop/harness-substrate-manifest.md`. This document defines the
+public runtime contract; the substrate manifest defines which dotfiles paths
+downstream repositories may cite.
+IF-0-SUBSTRATE-1 keeps that citation surface limited to runtime code, CLI
+wrappers, bridge skills, shared runner skills, protocol docs, fixtures, tests,
+scripts, and canonical `.phase-loop/**` state.
+The public skill namespace contract is recorded in
+`docs/phase-loop/harness-skill-matrix.md`; it freezes harness workflow names,
+Pi Agent role-style exceptions, direct route compatibility, and the
+governed-pipeline `.pipeline/skills/**` boundary.
+
+## CLI Interface
+
+The primary entrypoint is `phase-loop` (aliased as `codex-phase-loop`).
+
+### Commands
+
+- `run`: Start or continue phase execution.
+- `resume`: Resume the current phase after a non-terminal exit or blocker.
+- `status`: Show the current phase and loop status.
+- `dry-run`: Parse the roadmap and current plan without executing work.
+- `maintain-skills`: Analyze and propose improvements to harness-local skills based on execution reflections.
+- `sync-skills`: Audit or repair harness-local bridge skills for manual reentry.
+  (DECOUPLE: provided by the dotfiles-profile plugin — see the profile-command
+  note below — not by the generic runtime.)
+- `state`: Inspect the current durable state.
+- `handoff`: Generate a TUI handoff artifact for the current state.
+- `archive-state`: Move the current state to an archive directory.
+- `monitor`: Poll the runtime state and run notification commands on status changes.
+- `version`: Print the installed phase-loop version. The top-level
+  `--version` flag reports the same public version string.
+- `execute <phase>`: Direct bridge invocation for external runners. Supports
+  `--bundle <phase-source-bundle.v1>`, `--output <phase_loop_closeout.v1>`,
+  and `--mode execute|repair|review`. Unsupported modes and invalid bridge
+  inputs are typed non-human contract blockers.
+
+#### Profile-command plugin seam (DECOUPLE)
+
+The dotfiles-domain commands `adoption-bundle`, `sync-skills`, `build-bundle`, and
+`hotfix` are NOT part of the generic runtime surface. They are registered only when
+a profile plugin is loaded, via the `phase_loop_runtime.profile_commands`
+entry-point group (declared by a profile distribution) or the
+`PHASE_LOOP_PROFILE_PLUGINS` opt-in (a comma-separated list of `module:callable`
+specs). A clean wheel install with no profile plugin exposes none of them; the
+in-tree dotfiles profile is `phase_loop_runtime.dotfiles_profile_plugin`. Profiles
+likewise contribute skill source roots via the `phase_loop_runtime.skill_sources`
+group. This is the seam validated by the DECOUPLE Gate-A clean-room harness.
+
+### Core Flags
+
+- `--repo`: Path to the repository (default: `.`).
+- `--roadmap`: Path to the roadmap file.
+- `--phase`: Target phase alias.
+- `--json`: Emit machine-readable JSON output.
+- `--dry-run`: Enable dry-run mode.
+
+### External-Runner Invocation Contract
+
+This is the stable contract an external orchestrator (e.g. governed-pipeline)
+binds to when it delegates a phase to the phase-loop backend. The entrypoint
+name, the bridge subcommand, its argument shape, and the in/out schemas are a
+stability-guaranteed surface; changes are versioned, not silent.
+
+- **Entrypoint:** the console script `phase-loop` (legacy alias
+  `codex-phase-loop`). There is no `dotfiles` command — the runtime ships
+  `phase-loop`/`codex-phase-loop` only. Callers SHOULD resolve the entrypoint
+  configurably (a documented default of `phase-loop`, overridable via an env var
+  such as `PHASE_LOOP_CLI`) rather than hardcoding a command name, so the
+  binding survives non-PATH/venv installs, pinned versions, and renames. Do not
+  invent a repo-named (`dotfiles`) command.
+- **Bridge command:**
+  `phase-loop execute <phase> --bundle <phase-source-bundle.v1> --output <path> [--mode execute|repair|review]`.
+- **Input:** a validated `phase-source-bundle.v1` artifact (`--bundle`). In
+  `pipeline_required` mode the bridge fails closed unless the bundle and its
+  identity/freshness inputs validate together (see Operating Modes).
+- **Output:** exactly one `phase_loop_closeout.v1` JSON file written to
+  `--output`, plus a typed exit code (see Exit Codes). The closeout is the
+  structured result; callers read it rather than parsing the event ledger.
+- **Capability / version negotiation:** callers gate on `phase-loop --version`
+  (top-level `--version` reports the public version string) against a documented
+  version floor before invoking; when the entrypoint is absent or below the
+  floor, the caller degrades gracefully (e.g. artifact-only ingestion) instead
+  of failing the run.
+
+## Operating Modes
+
+Standalone phase-loop use is the default local operator path. `run`, `resume`,
+`status`, `dry-run`, and manual `codex-plan-phase` / `codex-execute-phase`
+workflows remain valid without governed-pipeline, `.pipeline/**`, Portal,
+Greenfield, a source bundle, credentials, Host bootstrap, Shell config, shell
+profile sourcing, SSH setup, MCP gateway setup, generic 1Password setup,
+provider-supplied payloads, or local environment contents. `.phase-loop/` is the
+canonical runtime state surface; `.codex/phase-loop/` is a legacy read fallback
+only when canonical state is absent.
+
+`pipeline_optional` runs may consume Pipeline source-bundle metadata when an
+external orchestrator supplies it, but missing Pipeline metadata does not make
+a legacy standalone phase plan invalid.
+
+`pipeline_required` direct bridge invocation must fail closed before execution
+unless these inputs validate together: bundle path, bundle SHA-256,
+Pipeline phase id or alias, roadmap identity, protected-source entries,
+protected-source file hashes, and source-bundle freshness. Governed Pipeline
+owns adoption, source-bundle emission, canonical refresh, replan, closeout
+ingest, Greenfield reduction, and Portal projection. Governed-pipeline owns
+canonical source-truth refresh, source-bundle emission,
+protected-source freshness, scheduling, closeout ingest, Greenfield reduction,
+and Portal projection; dotfiles consumes the supplied bundle and emits redacted
+closeout metadata.
+Governed-pipeline also owns canonical spec adoption, archive manifests,
+managed mirror manifests, mirror writes, source-truth reconciliation, canonical
+refresh, replan, and preflight block decisions. Dotfiles may echo validated
+metadata-only adoption roles in closeout, but it does not decide canonical
+adoption, archive membership, mirror refresh, or unmanaged spec promotion.
+
+Standalone dotfiles discovery treats root `specs/**` as the default
+human-visible future-spec intake root when no phase plan, source bundle, or
+repo-local config overrides it. Legacy or project-specific seed roots such as
+`Specs/**` are explicit input roots only, not automatic future-spec storage
+roots. See `docs/phase-loop/spec-discovery-roots.md`.
+
+## Python API
+
+The following modules under `phase_loop_runtime.*` are considered public:
+
+- `phase_loop_runtime.cli`: CLI entrypoint and parser definition.
+- `phase_loop_runtime.discovery`: Roadmap and repository resolution.
+- `phase_loop_runtime.handoff`: TUI handoff generation and metadata.
+- `phase_loop_runtime.models`: Core data models, schemas, and literals.
+- `phase_loop_runtime.maintenance`: Skill maintenance and improvement logic.
+- `phase_loop_runtime.observability`: Notification and monitoring utilities.
+- `phase_loop_runtime.profiles`: Model and effort profile definitions.
+- `phase_loop_runtime.reconcile`: State and roadmap reconciliation.
+- `phase_loop_runtime.render`: Text and JSON rendering for CLI output.
+- `phase_loop_runtime.runtime_paths`: Canonical `.phase-loop/` path helpers and legacy
+  `.codex/phase-loop/` read-fallback helpers.
+- `phase_loop_runtime.runner`: The main loop execution engine.
+- `phase_loop_runtime.state_ops`: State inspection and archiving operations.
+- `phase_loop_runtime.state`: Durable state persistence (JSON).
+
+## Artifacts and Paths
+
+- `.phase-loop/`: Canonical runtime directory.
+- `.phase-loop/state.json`: Current loop state.
+- `.phase-loop/events.jsonl`: Append-only event ledger.
+- `.phase-loop/runs/<run-id>/`: Artifacts for a specific run.
+- `.codex/phase-loop/`: Legacy compatibility root. It may be read only when
+  canonical `.phase-loop/` state is absent; new writes target `.phase-loop/`.
+- `plans/phase-plan-*.md`: Phase-specific execution plans.
+- `specs/phase-plans-*.md`: Multi-phase roadmaps.
+- `specs/**`: Standalone future-spec discovery and advisory intake root unless
+  a phase plan, source bundle, or repo-local config overrides it.
+- `Specs/**`: Legacy or project-specific seed input root only when explicitly
+  named by a phase plan, source bundle, or repo-local config.
+
+## Scheduler-Owned Lane Inputs
+
+The runtime may consume scheduler-owned lane assignment metadata, but does not
+own scheduling, runtime ledger policy, worktree allocation, merge reduction, or
+authority digests. The accepted assignment surface is lane id, wave id,
+worktree path, base SHA, isolation mode, owned files, read-only refs, harness
+route, model, effort, and fallback reason. Greenfield authority refs and
+governed-pipeline scheduling data remain external inputs, not dotfiles-owned
+runtime authority.
+
+`--lane-scheduler concurrent` launches scheduler-approved ready waves only
+when every writer is `parallel_safe`, writable ownership is disjoint, reducer
+lanes are excluded, and each writer has a `git_worktree` assignment at the
+current base SHA. `--lane-scheduler serialized` and the default coarse phase
+path remain compatibility modes and may run on the main worktree without
+assignment metadata.
+
+Closeout metadata may report lane identity, wave identity, worktree identity,
+verification status, changed paths, source-truth impact categories, advisory
+canonical-refresh reason codes, source-bundle identity, protected-source roles,
+and redacted evidence refs. Evidence refs are artifact paths and digests only;
+raw spec bodies, raw diffs, raw transcripts, credential material, private
+files, local environment contents, and provider tokens are outside the public
+runtime contract.
+
+## Bridge Fixture Boundary
+
+Dotfiles owns the native v1 bridge fixtures at
+`vendor/phase-loop-runtime/tests/fixtures/phase_loop_pipeline_bridge/**`. These fixtures are
+metadata-only examples for `phase_loop_closeout.v1` outcomes, including
+complete, blocked, stale source bundle, failed verification, human-required,
+malformed, standalone-no-bundle, and canonical-refresh-recommended cases.
+Native fixture JSON uses nested `automation`, `artifacts`, `verification`,
+`blocker`, `source_bundle`, and `source_truth_impact` objects and does not
+include deprecated root-level v5 automation aliases.
+DFADOPTHINTS fixtures cover standalone unmanaged spec hints,
+pipeline-required adoption roles, managed mirror specs, archive manifests,
+canonical refresh recommendations, and malformed redaction rejection.
+
+Governed-pipeline may mirror those fixtures under the downstream mirror location
+`packages/pipeline-runtime/test/fixtures/phase-loop-bridge/` for its own
+ingest tests. That mirror path is a downstream consumer and not a dotfiles write target.
+Governed-pipeline owns mirror updates, closeout ingest, canonical refresh,
+replan, and preflight block decisions; those decisions are governed-pipeline-owned.
+
+DFTRUTHSOAK is the final source-truth reconciliation soak for this dotfiles
+runtime boundary. Its evidence surface is local and metadata-only: standalone
+closeout, pipeline-required closeout, stale-input blockers, source-truth
+advisory hints, bridge fixtures, and downstream mirror refs. Portal-facing
+evidence remains governed-pipeline projection metadata, not Portal lifecycle,
+database, or contract writes from dotfiles. Greenfield-facing evidence remains
+path and digest authority refs mediated by governed-pipeline, not Greenfield
+reducer or authority-file writes from dotfiles.
+
+## Skill and Prompt Guardrails
+
+Operator skills and generated prompts must preserve standalone dotfiles use:
+planning, execution, bridge, and shared CLI runner workflows remain valid
+without governed-pipeline, Portal, Greenfield, `.pipeline/**`, or a source
+bundle. Pipeline metadata is additive and may be copied into plan frontmatter
+only from a validated source bundle or explicit `pipeline_required` run
+context.
+Harness workflow skill names are governed by
+`docs/phase-loop/harness-skill-matrix.md`. That matrix is the public contract
+for `<harness>-<workflow>` skill names, the Pi Agent role-style exceptions, and
+compatibility for direct Codex, Gemini, OpenCode, and Claude Code `claude -p`
+routes.
+Collaborator consumption of the runtime and harness workflow skill packs is
+documented in `docs/phase-loop/collaborator-bootstrap.md`. That document is the
+install citation surface for downstream repos; it does not expand the runtime
+boundary to host bootstrap, owner dotfiles, personal credentials, terminal
+state, or direct writes to governed-pipeline, Portal, Greenfield, ReGenesis, or
+`.pipeline/**`.
+
+Portal and Greenfield examples are governed-pipeline-mediated boundaries:
+Portal projection, governed-pipeline closeout ingest, and Greenfield metadata-only authority refs are not direct dotfiles write targets. Skills and
+prompts must forbid inferred reads or writes to `.pipeline/**`,
+governed-pipeline specs, Portal contracts, Greenfield authority files, private
+evidence, raw data, raw source evidence, credentials, provider-supplied data, and legacy `.codex/phase-loop/` state unless the active plan and source bundle explicitly
+own the exact path or glob.
+
+DFPARSOAK is the release-gate exercise of this boundary. Its metadata-only
+`GFPARSOAK` and `GPPARSOAK` inputs cite repo-relative receipt paths and sha256
+digests only. Its local scheduler-owned git-worktree wave records Pi Agent,
+Claude Code CLI, Codex, and Gemini route metadata while keeping redacted
+evidence as handles or hashes and preserving no sibling-repo mutation.
+
+## Exit Codes
+
+- `0`: Success (or completion in `run`/`resume`).
+- `1`: General failure or blocked status.
+- `2`: Ambiguous roadmap selection (requires human intervention).
+
+## Completeness for Extraction
+
+This inventory represents the full set of public interfaces required for the vendored package `phase-loop-runtime` to operate as a future standalone repository if publication is needed later. Governed-pipeline and other downstream consumers may use the documented CLI, schema, fixture, and state surfaces through the vendored package. Any tool or service consuming phase-loop should limit its integration to these documented surfaces.
+The harness substrate manifest separates those public surfaces from broader
+dotfiles environment normalization such as host bootstrap, shell config,
+terminal config, SSH, generic 1Password setup, MCP gateway setup, and unrelated
+editor config.
+DFFAKESMOKE substrate receipt fields for downstream Pipeline consumption are
+documented in `docs/phase-loop/dffakesmoke-substrate-receipt.md`.
+
+The standalone identity must preserve the Python import package `phase_loop_runtime`,
+the neutral `phase-loop` command, and the backward-compatible `codex-phase-loop`
+alias. `phase-loop` and `codex-phase-loop` remain separate entrypoints over the
+same parser; dotfiles bootstrap installs the vendored package in editable mode.
+
+Package-like use of the public modules, parser construction, status rendering,
+direct bridge diagnostics, and runtime path helpers must work from
+`vendor/phase-loop-runtime` without shell profile sourcing,
+1Password, Vercel, Supabase, or other dotfiles-specific credentials, and
+without ambient `~/.codex` state.
+
+- **Contract Coverage**: 100% of the `phase_loop_closeout.v1` schema is supported.
+- **CLI Parity**: The CLI provides full lifecycle management (`run`,
+  `resume`, `status`, `dry-run`, `maintain-skills`, `sync-skills`, `state`,
+  `handoff`, `archive-state`, `monitor`, and `version`) plus deterministic
+  direct bridge invocation through `execute <phase>`.
+- **Schema Stability**: All machine-readable artifacts (JSON/JSONL) follow the frozen protocol.
+
+## DFPARSOAK Integrated Soak
+
+DFPARSOAK publishes the final integrated substrate receipt at
+`docs/phase-loop/dfparsoak-receipt.md` and the local execution runbook at
+`docs/phase-loop/dfparsoak-runbook.md`. Those artifacts freeze the dotfiles
+side of lane, wave, worktree, harness route, model, effort, fallback, and
+redacted evidence metadata while keeping governed-pipeline as scheduler and
+closeout-ingest authority.

phase_loop_runtime/_contract_docs/phase-loop/spec-discovery-roots.md

@@ -0,0 +1,47 @@
+# Phase-Loop Spec Discovery Roots
+
+Standalone dotfiles phase-loop runs use root `specs/**` as the default
+human-visible future-spec discovery root when no phase plan, source bundle, or
+repo-local config names a different root.
+
+Legacy or project-specific seed roots such as `Specs/**` are explicit input
+roots only. They can be cited by a phase plan or validated source bundle as
+seed material, but they are not automatic storage roots for future accepted
+specs. Accepted future specs should normalize toward root `specs/**` for later
+governed-pipeline intake.
+
+Governed-pipeline owns canonical spec adoption, `.pipeline/specs/**`,
+archive manifests, managed mirror manifests, mirror writes, source-bundle
+emission, canonical refresh, source-truth reconciliation, replan, and preflight
+block decisions; those decisions are governed-pipeline-owned. Dotfiles may consume validated metadata and echo
+metadata-only adoption roles such as `active_canonical_spec`,
+`managed_mirror_file`, `mirror_manifest`, `archive_manifest`, and
+`unmanaged_spec_input`, but it does not decide whether a spec is canonical,
+archived, mirrored, refreshed, or blocked.
+
+Closeout and docs evidence stays metadata-only. Do not include raw spec bodies,
+raw diffs, provider payloads, credentials, local environment values, private
+evidence, or absolute private paths as runtime evidence.
+
+Closeout may cite repo-relative spec roots, changed-path categories, SHA-256
+hashes, source-bundle identity, protected-source roles, advisory reason codes,
+and evidence-ref paths. Standalone root `specs/**` changes are advisory
+`unmanaged_spec` future input by default. Managed root mirror and archived spec
+classification comes only from validated source-bundle metadata. Dotfiles emits
+`canonical_refresh_recommended` and reason codes as metadata-only hints;
+governed-pipeline decides whether those hints trigger refresh, mirror, archive,
+replan, or block actions.
+
+DFADOPTBRIDGE fixtures apply the same rule to governed-pipeline v11 adoption
+coverage. `dfadoptbridge_unmanaged_spec_input.json` represents root `specs/**`
+as unmanaged spec input metadata, while mirror manifest and archive manifest
+fixtures represent only repo-relative paths, SHA-256 fields, protected-source
+roles, changed-path categories, advisory reason codes, and evidence refs.
+
+DFADOPTSOAK keeps that boundary as a release gate. Standalone root `specs/**`
+changes are advisory unmanaged-spec hints. Non-default roots such as `Specs/**`
+remain non-advisory unless a phase plan, validated source bundle, or repo-local
+configuration explicitly names the root. Explicit intake roles such as
+`adapter_configured_intake_root` and `legacy_specs_bundle` classify those
+repo-relative paths as unmanaged spec input metadata only; they do not authorize
+dotfiles to read raw private source bytes or write downstream mirror artifacts.

phase_loop_runtime/_contract_docs/phase-loop/substrate-soak-governed-pipeline.md

@@ -0,0 +1,42 @@
+# SUBSTRATESOAK Governed Pipeline v25 Compatibility
+
+SUBSTRATESOAK proves compatibility through dotfiles-local fixtures and
+metadata-only closeout examples. The fixture matrix lives at
+`vendor/phase-loop-runtime/tests/fixtures/phase_loop_pipeline_bridge/substratesoak_*.json`,
+and dotfiles owns only the local fixture source plus the tests that validate
+that source.
+
+Governed Pipeline owns mirror regeneration. Governed Pipeline owns closeout ingest.
+Dotfiles does not take ownership of downstream mirror refresh,
+canonical adoption, archive, replan, preflight, or Portal projection decisions.
+The compatibility receipt records no sibling repository mutation.
+
+## Metadata Contract
+
+Governed Pipeline may consume only metadata fields from the local fixture
+matrix:
+
+- pipeline mode
+- source bundle path
+- source bundle SHA-256
+- phase id
+- protected-source roles
+- artifact paths
+- evidence refs
+- changed-path categories
+- verification status
+- blocker class
+- canonical-refresh advisory reason codes
+
+Those fields are identifiers, hashes, classifications, or redacted references.
+They are not permission to read source bundle bytes, protected source contents,
+private evidence, or downstream runtime state.
+
+## Boundaries
+
+The downstream mirror location
+`packages/pipeline-runtime/test/fixtures/phase-loop-bridge/`, governed-pipeline specs,
+`.pipeline/**`, sibling repositories, Raw evidence, Provider payloads,
+credentials, and local environment values are outside the dotfiles write and
+read boundary for this phase. Governed Pipeline remains the owner for any
+derived mirror copy or closeout ingestion behavior.

phase_loop_runtime/_contract_docs/phase-loop/substrate-soak-portal-projection.md

@@ -0,0 +1,34 @@
+# SUBSTRATESOAK Portal v40 Projection Boundary
+
+Portal v40 display evidence is projection-mediated. Dotfiles may publish only
+Governed Pipeline-mediated metadata for the Portal display path; it does not
+publish Portal runtime output.
+
+Allowed display metadata:
+
+- phase alias
+- terminal status
+- verification status
+- blocker class
+- human-required flag
+- changed paths
+- artifact refs
+- evidence ref hashes
+- source-bundle identity
+- protected-source roles
+- advisory reason codes
+
+The BAML source at
+`vendor/phase-loop-runtime/src/phase_loop_runtime/baml_src/emit_phase_closeout.baml` remains the schema
+authority. This document cites schema-adjacent field names only so the Portal
+projection can stay aligned with Governed Pipeline ingest without creating a
+second schema.
+
+## Denied Dotfiles Outputs
+
+Portal routing layer, Portal display layer, database storage, projection payloads,
+lifecycle state, Portal contracts, auth state, Raw evidence, Provider payloads,
+credentials, local environment values, host-specific paths, `.pipeline/**`, and
+legacy .codex/phase-loop/** are outside the SUBSTRATESOAK dotfiles output
+surface. Any Portal-visible value must arrive through Governed Pipeline
+projection using redacted metadata and hashes.

phase_loop_runtime/_contract_docs/phase-loop/substrate-soak-regenesis.md

@@ -0,0 +1,29 @@
+# SUBSTRATESOAK ReGenesis v46 Support Surface
+
+ReGenesis v46 may cite these dotfiles-owned surfaces:
+
+- phase-loop runtime
+- codex-phase-loop alias
+- harness workflow skill packs
+- collaborator bootstrap docs
+- runtime boundary docs
+- substrate manifest docs
+- bridge fixtures
+- metadata-only closeout surfaces
+
+The supported adoption path is through Governed Pipeline metadata and fixture
+projection. Dotfiles provides citation material and local compatibility tests;
+Governed Pipeline owns downstream adoption and mirror behavior.
+
+## Out of Scope
+
+Full owner dotfiles bootstrap is out of scope. Shell profile sourcing is out of scope.
+SSH setup is out of scope. MCP setup is out of scope. Terminal or Zellij setup is out of scope.
+Generic 1Password setup is out of scope.
+
+Sibling repository mutation is out of scope. Direct ReGenesis changes are out of scope.
+Direct Governed Pipeline changes are out of scope. Direct Portal changes are out of scope.
+Direct Greenfield changes are out of scope. .pipeline/** changes are out of scope.
+Raw evidence is out of scope. Provider payloads are out of scope.
+Credentials are out of scope. Local environment values are out of scope.
+Legacy .codex/phase-loop/** changes are out of scope.

phase_loop_runtime/_contract_docs/phase-loop/substrate-soak-report.md

@@ -0,0 +1,32 @@
+# SUBSTRATESOAK Reducer Receipt
+
+SUBSTRATESOAK reduces SL-0 through SL-3 against IF-0-SUBSTRATESOAK-1:
+cross-repo fixture matrix proves compatibility with Governed Pipeline v25
+without sibling repo mutation.
+
+## Exit Criteria
+
+| Criterion | Evidence |
+| --- | --- |
+| Fixture matrix covers standalone, `pipeline_optional`, `pipeline_required`, stale bundle, unmanaged spec hint, closeout complete, verification failed, human-required, and redaction violation cases. | SL-0 fixture matrix and `PYTHONPATH=vendor/phase-loop-runtime/src python -m pytest vendor/phase-loop-runtime/tests/test_phase_loop_pipeline_bridge.py -k substratesoak` |
+| Governed Pipeline v25 mirror fixtures can be regenerated by Governed Pipeline and are not written by dotfiles. | SL-1 receipt and `PYTHONPATH=vendor/phase-loop-runtime/src python -m pytest vendor/phase-loop-runtime/tests/test_phase_loop_substrate_soak_governed.py` |
+| Portal v40 evidence remains metadata-only and projection-mediated through Governed Pipeline. | SL-2 receipt and `PYTHONPATH=vendor/phase-loop-runtime/src python -m pytest vendor/phase-loop-runtime/tests/test_phase_loop_substrate_soak_portal.py` |
+| ReGenesis v46 docs state supported runtime, skill, fixture, and closeout metadata surfaces. | SL-3 support doc and `PYTHONPATH=vendor/phase-loop-runtime/src python -m pytest vendor/phase-loop-runtime/tests/test_phase_loop_substrate_soak_docs.py` |
+| The phase writes no sibling repo, governed-pipeline mirror path, Portal, Greenfield, ReGenesis, `.pipeline/**`, credential, Raw evidence, Provider payload, local environment value, private input, ignored output, personal host bootstrap, or legacy `.codex/phase-loop/**` target. | SL-0 through SL-3 negative assertions and grep checks from the phase plan |
+| .phase-loop/ remains the authoritative runner state source for this phase; legacy `.codex/phase-loop/` files are not used to block or supersede canonical state. | This reducer cites canonical runner state only and does not read or mutate legacy state |
+
+## Verification Commands
+
+```bash
+PYTHONPATH=vendor/phase-loop-runtime/src python -m pytest vendor/phase-loop-runtime/tests/test_phase_loop_pipeline_bridge.py -k substratesoak
+PYTHONPATH=vendor/phase-loop-runtime/src python -m pytest vendor/phase-loop-runtime/tests/test_phase_loop_substrate_soak_governed.py
+PYTHONPATH=vendor/phase-loop-runtime/src python -m pytest vendor/phase-loop-runtime/tests/test_phase_loop_substrate_soak_portal.py
+PYTHONPATH=vendor/phase-loop-runtime/src python -m pytest vendor/phase-loop-runtime/tests/test_phase_loop_substrate_soak_docs.py
+PYTHONPATH=vendor/phase-loop-runtime/src python -m pytest vendor/phase-loop-runtime/tests/test_phase_loop_pipeline_bridge.py vendor/phase-loop-runtime/tests/test_phase_loop_substrate_soak_governed.py vendor/phase-loop-runtime/tests/test_phase_loop_substrate_soak_portal.py vendor/phase-loop-runtime/tests/test_phase_loop_substrate_soak_docs.py
+```
+
+## IF Gate
+
+IF-0-SUBSTRATESOAK-1 is produced when the fixture matrix, Governed Pipeline
+receipt, Portal projection receipt, ReGenesis support doc, and this reducer
+receipt all pass their targeted and whole-phase verification commands.

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

@@ -0,0 +1,52 @@
+# 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) -> VerificationResult` writes two sibling files under the supplied run directory:
+
+- `verification.json`
+- `verification.log`
+
+`verification.json` uses schema version 1 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`.
+
+`verification.log` stores raw combined stdout and stderr from the recorded subprocesses. `log_offset` is the byte offset for each command's output. `log_sha256` is the SHA-256 digest of the final log bytes.
+
+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/_test_fixtures/evidence-audit-calibration/borderline/borderline-mixed-signals/commands.txt

@@ -0,0 +1,2 @@
+Commands are specific and plausible, but the score series is close enough to
+need operator review before trusting the closeout.

phase_loop_runtime/_test_fixtures/evidence-audit-calibration/borderline/borderline-mixed-signals/manifest.json

@@ -0,0 +1,16 @@
+{
+  "fixture_id": "borderline-mixed-signals",
+  "category": "borderline",
+  "expected_verdict_class": "uncertain",
+  "expected_confidence": 0.56,
+  "expected_artifact_characteristics": "Ambiguous evidence with one suspicious metric but concrete command and file details.",
+  "sample_artifact_paths": ["mixed.json", "commands.txt"],
+  "rationale": "Mixed real and suspicious signals should support threshold tuning.",
+  "tier2_signal_summary": {
+    "kind": "calibration_borderline",
+    "signals": ["one low-variance metric", "specific commands", "distinct files"]
+  },
+  "estimated_input_tokens": 730,
+  "estimated_output_tokens": 215,
+  "estimated_cost_usd": 0.0075
+}

phase_loop_runtime/_test_fixtures/evidence-audit-calibration/borderline/borderline-mixed-signals/mixed.json

@@ -0,0 +1,5 @@
+{
+  "scores": [0.870, 0.871, 0.869, 0.872],
+  "changed_files": ["src/a.py", "tests/test_a.py"],
+  "commands": ["python3 -m unittest tests.test_a", "git diff --check -- src/a.py tests/test_a.py"]
+}

phase_loop_runtime/_test_fixtures/evidence-audit-calibration/borderline/borderline-provider-timeout/manifest.json

@@ -0,0 +1,16 @@
+{
+  "fixture_id": "borderline-provider-timeout",
+  "category": "borderline",
+  "expected_verdict_class": "uncertain",
+  "expected_confidence": 0.25,
+  "expected_artifact_characteristics": "Ambiguous provider behavior where the wrapper should preserve uncertainty instead of asserting fake.",
+  "sample_artifact_paths": ["timeout-note.txt"],
+  "rationale": "Timeouts should produce uncertain fallback metadata, not hard classifications.",
+  "tier2_signal_summary": {
+    "kind": "calibration_borderline",
+    "signals": ["provider timeout", "no parsed judgment", "operator review"]
+  },
+  "estimated_input_tokens": 600,
+  "estimated_output_tokens": 190,
+  "estimated_cost_usd": 0.0062
+}

phase_loop_runtime/_test_fixtures/evidence-audit-calibration/borderline/borderline-provider-timeout/timeout-note.txt

@@ -0,0 +1,2 @@
+The provider request timed out after the audit wrapper sent a bounded sample.
+This is operationally ambiguous and should remain uncertain.

phase_loop_runtime/_test_fixtures/evidence-audit-calibration/borderline/borderline-redacted-summary/manifest.json

@@ -0,0 +1,16 @@
+{
+  "fixture_id": "borderline-redacted-summary",
+  "category": "borderline",
+  "expected_verdict_class": "uncertain",
+  "expected_confidence": 0.52,
+  "expected_artifact_characteristics": "Ambiguous metadata-only evidence where redaction hides details needed for a decisive judgment.",
+  "sample_artifact_paths": ["redacted-summary.json"],
+  "rationale": "Redacted summaries can be valid but should not be over-classified without corroboration.",
+  "tier2_signal_summary": {
+    "kind": "calibration_borderline",
+    "signals": ["metadata-only", "redacted details", "operator review"]
+  },
+  "estimated_input_tokens": 650,
+  "estimated_output_tokens": 205,
+  "estimated_cost_usd": 0.0067
+}

phase_loop_runtime/_test_fixtures/evidence-audit-calibration/borderline/borderline-redacted-summary/redacted-summary.json

@@ -0,0 +1,6 @@
+{
+  "phase": "PRIVATECHECK",
+  "verification_status": "passed",
+  "evidence_refs": ["redacted-metadata:artifact-present", "redacted-metadata:hash-present"],
+  "raw_payload_available": false
+}

phase_loop_runtime/_test_fixtures/evidence-audit-calibration/borderline/borderline-small-sample/manifest.json

@@ -0,0 +1,16 @@
+{
+  "fixture_id": "borderline-small-sample",
+  "category": "borderline",
+  "expected_verdict_class": "uncertain",
+  "expected_confidence": 0.48,
+  "expected_artifact_characteristics": "Ambiguous evidence with a small sample and insufficient corroborating artifacts.",
+  "sample_artifact_paths": ["sample.json"],
+  "rationale": "Too little evidence for a hard real or fake classification.",
+  "tier2_signal_summary": {
+    "kind": "calibration_borderline",
+    "signals": ["small sample", "moderate similarity", "limited context"]
+  },
+  "estimated_input_tokens": 640,
+  "estimated_output_tokens": 200,
+  "estimated_cost_usd": 0.0068
+}

phase_loop_runtime/_test_fixtures/evidence-audit-calibration/borderline/borderline-small-sample/sample.json

@@ -0,0 +1,7 @@
+{
+  "checks": [
+    {"name": "home", "similarity": 0.91},
+    {"name": "settings", "similarity": 0.89}
+  ],
+  "note": "Only two samples were captured."
+}

phase_loop_runtime/_test_fixtures/evidence-audit-calibration/borderline/borderline-threshold-edge/edge.txt

@@ -0,0 +1,2 @@
+The evidence is plausible and detailed, but confidence is deliberately below
+the default 0.85 threshold for calibration tuning.