oss-signal 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -2,11 +2,21 @@
 
 ## 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.5.1
+
+- Published the Issue-ready output release on a clean tag after release workflow hardening.
+- Guarded automatic npm publishing behind an explicit repository variable.
+
+## 0.5.0
+
+- Added `--format issue` for generating human-reviewed GitHub Issue bodies from audit findings.
+- Added an issue-output example and maintainer playbook guidance for audit-to-issue workflows.
 
 ## 0.4.0
 
+- 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.
+
 - Added SARIF output for GitHub Code Scanning and other security dashboards.
 - Added Action support for `format: sarif`.
 

package/README.md

@@ -9,7 +9,7 @@
 
 `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, JSON, or SARIF.
+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, or a GitHub Issue-ready Markdown body.
 
 ![oss-signal example output](docs/assets/terminal-report.svg)
 
@@ -87,6 +87,12 @@ Generate a report that can be attached to an issue:
 oss-signal . --format markdown --output docs/maintainer-readiness.md
 ```
 
+Generate a maintainer-friendly issue body:
+
+```bash
+oss-signal platformatic/massimo --format issue --output maintainer-follow-up.md
+```
+
 ## Checks
 
 `oss-signal` currently checks:
@@ -97,7 +103,7 @@ 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.
+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.
 
 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.
 
@@ -114,9 +120,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, 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, 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.
+The [Repository health workflow](.github/workflows/repository-health.yml) runs `SalmonPlays/oss-signal@v0.5.1`, uploads the Markdown report as an artifact, and uploads SARIF to GitHub Code Scanning on non-PR runs.
 
 ## Field Audits
 
@@ -130,6 +136,8 @@ See [docs/outreach](docs/outreach) for the reports and draft issue text. Drafts
 
 For a compact maintainer/adoption summary, see [docs/adoption-evidence.md](docs/adoption-evidence.md).
 
+Separate public workflow evidence: [SalmonPlays/oss-signal-adoption-demo](https://github.com/SalmonPlays/oss-signal-adoption-demo) runs `SalmonPlays/oss-signal@v0.4.0` and produced a successful [workflow run](https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26862361229) with a report artifact.
+
 ## Example Recommendation Output
 
 ```text
@@ -157,7 +165,7 @@ oss-signal . --fail-under 80
 Add `oss-signal` directly to a GitHub Actions workflow:
 
 ```yaml
-- uses: SalmonPlays/oss-signal@v0.4.0
+- uses: SalmonPlays/oss-signal@v0.5.1
   id: oss-signal
   with:
     fail-under: "80"
@@ -170,6 +178,16 @@ The Action writes a concise GitHub Actions step summary by default, so reviewers
 
 ![oss-signal GitHub Actions summary](docs/assets/github-step-summary.svg)
 
+Generate an editable Issue body from CI:
+
+```yaml
+- uses: SalmonPlays/oss-signal@v0.5.1
+  with:
+    format: issue
+    output: maintainer-follow-up.md
+    summary: "true"
+```
+
 Full workflow example:
 
 ```yaml
@@ -185,7 +203,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: SalmonPlays/oss-signal@v0.4.0
+      - uses: SalmonPlays/oss-signal@v0.5.1
         id: oss-signal
         with:
           fail-under: "80"
@@ -208,7 +226,7 @@ permissions:
 
 steps:
   - uses: actions/checkout@v4
-  - uses: SalmonPlays/oss-signal@v0.4.0
+  - uses: SalmonPlays/oss-signal@v0.5.1
     with:
       format: sarif
       output: oss-signal.sarif
@@ -218,7 +236,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.4.0` 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.5.1` 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

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

package/docs/adoption-evidence.md

@@ -5,11 +5,13 @@ 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 (`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
+- npm package: https://www.npmjs.com/package/oss-signal (`0.5.1` latest)
+- GitHub Release: https://github.com/SalmonPlays/oss-signal/releases/tag/v0.5.1
+- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.5.1
 - GitHub Action metadata: [action.yml](../action.yml)
 - Public dogfood workflow: [.github/workflows/repository-health.yml](../.github/workflows/repository-health.yml)
+- 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/26862361229
 - 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)
@@ -17,6 +19,7 @@ This page collects the public evidence that `oss-signal` is built for real open-
 - 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)
