Skip to content

dse120071750/m8m-harness-builder / skills/m8m/m8m-harness-builder

m8m-harness-builder

Flagged

Build and edit M8M harnesses that coordinate existing tools and FlowSteps, validate milestone outputs, and track progress and resume. Reuse working implementations in place. Compile workflow changes without runtime packaging; build portable packages when requested and deliver server installations through the dedicated M8M server installer.

FileKindSize
.gitattributesother112 B
.gitignoreother208 B
LICENSEother673 B
README.mdmarkdown29.8 KB
SKILL.mdskill md1.3 KB
agents/audit_complete.yamlconfig1.6 KB
agents/flow_generated.yamlconfig2.2 KB
agents/harness_validated.yamlconfig2.3 KB
agents/openai.yamlconfig4.6 KB
agents/skill_shipped.yamlconfig2.1 KB
agents/toolbox_ready.yamlconfig1.6 KB
conftest.pyscript275 B
contracts/conformance/expectation_first_runtime/candidate-cases.jsonconfig4.1 KB
contracts/conformance/expectation_first_runtime/common-linear.jsonconfig2.7 KB
contracts/conformance/expectation_first_runtime/schemas/judge-decision.schema.jsonconfig373 B
contracts/conformance/expectation_first_runtime/schemas/result.output.schema.jsonconfig589 B
contracts/conformance/expectation_first_runtime/schemas/source.output.schema.jsonconfig500 B
contracts/conformance/flowstep_flow_v4/invalid/judge-loop-unbound.jsonconfig483 B
contracts/conformance/flowstep_flow_v4/invalid/malformed-execution.jsonconfig571 B
contracts/conformance/flowstep_flow_v4/invalid/no-required-output.jsonconfig455 B
contracts/conformance/flowstep_flow_v4/invalid/nonjudge-bound.jsonconfig763 B
contracts/conformance/flowstep_flow_v4/invalid/unknown-field.jsonconfig469 B
contracts/conformance/flowstep_flow_v4/valid/authoring-union.jsonconfig4.3 KB
contracts/conformance/flowstep_flow_v4/valid/platform-dag.jsonconfig1.9 KB
contracts/file_ref_v2.schema.jsonconfig484 B
contracts/flow_sequence_action_v2.schema.jsonconfig1.5 KB
contracts/flowstep_flow_v4.schema.jsonconfig13.6 KB
contracts/flowstep_output_v2.schema.jsonconfig2.8 KB
contracts/flowstep_output_v3.schema.jsonconfig3.0 KB
contracts/flowstep_skill_audit_v1.schema.jsonconfig5.1 KB
contracts/m8m_builder_configuration_v1.schema.jsonconfig252 B
contracts/m8m_builder_input_v1.schema.jsonconfig183 B
contracts/m8m_builder_installation_receipt_v2.schema.jsonconfig2.9 KB
contracts/m8m_builder_output_v1.schema.jsonconfig453 B
contracts/m8m_builder_request_v3.schema.jsonconfig707 B
contracts/m8m_builder_result_v3.schema.jsonconfig422 B
contracts/m8m_builder_source_audit_v2.schema.jsonconfig6.1 KB
contracts/m8m_builder_source_bundle_v2.schema.jsonconfig8.6 KB
contracts/m8m_builder_toolbox_manifest_v2.schema.jsonconfig2.6 KB
contracts/m8m_builder_validation_report_v2.schema.jsonconfig3.4 KB
contracts/m8m_cache_receipt_v1.schema.jsonconfig1.2 KB
contracts/m8m_candidate_cache_entry_v1.schema.jsonconfig2.8 KB
contracts/m8m_chosen_output_v1.schema.jsonconfig2.3 KB
contracts/m8m_context_capsule_v1.schema.jsonconfig1.9 KB
contracts/m8m_contract_bundle_lock_v1.schema.jsonconfig648 B
contracts/m8m_goal_ledger_v1.schema.jsonconfig1.8 KB
contracts/m8m_milestone_agent_v1.schema.jsonconfig13.8 KB
contracts/m8m_milestone_expectation_v1.schema.jsonconfig1.9 KB
contracts/m8m_milestone_judge_receipt_v1.schema.jsonconfig1.7 KB
contracts/m8m_milestone_judge_request_v1.schema.jsonconfig3.0 KB
contracts/m8m_run_context_v1.schema.jsonconfig994 B
contracts/m8m_run_context_v2.schema.jsonconfig1.2 KB
contracts/m8m_run_storage_contract_v1.schema.jsonconfig894 B
contracts/m8m_runtime_lock_v1.schema.jsonconfig1.7 KB
contracts/m8m_runtime_release_v1.schema.jsonconfig2.2 KB
contracts/m8m_skill_canvas_v1.schema.jsonconfig4.0 KB
contracts/m8m_source_asset_manifest_v1.schema.jsonconfig1.2 KB
contracts/m8m_workflow_package_archive_v1.schema.jsonconfig1.1 KB
contracts/m8m_workflow_source_bundle_proof_v1.schema.jsonconfig1.6 KB
contracts/m8m_workflow_source_bundle_v1.schema.jsonconfig19.5 KB
contracts/tool_vs_intelligence_table_v1.schema.jsonconfig1.3 KB
docs/m8m-chart.jpgbinary172.2 KB
docs/m8m-task-builder-design.zh-HK.mdmarkdown66.9 KB
examples/article_infographic/README.mdmarkdown598 B
examples/article_infographic/planning/m8m-flowchart.jpgbinary186.0 KB
examples/article_infographic/planning/m8m-flowchart.mdmarkdown4.2 KB
flows/m8m_build_v2.yamlconfig9.9 KB
flowsteps/tools/audit_complete_judge/input.schema.jsonconfig190 B
flowsteps/tools/audit_complete_judge/output.schema.jsonconfig477 B
flowsteps/tools/audit_complete_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/audit_complete_judge/tool.pyscript1.2 KB
flowsteps/tools/audit_skill/input.schema.jsonconfig250 B
flowsteps/tools/audit_skill/output.schema.jsonconfig136 B
flowsteps/tools/audit_skill/tests/test_tool.pyscript1.9 KB
flowsteps/tools/audit_skill/tool.pyscript2.9 KB
flowsteps/tools/flow_generated_judge/input.schema.jsonconfig190 B
flowsteps/tools/flow_generated_judge/output.schema.jsonconfig475 B
flowsteps/tools/flow_generated_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/flow_generated_judge/tool.pyscript1.5 KB
flowsteps/tools/generate_from_audit/input.schema.jsonconfig562 B
flowsteps/tools/generate_from_audit/output.schema.jsonconfig137 B
flowsteps/tools/generate_from_audit/tests/test_tool.pyscript2.2 KB
flowsteps/tools/generate_from_audit/tool.pyscript3.0 KB
flowsteps/tools/harness_validated_judge/input.schema.jsonconfig193 B
flowsteps/tools/harness_validated_judge/output.schema.jsonconfig488 B
flowsteps/tools/harness_validated_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/harness_validated_judge/tool.pyscript1.3 KB
flowsteps/tools/install_local_skill/input.schema.jsonconfig733 B
flowsteps/tools/install_local_skill/output.schema.jsonconfig144 B
flowsteps/tools/install_local_skill/tests/test_tool.pyscript2.1 KB
flowsteps/tools/install_local_skill/tool.pyscript3.0 KB
flowsteps/tools/install_toolbox/input.schema.jsonconfig400 B
flowsteps/tools/install_toolbox/output.schema.jsonconfig140 B
flowsteps/tools/install_toolbox/tests/test_tool.pyscript1.9 KB
flowsteps/tools/install_toolbox/tool.pyscript3.0 KB
flowsteps/tools/skill_shipped_judge/input.schema.jsonconfig189 B
flowsteps/tools/skill_shipped_judge/output.schema.jsonconfig484 B
flowsteps/tools/skill_shipped_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/skill_shipped_judge/tool.pyscript1.3 KB
flowsteps/tools/toolbox_ready_judge/input.schema.jsonconfig189 B
flowsteps/tools/toolbox_ready_judge/output.schema.jsonconfig490 B
flowsteps/tools/toolbox_ready_judge/tests/test_tool.pyscript1.3 KB
flowsteps/tools/toolbox_ready_judge/tool.pyscript1.6 KB
flowsteps/tools/validate_harness/input.schema.jsonconfig563 B
flowsteps/tools/validate_harness/output.schema.jsonconfig141 B
flowsteps/tools/validate_harness/tests/test_tool.pyscript2.1 KB
flowsteps/tools/validate_harness/tool.pyscript3.0 KB
planning/upgrade.mdmarkdown16.2 KB
references/architecture.mdmarkdown28.1 KB
references/audit_complete.mdmarkdown739 B
references/builder-authoring.mdmarkdown9.8 KB
references/flow_generated.mdmarkdown1.2 KB
references/flowstep-development.mdmarkdown4.3 KB
references/harness-invocation.mdmarkdown2.9 KB
references/harness_validated.mdmarkdown786 B
references/master-prompts.mdmarkdown14.0 KB
references/milestone.mdmarkdown11.4 KB
references/output-lineage.mdmarkdown4.4 KB
references/runtime-packaging.mdmarkdown35.2 KB
references/server-delivery.mdmarkdown6.8 KB
references/skill_shipped.mdmarkdown798 B
references/tool-vs-intelligence.mdmarkdown10.0 KB
references/toolbox_ready.mdmarkdown612 B
requirements.txtmanifest150 B
scripts/audit_harness.pyscript80.7 KB
scripts/candidate_cache.pyscript27.6 KB
scripts/coordinate_workflow.pyscript4.3 KB
scripts/execution_identity.pyscript1.0 KB
scripts/flowchart_jpg.pyscript16.1 KB
scripts/flowstep_instruction.pyscript14.1 KB
scripts/flowstep_runtime.pyscript108.6 KB
scripts/flowstep_tools.pyscript5.7 KB
scripts/gem_text.pyscript5.7 KB
scripts/generate_harness.pyscript61.4 KB
scripts/humanize_chart.pyscript5.6 KB
scripts/humanize_chart_zh.pyscript5.2 KB
scripts/import_flow_v4.pyscript62.3 KB
scripts/m8m_build_steps.pyscript143.2 KB
scripts/m8m_cache.pyscript1.7 KB
scripts/m8m_delivery_common.pyscript3.8 KB
scripts/m8m_deploy.pyscript5.6 KB
scripts/m8m_factory.pyscript10.1 KB
scripts/m8m_flowchart.pyscript16.6 KB
scripts/m8m_local_bundle.pyscript4.5 KB
scripts/migrate_skill_source.pyscript34.2 KB
scripts/milestone_expectation.pyscript3.3 KB
scripts/milestone_pair.pyscript3.1 KB
scripts/package_archive.pyscript7.1 KB
scripts/project_imports.pyscript10.8 KB
scripts/run_flow.pyscript153.8 KB
scripts/run_goal.pyscript14.1 KB
scripts/run_m8m.pyscript3.8 KB
scripts/runtime_release.pyscript45.0 KB
scripts/schema_gate.pyscript5.6 KB
scripts/session_layout.pyscript74.4 KB
scripts/skill_source.pyscript65.3 KB
scripts/source_bundle.pyscript87.7 KB
scripts/teaching_contracts.pyscript8.9 KB
scripts/tool_vs_intelligence.pyscript9.3 KB
scripts/toolbox_plan.pyscript6.1 KB
scripts/validate_harness.pyscript24.1 KB
scripts/verify_platform_contract_parity.pyscript2.9 KB
seeds/branch_receipt/input.schema.jsonconfig1.0 KB
seeds/branch_receipt/output.schema.jsonconfig359 B
seeds/branch_receipt/tests/test_tool.pyscript2.0 KB
seeds/branch_receipt/tool.pyscript3.7 KB
seeds/cycle_receipt/input.schema.jsonconfig1.0 KB
seeds/cycle_receipt/output.schema.jsonconfig319 B
seeds/cycle_receipt/tests/test_tool.pyscript1.5 KB
seeds/cycle_receipt/tool.pyscript2.0 KB
seeds/hash_bind/input.schema.jsonconfig213 B
seeds/hash_bind/output.schema.jsonconfig288 B
seeds/hash_bind/tests/test_tool.pyscript814 B
seeds/hash_bind/tool.pyscript527 B
seeds/ledger_receipt/input.schema.jsonconfig278 B
seeds/ledger_receipt/output.schema.jsonconfig355 B
seeds/ledger_receipt/tests/test_tool.pyscript842 B
seeds/ledger_receipt/tool.pyscript747 B
seeds/ok_receipt/input.schema.jsonconfig280 B
seeds/ok_receipt/output.schema.jsonconfig280 B
seeds/ok_receipt/tests/test_tool.pyscript667 B
seeds/ok_receipt/tool.pyscript682 B
seeds/schema_validate/input.schema.jsonconfig265 B
seeds/schema_validate/output.schema.jsonconfig196 B
seeds/schema_validate/tests/test_tool.pyscript1.0 KB
seeds/schema_validate/tool.pyscript844 B
seeds/slot_write/input.schema.jsonconfig558 B
seeds/slot_write/output.schema.jsonconfig346 B
seeds/slot_write/tests/test_tool.pyscript1.2 KB
seeds/slot_write/tool.pyscript1015 B
tests/__init__.pyscript0 B
tests/support.pyscript668 B
tests/test_audit_harness.pyscript23.5 KB
tests/test_branch.pyscript14.4 KB
tests/test_builder3_templates.pyscript2.4 KB
tests/test_builder_install_integrity.pyscript30.6 KB
tests/test_builder_native_snapshot.pyscript5.0 KB
tests/test_builder_requirements.pyscript26.8 KB
tests/test_builder_self_dogfood.pyscript7.0 KB
tests/test_builder_self_source.pyscript10.3 KB

