**Stacked on #3036** (its commit is the parent). That PR fixes a guard
that had been red on `main`; this closes the gap it leaves and, in doing
so, turned up a second defect in the helper.
## 1. Nested anchors were accepted but never resolved
#3036 makes the parser recognise sub-entries — correct, and it fixes the
red. But it validates only their link *shape*. Measured on that branch:
| corruption | result |
|---|---|
| **nested** entry → `#kb-nonexistent-anchor` | **passes** |
| **top-level** entry → `#kb-nonexistent-anchor` | fails |
A TOC guard exists so links resolve. Checking that for one class of
entry and not the other leaves a dead sub-link to be found by a reader
clicking it.
## 2. Resolving them exposed the slugify bug
Adding the check failed immediately — on the **real document**, against
a heading that exists:
```
Nested TOC anchor #theming--overlay-layering-for-dashboard-views matches no heading
```
The document is right; the helper was wrong. `slugifyHeading` collapsed
whitespace **runs**:
```js
.replace(/\s+/g, "-") // theming-overlay-layering-...
.replace(/\s/g, "-") // theming--overlay-layering-... ← GitHub, and the doc's own link
```
GitHub emits one hyphen **per space**. `### Theming & Overlay Layering
for Dashboard Views` loses the `&` and keeps both spaces, so the true
anchor carries a double hyphen.
**This was latent, not dormant-and-harmless:** the two spellings differ
only when punctuation is stripped from *between* words, and all eighteen
numbered section titles are punctuation-free — so every existing use of
the helper agreed. The first heading with an `&` in it would have
produced a false failure against a correct document, which is the shape
most likely to get a guard edited rather than believed.
## Mutations (all four)
| mutation | result |
|---|---|
| clean | 4/4 pass |
| nested anchor broken | **fails** ← was green before this PR |
| top-level anchor broken | fails |
| malformed top-level line | fails |
| `slugify` reverted to collapsing | **fails** — the helper fix is
load-bearing |
Lint clean, FNXC gate exit 0. Test-only.
## Note
This is the fifth guard in this batch to ship with a hole found by
mutating it rather than reading it, and the second where fixing one
class of input revealed the checker had been quietly wrong about
another. The pattern is consistent enough to be worth expecting: **when
a guard starts examining something it previously skipped, the first
thing it finds is usually its own bug.**
If #3036 lands first this rebases to a single commit; if taken together
the stack applies as-is.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Improved heading links to match GitHub-style anchors when punctuation
separates words.
* Enhanced nested table-of-contents validation to confirm links point to
headings in the document.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
## A legal Markdown sub-entry turned this guard red
```
AssertionError: Invalid TOC line: - [Theming & Overlay Layering for Dashboard Views](#theming--overlay-layering-for-dashboard-views)
```
That line is an ordinary nested TOC entry, indented under item 8 of
`docs/PLUGIN_AUTHORING.md`. The parser did `.map(line => line.trim())`
**first** and then required every line to match the top-level `N.
[title](#anchor)` shape — so indentation, the one thing distinguishing a
sub-entry from a malformed top-level one, was destroyed before it could
be used.
**The doc was never wrong.** Only the parser was, and it has been red on
`main` since the entry was added.
Indentation is now read before trimming. Sub-entries are still required
to be well-formed links; they just do not participate in the numbering
or the count.
## Both guard directions verified by breaking them
A looser parser that skipped anything unrecognised would have made the
failure go away while quietly ending the guard's usefulness — so I
checked it still fails in both directions:
| mutation | result |
| --- | --- |
| top-level `9.` rewritten as a bullet | still fails (`Invalid TOC
line`) |
| nested entry replaced with un-linked prose | still fails (`Invalid
nested TOC line`) |
## The wider finding, which matters more than this fix
I found it by sweeping `scripts/__tests__` against clean `main`: **688
passing, 7 failing test files.**
| suite | failing assertion |
| --- | --- |
| `ci-test-shard-timings` | committed timing snapshot references live
test files |
| `dependency-security-floor` | pnpm overrides pin transitive protobufjs
to a safe floor |
| `engine-vitest-gate-policy` | pg gate canaries remain a subset of the
enabled suite |
| `plugin-authoring-docs` | **this PR** |
| `release-prompt-gate` | release dry-run exits before proceed
confirmation |
| `verify-fast` | defaults to every canonical pretest validator |
| `workflow-reliability-release-check` | manifest references existing
seam files |
All sit **outside the merge gate**. That is now the third instance of
this pattern I have hit — #2969's 15 red agent-action tests and #3033's
stale ratchet list were the others — and it is clearly systemic rather
than incidental.
I fixed only the one in plugin territory. The rest span CI sharding,
**dependency security** (that protobufjs floor is a security assertion
currently not holding), release gating and workflow manifests. Each
needs its owner's judgement about whether the assertion or the world is
wrong, and a drive-by "make it green" is exactly how a real signal gets
erased — `dependency-security-floor` especially.
## Verification (measured)
- this suite — **4 passed / 0 failed** (was 1 failed)
- `eslint` — clean
Test-only; the doc is untouched. No changeset.
Adds `docs/PLUGIN_AUTHORING.md` documenting the `executorRuntimeEnv` hook with cross-references to the architecture docs, accompanied by tests validating the documentation contract.
Fusion-Task-Id: FN-3967
- Create a disposable HOME/USERPROFILE env for scripts/test-changed.mjs execution
- Run isolation guard checks with the same isolated env, including cache-hit no-op paths
- Clean up temp HOME after test execution to avoid residue
- Update test coverage and contributing docs for the shared isolation behavior
Fusion-Task-Id: FN-3610
- Add missing top-level dashboard views section to the PLUGIN_AUTHORING table of contents
- Renumber downstream section headings and TOC entries to keep numbering sequential
- Add a node:test suite that validates heading order and TOC anchor alignment
Fusion-Task-Id: FN-3468