+- Codex for Open Source form answers: [docs/codex-for-oss-form-answers.md](codex-for-oss-form-answers.md)
 - Rule reference: [docs/rules.md](rules.md)
 
 ## Maintainer Use Case
@@ -32,6 +35,16 @@ It also ships as a GitHub Action, so maintainers can gate repository hygiene in
 
 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.
 
+## Separate Public Workflow Evidence
+
+The public repository https://github.com/SalmonPlays/oss-signal-adoption-demo runs `SalmonPlays/oss-signal@v0.4.0` from a separate workflow file:
+
+- Workflow file: https://github.com/SalmonPlays/oss-signal-adoption-demo/blob/main/.github/workflows/oss-signal.yml
+- Successful workflow run: https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26862361229
+- Artifact: `oss-signal-adoption-demo-report`, containing `oss-signal-report.md` and `oss-signal.sarif`
+
+This is not claimed as independent third-party adoption because the repository is owned by `SalmonPlays`. It is evidence that the public `v0.4.0` Action tag works outside the main repository and can publish maintainer-readiness reports from another public workflow.
+
 ## Public Field Audits And PRs
 
 The tool has been used to generate maintainer-readiness reports for public repositories and convert them into respectful cleanup issues:
@@ -53,16 +66,17 @@ 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
+npm exec --yes --package=oss-signal@0.5.1 -- 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.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.
+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.5.1` Action tag is used by the repository health workflow for Markdown and SARIF output. The published npm `0.5.1` 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
+- Separate workflow demo run: https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26862361229
 
 ## Boundaries
 

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

@@ -1,6 +1,6 @@
 # Codex for Open Source Application Brief
 
-Snapshot: 2026-06-03T03:06:42Z
+Snapshot: 2026-06-03T05:11:50Z
 
 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,12 +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 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 Release: https://github.com/SalmonPlays/oss-signal/releases/tag/v0.5.1
+- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.5.1
 - 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
+- Separate public workflow demo: https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26862361229
 - Maintainer evidence: [adoption-evidence.md](adoption-evidence.md)
+- Form answer pack: [codex-for-oss-form-answers.md](codex-for-oss-form-answers.md)
 - Maintainer playbook: [maintainer-playbook.md](maintainer-playbook.md)
 - Release process: [release-process.md](release-process.md)
 
@@ -42,19 +44,26 @@ This project is designed around repeatable maintainer workflows where Codex is u
 
 The repository currently has:
 
-- 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 published npm package with `0.5.1` as the latest release.
+- A published GitHub Release for v0.5.1 with issue-output release notes and CI usage guidance.
 - A reusable GitHub Action with `score`, `grade`, `failed`, and `report-path` outputs.
 - 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 v0.5.1 GitHub Action tag with step summary, SARIF support, and Issue-ready output.
+- A public dogfood workflow that runs `SalmonPlays/oss-signal@v0.5.1` against the repository, uploads the Markdown report artifact, and uploads SARIF to GitHub Code Scanning on non-PR runs.
+- A separate public workflow demo that runs `SalmonPlays/oss-signal@v0.4.0` from another repository and uploads a report artifact.
 - 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).
+- A clean-directory smoke test of `npm exec --yes --package=oss-signal@0.5.1 -- oss-signal SalmonPlays/oss-signal --format json`, returning 100/100 (A).
 - Public reports, issues, and PRs created from real repository audits.
 
+## Separate Workflow Demo
+
+The repository https://github.com/SalmonPlays/oss-signal-adoption-demo runs the public `SalmonPlays/oss-signal@v0.4.0` Action tag from a separate workflow. The successful run at https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26862361229 uploaded an `oss-signal-adoption-demo-report` artifact containing Markdown and SARIF output.
+
+This is intentionally described as a separate public workflow demo rather than third-party adoption because the repository is also owned by `SalmonPlays`. It still proves that the published Action tag is consumable outside the main repository.
+
 ## Field Audits And Follow-Up PRs
 
 | Repository | Report | Issue | PR | Status |
@@ -71,14 +80,16 @@ Recommended application angle:
 
 `oss-signal` is not yet a widely adopted project, but it is a public OSS maintainer tool built specifically for repeatable Codex-assisted maintenance. The project already has a working CLI, npm distribution, GitHub Action, passing CI/CodeQL, self-audit evidence, and three public field-audit PRs. Codex support would be used to continue auditing repositories, prepare focused maintainer PRs, improve Action automation, and document repeatable OSS maintenance workflows.
 
+Prepared official form answers are in [codex-for-oss-form-answers.md](codex-for-oss-form-answers.md). The applicant still needs to fill personal identity fields and their OpenAI Organization ID directly.
+
 ## Current Gaps
 
 - External PRs are open but not yet merged.
 - npm download metrics are still early because the package is newly published.
-- The project needs more real maintainers using the Action in their own repositories.
+- The project needs independent maintainer-owned repositories using the Action in their own workflows.
 
 ## Next Evidence To Collect
 
 - One or more merged external PRs.
-- A public workflow run in another repository using `SalmonPlays/oss-signal@v0.4.0`, ideally with SARIF upload enabled.
+- A public workflow run in an independent maintainer-owned repository using `SalmonPlays/oss-signal@v0.5.1`, ideally with SARIF upload enabled.
 - npm download data once the registry starts reporting weekly/monthly counts.

package/docs/codex-for-oss-form-answers.md

@@ -0,0 +1,94 @@
+# Codex for Open Source Form Answers
+
+Snapshot: 2026-06-03T05:11:50Z
+
+This page prepares concise answers for the official Codex for Open Source application form: https://openai.com/form/codex-for-oss/
+
+The official form asks for personal identity fields that must be filled by the applicant:
+
+- First name
+- Last name
+- Email associated with the applicant's ChatGPT account
+- OpenAI Organization ID
+
+## First Name
+
+```text
+Fill manually.
+```
+
+## Last Name
+
+```text
+Fill manually.
+```
+
+## Email
+
+```text
+Fill manually with the email associated with the applicant's ChatGPT account.
+```
+
+## GitHub Username
+
+```text
+SalmonPlays
+```
+
+## GitHub Repository URL
+
+```text
+https://github.com/SalmonPlays/oss-signal
+```
+
+## Describe Your Role
+
+```text
+Primary maintainer
+```
+
+## Why This Repository Qualifies
+
+```text
+oss-signal is a public OSS maintainer tool for reducing triage and review load. It ships as npm package oss-signal@0.5.1 and GitHub Action SalmonPlays/oss-signal@v0.5.1, supports Markdown/JSON/SARIF/Issue output, passes CI/CodeQL, and has public field-audit issues/PRs plus a separate workflow demo.
+```
+
+## Interest
+
+```text
+Codex Security
+API credits for my project
+```
+
+## OpenAI Organization ID
+
+```text
+Fill manually from https://platform.openai.com/settings/organization/general
+```
+
+## API Credit Use
+
+```text
+Use Codex/API credits to run repeatable public repository audits, draft focused maintainer PRs and issue summaries from reports, build organization-level maintainer-readiness inventories, improve release/Code Scanning automation, and keep every public follow-up behind human review before posting or opening PRs.
+```
+
+## Anything Else
+
+```text
+The project is early, so I am not overstating adoption. Current evidence includes npm 0.5.1, a published v0.5.1 release, a reusable GitHub Action, self-audit score 100/100, public CodeQL/CI, public field-audit PRs, and a separate public workflow run using SalmonPlays/oss-signal@v0.4.0 with a report artifact.
+```
+
+## Evidence Links
+
+- npm package: https://www.npmjs.com/package/oss-signal
+- GitHub Release v0.5.1: https://github.com/SalmonPlays/oss-signal/releases/tag/v0.5.1
+- Main repository health workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/repository-health.yml
+- Separate workflow demo repository: https://github.com/SalmonPlays/oss-signal-adoption-demo
+- Separate successful workflow run: https://github.com/SalmonPlays/oss-signal-adoption-demo/actions/runs/26862361229
+- Adoption evidence: https://github.com/SalmonPlays/oss-signal/blob/main/docs/adoption-evidence.md
+
+## Character Counts
+
+- Why this repository qualifies: 299/500
+- API credit use: 312/500
+- Anything else: 309/500

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.4.0
+      - uses: SalmonPlays/oss-signal@v0.5.1
         id: oss-signal
         with:
           fail-under: "80"

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

@@ -15,13 +15,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: SalmonPlays/oss-signal@v0.4.0
+      - uses: SalmonPlays/oss-signal@v0.5.1
         id: oss-signal
         with:
           fail-under: "80"
           output: oss-signal-report.md
           summary: "true"
-      - uses: SalmonPlays/oss-signal@v0.4.0
+      - uses: SalmonPlays/oss-signal@v0.5.1
         with:
           format: sarif
           output: oss-signal.sarif

package/docs/examples/github-issue-body.md

@@ -0,0 +1,37 @@
+# Maintainer Readiness Follow-Up
+
+oss-signal scored this repository **64/100 (D)**.
+
+Source: GitHub (platformatic/massimo@main)
+Generated: 2026-06-03T05:12:35.488Z
+
+## Scope
+
+This issue is limited to maintainer-readiness signals: documentation, contribution paths, CI, security reporting, and package hygiene. It does not claim there is a product-code bug.
+
+## Suggested Next Steps
+
+- [ ] **Security policy** (9 pts): Add SECURITY.md with supported versions, reporting instructions, and response expectations.
+- [ ] **Changelog** (6 pts): Keep CHANGELOG.md with dated release entries and migration notes.
+- [ ] **Issue templates** (5 pts): Add bug report and feature request templates under .github/ISSUE_TEMPLATE/.
+- [ ] **Pull request template** (5 pts): Add .github/PULL_REQUEST_TEMPLATE.md with a short checklist.
+- [ ] **Dependency update automation** (5 pts): Add .github/dependabot.yml for the package ecosystems used in the repository.
+- [ ] **Support policy** (4 pts): Add SUPPORT.md describing where to ask questions, what is in scope, and expected response times.
+- [ ] **Static security analysis** (4 pts): Add a CodeQL or equivalent security scanning workflow.
+
+## Why These Checks Matter
+
+- **Security policy**: Responsible disclosure needs a private, documented path.
+- **Changelog**: Users need a durable place to understand release impact.
+- **Issue templates**: Issue templates collect the facts maintainers need to reproduce and triage.
+- **Pull request template**: PR templates nudge contributors to include tests, docs, and review context.
+- **Dependency update automation**: Automated dependency updates reduce security and compatibility drift.
+- **Support policy**: Support boundaries help maintainers avoid turning every request into unpaid consulting.
+- **Static security analysis**: Static analysis finds common vulnerability patterns before releases.
+
+## Notes For Maintainers
+
+If any item is intentionally absent, documenting that decision is a valid outcome. Please close or edit this issue if it does not match the project's priorities.
+
+_Generated by oss-signal; review before posting._
+

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-03T02:26:40.233Z
+Generated: 2026-06-03T05:12:35.946Z
 
 Score: **100/100** (A)
 

package/docs/examples/self-audit.sarif

@@ -6,7 +6,7 @@
       "tool": {
         "driver": {
           "name": "oss-signal",
-          "semanticVersion": "0.4.0",
+          "semanticVersion": "0.5.1",
           "informationUri": "https://github.com/SalmonPlays/oss-signal",
           "rules": [
             {
@@ -400,7 +400,7 @@
         "score": 100,
         "grade": "A",
         "source": "local",
-        "generatedAt": "2026-06-03T02:26:40.315Z"
+        "generatedAt": "2026-06-03T05:12:33.963Z"
       }
     }
   ]

package/docs/maintainer-playbook.md

@@ -28,6 +28,12 @@ Use SARIF when the findings should appear in Code Scanning:
 oss-signal . --format sarif --output oss-signal.sarif
 ```
 