scripts/import_flow_v4.py

View on GitHub
#!/usr/bin/env python3
"""Explicit, staging-only ``flowstep_flow_v4`` to skill-source importer.

The importer has four separate operations: inspect, digest-bound accept,
stage, and verify.  It never installs a skill, writes a codebase, deploys, or
claims execution closure.  Execution/profile/capability declarations are
operator-supplied because a v4 flow does not contain those Builder 3 facts.
"""

from __future__ import annotations

import argparse
import copy
import hashlib
import json
import os
import re
import shutil
import tempfile
from pathlib import Path, PurePosixPath
from typing import Any, Mapping
from urllib.parse import unquote, urlsplit

import yaml
from jsonschema import Draft202012Validator

from flowstep_runtime import (
    FlowError,
    load_flow,
    local_tool_package_name,
    runtime_package_name,
    sha256_file,
)
from skill_source import (
    SkillSourceError,
    _native_graph,
    canonical_json_bytes,
    compile_skill_source,
    load_skill_source,
)


INSPECTION_SCHEMA = "m8m.flow_v4_import_inspection.v1"
ACCEPTANCE_REQUEST_SCHEMA = "m8m.flow_v4_import_acceptance_request.v1"
ACCEPTANCE_SCHEMA = "m8m.flow_v4_import_acceptance.v1"
VERIFY_SCHEMA = "m8m.flow_v4_import_verification.v1"
PROOF_SCHEMA = "m8m.flow_v4_import_equivalence_proof.v1"
RESOURCE_MANIFEST_SCHEMA = "m8m.flow_v4_import_resource_manifest.v1"
_VERSIONED_REF = re.compile(r"^[a-z][a-z0-9_.-]*@[0-9]+\.[0-9]+\.[0-9]+$")
_GLOB = re.compile(r"[*?\[]")


class ImportFlowV4Error(ValueError):
    """The requested import is ambiguous, stale, unsafe, or lossy."""


def _digest(value: Any) -> str:
    return "sha256:" + hashlib.sha256(canonical_json_bytes(value)).hexdigest()


def _with_digest(value: dict[str, Any], field: str) -> dict[str, Any]:
    result = copy.deepcopy(value)
    result[field] = _digest(result)
    return result


def _assert_digest(value: Mapping[str, Any], field: str, *, label: str) -> None:
    expected = str(value.get(field) or "")
    payload = {key: copy.deepcopy(item) for key, item in value.items() if key != field}
    if expected != _digest(payload):
        raise ImportFlowV4Error(f"{label} digest is missing or does not match its contents")


def _safe_relative(value: Any, *, label: str) -> str:
    if not isinstance(value, str) or not value.strip() or value != value.strip():
        raise ImportFlowV4Error(f"{label} must be a normalized non-empty relative path")
    if "\\" in value or value.startswith("/") or re.match(r"^[A-Za-z]:", value) or _GLOB.search(value):
        raise ImportFlowV4Error(f"{label} must be a safe relative path")
    path = PurePosixPath(value)
    if path.is_absolute() or any(part in {"", ".", ".."} for part in path.parts):
        raise ImportFlowV4Error(f"{label} must stay inside its declared root")
    return path.as_posix()


def _bounded_file(root: Path, relative: str, *, label: str) -> Path:
    relative = _safe_relative(relative, label=label)
    root = root.resolve()
    candidate = root.joinpath(*PurePosixPath(relative).parts)
    if candidate.is_symlink():
        raise ImportFlowV4Error(f"{label} may not be a symbolic link")
    try:
        resolved = candidate.resolve(strict=True)
    except (FileNotFoundError, OSError) as exc:
        raise ImportFlowV4Error(f"{label} is missing: {relative}") from exc
    if root not in resolved.parents or not resolved.is_file():
        raise ImportFlowV4Error(f"{label} escapes its declared root or is not a file")
    return resolved


def _project_root(harness: Path) -> Path:
    if harness.parent.name == "flows" and harness.parent.parent.name == "flowsteps":
        return harness.parent.parent.parent.resolve()
    return harness.resolve()


