plugin-quality: decide how write-once is guaranteed when the agent bound by it is the party able to break it

[kyle-sexton]

This was generated by AI during triage.

Parent

Refs #3357, finding P1. Decision carrier for a two-item cluster; the snapshot-consistency child carries a blocking edge to this issue.

Re-verified against current main (2026-09-06)

The write-once discipline is still a live, load-bearing part of the contract. The skill body states it in several places: each evidence flush must be a new numbered artifact and never an append to an existing one, because packet files are write-once, and the sealing rules are what a sibling enforcement hook depends on. The sealing tool itself distinguishes several outcomes, including a distinct status for a packet whose files are present but unsealed.

So the property is real, it is depended upon, and it is stated as a rule the agent must follow.

The problem

The party bound by the rule is the party positioned to break it, and breaking it is terminal.

Write-once is asserted as a discipline the producing agent observes, not as a property the system guarantees. Nothing makes a sealed packet physically unwritable. An agent that appends to an existing artifact instead of creating a new one, or that rewrites a file after sealing, violates the contract, and the violation is not recoverable: the sealed state records what the file was, the file is now something else, and the original content is gone. Verification can report the discrepancy afterward, which is valuable, but detection after loss is not the same as prevention.

That is what makes this a design question rather than a defect to patch. An unrecoverable failure mode reachable by ordinary operation is not something to paper over with a stronger warning in the instructions. The instructions already say write-once. Saying it more emphatically does not change who can break it or what happens when they do.

The decision

Broadly two directions, and a maintainer should pick:

Enforce it mechanically. After sealing, make the packet physically unwritable, so the contract is a property of the system rather than a promise by its most fallible participant. The obvious levers are filesystem permissions on the sealed artifacts, or routing all writes through a tool that refuses to touch a sealed file. Costs: it must not break legitimate re-sealing (the skill documents a flow that updates a contract file and re-seals), it interacts with whatever the sibling enforcement hook already does, and permission changes behave differently across platforms, which this plugin's own sibling findings show matters here.

Restate the contract to match what is actually guaranteed. Stop asserting write-once as a property and describe it as a discipline with after-the-fact verification, naming the failure mode plainly, including its unrecoverability. Costs nothing, makes the documentation honest, and leaves the terminal failure reachable.

A third possibility worth weighing: make the failure non-terminal instead of unreachable. If a sealed artifact could not be lost, only superseded, the question changes shape entirely. That may be cheaper than either option above and it addresses the property that actually hurts. The parent's plan does not raise it; it is offered here because "terminal" is doing most of the work in this finding, and removing that is a legitimate answer.

What must be decided

1. Is write-once a guaranteed property or a documented discipline?
2. If guaranteed, by what mechanism, and how does it coexist with the documented re-seal flow and the sibling enforcement hook?
3. If a discipline, is the unrecoverable loss acceptable, or is the failure made non-terminal instead?
4. Whatever is chosen, does the snapshot-consistency sibling resolve the same way? The parent's plan expects it to, which is why it is blocked on this.

Acceptance criteria

• The four questions are answered here.
• The skill's statement of the write-once rule matches what the system actually guarantees; no surface claims a property that is only a convention.
• If enforced mechanically: the documented re-seal flow still works, and the mechanism is tested on the platforms the plugin supports rather than assumed portable.
• If left as a discipline: the unrecoverability is stated where the producing agent will read it, and the decision is recorded so a later audit does not re-file it.
• The blocked sibling is unblocked or closed in light of the answer.

Out of scope

• The mechanical findings in the parent, which need re-verification first.
• Changing what the sealing tool verifies or its exit-status vocabulary.

Blocked by

None, but it cannot proceed without a maintainer's judgment.