docs(spec): trace 64 frontend methods to their spec, and sync the spec seven tags already pointed at (#471)

gate-16 spec-coverage 64 -> PASS, measured with hydra-gates 651e5c5 at the CI
scope (--scope-to-diff --base origin/beta). gate-46 spec-anchor-existence stays
PASS, so every anchor added here resolves to a heading that exists.

64 changed frontend methods across 24 files carried no @SPEC. Each now names the
requirement it serves — facet views and the facet store to gemma-faceted-search,
the SBOM panel to sbom-import, the suite wizard to suite-wizard, the portfolio
helpers to portfolio-rationalization-time, the view store to view-enrichment-api,
the review modals to catalog-ratings, and so on. No tag was added without
reading the method and the requirement it points at.

openspec/specs/realtime-updates-ui/ is NEW here, and that is the real find.
Change `adopt-live-updates-ui` declares "Affected specs: realtime-updates-ui
(new)" and shipped src/composables/useLiveCollections.js plus its seven
consumers — but the delta was never synced into openspec/specs/. SEVEN @SPEC
tags across six source files have been pointing at a spec that does not exist.
gate-46 never caught it because gate-46 validates ANCHORS (#fragment), not bare
file targets; an audit of every `@spec openspec/specs/<x>/spec.md` in src/ found
this one and only this one dangling. The delta is promoted verbatim — its
requirement, its three scenarios and its author's reason-bearing `@e2e exclude`
are unchanged; the only edits are the title line and the delta's
"## ADDED Requirements" heading becoming "## Requirements", plus a Purpose
recording where it came from. I did not author that exclusion.

I nearly made this worse: the first draft of this change copied the dangling
`@spec openspec/specs/realtime-updates-ui/spec.md` onto useLiveCollections()
itself. Checking the target existed before trusting it is what turned a
propagated broken reference into a fixed one.

Can-fail: reverting the 22 annotated files takes gate-16 from PASS back to 51;
the run before any of this work reported 64 on the same package.

vitest 215/215. gate-46 PASS. No other gate count moved.

Author: rubenvdlinde

openspec/specs/realtime-updates-ui/spec.md

@@ -0,0 +1,43 @@
+# realtime-updates-ui Specification
+
+## Purpose
+Live-update subscription behaviour for Softwarecatalog views that render from the
+`createObjectStore`-based object store. Synced from change `adopt-live-updates-ui`,
+which shipped `src/composables/useLiveCollections.js` and its seven consumers but
+was never synced into `openspec/specs/`.
+
+## Requirements
+
+### Requirement: Store-rendered views MUST subscribe to live updates for their scope
+
+Views that render from Softwarecatalog's `createObjectStore`-based object store MUST subscribe to
+live updates for the data they display: collection-scoped views subscribe to
+`or-collection-{register-slug}-{schema-slug}` per rendered object type, object-scoped views
+subscribe to `or-object-{uuid}`. Subscriptions MUST be re-scoped when the viewed scope
+changes and released when the view is destroyed. Events are refetch HINTS only: views MUST
+refetch through their existing fetch paths and MUST NOT patch rendered state from an event
+payload.
+
+@e2e exclude Requires a second concurrent authenticated session plus a notify_push (or poll-tick) round-trip; covered by the shared library's transport tests and manual two-browser verification.
+
+#### Scenario: Module view refreshes when a rendered collection changes elsewhere
+
+- **GIVEN** a module view (vulnerabilities, compliance matrix, license posture, lifecycle
+  roadmap, or organisaties index) is open
+- **WHEN** another user creates, updates or deletes an object of a type the view renders
+- **THEN** the view receives the `or-collection-{register}-{schema}` hint, the plugin
+  re-runs `fetchCollection` with the last-used params, and the view's `getCollection`-backed
+  computeds re-render the fresh data without a manual refresh
+
+#### Scenario: Subscription waits for lazy type registration
+
+- **GIVEN** a module view mounts before its `loadData()` has registered its object types
+- **WHEN** the registration lands in the store's `objectTypeRegistry`
+- **THEN** the reactive `enabled` gate flips and the subscription attaches — no subscribe
+  call is attempted against an unregistered type
+
+#### Scenario: Subscription released on destroy
+
+- **GIVEN** live subscriptions are active for a module view
+- **WHEN** the user navigates away and the component scope is disposed
+- **THEN** every subscription is released via the composable's scope-bound lifecycle

src/components/cards/OrganisatieCard.vue

@@ -240,6 +240,7 @@ export default {
 		 * a custom cardComponent like this one must emit it explicitly —
 		 * without it, clicking an organisation card was a no-op.
 		 * @return {void}
+		 * @spec openspec/specs/fe-organizations/spec.md
 		 */
 		handleCardClick() {
 			this.$emit('click', this.item)

src/components/reviews/ReviewsPanel.vue

@@ -176,6 +176,7 @@ export default {
 		 * Open the submit-review modal.
 		 *
 		 * @return {void}
+		 * @spec openspec/specs/catalog-ratings/spec.md
 		 */
 		openSubmitModal() {
 			this.showSubmitModal = true

src/components/sbom/SbomComponentsPanel.vue

@@ -206,6 +206,7 @@ export default {
 		 * The moduleVersie's raw data bag.
 		 *
 		 * @return {object} The property bag.
+		 * @spec openspec/specs/sbom-import/spec.md#requirement-imported-components-persist-as-openregister-objects-scoped-to-a-moduleversie
 		 */
 		moduleVersieData() {
 			if (!this.moduleVersie) {
@@ -243,6 +244,7 @@ export default {
 		 * All kwetsbaarheid records — the vulnerability-match candidate set.
 		 *
 		 * @return {Array<object>} The kwetsbaarheid records.
+		 * @spec openspec/specs/sbom-import/spec.md#requirement-components-are-matched-against-existing-kwetsbaarheden-without-external-calls
 		 */
 		kwetsbaarheden() {
 			return objectStore.getCollection('kwetsbaarheid')?.results || []
@@ -263,6 +265,7 @@ export default {
 		 * Display rows for CnDataTable: name/version/purl/licenses plus match badge counts.
 		 *
 		 * @return {Array<object>} The table rows.
+		 * @spec openspec/specs/sbom-import/spec.md#requirement-the-module-version-detail-page-shows-imported-components-with-summary-counts
 		 */
 		rows() {
 			return this.matches.rows.map(({ component, confirmed, possible }) => {
@@ -283,6 +286,7 @@ export default {
 		 * Total imported component count.
 		 *
 		 * @return {number} The count.
+		 * @spec openspec/specs/sbom-import/spec.md#requirement-the-module-version-detail-page-shows-imported-components-with-summary-counts
 		 */
 		totalComponents() {
 			return this.components.length
@@ -292,6 +296,7 @@ export default {
 		 * Distinct, non-empty license count across the imported set.
 		 *
 		 * @return {number} The count.
+		 * @spec openspec/specs/sbom-import/spec.md#requirement-the-module-version-detail-page-shows-imported-components-with-summary-counts
 		 */
 		distinctLicenseCount() {
 			const set = new Set()
@@ -313,6 +318,7 @@ export default {
 		 * deduplicated) across the whole component list.
 		 *
 		 * @return {number} The count.
+		 * @spec openspec/specs/sbom-import/spec.md#requirement-components-are-matched-against-existing-kwetsbaarheden-without-external-calls
 		 */
 		matchedVulnerabilityCount() {
 			return this.matches.matchedVulnerabilityCount
@@ -378,6 +384,7 @@ export default {
 		 *
 		 * @param {string} type Object type slug.
 		 * @return {Promise<void>} Resolves once fetched.
+		 * @spec openspec/specs/sbom-import/spec.md#requirement-the-module-version-detail-page-shows-imported-components-with-summary-counts
 		 */
 		async fetchType(type) {
 			if (typeof objectStore.registerObjectType === 'function'
@@ -402,6 +409,7 @@ export default {
 		 *
 		 * @param {Event} event The file input change event.
 		 * @return {void}
+		 * @spec openspec/specs/sbom-import/spec.md#requirement-uploaded-sbom-files-are-bounded-in-size-and-json-only
 		 */
 		handleFileSelect(event) {
 			const file = event.target.files[0]
@@ -417,6 +425,7 @@ export default {
 		 *
 		 * @param {number} bytes The size in bytes.
 		 * @return {string} A human-readable size.
+		 * @spec openspec/specs/sbom-import/spec.md#requirement-uploaded-sbom-files-are-bounded-in-size-and-json-only
 		 */
 		formatFileSize(bytes) {
 			if (!bytes) {

src/composables/useLiveCollections.js

@@ -26,6 +26,15 @@
 import { computed } from 'vue'
 import { useObjectSubscription } from '@conduction/nextcloud-vue'
 
+/**
+ * Subscribe a component to live updates for a static list of object types.
+ *
+ * @param {object} objectStore The app's createObjectStore-based store instance.
+ * @param {Array<string>} types Object type slugs to subscribe to (static list).
+ * @return {void}
+ *
+ * @spec openspec/specs/realtime-updates-ui/spec.md
+ */
 export function useLiveCollections(objectStore, types) {
 	for (const type of types) {
 		useObjectSubscription(objectStore, type, null, {

src/dialogs/SuiteWizard/Step1Details.vue

@@ -64,11 +64,21 @@ export default {
 		 * `onField` so `_step1Valid` recomputes on every keystroke.
 		 *
 		 * @return {string} The current long description.
+		 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-shall-guide-suite-creation-through-details-application-attachment-and-confirmation-steps
 		 */
 		beschrijvingLangModel: {
+			/**
+			 * @return {string} The current long description.
+			 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-shall-guide-suite-creation-through-details-application-attachment-and-confirmation-steps
+			 */
 			get() {
 				return this.payload.beschrijvingLang || ''
 			},
+			/**
+			 * @param {string} value The new long description.
+			 * @return {void}
+			 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-shall-guide-suite-creation-through-details-application-attachment-and-confirmation-steps
+			 */
 			set(value) {
 				this.onField('beschrijvingLang', value)
 			},
@@ -86,6 +96,7 @@ export default {
 		 * @param {string} key The stepData field to update.
 		 * @param {string} value The new value.
 		 * @return {void}
+		 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-must-require-at-least-one-attached-application-before-advancing-past-the-applications-step
 		 */
 		onField(key, value) {
 			const merged = { ...this.payload, [key]: value }

src/dialogs/SuiteWizard/Step2Applications.vue

@@ -73,6 +73,7 @@ export default {
 		 * Existing modules, mapped to `NcSelect` option shape.
 		 *
 		 * @return {Array<{uuid: string, label: string, raw: object}>}
+		 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-shall-guide-suite-creation-through-details-application-attachment-and-confirmation-steps
 		 */
 		applicationOptions() {
 			// `getCollection()` returns the paginated ENVELOPE ({ results, ... }),
@@ -89,6 +90,7 @@ export default {
 		 * so re-entering this step (e.g. via "Back") keeps the selection.
 		 *
 		 * @return {Array<object>}
+		 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-must-require-at-least-one-attached-application-before-advancing-past-the-applications-step
 		 */
 		selected() {
 			const applications = this.payload.applications || []
@@ -149,6 +151,7 @@ export default {
 		 *
 		 * @param {Array<{raw: object}>} options The selected NcSelect options.
 		 * @return {void}
+		 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-must-require-at-least-one-attached-application-before-advancing-past-the-applications-step
 		 */
 		onSelectionChange(options) {
 			const applications = (options || []).map((option) => option.raw)

src/dialogs/SuiteWizard/Step3Confirm.vue

@@ -57,6 +57,7 @@ export default {
 		 * The attached applications' names, for the review list.
 		 *
 		 * @return {Array<string>}
+		 * @spec openspec/specs/suite-wizard/spec.md#requirement-submitting-the-wizard-shall-create-a-suite-object-with-the-attached-applications
 		 */
 		applicationNames() {
 			return summarizeApplications(this.payload.applications)

src/dialogs/SuiteWizardDialog.vue

@@ -81,6 +81,7 @@ export default {
 		 * Seed values for the wizard's shared stepData.
 		 *
 		 * @return {object}
+		 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-shall-guide-suite-creation-through-details-application-attachment-and-confirmation-steps
 		 */
 		defaults() {
 			return {
@@ -98,6 +99,7 @@ export default {
 		 * (attach existing only), confirm.
 		 *
 		 * @return {Array<{id: string, label: string}>}
+		 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-shall-guide-suite-creation-through-details-application-attachment-and-confirmation-steps
 		 */
 		wizardSteps() {
 			return [
@@ -191,6 +193,7 @@ export default {
 		 * reopens fresh.
 		 *
 		 * @return {void}
+		 * @spec openspec/specs/suite-wizard/spec.md#requirement-the-wizard-shall-guide-suite-creation-through-details-application-attachment-and-confirmation-steps
 		 */
 		onClose() {
 			this.$emit('update:show', false)

src/modals/SaveFacetViewModal.vue

@@ -80,6 +80,14 @@ export default {
 	},
 
 	watch: {
+		/**
+		 * Clear the name field each time the modal is (re)opened, so a
+		 * previous attempt's text never leaks into the next save.
+		 *
+		 * @param {boolean} value Whether the modal became visible.
+		 * @return {void}
+		 * @spec openspec/specs/gemma-faceted-search/spec.md#requirement-a-facet-selection-can-be-saved-as-a-view
+		 */
 		show(value) {
 			if (value === true) {
 				this.name = ''
@@ -89,14 +97,20 @@ export default {
 
 	methods: {
 		/**
+		 * Dismiss the modal without saving.
+		 *
 		 * @return {void}
+		 * @spec openspec/specs/gemma-faceted-search/spec.md#requirement-a-facet-selection-can-be-saved-as-a-view
 		 */
 		closeModal() {
 			this.$emit('close')
 		},
 
 		/**
+		 * Emit the trimmed view name, refusing an empty one.
+		 *
 		 * @return {void}
+		 * @spec openspec/specs/gemma-faceted-search/spec.md#requirement-a-facet-selection-can-be-saved-as-a-view
 		 */
 		save() {
 			const trimmed = this.name.trim()