def _roots(source_root: str | Path, project_root: str | Path | None = None) -> tuple[Path, Path]:
    harness = Path(source_root).resolve(strict=True)
    if not harness.is_dir():
        raise ImportFlowV4Error("source root is not a directory")
    project = Path(project_root).resolve(strict=True) if project_root is not None else _project_root(harness)
    if not project.is_dir():
        raise ImportFlowV4Error("project root is not a directory")
    return harness, project


_PROJECTION_FIELDS = (
    "id", "handler", "implementation_dependencies", "intelligence", "tools", "flowsteps",
    "inputs", "output_contract", "input_schema", "output_schema", "test", "on_tool_fail",
    "max_model_attempts", "max_tool_attempts", "max_attempts", "loop", "ledger", "worker",
    "judge_abi", "receipt_schema", "branch", "on_path", "cycle", "on_cycle", "success",
    "draft_schema", "model_justification", "asset", "outputs", "cache", "side_effects",
    "phase_journal", "execution",
)


def semantic_projection(skill_dir: Path, flow_path: Path | None = None) -> dict[str, Any]:
    """Return the exact normalized runtime-significant v4 projection."""

    loaded = load_flow(skill_dir, flow_path, allow_unbound_import=True)
    milestones: list[dict[str, Any]] = []
    for step in loaded["steps"]:
        row = {field: copy.deepcopy(step.get(field)) for field in _PROJECTION_FIELDS}
        row["gem"] = str(step.get("gem") or f"references/{step['id']}.md")
        milestones.append(row)
    return {
        "schema": loaded["schema"],
        "flow_id": loaded["flow_id"],
        "version": loaded["version"],
        "context_policy": loaded.get("context_policy"),
        "max_run_seconds": loaded.get("max_run_seconds"),
        "artifact_root": loaded.get("artifact_root"),
        "implementation_dependencies": list(loaded.get("implementation_dependencies") or []),
        "milestones": milestones,
    }


_AGENT_FLOW_FIELDS = (
    "success", "output_contract", "output_schema", "outputs", "asset", "handler",
    "implementation_dependencies", "test", "input_schema", "inputs", "flowsteps", "tools",
    "intelligence", "model_justification", "draft_schema", "on_tool_fail",
    "max_model_attempts", "max_tool_attempts", "side_effects", "phase_journal", "loop",
    "worker", "judge_abi", "receipt_schema", "max_attempts", "ledger", "branch", "on_path",
    "cycle", "on_cycle", "cache", "execution",
)


def _agent_skeleton(step: Mapping[str, Any]) -> dict[str, Any]:
    milestone_id = str(step["id"])
    agent: dict[str, Any] = {
        "schema": "m8m_milestone_agent_v1",
        "agent_id": milestone_id,
        "role": "milestone",
    }
    for field in _AGENT_FLOW_FIELDS:
        value = step.get(field)
        if value is not None and value != []:
            agent[field] = copy.deepcopy(value)
    agent["flowsteps"] = []
    for flowstep in step.get("flowsteps") or []:
        exact_or_local = str(flowstep.get("tool") or "")
        try:
            local_name = local_tool_package_name(
                exact_or_local,
                label=f"{milestone_id}.{flowstep.get('id')}.tool",
            )
        except FlowError:
            local_name = exact_or_local
        agent["flowsteps"].append(
            {"id": str(flowstep["id"]), "tool": local_name}
        )
    agent["gem"] = f"references/{milestone_id}.md"
    agent["read_paths"] = [agent["gem"]]
    agent["observer"] = {
        "title": milestone_id.replace("_", " ").title(),
        "summary": str(step.get("success") or f"Complete {milestone_id}."),
        "actions": [
            {
                "flowstep_id": item["id"],
                "title": str(item["id"]).replace("_", " ").title(),
                "summary": f"Run the declared {item['tool']} FlowStep.",
            }
            for item in step.get("flowsteps") or []
        ],
        "outputs": [
            {
                "output_id": item["id"],
                "title": item["name"],
                "summary": f"Declared {item['cardinality']} {item['kind']} output.",
            }
            for item in step.get("outputs") or []
        ],
    }
    return agent


def _schema_refs(value: Any) -> list[str]:
    found: list[str] = []
    if isinstance(value, dict):
        for key, child in value.items():
            if key == "$ref" and isinstance(child, str):
                found.append(child)
            else:
                found.extend(_schema_refs(child))
    elif isinstance(value, list):
        for child in value:
            found.extend(_schema_refs(child))
    return found


def _closed_judge_receipt(path: Path) -> bool:
    try:
        value = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError):
        return False
    properties = value.get("properties") if isinstance(value, dict) else None
    required = value.get("required") if isinstance(value, dict) else None
    return bool(
        isinstance(value, dict)
        and value.get("type") == "object"
        and value.get("additionalProperties") is False
        and isinstance(required, list)
        and set(required) == {"decision", "reasons", "blockers"}
        and isinstance(properties, dict)
        and set(properties) == {"decision", "reasons", "blockers"}
        and set((properties.get("decision") or {}).get("enum") or [])
        == {"PASS", "RETRY", "BLOCKED"}
    )


def _collect_resources(
    harness: Path,
    project: Path,
    agents: list[dict[str, Any]],
    flow_dependencies: list[str],
) -> tuple[list[dict[str, Any]], list[str]]:
    resources: dict[str, dict[str, Any]] = {}
    blockers: list[str] = []

    def add(scope: str, source_relative: str, stage_relative: str, label: str) -> None:
        try:
            source_relative = _safe_relative(source_relative, label=label)
            stage_relative = _safe_relative(stage_relative, label=f"{label} stage path")
            root = harness if scope == "harness" else project
            path = _bounded_file(root, source_relative, label=label)
            row = {
                "source_scope": scope,
                "source_path": source_relative,
                "stage_path": stage_relative,
                "byte_count": path.stat().st_size,
                "sha256": "sha256:" + sha256_file(path),
            }
            prior = resources.get(stage_relative)
            if prior is not None and prior["sha256"] != row["sha256"]:
                raise ImportFlowV4Error(f"two different source files map to {stage_relative}")
            resources[stage_relative] = row
        except (ImportFlowV4Error, OSError) as exc:
            blockers.append(str(exc))

    for agent in agents:
        milestone_id = agent["agent_id"]
        for field in ("handler", "test", "output_schema", "draft_schema", "receipt_schema", "gem"):
            if agent.get(field):
                add("harness", str(agent[field]), str(agent[field]), f"{milestone_id}.{field}")
        for control_field in ("branch", "cycle"):
            control = agent.get(control_field)
            if isinstance(control, dict) and control.get("receipt_schema"):
                ref = str(control["receipt_schema"])
                add("harness", ref, ref, f"{milestone_id}.{control_field}.receipt_schema")
        for dependency in agent.get("implementation_dependencies") or []:
            add("project", str(dependency), str(dependency), f"{milestone_id}.implementation_dependencies")
    for dependency in flow_dependencies:
        add("project", str(dependency), str(dependency), "flow.implementation_dependencies")

    # Close local JSON Schema references so staging cannot silently drop a
    # schema dependency that the skill compiler will later hash-bind.
    pending = [row for row in resources.values() if str(row["stage_path"]).endswith(".json")]
    seen: set[str] = set()
    while pending:
        row = pending.pop(0)
        key = str(row["stage_path"])
        if key in seen:
            continue
        seen.add(key)
        root = harness if row["source_scope"] == "harness" else project
        try:
            path = _bounded_file(root, str(row["source_path"]), label=f"schema {key}")
            document = json.loads(path.read_text(encoding="utf-8"))
        except (ImportFlowV4Error, OSError, UnicodeError, json.JSONDecodeError) as exc:
            blockers.append(f"schema {key} cannot be inspected: {exc}")
            continue
        for raw_ref in _schema_refs(document):
            parts = urlsplit(raw_ref)
            if parts.scheme or parts.netloc or parts.query:
                blockers.append(f"schema {key} has unsupported external $ref: {raw_ref}")
                continue
            if not parts.path:
                continue
            decoded = unquote(parts.path)
            source_rel = (PurePosixPath(str(row["source_path"])).parent / decoded).as_posix()
            stage_rel = (PurePosixPath(key).parent / decoded).as_posix()
            before = set(resources)
            add(str(row["source_scope"]), source_rel, stage_rel, f"schema dependency of {key}")
            if set(resources) != before:
                pending.append(resources[stage_rel])
    return [resources[key] for key in sorted(resources)], list(dict.fromkeys(blockers))


