Summary
Follow-on to #1141 (neutral convention SSOT, source-control 0.23.0). The neutral YAML landed as an
opt-in convention_source pointer living inside agent-rewritable markdown-H2 prose, with no
native config surface — so every non-plugin consumer (commit-msg hook, CI, other agent) must
markdown-parse .claude/source-control.md to discover the path, and an agent tidying that file can
silently sever resolution (fails closed, no signal).
Raised via the melodic handoff-inbox (20260723-163434-source-control-setup-convention-default-and-config-surface), producer SW2030.
Decision (locked with maintainer)
Well-known default path, defaulting to the marketplace's own dogfooded docs/conventions/<concern>/
layout: docs/conventions/source-control/commit-convention.yml. Fixed 3-rung precedence, identical on
the drafting and enforcement surfaces:
- explicit
convention_source pointer (relocation override — path stays repo-owned)
- well-known default path when the file exists (common case — read ONE tool-agnostic file, no pointer)
- markdown-H2 (legacy / back-compat)
Design + re-anchor rationale (reuse-or-replace, recheck-against-upstream, reason-dont-recite,
point-dont-copy): docs/topics/commit-convention-well-known-path/design-resolution.md.
Findings folded in
- F2 (config surface) — the well-known default path (above); no markdown pointer-parse in the common case.
- F1 (default steer) — setup recommends the neutral SSOT as the default when a second enforcement
consumer (commit-msg hook / CI title check) is detected; markdown-only when this plugin is the sole consumer.
- F3 (fragility/observability) —
setup check gains drift probes: broken pointer/neutral file (FAIL),
and a resolved neutral file shadowing a stale markdown-H2 duplicate (WARN).
- F4 (taste) — neutral-YAML preamble template trimmed to a 1–2 line header.
Touches the sync-gated lib/resolve-convention-pattern.sh (byte-identical guardrails mirror; forced
guardrails version bump).
Related
Summary
Follow-on to #1141 (neutral convention SSOT, source-control 0.23.0). The neutral YAML landed as an
opt-in
convention_sourcepointer living inside agent-rewritable markdown-H2 prose, with nonative config surface — so every non-plugin consumer (commit-msg hook, CI, other agent) must
markdown-parse
.claude/source-control.mdto discover the path, and an agent tidying that file cansilently sever resolution (fails closed, no signal).
Raised via the melodic handoff-inbox (
20260723-163434-source-control-setup-convention-default-and-config-surface), producer SW2030.Decision (locked with maintainer)
Well-known default path, defaulting to the marketplace's own dogfooded
docs/conventions/<concern>/layout:
docs/conventions/source-control/commit-convention.yml. Fixed 3-rung precedence, identical onthe drafting and enforcement surfaces:
convention_sourcepointer (relocation override — path stays repo-owned)Design + re-anchor rationale (reuse-or-replace, recheck-against-upstream, reason-dont-recite,
point-dont-copy):
docs/topics/commit-convention-well-known-path/design-resolution.md.Findings folded in
consumer (commit-msg hook / CI title check) is detected; markdown-only when this plugin is the sole consumer.
setup checkgains drift probes: broken pointer/neutral file (FAIL),and a resolved neutral file shadowing a stale markdown-H2 duplicate (WARN).
Touches the sync-gated
lib/resolve-convention-pattern.sh(byte-identical guardrails mirror; forcedguardrails version bump).
Related
20260723-163434-source-control-setup-convention-default-and-config-surface