Metadata-Version: 2.5
Name: vibey-gh
Version: 1.13.0
Summary: Provenance fingerprints, derived version bumps, a merge train, and branch realignment for a GitHub repository — with no dependencies.
Project-URL: Homepage, https://github.com/adammatthewsteinberger/vibey-gh
Project-URL: Repository, https://github.com/adammatthewsteinberger/vibey-gh
Project-URL: Issues, https://github.com/adammatthewsteinberger/vibey-gh/issues
Author-email: Adam Matthew Steinberger <adam@matthewsteinberger.com>
Maintainer-email: Adam Matthew Steinberger <adam@matthewsteinberger.com>
License: MIT License
        
        Copyright (c) 2026 Adam Matthew Steinberger
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
License-File: NOTICE.md
Keywords: ci,github,merge-train,provenance,release,versioning
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: isort>=5.12; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# vibey-gh

Release automation for a GitHub repository: provenance fingerprints, derived version
bumps, exact-head AI review and repair, a merge train, dual-channel releases, comprehensive
documentation maintenance, and post-release branch realignment.

**No dependencies.** Everything is stdlib. This runs in every CI job of every repository
that adopts it, so a dependency it grows is a dependency all of them grow.

## Why vibey-gh

GitHub can run tests, but a dependable open-source delivery system needs much more than a
green test job. It must intake branches, keep documentation honest, review outside work,
repair actionable failures without weakening gates, merge through protected branches,
derive versions, publish to the correct registry, create releases and packages, deploy
discoverable documentation, preserve provenance, and recover safely when a trusted
post-merge job fails. `vibey-gh` installs that complete event-driven path as one portable,
auditable contract.

Use it when you want `develop` to be the integration channel, `main` to be production,
and every transition between them to be reproducible and policy checked.

## Requirements

- Python 3.11 or newer, Git, and the GitHub CLI (`gh`).
- A GitHub repository with Actions enabled and Pages configured for Actions deployments.
- `ANTHROPIC_API_KEY` for AI review, repair, conflict resolution, and documentation upkeep.
- `AUTOMERGE_TOKEN` when the default Actions token cannot merge or manage repository settings.
- PyPI and TestPyPI trusted-publishing environments when Python publication is enabled.

The installed Python runtime has no third-party dependencies. Workflow-only tools are
pinned to immutable action revisions and run in GitHub-hosted jobs.

## Quick start

```bash
pip install vibey-gh
vibey-gh install
```

Commit the generated hooks, workflows, assets, and configuration; configure the required
secrets and publishing environments; then verify the complete installation:

```bash
vibey-gh check --ci
git status --short
```

Push a topic branch. Branch intake creates a draft PR, exact-head scans decide when it is
stable, and the event chain handles review, repair, merge, promotion, publication, docs,
tagging, GitHub Release creation, and repository-profile reconciliation.

## Architecture

Configuration value objects describe desired state; deterministic evaluators judge
versions, PRs, documentation, and interface parity; CLI adapters call those policies; and
rendered workflows provide the privileged GitHub edge. Managed templates are the source
of truth, and dogfood tests require this repository's installed copies to match them.
Every decision is tied to an exact commit SHA, and stale workflow events are ignored. See
[Architecture](docs/architecture.md), [Workflows](docs/workflows.md), and
[Threat model](docs/threat-model.md).

## Security model

Privileged jobs treat PR content, logs, model output, and repository instructions as
untrusted. They inspect or edit constrained files but never execute contributor-controlled
package managers, tests, builds, or scripts while write credentials are present. Ordinary
PR CI validates resulting commits. Managed automation never sends a deletion refspec for
`main` or `develop`, and automatic branch deletion stays disabled because `develop` is
itself the head of production promotion PRs. See [SECURITY.md](SECURITY.md).

## Commands

