patchrail 0.1.0__tar.gz

patchrail-0.1.0/.agents/skills/patchrail-ci-triage/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: patchrail-ci-triage
+description: Use when a PatchRail CI classifier, CI fixture, or failed CI log needs root-cause analysis, evidence extraction, or regression coverage.
+---
+
+# PatchRail CI Triage
+
+PatchRail CI triage is local-first. Produce evidence and reviewable suggestions;
+do not perform write actions.
+
+## Workflow
+
+1. Inspect the failing log or sanitized fixture.
+2. Identify the smallest root-cause category that explains the failure.
+3. Check whether an existing fixture already covers the pattern.
+4. If classifier logic changes, add or update a fixture and expected metadata.
+5. Run the focused classifier tests and the public benchmark.
+6. Summarize evidence lines, confidence, changed files, and commands run.
+
+## Required Checks
+
+```bash
+uv run --extra dev pytest -q
+uv run --extra dev ruff check .
+uv run --extra dev patchrail ci benchmark examples/ci-triage --format json
+```
+
+## Safety
+
+- Do not quote raw logs that may contain secrets.
+- Redact logs before sharing fixtures or report excerpts.
+- Do not send logs to external services unless the maintainer explicitly opts in.
+- Do not open pull requests or comment on third-party repositories automatically.

patchrail-0.1.0/.agents/skills/patchrail-release-captain/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: patchrail-release-captain
+description: Use when preparing a PatchRail release, changelog update, package build, release evidence page, or release notes draft.
+---
+
+# PatchRail Release Captain
+
+Prepare release evidence. Do not publish packages, create tags, or announce
+releases unless the maintainer explicitly asks for that external action.
+
+## Workflow
+
+1. Read `docs/release-process.md`.
+2. Check `pyproject.toml`, `CHANGELOG.md`, README quickstart, docs links, and
+   release evidence pages for drift.
+3. Build sdist and wheel.
+4. Run package checks and a clean wheel smoke install.
+5. Update release evidence with exact command results.
+6. Leave any remaining publish steps as explicit maintainer gates.
+
+## Required Checks
+
+```bash
+uv run --extra dev pytest -q
+uv run --extra dev ruff check .
+uv run --extra dev ruff format --check .
+uv run --extra dev python -m build
+uv run --extra dev twine check dist/*
+```
+
+## Safety
+
+- Do not publish to PyPI without an explicit maintainer release request.
+- Do not create or push release tags unless requested.
+- Do not invent download, adoption, or CI metrics.
+- Keep release notes focused on verified behavior.

patchrail-0.1.0/.agents/skills/patchrail-review-guardrails/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: patchrail-review-guardrails
+description: Use when reviewing changes that affect network access, GitHub write actions, funded issue discovery, log redaction, local queue approvals, or agent workflows.
+---
+
+# PatchRail Review Guardrails
+
+Review PatchRail changes for maintainer control, local-first behavior, and
+anti-abuse boundaries.
+
+## P0 Findings
+
+Flag a P0 if a change introduces any of these:
+
+- unredacted log export;
+- external model calls without explicit opt-in;
+- network access without a clear opt-in flag;
+- automatic bounty or funded-issue claiming;
+- mass comments or automatic issue replies;
+- automatic pull requests to third-party repositories;
+- GitHub write actions without dry-run and human approval;
+- queue approvals that execute code or grant write permissions by themselves.
+
+## Review Flow
+
+1. Inspect the diff and affected docs.
+2. Check whether new commands preserve `--format json` or equivalent
+   machine-readable output when relevant.
+3. Verify docs state the human approval boundary.
+4. Run focused tests, then the public workflow tests.
+5. Report findings before summaries, with file and line references when
+   available.
+
+## Required Checks
+
+```bash
+uv run --extra dev pytest -q tests/test_public_workflows.py
+uv run --extra dev ruff check .
+```

patchrail-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.pkg-smoke/
+.patchrail-release-smoke/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+*.pyc
+.patchrail-demo/

patchrail-0.1.0/ADOPTERS.md

