Add MAINTAINERS_GUIDELINES.md

CONTRIBUTING.md

@@ -12,6 +12,10 @@ Thank you for your interest in contributing to the Architecture as Code project!
 > apply to every repository in the project and are maintained there. This document covers what is
 > specific to *this* repository: our commit conventions and release process.
 
+Maintainers working in this repository should also read
+[MAINTAINERS_GUIDELINES.md](./MAINTAINERS_GUIDELINES.md) for repository-specific review, triage,
+merge, release, and onboarding guidance.
+
 ## 🚀 Why We Use Semantic Release
 
 We use [Semantic Release](https://semantic-release.gitbook.io/) to automate our release process for the **CLI module**, with plans to expand to other modules in the future. This ensures:

MAINTAINERS_GUIDELINES.md

@@ -0,0 +1,128 @@
+# Maintainer Guidelines for architecture-as-code
+
+This document is for maintainers working in the `finos/architecture-as-code` monorepo. It complements the contributor-facing guidance in [CONTRIBUTING.md](./CONTRIBUTING.md) and the project-wide governance documents in [finos/calm-governance](https://github.com/finos/calm-governance).
+
+The existing [MAINTAINERS.md](./MAINTAINERS.md) in this repository remains a pointer to the project-wide maintainer roster. Use this document for repository-specific maintainer workflow and expectations.
+
+## Source Documents
+
+Use these documents as the source of truth for the corresponding topics:
+
+| Document | Purpose |
+|---|---|
+| [finos/calm-governance/GOVERNANCE.md](https://github.com/finos/calm-governance/blob/main/GOVERNANCE.md) | Maintainer roles, voting, elections, removal, and escalation rules |
+| [finos/calm-governance/MAINTAINERS.md](https://github.com/finos/calm-governance/blob/main/MAINTAINERS.md) | Project-wide maintainer roster and Lead Maintainer |
+| [README.md](./README.md#projects) | Maintainer mapping for subprojects in this monorepo |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contributor workflow, commit conventions, and release expectations |
+| [SECURITY.md](./SECURITY.md) | Private vulnerability reporting and disclosure process |
+| [.github/CODEOWNERS](./.github/CODEOWNERS) | Default ownership and review routing |
+| [.github/pull_request_template.md](./.github/pull_request_template.md) | Required PR metadata and maintainer review checklist |
+| [.github/ISSUE_TEMPLATE/Maintainer_update.md](./.github/ISSUE_TEMPLATE/Maintainer_update.md) | Process checklist for adding or removing maintainers |
+
+## Core Responsibilities
+
+Maintainers are responsible for keeping this repository healthy, reviewable, and welcoming. In practice, that includes:
+
+- Reviewing pull requests and giving clear, actionable feedback
+- Triaging issues and routing work to the right subproject maintainers
+- Protecting code quality, documentation quality, and CI health
+- Coordinating releases and versioning changes for affected components
+- Handling dependency, licensing, and security maintenance responsibly
+- Supporting contributors and onboarding new maintainers
+
+The maintainers listed for each subproject in the [Projects table](./README.md#projects) are expected to steward that area, but repository-wide changes often need coordination across multiple subprojects.
+
+## Reviewing Pull Requests
+
+When reviewing a pull request:
+
+- Use the [PR template](./.github/pull_request_template.md) to verify the change type, affected components, testing notes, and follow-up documentation.
+- Confirm that project-wide contribution requirements are met, including the expectations documented in [finos/calm-governance/CONTRIBUTING.md](https://github.com/finos/calm-governance/blob/main/CONTRIBUTING.md).
+- Make sure the right reviewers are involved based on the affected paths in [.github/CODEOWNERS](./.github/CODEOWNERS), which is the repository's primary PR review-routing map for changed files, and the subproject ownership listed in [README.md](./README.md#projects).
+- Ask for tests, migration notes, or documentation updates when behavior, interfaces, workflows, or public examples change.
+- Ask specifically for regression coverage when a change fixes a bug, alters migration behavior, or introduces stateful UI or persistence logic where a precise failure mode should stay pinned by tests.
+- Prefer shared helpers over copied logic for keys, namespace rules, error responses, and similar repeated behavior; if duplication is kept deliberately, ask for the rationale to be made explicit in the code or PR discussion.
+- Pull in additional maintainers early for cross-cutting changes, schema changes, release automation changes, or changes that affect multiple packages or services.
+
+## Approval and Merge Expectations
+
+Before merging a pull request:
+
+- Ensure required GitHub checks have passed.
+- Ensure required approvals and code-owner reviews are complete.
+- Resolve open review threads or capture an explicit follow-up issue when something is intentionally deferred.
+- Confirm the PR description still accurately reflects the final diff.
+- Ask authors to split unrelated changes into separate pull requests when a single PR has become too broad to review safely.
+
+Treat automated release pull requests and release-preparation branches carefully. For example, PRs or branches generated by workflows such as `ci(cli): release version ...`, `ci(calm-server): release version ...`, or `release-prep/calm-models-v...` should stay focused on release artifacts and version changes rather than accumulating unrelated manual edits.
+
+## Issue and Pull Request Triage
+
+Maintainers help keep work discoverable and moving:
+
+- Acknowledge new issues and PRs, especially when follow-up will take time.
+- Apply existing labels, close duplicates, and redirect out-of-scope requests to the right place.
+- Route governance matters, including maintainer roster changes, to [finos/calm-governance](https://github.com/finos/calm-governance) and use the [Maintainer Update template](./.github/ISSUE_TEMPLATE/Maintainer_update.md) when this repository needs a maintainer change processed.
+- Keep the [Projects table](./README.md#projects) and [.github/CODEOWNERS](./.github/CODEOWNERS) aligned when component ownership changes.
+- Remember that [.github/CODEOWNERS](./.github/CODEOWNERS) also establishes repo-wide ownership for dependency and build-manifest files such as `package.json`, `package-lock.json`, and `pom.xml`, so changes to those files should usually be treated as cross-cutting review rather than package-local review.
+- If a path does not have a more specific owner entry, GitHub falls back to the default owners in [.github/CODEOWNERS](./.github/CODEOWNERS); when adding a new top-level area or changing review routing expectations, update `CODEOWNERS` deliberately rather than relying on the fallback by accident.
+
+## Quality, CI, and Security Responsibilities
+
+Maintainers are expected to protect repository quality, not just merge code:
+
+- Keep required workflows green before merge and investigate recurring failures instead of normalizing them.
+- Pay close attention to repository-wide automation such as CodeQL, Semgrep, CVE scanning, license scanning, lockfile validation, and component build workflows.
+- Make sure documentation and examples evolve with behavior changes so contributor and user guidance stays trustworthy.
+- Make sure technical rationale is documented clearly and locally when the design is non-obvious; avoid circular comments or explanations that force readers to bounce between files to understand a decision.
+- Treat dependency updates, workflow changes, and shared-package changes as potentially cross-cutting work that may affect multiple downstream components.
+- For dependency and security remediation PRs, verify that the selected version, override, or workflow change actually fixes the reported issue rather than only appearing newer.
+- Handle security vulnerabilities privately according to [SECURITY.md](./SECURITY.md); do not use public issues for undisclosed vulnerabilities.
+
+## GitHub Actions
+
+When maintaining workflows, use the existing repository guidance as the source of truth rather than restating it here:
+
+- Follow the naming and documentation expectations in [README.md](./README.md#github-actions), especially when adding new workflows or less-familiar third-party actions.
+- Keep workflow runtime assumptions aligned with the CI standards in [AGENTS.md](./AGENTS.md), especially the [Node 26 requirement](./AGENTS.md#node-version-requirements) and [lockfile regeneration rules](./AGENTS.md#lockfile-regeneration), because those expectations are enforced by workflows such as [validate-lockfile.yml](./.github/workflows/validate-lockfile.yml).
+- For release-oriented workflow changes or manual runs, review the release guidance in [CONTRIBUTING.md](./CONTRIBUTING.md#-why-we-use-semantic-release) and the workflow-specific comments and inputs in [automated-release.yml](./.github/workflows/automated-release.yml), [automated-release-calm-server.yml](./.github/workflows/automated-release-calm-server.yml), [release-calm-models-maven.yml](./.github/workflows/release-calm-models-maven.yml), and [build-vscode-extension.yml](./.github/workflows/build-vscode-extension.yml) before approving or triggering release automation.
+- Use the PR template's CI/CD and testing sections when reviewing workflow changes, and remember the note in [pull_request_template.md](./.github/pull_request_template.md) that only `(cli)`-scoped commits trigger the CLI automated release flow.
+
+## Release and Version Management
+
+This repository contains multiple independently released components, so maintainers should be deliberate about release-related changes:
+
+- Enforce the conventional-commit expectations in [CONTRIBUTING.md](./CONTRIBUTING.md), because release automation depends on them.
+- Review release workflow changes carefully, especially when they affect generated changelogs, package publication, tags, or release branches.
+- Verify release-preparation PRs contain the expected generated changes and no unrelated edits.
+- Document any manual intervention clearly in the PR when normal release automation is not sufficient.
+
+## Significant or Breaking Changes
+
+For large or high-risk changes:
+
+- Ask for an issue or design discussion before merge when the change is breaking, architectural, security-sensitive, or spans multiple subprojects.
+- Involve all affected maintainers early rather than relying on a single late-stage review.
+- For significant new enhancements, require two maintainer approvals from two different organizations before merge.
+- Require clear rollout or migration notes when the change impacts consumers, contributors, or release workflows.
+- Treat schema and data-migration changes as sequence-sensitive, high-risk work: review them for malformed legacy data handling, atomicity, ordering, rollback or retry safety, and avoid changing the behavior of already-merged migration steps unless there is a compelling reason and the impact is fully understood.
+- Use the governance process in [GOVERNANCE.md](https://github.com/finos/calm-governance/blob/main/GOVERNANCE.md) when escalation or formal maintainer decision-making is needed.
+
+## Supporting Contributors
+
+Maintainers set the tone for the project:
+
+- Be respectful, specific, and timely in review feedback.
+- Explain requested changes and point contributors to the relevant documentation or examples.
+- Close the loop after merge or closure so contributors understand the outcome.
+- Keep maintainer behavior aligned with the [Code of Conduct](https://github.com/finos/calm-governance/blob/main/CODE_OF_CONDUCT.md) and FINOS community expectations.
+
+## Onboarding New Maintainers
+
+When onboarding a new maintainer:
+
+- Follow the role and voting rules in [GOVERNANCE.md](https://github.com/finos/calm-governance/blob/main/GOVERNANCE.md).
+- Use the checklist in [.github/ISSUE_TEMPLATE/Maintainer_update.md](./.github/ISSUE_TEMPLATE/Maintainer_update.md).
+- Update the project-wide roster in [finos/calm-governance/MAINTAINERS.md](https://github.com/finos/calm-governance/blob/main/MAINTAINERS.md), the [Projects table](./README.md#projects), and [.github/CODEOWNERS](./.github/CODEOWNERS) as needed.
+- Make sure the maintainer is added to the appropriate GitHub team and that FINOS is notified where required by the maintainer update checklist.
+- Point the new maintainer to [README.md](./README.md), [CONTRIBUTING.md](./CONTRIBUTING.md), [SECURITY.md](./SECURITY.md), and this guide.

README.md

@@ -85,6 +85,7 @@ in the project.
 |---|---|
 | [GOVERNANCE.md](https://github.com/finos/calm-governance/blob/main/GOVERNANCE.md) | Roles, contribution rules, Maintainer voting, and how Maintainers are added and removed |
 | [MAINTAINERS.md](https://github.com/finos/calm-governance/blob/main/MAINTAINERS.md) | The project-wide Maintainer roster and the Lead Maintainer |
+| [MAINTAINERS_GUIDELINES.md](./MAINTAINERS_GUIDELINES.md) | Repository-specific maintainer guidance for review, triage, quality, releases, and onboarding in this monorepo |
 | [CONTRIBUTING.md](https://github.com/finos/calm-governance/blob/main/CONTRIBUTING.md) | Project-wide contribution guidelines |
 | [CODE_OF_CONDUCT.md](https://github.com/finos/calm-governance/blob/main/CODE_OF_CONDUCT.md) | The Code of Conduct all participants are subject to |