def _tool_package_manifest(project: Path, tool_ids: list[str]) -> tuple[list[dict[str, Any]], list[str]]:
    packages: list[dict[str, Any]] = []
    blockers: list[str] = []
    package_ids = list(
        dict.fromkeys(
            tool_id.rsplit("@", 1)[0]
            if _VERSIONED_REF.fullmatch(tool_id)
            else tool_id
            for tool_id in tool_ids
        )
    )
    for tool_id in package_ids:
        tool_root = project / "flowsteps" / "tools" / tool_id
        if not tool_root.is_dir() or tool_root.is_symlink():
            blockers.append(f"tool {tool_id}: package is missing from project flowsteps/tools")
            continue
        entries = sorted(tool_root.rglob("*"), key=lambda item: item.as_posix().lower())
        symlinks = [path.relative_to(tool_root).as_posix() for path in entries if path.is_symlink()]
        if symlinks:
            blockers.append(
                f"tool {tool_id}: symbolic links are not allowed in the frozen package: "
                + ", ".join(symlinks)
            )
            continue
        members: list[dict[str, Any]] = []
        for path in entries:
            if not path.is_file() or "__pycache__" in path.parts or path.suffix.lower() in {".pyc", ".pyo"}:
                continue
            relative = path.relative_to(tool_root).as_posix()
            members.append(
                {
                    "path": relative,
                    "byte_count": path.stat().st_size,
                    "sha256": "sha256:" + sha256_file(path),
                }
            )
        if not members:
            blockers.append(f"tool {tool_id}: package contains no bindable files")
            continue
        packages.append(
            {
                "tool_id": tool_id,
                "members": members,
                "package_digest": _digest(members),
                "copied_into_skill": False,
            }
        )
    return packages, blockers


def inspect_flow_v4(
    source_root: str | Path,
    flow_path: str | Path | None = None,
    *,
    skill_name: str | None = None,
    display_name: str | None = None,
    description: str | None = None,
    default_prompt: str | None = None,
) -> dict[str, Any]:
    """Inspect one legacy v4 flow and return a deterministic import plan."""

    harness, project = _roots(source_root)
    chosen_flow = Path(flow_path) if flow_path is not None else harness / "flow.yaml"
    if not chosen_flow.is_absolute():
        chosen_flow = harness / chosen_flow
    try:
        chosen_flow = chosen_flow.resolve(strict=True)
        flow_relative = chosen_flow.relative_to(harness).as_posix()
    except (FileNotFoundError, OSError, ValueError) as exc:
        raise ImportFlowV4Error("flow path must be a file inside source root") from exc
    try:
        loaded = load_flow(harness, chosen_flow, allow_unbound_import=True)
    except FlowError as exc:
        raise ImportFlowV4Error(str(exc)) from exc

    projection = semantic_projection(harness, chosen_flow)
    raw_milestones = list(loaded.get("milestones") or [])
    blockers: list[str] = []
    agents: list[dict[str, Any]] = []
    for raw, step in zip(raw_milestones, loaded["steps"]):
        milestone_id = str(step["id"])
        legacy_fields = [field for field in ("next", "else", "join") if field in raw]
        if legacy_fields:
            blockers.append(
                f"{milestone_id}: raw {', '.join(legacy_fields)} routing is not a native v4 runtime declaration"
            )
        if str(raw.get("loop") or "none") == "for":
            blockers.append(f"{milestone_id}: legacy loop=for needs an operator-authored explicit cycle and join")
        if step.get("loop") == "judge" and step.get("judge_abi") != "m8m_milestone_judge_v1":
            blockers.append(
                f"{milestone_id}: implicit legacy judge behavior cannot be upgraded to the strict judge ABI losslessly"
            )
        if step.get("loop") == "judge" and step.get("judge_abi") == "m8m_milestone_judge_v1":
            receipt_ref = str(step.get("receipt_schema") or "")
            try:
                receipt_path = _bounded_file(harness, receipt_ref, label=f"{milestone_id}.receipt_schema")
            except ImportFlowV4Error as exc:
                blockers.append(str(exc))
            else:
                if not _closed_judge_receipt(receipt_path):
                    blockers.append(
                        f"{milestone_id}: strict judge result schema must be closed with "
                        "exact decision, reasons, and blockers fields"
                    )
        raw_gem = str(raw.get("gem") or f"references/{milestone_id}.md")
        if raw_gem != f"references/{milestone_id}.md":
            blockers.append(f"{milestone_id}: custom gem path cannot be losslessly renamed")
        if not step.get("flowsteps") or any(not item.get("tool") for item in step.get("flowsteps") or []):
            blockers.append(f"{milestone_id}: every imported FlowStep must have one explicit tool")
        agents.append(_agent_skeleton(step))

    try:
        adjacency = _native_graph(agents)
    except SkillSourceError as exc:
        blockers.append(str(exc))
        adjacency = {agent["agent_id"]: [] for agent in agents}
    order = [agent["agent_id"] for agent in agents]
    incoming = {item: 0 for item in order}
    for targets in adjacency.values():
        for target in targets:
            if target in incoming:
                incoming[target] += 1
    roots = [item for item in order if incoming[item] == 0]
    terminals = [item for item in order if not adjacency.get(item)]
    if len(roots) != 1:
        blockers.append("native graph must have exactly one entry root")
    if not terminals:
        blockers.append("native graph must have at least one success terminal")

    resources, resource_blockers = _collect_resources(
        harness,
        project,
        agents,
        list(loaded.get("implementation_dependencies") or []),
    )
    blockers.extend(resource_blockers)
    tool_ids: list[str] = []
    for step in loaded["steps"]:
        for flowstep in step.get("flowsteps") or []:
            tool_ref = str(flowstep.get("tool") or "")
            try:
                tool_ids.append(
                    local_tool_package_name(
                        tool_ref,
                        label=f"{step['id']}.{flowstep.get('id')}.tool",
                    )
                )
            except FlowError:
                if tool_ref:
                    tool_ids.append(tool_ref)
        worker = str(step.get("worker") or "")
        if worker:
            tool_ids.append(
                runtime_package_name(worker, label=f"{step['id']}.worker")
                if step.get("judge_abi")
                else worker
            )
    tool_ids = list(dict.fromkeys(tool_ids))
    tool_packages, tool_blockers = _tool_package_manifest(project, tool_ids)
    blockers.extend(tool_blockers)
    resolved_skill_name = skill_name or str(loaded["flow_id"]).replace("_", "-")
    resolved_display = display_name or str(loaded["flow_id"]).replace("_", " ").title()
    resolved_description = description or f"Imported local M8M workflow {loaded['flow_id']}."
    resolved_prompt = default_prompt or f"Use ${resolved_skill_name} with an explicit request."
    plan = {
        "schema": INSPECTION_SCHEMA,
        "source": {
            "flow_path": flow_relative,
            "flow_sha256": "sha256:" + sha256_file(chosen_flow),
        },
        "skill": {"name": resolved_skill_name, "description": resolved_description},
        "interface": {
            "display_name": resolved_display,
            "short_description": resolved_description,
            "default_prompt": resolved_prompt,
        },
        "flow_id": loaded["flow_id"],
        "version": loaded["version"],
        "semantic_projection": projection,
        "source_semantic_digest": _digest(projection),
        "graph": [{"from": item, "to": list(adjacency[item])} for item in order],
        "entry": roots[0] if len(roots) == 1 else "",
        "terminals": terminals,
        "milestones": [
            {
                "id": agent["agent_id"],
                "intelligence": agent.get("intelligence", "none"),
                "loop": agent.get("loop", "none"),
                "tools": list(agent.get("tools") or []),
                "agent": agent,
            }
            for agent in agents
        ],
        "resources": resources,
        "tool_packages": tool_packages,
        "lossless": not blockers,
        "blockers": list(dict.fromkeys(blockers)),
        "operator_boundary": (
            "Supply exact execution/profile/capability declarations and accept this inspection digest. "
            "The importer proves v4 runtime equivalence only; it does not prove implementations built."
        ),
        "staging_only": True,
    }
    return _with_digest(plan, "inspection_digest")