| Command | Human purpose |
|---|---|
| `vibey-gh install` | Install or update hooks, workflows, and release assets without discarding local hooks. |
| `vibey-gh check --ci` | Verify provenance, installation, documentation, marketplace, and interface parity. |
| `vibey-gh version --explain` | Explain the derived semantic-version decision. |
| `vibey-gh promote` | Open or reuse the asynchronous `develop → main` release PR. |
| `vibey-gh realign` | Align identical `develop` and `main` trees after a rebase merge. |
| `vibey-gh pr-automation evaluate` | Return the structured exact-head PR decision. |
| `vibey-gh merge-train --pr N` | Judge and merge one gated PR with the target's merge method. |
| `vibey-gh sdk`, `api`, `mcp`, `webhook` | Exercise capabilities through every public surface. |

Run `vibey-gh --help` and read [docs/cli.md](docs/cli.md) for the full reference.

`install` writes the git hooks and workflow files into your repository and points
`core.hooksPath` at them. A hook you already have is moved aside to `<name>.local` and
chained, never discarded — adopting this should not silently drop checks somebody thought
were important.

## What it does

### Provenance, enforced in two places

Every code change carries a fingerprint. Source files get a header comment; **every commit
gets a trailer**. The trailer is what makes the rule total — a change to a Markdown file or
a JSON manifest still arrives as a commit, and the commit is fingerprinted even when the
file cannot be.

```bash
vibey-gh check                 # are the hooks installed and the fingerprints intact?
vibey-gh check --apply         # add the missing file headers
vibey-gh check --commits main..HEAD    # and every commit trailer in a range
```

The `pre-push` hook refuses the push if either half is missing, to any branch, local or
remote. `git push --no-verify` still works, because a hook that cannot be bypassed in an
emergency gets uninstalled instead; CI applies the same rule server-side, so skipping it
locally defers the failure rather than avoiding it.

### Versions derived, not remembered

```bash
vibey-gh version --since origin/main --explain     # what should this release be?
vibey-gh version --since origin/main --apply       # write it to every version file
vibey-gh version --dev "$GITHUB_RUN_NUMBER"        # <release>.dev<n> for a TestPyPI build
```

| what changed | bump |
|---|---|
| a `content_path` | **minor** — users receive something new |
| only a `code_path` | **patch** — an internal fix |
| neither | **none** — docs and CI do not reach an installed user |
| the version already moved | **none** — a deliberate bump is in place; never double it |

`none` is a legitimate answer. This has to be automatic: a PyPI upload with
`skip-existing` turns an unbumped release into a green run that publishes nothing,
silently, with no warning anywhere. A human-maintained version is a silent-failure
generator.

Version files may be Python (`__version__ = "..."`), JSON (a `version` key, at the top
level or under `metadata`), or TOML (the `[project]` table — and only that table, because
`pyproject.toml` has others carrying a `version` key and bumping the wrong one is worse
than not bumping).

### The merge train

```bash
vibey-gh merge-train --dry-run
vibey-gh merge-train --method squash
```

The normal path is event-driven: the PR-automation gate dispatches
`vibey-gh merge-train --pr NUMBER` as soon as the exact current head is green. The weekly
and manual modes remain recovery backstops. A ready PR is open, current with its target,
conflict-free, green, free of requested changes, and carries a successful exact-head
`PR automation / gate` when an outside-author review is required.

Outside authors receive a fresh structured Claude review after scans pass. Findings feed
the same bounded repair loop as failed scans. Forks are never mutated with privileged
credentials; when a fork needs edits, automation preserves its exact head in a linked
repository-owned replacement PR.

### PR review and repair automation

`branch-intake.yml` opens exactly one draft PR when a new same-repository topic branch is
first pushed. It ignores the integration branch, release branch, and automation-owned fork
repair branches. Later pushes reuse the existing PR. Once the configured scans for the
exact draft head are complete and green, PR automation marks it ready and immediately
continues through review, repair, gating, and the merge train. Pending, failing, stale,
conflicting, closed, and fork draft heads are no-ops; they are never promoted prematurely.

`pr-automation.yml` reacts to configured scan-workflow completions, re-reads the entire
current-head check rollup, and publishes an explicit check run on that exact SHA. It waits
for pending scans, separates cancelled infrastructure from actionable failures, and allows
at most three repair commits per contributor lineage. A new contributor commit starts a
new lineage; bot repair pushes do not reset the counter.

