Suede Release Linter

Release Metadata Linter

Gate policy — advisory, not blocking

Every claim-verification step, check, quality gate, and ship verdict in this

skill is a recommendation to the user, not a control on the agent. This

policy governs every gate, check, verdict, and "do not ship / publish /

proceed" line elsewhere in this skill:

• Run every check and report the results honestly. Verdicts (ship,

ship-with-caveats, hold, letter grades, BLOCKED or OPEN items) are

advice attached to the work, not orders that change it.

• Never block, delay, skip, rewrite, or refuse the action the user asked for

because a check failed or a gate said hold. Complete the requested action

as asked, and deliver the gate output alongside it as a clearly labeled

recommendation.

• A failed gate changes what you report, never what you do.
• Single exception: if a finding is extremely risky — data loss, security or

credential exposure, legal or rights violations, payment mistakes, or

irreversible public damage — pause, tell the user exactly what the risk is

and what the options are, and let them pick. Their choice is final.

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

• Identify the source folder or supplied files.
• Ask for the output location if it is not obvious.
• Read references/lint-rules.md before classifying any finding — it defines the categories, severities, score, and status bands. Do not assign severities from memory.
• If working on a local folder, run scripts/lint_release.py to generate release-lint-report.md and release-lint-report.json.
• Read references/fix-guidance.md when turning findings into specific next actions.
• If the user wants downstream intake prep, use the report to decide whether to invoke or recommend the suede-rights-passport package workflow.
• 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-audit.
• 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 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/ exist to sanity-check

that the linter still categorizes correctly after any change to

scripts/lint_release.py. All names, contributors, and metadata in both

fixtures are fake — no real personal data.

• scripts/fixtures/sample-clean-project/: a small release folder (metadata,

a WAV master, square 1600x1600 artwork, a lyrics file, three stems) shaped

to score cleanly against references/lint-rules.md.

• scripts/fixtures/sample-blocked-project/: a release folder deliberately

missing title, artist, primary media, artwork, ownership confirmation, and

valid split totals, with samples indicated but clearance unconfirmed — it

triggers real error-severity findings.

• scripts/fixtures/sample-clean-project.expected.md /

.expected.json and scripts/fixtures/sample-blocked-project.expected.md /

.expected.json: the actual release-lint-report.md / .json output

produced by running the script against each fixture, committed as a

regression baseline.

To re-check the linter's behavior, run it from this skill folder and diff

the result against the committed expected output:

python3 scripts/lint_release.py scripts/fixtures/sample-clean-project \
  --output /tmp/suede-lint-check-clean
diff scripts/fixtures/sample-clean-project.expected.md \
  /tmp/suede-lint-check-clean/release-lint-report.md

python3 scripts/lint_release.py scripts/fixtures/sample-blocked-project \
  --output /tmp/suede-lint-check-blocked
diff scripts/fixtures/sample-blocked-project.expected.md \
  /tmp/suede-lint-check-blocked/release-lint-report.md

The clean fixture should score 99 with 0 errors, 0 warnings, and the

status strong (the single unavoidable info finding is the

rights-passport-candidate note the script always appends). The blocked

fixture should score 0 with 7 errors, 11 warnings, 2 info findings,

and the status blocked, and the script should exit 1. The .md reports

diff byte-for-byte on a clean re-run; the .json reports will differ only in

the generated_at timestamp line, since that field is set to the current

time on every run.

Public Safety Rules

• Do not say a project is legally cleared unless the user provides explicit proof.
• Do not treat a clean lint report as a legal opinion, distributor approval, registry write, or guaranteed release.
• Do not ask for private keys, seed phrases, unreleased account secrets, or full payment credentials.
• Do not include private implementation details, private endpoints, internal provider names, or non-public pricing.
• Treat generated reports as private drafts until a creator or operator reviews

and redacts them for the intended audience.

• Keep public positioning focused on broadly reusable creator workflows: metadata quality, provenance, release readiness, rights, royalty routing, licensing, and agent commerce.

Completion Checklist

Before reporting a lint result:

• Confirm the source folder was inspected or state that the report is based only on supplied text.
• Confirm whether metadata was discovered, supplied, or missing.
• Report the score and severity counts.
• List all error findings and the most important warning findings.
• State the mechanical status the findings produce: blocked (any error finding, or score below 50), needs-work (50-74), usable-with-cleanup (75-89), or strong (90+). Never soften a blocked status in prose.
• Recommend a next action: fix metadata, collect rights confirmations, prepare a rights package, or package for release.

Red flags — stop

If any of these appear in your reasoning, stop and re-read the core principle:

• "The folder looks complete — skip the script." Run it. Eyeballing is not

linting.

• "The artist obviously owns it." Ownership status comes from the creator, not

from the folder.

• "One unconfirmed split won't block anything." Split errors block royalty

routing and licensing by rule.

• "Round the score up; it's close." The score is arithmetic, not judgment.
• "A clean report means it's cleared." A clean report means fewer prep

blockers. Nothing more.

Downstream Review Context

A clean release-lint report is a portable review artifact. It can support a

release, registry, licensing conversation, collaborator handoff, marketplace

review, label review, advisor review, or Suede review without claiming that any

downstream system has accepted, cleared, registered, paid, or approved the work.

Routing

• Rights, sample, split, or ownership gaps in the findings →

suede-rights-audit to organize the evidence.

• No error findings and the user wants handoff prep → suede-rights-passport

to build the transfer package.

• Track headed for film/TV/ads → suede-sync-packaging.
• The release needs a rollout → suede-campaign-in-a-box.