specfuse-loop 0.31.1__tar.gz → 0.32.0__tar.gz

{specfuse_loop-0.31.1/specfuse_loop.egg-info → specfuse_loop-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.31.1
+Version: 0.32.0
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0

{specfuse_loop-0.31.1 → specfuse_loop-0.32.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.31.1"
+version = "0.32.0"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"

{specfuse_loop-0.31.1 → specfuse_loop-0.32.0}/specfuse/loop/arm_eval.py

@@ -110,6 +110,8 @@ JUDGE_MODULES = tuple(
         "closing_requirements.py",
         "criteria_state.py",
         "lint_closing.py",
+        "changelog.py",          # its parser is how close-k, lint --closing and the auto-close guard read Unreleased
+        "changelog_fragments.py",  # the one reader/writer of changelog entries the close guards read
         "lint_plan.py",
         "ids.py",                # supplies lint_plan's CORRELATION_ID_RE; an edit changes what the close's lint accepts
         "plan_baseline.py",      # the baseline retroactive_edits compares to
@@ -144,7 +146,6 @@ NON_JUDGE_MODULES = {
     "caller_check.py": "reports public symbols whose only callers are "
         "tests; a hygiene report, grants no verdict and no arm/close/"
         "merge decision reads it",
-    "changelog.py": "parses and stamps CHANGELOG.md; no gate reads it",
     "decisions_format.py": "parses DECISIONS.md into entries; not on the "
         "arm/close/merge judge path — T02/T03 own the lint that reads it",
     "driver_edit.py": "applies operator edits to a feature folder",

specfuse_loop-0.32.0/specfuse/loop/changelog_fragments.py

@@ -0,0 +1,232 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""Changelog fragments — FEAT-LOOP-2026-0249.
+
+One writer for changelog entries. `add` routes by `changelog.mode` in
+`.specfuse/layout.yml`: `fragments` writes `changelog.d/<trace>-<slug>.md`
+(so concurrent PRs never touch the same file), `single` (the default) appends
+to `CHANGELOG.md` through `changelog.append_entry`.
+
+    python3 -m specfuse.loop.changelog_fragments add --class C --trace T --summary S [--repo DIR]
+    python3 -m specfuse.loop.changelog_fragments collate [--repo DIR]
+    python3 -m specfuse.loop.changelog_fragments check [--repo DIR]
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from specfuse.loop import layout
+from specfuse.loop.changelog import (
+    _TRACE_RE,
+    ENTRY_CLASSES,
+    ChangelogEntry,
+    append_entry,
+    parse_changelog,
+)
+
+FRAGMENT_DIR = "changelog.d"
+CHANGELOG_FILE = "CHANGELOG.md"
+_SLUG_MAX = 40
+
+
+def normalize_trace(trace: str) -> str:
+    """`#3563` -> `3563`, `FEAT-X/T01` -> `FEAT-X-T01`."""
+    return trace.lstrip("#").replace("/", "-")
+
+
+def slugify(summary: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", summary.lower()).strip("-")[:_SLUG_MAX].strip("-")
+    return slug or "entry"
+
+
+def _validate(entry_class: str, trace: str, summary: str) -> None:
+    if entry_class not in ENTRY_CLASSES:
+        raise ValueError(
+            f"unrecognised entry class {entry_class!r} — must be one of "
+            f"{', '.join(ENTRY_CLASSES)}"
+        )
+    if not _TRACE_RE.match(trace):
+        raise ValueError(f"trace {trace!r} is not a FEAT-YYYY-NNNN or #<issue-number> trace")
+    if not summary.strip():
+        raise ValueError("summary must not be empty")
+    if "\n" in summary or "\r" in summary:
+        raise ValueError("summary must be a single line")
+
+
+def read_fragment(path) -> ChangelogEntry | None:
+    """The entry one fragment file carries, or None when it is not a valid fragment.
+
+    Frontmatter is read line by line, not through `_miniyaml`: `trace: #101`
+    is a comment to a YAML reader. Never raises on a malformed file.
+    """
+    try:
+        lines = Path(path).read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError):
+        return None
+    if not lines or lines[0].strip() != "---":
+        return None
+    try:
+        end = next(i for i in range(1, len(lines)) if lines[i].strip() == "---")
+    except StopIteration:
+        return None
+    fields: dict[str, str] = {}
+    for line in lines[1:end]:
+        key, sep, value = line.partition(":")
+        if not sep:
+            return None
+        fields[key.strip()] = value.strip()
+    entry_class, trace = fields.get("class", ""), fields.get("trace", "")
+    body = [ln.strip() for ln in lines[end + 1:] if ln.strip()]
+    if entry_class not in ENTRY_CLASSES or not _TRACE_RE.match(trace) or len(body) != 1:
+        return None
+    return ChangelogEntry(entry_class=entry_class, summary=body[0], trace=trace, line=end + 2)
+
+
+def fragment_entries(repo_root) -> list:
+    """Every valid fragment's entry under `changelog.d/`; malformed files are skipped."""
+    directory = Path(repo_root) / FRAGMENT_DIR
+    if not directory.is_dir():
+        return []
+    found = (read_fragment(p) for p in sorted(directory.glob("*.md")))
+    return [entry for entry in found if entry is not None]
+
+
+def add(repo_root, *, entry_class: str, trace: str, summary: str) -> Path:
+    """Write one entry in the project's mode; return the file written."""
+    _validate(entry_class, trace, summary)
+    summary = summary.strip()
+    root = Path(repo_root)
+    if layout.load(root).changelog.mode == "fragments":
+        target = root / FRAGMENT_DIR / f"{normalize_trace(trace)}-{slugify(summary)}.md"
+        if target.exists():
+            raise ValueError(f"{target.relative_to(root).as_posix()} already exists")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(
+            f"---\nclass: {entry_class}\ntrace: {trace}\n---\n{summary}\n", encoding="utf-8"
+        )
+        return target
+    path = root / CHANGELOG_FILE
+    if not path.is_file():
+        raise ValueError(f"{CHANGELOG_FILE} not found in {root}")
+    text = path.read_text(encoding="utf-8")
+    path.write_text(
+        append_entry(text, entry_class=entry_class, summary=summary, trace=trace),
+        encoding="utf-8",
+    )
+    return path
+
+
+def invalid_fragments(repo_root) -> list:
+    """One message per malformed fragment under `changelog.d/`, each naming the file."""
+    directory = Path(repo_root) / FRAGMENT_DIR
+    paths = sorted(directory.glob("*.md")) if directory.is_dir() else []
+    return [
+        f"{FRAGMENT_DIR}/{path.name} is not a valid fragment — expected "
+        "`class:` and `trace:` frontmatter and a single-line summary"
+        for path in paths
+        if read_fragment(path) is None
+    ]
+
+
+def collate_text(repo_root, text: str) -> tuple:
+    """Fold every fragment into `text`'s `Unreleased`; return `(new_text, fragment_paths)`.
+
+    Fragments fold in sorted filename order through `append_entry`. Writes and
+    deletes nothing: any malformed fragment, or a result that does not parse
+    clean, raises `ValueError` naming the file, so the caller's tree is untouched.
+    """
+    directory = Path(repo_root) / FRAGMENT_DIR
+    paths = sorted(directory.glob("*.md")) if directory.is_dir() else []
+    problems = invalid_fragments(repo_root)
+    if problems:
+        raise ValueError(problems[0])
+    for path in paths:
+        entry = read_fragment(path)
+        text = append_entry(
+            text, entry_class=entry.entry_class, summary=entry.summary, trace=entry.trace
+        )
+    if paths:
+        result = parse_changelog(text)
+        if not result.ok:
+            raise ValueError(
+                f"collating {FRAGMENT_DIR}/ leaves {CHANGELOG_FILE} unparseable: "
+                + "; ".join(str(f) for f in result.findings)
+            )
+    return text, paths
+
+
+def remove_fragments(paths) -> None:
+    """Delete consumed fragments; drop `changelog.d/` when it is left empty."""
+    parents = {Path(p).parent for p in paths}
+    for path in paths:
+        Path(path).unlink()
+    for parent in parents:
+        try:
+            parent.rmdir()
+        except OSError:
+            pass
+
+
+def collate(repo_root) -> list:
+    """Fold fragments into `CHANGELOG.md` and delete them; return the fragment paths."""
+    path = Path(repo_root) / CHANGELOG_FILE
+    if not path.is_file():
+        raise ValueError(f"{CHANGELOG_FILE} not found in {repo_root}")
+    new_text, paths = collate_text(repo_root, path.read_text(encoding="utf-8"))
+    if paths:
+        path.write_text(new_text, encoding="utf-8")
+        remove_fragments(paths)
+    return paths
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="specfuse.loop.changelog_fragments", description="Write changelog entries."
+    )
+    parser.add_argument("--repo", default=".", help="repository root (default: cwd)")
+    sub = parser.add_subparsers(dest="command", required=True)
+    addp = sub.add_parser("add", help="write one changelog entry in the project's mode")
+    addp.add_argument("--class", dest="entry_class", required=True)
+    addp.add_argument("--trace", required=True)
+    addp.add_argument("--summary", required=True)
+    sub.add_parser("collate", help="fold changelog.d/ fragments into CHANGELOG.md and delete them")
+    sub.add_parser("check", help="fail when any changelog.d/ fragment is malformed")
+    args = parser.parse_args(argv)
+
+    if args.command == "check":
+        problems = invalid_fragments(args.repo)
+        for problem in problems:
+            print(problem, file=sys.stderr)
+        return 2 if problems else 0
+
+    if args.command == "collate":
+        try:
+            folded = collate(args.repo)
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            return 2
+        print(f"collated {len(folded)} fragment(s)")
+        return 0
+
+    try:
+        target = add(
+            args.repo,
+            entry_class=args.entry_class,
+            trace=args.trace,
+            summary=args.summary,
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    print(target)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{specfuse_loop-0.31.1 → specfuse_loop-0.32.0}/specfuse/loop/closing_requirements.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import Optional
 
 # --------------------------------------------------------------------------- #
@@ -232,6 +233,35 @@ def changelog_has_entry_for(unreleased_entries, feature_id: str) -> bool:
     )
 
 
+def changelog_exists(repo_root) -> bool:
+    """True if the project has a changelog in either form: `CHANGELOG.md` or `changelog.d/*.md`."""
+    root = Path(repo_root)
+    return (root / CHANGELOG_PATH).exists() or any((root / "changelog.d").glob("*.md"))
+
+
+def changelog_has_entry_for_feature(repo_root, feature_id: str) -> bool:
+    """True if *feature_id* has an entry in `CHANGELOG.md`'s Unreleased section or a valid fragment.
+
+    The one reader behind close-k, `lint --closing` and the auto-close guard
+    (FEAT-LOOP-2026-0249). Both forms are read in every mode. A missing or
+    unparseable changelog and a malformed fragment count as no entry; this
+    never raises.
+    """
+    from . import changelog_fragments
+    from .changelog import parse_changelog
+
+    root = Path(repo_root)
+    entries = list(changelog_fragments.fragment_entries(root))
+    changelog = root / CHANGELOG_PATH
+    if changelog.is_file():
+        try:
+            unreleased = parse_changelog(changelog.read_text(encoding="utf-8")).unreleased()
+        except Exception:  # noqa: BLE001 - a guard reports a gap, never crashes on one
+            unreleased = None
+        entries += unreleased.entries if unreleased else []
+    return changelog_has_entry_for(entries, feature_id)
+
+
 # --------------------------------------------------------------------------- #
 # Requirement records                                                         #
 # --------------------------------------------------------------------------- #
@@ -354,8 +384,8 @@ CLOSING_REQUIREMENTS: dict[str, list[Requirement]] = {
             description=(
                 f"When the '{CONSUMER_VISIBLE_HEADING}' section (close-discipline.md "
                 f"§3) is not the '{CONSUMER_VISIBLE_NA_PHRASE}' line, "
-                f"{CHANGELOG_PATH}'s Unreleased section gains an entry carrying "
-                "this feature's FEAT-ID — the same enumeration §3 already "
+                f"{CHANGELOG_PATH}'s Unreleased section or a valid changelog.d/ "
+                "fragment gains an entry carrying this feature's FEAT-ID — the same enumeration §3 already "
                 "requires, appended where a consumer reads it, not re-derived"
             ),
             file=RETROSPECTIVE_FILENAME,

specfuse_loop-0.32.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.32.0

{specfuse_loop-0.31.1 → specfuse_loop-0.32.0}/specfuse/loop/data/docs/lifecycles.md

@@ -175,6 +175,18 @@ hit stops the branch rather than shipping feature-scoped work as a bug fix.
 **The `CHANGELOG.md` entry is written here or nowhere.** Bugs have no close
 ceremony to collect through, so `/fix-bug` is the collection point.
 
+`/fix-bug` records the entry with `python3 -m specfuse.loop.changelog_fragments add`
+(trace `#<issue-number>`) and commits what it wrote with the fix.
+
+**Opting in to fragments.** By default entries append to `CHANGELOG.md`. To
+stop concurrent PRs colliding on that file, set `changelog.mode: fragments` in
+`.specfuse/layout.yml`; `add` then writes one `changelog.d/<trace>-<slug>.md`
+per entry. Add `python3 -m specfuse.loop.changelog_fragments check` as a gate
+in `.specfuse/verification.yml` to fail on malformed fragments. A custom
+release script must run `python3 -m specfuse.loop.changelog_fragments collate`
+before stamping the release, so fragments fold into `CHANGELOG.md` and are
+deleted first.
+
 ---
 
 ## 3. The autonomous lifecycle

{specfuse_loop-0.31.1 → specfuse_loop-0.32.0}/specfuse/loop/data/rules/close-discipline.md

@@ -138,18 +138,19 @@ A close carrying this obligation is always load-bearing
 (`auto_close_disabled: true`).
 
 **Also append it to `CHANGELOG.md`'s `Unreleased` section (FEAT-2026-0064).**
-When this section is a real enumeration — not the `n/a` line — the close
-appends each item to `Unreleased`, classified `added` / `changed` / `fixed` /
-`breaking` and carrying the feature's `FEAT-YYYY-NNNN` ID, via
-`specfuse/loop/changelog.py`'s schema. **This is the same material the
+When this section is a real enumeration — not the `n/a` line — run one
+`python3 -m specfuse.loop.changelog_fragments add --class <class> --trace <FEAT-ID> --summary '<line>'`
+per enumerated item, classified `added` / `changed` / `fixed` / `breaking`,
+with the feature's `FEAT-YYYY-NNNN` ID as trace. Never hand-edit; `add`
+routes by the project's `changelog.mode`. **This is the same material the
 paragraph above already requires you to write, put where a consumer will
 read it — not a second write.** An author who treats the changelog append as
 new work will write the enumeration twice, badly; write it once, in both
 places, from the same understanding. `closing_requirements.py`'s `close-k`
 requirement (enforced by `assert_changelog_entry_for_contract_changes` in
 `loop.py`, and pre-squash by `specfuse lint --closing`) fires when this
-section names a real change and `Unreleased` gained no entry tracing to this
-feature's FEAT-ID.
+section names a real change and no entry tracing to this feature's FEAT-ID
+lives in `CHANGELOG.md` or a `changelog.d/` fragment.
 
 **An `n/a` close appends nothing to `Unreleased`, and that is correct.** A
 changelog padded with "no user-facing change" entries is noise that trains

{specfuse_loop-0.31.1 → specfuse_loop-0.32.0}/specfuse/loop/ids.py

@@ -399,7 +399,10 @@ def _rewrite_file(rel, text, renames, include_prose, plan, folders=()):
     is_changelog = rel == "CHANGELOG.md"
     lines = text.splitlines(keepends=True)
     bare = [ln.rstrip("\r\n") for ln in lines]
-    fm_end = _frontmatter_end(bare) if is_md and in_features else -1
+    # A changelog.d/ fragment is unreleased by definition: its `trace:` frontmatter
+    # is structural, so it follows the rename (the filename stays; frontmatter wins).
+    is_fragment = is_md and rel.startswith("changelog.d/")
+    fm_end = _frontmatter_end(bare) if is_md and (in_features or is_fragment) else -1
     graph = _task_graph_lines(bare) if name == "PLAN.md" and in_features else set()
     span = _unreleased_span(bare) if is_changelog else None
     if is_changelog and span is None:

{specfuse_loop-0.31.1 → specfuse_loop-0.32.0}/specfuse/loop/layout.py

@@ -6,7 +6,8 @@
 """Project layout resolver — FEAT-2026-0224 (project-configurable layout).
 
 Reads an optional `.specfuse/layout.yml` and answers `layout get <key>` for
-`decisions.style`, `decisions.location`, `decisions.link` and `ids.key`.
+`decisions.style`, `decisions.location`, `decisions.link`, `decisions.entryKey`
+and `ids.key`.
 
 Contract: no file (or no `decisions:` block) means today's behaviour — style
 `adr`, location `docs/adr`, link `{path}`. An `entries` style with `location`
@@ -41,12 +42,23 @@ _STYLE_DEFAULTS = {
 }
 _FALLBACK_DEFAULTS = _STYLE_DEFAULTS["adr"]
 
-KEYS = ("decisions.style", "decisions.location", "decisions.link", "ids.key")
+KEYS = (
+    "decisions.style",
+    "decisions.location",
+    "decisions.link",
+    "decisions.entryKey",
+    "ids.key",
+    "changelog.mode",
+)
+
+DEFAULT_CHANGELOG_MODE = "single"
+VALID_CHANGELOG_MODES = ("single", "fragments")
 
 VALID_STYLES = ("adr", "entries")
 LINK_PLACEHOLDERS = ("location", "path", "id", "domain")
-KNOWN_TOP_LEVEL = ("decisions", "ids")
+KNOWN_TOP_LEVEL = ("decisions", "ids", "changelog")
 _PLACEHOLDER_RE = re.compile(r"\{([^{}]*)\}")
+_ENTRY_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*$")
 _DRIVE_RE = re.compile(r"^[A-Za-z]:")
 
 
@@ -55,6 +67,7 @@ class Decisions:
     style: str
     location: str
     link: str
+    entry_key: Optional[str] = None
 
 
 @dataclass(frozen=True)
@@ -62,10 +75,16 @@ class Ids:
     key: Optional[str] = None
 
 
+@dataclass(frozen=True)
+class Changelog:
+    mode: str = DEFAULT_CHANGELOG_MODE
+
+
 @dataclass(frozen=True)
 class Layout:
     decisions: Decisions
     ids: Ids = Ids()
+    changelog: Changelog = Changelog()
 
 
 def _normalise(location: str) -> str:
@@ -81,10 +100,12 @@ def _resolve_decisions(block: Optional[dict]) -> Decisions:
     default_location, default_link = _STYLE_DEFAULTS.get(style, _FALLBACK_DEFAULTS)
     location = block.get("location")
     link = block.get("link")
+    entry_key = block.get("entryKey")
     return Decisions(
         style=style,
         location=default_location if location is None else _normalise(str(location)),
         link=default_link if link is None else str(link),
+        entry_key=None if entry_key is None else str(entry_key),
     )
 
 
@@ -104,9 +125,12 @@ def load(repo_root) -> Layout:
     block = data.get("decisions") if isinstance(data, dict) else None
     ids_block = data.get("ids") if isinstance(data, dict) else None
     key = ids_block.get("key") if isinstance(ids_block, dict) else None
+    cl_block = data.get("changelog") if isinstance(data, dict) else None
+    mode = cl_block.get("mode") if isinstance(cl_block, dict) else None
     return Layout(
         decisions=_resolve_decisions(block if isinstance(block, dict) else None),
         ids=Ids(key=None if key is None else str(key)),
+        changelog=Changelog(mode=DEFAULT_CHANGELOG_MODE if mode is None else str(mode)),
     )
 
 
@@ -168,6 +192,17 @@ def validate(repo_root) -> list:
                 "(2-6 characters, upper-case letters and digits, starting with a letter)",
             )
 
+    cl_block = data.get("changelog")
+    if isinstance(cl_block, dict) and cl_block.get("mode") is not None:
+        mode = str(cl_block["mode"])
+        if mode not in VALID_CHANGELOG_MODES:
+            add(
+                SEVERITY_ERROR,
+                "mode",
+                f"changelog.mode {mode!r} is invalid; must be one of "
+                f"{VALID_CHANGELOG_MODES[0]!r} or {VALID_CHANGELOG_MODES[1]!r}",
+            )
+
     block = data.get("decisions")
     if not isinstance(block, dict):
         return findings
@@ -227,6 +262,18 @@ def validate(repo_root) -> list:
                     f"decisions.link placeholder '{{{name}}}' is not allowed; "
                     "use {location}, {path}, {id} or {domain}",
                 )
+
+    entry_key = block.get("entryKey")
+    if entry_key is not None:
+        if not _ENTRY_KEY_RE.match(str(entry_key)):
+            add(
+                SEVERITY_ERROR,
+                "entryKey",
+                f"decisions.entryKey {str(entry_key)!r} is invalid; must match "
+                f"{_ENTRY_KEY_RE.pattern}",
+            )
+        if style is None or str(style) != "entries":
+            add(SEVERITY_ERROR, "entryKey", "decisions.entryKey applies only to style 'entries'")
     return findings
 
 
@@ -239,6 +286,10 @@ def get(layout: Layout, key: str) -> str:
         raise KeyError(key)
     if key == "ids.key":
         return layout.ids.key or ""
+    if key == "changelog.mode":
+        return layout.changelog.mode
+    if key == "decisions.entryKey":
+        return layout.decisions.entry_key or ""
     return getattr(layout.decisions, key.split(".", 1)[1])
 
 

{specfuse_loop-0.31.1 → specfuse_loop-0.32.0}/specfuse/loop/lint_closing.py

@@ -28,7 +28,6 @@ from pathlib import Path
 from . import closing_requirements as creq
 from . import criteria_state
 from ._wu_sections import slice_wu_section
-from .changelog import parse_changelog
 from .judge import MEASUREMENTS_SECTION
 from .loop import (
     _gate_number_from_wu_id,
@@ -293,22 +292,18 @@ def _check_changelog_entry_for_contract_changes(req: creq.Requirement, ctx: Clos
         return True, ""
     if creq.consumer_visible_section_is_na(section):
         return True, ""
-    changelog = ctx.repo_root / creq.CHANGELOG_PATH
-    if not changelog.exists():
+    feature_id = ctx.wu_id.rsplit("/", 1)[0]
+    if creq.changelog_has_entry_for_feature(ctx.repo_root, feature_id):
+        return True, ""
+    if not creq.changelog_exists(ctx.repo_root):
         return False, (
             f"'{creq.CONSUMER_VISIBLE_HEADING}' names a real change but "
             f"{creq.CHANGELOG_PATH} does not exist"
         )
-    result = parse_changelog(changelog.read_text())
-    unreleased = result.unreleased()
-    feature_id = ctx.wu_id.rsplit("/", 1)[0]
-    entries = unreleased.entries if unreleased else []
-    if creq.changelog_has_entry_for(entries, feature_id):
-        return True, ""
     return False, (
-        f"'{creq.CONSUMER_VISIBLE_HEADING}' names a real change but "
-        f"{creq.CHANGELOG_PATH}'s Unreleased section has no entry tracing to "
-        f"{feature_id}"
+        f"'{creq.CONSUMER_VISIBLE_HEADING}' names a real change but neither "
+        f"{creq.CHANGELOG_PATH}'s Unreleased section nor a valid changelog.d/ "
+        f"fragment has an entry tracing to {feature_id}"
     )
 
 

{specfuse_loop-0.31.1 → specfuse_loop-0.32.0}/specfuse/loop/lint_roadmap.py

@@ -44,6 +44,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
 from urllib.parse import urlparse
+import json
 import re
 
 from specfuse.loop import ids as _ids
@@ -160,6 +161,7 @@ def _find_anchors(lines):
     return anchors
 
 
+_ENTRY_FILE_SUFFIXES = (".yaml", ".yml", ".json")
 _EXPLICIT_ANCHOR_RE = re.compile(r'<a\s+(?:id|name)\s*=\s*"([^"]+)"', re.IGNORECASE)
 _MD_HEADING_RE = re.compile(r'^ {0,3}#{1,6}\s+(.*?)\s*#*\s*$')
 
@@ -193,6 +195,58 @@ def _collect_anchor_names(text: str) -> set:
     return names
 
 
+def _json_entry_ids(value, entry_key: str) -> set:
+    """Every scalar `entry_key` value in a parsed JSON document, at any depth."""
+    ids = set()
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if key == entry_key and isinstance(item, (str, int)) and not isinstance(item, bool):
+                ids.add(str(item))
+            ids |= _json_entry_ids(item, entry_key)
+    elif isinstance(value, list):
+        for item in value:
+            ids |= _json_entry_ids(item, entry_key)
+    return ids
+
+
+def _collect_entry_ids(path: Path, entry_key: str):
+    """Ids a YAML or JSON decision file answers to, or None when it cannot be read (#3567).
+
+    YAML is scanned by line rather than parsed: `_miniyaml` refuses block scalars
+    and flow mappings by design, and decision files hold long rationale. A line
+    inside a block scalar that looks like the key therefore counts as an id, which
+    can only let a typo pass, never fail a good link.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+        if path.suffix == ".json":
+            return _json_entry_ids(json.loads(text), entry_key)
+    except (OSError, UnicodeDecodeError, ValueError):
+        return None
+    line_re = re.compile(
+        rf"""^\s*(?:-\s+)*["']?{re.escape(entry_key)}["']?\s*:\s+"""
+        r"""(?:"([^"]*)"|'([^']*)'|([^\s#"'][^#]*?))\s*(?:\#.*)?$"""
+    )
+    ids = set()
+    for line in text.splitlines():
+        m = line_re.match(line)
+        if m:
+            ids.add(next(group for group in m.groups() if group is not None))
+    return ids
+
+
+def _entry_anchor_problem(target: Path, link_path: str, fragment: str, entry_key: str):
+    """Why `fragment` does not resolve in a YAML or JSON decision file, or None."""
+    ids = _collect_entry_ids(target, entry_key)
+    if ids is None:
+        return f"'{link_path}', which could not be read as YAML or JSON"
+    if not ids:
+        return f"'{link_path}', which has no entries under entryKey '{entry_key}'"
+    if fragment not in ids:
+        return f"'{link_path}', which has no anchor '{fragment}'"
+    return None
+
+
 def _declared_decisions_location(repo_root: Path):
     """Resolved `decisions.location` only when layout.yml declares a `decisions:` block."""
     data = _layout._read(repo_root / _layout.LAYOUT_RELPATH)
@@ -419,6 +473,7 @@ def _find_blocked_by(section, lines):
 def _check_blocked_by(roadmap_doc: _FileDoc, archive_doc: _FileDoc, rows, repo_root: Path) -> list:
     findings = []
     declared_location = _declared_decisions_location(repo_root)
+    entry_key = _layout.load(repo_root).decisions.entry_key
     roadmap_sections = _detail_sections(roadmap_doc.lines)
     archive_sections = _detail_sections(archive_doc.lines)
 
@@ -488,6 +543,16 @@ def _check_blocked_by(roadmap_doc: _FileDoc, archive_doc: _FileDoc, rows, repo_r
                             f"{row['id']}'s Blocked-by link '{href}' points at "
                             f"'{link_path}', which has no anchor '{fragment}'",
                         ))
+                elif (
+                    fragment and entry_key and target.is_file()
+                    and target.suffix in _ENTRY_FILE_SUFFIXES
+                ):
+                    problem = _entry_anchor_problem(target, link_path, fragment, entry_key)
+                    if problem:
+                        findings.append(Finding(
+                            SEVERITY_ERROR, doc.filename, blocked_by_line + 1,
+                            f"{row['id']}'s Blocked-by link '{href}' points at {problem}",
+                        ))
                 if declared_location is not None:
                     location = (repo_root / declared_location).resolve()
                     try: