bmad-module-ultracode-goal 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/README.md +12 -4
  3. package/docs/_internal/RELEASING.md +3 -2
  4. package/docs/architecture.md +6 -6
  5. package/docs/comparison.md +25 -25
  6. package/docs/gate-model.md +1 -1
  7. package/docs/getting-started.md +9 -5
  8. package/docs/how-it-works.md +5 -5
  9. package/docs/index.md +1 -1
  10. package/docs/operating-tips.md +1 -1
  11. package/docs/troubleshooting.md +6 -3
  12. package/docs/why-ultracode-goal.md +3 -3
  13. package/package.json +6 -2
  14. package/skills/ucg-formalize/SKILL.md +11 -4
  15. package/skills/ucg-resolve/SKILL.md +4 -4
  16. package/skills/ucg-status/SKILL.md +21 -8
  17. package/skills/ultracode-goal/SKILL.md +4 -4
  18. package/skills/ultracode-goal/assets/module.yaml +1 -1
  19. package/skills/ultracode-goal/references/define-done.md +3 -1
  20. package/skills/ultracode-goal/references/execute.md +16 -16
  21. package/skills/ultracode-goal/references/finalize.md +6 -5
  22. package/skills/ultracode-goal/references/gate.md +18 -12
  23. package/skills/ultracode-goal/references/preflight.md +20 -12
  24. package/skills/ultracode-goal/scripts/drive_epic.py +11 -6
  25. package/skills/ultracode-goal/scripts/gate_trail.py +107 -18
  26. package/skills/ultracode-goal/scripts/headless_envelope.py +20 -6
  27. package/skills/ultracode-goal/scripts/hooks/budget_stop.py +41 -22
  28. package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +26 -6
  29. package/skills/ultracode-goal/scripts/preflight_check.py +237 -12
  30. package/skills/ultracode-goal/scripts/status_render.py +96 -19
  31. package/tools/cli/lib/platform-codes.yaml +1 -1
  32. package/tools/cli/lib/ui.js +1 -1
  33. package/tools/validate-docs-links.js +302 -29
@@ -6,19 +6,22 @@
6
6
  """Render what a run is doing, out of the files that run already produced.
7
7
 
8
8
  This is the READ side over the spine's own artifacts. It answers "what is this
9
- run doing right now" from five sources and nothing else:
9
+ run doing right now" from six sources and nothing else:
10
10
 
11
11
  | what | source |
12
12
  | heartbeat | <impl-artifacts>/run-status.json |
13
13
  | decision log tail | the run folder's .decision-log.md |
14
14
  | ledger | the deferred-work ledger |
15
15
  | escalations | .escalation-<story>.md and escalation-<story>.json|
16
+ | advanced stories | <impl-artifacts>/sprint-status.yaml `done` rows |
16
17
  | runs index | the runs root's per-run folders |
17
18
 
18
19
  STRICTLY READ-ONLY. It starts no run, attaches to no session, and opens no file
19
- for output. The one process it starts is the `which` probe for the optional
20
- diff-viewer affordance below, and that probe's result reaches stdout only - it
21
- is never recorded anywhere. Everything else is a read. That property is what
20
+ for output. The processes it starts are read-only and serve the optional
21
+ diff-viewer affordance below: the `which` probe, and, only when the viewer is
22
+ present and the repository reads, one `git log` per story listing the commits in
23
+ its range (through `gate_trail._git_log`). Their results reach stdout only and
24
+ are never recorded anywhere. Everything else is a read. That property is what
22
25
  makes this safe to run against a LIVE run: a status read that touched the
23
26
  artifacts would be a status read that changed the thing it reports on.
24
27
 
@@ -53,6 +56,7 @@ from pathlib import Path
53
56
  sys.path.insert(0, str(Path(__file__).resolve().parent))
54
57
 
55
58
  import gate_trail # noqa: E402 (sibling script, path set above)
59
+ import preflight_check # noqa: E402 (sibling script, path set above)
56
60
 
57
61
  # Rendered wherever a source was absent, empty or unreadable.
58
62
  NA = "n/a"
@@ -61,10 +65,16 @@ NA = "n/a"
61
65
  # hook-maintained turn counter carry it.
62
66
  MACHINE = "[machine-derived]"
63
67
 
64
- # The residual a session leaves when it died between the Stop hook's write and
65
- # Execute's promotion of that marker into the typed sidecar. The marker is real
66
- # evidence of a real escalation; it just never got typed.
67
- UNPROMOTED = "escalation (unpromoted: session ended before Execute promoted it)"
68
+ # A raw Stop-hook marker with no typed sidecar beside it, for a story that has
69
+ # not advanced. Either its gate has not ruled yet (Execute promotes the marker
70
+ # only when the gate escalates the story on its turn count), or the session
71
+ # died before Execute promoted it. Either way it may be a pending escalation.
72
+ UNPROMOTED = "escalation (unpromoted: no gate verdict yet, or the session ended before Execute promoted it)"
73
+
74
+ # The same raw marker for a story whose gate advanced it. Execute never promotes
75
+ # that one: the gate decided completion, and the overrun is a sizing note in the
76
+ # decision log, so nothing is pending and it is not listed as an escalation.
77
+ CEILING_NOTE = "turn ceiling reached; the story advanced at its gate, so this is a sizing note and nothing is pending"
68
78
 
69
79
  # The other thin record: the typed sidecar IS on disk but is empty or does not
70
80
  # parse, so there is nothing to render out of it. Distinct from UNPROMOTED
@@ -78,8 +88,10 @@ SIDECAR_FIELDS = ("kind", "source", "decision_needed", "evidence")
78
88
 
79
89
  # The optional diff viewer. Absent, nothing about it is rendered and the render
80
90
  # is otherwise unchanged; present, each story that recorded a baseline commit
81
- # gains one copy-paste line. It is an affordance, never a dependency.
91
+ # gains a copy-paste line per commit in its range. It is an affordance, never a
92
+ # dependency.
82
93
  VIEWER = "hunk"
94
+ MAX_VIEWER_LINES = 10
83
95
 
84
96
 
85
97
  # --------------------------------------------------------------------------
@@ -252,6 +264,39 @@ def escalations(impl: Path) -> list[tuple[str, dict | None, Path]]:
252
264
  return [(story, payload, path) for story, (payload, path) in sorted(found.items())]
253
265
 
254
266
 
267
+ def done_stories(impl: Path) -> set[str]:
268
+ """Story keys whose `sprint-status.yaml` row reads `done`.
269
+
270
+ The gate's advance route writes `done` for every story it advances, and the
271
+ row outlives the heartbeat: `run-status.json` lists in-scope stories only, so
272
+ a later invocation's snapshot no longer carries a story an earlier one
273
+ advanced. Read with preflight's own block-scoped parser, so both agree.
274
+ """
275
+ text = read_text(impl / "sprint-status.yaml")
276
+ if not text:
277
+ return set()
278
+ statuses = preflight_check._parse_development_status(text)
279
+ return {key for key, value in statuses.items() if value == "done"}
280
+
281
+
282
+ def advanced_stories(status: dict | None, impl: Path) -> set[str]:
283
+ """Stories the gate advanced: by this snapshot's verdict, or by a `done` row."""
284
+ return {
285
+ str(entry.get("story"))
286
+ for entry in story_entries(status)
287
+ if entry.get("story") and entry.get("verdict") in ("advance", "defer")
288
+ } | done_stories(impl)
289
+
290
+
291
+ def ceiling_note_only(impl: Path, story: str, advanced: set[str]) -> bool:
292
+ """True for an advanced story with the hook's raw marker and no typed sidecar."""
293
+ return (
294
+ story in advanced
295
+ and (impl / f".escalation-{story}.md").is_file()
296
+ and not (impl / f"escalation-{story}.json").exists()
297
+ )
298
+
299
+
255
300
  def known_runs(runs_root: Path | None) -> list[tuple[str, str]]:
