gabion 0.1.5

Architectural linter that stabilizes loose parameters into structural bundles.

---

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

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.