bacon-tracker 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69adddc52e57d700e447f7090e300ff58cf74c3ca9881eb54c19b488f39222d7
-  data.tar.gz: 5efcc62978f6d2aeb3689649298956be52ab3fba0bef0ac3ae55603c2afc584f
+  metadata.gz: 42440d405b85d2a4c75b2d12dc9f76a5519e694ecd88e10b208d008bc8f8a6ad
+  data.tar.gz: 2a7a38d3156579ec88136713ecc60f8b1bf35a35d57f4e9141000be7a9ac2946
 SHA512:
-  metadata.gz: 202a6ab1a3974e6a303d6571500c230a968114e85003db38c9206908701a51472566f01523637ee032507a1d060df5c2b1272dec001d0a4b76275d64c374628a
-  data.tar.gz: 9c33747da78d15551c351a884c81ff3a1ef1284079fc6dd627d0284ec6fada9f5ba3f4ec3586f06bf6a56ac958e87a63b066d0a303b7445d60a94f8572b88487
+  metadata.gz: c85377256c359817bf27bae870babd0f34fe724d5b1f117eb0a61c216ea50fc18dbb5bfbded6d105286f9d146ffe9c315e83b1d7b5bfd70e1ae5014e2c865f1d
+  data.tar.gz: d57fc7d4fb694b8729751b92d04d34921de3099ded4fcd2a52eadd2e665ceae33f66129663198279dd489b30c242f41f683f081ec5bea48e730d0f506eba5d82

