oss-signal 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+- Added a maintainer playbook for audit-to-issue, PR, CI gate, and SARIF workflows.
+- Added a documented release process and tag-triggered release workflow with npm dry-run verification.
+
+## 0.4.0
+
+- Added SARIF output for GitHub Code Scanning and other security dashboards.
+- Added Action support for `format: sarif`.
+
 ## 0.3.0
 
 - Added GitHub Actions step summary output for readable workflow reports.

package/README.md

@@ -2,13 +2,14 @@
 
 [![CI](https://github.com/SalmonPlays/oss-signal/actions/workflows/ci.yml/badge.svg)](https://github.com/SalmonPlays/oss-signal/actions/workflows/ci.yml)
 [![Repository health](https://github.com/SalmonPlays/oss-signal/actions/workflows/repository-health.yml/badge.svg)](https://github.com/SalmonPlays/oss-signal/actions/workflows/repository-health.yml)
+[![GitHub release](https://img.shields.io/github/v/release/SalmonPlays/oss-signal.svg)](https://github.com/SalmonPlays/oss-signal/releases/latest)
 [![npm version](https://img.shields.io/npm/v/oss-signal.svg)](https://www.npmjs.com/package/oss-signal)
 [![npm downloads](https://img.shields.io/npm/dm/oss-signal.svg)](https://www.npmjs.com/package/oss-signal)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 `oss-signal` is a dependency-light CLI for auditing open-source repository maintenance readiness.
 
-It checks the files and automation that reduce maintainer load: README, license, contributing guide, security policy, CI, tests, issue templates, pull request templates, Dependabot, and release notes. The output is a score plus concrete next steps in Markdown or JSON.
+It checks the files and automation that reduce maintainer load: README, license, contributing guide, security policy, CI, tests, issue templates, pull request templates, Dependabot, and release notes. The output is a score plus concrete next steps in Markdown, JSON, or SARIF.
 
 ![oss-signal example output](docs/assets/terminal-report.svg)
 
@@ -24,12 +25,20 @@ Open-source projects often fail quietly because the maintainer workflow is undoc
 - Foundations and working groups can compare repository hygiene across many projects.
 - CI maintainers can add it as a GitHub Action, show the score in the workflow summary, and publish the report as an artifact.
 
+See [docs/maintainer-playbook.md](docs/maintainer-playbook.md) for a concrete maintainer workflow from audit to issue, PR, CI gate, and Code Scanning evidence.
+
 ## Install
 
 ```bash
 npm install --global oss-signal
 ```
 
+Try it without installing:
+
+```bash
+npx oss-signal SalmonPlays/oss-signal
+```
+
 For local development:
 
 ```bash
@@ -66,6 +75,12 @@ Use JSON in automation:
 oss-signal . --format json --fail-under 80
 ```
 
+Write SARIF for GitHub Code Scanning or other dashboards:
+
+```bash
+oss-signal . --format sarif --output oss-signal.sarif
+```
+
 Generate a report that can be attached to an issue:
 
 ```bash
@@ -82,11 +97,13 @@ oss-signal . --format markdown --output docs/maintainer-readiness.md
 
 See [docs/rules.md](docs/rules.md) for rule details and scoring weights.
 
+SARIF output reports failed maintainer-readiness checks as warning-level results. This lets teams upload the audit to code scanning dashboards while keeping the Markdown report available for maintainers.
+
 For GitHub URL audits, `oss-signal` reads the repository file tree through the GitHub API and also uses GitHub's community profile signal when available. This lets it detect organization-level files such as a shared code of conduct.
 
 ## Real Output
 
-This repository audits itself at **100/100 (A)**:
+This repository audits itself at **100/100 (A)** and dogfoods the public GitHub Action:
 
 ```text
 Score: 100/100 (A)
@@ -97,7 +114,9 @@ Summary:
 - Total checks: 15
 ```
 
-See [docs/self-audit.md](docs/self-audit.md) for the full local self-audit report and [docs/examples/github-url-report.md](docs/examples/github-url-report.md) for the GitHub URL audit output.
+See [docs/self-audit.md](docs/self-audit.md) for the full local self-audit report, [docs/examples/github-url-report.md](docs/examples/github-url-report.md) for the GitHub URL audit output, and [docs/examples/self-audit.sarif](docs/examples/self-audit.sarif) for SARIF output.
+
+The [Repository health workflow](.github/workflows/repository-health.yml) runs `SalmonPlays/oss-signal@v0.4.0`, uploads the Markdown report as an artifact, and uploads SARIF to GitHub Code Scanning on non-PR runs.
 
 ## Field Audits
 
@@ -138,7 +157,7 @@ oss-signal . --fail-under 80
 Add `oss-signal` directly to a GitHub Actions workflow:
 
 ```yaml
-- uses: SalmonPlays/oss-signal@v0.3.0
+- uses: SalmonPlays/oss-signal@v0.4.0
   id: oss-signal
   with:
     fail-under: "80"
@@ -166,7 +185,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: SalmonPlays/oss-signal@v0.3.0
+      - uses: SalmonPlays/oss-signal@v0.4.0
         id: oss-signal
         with:
           fail-under: "80"
@@ -178,9 +197,28 @@ jobs:
           path: oss-signal-report.md
 ```
 
-See [docs/examples/github-action-workflow.yml](docs/examples/github-action-workflow.yml) for a copyable workflow.
+See [docs/examples/github-action-workflow.yml](docs/examples/github-action-workflow.yml) for a copyable workflow and [docs/examples/github-code-scanning-workflow.yml](docs/examples/github-code-scanning-workflow.yml) for a workflow that uploads SARIF to GitHub Code Scanning.
+
+Upload SARIF to GitHub Code Scanning:
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: SalmonPlays/oss-signal@v0.4.0
+    with:
+      format: sarif
+      output: oss-signal.sarif
+      summary: "true"
+  - uses: github/codeql-action/upload-sarif@v3
+    with:
+      sarif_file: oss-signal.sarif
+```
 
-This repository dogfoods the public Action tag in [Repository health](.github/workflows/repository-health.yml), which runs `SalmonPlays/oss-signal@v0.3.0` against the repository and uploads the Markdown report artifact.
+This repository dogfoods the public Action tag in [Repository health](.github/workflows/repository-health.yml), which runs `SalmonPlays/oss-signal@v0.4.0` against the repository, uploads the Markdown report artifact, and publishes SARIF to Code Scanning on non-PR runs.
 
 You can also run the CLI directly in CI:
 
@@ -197,8 +235,13 @@ You can also run the CLI directly in CI:
 ## Roadmap
 
 - Ecosystem-specific profiles for Python, Rust, Go, and JavaScript packages
-- SARIF output for code scanning dashboards
-- Rules for release automation and provenance metadata
+- Release automation and provenance metadata checks
+- Maintainer score trends over time
+- Organization-level repository inventory reports
+
+## Release Process
+
+Releases use the checklist in [docs/release-process.md](docs/release-process.md). The repository also includes a tag-triggered [release workflow](.github/workflows/release.yml) that verifies the package, runs `npm publish --dry-run`, and can publish to npm with provenance when `NPM_TOKEN` is configured.
 
 ## Contributing
 

package/action.yml

@@ -10,7 +10,7 @@ inputs:
     required: false
     default: "."
   format:
-    description: Output format, either markdown or json.
+    description: Output format, either markdown, json, or sarif.
     required: false
     default: markdown
   output:

package/docs/adoption-evidence.md

@@ -5,13 +5,17 @@ This page collects the public evidence that `oss-signal` is built for real open-
 ## Project Links
 
 - Repository: https://github.com/SalmonPlays/oss-signal
-- npm package: https://www.npmjs.com/package/oss-signal
-- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.3.0
+- npm package: https://www.npmjs.com/package/oss-signal (`0.3.0` latest)
+- GitHub Release: https://github.com/SalmonPlays/oss-signal/releases/tag/v0.4.0
+- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.4.0
 - GitHub Action metadata: [action.yml](../action.yml)
 - Public dogfood workflow: [.github/workflows/repository-health.yml](../.github/workflows/repository-health.yml)
 - Self-audit report: [docs/self-audit.md](self-audit.md)
+- SARIF self-audit output: [docs/examples/self-audit.sarif](examples/self-audit.sarif)
 - GitHub URL audit report: [docs/examples/github-url-report.md](examples/github-url-report.md)
 - GitHub Action workflow example: [docs/examples/github-action-workflow.yml](examples/github-action-workflow.yml)
+- Maintainer playbook: [docs/maintainer-playbook.md](maintainer-playbook.md)
+- Release process: [docs/release-process.md](release-process.md)
 - Codex for Open Source application brief: [docs/codex-for-oss-application.md](codex-for-oss-application.md)
 - Rule reference: [docs/rules.md](rules.md)
 
@@ -24,7 +28,9 @@ The CLI supports two practical modes:
 - Local repository audit for maintainers working in a clone.
 - Public GitHub repository audit for quick triage without cloning.
 
-It also ships as a GitHub Action, so maintainers can gate repository hygiene in CI, show the result in the GitHub Actions step summary, and upload a Markdown report as a workflow artifact. This repository dogfoods the public Action tag through the Repository health workflow.
+It also ships as a GitHub Action, so maintainers can gate repository hygiene in CI, show the result in the GitHub Actions step summary, upload a Markdown report as a workflow artifact, and upload failed maintainer-readiness checks as SARIF for GitHub Code Scanning. This repository dogfoods the public Action tag through the Repository health workflow.
+
+The [maintainer playbook](maintainer-playbook.md) documents the end-to-end workflow from audit to issue, pull request, CI gate, and Code Scanning evidence. The [release process](release-process.md) documents pre-release verification, tag consistency, npm publish checks, and post-release smoke tests.
 
 ## Public Field Audits And PRs
 
@@ -45,10 +51,12 @@ From this repository:
 ```bash
 npm run check
 npm run audit:github
+node src/cli.js . --format sarif --output docs/examples/self-audit.sarif
 node src/cli.js platformatic/massimo --format json
+npx --yes oss-signal@0.3.0 SalmonPlays/oss-signal --format json
 ```
 
-The current repository self-audit score is 100/100, the GitHub community profile health score is 100, and CI verifies the local GitHub Action wrapper.
+The current repository self-audit score is 100/100, the GitHub community profile health score is 100, and CI verifies the local GitHub Action wrapper. The public `v0.4.0` Action tag is used by the repository health workflow for Markdown and SARIF output. The published npm `0.3.0` package has also been executed from a clean temporary directory against the public GitHub repository.
 
 Public CI evidence:
 

package/docs/codex-for-oss-application.md

@@ -1,6 +1,6 @@
 # Codex for Open Source Application Brief
 
-Snapshot: 2026-06-02T11:20:40Z
+Snapshot: 2026-06-03T03:06:42Z
 
 This document summarizes why `oss-signal` is a fit for OpenAI's Codex for Open Source program. The official program page says open-source maintainers can apply, with emphasis on core maintainers, widely used public projects, and projects that play an important ecosystem role: https://developers.openai.com/community/codex-for-oss
 
@@ -8,11 +8,14 @@ This document summarizes why `oss-signal` is a fit for OpenAI's Codex for Open S
 
 - Repository: https://github.com/SalmonPlays/oss-signal
 - npm package: https://www.npmjs.com/package/oss-signal
-- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.3.0
+- GitHub Release: https://github.com/SalmonPlays/oss-signal/releases/tag/v0.4.0
+- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.4.0
 - CI workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/ci.yml
 - Repository health workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/repository-health.yml
 - CodeQL workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/codeql.yml
 - Maintainer evidence: [adoption-evidence.md](adoption-evidence.md)
+- Maintainer playbook: [maintainer-playbook.md](maintainer-playbook.md)
+- Release process: [release-process.md](release-process.md)
 
 ## What `oss-signal` Does
 
@@ -22,7 +25,7 @@ This document summarizes why `oss-signal` is a fit for OpenAI's Codex for Open S
 - CI, tests, issue templates, pull request templates, Dependabot, and CodeQL-style security workflow.
 - Package metadata and lockfile hygiene.
 
-The output is a deterministic score plus actionable next steps in Markdown or JSON. The GitHub Action also writes a workflow step summary so maintainers and reviewers can see the result without downloading an artifact.
+The output is a deterministic score plus actionable next steps in Markdown, JSON, or SARIF. The GitHub Action also writes a workflow step summary so maintainers and reviewers can see the result without downloading an artifact.
 
 ## Why Codex Helps
 
@@ -31,6 +34,7 @@ This project is designed around repeatable maintainer workflows where Codex is u
 - Run audits against public repositories without cloning.
 - Convert findings into focused cleanup issues or pull requests.
 - Keep repository hygiene visible in CI.
+- Upload failed maintainer-readiness checks to GitHub Code Scanning through SARIF.
 - Generate small contributor-facing files that maintainers can review quickly.
 - Use Codex to turn audit findings into scoped documentation and workflow improvements.
 
@@ -38,12 +42,17 @@ This project is designed around repeatable maintainer workflows where Codex is u
 
 The repository currently has:
 
-- A published npm package.
+- A published npm package with `0.3.0` as the latest release.
+- A published GitHub Release for v0.4.0 with SARIF release notes and CI usage guidance.
 - A reusable GitHub Action with `score`, `grade`, `failed`, and `report-path` outputs.
-- A v0.3.0 GitHub Action tag with step summary support.
-- A public dogfood workflow that runs `SalmonPlays/oss-signal@v0.3.0` against the repository.
+- SARIF output for GitHub Code Scanning integration.
+- A v0.4.0 GitHub Action tag with step summary and SARIF support.
+- A public dogfood workflow that runs `SalmonPlays/oss-signal@v0.4.0` against the repository, uploads the Markdown report artifact, and uploads SARIF to GitHub Code Scanning on non-PR runs.
+- A maintainer playbook that documents audit, triage, issue, PR, CI, and SARIF workflows.
+- A release process and tag-triggered release workflow that verify package contents and support npm provenance publishing when repository secrets are configured.
 - CI and CodeQL workflows passing on `main`.
 - A local self-audit score of 100/100.
+- A clean-directory smoke test of `npx --yes oss-signal@0.3.0 SalmonPlays/oss-signal --format json`, returning 100/100 (A).
 - Public reports, issues, and PRs created from real repository audits.
 
 ## Field Audits And Follow-Up PRs
@@ -71,6 +80,5 @@ Recommended application angle:
 ## Next Evidence To Collect
 
 - One or more merged external PRs.
-- A GitHub Release for v0.3.0 with release notes.
-- A public workflow run in another repository using `SalmonPlays/oss-signal@v0.3.0`.
+- A public workflow run in another repository using `SalmonPlays/oss-signal@v0.4.0`, ideally with SARIF upload enabled.
 - npm download data once the registry starts reporting weekly/monthly counts.

package/docs/examples/github-action-workflow.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: SalmonPlays/oss-signal@v0.3.0
+      - uses: SalmonPlays/oss-signal@v0.4.0
         id: oss-signal
         with:
           fail-under: "80"

package/docs/examples/github-code-scanning-workflow.yml

@@ -0,0 +1,38 @@
+name: Repository health
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  oss-signal:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: SalmonPlays/oss-signal@v0.4.0
+        id: oss-signal
+        with:
+          fail-under: "80"
+          output: oss-signal-report.md
+          summary: "true"
+      - uses: SalmonPlays/oss-signal@v0.4.0
+        with:
+          format: sarif
+          output: oss-signal.sarif
+          summary: "false"
+      - uses: github/codeql-action/upload-sarif@v3
+        if: github.event_name != 'pull_request'
+        with:
+          sarif_file: oss-signal.sarif
+      - uses: actions/upload-artifact@v4
+        with:
+          name: oss-signal-report
+          path: |
+            oss-signal-report.md
+            oss-signal.sarif

package/docs/examples/github-url-report.md

@@ -2,7 +2,7 @@
 
 Repository: `https://github.com/SalmonPlays/oss-signal`
 Source: GitHub (SalmonPlays/oss-signal@main)
-Generated: 2026-06-02T08:09:34.957Z
+Generated: 2026-06-03T02:26:40.233Z
 
 Score: **100/100** (A)
 

package/docs/examples/self-audit.sarif

@@ -0,0 +1,407 @@
+{
+  "version": "2.1.0",
+  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+  "runs": [
+    {
+      "tool": {
+        "driver": {
+          "name": "oss-signal",
+          "semanticVersion": "0.4.0",
+          "informationUri": "https://github.com/SalmonPlays/oss-signal",
+          "rules": [
+            {
+              "id": "oss-signal/readme",
+              "name": "README",
+              "shortDescription": {
+                "text": "README"
+              },
+              "fullDescription": {
+                "text": "A clear README is the front door for users and contributors."
+              },
+              "help": {
+                "text": "Add setup, usage, contribution, support, and project status sections to README.md.",
+                "markdown": "Add setup, usage, contribution, support, and project status sections to README.md."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 12
+              }
+            },
+            {
+              "id": "oss-signal/license",
+              "name": "License",
+              "shortDescription": {
+                "text": "License"
+              },
+              "fullDescription": {
+                "text": "A license tells downstream users what they may legally do with the code."
+              },
+              "help": {
+                "text": "Add an OSI-approved license file such as MIT, Apache-2.0, BSD-3-Clause, or MPL-2.0.",
+                "markdown": "Add an OSI-approved license file such as MIT, Apache-2.0, BSD-3-Clause, or MPL-2.0."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 10
+              }
+            },
+            {
+              "id": "oss-signal/contributing",
+              "name": "Contributing guide",
+              "shortDescription": {
+                "text": "Contributing guide"
+              },
+              "fullDescription": {
+                "text": "Maintainers get better issues and pull requests when expectations are documented."
+              },
+              "help": {
+                "text": "Add CONTRIBUTING.md with local setup, test commands, review expectations, and release notes guidance.",
+                "markdown": "Add CONTRIBUTING.md with local setup, test commands, review expectations, and release notes guidance."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 9
+              }
+            },
+            {
+              "id": "oss-signal/security",
+              "name": "Security policy",
+              "shortDescription": {
+                "text": "Security policy"
+              },
+              "fullDescription": {
+                "text": "Responsible disclosure needs a private, documented path."
+              },
+              "help": {
+                "text": "Add SECURITY.md with supported versions, reporting instructions, and response expectations.",
+                "markdown": "Add SECURITY.md with supported versions, reporting instructions, and response expectations."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 9
+              }
+            },
+            {
+              "id": "oss-signal/code-of-conduct",
+              "name": "Code of conduct",
+              "shortDescription": {
+                "text": "Code of conduct"
+              },
+              "fullDescription": {
+                "text": "Community norms reduce ambiguity during difficult interactions."
+              },
+              "help": {
+                "text": "Add CODE_OF_CONDUCT.md, for example the Contributor Covenant.",
+                "markdown": "Add CODE_OF_CONDUCT.md, for example the Contributor Covenant."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 6
+              }
+            },
+            {
+              "id": "oss-signal/changelog",
+              "name": "Changelog",
+              "shortDescription": {
+                "text": "Changelog"
+              },
+              "fullDescription": {
+                "text": "Users need a durable place to understand release impact."
+              },
+              "help": {
+                "text": "Keep CHANGELOG.md with dated release entries and migration notes.",
+                "markdown": "Keep CHANGELOG.md with dated release entries and migration notes."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 6
+              }
+            },
+            {
+              "id": "oss-signal/support",
+              "name": "Support policy",
+              "shortDescription": {
+                "text": "Support policy"
+              },
+              "fullDescription": {
+                "text": "Support boundaries help maintainers avoid turning every request into unpaid consulting."
+              },
+              "help": {
+                "text": "Add SUPPORT.md describing where to ask questions, what is in scope, and expected response times.",
+                "markdown": "Add SUPPORT.md describing where to ask questions, what is in scope, and expected response times."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 4
+              }
+            },
+            {
+              "id": "oss-signal/ci",
+              "name": "Continuous integration",
+              "shortDescription": {
+                "text": "Continuous integration"
+              },
+              "fullDescription": {
+                "text": "CI catches regressions before maintainers merge changes."
+              },
+              "help": {
+                "text": "Add a GitHub Actions workflow that runs linting and tests on pushes and pull requests.",
+                "markdown": "Add a GitHub Actions workflow that runs linting and tests on pushes and pull requests."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 12
+              }
+            },
+            {
+              "id": "oss-signal/tests",
+              "name": "Tests",
+              "shortDescription": {
+                "text": "Tests"
+              },
+              "fullDescription": {
+                "text": "Tests make review safer and lower the cost of outside contributions."
+              },
+              "help": {
+                "text": "Add focused tests for public behavior and document the test command.",
+                "markdown": "Add focused tests for public behavior and document the test command."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 10
+              }
+            },
+            {
+              "id": "oss-signal/issue-templates",
+              "name": "Issue templates",
+              "shortDescription": {
+                "text": "Issue templates"
+              },
+              "fullDescription": {
+                "text": "Issue templates collect the facts maintainers need to reproduce and triage."
+              },
+              "help": {
+                "text": "Add bug report and feature request templates under .github/ISSUE_TEMPLATE/.",
+                "markdown": "Add bug report and feature request templates under .github/ISSUE_TEMPLATE/."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 5
+              }
+            },
+            {
+              "id": "oss-signal/pull-request-template",
+              "name": "Pull request template",
+              "shortDescription": {
+                "text": "Pull request template"
+              },
+              "fullDescription": {
+                "text": "PR templates nudge contributors to include tests, docs, and review context."
+              },
+              "help": {
+                "text": "Add .github/PULL_REQUEST_TEMPLATE.md with a short checklist.",
+                "markdown": "Add .github/PULL_REQUEST_TEMPLATE.md with a short checklist."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 5
+              }
+            },
+            {
+              "id": "oss-signal/dependabot",
+              "name": "Dependency update automation",
+              "shortDescription": {
+                "text": "Dependency update automation"
+              },
+              "fullDescription": {
+                "text": "Automated dependency updates reduce security and compatibility drift."
+              },
+              "help": {
+                "text": "Add .github/dependabot.yml for the package ecosystems used in the repository.",
+                "markdown": "Add .github/dependabot.yml for the package ecosystems used in the repository."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 5
+              }
+            },
+            {
+              "id": "oss-signal/codeql",
+              "name": "Static security analysis",
+              "shortDescription": {
+                "text": "Static security analysis"
+              },
+              "fullDescription": {
+                "text": "Static analysis finds common vulnerability patterns before releases."
+              },
+              "help": {
+                "text": "Add a CodeQL or equivalent security scanning workflow.",
+                "markdown": "Add a CodeQL or equivalent security scanning workflow."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 4
+              }
+            },
+            {
+              "id": "oss-signal/package-json",
+              "name": "Node package metadata",
+              "shortDescription": {
+                "text": "Node package metadata"
+              },
+              "fullDescription": {
+                "text": "Package metadata makes installation, testing, and release automation discoverable."
+              },
+              "help": {
+                "text": "Add package.json with name, description, license, scripts, repository, and engines fields.",
+                "markdown": "Add package.json with name, description, license, scripts, repository, and engines fields."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 5
+              }
+            },
+            {
+              "id": "oss-signal/lockfile",
+              "name": "Dependency lockfile",
+              "shortDescription": {
+                "text": "Dependency lockfile"
+              },
+              "fullDescription": {
+                "text": "Lockfiles make CI and contributor setup reproducible."
+              },
+              "help": {
+                "text": "Commit the lockfile for application-style projects, or document why this library intentionally omits one.",
+                "markdown": "Commit the lockfile for application-style projects, or document why this library intentionally omits one."
+              },
+              "defaultConfiguration": {
+                "level": "warning"
+              },
+              "properties": {
+                "tags": [
+                  "oss-signal",
+                  "maintainer-readiness"
+                ],
+                "precision": "high",
+                "weight": 4
+              }
+            }
+          ]
+        }
+      },
+      "automationDetails": {
+        "id": "oss-signal/maintainer-readiness"
+      },
+      "invocations": [
+        {
+          "executionSuccessful": true
+        }
+      ],
+      "results": [],
+      "properties": {
+        "score": 100,
+        "grade": "A",
+        "source": "local",
+        "generatedAt": "2026-06-03T02:26:40.315Z"
+      }
+    }
+  ]
+}

package/docs/maintainer-playbook.md

@@ -0,0 +1,103 @@
+# Maintainer Playbook
+
+This playbook shows the workflow `oss-signal` is designed to support: run a deterministic audit, turn missing maintainer-readiness signals into a focused issue or pull request, then keep the score visible in CI.
+
+## 1. Audit A Repository
+
+Run against a local checkout:
+
+```bash
+oss-signal . --format markdown --output oss-signal-report.md
+```
+
+Run against a public GitHub repository without cloning it:
+
+```bash
+oss-signal owner/repo --format markdown --output owner-repo-report.md
+```
+
+Use JSON when another tool needs to consume the score:
+
+```bash
+oss-signal owner/repo --format json
+```
+
+Use SARIF when the findings should appear in Code Scanning:
+
+```bash
+oss-signal . --format sarif --output oss-signal.sarif
+```
+
+## 2. Triage Findings
+
+Prioritize missing checks that reduce maintainer load:
+
+- Security policy, so reporters have a private disclosure path.
+- Contributing guide, so contributors know setup, tests, and review expectations.
+- Issue and pull request templates, so maintainers receive reproducible reports.
+- CI, tests, Dependabot, and CodeQL-style scanning, so review cost stays low.
+
+Do not treat the score as a code-quality verdict. It is a workflow-readiness signal.
+
+## 3. Turn Findings Into Maintainer-Friendly Follow-Up
+
+For an issue, include:
+
+- The generated score and report link.
+- The specific missing signal.
+- Why it matters for maintainers.
+- One concrete proposed fix.
+
+For a pull request, keep the change narrow. Good PRs add or improve files such as `CONTRIBUTING.md`, `SECURITY.md`, `.github/ISSUE_TEMPLATE/*`, `.github/PULL_REQUEST_TEMPLATE.md`, or a small CI workflow. Avoid broad product-code changes unless the maintainer asked for them.
+
+The field-audit examples in [docs/outreach](outreach) show this pattern for public repositories.
+
+## 4. Add A CI Gate
+
+Add the GitHub Action to keep the signal visible:
+
+```yaml
+- uses: SalmonPlays/oss-signal@v0.4.0
+  id: oss-signal
+  with:
+    fail-under: "80"
+    output: oss-signal-report.md
+    summary: "true"
+```
+
+The Action writes `score`, `grade`, `failed`, and `report-path` outputs, and writes a concise GitHub Actions step summary by default.
+
+## 5. Upload SARIF To Code Scanning
+
+When maintainers already use GitHub Code Scanning, upload SARIF:
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: SalmonPlays/oss-signal@v0.4.0
+    with:
+      format: sarif
+      output: oss-signal.sarif
+      summary: "false"
+  - uses: github/codeql-action/upload-sarif@v3
+    with:
+      sarif_file: oss-signal.sarif
+```
+
+See [docs/examples/github-code-scanning-workflow.yml](examples/github-code-scanning-workflow.yml) for a complete workflow.
+
+## 6. Collect Adoption Evidence
+
+Useful evidence for maintainers and reviewers:
+
+- A public workflow run that uses `SalmonPlays/oss-signal@v0.4.0`.
+- A generated Markdown report attached as an artifact.
+- A SARIF upload in Code Scanning.
+- A small issue or PR that follows from an audit finding.
+- A release note or changelog entry showing the maintainer workflow improved.
+
+Keep the evidence factual. Do not claim adoption from a repository unless that repository actually runs the tool or accepted a related change.

package/docs/release-notes/v0.4.0.md

@@ -0,0 +1,26 @@
+# oss-signal v0.4.0
+
+`oss-signal` v0.4.0 adds SARIF output so maintainers can send failed maintainer-readiness checks to GitHub Code Scanning while keeping the Markdown report and GitHub Actions step summary available for day-to-day review.
+
+## Highlights
+
+- Added `--format sarif` to the CLI.
+- Added `format: sarif` support to the GitHub Action.
+- Added a self-audit SARIF example at `docs/examples/self-audit.sarif`.
+- Added README guidance for uploading `oss-signal.sarif` to GitHub Code Scanning.
+- Updated the repository health workflow to dogfood the public `SalmonPlays/oss-signal@v0.4.0` Action tag.
+
+## Try It
+
+```bash
+git clone https://github.com/SalmonPlays/oss-signal.git
+cd oss-signal
+npm install
+node src/cli.js SalmonPlays/oss-signal --format sarif > oss-signal.sarif
+```
+
+For CI, use `SalmonPlays/oss-signal@v0.4.0` in GitHub Actions, copy `docs/examples/github-code-scanning-workflow.yml`, and adjust `fail-under` for your project.
+
+## Why It Matters
+
+Maintainers already use GitHub Code Scanning for actionable repository findings. SARIF support lets `oss-signal` meet that workflow instead of forcing maintainers to inspect a separate report format.

package/docs/release-process.md

@@ -0,0 +1,82 @@
+# Release Process
+
+This process keeps `oss-signal` releases reproducible and easy to verify.
+
+## Pre-Release
+
+Run the full local check:
+
+```bash
+npm run check
+```
+
+Verify the public GitHub audit example:
+
+```bash
+npm run audit:github
+```
+
+Verify SARIF output:
+
+```bash
+node src/cli.js . --format sarif --output docs/examples/self-audit.sarif
+node -e "const fs = require('fs'); const sarif = JSON.parse(fs.readFileSync('docs/examples/self-audit.sarif', 'utf8')); if (sarif.version !== '2.1.0') throw new Error('invalid SARIF');"
+```
+
+Inspect the npm tarball before publishing:
+
+```bash
+npm publish --dry-run
+```
+
+## Tag
+
+The package version and tag must match:
+
+```bash
+node src/cli.js --version
+git tag v$(node src/cli.js --version)
+git push origin main --tags
+```
+
+## GitHub Release
+
+Create a GitHub Release for the tag and use the release notes in `docs/release-notes/` when available.
+
+For example, `v0.4.0` uses [docs/release-notes/v0.4.0.md](release-notes/v0.4.0.md).
+
+## npm Publish
+
+Manual publish path:
+
+```bash
+npm publish --access public
+```
+
+Automation path:
+
+The tag-triggered [release workflow](../.github/workflows/release.yml) runs the same checks, verifies the package with `npm publish --dry-run`, and publishes with provenance when `NPM_TOKEN` is configured for the repository.
+
+## Post-Release Verification
+
+Check the registry version:
+
+```bash
+npm view oss-signal version dist-tags.latest --json
+```
+
+Run from a clean temporary directory:
+
+```bash
+tmpdir=$(mktemp -d)
+cd "$tmpdir"
+npm exec --yes --package=oss-signal -- oss-signal SalmonPlays/oss-signal --format json
+```
+
+Check the public Action tag:
+
+```bash
+git ls-remote --tags https://github.com/SalmonPlays/oss-signal.git
+```
+
+Download metrics can lag behind package publication. Treat npm download counts as delayed evidence, not immediate proof that a release worked.

package/docs/self-audit.md

@@ -2,7 +2,7 @@
 
 Repository: `/Users/amon/Documents/Codex/2026-06-01/openai-s/outputs/oss-signal`
 Source: local
-Generated: 2026-06-02T08:09:32.913Z
+Generated: 2026-06-03T02:26:38.240Z
 
 Score: **100/100** (A)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oss-signal",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A dependency-light CLI that audits open-source repository maintenance readiness.",
   "type": "module",
   "bin": {

package/src/action.js

@@ -2,7 +2,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { auditTarget, renderMarkdown } from "./index.js";
+import { auditTarget, renderMarkdown, renderSarif } from "./index.js";
 
 const OUTPUT_DELIMITER = "oss_signal_output";
 
@@ -12,7 +12,7 @@ export async function runAction(env = process.env, stdout = process.stdout, stde
     maxFiles: options.maxFiles,
     ref: options.ref
   });
-  const body = options.format === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderMarkdown(report);
+  const body = renderReport(report, options.format);
 
   if (options.output) {
     await fs.mkdir(path.dirname(path.resolve(options.output)), { recursive: true });
@@ -42,8 +42,8 @@ export async function runAction(env = process.env, stdout = process.stdout, stde
 
 export function parseActionInputs(env = process.env) {
   const format = getInput(env, "format") || "markdown";
-  if (!["markdown", "json"].includes(format)) {
-    throw new Error("format must be either markdown or json");
+  if (!["markdown", "json", "sarif"].includes(format)) {
+    throw new Error("format must be markdown, json, or sarif");
   }
 
   return {
@@ -57,6 +57,16 @@ export function parseActionInputs(env = process.env) {
   };
 }
 
+function renderReport(report, format) {
+  if (format === "json") {
+    return `${JSON.stringify(report, null, 2)}\n`;
+  }
+  if (format === "sarif") {
+    return renderSarif(report);
+  }
+  return renderMarkdown(report);
+}
+
 export async function writeGitHubOutput(outputFile, values) {
   if (!outputFile) {
     return;

package/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { promises as fs } from "node:fs";
-import { auditTarget, renderMarkdown, VERSION } from "./index.js";
+import { auditTarget, renderMarkdown, renderSarif, VERSION } from "./index.js";
 
 async function main(argv) {
   const options = parseArgs(argv);
@@ -18,7 +18,7 @@ async function main(argv) {
     maxFiles: options.maxFiles,
     ref: options.ref
   });
-  const body = options.format === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderMarkdown(report);
+  const body = renderReport(report, options.format);
 
   if (options.output) {
     await fs.writeFile(options.output, body, "utf8");
@@ -85,12 +85,22 @@ function parseArgs(argv) {
   if (positionals.length === 1) {
     options.path = positionals[0];
   }
-  if (!["markdown", "json"].includes(options.format)) {
-    throw new Error("--format must be either markdown or json");
+  if (!["markdown", "json", "sarif"].includes(options.format)) {
+    throw new Error("--format must be markdown, json, or sarif");
   }
   return options;
 }
 
+function renderReport(report, format) {
+  if (format === "json") {
+    return `${JSON.stringify(report, null, 2)}\n`;
+  }
+  if (format === "sarif") {
+    return renderSarif(report);
+  }
+  return renderMarkdown(report);
+}
+
 function requireValue(argv, index, optionName) {
   const value = argv[index];
   if (!value || value.startsWith("-")) {
@@ -111,7 +121,7 @@ function helpText() {
   return `oss-signal audits open-source repository maintenance readiness.
 
 Usage:
-  oss-signal [path-or-github-url] [--format markdown|json] [--output file] [--fail-under score]
+  oss-signal [path-or-github-url] [--format markdown|json|sarif] [--output file] [--fail-under score]
 
 Examples:
   oss-signal .

package/src/index.js

@@ -2,7 +2,25 @@ import { promises as fs } from "node:fs";
 import https from "node:https";
 import path from "node:path";
 
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.0";
+
+const SARIF_RULE_LOCATIONS = {
+  readme: "README.md",
+  license: "LICENSE",
+  contributing: "CONTRIBUTING.md",
+  security: "SECURITY.md",
+  "code-of-conduct": "CODE_OF_CONDUCT.md",
+  changelog: "CHANGELOG.md",
+  support: "SUPPORT.md",
+  ci: ".github/workflows/ci.yml",
+  tests: "test/example.test.js",
+  "issue-templates": ".github/ISSUE_TEMPLATE/bug_report.md",
+  "pull-request-template": ".github/PULL_REQUEST_TEMPLATE.md",
+  dependabot: ".github/dependabot.yml",
+  codeql: ".github/workflows/codeql.yml",
+  "package-json": "package.json",
+  lockfile: "package-lock.json"
+};
 
 const COMMUNITY_FILES = [
   {
@@ -276,6 +294,91 @@ export function renderMarkdown(report) {
   return `${lines.join("\n")}\n`;
 }
 
+export function renderSarif(report) {
+  const rules = report.checks.map((check) => ({
+    id: `oss-signal/${check.id}`,
+    name: check.label,
+    shortDescription: {
+      text: check.label
+    },
+    fullDescription: {
+      text: check.why
+    },
+    help: {
+      text: check.fix,
+      markdown: check.fix
+    },
+    defaultConfiguration: {
+      level: "warning"
+    },
+    properties: {
+      tags: ["oss-signal", "maintainer-readiness"],
+      precision: "high",
+      weight: check.weight
+    }
+  }));
+
+  const results = report.checks
+    .filter((check) => !check.passed)
+    .map((check) => ({
+      ruleId: `oss-signal/${check.id}`,
+      level: "warning",
+      message: {
+        text: `${check.label}: ${check.fix}`
+      },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: {
+              uri: SARIF_RULE_LOCATIONS[check.id] ?? "."
+            },
+            region: {
+              startLine: 1,
+              startColumn: 1
+            }
+          }
+        }
+      ],
+      properties: {
+        why: check.why,
+        fix: check.fix,
+        weight: check.weight
+      }
+    }));
+
+  return `${JSON.stringify({
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "oss-signal",
+            semanticVersion: report.version,
+            informationUri: "https://github.com/SalmonPlays/oss-signal",
+            rules
+          }
+        },
+        automationDetails: {
+          id: "oss-signal/maintainer-readiness"
+        },
+        invocations: [
+          {
+            executionSuccessful: true
+          }
+        ],
+        results,
+        properties: {
+          score: report.score,
+          grade: report.grade,
+          source: sourceSummary(report.source),
+          generatedAt: report.generatedAt
+        }
+      }
+    ]
+  }, null, 2)}\n`;
+}
+
 export async function listRepositoryFiles(root, options = {}) {
   const maxFiles = options.maxFiles ?? 20000;
   const files = [];