Skip to content

hoatv2211/GameStudio-CodexKIT / skills/studio-project-scaffold

studio-project-scaffold

Verified

Use when running gamestudio init, status, or uninit, or bootstrapping a new or adopted game repository with AGENTS.md, HANDOFF.md, .agents/CONTRACT.md, project governance, a subsystem registry, or a per-project adapter report, plan digest, named reviewer, backup root, generated agent overlay, apply, uninstall, and .codex/config.toml preservation.

FileKindSize
SKILL.mdskill md8.5 KB
agents/openai.yamlconfig259 B
references/code-intelligence-providers.yamlconfig1.8 KB
schemas/studio-evidence-card.schema.jsonconfig3.1 KB
schemas/studio-task-packet.schema.jsonconfig4.8 KB
scripts/agent_overlay.pyscript25.0 KB
scripts/code_intelligence.pyscript62.3 KB
scripts/codegraph_adapter.pyscript18.7 KB
scripts/gamestudio_cli.pyscript8.0 KB
scripts/project_complexity.pyscript13.1 KB
scripts/project_profile.pyscript19.7 KB
scripts/project_scaffold.pyscript26.1 KB
scripts/project_skill_overlay.pyscript10.7 KB
scripts/safe_mutation.pyscript61.6 KB
scripts/studio_experience.pyscript27.3 KB
templates/agents/implementer.tomlconfig1.1 KB
templates/agents/investigator.tomlconfig918 B
templates/agents/verifier.tomlconfig1.4 KB
templates/specialists/asset-pipeline-specialist.tomlconfig1.2 KB
templates/specialists/audio-engineer.tomlconfig1.2 KB
templates/specialists/build-release-engineer.tomlconfig1.8 KB
templates/specialists/cpp-game-server.tomlconfig1.2 KB
templates/specialists/csharp-backend.tomlconfig1.1 KB
templates/specialists/game-data-engineer.tomlconfig1.2 KB
templates/specialists/game-security-engineer.tomlconfig1.2 KB
templates/specialists/game-showcase-capture-producer.tomlconfig1.6 KB
templates/specialists/golang-services.tomlconfig1.2 KB
templates/specialists/level-content-designer.tomlconfig1.2 KB
templates/specialists/liveops-sre.tomlconfig1.3 KB
templates/specialists/lua-gameplay.tomlconfig1.2 KB
templates/specialists/narrative-designer.tomlconfig1.3 KB
templates/specialists/producer.tomlconfig1.2 KB
templates/specialists/product-analyst.tomlconfig1.2 KB
templates/specialists/qa-automation.tomlconfig1.2 KB
templates/specialists/systems-game-designer.tomlconfig1.1 KB
templates/specialists/technical-artist.tomlconfig1.2 KB
templates/specialists/ui-localization-specialist.tomlconfig1.4 KB
templates/specialists/ui-motion-artist.tomlconfig1.8 KB
templates/specialists/unity-csharp-client.tomlconfig1.3 KB

scripts/code_intelligence.py

View on GitHub
# Generated by scripts/sync_skill_resources.py. Do not edit manually.

from __future__ import annotations

import hashlib
import os
import re
import subprocess
from dataclasses import asdict, dataclass
from pathlib import Path, PurePosixPath, PureWindowsPath
from typing import Any, Mapping, Protocol, Sequence

try:
    from scripts.common import load_yaml
except ModuleNotFoundError:
    from common import load_yaml


PROVIDERS = ("graphify", "gitnexus", "understand-anything", "codegraph")

CANONICAL_STATES = frozenset(
    {
        "UNAVAILABLE",
        "NOT_INITIALIZED",
        "FRESH",
        "STALE_HEAD",
        "STALE_WORKTREE",
        "PARTIAL_LANGUAGE",
        "BROKEN",
        "SIDE_EFFECT_VIOLATION",
        "USER_DISABLED",
    }
)
BLOCKED_STATES = CANONICAL_STATES - {"FRESH"}
LEGACY_STATE_MAP = {
    "INITIALIZED_HEALTHY": "FRESH",
    "AVAILABLE_NOT_INITIALIZED": "NOT_INITIALIZED",
    "INITIALIZING": "BROKEN",
    "INITIALIZED_STALE": "STALE_HEAD",
    "INITIALIZED_BROKEN": "BROKEN",
    "PARTIAL": "PARTIAL_LANGUAGE",
    "UNSUPPORTED_LANGUAGE": "PARTIAL_LANGUAGE",
}

# Kept for callers of the provisional helper. New status values are always
# canonical; legacy values are normalized before evidence classification.
FRESH_STATES = frozenset({"FRESH", "INITIALIZED_HEALTHY"})

ALLOWED_ROLES = frozenset(
    {
        "experimental-default",
        "advanced-optional",
        "onboarding-optional",
        "legacy-compatible",
    }
)
ALLOWED_CAPABILITIES = frozenset(
    {
        "status",
        "context",
        "dependency-path",
        "impact",
        "cross-repo",
        "pdg",
        "taint",
        "architecture",
        "domain-flow",
        "onboarding",
    }
)
PROVIDER_KEYS = frozenset(
    {
        "id",
        "display_name",
        "role",
        "maturity",
        "priority",
        "opt_in_required",
        "terms_review_required",
        "capabilities",
        "limitations",
        "upstream_source",
    }
)

SOURCE_EDGE_KINDS = {"EXTRACTED", "AST", "SOURCE"}
INFERRED_EDGE_KINDS = {"INFERRED", "AMBIGUOUS", "SEMANTIC", "LLM"}
CONFIDENCE_TO_PROVENANCE = {
    "EXTRACTED": "SOURCE_EXTRACTED",
    "INFERRED": "INFERRED",
    "AMBIGUOUS": "INFERRED",
    "SEMANTIC": "SEMANTIC",
    "LLM": "LLM",
    "UNKNOWN": "UNKNOWN",
}
ORIGIN_TO_PROVENANCE = {
    "ast": "SOURCE_EXTRACTED",
    "source": "SOURCE_EXTRACTED",
    "inferred": "INFERRED",
    "semantic": "SEMANTIC",
    "llm": "LLM",
}
SOURCE_DERIVED_ORIGINS = frozenset({"ast", "source"})
EDGE_FIELDS = frozenset(
    {"relation", "source", "target", "source_locator", "origin", "confidence"}
)
COMMAND_FIELDS = frozenset({"command", "exit_code"})
NO_GRAPH_RESULT_LIMITATION = (
    "No graph result is not proof that no dependency exists."
)
_KEBAB_RE = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*\Z")
_SHA256_ID_RE = re.compile(r"sha256:[0-9a-f]{64}\Z")


@dataclass(frozen=True)
class ProviderDescriptor:
    id: str
    display_name: str
    role: str
    maturity: str
    priority: int
    opt_in_required: bool
    terms_review_required: bool
    capabilities: tuple[str, ...]
    limitations: tuple[str, ...]
    upstream_source: str | None


@dataclass(frozen=True)
class RepositoryIdentity:
    repository: str
    revision: str | None
    worktree_identity: str | None
    complete: bool
    limitations: tuple[str, ...] = ()


class GitTextRunner(Protocol):
    """Read-only runner for one Git command returning text stdout."""

    def __call__(self, args: list[str], *, cwd: Path) -> str:
        ...


def _default_git_text_runner(args: list[str], *, cwd: Path) -> str:
    """Run a Git text command without invoking a shell or writing state."""

    result = subprocess.run(
        ["git", *args],
        cwd=cwd,
        shell=False,
        check=False,
        text=True,
        capture_output=True,
    )
    if result.returncode != 0:
        detail = result.stderr.strip() if result.stderr else ""
        suffix = f": {detail}" if detail else ""
        command = " ".join(["git", *args])
        raise ValueError(
            f"git command failed ({command!s}, return code {result.returncode}){suffix}"
        )
    return result.stdout or ""


