#1294 Specify artifact mutability and its sanctioned exceptions

packages/agents/content/guidance/shared/AGENTS.md

@@ -66,6 +66,10 @@ Read-only exercises (`--dry-run`, help text, preview tables, `--list`, exit-code
 
 When creating an artifact (plan, devlog, review, change summary, chat summary, etc.), invoke the `save-artifact` skill to resolve path and naming. Do not place artifacts in ad-hoc locations.
 
+A saved artifact records a moment, not a running state. Once written it stands: never rewrite one to match a later human edit, a rebase, or any other event downstream of it, and never raise its divergence from current state as a defect or as a repair for the user to weigh. Update a saved artifact only where the next step in the flow reads it, or where a skill directs the write (stamping a PR URL into a change summary, for instance).
+
+The same restraint governs the remote ticket. Align its acceptance criteria to the implementation only where the two conflict, or where the gap would mislead a reviewer. Small improvements arrive as a matter of course, and the ticket is not rewritten to pretend they were foreseen.
+
 ## Commits
 
 Invoke the `commit` skill before writing a commit message. It carries the title and body conventions, the work-type taxonomy, and the branch-naming format.

packages/agents/content/skills/_data/artifact-conventions.md

@@ -686,15 +686,16 @@ The first `coder_change-summary` in a run has no dispositions (nothing to respon
 ### Ticket-level artifacts
 
 - `change-summary` — Branch change summary for PRs
+- `deferred-findings` — Record of findings deferred during a `wrap-up` session, with cross-references to created tickets (falls back to non-ticket path when no ticket is in session)
 - `devlog` — Development log entry (falls back to non-ticket path when no ticket is in session)
+- `merge` — Record of a merged pull request
 - `orchestration-plan` — Orchestration plan (`orchestration-plan.json` is a **mutable** artifact overwritten each planning iteration; `{timestamp}_planner_orchestration-plan.md` files are versioned human-readable snapshots)
 - `plan` — Implementation plan document
 - `plan-review` — Plan review findings (completeness and correctness analysis)
 - `plan-v2` — Refined implementation plan after review and revision
 - `pull-request` — PR description file
 - `review` — Code review (ticket-level, commit scope)
 - `ticket` — Issue ticket
-- `deferred-findings` — Record of findings deferred during a `wrap-up` session, with cross-references to created tickets (falls back to non-ticket path when no ticket is in session)
 
 ### Non-ticket artifacts
 
@@ -864,6 +865,20 @@ Insights never carry criticality, never block a merge, and never count toward a
 - **Active**: Artifact is current and relevant
 - **Stale**: Branch has been merged or deleted, and artifact is 30+ days old
 
+### Mutability
+
+A saved artifact is a point-in-time record of what its author produced at the moment of writing. It is never reconciled with anything downstream of it: not a later human edit to the remote it was published to, not a rebase that leaves `baseSha` and `commit` unresolvable, not a subsequent turn of the session that wrote it. Divergence from current state is the artifact doing its job, so it is never reported as a defect or raised as a repair for the user to weigh. A step that discloses which of two candidate sources it measured against is reporting its own input, not proposing a reconciliation.
+
+These mutations are sanctioned, and no others:
+
+- **Frontmatter a skill's own step directs**: `create-pr` backfills a `pr:` line into the change summary, and `plan-orchestrable-steps` prepends resolved frontmatter to the planner's markdown snapshot. A pointer added after the fact is provenance the artifact could not carry at write time, which is what separates it from a content rewrite.
+- **Artifacts declared mutable**: `orchestration-plan.json` is overwritten each planning iteration, while its `.md` counterparts are versioned snapshots.
+- **Working input forwarded to another agent**: the receiving agent acts on the contents, so staleness would misdirect real work.
+
+Revision writes a new artifact rather than editing one. `refine-plan` saves its output as `plan-v2` under a later timestamp, leaving the plan it refines intact.
+
+Overwriting a record also breaks consumers. `capture-lede-decision` derives the agent's side of a lede episode by diffing the `pull-request` artifact's `## What` against the `merge` artifact's `## Body`; a `pull-request` body rewritten to match a human's later edit reports `differ: false` for a lede that was in fact revised, inviting an `accepted` verdict the author never gave. The corruption raises no error and is undetectable in any session that no longer holds the original text.
+
 ## Portability
 
 Every level degrades gracefully:

packages/agents/content/skills/save-artifact/SKILL.md

@@ -52,15 +52,16 @@ Run artifacts are saved by the skills that produce them (`review-branch`, `respo
 ### Ticket-level
 
 - `change-summary` — Branch change summary for PRs
+- `deferred-findings` — Record of findings deferred during a `wrap-up` session, with cross-references to any tickets created (ticket-scoped when a ticket is in session; falls back to project-scoped `deferred-findings/` otherwise)
 - `devlog` — Development log entry (ticket-scoped when a ticket is in session; falls back to project-scoped `devlogs/` otherwise)
+- `merge` — Record of a merged pull request
 - `orchestration-plan` — Orchestration plan for the orchestrate engine
 - `plan` — Implementation plan document
 - `plan-review` — Plan review findings (completeness and correctness analysis)
 - `plan-v2` — Refined implementation plan after review and revision
 - `pull-request` — PR description file
 - `review` — Code review (ticket-level, commit scope)
 - `ticket` — Issue ticket
-- `deferred-findings` — Record of findings deferred during a `wrap-up` session, with cross-references to any tickets created (ticket-scoped when a ticket is in session; falls back to project-scoped `deferred-findings/` otherwise)
 
 ### Run artifacts