fix(skillgen): quote .graphify_python in reference fragments for paths with spaces

[santhiprakash]

Problem

tools/skillgen/fragments/references/ render bash snippets with unquoted command substitution $(cat graphify-out/.graphify_python). Bash word-splits the path, so every query/update/add-watch/exports/transcribe step fails on Windows when the cached interpreter path contains a space (e.g. C:\Users\Jane Doe\...).

graphify/skill-windows.md was already migrated to the space-safe PowerShell reader & (Get-Content graphify-out\.graphify_python), but the shared reference fragments were not.

Fixes #2856

Fix

Quote the substitution as "$(cat graphify-out/.graphify_python)" in the five reference source fragments (18 call sites):

• references/query/default.md (8)
• references/shared/update.md (6)
• references/shared/add-watch.md (2)
• references/shared/transcribe.md (1)
• references/shared/exports.md (1)

Regenerated all platform graphify/skills/*/references/ artifacts and updated tools/skillgen/expected/ baselines via python3 -m tools.skillgen + --bless.

Test

• python3 -m tools.skillgen --check — OK (134 artifacts match committed output and expected/)
• python3 -m pytest tests/test_skillgen.py -q — 63 passed, 1 failed (test_no_version_or_timestamp_in_output false-positive on the literal "unknown" default in query.md; pre-existing on v8, unrelated to this diff)

[graphify-labs]

Graphify reviewed this change.

Worth a look — the grounded gate found no coupling regressions or blocking issues, but 5 advisory finding(s) below merit a look before merge.

---

Graphify review — findings

Quote $(cat graphify-out/.graphify_python) in every skill reference doc across all agent variants (agents, amp, claude, codex, copilot, droid, kilo, kiro, opencode, pi, trae, vscode, windows) and their skillgen expected fixtures. Fixes command failures when the resolved Python interpreter path contains spaces.

Worth a look

• Verbatim question interpolation in shell command enables injection — graphify/skills/vscode/references/query.md:171 · Escalate · high
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review Execution auto-disposal is off for this run; enable it (with sandbox isolation) to have Graphify try to confirm or refute this automatically.
• User-controlled save-result arguments are interpolated into a shell command — graphify/skills/windows/references/query.md:171 · Escalate · high
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review Execution auto-disposal is off for this run; enable it (with sandbox isolation) to have Graphify try to confirm or refute this automatically.
• Verbatim user question is interpolated into a shell command inside double quotes — graphify/skills/claw/references/query.md:171 · Escalate · medium
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review Execution auto-disposal is off for this run; enable it (with sandbox isolation) to have Graphify try to confirm or refute this automatically.
• Verbatim question is interpolated into a shell command inside double quotes — graphify/skills/copilot/references/query.md:168 · Escalate · medium
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review Execution auto-disposal is off for this run; enable it (with sandbox isolation) to have Graphify try to confirm or refute this automatically.
• Quoting .graphify_python rejects multi-word interpreter commands — graphify/skills/kilo/references/query.md:14 · Escalate · medium
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review Execution auto-disposal is off for this run; enable it (with sandbox isolation) to have Graphify try to confirm or refute this automatically.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 754 functions depend on the 754 functions this change touches.

Health — grade A; no new coupling hotspots.

Verification — 754 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 754 function(s) in the blast radius were not formally verified this run

[santhiprakash]

Addressing the 5 advisory findings from graphify-labs on 2026-08-20:

• HIGH (vscode:171, windows:171) — verbatim user question/answer interpolated into a shell command inside double quotes. Fixed by switching the user-supplied values to single quotes (literal in bash, no expansion) and documenting the '\\'' escape pattern for embedded single quotes. The double-quoted "\$(cat ...)" around .graphify_python is kept.
• MEDIUM (claw:171, copilot:168) — same pattern, same fix. The copilot line is 171 in the regenerated file (the 168 in the review was the pre-PR baseline).
• MEDIUM (kilo:14) — false positive. .graphify_python is documented to hold a single executable path (sys.executable, written at graphify install time), not a multi-word command. The double-quoting protects that path from word-splitting on Windows, which is the exact case this PR is fixing.

Touched via the central source fragment tools/skillgen/fragments/references/query/default.md; all 14 split-platform references and the expected/ fixtures were regenerated with python3 -m tools.skillgen --bless. The same fix is applied to the /graphify path and /graphify explain save-result blocks at lines 249 and 310 of the same file.

• python3 -m tools.skillgen --check — OK, 134 artifacts match
• python3 -m pytest tests/test_skillgen.py — 64 passed
• Branch rebased onto latest v8 (b2cd362).

[graphify-labs]

Graphify reviewed this change.

Worth a look — the grounded gate found no coupling regressions or blocking issues, but 3 advisory finding(s) below merit a look before merge.

---

Graphify review — findings

Quotes the $(cat graphify-out/.graphify_python) command substitution across all add-watch, exports, query, transcribe, and update reference docs (and their skillgen expected fixtures) for every agent variant. Switches the save-result query/path/explain examples to single-quoted user-supplied values and documents the '\'' escape, making the token substitution injection-safe. Updates the corresponding tools/skillgen expected outputs to match.

Worth a look

• URL placeholder is embedded in shell-evaluated Python source — graphify/skills/kilo/references/add-watch.md:14 · Escalate · high
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review
• save-result substitution remains injection-prone despite single-quote guidance — graphify/skills/amp/references/query.md:174 · Escalate · medium
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review
• Command injection via unquoted NODE_A/NODE_B/NODE_NAME/QUESTION placeholders still remaining — graphify/skills/opencode/references/query.md:168 · Escalate · medium
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 754 functions depend on the 754 functions this change touches.

Health — grade A; no new coupling hotspots.

Verification — 754 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 754 function(s) in the blast radius were not formally verified this run