mr8lu/apple-design-hig

Review signals: 1 connection review.

Reviewed as expected for a test run: attempted writes that failed, so nothing was written.

Repository processes attempted these non-loopback connections; proxies can hide the final hostname. 13 distinct locations. 22 attributed processes.

OSV scanned supported lockfiles; unpinned dependencies and unsupported formats are outside this check.

A short run cannot establish that code is safe.

Connections show IP addresses; proxies can hide the final hostname.

Tracing covers dispatched commands and their children, not the whole OS; guest root can interfere with tracing.

Full safety evidence →

• CLI topic prints an official HIG topic as Markdown: Real input produced the expected result: # Color

  Source: Fetches and prints the complete Markdown article for any topic slug

  Input: color

  Expected: Markdown article titled Color

  Command: uv run apple-design-hig topic color

  Observed: # Color - **Category**: Apple Human Interface Guidelines - **Slug**: `color` - **Official URL**: https://developer.apple.com/design/human-interface-guidelines/color **Summary**: Judicious use of color can enhance communication, evoke your brand, provide visual continuity, communicate status and feedback, and help people understand information. [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.] The system defines colors that l

• CLI search finds HIG topics by keyword: Real input produced the expected result: Navigation and search

  Source: Searches all 172+ Apple HIG topics by keyword and optional section filter

  Input: navigation

  Expected: Navigation and search topic listed

  Command: uv run apple-design-hig search navigation

  Observed: Navigation and search** (`navigation-and-search`) [Components] -> https://developer.apple.com/design/human-interface-guidelines/navigation-and-search

• MCP hig_search performs case-insensitive matching: Real input produced the expected result: navigation-and-search

  Source: Executes case-insensitive substring matching across topic titles, slugs, and section names.

  Input: {"tool": "hig_search", "arguments": {"query": "navigation"}}

  Expected: navigation-and-search slug returned

  Command: uv --directory <guest-path> run --with 'mcp<2' apple-design-hig-mcp tools/call {"tool": "hig_search", "arguments": {"query": "navigation"}}

  Observed: 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

Examples

• Unit test suite runs via uv: command completed successfully

  Source: README.md Development & Verification: uv run pytest -v

  Input: none

  Expected: all 5 tests pass

  Command: uv run pytest -v

  Observed: /coldpass/workspace configfile: pyproject.toml plugins: anyio-4.15.1 collecting ... collected 5 items tests/test_hig.py::test_normalize_slug PASSED [ 20%] tests/test_hig.py::test_flatten_index_nodes PASSED [ 40%] tests/test_hig.py::test_render_topic_markdown_replaces_em_dash_and_renders_blocks PASSED [ 60%] tests/test_hig.py::test_install_skill_directories PASSED [ 80%] tests/test_hig.py::test_no_personal_footprint_in_repo_files PASSED [100%] ============================== 5 passed in 0.12s ===============================

• Sync writes catalog and pillar files to an output directory: command completed successfully

  Source: README.md CLI Reference: sync [--output-dir <path>]

  Input: --output-dir .coldpass/sync-example (fresh path)

  Expected: Synced 172 topics into the directory

  Command: uv run apple-design-hig sync --output-dir .coldpass/sync-example

  Observed: Success: Synced 172 topics (6 pillars) into .coldpass/sync-example

Local or hosted: local

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

