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

tests/test_audit_harness.py

View on GitHub
from __future__ import annotations

import json
import tempfile
import unittest
from pathlib import Path

from support import EXAMPLE, optional_product_repo, optional_sample_skill

from audit_harness import (
    AUDIT_SCHEMA,
    _is_action_step,
    audit_harness,
    audit_skill,
    main,
    render_audit_markdown,
)
from flowstep_runtime import validate_against_schema


AUDIT_CONTRACT = Path(__file__).resolve().parents[1] / "contracts" / "flowstep_skill_audit_v1.schema.json"
REQUIRED_HEADINGS = (
    "## Audited skill",
    "## Goal",
    "## Tool vs intelligence",
    "## Current tools",
    "## Proposed milestone split",
    "## Toolbox plan",
    "## Teaching contracts",
    "## Tools to standardize to Python",
    "## Schema control",
    "## Milestone context and output schemas",
)


class AuditHarnessTests(unittest.TestCase):
    def test_external_state_suffixes_remain_milestones(self) -> None:
        for step_id in ("base_written", "case_io_complete"):
            self.assertFalse(
                _is_action_step(
                    {
                        "id": step_id,
                        "intelligence": "none",
                        "handler": f"milestones/{step_id}/assemble.py",
                    }
                )
            )

    def test_article_repo_flow_is_milestone_toolbox(self) -> None:
        product = optional_product_repo()
        if product is None:
            self.skipTest("set M8M_PRODUCT_REPO to audit a live product flow")
        repo = product / "flowsteps" / "flows" / "article_infographic_zh_hant_v2"
        if not repo.is_dir():
            self.skipTest("sample article flow not in M8M_PRODUCT_REPO")
        report = audit_harness(repo)
        self.assertEqual(report["verdict"], "MILESTONE_TOOLBOX")
        self.assertEqual(report["flow_schema"], "flowstep_flow_v3")
        self.assertEqual(report["p0_count"], 0)

    def test_v4_fixture_is_milestone_toolbox(self) -> None:
        report = audit_harness(EXAMPLE)
        self.assertEqual(report["verdict"], "MILESTONE_TOOLBOX")
        self.assertEqual(report["flow_schema"], "flowstep_flow_v4")

    def test_invalid_cache_policy_is_a_p0_finding(self) -> None:
        with tempfile.TemporaryDirectory() as temp:
            root = Path(temp) / "repo" / "flowsteps" / "flows" / "bad_cache_v1"
            root.mkdir(parents=True)
            (root / "flow.yaml").write_text(
                "\n".join(
                    [
                        "schema: flowstep_flow_v4",
                        "flow_id: bad_cache_v1",
                        "version: 1",
                        "artifact_root: artifacts",
                        "milestones:",
                        "  - id: result_ready",
                        "    success: A result is ready.",
                        "    output_contract: result_v1",
                        "    output_schema: output.schema.json",
                        "    outputs:",
                        "      - {id: result, name: Result, kind: json, cardinality: one, required: true}",
                        "    handler: assemble.py",
                        "    input_schema: input.schema.json",
                        "    inputs: {request: user.request}",
                        "    intelligence: none",
                        "    cache:",
                        "      reuse: candidate",
                        "      side_effects: none",
                    ]
                )
                + "\n",
                encoding="utf-8",
            )
            report = audit_harness(root)
            self.assertEqual(report["verdict"], "NEEDS_UPGRADE")
            self.assertTrue(
                any(
                    item["severity"] == "P0" and "ttl_seconds" in item["note"]
                    for item in report["findings"]
                )
            )
            text = (root / "flow.yaml").read_text(encoding="utf-8")
            text = text.replace(
                "    cache:\n",
                "    tools: [upload_asset]\n    cache:\n",
            ).replace(
                "      side_effects: none\n",
                "      ttl_seconds: 60\n      side_effects: none\n",
            )
            (root / "flow.yaml").write_text(text, encoding="utf-8")
            report = audit_harness(root)
            self.assertTrue(
                any(
                    item["severity"] == "P0" and "external side effects" in item["note"]
                    for item in report["findings"]
                )
            )

    def test_external_milestone_requires_phase_journal(self) -> None:
        with tempfile.TemporaryDirectory() as temp:
            root = Path(temp) / "repo" / "flowsteps" / "flows" / "publish_v1"
            root.mkdir(parents=True)
            (root / "flow.yaml").write_text(
                "\n".join(
                    [
                        "schema: flowstep_flow_v4",
                        "flow_id: publish_v1",
                        "version: 1",
                        "milestones:",
                        "  - id: published_live",
                        "    success: Live readback passes.",
                        "    output_contract: published_v1",
                        "    output_schema: output.schema.json",
                        "    outputs:",
                        "      - {id: result, name: Published, kind: json, cardinality: one, required: true}",
                        "    handler: assemble.py",
                        "    inputs: {request: user.request}",
                        "    tools: [publish_case]",
                        "    intelligence: none",
                        "    on_tool_fail: retryable",
                    ]
                )
                + "\n",
                encoding="utf-8",
            )
            report = audit_harness(root)
            self.assertTrue(
                any(
                    item["severity"] == "P0" and "phase_journal" in item["note"]
                    for item in report["findings"]
                )
            )

    def test_v4_blank_expectation_fields_are_p0_findings(self) -> None:
        with tempfile.TemporaryDirectory() as temp:
            root = Path(temp) / "repo" / "flowsteps" / "flows" / "blank_v1"
            root.mkdir(parents=True)
            (root / "flow.yaml").write_text(
                "\n".join(
                    [
                        "schema: flowstep_flow_v4",
                        "flow_id: blank_v1",
                        "version: 1",
                        "milestones:",
                        "  - id: result_ready",
                        "    success: '   '",
                        "    output_contract: '   '",
                        "    output_schema: '   '",
                        "    outputs:",
                        "      - {id: '   ', name: '   ', kind: json, cardinality: one, required: true}",
                        "    handler: assemble.py",
                        "    intelligence: none",
                    ]
                )
                + "\n",
                encoding="utf-8",
            )
            report = audit_harness(root)
            notes = {item["note"] for item in report["findings"] if item["severity"] == "P0"}
            self.assertIn("missing milestone success goal", notes)
            self.assertIn("missing non-blank output_contract", notes)
            self.assertIn("missing non-blank output_schema", notes)
            self.assertIn("outputs[0].id must be non-blank", notes)
            self.assertIn("outputs[0].name must be non-blank", notes)

    def test_v4_output_schema_must_close_root_and_outputs_object(self) -> None:
        with tempfile.TemporaryDirectory() as temp:
            root = Path(temp) / "repo" / "flowsteps" / "flows" / "open_schema_v1"
            root.mkdir(parents=True)
            (root / "flow.yaml").write_text(
                "\n".join(
                    [
                        "schema: flowstep_flow_v4",
                        "flow_id: open_schema_v1",
                        "version: 1",
                        "milestones:",
                        "  - id: result_ready",
                        "    success: A result is ready.",
                        "    output_contract: result_v1",
                        "    output_schema: output.schema.json",
                        "    outputs:",
                        "      - {id: result, name: Result, kind: json, cardinality: one, required: true}",
                        "    handler: assemble.py",
                        "    intelligence: none",
                    ]
                )
                + "\n",
                encoding="utf-8",
            )
            (root / "output.schema.json").write_text(
                json.dumps(
                    {
                        "type": "object",
                        "properties": {
                            "outputs": {
                                "type": "object",
                                "properties": {"result": {"type": "object"}},
                                "required": ["result"],
                            }
                        },
                        "required": ["outputs"],
                    }
                ),
                encoding="utf-8",
            )
            report = audit_harness(root)
            notes = {item["note"] for item in report["findings"] if item["severity"] == "P0"}
            self.assertIn(
                "output_schema root must be an object with additionalProperties: false",
                notes,
            )
            self.assertIn(
                "output_schema outputs object must set additionalProperties: false",
                notes,
            )

    def test_v4_audit_enforces_exact_judge_binding_shape(self) -> None:
        with tempfile.TemporaryDirectory() as temp:
            root = Path(temp) / "repo" / "flowsteps" / "flows" / "judge_shape_v1"
            root.mkdir(parents=True)
            common = [
                "schema: flowstep_flow_v4",
                "flow_id: judge_shape_v1",
                "version: 1",
                "milestones:",
                "  - id: result_ready",
                "    success: A result is ready.",
                "    output_contract: result_v1",
                "    output_schema: output.schema.json",
                "    outputs:",
                "      - {id: result, name: Result, kind: json, cardinality: one, required: true}",
                "    handler: assemble.py",
                "    intelligence: none",
            ]
            (root / "flow.yaml").write_text(
                "\n".join(common + ["    loop: judge"]) + "\n",
                encoding="utf-8",
            )
            report = audit_harness(root)
            self.assertTrue(
                any(
                    item["severity"] == "P0"
                    and "loop=judge requires closed" in item["note"]
                    for item in report["findings"]
                )
            )
            (root / "flow.yaml").write_text(
                "\n".join(
                    common
                    + [
                        "    loop: none",
                        "    worker: result_judge@1.0.0",
                    ]
                )
                + "\n",
                encoding="utf-8",
            )
            report = audit_harness(root)
            self.assertTrue(
                any(
                    item["severity"] == "P0"
                    and "loop=none forbids" in item["note"]
                    for item in report["findings"]
                )
            )

