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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.2.0
+Version: 0.3.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.5.0,>=0.3.0
+Requires-Dist: consiliency-contract<0.7,>=0.6.3
 Requires-Dist: jsonschema<5,>=4
 Requires-Dist: tomli<3,>=2; python_version < "3.11"
 

{phase_loop_runtime-0.2.0 → phase_loop_runtime-0.3.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.2.0"
+version = "0.3.0"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,12 +22,17 @@ dependencies = [
     "baml-py>=0.222,<0.223",
     "pydantic>=2,<3",
     "PyYAML>=6,<7",
-    # Widened ceiling (Slice G): the git-discipline guardrail CONSUMES the
-    # contract's `pipeline_ref_classes` registry + `git_discipline_protocol`
-    # schema, first published in 0.4.x. Floor stays at 0.3.0 so CI still resolves
-    # against the currently-published 0.3.0 (the guardrail then degrades to a
-    # neutral no-op); it auto-adopts the git-discipline contract once 0.4.x ships.
-    "consiliency-contract>=0.3.0,<0.5.0",
+    # PIN (spec-integration v0.3.0): floor at 0.6.3 -- ships the `gate_posture_registry`
+    # AND the manifest-schema `gate_posture_overrides` key (0.6.3) that makes the dial
+    # OPERABLE (a repo can declare per-repo posture overrides without failing layout_validity),
+    # alongside `pipeline_ref_classes` + `git_discipline_protocol`. This
+    # ACTIVATES the git-discipline guardrail AND the posture dial (per-finding-class
+    # enforcement with non-retractable floors). The dial degrades gracefully on an older
+    # contract (gate_posture.available() False -> legacy per-gate behavior preserved), so
+    # < 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",
     "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.2.0 → phase_loop_runtime-0.3.0}/src/phase_loop_runtime/__init__.py

@@ -17,4 +17,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{phase_loop_runtime-0.2.0 → phase_loop_runtime-0.3.0}/src/phase_loop_runtime/advisor_board/CONTRACTS.md

@@ -255,3 +255,72 @@ the golden proves byte-identity):
   `claude` seats) now runs two concurrent same-lane CLI/PTY sessions — a scenario this
   fan-out newly enables and nothing yet tests. The `default` board has one claude seat,
   so it is unaffected.
