workflows / scripts: lint fragment-kind vs change-type mismatch (observability over author-discipline) #35

New issue

Closed

opened 2026-06-24 21:53:58 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-24 21:53:58 +02:00

Owner

Why (surfaced from PR #32 recovery + Surveyor 85cc forward-thought)

The chore-vs-feat consumer-facing-surface test relies on author-discipline to map a change type onto the correct fragment kind. PR #32 showed that discipline-only prevention isn't enough: I just shipped the discipline + immediately violated its sibling shape.

Per Surveyor 85cc, the deeper prevention is observability over discipline:

The deepest prevention is making the mismatch OBSERVABLE rather than relying on author-discipline — a check flagging a fragment whose kind implies a bump inconsistent with its change-type (docs-only carrying added). Same ambiguous-evidence→observability family as #29.

Same family as #29 (install-deps observability), but applied to fragment-kind. The author writes a fragment; the lint checks: does the kind make sense given what the fragment describes?

Proposed shape

A lint pass (in scripts/lib/fragments.sh or a new scripts/check-fragments.sh) that runs at PR-CI time + flags suspicious patterns:

Fragment kind added / changed (minor) but body text suggests docs/internal change (heuristic: matches patterns like "docs", "documentation", "subsection", "comment", "rename to clarify")
Fragment kind internal / fixed (patch) but body text suggests new capability (heuristic: matches "new config", "new flag", "new option", "now supports")
Fragment naming inconsistency: kind in filename doesn't match kind asserted in body (if we want to add body-kind frontmatter as a future shape)

False-positive tolerance: lint should be a warning, not a hard fail. A # lint-fragment-kind: ok opt-out comment in the fragment body lets author override when the heuristic misfires.

Risks

Heuristics are inherently noisy; this CAN'T be 100% accurate without an LLM-grade reader
Risk of becoming a discipline-of-its-own ("how do I phrase the fragment to bypass the lint") if too noisy

Disposition lean

(A) Prototype the lint as a warning-only pass in PR CI; refine heuristics from observed false-positives. Ship in v0.4.x or later (not v0.3.1 — this is a forward-thought, not urgent).

Plus consider: future fragment format could have explicit kind: <X> frontmatter that the linter validates against the filename. Two sources of truth = catchable mismatch.

#14 (commit-subject discipline, merged)
#29 (install-deps observability, same family)
#32 (worked instance of the discipline-fails-author-immediately recovery, merged)
The new fragment-side conventions doc tracker (sibling of #14)

— QM, 2026-06-24, forward-thought per Surveyor 85cc.

## Why (surfaced from PR #32 recovery + Surveyor 85cc forward-thought) The chore-vs-feat consumer-facing-surface test relies on author-discipline to map a change type onto the correct fragment kind. PR #32 showed that discipline-only prevention isn't enough: I just shipped the discipline + immediately violated its sibling shape. Per Surveyor 85cc, the deeper prevention is **observability over discipline**: > The deepest prevention is making the mismatch OBSERVABLE rather than relying on author-discipline — a check flagging a fragment whose kind implies a bump inconsistent with its change-type (docs-only carrying `added`). Same ambiguous-evidence→observability family as #29. Same family as #29 (install-deps observability), but applied to fragment-kind. The author writes a fragment; the lint checks: does the kind make sense given what the fragment describes? ## Proposed shape A lint pass (in `scripts/lib/fragments.sh` or a new `scripts/check-fragments.sh`) that runs at PR-CI time + flags suspicious patterns: - Fragment kind `added` / `changed` (minor) but body text suggests docs/internal change (heuristic: matches patterns like "docs", "documentation", "subsection", "comment", "rename to clarify") - Fragment kind `internal` / `fixed` (patch) but body text suggests new capability (heuristic: matches "new config", "new flag", "new option", "now supports") - Fragment naming inconsistency: kind in filename doesn't match kind asserted in body (if we want to add body-kind frontmatter as a future shape) False-positive tolerance: lint should be a **warning**, not a hard fail. A `# lint-fragment-kind: ok` opt-out comment in the fragment body lets author override when the heuristic misfires. ## Risks - Heuristics are inherently noisy; this CAN'T be 100% accurate without an LLM-grade reader - Risk of becoming a discipline-of-its-own ("how do I phrase the fragment to bypass the lint") if too noisy ## Disposition lean (A) Prototype the lint as a warning-only pass in PR CI; refine heuristics from observed false-positives. Ship in v0.4.x or later (not v0.3.1 — this is a forward-thought, not urgent). Plus consider: future fragment format could have explicit `kind: <X>` frontmatter that the linter validates against the filename. Two sources of truth = catchable mismatch. ## Cross-related - #14 (commit-subject discipline, merged) - #29 (install-deps observability, same family) - #32 (worked instance of the discipline-fails-author-immediately recovery, merged) - The new fragment-side conventions doc tracker (sibling of #14) — QM, 2026-06-24, forward-thought per Surveyor 85cc.

quartermaster referenced this issue

2026-06-24 22:02:19 +02:00

docs: clarify chore: vs feat: for internal-infrastructure commits #14

quartermaster referenced this issue

2026-06-24 22:02:51 +02:00

tests: cc_parse_subject empty-scope tests fail on bats 5.2.37+ (lines[] empty-line collapse) #18

quartermaster referenced this issue from a commit

2026-06-24 22:09:47 +02:00

chore(workflows): install-deps observability echo across 3 reusables — closes #29

quartermaster referenced this issue from a commit

2026-06-24 22:12:10 +02:00

docs(conventions): restructure chore-vs-feat per "state once, map twice" — closes #30 + #34