def _normalize_git_repository_path(repository: str) -> str:
    """Preserve Git's absolute path syntax across host operating systems."""

    normalized = repository.replace("\\", "/")
    windows_path = PureWindowsPath(repository)
    posix_path = PurePosixPath(repository)
    foreign_windows = os.name != "nt" and windows_path.is_absolute()
    foreign_posix = (
        os.name == "nt"
        and posix_path.is_absolute()
        and not windows_path.is_absolute()
    )
    if foreign_windows or foreign_posix:
        return normalized
    return Path(repository).resolve().as_posix()


def capture_repository_identity(
    root: Path | str,
    *,
    runner: GitTextRunner | None = None,
    untracked_content_identity: str | None = None,
) -> RepositoryIdentity:
    """Capture a deterministic, read-only identity for a repository snapshot.

    The worktree digest includes Git's status stream and binary staged/unstaged
    diffs, but deliberately never opens files named by the status stream.
    """

    root_path = Path(root)
    command = runner or _default_git_text_runner
    try:
        root_path = root_path.resolve()
        repository = command(["rev-parse", "--show-toplevel"], cwd=root_path).strip()
        revision = command(["rev-parse", "HEAD"], cwd=root_path).strip()
        status = command(
            ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
            cwd=root_path,
        )
        unstaged = command(["diff", "--binary"], cwd=root_path)
        staged = command(["diff", "--binary", "--cached"], cwd=root_path)
        repository_path = (
            _normalize_git_repository_path(repository)
            if repository
            else root_path.as_posix()
        )
    except (OSError, ValueError) as error:
        return RepositoryIdentity(
            repository=root_path.as_posix(),
            revision=None,
            worktree_identity=None,
            complete=False,
            limitations=(f"repository identity unavailable: {error}",),
        )

    has_untracked = any(
        entry.startswith("?? ")
        for entry in status.split("\0")
        if entry
    )
    supplied_untracked_identity = (
        untracked_content_identity.strip().casefold()
        if isinstance(untracked_content_identity, str)
        else None
    )
    if (
        supplied_untracked_identity is not None
        and _SHA256_ID_RE.fullmatch(supplied_untracked_identity) is None
    ):
        supplied_untracked_identity = None

    digest = hashlib.sha256()
    for value in (repository, revision, status, unstaged, staged):
        encoded = value.encode("utf-8", errors="surrogateescape")
        digest.update(len(encoded).to_bytes(8, "big"))
        digest.update(encoded)
    if has_untracked and supplied_untracked_identity is not None:
        encoded = supplied_untracked_identity.encode("ascii")
        digest.update(len(encoded).to_bytes(8, "big"))
        digest.update(encoded)

    limitations: tuple[str, ...] = ()
    if has_untracked and supplied_untracked_identity is None:
        limitations = (
            "untracked worktree content identity is unavailable; path-only metadata cannot prove freshness",
        )

    return RepositoryIdentity(
        repository=repository_path,
        revision=revision or None,
        worktree_identity=f"sha256:{digest.hexdigest()}",
        complete=bool(
            repository
            and revision
            and (not has_untracked or supplied_untracked_identity is not None)
        ),
        limitations=limitations,
    )


@dataclass(frozen=True)
class CodeIntelligenceStatus:
    provider: str
    provider_version: str | None
    repository: str
    revision: str | None
    worktree_identity: str | None
    index_revision: str | None
    index_worktree_identity: str | None
    index_state: str
    capabilities: tuple[str, ...]
    required_languages: tuple[str, ...]
    supported_languages: tuple[str, ...]
    missing_languages: tuple[str, ...]
    artifact_paths: tuple[str, ...]
    side_effects: tuple[str, ...]
    limitations: tuple[str, ...]

    def to_dict(self) -> dict[str, object]:
        return asdict(self)


def default_provider_registry_path(module_path: Path | str = __file__) -> Path:
    """Resolve the canonical or bundled provider registry next to a helper."""

    module = Path(module_path).resolve()
    candidates = (
        module.parent.parent / "registry" / "code-intelligence-providers.yaml",
        module.parent.parent / "references" / "code-intelligence-providers.yaml",
    )
    for candidate in candidates:
        if candidate.is_file():
            return candidate
    raise ValueError("code-intelligence provider registry is unavailable")


def _text_list(value: object, *, allow_empty: bool) -> bool:
    if not isinstance(value, list):
        return False
    if not allow_empty and not value:
        return False
    if any(not isinstance(item, str) or not item.strip() for item in value):
        return False
    return len(value) == len(set(value))


def load_provider_descriptors(
    path: Path | str | None = None,
) -> tuple[ProviderDescriptor, ...]:
    """Load and strictly validate the provider-neutral YAML registry."""

    registry_path = Path(path) if path is not None else default_provider_registry_path()
    document = load_yaml(registry_path)
    if not isinstance(document, dict) or set(document) != {"schema_version", "providers"}:
        raise ValueError("code-intelligence provider registry has an invalid top-level schema")
    schema_version = document["schema_version"]
    if (
        not isinstance(schema_version, int)
        or isinstance(schema_version, bool)
        or schema_version != 1
        or not isinstance(document["providers"], list)
    ):
        raise ValueError("code-intelligence provider registry schema_version must be 1")

    providers: list[ProviderDescriptor] = []
    seen_ids: set[str] = set()
    seen_priorities: set[int] = set()
    for raw in document["providers"]:
        if not isinstance(raw, dict) or set(raw) != PROVIDER_KEYS:
            raise ValueError("code-intelligence provider descriptor has invalid keys")

        provider_id = raw["id"]
        if (
            not isinstance(provider_id, str)
            or _KEBAB_RE.fullmatch(provider_id) is None
            or provider_id in seen_ids
        ):
            raise ValueError(f"invalid or duplicate provider id: {provider_id!r}")

        capabilities = raw["capabilities"]
        if (
            not _text_list(capabilities, allow_empty=False)
            or any(item not in ALLOWED_CAPABILITIES for item in capabilities)
        ):
            raise ValueError(f"invalid capabilities for provider {provider_id}")

        limitations = raw["limitations"]
        upstream_source = raw["upstream_source"]
        priority = raw["priority"]
        if (
            not isinstance(raw["display_name"], str)
            or not raw["display_name"].strip()
            or not isinstance(raw["role"], str)
            or raw["role"] not in ALLOWED_ROLES
            or not isinstance(raw["maturity"], str)
            or not raw["maturity"].strip()
            or not isinstance(priority, int)
            or isinstance(priority, bool)
            or priority in seen_priorities
            or not isinstance(raw["opt_in_required"], bool)
            or not isinstance(raw["terms_review_required"], bool)
            or not _text_list(limitations, allow_empty=True)
            or (
                upstream_source is not None
                and (
                    not isinstance(upstream_source, str)
                    or _KEBAB_RE.fullmatch(upstream_source) is None
                )
            )
        ):
            raise ValueError(f"invalid descriptor for provider {provider_id}")

        seen_ids.add(provider_id)
        seen_priorities.add(priority)
        providers.append(
            ProviderDescriptor(
                id=provider_id,
                display_name=raw["display_name"],
                role=raw["role"],
                maturity=raw["maturity"],
                priority=priority,
                opt_in_required=raw["opt_in_required"],
                terms_review_required=raw["terms_review_required"],
                capabilities=tuple(capabilities),
                limitations=tuple(limitations),
                upstream_source=upstream_source,
            )
        )
    providers.sort(key=lambda item: item.priority)
    return tuple(providers)


