frmscoe · Sandy-at-Tazama · Apr 5, 2026 · Apr 5, 2026 · Apr 5, 2026
@@ -1,9 +1,105 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
-# workflows
+# frmscoe/workflows
 
-> **⚠️ This repository is a subordinate mirror of [tazama-lf/workflows](https://github.com/tazama-lf/workflows).**
+> **⚠️ This repository is a downstream mirror of [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows), which is the canonical source for all Tazama GitHub Actions workflows.**
 >
-> All workflow changes must be made in `tazama-lf/workflows` first. The `sync-workflows.yml` workflow in that repo propagates updates here automatically. **Do not edit workflow files in this repo directly** — any direct changes will be overwritten on the next sync.
+> **All workflow changes must originate in `tazama-lf/workflows`.** There is no automated sync between the two workflow repos — changes must be applied here manually after merging in `tazama-lf/workflows`. **Do not edit workflow files in this repo directly** without a corresponding change upstream.
 
-This repository holds the GitHub Actions workflows used by `frmscoe` organisation repositories. Workflows are gated on PRs to `dev` and `main`.
+For complete SDLC documentation, repository class definitions, workflow reference tables, routine maintenance procedures, and known issues, see the **[`tazama-lf/workflows` README](https://github.com/tazama-lf/workflows/blob/dev/README.md)**.
+
+---
+
+## What this repo is
+
+This repository holds the GitHub Actions workflows distributed to all active `frmscoe` organisation repositories (33 rule repos). It is a manually-maintained subset of `tazama-lf/workflows`, adapted for the `frmscoe` org context.
+
+---
+
+## Cascade and dependency
+
+Changes flow in one direction:
+
+```
+tazama-lf/workflows  →  (manual PR)  →  frmscoe/workflows  →  (auto sync on push:dev)  →  33 frmscoe rule repos
+```
+
+1. A workflow change is developed and merged to `dev` in `tazama-lf/workflows`.
+2. The same change is applied manually to `frmscoe/workflows` via a separate PR.
+3. On merge to `dev` in `frmscoe/workflows`, `sync-workflows.yml` fires automatically (`push: dev`) and opens `sync-workflows-update` PRs in all 33 target rule repos.
+4. Reviewers merge the sync PRs in each rule repo.
+
+> **Note:** Unlike `tazama-lf/workflows` (which triggers sync on every PR event before merge), `frmscoe/workflows` triggers sync only on `push: dev` — i.e. after merge. Sync PRs in rule repos accurately reflect merged changes.
+
+---
+
+## Differences from tazama-lf/workflows
+
+| Aspect | `frmscoe/workflows` | `tazama-lf/workflows` |
+|--------|--------------------|-----------------------|
+| npm scope | `@frmscoe` | `@tazama-lf` |
+| Docker caller stub org | `rule_org: "frmscoe"` | `rule_org: "tazama-lf"` |
+| Sync trigger | `push: dev` (after merge) | `pull_request: [dev]` (on open/update) |
+| Sync targets | 33 frmscoe rule repos | 26 tazama-lf repos |
+| Sync segmentation | None — all repos receive the same file set | `SPECIFIC_REPOS` / `PUBLISH_REPOS` / `RULE_REPOS` groups |
+| Missing workflows | `dockerfile-linter.yml`, `dockerhub-image-build.yml`, `dockerhub-image-build-rc.yml` | All canonical files present |
+
+---
+
+## Workflows distributed to frmscoe rule repos
+
+All 33 rule repos receive:
+
+`branch-target-check.yml`, `codacy.yml`, `codeql.yml`, `conventional-commits.yml`, `dco-check.yml`, `dependency-review.yml`, `gpg-verify.yml`, `milestone.yml`, `njsscan.yml`, `publish.yml`, `release-train.yml`, `release.yml`, `sbom.yml`, `scorecard.yml`, `version-check.yml`
+
+Plus per-repo caller stubs for: `package-rule-rc.yml` (fires on `push: dev`) and `package-rule.yml` (fires on `push: main`)
+
+**Not distributed:** `sync-workflows.yml`, `node.js.yml` (each repo maintains its own copy), `package-rule*.yml` canonical reusable definitions (replaced with caller stubs)
+
+---
+
+## Target repositories
+
+`rule-001`, `rule-002`, `rule-003`, `rule-004`, `rule-006`, `rule-007`, `rule-008`, `rule-010`, `rule-011`, `rule-016`, `rule-017`, `rule-018`, `rule-020`, `rule-021`, `rule-024`, `rule-025`, `rule-026`, `rule-027`, `rule-028`, `rule-030`, `rule-044`, `rule-045`, `rule-048`, `rule-054`, `rule-063`, `rule-074`, `rule-075`, `rule-076`, `rule-078`, `rule-083`, `rule-084`, `rule-090`, `rule-091`
+
+---
+
+## Workflow documentation
+
+Individual workflow documentation is in [`workflow-docs/`](workflow-docs/). For workflows shared with `tazama-lf/workflows`, docs contain a redirect link to the canonical entry in that repo. Docs for frmscoe-specific behaviour (`publish.yml`, `package-rule*.yml`, `sync-workflows.yml`) are maintained here.
+
+| Doc | Status |
+|-----|--------|
+| [`branch-target-check.md`](workflow-docs/branch-target-check.md) | → tazama-lf docs |
+| [`codacy.md`](workflow-docs/codacy.md) | → tazama-lf docs |
+| [`codeql.md`](workflow-docs/codeql.md) | → tazama-lf docs |
+| [`conventional-commits.md`](workflow-docs/conventional-commits.md) | → tazama-lf docs |
+| [`dco-check.md`](workflow-docs/dco-check.md) | → tazama-lf docs (⚠️ known issue [#37](https://github.com/tazama-lf/workflows/issues/37)) |
+| [`dependency-review.md`](workflow-docs/dependency-review.md) | → tazama-lf docs |
+| [`dockerfile-linter.md`](workflow-docs/dockerfile-linter.md) | Not in frmscoe/workflows |
+| [`dockerhub-image-build.md`](workflow-docs/dockerhub-image-build.md) | Not in frmscoe/workflows |
+| [`gpg-verify.md`](workflow-docs/gpg-verify.md) | → tazama-lf docs |
+| [`milestone.md`](workflow-docs/milestone.md) | → tazama-lf docs |
+| [`njsscan.md`](workflow-docs/njsscan.md) | → tazama-lf docs |
+| [`nodejs.md`](workflow-docs/nodejs.md) | → tazama-lf docs (⚠️ `NPM_SCOPE=@frmscoe`) |
+| [`package-rule-rc.md`](workflow-docs/package-rule-rc.md) | frmscoe-specific |
+| [`package-rule.md`](workflow-docs/package-rule.md) | frmscoe-specific |
+| [`publish.md`](workflow-docs/publish.md) | frmscoe-specific (`@frmscoe` scope) |
+| [`release-train.md`](workflow-docs/release-train.md) | → tazama-lf docs |
+| [`release.md`](workflow-docs/release.md) | → tazama-lf docs |
+| [`sbom.md`](workflow-docs/sbom.md) | → tazama-lf docs (⚠️ known issue [#39](https://github.com/tazama-lf/workflows/issues/39)) |
+| [`scorecard.md`](workflow-docs/scorecard.md) | → tazama-lf docs |
+| [`sync-workflows.md`](workflow-docs/sync-workflows.md) | frmscoe-specific |
+| [`version-check.md`](workflow-docs/version-check.md) | → tazama-lf docs |
+
+---
+
+## Updating this repo
+
+To apply a workflow change from `tazama-lf/workflows`:
+
+1. Confirm the source PR in `tazama-lf/workflows` is merged to `dev`.
+2. Open a PR in this repo with the same changes, referencing the source PR.
+3. Update the corresponding `workflow-docs/` entry if the frmscoe behaviour differs.
+4. On merge to `dev`, `sync-workflows.yml` will open `sync-workflows-update` PRs in all 33 target repos.
+5. Review and merge the sync PRs in each target repo.
@@ -0,0 +1,9 @@
+# `branch-target-check.yml`
+
+> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see:
+>
+> **[`workflow-docs/branch-target-check.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/branch-target-check.md)**
+
+## frmscoe-specific notes
+
+_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._
@@ -1,33 +1,9 @@
-## Workflow Name: Codacy Security Scan
+# `codacy.yml`
 
-#### Purpose: 
+> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see:
+>
+> **[`workflow-docs/codacy.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/codacy.md)**
 
-- This workflow performs security scans on the codebase using Codacy and uploads the results in SARIF format to GitHub.
+## frmscoe-specific notes
 
-#### Trigger Events:
-
-`Push`: Runs on pushes to the dev and main branches.
-
-`Pull Requests`: Runs on pull requests targeting dev and main.
-
-`Scheduled`: Runs every Thursday at 00:17 UTC.
-
-#### Permissions:
-
-`contents: read`: Allows reading repository contents.
-
-`security-events`: write: Allows uploading SARIF results.
-
-`actions: read`: Required for private repositories to retrieve Action run status.
-
-- Runs on: ubuntu-latest
-
-#### Workflow Steps:
-
-- Checkout Code: Uses actions/checkout@v4 to clone the repository.
-
-- Run Codacy Analysis CLI: Executes Codacy's CLI to scan the codebase, generating a SARIF file.
-
-- Upload SARIF Results: Uploads the SARIF file to GitHub using github/codeql-action/upload-sarif@v3.
-
-- This workflow ensures that security issues in the codebase are identified and reported efficiently.
+_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._
@@ -1,36 +1,11 @@
-## Workflow Name: CodeQL
+# `codeql.yml`
 
-#### Purpose: 
+> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see:
+>
+> **[`workflow-docs/codeql.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/codeql.md)**
 
-- This workflow automates the process of scanning code for vulnerabilities using GitHub's CodeQL analysis.
+## frmscoe-specific notes
 
-#### Trigger Events:
-
-`Push`: Runs on pushes to the dev and main branches.
-
-`Pull Requests`: Runs on pull requests targeting dev and main.
-
-`Scheduled`: Runs every Thursday at 00:34 UTC.
-
-#### Permissions:
-
-`actions: read`
-
-`contents: read`
-
-`security-events: write`
-
-#### Workflow Steps:
-
-- Checkout Repository: Uses actions/checkout@v4 to clone the repository.
-
-- Initialize CodeQL: Prepares the CodeQL environment for the specified languages.
-
-- Autobuild: Automatically builds the codebase (useful for compiled languages).
-
-- Perform CodeQL Analysis: Executes the CodeQL scan and uploads results.
-
-#### Language Support:
-The workflow is configured to scan JavaScript code but can be extended to support other languages like Java, Python, Go, etc.
+_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._
 
 This setup ensures that your code is continuously analyzed for security vulnerabilities and quality issues.
@@ -1,25 +1,9 @@
-## Workflow Name: PR Conventional Commit Validation
+# `conventional-commits.yml`
 
-#### Purpose: 
+> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see:
+>
+> **[`workflow-docs/conventional-commits.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/conventional-commits.md)**
 
-- This workflow automatically validates the title of a pull request (PR) to ensure it follows conventional commit guidelines. It also applies corresponding GitHub labels based on the commit type.
+## frmscoe-specific notes
 
-- Uses the ytanikin/PRConventionalCommits@1.1.0 action.
-
-- Validates the PR title against a set of predefined conventional commit types (e.g., feat, fix, docs).
-
-- Maps these types to corresponding GitHub labels and applies them to the PR.
-
-- Utilizes a GitHub token for authentication and label management.
-
-- This workflow helps enforce commit message conventions and improve PR management by automatically labeling PRs based on their titles.
-
-#### Trigger Events:
-
-`Pull Request Events`: The workflow is triggered when a pull request is opened, synchronized, reopened, or edited.
-
-#### Workflow Steps:
-
-- Checkout Code: Uses actions/checkout@v4 to check out the repository.
-
-- PR Conventional Commit Validation:
+_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._
@@ -1,25 +1,9 @@
-## Workflow Name: DCO (Developer Certificate of Origin)
+# `dco-check.yml`
 
-#### Purpose: 
+> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see:
+>
+> **[`workflow-docs/dco-check.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/dco-check.md)**
 
-- This workflow automatically checks whether each commit in a pull request (PR) has a "Signed-off-by" line, ensuring compliance with the Developer Certificate of Origin (DCO).
+## frmscoe-specific notes
 
-- Retrieves commits between the head and base branches.
-
-- Verifies that each commit contains a "Signed-off-by" line.
-
-- Lists any non-compliant commits and fails the job if any are found.
-
-- This workflow enforces DCO compliance, ensuring that all contributions are properly signed off, indicating that the contributor agrees to the terms of the DCO.
-
-#### Trigger Events:
-
-`Pull Request`: The workflow triggers whenever a pull request event occurs (e.g., opened, updated).
-
-#### Workflow Steps:
-
-- Checkout Repository:
-
-- Set Up Environment Variables:
-
-- Check for DCO Sign-off:
+⚠️ The `git log` range in this workflow is reversed — it checks commits in the base branch that are not in the head branch, rather than the PR's new commits. DCO sign-off is not currently being verified correctly. This is a known issue tracked in [tazama-lf/workflows#37](https://github.com/tazama-lf/workflows/issues/37).
@@ -1,25 +1,9 @@
-## Workflow Name: Dependency Review
+# `dependency-review.yml`
 
-#### Purpose: 
+> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see:
+>
+> **[`workflow-docs/dependency-review.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/dependency-review.md)**
 
-- This workflow automatically reviews the dependencies of a project whenever a pull request (PR) is opened or updated, ensuring that new dependencies are checked for security vulnerabilities and other issues.
+## frmscoe-specific notes
 
-- This workflow helps maintain the security and stability of your project by automatically reviewing new or updated dependencies in pull requests.
-
-#### Trigger Events:
-
-`Pull Request`: The workflow runs whenever a pull request is created or updated.
-
-#### Permissions:
-
-`Contents`: read: Grants the action read-only access to the repository contents.
-
-- Runs on: ubuntu-latest
-
-#### Workflow Steps:
-
-- Checkout Repository:
-
-- Dependency Review:
-
-Uses actions/dependency-review-action@v4 to analyze the dependencies of the project and identify any potential issues.
+_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._
@@ -1,37 +1,7 @@
-## Workflow Name: Hadolint
+# `dockerfile-linter.yml`
 
-#### Purpose: 
-
-- This workflow automates the linting of Dockerfiles using Hadolint and uploads the results to GitHub in SARIF format for further analysis.
-
-- This workflow ensures that Dockerfiles are automatically checked for best practices and potential issues, with results easily accessible within GitHub.
-
-#### Trigger Events:
-
-`Push`: Runs on pushes to the dev and main branches.
-
-`Pull Request`: Runs on pull requests targeting the dev branch.
-
-`Scheduled`: Runs every Sunday at 13:17 UTC.
-
-#### Permissions:
-
-`Contents: read:` Grants read-only access to the repository contents.
-
-`Security-events: write:` Allows uploading SARIF results.
-
-`Actions: read:` Required for private repositories to retrieve Action run status.
-
-- Runs on: ubuntu-latest
-
-#### Workflow Steps:
-
-- Checkout Code
-
-- Run Hadolint
-
-Generates a SARIF file with the results.
-
-- Upload Analysis Results:
-
-Uses github/codeql-action/upload-sarif@v2 to upload the SARIF file to GitHub for security analysis and code scanning.
+> **This workflow is not present in `frmscoe/workflows`.**
+>
+> `frmscoe` rule repos do not maintain Dockerfiles that are linted by a separate workflow. Docker image builds for rule repos are handled by the `package-rule-rc.yml` and `package-rule.yml` caller stubs distributed by `sync-workflows.yml`.
+>
+> For reference, see the canonical documentation in `tazama-lf/workflows`: [`workflow-docs/dockerfile-linter.md`](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/dockerfile-linter.md).
@@ -1,42 +1,7 @@
-## Workflow Name: Publish Docker Image
+# `dockerhub-image-build.yml`
 
-Purpose: 
-
-- This workflow automates the process of building, tagging, and pushing Docker images to Docker Hub whenever a new release is published.
-
-#### Trigger Events:
-
-`Release`: The workflow is triggered when a release is published.
-
-#### Jobs:
-
-- push_to_registry:
-
-- Runs on: ubuntu-latest
-
-#### Permissions:
-
-`Packages: write:` Allows pushing packages to the Docker registry.
-
-`Contents: read:` Grants read access to the repository contents.
-
-`Attestations: write:` Allows writing attestations.
-
-`ID-Token: write:` Required for generating artifact attestations.
-
-#### Workflow Steps:
-
-- Check Out the Repo:
-
-- Log in to Docker Hub:
-
-Uses docker/login-action to authenticate with Docker Hub using credentials stored in GitHub Secrets.
-
-- Extract Metadata:
-
-Uses docker/metadata-action to generate Docker image tags and labels.
-
-- Build and Push Docker Image:
-
-Uses docker/build-push-action to build the Docker image and push it to Docker Hub with the generated tags and labels.
-Generate Artifact Attestation:
+> **This workflow is not present in `frmscoe/workflows`.**
+>
+> `frmscoe` rule repos do not use standalone Docker build workflows. Docker image builds are handled by the `package-rule-rc.yml` and `package-rule.yml` reusable workflows (called via caller stubs distributed by `sync-workflows.yml`).
+>
+> For reference, see the canonical documentation in `tazama-lf/workflows`: [`workflow-docs/dockerhub-image-build.md`](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/dockerhub-image-build.md).