Public surface sweeper

Release hygiene made visible.

Public Surface Sweeper is a Python CLI that checks a repository or local portfolio before publication for missing public files, unclear README handoff material, credential-like strings, release metadata, proof-packet readiness, and workspace delivery drift. It is a release-hygiene check, not a full security scanner or certification.

View repository Pilot overview

Current release

v0.1.3 is the verified public path.

GitHub release v0.1.3 and PyPI 0.1.3 are both recorded in the registry. Their wheel hashes differ and are tracked separately.

python -m pip install public-surface-sweeper==0.1.3
public-surface-sweeper <workspace> --workspace --json

First task

Check the delivery surface before publishing.

Run workspace mode when a portfolio or release area contains linked Git worktrees or generated public outputs. Version 0.1.3 recognizes linked worktrees and fails empty coverage by default, so a clean-looking empty pass is not accepted as success.

Boundary: this is release hygiene. It is not a security certification, exploit test, dependency vulnerability scan, or proof that a secret-shaped string is live.

Blocker

Missing public contract

The visitor cannot quickly identify who the tool serves, what the first command does, and what outcome proves it worked.

Action

Show one clean path

Add a minimal fixture, command example, expected output, and non-goals section. The fastest buyer path is one honest run.

Strength

Native market signal

The tool converts README quality, licensing, contribution posture, examples, and handoff clarity into scored evidence.

What it checks

Repository presentation surface

README command path and outcome language.
License, contribution, authorship, and governance files.
Example fixtures that make evaluation concrete.
Public release language that avoids overclaiming capability.

Sample output

{
  "repo": "sample-release-tool",
  "score": 72,
  "status": "needs-polish",
  "blockers": [
    "No expected-output example",
    "README does not name buyer/user action"
  ],
  "next_actions": [
    "Add one fixture-backed demo",
    "Add non-goals and safety boundary",
    "Add evidence receipt link"
  ]
}

Commercial use

Small utility, direct value

For employers, this shows disciplined release thinking. For clients, it becomes a pre-release cleanup check before publishing internal tools, open-source utilities, or AI-assisted code drops.

Mission fit

AI output needs an edge check

AI can produce code faster than teams can assess the surrounding evidence. This tool focuses where code becomes a claim: documentation, examples, boundaries, and proof that the release is safe to evaluate.