def get_provider_descriptor(
    provider: str,
    *,
    registry_path: Path | str | None = None,
) -> ProviderDescriptor:
    provider_id = provider.casefold() if isinstance(provider, str) else ""
    for descriptor in load_provider_descriptors(registry_path):
        if descriptor.id == provider_id:
            return descriptor
    raise ValueError(f"unsupported code-intelligence provider: {provider}")


def provider_descriptors() -> list[dict[str, object]]:
    """Compatibility view retained for the legacy CodeGraph adapter."""

    return [asdict(descriptor) for descriptor in load_provider_descriptors()]


def normalize_index_state(state: str) -> str:
    normalized = state.upper() if isinstance(state, str) else ""
    if normalized in CANONICAL_STATES:
        return normalized
    return LEGACY_STATE_MAP.get(normalized, "BROKEN")


INDEX_MANIFEST_KEYS = frozenset(
    {
        "provider",
        "provider_version",
        "repository",
        "revision",
        "worktree_identity",
        "capabilities",
        "languages",
        "artifact_paths",
        "artifacts_validated",
    }
)


def _validated_index_manifest(
    raw: Mapping[str, object],
    *,
    provider: str,
) -> dict[str, object]:
    if not isinstance(raw, Mapping) or set(raw) != INDEX_MANIFEST_KEYS or raw.get("provider") != provider:
        raise ValueError("provider index manifest has invalid keys or provider")
    for field in ("provider_version", "repository", "revision", "worktree_identity"):
        value = raw.get(field)
        if not isinstance(value, str) or not value.strip():
            raise ValueError(f"provider index manifest {field} is invalid")
    for field in ("capabilities", "languages", "artifact_paths"):
        values = raw.get(field)
        if not _text_list(values, allow_empty=False):
            raise ValueError(f"provider index manifest {field} is invalid")
        if field == "capabilities" and any(
            item not in ALLOWED_CAPABILITIES for item in values
        ):
            raise ValueError(f"provider index manifest {field} is invalid")
        if field == "languages" and len(_normalized_language_tokens(values)) != len(values):
            raise ValueError(f"provider index manifest {field} is invalid")
    if raw.get("artifacts_validated") is not True:
        raise ValueError("provider index artifacts are not validated")
    return dict(raw)


def _normalized_language_tokens(
    values: Sequence[object],
    *,
    field: str = "languages",
) -> tuple[str, ...]:
    """Normalize language names while preserving first-seen deterministic order."""

    if (
        isinstance(values, (str, bytes, Mapping))
        or not isinstance(values, Sequence)
        or any(not isinstance(item, str) or not item.strip() for item in values)
    ):
        raise ValueError(f"{field} must contain nonblank strings")
    return tuple(
        dict.fromkeys(
            item.strip().casefold() for item in values
        )
    )


def _status_for_identity(
    identity: RepositoryIdentity,
    descriptor: ProviderDescriptor,
    *,
    manifest: Mapping[str, object] | None,
    required_capability: str | None,
    required_languages: Sequence[str],
    after_identity: RepositoryIdentity | None,
    observed_side_effects: Sequence[str],
    discovered_artifacts: Sequence[str],
    user_disabled: bool,
) -> CodeIntelligenceStatus:
    required = _normalized_language_tokens(
        required_languages,
        field="required_languages",
    )
    limitations = list(descriptor.limitations)
    side_effects = tuple(dict.fromkeys(str(item) for item in observed_side_effects))
    artifacts = tuple(str(item) for item in discovered_artifacts)

    if side_effects:
        state = "SIDE_EFFECT_VIOLATION"
    elif user_disabled:
        state = "USER_DISABLED"
    elif after_identity is not None and (
        after_identity.repository != identity.repository
        or after_identity.revision != identity.revision
        or after_identity.worktree_identity != identity.worktree_identity
    ):
        state = "STALE_WORKTREE"
        limitations.append("repository identity changed during provider operation")
    elif not identity.complete:
        state = "BROKEN"
        limitations.extend(identity.limitations)
    elif manifest is None:
        state = "STALE_HEAD" if artifacts else "NOT_INITIALIZED"
        limitations.append("provider artifact lacks a repository/index identity manifest")
    else:
        try:
            checked = _validated_index_manifest(manifest, provider=descriptor.id)
        except ValueError as error:
            return CodeIntelligenceStatus(
                provider=descriptor.id,
                provider_version=None,
                repository=identity.repository,
                revision=identity.revision,
                worktree_identity=identity.worktree_identity,
                index_revision=None,
                index_worktree_identity=None,
                index_state="BROKEN",
                capabilities=(),
                required_languages=required,
                supported_languages=(),
                missing_languages=required,
                artifact_paths=artifacts,
                side_effects=side_effects,
                limitations=tuple(dict.fromkeys([*limitations, str(error)])),
            )

        capabilities = tuple(str(item) for item in checked["capabilities"])
        languages = _normalized_language_tokens(checked["languages"])
        missing = tuple(language for language in required if language not in languages)
        unsupported_capabilities = tuple(
            capability
            for capability in capabilities
            if capability not in descriptor.capabilities
        )
        if checked["repository"] != identity.repository:
            state = "BROKEN"
            limitations.append("provider manifest repository mismatch")
        elif checked["revision"] != identity.revision:
            # An index bound to another HEAD cannot be fresh.
            state = "STALE_HEAD"
        elif checked["worktree_identity"] != identity.worktree_identity:
            state = "STALE_WORKTREE"
        elif unsupported_capabilities:
            state = "BROKEN"
            limitations.append(
                "provider manifest capabilities unsupported by "
                f"{descriptor.id}: {', '.join(unsupported_capabilities)}"
            )
        elif (
            required_capability is not None
            and (
                required_capability not in descriptor.capabilities
                or required_capability not in capabilities
            )
        ):
            state = "BROKEN"
            limitations.append(f"capability mismatch: {required_capability}")
        elif missing:
            state = "PARTIAL_LANGUAGE"
        else:
            state = "FRESH"
        return CodeIntelligenceStatus(
            provider=descriptor.id,
            provider_version=str(checked["provider_version"]),
            repository=identity.repository,
            revision=identity.revision,
            worktree_identity=identity.worktree_identity,
            index_revision=str(checked["revision"]),
            index_worktree_identity=str(checked["worktree_identity"]),
            index_state=state,
            capabilities=capabilities,
            required_languages=required,
            supported_languages=languages,
            missing_languages=missing,
            artifact_paths=tuple(str(item) for item in checked["artifact_paths"]),
            side_effects=side_effects,
            limitations=tuple(dict.fromkeys(limitations)),
        )

    return CodeIntelligenceStatus(
        provider=descriptor.id,
        provider_version=None,
        repository=identity.repository,
        revision=identity.revision,
        worktree_identity=identity.worktree_identity,
        index_revision=None,
        index_worktree_identity=None,
        index_state=state,
        capabilities=descriptor.capabilities,
        required_languages=required,
        supported_languages=(),
        missing_languages=required,
        artifact_paths=artifacts,
        side_effects=side_effects,
        limitations=tuple(dict.fromkeys(limitations)),
    )


