Gate hard-wrapped markdown instead of only documenting the rule

[FrankRay78]

Problem

.claude/memory/feedback_markdown_soft_wrap.md tells Claude to author each markdown paragraph, bullet and table row as a single unwrapped line, and explicitly names docs, READMEs, memory files and PR bodies. It is written, it is indexed in MEMORY.md, and it still did not land.

On the #281 branch, bbd6454 committed four hard-wrapped paragraphs into .claude/commands/speckit.reviewissue.md. 211726c then unwrapped them as a separate rework commit — 5 insertions against 23 deletions, pure churn. The file was touched 3 times in a 4-commit branch, and one of those touches existed only to undo the previous one.

The reason the rule failed is worth stating, because it will recur: the surrounding text in that file is itself hard-wrapped legacy prose, so matching local style and following the written rule pointed in opposite directions. Local style won.

Motivation

A memory that fails after being written is the signal to escalate, not to restate. The repo's own preference order puts a deterministic mechanism above a memory entry precisely for this case, and .claude/memory/feedback_audit_class_after_two_failures.md says the second occurrence of a failure shape is the point to fix the class rather than the instance.

There is direct in-repo precedent for the mechanism. .claude/hooks/ already carries three gates that decide markdown- and code-shape invariants — no-skipped-tests.sh, traceability-gate.sh, green-gate.sh — each with a --check mode and a committed *.tests.sh fixture matrix.

Proposal

A .claude/hooks/ gate that rejects a commit introducing hard-wrapped markdown prose, following the existing --check + *.tests.sh pattern.

The binding constraint is that it must inspect added lines only. Almost every long-lived markdown file in this repo is hard-wrapped throughout, so a whole-file check would fail on contact with nearly any doc commit.

The hard part, stated up front

Distinguishing an added hard-wrapped paragraph line from a legitimately short line is the whole difficulty, and a naive length test will not do it. Lines that are short for good reasons include headings, list items, table rows, blockquote lines, fenced-code content, link-reference definitions, and the last line of any paragraph.

A false-positive gate firing on ordinary doc commits would be worse than the memory that currently fails, so the acceptance bar should be behavioural rather than aspirational.

Acceptance criteria (draft — expect the review to sharpen these)

• A commit adding a hard-wrapped prose paragraph to a markdown file is rejected, naming the file and line.
• A commit adding soft-wrapped prose to a markdown file passes.
• Editing a line inside an existing hard-wrapped paragraph, without re-wrapping it, is not rejected — otherwise the gate forces unrelated reflows, which is the diff noise the rule exists to prevent.
• Headings, list items, table rows, blockquote lines, fenced-code content and link-reference definitions are never flagged.
• The gate runs on bbd6454 and fails, and on 211726c and passes. These two commits are the real before/after and are the RED-GREEN evidence for this change.
• A --check mode exists for CI and manual scans, matching the three existing hooks.
• A committed *.tests.sh fixture matrix covers each criterion above.

Out of scope

• Re-wrapping existing hard-wrapped files. The memory explicitly forbids tidying them, and doing it would produce exactly the reflow diffs this is meant to avoid.
• Any change to feedback_markdown_soft_wrap.md's substance. The rule is right; only its enforcement is missing.
• Adding a hard-wrap step to any formatter or hook, which the memory forbids outright.
• Markdown outside this repository — issue bodies and PR bodies are composed by hand and land via gh, where no commit hook can see them.

Open questions

• Is a commit hook the right gate at all, or should this be a --check run in CI only? A PreToolUse hook that fails closed blocks every commit when it misfires, and this check is more heuristic than the three that exist.
• What is the right threshold, and should it be a threshold at all? A paragraph line that ends well short of the wrap column while the next line continues the sentence is the real signal, and that is a shape test rather than a length test.

Related

• .claude/memory/feedback_markdown_soft_wrap.md — the rule this enforces.
• .claude/memory/feedback_audit_class_after_two_failures.md — why the second occurrence is the point to mechanise.
• docs/study/281.md — row 3 records this failure.
• .claude/hooks/README.md — the --check + *.tests.sh convention any new gate should follow.
• Commits bbd6454 and 211726c on the merged feature/281-triageable-review branch — the before/after pair.

[claude]

