dotslot 0.2.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.2.1 · 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 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

pre-commit:

- repo: https://github.com/ao3575911/dotslot
  rev: v0.2.1
  hooks: [{ id: dotslot-check }]

GitHub Action:

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

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. See CHANGELOG.md for open items and PLAN.md for the roadmap.

Repository layout

• dotslot/: the v0.2 package (CLI, MCP server).
• slot/, bin/slot: the v0.1 reference, kept only so experiments/run.sh reproduces findings (a)–(g). Not installed.
• tests/: 45 tests (12 v0.1, 33 v0.2). 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.