def inspect_provider(
    root: str | Path | RepositoryIdentity,
    provider: str,
    *,
    manifest: Mapping[str, object] | None = None,
    required_capability: str | None = None,
    required_languages: Sequence[str] = (),
    registry_path: Path | str | None = None,
    after_identity: RepositoryIdentity | None = None,
    observed_side_effects: Sequence[str] = (),
    discovered_artifacts: Sequence[str] = (),
    user_disabled: bool = False,
) -> CodeIntelligenceStatus:
    """Inspect a provider without executing provider commands.

    The path-based form preserves the provisional artifact-only compatibility
    helper. The identity/manifest form validates semantic freshness: required
    language coverage and index identity must match before ``FRESH`` is emitted.
    """

    descriptor = get_provider_descriptor(provider, registry_path=registry_path)
    if isinstance(root, RepositoryIdentity):
        return _status_for_identity(
            root,
            descriptor,
            manifest=manifest,
            required_capability=required_capability,
            required_languages=required_languages,
            after_identity=after_identity,
            observed_side_effects=observed_side_effects,
            discovered_artifacts=discovered_artifacts,
            user_disabled=user_disabled,
        )

    root_path = Path(root).resolve()
    artifact_map = {
        "graphify": ("graphify-out/GRAPH_REPORT.md", "graphify-out/graph.json"),
        "gitnexus": (".gitnexus/",),
        "understand-anything": (
            ".ua/knowledge-graph.json",
            ".understand-anything/knowledge-graph.json",
        ),
        "codegraph": (".codegraph/",),
    }
    artifacts = tuple(path for path in artifact_map[descriptor.id] if (root_path / path).exists())
    identity = RepositoryIdentity(str(root_path), None, None, False)
    # Artifact-only probing cannot establish a complete identity, so it is
    # intentionally reported as stale/not initialized rather than fresh.
    state = "STALE_HEAD" if artifacts else "NOT_INITIALIZED"
    return CodeIntelligenceStatus(
        provider=descriptor.id,
        provider_version=None,
        repository=str(root_path),
        revision=identity.revision,
        worktree_identity=identity.worktree_identity,
        index_revision=None,
        index_worktree_identity=None,
        index_state=state,
        capabilities=descriptor.capabilities,
        required_languages=(),
        supported_languages=(),
        missing_languages=(),
        artifact_paths=artifacts,
        side_effects=(),
        limitations=descriptor.limitations,
    )


LEGACY_STRING_COLLECTION_FIELDS = (
    "resolved_subjects",
    "affected_paths",
    "dependencies",
    "dependency_paths",
    "paths",
    "nodes",
    "symbols",
)


def _legacy_string_collection(value: object) -> bool:
    return (
        not isinstance(value, (str, bytes))
        and isinstance(value, Sequence)
        and bool(value)
        and all(isinstance(item, str) and bool(item.strip()) for item in value)
    )


def _legacy_edge_item(value: object) -> bool:
    if not isinstance(value, Mapping):
        return False
    for source_field, target_field in (
        ("source", "target"),
        ("from", "to"),
        ("caller", "callee"),
    ):
        source = value.get(source_field)
        target = value.get(target_field)
        if (
            isinstance(source, str)
            and source.strip()
            and isinstance(target, str)
            and target.strip()
        ):
            return True
    return False


def _legacy_edge_collection(value: object) -> bool:
    return (
        not isinstance(value, (str, bytes))
        and isinstance(value, Sequence)
        and bool(value)
        and all(_legacy_edge_item(item) for item in value)
    )


def _legacy_has_direct_dependency_evidence(result: Mapping[str, object]) -> bool:
    if any(
        _legacy_string_collection(result.get(field))
        for field in LEGACY_STRING_COLLECTION_FIELDS
        if field in result
    ):
        return True
    return "edges" in result and _legacy_edge_collection(result["edges"])


def _legacy_has_dependency_evidence(result: object) -> bool:
    if not isinstance(result, Mapping):
        return False
    if _legacy_has_direct_dependency_evidence(result):
        return True
    nested_results = result.get("results")
    if (
        isinstance(nested_results, Sequence)
        and not isinstance(nested_results, (str, bytes))
        and bool(nested_results)
        and all(isinstance(item, Mapping) for item in nested_results)
    ):
        return any(
            _legacy_has_direct_dependency_evidence(item)
            for item in nested_results
        )
    return False


def _legacy_result_texts(
    result: object,
    *,
    fields: Sequence[str],
) -> tuple[str, ...]:
    if not isinstance(result, Mapping):
        return ()
    for field in fields:
        values = result.get(field)
        if _legacy_string_collection(values):
            return tuple(dict.fromkeys(item.strip() for item in values))
    return ()


def _normalize_legacy_evidence(
    *,
    provider: str,
    provider_version: str | None,
    repository: str,
    revision: str | None,
    index_state: str,
    edge_kind: str,
    result: object,
    limitations: list[str] | tuple[str, ...] = (),
) -> dict[str, object]:
    """Route the legacy call shape through the canonical fail-closed contract."""

    provider_id = provider.casefold()
    if provider_id not in PROVIDERS:
        raise ValueError(f"unsupported code-intelligence provider: {provider}")
    state = normalize_index_state(index_state)
    notes = list(limitations)
    notes.append(
        "Legacy input lacks complete canonical repository/worktree/index identity; "
        "caller-declared freshness or edge provenance cannot establish PASS."
    )
    status = CodeIntelligenceStatus(
        provider=provider_id,
        provider_version=provider_version,
        repository=repository,
        revision=revision,
        worktree_identity=None,
        index_revision=revision,
        index_worktree_identity=None,
        index_state=state,
        capabilities=("dependency-path",),
        required_languages=(),
        supported_languages=(),
        missing_languages=(),
        artifact_paths=(),
        side_effects=(),
        limitations=tuple(notes),
    )
    return normalize_evidence(
        status=status,
        capability="dependency-path",
        query={
            "query_id": f"legacy:{provider_id}:dependency-path",
            "subjects": ["legacy provider query"],
        },
        resolved_subjects=_legacy_result_texts(
            result,
            fields=("resolved_subjects",),
        ),
        affected_paths=_legacy_result_texts(
            result,
            fields=("affected_paths", "dependency_paths", "paths"),
        ),
        next_action=(
            "Capture complete canonical repository/worktree/index identity before "
            "using legacy graph evidence."
        ),
    )


def _required_text(value: object, *, field: str) -> str:
    if not isinstance(value, str) or not value.strip():
        raise ValueError(f"code-intelligence {field} must be a nonblank string")
    return value


def _optional_text(value: object, *, field: str) -> str | None:
    if value is None:
        return None
    return _required_text(value, field=field)


def _normalized_texts(values: Sequence[object], *, field: str) -> list[str]:
    if isinstance(values, (str, bytes)) or not isinstance(values, Sequence):
        raise ValueError(f"code-intelligence {field} must be a sequence")
    normalized: list[str] = []
    seen: set[str] = set()
    for value in values:
        text = _required_text(value, field=field)
        if text not in seen:
            seen.add(text)
            normalized.append(text)
    return normalized


def _normalized_kebab_texts(values: Sequence[object], *, field: str) -> list[str]:
    normalized = _normalized_texts(values, field=field)
    result: list[str] = []
    seen: set[str] = set()
    for value in normalized:
        normalized_value = value.strip().casefold()
        if _KEBAB_RE.fullmatch(normalized_value) is None:
            raise ValueError(f"code-intelligence {field} contains an invalid token")
        if normalized_value not in seen:
            seen.add(normalized_value)
            result.append(normalized_value)
    return result


def _normalize_query(raw: Mapping[str, object]) -> dict[str, object]:
    if not isinstance(raw, Mapping) or set(raw) != {"query_id", "subjects"}:
        raise ValueError("code-intelligence query has invalid fields")
    query_id = _required_text(raw["query_id"], field="query query_id")
    raw_subjects = raw["subjects"]
    if isinstance(raw_subjects, (str, bytes)) or not isinstance(raw_subjects, Sequence):
        raise ValueError("code-intelligence query subjects must be a sequence")
    subjects = _normalized_texts(raw_subjects, field="query subject")
    if len(subjects) != 1 or len(raw_subjects) != 1:
        raise ValueError("code-intelligence query must contain exactly one subject")
    return {"query_id": query_id, "subjects": subjects}


