Design gaia author replacement commands for review-driven edits

[kunyuan]

Context

While designing the top-level gaia review CLI, we decided that review should not become a second authoring surface. gaia review can select the next target, render a review packet, and suggest edits, but any mutation of DSL source, priors, or authored probabilities should go through gaia author.

That leaves one missing authoring capability: today most gaia author commands append new statements. Review-driven edits often need to replace or revise an existing declaration instead of appending a duplicate.

Problem

A reviewer may inspect a packet and conclude that:

• an independent claim needs a different prior or justification;
• an infer(...) statement has incorrect p_e_given_h / p_e_given_not_h;
• an associate(...) statement has an incorrect strength / rationale;
• a text warrant/rationale needs to be revised in place.

If the only supported workflow is append-only authoring, users can easily create duplicate or stale statements. That makes the future gaia review loop messy and blurs the boundary between review and authoring.

Proposed direction

Add a small gaia author replacement/revision surface that can update an existing authored target by label/binding, while keeping gaia review read-mostly. Possible shapes to design:

gaia author replace <label-or-binding> ...
gaia author revise <label-or-binding> ...
gaia author register-prior --claim X --value 0.7 --justification "..." --replace

The exact command names can be decided in design, but the ownership boundary should be explicit:

• gaia review renders packets, orders review work, and records qualitative target status in ReviewManifest;
• gaia author is the only CLI that mutates package source, priors, or authored probability parameters.

Requirements

• Resolve existing declarations by label, binding name, or stable authored target where possible.
• Replace in the original source file, preserving surrounding formatting as much as practical.
• Reuse the existing author prewrite/postwrite validation and gaia build check behavior.
• Support JSON-first output consistent with current gaia author envelopes.
• Provide a dry-run or preview mode before mutating source.
• Avoid editing .gaia/review_manifest.json as part of this author command.

Initial target cases

• Replace/update register_prior(...) for a claim without accumulating duplicate prior records.
• Revise authored probabilities and rationale for infer(...).
• Revise authored strength/rationale for associate(...).
• Revise rationale/text fields for warrant-bearing author verbs where safe.

Non-goals

• Do not make gaia review write priors, strengths, likelihoods, or posterior beliefs.
• Do not write posterior belief values back into source.
• Do not design registry-side review reports or reviewer assignment here.

Acceptance criteria

• A review packet can suggest concrete gaia author ... commands for probability/text fixes.
• The suggested commands can update existing package source without duplicate stale statements.
• gaia build check continues to be the validation gate after replacement.