repocodex 0.0.1__tar.gz

repocodex-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajay Lamba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

repocodex-0.0.1/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: repocodex
+Version: 0.0.1
+Summary: Repository-native executable memory for coding agents
+Author: Ajay Lamba
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/azaylamba/repocodex
+Project-URL: Source, https://github.com/azaylamba/repocodex
+Project-URL: Issues, https://github.com/azaylamba/repocodex/issues
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.27.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1.1; extra == "dev"
+Requires-Dist: ruff>=0.12.0; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.1.1; extra == "mcp"
+Dynamic: license-file
+
+# RepoCodex
+
+[![Engine tests](https://img.shields.io/github/actions/workflow/status/azaylamba/repocodex/engine-tests.yml?branch=main&label=Engine%20tests)](https://github.com/azaylamba/repocodex/actions/workflows/engine-tests.yml)
+
+**Git-native why next to code — with a pin check that proves it still matches.**
+
+Coding agents write syntax well and forget _why_. Comments rot. Instruction files (`CLAUDE.md`, `AGENTS.md`, Cursor rules) never prove they still describe live text. Tests check behavior you remembered to assert; they do not keep institutional why attached to the lines that implement it.
+
+RepoCodex stores that why in git beside the code. Agents retrieve it before they edit. A deterministic pin check (ripgrep + git) attests the attachment. Built for repositories where coding agents make the changes.
+
+**Not** a test suite. **Not** another instruction file. **Not** a linter.
+
+Experimental `0.0.1`. Requires Python 3.11+ and [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) on `PATH`.
+
+## Install
+
+```bash
+pip install "repocodex==0.0.1"
+# or from a local clone: pip install -e .
+repocodex install
+```
+
+`repocodex install` writes the pre-commit hook, GitHub Action, agent skills, and `.repocodex.toml` (engine pin). The product is that loop: agents retrieve stored why before they edit, so they do not silently break existing behavior; the pin check fails the turn when why and code diverge, and a first substantive edit of an uncovered file is denied until a pinning concept is written.
+
+```bash
+repocodex context src/billing/PaymentGateway.ts   # retrieve why before edit
+repocodex validate --diff                         # attest pins still hold
+```
+
+Pin the engine in `.repocodex.toml`. Hook, local CLI, and CI resolve that pin so verdicts agree.
+
+## What a concept looks like
+
+Types are orthogonal — one change may write more than one. Three common shapes:
+
+**TechnicalDecision** (`decisions/…`) — why this construct exists:
+
+```yaml
+---
+title: Capture streams enterprise retries instead of buffering
+type: TechnicalDecision
+verification:
+  engine: ripgrep
+  anchors:
+    - path: src/billing/PaymentGateway.ts
+      all_of: ["yield", "ENTERPRISE", "capturePayment"]
+---
+Enterprise capture is a generator so retries stay backpressure-aware. Do not
+replace with an in-memory list of attempts.
+```
+
+**InvariantContract** (`invariants/…`) — must-hold token (requires `claims`):
+
+```yaml
+---
+title: Enterprise capture grace is three attempts
+type: InvariantContract
+verification:
+  engine: ripgrep
+  anchors:
+    - path: src/billing/PaymentGateway.ts
+      all_of: ["ENTERPRISE", "grace", "= 3"]
+claims:
+  - subject: enterprise_grace_attempts
+    literal: "3"
+---
+Enterprise plans get three capture retries before failure. Do not silently shrink this window.
+```
+
+**BusinessWorkflow** (`workflows/…`) — thin cross-package flow (one anchor per site):
+
+```yaml
+---
+title: Checkout capture flows api → billing → ledger
+type: BusinessWorkflow
+verification:
+  engine: ripgrep
+  anchors:
+    - path: src/api/checkout.ts
+      all_of: ["capturePayment", "billing"]
+    - path: src/billing/PaymentGateway.ts
+      all_of: ["capturePayment", "ledger"]
+    - path: src/ledger/posting.ts
+      all_of: ["postCapture", "idempotency"]
+---
+Checkout capture crosses api, billing, then ledger. Keep that order; do not
+post to the ledger from the API layer.
+```
+
+## Docs
+
+| Doc | Job |
+| --- | --- |
+| [How it works](https://github.com/azaylamba/repocodex/blob/main/docs/how-it-works.md) | Purpose, benefit, and the retrieve → read → edit → update why → pin-check loop |
+| [Memory](https://github.com/azaylamba/repocodex/blob/main/docs/memory.md) | How to read `.context/` |
+| [Agents](https://github.com/azaylamba/repocodex/blob/main/docs/agents.md) | How coding agents (and optionally humans) run the loop |
+| [Install](https://github.com/azaylamba/repocodex/blob/main/docs/install.md) | CLI, pin, hook, GitHub Action, optional MCP |
+| [Architecture](https://github.com/azaylamba/repocodex/blob/main/docs/architecture.md) | Current engine architecture (further reading) |
+
+## License and contributing
+
+[MIT](https://github.com/azaylamba/repocodex/blob/main/LICENSE) · [Contributing](https://github.com/azaylamba/repocodex/blob/main/CONTRIBUTING.md) · [Security](https://github.com/azaylamba/repocodex/blob/main/SECURITY.md)
+
+Created by [Ajay Lamba](https://github.com/azaylamba/repocodex).

repocodex-0.0.1/README.md

@@ -0,0 +1,104 @@
+# RepoCodex
+
+[![Engine tests](https://img.shields.io/github/actions/workflow/status/azaylamba/repocodex/engine-tests.yml?branch=main&label=Engine%20tests)](https://github.com/azaylamba/repocodex/actions/workflows/engine-tests.yml)
+
+**Git-native why next to code — with a pin check that proves it still matches.**
+
+Coding agents write syntax well and forget _why_. Comments rot. Instruction files (`CLAUDE.md`, `AGENTS.md`, Cursor rules) never prove they still describe live text. Tests check behavior you remembered to assert; they do not keep institutional why attached to the lines that implement it.
+
+RepoCodex stores that why in git beside the code. Agents retrieve it before they edit. A deterministic pin check (ripgrep + git) attests the attachment. Built for repositories where coding agents make the changes.
+
+**Not** a test suite. **Not** another instruction file. **Not** a linter.
+
+Experimental `0.0.1`. Requires Python 3.11+ and [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) on `PATH`.
+
+## Install
+
+```bash
+pip install "repocodex==0.0.1"
+# or from a local clone: pip install -e .
+repocodex install
+```
+
+`repocodex install` writes the pre-commit hook, GitHub Action, agent skills, and `.repocodex.toml` (engine pin). The product is that loop: agents retrieve stored why before they edit, so they do not silently break existing behavior; the pin check fails the turn when why and code diverge, and a first substantive edit of an uncovered file is denied until a pinning concept is written.
+
+```bash
+repocodex context src/billing/PaymentGateway.ts   # retrieve why before edit
+repocodex validate --diff                         # attest pins still hold
+```
+
+Pin the engine in `.repocodex.toml`. Hook, local CLI, and CI resolve that pin so verdicts agree.
+
+## What a concept looks like
+
+Types are orthogonal — one change may write more than one. Three common shapes:
+
+**TechnicalDecision** (`decisions/…`) — why this construct exists:
+
+```yaml
+---
+title: Capture streams enterprise retries instead of buffering
+type: TechnicalDecision
+verification:
+  engine: ripgrep
+  anchors:
+    - path: src/billing/PaymentGateway.ts
+      all_of: ["yield", "ENTERPRISE", "capturePayment"]
+---
+Enterprise capture is a generator so retries stay backpressure-aware. Do not
+replace with an in-memory list of attempts.
+```
+
+**InvariantContract** (`invariants/…`) — must-hold token (requires `claims`):
+
+```yaml
+---
+title: Enterprise capture grace is three attempts
+type: InvariantContract
+verification:
+  engine: ripgrep
+  anchors:
+    - path: src/billing/PaymentGateway.ts
+      all_of: ["ENTERPRISE", "grace", "= 3"]
+claims:
+  - subject: enterprise_grace_attempts
+    literal: "3"
+---
+Enterprise plans get three capture retries before failure. Do not silently shrink this window.
+```
+
+**BusinessWorkflow** (`workflows/…`) — thin cross-package flow (one anchor per site):
+
+```yaml
+---
+title: Checkout capture flows api → billing → ledger
+type: BusinessWorkflow
+verification:
+  engine: ripgrep
+  anchors:
+    - path: src/api/checkout.ts
+      all_of: ["capturePayment", "billing"]
+    - path: src/billing/PaymentGateway.ts
+      all_of: ["capturePayment", "ledger"]
+    - path: src/ledger/posting.ts
+      all_of: ["postCapture", "idempotency"]
+---
+Checkout capture crosses api, billing, then ledger. Keep that order; do not
+post to the ledger from the API layer.
+```
+
+## Docs
+
+| Doc | Job |
+| --- | --- |
+| [How it works](https://github.com/azaylamba/repocodex/blob/main/docs/how-it-works.md) | Purpose, benefit, and the retrieve → read → edit → update why → pin-check loop |
+| [Memory](https://github.com/azaylamba/repocodex/blob/main/docs/memory.md) | How to read `.context/` |
+| [Agents](https://github.com/azaylamba/repocodex/blob/main/docs/agents.md) | How coding agents (and optionally humans) run the loop |
+| [Install](https://github.com/azaylamba/repocodex/blob/main/docs/install.md) | CLI, pin, hook, GitHub Action, optional MCP |
+| [Architecture](https://github.com/azaylamba/repocodex/blob/main/docs/architecture.md) | Current engine architecture (further reading) |
+
+## License and contributing
+
+[MIT](https://github.com/azaylamba/repocodex/blob/main/LICENSE) · [Contributing](https://github.com/azaylamba/repocodex/blob/main/CONTRIBUTING.md) · [Security](https://github.com/azaylamba/repocodex/blob/main/SECURITY.md)
+
+Created by [Ajay Lamba](https://github.com/azaylamba/repocodex).

repocodex-0.0.1/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=84.0.0", "wheel>=0.48.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "repocodex"
+version = "0.0.1"
+description = "Repository-native executable memory for coding agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ajay Lamba" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+]
+dependencies = [
+    "typer>=0.27.1",
+    "pydantic>=2.13.4",
+    "pyyaml>=6.0.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/azaylamba/repocodex"
+Source = "https://github.com/azaylamba/repocodex"
+Issues = "https://github.com/azaylamba/repocodex/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.12.0",
+]
+mcp = [
+    "mcp>=2.1.1",
+]
+
+[project.scripts]
+repocodex = "repocodex.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+repocodex = ["data/**/*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = "-q"
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.ruff]
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["D"]
+ignore = ["D105", "D107"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/test_*.py" = ["D101", "D102", "D103"]

repocodex-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

repocodex-0.0.1/src/repocodex/__init__.py

@@ -0,0 +1,6 @@
+"""RepoCodex engine: repository-native executable memory for coding agents."""
+
+from __future__ import annotations
+
+ENGINE_VERSION = "0.0.1"
+__version__ = ENGINE_VERSION

repocodex-0.0.1/src/repocodex/__main__.py

@@ -0,0 +1,8 @@
+"""Run the RepoCodex CLI as `python -m repocodex`."""
+
+from __future__ import annotations
+
+from repocodex.cli import app
+
+if __name__ == "__main__":
+    app()

repocodex-0.0.1/src/repocodex/cli.py

@@ -0,0 +1,189 @@
+"""Typer CLI for RepoCodex. Commands print JSON envelopes and exit non-zero on failure."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from repocodex.commands.advisory import advisory as run_advisory
+from repocodex.commands.audit import audit as run_audit
+from repocodex.commands.bootstrap import bootstrap as run_bootstrap
+from repocodex.commands.context import context_for
+from repocodex.commands.install import install as run_install
+from repocodex.commands.reconcile import apply_anchor_patch, reconcile_memory
+from repocodex.commands.relocate import relocate_memory
+from repocodex.commands.repair import repair as run_repair
+from repocodex.commands.validate import validate as run_validate
+from repocodex.commands.write import write_memory
+from repocodex.config import EngineVersionMismatch
+from repocodex.schema import envelope
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="RepoCodex executable memory CLI")
+
+
+def _emit(payload: dict, exit_code: int = 0) -> None:
+    """Print ``payload`` as JSON and exit with ``exit_code``."""
+    typer.echo(json.dumps(payload, indent=2))
+    raise typer.Exit(exit_code)
+
+
+def _repo() -> Path:
+    """Return the process working directory as the target repository."""
+    return Path.cwd()
+
+
+def _guarded(fn):
+    """Run ``fn`` and emit an engine-version-mismatch envelope on pin failure."""
+    try:
+        return fn()
+    except EngineVersionMismatch as exc:
+        _emit(exc.to_json(), 1)
+        raise
+
+
+@app.command("validate")
+def validate_command(
+    diff: bool = typer.Option(False, "--diff", help="Attest anchors intersecting the diff"),
+    base: Optional[str] = typer.Option(None, "--base", help="Git diff base, e.g. origin/main...HEAD"),
+    staged: bool = typer.Option(False, "--staged"),
+    all_concepts: bool = typer.Option(False, "--all"),
+    check: bool = typer.Option(False, "--check", help="Exit 1 on deterministic blocking outcomes"),
+    hook: bool = typer.Option(False, "--hook"),
+    memory_exempt: bool = typer.Option(False, "--memory-exempt"),
+    review_ack: bool = typer.Option(False, "--review-ack", hidden=True),
+    ack_file: Optional[Path] = typer.Option(None, "--ack-file", help="Tracked review-agent acknowledgment record"),
+    apply_patches: bool = typer.Option(False, "--apply-patches"),
+) -> None:
+    """Attest anchors on the working tree or diff. JSON includes engine_version."""
+    payload = _guarded(
+        lambda: run_validate(
+            _repo(),
+            base=base,
+            staged=staged or hook,
+            all_concepts=all_concepts or not diff,
+            memory_exempt=memory_exempt,
+            review_ack=review_ack,
+            ack_file=str(ack_file) if ack_file else None,
+        )
+    )
+    if apply_patches:
+        for patch in payload.get("patches") or []:
+            apply_anchor_patch(_repo(), patch)
+            payload.setdefault("applied_patches", []).append(patch)
+    code = 1 if (check or hook) and payload.get("blocking") else 0
+    _emit(payload, code)
+
+
+@app.command("write")
+def write_command(
+    concept: Optional[Path] = typer.Argument(None),
+    identity: Optional[str] = typer.Option(None, "--identity"),
+    stdin: bool = typer.Option(False, "--stdin"),
+) -> None:
+    """Write-gate a concept into .context/."""
+    text = None
+    if stdin:
+        text = typer.get_text_stream("stdin").read()
+    if concept is None and text is None:
+        raise typer.BadParameter("provide a concept file or --stdin")
+    payload = _guarded(lambda: write_memory(_repo(), concept or Path("."), identity=identity, stdin_text=text))
+    _emit(payload, 0 if payload.get("accepted") else 1)
+
+
+@app.command("relocate")
+def relocate_command(
+    identity: Optional[str] = typer.Argument(None),
+    mismatched: bool = typer.Option(
+        False, "--mismatched", help="Move all authored-type concepts with wrong prefixes"
+    ),
+) -> None:
+    """Move authored concepts into the type-folder identity required by their type."""
+    if not mismatched and not identity:
+        raise typer.BadParameter("provide an identity or --mismatched")
+    payload = _guarded(lambda: relocate_memory(_repo(), identity, mismatched=mismatched))
+    _emit(payload)
+
+
+@app.command("reconcile")
+def reconcile_command(
+    concept: Optional[Path] = typer.Argument(None),
+    identity: Optional[str] = typer.Option(None, "--identity"),
+    apply_patch: Optional[str] = typer.Option(None, "--apply-patch", help="JSON patch object"),
+) -> None:
+    """Repair DRIFT with gate-enforced new anchors, or apply a REANCHOR patch."""
+    repo = _repo()
+    if apply_patch:
+        patch = json.loads(apply_patch)
+        path = apply_anchor_patch(repo, patch)
+        _emit(envelope({"applied": True, "path": str(path)}))
+    if concept is None:
+        raise typer.BadParameter("provide a concept file")
+    payload = _guarded(lambda: reconcile_memory(repo, concept, identity=identity))
+    _emit(payload, 0 if payload.get("accepted") else 1)
+
+
+@app.command("context")
+def context_command(
+    paths: list[Path] = typer.Argument(..., metavar="PATHS"),
+    drafts: bool = typer.Option(False, "--drafts"),
+) -> None:
+    """Staged retrieval: reverse index → catalogs → bodies + one link-hop of titles."""
+    payload = _guarded(lambda: context_for(_repo(), [str(p) for p in paths], include_drafts=drafts))
+    _emit(payload)
+
+
+@app.command("repair")
+def repair_command() -> None:
+    """Invoke a repair agent against the current RECONCILE state."""
+    payload = _guarded(lambda: run_repair(_repo()))
+    code = 1 if payload.get("error") else 0
+    _emit(payload, code)
+
+
+@app.command("install")
+def install_command(
+    mcp: bool = typer.Option(False, "--mcp", help="Register optional MCP wrapper"),
+) -> None:
+    """Install pre-commit hook, GitHub Action, skills, and optional MCP."""
+    payload = _guarded(lambda: run_install(_repo(), mcp=mcp))
+    _emit(payload, 0 if payload.get("ok", True) else 1)
+
+
+@app.command("bootstrap")
+def bootstrap_command() -> None:
+    """Mine history/comments/docs; keep only gate-passing drafts."""
+    _emit(_guarded(lambda: run_bootstrap(_repo())))
+
+
+@app.command("audit")
+def audit_command(
+    sample_size: int = typer.Option(10, "--sample-size"),
+    seed: int = typer.Option(0, "--seed"),
+    findings: Optional[Path] = typer.Option(None, "--findings", help="Out-of-band screening result JSON"),
+) -> None:
+    """Emit a screening payload for out-of-band review. No model is invoked."""
+    _emit(
+        _guarded(
+            lambda: run_audit(_repo(), sample_size=sample_size, seed=seed, findings_path=findings)
+        )
+    )
+
+
+@app.command("advisory")
+def advisory_command(
+    base: Optional[str] = typer.Option(None, "--base"),
+    staged: bool = typer.Option(False, "--staged"),
+) -> None:
+    """Agent-judged findings for the advisory CI check. Never affects the required verdict."""
+    _emit(_guarded(lambda: run_advisory(_repo(), base=base, staged=staged)))
+
+
+@app.command("mcp")
+def mcp_command() -> None:
+    """Run the optional MCP server wrapping the CLI."""
+    from repocodex.mcp_server import run_mcp
+
+    run_mcp()

repocodex-0.0.1/src/repocodex/commands/__init__.py

@@ -0,0 +1,3 @@
+"""CLI command implementations invoked from `repocodex.cli`."""
+
+from __future__ import annotations

repocodex-0.0.1/src/repocodex/commands/advisory.py

@@ -0,0 +1,95 @@
+"""Rank code-side impact and wrap optional agent judgments into a non-blocking advisory envelope."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from repocodex.commands.validate import changed_files
+from repocodex.config import load_config
+from repocodex.engine.code_impact import rank_code_hits
+from repocodex.schema import envelope
+
+NOT_EVALUATED = "not_evaluated"
+EVALUATED = "evaluated"
+
+
+def _category(status: str, findings: list[dict] | None = None) -> dict[str, Any]:
+    """Build a category payload, attaching findings only when evaluated."""
+    payload: dict[str, Any] = {"status": status}
+    if status == EVALUATED:
+        payload["findings"] = findings or []
+    return payload
+
+
+def advisory(
+    repo: Path,
+    *,
+    base: str | None = None,
+    staged: bool = False,
+    judgments: dict[str, list[dict]] | None = None,
+) -> dict:
+    """Return a non-blocking advisory envelope for the current diff.
+
+    Skips ``.context/`` paths and ``reverse-index.md``. Judgment categories
+    without a key in ``judgments`` stay ``not_evaluated``.
+
+    Returns:
+        Envelope with ``kind`` ``advisory``, ``code_side_impact`` (path/hits
+        rows), ``prose_versus_diff``, ``skipped_recipe_steps``, ``churn_flags``
+        (each ``status`` plus optional ``findings``), ``agent_judgment``, and
+        ``required_verdict_unaffected`` always ``True``.
+
+    """
+    config = load_config(repo)
+    files = changed_files(repo, base=base, staged=staged)
+    code_side: list[dict] = []
+    for path in files:
+        if path.startswith(".context/") or path.endswith("reverse-index.md"):
+            continue
+        symbols = Path(path).stem
+        hits = rank_code_hits(path, symbols, repo, cap=config.impact_read_cap, exclusions=config.all_exclusions)
+        if hits:
+            code_side.append({"path": path, "hits": hits})
+
+    judgments = judgments or {}
+
+    def category_for(name: str) -> dict[str, Any]:
+        if name in judgments:
+            return _category(EVALUATED, judgments[name])
+        return _category(NOT_EVALUATED)
+
+    prose = category_for("prose_versus_diff")
+    skipped = category_for("skipped_recipe_steps")
+    churn = category_for("churn_flags")
+    any_judgment = any(cat["status"] == EVALUATED for cat in (prose, skipped, churn))
+    return envelope(
+        {
+            "kind": "advisory",
+            "code_side_impact": code_side,
+            "prose_versus_diff": prose,
+            "skipped_recipe_steps": skipped,
+            "churn_flags": churn,
+            "agent_judgment": any_judgment,
+            "required_verdict_unaffected": True,
+        }
+    )
+
+
+def scenario_integrity_status(root: Path) -> dict:
+    """Report whether an OKF concept bundle exists for scenario integrity.
+
+    Never falls back to a test table.
+
+    Returns:
+        ``{"status": "unsatisfied", "reason": "no_okf_bundle"}`` when no
+        concepts are loaded, otherwise
+        ``{"status": "available", "reason": "agent_read_okf"}``.
+
+    """
+    from repocodex.store.bundle import load_concepts
+
+    concepts = load_concepts(root)
+    if not concepts:
+        return {"status": "unsatisfied", "reason": "no_okf_bundle"}
+    return {"status": "available", "reason": "agent_read_okf"}