def _normalize_edge(raw: Mapping[str, object]) -> dict[str, str]:
    if not isinstance(raw, Mapping) or set(raw) != EDGE_FIELDS:
        raise ValueError("code-intelligence edge has invalid fields")
    normalized = {
        field: _required_text(raw[field], field=f"edge {field}")
        for field in ("relation", "source", "target", "source_locator")
    }
    origin = _required_text(raw["origin"], field="edge origin").strip().casefold()
    raw_confidence = _required_text(raw["confidence"], field="edge confidence")
    confidence = raw_confidence.strip().upper()
    if confidence not in CONFIDENCE_TO_PROVENANCE:
        confidence = "UNKNOWN"
    if origin in SOURCE_DERIVED_ORIGINS:
        provenance = CONFIDENCE_TO_PROVENANCE[confidence]
    else:
        provenance = ORIGIN_TO_PROVENANCE.get(origin, "UNKNOWN")
    return {
        **normalized,
        "origin": origin,
        "confidence": confidence,
        "provenance": provenance,
    }


def _normalize_edges(
    edges: Sequence[Mapping[str, object]],
) -> list[dict[str, str]]:
    if isinstance(edges, (str, bytes)) or not isinstance(edges, Sequence):
        raise ValueError("code-intelligence edges must be a sequence")
    normalized: list[dict[str, str]] = []
    seen: set[tuple[str, ...]] = set()
    for raw in edges:
        edge = _normalize_edge(raw)
        marker = tuple(edge[field] for field in (*EDGE_FIELDS, "provenance"))
        if marker not in seen:
            seen.add(marker)
            normalized.append(edge)
    return normalized


def _normalize_commands(
    commands: Sequence[Mapping[str, object]],
) -> list[dict[str, object]]:
    if isinstance(commands, (str, bytes)) or not isinstance(commands, Sequence):
        raise ValueError("code-intelligence commands must be a sequence")
    normalized: list[dict[str, object]] = []
    seen: set[tuple[str, int | None]] = set()
    for raw in commands:
        if not isinstance(raw, Mapping) or set(raw) != COMMAND_FIELDS:
            raise ValueError("code-intelligence command has invalid fields")
        command = _required_text(raw["command"], field="command")
        exit_code = raw["exit_code"]
        if exit_code is not None and (
            not isinstance(exit_code, int) or isinstance(exit_code, bool)
        ):
            raise ValueError("code-intelligence command exit_code must be an integer or null")
        marker = (command, exit_code)
        if marker not in seen:
            seen.add(marker)
            normalized.append({"command": command, "exit_code": exit_code})
    return normalized


def normalize_evidence(
    *,
    status: CodeIntelligenceStatus | None = None,
    capability: str | None = None,
    query: Mapping[str, object] | None = None,
    resolved_subjects: Sequence[str] = (),
    edges: Sequence[Mapping[str, object]] = (),
    affected_paths: Sequence[str] = (),
    generated_boundaries: Sequence[str] = (),
    source_confirmations: Sequence[str] = (),
    test_confirmations: Sequence[str] = (),
    disagreements: Sequence[str] = (),
    commands: Sequence[Mapping[str, object]] = (),
    artifacts: Sequence[str] = (),
    next_action: str = (
        "Confirm important graph findings against authoritative source and tests."
    ),
    **legacy: Any,
) -> dict[str, object]:
    """Normalize provider-neutral evidence without upgrading inference into proof.

    The provisional provider-specific call form remains accepted until legacy
    CodeGraph callers migrate to this normalized artifact contract.
    """

    if status is None:
        if capability is not None or query is not None:
            raise ValueError("code-intelligence status is required")
        return _normalize_legacy_evidence(**legacy)
    if not isinstance(status, CodeIntelligenceStatus):
        raise ValueError("code-intelligence status is invalid")
    if legacy:
        raise ValueError("legacy evidence fields cannot be mixed with normalized fields")

    provider = _required_text(status.provider, field="provider").strip().casefold()
    if _KEBAB_RE.fullmatch(provider) is None:
        raise ValueError("code-intelligence provider is invalid")
    repository = _required_text(status.repository, field="repository")
    provider_version = _optional_text(status.provider_version, field="provider_version")
    revision = _optional_text(status.revision, field="revision")
    worktree_identity = _optional_text(
        status.worktree_identity, field="worktree_identity"
    )
    index_revision = _optional_text(status.index_revision, field="index_revision")
    index_worktree_identity = _optional_text(
        status.index_worktree_identity, field="index_worktree_identity"
    )
    capabilities = _normalized_kebab_texts(
        status.capabilities, field="capabilities"
    )
    required_languages = _normalized_kebab_texts(
        status.required_languages, field="required_languages"
    )
    supported_languages = _normalized_kebab_texts(
        status.supported_languages, field="supported_languages"
    )
    declared_missing_languages = _normalized_kebab_texts(
        status.missing_languages, field="missing_languages"
    )
    actual_missing_languages = [
        language
        for language in required_languages
        if language not in supported_languages
    ]
    side_effects = _normalized_texts(status.side_effects, field="side_effects")
    limitations = _normalized_texts(status.limitations, field="limitations")
    status_artifacts = _normalized_texts(
        status.artifact_paths,
        field="artifact_paths",
    )

    normalized_capability = _required_text(capability, field="capability").strip().casefold()
    if _KEBAB_RE.fullmatch(normalized_capability) is None:
        raise ValueError("code-intelligence capability is invalid")
    if query is None:
        raise ValueError("code-intelligence query is required")
    normalized_query = _normalize_query(query)
    subjects = _normalized_texts(resolved_subjects, field="resolved_subjects")
    normalized_edges = _normalize_edges(edges)
    paths = _normalized_texts(affected_paths, field="affected_paths")
    boundaries = _normalized_texts(
        generated_boundaries, field="generated_boundaries"
    )
    source_checks = _normalized_texts(
        source_confirmations, field="source_confirmations"
    )
    test_checks = _normalized_texts(test_confirmations, field="test_confirmations")
    normalized_disagreements = _normalized_texts(
        disagreements, field="disagreements"
    )
    normalized_commands = _normalize_commands(commands)
    supplied_artifacts = _normalized_texts(artifacts, field="artifacts")
    normalized_artifacts = list(
        dict.fromkeys([*status_artifacts, *supplied_artifacts])
    )
    normalized_next_action = _required_text(next_action, field="next_action")

    state = normalize_index_state(status.index_state)
    if declared_missing_languages != actual_missing_languages:
        limitations.append(
            "Declared missing-language coverage disagreed with required and supported languages."
        )
    missing_languages = actual_missing_languages
    if side_effects:
        state = "SIDE_EFFECT_VIOLATION"
        limitations.append("Observed provider side effects forced a blocked state.")
    elif missing_languages:
        if state != "PARTIAL_LANGUAGE":
            limitations.append(
                "Missing required language coverage forced a blocked partial-language state."
            )
        state = "PARTIAL_LANGUAGE"
    elif declared_missing_languages != actual_missing_languages:
        state = "BROKEN"
    elif state == "FRESH":
        identity_limitations: list[str] = []
        if provider_version is None:
            identity_limitations.append("Fresh provider version is unavailable.")
        if not status_artifacts:
            identity_limitations.append("Fresh index artifact binding is unavailable.")
        if any(
            value is None
            for value in (
                revision,
                worktree_identity,
                index_revision,
                index_worktree_identity,
            )
        ):
            identity_limitations.append("Fresh index identity is incomplete.")
        else:
            if revision != index_revision:
                identity_limitations.append("Fresh index revision identity mismatch.")
            if worktree_identity != index_worktree_identity:
                identity_limitations.append("Fresh index worktree identity mismatch.")
        if identity_limitations:
            state = "BROKEN"
            limitations.extend(identity_limitations)

    limitations.append(NO_GRAPH_RESULT_LIMITATION)
    if state in BLOCKED_STATES:
        query_state, evidence_label, graph_verdict = (
            "STATUS_BLOCKED",
            "BLOCKED",
            "BLOCKED",
        )
        limitations.append(
            "Graph evidence is unavailable until index status is fresh and supported."
        )
    elif normalized_capability not in capabilities:
        query_state, evidence_label, graph_verdict = (
            "CAPABILITY_MISMATCH",
            "BLOCKED",
            "BLOCKED",
        )
        limitations.append(f"capability mismatch: {normalized_capability}")
    elif len(subjects) != 1 and (subjects or normalized_edges or paths):
        query_state, evidence_label, graph_verdict = (
            "AMBIGUOUS",
            "BLOCKED",
            "BLOCKED",
        )
        if subjects:
            limitations.append("Multiple resolved candidates require explicit disambiguation.")
        else:
            limitations.append(
                "Dependency evidence without one resolved subject cannot support a graph conclusion."
            )
    elif not subjects and not normalized_edges and not paths:
        query_state, evidence_label, graph_verdict = (
            "EMPTY_UNCERTAIN",
            "Unverified",
            "UNVERIFIED",
        )
    elif normalized_edges and all(
        edge["provenance"] == "SOURCE_EXTRACTED" for edge in normalized_edges
    ) and not normalized_disagreements:
        query_state, evidence_label, graph_verdict = (
            "COMPLETE",
            "Verified",
            "PASS",
        )
        limitations.append(
            "Verified applies to source extraction at this snapshot, not runtime behavior or complete recall."
        )
    else:
        query_state, evidence_label, graph_verdict = (
            "COMPLETE",
            "Snapshot",
            "UNVERIFIED",
        )
        if normalized_disagreements:
            limitations.append(
                "Disagreements require authoritative source or runtime confirmation."
            )
        else:
            limitations.append(
                "Inferred, semantic, LLM, or unknown edges require source or runtime confirmation."
            )

    evidence = {
        "schema_version": 1,
        "provider": provider,
        "provider_version": provider_version,
        "repository": repository,
        "revision": revision,
        "worktree_identity": worktree_identity,
        "index_revision": index_revision,
        "index_worktree_identity": index_worktree_identity,
        "index_state": state,
        "capability": normalized_capability,
        "query": normalized_query,
        "resolved_subjects": subjects,
        "required_languages": required_languages,
        "supported_languages": supported_languages,
        "missing_languages": missing_languages,
        "affected_paths": paths,
        "generated_boundaries": boundaries,
        "edges": normalized_edges,
        "query_state": query_state,
        "evidence_label": evidence_label,
        "graph_verdict": graph_verdict,
        "source_confirmations": source_checks,
        "test_confirmations": test_checks,
        "side_effects": side_effects,
        "limitations": list(dict.fromkeys(limitations)),
        "disagreements": normalized_disagreements,
        "commands": normalized_commands,
        "artifacts": normalized_artifacts,
        "next_action": normalized_next_action,
    }
    validate_evidence_semantics(evidence)
    return evidence


