docs(source-control): setup skill-quality pass — Gotchas surface, apply-convention spoke split - #1146
Merged
Merged
Conversation
…ly-convention spoke split (0.22.0) Verified the audit's MD041/MD013 findings against the repo's actual markdownlint config first: .markdownlint-cli2.jsonc disables both, so they do not apply under the repo's own gate — no lint edits for them. Added a Gotchas section recording real first-contact failure patterns (omission-never-resets fallthrough, none vs absence, resolved-value inference gating, nested-dir cwd reads, linked-worktree hooks dir, committer-date recency clocks, same-session stale userConfig reads). Hub-split decision: DONE — #1139's consensus-window inference pushed the hub to 512 lines, over the gate's 500-line hard cap, so the apply convention write path (layer selection, non-interactive update semantics, interview, template, per-layer verification) moved verbatim to reference/apply-convention.md with a normative pointer in the hub. Hub 211 lines; skill-quality:check passes with zero errors and no Gotchas WARN. Closes #1140 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
|
Claude encountered an error after 1s —— View job I'll analyze this and get back to you. |
Contributor
|
Claude encountered an error after 0s —— View job I'll analyze this and get back to you. |
|
Warning Automated review did not complete — this is an infrastructure failure, not a review verdict. Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."
Re-running the job, or pushing a new commit, will retry the review. |
|
Warning Automated security review did not complete — this is an infrastructure failure, not a review verdict. Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."
Re-running the job, or pushing a new commit, will retry the review. |
Contributor
Author
|
Pre-merge CI classification
Merging per the drive-to-merged directive on record for this issue chain (#1138 → #1141). |
kyle-sexton
added a commit
that referenced
this pull request
Jul 23, 2026
…ntion_source (#1149) Closes #1141 ## Summary Author-directed reopen of #913's recorded "no YAML / no path rename" decision — the four reopen grounds (author directive, a real consuming machine hand-syncing three byte-identical regex copies, the ecosystem's prose-only AGENTS.md pointer standard with no machine format, and the plugin-audit recurring-concerns memory contradicting the decline) are recorded in #1141; a comment recording the outcome goes on #913 at merge. The team-tracked `.claude/source-control.md` may now declare `## convention_source`: a **repo-relative flat-scalar YAML file** (`subject_pattern`, `pr_title_pattern`, optional `pr_body_required_sections` list or `none`, optional `dialect:` defaulting `posix-ere`) that enforcement (commit-msg hooks, CI) and drafting (any agent) consume as one source. Key contract points, all recorded in the commit-convention seam README: - **Back-compat absolute:** no pointer → today's markdown-H2 behavior, zero action for existing consumers. - **Everything repo-declared:** the path is the consuming repo's call (no hardcoded doc root; no well-known search list in V1 — recorded decision with rationale). The `Conventional Commits` keyword and the pr-title deferral marker work identically on both surfaces. - **Per-key precedence:** the neutral file is authoritative for keys it carries; omitted keys fall back to the markdown H2; plugin-only keys (`trailer_policy`, `pr_body_attribution`) stay `.claude/`-side; user/local overlay layers unchanged. - **Enforcement contract unchanged:** POSIX ERE only, unresolved = no enforcement, team-only policy floor — including the pointer itself (an overlay cannot redirect the gate). A declared-but-broken pointer (absolute/backslash/`..` path, missing file) or a non-`posix-ere` dialect **fails closed** with a diagnostic, never a silent markdown fallback that could enforce a migration-retired pattern. - **Incumbent steelman documented:** markdown-H2's doubles-as-documentation purposes tested against the move (YAML `#` comments + prose pointer doc); frontmatter-hybrid re-examined and declined for V1 with rationale. - **`setup apply`** gains the offer-and-migrate path: repo-chosen path, YAML write, pointer declaration, and retiring duplicated markdown keys so both surfaces are never authoritative for the same key. Monorepo per-directory scoping: out of scope V1, recorded. `lib/resolve-convention-pattern.sh` extended; the guardrails vendored copy synced byte-identical via `scripts/sync-resolve-convention-pattern.sh` (gate: resolve-convention-pattern-sync), with guardrails 0.12.3 → 0.13.0 + CHANGELOG per the bump gate. source-control 0.22.0 → 0.23.0 + CHANGELOG. ## Test plan - `bash lib/resolve-convention-pattern.test.sh`: **44 cases, 0 failed** — 14 new neutral-SSOT cases: quoted/double-quoted/unquoted YAML values, CC keyword and deferral marker in YAML, explicit `posix-ere` dialect, non-ERE dialect → fail closed, missing-file pointer → fail closed with no stale markdown fallback, absolute/traversal pointer rejection, omitted-key markdown fallback, YAML-wins-over-unretired-duplicate, comment/blank inertness, overlay-pointer ignored (team-only floor). - `scripts/sync-resolve-convention-pattern.sh --check`: guardrails copy byte-identical. - `skill-quality:check` on `setup`: PASS, 0 errors. - `jq -e` validates both manifests and the evals file; new setup eval 18 covers the apply migration path. ## Related - #913 — the reopened decision (outcome comment lands there on merge). - Issue chain: #1138 (PR #1142) → #1139 (PR #1144) → #1140 (PR #1146) → #1141 (this), all merged in order. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1140
Summary
Skill-quality pass over
source-control:setupper the F4 audit finding. The audit's MD041/MD013 lint findings were verified against the repo's actual markdownlint config first (per the issue's explicit instruction):.markdownlint-cli2.jsoncdisables both MD013 and MD041, so they do not apply under the repo's own gate — no lint edits made for them; markdownlint reports clean.Added a
## Gotchassurface recording real first-contact failure patterns from the live audits: omission-never-resets per-key fallthrough,nonevs absence as distinct states, resolved-value (not file-presence) inference gating, nested-directory cwd-relative read degradation, linked-worktree hooks-dir resolution,--sincecommitter-date vs%adauthor-date recency skew (review-caught during #1139), and same-session staleuserConfigreads.Hub-split decision: DONE, not deferred. #1139's consensus-window inference had pushed the hub to 512 lines — over the skill-quality gate's 500-line hard cap — so the split fell out naturally: the
applyconvention write path (layer selection, non-interactive update semantics, the 7-step interview, the written-file template, per-layer verification scripts, failure remediations) moved verbatim to a progressive-disclosure spokeskills/setup/reference/apply-convention.md(332 lines, one relative link re-depthed), with a normative pointer + summary in the hub. Hub now 211 lines.source-control 0.21.0 → 0.22.0 + CHANGELOG.
Test plan
skill-quality:check(bundledcheck-skill.sh, twenty-check static gate) onsetup: PASS — 0 errors; all 8 base-ref trigger phrases preserved; markdownlint clean; no Gotchas WARN; hub 211/500 lines (only remaining note: advisory soft target 200).config-resolution.md) re-depthed for the new location.jq -evalidatesplugin.json.Related
🤖 Generated with Claude Code