phase-loop-runtime 0.3.0__tar.gz → 0.4.0__tar.gz

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.3.0
+Version: 0.4.0
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author: ViperJuice
 License-Expression: Apache-2.0
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: baml-py<0.223,>=0.222
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: PyYAML<7,>=6
-Requires-Dist: consiliency-contract<0.7,>=0.6.3
+Requires-Dist: consiliency-contract<0.7,>=0.6.5
 Requires-Dist: jsonschema<5,>=4
 Requires-Dist: tomli<3,>=2; python_version < "3.11"
 
@@ -104,3 +104,50 @@ The closeout verdict is runner-authoritative: when the runner rejects a child's
 closeout, the persisted `terminal-summary.json` reflects the runner's blocking verdict
 (the child's self-reported `complete`/`passed` is not overlaid back), preventing a
 stale "complete" summary from reconcile-skipping the work on the next run.
+
+## Conformance library (one library, two roles)
+
+`phase_loop_runtime.conformance` is the named, stable, importable surface for the
+deterministic `.consiliency/` conformance evaluator. It is a re-export (not a
+re-implementation) of the same function the actor already runs, so an **external
+CR-fence** — in gp CI, a git-host pre-merge check, anywhere — can import and run
+the identical check:
+
+```python
+from phase_loop_runtime.conformance import scan_consiliency_gates
+
+verdict = scan_consiliency_gates("/path/to/repo")   # {"status": "passed" | "warn" | "blocked" | "skipped", "gates": {...}, ...}
+```
+
+The surface also exposes the pure cores (`evaluate_git_discipline`,
+`self_heal_partition`, `evaluate_governance_scope`) for consumers that already
+hold the injected facts.
+
+**Two roles, one library.** This is meant to be mounted BOTH as the actor-side
+self-check (a pre-PR sanity pass the author runs locally) AND as the
+authoritative CR-fence (the real validator). The actor-side result is **never
+authoritative** — the fence always re-runs the check itself. Because it is the
+same function versioned with the same vendored `consiliency_contract`, the honest
+actor sees exactly the verdict the fence will; a stale or dishonest actor result
+simply does not matter.
+
+**Scope.** This surface asserts the L0 **shape + governance** tier only. The
+cert-schema tier and authority/provenance verification are explicitly out of
+scope (delegated downstream / to gp).
+
+### `consiliency-ingest --check-only`
+
+`--check-only` decouples "run the check" from "is this repo adopted". It is
+strictly read-only (never shapes; ignores `--adopt`). It makes the exit code
+verdict-significant so a pre-PR actor is never misled into reading a no-op — or a
+failing verify — as a pass:
+
+| Repo state | mode | exit |
+|---|---|---|
+| adopted, verify clean (or `warn`) | `verify` | `0` |
+| adopted, gate scan `blocked` | `verify` | `1` |
+| un-adopted (no `.consiliency/manifest`) | `not-adopted` | `3` |
+| usage error | — | `2` |
+
+The plain (non-`--check-only`) path is unchanged — it keeps the silent green
+`skipped` no-op on an un-adopted repo and its existing exit `0`.

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/README.md

@@ -80,3 +80,50 @@ The closeout verdict is runner-authoritative: when the runner rejects a child's
 closeout, the persisted `terminal-summary.json` reflects the runner's blocking verdict
 (the child's self-reported `complete`/`passed` is not overlaid back), preventing a
 stale "complete" summary from reconcile-skipping the work on the next run.
+
+## Conformance library (one library, two roles)
+
+`phase_loop_runtime.conformance` is the named, stable, importable surface for the
+deterministic `.consiliency/` conformance evaluator. It is a re-export (not a
+re-implementation) of the same function the actor already runs, so an **external
+CR-fence** — in gp CI, a git-host pre-merge check, anywhere — can import and run
+the identical check:
+
+```python
+from phase_loop_runtime.conformance import scan_consiliency_gates
+
+verdict = scan_consiliency_gates("/path/to/repo")   # {"status": "passed" | "warn" | "blocked" | "skipped", "gates": {...}, ...}
+```
+
+The surface also exposes the pure cores (`evaluate_git_discipline`,
+`self_heal_partition`, `evaluate_governance_scope`) for consumers that already
+hold the injected facts.
+
+**Two roles, one library.** This is meant to be mounted BOTH as the actor-side
+self-check (a pre-PR sanity pass the author runs locally) AND as the
+authoritative CR-fence (the real validator). The actor-side result is **never
+authoritative** — the fence always re-runs the check itself. Because it is the
+same function versioned with the same vendored `consiliency_contract`, the honest
+actor sees exactly the verdict the fence will; a stale or dishonest actor result
+simply does not matter.
+
+**Scope.** This surface asserts the L0 **shape + governance** tier only. The
+cert-schema tier and authority/provenance verification are explicitly out of
+scope (delegated downstream / to gp).
+
+### `consiliency-ingest --check-only`
+
+`--check-only` decouples "run the check" from "is this repo adopted". It is
+strictly read-only (never shapes; ignores `--adopt`). It makes the exit code
+verdict-significant so a pre-PR actor is never misled into reading a no-op — or a
+failing verify — as a pass:
+
+| Repo state | mode | exit |
+|---|---|---|
+| adopted, verify clean (or `warn`) | `verify` | `0` |
+| adopted, gate scan `blocked` | `verify` | `1` |
+| un-adopted (no `.consiliency/manifest`) | `not-adopted` | `3` |
+| usage error | — | `2` |
+
+The plain (non-`--check-only`) path is unchanged — it keeps the silent green
+`skipped` no-op on an un-adopted repo and its existing exit `0`.

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phase-loop-runtime"  # PyPI dist name; NOT "agent-harness" (an unrelated third-party PyPI project)
-version = "0.3.0"
+version = "0.4.0"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -32,7 +32,17 @@ dependencies = [
     # < 0.6.2 stays safe; the floor guarantees the teeth are present. Warn-default remains;
     # human_required is never set. (0.6.0 shipped self-inconsistent version refs -> fixed in
     # 0.6.1, contract PR #18.)
-    "consiliency-contract>=0.6.3,<0.7",
+    #
+    # PIN (PSCAT-PL, roadmap Phase 2B): floor at 0.6.5 -- ships the
+    # `protected_source_categories` registry that OWNS the coarse
+    # protected_source_category vocabulary (the six pre-existing buckets +
+    # `governance_contracts`). phase-loop reads that registry via
+    # `consiliency_contract.load_registry` and validates against it as the SoT
+    # (models.py `protected_source_categories()`), replacing the hardcoded enum.
+    # Registry-present is authoritative; the runtime still degrades to the legacy
+    # six-tuple if a caller runs an older contract (no hard crash), but this floor
+    # guarantees the contract-owned vocabulary (incl. governance_contracts) is live.
+    "consiliency-contract>=0.6.5,<0.7",
     "jsonschema>=4,<5",
     # Advisor Board config loader (ABDREG) parses advisor-boards.toml. tomllib is
     # stdlib on 3.11+; on the 3.10 requires-python floor it is absent, so pull in

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/src/phase_loop_runtime/__init__.py

@@ -3,6 +3,7 @@
 __all__ = [
     "__version__",
     "cli",
+    "conformance",
     "discovery",
     "handoff",
     "maintenance",
@@ -17,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/src/phase_loop_runtime/_contract_docs/phase-loop/runtime-boundary.md

@@ -129,6 +129,7 @@ roots. See `docs/phase-loop/spec-discovery-roots.md`.
 The following modules under `phase_loop_runtime.*` are considered public:
 
 - `phase_loop_runtime.cli`: CLI entrypoint and parser definition.
+- `phase_loop_runtime.conformance`: Named conformance-check surface (the six L0 consiliency gates) for actor-side self-check and the CR-fence.
 - `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-0.3.0 → phase_loop_runtime-0.4.0}/src/phase_loop_runtime/advisor_board/CONTRACTS.md

@@ -264,11 +264,14 @@ building `artifact: str` forces the caller to hold the whole (20k+ token) bundle
 its own context. `artifact_ref` / `brief_ref` promote that to by-reference ingestion:
 the caller passes a PATH and the runtime reads it.
 
-- **Entry points.** `invoke_panel`, `invoke_board`, and `invoke_panel_request` accept
-  keyword-only `artifact_ref: str | Sequence[str] | None` and `brief_ref: str | None`
+- **Entry points.** `invoke_panel` and `invoke_board` accept keyword-only
+  `artifact_ref: str | Sequence[str] | None` and `brief_ref: str | None`
   (default-valued additive extensions to the frozen signatures — back-compat, like
-  `models` / `max_concurrency`). The artifact is resolved at the TOP of the entry
-  point so timeout scaling, staging, and metadata all see the resolved content.
+  `models` / `max_concurrency`). `invoke_panel_request` consumes
+  `PanelRequest.artifact_ref` but deliberately does not define `PanelRequest.brief_ref`
+  in this contract; callers that need a custom brief use the direct `invoke_panel` or
+  `invoke_board` entry point. The artifact is resolved at the TOP of the entry point
+  so timeout scaling, staging, and metadata all see the resolved content.
 - **`_resolve_artifact(artifact, artifact_ref)`.** `artifact_ref is None` →
   `artifact or ""` (today's bytes, verbatim). A single path (a bare string OR a
   one-element sequence) returns the file content VERBATIM — no header — so
@@ -298,6 +301,60 @@ the caller passes a PATH and the runtime reads it.
   `_exec_leg`; Proof B injects `spawn=`) is untouched;
   `tests/test_advisor_board_ingestion.py` proves the new path is byte-transparent.
 
+## CTXFREEZE — Context references and panel reliability (#114)
+
+CTXFREEZE freezes the #114 public contract for downstream implementation and
+documentation phases. It does not claim that `artifact_ref` or `brief_ref` are true
+non-inlining modes: both are read-file-and-inline conveniences that keep bytes out
+of the caller context but still stage raw contents for each leg.
+
+- **Ingestion modes and precedence.** `artifact` is inline text. `artifact_ref` is a
+  file path, or ordered path sequence, whose contents replace `artifact` when both
+  are supplied. `brief_ref` is a file path used only by `invoke_panel` and
+  `invoke_board`; it replaces the generated review/advisory instruction file.
+  `context_refs` is the only true by-reference mode. `invoke_panel_request` threads
+  `PanelRequest.artifact_ref`, `PanelRequest.context_refs`,
+  `PanelRequest.context_refs_soft_warn`, and `PanelRequest.timeout_seconds_by_leg`;
+  `PanelRequest.brief_ref` is explicitly out of contract for this phase.
+- **True by-reference manifest.** `context_refs` appends a deterministic manifest to
+  the already-resolved artifact. Each entry is emitted in caller order and contains a
+  JSON-escaped absolute path, byte count, streamed SHA-256 digest, untrusted MIME
+  guess, untrusted extension hint, and optional best-effort PDF page count. Raw file
+  contents are not written into `review-bundle.md`, prompt text, or the manifest.
+- **Metadata sensitivity.** Absolute pathnames and hashes can disclose sensitive
+  project names, customer names, filenames, document structure, and content
+  fingerprints even when raw bytes are not inlined. Callers should treat the
+  manifest as metadata-bearing, not private-by-construction.
+- **Filesystem boundary.** Paths are interpreted relative to the current process
+  working directory when relative and are reported as `Path.resolve()` absolute
+  paths. Entries must be regular files at validation time; missing paths,
+  directories, devices, and other non-regular files fail closed by default. Symlinks
+  are followed only if their resolved target is a regular file under normal OS path
+  resolution. The runtime opens the file once to stream size/hash metadata and, for
+  PDF-looking files only, may reopen a bounded prefix for page counting; CTXIMPL owns
+  any stronger root jail or TOCTOU hardening.
+- **Provider and backing limits.** `context_refs` assumes the selected provider and
+  backing can access the same local filesystem path from the leg runtime. Remote,
+  sandboxed, or service-backed harnesses may not have local file access even when
+  the manifest validates on the caller host.
+- **Soft-warning opt-in.** Missing or unreadable `context_refs` raise `ValueError`
+  unless `context_refs_soft_warn=True`. Soft warning logs a warning and emits a
+  `MISSING` or `UNREADABLE` entry. The manifest instruction text remains strict:
+  a leg must not infer, guess, or fabricate unavailable contents.
+- **Output-boundary claim.** The frozen privacy claim is runtime non-inlining only:
+  referenced contents are absent from the staged bundle and prompt produced by this
+  runtime path. This is not a global DLP guarantee for provider logs, human-visible
+  outputs, handoffs, screenshots, shell commands, or tools the leg chooses to run
+  after reading a referenced file. A leg may disclose file contents after it
+  intentionally inspects a referenced path unless an output policy forbids that
+  disclosure.
+- **Reliability names.** Direct entry points accept `timeouts_by_leg`; `PanelRequest`
+  uses `timeout_seconds_by_leg`. Both feed the same per-leg override. Unset legs keep
+  input-scaled defaults. The codex and gemini CLI legs retry one fast soft-empty or
+  transient-stall result once, guarded by elapsed-time fraction; hard subprocess
+  timeouts return timeout status without retry. CTXRELY owns any follow-on reliability
+  split beyond these frozen names and retry/timeout invariants.
+
 ## ABDMODE — Purpose-derived default mode + advisory prompt hygiene · `panel_invoker.py` (#107)
 
 A board's PURPOSE now selects its default panel MODE automatically, so a domain

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/src/phase_loop_runtime/cli.py

@@ -414,6 +414,16 @@ def build_parser() -> argparse.ArgumentParser:
                 action="store_true",
                 help="Consent to shape an unmanaged repo (no-op without this flag when no manifest exists yet).",
             )
+            sub.add_argument(
+                "--check-only",
+                action="store_true",
+                help=(
+                    "Run the conformance check only; never shape (ignores --adopt). "
+                    "On an adopted repo this is the verify pass. On an UN-ADOPTED repo "
+                    "it emits an explicit 'not adopted / nothing to verify' signal and "
+                    "exits non-zero (3), so a no-op is never mistaken for a pass."
+                ),
+            )
             sub.add_argument(
                 "--archetype",
                 action="append",
@@ -1634,6 +1644,7 @@ def _consiliency_ingest_command(*, repo: Path, args: argparse.Namespace, as_json
     archetypes = tuple(dict.fromkeys(getattr(args, "archetype", None) or ()))
     modifiers = tuple(dict.fromkeys(getattr(args, "modifier", None) or ()))
     baseline_only = bool(getattr(args, "baseline_only", False))
+    check_only = bool(getattr(args, "check_only", False))
     if baseline_only and (archetypes or modifiers):
         print("phase-loop consiliency-ingest: --baseline-only is mutually exclusive with --archetype/--modifier", file=sys.stderr)
         return 2
@@ -1641,6 +1652,7 @@ def _consiliency_ingest_command(*, repo: Path, args: argparse.Namespace, as_json
         result = ingest(
             repo,
             adopt=bool(getattr(args, "adopt", False)),
+            check_only=check_only,
             mode="baseline-only" if baseline_only else "archetyped",
             archetypes=archetypes,
             modifiers=modifiers,
@@ -1658,6 +1670,8 @@ def _consiliency_ingest_command(*, repo: Path, args: argparse.Namespace, as_json
         print(f"phase-loop consiliency-ingest: {result.mode} {result.manifest_path}")
         if result.mode == "skipped":
             print("  no .consiliency/manifest and --adopt was not passed; repo left untouched")
+        if result.mode == "not-adopted":
+            print("  NOT ADOPTED: no .consiliency/manifest -- nothing to verify (a no-op is not a pass)")
         if result.mode == "shape":
             created = (result.scaffold or {}).get("created_paths", [])
             print(f"  scaffolded {len(created)} doc(s); proposed governed_set entries: {len(result.governed_set)}")
@@ -1665,6 +1679,19 @@ def _consiliency_ingest_command(*, repo: Path, args: argparse.Namespace, as_json
             print(f"  gate scan: {result.gate_scan.get('status')}")
             for finding in result.findings:
                 print(f"  finding: {finding.get('code')} ({finding.get('path')})")
+    # --check-only makes the exit code verdict-significant, so a pre-PR actor is
+    # never misled into reading a no-op OR a failing verify as a pass:
+    #   3 -> not adopted / nothing to verify (distinct from a pass)
+    #   1 -> adopted but the gate scan is BLOCKED (a real conformance failure)
+    #   0 -> adopted + verify clean (warn stays 0: soft by default)
+    # 2 remains the usage-error code. The plain (non --check-only) path is
+    # UNCHANGED -- it keeps returning 0 exactly as before (see report note on
+    # the pre-existing blocked->0 gap on the plain command).
+    if check_only:
+        if result.mode == "not-adopted":
+            return 3
+        if result.gate_scan is not None and result.gate_scan.get("status") == "blocked":
+            return 1
     return 0
 
 

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/src/phase_loop_runtime/closeout.py

@@ -15,9 +15,9 @@ from .closeout_validators import (
 from .models import (
     PIPELINE_CLOSEOUT_OUTCOMES,
     PIPELINE_CLOSEOUT_SCHEMA,
-    PIPELINE_PROTECTED_SOURCE_CATEGORIES,
     PIPELINE_PROTECTED_SOURCE_LEGACY_ROLES,
     PIPELINE_PROTECTED_SOURCE_ROLES,
+    protected_source_categories,
     SPEC_DELTA_CLOSEOUT_SCHEMA,
     SPEC_DELTA_DECISIONS,
     DirtyPathClassification,
@@ -625,7 +625,7 @@ def phase_loop_closeout_diagnostic(payload: Mapping[str, Any] | None) -> dict[st
                 return {"kind": "malformed_closeout", "message": "closeout source_bundle.protected_sources entries must be objects"}
             category = item.get("category")
             role = item.get("role")
-            if category not in PIPELINE_PROTECTED_SOURCE_CATEGORIES:
+            if category not in protected_source_categories():
                 return {"kind": "malformed_closeout", "message": "closeout source_bundle protected source has invalid category"}
             if role is not None and role not in PIPELINE_PROTECTED_SOURCE_ROLES and role not in PIPELINE_PROTECTED_SOURCE_LEGACY_ROLES:
                 return {"kind": "malformed_closeout", "message": "closeout source_bundle protected source has invalid role"}

phase_loop_runtime-0.4.0/src/phase_loop_runtime/conformance.py

@@ -0,0 +1,94 @@
+"""``phase_loop_runtime.conformance`` -- the named, stable conformance surface.
+
+ONE LIBRARY, TWO ROLES. This module is the first-class public re-export of the
+deterministic, consent-gated ``.consiliency/`` conformance evaluator that already
+runs inside agent-harness. It exists so an EXTERNAL consumer -- a CR-fence in gp
+CI, a git-host pre-merge check, anywhere -- can::
+
+    from phase_loop_runtime.conformance import scan_consiliency_gates
+
+    verdict = scan_consiliency_gates("/path/to/repo")
+    if verdict["status"] == "blocked":
+        ...
+
+and run the *identical* function the actor runs against its own working tree.
+Nothing here is re-implemented: every name is re-exported unchanged from the
+module it already lives in, so the actor-side self-check (the "mock") and the
+authoritative CR-fence (the "real validator") are provably the same code.
+
+DUAL MOUNT -- ACTOR RESULT IS NEVER AUTHORITATIVE.
+    This library is intended to be mounted BOTH as the actor-side self-check
+    (a pre-PR sanity pass the author runs locally) AND as the authoritative
+    CR-fence (the real validator, run by the reviewing side / gp). The
+    actor-side result is advisory only -- a courtesy so the author is not
+    surprised. It is NEVER trusted as proof: **the fence always re-runs the
+    check itself.** Because it is the same function, the honest actor sees the
+    same verdict the fence will; a dishonest or stale actor result simply does
+    not matter, since the fence recomputes from the repo.
+
+    Consequently this library is meant to be VERSIONED WITH THE CONTRACT it
+    reads (the vendored ``consiliency_contract`` registries are the SoT for
+    every gate). Pin actor and fence to the same contract version and they
+    evaluate byte-for-byte the same policy. (This is a note, not machinery:
+    nothing here enforces a pin -- it is a deployment discipline for callers.)
+
+SCOPE -- SHAPE / GOVERNANCE TIER ONLY.
+    What this surface covers is the L0 SHAPE + GOVERNANCE tier:
+
+    * :func:`scan_consiliency_gates` -- the deterministic, consent-gated
+      evaluator that runs the six L0 gates (presence, layout_validity,
+      version_skew, git_discipline, local_integrity, spec_conformance) against
+      the vendored contract. Input: a repo path (+ optional ``env`` for the
+      gate-mode opt-in). Output: the per-gate findings plus an overall
+      ``status`` verdict. Read-only; a repo with no ``.consiliency/manifest.json``
+      is a pure no-op (``status: "skipped"``, ``consent: false``).
+    * :func:`evaluate_git_discipline` / :func:`self_heal_partition` /
+      :func:`evaluate_governance_scope` -- the PURE cores. They take injected
+      facts (git ref facts, adoption profile, subject) and no repo/runner
+      coupling, so a consumer that already has the facts can drive them
+      directly.
+
+    EXPLICITLY OUT OF SCOPE (delegated downstream / to gp): the cert-schema
+    tier, and authority / provenance verification. This surface asserts only
+    the *shape* and *governance* of a repo's ``.consiliency/`` layout -- it does
+    NOT mint, sign, or verify a conformance certificate, and it does not verify
+    canon/provenance of the underlying artifacts. Those higher rungs
+    (``realized-edge-observed``+ in the maturity ladder) pass through as
+    accepted claims here and are verified by a canon-backed verifier
+    downstream, not by this library.
+
+STABILITY.
+    The names re-exported here are the stable public surface. Prefer importing
+    from ``phase_loop_runtime.conformance`` (this submodule) rather than reaching
+    into ``consiliency_gates`` / ``git_discipline`` / ``consiliency_ingest``
+    directly -- those are the private implementation homes and may move; this
+    module is the contract.
+"""
+from __future__ import annotations
+
+# Re-exports (identical functions -- NOT re-implementations). The evaluator and
+# its pure cores live in three implementation modules; this module is the single
+# named door onto them.
+from .consiliency_gates import (
+    CONSILIENCY_GATES_ENV,
+    CONSILIENCY_GATES_MODES,
+    DEFAULT_CONSILIENCY_GATES_MODE,
+    resolve_consiliency_gates_mode,
+    scan_consiliency_gates,
+)
+from .consiliency_ingest import evaluate_governance_scope
+from .git_discipline import evaluate_git_discipline, self_heal_partition
+
+__all__ = [
+    # The evaluator (the "one library" both roles mount).
+    "scan_consiliency_gates",
+    # Gate-mode helpers (so a consumer can inspect / set the block-opt-in).
+    "resolve_consiliency_gates_mode",
+    "CONSILIENCY_GATES_ENV",
+    "CONSILIENCY_GATES_MODES",
+    "DEFAULT_CONSILIENCY_GATES_MODE",
+    # The pure cores (injected facts, no runner coupling).
+    "evaluate_git_discipline",
+    "self_heal_partition",
+    "evaluate_governance_scope",
+]

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/src/phase_loop_runtime/consiliency_ingest.py

@@ -278,6 +278,7 @@ def ingest(
     repo: str | Path,
     *,
     adopt: bool = False,
+    check_only: bool = False,
     mode: str = "baseline-only",
     archetypes: tuple[str, ...] = (),
     modifiers: tuple[str, ...] = (),
@@ -285,12 +286,47 @@ def ingest(
     display_name: str | None = None,
     dry_run: bool = False,
 ) -> IngestResult:
+    """Brownfield ingestion. See the module docstring for the SHAPE/VERIFY split.
+
+    ``check_only`` DECOUPLES "run the conformance check" from "is this repo
+    adopted". It is strictly read-only -- it NEVER shapes, so it ignores
+    ``adopt``. On an adopted repo it is exactly the VERIFY pass. On an
+    un-adopted repo (no ``.consiliency/manifest``) it does NOT return the silent
+    green ``skipped`` no-op that a plain (non-check) unflagged pass returns;
+    instead it returns an explicit, honest ``mode == "not-adopted"`` result so a
+    pre-PR actor is not misled into reading a no-op as a pass. Because
+    ``check_only`` makes the outcome verdict-significant, the CLI maps its exit
+    code accordingly (see ``_consiliency_ingest_command``): ``3`` = not adopted /
+    nothing to verify, ``1`` = adopted but the gate scan is ``blocked``, ``0`` =
+    adopted + verify clean. This function itself only returns the
+    :class:`IngestResult`; the exit mapping lives in the CLI.
+    """
     repo = Path(repo)
     existing = find_consiliency_manifest(repo)
     if existing is not None:
         return _verify(repo, existing_manifest_path=existing, dry_run=dry_run)
 
     target_manifest_path = manifest_path(repo)
+    if check_only:
+        # Honest not-adopted signal: there is genuinely nothing to verify, and
+        # saying so out loud is the point -- a no-op is NOT a pass.
+        return IngestResult(
+            repo=repo, mode="not-adopted", dry_run=dry_run, adopted=False,
+            manifest_path=target_manifest_path, scaffold=None, gate_scan=None,
+            governed_set=(), document_labels=(),
+            findings=(
+                {
+                    "code": "adoption.not_adopted",
+                    "severity": "info",
+                    "message": (
+                        "No .consiliency/manifest present: this repo is NOT ADOPTED, "
+                        "so there is nothing to verify. --check-only reports this "
+                        "explicitly (distinct from a passing verify) so a no-op is "
+                        "never mistaken for a pass."
+                    ),
+                },
+            ),
+        )
     if not adopt:
         return IngestResult(
             repo=repo, mode="skipped", dry_run=dry_run, adopted=False,

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/src/phase_loop_runtime/discovery.py

@@ -1462,6 +1462,8 @@ def _read_phase_source_bundle(
                 category=str(entry.get("category", "")),
                 sha256=str(entry["sha256"]) if entry.get("sha256") is not None else None,
                 role=str(entry["role"]) if entry.get("role") is not None else None,
+                # PSCAT-PL: accept the optional free-form producer subtype.
+                subtype=str(entry["subtype"]) if entry.get("subtype") is not None else None,
             )
         except ValueError as exc:
             return None, PipelineMetadataDiagnostic(

{phase_loop_runtime-0.3.0 → phase_loop_runtime-0.4.0}/src/phase_loop_runtime/models.py

@@ -168,6 +168,18 @@ DIRTY_PATH_CLASSIFICATIONS = (
     "unowned",
 )
 PIPELINE_MODE_LITERALS = ("standalone", "pipeline_optional", "pipeline_required")
+# LEGACY FALLBACK ONLY. The canonical protected_source_category vocabulary is
+# owned by the contract SoT (consiliency-contract >= 0.6.5,
+# `core/registries/protected-source-categories.json`, registry name
+# `protected_source_categories`). When the installed contract ships that
+# registry, its `coarse_categories` enum is AUTHORITATIVE and is what
+# `PipelineProtectedSource` validates against -- see
+# `protected_source_categories()` below. This tuple is retained only as the
+# contract-absent degrade path (older contract with no registry): the six
+# pre-existing coarse buckets the loop has always accepted. The registry is a
+# strict superset (same six + `governance_contracts`), so a category valid under
+# the fallback is never rejected under the registry. This is migration glue, not
+# a permanent shim -- registry-present is the SoT.
 PIPELINE_PROTECTED_SOURCE_CATEGORIES = (
     "specs",
     "diagrams",
@@ -353,6 +365,87 @@ def require_literal(value: str, allowed: tuple[str, ...], label: str) -> str:
     return value
 
 
+# --- protected_source_category vocabulary: sourced from the contract SoT -------
+#
+# The coarse `protected_source_category` enum is owned by consiliency-contract
+# (>= 0.6.5), registry `protected_source_categories`. We read it through the same
+# `consiliency_contract.load_registry` loader the git-discipline / consiliency
+# gates use, mirroring the lazy-cached `available()` / contract-absent degrade
+# pattern in `gate_posture.py`. When the registry is present it is AUTHORITATIVE;
+# when the installed contract predates it (no registry / load error) we degrade
+# to the legacy six-tuple rather than hard-crashing at import time.
+_PROTECTED_CATEGORY_CACHE: tuple[str, ...] | None = None
+_PROTECTED_CATEGORY_REGISTRY_PRESENT = False
+_PROTECTED_CATEGORY_LOADED = False
+_PROTECTED_FINE_SUBTYPES_CACHE: tuple[str, ...] = ()
+
+
+def _load_protected_source_registry() -> None:
+    global _PROTECTED_CATEGORY_CACHE, _PROTECTED_CATEGORY_REGISTRY_PRESENT
+    global _PROTECTED_CATEGORY_LOADED, _PROTECTED_FINE_SUBTYPES_CACHE
+    if _PROTECTED_CATEGORY_LOADED:
+        return
+    coarse: tuple[str, ...] | None = None
+    fine: tuple[str, ...] = ()
+    try:
+        from consiliency_contract import load_registry
+
+        reg = load_registry("protected_source_categories")
+        entries = reg.get("coarse_categories") if isinstance(reg, dict) else None
+        if isinstance(entries, list):
+            ids = tuple(
+                str(item["id"])
+                for item in entries
+                if isinstance(item, dict) and item.get("id")
+            )
+            if ids:
+                coarse = ids
+        raw_fine = reg.get("fine_subtypes") if isinstance(reg, dict) else None
+        if isinstance(raw_fine, list):
+            fine = tuple(str(x) for x in raw_fine if isinstance(x, str))
+    except Exception:
+        # Installed contract predates the registry (< 0.6.5) or read failed:
+        # degrade to the legacy tuple. Not a hard crash -- see gate_posture.py.
+        coarse = None
+    _PROTECTED_CATEGORY_REGISTRY_PRESENT = coarse is not None
+    _PROTECTED_CATEGORY_CACHE = coarse if coarse is not None else PIPELINE_PROTECTED_SOURCE_CATEGORIES
+    _PROTECTED_FINE_SUBTYPES_CACHE = fine
+    _PROTECTED_CATEGORY_LOADED = True
+
+
+def _reset_protected_source_registry_cache() -> None:
+    """Test-only: clear the memoized registry read (present/absent isolation)."""
+    global _PROTECTED_CATEGORY_CACHE, _PROTECTED_CATEGORY_REGISTRY_PRESENT
+    global _PROTECTED_CATEGORY_LOADED, _PROTECTED_FINE_SUBTYPES_CACHE
+    _PROTECTED_CATEGORY_CACHE = None
+    _PROTECTED_CATEGORY_REGISTRY_PRESENT = False
+    _PROTECTED_CATEGORY_LOADED = False
+    _PROTECTED_FINE_SUBTYPES_CACHE = ()
+
+
+def protected_source_categories() -> tuple[str, ...]:
+    """The authoritative coarse `protected_source_category` enum.
+
+    Prefers the distributed contract registry (>= 0.6.5); falls back to the
+    legacy six-tuple when the contract lacks the registry.
+    """
+    _load_protected_source_registry()
+    assert _PROTECTED_CATEGORY_CACHE is not None  # set by loader
+    return _PROTECTED_CATEGORY_CACHE
+
+
+def protected_source_category_registry_available() -> bool:
+    """True when the installed contract ships the coarse-category registry."""
+    _load_protected_source_registry()
+    return _PROTECTED_CATEGORY_REGISTRY_PRESENT
+
+
+def protected_source_fine_subtypes() -> tuple[str, ...]:
+    """Registered fine `subtype` names (soft/warn signal only, never a gate)."""
+    _load_protected_source_registry()
+    return _PROTECTED_FINE_SUBTYPES_CACHE
+
+
 @dataclass(frozen=True)
 class ModelSelection:
     profile: str
@@ -691,11 +784,19 @@ class PipelineProtectedSource:
     category: str
     sha256: str | None = None
     role: str | None = None
+    # PSCAT-PL: the producer's OPTIONAL fine governance granularity, carried
+    # alongside the coarse `category`. Free-form by contract design (the fine
+    # vocabulary is deliberately NOT re-coupled across repos) -- accepted as any
+    # string and never enum-gated. `protected_source_fine_subtypes()` is a soft
+    # reference set for tooling only, never a hard reject.
+    subtype: str | None = None
 
     def __post_init__(self) -> None:
         if not self.path.strip():
             raise ValueError("protected source path must not be empty")
-        require_literal(self.category, PIPELINE_PROTECTED_SOURCE_CATEGORIES, "protected source category")
+        # Validate the coarse category against the contract-owned enum
+        # (registry-authoritative >= 0.6.5; legacy six-tuple when absent).
+        require_literal(self.category, protected_source_categories(), "protected source category")
         if self.role is not None and self.role not in PIPELINE_PROTECTED_SOURCE_LEGACY_ROLES:
             require_literal(self.role, PIPELINE_PROTECTED_SOURCE_ROLES, "protected source role")