CANONICAL_EVIDENCE_FIELDS = frozenset(
    {
        "schema_version",
        "provider",
        "provider_version",
        "repository",
        "revision",
        "worktree_identity",
        "index_revision",
        "index_worktree_identity",
        "index_state",
        "capability",
        "query",
        "resolved_subjects",
        "required_languages",
        "supported_languages",
        "missing_languages",
        "affected_paths",
        "generated_boundaries",
        "edges",
        "query_state",
        "evidence_label",
        "graph_verdict",
        "source_confirmations",
        "test_confirmations",
        "side_effects",
        "limitations",
        "disagreements",
        "commands",
        "artifacts",
        "next_action",
    }
)
SOURCE_TEST_FALLBACK_FIELDS = frozenset(
    {
        "decision",
        "graph_verdict",
        "graph_blocker",
        "source_owners",
        "known_callers",
        "known_consumers",
        "generated_authorities",
        "test_commands",
        "reviewer",
        "residual_risk",
        "missing_requirements",
    }
)


def _validate_source_test_fallback(raw: object) -> None:
    if not isinstance(raw, Mapping) or set(raw) != SOURCE_TEST_FALLBACK_FIELDS:
        raise ValueError("canonical source_test_fallback has invalid fields")
    decision = raw["decision"]
    if decision not in {"BLOCKED", "REVIEWER_ACKNOWLEDGED_FALLBACK"}:
        raise ValueError("canonical source_test_fallback decision is invalid")
    if raw["graph_verdict"] != "BLOCKED":
        raise ValueError("canonical source_test_fallback graph verdict must be BLOCKED")

    graph_blocker = _fallback_text(raw["graph_blocker"], field="graph blocker")
    residual_risk = _fallback_text(raw["residual_risk"], field="residual risk")
    if graph_blocker != raw["graph_blocker"] or residual_risk != raw["residual_risk"]:
        raise ValueError("canonical source_test_fallback text is not normalized")
    reviewer = raw["reviewer"]
    if reviewer is not None:
        normalized_reviewer = _required_text(reviewer, field="reviewer").strip()
        if reviewer != normalized_reviewer:
            raise ValueError("canonical source_test_fallback reviewer is not normalized")

    normalized_lists: dict[str, list[str]] = {}
    for field in (
        "source_owners",
        "known_callers",
        "known_consumers",
        "generated_authorities",
        "test_commands",
        "missing_requirements",
    ):
        values = raw[field]
        if not isinstance(values, list):
            raise ValueError(f"canonical source_test_fallback {field} must be an array")
        normalized = _normalized_handoff_texts(values, field=field)
        if normalized != values:
            raise ValueError(f"canonical source_test_fallback {field} is not normalized")
        normalized_lists[field] = normalized

    if decision == "REVIEWER_ACKNOWLEDGED_FALLBACK":
        authorities, authorities_valid = _generated_authority_status(
            normalized_lists["generated_authorities"]
        )
        if (
            not graph_blocker
            or not normalized_lists["source_owners"]
            or not normalized_lists["known_callers"]
            or not normalized_lists["known_consumers"]
            or not authorities_valid
            or authorities != normalized_lists["generated_authorities"]
            or not normalized_lists["test_commands"]
            or reviewer is None
            or not residual_risk
            or normalized_lists["missing_requirements"]
        ):
            raise ValueError(
                "acknowledged source_test_fallback is missing required evidence"
            )
    elif not normalized_lists["missing_requirements"]:
        raise ValueError("blocked source_test_fallback requires missing requirements")


