How a contribution — human or model — should be shaped so it stays reviewable. This expands the Accountability axiom (see README.md): no contribution without a claim; no claim without evidence.
Contribution shape
A meaningful contribution should tend toward this shape:
purpose: What is this for?
change: What changed?
evidence: Why should we believe it works for that purpose?
weakness: What is still unclear, untested, or risky?
next: What would improve the claim, evidence, or implementation?
Not every contribution will satisfy this perfectly. The workbench should accept imperfect contributions from reasonable actors, human or model, while making their weaknesses legible and improvable.
Evidence patterns
Crystal specs are necessary evidence for behavior, but they are not sufficient evidence for every purpose. Purpose determines evidence.
| Purpose claim | Default evidence pattern |
|---|---|
| "This behaves correctly" | Crystal specs |
| "This is formatted consistently" | crystal tool format --check |
| "This is faster" | A repeatable benchmark pattern |
| "This is simpler" | A before/after explanation and a smaller surface area |
| "This is clearer" | A clearer name, boundary, document, or example |
| "This is more interchangeable" | A seam, adapter, replacement test, or reduced coupling |
| "This is safer" | A constrained interface, redaction check, permission check, or failure test |
| "This improves code generation" | Comparison on defined generation tasks |
| "This improves accountability" | A traceable claim, evidence, review record, and follow-up path |
These patterns should begin as conventions. Pave the cowpaths: when a practice repeatedly helps, name it, document it, support it, make it easy, and only later make it enforceable.
Missing evidence should be visible as weakness, not hidden as certainty. When two approaches are available, prefer the one with better evidence.
Practical rules
- Keep changes small and reviewable.
- Prefer Crystal for maintained application code.
- Prefer Fossil-native integration where it strengthens project memory and review.
- Keep secrets, tokens, passwords, and session material out of versioned files.
- Run model tasks in isolated checkouts.
- Prefer structured native tools over raw shell access.
- Treat generated code as incomplete until its purpose and evidence are recorded.
- Prefer evidenced paths over unevidenced paths.
- Record weak evidence so future work can strengthen it.
- Make interchangeability real when the current level of efficiency can afford it.
Before claiming green
Run the full crystal spec and crystal tool format before claiming a change is done or merging it. The worker's verify_crystal_change and Accept-and-merge's verify_live do not run integration / cross-file checks, so regressions can otherwise slip to trunk. See docs/review-checklist.md.
A full suite run can exceed a single turn's own timeout — launch it as a supervised background job (agent-tool run-job, or the job supervisor's job_start) rather than as an in-turn foreground command, and always run it against an isolated checkout, never the live/served one (every checkout on the box shares one physical Fossil repo file, so a spec run against the wrong path contends with the live daemon — ticket cbec0a058b).