fix: address docs checker review findings

Check every link reference definition, decode destinations per CommonMark,
report correct lines for empty headings, autolinks and nested definitions,
reject symlinked record directories and wrong-case path components, and
refuse titles that cannot pass. Only top-level headings count (spec section 6).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

internal/docs/id.go

@@ -55,6 +55,8 @@ func slugify(title string) string {
 	return strings.Trim(s[:min(len(s), maxSlug)], "-")
 }
 
+var closingRe = regexp.MustCompile(`(^|[ \t])#+$`)
+
 // New creates a record of the given kind ("adr" or "plan") under root and
 // returns its root-relative slash path. The file is created exclusively; the
 // timestamp advances by 1 ms on a collision.
@@ -63,6 +65,9 @@ func New(root, kind, title string, now time.Time) (string, error) {
 	if title == "" || strings.ContainsAny(title, "\r\n") {
 		return "", errors.New("title must be non-empty and a single line")
 	}
+	if closingRe.MatchString(title) {
+		return "", errors.New(`title must not end in a "#" run: it would be read as a closing sequence of the H1`)
+	}
 	slug := slugify(title)
 	if slug == "" {
 		return "", errors.New("title needs at least one ASCII letter or digit for the file name")