link-cliref: KNOWN_ALIAS_SEGMENTS is unscoped — `poe`/`qos` are real menu segments, producing 3 wrong schema links

[mobileskyfi]

Summary

KNOWN_ALIAS_SEGMENTS in src/link-cliref.ts is a global, unscoped
allowlist: a segment on the list may be dropped from any source_path. Five of
its nineteen entries — acl, controller, poe, qos, route — are real
CLI menu segments published elsewhere in the very same CLI Reference source.

Result: three cliref_entry_schema_links rows link a published entry to a
different command. The failure is silent, because the alias branch only runs
when the exact path is missing from schema_nodes — which is precisely the
hardware-gated class where nobody has a device to notice.

The bad links

Simulating the current algorithm (exact → single-drop alias → manual-only)
against four typed inspect trees (restraml, extra-packages, x86 + arm64,
7.10.2 → 7.24rc2), 23 alias links fire. Three are wrong:

Published entry	Linked to	Should be
interface/ethernet/poe/monitor	/interface/ethernet/monitor	manual-only
interface/ethernet/switch/qos/port	/interface/ethernet/switch/port	manual-only
interface/ethernet/switch/qos/port/reset-counters	/interface/ethernet/switch/port/reset-counters	manual-only

These are demonstrably different commands, provable from the publication alone —
their field sets are disjoint:

interface/ethernet/poe/monitor   name poe-out poe-voltage poe-out-status poe-out-voltage
                                 poe-out-current poe-out-power poe-out-power-pair
                                 power-cycle-host-alive power-cycle-after

interface/ethernet/monitor       name status auto-negotiation rate full-duplex
                                 tx-flow-control rx-flow-control fec supported
                                 sfp-* (35 more) phy-regs eeprom ...

interface/ethernet/switch/qos/port publishes ~140 fields (per-queue caps, PFC
thresholds); interface/ethernet/switch/port publishes 15 (vlan-mode,
mirror-*, rates). No overlap beyond name/switch.

Live confirmation that these are gated, not phantom: on CHR 7.23.3 stable and
7.24rc3 testing, /interface/ethernet/poe and /interface/ethernet/switch/qos
are absent over /console/inspect, REST and the native API — consistent with
their published gates (syscap: (poe or poe-in), syscap: multiswitch /
crs_prestera). They are real menus on hardware rosetta has never inspected.

Root cause and fix

The allowlist encodes "this word is an internal module name" as a global
property. It is not global — it is positional. A segment that is itself a
published entry at that point in the path is a real menu, not a doc-internal
module.

Derivable rule, no device needed: never drop segment S at position i
when the prefix ending at S is itself a cliref_entries.source_path.

Applied to the current list:

Segment	Prefix published as	Verdict
poe	interface/ethernet/poe = Directory	real menu — reject the drop
qos	interface/ethernet/switch/qos = Directory	real menu — reject the drop
acl	interface/ethernet/switch/acl = Directory	real menu — reject the drop
controller	zerotier/controller = Directory	real menu — reject the drop
route	ip/route, routing/route = Directory	real menu — reject the drop
cfg chancfg dpathcfg ifaceactual ratescfg remoteap seccfg sta rule easymesh serial-interface ddns ifaces queues	—	internal module — safe

acl, controller and route currently produce correct links by luck (they
fire only in caps-man/… and routing/route/rule, different subtrees), so the
rule costs three links and buys a guarantee.

Suggested implementation:

1. Add the prefix-scoping check to the alias branch.
2. Add a field-set-overlap sanity check as a second gate: refuse an alias
   link whose published fields are disjoint from the target's inspect args. This
   would have caught all three independently.
3. Keep the segment allowlist — it still stops arbitrary normalization; the two
   new checks are additive, and the cli-reference-links.tsv drift gate makes
   the −3 visible for review.

Why this is worth fixing even though it is only three rows

interface/ethernet/poe/monitor is a command real users run on real hardware.
Anything reading cliref_entry_schema_links — routeros_explain_command,
the command-prose join, the export dataset — currently attributes PoE monitoring
fields to the SFP/ethernet monitor command. Wrong provenance on hardware-only
surfaces is exactly the class nobody can catch from a CHR.

