Inspiration
EVOTOOL began in a real inventory project where product revisions moved faster than document maintenance. Decisions were recorded, but their order, current meaning, and implementation status became increasingly difficult to reconstruct. A master log alone was not enough.
While separating process contracts from precise specification values—and using those constraints to guide an AI agent building HTML—a broader idea emerged: documents should preserve how decisions evolve, not only the latest wording.
For human–AI collaboration, this matters because an agent can produce confident but incorrect work when it starts from a missing, outdated, or duplicated source of truth.
What it does
This Build Week submission demonstrates EVOTOOL's first safety layer: locating the unique formal evolution record for a workspace and evolution line.
The evaluator runs:
evotool --workspace <workspace> --line <line-code>
If exactly one valid record matches, EVOTOOL:
- returns
selected - displays the line code
- returns the canonical relative path
- calculates a SHA-256 source fingerprint
- avoids exposing the private absolute workspace path
If the record is missing, duplicated, unreadable, or resolves outside the allowed root, EVOTOOL stops and presents safe evidence instead of guessing. A duplicate result returns exit code 1 because the safety gate worked—not because the program crashed.
EVOTOOL is currently read-only. It does not modify the workspace.
How we built it
The submission preserves an existing diagnostic core and adds a thin evaluator-facing layer around it.
Before Build Week, EVOTOOL already had its read-only record-location core and a 107-test baseline.
During Build Week, Codex powered by GPT-5.6 added:
- a minimal installable Python package entry point
- the
--workspaceand--linecommand - compatibility with the existing single-record diagnostic command
- anonymous positive and duplicate examples
- CLI contract and privacy-safety tests
- an English evaluator guide with installation and reproduction steps
The new CLI presents the existing core result instead of duplicating record-selection, scanning, or path-safety rules. EVOTOOL has no third-party runtime dependencies.
The human owner made the product and safety decisions: keep the submission read-only, preserve the existing core, reject ambiguous records, exclude private workspace data, and constrain implementation to a narrow reviewed file set.
Challenges we ran into
The hardest challenge was not adding more features. It was creating an honest, reproducible submission around an existing project without confusing pre-event work with Build Week contributions.
We also had to preserve old CLI behavior while adding a new evaluator-facing command, keep output deterministic, prevent absolute-path disclosure, and make ambiguity visible as a deliberate stop condition.
Windows path behavior required particular care. One existing symlink-permission test remains skipped when the environment cannot create the required link.
Accomplishments that we're proud of
- 112 tests total
- 111 tests passing
- 1 existing Windows permission skip
- clean installation and CLI execution in temporary virtual environments
- independently repeated positive and duplicate-stop demonstrations
- deterministic relative-path and fingerprint output
- no third-party runtime dependencies
- no private workspace paths or data in the examples
- three dated Build Week commits for traceability
Most importantly, the negative demonstration is treated as a successful safety outcome: when two files claim the same evolution line, EVOTOOL lists the evidence and refuses to choose.
What we learned
AI initiative becomes more useful when it is grounded in concrete evidence. Agents should surface conflicts, omissions, trace links, and differences between documents and code instead of inventing continuity or offering generic advice.
Human judgment remains authoritative. The tool should reduce the cost of reconstructing context without outsourcing decisions about meaning, trade-offs, or formal truth.
We also learned that explicit stopping behavior is a product capability. A trustworthy tool must be able to say, “There is not enough evidence to continue safely.”
What's next for EVOTOOL
The larger direction is an evolution workbench for humans and agents:
- Safe record location
- Preview of proposed changes
- Explicit human decision
- Conflict-checked safe writeback
Only the first step is implemented in this submission. Preview, human adjudication, and safe writeback remain future work.
Future iterations will also explore traceable links between decisions, documents, and code while preserving privacy boundaries and human authority.
EVOTOOL makes evolution traceable. When truth conflicts, stop before guessing.
Log in or sign up for Devpost to join the conversation.