Freezing a Tool at Version One
An architecture defined by its refusals, orchestrate, never reimplement.
Context
An operator tool had replaced a single generator script that hardcoded file templates and re-derived rules the main system already enforced. It settled at five commands. Six more had been sketched, including variants of an existing command and a general diagnostic.
The question was not which commands to add. It was whether the tool should acquire the machinery that tools acquire, a command registry, auto-discovery, middleware, a base class, and whether it should own any rules of its own.
Decision
Freeze the command set, and define the tool by its refusals. No command registry, no auto-discovery, no middleware, no base class: those mechanisms manage coupling between many commands, and there are five that never reference one another. Orchestrate rather than reimplement, invoke the same script an operator would run by hand, so every heavy operation has exactly one implementation. And keep one authority for validation rules, reached by calling it rather than by copying it.
Options Weighed
- Build the sketched command variantsDeferred
Quality-of-life over a command that already works end to end. The right defaults are best chosen from repeated use of the existing flow rather than guessed before it has been used in anger.
- Wrap the existing backup and restore scriptsRejected
Adds a second entry point without adding capability.
- Add a general diagnostic commandRejected
The classic speculative command: it accumulates checks for failures nobody has hit, and each check is a guess about how the system breaks.
- Extract the shared logic into a package so the tool can import it in-processRejected
The cleaner-looking answer. It would have created a shared dependency on speculation, before a second consumer proved the logic was genuinely shared. Orchestration through a subprocess required no changes and preserved a single implementation.
- Freeze at five commands, with refusals recordedChosen
The cost of adding a command is one folder and one line, because nothing exists to manage coupling that is not there.
Consequences
- Adding a command costs one folder and one line. That property is the whole return on the refusals.
- The tool cannot validate on every keystroke, because validation is a call into the authority rather than a local copy of its rules. Accepted deliberately: the interactive hint is looser than the real rule, with a test pinning the looseness so nobody can later tighten it into a second, drifting copy.
- An invalid configuration shows blanks in the listing, because the summary comes from the validator and the validator prints only on success. The correct fix is named, have the authority emit a summary on failure, rather than adding a parser to the tool and creating a second interpretation.
- The boundary is drawn at removing a workspace directory and nothing else. Databases, volumes, backups and logs belong to deployment infrastructure; extending across that line would make the tool responsible for state it does not own and cannot verify.
- The invariant that keeps it honest: delete the tool tomorrow and every runtime behaviour still works. It is a faster way to do things that were always possible, never a place where behaviour lives.
Cost of Not Deciding
The sketched commands get built one at a time, each individually reasonable. The tool accumulates a registry to manage them, a configuration layer to feed them, and eventually a second interpretation of rules the authority already owns, at which point the two can disagree and nobody will notice until they do.
Rollback
Free. Nothing was built.
Evidence Required to Reopen
- A command is wanted repeatedly by someone who has already done the task by hand, so its shape is known rather than predicted.
- A second consumer proves the shared logic is genuinely shared, which is what the package extraction was declined for lacking.
- Never for symmetry with another tool.
Learned From
Derives From· 2
Related Knowledge· 1
Version History
- v1.0.0
Accepted. Command set frozen; six sketched commands deferred or rejected with reasons recorded.