{ "checker": { "claims": [ { "claim": "CLI topic prints an official HIG topic as Markdown", "command": "uv run apple-design-hig topic color", "evidence": "# Color\n\n- **Category**: Apple Human Interface Guidelines\n- **Slug**: `color`\n- **Official URL**: https://developer.apple.com/design/human-interface-guidelines/color\n\n**Summary**: Judicious use of color can enhance communication, evoke your brand, provide visual continuity, communicate status and feedback, and help people understand information.\n\n[Image: A sketch of a paint palette, suggesting the use of color. The image is overlaid with rectangular and circular grid lines and is tinted yellow to subtly reflect the yellow in the original six-color Apple logo.]\n\nThe system defines colors that l", "expected": "Markdown article titled Color", "input": "color", "kind": "claim", "outcome": "Real input produced the expected result: # Color", "returncode": 0, "source": "Fetches and prints the complete Markdown article for any topic slug", "source_checked": true, "source_file": "README.md", "verdict": "yes" }, { "claim": "CLI search finds HIG topics by keyword", "command": "uv run apple-design-hig search navigation", "evidence": "Navigation and search** (`navigation-and-search`) [Components] -> https://developer.apple.com/design/human-interface-guidelines/navigation-and-search\n", "expected": "Navigation and search topic listed", "input": "navigation", "kind": "claim", "outcome": "Real input produced the expected result: Navigation and search", "returncode": 0, "source": "Searches all 172+ Apple HIG topics by keyword and optional section filter", "source_checked": true, "source_file": "README.md", "verdict": "yes" }, { "claim": "MCP hig_search performs case-insensitive matching", "command": "uv --directory run --with 'mcp<2' apple-design-hig-mcp tools/call {\"tool\": \"hig_search\", \"arguments\": {\"query\": \"navigation\"}}", "evidence": "navigation-and-search\\\",\\n \\\"path\\\": \\\"/design/human-interface-guidelines/navigation-and-search\\\",\\n \\\"url\\\": \\\"https://developer.apple.com/design/human-interface-guidelines/navigation-and-search\\\",\\n \\\"section\\\": \\\"Components\\\",\\n \\\"type\\\": \\\"collection\\\"\\n }\\n ]\\n}\"}], \"structuredContent\": {\"query\": \"navigation\", \"section\": null, \"count\": 1, \"matches\": [{\"title\": \"Navigation and search\", \"slug\": \"navigation-and-search\", \"path\": \"/design/human-interface-guidelines/navigation-and-search\", \"url\": \"https://developer.apple.com/design/human-interface-guidelines/navigation-a", "expected": "navigation-and-search slug returned", "input": "{\"tool\": \"hig_search\", \"arguments\": {\"query\": \"navigation\"}}", "kind": "claim", "outcome": "Real input produced the expected result: navigation-and-search", "source": "Executes case-insensitive substring matching across topic titles, slugs, and section names.", "source_checked": true, "source_file": "README.md", "verdict": "yes" } ], "cycle_checks": [ { "claim": "Scheduled or looping main behavior", "command": "", "evidence": "Inspected README.md and src/apple_design_hig/cli.py entry points (topic, search, sync, install-skill, mcp). The only scheduling is .github/workflows/sync-hig.yml (GitHub Actions cron every Monday 09:00 UTC), which is CI, not a product cycle. The product has no daemon, loop, --once or webhook mode.", "expected": "identify the product trigger", "input": "source inspection", "kind": "cycle", "outcome": "Inspected README.md and src/apple_design_hig/cli.py entry points (topic, search, sync, install-skill, mcp). The only scheduling is .github/workflows/sync-hig.yml (GitHub Actions cron every Monday 09:00 UTC), which is CI, not a product cycle. The product has no daemon, loop, --once or webhook mode.", "source": "repository entry points", "verdict": "yes" } ], "details": { "argv": [ "uv", "--directory", "", "run", "--with", "mcp<2", "apple-design-hig-mcp" ], "kind": "mcp", "scope": "product operation", "serverInfo": { "name": "apple-design-hig", "version": "1.30.0" }, "tool_result": { "content": [ { "text": "{\n \"query\": \"navigation\",\n \"section\": null,\n \"count\": 1,\n \"matches\": [\n {\n \"title\": \"Navigation and search\",\n \"slug\": \"navigation-and-search\",\n \"path\": \"/design/human-interface-guidelines/navigation-and-search\",\n \"url\": \"https://developer.apple.com/design/human-interface-guidelines/navigation-and-search\",\n \"section\": \"Components\",\n \"type\": \"collection\"\n }\n ]\n}", "type": "text" } ], "isError": false, "structuredContent": { "count": 1, "matches": [ { "path": "/design/human-interface-guidelines/navigation-and-search", "section": "Components", "slug": "navigation-and-search", "title": "Navigation and search", "type": "collection", "url": "https://developer.apple.com/design/human-interface-guidelines/navigation-and-search" } ], "query": "navigation", "section": null } }, "tool_result_checked": true, "tool_schema_bytes": 1469, "tools": [ "hig_list_sections", "hig_search", "hig_get_topic", "hig_sync" ], "working": true }, "evidence_strength": "readme_checked", "example_checks": [ { "claim": "Unit test suite runs via uv", "command": "uv run pytest -v", "deferred": false, "evidence": "/coldpass/workspace\nconfigfile: pyproject.toml\nplugins: anyio-4.15.1\ncollecting ... collected 5 items\n\ntests/test_hig.py::test_normalize_slug PASSED [ 20%]\ntests/test_hig.py::test_flatten_index_nodes PASSED [ 40%]\ntests/test_hig.py::test_render_topic_markdown_replaces_em_dash_and_renders_blocks PASSED [ 60%]\ntests/test_hig.py::test_install_skill_directories PASSED [ 80%]\ntests/test_hig.py::test_no_personal_footprint_in_repo_files PASSED [100%]\n\n============================== 5 passed in 0.12s ===============================", "expected": "all 5 tests pass", "input": "none", "kind": "example", "outcome": "command completed successfully", "returncode": 0, "source": "README.md Development & Verification: uv run pytest -v", "verdict": "yes" }, { "claim": "Sync writes catalog and pillar files to an output directory", "command": "uv run apple-design-hig sync --output-dir .coldpass/sync-example", "deferred": false, "evidence": "Success: Synced 172 topics (6 pillars) into .coldpass/sync-example", "expected": "Synced 172 topics into the directory", "input": "--output-dir .coldpass/sync-example (fresh path)", "kind": "example", "outcome": "command completed successfully", "returncode": 0, "source": "README.md CLI Reference: sync [--output-dir ]", "verdict": "yes" } ], "status": "PASS" }, "deviations": [ "The documented MCP entrypoint fails as shipped: uv sync resolved mcp 2.3.0 (uv.lock pins 2.3.0) and src/apple_design_hig/mcp_server.py imports mcp.server.fastmcp, which mcp 2.x removed. Traceback: ModuleNotFoundError: No module named 'mcp.server.fastmcp'.", "Workaround used for the MCP probe and MCP claim only: added --with \"mcp<2\" to uv run. Source and uv.lock were not edited.", "Sync was run to fresh output directories (.coldpass/sync-out, .coldpass/sync-example) instead of the bundled skills/apple-design-hig/references, so repo files were not overwritten.", "The preflight path /inputs/coldpass-preflight.py named in the task does not exist; the checker at was used instead.", "No browser or CDP endpoint was used; the product needs none. CDP_URL returned HTTP 200 on the /json/version check but was not needed." ], "fault_owner": "repo", "main_blocker": null, "operation": "Read the HIG topics and search them from the CLI (apple-design-hig topic/search/sync) and run the MCP server (apple-design-hig-mcp) with a hig_search tool call", "operation_scope": "Python 3.12.3 with uv 0.13.5 on Linux; live access to developer.apple.com DocC endpoints. CLI parts and tests work; the MCP server works only with a mcp<2 pin at launch.", "outcome": "working", "plain_failure": "The MCP server that the README tells you to start does not start from a fresh install: it crashes on launch because the locked version of its MCP library is too new for the code. The command-line tools and tests work. The server works once the MCP library is pinned to version 1.x when launching.", "steps": [ "uv sync", "uv run apple-design-hig search \"navigation\" -> Navigation and search (navigation-and-search)", "uv run apple-design-hig topic color -> Markdown article beginning '# Color'", "uv run pytest -v -> 5 passed", "uv run apple-design-hig sync --output-dir .coldpass/sync-out -> Synced 172 topics (6 pillars)", "uv --directory run apple-design-hig-mcp (documented stdio server) -> FAILED at startup (see stuck_step)", "uv --directory run --with \"mcp<2\" apple-design-hig-mcp -> hig_search(query=navigation) returned navigation-and-search" ], "stuck_step": "uv --directory run apple-design-hig-mcp (README 'Model Context Protocol (MCP) Server' / 'Local Clone Configuration via uv')", "suggested_fix": "Pin mcp to <2 in pyproject.toml (e.g. mcp>=1.6.0,<2) and regenerate uv.lock, or port mcp_server.py to the mcp 2.x API (MCPServer)." }