Follow-up: deferred review findings from PR #505

[philcunliffe]

Neutral triage on PR #505 (fix/issue-497, head 756dabc) exhausted the 2-round
review fix-loop with three residual findings, all judged non-blocking
(preference / correctly-deferred design questions, not production defects).
Filed here so they are not lost, per LLP 0017.

Backlink: #505

1. Symlink-inside-target: purge deletes a row reached only via a symlink (documented, not fixed)

src/core/usage-policy/matcher.js — scopeGovernance/scopeGoverns.

Reproduced independently (a third time, after the PR author and two review
rounds) against head 756dabc:

cwd as given                                     = <root>/proj/link/sub
realpath(cwd)                                    = <root>/elsewhere/sub
scopeGovernance(as-given, target, proveAliases)  = governs
scopeGovernance(as-given, target) plain          = governs
scopeGoverns (gate shape)                        = true
scopeGovernance(realCwd, target) plain           = outside

A row recorded under a path that is lexically inside the purge target, but
that a symlink resolves to a directory physically elsewhere on disk, reads as
governs even with the proveAliases opt-in off — i.e. this is the plain
canonicalSpellings/matchDepth match from #482, not #493's fold, and predates
both. hyp purge will delete cache rows for such a spelling.

Why PR #505 documents rather than fixes it: the same plain predicate is what
hyp ignore --check, policy show, and every other verb use to decide what
proj governs. Making purge alone treat the row as out of scope would desync it
from the gate — the gate would keep saying the row is governed while purge
refuses to clear it, leaving a residual the user has no spelling to name to
clear. LLP 0104 §Consequences (llp/0104-hyp-purge.decision.md:180-188)
records this explicitly, including that reversing it is a change to
LLP 0050 §canonicalization's set-of-spellings semantics, not to purge's own
decision.

Issue #497 itself flagged this as "worth a decision, separately."

Follow-up: a maintainer should decide whether canonicalSpellings /
matchDepth should stop following symlinks for containment purposes across all
verbs (a LLP 0050 change), not just purge. Until decided, current behaviour is
unchanged from pre-#493 releases and is internally consistent across every verb
that consults the gate.

2. @ref annotation separated from its construct by a blank line

test/core/purge-command.test.js:442 — @ref LLP 0104#spellings [tests] is
followed by a blank line (443) before the construct it should attach to
(const NFC at 444), which breaks CLAUDE.md's attachment rule ("a blank line
breaks attachment").

Not a slip specific to this file: a corpus-wide scan (re-run by the round-2
reviewer) found the same shape in 38 places across 34 files, all in test/,
essentially all section-level headers over a block of tests. Closing this one
blank would also make the annotation worse, not better — it would attach a
section-level gloss ("purge deletes an aliased spelling...") to the NFC
constant declaration, which is not what it glosses.

Follow-up: a maintainer should decide whether to (a) normalize the
convention corpus-wide, or (b) amend CLAUDE.md's attachment rule to allow a
section-level @ref to precede a blank line before its block. CLAUDE.md is
currently the only place the rule is written; LLP 0000 does not define
attachment semantics even though .claude/skills/ref-check/SKILL.md cites it as
if it did.

3. Hyphen soft-wrap renders oddly in a new LLP 0104 list item

llp/0104-hyp-purge.decision.md:134 — "case-sensitive (or normalization-\n
sensitive) volume" line-wraps at a hyphen, which most Markdown renderers turn
into "normalization- sensitive" (a stray space after the hyphen) since a single
newline collapses to a space in paragraph text.

Purely cosmetic; zero behavioural effect. The same pattern already exists
untouched elsewhere in the same file (llp/0104-hyp-purge.decision.md:168-169,
"purge-then-\n re-record"), so it is this file's pre-existing convention, not a
new slip introduced by PR #505.

Follow-up: a maintainer may want to reflow both list items to avoid
wrapping mid-word, or adopt a doc-lint rule against it.

---

