| name | append-vs-modify |
|---|---|
| description | Action-scoped discipline for IDD modify-actions — every modify SHALL declare scope category, undeclared SHALL refuse |
Every modify-action SHALL declare an explicit scope category. Undeclared modify-actions SHALL be refused.
This rule supersedes IDD's previously implicit hybrid append+modify discipline. It applies uniformly to AI invocations and human user invocations — actor identity is NOT a discipline boundary.
IDD plugin v2.72.0 development hit ≥ 6 supersession workaround instances in a single session — each new feature ran into "AI-authored stale state" and re-invented its own bridge:
#515supersession bridge (idd-closeStep 0 gate fork for Strategy/Plan pre-impl checkbox staleness)#148retroactive## Implementation Completepost (configured to trigger #515)#149retroactive## Closing Summarypost (after commit-body auto-close trap)- IC_R011 audit blocks (
### Sister Concerns Filed/### Closing Follow-ups Filed/### Distribution Sync/### Residue Acknowledgement) appending to one comment without convergence - Canonical reference docs growing freely (
ic-r011-checkpoint.md301→397 lines) #150body wiped by badsedsubstitution + silentgh issue editaccept
Pattern: no first-class principle governs "how a modify-action should exist". Each new IDD feature ran into the same shape of pain and shipped its own ad-hoc workaround. This rule codifies the discipline so future contributors classify their modify-actions on day one instead of inventing a 7th supersession workaround.
User pivot during /spectra-discuss (2026-05-25): actor-based exemption ("AI restricted / user free") was structurally weak — /idd-edit blanket user-modify entry was a black hole, structurally same shape as raw bash sed (both lack scope declaration). Discipline shifted to action-scoped: every action declares what it modifies, regardless of who invokes.
Every modify-action SHALL declare exactly one scope category from the canonical 8-category enumeration. Actions without a declared category SHALL be treated as
(undeclared)and SHALL be refused at runtime (by skill spec gate) or at review time (by analyzer, future tooling).
Scope declaration takes the form of an inline note in the action's SKILL.md description:
(category: <name>)
(category: <name>, scope: "<identifier>")
The scope qualifier names the targeted section / field / artifact when relevant (e.g. scope: "## Current Status").
Definition: Changes a machine-readable state field — phase, timestamp, status enum value, checkbox boolean. Does NOT modify prose.
Scope boundary: Only the named field. Surrounding text immutable.
Examples:
/idd-updateCurrent Status**Phase**:field change (created→diagnosed)/idd-clarify --status resolved=N,<reason>flips Clarity Surface row status enumspectra task doneflips- [ ]to- [x]- Step 0.5 dismiss row sets
deferred→dismissedwith reason
Definition: Whole named section REPLACE — section boundary explicitly declared (section identifier is part of invocation contract). Does NOT overflow.
Scope boundary: The named section's heading-to-next-heading range only.
Examples:
/idd-updateREPLACE## Current Statusentire section below---separator/idd-edit --section "## Foo"REPLACE the named section's content (heading preserved)
Definition: APPEND a new audit block to a named comment under a named section heading. Does NOT modify existing content within or outside the target.
Scope boundary: The target section's end position (insert before next heading or EOF). Existing text immutable.
Examples:
- IC_R011 sister sweep PATCHes
### Sister Concerns Filedblock into a Diagnosis comment /idd-diagnoseStep 3.4 Layer V Vagueness Pre-check PATCHes### Vagueness Pre-checkblock/idd-issueStep 4.6 emits### Clarity Surfaceblock into a new issue body
Definition: Modify occurs in the draft phase before publish. Once published (committed to GitHub or written to disk as final artifact), the content falls under append-only discipline.
Scope boundary: Time-bounded — only during draft assembly. Post-publish the same content is immutable.
Examples:
/idd-closeStep 3.5 inline replace「follow up later」→「(see #NEW)」in closing summary body assembly beforegh issue commentpublishes the comment
Definition: Absolute immutability. Once written, never modified by any action (AI or user), including in-place-correction. This is the IC_R007 zone.
Scope boundary: Exactly two kinds of content (closed list, #351 — do not extend by analogy):
- Original-source quotations — a maximal run of consecutive lines starting with
>in which some line contains one of exactly three labels:Original text, the decision-template label**Original**, or the reply-template label**Point(> **Point i**, a reviewer's words quoted verbatim — verify #351 round 7). The quotation records what was actually said; it stays true as a record even when the judgment it led to turns out wrong. - Third-party content — comments, and issue bodies, whose author is neither the OWNER, a bot, nor the invoking user (the authenticated
ghuser). They are someone else's words; IDD proposes corrections to them but does not correct them in place. A bot's comment is outside this list (--append/--replace/--prepend-notemay touch it), and so is the OWNER's content when someone else runs the edit, but both are still someone else's words to the person running it, so--correctrefuses them (bot: verify #351 round 2; OWNER: user decision 2026-10-17). For an issue body the author is the person who opened the issue — an approximation: text an IDD skill or a maintainer later wrote into someone else's issue body counts as that person's, and text a collaborator wrote into yours counts as yours (user decision 2026-10-17).
--override-user-content --reason="..." still exists for --append / --replace / --prepend-note as an explicit, audited exception for third-party comments; it is never accepted with --correct.
Issue-body prose in an issue opened by the invoking user — interpretation paragraphs, Expected, Actual, Impact, including text an IDD skill wrote there — is not in this zone: it is correctable through in-place-correction. An issue body opened by anyone else is third-party content (item 2). Before #351 the whole body above the --- separator was listed here, which made every wrong interpretation permanent and pushed corrections into appended errata that downstream readers kept missing.
Examples:
- The
> **Original text**: …blockquote under## Problem(per IC_R007) - A collaborator's review comment on the issue (
/idd-editR5 refuses it;--correcthas no override)
Definition: Only add new entries; never modify or remove existing entries.
Scope boundary: Whole artifact is append-target. Existing entries immutable; new entries inserted at top or bottom per artifact convention.
Examples:
- GitHub comments after publish (the GitHub mechanism enforces this; PATCH is reserved for
audit-block-appendandin-place-correction) CHANGELOG.md— new version entries prepended on top, old entries never modifiedtasks.mdhistory rows (the rows themselves are append-only; the checkbox state field isstate-field-update)- Spectra archive snapshot directories (
openspec/changes/archive/<date>-<name>/) openspec/specs/<name>/spec.md— changed only by archiving a change's delta, never edited directly
Definition: Documentation / source code artifacts — the artifact IS the work product, not audit history. Free rewriting allowed (git provides history).
Scope boundary: Whole artifact. No internal structural protection.
Examples:
- SKILL.md files
- Canonical reference docs (
plugins/issue-driven-dev/references/*.md) - Source code files (
.rs/.py/.swift/.ts/ etc.) - Plugin manifesto, README, contributor guides
Definition: Replace content that is wrong — as the user states in a discussion of the issue, or agrees to when a skill proposes the correction (#424) — in place, so that later readers — humans and AI sessions that re-read the issue as memory — stop inheriting the error (#351). Applies only to the invoking user's own content — issue bodies and comments whose author is the invoking user's own gh login (org maintainers show as MEMBER; the repository OWNER's content counts only when the OWNER runs it — user decision 2026-10-17) — including published comments that are otherwise append-only. A bot's comment is not included: it is a third party's words, answered with an errata comment (verify #351 round 2).
Scope boundary: One bounded region — a whole comment (--scope whole-comment) or one named section (--section <heading>; the only form allowed for an issue body). Known limitation (user decision 2026-10-17): text that belongs to no heading — below an issue body's last ---, such as the IC_R011 **Source** footnote, or before its first heading — cannot be reached; an error there is answered with /idd-comment --type correction. The action SHALL (a) show the diff and the full replacement in the conversation and then apply without asking for confirmation in a repository the user can write to (#424 D1; it asks when the privacy level is enforce; the privacy review covers the added text, and a hit at enforce or warn, newly added third-party verbatim text at light, a credential at any level, or an unconfirmed #272 question holds it back instead), (b) archive the prior full text under .claude/.idd/archive/edits/ of the main worktree (not a linked worktree, so the archive outlives worktree cleanup) before writing — the archive is never tracked by git and Claude's tools are denied access to it — (c) end the replaced region with a marker that carries the backup id and no path, and (d) refuse verbatim-preserve content and the regions owned by other skills (## Current Status → idd-update, ### Clarity Surface → idd-clarify). /idd-edit --correct is the only action declared in this category; other skills reach it by proposing the command, and the user's "run now" is the confirmation (#424).
Examples:
/idd-edit comment:<id> --correct --section "### Strategy"replaces a Diagnosis strategy that named the wrong backup location/idd-edit issue:<N> --correct --section "## Expected"replaces an Expected paragraph that misread the request, keeping theOriginal textquotation above it untouched/idd-comment --type errata --target-comment <id>on the invoking user's own comment delegates to/idd-edit --correctinstead of appending an errata comment
issue-write-back.md routes each change the user decides while an issue is discussed in a session to one place; each place maps to one category of this rule:
| Change | Written with | Category |
|---|---|---|
The problem (question, scope, ## Expected) |
/idd-edit issue:<N> --correct --section <heading> |
in-place-correction |
| The diagnosis (root cause, strategy, routing), and the affected Implementation Plan sections (verify reports are not edited) | /idd-edit comment:<id> --correct --section <heading> |
in-place-correction |
| A decision that changes the diagnosis | both: /idd-comment #N --type decision and /idd-edit comment:<id> --correct --section <heading> |
append-only and in-place-correction |
| New information, a decision, the course of the discussion | /idd-comment #N --type <decision|note|question|link> |
append-only (a new comment) |
Someone else's content is never rewritten: their comment gets /idd-comment --type errata, their issue body /idd-comment --type correction, both new comments. Skills that detect an error keep proposing corrections (### Proposed Corrections); a user's "run now" is the confirmation. --correct ends the replaced text with a visible line (--note) before its marker.
When introducing a new IDD action that modifies an existing artifact, walk this tree to assign a category:
Does the action publish to a permanent place (GitHub comment, archived spec)?
├─ Yes → Does it happen in draft phase (before publish call)?
│ ├─ Yes → category: inline-replace-before-publish
│ └─ No → Continue ↓
│
Is the target verbatim-preserve content (an Original-text / **Original** / **Point i** quotation,
or a comment or issue body authored by someone other than the OWNER, a bot, or the invoking user)?
├─ Yes → REFUSE the action entirely (this zone is verbatim-preserve)
│
Is the action replacing content that is wrong (a problem or diagnosis change the user decides in a discussion counts)?
├─ Yes → category: in-place-correction (only via /idd-edit --correct; your own content only —
│ anyone else's, the OWNER's and a bot's included, gets an errata comment instead)
│
Is the target a machine-readable state field (phase, timestamp, status enum, checkbox boolean)?
├─ Yes → category: state-field-update
│
Is the target a whole named section (with explicit identifier in the invocation)?
├─ Yes → category: bounded-section-replace
│
Does the action APPEND to a named section without modifying existing content?
├─ Yes → category: audit-block-append
│
Is the target a doc / source code file (artifact IS the work product)?
├─ Yes → category: free-rewrite
│
Is the action purely additive (new entries only, existing entries immutable)?
├─ Yes → category: append-only
│
None of the above → REFUSE; the action lacks a defined scope and SHALL NOT proceed
This rule does NOT replace existing IDD principles — it codifies the modify-action axis that the IC principles each touch from their own angle.
| IC principle | Concern | Boundary with this rule |
|---|---|---|
| IC_R007 (verbatim source preservation) | "Don't modify original-source quotations (Original text / **Original** / **Point i**) or third-party content" |
IC_R007 zones map to verbatim-preserve category in this rule. IC_R007 remains the authoritative source for what counts as verbatim; this rule says how the discipline is structurally enforced (refuse modification via category gate). |
| IC_R010 (confidence-tagged routing) | "Tag confidence on automated decisions; defer low-confidence to review" | Orthogonal axis. IC_R010 governs whether an action should proceed; this rule governs what scope it operates on once proceeding. An IC_R010-confident action still SHALL declare its scope. |
| IC_R011 (follow-up filing checkpoint) | "Surface tangential concerns at deliberation moments; file by default" | IC_R011 audit blocks (### Sister Concerns Filed / ### Closing Follow-ups Filed / ### Linked-Context Siblings Filed / ### Distribution Sync / ### Residue Acknowledgement) are all instances of audit-block-append category under this rule. IC_R011 governs when and why to surface; this rule governs how the surface is structurally written (named-section append, not free modification). |
When an IC principle and this rule both apply to an action, both SHALL be satisfied. They do not conflict in observed cases — IC principles operate on different axes (content selection, surfacing eligibility) while this rule operates on the modify-action axis (scope discipline).
#515 introduced supersession bridge logic in idd-close Step 0: when ## Implementation Complete > ### Checklist exists with all items [x], the gate ignores pre-impl Strategy/Plan checkboxes (they are superseded snapshots).
This rule generalizes that pattern。參與者要按角色描述而非當成一組同質的 gate site
(#290 修正——原本寫「4 個 gate site」,把 producer 誤列為 gate)。角色不是互斥的:
idd-update 兩者皆是。
| 誰 | Producer | Consumer |
|---|---|---|
idd-implement Step 5a Checklist Sync |
✅ 寫 priority 1(## Implementation Complete > ### Checklist) |
— |
idd-update |
✅ 寫 priority 2(## Current Status > ### Tasks,經 --tasks-file,#290) |
✅ body sync 的 phase 推斷 fallback |
idd-close Step 0 |
— | ✅ 硬 gate:未完成則拒絕 close |
idd-verify checklist scan |
— | ✅ 讀為 verify context |
以 producer 身分執行時不評估 resolution;idd-update 在同一次執行中兩件事都做,但那是
兩個分開的動作(先寫、後讀),不是一個角色。
每個 consumer SHALL resolve an authoritative_source via the following priority order:
authoritative_source = first_exists([
"## Implementation Complete > ### Checklist", # producer: idd-implement Step 5a
"## Current Status > ### Tasks", # producer: idd-update --tasks-file
"## Todo" | "## Tasks" | "## Checklist" # producer: 無(僅人手寫)
])
When a source resolves, the gate evaluates only items in that source. Earlier sources (Strategy, Implementation Plan) are treated as superseded snapshots — not subject to gate evaluation, retained for historical reference.
一個候選只有在 heading 存在且其下含至少一個可解析的 checklist 項目時才 resolve。 heading 在而項目數為 0 視同不存在,resolution 繼續往下一個候選。
此定義三個 consumer 一致適用;consumer SHALL NOT 自訂 emptiness 規則。在 #290 之前
只有 idd-close Step 0 寫出這個條件(len(items) > 0),且只對 priority 1,另兩個無條件——
本節把它升為 canonical。
| 候選狀態 | resolve? |
|---|---|
| heading 缺席 | 否 |
| heading 在,0 項 | 否 |
| heading 在,1 項未勾 | 是 |
| heading 在,3 項已勾 | 是 |
優先序的每一層 MUST 在上表指名它的 producer,或明示「無自動 producer(僅人手寫)」。 兩者皆可,但不得留白——留白會讓一層在實務上永遠不 resolve,使優先序靜默塌縮成剩下 的層,而塌縮不報錯,只會讓某些路徑莫名其妙地 fallback。
措辭注意:本不變式要求的是具名,不是「必須有自動 producer」。priority 3 明示為人工 逃生口即滿足;若寫成「每層都必須有 producer」,會與 priority 3 的既定設計直接矛盾。
這正是 #290 的成因:priority 2 被 consumer 讀,卻沒有任何 skill 寫它,而那個事實沒有被
記在任何地方——於是 chain 退化成「只有 priority 1」,而 priority 1 只有 idd-implement
產生,任何繞過它的路徑都沒有 authoritative source。
priority 3 明示為「無自動 producer(僅人手寫)」——它是給人工維護的 issue 用的逃生口。 若日後有工具開始依賴它,本不變式要求先為它指名 producer。
本不變式無法被測試強制——它約束的是「未來新增的層」,而未來的層尚不存在。只能寫在此處 靠 review 維持。
When no authoritative_source resolves (legacy issues created before this rule shipped, or pre-Implementation issues that genuinely have only Strategy), the gate SHALL fall back to scanning all checklist-bearing sections (Strategy, Implementation Plan, Implementation Complete, Todo, Tasks, Checklist, Current Status > Tasks) — the pre-discipline behavior.
This fallback preserves backward compatibility:
- Existing closed issues remain inspectable / verifiable under the same behavior they were closed under
- Legacy in-flight issues (still using Strategy-only pattern) continue to gate correctly
- The supersession bridge for
#515remains a no-op (the new generalized logic subsumes it)
Fallback is non-permanent: once an issue acquires an authoritative_source via normal /idd-implement flow, the gate transitions to authoritative-source-only evaluation for that issue.
This rule defines the discipline; tooling-level enforcement is reserved for follow-up work:
- Skill spec gate (in scope of this rule): each modify-action's SKILL.md description SHALL contain
(category: <name>)inline note. Skill author's responsibility; reviewable manually. - Future analyzer (out of scope): static analyzer that scans SKILL.md for modify-action descriptions missing
(category: ...)notes and flags as Critical. Follow-up issue when needed. - CLI parser + bash enforcement (out of scope): native
--section/--scopeflag handling for/idd-editat CLI parser layer + verbatim-preserve guard. Three R1/R2/R3 attempts at bash-level enforcement in SKILL.md introduced new bugs each iteration (infinite loop, flag-eat, multi-line awk-v BREAK). Deferred to follow-up issue #154 for proper standalone proposal with multi-line body handling + parser pattern guards + errata flow integration designed upfront. Phase 1 (this change) is spec-discipline-only: the normative--scope/--sectionrequirements + verbatim-preserve guard live inopenspec/specs/append-vs-modify-discipline/spec.mdRequirements 4-5 + this rule's "Spec discipline" section below + CHANGELOG[2.73.0].idd-edit/SKILL.mdwas reverted to pre-#150 baseline as part of the R4 / Path (c) decision — SKILL.md surface (argument-hint, mode table, usage examples) does NOT currently describe the discipline. AI / user invocation reads spec + rule + CHANGELOG + applies discipline manually until #154 ships both the runtime gate AND the SKILL.md surface updates. (#154 shipped in v2.81.0 — see the Enforcement status paragraph under "Spec discipline" below.)
≥ 8 existing IDD actions are retroactively labeled by the change that introduced this rule (add-action-scoped-modify-discipline). New actions added after this rule ships SHALL declare category at SKILL.md authoring time. The (undeclared) → REFUSE rule applies to both new and retroactively-introduced actions; legacy actions without inline notes are caught at next maintainer review.
/idd-edit is the IDD plugin's existing comment-edit primitive. Per this rule's action-scoped discipline, the skill's invocation surface SHALL declare scope:
--append/--prepend-notemodes:audit-block-appendcategory (scope inherent in mode semantics — trailing block / leading errata marker). No additional flag required.--replacemode:bounded-section-replacecategory. Invocations SHALL include--scope whole-comment(full-comment overwrite acknowledgment) OR--section <heading-within-comment>(named subsection scope).--correctmode:in-place-correctioncategory (#351). Same scope flags as--replace; an issue-body target (issue:<N>) accepts--sectiononly. No--override-user-content.
This rule additionally declares a verbatim-preserve guard at the comment layer: comments where author_association ≠ OWNER (and the author is neither in the known-bot allowlist nor the invoking user's own gh login) SHALL NOT be modified without explicit --override-user-content --reason="..." invocation discipline. --correct is narrower still: it admits only the invoking user's own content — not a bot's, and not the OWNER's when someone else runs it — and has no override.
Enforcement status: enforced at runtime by scripts/idd-edit-helper.py since v2.81.0 (#154 → #155 Python layer): parse-args refuses --replace / --correct without scope (exit 3), validate-target refuses authors other than the OWNER, a bot, or the invoking gh user (exit 4; with --correct only the invoking user's own content passes), and check-correction refuses protected regions (exit 6, #351). The bash-in-SKILL.md attempts on PR #153 that this paragraph used to describe were replaced by that helper.
Recommended invocation patterns (per discipline):
/idd-edit comment:NNN --replace --scope whole-comment --body "..."/idd-edit comment:NNN --replace --section "### Sister Concerns Filed" --body "..."/idd-edit comment:<external-user-id> --append --body "..." --override-user-content --reason="..."
CHANGELOG.md [2.73.0] declares the spec discipline + cites this rule + tracks runtime-enforcement deferral via #154.
Some state-field-update operations carry a reason field that downstream gates must regex-match for behavior dispatch (e.g. /idd-diagnose Step 0.5 gate proceeds-with-warn only on specific reasons). To prevent typo drift across multiple SKILL.md sites that cite the same literal, all gate-recognized reason literals SHALL be registered here as the single source of truth. SKILL.md sites SHALL cite by reference (with cross-link to this section), not by inline duplication.
| Reason literal | Originating action | Recognized by | Behavior |
|---|---|---|---|
unattended-auto-Step-4.6-deferred |
/idd-clarify Step 4.8.A — auto-defer in unattended mode (#137, v2.74.0+) |
/idd-diagnose Step 0.5 gate |
Proceed-with-warn (instead of REFUSE the deferred row) |
unattended-auto-Step-3.4-layerV-deferred |
/idd-diagnose Step 3.4 F — Layer V trigger auto-proceeds in unattended mode, leaving a structured deferred record in the Diagnosis comment (#120) |
/idd-all Phase 6 Action items scan; /idd-all Phase 5c close stage (scripts/close-stage.py, #392) |
Aggregate into「## Action items (require human review)」with the catch-up command /idd-clarify #N — not a gate bypass: the auto-proceed already happened, the record makes it recoverable. The close stage stops at verified while the latest Diagnosis carries the record |
unattended-auto-Step-4-choice-default |
/idd-diagnose Step 4 Stage 1 choice-first decision surfacing — an unattended run takes the safe default for a decision a stakeholder should pick, leaving a #### Choice Default Record in the Diagnosis comment (#392) |
/idd-all Phase 5c close stage (scripts/close-stage.py); /idd-all Phase 6 Action items scan |
The close stage stops at verified (no automatic merge or close) while the latest Diagnosis carries the record; Phase 6 lists it under Action items |
Adding a new reason literal:
- Choose strict literal (no abbreviation, no version suffix, no underscore variants — kebab-case with clear semantic anchor)
- Add row to this table — name the originating action, recognizing gate(s), behavior
- Update the originating SKILL.md to write the literal; update the recognizing gate SKILL.md to match
- Both SKILL.md sites cite this registry rather than embed the literal inline
- Add corresponding scenario to
openspec/specs/append-vs-modify-discipline/spec.mdif discipline-level recognition is required
Why centralized: 3+ SKILL.md sites citing the same literal is a typo-drift HIGH risk surface. One source eliminates drift; sites that drift their citation are caught by spectra analyze or manual grep (grep -c "<literal>" plugins/issue-driven-dev/rules/append-vs-modify.md = 1 SHALL hold).
Regex matching convention: when gates match these literals via regex, dot characters in the literal MUST be escaped (Step-4\.6-deferred, not Step-4.6-deferred) to prevent over-broad match. Case-sensitive, anchored (^...$) match preferred.
openspec/specs/append-vs-modify-discipline/spec.md— normative specplugins/issue-driven-dev/references/ic-r011-checkpoint.md— audit-block-append category authority#515— Path C precedent (supersession bridge)#150— the META issue codifying this rule#137— first reason literal registered (see Reason pattern registry section)