+Generate an issue body that can be reviewed and edited before posting:
+
+```bash
+oss-signal owner/repo --format issue --output owner-repo-issue.md
+```
+
 ## 2. Triage Findings
 
 Prioritize missing checks that reduce maintainer load:
@@ -48,6 +54,8 @@ For an issue, include:
 - Why it matters for maintainers.
 - One concrete proposed fix.
 
+`--format issue` generates that structure as a Markdown checklist. Review it before posting, remove anything that does not fit the repository, and keep the title specific to the missing maintainer-readiness signal.
+
 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.
@@ -57,7 +65,7 @@ The field-audit examples in [docs/outreach](outreach) show this pattern for publ
 Add the GitHub Action to keep the signal visible:
 
 ```yaml
-- uses: SalmonPlays/oss-signal@v0.4.0
+- uses: SalmonPlays/oss-signal@v0.5.1
   id: oss-signal
   with:
     fail-under: "80"
@@ -78,7 +86,7 @@ permissions:
 
 steps:
   - uses: actions/checkout@v4
-  - uses: SalmonPlays/oss-signal@v0.4.0
+  - uses: SalmonPlays/oss-signal@v0.5.1
     with:
       format: sarif
       output: oss-signal.sarif
@@ -94,7 +102,7 @@ See [docs/examples/github-code-scanning-workflow.yml](examples/github-code-scann
 
 Useful evidence for maintainers and reviewers:
 
-- A public workflow run that uses `SalmonPlays/oss-signal@v0.4.0`.
+- A public workflow run that uses `SalmonPlays/oss-signal@v0.5.1`.
 - 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.

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

@@ -0,0 +1,22 @@
+# oss-signal v0.5.0
+
+`oss-signal` v0.5.0 adds Issue-ready output for maintainers who want to turn a deterministic audit into a reviewed GitHub Issue body.
+
+## Changes
+
+- Added `--format issue` to the CLI.
+- Added `format: issue` support to the GitHub Action.
+- Added an issue-output example at `docs/examples/github-issue-body.md`.
+- Updated the maintainer playbook with audit-to-issue guidance.
+
+## Example
+
+```bash
+oss-signal owner/repo --format issue --output maintainer-follow-up.md
+```
+
+The generated Markdown includes the score, scope, missing maintainer-readiness checks, why each check matters, and a reminder to review before posting.
+
+## Maintainer Workflow
+
+This release strengthens the audit-to-triage workflow: run a public repository audit, generate a focused issue checklist, edit it for the repository's context, then post or turn it into a narrow PR only when the suggested changes are useful.

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

@@ -0,0 +1,22 @@
+# oss-signal v0.5.1
+
+`oss-signal` v0.5.1 publishes the Issue-ready maintainer workflow on a clean release tag.
+
+## Changes
+
+- Includes `--format issue` for generating human-reviewed GitHub Issue bodies from audit findings.
+- Includes `format: issue` support in the GitHub Action.
+- Includes the issue-output example at `docs/examples/github-issue-body.md`.
+- Guards automatic npm publishing behind an explicit `NPM_PUBLISH_ENABLED=true` repository variable.
+
+## Example
+
+```bash
+oss-signal owner/repo --format issue --output maintainer-follow-up.md
+```
+
+The generated Markdown includes the score, scope, missing maintainer-readiness checks, why each check matters, and a reminder to review before posting.
+
+## Maintainer Workflow
+
+Use this release to run a public repository audit, generate a focused issue checklist, edit it for the repository's context, then post or turn it into a narrow PR only when the suggested changes are useful.

package/docs/release-process.md

@@ -43,7 +43,7 @@ git push origin main --tags
 
 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).
+For example, `v0.5.1` uses [docs/release-notes/v0.5.1.md](release-notes/v0.5.1.md).
 
 ## npm Publish
 
@@ -55,7 +55,14 @@ 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.
+The tag-triggered [release workflow](../.github/workflows/release.yml) runs the same checks and verifies the package with `npm publish --dry-run`.
+
+It publishes with provenance only when both release controls are configured:
+
+- Repository secret `NPM_TOKEN` contains an npm automation token.
+- Repository variable `NPM_PUBLISH_ENABLED` is set to `true`.
+
+If either control is missing, the workflow prints a notice and stops after dry-run verification. This keeps tag verification useful when npm publishing is handled manually.
 
 ## Post-Release Verification
 

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-03T02:26:38.240Z
+Generated: 2026-06-03T05:12:34.292Z
 
 Score: **100/100** (A)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oss-signal",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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, renderSarif } from "./index.js";
+import { auditTarget, renderIssue, renderMarkdown, renderSarif } from "./index.js";
 
 const OUTPUT_DELIMITER = "oss_signal_output";
 
@@ -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", "sarif"].includes(format)) {
-    throw new Error("format must be markdown, json, or sarif");
+  if (!["markdown", "json", "sarif", "issue"].includes(format)) {
+    throw new Error("format must be markdown, json, sarif, or issue");
   }
 
   return {
@@ -64,6 +64,9 @@ function renderReport(report, format) {
   if (format === "sarif") {
     return renderSarif(report);
   }
+  if (format === "issue") {
+    return renderIssue(report);
+  }
   return renderMarkdown(report);
 }
 

package/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { promises as fs } from "node:fs";
-import { auditTarget, renderMarkdown, renderSarif, VERSION } from "./index.js";
+import { auditTarget, renderIssue, renderMarkdown, renderSarif, VERSION } from "./index.js";
 
 async function main(argv) {
   const options = parseArgs(argv);
@@ -85,8 +85,8 @@ function parseArgs(argv) {
   if (positionals.length === 1) {
     options.path = positionals[0];
   }
-  if (!["markdown", "json", "sarif"].includes(options.format)) {
-    throw new Error("--format must be markdown, json, or sarif");
+  if (!["markdown", "json", "sarif", "issue"].includes(options.format)) {
+    throw new Error("--format must be markdown, json, sarif, or issue");
   }
   return options;
 }
@@ -98,6 +98,9 @@ function renderReport(report, format) {
   if (format === "sarif") {
     return renderSarif(report);
   }
+  if (format === "issue") {
+    return renderIssue(report);
+  }
   return renderMarkdown(report);
 }
 
@@ -121,12 +124,13 @@ function helpText() {
   return `oss-signal audits open-source repository maintenance readiness.
 
 Usage:
