Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.


doc_revision: 58 reader_reintern: "Reader-only: re-intern if doc_revision changed since you last read this doc." doc_id: readme doc_role: readme doc_scope:

  • repo
  • overview
  • tooling doc_authority: informative doc_requires:
  • POLICY_SEED.md
  • glossary.md
  • AGENTS.md
  • CONTRIBUTING.md doc_reviewed_as_of: POLICY_SEED.md: 28 glossary.md: 13 AGENTS.md: 12 CONTRIBUTING.md: 69 doc_change_protocol: "POLICY_SEED.md §6" doc_erasure:
  • formatting
  • typos doc_owner: maintainer

Gabion

CI

Gabion is an architectural linter that stabilizes loose parameters into structural bundles. It discovers recurring argument groups in a Python codebase and guides their reification into dataclass-based Protocols.

This repo contains scaffolded infrastructure plus a prototype dataflow audit. Synthesis and refactoring exist as evolving prototypes and are intentionally conservative.

Why Gabion

  • Find implicit structure: detect “dataflow grammar” bundles that repeatedly travel together across function boundaries.
  • Refactor safely: promote bundles into explicit dataclass Protocols.
  • Govern meaning: enforce semantics via a normative glossary.

Status

  • CLI uses the LSP server as its semantic core.
  • Dataflow grammar audit is implemented (prototype).
  • Type-flow, constant-flow, and unused-argument smells are implemented (prototype).
  • Refactor engine can rewrite signatures/call sites for targeted functions (prototype).
  • Governance layer is active.

Versioning (pre-1.0)

Gabion is pre-1.0. Until a 1.0 release, minor version bumps (0.x) may include breaking changes; patch releases target fixes. Breaking changes will be called out in release notes.

Branching model

  • stage is the integration branch for routine pushes; CI runs on stage pushes.
  • main is protected and receives changes via PRs from stage.
  • Merges to main are regular merge commits (no squash or rebase).
  • stage accumulates changes and may include merge commits from main as it stays in sync.
  • next mirrors main (no unique commits) and is updated after main merges.
  • release mirrors next (no unique commits) and is updated only after test-v* succeeds.
  • Tags are cut via the release-tag workflow on next (test) and release (prod).
  • next and release are automation-only branches; mirror-next and promote-release keep them in sync.

Convergence checklist

Bottom-up convergence targets live in docs/sppf_checklist.md.

Governance addenda (optional)

See docs/doer_judge_witness.md for optional role framing.

Non-goals (for now)

  • Docflow is a repo-local convenience feature, not a Gabion product feature.
  • Public-API compatibility shims for refactors are not yet implemented.
  • Multi-language support is out of scope (Python-first).

Quick start

Install toolchain with mise (once):

mise install

Install from source (editable):

mise exec -- python -m pip install -e .

Dependencies are locked in requirements.lock (generated via uv). CI installs from the lockfile inside an explicit venv to prevent drift.

Install git hooks (optional):

scripts/install_hooks.sh

Commands below assume the package is installed (editable) or PYTHONPATH=src.

Run the dataflow grammar audit (strict defaults):

mise exec -- python -m gabion check

gabion check enforces violations even without --report output. Use --baseline path/to/baseline.txt to ratchet existing violations and --baseline-write to generate/update the baseline file.

Run the dataflow grammar audit (prototype):

mise exec -- python -m gabion dataflow-audit path/to/project

Repo defaults are driven by gabion.toml (see [dataflow]). By default, in/ (inspiration) is excluded from enforcement there. Use --synthesis-plan to emit a JSON plan and --synthesis-report to append a summary section to the Markdown report. Use --synthesis-protocols to emit dataclass stubs (prototype) for review, or add --synthesis-protocols-kind protocol for typing.Protocol stubs. Use --refactor-plan to append a per-bundle refactoring schedule and --refactor-plan-json to emit the JSON plan.

Generate protocol refactor edits (prototype):

mise exec -- python -m gabion refactor-protocol \
  --protocol-name BundleProtocol \
  --bundle a --bundle b \
  --target-path path/to/module.py \
  --target-function foo

Run audit + synthesis in one step (timestamped output under artifacts/synthesis):

mise exec -- python -m gabion synth path/to/project

Run the docflow audit (governance docs only):

mise exec -- python -m gabion docflow-audit

Note: docflow is a repo-local convenience feature. It is not a core Gabion capability and is not intended to generalize beyond this repository.