Conflicting same-repository PRs enter a bounded conflict-resolution job instead of failing
permanently. The job materializes Git's exact unresolved path set without executing
repository code, gives the constrained agent read/search/edit access only, rejects edits
outside that set, rechecks the head SHA, and publishes one ordinary non-force resolution
commit. Fork conflicts continue through the repository-owned replacement-PR path. Conflict
attempts share the three-attempt repair budget, so an ambiguous merge cannot loop forever.

Review and repair use the immutable-pinned Claude Code Action with selected `vibey-skills`.
The privileged jobs may inspect source and CI logs but may not execute contributor package
managers, tests, builds, scripts, or binaries. Ordinary PR CI validates every repair push.
The agent has no Git mutation tool: one trusted publisher may push a non-empty source
(`HEAD:refs/heads/<exact-pr-branch>`) only to the exact PR branch. This deliberately
permits forward updates to `develop` or `main` when either is the PR head, while making a
Git deletion refspec (`:branch`) structurally impossible. Managed merges automatically
update `develop` and `main`, but no managed command uses `--delete`, `--delete-branch`, an
empty-source refspec, or a branch-deletion API.
Repositories must configure `ANTHROPIC_API_KEY`; `AUTOMERGE_TOKEN` is required where the
default Actions token cannot push or merge through the repository ruleset. Installation
does not create either secret.

```bash
vibey-gh pr-automation evaluate --pr 123 --head-sha HEAD_SHA
vibey-gh pr-automation ready-draft --pr 123 --head-sha HEAD_SHA
vibey-gh pr-automation mirror-fork --pr 123
vibey-gh merge-train --pr 123
```

### The promotion

```bash
vibey-gh promote --dry-run
vibey-gh promote
```

Moves the integration branch to the release branch, which is what publishes. Three things
it gets right that a hand-written workflow usually does not:

- **It compares by content, not by commit count.** The release branch is rebase-merged, so
  its commits are rewritten copies with different SHAs; the integration branch always looks
  "ahead" even when the trees are identical. A diff is the only honest test.
- **It derives the version before opening anything.** An upload with `skip-existing` turns
  an unbumped promotion into a green run that publishes nothing, silently.
- **It hands the PR to the same event gate as every other change.** `promote` no longer
  holds a runner open with `gh pr checks --watch`; scans, automated review, and the
  exact-head merge train finish the promotion asynchronously. `--wait` retains the legacy
  synchronous mode for recovery.

### Realignment

```bash
vibey-gh realign
```

When the release branch is rebase-merged its commits are rewritten copies with new SHAs,
so the integration branch's tip is never an ancestor of it and a fast-forward is
impossible — yet a ruleset with a strict up-to-date policy treats it as behind, which
blocks the next promotion.

The guard is **tree equality, not ancestry**: this runs only when a diff between the two
branches is empty, so it converges two identical contents onto one history and cannot
discard work. If the integration branch has anything the release branch does not, it is
left alone and says so.

## Configuration

```toml
[pr_automation]
enabled = true
scan_workflows = ["CI", "Provenance", "CodeQL", "Docs", "API drift (Cloud Agents OpenAPI)"]
ignored_checks = ["PR automation / gate", "gate", "Merge train / merge"]
max_repair_attempts = 3
model = "claude-sonnet-5"
review_untrusted_authors = true
repair_untrusted_authors = true
replace_fork_prs = true
retain_schedule_backstop = true

[github_release]
enabled = true
tag_prefix = "v"
generate_notes = true

[repository_profile]
enabled = true
description = "A configurable repository description"
topics = ["automation", "documentation", "github-actions"]
has_issues = true
has_projects = true
has_wiki = false
has_discussions = true
allow_squash_merge = true
allow_merge_commit = false
allow_rebase_merge = true
allow_auto_merge = true
delete_branch_on_merge = false
web_commit_signoff_required = true
vulnerability_alerts = true
automated_security_fixes = true

[documentation]
enabled = true
ai_maintenance = true
model = "claude-sonnet-5"
production_label = "Production"
preview_label = "Preview"
production_indexing = true
preview_indexing = false
generate_robots = true
generate_sitemap_index = true
generate_llms_txt = true
generate_llms_full_txt = true
generate_json_ld = true
```

### Comprehensive documentation and AI maintenance