class AuditWorkerTests(unittest.TestCase):
    def test_external_writer_script_outside_linked_flow_is_p0(self) -> None:
        with tempfile.TemporaryDirectory() as temp:
            repo = Path(temp) / "repo"
            flow = repo / "flowsteps" / "flows" / "sample_v1"
            skill = repo / "skill"
            (skill / "scripts").mkdir(parents=True)
            flow.mkdir(parents=True)
            (skill / "SKILL.md").write_text(
                "---\nname: sample-skill\ndescription: Sample publisher.\n---\n\n"
                f"Live flow: `{flow}`\n",
                encoding="utf-8",
            )
            writer = skill / "scripts" / "publish_case.py"
            writer.write_text(
                "def run(client):\n    return client.post('/commit', {})\n",
                encoding="utf-8",
            )
            (flow / "flow.yaml").write_text(
                "\n".join(
                    [
                        "schema: flowstep_flow_v4",
                        "flow_id: sample_v1",
                        "version: 1",
                        "milestones:",
                        "  - id: source_ready",
                        "    success: Source is ready.",
                        "    output_contract: source_v1",
                        "    output_schema: output.schema.json",
                        "    outputs:",
                        "      - {id: result, name: Source, kind: json, cardinality: one, required: true}",
                        "    handler: assemble.py",
                        "    inputs: {request: user.request}",
                        "    tools: [hash_bind]",
                        "    intelligence: none",
                        "    on_tool_fail: BLOCKED",
                    ]
                )
                + "\n",
                encoding="utf-8",
            )
            report = audit_skill(skill)
            self.assertTrue(
                any(
                    item["severity"] == "P0" and "outside the linked M8M flow" in item["note"]
                    for item in report["grade"]["findings"]
                )
            )
            writer.write_text(
                'M8M_EXTERNAL_SIDE_EFFECT_OWNER = "other-writer-skill"\n'
                "def run(client):\n    return client.post('/commit', {})\n",
                encoding="utf-8",
            )
            report = audit_skill(skill)
            self.assertFalse(
                any("outside the linked M8M flow" in item["note"] for item in report["grade"]["findings"])
            )

    def test_text_pipeline_audit_writes_required_sections(self) -> None:
        report = audit_skill(EXAMPLE)
        self.assertEqual(report["schema"], AUDIT_SCHEMA)
        self.assertEqual(report["audited_skill"]["name"], "text-pipeline")
        self.assertIn("Separate", report["goal"])
        ids = [item["id"] for item in report["proposed_milestones"]]
        self.assertIn("source_ready", ids)
        self.assertTrue(any(item["id"].endswith("_frozen") or item["id"] == "label" for item in report["proposed_milestones"]))
        source = next(item for item in report["proposed_milestones"] if item["id"] == "source_ready")
        self.assertIn("ingest", source["tools"])
        self.assertIn("segment", source["tools"])
        self.assertEqual(source["flowsteps"][0]["tool"], "ingest")
        labeled = next(item for item in report["proposed_milestones"] if "label" in item["id"])
        self.assertEqual(labeled["intelligence"], "completion")
        self.assertIn("tool_vs_intelligence", report)
        self.assertEqual(report["tool_vs_intelligence"]["schema"], "tool_vs_intelligence_table_v1")
        self.assertTrue(report["tool_vs_intelligence"]["rows"])
        source_result = source["output_schema"]["properties"]["outputs"]["properties"]["result"]
        label_result = labeled["output_schema"]["properties"]["outputs"]["properties"]["result"]
        self.assertIn("sentences", source_result["properties"])
        self.assertIn("label", label_result["properties"])
        self.assertIn("source_ready", labeled["inputs"])
        self.assertIn("flowsteps", labeled)
        markdown = render_audit_markdown(report)
        for heading in REQUIRED_HEADINGS:
            self.assertIn(heading, markdown)
        self.assertNotIn("input_schema", source)
        self.assertNotIn("input_schema", labeled)
        self.assertIn("**Output schema**", markdown)
        validate_against_schema(report, AUDIT_CONTRACT)

    def test_action_named_steps_become_python_tools(self) -> None:
        with tempfile.TemporaryDirectory() as temp:
            root = Path(temp) / "toy-skill"
            (root / "flows").mkdir(parents=True)
            (root / "SKILL.md").write_text(
                "---\nname: toy-skill\ndescription: Crop then plan.\n---\n\n# toy\n",
                encoding="utf-8",
            )
            (root / "flows" / "toy_v1.yaml").write_text(
                "\n".join(
                    [
                        "schema: flowstep_flow_v2",
                        "flow_id: toy_v1",
                        "version: 1",
                        "steps:",
                        "  - id: crop_4x5",
                        "    class: tool",
                        "    handler: steps/crop_4x5/tool.py",
                        "    model: none",
                        "    inputs:",
                        "      request: user.request",
                        "    output_contract: crop_v1",
                        "    input_schema: steps/crop_4x5/input.schema.json",
                        "    output_schema: steps/crop_4x5/output.schema.json",
                        "  - id: plan_frozen",
                        "    class: intelligence",
                        "    handler: steps/plan_frozen/tool.py",
                        "    model: completion",
                        "    inputs:",
                        "      crop_4x5: crop_4x5.crop_v1",
                        "    output_contract: plan_v1",
                        "    input_schema: steps/plan_frozen/input.schema.json",
                        "    output_schema: steps/plan_frozen/output.schema.json",
                    ]
                )
                + "\n",
                encoding="utf-8",
            )
            report = audit_skill(root)
            ids = [item["id"] for item in report["proposed_milestones"]]
            self.assertEqual(ids, ["milestone01", "milestone02"])
            self.assertNotIn("crop_4x5", ids)
            source = report["proposed_milestones"][0]
            self.assertIn("crop_4x5", source["tools"])
            tool_ids = [item["tool_id"] for item in report["python_standardization"]]
            self.assertIn("crop_4x5", tool_ids)
            self.assertIn("flowsteps/tools/crop_4x5/", report["python_standardization"][0]["destination"])

    def test_no_flow_skill_proposes_from_scripts_and_contracts(self) -> None:
        with tempfile.TemporaryDirectory() as temp:
            root = Path(temp) / "bare-skill"
            (root / "scripts").mkdir(parents=True)
            (root / "contracts").mkdir()
            (root / "agents").mkdir()
            (root / "SKILL.md").write_text(
                "---\nname: bare-skill\ndescription: Fetch a record and package it.\n---\n\n# bare\n",
                encoding="utf-8",
            )
            (root / "scripts" / "fetch_record.py").write_text("def run(input_data, **kwargs):\n    return input_data\n", encoding="utf-8")
            (root / "scripts" / "package_bundle.py").write_text("def run(input_data, **kwargs):\n    return input_data\n", encoding="utf-8")
            (root / "scripts" / "run.py").write_text("print('driver')\n", encoding="utf-8")
            (root / "contracts" / "article_source_v2.schema.json").write_text(
                json.dumps(
                    {
                        "type": "object",
                        "required": ["source_path", "source_sha256"],
                        "properties": {
                            "source_path": {"type": "string"},
                            "source_sha256": {"type": "string"},
                        },
                    }
                ),
                encoding="utf-8",
            )
            (root / "agents" / "release_judge_worker.yaml").write_text(
                "agent_id: release_judge_worker\nrole: persistent_workflow_worker\n",
                encoding="utf-8",
            )
            report = audit_skill(root)
            self.assertEqual(report["verdict"], "NO_FLOW")
            ids = [item["id"] for item in report["proposed_milestones"]]
            self.assertEqual(ids, ["milestone01", "milestone02"])
            current_ids = {item["id"] for item in report["current_tools"]}
            self.assertIn("fetch_record", current_ids)
            self.assertIn("package_bundle", current_ids)
            self.assertIn("run", current_ids)
            source = report["proposed_milestones"][0]
            self.assertIn("source_path", source["output_schema"]["properties"])
            tool_ids = [item["tool_id"] for item in report["python_standardization"]]
            self.assertIn("fetch_record", tool_ids)
            self.assertNotIn("run", tool_ids)

    def test_main_writes_planning_markdown(self) -> None:
        with tempfile.TemporaryDirectory() as temp:
            report_path = Path(temp) / "flowstep-audit.md"
            code = main(["--target", str(EXAMPLE), "--write-report", str(report_path)])
            self.assertEqual(code, 0)
            text = report_path.read_text(encoding="utf-8")
            for heading in REQUIRED_HEADINGS:
                self.assertIn(heading, text)
            self.assertIn("text-pipeline", text)

    def test_case_io_skill_follows_linked_repo_flow(self) -> None:
        skill = optional_sample_skill()
        product = optional_product_repo()
        if skill is None or product is None:
            self.skipTest("set M8M_SAMPLE_SKILL and M8M_PRODUCT_REPO to audit a linked product skill")
        repo = product / "flowsteps" / "flows" / "nisan_case_io_v1"
        if not repo.is_dir():
            self.skipTest("sample case-io flow not in M8M_PRODUCT_REPO")
        report = audit_skill(skill)
        ids = [item["id"] for item in report["proposed_milestones"]]
        for expected in (
            "request_ready",
            "package_admitted",
            "restyle_with_floor_base_written",
            "restyle_with_floor_floor_written",
            "restyle_with_floor_dna_written",
            "restyle_with_floor_facts_written",
            "restyle_with_floor_final_verified",
            "restyle_without_floor_final_verified",
            "case_io_complete",
        ):
            self.assertIn(expected, ids)
        self.assertIn("existing-case-patch-worker", {item["id"] for item in report["current_tools"]})

    def test_article_skill_keeps_six_milestones(self) -> None:
        article = optional_sample_skill()
        if article is None:
            self.skipTest("set M8M_SAMPLE_SKILL to audit a live article skill")
        report = audit_skill(article)
        ids = [item["id"] for item in report["proposed_milestones"]]
        for expected in (
            "source_ready",
            "plan_frozen",
            "prompts_frozen",
            "assets_bound",
            "cards_rendered",
            "release_packaged",
        ):
            self.assertIn(expected, ids)
        rendered = next(item for item in report["proposed_milestones"] if item["id"] == "cards_rendered")
        self.assertIn("render_html_shell", rendered["tools"])
        self.assertGreaterEqual(len(rendered["inputs"]), 2)
        markdown = render_audit_markdown(report)
        self.assertIn("## Goal", markdown)
        self.assertIn("render_html_shell", markdown)


if __name__ == "__main__":
    unittest.main()
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