dotslot 0.3.1

dotslot: let agents fill the blanks, and prove they touched nothing else.

Owner: `<./owner:____________>`   Status: `<./status~:____________>`

$ dotslot fill release.md --set owner=Adam --set status="ready for tag" -i
$ dotslot check release.md --git-base HEAD
release.md: fill-safe (2 slot(s) changed)

CLI · pre-commit · GitHub Action · MCP server (Claude Code, Cursor, aider)

· MIT · v0.3.0 · Spec · Experiments · Changelog

What it is

Mark the parts of a file that may change with <./________>. An agent or script fills those blanks and nothing else. dotslot check proves the diff touched only the blanks, and that each blank kept its width, so columns and line wraps stay put. It works in docs, configs and code comments.

A file with slots is fill-only. That turns "don't touch the rest" into a rule a machine can check.

Install

Install from PyPI:

pip install dotslot
dotslot --help

Requires Python 3.10+ and wcwidth.

Use

dotslot new notes --width 26 --lines 3 --comment '# '   # generate a slot or block
dotslot scan FILE                                         # list slots, widths, capacity
dotslot fill FILE --set name=value -i                     # fill in place, width kept
dotslot check FILE --git-base HEAD [--allow a,b]          # prove only slots changed
dotslot check FILE --git-base HEAD --ignore-whitespace    # ...ignoring trailing whitespace outside slots
dotslot repad FILE --base OLD -i                          # restore padding after a hand edit
dotslot fit FILE --targets 80,100,120                     # where will lines wrap?

Slot forms: <./______> (unnamed), <./owner:____> (named), <./status~:____> (ellipsis on overflow). In Markdown, put slots in backticks. Full grammar: SPEC.md.

Integrations

Setup for each agent: integrations/README.md.

pre-commit (run dotslot after formatters):

- repo: https://github.com/ao3575911/dotslot
  rev: v0.3.1
  hooks:
    - id: dotslot-check
    - id: dotslot-lint

GitHub Action:

- uses: actions/checkout@v5
  with: { fetch-depth: 0 }
- uses: ao3575911/dotslot@v0.3.1
  with: { files: "docs/**/*.md config/*.yaml", allow: "status,owner" }

Inputs: files (required), allow, base (default: the PR base SHA), ignore-whitespace, report (default dotslot-report.json). The step summary lists violations and the JSON report (one array, one entry per file). No matched files is a pass; a missing base revision is a failure.

Limits

dotslot is a check, not a sandbox. The comment finder is a heuristic until tree-sitter lands; formatters such as gofmt can move columns, so run dotslot after them; trailing whitespace counts as a change unless you pass --ignore-whitespace. See CHANGELOG.md for open items and PLAN.md for the roadmap.

Repository layout

• dotslot/: the package (CLI, MCP server).
• slot/, bin/slot: the v0.1 reference, kept only so experiments/run.sh reproduces findings (a)–(g). Not installed.
• tests/: 70 tests (12 v0.1, 33 v0.2, 25 v0.3 including the h1–h9 exit gate). Run pip install -e ".[test]" && pytest -q.
• experiments/: run.sh (a–g) and run_v02.sh (v02, h, i), with recorded output in out/.

Licence

MIT. See LICENSE. Releases are GPG-signed in CI and carry SHA256SUMS and build provenance; see RELEASING.md.