data/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), [Semantic Versioning](https://semver.org/).
 
+## [1.1.1] - 2026-10-21
+
+### Fixed
+
+- `rake story:commit` (and every other path that adds a line to `backlog.md`) writes the story's own title to the line, the same one the board shows, instead of the humanized filename slug. The slug is the fallback only when the file has neither a title line nor an opening heading. Retitling a committed story rewrites its line even when the filename does not change. `stats.next_task` follows.
+- `rake story:lint` reports a `backlog.md` line whose title is not the story's (`title-drift`), on the line in `backlog.md`, and fails on it - the same comparison the shared CI lint makes, so the local check and CI agree on the same tree.
+- A story created from a `_template.md` or `_template.feature` that starts with a header block of its own (`id`, `type`, `status` with a placeholder id) now has exactly one header and the title as typed. It used to carry both headers, the template's placeholder id and the template's placeholder title; the typed title reached only the filename. The title is filled into the template's first `Title:`/`Feature:` line wherever it sits, and a template without one gets the line added. `rake story:lint` points out such a template (`template-header`) as a notice, so the project can drop the block.
+- `rake story:feature|bug|chore` with an unknown `size=` (say `XS`) is refused before a story is created, like the API and the board already were. It used to create the story, spend its number, and only then report "could not set fields", leaving an unsized story behind. One list of sizes (`S`, `M`, `L`) now backs creating, editing, showing and linting.
+- `rake story:lint` reports a story whose file carries a size the tracker does not know (`unknown-size`), naming the story and its `size:` line. It is a notice, not a failure: the board shows such a story without a size, and old files are not made to be swept. With `LINT_FORMAT=github` it is a `::notice` annotation.
+- A bug or chore with no `Title:` line that opens with a markdown heading now takes the heading as its title on the board, the dashboard and the API, the way decision records do. It used to fall back to the humanized filename slug, which loses dashes, punctuation, capitals and umlauts ("# Fix the Ä-key — today" showed as "fix the ae key today"). Retitling such a story rewrites the heading. The slug remains the fallback when there is neither.
+
+## [1.1.0] - 2026-10-01
+
+### Changed
+
+- Filename slugs spell out `ä`, `ö`, `ü`, `ß` as `ae`, `oe`, `ue`, `ss` and drop accents from other letters, so "Datenschutzerklärung" becomes `datenschutzerklaerung` instead of `datenschutzerkl-rung`. Existing files keep their names until the story is retitled.
+- A title with nothing the slug rule keeps (all-CJK, all-punctuation) now slugs to `non-latin-REPLACE-ME` instead of `untitled`, for story files, decision records and dashboard project slugs alike. The dashboard used to get an empty project slug in that case.
+
+### Fixed
+
+- Story titles on the board and in the API now come from the in-file `Title:`/`Feature:` line, so umlauts, dots and capitals survive. They were humanized from the filename slug, which keeps only ASCII letters and digits ("Datenschutzerklärung" showed as "datenschutzerkl rung", "bybacon.com" as "bybacon com"). The slug remains the fallback when the line is missing.
+
 ## [1.0.0] - 2026-09-25
 
 First public release.

data/lib/bacon_tracker/commands/tracker.md

@@ -105,9 +105,9 @@ type must be `feature`, `bug`, or `chore`. The title is everything after the typ
 1. Determine N: read the integer from `$TRACKER_ROOT/.next-id`, then **floor it above the highest `<NS>-NNN` already on disk** (`N = max(read, highest + 1)`). A stale `.next-id` from a merge or hand edit must never reissue an existing ID. When `rake` is available, prefer `rake story:<type>['title',field=…]`, which allocates the ID atomically (with this floor, under a file lock).
 2. Write `N+1` back to `.next-id`
 3. Pad N to 3 digits: `NNN`
-4. Slugify the title: lowercase it, turn each run of characters that aren't `a-z` or `0-9` into a single hyphen, and trim hyphens from both ends. If nothing is left, the slug is `untitled`
+4. Slugify the title: spell out `ä`/`ö`/`ü`/`ß` as `ae`/`oe`/`ue`/`ss`, drop accents from other letters (`é` → `e`), lowercase it, turn each run of characters that aren't `a-z` or `0-9` into a single hyphen, and trim hyphens from both ends. If nothing is left, the slug is `non-latin-REPLACE-ME`
 5. Extension: `.feature` for features, `.md` for bugs and chores
-6. Create `$TRACKER_ROOT/<plural-type>/1_icebox/<NS>-<NNN>-<slug>.<ext>` (e.g. `features/1_icebox/...`). The body is the type's `_template.feature` / `_template.md` if one exists, with the title filled in (`Feature: <title>`, or `Title: <title>` on the first line for `.md`). Write frontmatter **in the file's format**: for `.md`, a YAML block `---` / `id: <NS>-<NNN>` / `type: <type>` / `status: icebox` / `---`; for `.feature`, comment-style header lines `# id: <NS>-<NNN>` / `# type: <type>` / `# status: icebox`. (A `.feature` file is parsed by its `# key:` lines **or** a leading YAML `---` block if one is present - but a file mixes only one style, so match the sibling files in the same tracker rather than introducing the other.)
+6. Create `$TRACKER_ROOT/<plural-type>/1_icebox/<NS>-<NNN>-<slug>.<ext>` (e.g. `features/1_icebox/...`). The body is the type's `_template.feature` / `_template.md` if one exists, with the title filled into its first `Feature:` / `Title:` line (add the line at the top if the template has none). If the template itself starts with a header block (`---` … `---`, or `# id:` lines), leave that block out - the new story gets exactly one header, written next. Write frontmatter **in the file's format**: for `.md`, a YAML block `---` / `id: <NS>-<NNN>` / `type: <type>` / `status: icebox` / `---`; for `.feature`, comment-style header lines `# id: <NS>-<NNN>` / `# type: <type>` / `# status: icebox`. (A `.feature` file is parsed by its `# key:` lines **or** a leading YAML `---` block if one is present - but a file mixes only one style, so match the sibling files in the same tracker rather than introducing the other.)
 7. If any `field=value` tokens were given, set them in the frontmatter (same rules as `edit`)
 8. Confirm the new ID and file path
 
@@ -122,7 +122,7 @@ Move a story from icebox → backlog (committing to do it).
 1. Find the file: `find $TRACKER_ROOT -path "*/1_icebox/${ID}-*"`
 2. `mv` it to the corresponding `2_backlog/` directory
 3. Update `status:` in the frontmatter to `backlog`
-4. Append `- <ID> <title>` to `backlog.md`, where the title is the filename slug with hyphens as spaces (bottom = lowest priority, unless user specifies a position)
+4. Append `- <ID> <title>` to `backlog.md`, where the title is the story's own: its `Title:`/`Feature:` line, or the opening `#` heading of a `.md` without one, or the filename slug with hyphens as spaces when there is neither (bottom = lowest priority, unless user specifies a position)
 5. Confirm new stage
 
 ---
@@ -158,7 +158,7 @@ Update story fields in place. Fields: `title`, `size` (S/M/L), `assignee` (initi
 
 1. Find the file: `find $TRACKER_ROOT -name "${ID}-*"`
 2. Frontmatter fields: update the existing line, or add it if missing - matching the file's format (comment-style for `.feature`, YAML for `.md`). An empty value (`size=`) removes the line.
-3. `title`: re-slugify the new title, `mv` the file to `<ID>-<new-slug>.<ext>` in its current stage directory, and update the story's `backlog.md` line if it has one (keep the `- <ID> <title>` format)
+3. `title`: rewrite the `Title:`/`Feature:` line (or the opening `#` heading of a `.md` that has no `Title:` line), re-slugify the new title, `mv` the file to `<ID>-<new-slug>.<ext>` in its current stage directory, and update the story's `backlog.md` line if it has one (keep the `- <ID> <title>` format)
 4. Reject values containing newlines - the gem treats these as invalid everywhere
 5. Confirm what changed
 
@@ -183,7 +183,7 @@ Display a story's content:
 
 1. `find $TRACKER_ROOT -name "${ID}-*"` to locate the file
 2. Read it, strip the frontmatter block
-3. Print: ID, type, stage, title (humanised from filename), any set metadata fields, then body
+3. Print: ID, type, stage, title (the `Title:`/`Feature:` line; for a `.md` without one, its opening `#` heading; humanised from the filename if there is neither), any set metadata fields, then body
 
 ```
 APP-003 - implement user auth
@@ -264,6 +264,6 @@ Report each finding with the ID and file path, or confirm all checks pass. Don't
 
 - Expand `~` in any paths using shell: `eval echo <path>` or `realpath`.
 - When editing frontmatter, match the existing format (comment-style for `.feature`, YAML for `.md`).
-- Slugify: `echo "$TITLE" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'` - and use `untitled` if the result is empty
+- Slugify: `echo "$TITLE" | sed 's/ä/ae/g; s/ö/oe/g; s/ü/ue/g; s/ß/ss/g; s/Ä/Ae/g; s/Ö/Oe/g; s/Ü/Ue/g' | perl -CS -MUnicode::Normalize -pe '$_ = NFKD($_); s/\p{Mn}//g' | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'` - and use `non-latin-REPLACE-ME` if the result is empty
 - `backlog.md` line format: `- <NS>-NNN <title>` (leading dash, single space - exactly what the gem writes; the stats and next-task parsers depend on it). Preserve this when adding/removing entries.
 - Keep output concise - one line per story, full content only for `show`.

data/lib/bacon_tracker/dashboard.rb

@@ -136,11 +136,15 @@ module BaconTracker
         return nil
       end
 
+      # A name with nothing the slug rule keeps gets the EMPTY_SLUG placeholder
+      # as its route (never an empty "/projects/"), but a namespace must not be
+      # guessed from it: stories are matched by "<NS>-NNN", so an explicit
+      # 'namespace:' is required.
       slug      = BaconTracker.slugify(item[:name])
-      namespace = item[:attrs]['namespace'] || slug.upcase.gsub('-', '_')
+      namespace = item[:attrs]['namespace'] || (slug == BaconTracker::EMPTY_SLUG ? '' : slug.upcase.gsub('-', '_'))
       if namespace.empty?
         warn "[BaconTracker] dashboard.md: skipping project #{item[:name].inspect} - " \
-             "empty namespace (its name has no letters/digits; add an explicit 'namespace:')"
+             "no usable namespace (its name has no letters/digits; add an explicit 'namespace:')"
         return nil
       end
 

data/lib/bacon_tracker/tasks.rb

@@ -288,12 +288,13 @@ module BaconTracker
           puts lines.first.strip
         end
 
-        desc 'Check backlog.md against 2_backlog story files for drift, flag duplicate IDs across stages, check blocked_by/linked_to, and verify .next-id'
+        desc 'Check backlog.md against 2_backlog story files for drift (membership and titles), flag duplicate IDs across stages, check blocked_by/linked_to, sizes, templates and .next-id'
         task :lint do
           listed   = core.backlog_ids
           on_disk  = core.backlog_story_files.filter_map { |f| File.basename(f)[core.filename_id_pattern] }
           phantom  = listed - on_disk
           unlisted = on_disk - listed
+          titles   = core.backlog_title_drift
           dupes    = core.duplicate_id_stages
           drift    = core.status_drift
           max_id   = core.max_story_id
@@ -302,13 +303,15 @@ module BaconTracker
 
           rel = core.relationship_findings
           rel_warn, rel_err = rel.partition { |f| BaconTracker::Core::RELATIONSHIP_WARNINGS.include?(f[:kind]) }
+          sizes = core.unknown_sizes
+          templates = core.template_headers
 
           # Flow signals (rel_warn) are reported but never fail the build: a
           # started story waiting on a blocker is a legitimate state per
           # docs/flow.md, so failing CI on it would train people to ignore lint.
-          broken = !(phantom.empty? && unlisted.empty? && dupes.empty? && drift.empty? && rel_err.empty?) || stale_id
+          broken = !(phantom.empty? && unlisted.empty? && titles.empty? && dupes.empty? && drift.empty? && rel_err.empty?) || stale_id
 
-          if !broken && rel_warn.empty?
+          if !broken && rel_warn.empty? && sizes.empty? && templates.empty?
             puts "Backlog is clean - #{listed.size} stories."
           else
             # One list, two renderings. Each entry carries the text (identical
@@ -332,6 +335,12 @@ module BaconTracker
               add.call("unlisted: #{id} has file in 2_backlog/ but missing from backlog.md",
                        core.backlog_story_files.find { |f| File.basename(f).start_with?(id) } || backlog)
             end
+            # The estate's CI lint fails on this; reporting it here keeps the
+            # local check and CI in agreement on the same tree (BT-186).
+            titles.each do |t|
+              add.call("title-drift: #{t[:id]} is listed in backlog.md as '#{t[:listed]}' but the story is titled '#{t[:title]}'",
+                       backlog, t[:line])
+            end
             dupes.each do |id, paths|
               text = "duplicate: #{id} found in #{paths.map { |p| p.sub("#{core.config.tracker_root}/", '') }.join(' and ')}"
               paths.each { |dup| add.call(text, dup) }
@@ -351,6 +360,20 @@ module BaconTracker
                        BaconTracker::Tasks.line_matching(f[:path], /^#?\s*#{field}:/),
                        BaconTracker::Core::RELATIONSHIP_WARNINGS.include?(f[:kind]) ? :notice : :error)
             end
+            # A size the tracker does not know is reported, not failed (BT-184):
+            # the board shows the story without one, and a project is not made
+            # to sweep its old stories to get a green build.
+            sizes.each do |f|
+              add.call("unknown-size: #{f[:id]} says size '#{f[:size]}' - sizes are #{BaconTracker::Core::SIZES.join(', ')}, the board shows none",
+                       f[:path], BaconTracker::Tasks.line_matching(f[:path], /^#?\s*size:/), :notice)
+            end
+            # A template that starts with its own header (BT-185): the rake
+            # task and the API drop it, but a hand copy would not. Reported,
+            # not failed - nothing on the board is wrong.
+            templates.each do |f|
+              add.call("template-header: #{File.basename(f[:path])} in #{f[:dir]}/ starts with a header block - new stories get their own, take it out of the template",
+                       f[:path], 1, :notice)
+            end
 
             if ENV['LINT_FORMAT'] == 'github'
               # Duplicates share one text across two files; each still gets its
@@ -360,7 +383,7 @@ module BaconTracker
             else
               findings.uniq { |f| f[:text] }.each { |f| warn "  #{f[:text]}" }
             end
-            puts 'No integrity problems - the note above is a flow signal, not a failure.' if !broken && rel_warn.any?
+            puts 'No integrity problems - the note above does not fail the check.' if !broken && (rel_warn.any? || sizes.any? || templates.any?)
             exit 1 if broken
           end
         end

data/lib/bacon_tracker/version.rb

@@ -1,3 +1,3 @@
 module BaconTracker
-  VERSION = "1.0.0"
+  VERSION = "1.1.1"
 end

data/lib/bacon_tracker.rb

@@ -170,11 +170,32 @@ module BaconTracker
     @config || configure
   end
 
+  # German letters have a spelled-out ASCII form that readers expect in a
+  # filename ("datenschutzerklaerung", not "datenschutzerkl-rung"); every
+  # other accented letter loses its mark via NFKD decomposition (é -> e).
+  TRANSLITERATIONS = {
+    'ä' => 'ae', 'ö' => 'oe', 'ü' => 'ue', 'ß' => 'ss',
+    'Ä' => 'Ae', 'Ö' => 'Oe', 'Ü' => 'Ue', 'ẞ' => 'SS'
+  }.freeze
+
+  # What slugify returns when nothing of the title survives the ASCII rule
+  # (all-CJK, all-punctuation). Never "": an empty slug makes a dangling
+  # "<id>-.md" that is not a record (BT-095) and a dashboard route of
+  # "/projects/". The placeholder says what happened and asks for a hand-picked
+  # slug; the real title stays in the file's Title:/Feature: line.
+  EMPTY_SLUG = 'non-latin-REPLACE-ME'
+
   # Filesystem-safe slug from a human title - the single source shared by
   # Core (story filenames) and Dashboard (project slugs) so the two can never
-  # drift apart.
+  # drift apart. ASCII-only: the German letters are transliterated, other
+  # accents stripped, and whatever is still not [a-z0-9] becomes a hyphen.
+  # Never empty - see EMPTY_SLUG.
   def self.slugify(title)
-    title.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-|-\z/, '')
+    slug = title.to_s
+                .gsub(/[äöüßÄÖÜẞ]/, TRANSLITERATIONS)
+                .unicode_normalize(:nfkd).gsub(/\p{Mn}/, '')
+                .downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-|-\z/, '')
+    slug.empty? ? EMPTY_SLUG : slug
   end
 
   class Core
@@ -313,16 +334,6 @@ module BaconTracker
       BaconTracker.slugify(title)
     end
 
-    # A non-empty slug for a filename. slugify keeps only [a-z0-9], so a title
-    # with no ASCII alphanumerics (all-CJK, all-punctuation) slugs to "" - fall
-    # back to 'untitled' so the file is "<id>-untitled.ext", not a dangling
-    # "<id>-.ext" with a blank humanized name (BT-095). The real title stays in
-    # the file's Title:/Feature: line.
-    def filename_slug(title)
-      slug = slugify(title)
-      slug.empty? ? 'untitled' : slug
-    end
-
     def story_dirs
       STORY_DIRS.flat_map do |dir, meta|
         STAGES.map do |stage|
@@ -404,6 +415,42 @@ module BaconTracker
       base.sub(/\A#{id_pattern}-/, '').gsub('-', ' ')
     end
 
+    # The in-file title: the "Feature:" line of a .feature, the "Title:" line
+    # of a .md. The filename slug is ASCII-only, so a humanized slug loses
+    # umlauts, dots and case ("Datenschutzerklärung" shows as
+    # "datenschutzerklaerung"); the in-file line is the title as typed. A .md
+    # story without a Title: line that opens with a markdown heading takes that
+    # heading, the way decision records do (BT-183) - a third of the stories
+    # across Ingo's projects are written that way. nil when the line is missing
+    # or blank and the story does not open with a heading, so callers fall back
+    # to the slug.
+    def story_title(body, ext)
+      line  = ext == '.feature' ? /^Feature:[ \t]*(.*)$/ : /^Title:[ \t]*(.*)$/
+      title = body[line, 1]&.strip
+      title = body[LEADING_HEADING, 'text']&.strip if (title.nil? || title.empty?) && ext != '.feature'
+      title unless title.nil? || title.empty?
+    end
+
+    # A markdown heading (any level) as the first non-blank line of a story
+    # body: the title of a .md story that has no Title: line (BT-183). Only the
+    # opening line counts, so a "## Description" section further down, or a
+    # "# comment" inside a code fence, is never mistaken for the title.
+    LEADING_HEADING = /\A(?<lead>\s*\#{1,6}[ \t]+)(?<text>.+?)(?<tail>[ \t#]*)$/
+
+    # Rewrite the opening heading of a .md story (see LEADING_HEADING) to
+    # `title`, leaving any YAML frontmatter untouched. Content without such a
+    # heading is returned as is.
+    def retitle_leading_heading(content, title)
+      fm, body =
+        if content.start_with?("---\n")
+          close = content.index(/^---\n/, 4)
+          close ? [content[0...(close + 4)], content[(close + 4)..]] : ['', content]
+        else
+          ['', content]
+        end
+      fm + body.sub(LEADING_HEADING) { "#{$~[:lead]}#{title}#{$~[:tail]}" }
+    end
+
     # Delegates to set_frontmatter_field: the substitution stays scoped to the
     # frontmatter block (a body line like "status: healthy" is never touched)
     # and a missing status field is added instead of silently skipped.
@@ -500,7 +547,14 @@ module BaconTracker
       raise
     end
 
-    # Normalize a T-shirt size to S/M/L (upcased), treating nil/"" as "unset"
+    # The T-shirt sizes the tracker knows. The one list behind creating,
+    # editing, showing and linting a story, so no entry point can accept a
+    # size another one hides (BT-184 - XS was refused on edit, created by the
+    # rake task, and shown as nothing by the board).
+    SIZES = %w[S M L].freeze
+    SIZE_RULE = "size must be #{SIZES[0...-1].join(', ')}, or #{SIZES.last}".freeze
+
+    # Normalize a T-shirt size to SIZES (upcased), treating nil/"" as "unset"
     # and raising on anything else - the one rule shared by create_story and
     # update_story so the two entry points can't disagree (BT-101).
     def normalized_size!(size)
@@ -509,11 +563,25 @@ module BaconTracker
       return nil if size.empty?
 
       up = size.upcase
-      raise ArgumentError, 'size must be S, M, or L' unless %w[S M L].include?(up)
+      raise ArgumentError, SIZE_RULE unless SIZES.include?(up)
 
       up
     end
 
+    # Stories whose size: is not one the tracker knows (BT-184). story:lint
+    # reports them as a notice, not a failure: the value came from a hand edit
+    # or an older tool, the board already shows the story without a size, and
+    # a project is not made to sweep its old stories for a green build. Done
+    # stories are a record and are skipped, as relationship_findings does.
+    def unknown_sizes
+      all_stories.reject { |s| s[:stage] == '4_done' }.sort_by { |s| s[:id] }.filter_map do |s|
+        declared = s[:declared_size]
+        next if declared.nil? || SIZES.include?(declared.upcase)
+
+        { id: s[:id], size: declared, path: s[:path] }
+      end
+    end
+
     def move_to_stage(result, new_stage)
       old_path = result[:file]
       new_dir  = File.join(@config.tracker_root, result[:dir], new_stage)
@@ -527,8 +595,44 @@ module BaconTracker
       new_path
     end
 
+    # The title a backlog.md line carries: the story's in-file title, the same
+    # one the board shows, so the line and the card never disagree (BT-186).
+    # The humanized slug is what parse_story_file falls back to when the file
+    # has no title line and no opening heading.
+    def backlog_title(path)
+      meta  = story_dirs.find { |d| d[:path] == File.dirname(path) }
+      story = meta && parse_story_file(path, meta)
+      story ? story[:title] : humanize_slug(path)
+    end
+
+    # The title part of a backlog ENTRY line ("- NS-123 title" -> "title"),
+    # nil for a non-entry line. Compared against backlog_title by story:lint.
+    def backlog_line_title(line)
+      m = line.match(/\A\s*-\s+#{id_pattern}[ \t]*(.*?)\s*\z/)
+      m && m[1]
+    end
+
+    # Backlog entry lines whose title is not the story's (BT-186): the same
+    # comparison the estate's CI lint makes, so a tree that passes locally
+    # passes there. Lines without a file are phantoms and reported as such.
+    def backlog_title_drift
+      return [] unless File.exist?(@config.backlog_path)
+
+      on_disk = backlog_story_files.to_h { |f| [File.basename(f)[filename_id_pattern], f] }
+      File.readlines(@config.backlog_path, encoding: 'utf-8').each_with_index.filter_map do |line, i|
+        id = backlog_line_id(line)
+        next unless id && on_disk.key?(id)
+
+        listed = backlog_line_title(line)
+        title  = backlog_title(on_disk[id])
+        next if listed == title
+
+        { id: id, listed: listed, title: title, path: on_disk[id], line: i + 1 }
+      end
+    end
+
     def backlog_add(id, filename)
-      title    = humanize_slug(filename)
+      title    = backlog_title(filename)
       existing = File.exist?(@config.backlog_path) ? File.read(@config.backlog_path, encoding: 'utf-8') : ''
       # Normalize the trailing newline first so a hand-edited backlog.md that
       # doesn't end in one doesn't glue the new entry onto the last line
@@ -554,7 +658,7 @@ module BaconTracker
       lines = File.exist?(@config.backlog_path) ? File.readlines(@config.backlog_path, encoding: 'utf-8') : []
       kept  = lines.select { |l| (id = backlog_line_id(l)).nil? || on_disk.key?(id) }
       listed    = kept.filter_map { |l| backlog_line_id(l) }
-      additions = (on_disk.keys - listed).map { |id| "- #{id} #{humanize_slug(on_disk[id])}\n" }
+      additions = (on_disk.keys - listed).map { |id| "- #{id} #{backlog_title(on_disk[id])}\n" }
       atomic_write(@config.backlog_path, (kept + additions).join) if kept != lines || additions.any?
     end
 
@@ -1324,7 +1428,7 @@ module BaconTracker
       with_decisions_lock do
         heal_proposed!
         id   = format_decision_id(consume_decision_id)
-        slug = filename_slug(title) # never "<id>-.md", which is not a record
+        slug = slugify(title) # never "<id>-.md", which is not a record (EMPTY_SLUG)
         template_path = File.join(root, '_template.md')
         body = File.exist?(template_path) ? File.read(template_path, encoding: 'utf-8') : Templates::DECISION
         today = Date.today.iso8601
@@ -1550,7 +1654,11 @@ module BaconTracker
     # same set the `story:edit` task parses. A field-validation failure is
     # reported against the just-created story so its ID isn't lost.
     def create(kind, title, fields = {})
-      story = create_story(kind, title)
+      fields = fields.dup
+      # The size goes through create_story, which validates it before an ID is
+      # consumed (BT-184): a refused size leaves no unsized story behind. The
+      # remaining fields are set afterwards, as before.
+      story = create_story(kind, title, size: fields.delete(:size))
       path  =
         if fields.empty?
           story[:path]
@@ -1647,8 +1755,11 @@ module BaconTracker
           [{}, content]
         end
 
-      raw_size = fm['size']&.to_s&.upcase
-      size = %w[S M L].include?(raw_size) ? raw_size : nil
+      # declared_size is the value as written; size is nil unless it is one
+      # the tracker knows, and story:lint reports the difference (BT-184).
+      declared_size = fm['size']&.to_s&.strip
+      declared_size = nil if declared_size&.empty?
+      size = declared_size && SIZES.include?(declared_size.upcase) ? declared_size.upcase : nil
 
       blocked_by = decision_refs(fm['blocked_by'])
       linked_to  = decision_refs(fm['linked_to'])
@@ -1660,12 +1771,12 @@ module BaconTracker
       subtasks = subtask_counts(body, ext)
 
       { id: id, type: dir_meta[:type], stage: dir_meta[:stage], dir: dir_meta[:dir],
-        path: path, title: humanize_slug(path), body: body, size: size,
+        path: path, title: story_title(body, ext) || humanize_slug(path), body: body, size: size,
         blocked_by: blocked_by, linked_to: linked_to, assignee: assignee, subtasks: subtasks,
         # Body-line addresses of the subtasks - the client renders/toggles by
         # these instead of re-deriving fence rules (the BT-049 drift class).
         subtask_lines: st_lines.empty? ? nil : st_lines,
-        declared_status: fm['status']&.to_s }
+        declared_status: fm['status']&.to_s, declared_size: declared_size }
     end
 
     # Indices of body lines that are subtasks, skipping fenced content
@@ -1851,7 +1962,7 @@ module BaconTracker
       with_lock do
         id_num = consume_id
         id     = format_id(id_num)
-        slug   = filename_slug(title)
+        slug   = slugify(title)
 
         filename = "#{id}-#{slug}#{ext}"
         dest_dir = File.join(@config.tracker_root, dir, stage)
@@ -1865,13 +1976,8 @@ module BaconTracker
                    else
                      Templates.for(ext, kind)
                    end
-        filled = if ext == '.feature'
-                   template.sub('Name the Feature') { title }
-                 else
-                   template.sub(/\ATitle:.*/) { "Title: #{title}" }
-                 end
         fm      = kind == 'feature' ? frontmatter_feature(id, kind, status) : frontmatter_md(id, kind, status)
-        content = fm + filled
+        content = fm + fill_template(template, ext, title)
 
         atomic_write(dest, content)
         backlog_add(id, dest) if stage == '2_backlog'
@@ -1881,6 +1987,52 @@ module BaconTracker
       end
     end
 
+    # The body of a new story: the template without any header block of its
+    # own, with the title filled into its first Title:/Feature: line. A
+    # template that starts with a header (id/type/status, a placeholder id)
+    # used to be copied as is, so the new story carried two headers and the
+    # template's placeholder title (BT-185). A template without a title line
+    # gets one, so the title as typed always reaches the file.
+    def fill_template(template, ext, title)
+      body = strip_template_header(template)
+      line = ext == '.feature' ? 'Feature' : 'Title'
+      if body.match?(/^#{line}:.*$/)
+        body.sub(/^#{line}:.*$/) { "#{line}: #{title}" }
+      else
+        "#{line}: #{title}\n\n#{body}"
+      end
+    end
+
+    # The header block a template starts with, if any - a YAML '---' block in
+    # either dialect, or the '# key: value' lines of a .feature. Returns the
+    # body after it (leading blank lines dropped), or the template unchanged.
+    def strip_template_header(template)
+      if template.start_with?("---\n")
+        close = template.index(/^---\n/, 4)
+        close ? template[(close + 4)..].lstrip : template
+      elsif template.match?(/\A#{FEATURE_HEADER}/)
+        template.lines.drop_while { |l| l.match?(FEATURE_HEADER) }.join.lstrip
+      else
+        template
+      end
+    end
+
+    # Story templates that start with a header block of their own (BT-185).
+    # create_story drops it, but the /tracker command's file steps and anyone
+    # copying the template by hand would not, so story:lint points it out and
+    # the project can take it out of the template.
+    def template_headers
+      STORY_DIRS.filter_map do |dir, m|
+        path = File.join(@config.tracker_root, dir, "_template#{m[:ext]}")
+        next unless File.exist?(path)
+
+        template = File.read(path, encoding: 'utf-8')
+        next if strip_template_header(template).equal?(template)
+
+        { path: path, dir: dir }
+      end
+    end
+
     def delete_story(id)
       with_lock do
         result = find_story(id)
@@ -1942,8 +2094,12 @@ module BaconTracker
       if title
         content = if ext == '.feature'
                     content.sub(/^Feature: .+/) { "Feature: #{title}" }
-                  else
+                  elsif content.match?(/^Title: .+/)
                     content.sub(/^Title: .+/) { "Title: #{title}" }
+                  else
+                    # A story titled by its opening heading (BT-183) is retitled
+                    # in that heading, so the card keeps following the file.
+                    retitle_leading_heading(content, title)
                   end
       end
 
@@ -1975,15 +2131,17 @@ module BaconTracker
 
       if title || body || !size.nil? || !blocked_by.nil? || !linked_to.nil? || !assignee.nil?
         atomic_write(path, content)
-        new_path = title ? File.join(File.dirname(path), "#{id}-#{filename_slug(title)}#{ext}") : path
+        new_path = title ? File.join(File.dirname(path), "#{id}-#{slugify(title)}#{ext}") : path
         if path != new_path
           FileUtils.mv(path, new_path)
           path = new_path
-          if result[:stage] == '2_backlog' && File.exist?(@config.backlog_path)
-            lines = File.readlines(@config.backlog_path, encoding: 'utf-8')
-            atomic_write(@config.backlog_path,
-                         lines.map { |l| backlog_line_id(l) == id ? "- #{id} #{title}\n" : l }.join)
-          end
+        end
+        # The backlog line follows the title even when the slug, and so the
+        # filename, did not change ("Fix bug" -> "Fix bug!") - BT-186.
+        if title && result[:stage] == '2_backlog' && File.exist?(@config.backlog_path)
+          lines = File.readlines(@config.backlog_path, encoding: 'utf-8')
+          atomic_write(@config.backlog_path,
+                       lines.map { |l| backlog_line_id(l) == id ? "- #{id} #{title}\n" : l }.join)
         end
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bacon-tracker
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Alex Berger