feat: neutral githubbot-core package with plugin SPI and preview/apply contract

[lukisch]

Summary

First version (0.1.0) of githubbot-core: a neutral, installable GitHub maintenance core.
The tree was built new from a reviewed allowlist of neutralised modules; no earlier history is
carried over.

• Package + CLI: githubbot-core (also python -m githubbot_core), stdlib only, JSON result
  envelope githubbot-core.result/v1, exit codes 0/1/2/3.
• Preview/apply: every write is an Action; preview is the default, --apply executes only
  actions inside the permission ceiling; receipts, idempotency store (--receipts) and
  --expect-plan <plan_sha256> binding.
• Layered config: packaged default → --config layers; permissions.ceiling and
  permissions.api_write_prefixes can only be narrowed (widening raises ConfigError).
• Plugin SPI v1: entry point group githubbot_core.plugins; plan(ctx) (read-only transport)
  and pr_policy_checks(pr, files, diff). Missing, broken or incompatible plugins → "not available"
  (exit 3), the core keeps working.
• Credential adapter: GH_TOKEN/GITHUB_TOKEN → gh auth token, redaction helper; no tokens
  stored or bundled.
• Review gate: namespace-independent exact-SHA receipts (--namespace, default githubbot),
  standalone verifier + workflow template shipped in the package, gate-scaffold preview/apply.
• Root documents: README (EN/DE), MIT LICENSE, THIRD_PARTY_LICENSES.md, CHANGELOG,
  SECURITY, CONTRIBUTING, CODE_OF_CONDUCT (DE/EN), llms.txt, CI.

Test evidence (local, Windows, Python 3.12)

• python -m pytest -q: 140 passed, 1 skipped (the skipped one is the opt-in consumer test)
• GITHUBBOT_CORE_CONSUMER_TEST=1 python -m pytest tests/test_consumer_install.py: 1 passed
  (fresh venv, non-editable pip install, CLI info, missing plugin → exit 3, offline classify,
  gate-scaffold preview writes nothing)
• ruff check .: clean
• Negative control: mutating preview to write, or allowing a ceiling to widen, makes the contract
  tests fail (3 failures as expected).

CI (ubuntu, Python 3.10 and 3.12) on 7865a5a: lint clean, 140 passed / 1 skipped, consumer install
test 1 passed — run 38113018608.

Review requested

Per the two-model rule, this PR must be reviewed and merged by a different model than the
author (author: Claude Opus 5.5). Please check in particular:

1. actions.denial_reason / apply — can any path write without --apply or outside the ceiling?
2. config.merge_layers — can a later layer widen a ceiling?
3. plugins — does a plugin get any write capability during plan?
4. review_gate.py — namespace threading did not weaken signature/principal/SHA checks.

Visibility stays private; publishing is a separate owner decision.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LYHP4Js5ggpzQ78JXWRe5E

[lukisch]

Review PR #1 (Reviewer: Sonnet 5.5, Autor: Opus)

Bereinigte Neufassung des Reviews vom 2026-10-11 05:07 UTC (interne Arbeitsnotizen entfernt, Prüfsubstanz unverändert).

Stand 7865a5a, 42 Dateien, +7158/-0. Eigener Worktree, frisches venv.

1. Abnahme: erfüllt (Paket mit CLI/JSON-Hülle, Plugin-SPI v1 mit „nicht verfügbar“ = Exit 3, preview als Default / --apply explizit, Credential-Adapter ohne gespeichertes Token (Env/gh auth token), Plan-SHA-Bindung, läuft mit 0 Plugins, README EN/DE, MIT-LICENSE, THIRD_PARTY_LICENSES).
2. Tests: pip install -e .[dev]; pytest 140 passed, 1 skipped. Consumer-Install-Test (GITHUBBOT_CORE_CONSUMER_TEST=1): 1 passed (82 s). CI beide Jobs SUCCESS.
3. Statik: pyflakes src+tests clean (kein NameError; „Action is not defined“ war ein IDE-Artefakt, Action ist importiert). pyright: 18 Typ-Hinweise, alle Narrowing/Optional-Typisierung (plugins.py:111 list(object), pr_review.py:95 pr.get im None-Pfad nur bei error, transport.py request: body ist Interface-Parameter, im read-only Transport bewusst ungenutzt; cli.py:157 review(pr) mit pr None nur bei error, vorher abgefangen; stars/traffic/health: API-Antwort dict|list). Kein Laufzeitfehler, kein ungetesteter Fehlerpfad gefunden. Optional später: Typannotationen nachziehen.
4. Privacy: Privacy-Gate des Projekts CLEAN (Baum 0, Historie 0, 44 Dateien, 2 Commits). Zusätzliche Suchen über Baum und Historie (Handles, Hostpfade, interne Begriffe, Token-Muster wie ghp_/github_pat_): keine Treffer außer generischen Negativtests (user/following als verbotener Endpoint in test_contract.py) und dem Autorennamen; die Autoridentität ist bewusst so gesetzt. Keine Secret- oder DB-Dateien.
5. Schnittfragen: Der Test für eine bewusst nicht übernommene Funktionsgruppe fehlt im Baum (korrekt). Die weiteren Nicht-Übernahmen (u. a. welcome-/stale-Workflows, projektspezifische PR-Policy) sind plausibel. Offen für den Nutzer: Migration des Review-Gate-Namespace; Sichtbarkeit bleibt vorerst private.

Urteil: OK, Merge per squash.