Generate a synthesis plan from a JSON payload (prototype scaffolding):

mise exec -- python -m gabion synthesis-plan --input path/to/payload.json --output plan.json

Example payload:

{
  "bundles": [
    { "bundle": ["ctx", "config"], "tier": 2 }
  ],
  "field_types": {
    "ctx": "Context",
    "config": "Config"
  }
}

Payload schema: docs/synthesis_payload.md.

Capture an audit snapshot (reports + DOT graph under artifacts/):

scripts/audit_snapshot.sh

Snapshots now include a synthesis plan JSON and protocol stub file. Show the latest snapshot paths:

scripts/latest_snapshot.sh

Editor integration

The VS Code extension stub lives in extensions/vscode and launches the Gabion LSP server over stdio. It is a thin wrapper only.

Quick commands (make)

make bootstrap
make check
make check-ci
make test
make test-logs
make clean-artifacts
make docflow
make dataflow
make lsp-smoke
make audit-snapshot
make audit-latest

CI

GitHub-hosted CI runs gabion check, docflow audit, and pytest using mise as defined in .github/workflows/ci.yml. If POLICY_GITHUB_TOKEN is set, the posture check also runs on pushes.

Allow-listed actions are defined in docs/allowed_actions.txt.

Pull requests also get a dataflow-grammar report artifact (and a comment on same-repo PRs) via .github/workflows/pr-dataflow-grammar.yml.

GitHub Action (redistributable)

A composite action wrapper lives at .github/actions/gabion. It installs Gabion via pip and runs gabion check (or another subcommand). See .github/actions/gabion/README.md for usage and pinning guidance. Example workflow (with pinned SHA placeholders): docs/workflows/gabion_action_example.yml. Pinning guide: docs/pinning_actions.md.

Architecture (planned shape)

  • LSP-first: the language server is the semantic core; the CLI is a thin LSP client. Editor integrations remain thin wrappers over the same server. The server is the single source of truth for diagnostics and code actions.
  • Analysis: import resolution, alias-aware identity tracking, fixed-point bundle propagation, and tiering. Type-flow, constant-flow, and unused-argument audits are part of the prototype coverage.
  • Reports: Mermaid/DOT graph outputs and a violations list from the audit.
  • Synthesis: Protocol generation, bundle-merge heuristics, and refactoring assistance (callee-first/topological schedule).

See in/ for design notes and the prototype audit script.

Governance

This repository is governed by two co-equal contracts:

  • POLICY_SEED.md (execution and CI safety)
  • glossary.md (semantic meanings and commutation obligations)

LLM/agent behavior is governed by AGENTS.md.

Cross-references

  • CONTRIBUTING.md defines workflow guardrails and dataflow grammar rules.
  • AGENTS.md defines LLM/agent obligations.
  • POLICY_SEED.md defines execution and CI safety constraints.
  • glossary.md defines semantic meanings, axes, and commutation obligations.

License

Apache-2.0. See LICENSE.

Metadata

Release files for gabion 0.1.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for gabion 0.1.5
File Size Uploaded Provenance Actions
gabion-0.1.5.tar.gz 203.4 kB With provenance Details for gabion-0.1.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gabion 0.1.5
File Interpreter ABI Platform Actions
gabion-0.1.5-py3-none-any.whl Python 3 none any Details for gabion-0.1.5-py3-none-any.whl

Total release size: 262.8 kB

Release files / gabion-0.1.5.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL gabion-0.1.5.tar.gz
Size 203.4 kB
Tags Source
SHA-256 checksum
How to use checksums
b9512fc2701294be12cd4506c1e61cc8a6079b11a8abec9fd8d317b111b9f62f
BLAKE2b-256 checksum
How to use checksums
0e8c78dec3c39c44c34329159f3de76f3fc86a7e2b55d8a0c81566c4a9402a22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.11

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 3, 2026.

Transparency log

Release files / gabion-0.1.5-py3-none-any.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL gabion-0.1.5-py3-none-any.whl
Size 59.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
728584f3cd559f56cbe472366eb45ca361ec49d49c707d65fe72abaedf68f298
BLAKE2b-256 checksum
How to use checksums
1fb6b16a31cc6dafd515f051c2007b9dc1d683bf1365363a88900fdc5213b7d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.11

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 3, 2026.

Transparency log

Security for gabion 0.1.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Change of provenance

The configuration that created this release differs from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for gabion-0.1.5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page