def validate_evidence_semantics(evidence: Mapping[str, object]) -> None:
    """Fail closed on cross-field evidence rules JSON Schema cannot express."""

    if not isinstance(evidence, Mapping):
        raise ValueError("canonical code-intelligence evidence must be a mapping")
    missing_fields = sorted(CANONICAL_EVIDENCE_FIELDS - set(evidence))
    if missing_fields:
        raise ValueError(
            "canonical code-intelligence evidence is missing fields: "
            + ", ".join(missing_fields)
        )
    unexpected_fields = sorted(
        set(evidence) - CANONICAL_EVIDENCE_FIELDS - {"source_test_fallback"}
    )
    if unexpected_fields:
        raise ValueError(
            "canonical code-intelligence evidence has unexpected fields: "
            + ", ".join(unexpected_fields)
        )
    if "source_test_fallback" in evidence:
        _validate_source_test_fallback(evidence["source_test_fallback"])
        if (
            evidence["evidence_label"] != "BLOCKED"
            or evidence["graph_verdict"] != "BLOCKED"
        ):
            raise ValueError(
                "source_test_fallback requires top-level BLOCKED graph evidence"
            )
    if type(evidence["schema_version"]) is not int or evidence["schema_version"] != 1:
        raise ValueError("canonical code-intelligence schema_version must be 1")

    provider = _required_text(evidence["provider"], field="provider").strip().casefold()
    capability = _required_text(
        evidence["capability"],
        field="capability",
    ).strip().casefold()
    if _KEBAB_RE.fullmatch(provider) is None or _KEBAB_RE.fullmatch(capability) is None:
        raise ValueError("canonical code-intelligence provider or capability is invalid")
    if evidence["provider"] != provider or evidence["capability"] != capability:
        raise ValueError("canonical code-intelligence provider or capability is not normalized")
    if _normalize_query(evidence["query"]) != evidence["query"]:
        raise ValueError("canonical code-intelligence query is not normalized")
    for field in (
        "resolved_subjects",
        "affected_paths",
        "generated_boundaries",
        "source_confirmations",
        "test_confirmations",
        "limitations",
        "disagreements",
        "artifacts",
        "side_effects",
    ):
        if not isinstance(evidence[field], list):
            raise ValueError(f"canonical code-intelligence {field} must be an array")
        if _normalized_texts(evidence[field], field=field) != evidence[field]:
            raise ValueError(f"canonical code-intelligence {field} is not normalized")
    for field in (
        "required_languages",
        "supported_languages",
        "missing_languages",
    ):
        if not isinstance(evidence[field], list):
            raise ValueError(f"canonical code-intelligence {field} must be an array")
        if _normalized_kebab_texts(evidence[field], field=field) != evidence[field]:
            raise ValueError(f"canonical code-intelligence {field} is not normalized")
    normalized_edges = evidence["edges"]
    if not isinstance(normalized_edges, list):
        raise ValueError("canonical code-intelligence edges must be an array")
    seen_edges: set[tuple[str, ...]] = set()
    normalized_edge_fields = EDGE_FIELDS | {"provenance"}
    for raw_edge in normalized_edges:
        if not isinstance(raw_edge, Mapping) or set(raw_edge) != normalized_edge_fields:
            raise ValueError("canonical code-intelligence edge has invalid fields")
        edge_values = {
            field: _required_text(raw_edge[field], field=f"edge {field}")
            for field in normalized_edge_fields
        }
        if edge_values["origin"] != edge_values["origin"].strip().casefold():
            raise ValueError("canonical code-intelligence edge origin is not normalized")
        if edge_values["confidence"] not in CONFIDENCE_TO_PROVENANCE:
            raise ValueError("canonical code-intelligence edge confidence is invalid")
        if edge_values["provenance"] not in set(CONFIDENCE_TO_PROVENANCE.values()) | {
            "UNKNOWN"
        }:
            raise ValueError("canonical code-intelligence edge provenance is invalid")
        reconstructed_edge = _normalize_edge(
            {
                field: raw_edge[field]
                for field in EDGE_FIELDS
            }
        )
        if reconstructed_edge != dict(raw_edge):
            raise ValueError(
                "canonical code-intelligence edge provenance is inconsistent"
            )
        edge_marker = tuple(edge_values[field] for field in sorted(normalized_edge_fields))
        if edge_marker in seen_edges:
            raise ValueError("canonical code-intelligence edges must be unique")
        seen_edges.add(edge_marker)
    if not isinstance(evidence["commands"], list):
        raise ValueError("canonical code-intelligence commands must be an array")
    if _normalize_commands(evidence["commands"]) != evidence["commands"]:
        raise ValueError("canonical code-intelligence commands are not normalized")
    _required_text(evidence["next_action"], field="next_action")
    if evidence["query_state"] not in {
        "COMPLETE",
        "STATUS_BLOCKED",
        "EMPTY_UNCERTAIN",
        "AMBIGUOUS",
        "CAPABILITY_MISMATCH",
    }:
        raise ValueError("canonical code-intelligence query_state is invalid")
    if evidence["evidence_label"] not in {
        "Verified",
        "Snapshot",
        "Unverified",
        "BLOCKED",
    }:
        raise ValueError("canonical code-intelligence evidence_label is invalid")
    if evidence["graph_verdict"] not in {"PASS", "UNVERIFIED", "BLOCKED"}:
        raise ValueError("canonical code-intelligence graph_verdict is invalid")

    state = evidence["index_state"]
    if not isinstance(state, str) or state not in CANONICAL_STATES:
        raise ValueError("canonical code-intelligence index state is invalid")
    provider_version = _optional_text(
        evidence["provider_version"],
        field="provider_version",
    )
    repository = _required_text(evidence["repository"], field="repository")
    revision = _optional_text(evidence["revision"], field="revision")
    worktree_identity = _optional_text(
        evidence["worktree_identity"],
        field="worktree_identity",
    )
    index_revision = _optional_text(
        evidence["index_revision"],
        field="index_revision",
    )
    index_worktree_identity = _optional_text(
        evidence["index_worktree_identity"],
        field="index_worktree_identity",
    )
    required = _normalized_kebab_texts(
        evidence["required_languages"],
        field="required_languages",
    )
    supported = _normalized_kebab_texts(
        evidence["supported_languages"],
        field="supported_languages",
    )
    declared_missing = _normalized_kebab_texts(
        evidence["missing_languages"],
        field="missing_languages",
    )
    actual_missing = [language for language in required if language not in supported]
    if declared_missing != actual_missing:
        raise ValueError(
            "canonical code-intelligence missing_languages do not match coverage"
        )
    artifacts = _normalized_texts(evidence["artifacts"], field="artifacts")
    side_effects = _normalized_texts(evidence["side_effects"], field="side_effects")

    if side_effects and state != "SIDE_EFFECT_VIOLATION":
        raise ValueError(
            "canonical code-intelligence side effects require SIDE_EFFECT_VIOLATION"
        )
    if state == "FRESH":
        if provider_version is None:
            raise ValueError("fresh code-intelligence evidence requires provider version")
        if not artifacts:
            raise ValueError("fresh code-intelligence evidence requires artifacts")
        if not repository:
            raise ValueError("fresh code-intelligence evidence requires repository")
        if any(
            value is None
            for value in (
                revision,
                worktree_identity,
                index_revision,
                index_worktree_identity,
            )
        ):
            raise ValueError("fresh code-intelligence evidence requires complete identity")
        if revision != index_revision:
            raise ValueError("fresh code-intelligence revision binding does not match")
        if worktree_identity != index_worktree_identity:
            raise ValueError("fresh code-intelligence worktree binding does not match")
        if actual_missing:
            raise ValueError("fresh code-intelligence evidence lacks language coverage")
        if side_effects:
            raise ValueError("fresh code-intelligence evidence contains side effects")

    graph_verdict = evidence["graph_verdict"]
    query_state = evidence["query_state"]
    evidence_label = evidence["evidence_label"]
    resolved_subjects = evidence["resolved_subjects"]
    disagreements = evidence["disagreements"]

    if state in BLOCKED_STATES and (
        query_state != "STATUS_BLOCKED"
        or evidence_label != "BLOCKED"
        or graph_verdict != "BLOCKED"
    ):
        raise ValueError("blocked index state requires blocked graph evidence")
    if query_state in {"AMBIGUOUS", "CAPABILITY_MISMATCH"} and (
        evidence_label != "BLOCKED" or graph_verdict != "BLOCKED"
    ):
        raise ValueError("blocked query state requires blocked graph evidence")
    if query_state == "EMPTY_UNCERTAIN" and (
        resolved_subjects
        or evidence["affected_paths"]
        or normalized_edges
        or evidence_label != "Unverified"
        or graph_verdict != "UNVERIFIED"
        or NO_GRAPH_RESULT_LIMITATION not in evidence["limitations"]
    ):
        raise ValueError("empty graph result requires explicit unverified evidence")
    if evidence_label == "BLOCKED" and graph_verdict != "BLOCKED":
        raise ValueError("BLOCKED evidence label requires BLOCKED graph verdict")
    if graph_verdict == "BLOCKED" and evidence_label != "BLOCKED":
        raise ValueError("BLOCKED graph verdict requires BLOCKED evidence label")
    if graph_verdict == "UNVERIFIED" and evidence_label not in {
        "Snapshot",
        "Unverified",
    }:
        raise ValueError("UNVERIFIED graph verdict requires non-verified evidence")
    if graph_verdict == "PASS":
        if (
            state != "FRESH"
            or query_state != "COMPLETE"
            or evidence_label != "Verified"
            or len(resolved_subjects) != 1
            or not normalized_edges
            or disagreements
            or any(
                edge["confidence"] != "EXTRACTED"
                or edge["provenance"] != "SOURCE_EXTRACTED"
                for edge in normalized_edges
            )
        ):
            raise ValueError(
                "graph PASS requires fresh, complete, unambiguous source-extracted evidence"
            )


