oss-signal 0.6.4 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.7.0
+
+- Added `--format plan` for generating PR-sized maintainer plans with suggested files and acceptance criteria.
+- Added maintainer plan documentation and a GitHub repository plan example.
+
 ## 0.6.3
 
 - Updated the release workflow to use Node 24 and npm 11.16 for npm Trusted Publishing support.

package/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If oss-signal helps your maintainer workflow, please cite the repository."
+title: "oss-signal"
+abstract: "Maintainer-readiness CLI and GitHub Action for OSS triage, CI evidence, inventory reports, SARIF, and issue-ready cleanup."
+authors:
+  - family-names: "Oda"
+    given-names: "Amon"
+repository-code: "https://github.com/SalmonPlays/oss-signal"
+url: "https://salmonplays.github.io/oss-signal/"
+license: "MIT"
+version: "0.6.4"
+date-released: "2026-06-04"
+keywords:
+  - open-source
+  - maintainer-tools
+  - github-actions
+  - repository-health
+  - sarif
+  - triage

package/README.md

@@ -6,7 +6,9 @@
 
 [![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)
+[![OpenSSF Scorecard](https://github.com/SalmonPlays/oss-signal/actions/workflows/scorecard.yml/badge.svg)](https://github.com/SalmonPlays/oss-signal/actions/workflows/scorecard.yml)
 [![GitHub release](https://img.shields.io/github/v/release/SalmonPlays/oss-signal.svg)](https://github.com/SalmonPlays/oss-signal/releases/latest)
+[![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-oss--signal-blue.svg)](https://github.com/marketplace/actions/oss-signal)
 [![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)
 [![Self audit](https://img.shields.io/badge/self--audit-100%2F100-brightgreen.svg)](docs/self-audit.md)
@@ -15,20 +17,36 @@
 
 `oss-signal` is a dependency-light maintainer-readiness CLI and GitHub Action for OSS projects that need repeatable triage, CI evidence, SARIF, inventory reports, and issue-ready cleanup notes.
 
-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, SARIF, inventory, or a GitHub Issue-ready Markdown body.
+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, SARIF, inventory, GitHub Issue-ready Markdown, or PR-sized maintainer plan formats.
 
 ![oss-signal example output](docs/assets/terminal-report.svg)
 
 ## Maintainer Evidence Snapshot
 
-Public evidence for the maintainer workflow is collected in [docs/reviewer-evidence.md](docs/reviewer-evidence.md), [docs/adoption-evidence.md](docs/adoption-evidence.md), [docs/post-submission-update.md](docs/post-submission-update.md), and [docs/brand.md](docs/brand.md).
-
-- Published package: [`oss-signal@0.6.4`](https://www.npmjs.com/package/oss-signal), with `latest` pointing at `0.6.4`.
-- Published GitHub Action: [`SalmonPlays/oss-signal@v0.6.4`](https://github.com/SalmonPlays/oss-signal/tree/v0.6.4).
-- Post-submission version note: the application may reference earlier evidence; `0.6.4` is the current maintained release and is documented in [docs/post-submission-update.md](docs/post-submission-update.md).
+Public evidence for the maintainer workflow is collected in [docs/index.md](docs/index.md), [docs/trust-center.md](docs/trust-center.md), [docs/reviewer-evidence.md](docs/reviewer-evidence.md), [docs/adoption-evidence.md](docs/adoption-evidence.md), [docs/adoption-kit.md](docs/adoption-kit.md), [docs/architecture.md](docs/architecture.md), [docs/security-model.md](docs/security-model.md), [docs/json-output.md](docs/json-output.md), [docs/plan-output.md](docs/plan-output.md), [docs/sarif-code-scanning.md](docs/sarif-code-scanning.md), [docs/roadmap.md](docs/roadmap.md), [docs/post-submission-update.md](docs/post-submission-update.md), and [docs/brand.md](docs/brand.md).
+
+- Landing page: https://salmonplays.github.io/oss-signal/
+- Published package: [`oss-signal@0.7.0`](https://www.npmjs.com/package/oss-signal), with `latest` pointing at `0.7.0`.
+- Published GitHub Action: [`SalmonPlays/oss-signal@v0.7.0`](https://github.com/SalmonPlays/oss-signal/tree/v0.7.0).
+- GitHub Marketplace listing: https://github.com/marketplace/actions/oss-signal
+- Trust center: [docs/trust-center.md](docs/trust-center.md)
+- Adoption kit: [docs/adoption-kit.md](docs/adoption-kit.md)
+- Architecture: [docs/architecture.md](docs/architecture.md)
+- Security model: [docs/security-model.md](docs/security-model.md)
+- JSON output contract: [docs/json-output.md](docs/json-output.md)
+- Maintainer plan output: [docs/plan-output.md](docs/plan-output.md)
+- SARIF Code Scanning walkthrough: [docs/sarif-code-scanning.md](docs/sarif-code-scanning.md)
+- Roadmap: [docs/roadmap.md](docs/roadmap.md)
+- Post-submission version note: the application may reference earlier evidence; `0.7.0` is the current maintained release and is documented in [docs/post-submission-update.md](docs/post-submission-update.md).
 - Public checks: CI, Repository health, and CodeQL are passing on `main`.
+- Security posture: OpenSSF Scorecard is scheduled, CodeQL is active, secret scanning push protection is enabled, Dependabot alerts/security updates/malware alerts are enabled, and private vulnerability reporting is enabled.
+- Branch posture: `main` has branch protection to prevent force pushes and deletions while keeping direct maintainer maintenance possible.
+- Governance posture: [MAINTAINERS.md](MAINTAINERS.md), [GOVERNANCE.md](GOVERNANCE.md), and [.github/CODEOWNERS](.github/CODEOWNERS) define ownership, review routing, and supported change scope.
+- Community route: [Discussion #5](https://github.com/SalmonPlays/oss-signal/discussions/5) is the public maintainer-workflow thread for usage questions and rule feedback.
 - Self-audit: this repository scores **100/100 (A)** locally and through GitHub URL mode.
-- Field use: four public maintainer-readiness audits have been turned into four issues and four focused follow-up PRs.
+- Field use: five public maintainer-readiness audits have been turned into five issues and four focused follow-up PRs.
+- External OSS contribution: [icoretech/codex-action PR #24](https://github.com/icoretech/codex-action/pull/24) is a focused Codex Action documentation safety fix.
+- Contributor intake: [good first issues](https://github.com/SalmonPlays/oss-signal/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) are labeled for small outside PRs.
 - Inventory mode: the CLI and Action can audit a newline-delimited list of repositories for organization-level triage.
 - Separate workflow demo: [oss-signal-adoption-demo](https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26883001038) runs the public Action tag and uploads Markdown, SARIF, and Issue-ready artifacts.
 
@@ -58,6 +76,8 @@ Try it without installing:
 npx oss-signal SalmonPlays/oss-signal
 ```
 
+Use it from GitHub Marketplace: https://github.com/marketplace/actions/oss-signal
+
 For local development:
 
 ```bash
@@ -94,6 +114,8 @@ Use JSON in automation:
 oss-signal . --format json --fail-under 80
 ```
 
+See [docs/json-output.md](docs/json-output.md) for the JSON schema and fixture.
+
 Audit multiple repositories from one newline-delimited inventory file:
 
 ```bash
@@ -108,6 +130,8 @@ Write SARIF for GitHub Code Scanning or other dashboards:
 oss-signal . --format sarif --output oss-signal.sarif
 ```
 
+See [docs/sarif-code-scanning.md](docs/sarif-code-scanning.md) for the Code Scanning upload workflow and expected output.
+
 Generate a report that can be attached to an issue:
 
 ```bash
@@ -120,6 +144,14 @@ Generate a maintainer-friendly issue body:
 oss-signal platformatic/massimo --format issue --output maintainer-follow-up.md
 ```
 
+Generate a PR-sized maintainer plan:
+
+```bash
+oss-signal Grovanni/oss-signal --format plan --output maintainer-plan.md
+```
+
+See [docs/plan-output.md](docs/plan-output.md) and [docs/examples/github-plan.md](docs/examples/github-plan.md) for an example.
+
 ## Checks
 
 `oss-signal` currently checks:
@@ -130,7 +162,7 @@ oss-signal platformatic/massimo --format issue --output maintainer-follow-up.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. Issue output turns the same findings into a human-reviewed checklist that can be edited before posting.
+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. Issue output turns the same findings into a human-reviewed checklist that can be edited before posting. Plan output turns the findings into a PR-sized sequence with suggested files and acceptance criteria.
 
 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.
 
@@ -147,9 +179,9 @@ Summary:
 - Total checks: 15
 ```
 
-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, [docs/examples/github-issue-body.md](docs/examples/github-issue-body.md) for issue output, and [docs/examples/self-audit.sarif](docs/examples/self-audit.sarif) for SARIF 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, [docs/examples/github-issue-body.md](docs/examples/github-issue-body.md) for issue output, [docs/examples/github-plan.md](docs/examples/github-plan.md) for plan 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.6.4`, uploads the Markdown report as an artifact, and uploads SARIF to GitHub Code Scanning on non-PR runs. The [Repository inventory workflow](.github/workflows/repository-inventory.yml) runs the inventory mode from CI and uploads a multi-repository report artifact.
+The [Repository health workflow](.github/workflows/repository-health.yml) runs `SalmonPlays/oss-signal@v0.7.0`, uploads the Markdown report as an artifact, and uploads SARIF to GitHub Code Scanning on non-PR runs. The [Repository inventory workflow](.github/workflows/repository-inventory.yml) runs the inventory mode from CI and uploads a multi-repository report artifact.
 
 ## Field Audits
 
@@ -159,9 +191,14 @@ The [Repository health workflow](.github/workflows/repository-health.yml) runs `
 - [supermarkt/checkjebon report](docs/outreach/supermarkt-checkjebon-report.md), [issue #22](https://github.com/supermarkt/checkjebon/issues/22), and [PR #23](https://github.com/supermarkt/checkjebon/pull/23)
 - [sammorrisdesign/interactive-feed report](docs/outreach/sammorrisdesign-interactive-feed-report.md), [issue #14](https://github.com/sammorrisdesign/interactive-feed/issues/14), and [PR #15](https://github.com/sammorrisdesign/interactive-feed/pull/15)
 - [flox/install-flox-action report](docs/outreach/flox-install-flox-action-report.md), [issue #204](https://github.com/flox/install-flox-action/issues/204), and [PR #205](https://github.com/flox/install-flox-action/pull/205)
+- [Grovanni/oss-signal report](docs/outreach/grovanni-oss-signal-report.md) and [issue #1](https://github.com/Grovanni/oss-signal/issues/1)
 
 See [docs/outreach](docs/outreach) for the reports and draft issue text. Drafts are not posted automatically; maintainers should only receive specific, useful, and respectful suggestions.
 
+Additional prepared outreach candidates are tracked in [docs/outreach/peer-shortlist-2026-06.md](docs/outreach/peer-shortlist-2026-06.md). The shortlist explicitly separates respectful, defensible candidates from low-signal mass outreach.
+
+Additional focused external contribution: [icoretech/codex-action PR #24](https://github.com/icoretech/codex-action/pull/24) updates Codex Action README examples to route generated output through environment variables before printing it from shell steps.
+
 For a compact maintainer/adoption summary, see [docs/adoption-evidence.md](docs/adoption-evidence.md). For a reviewer-oriented verification path, see [docs/reviewer-evidence.md](docs/reviewer-evidence.md).
 
 Separate public workflow evidence: [SalmonPlays/oss-signal-adoption-demo](https://github.com/SalmonPlays/oss-signal-adoption-demo) runs `SalmonPlays/oss-signal@v0.5.1` and produced a successful [workflow run](https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26883001038) with Markdown, SARIF, and Issue-ready report artifacts.
@@ -193,7 +230,7 @@ oss-signal . --fail-under 80
 Add `oss-signal` directly to a GitHub Actions workflow:
 
 ```yaml
-- uses: SalmonPlays/oss-signal@v0.6.4
+- uses: SalmonPlays/oss-signal@v0.7.0
   id: oss-signal
   with:
     fail-under: "80"
@@ -209,7 +246,7 @@ The Action writes a concise GitHub Actions step summary by default, so reviewers
 Run an inventory from CI:
 
 ```yaml
-- uses: SalmonPlays/oss-signal@v0.6.4
+- uses: SalmonPlays/oss-signal@v0.7.0
   env:
     GITHUB_TOKEN: ${{ github.token }}
   with:
@@ -221,7 +258,7 @@ Run an inventory from CI:
 Generate an editable Issue body from CI:
 
 ```yaml
-- uses: SalmonPlays/oss-signal@v0.6.4
+- uses: SalmonPlays/oss-signal@v0.7.0
   with:
     format: issue
     output: maintainer-follow-up.md
@@ -243,7 +280,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: SalmonPlays/oss-signal@v0.6.4
+      - uses: SalmonPlays/oss-signal@v0.7.0
         id: oss-signal
         with:
           fail-under: "80"
@@ -266,7 +303,7 @@ permissions:
 
 steps:
   - uses: actions/checkout@v4
-  - uses: SalmonPlays/oss-signal@v0.6.4
+  - uses: SalmonPlays/oss-signal@v0.7.0
     with:
       format: sarif
       output: oss-signal.sarif
@@ -276,7 +313,7 @@ steps:
       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.6.4` against the repository, uploads the Markdown report artifact, and publishes SARIF to Code Scanning on non-PR runs.
+This repository dogfoods the public Action tag in [Repository health](.github/workflows/repository-health.yml), which runs `SalmonPlays/oss-signal@v0.7.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:
 

package/action.yml

@@ -13,7 +13,7 @@ inputs:
     description: Newline-delimited file of local paths, GitHub URLs, or owner/repo shorthands to audit as an inventory.
     required: false
   format:
-    description: Output format, either markdown, json, sarif, or issue. Inventory mode supports markdown or json.
+    description: Output format, either markdown, json, sarif, issue, or plan. Inventory mode supports markdown or json.
     required: false
     default: markdown
   output:

package/docs/adoption-evidence.md

@@ -2,17 +2,24 @@
 
 This page collects the public evidence that `oss-signal` is built for real open-source maintainer workflows.
 
-Last verified: 2026-06-04T03:01:28Z
+Last verified: 2026-06-04T11:14:41Z
 
 ## Project Links
 
 - Repository: https://github.com/SalmonPlays/oss-signal
-- npm package: https://www.npmjs.com/package/oss-signal (`0.6.4` latest)
-- GitHub Release: https://github.com/SalmonPlays/oss-signal/releases/tag/v0.6.4
-- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.6.4
+- GitHub Pages landing page: https://salmonplays.github.io/oss-signal/
+- npm package: https://www.npmjs.com/package/oss-signal (`0.7.0` latest)
+- GitHub Release: https://github.com/SalmonPlays/oss-signal/releases/tag/v0.7.0
+- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.7.0
+- GitHub Marketplace listing: https://github.com/marketplace/actions/oss-signal
 - GitHub Action metadata: [action.yml](../action.yml)
 - Public dogfood workflow: [.github/workflows/repository-health.yml](../.github/workflows/repository-health.yml)
 - Public inventory workflow: [.github/workflows/repository-inventory.yml](../.github/workflows/repository-inventory.yml)
+- OpenSSF Scorecard workflow: [.github/workflows/scorecard.yml](../.github/workflows/scorecard.yml)
+- Maintainers: [MAINTAINERS.md](../MAINTAINERS.md)
+- Governance: [GOVERNANCE.md](../GOVERNANCE.md)
+- CODEOWNERS: [.github/CODEOWNERS](../.github/CODEOWNERS)
+- Maintainer workflow Discussion: https://github.com/SalmonPlays/oss-signal/discussions/5
 - Separate public workflow demo: https://github.com/SalmonPlays/oss-signal-adoption-demo
 - Separate public workflow run: https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26883001038
 - Self-audit report: [docs/self-audit.md](self-audit.md)
@@ -22,7 +29,16 @@ Last verified: 2026-06-04T03:01:28Z
 - Inventory target example: [docs/examples/inventory-targets.txt](examples/inventory-targets.txt)
 - Inventory report example: [docs/examples/inventory-report.md](examples/inventory-report.md)
 - Brand assets and GitHub settings copy: [docs/brand.md](brand.md)
+- GitHub Pages landing page source: [docs/index.md](index.md)
+- GitHub Marketplace publishing checklist: [docs/marketplace.md](marketplace.md)
 - Maintainer playbook: [docs/maintainer-playbook.md](maintainer-playbook.md)
+- Trust center: [docs/trust-center.md](trust-center.md)
+- Adoption kit: [docs/adoption-kit.md](adoption-kit.md)
+- Architecture: [docs/architecture.md](architecture.md)
+- Security model: [docs/security-model.md](security-model.md)
+- JSON output contract: [docs/json-output.md](json-output.md)
+- SARIF Code Scanning walkthrough: [docs/sarif-code-scanning.md](sarif-code-scanning.md)
+- Roadmap: [docs/roadmap.md](roadmap.md)
 - Reviewer evidence quickstart: [docs/reviewer-evidence.md](reviewer-evidence.md)
 - Post-submission update: [docs/post-submission-update.md](post-submission-update.md)
 - Release process: [docs/release-process.md](release-process.md)
@@ -48,7 +64,7 @@ The [post-submission update](post-submission-update.md) records why the current
 
 ## Published Package Verification
 
-The npm package is publicly available as `oss-signal@0.6.4` with `latest` pointing at `0.6.4`.
+The npm package is publicly available as `oss-signal@0.7.0` with `latest` pointing at `0.7.0`.
 
 The npm downloads API returned 356 downloads for both last-week and last-month windows on 2026-06-04. Download counts can lag publication, so this is treated as supporting evidence rather than proof of broad adoption.
 
@@ -56,7 +72,7 @@ Clean-directory execution against the public GitHub repository returned:
 
 ```json
 {
-  "version": "0.6.4",
+  "version": "0.7.0",
   "score": 100,
   "grade": "A",
   "source": "github"
@@ -69,10 +85,19 @@ Current public workflow status:
 - Repository health: passing
 - Repository inventory: passing
 - CodeQL: passing
+- OpenSSF Scorecard: configured on `main` pushes and a weekly schedule, with JSON artifact output and public Scorecard publishing
 - Release: passing
+- GitHub Pages deployment: passing, with the repository homepage set to https://salmonplays.github.io/oss-signal/
+- GitHub Marketplace listing: published for the `v0.7.0` Action release
+- GitHub issue forms: adoption report and maintainer audit report forms are available for structured public evidence intake
+- GitHub citation metadata: `CITATION.cff` is present for the repository citation UI
+- Automation contract: JSON schema and fixture are documented for `--format json`
+- Code Scanning walkthrough: SARIF upload permissions, expected warnings, fixture, and output example are documented
+- GitHub repository hardening: `main` branch protection, private vulnerability reporting, dependency graph, automatic dependency submission, Dependabot alerts/security updates/grouped updates/malware alerts, secret scanning, and push protection are enabled
+- Maintainer workflow Discussion: published
 - Separate public workflow demo: passing
 
-The npm registry returned `0.6.4` for both the package version and `latest` dist-tag on 2026-06-04T02:42:51Z. The same check returned 356 downloads for the last-week and last-month windows.
+After the v0.7.0 release, the npm registry should return `0.7.0` for both the package version and `latest` dist-tag. The earlier 2026-06-04 download check returned 356 downloads for the last-week and last-month windows.
 
 ## Separate Public Workflow Evidence
 
@@ -94,10 +119,34 @@ The tool has been used to generate maintainer-readiness reports for public repos
 | `supermarkt/checkjebon` | [report](outreach/supermarkt-checkjebon-report.md) | https://github.com/supermarkt/checkjebon/issues/22 | https://github.com/supermarkt/checkjebon/pull/23 | open, clean |
 | `sammorrisdesign/interactive-feed` | [report](outreach/sammorrisdesign-interactive-feed-report.md) | https://github.com/sammorrisdesign/interactive-feed/issues/14 | https://github.com/sammorrisdesign/interactive-feed/pull/15 | open |
 | `flox/install-flox-action` | [report](outreach/flox-install-flox-action-report.md) | https://github.com/flox/install-flox-action/issues/204 | https://github.com/flox/install-flox-action/pull/205 | open, checks pending |
+| `Grovanni/oss-signal` | [report](outreach/grovanni-oss-signal-report.md) | https://github.com/Grovanni/oss-signal/issues/1 | N/A | open |
 
 These issues and pull requests are evidence of the intended maintainer workflow: run a deterministic audit, explain the missing signals, and give maintainers a small set of actionable improvements. Each PR is intentionally limited to documentation or GitHub templates.
 
-All four follow-up PRs were still open when checked from GitHub on 2026-06-04T02:42:51Z. They are not claimed as accepted adoption unless a maintainer merges or otherwise endorses them.
+Prepared but not yet posted outreach candidates are tracked separately in [outreach/peer-shortlist-2026-06.md](outreach/peer-shortlist-2026-06.md) and [outreach](outreach). This prevents candidate research from being overstated as real external maintainer engagement.
+
+The workflow now includes [plan-output.md](plan-output.md), which converts audit findings into a PR-sized sequence before a contributor posts externally. The example [examples/github-plan.md](examples/github-plan.md) uses the `Grovanni/oss-signal` field audit and shows suggested files plus acceptance criteria.
+
+Additional focused external contribution:
+
+- `icoretech/codex-action`: https://github.com/icoretech/codex-action/pull/24 updates Codex Action README examples so generated output is routed through environment variables before shell printing.
+
+All field-audit follow-up PRs were still open when checked from GitHub on 2026-06-04T10:38:39Z. They are not claimed as accepted adoption unless a maintainer merges or otherwise endorses them.
+
+## Contributor Intake
+
+The project now has labeled good-first-issue routes for outside contributors:
+
+- https://github.com/SalmonPlays/oss-signal/issues/6
+- https://github.com/SalmonPlays/oss-signal/issues/7
+
+The repository also includes a GitHub Discussions category form for structured rule feedback, Action usage questions, and maintainer workflow adoption notes. The issue templates include adoption and maintainer-audit forms so users can share workflow-run evidence or discuss reports without inventing the format.
+
+Current public roadmap evidence:
+
+- https://github.com/SalmonPlays/oss-signal/issues/8 tracks the first independent public workflow run or maintainer acknowledgement.
+- https://github.com/SalmonPlays/oss-signal/issues/9 was closed as completed after adding [json-output.md](json-output.md), the JSON schema, fixture, and reviewer links.
+- https://github.com/SalmonPlays/oss-signal/issues/10 was closed as completed after adding [sarif-code-scanning.md](sarif-code-scanning.md), the Code Scanning output example, and reviewer links.
 
 ## Verification Commands
 
@@ -109,16 +158,18 @@ npm run audit:github
 node src/cli.js . --format sarif --output docs/examples/self-audit.sarif
 node src/cli.js --inventory docs/examples/inventory-targets.txt --format markdown --output docs/examples/inventory-report.md
 node src/cli.js platformatic/massimo --format json
-npm exec --yes --package=oss-signal@0.6.4 -- oss-signal SalmonPlays/oss-signal --format json
+npm exec --yes --package=oss-signal@0.7.0 -- oss-signal 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 public `v0.6.4` Action tag is used by the repository health workflow for Markdown and SARIF output. The published npm `0.6.4` package has also been executed from a clean temporary directory against the public GitHub repository, returning 100/100 (A).
+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.7.0` Action tag is used by the repository health workflow for Markdown and SARIF output. The published npm `0.7.0` package has also been executed from a clean temporary directory against the public GitHub repository, returning 100/100 (A).
 
 Public CI evidence:
 
 - 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
+- OpenSSF Scorecard workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/scorecard.yml
+- Maintainer workflow Discussion: https://github.com/SalmonPlays/oss-signal/discussions/5
 - Separate workflow demo run: https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26883001038
 - Reviewer verification quickstart: [reviewer-evidence.md](reviewer-evidence.md)
 

package/docs/adoption-kit.md

@@ -0,0 +1,92 @@
+# Adoption Kit
+
+This page gives maintainers a copy-paste path for trying `oss-signal` and leaving useful public evidence.
+
+## Try The CLI
+
+Run against a public repository without cloning:
+
+```bash
+npm exec --yes --package=oss-signal@0.7.0 -- oss-signal owner/repo --format markdown --output oss-signal-report.md
+```
+
+Run against the current checkout:
+
+```bash
+npx oss-signal . --format markdown --output oss-signal-report.md
+```
+
+Generate a human-reviewed issue body:
+
+```bash
+npx oss-signal owner/repo --format issue --output maintainer-follow-up.md
+```
+
+## Add The GitHub Action
+
+```yaml
+name: Repository health
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  oss-signal:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: SalmonPlays/oss-signal@v0.7.0
+        id: oss-signal
+        with:
+          fail-under: "80"
+          output: oss-signal-report.md
+          summary: "true"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: oss-signal-report
+          path: oss-signal-report.md
+```
+
+## Add SARIF To Code Scanning
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: SalmonPlays/oss-signal@v0.7.0
+    with:
+      format: sarif
+      output: oss-signal.sarif
+      summary: "false"
+  - uses: github/codeql-action/upload-sarif@v3
+    with:
+      sarif_file: oss-signal.sarif
+```
+
+Full walkthrough: [sarif-code-scanning.md](sarif-code-scanning.md)
+
+## Share Evidence
+
+Useful adoption evidence is concrete and public:
+
+- A workflow run that uses `SalmonPlays/oss-signal@v0.7.0`.
+- A Markdown report attached as a workflow artifact.
+- A SARIF upload that appears in Code Scanning.
+- A focused issue or pull request created from an audit finding.
+- A short note about what maintainer task the audit improved.
+
+Open an [adoption report](https://github.com/SalmonPlays/oss-signal/issues/new?template=adoption_report.yml) when a public repository uses the CLI or Action. Open a [maintainer audit report](https://github.com/SalmonPlays/oss-signal/issues/new?template=audit_report.yml) when you want to discuss a generated report before posting follow-up to another repository.
+
+## Boundaries
+
+Do not treat the score as a code-quality verdict. It measures visible maintainer-readiness signals: contribution paths, security reporting, CI, templates, release notes, and related repository hygiene.
+
+Do not claim third-party adoption unless the repository owner or maintainer has actually used, merged, or acknowledged the workflow.

package/docs/architecture.md

@@ -0,0 +1,57 @@
+# Architecture
+
+`oss-signal` is intentionally small: a Node.js CLI, a GitHub Action wrapper, and deterministic rule modules that inspect visible repository files and GitHub repository metadata.
+
+## Components
+
+| Component | Path | Responsibility |
+| --- | --- | --- |
+| CLI entrypoint | [src/cli.js](../src/cli.js) | Parses arguments, selects local/GitHub/inventory mode, writes reports, and applies `--fail-under`. |
+| Audit engine | [src/index.js](../src/index.js) | Reads repository files, evaluates maintainer-readiness rules, scores results, and renders Markdown, JSON, SARIF, inventory, or issue output. |
+| Action wrapper | [src/action.js](../src/action.js) | Maps GitHub Action inputs to CLI behavior, sets Action outputs, and writes the step summary. |
+| Action metadata | [action.yml](../action.yml) | Defines Marketplace-visible inputs, outputs, branding, and Node runtime. |
+| Rules reference | [docs/rules.md](rules.md) | Documents each rule, weight, and maintainer rationale. |
+
+## Data Flow
+
+```mermaid
+flowchart LR
+  input["Repository path, GitHub URL, owner/repo, or inventory file"]
+  reader["File and metadata reader"]
+  rules["Maintainer-readiness rules"]
+  score["Score and grade"]
+  outputs["Markdown, JSON, SARIF, issue body, or inventory report"]
+  ci["GitHub Actions summary, artifact, or Code Scanning upload"]
+
+  input --> reader --> rules --> score --> outputs --> ci
+```
+
+## Local Repository Mode
+
+Local mode reads files from the target path and checks for visible maintainer signals such as `README`, license, `CONTRIBUTING.md`, `SECURITY.md`, issue templates, pull request templates, CI, tests, Dependabot, CodeQL-style workflows, and release notes.
+
+No network access is required for local mode.
+
+## GitHub Repository Mode
+
+GitHub URL mode fetches a public repository file tree through the GitHub API and checks the same visible signals without requiring a clone. When `GITHUB_TOKEN` is available, it can use the token for higher API rate limits. The token is not printed in output.
+
+## Inventory Mode
+
+Inventory mode reads a newline-delimited target list and runs the audit for each repository. It is designed for maintainers who need a quick portfolio view across several public repositories.
+
+## Output Modes
+
+- Markdown: human-readable maintainer report.
+- JSON: automation-friendly result object.
+- SARIF: warning-level findings for GitHub Code Scanning or other SARIF consumers.
+- Issue: an editable maintainer follow-up body.
+- Inventory: table and aggregate summary across multiple targets.
+
+## Design Constraints
+
+- Dependency-light by design.
+- Deterministic scoring from visible repository signals.
+- No hidden telemetry.
+- No automatic issue or pull request posting.
+- No claim that the score measures product quality, code quality, popularity, or security completeness.

package/docs/assets/code-scanning-results.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="430" viewBox="0 0 920 430" role="img" aria-labelledby="title desc">
+  <title id="title">oss-signal Code Scanning results example</title>
+  <desc id="desc">Example GitHub Code Scanning view showing warning-level maintainer-readiness findings from oss-signal SARIF output.</desc>
+  <rect width="920" height="430" rx="18" fill="#ffffff"/>
+  <rect x="1" y="1" width="918" height="428" rx="18" fill="none" stroke="#d0d7de" stroke-width="2"/>
+  <rect x="0" y="0" width="920" height="58" rx="18" fill="#f6f8fa"/>
+  <text x="32" y="37" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="18" font-weight="700">GitHub Code Scanning</text>
+  <text x="32" y="98" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="28" font-weight="700">oss-signal maintainer-readiness findings</text>
+  <text x="32" y="132" fill="#57606a" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="16">SARIF upload from SalmonPlays/oss-signal@v0.7.0</text>
+  <rect x="32" y="162" width="856" height="72" rx="10" fill="#fffbdd" stroke="#d4a72c"/>
+  <circle cx="65" cy="198" r="10" fill="#bf8700"/>
+  <text x="88" y="194" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="17" font-weight="700">oss-signal/security</text>
+  <text x="88" y="218" fill="#57606a" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="15">Security policy: Add SECURITY.md with supported versions and reporting instructions.</text>
+  <text x="758" y="203" fill="#57606a" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="15">warning</text>
+  <rect x="32" y="252" width="856" height="72" rx="10" fill="#fffbdd" stroke="#d4a72c"/>
+  <circle cx="65" cy="288" r="10" fill="#bf8700"/>
+  <text x="88" y="284" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="17" font-weight="700">oss-signal/dependabot</text>
+  <text x="88" y="308" fill="#57606a" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="15">Dependency update automation: Add .github/dependabot.yml for the repository ecosystem.</text>
+  <text x="758" y="293" fill="#57606a" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="15">warning</text>
+  <rect x="32" y="342" width="856" height="46" rx="10" fill="#f6f8fa" stroke="#d0d7de"/>
+  <text x="54" y="371" fill="#57606a" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="15">Report properties include score, grade, source, and generatedAt for reviewer context.</text>
+</svg>

package/docs/assets/oss-signal-banner.svg

@@ -34,7 +34,7 @@
     <rect x="334" y="266" width="144" height="42" rx="21" fill="#dcfce7"/>
     <text x="359" y="293" fill="#166534">100/100 A</text>
     <rect x="494" y="266" width="142" height="42" rx="21" fill="#dbeafe"/>
-    <text x="521" y="293" fill="#1e40af">npm 0.6.4</text>
+    <text x="521" y="293" fill="#1e40af">npm 0.7.0</text>
     <rect x="652" y="266" width="178" height="42" rx="21" fill="#e0f2fe"/>
     <text x="681" y="293" fill="#075985">GitHub Action</text>
     <rect x="846" y="266" width="168" height="42" rx="21" fill="#fef9c3"/>

package/docs/brand.md

@@ -13,6 +13,7 @@ The display name is intentionally more descriptive for reviewers, while `oss-sig
 - README banner: [assets/oss-signal-banner.svg](assets/oss-signal-banner.svg)
 - GitHub social preview source: [assets/github-social-preview.svg](assets/github-social-preview.svg)
 - GitHub social preview PNG: [assets/github-social-preview.png](assets/github-social-preview.png)
+- GitHub profile avatar candidate: [assets/github-profile-avatar.png](assets/github-profile-avatar.png)
 
 ## GitHub Settings Copy
 
@@ -38,6 +39,6 @@ oss
 These cannot be committed through git:
 
 - Repository social preview: upload `docs/assets/github-social-preview.png` in GitHub repository settings.
-- GitHub profile or organization avatar: upload `docs/assets/oss-signal-icon.png`.
+- GitHub profile or organization avatar: upload `docs/assets/github-profile-avatar.png` for a maintainer-profile look, or `docs/assets/oss-signal-icon.png` for a pure project-logo look.
 
 The repository name should remain `oss-signal` unless the npm package and GitHub Action distribution are intentionally migrated.