@@ -0,0 +1,37 @@
+# PatchRail Adopters
+
+PatchRail lists external adopters only with explicit maintainer permission.
+Please do not add private repositories, customer names, or unapproved pilot
+details.
+
+## Current Status
+
+PatchRail is collecting first read-only maintainer pilots. There are no public external adopters listed yet.
+
+Use [examples/pilot-outcome](examples/pilot-outcome/README.md) as the safe
+shape for a pilot summary before requesting a public adopter listing.
+Use [docs/pilot-request-package.md](docs/pilot-request-package.md) for the
+consent checklist and public listing rules.
+
+## How To Be Listed
+
+Open an adopter report issue when you have run PatchRail on a repository you
+maintain or are authorized to test:
+
+- repository or organization name approved for public mention;
+- PatchRail version or commit used;
+- workflow used, such as CI triage, queue demo, or funded issue read-only scan;
+- safe outcome summary without raw logs, secrets, or private paths;
+- whether you permit PatchRail to list the repo here.
+
+Accepted entries should stay factual and short:
+
+```markdown
+- `owner/repo` - Used PatchRail CI triage on GitHub Actions logs; fixture PR pending.
+```
+
+## Privacy Boundary
+
+Do not submit raw CI logs, private repository names, usernames, email addresses,
+tokens, local home paths, customer names, or screenshots containing secrets.
+Use `patchrail redact` and review the output manually before sharing anything.

patchrail-0.1.0/AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+PatchRail is a local-first maintainer automation toolkit. The core safety rule
+is: produce evidence and reviewable suggestions; do not perform write actions
+without maintainer approval.
+
+## Setup
+
+```bash
+uv run --extra dev pytest -q
+uv run --extra dev ruff check .
+uv run --extra dev patchrail ci benchmark examples/ci-triage --format json
+```
+
+## Review guidelines
+
+- Treat possible secret leakage as P0.
+- Treat new network access without explicit opt-in as P0.
+- Treat repository write actions without dry-run and human approval as P0.
+- Treat missing fixtures for classifier changes as P1.
+- Treat documentation quickstart drift as P1.
+- Check that CLI examples still work.
+
+## Safety rules
+
+- Do not add automatic bounty claiming.
+- Do not add mass-commenting workflows.
+- Do not submit pull requests to third-party repositories automatically.
+- Do not send raw CI logs to external services unless explicitly requested.
+- Prefer local-first behavior.
+
+## CI classifier changes
+
+When changing classifier logic:
+
+1. Add or update a fixture.
+2. Add expected classification metadata.
+3. Run the relevant tests.
+4. Include evidence lines in the pull request description.
+
+## Release changes
+
+Do not publish packages, create tags, or push release commits unless a maintainer
+explicitly asks. Prepare release pull requests only.

