docs(plugin-quality): settle write-once as an agent discipline (#3866)

plugins/plugin-quality/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "plugin-quality",
-  "version": "0.7.26",
+  "version": "0.7.27",
   "description": "Post-use behavioral audit of Claude Code plugin components: a six-step audit workflow (evidence capture, grounded mapping in a fresh subagent, blindspot pass, interactive contract lock, presence-gated review seams, work-item emit with draft+confirm) over any skill, agent, hook, command, or config you have actually used, zone-informed by context-guard snapshots when present, conservative when not.",
   "author": {
     "name": "Melodic Software",

plugins/plugin-quality/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to the `plugin-quality` plugin.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.27] - 2026-09-28
+
+### Changed
+
+- **Write-once is a documented discipline, not a filesystem guarantee (#3866).** The packet
+  contract, the `auditor` prompt, and the recurring-concerns checklist now state that the
+  producing agent can break write-once, that `packet-seal.sh verify` detects after the fact,
+  and that an in-place edit is terminal for that packet (`record` refuses to reseal). Mechanical
+  chmod or a sealed-file write proxy is unpaid. A sealed packet asserts bytes at seal time, not
+  current world state, which unblocks the snapshot question on #3867.
+
 ## [0.7.26] - 2026-09-28
 
 ### Changed

plugins/plugin-quality/agents/auditor.md

@@ -64,6 +64,11 @@ a new file, since their autocorrect has no memory and reverts a hand-repair on t
 when your packet writes are done, run
 `bash "${CLAUDE_PLUGIN_ROOT}/scripts/packet-seal.sh" record <packet-dir>` so a later reader can
 detect any divergence after the seal. Do not try to evade the hooks. Detection is the lever.
+Write-once is a discipline you observe, not a lock the filesystem enforces (#3866). An Edit of a
+sealed file is terminal for this packet: `record` refuses to reseal over the divergence, and later
+notes stay UNSEALED. Corrections go in a new file (`audit-notes-2.md`, `evidence-<n>.md`), never an
+edit. As of 2026-09-28. Recheck: a paid mechanical-seal slice, or `packet-seal.sh` gaining a
+divergence-acknowledge path.
 
 **Recheck trigger for both dated stamps above:** re-read the cited page and re-date the stamp when
 the sub-agents page starts describing the report-filename guardrail, when the hooks page stops

plugins/plugin-quality/skills/audit/SKILL.md

@@ -159,7 +159,8 @@ Every resolved target gets one packet under
 every later step. Read
 [`reference/evidence-packet.md`](reference/evidence-packet.md) before step 1 writes anything: it
 owns the directory layout and the file set, the `audit-notes.md` filename constraint and why
-`findings.md` is forbidden, and the write-once discipline that keeps a sibling `PostToolUse` hook
+`findings.md` is forbidden, and the write-once discipline (an agent rule with after-the-fact
+verify, not a filesystem lock: #3866) that keeps a sibling `PostToolUse` hook
 from rewriting evidence underneath the run. Getting any of the three wrong silently corrupts the
 audit rather than failing it.
 
@@ -352,8 +353,9 @@ the gate does not cover, because it produces no external effect; there is still
 ## Recurring concerns. Apply every audit
 
 Walk `reference/recurring-concerns.md` before finalizing findings, the accumulated
-design-failure checklist (silent bypass surfaces, enforcement scope/tiers, SSOT/drift, coupling,
-cross-platform, escape hatches, observability).
+design-failure checklist (silent bypass surfaces, enforcement scope/tiers including a claimed
+property the producer can break, SSOT/drift, coupling, cross-platform, escape hatches,
+observability).
 
 ## Reference index. Load on demand
 

plugins/plugin-quality/skills/audit/reference/evidence-packet.md

@@ -199,3 +199,16 @@ These escapes do not hold: a non-`.md` extension evades `markdown-format` but no
 `typos` allowlist / `markdownlint` opt-out is unreliable on the `$HOME`-rooted residual;
 a shell redirect to dodge `Write|Edit` is a hook bypass the fleet blocks. Detection, not
 evasion.
+
+**Write-once is a discipline, not a filesystem guarantee (#3866).** The producing agent
+holds Write (and the main thread can Edit). Nothing makes a sealed file physically
+unwritable. `packet-seal.sh verify` reports CHANGED after the fact; `record` then refuses
+to reseal, so later files in that packet stay UNSEALED. That loss is unrecoverable for
+this packet. Mechanical chmod, or a write proxy that refuses sealed files, is unpaid.
+A sealed packet asserts bytes at seal time, not current world state (the snapshot
+question on #3867). Corrections go in a new file (`audit-notes-2.md`, `evidence-<n>.md`),
+never an edit of a file already on disk.
+
+| Claim | Basis | As of | Recheck |
+|---|---|---|---|
+| Write-once is an agent discipline with after-the-fact verify. The system does not make sealed files unwritable. Breaking it is terminal for that packet. | `packet-seal.sh` record/verify (reseal refuses over a CHANGED entry); this section's three rules; `agents/auditor.md` Write grant. | 2026-09-28 | A paid slice that makes sealed packet files physically unwritable on the platforms this plugin supports without breaking the documented re-seal of `packet.sha256`, or `packet-seal.sh` gaining an `--acknowledge-divergence` path. |

plugins/plugin-quality/skills/audit/reference/recurring-concerns.md

@@ -36,6 +36,10 @@ A guard is only as good as its coverage. Find the paths where it *doesn't* fire.
 - **Process** (rebase happened, triage occurred, footer assembled): NO command signature → NOT
   hook-enforceable. Advisory is the correct ceiling; the fix is making the advisory reliably fire,
   not hard-blocking. Never hard-block a command that has a documented legitimate direct use.
+- **Claimed property the producer can break.** If a skill asserts write-once, sealed, or immutable,
+  but the producing agent can Edit the artifact, that is a discipline with after-the-fact verify,
+  not a guarantee (#3866). Flag a surface that states the stronger reading. Detection after loss
+  is not prevention.
 
 ## 4. SSOT / DRY / drift