cd <guest-path> && pwd && ls -la && id -u && python3 --version && (git -C . rev-parse HEAD 2>&1 | head -1); ls <guest-path>; echo "CDP=$CDP_URL"
cd <guest-path> && cat README.md 2>/dev/null | head -150; ls -R | head -80
cd <guest-path> && sed -n 150,400p README.md
cd <guest-path> && cat pyproject.toml; ls .coldpass; which uv; uv --version 2>&1; curl -s -m 10 -o /dev/null -w "%{http_code}\n" $CDP_URL/json/version
cd <guest-path> && uv sync 2>&1 | tail -20; echo "rc=$?"
cd <guest-path> && uv run apple-design-hig search "navigation" 2>&1 | head -40
cd <guest-path> && uv run apple-design-hig topic color 2>&1 | head -30; echo "rc=${PIPESTATUS[0]}"
cd <guest-path> && uv run pytest -v 2>&1 | tail -25
cd <guest-path> && mkdir -p .coldpass && test ! -e .coldpass/sync-out && uv run apple-design-hig sync --output-dir .coldpass/sync-out 2>&1 | tail -20; echo "rc=${PIPESTATUS[0]}"; ls -la .coldpass/sync-out 2>&1; wc -c .coldpass/sync-out/* 2>/dev/null
cd <guest-path> && rm -rf .coldpass/sync-out && cat > .coldpass/probe.json <<'EOF'
{"kind":"mcp","argv":["uv","--directory","<guest-path>","run","apple-design-hig-mcp"],"cwd":"<guest-path>","tool":"hig_search","arguments":{"query":"navigation"},"expected_text":"navigation-and-search"}
EOF
python3 -I -c 'import json,sys; json.load(open(sys.argv[1])); print("ok")' .coldpass/probe.json && ls -la .coldpass
cd <guest-path> && cat > .coldpass/claims.json <<'EOF'
[
{"kind":"claim","claim":"CLI topic prints an official HIG topic as Markdown","source":"Fetches and prints the complete Markdown article for any topic slug","input":"color","expected":"Markdown article titled Color","probe_kind":"cli","argv":["uv","run","apple-design-hig","topic","color"],"expected_text":"# Color","cwd":"<guest-path>"},
{"kind":"claim","claim":"CLI search finds HIG topics by keyword","source":"Searches all 172+ Apple HIG topics by keyword and optional section filter","input":"navigation","expected":"Navigation and search topic listed","probe_kind":"cli","argv":["uv","run","apple-design-hig","search","navigation"],"expected_text":"Navigation and search","cwd":"<guest-path>"},
{"kind":"claim","claim":"MCP hig_search performs case-insensitive matching","source":"Executes case-insensitive substring matching across topic titles, slugs, and section names.","input":"navigation","expected":"navigation-and-search slug returned","probe_kind":"mcp","argv":["uv","--directory","<guest-path>","run","apple-design-hig-mcp"],"tool":"hig_search","arguments":{"query":"navigation"},"expected_text":"navigation-and-search","cwd":"<guest-path>"}
]
EOF
<env-var>=<guest-path> python3 -I -c 'import json;print(len(json.load(open("<guest-path>"))))'; ls <guest-path>; ls /inputs 2>&1 | head
cd <guest-path> && cat > .coldpass/examples.json <<'EOF'
[
{"kind":"example","claim":"Unit test suite runs via uv","source":"README.md Development & Verification: uv run pytest -v","input":"none","expected":"all 5 tests pass","argv":["uv","run","pytest","-v"],"cwd":"<guest-path>","expected_text":"5 passed"},
{"kind":"example","claim":"Sync writes catalog and pillar files to an output directory","source":"README.md CLI Reference: sync [--output-dir <path>]","input":"--output-dir .coldpass/sync-example (fresh path)","expected":"Synced 172 topics into the directory","argv":["uv","run","apple-design-hig","sync","--output-dir",".coldpass/sync-example"],"cwd":"<guest-path>","expected_text":"Success: Synced 172 topics (6 pillars)"}
]
EOF
cat > .coldpass/cycles.json <<'EOF'
{"detected":false,"reason":"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.","checks":[]}
EOF
python3 -I -c 'import json;[json.load(open("<guest-path>"+f)) for f in ["examples.json","cycles.json"]];print("ok")'
cd <guest-path> && <env-var>=<guest-path> timeout 600 python3 -I <guest-path> --validate --replay 2>&1 | tail -80; echo "rc=${PIPESTATUS[0]}"
cd <guest-path> && grep -n -A2 '^name = "mcp"' uv.lock | head; echo ---; uv lock --check 2>&1 | tail -3; echo "rc=$?"; echo ---; cat .gitignore
cd <guest-path> && printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' '{"jsonrpc":"2.0","method":"notifications/initialized"}' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"hig_search","arguments":{"query":"navigation"}}}' | timeout 120 uv run --with "mcp<2" apple-design-hig-mcp 2><guest-path> | cut -c1-600; echo "rc=${PIPESTATUS[1]}"; tail -5 <guest-path>
cd <guest-path> && python3 -I - <<'EOF'
import json
W="<guest-path>"
argv=["uv","--directory",W,"run","--with","mcp<2","apple-design-hig-mcp"]
p=json.load(open(W+"/.coldpass/probe.json")); p["argv"]=argv
json.dump(p,open(W+"/.coldpass/probe.json","w"))
c=json.load(open(W+"/.coldpass/claims.json"))
for x in c:
    if x["probe_kind"]=="mcp": x["argv"]=argv
json.dump(c,open(W+"/.coldpass/claims.json","w"),indent=1)
print("updated")
EOF
cat .coldpass/probe.json
cd <guest-path> && <env-var>=<guest-path> timeout 900 python3 -I <guest-path> --validate --replay > <guest-path> 2>&1; echo "rc=$?"; python3 -I -c 'import json,sys; d=json.load(open("<guest-path>")) if False else None' ; head -c 3000 <guest-path>
cd <guest-path> && mkdir -p .coldpass && python3 -I - <<'EOF'
import json
W="<guest-path>"
r={
 "outcome":"blocked",
 "fault_owner":"repo",
 "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.",
 "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 <guest-path> run apple-design-hig-mcp  (documented stdio server) -> FAILED at startup (see stuck_step)",
  "uv --directory <guest-path> run --with \"mcp<2\" apple-design-hig-mcp  -> hig_search(query=navigation) returned navigation-and-search"
 ],
 "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 <guest-path> 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."
 ],
 "stuck_step":"uv --directory <guest-path> run apple-design-hig-mcp (README 'Model Context Protocol (MCP) Server' / 'Local Clone Configuration via uv')",
 "main_blocker":"Dependency mismatch: the committed uv.lock resolves mcp 2.3.0, but the server code uses the mcp 1.x FastMCP API (pyproject allows mcp>=1.6.0 with no upper bound).",
 "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.",
 "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)."
}
json.dump(r,open(W+"/.coldpass/report.json","w"),indent=1)
print("written")
EOF
python3 -I -c 'import json;json.load(open("<guest-path>"));print("valid json")'; ls -la <guest-path>; ls <guest-path> | head -20
cd <guest-path> && <env-var>=<guest-path> timeout 900 python3 -I <guest-path> --validate --replay > <guest-path> 2>&1; echo "rc=$?"; python3 -I -c 'import json;d=json.loads(open("<guest-path>").read().split("\n",1)[0] if False else "{}")' ; head -c 400 <guest-path>; echo; grep -o '"valid": [a-z]*' <guest-path>; grep -o 'Success[^"]*' <guest-path> | head -3; pgrep -fa apple-design-hig-mcp || echo "no leftover mcp servers"