def _accept_workflow_contracts(
    inspection: Mapping[str, Any], request: Mapping[str, Any], harness: Path
) -> tuple[dict[str, Any], list[dict[str, Any]]]:
    contracts = request.get("workflow_contracts")
    required = {"request_schema", "configuration_schema", "result_schema", "terminal_bindings"}
    if not isinstance(contracts, dict) or set(contracts) != required:
        raise ImportFlowV4Error("acceptance requires exact workflow_contracts schema paths and terminal_bindings")
    resources: list[dict[str, Any]] = []
    documents: dict[str, dict[str, Any]] = {}
    for field in ("request_schema", "configuration_schema", "result_schema"):
        relative = _safe_relative(contracts[field], label=f"workflow_contracts.{field}")
        path = _bounded_file(harness, relative, label=f"workflow_contracts.{field}")
        try:
            document = json.loads(path.read_text(encoding="utf-8"))
            Draft202012Validator.check_schema(document)
        except (OSError, UnicodeError, json.JSONDecodeError, Exception) as exc:
            raise ImportFlowV4Error(f"workflow_contracts.{field} is not valid JSON Schema: {exc}") from exc
        if (
            not isinstance(document, dict)
            or document.get("$schema") != "https://json-schema.org/draft/2020-12/schema"
            or document.get("type") != "object"
            or document.get("additionalProperties") is not False
        ):
            raise ImportFlowV4Error(f"workflow_contracts.{field} must be a closed Draft 2020-12 object schema")
        documents[field] = document
        resources.append(
            {
                "source_scope": "harness",
                "source_path": relative,
                "stage_path": relative,
                "byte_count": path.stat().st_size,
                "sha256": "sha256:" + sha256_file(path),
            }
        )
    by_stage = {row["stage_path"]: row for row in resources}
    pending = list(resources)
    while pending:
        row = pending.pop(0)
        path = _bounded_file(harness, row["source_path"], label=f"workflow schema {row['stage_path']}")
        try:
            document = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, UnicodeError, json.JSONDecodeError) as exc:
            raise ImportFlowV4Error(f"workflow schema dependency is invalid JSON: {row['stage_path']}") from exc
        for raw_ref in _schema_refs(document):
            parts = urlsplit(raw_ref)
            if parts.scheme or parts.netloc or parts.query:
                raise ImportFlowV4Error(f"workflow schema has unsupported external $ref: {raw_ref}")
            if not parts.path:
                continue
            decoded = unquote(parts.path)
            source_rel = (PurePosixPath(row["source_path"]).parent / decoded).as_posix()
            stage_rel = _safe_relative(
                (PurePosixPath(row["stage_path"]).parent / decoded).as_posix(),
                label=f"workflow schema dependency of {row['stage_path']}",
            )
            dependency = _bounded_file(harness, source_rel, label=f"workflow schema dependency {stage_rel}")
            descriptor = {
                "source_scope": "harness",
                "source_path": _safe_relative(source_rel, label=f"workflow schema dependency {stage_rel}"),
                "stage_path": stage_rel,
                "byte_count": dependency.stat().st_size,
                "sha256": "sha256:" + sha256_file(dependency),
            }
            prior = by_stage.get(stage_rel)
            if prior is not None and prior != descriptor:
                raise ImportFlowV4Error(f"workflow schema dependency collision: {stage_rel}")
            if prior is None:
                by_stage[stage_rel] = descriptor
                resources.append(descriptor)
                pending.append(descriptor)
    bindings = contracts["terminal_bindings"]
    if not isinstance(bindings, list) or not bindings:
        raise ImportFlowV4Error("workflow_contracts.terminal_bindings must be non-empty")
    terminals = set(inspection["terminals"])
    by_id = {row["id"]: row["agent"] for row in inspection["milestones"]}
    names: list[str] = []
    seen_sources: set[tuple[str, str]] = set()
    for index, binding in enumerate(bindings):
        if not isinstance(binding, dict) or set(binding) != {"name", "from", "output"}:
            raise ImportFlowV4Error(f"terminal binding {index} must contain only name, from, and output")
        name = str(binding["name"])
        source_ref = str(binding["from"])
        if "." not in source_ref:
            raise ImportFlowV4Error(f"terminal binding {name} has an invalid from reference")
        source, contract = source_ref.split(".", 1)
        if source not in terminals or contract != by_id[source]["output_contract"]:
            raise ImportFlowV4Error(f"terminal binding {name} does not name an exact success-terminal contract")
        output = str(binding["output"])
        if output not in {row["id"] for row in by_id[source]["outputs"]}:
            raise ImportFlowV4Error(f"terminal binding {name} names an unknown output port")
        if name in names or (source, output) in seen_sources:
            raise ImportFlowV4Error("workflow terminal binding names and source ports must be unique")
        names.append(name)
        seen_sources.add((source, output))
    result = documents["result_schema"]
    if set(result.get("properties") or {}) != set(names) or set(result.get("required") or []) != set(names):
        raise ImportFlowV4Error("result schema properties/required must exactly match terminal binding names")
    return copy.deepcopy(contracts), [by_stage[key] for key in sorted(by_stage)]


def _validate_profile(
    milestone_id: str,
    role: str,
    profile: Any,
    *,
    expected_tools: list[str],
    capability_ids: set[str],
) -> set[str]:
    if not isinstance(profile, dict):
        raise ImportFlowV4Error(f"{milestone_id}: {role} profile must be an object")
    required = {"ref", "model_configuration", "token_budget", "timeout_seconds", "tools", "capabilities"}
    if set(profile) != required:
        raise ImportFlowV4Error(f"{milestone_id}: {role} profile must contain exactly {sorted(required)}")
    ref = profile["ref"]
    if not isinstance(ref, str) or not ref.strip() or ref != ref.strip():
        raise ImportFlowV4Error(f"{milestone_id}: {role} profile ref must be explicit")
    configuration = profile["model_configuration"]
    if not isinstance(configuration, dict) or set(configuration) - {"model", "reasoning", "temperature"} or not {"model", "reasoning"}.issubset(configuration):
        raise ImportFlowV4Error(f"{milestone_id}: {role} model configuration is incomplete")
    if not isinstance(configuration["model"], str) or not configuration["model"].strip():
        raise ImportFlowV4Error(f"{milestone_id}: {role} model is required")
    if configuration["reasoning"] not in {"none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"}:
        raise ImportFlowV4Error(f"{milestone_id}: {role} reasoning is invalid")
    budget = profile["token_budget"]
    if not isinstance(budget, dict) or set(budget) != {"max_input_tokens", "max_output_tokens"}:
        raise ImportFlowV4Error(f"{milestone_id}: {role} token budget is incomplete")
    if any(not isinstance(budget[key], int) or isinstance(budget[key], bool) or budget[key] < 1 for key in budget):
        raise ImportFlowV4Error(f"{milestone_id}: {role} token budgets must be positive integers")
    timeout = profile["timeout_seconds"]
    if not isinstance(timeout, int) or isinstance(timeout, bool) or timeout < 1:
        raise ImportFlowV4Error(f"{milestone_id}: {role} timeout must be a positive integer")
    profile_tools = profile["tools"]
    if not isinstance(profile_tools, list) or list(profile_tools) != expected_tools:
        raise ImportFlowV4Error(f"{milestone_id}: {role} profile tools do not match its executor role")
    bound_capabilities = profile["capabilities"]
    if (
        not isinstance(bound_capabilities, list)
        or any(not isinstance(item, str) or not item for item in bound_capabilities)
        or len(bound_capabilities) != len(set(bound_capabilities))
    ):
        raise ImportFlowV4Error(f"{milestone_id}: {role} profile capabilities must be unique")
    unknown = set(bound_capabilities) - capability_ids
    if unknown:
        raise ImportFlowV4Error(f"{milestone_id}: {role} profile binds undeclared capabilities")
    return set(bound_capabilities)