256
301
  """Every run folder under the runs root, as (name, status).
257
302
 
@@ -329,6 +374,7 @@ def render(
329
374
  runs_root: Path | None,
330
375
  ledger: Path,
331
376
  viewer: bool,
377
+ repo: Path | None = None,
332
378
  ) -> str:
333
379
  """The whole render. Assembled once, printed once, written nowhere."""
334
380
  status_path = impl / "run-status.json"
@@ -371,7 +417,18 @@ def render(
371
417
  # Stories.
372
418
  lines.extend(["## Stories", ""])
373
419
  entries = story_entries(status)
374
- if not entries:
420
+ advanced = advanced_stories(status, impl)
421
+ # An advanced story a later invocation's heartbeat no longer lists still
422
+ # gets its note, on a line of its own after the listed stories.
423
+ listed = {str(entry.get("story")) for entry in entries}
424
+ unlisted_notes = [
425
+ f"- {story}: {CEILING_NOTE} (`{marker.name}`)"
426
+ for marker in sorted(impl.glob(".escalation-*.md"))
427
+ if (story := marker.name[len(".escalation-") : -len(".md")])
428
+ and story not in listed
429
+ and ceiling_note_only(impl, story, advanced)
430
+ ]
431
+ if not entries and not unlisted_notes:
375
432
  lines.append(f"- {NA}")
376
433
  for entry in entries:
377
434
  story = str(entry.get("story") or NA)
@@ -381,23 +438,42 @@ def render(
381
438
  f"attempts={entry.get('dev_attempts') if entry.get('dev_attempts') is not None else NA} "
382
439
  f"re-loops={entry.get('reloop_count') if entry.get('reloop_count') is not None else NA}"
383
440
  )
441
+ if ceiling_note_only(impl, story, advanced):
442
+ lines.append(f" - {CEILING_NOTE} (`.escalation-{story}.md`)")
384
443
  sha = gate_trail.baseline_sha(impl, story)
385
444
  if sha:
386
445
  lines.append(f" - baseline `{sha}`")
387
446
  if viewer:
388
- # The affordance has to point at THIS story's diff, so it shows
389
- # the end commit `.commit-<story>` records. The baseline is the
390
- # commit that preceded the story's work, so showing it renders
391
- # the previous story's diff - silently, since it is a real diff
392
- # from the same repo. Only where no end commit was recorded is
393
- # the anchor the sole sha there is to hand the reader.
394
- end = gate_trail.commit_sha(impl, story) or sha
395
- lines.append(f" - {VIEWER} show {end}")
447
+ # The affordance has to point at THIS story's diff. The baseline
448
+ # is the commit that preceded the story's work, so showing it
449
+ # renders the previous story's diff - silently, since it is a
450
+ # real diff from the same repo. The end commit `.commit-<story>`
451
+ # records is the gate's evidence commit once one was made, which
452
+ # holds the trace files and not the code, so where the repo is
453
+ # readable every commit in the story's range gets its own line.
454
+ # Only where no end commit was recorded is the anchor the sole
455
+ # sha there is to hand the reader.
456
+ # A range longer than a story ever needs (a baseline that is not
457
+ # an ancestor of the end commit, say) falls back to one line
458
+ # rather than printing hundreds.
459
+ end = gate_trail.commit_sha(impl, story)
460
+ in_range = gate_trail._git_log(repo, sha, end) if (repo and end) else None
461
+ if in_range and len(in_range) > MAX_VIEWER_LINES:
462
+ in_range = None
463
+ for commit in reversed(in_range or [end or sha]):
464
+ lines.append(f" - {VIEWER} show {commit}")
465
+ lines.extend(unlisted_notes)
396
466
  lines.append("")
397
467
 
398
468
  # Escalations.
399
469
  lines.extend(["## Escalations", ""])
400
- pending = escalations(impl)
470
+ # An advanced story's raw turn-ceiling marker is a sizing note, shown on its
471
+ # story row above, not a pending escalation.
472
+ pending = [
473
+ (story, payload, path)
474
+ for story, payload, path in escalations(impl)
475
+ if not ceiling_note_only(impl, story, advanced)
476
+ ]
401
477
  if not pending:
402
478
  lines.append(f"- {NA}")
403
479
  for story, payload, path in pending:
@@ -479,6 +555,7 @@ def main(argv: list[str] | None = None) -> int:
479
555
  runs_root=runs_root,
480
556
  ledger=ledger,
481
557
  viewer=viewer_available(),
558
+ repo=repo,
482
559
  ),
483
560
  end="",
484
561
  )
@@ -1,7 +1,7 @@
1
1
  # BMAD Platform Codes Configuration
2
2
  #
3
3
  # UltraCode Goal is Claude-Code-only: its autonomous run composes Claude Code
4
- # primitives (/goal, Auto Mode, Auto Memory, PreToolUse/Stop hooks, dynamic
4
+ # primitives (Auto Mode, Auto Memory, PreToolUse/Stop hooks, dynamic
5
5
  # workflows) that no other editor provides, so the installer targets Claude Code
6
6
  # and only Claude Code. This file stays config-driven (one entry) so the install
7
7
  # machinery has a single source of truth.
@@ -221,7 +221,7 @@ class UI {
221
221
  }
222
222
 
223
223
  // UCG is Claude-Code-only: its autonomous run composes Claude Code
224
- // primitives (/goal, Auto Mode, hooks, dynamic workflows) no other editor
224
+ // primitives (Auto Mode, hooks, dynamic workflows) no other editor
225
225
  // provides, so the skill installs to Claude Code with no IDE prompt.
226
226
  const ides = ['claude-code'];
227
227
  log.info(`The skill installs for ${brand.light('Claude Code')}.`);
@@ -17,11 +17,19 @@
17
17
  *
18
18
  * So there are two passes:
19
19
  *
20
- * 1. SOURCE (docs/ *.md) - a relative `.md` target must exist on disk.
21
- * Cheap, and catches a typo before a build is needed.
20
+ * 1. SOURCE (docs/ *.md, including docs/_internal/, plus CONTRIBUTING.md,
21
+ * README.md and, when present, changes/README.md) - every
22
+ * relative target must exist on disk, and every `#anchor`,
23
+ * same-file or on a `.md` target, must match a heading id in
24
+ * that file. Cheap, and catches a typo or a renamed heading
25
+ * before a build is needed.
22
26
  * 2. BUILT (build/site/ *.html) - every internal href must resolve to a
23
- * real file. This is the pass that catches plugin bugs, base-path
24
- * bugs, and anything else that only manifests as a route.
27
+ * real file, and its `#fragment` to an id on that page. This is
28
+ * the pass that catches plugin bugs, base-path bugs, and anything
29
+ * else that only manifests as a route.
30
+ *
31
+ * The heading-to-id rules live here, in `extractAnchors`, so every id the
32
+ * source pass checks is computed one way.
25
33
  *
26
34
  * The built pass is skipped with a warning when no build is present, so the
27
35
  * tool stays usable locally without a build step. CI builds the site, so the
@@ -112,6 +120,36 @@ function pathPortion(href) {
112
120
  return first === Infinity ? href : href.slice(0, first);
113
121
  }
114
122
 
123
+ /**
124
+ * The decoded fragment of an href, or '' when it has none.
125
+ *
126
+ * Browsers match the percent-decoded fragment against ids, so `#caf%C3%A9`
127
+ * and `#café` name the same heading. A malformed escape is kept as written,
128
+ * which then matches nothing and is reported.
129
+ */
130
+ function fragmentOf(href) {
131
+ const at = href.indexOf('#');
132
+ if (at === -1) {
133
+ return '';
134
+ }
135
+ const raw = href.slice(at + 1);
136
+ try {
137
+ return decodeURIComponent(raw);
138
+ } catch {
139
+ return raw;
140
+ }
141
+ }
142
+
143
+ /**
144
+ * Whether a fragment resolves on a page with these ids.
145
+ *
146
+ * An empty fragment and `#top` (any case) scroll to the top of the page by
147
+ * the HTML standard, whether or not an element carries that id.
148
+ */
149
+ function fragmentResolves(fragment, ids) {
150
+ return fragment === '' || fragment.toLowerCase() === 'top' || ids.has(fragment);
151
+ }
152
+
115
153
  // ---------------------------------------------------------------------------
116
154
  // Pass 1: source
117
155
  // ---------------------------------------------------------------------------
@@ -120,25 +158,17 @@ function pathPortion(href) {
120
158
  const MD_LINK = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
121
159
 
122
160
  /**
123
- * Blank out code so a link that is merely *shown* is not read as a real one.
124
- *
125
- * `MD_LINK` is a regex over raw text, so it cannot tell a link from a picture
126
- * of a link. Without this, documenting the link convention itself, e.g. a
127
- * ```markdown block containing [label](./example.md), fails the build as a
128
- * broken link, and the only way to appease it is to create the placeholder
129
- * file. (`tools/validate-file-refs.js` does NOT do this, so it carries the
130
- * same latent false positive; worth fixing there too if it ever fires.)
161
+ * Blank out fenced code blocks, keeping every other line as it is.
131
162
  *
132
163
  * Fences are tracked line by line rather than matched as a pair, so an
133
164
  * unterminated fence blanks to end of file instead of silently reverting to
134
- * prose scanning. Inline spans are only stripped outside a fence, so a stray
135
- * backtick inside a block cannot pair with one outside it. Line count is
136
- * preserved, which keeps byte offsets usable if this ever reports positions.
165
+ * prose scanning. Line count is preserved, which keeps byte offsets usable if
166
+ * this ever reports positions.
137
167
  *
138
168
  * @param {string} text - Raw Markdown
139
- * @returns {string} The same text with fenced blocks and code spans blanked
169
+ * @returns {string} The same text with fenced blocks blanked
140
170
  */
141
- function blankCode(text) {
171
+ function blankFences(text) {
142
172
  let fence = null;
143
173
 
144
174
  return text
@@ -157,22 +187,233 @@ function blankCode(text) {
157
187
  fence = marker[1];
158
188
  return '';
159
189
  }
160
-
161
- // Inline spans: a run of N backticks closes on a run of N.
162
- return line.replaceAll(/(`+)[^`]*\1/g, ' ');
190
+ return line;
163
191
  })
164
192
  .join('\n');
165
193
  }
166
194
 
167
195
  /**
168
- * Check that every relative `.md` target in docs/ exists on disk.
196
+ * Blank out code so a link that is merely *shown* is not read as a real one.
197
+ *
198
+ * `MD_LINK` is a regex over raw text, so it cannot tell a link from a picture
199
+ * of a link. Without this, documenting the link convention itself, e.g. a
200
+ * ```markdown block containing [label](./example.md), fails the build as a
201
+ * broken link, and the only way to appease it is to create the placeholder
202
+ * file. (`tools/validate-file-refs.js` does NOT do this, so it carries the
203
+ * same latent false positive; worth fixing there too if it ever fires.)
204
+ *
205
+ * Inline spans are only stripped outside a fence, so a stray backtick inside
206
+ * a block cannot pair with one outside it.
207
+ *
208
+ * @param {string} text - Raw Markdown
209
+ * @returns {string} The same text with fenced blocks and code spans blanked
210
+ */
211
+ function blankCode(text) {
212
+ return (
213
+ blankFences(text)
214
+ .split('\n')
215
+ // Inline spans: a run of N backticks closes on a run of N.
216
+ .map((line) => line.replaceAll(/(`+)[^`]*\1/g, ' '))
217
+ .join('\n')
218
+ );
219
+ }
220
+
221
+ // ---------------------------------------------------------------------------
222
+ // Heading ids
223
+ // ---------------------------------------------------------------------------
224
+
225
+ /**
226
+ * Characters `github-slugger` deletes from a heading: everything except
227
+ * alphabetic characters (letters, letter numbers, and symbols Unicode counts
228
+ * as alphabetic, such as circled letters), marks, decimal digits, connector
229
+ * punctuation (`_`), the ASCII space and the hyphen-minus. Other punctuation
230
+ * (the em dash included), other symbols and emoji, other spaces and control
231
+ * characters all go.
232
+ */
233
+ const SLUG_STRIP = /[^\p{Alphabetic}\p{M}\p{Nd}\p{Pc} -]/gu;
234
+
235
+ /**
236
+ * Convert heading text to the id GitHub gives it, and the site too except
237
+ * for the two cases below.
238
+ *
239
+ * Must match `github-slugger`, which is what both GitHub and Starlight use to
240
+ * generate heading ids. The distinction that matters: it replaces each space
241
+ * INDIVIDUALLY and never collapses runs, so punctuation between words leaves a
242
+ * doubled hyphen. `## Scenario A: Greenfield + BMM Integration` becomes
243
+ * `scenario-a-greenfield--bmm-integration`, with two hyphens where the `+`
244
+ * was. Collapsing them here produced a slug no page ever has, so a correct
245
+ * anchor was reported broken.
246
+ *
247
+ * github-slugger itself is ESM-only and this tool is CommonJS in a synchronous
248
+ * flow, hence the faithful reimplementation rather than a dependency. Its
249
+ * table dates from Unicode 13, so a letter Unicode assigned later is dropped
250
+ * there and kept here; for every other character the two agree.
251
+ *
252
+ * The site's Markdown pipeline (Astro, under Starlight) differs in two ways:
253
+ * it trims one trailing hyphen off the id, and its SmartyPants step turns a
254
+ * `--` outside code into a dash the slug then drops. So a heading that ends
255
+ * in punctuation, or holds a `--`, gets different ids on GitHub and on the
256
+ * site. The source pass checks GitHub's; the built pass reads the ids the
257
+ * site actually carries.
258
+ *
259
+ * @param {string} text - Heading text as rendered, without Markdown syntax
260
+ * @returns {string} The id, before any `-N` suffix for a repeat
261
+ */
262
+ function headingToAnchor(text) {
263
+ return text.toLowerCase().replaceAll(SLUG_STRIP, '').replaceAll(' ', '-');
264
+ }
265
+
266
+ /**
267
+ * An ATX heading line: up to three spaces, one to six `#`, then a space or
268
+ * the end of the line. `#tag` is a paragraph, not a heading. The `\r` of a
269
+ * CRLF line ending is trailing space like any other.
270
+ */
271
+ const ATX_HEADING = /^ {0,3}#{1,6}(?:[ \t]+(.*?))?[ \t\r]*$/;
272
+
273
+ /** Named entities a heading is likely to carry; numeric ones are decoded too. */
274
+ const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: '\u00A0' };
275
+
276
+ /**
277
+ * Reduce the Markdown of a heading to the text a renderer slugs.
278
+ *
279
+ * Only what changes the id is handled. Characters the slugger deletes anyway
280
+ * (`*`, `~`, brackets) need no care, but the ones it keeps do: a link's URL,
281
+ * an image's alt text (a renderer drops it), an entity's name, and the `_`
282
+ * of emphasis, which survives slugging where `*` does not. Code spans and
283
+ * backslash escapes are literal text, so they are set aside first, behind
284
+ * private-use placeholders that no heading carries.
285
+ *
286
+ * @param {string} raw - Heading content after the `#` markers
287
+ * @returns {string} Plain text
288
+ */
289
+ function headingText(raw) {
290
+ const literals = [];
291
+ const keep = (literal) => {
292
+ literals.push(literal);
293
+ return `\uE000${literals.length - 1}\uE001`;
294
+ };
295
+ const text = raw
296
+ // A closing sequence of `#` is syntax when a space precedes it.
297
+ .replace(/(?:^|[ \t]+)#+[ \t]*$/, '')
298
+ // One space is stripped from each side of a code span when both have one.
299
+ .replaceAll(/(`+)(.+?)\1(?!`)/g, (_, _ticks, body) =>
300
+ keep(body.startsWith(' ') && body.endsWith(' ') && body.trim() ? body.slice(1, -1) : body),
301
+ )
302
+ // A backslash-escaped character is literal, never syntax.
303
+ .replaceAll(/\\([!-/:-@[-`{-~])/g, (_, char) => keep(char))
304
+ .replaceAll(/!\[[^\]]*\]\([^)]*\)/g, '')
305
+ .replaceAll(/\[([^\]]*)\]\([^)]*\)/g, '$1')
306
+ .replaceAll(/\[([^\]]*)\]\[[^\]]*\]/g, '$1')
307
+ .replaceAll(/<((?:https?|mailto):[^>\s]*)>/gi, '$1')
308
+ .replaceAll(/<\/?[a-z][^>]*>/gi, '')
309
+ .replaceAll(/(^|[^\p{L}\p{N}_])(__?)(?=\S)(.*?\S)\2(?![\p{L}\p{N}_])/gu, '$1$3')
310
+ .replaceAll(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, name) => {
311
+ if (name[0] === '#') {
312
+ const code = /x/i.test(name[1]) ? Number.parseInt(name.slice(2), 16) : Number(name.slice(1));
313
+ return code > 0 && code <= 0x10_ff_ff ? String.fromCodePoint(code) : '\uFFFD';
314
+ }
315
+ return ENTITIES[name.toLowerCase()] ?? entity;
316
+ });
317
+
318
+ // No trim: the heading line was trimmed already, and space left beside a
319
+ // dropped image or tag is still in the rendered text, so it is in the id.
320
+ return text.replaceAll(/\uE000(\d+)\uE001/g, (_, index) => literals[Number(index)]);
321
+ }
322
+
323
+ /**
324
+ * Blank out a leading YAML front matter block, keeping the line count.
325
+ *
326
+ * Its `# ` lines are YAML comments, not headings.
327
+ */
328
+ function blankFrontMatter(text) {
329
+ const lines = text.split('\n');
330
+ if (lines[0].trimEnd() !== '---') {
331
+ return text;
332
+ }
333
+ const end = lines.findIndex((line, index) => index > 0 && /^(?:---|\.\.\.)\s*$/.test(line));
334
+ if (end === -1) {
335
+ return text;
336
+ }
337
+ return lines.map((line, index) => (index <= end ? '' : line)).join('\n');
338
+ }
339
+
340
+ /**
341
+ * Collect the id of every heading in a Markdown file.
342
+ *
343
+ * Repeated headings are disambiguated exactly as github-slugger does: the
344
+ * first occurrence keeps the bare slug and each later one gets `-N` appended,
345
+ * counting from 1, skipping any id an earlier heading already took. A
346
+ * stateless slug function would collect only the first of several same-named
347
+ * headings and report a link to any later one as broken.
348
+ *
349
+ * Fenced code is skipped. A shell comment in a ```bash block starts with `# `
350
+ * like a heading, and reading the raw file counted every one of them, so a
351
+ * link to a comment passed as a link to a section. Front matter is skipped
352
+ * for the same reason. Only ATX headings are read: a setext heading (text
353
+ * underlined with `===` or `---`) gets no id here.
354
+ *
355
+ * @param {string} content - Raw Markdown
356
+ * @returns {Set<string>} Every heading id in the file
357
+ */
358
+ function extractAnchors(content) {
359
+ const anchors = new Set();
360
+ const occurrences = new Map();
361
+
362
+ for (const line of blankFences(blankFrontMatter(content)).split('\n')) {
363
+ const match = line.match(ATX_HEADING);
364
+ if (!match) {
365
+ continue;
366
+ }
367
+ const base = headingToAnchor(headingText(match[1] ?? ''));
368
+ let id = base;
369
+ while (occurrences.has(id)) {
370
+ const count = occurrences.get(base) + 1;
371
+ occurrences.set(base, count);
372
+ id = `${base}-${count}`;
373
+ }
374
+ occurrences.set(id, 0);
375
+ anchors.add(id);
376
+ }
377
+
378
+ return anchors;
379
+ }
380
+
381
+ /**
382
+ * Markdown files outside docs/ that the source pass reads too, relative to
383
+ * the project root, each read when present.
384
+ *
385
+ * GitHub is the only place they render, so no build resolves their links: a
386
+ * moved file or a renamed heading leaves them dead with every other check
387
+ * green. Their relative targets resolve from their own folder, as on GitHub.
388
+ */
389
+ const ROOT_DOCS = ['CONTRIBUTING.md', 'README.md', 'changes/README.md'];
390
+
391
+ /**
392
+ * Check every relative link in the Markdown sources: the target must exist
393
+ * on disk, and a `#anchor` must match a heading id in its file.
394
+ *
395
+ * Any target counts, not only `.md`: a workflow file, a folder or LICENSE is
396
+ * as dead on GitHub when it moves. Anchors are checked on the same file and
397
+ * on `.md` targets; GitHub gives other files line anchors, not heading ids.
169
398
  *
170
399
  * Deliberately does NOT enforce a `./` prefix. The plugin accepts bare links,
171
400
  * and GitHub renders them correctly, so requiring the prefix would be style,
172
401
  * not correctness. What matters is that the target exists.
173
402
  */
174
403
  function checkSource({ projectRoot, docsDir }, report) {
175
- const files = walk(docsDir, new Set(['.md']));
404
+ const files = [
405
+ ...new Set([
406
+ ...walk(docsDir, new Set(['.md'])),
407
+ ...ROOT_DOCS.map((rel) => path.join(projectRoot, rel)).filter((file) => fs.existsSync(file)),
408
+ ]),
409
+ ];
410
+ const anchorsByFile = new Map();
411
+ const anchorsOf = (file) => {
412
+ if (!anchorsByFile.has(file)) {
413
+ anchorsByFile.set(file, extractAnchors(fs.readFileSync(file, 'utf8')));
414
+ }
415
+ return anchorsByFile.get(file);
416
+ };
176
417
 
177
418
  for (const file of files) {
178
419
  const rel = path.relative(projectRoot, file);
@@ -180,12 +421,17 @@ function checkSource({ projectRoot, docsDir }, report) {
180
421
  const text = blankCode(fs.readFileSync(file, 'utf8'));
181
422
 
182
423
  for (const match of text.matchAll(MD_LINK)) {
183
- const target = pathPortion(match[1]);
424
+ const href = match[1];
425
+ const target = pathPortion(href);
426
+ const anchor = fragmentOf(href);
184
427
 
185
- if (!target || target.startsWith('#') || EXTERNAL.test(target)) {
428
+ if (EXTERNAL.test(href)) {
186
429
  continue;
187
430
  }
188
- if (!target.endsWith('.md')) {
431
+ if (!target) {
432
+ if (!fragmentResolves(anchor, anchorsOf(file))) {
433
+ report(rel, `anchor matches no heading in this file: ${href}`);
434
+ }
189
435
  continue;
190
436
  }
191
437
  // Root-absolute targets mean different things on the two surfaces, and
@@ -206,9 +452,13 @@ function checkSource({ projectRoot, docsDir }, report) {
206
452
  report(
207
453
  rel,
208
454
  target.startsWith('/')
209
- ? `root-absolute link target does not exist at the repository root, so it is dead on GitHub: ${match[1]}`
210
- : `link target does not exist: ${match[1]}`,
455
+ ? `root-absolute link target does not exist at the repository root, so it is dead on GitHub: ${href}`
456
+ : `link target does not exist: ${href}`,
211
457
  );
458
+ continue;
459
+ }
460
+ if (target.endsWith('.md') && fs.statSync(resolved).isFile() && !fragmentResolves(anchor, anchorsOf(resolved))) {
461
+ report(rel, `anchor matches no heading in ${path.relative(projectRoot, resolved)}: ${href}`);
212
462
  }
213
463
  }
214
464
  }
@@ -315,11 +565,24 @@ function assetUrls(html) {
315
565
  * which is precisely how a browser resolves them, and precisely the step that
316
566
  * the earlier page-relative bug failed.
317
567
  *
568
+ * An href's `#fragment` must match an id on the page it lands on, the same
569
+ * page for a bare `#anchor`. These are the ids the site really carries, which
570
+ * are not always GitHub's (see `headingToAnchor`), so a link that the source
571
+ * pass accepts for GitHub and that misses on the site fails here.
572
+ *
318
573
  * @param {string} base - Deployment base path
319
574
  * @returns {number} Number of HTML pages checked
320
575
  */
321
576
  function checkBuilt({ projectRoot, buildDir }, base, report) {
322
577
  const pages = walk(buildDir, new Set(['.html']));
578
+ const idsByPage = new Map();
579
+ const idsOf = (page) => {
580
+ if (!idsByPage.has(page)) {
581
+ const html = fs.readFileSync(page, 'utf8');
582
+ idsByPage.set(page, new Set(Array.from(html.matchAll(/\sid="([^"]*)"/g), (match) => match[1])));
583
+ }
584
+ return idsByPage.get(page);
585
+ };
323
586
 
324
587
  for (const page of pages) {
325
588
  const rel = path.relative(projectRoot, page);
@@ -331,13 +594,16 @@ function checkBuilt({ projectRoot, buildDir }, base, report) {
331
594
  const seen = new Set();
332
595
 
333
596
  for (const { attr, url: href } of assetUrls(html)) {
334
- if (!href || href.startsWith('#') || EXTERNAL.test(href) || seen.has(href)) {
597
+ if (!href || EXTERNAL.test(href) || seen.has(href)) {
335
598
  continue;
336
599
  }
337
600
  seen.add(href);
338
601
 
339
602
  const target = pathPortion(href);
340
603
  if (!target) {
604
+ if (attr === 'href' && !fragmentResolves(fragmentOf(href), idsOf(page))) {
605
+ report(rel, `href matches no id on this page: ${href}`);
606
+ }
341
607
  continue;
342
608
  }
343
609
 
@@ -366,6 +632,10 @@ function checkBuilt({ projectRoot, buildDir }, base, report) {
366
632
 
367
633
  if (!fs.existsSync(candidate)) {
368
634
  report(rel, `${attr} resolves to nothing: ${href} (looked for ${path.relative(buildDir, candidate)})`);
635
+ continue;
636
+ }
637
+ if (attr === 'href' && candidate.endsWith('.html') && !fragmentResolves(fragmentOf(href), idsOf(candidate))) {
638
+ report(rel, `href matches no id on ${path.relative(buildDir, candidate)}: ${href}`);
369
639
  }
370
640
  }
371
641
  }
@@ -528,7 +798,7 @@ async function run(cfg, log = console.log) {
528
798
  }
529
799
 
530
800
  const sourceCount = checkSource(cfg, report);
531
- log(`Source pass: ${sourceCount} markdown file(s) in docs/`);
801
+ log(`Source pass: ${sourceCount} markdown file(s) in docs/, plus ${ROOT_DOCS.join(', ')} where present`);
532
802
 
533
803
  let builtCount = 0;
534
804
  const haveBuild = fs.existsSync(cfg.buildDir);
@@ -640,6 +910,9 @@ module.exports = {
640
910
  checkBuilt,
641
911
  resolveBase,
642
912
  blankCode,
913
+ blankFences,
914
+ headingToAnchor,
915
+ extractAnchors,
643
916
  assetUrls,
644
917
  walk,
645
918
  buildInputsStatus,