fix(source-control): state well-known rung git-tracked requirement on both surfaces

[kyle-sexton]

Summary

#1185's P1 review hardening — the well-known convention-file rung activates only when the file is
git-tracked — landed only in the enforcement resolver bash. The drafting spec
(config-resolution.md) and the commit-convention seam README still said rung 2 fires "when that
file exists", and config-resolution.md claimed the surfaces were "identical" — false after the fix.

The drift it created: a repo with an untracked/gitignored well-known file + a different markdown-H2
subject_pattern → drafting resolves the untracked file, enforcement skips it → the plugin drafts
commits its own gate rejects. Exactly the two-surface divergence the design exists to prevent.

Adds the git-tracked requirement + how the drafting reader checks it (git ls-files --error-unmatch)
to config-resolution.md, the seam README, and the setup SKILL.md gotcha. Docs-only — the resolver
already enforced tracked; this makes the specs match and "identical on both surfaces" true again.

source-control 0.25.0 → 0.25.1.

Test plan

• lychee --offline clean on the three edited docs.
• scripts/check-changelog-parity.sh --check-bump origin/main — bump has an entry.
• No code change (resolver + its 58 tests unchanged); the resolver already required tracked.

Related

• Closes source-control: well-known rung git-tracked requirement missing from drafting spec + seam README (cross-surface drift) #1191
• Follow-up to feat(source-control): well-known default path for neutral convention SSOT (F1–F4) #1185 / #163434 (well-known default path)

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 1m 15s —— View job

---

PR Review

• Gather context and read changed files
• Review docs changes for correctness and consistency
• Check version bump and changelog
• Post final review

---

This is a clean docs-only patch that closes the spec/implementation gap introduced by #1185. The enforcement resolver already required git-tracked; this PR makes the three documentation surfaces say the same thing. Review below.

Correctness

The core claim — rung 2 fires only when the well-known file is git-tracked — is accurately reflected in all three edited surfaces now:

Surface	Before	After
commit-convention/README.md	"when that file exists"	"when that file is git-tracked"
reference/config-resolution.md	"when that file exists"	"when that file is git-tracked"
skills/setup/SKILL.md	missing the constraint	"when git-tracked"

All three now point to git ls-files --error-unmatch as the check, and all describe the same fallback: untracked → skip rung 2 → fall through to markdown H2. Cross-surface alignment is exact.

One formatting nit in config-resolution.md

config-resolution.md L74 — the edit accidentally joined two wrapped lines into one long line:

  applies; a key it omits still falls back per key to the markdown H2. Value grammar, pointer safety rules, and the fail-closed

The surrounding prose wraps at ~96 characters; this line is well over that. The original had this content split across two lines. Non-blocking, but worth rewrapping for readability consistency with the rest of the block. Fix this →

Version bump

0.25.0 → 0.25.1 is the right semver level for a docs-only patch that carries no behavioral change.

Changelog

The 0.25.1 entry is accurate, references the predecessor PR (#1185), and explains both what was wrong and that the resolver was already correct. No issues.

Security / other concerns

None. No code paths changed; no secrets, PII, or external egress introduced.

---

Overall: LGTM. The one formatting nit is cosmetic and doesn't block merge.

[claude]

Claude finished @kyle-sexton's task in 1m 4s —— View job

---

Security Review — PR #1192

• Read PR diff and changed files
• Audit shell commands documented in diff
• Check plugin.json for dangerous patterns
• Review for secrets/credentials
• Post findings

---

No security issues found.

This is a docs-only PR (5 markdown files + a semver bump in plugin.json). Here is what I checked:

Shell command introduced in docs

The only new shell invocation documented across the three changed markdown files is:

git ls-files --error-unmatch docs/conventions/source-control/commit-convention.yml

(config-resolution.md L71, same command cited in the seam README and setup SKILL.md)

This is a safe, read-only git plumbing call with a hardcoded repo-relative path — no user-controlled input, no shell expansion surface, no exec side-effects. It exits non-zero when the file is absent/untracked; the documentation correctly describes that exit code as the "skip rung 2" signal. There is no injection risk.

plugin.json

Change is a single field: "version": "0.25.0" → "0.25.1". No new permissions, no new userConfig keys, no remote endpoints, no dependency changes. (plugin.json L4)

Secrets / credentials

None present anywhere in the diff.

GitHub Actions / workflows

No workflow files touched.

Security posture assessment

The PR strengthens the existing posture: it closes the spec gap where documentation claimed drafting and enforcement were "identical" while the enforcement resolver already enforced the git-tracked requirement and the drafting spec did not. A repo with an untracked/gitignored file at the well-known path could have had the agent draft commits its own gate would then reject — a drafting/enforcement divergence. Aligning both specs to require git-tracking and documenting the verification command is a correctness fix that also tightens predictability of the security gate.