patchrail-0.1.0/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+## 0.2.0 - draft
+
+- Added a permanent source-level blocklist to the funded-issues tracker:
+  owners manually verified as fake-bounty sources are dropped at the
+  `merge_into_store` choke point (counted as `blocked` in the merge summary)
+  and `purge_blocklisted_entries` removes any legacy entries -- `track` runs
+  the purge on every merge so existing stores self-heal. The list is code, not
+  config: removing an owner requires a reviewed change.
+- Added `funded-issues import-algora-board`, an offline parser for a locally
+  saved Algora organization bounty-board page (`https://algora.io/<org>/bounties`).
+  It extracts the funder-stated USD amount, GitHub issue reference, posting
+  age, and declared claim count per bounty, marks funding as `verified` with
+  the board as `evidence_url`, raises `contested_bounty` when declared claims
+  reach the competition threshold, and can merge the scored records straight
+  into a tracker store (`--store`). The page must be saved locally first: the
+  command performs no network access, and the payload reports how many open
+  bounties the server-rendered page did not include.
+- Added a read-only `assess_bounty_competition` signal to `funded-issues`
+  scoring that derives `contested_bounty` / `crowded_no_assignment` risk flags
+  from public competition metadata (competing PR count, distinct claimants,
+  comment volume, assignment), with curated `CONTESTED_HIGH_COMPETITION` /
+  `CROWDED_NO_CLEAR_OWNER` reason codes. Competition flags cost score and
+  confidence without forcing an automatic no-go.
+- Added `funded-issues competition`, a read-only batch command that scores
+  competition / noise-trap pressure across many bounties from public metadata
+  observations (JSON list or `{observations: [...]}`), sorts results
+  highest-pressure first, and summarizes high/elevated/low counts plus
+  contested/crowded totals. Backed by the pure `assess_competition_batch`
+  helper and an example observations fixture. Strictly read-only: no claims,
+  comments, or maintainer contact.
+- Added a read-only `assess_payout_effort` signal to `funded-issues` scoring
+  that compares a bounty's public funding amount against an effort estimate and
+  a target hourly-rate floor ($150/h default), deriving a
+  `payout_too_low_for_effort` risk flag with a curated
+  `PAYOUT_TOO_LOW_FOR_EFFORT` reason code. Levels are strong / marginal / low /
+  unknown / unverified_currency; the flag costs score without forcing an
+  automatic no-go, and non-USD funding is surfaced as unverified rather than
+  guessed.
+- Added `funded-issues payout-effort`, a read-only batch command that scores
+  payout-vs-effort across many bounties from observations (JSON list or
+  `{observations: [...]}`), sorts results worst-payout first, and summarizes
+  low/marginal/strong/unknown/unverified-currency counts plus an underpaid
+  total. Backed by the pure `assess_payout_effort_batch` helper and an example
+  observations fixture. Strictly read-only: no claims, comments, or maintainer
+  contact.
+- Added an offline owner-level `source_noise` heuristic to `funded-issues`: the
+  pure `assess_owner_source_noise` helper screens an owner's public metadata
+  (account age, public repos, followers, website, payout verifiability) plus its
+  near-identical-issue volume into `noise_flags`, flagging the owner when it
+  trips at least two strong signals. `apply_source_noise_to_store` stamps the
+  verdict onto store entries via a new `noise_flags` field that survives
+  merge/upsert and apply-recheck, and `track-status` / web metrics now report a
+  `tracked_total` / `noise_flagged` / `clean_active` breakdown instead of a
+  single inflated active count. Strictly read-only: no network, no third-party
+  writes.
+- Added `funded-issues apply-recheck`, a local-file-only command that applies
+  recheck observations (a JSON list, an `{observations: [...]}` object, or a
+  list of GitHub API issue objects) to a tracker store, transitioning entries
+  to closed / stale / active. Stale is derived from `updated_at` against a
+  `--stale-after-days` floor (default 45); `state_history` records only real
+  transitions, `--dry-run` reports without writing, and a second identical pass
+  is a no-op. Backed by the pure `apply_recheck_to_store` helper and the
+  `funded-issues-recheck-summary` schema. Strictly read-only: no claims,
+  comments, or maintainer contact.
+- Prepared the CI Janitor v0.2 evidence bundle around the 143-case fixture zoo,
+  `fixture-check`, read-only GitHub Actions triage artifact, maintainer pilot
+  guide, and public metrics/adopter surfaces.
+- Added .NET/NuGet/C# and xUnit fixture coverage for `dotnet restore`,
+  `dotnet build`, and `dotnet test` failure modes.
+- v0.2 remains a maintainer-gated release candidate until the maintainer
+  explicitly bumps `pyproject.toml`, tags the release, publishes package
+  artifacts, and records final CI/PyPI evidence.
+
+## 0.1.0 - 2026-06-02
+
+- Initial public CI Janitor snapshot.
+- Added `patchrail ci explain` and `patchrail ci classify`.
+- Added local Markdown, JSON, and text reports.
+- Added Apache-2.0 license and safety/ethics documentation.
+- Added fixture-backed tests, local benchmark command, and GitHub Actions CI.
+- Expanded the initial CI fixture zoo to 101 sanitized synthetic examples across
+  Python, Node, TypeScript, Go, Rust, and GitHub Actions failure modes.
+- Added a read-only GitHub Actions triage artifact workflow.
+- Added the experimental local Agent Control Plane queue with SQLite-backed
+  work items, approval states, audit export, CI result import, and proposal
+  records.
+- Added the experimental read-only `funded-issues` CLI over local metadata,
+  with safe-only filtering and explicit anti-abuse blocked actions.
+- Added permission-only adopter reporting and a public metrics tracker for
+  pilot outcomes, adoption signals, and Codex for open-source evidence gaps.
+- Added release-prep evidence docs, package smoke checks, and manual publish
+  gates. Release tags, PyPI publishing, GitHub Releases, and public
+  announcements remain maintainer actions.

patchrail-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+PatchRail follows the Contributor Covenant Code of Conduct, version 2.1.
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for
+everyone, regardless of age, body size, visible or invisible disability,
+ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance,
+race, caste, color, religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- demonstrating empathy and kindness toward other people;
+- being respectful of differing opinions, viewpoints, and experiences;
+- giving and gracefully accepting constructive feedback;
+- accepting responsibility and apologizing to those affected by mistakes;
+- focusing on what is best for the overall community.
+
+Examples of unacceptable behavior include harassment, trolling, insulting
+comments, public or private harassment, publishing others' private information,
+or other conduct that could reasonably be considered inappropriate.
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing standards of
+acceptable behavior and may remove, edit, or reject comments, commits, code,
+issues, and other contributions that are not aligned with this Code of Conduct.

