Add weighted station stakeholder mappings

Author: mniinio

README.md

@@ -53,7 +53,21 @@ import {
 
 The `method-engine` export is intended for reusable APIOps workflow logic. It gives CLIs, AI agents, apps, and APIs the same station recommendation, resource lookup, and canvas generation behavior without reimplementing the method rules.
 
-Sticky note authoring should uses the shared palette exposed by the method engine:
+The method now also includes reusable stakeholder data:
+
+- `src/data/method/stakeholders.json` defines the shared stakeholder catalog
+- `src/data/method/station-stakeholders.json` maps each station to weighted stakeholder participation
+- `src/data/method/<locale>/labels.stakeholders.json` stores localized stakeholder titles, descriptions, and involvement labels
+
+Stakeholder involvement uses three lightweight levels:
+
+- `lead`
+- `core`
+- `consulted`
+
+This is meant to keep APIOps Cycles explicitly cross-functional, including business, security, compliance, support, and consumer voices in architecture and design work where relevant.
+
+Sticky note authoring should use the shared palette exposed by the method engine:
 
 - `benefit`: `#C0EB6A`
 - `neutral`: `#DFDDC5`
@@ -88,16 +102,17 @@ If you spot a problem in the documentation or have an idea for new content, plea
 
 ### Editing or adding content
 
-The main method content files (instructions, guidelines, method structure) are located in the the JSON files at `src/data/method/`. These base files (`lines.json`, `stations.json`, `resources.json`, `criteria.json` and `station-criteria.json`) are not localized and live at the root of the folder. Textual values in them reference label keys. English labels are in `src/data/method/en-US` and translations are provided in `labels.lines.json`, `labels.stations.json`, `labels.resources.json` and `labels.criteria.json` under each locale folder. Some longer or more complex resource pages like the API Audit Checklist also use markdown snippets `src/snippets/` linked to the `resources.json`. Do not use any frontmatter in the snippet files. Any supported markdown markup is ok. See references from [Starlight markdown reference](https://starlight.astro.build/guides/authoring-content/) and [Extended markdown reference](https://www.markdownguide.org/extended-syntax/).
+The main method content files (instructions, guidelines, method structure) are located in the JSON files at `src/data/method/`. These base files (`lines.json`, `stations.json`, `resources.json`, `criteria.json`, `station-criteria.json`, `stakeholders.json`, and `station-stakeholders.json`) are not localized and live at the root of the folder. Textual values in them reference label keys. English labels are in `src/data/method/en` and translations are provided in `labels.lines.json`, `labels.stations.json`, `labels.resources.json`, `labels.criteria.json`, and `labels.stakeholders.json` under each locale folder. Some longer or more complex resource pages like the API Audit Checklist also use markdown snippets `src/snippets/` linked to the `resources.json`. Do not use any frontmatter in the snippet files. Any supported markdown markup is ok. See references from [Starlight markdown reference](https://starlight.astro.build/guides/authoring-content/) and [Extended markdown reference](https://www.markdownguide.org/extended-syntax/).
 
-Each station links to specific entry criteria followed by the next core station's criteria as exit criteria.`criteria.json`, `station-criteria.json` and `labels.criteria.json` 
+Each station links to specific entry criteria followed by the next core station's criteria as exit criteria. Stakeholder participation is modeled separately through `stakeholders.json`, `station-stakeholders.json`, and `labels.stakeholders.json`.
 
 #### Editing existing content of Method pages (metrolines, core- and substations, resources). 
 1. Go to `src/data/method/en` and edit the content in English (English is considered the master langauge, and for the translations to work for other languages, it must always be the first to be edited). 
 2. Validate that your changes work by running the schema validations (`npm test`)
 3. Follow the translation guide if you are able to translate the content to other languages manually or automatically.
-4. Commit your code and make a pull request.
-5. If you were not able to create the translations of your changes to all languages, create an issue for in the repository for the translations.
+4. Update all supported locales before considering the change complete. This includes criteria wording and stakeholder labels when those are touched.
+5. Commit your code and make a pull request.
+6. If you were not able to create the translations of your changes to all languages, create an issue in the repository for the translations.
 
 #### Translating the language manually or with automated services (new or existing languages with new or changed content)
 

package.json

@@ -23,10 +23,12 @@
     "./localizedData.json": "./src/data/canvas/localizedData.json",
     "./method/stations.json": "./src/data/method/stations.json",
     "./method/resources.json": "./src/data/method/resources.json",
-    "./method/station-criteria.json": "./src/data/method/station-criteria.json"
+    "./method/station-criteria.json": "./src/data/method/station-criteria.json",
+    "./method/stakeholders.json": "./src/data/method/stakeholders.json",
+    "./method/station-stakeholders.json": "./src/data/method/station-stakeholders.json"
   },
   "scripts": {
-    "test": "node scripts/validate.mjs && node scripts/test-note-colors.mjs && node scripts/test-print-method-snippet.mjs",
+    "test": "node scripts/validate.mjs && node scripts/test-method-stakeholders.mjs && node scripts/test-note-colors.mjs && node scripts/test-print-method-snippet.mjs",
     "release:create-apiops:pack": "npm pack --workspace packages/create-apiops",
     "release:create-apiops:publish": "npm publish --workspace packages/create-apiops --access public",
     "check:packaging:skills": "node scripts/check-packaging-skills.mjs",

scripts/test-method-stakeholders.mjs

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import * as methodEngine from "../src/lib/method-engine.js";
+
+const stations = methodEngine.getStations();
+const stationIds = new Set(stations.map((station) => station.id));
+const stakeholderIds = new Set(methodEngine.getStakeholders().map((stakeholder) => stakeholder.id));
+const stationStakeholderMap = methodEngine.getStationStakeholderMap();
+
+for (const station of stations) {
+  const entries = stationStakeholderMap[station.id];
+  assert.ok(entries, `Missing stakeholder mapping for ${station.id}.`);
+  assert.ok(entries.length > 0, `Expected at least one stakeholder mapping for ${station.id}.`);
+
+  const seenStakeholders = new Set();
+  const leads = entries.filter((entry) => entry.involvement === "lead");
+  const cores = entries.filter((entry) => entry.involvement === "core");
+
+  assert.equal(leads.length, 1, `Expected exactly one lead for ${station.id}.`);
+  assert.ok(cores.length > 0, `Expected at least one core stakeholder for ${station.id}.`);
+
+  for (const entry of entries) {
+    assert.ok(stakeholderIds.has(entry.stakeholder), `Unknown stakeholder ${entry.stakeholder} in ${station.id}.`);
+    assert.ok(!seenStakeholders.has(entry.stakeholder), `Duplicate stakeholder ${entry.stakeholder} in ${station.id}.`);
+    seenStakeholders.add(entry.stakeholder);
+  }
+
+  const localizedStakeholders = methodEngine.buildStationStakeholderData(station.id, "fi");
+  assert.equal(localizedStakeholders.length, entries.length, `Localized stakeholder count mismatch for ${station.id}.`);
+  assert.ok(localizedStakeholders.every((entry) => entry.title && entry.description && entry.involvementLabel), `Incomplete localized stakeholder data for ${station.id}.`);
+}
+
+for (const stationId of Object.keys(stationStakeholderMap)) {
+  assert.ok(stationIds.has(stationId), `Stakeholder mapping references unknown station ${stationId}.`);
+}
+
+const startData = methodEngine.buildStartData("en");
+assert.ok(startData.every((station) => Array.isArray(station.stakeholders) && station.stakeholders.length > 0), "Expected stakeholders in start data.");
+
+const designData = methodEngine.buildStationResourceData("api-design", "en");
+assert.ok(Array.isArray(designData.stakeholders) && designData.stakeholders.length > 0, "Expected stakeholders in station resource data.");
+assert.ok(designData.stakeholders.some((entry) => entry.id === "security-specialist"), "Expected api-design to include security-specialist.");
+assert.ok(designData.stakeholders.some((entry) => entry.id === "compliance-legal-specialist"), "Expected api-design to include compliance-legal-specialist.");
+assert.ok(designData.stakeholders.some((entry) => entry.id === "business-owner"), "Expected api-design to include business-owner.");
+
+const architectureData = methodEngine.buildStationResourceData("api-platform-architecture", "en");
+assert.ok(architectureData.stakeholders.some((entry) => entry.id === "security-specialist"), "Expected api-platform-architecture to include security-specialist.");
+assert.ok(architectureData.stakeholders.some((entry) => entry.id === "compliance-legal-specialist"), "Expected api-platform-architecture to include compliance-legal-specialist.");
+
+const fallbackStakeholders = methodEngine.buildStationStakeholderData("api-product-strategy", "sv");
+assert.ok(fallbackStakeholders.some((entry) => entry.involvementLabel === "Lead"), "Expected missing locale fallback to English stakeholder labels.");
+
+console.log("Method stakeholder regression test passed.");

scripts/validate.mjs

@@ -51,7 +51,9 @@ async function gatherTemplateFiles() {
   await validate('src/schemas/criteria.schema.json', ['src/data/method/criteria.json']);
   await validate('src/schemas/lines.schema.json', ['src/data/method/lines.json']);
   await validate('src/schemas/resources.schema.json', ['src/data/method/resources.json']);
+  await validate('src/schemas/stakeholders.schema.json', ['src/data/method/stakeholders.json']);
   await validate('src/schemas/station-criteria.schema.json', ['src/data/method/station-criteria.json']);
+  await validate('src/schemas/station-stakeholders.schema.json', ['src/data/method/station-stakeholders.json']);
   await validate('src/schemas/stations.schema.json', ['src/data/method/stations.json']);
   await validate('src/schemas/canvasData.schema.json', ['src/data/canvas/canvasData.json']);
   await validate('src/schemas/canvas-localized.schema.json', ['src/data/canvas/localizedData.json']);

src/data/method/criteria.json

@@ -1,7 +1,7 @@
 [
   {
     "id": "metrics-feedback-available",
-    "description": "Insights from metrics and feedback are available to optimize existing APIs."
+    "description": "Relevant market signals, feedback, or operational insights are available to guide this API opportunity."
   },
   {
     "id": "business-goals-defined",
@@ -13,7 +13,7 @@
   },
   {
     "id": "stakeholder-approval",
-    "description": "Stakeholders approve strategy discussions."
+    "description": "Relevant stakeholders agree this API opportunity is worth exploring and prioritizing."
   },
   {
     "id": "api-opportunity-documented",
@@ -25,11 +25,11 @@
   },
   {
     "id": "hide-backend-discrepancies",
-    "description": "The goal of the API is to hide backend data models and discrepancies."
+    "description": "The API is intended to shield consumers from backend complexity and inconsistencies."
   },
   {
     "id": "value-prop-validated",
-    "description": "The value proposition validates with key stakeholders."
+    "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders."
   },
   {
     "id": "consumer-segments-identified",
@@ -41,46 +41,46 @@
   },
   {
     "id": "architecture-patterns-validated",
-    "description": "The API architecture uses patterns that promote reusability and integration, and is validated with stakeholders."
+    "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders."
   },
   {
     "id": "design-reflects-business-value",
-    "description": "The API's design and endpoints have a clear connection to their business value and features."
+    "description": "The API design and exposed capabilities clearly trace back to business value and user needs."
   },
   {
     "id": "api-consistency",
-    "description": "API has a consistent design with our other API products."
+    "description": "The API design follows our shared API product and design conventions."
   },
   {
     "id": "api-contract-tested",
     "description": "The API contract is tested and meets functional and non-functional requirements."
   },
   {
     "id": "api-description-available",
-    "description": "The API and its endpoints have descriptions that explain their business value and features."
+    "description": "The API and its exposed capabilities are described clearly enough for review, audit, and onboarding."
   },
   {
     "id": "audit-passed",
     "description": "The API passes compliance, security, and audit checks."
   },
   {
     "id": "audit-reports-shared",
-    "description": "Audit reports are shared with stakeholders."
+    "description": "Audit findings and remediation decisions are shared with the relevant stakeholders."
   },
   {
     "id": "api-ready-for-publishing",
-    "description": "The API is ready to be published to the appropriate gateways and environments to support reusability for multiple API consumers."
+    "description": "The API is ready to be deployed and exposed through the intended gateways and environments."
   },
   {
     "id": "api-documentation-ready",
-    "description": "API documentation is complete and ready for publishing."
+    "description": "Consumer-facing API documentation is complete enough for publishing and onboarding."
   },
   {
     "id": "consumer-support-ready",
-    "description": "API registration, support, and communication processes are in place."
+    "description": "Registration, support, and communication processes are ready for API consumers."
   },
   {
     "id": "legal-compliance-clear",
-    "description": "Legal and compliance requirements are precise enough for publishing."
+    "description": "Legal, privacy, and compliance requirements for publishing are defined and understood."
   }
-]
+]

src/data/method/de/labels.criteria.json

@@ -1,25 +1,25 @@
 {
   "exit_criteria": "Austrittskriterien",
   "entry_criteria": "Eintrittskriterien",
-  "criterion.metrics-feedback-available": "Erkenntnisse aus Metriken und Feedback stehen zur Optimierung bestehender APIs zur Verfügung",
+  "criterion.metrics-feedback-available": "Relevante Marktsignale, Feedback oder operative Erkenntnisse sind verfügbar, um diese API-Möglichkeit zu steuern.",
   "criterion.business-goals-defined": "Geschäftsziele sind definiert",
   "criterion.market-research-done": "Marktforschung identifiziert API-Möglichkeiten",
-  "criterion.stakeholder-approval": "Stakeholder genehmigen Strategiediskussionen",
+  "criterion.stakeholder-approval": "Relevante Stakeholder stimmen zu, dass diese API-Möglichkeit es wert ist, sie zu erkunden und Priorität einzuräumen.",
   "criterion.api-opportunity-documented": "Individuelle API-Möglichkeiten werden identifiziert und dokumentiert",
   "criterion.api-reusability": "Die API erfüllt einen klaren Geschäftsbedarf und ist für mehrere API-Nutzer wiederverwendbar",
-  "criterion.hide-backend-discrepancies": "Das Ziel der API ist es, Backend-Datenmodelle und Diskrepanzen zu verbergen.",
-  "criterion.value-prop-validated": "Das Wertversprechen wird mit den wichtigsten Stakeholdern validiert.",
+  "criterion.hide-backend-discrepancies": "Die API ist dazu gedacht, Verbraucher vor Backend-Komplexität und Inkonsistenzen zu schützen.",
+  "criterion.value-prop-validated": "Die API-Wert proposition wurde mit den relevanten Geschäft und Verbraucher-Stakeholdern überprüft und validiert.",
   "criterion.consumer-segments-identified": "API-Nutzersegmente (intern und extern) werden identifiziert.",
   "criterion.api-roadmap-defined": "Hochrangige Roadmaps für die API-Entwicklung werden erstellt.",
-  "criterion.architecture-patterns-validated": "Die API-Architektur verwendet Muster, die die Wiederverwendbarkeit und Integration fördern, und wird mit den Stakeholdern validiert.",
-  "criterion.design-reflects-business-value": "Das Design und die Endpunkte der API stehen in klarem Zusammenhang mit ihrem geschäftlichen Nutzen und ihren Funktionen.",
-  "criterion.api-consistency": "Die API weist ein einheitliches Design mit unseren anderen API-Produkten auf.",
+  "criterion.architecture-patterns-validated": "Die gewählten API-Architektur- und Plattformmuster wurden mit den relevanten Architektur-, Sicherheits- und Plattform-Stakeholdern validiert.",
+  "criterion.design-reflects-business-value": "Die API-Design und die offengelegten Funktionen spiegeln klar den Geschäftswert und die Bedürfnisse der Benutzer wider.",
+  "criterion.api-consistency": "Das API-Design folgt unseren gemeinsamen API-Produkt- und Design-Vorgaben.",
   "criterion.api-contract-tested": "Der API-Vertrag wurde getestet und erfüllt die funktionalen und nicht-funktionalen Anforderungen.",
-  "criterion.api-description-available": "Die API und ihre Endpunkte verfügen über Beschreibungen, die ihren geschäftlichen Nutzen und ihre Funktionen erläutern.",
+  "criterion.api-description-available": "Die API und ihre offengelegten Funktionen sind ausreichend beschrieben für Überprüfung, Auditierung und Onboarding.",
   "criterion.audit-passed": "Die API besteht Compliance-, Sicherheits- und Audit-Prüfungen.",
-  "criterion.audit-reports-shared": "Auditberichte werden mit den Stakeholdern geteilt.",
-  "criterion.api-ready-for-publishing": "Die API kann in den entsprechenden Gateways und Umgebungen veröffentlicht werden, um die Wiederverwendbarkeit für mehrere API-Nutzer zu unterstützen.",
-  "criterion.api-documentation-ready": "Die API-Dokumentation ist vollständig und bereit zur Veröffentlichung.",
-  "criterion.consumer-support-ready": "Prozesse für die API-Registrierung, den Support und die Kommunikation sind eingerichtet.",
-  "criterion.legal-compliance-clear": "Die rechtlichen und Compliance-Anforderungen sind für die Veröffentlichung präzise genug."
+  "criterion.audit-reports-shared": "API-Auditberichte wurden mit relevanten Stakeholdern geteilt.",
+  "criterion.api-ready-for-publishing": "Die API ist bereit, für Verbraucher verfügbar gemacht zu werden.",
+  "criterion.api-documentation-ready": "Die API-Dokumentation ist vollständig und für die Veröffentlichung und das Onboarding geeignet.",
+  "criterion.consumer-support-ready": "Registrierungs-, Support- und Kommunikationsprozesse sind für API-Nutzer bereit.",
+  "criterion.legal-compliance-clear": "Rechtliche, datenschutzrechtliche und Compliance-Anforderungen für die Veröffentlichung sind definiert und verstanden."
 }