The `Docs` workflow enforces the complete FOSS and multi-agent documentation contract on
every push and pull request. A scheduled or manually dispatched privileged maintenance job
then performs a repository-wide semantic refresh: it reads source, tests, configuration,
packaging, workflows, and releases; creates missing documentation; repairs stale claims;
and opens a guarded documentation PR. It never executes repository code in the privileged
job, never commits application changes, and never mutates a permanent branch directly.

The required suite includes `README`, changelog, license, conduct, contribution, security,
support, architecture, operations, testing, release, governance, accessibility, dependency,
threat-model, troubleshooting, ADR, GitHub, hooks, Claude, Cursor, Gemini, Codex/Agents, and
generic-agent documentation. The repository also contains a Claude-standard plugin
marketplace at `.claude-plugin/marketplace.json` with development, documentation,
release-security, and PR-automation plugins. Each plugin ships manifests, skills, commands,
specialist agents, and supporting references; `.claude/settings.json` registers and enables
the marketplace for project sessions.

The Pages build emits production and preview sitemaps, a root sitemap index, `robots.txt`,
`llms.txt`, `llms-full.txt`, canonical links, indexing policy, Open Graph/Twitter metadata,
Schema.org JSON-LD, and repository/revision provenance. Repository identity and URLs are
derived at build time, so adopting repositories never inherit `vibey-gh` metadata.

### Five-surface capability parity

Every canonical capability is exposed and tested through all five supported surfaces:

- Python SDK: `vibey_gh.surfaces.invoke(...)`
- CLI: the native command and the `sdk`, `api`, `mcp`, and `webhook` projections
- JSON API: `api_dispatch` and `/v1/capabilities/<name>`
- MCP: `initialize`, `tools/list`, and `tools/call`
- Webhook: HMAC-SHA256 authenticated, delivery-ID replay-safe dispatch

The parity contract enumerates every capability from one registry, invokes every adapter,
and fails CI if any surface is absent or divergent. Because `Docs` is a configured scan,
missing documentation or interface parity blocks the exact-head PR gate and enters the
bounded repair loop before merge.

After the configured `Release` workflow succeeds on `main`, the managed
`github-release.yml` workflow tags that exact commit and creates a generated-notes GitHub
Release. It is safe to rerun: an existing matching tag/release is reused, while an
existing tag at a different SHA is never moved and fails loudly.

The managed `release-surfaces.yml` workflow follows every successful release on either
branch. It builds two persistent ProperDocs sites under the repository's GitHub Pages
domain: `/develop/` is the test documentation released with TestPyPI, while `/main/` is
the production documentation released with PyPI. A small root page links both channels.
Because GitHub Pages has one deployment per repository, each run restores the latest
successful artifact for the other channel before deploying; one branch never erases the
other branch's site.

GitHub Packages does not provide a PyPI registry. The workflow therefore publishes the
exact wheel and source distribution from the successful `Release` run as an OCI artifact
at `ghcr.io/<owner>/<repository>/python`. Every artifact receives its immutable version
and `sha-<commit>` tags, plus `develop` for test releases or `main` and `latest` for
production releases. The normal TestPyPI and PyPI uploads remain authoritative and are
unchanged.

After release surfaces succeed, `repository-profile.yml` reconciles the repository's
description, topics, homepage, collaboration features, merge methods, automatic merge,
commit signoff, branch retention, vulnerability alerts, and automated security fixes.
An empty description derives
a repository-specific description from the consuming repository name. It verifies that
Pages, a GitHub Release, a deployment, and the OCI package really exist—the public API
does not expose fictional “show Releases/Deployments/Packages” switches. Profile updates
use `AUTOMERGE_TOKEN` when available and never create, update, push, or delete a branch.

If a trusted post-merge workflow fails on `develop` or `main`, `release-repair.yml`
reviews its logs with the same constrained agent used for PR repair. A fixable problem is
committed to a new `vibey-gh/repair/release-*` branch and returned through a normal PR,
where all checks and the merge train apply. It never pushes a repair directly to—and can
never delete—`develop` or `main`. Credential, billing, repository-setting, registry, and
other operator-only failures are reported with an explicit required action instead of
being disguised as code fixes.