def accept_import(
    inspection: Mapping[str, Any],
    request: Mapping[str, Any],
    *,
    source_root: str | Path,
    project_root: str | Path | None = None,
) -> dict[str, Any]:
    """Bind explicit operator declarations to one immutable inspection."""

    _assert_digest(inspection, "inspection_digest", label="inspection")
    if inspection.get("schema") != INSPECTION_SCHEMA or not inspection.get("lossless"):
        raise ImportFlowV4Error("inspection is not lossless; resolve every blocker before acceptance")
    if request.get("schema") != ACCEPTANCE_REQUEST_SCHEMA:
        raise ImportFlowV4Error(f"acceptance request schema must be {ACCEPTANCE_REQUEST_SCHEMA}")
    if request.get("inspection_digest") != inspection.get("inspection_digest"):
        raise ImportFlowV4Error("acceptance request is not bound to this inspection digest")
    acknowledgements = request.get("acknowledgements")
    required_ack = {
        "execution_declarations_are_operator_supplied": True,
        "staging_only": True,
        "no_install_or_deploy": True,
    }
    if acknowledgements != required_ack:
        raise ImportFlowV4Error("acceptance must explicitly acknowledge execution ownership and staging-only scope")
    harness, _project = _roots(source_root, project_root)
    workflow_contracts, workflow_resources = _accept_workflow_contracts(inspection, request, harness)
    known_resources = {row["stage_path"]: row["sha256"] for row in inspection["resources"]}
    for row in workflow_resources:
        prior = known_resources.get(row["stage_path"])
        if prior is not None and prior != row["sha256"]:
            raise ImportFlowV4Error(f"workflow contract conflicts with inspected resource {row['stage_path']}")
    requested = request.get("milestones")
    if not isinstance(requested, list):
        raise ImportFlowV4Error("acceptance request milestones must be a list")
    expected_ids = [row["id"] for row in inspection["milestones"]]
    actual_ids = [str(row.get("id") or "") for row in requested if isinstance(row, dict)]
    if actual_ids != expected_ids or len(actual_ids) != len(requested):
        raise ImportFlowV4Error("acceptance milestones must exactly cover the inspected roster in order")

    semantic_by_id = {
        str(item.get("id") or ""): item
        for item in (inspection.get("semantic_projection") or {}).get("milestones") or []
        if isinstance(item, Mapping)
    }
    for inspected, declared in zip(inspection["milestones"], requested):
        execution = declared.get("execution")
        if not isinstance(execution, dict) or not isinstance(execution.get("candidate_executor"), dict):
            raise ImportFlowV4Error(f"{inspected['id']}: candidate executor declaration is required")
        candidate = execution["candidate_executor"]
        if not _VERSIONED_REF.fullmatch(str(candidate.get("ref") or "")):
            raise ImportFlowV4Error(f"{inspected['id']}: candidate executor ref must be versioned")
        bindings = execution.get("tool_bindings")
        bound_tools = [str(row.get("tool") or "") for row in bindings or [] if isinstance(row, dict)]
        if bound_tools != list(inspected["tools"]) or len(bound_tools) != len(bindings or []):
            raise ImportFlowV4Error(f"{inspected['id']}: tool bindings must exactly cover effective FlowStep tools")
        exact_flowstep_refs = {
            str(item.get("id") or ""): str(item.get("tool") or "")
            for item in semantic_by_id.get(str(inspected["id"]), {}).get("flowsteps") or []
            if isinstance(item, Mapping)
        }
        for binding in bindings:
            ref = str(binding.get("ref") or "")
            if not _VERSIONED_REF.fullmatch(ref):
                raise ImportFlowV4Error(f"{inspected['id']}: tool ref must be versioned")
            exact_flowstep_ref = exact_flowstep_refs.get(str(binding["tool"]), "")
            if _VERSIONED_REF.fullmatch(exact_flowstep_ref) and ref != exact_flowstep_ref:
                raise ImportFlowV4Error(
                    f"{inspected['id']}: tool binding {binding['tool']} must exactly equal "
                    "the inspected executable FlowStep ref"
                )
            flowstep_local = {
                str(item.get("id") or ""): str(item.get("tool") or "")
                for item in inspected["agent"].get("flowsteps") or []
                if isinstance(item, dict)
            }.get(str(binding["tool"]), "")
            try:
                bound_local = local_tool_package_name(
                    ref,
                    label=f"{inspected['id']}.{binding['tool']}.ref",
                )
            except FlowError as exc:
                raise ImportFlowV4Error(str(exc)) from exc
            if bound_local != flowstep_local:
                raise ImportFlowV4Error(
                    f"{inspected['id']}: tool binding {binding['tool']} does not "
                    "resolve to its inspected FlowStep package"
                )
        if inspected.get("loop") == "judge":
            judge = execution.get("judge")
            if not isinstance(judge, dict) or not _VERSIONED_REF.fullmatch(str(judge.get("ref") or "")):
                raise ImportFlowV4Error(f"{inspected['id']}: judge loop needs a versioned judge ref")
            judge_ref = str(judge["ref"])
            worker_ref = str(inspected["agent"].get("worker") or "")
            if worker_ref != judge_ref:
                raise ImportFlowV4Error(
                    f"{inspected['id']}: worker must exactly equal execution.judge.ref"
                )
            candidate_ref = str(candidate.get("ref") or "")
            tool_binding_refs = {
                str(binding.get("ref") or "")
                for binding in bindings
                if isinstance(binding, dict)
            }
            if judge_ref == candidate_ref or judge_ref in tool_binding_refs:
                raise ImportFlowV4Error(
                    f"{inspected['id']}: judge ref must be distinct from candidate and tool refs"
                )
        capabilities = declared.get("capabilities") or []
        if not isinstance(capabilities, list):
            raise ImportFlowV4Error(f"{inspected['id']}: capabilities must be a list")
        capability_ids: list[str] = []
        for capability in capabilities:
            if not isinstance(capability, dict) or set(capability) != {"id", "ref", "access", "side_effects"}:
                raise ImportFlowV4Error(f"{inspected['id']}: every capability declaration must be closed")
            if not _VERSIONED_REF.fullmatch(str(capability.get("ref") or "")):
                raise ImportFlowV4Error(f"{inspected['id']}: capability ref must be versioned")
            if capability.get("access") not in {"read", "write", "execute", "use"} or capability.get("side_effects") not in {"none", "local", "external"}:
                raise ImportFlowV4Error(f"{inspected['id']}: capability access/side_effects are invalid")
            capability_ids.append(str(capability.get("id") or ""))
        if any(not item for item in capability_ids) or len(capability_ids) != len(set(capability_ids)):
            raise ImportFlowV4Error(f"{inspected['id']}: capability ids must be non-empty and unique")
        external = any(isinstance(item, dict) and item.get("side_effects") == "external" for item in capabilities)
        milestone_external = inspected["agent"].get("side_effects", "none") == "external"
        if external != milestone_external:
            raise ImportFlowV4Error(f"{inspected['id']}: external capability and side-effect semantics differ")
        candidate_profile = candidate.get("profile")
        judge_binding = execution.get("judge") if isinstance(execution.get("judge"), dict) else None
        judge_profile = judge_binding.get("profile") if judge_binding else None
        intelligence = str(inspected.get("intelligence") or "none")
        if intelligence != "none" and not isinstance(candidate_profile, dict):
            raise ImportFlowV4Error(f"{inspected['id']}: AI candidate profile must be operator supplied")
        if intelligence == "none" and candidate_profile is not None:
            raise ImportFlowV4Error(f"{inspected['id']}: deterministic candidate cannot accept an AI profile")
        if intelligence == "judge" and not isinstance(judge_profile, dict):
            raise ImportFlowV4Error(f"{inspected['id']}: legacy AI judge role requires an explicit judge profile")
        if judge_binding is not None and (
            inspected.get("loop") != "judge"
            or inspected["agent"].get("judge_abi") != "m8m_milestone_judge_v1"
            or not inspected["agent"].get("receipt_schema")
        ):
            raise ImportFlowV4Error(f"{inspected['id']}: separate judge requires the authored strict judge contract")
        bound_capabilities: set[str] = set()
        if isinstance(candidate_profile, dict):
            bound_capabilities |= _validate_profile(
                inspected["id"],
                "candidate",
                candidate_profile,
                expected_tools=list(inspected["tools"]),
                capability_ids=set(capability_ids),
            )
        if isinstance(judge_profile, dict):
            bound_capabilities |= _validate_profile(
                inspected["id"],
                "judge",
                judge_profile,
                expected_tools=[],
                capability_ids=set(capability_ids),
            )
        if (candidate_profile is not None or judge_profile is not None) and bound_capabilities != set(capability_ids):
            raise ImportFlowV4Error(f"{inspected['id']}: accepted profiles must exactly bind declared capabilities")
        if isinstance(candidate_profile, dict) and isinstance(judge_profile, dict) and candidate_profile["ref"] == judge_profile["ref"]:
            raise ImportFlowV4Error(f"{inspected['id']}: candidate and judge profiles must be separate")

    acceptance = {
        "schema": ACCEPTANCE_SCHEMA,
        "inspection_digest": inspection["inspection_digest"],
        "source_semantic_digest": inspection["source_semantic_digest"],
        "acknowledgements": copy.deepcopy(acknowledgements),
        "workflow_contracts": workflow_contracts,
        "workflow_contract_resources": workflow_resources,
        "milestones": copy.deepcopy(requested),
    }
    return _with_digest(acceptance, "acceptance_digest")


def _validate_acceptance(inspection: Mapping[str, Any], acceptance: Mapping[str, Any]) -> None:
    _assert_digest(inspection, "inspection_digest", label="inspection")
    _assert_digest(acceptance, "acceptance_digest", label="acceptance")
    if acceptance.get("schema") != ACCEPTANCE_SCHEMA:
        raise ImportFlowV4Error(f"acceptance schema must be {ACCEPTANCE_SCHEMA}")
    if acceptance.get("inspection_digest") != inspection.get("inspection_digest"):
        raise ImportFlowV4Error("acceptance is bound to a different inspection")
    if acceptance.get("source_semantic_digest") != inspection.get("source_semantic_digest"):
        raise ImportFlowV4Error("acceptance source semantic digest drifted")


def _source_is_frozen(
    inspection: Mapping[str, Any],
    acceptance: Mapping[str, Any],
    harness: Path,
    project: Path,
) -> None:
    source = inspection["source"]
    flow = _bounded_file(harness, str(source["flow_path"]), label="accepted flow")
    if "sha256:" + sha256_file(flow) != source["flow_sha256"]:
        raise ImportFlowV4Error("accepted flow bytes changed after inspection")
    for row in inspection["resources"]:
        root = harness if row["source_scope"] == "harness" else project
        path = _bounded_file(root, row["source_path"], label=f"accepted resource {row['stage_path']}")
        if "sha256:" + sha256_file(path) != row["sha256"] or path.stat().st_size != row["byte_count"]:
            raise ImportFlowV4Error(f"accepted resource changed after inspection: {row['stage_path']}")
    for row in acceptance["workflow_contract_resources"]:
        path = _bounded_file(harness, row["source_path"], label=f"accepted workflow contract {row['stage_path']}")
        if "sha256:" + sha256_file(path) != row["sha256"] or path.stat().st_size != row["byte_count"]:
            raise ImportFlowV4Error(f"accepted workflow contract changed: {row['stage_path']}")
    expected_tools, blockers = _tool_package_manifest(
        project, [row["tool_id"] for row in inspection["tool_packages"]]
    )
    if blockers or expected_tools != inspection["tool_packages"]:
        raise ImportFlowV4Error("accepted tool-package bytes changed after inspection")


