dotslot

Let agents fill the blanks in a file, and prove they touched nothing else.

· MIT · Spec · Changelog

Mark the editable parts of a file with fixed-width slots. An agent or script fills them; dotslot check proves the diff changed only the slots and that each slot kept its width, so columns and wraps stay put. Works in Markdown, config files and code comments.

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)

Install

Use

dotslot new owner --width 12                  # print a correctly sized slot
dotslot scan FILE                             # list slots, widths, capacity
dotslot fill FILE --set owner=Adam -i         # fill in place; width kept
dotslot check FILE --git-base HEAD            # prove only slots changed (--allow a,b to narrow)
dotslot check FILE --base OLD --ignore-whitespace
dotslot repad FILE --base OLD -i              # restore padding an editor dropped
dotslot migrate FILE -i                       # convert v0.1 `=` slots
dotslot fit FILE --targets 80,100,120         # where lines will wrap
dotslot fit FILE --fail-at 100                # exit 1 if any line is wider

Slot forms: <./______> unnamed, <./owner:____> named, <./status~:____> ellipsis on overflow (! error, + grow). In Markdown, keep slots in backticks. Grammar: SPEC.md. Values with control, bidi or zero-width characters are rejected; pass --allow-unsafe-chars to permit them. Headers like <./:___> or <./a b:__> are errors. Exit codes: 0 ok, 1 violation, 2 usage or input error.

GitHub Action

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

Inputs: files (required), allow, base (default: PR base SHA), ignore-whitespace, report (default dotslot-report.json). Violations and the JSON report go to the step summary. No matched files passes; a missing base revision fails.

pre-commit

Run after formatters.

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

Agents (MCP)

dotslot-mcp serves dotslot_scan, dotslot_fill and dotslot_check over stdio. Arguments are schema-validated before any write, bad JSON gets a -32700 reply, dry_run returns a diff, allow limits which slots may change, writes are atomic and confined to --root. Ready-made setups: Claude Code, Cursor, aider, and an AGENTS.md snippet. See integrations/README.md.

Limits

dotslot is a check, not a sandbox. Without dotslot[treesitter], comment detection is a line heuristic. Formatters such as gofmt can move columns, so run dotslot after them. Trailing whitespace counts as a change unless you pass --ignore-whitespace. Roadmap: PLAN.md.

Development

pip install -e ".[test]" && pytest -q runs the Python tests and the shared conformance fixtures; npm test in npm/ and vscode/ runs the others. slot/ and bin/slot are the v0.1 reference, kept for EXPERIMENTS.md; not installed.

Licence

MIT. Releases are GPG-signed in CI with SHA256SUMS and build provenance; see RELEASING.md and SECURITY.md.