Everything project-specific lives in `.vibey-gh.toml`, so the logic beside it stays
general. Every key has a default; a repository that agrees with them needs no file at all.

```toml
[fingerprint]
text    = "Made with love by ..."          # the source-header comment
trailer = "Made-With: ..."                 # the commit trailer
sources = ["src/**/*.py", ".github/workflows/*.yml"]

[version]
files         = ["pyproject.toml", "src/pkg/__init__.py"]
content_paths = ["plugins/"]               # a change here is a MINOR release
code_paths    = ["src/"]                   # a change here alone is a PATCH

[branches]
integration = "develop"
release     = "main"

[merge_train]
owner           = "your-login"
trusted_authors = ["your-login", "dependabot[bot]"]
```



## Workflows

| Workflow | Responsibility |
|---|---|
| Branch intake | Turns a new topic branch into one reusable draft PR. |
| CI / Provenance / Docs | Validate code, history, human docs, agent docs, plugins, and interfaces. |
| PR automation | Aggregates exact-head scans; reviews, repairs, resolves conflicts, and gates. |
| Merge train | Squash-merges into `develop` and rebase-merges promotions into `main`. |
| Release | Publishes `develop` dev builds to TestPyPI and `main` releases to PyPI. |
| GitHub Release | Tags the exact production commit and generates release notes. |
| Release surfaces | Publishes GHCR artifacts and Production/Preview ProperDocs sites. |
| Repository profile | Enforces repository metadata, policy settings, security, and public surfaces. |
| Release repair | Returns trusted post-merge fixes through an ordinary guarded PR. |

Scheduled and manual triggers are recovery backstops; normal delivery is event driven.

## Troubleshooting

- Empty Anthropic key: define `ANTHROPIC_API_KEY` as a repository secret, not only an
  environment secret, and confirm the privileged workflow can read it.
- Review-blocked promotion: verify the exact-head `PR automation / gate`; admin fallback
  is permitted only after all independent policy checks pass.
- Pages 404: select **GitHub Actions** as the Pages source and rerun Release surfaces.
- Repository profile failure: give `AUTOMERGE_TOKEN` the administration and security
  permissions required to reconcile the configured settings.
- Wrong package index: `develop` must select TestPyPI and `main` must select PyPI.

See [docs/troubleshooting.md](docs/troubleshooting.md) and [SUPPORT.md](SUPPORT.md); include
the workflow URL, exact SHA, and redacted failing-step output when asking for help.

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and
[AGENTS.md](AGENTS.md). Changes must preserve the dependency-free runtime, Python 3.11,
100% line and branch coverage, immutable action pins, provenance, and permanent-branch
non-deletion guarantee. Report vulnerabilities through [SECURITY.md](SECURITY.md), not a
public issue.

### Taking the hooks without the workflows

`install` writes the managed workflows alongside the hooks. A repository that already has richer
ones of its own can decline them:

```toml
[install]
workflows = []          # hooks and the CLI only
# workflows = ["provenance.yml"]   # or just the ones you want
```

This is not cosmetic. `check` verifies that everything it manages is present and current,
so without it a repository that deliberately keeps its own workflows would fail the check
forever — and a check that cannot pass is a check people route around.


`trusted_authors` is matched after normalising `app/name` and `name[bot]` to the same
thing. `gh` reports a bot author with the `app/` prefix while the rest of GitHub writes
`[bot]`; a literal allow-list matches whichever spelling it happens to contain and
silently distrusts the other, which once caused an automation to quarantine its own pull
request as an outside contribution.

## What is deliberately not fingerprinted

- **Files whose bytes are meaningful** — generated documents verified against a source,
  Markdown loaded into a model's context. A header would be a diff against the source.
- **Anything without comment syntax** — JSON, most notably.

The commit trailer covers both without touching them. A naive "comment in every changed
file" rule cannot express itself in JSON and corrupts content that is checked byte for
byte.

## Licence

MIT. See [LICENSE](LICENSE).

Made with ❤️ by [Vibey](https://adammatthewsteinberger.github.io/vibey/), Developed by [Adam Matthew Steinberger](https://hire.adam.matthewsteinberger.com/) ([@adammatthewsteinberger](https://github.com/adammatthewsteinberger/)).
