Skip to content

fix(spec): 102 @spec anchors pointed at nothing — three distinct causes - #157

Merged
rubenvdlinde merged 1 commit into
developmentfrom
fix/gate46-adr037-req-headings
Aug 9, 2026
Merged

rubenvdlinde merged 1 commit into
developmentfrom
fix/gate46-adr037-req-headings

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

gate-46 spec-anchor-existence measured 102 unresolved findings across 41 targets on development. They are not 102 bad tags. They are three defects, and each is fixed at its cause.

Measured with gate package 48c88ba1e0d049f8f38538c33e790d3e603c55d0, full-repo run: gate-46 102 → 0.

1. Tags pointing into an ARCHIVED change directory — 52 findings

Seven targets named openspec/changes/<change>/specs/<cap>/spec.md for changes that have since been archived. The resolver's archive index finds the frozen copy under openspec/changes/archive/<date>-<change>/ and judges the anchor against that snapshot — so it never consults the canonical spec, and editing the canonical spec has no effect at all. (I verified that the hard way: my first edit to openspec/specs/automation-designer/spec.md moved the count by zero.)

Retargeted to openspec/specs/<capability>/spec.md — where the project rule, and openbuild#152's own SpecTagSniff, say a @spec tag points.

2. Requirement IDs lived in the body, not the heading — 50 findings

The specs carried the ID as a body line:

### Requirement: Automations page lists automations per application version

… prose …

**ID:** REQ-AUTD-001

ADR-037 rule 2 is explicit that this is the wrong shape, and explicit about why: the ID belongs in the heading as a parenthesised suffix. An anchor resolves against headings, so #req-autd-001 named nothing.

Moved the IDs into the headings for every requirement in the six specs involved — not only the ones a tag happens to reference — so the files are uniformly ADR-037 Form A rather than half-migrated.

3. 2.1 written as 21 — 15 findings

#task-21 is read by the gate as "the 21st checkbox". The tasks files have 17. The tags meant task 2.1, and each lines up exactly with its task — SetupController.php was tagged #task-21 against "2.1 Create lib/Controller/SetupController.php". The spelling that names it is #task-2.1.

Proof it can fail

Run against the same file, same helper, same package:

fragment verdict
#task-21 FAIL
#task-2.1 resolves
#req-obr-007b before the heading edit FAIL
#req-obr-007b after resolves

The fix is the tags and the specs becoming correct, not the check becoming weaker. No gate config, no baseline, no exclude was touched.

One thing this PR surfaces but does not fix

gate-61 listener-work-placement reports 6 findings on this branch that development does not show. They are pre-existing debt in AutomationApprovalTriggerListener and DocumentGenerationListener (unbounded findAll() on the write path, ADR-078). gate-61 is diff-scoped against origin/development inside its own helper, so it only inspects files a change touches — and these @spec retags are what pulled those two files into its scope. No behaviour in either listener changed here. Tracked separately.

gate-46 spec-anchor-existence measured 102 unresolved findings across 41
targets. They are not 102 bad tags; they are three defects.