src/extract-cliref.ts itself is not implicated: source_path is the heading
verbatim, it is honestly named source, and an independent re-implementation
reproduced its output byte-for-byte. The defect is confined to the crosswalk.

Found while evaluating CLI Reference as offline evidence for centrs explain:
tikoci/centrs#228 (comment) (§7).

[mobileskyfi]

Related: rosetta#137 homework (2026-08-12) confirms this fix is on the critical path. The source migrated from 228 module pages → 814 leaf pages; all 24 alias-shaped source_paths in the ship DB are now deleted (plus ~273 module-internal entries gone), and the 20 remaining alias substrings (poe/qos/acl/route/…) are now published entries — the allowlist entries poe/ qos/ acl / controller/ route are real menus. The two remaining alias fires in the live simulation (interface/ethernet/poe/monitor, interface/ethernet/switch/qos/port/reset-counters) are exactly the wrong links this issue reports. The scoped fix (prefix-ending-at-S must not be a published source_path) + the pending canon-core _parts()/sub-path identity fix are complementary — qos may be event-less operationally, but it is a real published path, so canonicalization over it must not invent segmentType=field. Tracking ETL refresh + docs/counts sequencing in #137.

[mobileskyfi]

Update: #137 follow-up (2026-08-12) resolves the sitemap/llms discovery nuance — the 257 llms-only slugs are not an informational gap; 256 are Directory leaves mirroring the 257 trailing-sitemap dirs (the old 'category stubs — all 404s' verification used the wrong candidate URLs). Their union with the 814 filtered sitemap slugs reconciles llms 1,071 exactly. The ETL must be fixed to derive from trailing entries before this refresh — losing 256 Directory leaves is a correctness loss, not a doc note. See #137 correction comment for verification probes and revised sequencing (discovery fix → your prefix-scoping fix → re-extract). Your allowlist fix is still required on top.

[mobileskyfi]

Fixed in PR #138, together with #137 — and the two needed each other

The prefix-scoping rule proposed here is implemented as specified: a segment is never dropped when the prefix ending at it is itself a published cliref_entries.source_path. KNOWN_ALIAS_SEGMENTS is retained as the allowlist; the guard is additive.

All three wrong links are caught — not the two predicted from the sitemap-only corpus in rosetta#137's homework. Isolated on the corrected corpus (resolve every entry with and without the guard, diff):

without prefix-scoping: exact 967  alias 3  manual-only 107
with    prefix-scoping: exact 967  alias 0  manual-only 110

  interface/ethernet/poe/monitor                      was alias:/interface/ethernet/monitor                    -> manual-only
  interface/ethernet/switch/qos/port                  was alias:/interface/ethernet/switch/port                -> manual-only
  interface/ethernet/switch/qos/port/reset-counters   was alias:/interface/ethernet/switch/port/reset-counters -> manual-only

The third one only becomes catchable because of #137's discovery fix. The sitemap-only corpus never published interface/ethernet/switch/qos (it is a branching menu, so the sitemap serves it as a trailing-slash category URL and its Directory entry lives at interface/ethernet/switch/qos/qos.md, listed only in llms.txt). Without that entry there is no published prefix to scope against, so the guard stays blind to it. This is a nice confirmation of the issue's own root-cause claim: the rule is derivable from the publication alone — but only from the complete publication.

On the suggested field-set-overlap check

Not implemented. On the current corpus the crosswalk is 0 alias, so the second gate would have nothing to grade, and V-cliref-link-drift already makes any future alias visible for review before it ships. Worth revisiting if aliases ever reappear in the source.

Note for the audit table

The verdicts in this issue's "Applied to the current list" table remain correct, but their evidence changed shape: acl, controller and route no longer fire at all, because MikroTik deleted all 24 alias-shaped headings when the CLI Reference was decomposed into per-command leaf pages (rosetta#137). The rule still costs those three links nothing and buys the guarantee.

Committed baseline cli-reference-links.tsv now records all three as manual-only.