-  oss-signal [path-or-github-url] [--format markdown|json|sarif] [--output file] [--fail-under score]
+  oss-signal [path-or-github-url] [--format markdown|json|sarif|issue] [--output file] [--fail-under score]
 
 Examples:
   oss-signal .
   oss-signal https://github.com/SalmonPlays/oss-signal
   oss-signal platformatic/massimo --format json
+  oss-signal owner/repo --format issue --output maintainer-follow-up.md
 
 Options:
   --format       Output format. Defaults to markdown.

package/src/index.js

@@ -2,7 +2,7 @@ import { promises as fs } from "node:fs";
 import https from "node:https";
 import path from "node:path";
 
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.1";
 
 const SARIF_RULE_LOCATIONS = {
   readme: "README.md",
@@ -294,6 +294,49 @@ export function renderMarkdown(report) {
   return `${lines.join("\n")}\n`;
 }
 
+export function renderIssue(report) {
+  const lines = [
+    "# Maintainer Readiness Follow-Up",
+    "",
+    `oss-signal scored this repository **${report.score}/100 (${report.grade})**.`,
+    "",
+    `Source: ${sourceSummary(report.source)}`,
+    `Generated: ${report.generatedAt}`,
+    "",
+    "## Scope",
+    "",
+    "This issue is limited to maintainer-readiness signals: documentation, contribution paths, CI, security reporting, and package hygiene. It does not claim there is a product-code bug.",
+    "",
+    "## Suggested Next Steps",
+    ""
+  ];
+
+  if (report.recommendations.length === 0) {
+    lines.push("No missing maintainer-readiness checks were found. Keep the report current as the repository evolves.");
+  } else {
+    for (const recommendation of report.recommendations) {
+      lines.push(`- [ ] **${recommendation.label}** (${recommendation.weight} pts): ${recommendation.fix}`);
+    }
+
+    lines.push("", "## Why These Checks Matter", "");
+    for (const recommendation of report.recommendations) {
+      lines.push(`- **${recommendation.label}**: ${recommendation.why}`);
+    }
+  }
+
+  lines.push(
+    "",
+    "## Notes For Maintainers",
+    "",
+    "If any item is intentionally absent, documenting that decision is a valid outcome. Please close or edit this issue if it does not match the project's priorities.",
+    "",
+    "_Generated by oss-signal; review before posting._",
+    ""
+  );
+
+  return `${lines.join("\n")}\n`;
+}
+
 export function renderSarif(report) {
   const rules = report.checks.map((check) => ({
     id: `oss-signal/${check.id}`,