def _write_stage(
    stage: Path,
    inspection: Mapping[str, Any],
    acceptance: Mapping[str, Any],
    harness: Path,
    project: Path,
) -> None:
    for row in inspection["resources"]:
        root = harness if row["source_scope"] == "harness" else project
        source_path = _bounded_file(root, row["source_path"], label=f"resource {row['stage_path']}")
        destination = stage.joinpath(*PurePosixPath(row["stage_path"]).parts)
        destination.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(source_path, destination)
    for row in acceptance["workflow_contract_resources"]:
        source_path = _bounded_file(harness, row["source_path"], label=f"workflow contract {row['stage_path']}")
        destination = stage.joinpath(*PurePosixPath(row["stage_path"]).parts)
        destination.parent.mkdir(parents=True, exist_ok=True)
        if destination.exists() and "sha256:" + sha256_file(destination) != row["sha256"]:
            raise ImportFlowV4Error(f"workflow contract staging collision: {row['stage_path']}")
        shutil.copy2(source_path, destination)

    skill = inspection["skill"]
    frontmatter = yaml.safe_dump(
        {"name": skill["name"], "description": skill["description"], "metadata": {"version": "3.1"}},
        sort_keys=False,
        allow_unicode=True,
    )
    (stage / "SKILL.md").write_text(
        f"---\n{frontmatter}---\n\n# {inspection['interface']['display_name']}\n\n"
        "Invoke this skill through agents/openai.yaml; milestone instructions live only in "
        "references/<milestone>.md.\n",
        encoding="utf-8",
        newline="\n",
    )
    agents_dir = stage / "agents"
    agents_dir.mkdir(parents=True, exist_ok=True)
    canvas: dict[str, Any] = {
        "schema": "m8m_skill_canvas_v1",
        "flow_id": inspection["flow_id"],
        "version": inspection["version"],
        "context_policy": "isolated",
        "entry": inspection["entry"],
        "milestones": [row["id"] for row in inspection["milestones"]],
        "graph": copy.deepcopy(inspection["graph"]),
        "terminal_states": {"success": list(inspection["terminals"]), "blocked": "BLOCKED"},
        "observer": {
            "title": inspection["interface"]["display_name"],
            "summary": inspection["interface"]["short_description"],
        },
        "workflow_contracts": copy.deepcopy(acceptance["workflow_contracts"]),
    }
    for field in ("max_run_seconds", "artifact_root", "implementation_dependencies"):
        value = inspection["semantic_projection"].get(field)
        if value not in (None, []):
            canvas[field] = copy.deepcopy(value)
    openai = {"interface": copy.deepcopy(inspection["interface"]), "canvas": canvas}
    (agents_dir / "openai.yaml").write_text(
        yaml.safe_dump(openai, sort_keys=False, allow_unicode=True, width=1000),
        encoding="utf-8",
        newline="\n",
    )
    accepted_by_id = {row["id"]: row for row in acceptance["milestones"]}
    for inspected in inspection["milestones"]:
        milestone_id = inspected["id"]
        agent = copy.deepcopy(inspected["agent"])
        declared = accepted_by_id[milestone_id]
        for flowstep in agent.get("flowsteps") or []:
            ref = str(flowstep.get("tool") or "")
            if _VERSIONED_REF.fullmatch(ref):
                flowstep["tool"] = ref.rsplit("@", 1)[0]
        agent["execution"] = copy.deepcopy(declared["execution"])
        if declared.get("capabilities"):
            agent["capabilities"] = copy.deepcopy(declared["capabilities"])
        (agents_dir / f"{milestone_id}.yaml").write_text(
            yaml.safe_dump(agent, sort_keys=False, allow_unicode=True, width=1000),
            encoding="utf-8",
            newline="\n",
        )


def _compiled_projection(stage: Path, compiled: dict[str, Any]) -> dict[str, Any]:
    with tempfile.TemporaryDirectory(prefix="m8m-import-verify-") as temporary:
        root = Path(temporary)
        path = root / "flow.yaml"
        path.write_text(yaml.safe_dump(compiled, sort_keys=False, allow_unicode=True), encoding="utf-8")
        projection = semantic_projection(root, path)
        # Profiles and capabilities are operator-supplied Builder 3 closure
        # facts that a legacy v4 source cannot contain. Preserve their bytes in
        # the staged source, but omit them from the legacy-semantic equivalence
        # projection so the comparison remains about workflow behavior.
        for milestone in projection.get("milestones") or []:
            execution = milestone.get("execution")
            if isinstance(execution, dict):
                candidate = execution.get("candidate_executor")
                if isinstance(candidate, dict):
                    candidate.pop("profile", None)
                judge = execution.get("judge")
                if isinstance(judge, dict):
                    judge.pop("profile", None)
            milestone.pop("capabilities", None)
        return projection


def _accepted_projection(
    inspection: Mapping[str, Any], acceptance: Mapping[str, Any]
) -> dict[str, Any]:
    """Project operator-bound execution identity onto a legacy inspection.

    A pre-3.1 flow may name a local FlowStep package without declaring the
    exact executable ref or the closed ``execution`` object.  Acceptance is
    the one boundary where the operator supplies those missing facts.  Stage
    equivalence therefore compares the compiled flow with that accepted
    projection, while an already-versioned source ref remains byte-exact and
    is never rewritten.
    """

    projection = copy.deepcopy(inspection["semantic_projection"])
    accepted_by_id = {
        str(row["id"]): row
        for row in acceptance["milestones"]
        if isinstance(row, Mapping)
    }
    for milestone in projection.get("milestones") or []:
        if not isinstance(milestone, dict):
            continue
        declared = accepted_by_id[str(milestone["id"])]
        source_execution = milestone.get("execution")
        if source_execution is None:
            execution = copy.deepcopy(declared["execution"])
            candidate = execution.get("candidate_executor")
            if isinstance(candidate, dict):
                candidate.pop("profile", None)
            judge = execution.get("judge")
            if isinstance(judge, dict):
                judge.pop("profile", None)
            milestone["execution"] = execution
            refs_by_slot = {
                str(binding["tool"]): str(binding["ref"])
                for binding in execution.get("tool_bindings") or []
                if isinstance(binding, Mapping)
            }
            for flowstep in milestone.get("flowsteps") or []:
                if not isinstance(flowstep, dict):
                    continue
                source_ref = str(flowstep.get("tool") or "")
                if not _VERSIONED_REF.fullmatch(source_ref):
                    flowstep["tool"] = refs_by_slot[str(flowstep["id"])]
        elif isinstance(source_execution, dict):
            # Profiles are operator closure facts and are excluded from the
            # compiled equivalence projection on both sides.
            candidate = source_execution.get("candidate_executor")
            if isinstance(candidate, dict):
                candidate.pop("profile", None)
            judge = source_execution.get("judge")
            if isinstance(judge, dict):
                judge.pop("profile", None)
    return projection


def _first_projection_mismatch(
    expected: Any,
    actual: Any,
    path: str = "$",
) -> str:
    if type(expected) is not type(actual):
        return f"{path}: type {type(expected).__name__} != {type(actual).__name__}"
    if isinstance(expected, dict):
        if set(expected) != set(actual):
            missing = sorted(set(expected) - set(actual))
            extra = sorted(set(actual) - set(expected))
            return f"{path}: keys differ; missing={missing}, extra={extra}"
        for key in expected:
            if expected[key] != actual[key]:
                return _first_projection_mismatch(expected[key], actual[key], f"{path}.{key}")
    elif isinstance(expected, list):
        if len(expected) != len(actual):
            return f"{path}: list length {len(expected)} != {len(actual)}"
        for index, (left, right) in enumerate(zip(expected, actual)):
            if left != right:
                return _first_projection_mismatch(left, right, f"{path}[{index}]")
    elif expected != actual:
        return f"{path}: {expected!r} != {actual!r}"
    return f"{path}: values differ"


def _resource_manifest(
    inspection: Mapping[str, Any], acceptance: Mapping[str, Any]
) -> dict[str, Any]:
    copied: dict[str, dict[str, Any]] = {}
    for row in [*inspection["resources"], *acceptance["workflow_contract_resources"]]:
        public = {
            "stage_path": row["stage_path"],
            "byte_count": row["byte_count"],
            "sha256": row["sha256"],
        }
        prior = copied.get(row["stage_path"])
        if prior is not None and prior != public:
            raise ImportFlowV4Error(f"resource manifest collision: {row['stage_path']}")
        copied[row["stage_path"]] = public
    manifest = {
        "schema": RESOURCE_MANIFEST_SCHEMA,
        "copied_resources": [copied[key] for key in sorted(copied)],
        "external_tool_packages": copy.deepcopy(inspection["tool_packages"]),
        "local_readiness_evidence_only": True,
    }
    return _with_digest(manifest, "resource_manifest_digest")