None of the three could cause a production defect (wrong purge behaviour, data
loss, a security hole, a crash, or a perf regression) on their own at this head;
each was independently re-verified by execution before being filed here rather
than accepted from the PR body or review comments.

[philcunliffe]

🤖 neutral: stuck - three maintainer decisions, no worker-actionable work

The issue-fix rung ran against origin/master @ 71c6231 and opened no PR, deliberately. All three findings were independently re-verified and each terminates in a decision only you can make. One of them turns out to be materially different from how it was recorded.

Finding 1 - symlink-inside-target: the proposed direction is a privacy regression, not just a purge/gate desync

Reproduced with a real symlink(2) fixture (proj/link -> elsewhere, cwd proj/link/sub):

scopeGovernance(as-given, proj, proveAliases)  = governs
scopeGovernance(as-given, proj) plain          = governs
scopeGoverns(as-given, proj) gate shape        = true
scopeGovernance(realpath(cwd), proj) plain     = outside

That confirms the triage claim (the unwidened predicate already returns governs, so purge and the gate are consistent, and it predates proveAliases). But driving the actual resolver surfaces an argument the issue does not make. With a .hypignore (ignore) in proj:

resolve(as-given proj/link/sub) = ignore
resolve(realpath elsewhere/sub) = full

So lexical containment is not merely what purge happens to match - it is what suppresses capture. Making canonicalSpellings/matchDepth stop following the as-given spelling for containment would flip that cwd from ignore to full and start recording traffic the user opted out of.

Current behaviour is the safe direction, and purge deleting those rows is its required counterpart (purge must be able to clear exactly what the gate governs). llp/0104-hyp-purge.decision.md:180-188 already scopes the follow-up as an LLP 0050 #canonicalization change. The gate direction is the binding constraint here, not purge - worth deciding across all verbs at once rather than in purge alone.

Finding 2 - @ref before a blank line at test/core/purge-command.test.js:442

A fresh corpus scan found the pattern is broader than triage reported: 66 instances across 45 files (triage said 38/34). The decisive detail: test/core/llp-ref-hygiene.test.js:8-9 - the file that enforces @ref hygiene in npm test - uses the same file-header shape. So this is a deliberate convention, not drift.

At line 442 the @ref is followed by a separate comment block explaining the \u-escaped fixture constants, then const NFC. Closing the blank would attach the gloss ("purge deletes an aliased spelling the filesystem proves...") to a string constant it does not gloss. The only real options are corpus-wide normalization or amending CLAUDE.md's attachment rule - both yours.

Finding 3 - hyphen soft-wrap at llp/0104:134

I was prepared to fix this (trivial, zero-risk) until scanning the corpus: the same end-of-line hyphen wrap appears 21 times across 14 llp/ files (0049:29, 0073:30, 0022:176, 0135 x4, 0115 x3, 0154:68, 0097:77, ...). It is a repo-wide artifact of hard-wrapping at 80 columns, not a slip in this file. Fixing one line is inconsistent noise; fixing 21 is unrequested cosmetic churn across the design corpus.

Why no PR

A PR here must end in Fixes #526, which would close an issue whose findings 1 and 2 both terminate in a maintainer decision. Landing only the cosmetic reflow and closing the issue would discard finding 2's convention question from the tracker while delivering roughly nothing.

What it needs from you

1. Finding 1: decide LLP 0050 #canonicalization symlink-containment semantics across all verbs, weighing the gate-side privacy regression above. Or close it as working-as-intended with that rationale recorded.
2. Finding 2: either (a) normalize the 66 sites, or (b) amend CLAUDE.md's attachment rule to permit a section/file-level @ref header block. Separately, .claude/skills/ref-check/SKILL.md cites LLP 0000 for attachment semantics that LLP 0000 does not actually define - worth fixing whichever way you go.
3. Finding 3: close as wontfix, or adopt a doc-lint rule and reflow all 21 sites in one pass.

How to unstick: reply with a comment on this issue; neutral monitors this thread and will re-engage with your guidance on its next tick.