fix(spec): repoint 11 dangling @spec anchors onto real file-actions headings (gate-46)

[rubenvdlinde]

Replaces #2345, which became unmergeable after the fleet licence normalisation landed on development.

Why a new PR

#2345 bundled two things: 30 AGPL→EUPL licence headers (gate-28) and 11 dangling @spec anchors (gate-46). Between it being opened and now, chore(license): normalise licence declarations to EUPL-1.2 landed on development and did the licence half independently.

Measured before opening this:

• 23 of fix(license,spec): correct 30 AGPL licence headers and 11 dangling @spec anchors (gate-28, gate-46) #2345's 32 files were already byte-identical to development — the licence work was fully done there. grep -c AGPL across every file fix(license,spec): correct 30 AGPL licence headers and 11 dangling @spec anchors (gate-28, gate-46) #2345 touched returns 0 on development.
• Of the 9 that still differed, 6 differed only because the branch was 7 commits stale — merging them would have reverted newer work: four lib/Migration/* files would have re-added the @SuppressWarnings(PHPMD.UnusedFormalParameter) tags that development deliberately removed (the fleet UFP effort), and FolderManagementHandler / UpdateFileHandler would have reverted logger->debug back to logger->info and restored log lines that were deliberately deleted as duplicate noise.
• That left exactly 3 files carrying unique value, which is what this PR contains.

update-branch on #2345 returns HTTP 422 merge conflict between base and head, and the branch is ahead=11 behind=7 diverged. Rebuilding it in place kept conflicting, so this branch is cut fresh from development@f98fcb4 and carries only the surviving work.

What this changes

file	change
openspec/specs/file-actions/spec.md	splits two catch-all requirements into five named for the behaviour they contract
lib/Service/FileService.php	repoints 10 dangling @spec anchors
lib/Service/File/DocumentProcessingHandler.php	repoints 1 anchor out of openspec/changes/ onto the canonical openspec/specs/ home

No licence header is touched — development already owns that.

Evidence

Anchors resolved against the spec's own headings (Requirement: prefix stripped, matching the gate):

OK    file-creation-and-upsert-run-a-fixed-validate-write-own-tag-pipeline
OK    file-retrieval-resolves-by-id-or-name-and-projects-nodes-to-metadata
OK    file-update-and-delete-enforce-per-action-node-permissions
OK    file-update-guards-locks-preserves-object-tags-and-persists-or-side-metadata-separately
OK    object-and-register-folder-provisioning

NEGATIVE CONTROL — the anchor being replaced:
MISS  file-crud-operations-on-objects

The negative control is the point: it shows the check can fail, and that the old anchors were genuinely dangling rather than the checker being permissive.

The two PHP files were rebuilt from development's current content with only the anchor lines re-applied, so their diff is anchors and nothing else. php -l clean on both. The resulting anchor multiset is identical to the one #2345 intended — verified by diffing the sorted anchor lists.

[github-actions]

Quality Report — ConductionNL/openregister @ 289b0fc

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
check-specs		✅
test-l10n		✅
composer			✅	✅ 173/173
npm			✅	✅ 713/713
PHPUnit					✅
Newman					✅
Playwright					✅
Hydra gates					❌

---

Quality workflow — 2026-08-05 20:20 UTC

Download the full PDF report from the workflow artifacts.

[rubenvdlinde]

Blocked by gate-47, which I believe is a false positive here — flagging rather than working around it.

Everything else is green (25 SUCCESS, E2E Tests (Playwright) passing after a real 221s run). The single gate failure is:

[hydra-gates] Scope: diff vs origin/development — 3 changed file(s)
[gate-47] security-change-has-tests: FAIL — 2 security-touching change(s) without a test co-change

This PR changes no code. Measured on the diff: all 30 changed lines under lib/ are docblock comment lines — the @spec anchor strings and their continuation lines. Filtering the diff for any added/removed line that is not a * docblock line returns nothing:

$ gh pr diff 2355 | awk '/^diff --git a\/lib/,/^diff --git a\/openspec/' \
    | grep -E "^[+-]" | grep -vE "^(\+\+\+|---)" | grep -vE "^\s*[+-]\s*\*"
(empty)

The third file is openspec/specs/file-actions/spec.md, markdown.

So gate-47 is asking for a test co-change to accompany an edit that changed only a comment in a file it classifies as security-touching. There is no behaviour here to test — writing a test to satisfy it would be writing a test for nothing, and I am not going to add a suppression, a baseline entry, or flip require-full-coverage to get past it. All of those turn a gate that is wrong once into a gate that is silent always.

Suggested fix for the gate owner: gate-47 should exclude diffs whose changed lines in the file are entirely comment/docblock. This is the same shape of problem as the other gate-advice hazards seen tonight — the gate's remedy, applied literally, makes the codebase worse rather than better.

The PR itself is sound and its own evidence is in the description: all five repointed anchors resolve against the spec's headings, and the anchor being replaced (#file-crud-operations-on-objects) does not resolve — a negative control proving the anchors were genuinely dangling.

Needs a human call on gate-47 before this can land.