def _verify_core(
    inspection: Mapping[str, Any], acceptance: Mapping[str, Any], stage_dir: str | Path
) -> dict[str, Any]:
    """Compile staged source and return a base-independent equivalence proof."""

    _validate_acceptance(inspection, acceptance)
    stage = Path(stage_dir).resolve(strict=True)
    if not stage.is_dir():
        raise ImportFlowV4Error("stage path is not a directory")
    if (stage / "flow.yaml").exists():
        raise ImportFlowV4Error("stage must not contain an authored flow.yaml")
    for row in inspection["resources"]:
        path = _bounded_file(stage, row["stage_path"], label=f"staged resource {row['stage_path']}")
        if "sha256:" + sha256_file(path) != row["sha256"] or path.stat().st_size != row["byte_count"]:
            raise ImportFlowV4Error(f"staged resource differs from accepted bytes: {row['stage_path']}")
    for row in acceptance["workflow_contract_resources"]:
        path = _bounded_file(stage, row["stage_path"], label=f"staged workflow contract {row['stage_path']}")
        if "sha256:" + sha256_file(path) != row["sha256"] or path.stat().st_size != row["byte_count"]:
            raise ImportFlowV4Error(f"staged workflow contract differs from accepted bytes: {row['stage_path']}")
    try:
        source = load_skill_source(stage)
        compiled = compile_skill_source(stage)
        graph = _native_graph(source["milestones"])
    except SkillSourceError as exc:
        raise ImportFlowV4Error(f"staged skill source is invalid: {exc}") from exc
    expected_graph = {row["from"]: list(row["to"]) for row in inspection["graph"]}
    if graph != expected_graph:
        raise ImportFlowV4Error("staged native graph differs from the accepted graph")
    expected_projection = _accepted_projection(inspection, acceptance)
    projection = _compiled_projection(stage, compiled)
    digest = _digest(projection)
    if projection != expected_projection or digest != _digest(expected_projection):
        mismatch = _first_projection_mismatch(expected_projection, projection)
        raise ImportFlowV4Error(
            "staged compiled flow is not canonically equivalent to the accepted v4 flow; "
            + mismatch
        )
    return {
        "schema": PROOF_SCHEMA,
        "status": "PASS",
        "inspection_digest": inspection["inspection_digest"],
        "acceptance_digest": acceptance["acceptance_digest"],
        "source_semantic_digest": inspection["source_semantic_digest"],
        "staged_semantic_digest": digest,
        "compiled_flow_digest": _digest(compiled),
        "resource_manifest_digest": _resource_manifest(inspection, acceptance)["resource_manifest_digest"],
        "installed": False,
        "deployed": False,
    }


def _write_handoff(
    stage: Path, inspection: Mapping[str, Any], acceptance: Mapping[str, Any]
) -> None:
    handoff = stage / "planning" / "import-flow-v4"
    handoff.mkdir(parents=True, exist_ok=True)
    (handoff / "inspection.json").write_bytes(canonical_json_bytes(inspection))
    (handoff / "acceptance.json").write_bytes(canonical_json_bytes(acceptance))
    (handoff / "resource-manifest.json").write_bytes(
        canonical_json_bytes(_resource_manifest(inspection, acceptance))
    )
    (handoff / "equivalence-proof.json").write_bytes(
        canonical_json_bytes(_verify_core(inspection, acceptance, stage))
    )


def verify_staged_import(
    inspection: Mapping[str, Any], acceptance: Mapping[str, Any], stage_dir: str | Path
) -> dict[str, Any]:
    """Recheck source equivalence and the frozen, auditable staged handoff."""

    stage = Path(stage_dir).resolve(strict=True)
    proof = _verify_core(inspection, acceptance, stage)
    handoff = stage / "planning" / "import-flow-v4"
    expected = {
        "inspection.json": inspection,
        "acceptance.json": acceptance,
        "resource-manifest.json": _resource_manifest(inspection, acceptance),
        "equivalence-proof.json": proof,
    }
    for name, value in expected.items():
        path = handoff / name
        if not path.is_file() or path.read_bytes() != canonical_json_bytes(value):
            raise ImportFlowV4Error(f"staged handoff artifact is missing or drifted: {name}")
    return {
        "schema": VERIFY_SCHEMA,
        "status": "PASS",
        "stage_dir": str(stage),
        "handoff_dir": str(handoff),
        **{key: value for key, value in proof.items() if key not in {"schema", "status"}},
    }


def stage_import(
    inspection: Mapping[str, Any],
    acceptance: Mapping[str, Any],
    stage_dir: str | Path,
    *,
    source_root: str | Path,
    project_root: str | Path | None = None,
) -> dict[str, Any]:
    """Materialize an accepted source tree at a new staging path only."""

    _validate_acceptance(inspection, acceptance)
    harness, project = _roots(source_root, project_root)
    _source_is_frozen(inspection, acceptance, harness, project)
    destination = Path(stage_dir).resolve()
    if destination.exists():
        raise ImportFlowV4Error("stage destination already exists; refusing to merge or overwrite")
    destination.parent.mkdir(parents=True, exist_ok=True)
    temporary = Path(tempfile.mkdtemp(prefix=f".{destination.name}.import-", dir=destination.parent))
    try:
        _write_stage(temporary, inspection, acceptance, harness, project)
        _verify_core(inspection, acceptance, temporary)
        _write_handoff(temporary, inspection, acceptance)
        os.replace(temporary, destination)
    except Exception:
        shutil.rmtree(temporary, ignore_errors=True)
        raise
    return verify_staged_import(inspection, acceptance, destination)


def _read_json(path: Path) -> dict[str, Any]:
    try:
        value = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
        raise ImportFlowV4Error(f"cannot read JSON {path}: {exc}") from exc
    if not isinstance(value, dict):
        raise ImportFlowV4Error(f"JSON root must be an object: {path}")
    return value


def _emit(value: dict[str, Any], output: Path | None) -> None:
    payload = json.dumps(value, indent=2, ensure_ascii=False, sort_keys=True) + "\n"
    if output is None:
        print(payload, end="")
        return
    if output.exists():
        raise ImportFlowV4Error(f"output already exists: {output}")
    output.parent.mkdir(parents=True, exist_ok=True)
    output.write_text(payload, encoding="utf-8", newline="\n")


def main() -> int:
    parser = argparse.ArgumentParser(description="Explicit staging-only Builder 2 v4 importer")
    sub = parser.add_subparsers(dest="command", required=True)
    inspect_parser = sub.add_parser("inspect")
    inspect_parser.add_argument("--source-root", type=Path, required=True)
    inspect_parser.add_argument("--flow", type=Path)
    inspect_parser.add_argument("--skill-name")
    inspect_parser.add_argument("--display-name")
    inspect_parser.add_argument("--description")
    inspect_parser.add_argument("--default-prompt")
    inspect_parser.add_argument("--out", type=Path)
    accept_parser = sub.add_parser("accept")
    accept_parser.add_argument("--inspection", type=Path, required=True)
    accept_parser.add_argument("--request", type=Path, required=True)
    accept_parser.add_argument("--source-root", type=Path, required=True)
    accept_parser.add_argument("--project-root", type=Path)
    accept_parser.add_argument("--out", type=Path)
    stage_parser = sub.add_parser("stage")
    stage_parser.add_argument("--inspection", type=Path, required=True)
    stage_parser.add_argument("--acceptance", type=Path, required=True)
    stage_parser.add_argument("--stage-dir", type=Path, required=True)
    stage_parser.add_argument("--source-root", type=Path, required=True)
    stage_parser.add_argument("--project-root", type=Path)
    stage_parser.add_argument("--out", type=Path)
    verify_parser = sub.add_parser("verify")
    verify_parser.add_argument("--inspection", type=Path, required=True)
    verify_parser.add_argument("--acceptance", type=Path, required=True)
    verify_parser.add_argument("--stage-dir", type=Path, required=True)
    verify_parser.add_argument("--out", type=Path)
    args = parser.parse_args()
    try:
        if args.command == "inspect":
            result = inspect_flow_v4(
                args.source_root,
                args.flow,
                skill_name=args.skill_name,
                display_name=args.display_name,
                description=args.description,
                default_prompt=args.default_prompt,
            )
        elif args.command == "accept":
            result = accept_import(
                _read_json(args.inspection),
                _read_json(args.request),
                source_root=args.source_root,
                project_root=args.project_root,
            )
        elif args.command == "stage":
            result = stage_import(
                _read_json(args.inspection),
                _read_json(args.acceptance),
                args.stage_dir,
                source_root=args.source_root,
                project_root=args.project_root,
            )
        else:
            result = verify_staged_import(
                _read_json(args.inspection), _read_json(args.acceptance), args.stage_dir
            )
        _emit(result, args.out)
    except (ImportFlowV4Error, FlowError, SkillSourceError, OSError) as exc:
        parser.error(str(exc))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


__all__ = [
    "ACCEPTANCE_REQUEST_SCHEMA",
    "ACCEPTANCE_SCHEMA",
    "INSPECTION_SCHEMA",
    "ImportFlowV4Error",
    "VERIFY_SCHEMA",
    "accept_import",
    "inspect_flow_v4",
    "semantic_projection",
    "stage_import",
    "verify_staged_import",
]
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall