dhpk-openspec-artifact-guard

OpenSpec artifact guard

OpenSpec's directory shapes are easy to mis-name. The most expensive mistake — editing openspec/specs/ directly during an active change — is also the most invisible: nothing throws, the file commits cleanly, and the delta-merge step on archive silently does nothing because the SSOT already matches.

This skill is the fast pre-archive guard. The deep verifier is openspec-verify-change (different skill). Run this one whenever openspec/** files are in the diff.

Background reading: modules/library-author/references/openspec-naming-gotchas.md

---

When to run

• Editing any file under openspec/
• Reviewing a PR whose diff touches openspec/
• Before invoking openspec:archive on a change (last-line safety net)
• After mass-rename in the openspec tree (slug normalization)

When NOT to Use

• Editing source code that has nothing to do with the spec
• Running openspec:verify already (it covers a superset of these checks)

---

Inputs

The diff under openspec/ (or, if no diff, the current working tree state):

git diff --name-only -- openspec/
# or, if no diff:
find openspec/ -type f -name '*.md' -newer openspec/project.md 2>/dev/null

Also read openspec/changes/*/ directory shapes (regardless of diff).

---

Checks

Check 1 — Direct SSOT edit during active change (CRITICAL)

Find files matching openspec/specs/** in the diff that are NOT in an archive commit.

git diff --name-only | grep -E '^openspec/specs/[^/]+/'

A new file or modified file here is suspect. The only legitimate way to update openspec/specs/ is through openspec:archive which applies delta directives from openspec/changes/<slug>/specs/ to the SSOT.

Confirm legitimacy by:

• The commit message contains archive AND
• The same commit touches openspec/changes/.archive/<slug>/ or openspec/changes/archive/<slug>/

If both conditions are met → APPROVE. Otherwise → CRITICAL: redirect the edit to openspec/changes/<current-change>/specs/<capability>/spec.md with delta markers.