Pre-specification review — gaps & clarifications

Before taking this into SDD, the following points need answers. The table lists every gap and what turns on it — use it to decide where to spend your attention, then record responses inline beneath each gap.

If an answer slot says not sure, idk, tbd, more options, help me, or similar hedge (anything that means "I want help, not a decision"), re-run /speckit.reviewissue #285 and that question will be re-framed with extra options, a worked example, and a revised recommendation. Iterate as many times as you need.

If a gap turns out to be out of scope for this issue, answer with out of scope: <one-line reason> — /speckit.confirmissue will record it as a redirect. There is no separate "defer" path: anything not in scope here belongs in a different issue, not parked on this one.

When all answers are concrete, run /speckit.confirmissue #285 to fold them into the issue body as Confirmed decisions. That deletes this comment — the decisions are the record from then on, and you revise one by editing its bullet.

Gaps at a glance

#	Gap	If answered against the recommendation
1	Enforcement point: commit-blocking hook vs CI/manual-only	Changes what gets built — gate can never block a commit, only ever reports
2	Detection rule: threshold vs shape-based match	Changes what gets built — swaps the whole matching algorithm and its false-positive surface
3	Exempt spec-kit-vendored template markdown	Changes what gets built — whether a routine spec-kit upgrade trips the gate

Technical gaps

1. Enforcement point: commit-blocking hook vs CI/manual-only
Changes what gets built: decides whether the gate can ever block a commit or only ever reports.

Left open in the issue's own "Open questions." no-skipped-tests.sh and green-gate.sh hard-block git commit via PreToolUse(Bash); traceability-gate.sh only nudges via Stop, loop-guarded, never hard-locking. None of the three is wired into CI today — no workflow references any of them — so this issue's "for CI" AC has no existing wired pattern to match.

Recommendation: PreToolUse(Bash) on git commit, like no-skipped-tests.sh — but fail OPEN on classification uncertainty, like green-gate.sh, not fail-closed. Reason: a shape heuristic misfires more than an exact regex ban, and hooks/README's own rule is "a guard that falsely blocks is worse than no guard."

Answer:

2. Detection rule: threshold vs shape-based match
Changes what gets built: swaps the whole matching algorithm and its false-positive surface.

Also left open by the issue. A line-length threshold can't tell a short heading/table/list line from a wrapped paragraph line — the issue's own "hard part" section says so. .editorconfig's [*.md] trim_trailing_whitespace = false confirms this repo deliberately keeps two-space hard breaks, so the check must read trailing whitespace before any trim, not after.

Recommendation: Shape test: flag an added prose line (not heading/list/table/blockquote/fence/link-ref) that doesn't end in sentence punctuation, two trailing spaces, or a backslash, where the next line continues as prose. Reason: the issue's own example — short line, next line continues the sentence — is a shape signal, not a length one.

Answer:

3. Exempt spec-kit-vendored template markdown
Changes what gets built: whether a routine specify CLI upgrade can trip the gate on content this repo doesn't author.

.specify/templates/*.md (e.g. spec-template.md) is hard-wrapped upstream vendor prose, rewritten by the specify init --here --force upgrade procedure, not authored here. It's already Edit-denied in settings.json for that reason — but that only stops Claude's own Edit tool, not a commit of CLI-rewritten output. The issue's "Out of scope" list doesn't mention vendored files.

Recommendation: Exempt .specify/templates/** and .specify/scripts/** — the same paths already carved out from Edit. Reason: matches the existing rationale (upstream-controlled, not ours to reflow) and stops a routine spec-kit upgrade from being blocked by a rule about our own authoring style.

Answer:

Commentary

• Hook registration is manual: .claude/hooks/README.md notes a hook "lands in settings.json only after review" — building and testing the script doesn't wire it up; a human still adds the PreToolUse/Stop entry by hand.
• Escape-hatch naming convention: the three existing gates each expose an announced NETPACE_SKIP_<GATE> (or NETPACE_ALLOW_<THING>) override, always logged to stderr — matching that pattern is expected, though nothing enforces it.
• README section expected: each of the three existing gates gets its own section in .claude/hooks/README.md (scope, fail-open/closed rule, override var, commands) — this gate should too, to keep the file's own convention intact.