Placeholders

A placeholder lets one writ do the same work on different inputs. You write the name in braces, and you give the value when you issue the writ.

mandate: "The failing test {failing_test} passes without breaking other tests."

invariants:
  - { layer: letter, untouched: "{failing_test_file}" }

satisfaction:
  all:
    - { layer: letter, run: "pytest {failing_test} -x -q", exit: 0 }

Issue the writ with a value for each name:

writ issue bug-fixer.yaml \
  --set failing_test=tests/test_sync.py::test_retry \
  --set failing_test_file=tests/test_sync.py

The name

A name starts with a letter or an underscore. After the first character, the name can contain letters, numbers, and underscores.

Where a placeholder works

A placeholder works in each text value of the writ. This includes the mandate, the path patterns, the shell command patterns, the clauses, and the commands of a satisfaction clause.

A placeholder does not work in a number, so you cannot write iterations: {count}.

Each name must have a value

The writ issue command stops with an error when a name has no value. The error names each name that has no value.

bind placeholders: no value for {failing_test_file}

This rule is deliberate. A placeholder with no value in a path pattern makes a grant that matches nothing, or a grant that matches too much.

Use a placeholder to narrow a grant

A placeholder makes a writ general and keeps each run exact. This writ gives permission to change one directory, and the person who issues the writ selects the directory:

grants:
  - edit: { paths: ["{package}/**"] }

invariants:
  - { layer: letter, no_edits_outside: ["{package}/**"] }

writ issue refactor.yaml --set package=src/sync

Each run then has the narrow authority that the run needs, and the file stays one file.