patchrail-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Thanks for helping improve PatchRail.
+
+The easiest contribution is a sanitized CI failure fixture. If you are not sure
+where to start, open the [CI failure fixture issue template](.github/ISSUE_TEMPLATE/ci_failure_fixture.md)
+and include the smallest redacted log excerpt you can share. Maintainers who
+want to try PatchRail before contributing can follow the
+[maintainer pilot guide](docs/pilot-guide.md).
+
+## Sanitized fixture contribution path
+
+Use this path when you have a failed CI log and want to turn it into a public
+fixture:
+
+1. Save the raw log locally. Do not commit it.
+2. Redact the log with PatchRail:
+
+```bash
+patchrail redact --log failed-ci.log > failed-ci.redacted.log
+```
+
+3. Review `failed-ci.redacted.log` manually and remove anything PatchRail should
+   not publish: secrets, emails, private repo names, user names, customer names,
+   local home paths, and private URLs.
+4. Reduce the log to the shortest excerpt that still shows the root cause.
+5. Add the fixture and expected metadata under `examples/ci-triage/`.
+6. Run the fixture hygiene gate and benchmark:
+
+```bash
+patchrail ci fixture-check examples/ci-triage --format json
+patchrail ci benchmark examples/ci-triage --format json
+```
+
+7. Include the fixture-check result, benchmark result, and the useful evidence
+   lines in the issue or pull request.
+
+If a real log cannot be safely redacted, create a minimal synthetic fixture that
+preserves the error pattern without preserving private identifiers.
+
+## Adding a CI fixture
+
+1. Copy the smallest failing log excerpt that still shows the root cause.
+2. Redact secrets, emails, private repo names, user names, and local home paths.
+3. Add the fixture as `examples/ci-triage/<short-name>.log`.
+4. Add the expected metadata as `examples/ci-triage/<short-name>.expected.json`.
+5. Run the fixture hygiene gate, benchmark, and tests before opening a pull
+   request:
+
+```bash
+uv run --extra dev patchrail ci fixture-check examples/ci-triage --format json
+uv run --extra dev patchrail ci benchmark examples/ci-triage --format json
+uv run --extra dev pytest -q
+```
+
+Expected metadata files use this shape:
+
+```json
+{
+  "failure_class": "python_test_failure",
+  "minimum_confidence": 0.7
+}
+```
+
+## Pull request checklist
+
+- No secrets or raw private logs added.
+- `patchrail redact` was run first, or the fixture is synthetic.
+- `patchrail ci fixture-check examples/ci-triage --format json` passed.
+- `patchrail ci benchmark examples/ci-triage --format json` passed.
+- No new network access without explicit opt-in.
+- No new write action without human approval.
+- No bounty claiming or mass-commenting behavior.
+- CLI examples still work.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+uv run --extra dev pytest -q
+uv run --extra dev ruff check .
+uv run --extra dev ruff format --check .
+```

patchrail-0.1.0/ETHICS.md

@@ -0,0 +1,35 @@
+# PatchRail Ethics and Anti-Abuse Policy
+
+PatchRail exists to reduce open-source maintainer workload. It is not a tool for
+replacing maintainers, spamming projects, or extracting value from open-source
+communities.
+
+## Principles
+
+1. Maintainers stay in control.
+2. Local-first processing is the default.
+3. Write actions require explicit human approval.
+4. Logs may contain secrets and should be redacted before sharing.
+5. Funded issues are sustainability signals, not automation targets.
+
+## Non-goals
+
+PatchRail does not support:
+
+- automatic bounty claiming;
+- mass commenting on issues;
+- automatic pull request submission to third-party repositories;
+- scanning private repositories without permission;
+- bypassing platform limits or terms;
+- ranking work solely by funding amount.
+
+## Funded issue discovery
+
+PatchRail may later include read-only funded issue discovery. That feature is
+intended to help maintainers and contributors understand where maintenance work
+is funded. It must not be used to spam projects or submit low-quality work.
+
+## Reporting abuse
+
+If you see PatchRail being used abusively, please open a private security report
+or contact the maintainer.

patchrail-0.1.0/GOVERNANCE.md

@@ -0,0 +1,21 @@
+# Governance
+
+PatchRail is maintained by Pablo Guillén.
+
+## Maintainer responsibilities
+
+- Keep the default workflow local-first and human-approved.
+- Review changes that add network access, repository write actions, or workflow
+  automation with extra scrutiny.
+- Prefer small, test-backed classifier improvements.
+- Keep anti-abuse policy and security documentation current.
+
+## Contributor ladder
+
+1. Fixture contributor: contributes sanitized CI failure examples.
+2. Classifier contributor: adds rules with fixtures and tests.
+3. Workflow contributor: improves CLI, docs, or integration examples.
+4. Maintainer: reviews releases, security reports, and policy-sensitive changes.
+
+Maintainer status is granted manually after sustained, high-quality
+contributions.