def _normalized_handoff_texts(
    values: Sequence[object],
    *,
    field: str,
) -> list[str]:
    if (
        isinstance(values, (str, bytes, Mapping))
        or not isinstance(values, Sequence)
    ):
        raise ValueError(f"code-intelligence {field} must be a sequence")
    normalized: list[str] = []
    seen: set[str] = set()
    for value in values:
        text = _required_text(value, field=field).strip()
        if text not in seen:
            seen.add(text)
            normalized.append(text)
    return normalized


def compare_impact(
    *,
    pre: Mapping[str, object],
    post: Mapping[str, object],
    changed_paths: Sequence[str],
) -> dict[str, object]:
    """Compare identity-bound impact artifacts deterministically."""

    if not isinstance(pre, Mapping) or not isinstance(post, Mapping):
        raise ValueError("pre/post impact artifacts must be mappings")
    validate_evidence_semantics(pre)
    validate_evidence_semantics(post)
    for name, artifact in (("pre", pre), ("post", post)):
        if artifact["index_state"] != "FRESH":
            raise ValueError(f"{name} impact artifact must have a fresh index")
        if artifact["capability"] != "impact":
            raise ValueError(f"{name} impact artifact must use the impact capability")
        if artifact["query_state"] != "COMPLETE":
            raise ValueError(f"{name} impact artifact must have a complete query")
        if len(artifact["resolved_subjects"]) != 1:
            raise ValueError(
                f"{name} impact artifact must resolve exactly one subject"
            )
        if artifact["graph_verdict"] == "BLOCKED":
            raise ValueError(f"{name} impact artifact cannot be graph-blocked")

    for field in ("provider", "provider_version", "repository"):
        if pre[field] != post[field]:
            raise ValueError(f"pre/post impact {field} identities do not match")
    pre_query = pre.get("query")
    post_query = post.get("query")
    if not isinstance(pre_query, Mapping) or not isinstance(post_query, Mapping):
        raise ValueError("pre/post impact artifacts require query objects")
    normalized_pre_query = _normalize_query(pre_query)
    normalized_post_query = _normalize_query(post_query)
    pre_query_id = str(normalized_pre_query["query_id"]).strip()
    post_query_id = str(normalized_post_query["query_id"]).strip()
    if pre_query_id != post_query_id:
        raise ValueError("pre/post impact query identities do not match")
    if normalized_pre_query != normalized_post_query:
        raise ValueError("pre/post impact query subjects do not match")
    if "affected_paths" not in pre or "affected_paths" not in post:
        raise ValueError("pre/post impact artifacts require affected_paths")

    pre_paths = set(
        _normalized_handoff_texts(
            pre["affected_paths"],
            field="pre affected_paths",
        )
    )
    post_paths = set(
        _normalized_handoff_texts(
            post["affected_paths"],
            field="post affected_paths",
        )
    )
    changed = set(
        _normalized_handoff_texts(changed_paths, field="changed_paths")
    )
    if changed and (
        pre["revision"] == post["revision"]
        and pre["worktree_identity"] == post["worktree_identity"]
    ):
        raise ValueError(
            "pre/post impact transition must bind distinct repository snapshots"
        )
    removed = pre_paths - post_paths
    return {
        "query_id": pre_query_id,
        "added_affected_paths": sorted(post_paths - pre_paths),
        "removed_affected_paths": sorted(removed),
        "unchanged_affected_paths": sorted(pre_paths & post_paths),
        "changed_not_predicted": sorted(changed - pre_paths),
        "changed_no_longer_affected": sorted(changed & removed),
    }


def _fallback_text(value: object, *, field: str) -> str:
    if not isinstance(value, str):
        raise ValueError(f"code-intelligence {field} must be a string")
    return value.strip()


def _generated_authority_status(
    values: Sequence[str],
) -> tuple[list[str], bool]:
    normalized = _normalized_handoff_texts(
        values,
        field="generated authorities",
    )
    raw = [value.strip() for value in values]
    sentinel_tokens = [
        value for value in raw if value.casefold() == "not_applicable"
    ]
    if sentinel_tokens and (
        raw != ["NOT_APPLICABLE"]
        or sentinel_tokens != ["NOT_APPLICABLE"]
    ):
        return [], False
    return normalized, bool(normalized)


def evaluate_source_test_fallback(
    *,
    graph_blocker: str,
    source_owners: Sequence[str],
    known_callers: Sequence[str] = (),
    known_consumers: Sequence[str] = (),
    generated_authorities: Sequence[str],
    test_commands: Sequence[str],
    reviewer: str,
    residual_risk: str,
) -> dict[str, object]:
    """Record reviewer-owned source/test fallback without upgrading the graph."""

    blocker = _fallback_text(graph_blocker, field="graph blocker")
    owners = _normalized_handoff_texts(source_owners, field="source owners")
    callers = _normalized_handoff_texts(known_callers, field="known callers")
    consumers = _normalized_handoff_texts(known_consumers, field="known consumers")
    authorities, authorities_valid = _generated_authority_status(
        generated_authorities,
    )
    commands = _normalized_handoff_texts(test_commands, field="test commands")
    reviewer_name = _fallback_text(reviewer, field="reviewer")
    risk = _fallback_text(residual_risk, field="residual risk")

    missing: list[str] = []
    if not blocker:
        missing.append("graph blocker")
    if not owners:
        missing.append("source owners")
    if not callers:
        missing.append("known callers")
    if not consumers:
        missing.append("known consumers")
    if not authorities_valid:
        missing.append("generated authorities")
    if not commands:
        missing.append("test commands")
    if not reviewer_name:
        missing.append("reviewer")
    if not risk:
        missing.append("residual risk")
    return {
        "decision": "BLOCKED" if missing else "REVIEWER_ACKNOWLEDGED_FALLBACK",
        "graph_verdict": "BLOCKED",
        "graph_blocker": blocker,
        "source_owners": owners,
        "known_callers": callers,
        "known_consumers": consumers,
        "generated_authorities": authorities,
        "test_commands": commands,
        "reviewer": reviewer_name or None,
        "residual_risk": risk,
        "missing_requirements": missing,
    }
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall