build(skills): single source of truth + generation + pre-PR rescue guard + determinism propagation

[AndreJorgeLopes]

TL;DR

1. 🎯 One source of truth for skills: repo-root skills/<name>/SKILL.md. The plugin copies + flows are now GENERATED, so they cannot drift.
2. 🐛 Fixes the real drift: /devflow:finish-feature (slash command) was running a stale 128-line command while the Skill ran the current 166-line one. Behavior depended on invocation path.
3. 🛟 Pre-PR rescue guard: make skills-guard folds a skill edited in the wrong (generated) tree back into the source, instead of silently overwriting it.
4. 🔁 Propagates the determinism lib conversion (resolve-repo + finish-feature) uniformly into the loaded plugin copies.

The problem

devflow skills lived in three hand-maintained, drifted copies with no enforced sync:

• skills/<name>/SKILL.md (repo root) — where edits actually land (impr(finish-feature): source-grounded review gate + deferral-closure gate #49, feat(eval): skill-determinism audits + assertion configs + determinism guide #53, the determinism audits, and the lib conversion all went here). Also home to registry.json and the eval/ configs.
• devflow-plugin/skills/<name>/SKILL.md — loaded by the plugin as auto-invokable Skills.
• devflow-plugin/commands/<name>.md — what the LOADED /devflow:* slash command runs.
• devflow-plugin/flows/** — a generated 4th copy (make flows).

Nothing synced repo-root skills/ to devflow-plugin/. So when #49 added the source-grounded review gate + deferral-closure gate to skills/finish-feature, devflow-plugin/commands/finish-feature.md never got it. Result: the slash command ran a stale version missing both gates.

Measured blast radius: 25 of 28 command bodies were already identical to their SKILL.md modulo frontmatter. Only finish-feature, render-diagram, verify-first had drifted (bugs, not intent).

The decision (source of truth)

Repo-root skills/<name>/SKILL.md is the single authored source. The user's stated criteria ("what the plugin loads", "what flows generate from") both point at devflow-plugin, but generation satisfies them either way, so they do not discriminate. The real discriminator is dev-vs-distribution separation plus where the surrounding infra already lives (registry.json, eval/audits, determinism.promptfooconfig.yaml), which favors keeping the source at the repo root and keeping those dev files OUT of the shipped plugin.

skills/<name>/SKILL.md          SOURCE (authored) + registry.json + eval configs (dev only)
  |  scripts/build-skills.sh  (make skills-sync)
  |-> devflow-plugin/skills/<name>/     byte copy, minus dev-only determinism.promptfooconfig.yaml
  |-> devflow-plugin/commands/<name>.md frontmatter -> command form ([VERSION] + description), body verbatim
  \-> make flows -> devflow-plugin/flows/**

Nothing was deleted. The two plugin trees stay present (the plugin loads them) but are now generated.

Changes

Area	What changed and why
scripts/build-skills.sh	New generator. Renders devflow-plugin/{skills,commands} from repo-root skills/. Command frontmatter becomes [VERSION] + the SKILL.md description (version from plugin.json); body verbatim. Excludes the dev-only determinism.promptfooconfig.yaml. Prunes copies whose source was removed. Output dir overridable via DEVFLOW_PLUGIN_OUT (used by the guard for an exact temp compare).
scripts/skills-guard.sh	Pre-PR RESCUE guard. Renders source to a throwaway tree, finds skills whose real copy differs, and uses the git delta since the base ref to classify: source-changed (stale, run skills-sync) vs generated-copy hand-edited (MISPLACED, fold back into source) vs both (ambiguous, ask). Folding reverses the frontmatter transform for a command edit (name preserved from source) or byte-copies a skill-dir edit, then regenerates. --check mode for CI/hooks.
Makefile	skills-sync (regenerate skills + flows), skills-check (fail on drift, wired into make test next to flows-check), skills-guard.
skills/create-pr/SKILL.md	New Step 0: when inside the devflow repo (scripts/skills-guard.sh exists), run make skills-guard before opening a PR. No-op in any other repo.
CLAUDE.md	Replaced the stale "devflow-plugin/commands/ is canonical" note with the source-of-truth + generation + guard model.
generated copies	Regenerated the 3 drifted commands + the diagrams flow, then propagated the determinism conversion into the 4 plugin copies.
determinism conversion	Cherry-picked feat/skill-lib-conversion (resolve-repo + finish-feature source the determinism lib with the abstain->AI contract; scoring stays model-driven, only its output is pinned), then regenerated so the loaded plugin copies actually carry it.

Commits

1. build(skills): generate plugin copies from repo-root skills/ (one source of truth) — generator, guard, Makefile targets, drift fix, CLAUDE.md.
2. feat(create-pr): run the skills source-of-truth guard before opening a PR.
3. feat(skills): convert resolve-repo + finish-feature to source the determinism lib (cherry-picked).
4. build(skills): propagate determinism conversion to generated plugin copies.

Verification

• make test (smoke + skills-check + flows-check): PASS.
• make test-unit (bats, after git submodule update --init tests/lib/*): 75/75 PASS.
• make skills-guard: OK, plugin copies in sync with source.
• Guard exercised end to end: OK on a consistent tree (no bootstrap misfire), detects a hand-edit on a generated command via --check, folds it back into the source, round-trips clean.
• Confirmed dev-only determinism.promptfooconfig.yaml stays at the repo root and is excluded from the shipped plugin.

Reviewer note

The test-unit bats submodules (tests/lib/bats-support, tests/lib/bats-assert) were uninitialized in the worktree (pre-existing, unrelated). git submodule update --init tests/lib/bats-support tests/lib/bats-assert before running.

[Copilot]

Pull request overview

This PR makes repo-root skills/<name>/SKILL.md the single authored source for skills and generates the plugin-loaded copies (devflow-plugin/{skills,commands}), eliminating drift (notably /devflow:finish-feature) and propagating the determinism-lib changes uniformly.

Changes:

• Add scripts/build-skills.sh to generate devflow-plugin/{skills,commands} from repo-root skills/, and wire skills-sync / skills-check into make.
• Add scripts/skills-guard.sh and a make skills-guard target to rescue edits mistakenly made in generated plugin trees by folding them back into the source skill.
• Add/propagate determinism-lib guidance + Axis-B promptfoo assertion configs for resolve-repo and finish-feature, and regenerate the affected plugin copies/flows.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
skills/resolve-repo/SKILL.md	Adds determinism-lib offload guidance and tightens deterministic output/ordering constraints.
skills/resolve-repo/determinism.promptfooconfig.yaml	Adds promptfoo assertions to pin resolve-repo output shape.
skills/finish-feature/SKILL.md	Adds determinism-lib offload guidance and makes several gates/output formats deterministic/pinned.
skills/finish-feature/determinism.promptfooconfig.yaml	Adds promptfoo assertions to pin finish-feature output shape.
skills/create-pr/SKILL.md	Adds a pre-PR skills-guard step when operating inside the devflow repo.
scripts/skills-guard.sh	New guard to detect and fold misplaced edits from generated plugin trees back into skills/.
scripts/build-skills.sh	New generator to render plugin skills/ + commands/ from repo-root skills/.
Makefile	Adds skills-sync, skills-check, and skills-guard; wires skills-check into make test.
devflow-plugin/skills/resolve-repo/SKILL.md	Regenerated plugin copy of resolve-repo skill with determinism updates.
devflow-plugin/skills/finish-feature/SKILL.md	Regenerated plugin copy of finish-feature skill with determinism + gate updates.
devflow-plugin/skills/create-pr/SKILL.md	Regenerated plugin copy of create-pr skill with guard step.
devflow-plugin/flows/diagrams/commands/render-diagram.md	Regenerated flow command content with improved diagram rendering/display guidance.
devflow-plugin/commands/verify-first.md	Updates command content (description/body) to include requirement-coverage verification guidance.
devflow-plugin/commands/resolve-repo.md	Regenerated command form of resolve-repo from source skill.
devflow-plugin/commands/render-diagram.md	Regenerated command form of render-diagram with updated guidance.
devflow-plugin/commands/finish-feature.md	Regenerated command form of finish-feature to eliminate drift vs source skill.
devflow-plugin/commands/create-pr.md	Regenerated command form of create-pr including the guard step.
CLAUDE.md	Documents the new single-source-of-truth + generation + guard model for skills.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[AndreJorgeLopes]

good catches, both fixed in 6e067fb. added git diff --name-only --cached $base to the union so a staged-only edit (index differs, working tree clean) is still caught, and swapped the grep "^$1" prefix test for a case "$p" in "$pfx"*) glob so the . in paths like commands/<name>.md is matched literally instead of as a regex. verified the staged-only case now detects.

[AndreJorgeLopes]

i think this one's a false positive. the regex is an unanchored substring match, so \*\*Cloned:\*\*\s+(yes|no) matches the yes/no stem and ignores the parenthetical, **Cloned:** yes (just now) and **Cloned:** no (already existed) both match (tested both). it's intentionally asserting the stem, not the whole line, so the pinned contract isn't violated. leaving as is.

[AndreJorgeLopes]

i think this one's a false positive. the regex is an unanchored substring match, so \*\*Cloned:\*\*\s+(yes|no) matches the yes/no stem and ignores the parenthetical. both pinned forms match: **Cloned:** yes (just now) and **Cloned:** no (already existed) (tested both). it's intentionally asserting the stem, not the whole line, so the pinned contract isn't violated. leaving as is.