feat(setup): first-run welcome guide for the utilities family (#1663)

[Kaap10]

Summary

• Adds a first-run welcome guide for the utilities skill family (plugins/magpie-setup/skills/setup/setup_preflight/guides/utilities.md), following the template established in feat(setup): first-run welcome guides, general and for the security skills #1653.
• Introduces the typical utilities flow (list-skills → write-skill → optimize-skill → report-framework-issue → skill-reconciler), explicitly highlighting that meta-skills require no initial project configuration to run.
• Adds preflight-floor eval case-10-utilities-first-run, updates case-9-first-magpie-run, links the guide in docs/utilities/README.md, and expands test coverage in test_welcome.py.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other: Framework setup preflight welcome guide

Test plan

• prek run --all-files passes (markdownlint, mixed-line-ending, doctoc, add-license-headers)
• For Python packages touched: uv run pytest / ruff check / mypy passes
• For Groovy bridges touched: command-line invocation tested end-to-end
• For skill changes: eval suite passes for the affected skill
  (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
• For skill behaviour changes: a new or updated eval fixture is included in this PR
  (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
• Other: python tools/dev/render-preflight-fixtures.py --check passes with zero drift; pytest tools/setup-preflight/tests/test_welcome.py passes (49 tests).

RFC-AI-0004 compliance

• HITL — any new mutation is gated on explicit user confirmation
• Sandbox — no new unrestricted host access; network reach declared in the adapter
• Vendor neutrality — placeholders (<PROJECT>, <tracker>, <upstream>, <security-list>) used in all skill / tool prose (the check-placeholders prek hook is the mechanical gate)
• Conversational + correctable — agentic-override path documented if behaviour is adopter-tunable
• Write-access discipline — no autonomous outbound messages; drafts only, sent on confirmation
• Privacy LLM — private content does not reach a non-approved LLM; redactor invoked where needed

Linked issues

Closes #1663 (child of #1654)

Notes for reviewers (optional)

• The guide is 49 lines of Markdown, well under the 60-line floor constraint.
• render-preflight-fixtures.py now supports optional reconciled state in state.json to allow testing family-specific welcome guides where the general guide was previously seen.
• Windows: scan_families() in welcome.py falls back to reading a skills/ mirror entry as a text file holding its target path. That is how git checks out a symlink when core.symlinks=false, so mirrored skills resolve the same way on a Windows checkout as on Linux CI. test_a_mirror_entry_checked_out_as_a_text_file_still_resolves covers it, including an entry whose target is missing.
• An earlier revision also forced UTF-8 on stdout in welcome.main() for Windows consoles. That change is unrelated to the guide, so it was dropped from this PR.
• Maintainer edits (@potiuk): corrected the list-skills and skill-reconciler descriptions and examples in the guide, cleared the CodeQL empty-except alert, added the fallback test, and rebased onto main.

[Kaap10]

Implemented first-run welcome guide for the utilities family (#1663) and eval fixtures.
Ready for review!

[potiuk]

Thanks — the structure, wiring and fixtures follow #1653 closely. Two of the five skills are described inaccurately in the guide, which matters for a first-run page that teaches users what to ask for; details inline. Please also clear the CodeQL alert (suggestion inline) and regenerate case-10-utilities-first-run/report.md after the guide text changes.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. After you've
addressed the points above and pushed an update, an Apache Magpie
maintainer — a real person — will take the next look
at the PR. The findings cite the project's review criteria;
if you think one of them is mis-applied, please reply on the
PR and a maintainer will weigh in.

More on how Apache Magpie handles maintainer review:
Contributing guide.

[potiuk]

Thanks for this. It follows the #1653 pattern closely and the fixture and test changes are solid. The inline comments are mostly about two places where the guide describes list-skills and skill-reconciler differently from what those skills do. Because the guide's example phrases route users to skills, "reconcile my local skills against the snapshot" would send them to the wrong one. Two smaller points: the new text-symlink fallback in welcome.py needs a test, and the stdout reconfigure change needs a reason or its own PR.

I've rebased the branch onto current main, so please pull before pushing again.

Guide accuracy (plugins/magpie-setup/skills/setup/setup_preflight/guides/utilities.md:10)

list-skills lists only the skills installed for this repository (its description: "Print a human-readable index of every skill installed for this repository…"). It doesn't read the marketplace.

1. 📋 **List** the skills installed here, by family — *"list skills"*

Guide accuracy (plugins/magpie-setup/skills/setup/setup_preflight/guides/utilities.md:14)

skill-reconciler doesn't reconcile a repo against its snapshot. Its description: "Compare two near-duplicate skills — typically an ASF variant and a non-ASF or multi-project variant — and classify every difference as ALLOWED, DRIFT, or SAFETY-BASELINE… read-only". Checking local configuration against the installed framework is /magpie-setup:setup reconcile.

5. 🔁 **Reconcile** two near-duplicate skills and classify their differences — *"reconcile skill-A and skill-B"*

Guide accuracy (plugins/magpie-setup/skills/setup/setup_preflight/guides/utilities.md:35)

Same issue as line 14: the guide's example phrases route users to skills, and "reconcile my local skills against the snapshot" would send them to skill-reconciler, which compares two skills with each other. An example that matches the skill is something like "reconcile the ASF and generic variants of the triage skill".

Smaller observations

• See inline comments on plugins/magpie-setup/skills/setup/setup_preflight/guides/utilities.md:43, plugins/magpie-setup/skills/setup/setup_preflight/welcome.py:438, plugins/magpie-setup/skills/setup/setup_preflight/welcome.py:460.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. After you've
addressed the points above and pushed an update, an Apache Magpie
maintainer — a real person — will take the next look
at the PR. The findings cite the project's review criteria;
if you think one of them is mis-applied, please reply on the
PR and a maintainer will weigh in.

More on how Apache Magpie handles maintainer review:
Contributing guide.

[potiuk]

Thanks @Kaap10. To get this landed, I pushed 05b044d onto your branch with the points from my review applied:

• The guide now describes list-skills as listing the skills installed here, grouped by family, with no marketplace claim. The override example became "group the skill list by capability instead of family".
• skill-reconciler is now described as comparing two near-duplicate skills and classifying where they drifted. The "Just ask" example is now "have these two skill copies drifted?".
• The empty except OSError: pass that CodeQL flagged is now contextlib.suppress(OSError), with a comment explaining the text-file mirror fallback.
• I re-rendered case-10-utilities-first-run/report.md (render-preflight-fixtures.py --check is clean) and ran test_welcome.py (48 passed).

The Windows fallback and the stdout.reconfigure change still have no test. A small follow-up PR covering them would be welcome. Approving and merging.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.

[Kaap10]

Thanks @potiuk for polishing the skill descriptions and adding the plain-file mirror fallback test!