1. TAGS POINTING AT AN ARCHIVED CHANGE DIR (52 findings).
   Seven targets named `openspec/changes/<change>/specs/<cap>/spec.md` for
   changes that have since been archived. The gate's resolver finds the
   ARCHIVED copy under `openspec/changes/archive/<date>-<change>/` and judges
   the anchor against that frozen snapshot — never against the canonical
   spec. Retargeted to `openspec/specs/<capability>/spec.md`, which is where
   the project rule (and openbuild#152's SpecTagSniff) says a @SPEC tag
   points.

2. REQUIREMENT IDS LIVED IN THE BODY, NOT THE HEADING (50 findings).
   The specs carried `**ID:** REQ-XXX-NNN` as a body line. ADR-037 rule 2 is
   explicit that the ID belongs in the heading as a parenthesised suffix, and
   explicit about why the body line is wrong. An anchor resolves against
   HEADINGS, so `#req-autd-001` named nothing. Moved the IDs into the
   headings for every requirement in the six specs involved — not only the
   ones a tag happens to reference, so the files are uniformly ADR-037 Form A.

3. `2.1` WRITTEN AS `21` (15 findings).
   `#task-21` is read by the gate as "the 21st checkbox". The tasks files
   have 17. The tags meant task **2.1** — and each one lines up exactly with
   its task (SetupController against 2.1 "Create SetupController.php"). The
   anchor spelling that names it is `#task-2.1`.

Measured with the helper directly, both directions: `#task-21` FAILS and
`#task-2.1` RESOLVES against the same file, so the fix is not the check
being loosened. Full suite at gate package 48c88ba: gate-46 102 -> 0.

Note: gate-61 (listener-work-placement) reports 6 findings on this branch
that development does not show. They are PRE-EXISTING debt in
AutomationApprovalTriggerListener and DocumentGenerationListener — gate-61
is diff-scoped against origin/development inside its own helper, and these
@SPEC retags are what pulled the two files into its scope. No behaviour in
either listener changed here.
@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/openbuild @ 9e9b067

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
test-l10n ✅
check-gitignore ✅
composer ✅ ✅ 101/101
npm ✅ ✅ 654/654
PHPUnit ✅
Newman ⏭️
Playwright ❌
Hydra gates ❌

Quality workflow — 2026-08-09 14:42 UTC

Download the full PDF report from the workflow artifacts.

@rubenvdlinde
rubenvdlinde merged commit b975ccf into development Aug 9, 2026
29 of 32 checks passed
rubenvdlinde pushed a commit that referenced this pull request Aug 9, 2026
…n CI

gate-16 spec-coverage: 2 -> 0 on this branch's diff.

CI caught what my local run could not: gate-16 is DIFF-SCOPED, so a full-repo
run reports nothing for it and my "no other gate moved" check was blind to it
by construction. The two findings are both in the new file this PR adds:

  src/dialogs/PromptTextDialog.vue::onSubmit — missing @SPEC
  src/dialogs/PromptTextDialog.vue::open     — missing @SPEC

(`open` is the WATCHER on the `open` prop, which is a method in the options
object — worth knowing, because it reads like a prop in the finding.)

Both now carry `@spec openspec/specs/openconnector-api-sources/spec.md
#req-ocas-003` — "Schema mapping of the external payload to display fields",
which is exactly what this dialog serves: it collects the display-field name
for a mapped leaf.

Deliberately the CANONICAL spec, not the tasks file the calling component
uses. `openspec/changes/openconnector-api-sources/tasks.md#task-3.1` does
resolve, but only through the ARCHIVE index — it is an archived change dir,
which is precisely the shape #157 cleaned 52 tags out of. Adding a new tag of
that shape would re-introduce it. Verified the canonical anchor resolves
directly: has_anchor('openspec/specs/openconnector-api-sources/spec.md',
'req-ocas-003') -> True.

Re-measured --scope-to-diff --base origin/development at gate package
365fa31: NO gate fails on this diff (gate-16 PASS, gate-34 PASS, gate-46
PASS). eslint clean; vitest 140 files / 1375 tests pass.
rubenvdlinde added a commit that referenced this pull request Aug 9, 2026
…logs (#163)

* fix(a11y): replace 7 native window.confirm/prompt calls with real dialogs

gate-34 window-confirm: 7 -> 0. Measured full-repo at gate package 651e5c5.

Native window.confirm/prompt blocks the JS thread, cannot be translated or
themed, and inside Nextcloud's modal stack renders outside the dialog the user
is already in. window.prompt is worse still: its input has no programmatic
label at all.

All seven call sites had the same shape — a synchronous boolean guard in front
of a destructive continuation — so they share two new components rather than
each growing an inline NcDialog, which ADR-004 / gate-13 forbids:

  src/dialogs/ConfirmActionDialog.vue   (6 sites)
  src/dialogs/PromptTextDialog.vue      (1 site, the window.prompt)

Sites: AutomationsPage (delete automation), ThemeSection (remove theme),
SchedulesSection (remove task), WorkflowAttachmentsSection (detach case type),
DocumentAttachmentsSection (detach template), DataSourceOriginToggle (discard
connector mapping), ConnectorFieldMapper (name a display field).

THE FAIL-SAFE DIRECTION IS PRESERVED, AND NOW TESTED. The dialogs never run
the action; they only emit. The parent holds the target in `pending*` and acts
only in an `onConfirm*` handler, so a closed, cancelled or dismissed dialog
leaves state untouched. Every one of the six sites gained a test asserting the
destructive step has NOT run after the ask — the property window.confirm gave
us for free and the one worth pinning.

Two behaviours improved rather than merely ported:
  * AutomationsPage keeps the dialog open with disabled buttons while the
    DELETE is in flight (`busy`) — a synchronous confirm could not express it.
  * PromptTextDialog disables submit while the value is blank, so the empty
    -name guard is enforced at the source instead of by `if (!name) return`.

Verification, all re-run on this branch:
  * gate-34 PASS. Proven not blind: planting one window.confirm back into
    ThemeSection flips it PASS -> FAIL(1) -> PASS on removal.
  * gate-12 nc-input-labels PASS, gate-13 modal-isolation PASS, gate-16
    spec-coverage PASS — the new dialogs did not push a finding elsewhere.
  * vitest 140 files / 1375 tests pass (was 1366; +9 net).
  * eslint clean on all changed and new files.
  * check-l10n OK; 6 new source strings registered in en.json AND nl.json.

* fix(spec): tag PromptTextDialog's two methods, which gate-16 caught in CI

gate-16 spec-coverage: 2 -> 0 on this branch's diff.

CI caught what my local run could not: gate-16 is DIFF-SCOPED, so a full-repo
run reports nothing for it and my "no other gate moved" check was blind to it
by construction. The two findings are both in the new file this PR adds:

  src/dialogs/PromptTextDialog.vue::onSubmit — missing @SPEC
  src/dialogs/PromptTextDialog.vue::open     — missing @SPEC

(`open` is the WATCHER on the `open` prop, which is a method in the options
object — worth knowing, because it reads like a prop in the finding.)

Both now carry `@spec openspec/specs/openconnector-api-sources/spec.md
#req-ocas-003` — "Schema mapping of the external payload to display fields",
which is exactly what this dialog serves: it collects the display-field name
for a mapped leaf.

Deliberately the CANONICAL spec, not the tasks file the calling component
uses. `openspec/changes/openconnector-api-sources/tasks.md#task-3.1` does
resolve, but only through the ARCHIVE index — it is an archived change dir,
which is precisely the shape #157 cleaned 52 tags out of. Adding a new tag of
that shape would re-introduce it. Verified the canonical anchor resolves
directly: has_anchor('openspec/specs/openconnector-api-sources/spec.md',
'req-ocas-003') -> True.

Re-measured --scope-to-diff --base origin/development at gate package
365fa31: NO gate fails on this diff (gate-16 PASS, gate-34 PASS, gate-46
PASS). eslint clean; vitest 140 files / 1375 tests pass.

---------

Co-authored-by: Ruben van der Linde <juan.claude@conduction.nl>
@rubenvdlinde
rubenvdlinde deleted the fix/gate46-adr037-req-headings branch August 14, 2026 09:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants