codd-dev 2.88.0__tar.gz → 2.90.0__tar.gz

{codd_dev-2.88.0 → codd_dev-2.90.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.88.0
+Version: 2.90.0
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev

{codd_dev-2.88.0 → codd_dev-2.90.0}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "2.88.0"
+__version__ = "2.90.0"

{codd_dev-2.88.0 → codd_dev-2.90.0}/codd/cli.py

@@ -5023,6 +5023,15 @@ def verify(
         if not runtime:
             return
 
+    # Stack contract intake + lock enforcement (Contract Kernel v2.77a/v2.77b) —
+    # bring the project's declared framework-stack contract into the live verify
+    # run's trace (v2.77a, mirroring the greenfield intake), then ENFORCE the stack
+    # lock as a gate (v2.77b): a stack project whose committed lock has drifted from
+    # the resolved contract — or that has no committed lock at all — is RED. A
+    # project with no `stack:` block is unaffected; a declared-but-broken stack
+    # fails HONESTLY (anti-false-green), never a silent skip.
+    _intake_stack_contract_for_verify(Path(path).resolve())
+
     verify_kwargs: dict[str, Any] = {"path": path, "prefer_standalone": True}
     if runtime_skip:
         verify_kwargs["runtime_skip"] = runtime_skip
@@ -7591,6 +7600,65 @@ def _load_optional_project_config(project_root: Path) -> dict[str, Any]:
         return {}
 
 
+def _intake_stack_contract_for_verify(project_root: Path) -> None:
+    """Resolve the project's declared stack contract into the verify run trace.
+
+    Contract Kernel v2.77a (intake only) — the verify-path mirror of the greenfield
+    pipeline's :meth:`GreenfieldPipeline._intake_stack_contract`. Proves the
+    framework-stack contract is LIVE-consumed by the verify path (the hash enters
+    the run trace), WITHOUT enforcing any obligation or changing the verify verdict
+    (obligation enforcement is v2.77b-e).
+
+    * No ``stack:`` block → no-op (the opt-in framework layer is unused; the vast
+      majority of projects — emits a single trace line, no behaviour change).
+    * A declared stack → its ``stack_contract_hash`` is echoed to the run trace.
+    * A declared-but-BROKEN stack → honest failure (``SystemExit`` non-zero), never
+      a silent skip (anti-false-green / no-silent-fallback).
+    """
+    from codd.stack.project import stack_contract_intake, stack_contract_trace
+
+    try:
+        contract = stack_contract_intake(project_root)
+    except Exception as exc:  # noqa: BLE001 — a declared-but-broken stack must fail HONESTLY.
+        click.echo(
+            "stack contract intake failed: the project declares a `stack:` block in "
+            f"codd.yaml but it could not be resolved ({type(exc).__name__}: {exc}). "
+            "A declared-but-unresolvable stack is an honest error, never a silent skip.",
+            err=True,
+        )
+        raise SystemExit(1) from exc
+
+    if contract is None:
+        # No `stack:` block → byte-identical, UNLESS a committed lock still exists
+        # (a removed stack declaration on a still-pinned project = RED; closes the
+        # "drop stack: to dodge the gate" bypass — v2.77b anti-false-green).
+        from codd.stack.lock import orphan_stack_lock
+
+        orphan = orphan_stack_lock(project_root)
+        if orphan is not None and orphan.red:
+            click.echo(f"[verify] stack lock gate: {orphan.message}", err=True)
+            raise SystemExit(1)
+        return
+    trace = stack_contract_trace(contract)
+    click.echo(
+        f"[verify] stack contract intake: {trace['resolved_stack_id']} "
+        f"stack_contract_hash={trace['stack_contract_hash']}"
+    )
+
+    # Stack lock ENFORCEMENT (Contract Kernel v2.77b) — verify is always an
+    # enforcement context (it never CREATES a project), so it uses the strictly
+    # READ-ONLY gate: a stack project with no committed lock, or a lock that has
+    # drifted from (or cannot be parsed against) the resolved contract, is RED
+    # (honest non-zero exit). The gate never writes or refreshes the lock, so a
+    # drift cannot be silenced on the verify path.
+    from codd.stack.lock import enforce_stack_lock
+
+    gate = enforce_stack_lock(contract, project_root)
+    click.echo(f"[verify] stack lock gate: {gate.message}", err=gate.red)
+    if gate.red:
+        raise SystemExit(1)
+
+
 def _run_verify_once(
     path: str,
     *,

{codd_dev-2.88.0 → codd_dev-2.90.0}/codd/greenfield/pipeline.py

@@ -440,6 +440,66 @@ class GreenfieldPipeline:
 
         self._notify(options, f"greenfield start: {project_root.name}")
 
+        # Stack contract intake (Contract Kernel v2.77a) — bring the project's
+        # declared framework-stack contract into the LIVE run (in the run record +
+        # trace) so the framework layer is consumed by production, not only tests.
+        # INTAKE ONLY: no obligation is enforced here and NO verdict changes (that
+        # is v2.77b-e). A project with no ``stack:`` block is byte-identical (the
+        # opt-in framework layer is unused). A declared-but-broken stack is an
+        # HONEST failure (anti-false-green), never a silent skip. Done once, early,
+        # before the stage loop, so the hash covers the whole run. Routed through
+        # _fail (like every stage) so the autopilot REPORTS the honest error via a
+        # failed GreenfieldResult instead of raising to the caller. Its own
+        # pseudo-stage name (not a real STAGES entry) so the failure is attributed
+        # honestly to intake, not to ``init``.
+        # Whether THIS run is a genuine first generation (the project is being
+        # created now) vs a re-run/resume of an already-progressed project. This is
+        # the ONLY context in which the stack-lock gate may bootstrap a missing lock
+        # (anti-gaming). It is read from the ON-DISK session INDEPENDENTLY of the
+        # ``resume`` flag — because a re-run WITHOUT ``--resume`` builds a fresh
+        # in-memory ``session`` (all-pending), which must NOT be mistaken for a first
+        # generation on an already-built project (GPT-consult leak: "absence of
+        # session ≠ first generation"). Fail-closed: any persisted completed stage ⇒
+        # not first-gen, so a deleted lock on a built project is RED, never silently
+        # re-bootstrapped to green.
+        on_disk = load_session(project_root)
+        first_generation = on_disk is None or not any(
+            rec.get("status") in _COMPLETE_STATUSES
+            for rec in on_disk.get("stages", {}).values()
+        )
+
+        try:
+            contract = self._intake_stack_contract(project_root, session)
+        except StageError as exc:
+            return self._fail(
+                project_root, session, options, "stack_intake",
+                {"status": STATUS_PENDING, "detail": ""}, str(exc),
+            )
+
+        # Stack lock ENFORCEMENT (Contract Kernel v2.77b) — turn the already-live
+        # stack contract into a red/green GATE. For stack-declared projects
+        # (contract is not None): drift / missing-in-resume = RED (anti-false-green);
+        # a first-generation missing lock is bootstrapped once (never overwritten —
+        # anti-gaming). For projects with NO stack block: byte-identical UNLESS a
+        # committed lock still exists (a removed declaration on a still-pinned
+        # project = RED, closing the "drop stack: to dodge the gate" bypass).
+        # Routed through _fail like intake so the autopilot reports it honestly.
+        try:
+            if contract is not None:
+                self._enforce_stack_lock(project_root, session, contract, first_generation)
+            else:
+                from codd.stack.lock import orphan_stack_lock
+
+                orphan = orphan_stack_lock(project_root)
+                if orphan is not None and orphan.red:
+                    self.echo(f"[greenfield] stack lock gate: {orphan.message}")
+                    raise StageError(orphan.message)
+        except StageError as exc:
+            return self._fail(
+                project_root, session, options, "stack_lock",
+                {"status": STATUS_PENDING, "detail": ""}, str(exc),
+            )
+
         runners: dict[str, Callable[[Path, dict[str, Any], dict[str, Any]], None]] = {
             "init": self._stage_init,
             "elicit": self._stage_elicit,
@@ -522,6 +582,91 @@ class GreenfieldPipeline:
         self._notify(options, f"greenfield {project_root.name}: FAILED at {stage_name} — {error}")
         return result
 
+    # ── stack contract intake (Contract Kernel v2.77a, intake only) ──
+
+    def _intake_stack_contract(self, project_root: Path, session: dict[str, Any]):
+        """Resolve the project's declared stack contract into the live run record + trace.
+
+        See the call site in :meth:`run`. INTAKE ONLY — proves the framework-stack
+        contract is LIVE-consumed (it enters the run record and the trace); it does
+        NOT enforce any obligation and does NOT change any pass/fail verdict
+        (obligation enforcement is v2.77b-e).
+
+        * No ``stack:`` block → no-op: nothing is added to the record and only a
+          single debug ``self.echo`` is emitted, so a non-stack project (the vast
+          majority) is behaviour-preserving. Returns ``None``.
+        * A declared stack → its :func:`stack_contract_trace` payload (incl.
+          ``stack_contract_hash``) is written to ``session["stack_contract"]`` and
+          echoed to the run trace. Returns the resolved ``ResolvedStackContract`` so
+          the v2.77b lock-enforcement gate (run after intake) can pin it.
+        * A declared-but-BROKEN stack → :class:`StageError` (honest error), never a
+          silent skip (anti-false-green / no-silent-fallback).
+        """
+        from codd.stack.project import stack_contract_intake, stack_contract_trace
+
+        try:
+            contract = stack_contract_intake(project_root)
+        except Exception as exc:  # noqa: BLE001 — a declared-but-broken stack must fail HONESTLY.
+            raise StageError(
+                "stack contract intake failed: the project declares a `stack:` block in "
+                f"codd.yaml but it could not be resolved ({type(exc).__name__}: {exc}). "
+                "A declared-but-unresolvable stack is an honest error, never a silent skip "
+                "(check the language / frameworks / addons ids against the curated stack "
+                "profiles, or remove the `stack:` block to opt out of the framework layer)."
+            ) from exc
+
+        if contract is None:
+            # The opt-in framework layer is unused — byte-identical behaviour.
+            self.echo("[greenfield] stack contract intake: no `stack:` block (framework layer opt-out)")
+            return None
+
+        trace = stack_contract_trace(contract)
+        session["stack_contract"] = dict(trace)
+        self.echo(
+            "[greenfield] stack contract intake: "
+            f"{trace['resolved_stack_id']} "
+            f"stack_contract_hash={trace['stack_contract_hash']}"
+        )
+        return contract
+
+    # ── stack lock enforcement (Contract Kernel v2.77b) ──
+
+    def _enforce_stack_lock(self, project_root: Path, session: dict[str, Any], contract, first_generation: bool) -> None:
+        """Enforce the project's stack lock as a red/green gate (v2.77b).
+
+        Only called for stack-declared projects (``contract is not None``); non-stack
+        projects never reach here, so they are byte-identical (no lock gate at all).
+
+        Design B′ (split read-only gate vs. creation-path bootstrap):
+
+        * genuine FIRST GENERATION (``first_generation`` True — no prior completed
+          stage) → :func:`bootstrap_stack_lock` writes the first lock (exclusive
+          create) and immediately enforces it read-only; ``generated`` is traced.
+        * otherwise (RESUME / already-progressed project) → read-only
+          :func:`enforce_stack_lock`: a missing lock is RED (an already-progressed
+          stack project with no committed pin is unverifiable; a deleted lock cannot
+          be silently regenerated), drift is RED, a valid lock is GREEN.
+
+        Anti-gaming (exit gate 3): the read-only gate NEVER writes/refreshes a lock;
+        ``bootstrap_stack_lock`` writes only when the lock is ABSENT (exclusive
+        create) on this creation path, so a drift cannot be silenced by regenerating
+        the lock. See :func:`enforce_stack_lock` / :func:`bootstrap_stack_lock`.
+        """
+        from codd.stack.lock import bootstrap_stack_lock, enforce_stack_lock
+
+        if first_generation:
+            gate = bootstrap_stack_lock(contract, project_root)
+        else:
+            gate = enforce_stack_lock(contract, project_root)
+        # Record the lock verdict in the run trace (observable, like the intake hash).
+        record = session.get("stack_contract")
+        if isinstance(record, dict):
+            record["stack_lock_status"] = gate.status
+            record["stack_lock_path"] = gate.lock_path
+        self.echo(f"[greenfield] stack lock gate: {gate.message}")
+        if gate.red:
+            raise StageError(gate.message)
+
     # ── option resolution ───────────────────────────────────
 
     def _resolve_options(self, project_root: Path) -> dict[str, Any]:

codd_dev-2.90.0/codd/stack/lock.py

@@ -0,0 +1,366 @@
+"""``codd.stack.lock`` — pin a resolved stack for deterministic CI (design §2/§決定性).
+
+Auto-detection (package.json has ``next`` → use the Next.js profile) is convenient
+for ``local init`` only. In CI the lock is the SOURCE OF TRUTH: the resolved
+contract is recomputed and any divergence from the lock (a layer version bump, a
+profile edit changing a digest, a different resolved-contract hash) is RED, so a
+profile change can never silently alter a project's contract.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+import yaml
+
+from .compose import ResolvedStackContract
+
+#: The lock file lives next to ``codd.yaml`` inside the project's CoDD config dir
+#: (so ``<project>/codd/stack.lock`` or ``<project>/.codd/stack.lock``). The
+#: module docstring's ``codd.stack.lock`` is this file.
+LOCK_FILENAME = "stack.lock"
+
+LOCK_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class LockedLayer:
+    id: str
+    kind: str
+    version: str
+    digest: str
+
+
+@dataclass(frozen=True)
+class StackLock:
+    schema_version: int
+    stack_id: str
+    layers: tuple[LockedLayer, ...]
+    resolved_contract_digest: str
+    adapter_digests: Mapping[str, str] = field(default_factory=dict)
+    permissions: Mapping[str, Any] = field(default_factory=dict)
+
+
+def build_lock(
+    contract: ResolvedStackContract,
+    *,
+    adapter_digests: Mapping[str, str] | None = None,
+    permissions: Mapping[str, Any] | None = None,
+) -> StackLock:
+    """Derive a :class:`StackLock` from a resolved contract."""
+    return StackLock(
+        schema_version=LOCK_SCHEMA_VERSION,
+        stack_id=contract.stack_id,
+        layers=tuple(
+            LockedLayer(id=l.id, kind=l.kind, version=l.profile_version, digest=l.digest)
+            for l in contract.layers
+        ),
+        resolved_contract_digest=contract.content_hash,
+        adapter_digests=dict(adapter_digests or {}),
+        permissions=dict(permissions or {}),
+    )
+
+
+def lock_to_dict(lock: StackLock) -> dict[str, Any]:
+    return {
+        "schema_version": lock.schema_version,
+        "stack_id": lock.stack_id,
+        "layers": [
+            {"id": l.id, "kind": l.kind, "version": l.version, "digest": l.digest}
+            for l in lock.layers
+        ],
+        "resolved_contract_digest": lock.resolved_contract_digest,
+        "adapter_digests": dict(lock.adapter_digests),
+        "permissions": dict(lock.permissions),
+    }
+
+
+def dump_lock(lock: StackLock) -> str:
+    """Serialize a lock to YAML (stable key order for clean diffs)."""
+    return yaml.safe_dump(lock_to_dict(lock), sort_keys=True, default_flow_style=False)
+
+
+def parse_lock(data: str | Mapping[str, Any]) -> StackLock:
+    doc = yaml.safe_load(data) if isinstance(data, str) else dict(data)
+    if not isinstance(doc, Mapping):
+        raise ValueError("codd.stack.lock must be a mapping at the top level")
+    layers = tuple(
+        LockedLayer(
+            id=str(l["id"]),
+            kind=str(l.get("kind", "")),
+            version=str(l.get("version", "")),
+            digest=str(l.get("digest", "")),
+        )
+        for l in (doc.get("layers") or [])
+    )
+    return StackLock(
+        schema_version=int(doc.get("schema_version", LOCK_SCHEMA_VERSION)),
+        stack_id=str(doc.get("stack_id", "")),
+        layers=layers,
+        resolved_contract_digest=str(doc.get("resolved_contract_digest", "")),
+        adapter_digests=dict(doc.get("adapter_digests") or {}),
+        permissions=dict(doc.get("permissions") or {}),
+    )
+
+
+def verify_lock(contract: ResolvedStackContract, lock: StackLock) -> tuple[bool, list[str]]:
+    """Check a freshly-resolved contract against a pinned lock (CI gate).
+
+    Returns ``(ok, diffs)``. ``ok`` is False (CI RED) when the resolved contract
+    diverges from the lock — a layer set/version/digest change, or a different
+    resolved-contract digest (a profile edit that silently changed the contract).
+    """
+    diffs: list[str] = []
+    if contract.stack_id != lock.stack_id:
+        diffs.append(f"stack_id: contract={contract.stack_id!r} lock={lock.stack_id!r}")
+
+    contract_layers = {l.id: l for l in contract.layers}
+    lock_layers = {l.id: l for l in lock.layers}
+    for lid in sorted(set(contract_layers) | set(lock_layers)):
+        if lid not in contract_layers:
+            diffs.append(f"layer {lid!r}: in lock but not resolved")
+            continue
+        if lid not in lock_layers:
+            diffs.append(f"layer {lid!r}: resolved but not in lock")
+            continue
+        c, k = contract_layers[lid], lock_layers[lid]
+        if c.profile_version != k.version:
+            diffs.append(f"layer {lid!r} version: contract={c.profile_version} lock={k.version}")
+        if c.digest and k.digest and c.digest != k.digest:
+            diffs.append(f"layer {lid!r} digest changed (profile edited)")
+
+    if contract.content_hash != lock.resolved_contract_digest:
+        diffs.append(
+            "resolved_contract_digest changed "
+            f"(contract={contract.content_hash[:23]}… lock={lock.resolved_contract_digest[:23]}…)"
+        )
+    return (not diffs, diffs)
+
+
+# ── enforcement gate (Contract Kernel v2.77b — Stack Lock Enforcement) ───────
+#
+# v2.77a brought the stack contract LIVE (intake-only). v2.77b turns the
+# already-existing lock logic above into a GATE so stack-contract drift is RED.
+#
+# Anti-false-green is the entire point of this step. The design (B′, confirmed by
+# a GPT-5.5 Pro consult — see the task report) SPLITS the two responsibilities so
+# the gate has NO "verify-or-create" mixed semantics — the one and only thing that
+# could turn a drift-RED into green:
+#
+#   * :func:`enforce_stack_lock` is STRICTLY READ-ONLY. It NEVER writes/refreshes
+#     a lock. missing → RED, parse-error → RED, drift → RED, valid → GREEN. Both
+#     the verify path and the greenfield path call THIS for the verdict.
+#   * :func:`bootstrap_stack_lock` is the ONLY writer, and it uses EXCLUSIVE
+#     create (``open(..., "x")``): it writes only when the lock is ABSENT and is
+#     invoked only on a positively-identified project-creation path (greenfield
+#     first generation). It refuses to overwrite, so it cannot refresh a drift.
+#
+# ANTI-GAMING (exit gate 3, the crux): ``verify_lock(contract,
+# build_lock(contract))`` is ALWAYS ok by construction — a drift can be MASKED by
+# rewriting the lock to match. So the verify path can't detect gaming; the control
+# is "who may WRITE a lock, and when". Here: the read-only gate writes nothing
+# ever, and bootstrap writes only on exclusive-create in the creation path. A
+# drift against a committed lock is RED on every path and is never refreshed by
+# either function; auto-repair re-running the gate keeps seeing drift-RED.
+# Refreshing a drifted lock requires an explicit out-of-band proof
+# (``replace_with_proof``-style; full repair governance is v2.77f).
+#
+# WHY NOT "missing + absent-session ⇒ generate": absence of a session is NOT
+# proof of first generation (it can be a deleted session, a copied project, an
+# existing repo, or auto-repair having cleaned local state). Generation therefore
+# belongs to an explicit creation path (bootstrap), and the gate fails CLOSED
+# (missing = RED) everywhere else — the delete-and-regenerate attack cannot
+# silence a drift because the gate never participates in regeneration.
+
+#: ``StackLockGate.status`` values.
+LOCK_OK = "ok"  # a committed lock matches the resolved contract (GREEN).
+LOCK_DRIFT = "drift"  # a committed lock diverges / is unparseable (RED).
+LOCK_MISSING = "missing"  # no committed lock where one must exist (RED).
+LOCK_GENERATED = "generated"  # bootstrap wrote the first lock (GREEN, traced).
+
+
+def stack_lock_path(project_root: str | Path) -> Path:
+    """Return the path of a project's stack lock file (next to ``codd.yaml``).
+
+    Resolved from the canonical project root via the same config-dir discovery as
+    :func:`codd.config.load_project_config` (``codd/`` then ``.codd/``), NOT from a
+    mutable CWD. If no config dir is discoverable yet, defaults to
+    ``<project_root>/codd/stack.lock`` so a first-generation greenfield run (which
+    has just created ``codd/``) bootstraps the lock in the canonical place.
+    """
+    from codd.config import find_codd_dir
+
+    root = Path(project_root)
+    codd_dir = find_codd_dir(root)
+    if codd_dir is None:
+        codd_dir = root / "codd"
+    return codd_dir / LOCK_FILENAME
+
+
+@dataclass(frozen=True)
+class StackLockGate:
+    """The verdict of the (read-only) stack-lock enforcement gate (v2.77b).
+
+    ``red`` is the single anti-false-green signal the pipeline/verify call-sites
+    act on: ``drift`` and ``missing`` are RED; ``ok`` is GREEN; ``generated`` is the
+    GREEN result returned right after :func:`bootstrap_stack_lock` writes the first
+    lock. ``reasons`` carry the human-readable drift diffs.
+    """
+
+    status: str
+    red: bool
+    reasons: tuple[str, ...] = ()
+    lock_path: str = ""
+
+    @property
+    def message(self) -> str:
+        if self.status == LOCK_OK:
+            return f"stack lock OK ({self.lock_path})"
+        if self.status == LOCK_GENERATED:
+            return f"stack lock generated (first generation) at {self.lock_path}"
+        if self.status == LOCK_MISSING:
+            return (
+                f"stack lock MISSING at {self.lock_path}: a project that declares a "
+                "`stack:` block must commit a stack lock — an unpinned stack contract is "
+                "unverifiable (anti-false-green). It is generated once on a first "
+                "`codd greenfield` run; the enforcement gate is read-only and will never "
+                "silently create it (a missing lock outside first generation is RED, so a "
+                "deleted lock cannot be silently regenerated to green)."
+            )
+        # drift (incl. present-but-unparseable lock)
+        joined = "; ".join(self.reasons) if self.reasons else "resolved contract diverges from the lock"
+        return (
+            f"stack lock DRIFT ({self.lock_path}): the resolved stack contract no longer "
+            f"matches the committed lock [{joined}]. This is RED. Rewriting the lock to "
+            "match does NOT clear this — the gate is read-only and never refreshes a lock; "
+            "a drift requires reverting the contract change or an explicit proof-backed "
+            "lock update (replace_with_proof)."
+        )
+
+
+def enforce_stack_lock(
+    contract: ResolvedStackContract, project_root: str | Path
+) -> StackLockGate:
+    """Read-only stack-lock gate for a resolved contract (the v2.77b enforcement).
+
+    ``contract`` is the freshly-resolved :class:`ResolvedStackContract` (the caller
+    has already intaken it — v2.77a). This function reads the project's committed
+    lock and returns a verdict; it NEVER writes or refreshes the lock (so it cannot
+    turn a drift-RED into green — exit gate 3):
+
+    * **missing** — no committed lock → ``red=True`` (``status=missing``). A stack
+      project with no pin is unverifiable; generation is the separate
+      :func:`bootstrap_stack_lock` responsibility (creation path only).
+    * **parse error** — a present-but-unparseable lock → ``red=True``
+      (``status=drift``). A broken lock is NEVER treated as "missing" (which could
+      invite regeneration).
+    * **drift** — a committed lock exists but :func:`verify_lock` reports
+      divergence → ``red=True`` (``status=drift``).
+    * **valid** — a committed lock matches → ``status=ok``, ``red=False``.
+    """
+    path = stack_lock_path(project_root)
+    path_str = str(path)
+
+    if not path.exists():
+        return StackLockGate(status=LOCK_MISSING, red=True, lock_path=path_str)
+
+    try:
+        lock = parse_lock(path.read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001 — any read/parse failure is RED, never "missing".
+        # A present-but-unreadable/corrupt lock is NOT a pass and is NOT "missing"
+        # (which could invite regeneration): it is drift (RED).
+        return StackLockGate(
+            status=LOCK_DRIFT,
+            red=True,
+            reasons=(f"lock file present but unparseable: {type(exc).__name__}: {exc}",),
+            lock_path=path_str,
+        )
+
+    ok, diffs = verify_lock(contract, lock)
+    if ok:
+        return StackLockGate(status=LOCK_OK, red=False, lock_path=path_str)
+    # DRIFT — RED. Read-only: the lock is left untouched (anti-gaming, exit gate 3).
+    return StackLockGate(status=LOCK_DRIFT, red=True, reasons=tuple(diffs), lock_path=path_str)
+
+
+def bootstrap_stack_lock(
+    contract: ResolvedStackContract,
+    project_root: str | Path,
+    *,
+    adapter_digests: Mapping[str, str] | None = None,
+    permissions: Mapping[str, Any] | None = None,
+) -> StackLockGate:
+    """Write a project's FIRST stack lock (creation path only) — the ONLY writer.
+
+    Invoked ONLY on a positively-identified project-creation path (greenfield first
+    generation), never by the enforcement gate, never by verify/resume, never by
+    repair. Uses EXCLUSIVE create (``open(..., "x")``): it writes the lock iff it is
+    ABSENT and refuses to overwrite an existing lock. This is what makes the
+    delete-and-regenerate / drift-refresh attacks impossible — bootstrap cannot
+    refresh a drifted (existing) lock, and a missing lock outside the creation path
+    is RED at the read-only gate.
+
+    Returns the read-only :func:`enforce_stack_lock` verdict computed AFTER the
+    write (so the freshly-written lock is immediately verified — ``status=ok`` on
+    success). If the lock already exists, NOTHING is written and the existing lock
+    is enforced as-is (so a pre-existing drift stays RED).
+    """
+    path = stack_lock_path(project_root)
+    if not path.exists():
+        lock = build_lock(contract, adapter_digests=adapter_digests, permissions=permissions)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            # Exclusive create — refuse to clobber an existing lock (TOCTOU-safe).
+            with open(path, "x", encoding="utf-8") as fh:
+                fh.write(dump_lock(lock))
+        except FileExistsError:
+            # Raced: a lock appeared between the check and the create. Fall through
+            # to enforce the now-existing lock read-only (never overwrite it).
+            pass
+        else:
+            # Immediately enforce the freshly-written lock (read-only); on success
+            # surface it as GENERATED (traced) rather than a plain OK.
+            gate = enforce_stack_lock(contract, project_root)
+            if gate.status == LOCK_OK:
+                return StackLockGate(status=LOCK_GENERATED, red=False, lock_path=gate.lock_path)
+            return gate
+
+    # Lock already exists (or appeared in a race) — enforce it read-only, NEVER
+    # overwrite. A pre-existing drift therefore stays RED.
+    return enforce_stack_lock(contract, project_root)
+
+
+def orphan_stack_lock(project_root: str | Path) -> StackLockGate | None:
+    """Catch a removed ``stack:`` declaration that still has a committed lock.
+
+    Closes the "drop the ``stack:`` block to dodge the gate" bypass (GPT-consult
+    point #1): a project with a committed ``stack.lock`` is demonstrably
+    stack-governed, so silently removing its declaration would convert it to an
+    ungoverned project (false-green). This is called ONLY when the project has NO
+    resolved stack contract (``stack_contract_intake`` returned ``None``):
+
+    * a committed lock still present → RED (``status=drift``): the declaration was
+      removed but the project is still pinned. Decommission explicitly (delete the
+      lock) to opt out.
+    * no lock → ``None`` (a genuine non-stack project — byte-identical, no gate).
+
+    Returning ``None`` is the byte-identical path that preserves the "non-stack
+    projects are completely unaffected" guarantee (those have no lock file).
+    """
+    path = stack_lock_path(project_root)
+    if not path.exists():
+        return None
+    return StackLockGate(
+        status=LOCK_DRIFT,
+        red=True,
+        reasons=(
+            "a committed stack.lock exists but the project no longer declares a "
+            "`stack:` block — the stack declaration was removed while the lock "
+            "remains. A stack-governed project cannot silently become ungoverned "
+            "(anti-false-green). Restore the `stack:` block, or decommission "
+            "explicitly by deleting the lock.",
+        ),
+        lock_path=str(path),
+    )

{codd_dev-2.88.0 → codd_dev-2.90.0}/codd/stack/project.py

@@ -68,3 +68,45 @@ def verify_project_stack(
     if contract is None:
         return None
     return enforce_obligations(contract, project_root=project_root, **checker_inputs)
+
+
+def stack_contract_trace(contract: ResolvedStackContract) -> dict[str, Any]:
+    """Run-trace fields proving a run consumed the resolved stack contract.
+
+    Mirrors :meth:`codd.languages.contract.ResolvedLanguageContract.to_trace`: the
+    minimal, deterministic facts a run record / trace records so the live-consumption
+    of the framework-stack contract is observable (the v2.77a intake exit gate).
+    ``stack_contract_hash`` is the deterministic :attr:`ResolvedStackContract.content_hash`;
+    ``resolved_stack_id`` / ``resolved_stack_layers`` make "changing the profile changes
+    the plan" visible in the record itself.
+    """
+    return {
+        "resolved_stack_id": contract.stack_id,
+        "stack_contract_hash": contract.content_hash,
+        "resolved_stack_layers": [f"{ref.kind}:{ref.id}" for ref in contract.layers],
+    }
+
+
+def stack_contract_intake(project_root: str | Path) -> ResolvedStackContract | None:
+    """Resolve a project's declared stack contract for LIVE consumption (intake only).
+
+    This is the production seam the greenfield/verify pipeline calls EARLY in a run
+    to bring the (previously dormant) framework-stack contract into the live run —
+    *without* enforcing any obligation yet (enforcement is v2.77b-e). It is exactly
+    :func:`resolve_project_stack`, named for the intake call-site so the
+    "no non-test caller = 0 state" is eliminated by an unambiguous production caller.
+
+    Contract:
+
+    * No ``stack:`` block (the opt-in framework layer is unused) → ``None``. The
+      vast majority of projects; behaviour is byte-identical, never an error.
+    * A declared ``stack:`` block → the :class:`ResolvedStackContract` (its
+      ``content_hash`` is the run-trace hash; see :func:`stack_contract_trace`).
+    * A declared-but-BROKEN block (unknown language/framework/addon, malformed
+      mapping) → the resolver RAISES (``ValueError`` / ``UnknownLanguageError`` /
+      ``UnknownLayerError``). The intake NEVER swallows this: anti-false-green
+      forbids a declared-but-unresolvable stack from silently proceeding as if no
+      stack were declared. The pipeline call-site turns the raise into an honest
+      stage/command failure.
+    """
+    return resolve_project_stack(project_root)

{codd_dev-2.88.0 → codd_dev-2.90.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codd-dev"
-version = "2.88.0"
+version = "2.90.0"
 description = "CoDD: Coherence-Driven Development — cross-artifact change impact analysis"
 readme = "README.md"
 license = "MIT"