live: heartbeat sync 2026-10-30T21:32:40-07:00 (Refs #11)

agent/managed-skills/line-edit-anchor-discipline/SKILL.md

@@ -1,24 +1,42 @@
 ---
 name: line-edit-anchor-discipline
-description: "Avoid the recurring edit-tool line-op traps: empty PUT deletes lines, PUT ranges swallowing multi-line block delimiters, and anchors landing mid-expression. Use whenever issuing CUT/PUT line edits on tagged files."
+description: "Avoid the recurring edit-tool line-op traps: empty PUT deletes lines, PUT ranges swallowing neighbours, wrong-anchored PUTs replacing the wrong line, literal markdown bullet rows arriving verbatim as \"+-\"."
 ---
 
-# Line-edit anchor discipline (CUT/PUT ops on tagged files)
+# Line-edit anchor discipline
 
-Five self-inflicted syntax wounds in one session (franksign, 2026-10-21) all trace to three rules.
+The `edit` tool addresses lines, not intent. Three traps cost real time; all three
+fail *silently* or with a repair notice that is easy to skim past.
 
-## Rules
-1. **An empty PUT body DELETES the targeted lines** (tool warns: "Interpreted an empty PUT body as deletion"). Twice it ate a whole log entry / a closing `}`. For no-ops use nothing; for deletes use explicit `CUT`.
-2. **Never PUT a range whose endpoints cut through a multi-line block.** If a `| {`-style union variant, a frontmatter `---` fence, or a `test(...)` closer straddles the range boundary, the replacement swallows the opener/closer and strands the body. Pre-condition: line N-1 and M+1 must be block-complete. Fix-after-the-fact pattern: read the broken region raw, then `PUT k.=k:` to restore the single swallowed line (e.g. the missing `---`, the orphaned `  | {`, `}` → `});`).
-3. **Search-hit reads do not authorize PUT.** A grep/folded-summary read marks lines as "never displayed"; the edit tool refuses and echoes actual content. That refusal is a free verification — re-check the echoed lines match intent, then straight-retry with the same tag.
+## 1. Empty PUT deletes the range
 
-## Costly mistakes seen
-- Empty `PUT 7-7:` deleted a just-written log entry; restoring required re-issuing the full entry text.
-- `PUT 6.=7` replacing `timestamp`+`---` dropped the frontmatter close fence → lint-breaking file silently.
-- `PUT 10.=11` on a union type swallowed `  | {` opening a 12-line variant → cascade of LSP "unexpected label" warnings.
-- `CUT` of a stranded opener left its dangling `.json())` behind; balance errors surface only at EOF (`expected ')' but file ends`) — locate by reading regions raw, not by widening the payload.
+`PUT n.=m:` with no body rows deletes lines n..m. To insert, use `PUT >n:`
+(after line n) or `PUT <n:` (before line n). Never send a PUT range whose body is
+empty unless deletion is the goal.
 
-## Discipline
-- After any edit that reports a syntax error or a warning: read the touched region with `:raw` before the next op; fix the single wrong line, do not resend the block.
-- "no change: byte-identical" means your anchor math is off — re-read, don't append more content.
-- Prefer replacing whole coherent blocks (start line = block start, end line = block end) over edits that end mid-statement.
+## 2. PUT ranges must be the complete final content of exactly those lines
+
+- Replacing one line: `PUT n.=n:` with exactly one body row. If the body carries
+  the *previous* line as its first row (a copy-paste of the anchor), that line is
+  duplicated and the real target line is overwritten — no error, and the
+  "auto-repaired replacement boundary" note is the only hint.
+- Anchor only on lines the current `[path#tag]` display actually showed. If the
+  tool answers "anchors to lines you never displayed", the line numbers are
+  wrong: re-read that range, then re-issue. Do not retry blind.
+- Multi-op edits: order ops bottom-up (highest line numbers first) so earlier
+  inserts cannot shift later anchors.
+
+## 3. Literal `- ` rows (markdown bullets) cannot go through `edit`
+
+A body row starting with `-` parses as a CUT op. The error says to prefix it with
+`+` (`+- item`) — **that advice is wrong in practice**: the file ends up
+containing the literal `+- item`. When the content legitimately needs leading
+`- ` bullets (prompt law text, changelog entries, lists), write it with `write`
+after a full `read` of the file, or restructure the line to avoid the leading
+dash.
+
+## Verification habit
+
+After any PUT that replaces a range, `read` the touched range (not the whole
+file) and confirm the neighbouring lines survived — especially the line after the
+range, which is what a swallowed boundary eats. Cheap; catches the silent cases.