AI coding assistants have become a normal part of how software gets written. They read a repository, change files and run the checks that come with it. Until now a Clarive configuration gave them little to work with. It lived in a database and was edited through the browser, one dialog at a time.
Clarive 7.22 changes that. As the first post in this series described, cla export writes an installation's rules, resources, projects, roles, users and groups as HCL files. Put in a Git repository, those files are the same kind of material an assistant already works on every day.
This last post in the series is about what that makes possible, and about the parts of the design that keep a person in charge of what reaches an installation.
Something an assistant can read
The files were written for people. The same things help a model. Objects point at each other by address, like generic_server.web01 or role.deploy-manager, so a reference carries its meaning with it and needs no lookup in a database the assistant can't see. Values left at their defaults are omitted, so a step shows only what somebody chose. Every rule has its own file named after its address.
That covers the requests people make of an assistant most often. Adding a logging step to each pipeline that deploys to PROD starts with finding those pipelines, and one grep over the rule files does that, as the post on rules showed. Moving every step that runs on one server to another is a change to one address in each place it appears. A new role can be drafted by copying an existing one and changing its grant blocks.
Each of those ends as a change to text files. It can be reviewed as a diff before anything else happens.
A file is data
HCL is best known from Terraform, where a file can compute values with variables, conditions and loops. An assistant that has read a lot of Terraform will reach for those habits. Clarive's HCL refuses all of them. It evaluates nothing. In the documentation's words, "a file is data, and the only transformation between the text and the database is a name lookup."
The refusals come with directions. An index like foo.bar[0] is refused with a message to "reference Clarive objects by address instead." A splat like foo.bar.* gets "list every reference explicitly." Conditionals, arithmetic, for expressions and dynamic blocks are refused too, each with a message naming the construct. The whole function library is b64() and enc(), for secrets. A string holding ${job_dir} is kept as those exact characters, because it belongs to the rule and HCL doesn't interpret it.
For a person reviewing an assistant's work, that matters more than anything else in the format. What the file holds is what will be stored. There is no second step where a loop expands or a condition picks a branch, so the diff under review is the whole change.
Errors it can act on
An assistant improves a change the way a programmer does. It runs a check, reads the errors and tries again. The HCL tools suit that loop.
Every problem in a file is reported with the file, line and column it was found at, a severity and a stable code, followed by the line itself and a caret under the spot. This is the documentation's example:
foo.hcl:2:9: error[HCL017]: Bare identifier 'bar' used as a value -- did you mean the string "bar" or a reference like resource.<class>.<name>?
2 | run = bar
| ^Codes are never reused for a different meaning, so the diagnostics reference stays a reliable place to look one up. An error inside one block doesn't stop the parser from reading the rest, so a single run reports every independent problem instead of one per attempt.
Two commands check a change without writing anything. cla fmt --check reports any file that isn't in the canonical form cla export writes, so an assistant's edits end up formatted exactly as the rest of the repository. cla import-plan reads the files against an installation and exits with 2 if they couldn't be imported, because of a reference to an object that doesn't exist or an object declared twice.
Rules get one more check when they are imported. Each is compiled first, and one that doesn't build is refused. Before anyone starts editing an installation's rules as text, whether a person or a model, cla rule-check confirms that each existing rule comes back the same through HCL.
A person still decides
Nothing an assistant writes changes an installation by itself. The files have to be imported, and cla import prints its plan and asks before it writes anything. The answer defaults to no.
cla import-plan --out saves the same plan as JSON, which a reviewer can read line by line before anyone runs the import. That review is where a person checks that the change does what was asked and nothing more.
We'd recommend two habits when an assistant is involved. The first is to keep the confirming step with a person and leave -y out of any command an assistant is allowed to run, because the flag skips the one question that stands between a file and a live installation.
The second is to export with --secret omit. The default b64 form is an encoding that anyone holding the file can read, and a model with the file in its context is holding it. With omit, the files carry no credentials at all, and an import keeps the ones each installation already has. The post on servers and permissions covers the secret modes in detail.
The browser works the same way at a smaller scale. A step an assistant has rewritten can be pasted into the HCL tab of that step's dialog, and Apply checks it before it becomes part of the rule. The rule is stored only when someone saves it, as the post on the interface described.
What the files cover today
Resources, projects and their variables, rules, roles, users and user groups are all written as HCL. Topics are covered in part. cla export --topics takes the names of categories whose topics hold configuration, such as settings or deployment windows, and writes their titles, statuses and fields. The categories themselves have to exist already on the installation receiving them. Fuller support for topics is on the way.
Six kinds of object can be referred to by address but not yet written as files. They are categories, dashboards, kanban boards, notifications, calendars and schedules. A role can already be limited to one category with category.release, which is looked up by name on import. The category itself stays in the browser for now.
That leaves most of what people change from day to day in a form an assistant can read and a reviewer can check. The HCL overview is the place to start, and the diagnostics page is worth keeping open beside any session with an assistant. If you'd like to see how an assistant handles your own configuration, get in touch.