+
+## ABDREF — "Reference, don't inline" ingestion · `panel_invoker._resolve_artifact` / `_resolve_brief`
+
+The leg prompt was already lean (it stages `review-bundle.md` and instructs the leg
+to READ the file); the remaining inline path was the caller→runtime boundary, where
+building `artifact: str` forces the caller to hold the whole (20k+ token) bundle in
+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`
+  (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.
+- **`_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
+  `artifact_ref=P` is byte-identical to `artifact=<contents of P>`. Multiple paths
+  concatenate deterministically in the given order, each under a `## {filename}`
+  header, joined by a blank line. `artifact_ref` WINS when both it and `artifact` are
+  supplied. A `str` is checked BEFORE the `Sequence` branch (a string is itself an
+  iterable of characters).
+- **`_resolve_brief(mode, brief_ref)`.** `brief_ref` file when set, else
+  `_mode_instructions(mode)` — staged as `review-instructions.md`. Threaded through
+  `_default_spawn` / `_default_spawn_via_provider` (omitted-when-`None`, so the
+  default path's `_default_spawn` call stays byte-identical).
+- **Fail-closed.** A missing `artifact_ref` / `brief_ref` path raises `ValueError`
+  NAMING the path — never a silent-empty bundle that would read as a real (empty)
+  review.
+- **Inline-size guard (`_maybe_warn_inline_size`, `_MAX_INLINE_ARTIFACT_BYTES = 16 KB`).**
+  An INLINE (not-from-ref) artifact over the threshold logs ONE steering warning
+  pointing to `artifact_ref` — **WARN, never refuse, never mutate** (refusing would
+  break existing callers). A from-ref artifact is never warned.
+- **Crash-residual scratch GC (`_gc_stale_panel_scratch`).** Best-effort, age-gated
+  (`max_age_s = 24h`) sweep of `pl-panel-*` dirs, called at the top of
+  `_default_spawn`. Reclaims dirs leaked when a run is KILLED before the per-run
+  `finally: rmtree` (timeout/crash); a concurrent run's fresh dir is never touched,
+  and a GC failure can NEVER affect the run (fully swallowed).
+- **Golden byte-identity preserved.** No ref ⇒ identical staged bytes ⇒ identical
+  per-leg argv / env / timeout. `tests/test_advisor_board_golden.py` (Proof A hits
+  `_exec_leg`; Proof B injects `spawn=`) is untouched;
+  `tests/test_advisor_board_ingestion.py` proves the new path is byte-transparent.
+
+## 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
+board (esp. the legal boards) runs in the right posture instead of being hard
+code-review-gated. `tests/test_advisor_board_advisory_mode.py`.
+
+- **`_mode_for_purpose(purpose) -> str`.** Code-review-class purposes
+  (`code-review`, `premerge-review`) → `"review"` (the strict pre-merge gate:
+  bundle is untrusted material to accept/reject, a conforming AGREE / PARTIALLY
+  AGREE / DISAGREE verdict is REQUIRED). The known domain purposes (`legal-review`,
+  `legal-strategy-review`, `legal-brainstorm`, `brainstorm`, `doc-edit`, `general`)
+  → `"advisory"` (analysis / recommendation, no verdict — substantial prose is a
+  real leg). An UNKNOWN purpose → `"review"` (back-compat safe default: a strict
+  gate never silently loosens on an unrecognized board).
+- **`invoke_board(mode=None)` derives, a caller-passed `mode` overrides.**
+  `invoke_board` defaults `mode` to `None`; when `None` it derives
+  `_mode_for_purpose(board.purpose)`. `invoke_panel` KEEPS its legacy
+  `mode="review"` default (no board / no purpose). `DEFAULT_BOARD.purpose` is
+  `premerge-review` → derives `"review"` → **the golden byte-identity holds** —
+  `invoke_board(DEFAULT_BOARD)` stays byte-identical to the legacy review path.
+- **Mode-aware prompt hygiene (`_render_leg_prompt`, `_ADVISORY_INSTRUCTIONS`).**
+  The REVIEW framing is **byte-for-byte unchanged** (the golden asserts the exact
+  prompt/argv). The ADVISORY framing DROPS the code-review-gate posture — no
+  "authoritative", no "untrusted material under review", no accept/reject — while
+  KEEPING the instructions/material SEPARATION (injection-safe: the brief is your
+  task, the bundle is only material, never authoritative instructions).

{phase_loop_runtime-0.2.0 → phase_loop_runtime-0.3.0}/src/phase_loop_runtime/consiliency_gates.py

@@ -62,7 +62,28 @@ CONSILIENCY_GATES_ENV = "PHASE_LOOP_CONSILIENCY_GATES"
 CONSILIENCY_GATES_MODES: tuple[str, ...] = ("off", "warn", "hard")
 DEFAULT_CONSILIENCY_GATES_MODE = "warn"
 
-_GATE_NAMES = ("presence", "local_integrity", "layout_validity", "version_skew", "git_discipline")
+_GATE_NAMES = ("presence", "local_integrity", "layout_validity", "version_skew", "git_discipline", "spec_conformance")
+
+# spec_conformance (HGATE) — the generic conformance ladder + default bar. Advisory
+# panel (Fable + Codex 5.5 + Gemini 3.1 Pro, unanimous) set the default PASS bar at
+# `hash-checked`+ ("bar B"): it's the lowest rung where the claim is checkable by the
+# existing local_integrity digest machinery, so a self-asserted `hash-checked` obligates
+# a recorded digest rather than being a free claim. `presence-only` is an INFO-grade
+# soft warn (declared but not digest-anchored); `present-nonconforming`/`foreign`/
+# `unmanaged` are loud. The per-archetype/per-doc conformance floor as CONTRACT REGISTRY
+# DATA is the deferred ratchet (do NOT hardcode org policy here). These labels mirror the
+# contract `maturity-labels` registry; `certified` is a deprecated alias of `parity-certified`.
+_SPEC_PROJECTION_CLASSES = ("proj-S", "proj-code")
+_CONFORMANCE_LADDER = {  # conforming rungs, low -> high
+    "presence-only": 0,
+    "hash-checked": 1,
+    "realized-edge-observed": 2,
+    "parity-certified": 3,
+    "authority-certified": 4,
+}
+_CONFORMANCE_ALIASES = {"certified": "parity-certified"}  # deprecated alias, ranked as parity-certified
+_NONCONFORMING_LABELS = frozenset({"present-nonconforming", "foreign", "unmanaged"})
+_CONFORMANCE_FLOOR = "hash-checked"  # bar B: the generic default PASS floor
 
 
 def resolve_consiliency_gates_mode(env: Mapping[str, str] | None = None) -> str:
@@ -117,7 +138,8 @@ def scan_consiliency_gates(
         "local_integrity": _gate_local_integrity(repo_path, manifest, mode=mode),
         "layout_validity": _gate_layout_validity(repo_path, manifest, mode=mode),
         "version_skew": _gate_version_skew(manifest, mode=mode),
-        "git_discipline": _gate_git_discipline(repo_path, mode=mode),
+        "git_discipline": _gate_git_discipline(repo_path, manifest, mode=mode),
+        "spec_conformance": _gate_spec_conformance(manifest, mode=mode),
     }
     if any(g["status"] == "blocked" for g in gates.values()):
         overall = "blocked"
@@ -142,6 +164,50 @@ def _gate_status(findings: list[dict[str, Any]], *, mode: str, capped_warn: bool
     return "warn"
 
 
+_SEVERITY = {"note": 0, "warn": 1, "blocked": 2}
+_SEVERITY_STATUS = {0: "passed", 1: "warn", 2: "blocked"}
+
+
+def _apply_posture(
+    findings: list[dict[str, Any]], *, manifest: Mapping[str, Any] | None, mode: str,
+    legacy_capped_all: bool = False, legacy_capped_codes: frozenset[str] = frozenset(),
+) -> dict[str, Any]:
+    """Retractable teeth -- resolve each finding's posture from the contract registry and
+    derive the gate status. `observe` findings are RECORDED (as notes) but never escalate
+    past `passed`; `warn` -> warn; `enforce` -> warn unless the operator opted into `hard`
+    -> blocked. Any per-repo override that LOWERS a class below its default adds the
+    non-retractable `posture_retracted` finding -- fired from the manifest overrides, so
+    de-fanging is visible even on an otherwise-clean scan.
+
+    Contract < 0.6.2 fallback preserves each gate's PRIOR severity: `legacy_capped_all`
+    caps every finding at warn (version_skew's normative phase0 const), `legacy_capped_codes`
+    caps just those codes (spec_conformance's info tier); everything else follows mode."""
+    from . import gate_posture as gp
+
+    if not gp.available():
+        if not findings:
+            return {"status": "passed", "findings": findings}
+        worst = 0
+        for f in findings:
+            capped = legacy_capped_all or str(f.get("code") or "") in legacy_capped_codes
+            worst = max(worst, _SEVERITY["warn" if (capped or mode != "hard") else "blocked"])
+        return {"status": _SEVERITY_STATUS[worst], "findings": findings}
+
+    out: list[dict[str, Any]] = []
+    worst = 0
+    for f in findings:
+        res = gp.resolve_posture(str(f.get("code") or ""), manifest=manifest)
+        worst = max(worst, _SEVERITY.get(gp.posture_status(res["posture"], mode=mode), 1))
+        out.append({**f, "posture": res["posture"]})
+    retracted = gp.retracting_overrides(manifest)
+    if retracted:
+        r = gp.resolve_posture("posture_retracted", manifest=manifest)
+        worst = max(worst, _SEVERITY.get(gp.posture_status(r["posture"], mode=mode), 1))
+        out.append({"code": "posture_retracted", "posture": r["posture"], "retracted_classes": retracted,
+                    "message": "per-repo posture override lowered: " + ", ".join(retracted)})
+    return {"status": _SEVERITY_STATUS[worst], "findings": out}
+
+
 def _declared_archetypes_modifiers(manifest: Mapping[str, Any]) -> tuple[str, tuple[str, ...], tuple[str, ...]]:
     declaration = dict(manifest.get("declaration") or {})
     decl_mode = str(declaration.get("mode") or "baseline-only")
@@ -178,6 +244,84 @@ def _gate_presence(repo: Path, manifest: Mapping[str, Any], *, mode: str) -> dic
     return {"status": _gate_status(findings, mode=mode), "maturity": "presence-only", "findings": findings}
 
 
+def _gate_spec_conformance(manifest: Mapping[str, Any], *, mode: str) -> dict[str, Any]:
+    """HGATE: warn when a DECLARED spec-projection (proj-S/proj-code) sits below the
+    conformance bar. Structural — reads declared maturity, no byte/digest verification
+    (that is local_integrity's job for hash-checked, and a future canon-backed verifier's
+    for higher rungs). Full no-op when the repo declares no spec-projections (OPA-style
+    optional layer). Two-tier: `present-nonconforming`/`foreign`/`unmanaged` are loud
+    (may block under hard mode); a below-bar non-sanctioned `presence-only` is an
+    info-grade soft warn that NEVER blocks (so honest early adopters are nudged, not
+    punished).
+
+    HONESTY -- this gate is FORWARD INFRASTRUCTURE, dormant on schema-valid manifests
+    with today's contract data: (a) every proj-S/proj-code required-doc row is
+    `l0_stub_allowed` at a `presence-only` floor, so the info + below-floor branches
+    are dead until the per-archetype conformance ratchet raises floors (deferred to
+    contract-registry data); (b) the manifest schema's maturity enum is only
+    {presence-only, hash-checked, realized-edge-observed}, so the non-conforming labels
+    that drive the loud branches are schema-INVALID and already caught by
+    layout_validity. So today it fires nothing layout_validity does not; it activates
+    without code change when the schema enum + the ratchet expand. Known ceiling:
+    `hash-checked` is the only rung the harness can locally verify (via local_integrity,
+    and only for `path`-backed docs -- `ref`-backed hash-checked is not yet digest-
+    checked); `realized-edge-observed`+ pass as accepted claims, verified downstream by
+    a canon-backed verifier, not here."""
+    decl_mode, archetypes, modifiers = _declared_archetypes_modifiers(manifest)
+    try:
+        rows = compose_required_documents(mode=decl_mode, archetypes=archetypes, modifiers=modifiers)
+    except ValueError:
+        # A malformed declaration is presence/layout's finding, not conformance's.
+        return {"status": "passed", "maturity": "presence-only", "findings": [],
+                "note": "declaration invalid; deferred to presence/layout gates"}
+    proj_rows = {r.id: r for r in rows if r.doc_class in _SPEC_PROJECTION_CLASSES}
+    docs_by_id = {d.get("id"): d for d in manifest.get("documents", []) if isinstance(d, Mapping)}
+    declared = [(pid, proj_rows[pid], docs_by_id[pid]) for pid in sorted(proj_rows) if pid in docs_by_id]
+    if not declared:
+        return {"status": "passed", "maturity": "presence-only", "findings": [],
+                "note": "no spec-projection documents declared; conformance gate is a no-op"}
+
+    bar_rank = _CONFORMANCE_LADDER[_CONFORMANCE_FLOOR]
+    loud: list[dict[str, Any]] = []
+    info: list[dict[str, Any]] = []
+    for pid, row, entry in declared:
+        raw = str(entry.get("maturity") or "").strip()
+        label = _CONFORMANCE_ALIASES.get(raw, raw)
+        floor_rank = _CONFORMANCE_LADDER.get(_CONFORMANCE_ALIASES.get(row.maturity_floor, row.maturity_floor), 0)
+        if not raw:
+            loud.append({"code": "spec_maturity_missing", "doc_id": pid,
+                         "message": f"spec-projection '{pid}' declares no maturity"})
+        elif label == "present-nonconforming":
+            loud.append({"code": "spec_nonconforming", "doc_id": pid, "maturity": raw,
+                         "message": f"spec-projection '{pid}' is 'present-nonconforming' -- the projection asserts the code does NOT match spec"})
+        elif label in _NONCONFORMING_LABELS:  # foreign / unmanaged -- governance-status, NOT a non-conformance assertion
+            loud.append({"code": "spec_ungoverned", "doc_id": pid, "maturity": raw,
+                         "message": f"spec-projection '{pid}' declares governance status '{raw}' (not this repo's, or ungoverned) -- outside the conformance ladder"})
+        elif label not in _CONFORMANCE_LADDER:
+            loud.append({"code": "spec_maturity_unknown", "doc_id": pid, "maturity": raw,
+                         "message": f"spec-projection '{pid}' declares an unrecognized maturity '{raw}'"})
+        elif _CONFORMANCE_LADDER[label] < floor_rank:
+            # Below the doc's OWN contract-declared maturity_floor -- a real regression.
+            loud.append({"code": "spec_below_declared_floor", "doc_id": pid, "maturity": raw, "floor": row.maturity_floor,
+                         "message": f"spec-projection '{pid}' is '{raw}' but the contract floor for it is '{row.maturity_floor}'"})
+        elif _CONFORMANCE_LADDER[label] < bar_rank and not row.l0_stub_allowed:
+            # Below the generic conformance bar AND not a contract-sanctioned L0 stub -> info nudge.
+            info.append({"code": "spec_below_conformance_bar", "doc_id": pid, "maturity": raw,
+                         "message": f"spec-projection '{pid}' is '{raw}'; the conformance bar is '{_CONFORMANCE_FLOOR}'+ (declared but not digest-anchored). Informational -- pass requires {_CONFORMANCE_FLOOR}+ unless it is a sanctioned L0 stub or local policy overrides."})
+        # else: at/above its contract floor and (hash-checked+ OR a sanctioned L0 stub) -> conforming
+
+    # Retractable teeth: the contract's posture registry (not a hardcoded loud/info split)
+    # now drives severity per finding-class -- spec_nonconforming/etc default to `warn`
+    # (advisory, may be raised to enforce per-repo), spec_below_conformance_bar to `observe`
+    # (a recorded note). This gate does NO digest work itself, so it reports its own
+    # maturity as presence-only (honest); hash-checked is the bar, not a verified claim.
+    # legacy_capped_codes: preserve the pre-registry info tier -- spec_below_conformance_bar
+    # never blocked even under hard, so cap it in the < 0.6.2 fallback.
+    result = _apply_posture(loud + info, manifest=manifest, mode=mode,
+                            legacy_capped_codes=frozenset({"spec_below_conformance_bar"}))
+    return {"status": result["status"], "maturity": "presence-only", "findings": result["findings"]}
+
+
 def _git_show(repo: Path, path: str) -> bytes | None:
     try:
         return subprocess.check_output(
@@ -222,10 +366,14 @@ def _gate_local_integrity(repo: Path, manifest: Mapping[str, Any], *, mode: str)
         checked_any = True
         if recorded != digest:
             findings.append({"code": "hash_drift", "doc_id": doc_id, "path": path, "expected": recorded, "actual": digest})
+    # Retractable teeth: hash_drift is an audit-chain invariant floored at `warn` in the
+    # registry (warns, does not hard-block by default; can be raised to enforce). Migrated
+    # onto the dial so the contract data matches live behavior (CR: Codex/Gemini/Fable).
+    posture = _apply_posture(findings, manifest=manifest, mode=mode)
     return {
-        "status": _gate_status(findings, mode=mode),
+        "status": posture["status"],
         "maturity": "hash-checked" if checked_any else "presence-only",
-        "findings": findings,
+        "findings": posture["findings"],
     }
 
 
@@ -264,7 +412,7 @@ def _gate_layout_validity(repo: Path, manifest: Mapping[str, Any], *, mode: str)
     return {"status": _gate_status(findings, mode=mode), "maturity": "presence-only", "findings": findings}
 
 
-def _gate_git_discipline(repo: Path, *, mode: str) -> dict[str, Any]:
+def _gate_git_discipline(repo: Path, manifest: Mapping[str, Any] | None, *, mode: str) -> dict[str, Any]:
     """Slice-G git-discipline guardrail: classify the repo's refs against the
     neutral contract's ``pipeline_ref_classes`` registry and check the
     write-footprint / branch-naming invariants. Consumes the contract, does not
@@ -296,7 +444,13 @@ def _gate_git_discipline(repo: Path, *, mode: str) -> dict[str, Any]:
         registry=registry,
         protocol=protocol,
     )
-    return {"status": _gate_status(findings, mode=mode), "maturity": "presence-only", "findings": findings}
+    # Retractable teeth: per-finding-class posture from the contract registry replaces the
+    # uniform _gate_status -- pipeline_branch_naming_drift softens to `observe` (a note),
+    # write_footprint_violation holds at its `warn` floor, and never_delete_human_refs is
+    # `enforce` and NON-RETRACTABLE. Legacy uniform behavior survives when the contract
+    # predates the posture registry (< 0.6.2).
+    result = _apply_posture(findings, manifest=manifest, mode=mode)
+    return {"status": result["status"], "maturity": "presence-only", "findings": result["findings"]}
 
 
 _RANGE_RE = re.compile(r"^>=\s*([0-9.]+)\s*<\s*([0-9.]+)$")
@@ -361,14 +515,19 @@ def _gate_version_skew(manifest: Mapping[str, Any], *, mode: str) -> dict[str, A
             )
         else:
             compatibility = "compatible"
-    # Normative: version-skew stays warn-only at Phase 0 regardless of the
-    # gate mode opt-in (version-skew-protocol.schema `default_behavior.
-    # phase0_severity` is a fixed const, not a per-consumer policy knob).
+    # Normative: version-skew stays warn-only at Phase 0. The `version_skew` finding class
+    # carries max_posture=warn in the contract posture registry, so the cap is now contract
+    # DATA (retractable teeth) rather than the hardcoded capped_warn flag -- the legacy
+    # cap survives (fallback) when the contract predates the registry.
+    # legacy_capped_all: the version-skew phase0 severity is a normative const `warn`, so
+    # the < 0.6.2 fallback must cap at warn (never block under hard) -- preserving the old
+    # capped_warn=True behavior.
+    posture = _apply_posture(findings, manifest=manifest, mode=mode, legacy_capped_all=True)
     return {
-        "status": _gate_status(findings, mode=mode, capped_warn=True),
+        "status": posture["status"],
         "maturity": "realized-edge-observed",
         "compatibility": compatibility,
         "installed_contract_version": installed_version,
         "repo_contract_version": repo_version or None,
-        "findings": findings,
+        "findings": posture["findings"],
     }

phase_loop_runtime-0.3.0/src/phase_loop_runtime/gate_posture.py

@@ -0,0 +1,135 @@
+"""Retractable teeth -- gate enforcement posture resolution.
+
+Reads the merge-gated ``gate_posture_registry`` (consiliency-contract >= 0.6.2) and
+resolves the *effective* posture for a finding class from three layers -- the contract
+``default_posture``, then a per-repo ``.consiliency/manifest.json`` override -- clamped
+to the class's non-retractable ``min_posture`` FLOOR and optional ``max_posture`` cap.
+
+Posture rungs: ``observe`` < ``warn`` < ``enforce``. A per-repo override may RAISE any
+class freely but may LOWER it only to (never below) its floor -- ``invariant`` classes
+(never-delete-human-refs, write-footprint, hash-drift) carry a real floor; ``advisory``
+classes retract freely to ``observe``. The operator's ``PHASE_LOOP_CONSILIENCY_GATES``
+= off | warn | hard remains the MASTER switch: ``enforce`` blocks ONLY under ``hard``;
+``human_required`` is NEVER set at any posture. A per-repo *downward* move is surfaced
+via the non-retractable ``posture_retracted`` note so de-fanging is always fleet-visible.
+
+Contract-absent degrade: if the installed contract predates the registry (< 0.6.2),
+:func:`available` is False and callers keep their legacy status logic unchanged.
+
+Design ratified by advisory panel (Fable + Codex 5.5 + Gemini 3.1 Pro, unanimous).
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+_RUNG = {"observe": 0, "warn": 1, "enforce": 2}
+# Optional per-repo overrides live under this manifest key: {finding_code: posture}.
+MANIFEST_OVERRIDE_KEY = "gate_posture_overrides"
+_DEFAULT_UNLISTED = {"category": "advisory", "default_posture": "warn", "min_posture": "observe"}
+
+
+def _rank(posture: str) -> int:
+    return _RUNG.get(posture, _RUNG["warn"])
+
+
+_REGISTRY_CACHE: dict[str, Any] | None = None
+_REGISTRY_LOADED = False
+
+
+def _registry() -> dict[str, Any] | None:
+    global _REGISTRY_CACHE, _REGISTRY_LOADED
+    if _REGISTRY_LOADED:
+        return _REGISTRY_CACHE
+    try:
+        from consiliency_contract import load_registry
+
+        reg = load_registry("gate_posture_registry")
+        _REGISTRY_CACHE = reg if isinstance(reg, Mapping) else None
+    except Exception:
+        _REGISTRY_CACHE = None  # contract predates the registry (< 0.6.2)
+    _REGISTRY_LOADED = True
+    return _REGISTRY_CACHE
+
+
+def available() -> bool:
+    """True when the installed contract ships the posture registry (>= 0.6.2)."""
+    return _registry() is not None
+
+
+def _class_entry(reg: Mapping[str, Any], code: str) -> Mapping[str, Any]:
+    for fc in reg.get("finding_classes", []):
+        if isinstance(fc, Mapping) and fc.get("code") == code:
+            return fc
+    unlisted = reg.get("default_unlisted")
+    return unlisted if isinstance(unlisted, Mapping) else _DEFAULT_UNLISTED
+
+
+def _overrides(manifest: Mapping[str, Any] | None) -> dict[str, str]:
+    if isinstance(manifest, Mapping):
+        raw = manifest.get(MANIFEST_OVERRIDE_KEY)
+        if isinstance(raw, Mapping):
+            return {str(k): str(v) for k, v in raw.items()}
+    return {}
+
+
+def resolve_posture(code: str, *, manifest: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    """Resolve the effective posture for a finding ``code``.
+
+    Returns a dict with the effective ``posture`` plus provenance (``default``, ``floor``,
+    ``cap``, ``requested`` per-repo value, ``retracted`` = a real downward move below the
+    default, ``clamped_to_floor`` = an override that tried to go below the floor and was
+    denied, ``category``). ``available`` is False when the contract lacks the registry.
+    """
+    reg = _registry()
+    if reg is None:
+        return {"posture": "warn", "default": "warn", "floor": "observe", "cap": None,
+                "requested": None, "retracted": False, "clamped_to_floor": False,
+                "category": "advisory", "available": False}
+    entry = _class_entry(reg, code)
+    default = str(entry.get("default_posture", "warn"))
+    floor = str(entry.get("min_posture", "observe"))
+    cap = entry.get("max_posture")
+    cap = str(cap) if cap in _RUNG else None
+
+    requested = _overrides(manifest).get(code)
+    chosen = requested if requested in _RUNG else default
+
+    effective = chosen
+    clamped_to_floor = requested in _RUNG and _rank(requested) < _rank(floor)
+    if cap and _rank(effective) > _rank(cap):
+        effective = cap
+    if _rank(effective) < _rank(floor):
+        # NON-RETRACTABLE floor: a repo can never weaken below it -- and the floor wins
+        # even over a mis-configured max_posture < min_posture registry entry.
+        effective = floor
+
+    # `retracted` reflects an ACTUAL downward move of the effective posture below the
+    # default -- a floor-clamped attempt (effective unchanged) is NOT a retraction; it is
+    # surfaced via `clamped_to_floor` instead.
+    retracted = requested in _RUNG and _rank(effective) < _rank(default)
+    return {"posture": effective, "default": default, "floor": floor, "cap": cap,
+            "requested": requested, "retracted": bool(retracted),
+            "clamped_to_floor": bool(clamped_to_floor),
+            "category": str(entry.get("category", "advisory")), "available": True}
+
+
+def retracting_overrides(manifest: Mapping[str, Any] | None) -> list[str]:
+    """The finding codes whose per-repo override LOWERS the effective posture below its
+    default -- de-fanging that must be surfaced even when that class fired no finding this
+    scan. A floor-clamped attempt (effective unchanged) is not counted (see resolve_posture)."""
+    if _registry() is None:
+        return []
+    out = [code for code in _overrides(manifest) if resolve_posture(code, manifest=manifest)["retracted"]]
+    return sorted(set(out))
+
+
+def posture_status(posture: str, *, mode: str) -> str:
+    """Map a resolved posture + operator mode to a gate-status contribution:
+    ``observe`` -> ``note`` (recorded, never warns/blocks); ``warn`` -> ``warn``;
+    ``enforce`` -> ``warn`` unless the operator opted into ``hard`` -> ``blocked``.
+    ``human_required`` is never implied at any rung."""
+    if posture == "observe":
+        return "note"
+    if posture == "enforce" and mode == "hard":
+        return "blocked"
+    return "warn"