/suede-release-linter

name: suede-release-linter
description: "Suede AI skill that lints a local music or media release folder and scores it for release readiness: missing files, weak or malformed metadata, artwork and stem problems, split gaps, sample and rights blockers, unstated AI involvement, and platform-delivery issues, produced by a bundled offline script as a scored markdown and JSON report. Use when a creator has one or more release folders of tracks, artwork, and stems and wants to know what is missing before distributing, delivering, or handing it off; when metadata quality or a delivery rejection is the question; or when a release-readiness score is asked for. Reports what is present, missing, or unknown; never upgrades unknown to confirmed and never means legal clearance. NOT FOR: investigating the rights gaps the report surfaces or building the transfer package (use suede-rights-passport); a sync one-sheet (use suede-sync-packaging); a release rollout campaign (use suede-campaign-in-a-box)."

Release Metadata Linter

Gate policy

Every check and verdict here is advice to the user, not a control on the agent. Run the checks, report results honestly, and complete what the user asked. A failed gate changes the report, never the work. The one exception: a finding that risks data loss, credential exposure, a legal or rights violation, a payment mistake, or irreversible public damage. Pause, name the risk, give the options, and let the user choose.

Overview

Audit a music or media project folder and produce a practical release-readiness report. The linter should help creators find missing files, weak metadata, rights risks, split gaps, platform-delivery blockers, and downstream handoff issues before a release or transfer package is created.

**Core principle:** report what is present, missing, or unknown. Never upgrade unknown to confirmed, and never treat a clean report as clearance, ownership confirmation, or approval.

Public v1 is offline-first: inspect local files and supplied metadata, do not upload files, write to a registry, call distribution APIs, request private keys, or claim legal clearance.

Workflow

1. Identify the source folder or supplied files. 2. Ask for the output location if it is not obvious. 3. Read `references/lint-rules.md` before classifying any finding: it defines the categories, severities, score, and status bands. Do not assign severities from memory. 4. If working on a local folder, run `scripts/lint_release.py` to generate `release-lint-report.md` and `release-lint-report.json`. Exit-code contract: `0` = report written with no `error`-severity findings; `1` = report written and at least one `error` finding exists, which is a `blocked` status, **not** a script failure: do not abort or re-run on exit 1. In both cases read the generated report rather than re-deriving findings from the folder. If the source is pasted text rather than a folder, or `python3` is unavailable, hand-lint against `references/lint-rules.md`, produce the same report shape from `assets/release-lint-report.template.md`, and label the report text-only. 5. Read `references/fix-guidance.md` when turning findings into specific next actions. 6. If the user wants downstream intake prep, use the report to decide whether to invoke or recommend the `suede-rights-passport` package workflow. 7. Do not invent release metadata. Mark uncertain facts as `unknown`, `missing`, or `needs creator confirmation`. Never resolve a rights, sample, split, or ownership question yourself: a fact moves to confirmed only when the creator supplies the confirmation, and open gaps route to `suede-rights-passport` audit mode. 8. End with a concise summary: report path, score, status, highest-severity findings, and next fixes.

Quick Start

python3 /path/to/suede-release-linter/scripts/lint_release.py \
  /path/to/music-project \
  --output /path/to/release-lint-output

If the source folder contains a metadata file, pass it explicitly:

python3 /path/to/suede-release-linter/scripts/lint_release.py \
  /path/to/music-project \
  --metadata /path/to/music-project/metadata.json \
  --output /path/to/release-lint-output

Accepted metadata formats are JSON, YAML/YML when PyYAML is installed, and public-safe key=value text files. Do not point metadata at real `.env`, credential, wallet, or deployment config files.

Safety defaults:

• Hidden files, dependency folders, build outputs, caches, and secret-like files are skipped by default.
• Unrecognized file types are skipped unless `--include-other` is passed.
• Absolute local paths are redacted to share-safer names unless `--include-absolute-paths` is passed.
• Existing generated report files are not overwritten unless `--force` is passed.
• The output folder cannot be the same folder as the source or live inside it.
• YAML metadata requires PyYAML: `python3 -m pip install PyYAML`.

What To Check

Read each bundled reference at the moment it is needed, not up front:

• `references/lint-rules.md`: before classifying findings, or when hand-linting without the script: categories, severity levels, score, and status bands.
• `references/metadata-fields.md`: when metadata is missing, malformed, or being authored: recommended fields, accepted aliases, and confirmation values.
• `references/fix-guidance.md`: when turning findings into next actions or a fix plan.
• `references/passport-context.md`: when the user asks how the lint report relates to Suede AI review or the Suede Creator Passport.

The script writes:

• `release-lint-report.md`: human-readable report.
• `release-lint-report.json`: machine-readable findings.

Use the bundled assets when repairing or hand-writing reports:

• `assets/release-lint-report.template.md`
• `assets/release-lint-report.template.json`
• `assets/metadata.example.json`

Fixtures

Two synthetic release folders under `scripts/fixtures/` (all names and metadata fake: no real personal data) exis