docs: ADR infrastructure, story authoring workflow, and InvenioRDM stakeholder documents

[sven1103-agent]

WIP: InvenioRDM Dataset Connection — Documentation, Governance, and Prototype

Draft PR. This branch carries a prototype-stage exploration of connecting InvenioRDM datasets to Data Manager projects. The documentation, governance updates, and UI prototype included here are works-in-progress, open for early review.

What's in this PR

📘 Governance & Documentation

• ADR infrastructure — New docs/adr/ directory with:
  • MADR template (docs/adr/templates/madr-template.md) — blank template for creating Architecture Decision Records
  • README.md — index, naming convention, creation rules, and lifecycle (append-only)
  • templates/LICENSE.md — MADR license attribution (MIT OR CC0-1.0)
• Story authoring workflow — AGENTS.md §11.1 updated to define the two decoupled surfaces (stakeholder space = Word Online/SharePoint, PO-internal; developer space = GitHub/docs/features.md) and cast the PO as the handoff actor. Post-approval changes now explicitly go through GitHub PRs.
• ADR cross-references — docs/requirements.md and docs/requirements-guide.md now link ADR mentions to docs/adr/README.md.

📄 Stakeholder Documents (reference only)

• Feature brief and Connected Resource Information specification are referenced from GitHub feature issue #1466 and live in stakeholder space (Word Online / SharePoint). They are intentionally not committed to this repository per AGENTS.md §11.1.

🎨 Prototype UI (AssociatedDatasetsDemoV2)

• Vaadin prototype demonstrating the InvenioRDM dataset search & connect flow
• Account settings workflow for InvenioRDM credential (token) management
• Demonstrates open + restricted dataset handling

📝 Related documentation

• docs/feature-vision-associated-datasets.md — vision document (with a note flagging the updated integration mechanism)
• docs/prototypes/connect-resources/ — init prompts for prototype exploration sessions

GitHub Issues (already created)

• Feature: #1466 — FEAT-DATASET-CONNECTION
• Stories: #1467 through #1479 (13 children, linked)
• Stories 10 and 11 are TBD in the source document and were intentionally not created yet

Proposed Requirement IDs (pending formal addition to docs/requirements.md)

ID	Description
DATA-R-01	Dataset Connection Management (search, connect, view, remove)
DATA-R-02	Dataset Synchronisation
DATA-R-03	InvenioRDM Credential Management
COMM-R-01	Project Change Notifications

Integration Mechanism

The original feature brief was designed around FAIR Signposting as the integration mechanism. This has been revised — a severe bug in InvenioRDM's FAIR Signposting serialization has been reported upstream, and the fix is scheduled for a future major release that would delay the feature unacceptably. The current design uses conventional API-based integration against the InvenioRDM OpenAPI. The markdown renderings of the feature brief in the repo (docs/feature-vision-associated-datasets.md and docs/prototypes/connect-resources/2026-06-19_FEATURE_Connect_associated_datasets.md) still carry the original stakeholder wording but include a prominent correction note.

⚠️ Known Open Items

• Governance update (AGENTS.md §11.1) currently describes a PO-as-bridge model but the PO did not author the GitHub issues directly (the issues were created as part of this PR's exploration). Need to reconcile with the workflow: PO reviews the issues and provides explicit approval before they become the authoritative source of truth.
• Requirement IDs are proposed and need PO/lead confirmation before being formalized in docs/requirements.md.
• Prototype Java code is exploratory only — not intended for production merge in this branch.
• Some binary files (img.png, img_1.png, ui-screenshot-restricted.png) and dev.bundle are prototype artifacts — may warrant cleanup before final merge.

Testing notes

Prototype-only at this stage. No production tests apply to the documentation changes. The prototype Java view is annotated with @AnonymousAllowed for local exploration.

[gitguardian]

️✅ There are no secrets present in this pull request anymore.

If these secrets were true positive and are still valid, we highly recommend you to revoke them.
While these secrets were previously flagged, we no longer have a reference to the
specific commits where they were detected. Once a secret has been leaked into a git
repository, you should consider it compromised, even if it was deleted immediately.
Find here more information about risks.

---

^{_{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}}

[sonarqubecloud]

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)
D Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

💡 Need a hand with PR review? Try Gitar by Sonar!