docs(incident): stop promising byte-for-byte fidelity the command no longer offers

The card said the command 'exits non-zero if the stored text doesn't
match the file byte-for-byte'. That stopped being true when the comment
text started being trimmed before the write: leading and trailing
whitespace never reaches storage, so an agent following the card's own
heredoc idiom would be promised a fidelity the command deliberately does
not provide. State what actually holds instead — the write is verified,
surrounding whitespace is stripped on both ends, everything else
including interior blank lines survives.

The guidance test pinned that exact sentence, so it was keeping the
false claim in place. Assert the property instead: the guarantee must be
documented (read-back + non-zero exit), and the byte-for-byte promise
must NOT come back. Verified load-bearing - restoring the old sentence
turns the new assertion red.

Author: ysyneu

internal/skilldoc/incident_comment_guidance_test.go

@@ -41,8 +41,19 @@ func TestIncidentCardCommentWorkflow(t *testing.T) {
 	if strings.Contains(body, "read back every target and verify the intended comment is present before reporting success") {
 		t.Error("incident card must not retain the manual read-back workaround now that the CLI verifies content fidelity itself")
 	}
-	if !strings.Contains(body, "exits non-zero if the stored text doesn't match the file byte-for-byte") {
-		t.Error("incident card must document the command's own read-after-write content-fidelity guarantee")
+	// Assert the guarantee is documented, not the sentence that documents it:
+	// pinning a full sentence turns this check into a checksum that goes red on
+	// every reword and teaches the next reader to update the literal reflexively.
+	if !strings.Contains(body, "reads back") || !strings.Contains(body, "exits non-zero") {
+		t.Error("incident card must document the command's own read-after-write verification — that is what replaced the manual read-back step removed above")
+	}
+	// The CLI trims leading/trailing whitespace before sending, because the
+	// server trims it too, so the stored text is deliberately NOT the file's
+	// exact bytes. The card used to promise byte-for-byte fidelity against the
+	// file; that claim is false and would set an agent up to expect trailing
+	// newlines to survive a heredoc write.
+	if strings.Contains(body, "match the file byte-for-byte") {
+		t.Error("incident card must not promise byte-for-byte fidelity against the file: leading/trailing whitespace is stripped before the write")
 	}
 }
 

skills/flashduty/reference/incident.md

@@ -73,7 +73,7 @@ fduty incident resolve <incident-id> --root-cause "DB primary failover delay" --
 
 Projected `similar` lists stay below 16 KiB, and projected `detail --fields` output stays below 8 KiB. A trailing `...` means a long retained string was shortened; omit `--fields` only when the full unbounded detail is explicitly required.
 
-`comment` never accepts the text as a command-line argument — only `--comment-file <path>` (or `--comment-file -` to read stdin), so backticks/`$()`/quotes inside the comment are inert. The command also reads back every target's timeline after writing and exits non-zero if the stored text doesn't match the file byte-for-byte, so `Commented on ...` is proof of content fidelity, not just acceptance — no separate manual read-back is needed.
+`comment` never accepts the text as a command-line argument — only `--comment-file <path>` (or `--comment-file -` to read stdin), so backticks/`$()`/quotes inside the comment are inert. The command also reads back every target's timeline after writing and exits non-zero unless it finds an entry matching what it sent, so `Commented on ...` is proof of content fidelity, not just acceptance — no separate manual read-back is needed. Leading and trailing whitespace is stripped before sending (the server strips it too, so this is what gets stored); everything else, including interior blank lines, is preserved exactly.
 
 > `incident list --output-format json|toon` defaults to the compact row projection `incident_id,title,incident_severity,progress,start_time,channel_id`. Pass `--fields incident_id,title,channel_id,start_time` when you need different list columns; use `incident detail <id>` / `incident get <id>` for full incident records.