[shiplog/discovery] Harden envelope parsing against cross-platform line-ending variance

[devallibus]

Discovered During

Issue #102 — while implementing the triage scan workflow and testing envelope parsing on Windows 11.

Problem

The triage scan bulk-fetches issue bodies via gh issue list --json body and parses <!-- shiplog: ... --> envelopes with a regex. On Windows, the GitHub API returns \r\n line endings in JSON string values, which breaks the standard \n-based regex pattern. This caused all 7 backfilled envelopes to fail parsing silently — the scan returned ? for every field.

Root cause: The envelope format spec and all examples assume \n line endings. The normalization rules section didn't mention line-ending handling. While the fix for #102 added a one-line note (body.replace('\r\n', '\n')), this is a narrow patch — it doesn't cover all the places agents interact with envelope text.

Scope beyond Windows: This isn't just a Windows problem:

• macOS/Linux: gh CLI may return \r\n when the issue body was authored on Windows or via the GitHub web editor, which preserves the original line endings
• Git config: core.autocrlf settings can affect how text is stored and retrieved
• GitHub API: REST and GraphQL responses may encode line endings differently depending on the client platform, content origin, or API version
• Copy-paste: Users pasting envelope templates from browsers or editors may introduce mixed line endings

Any agent on any platform can encounter \r\n in envelope text. The normalization must be a first-class parsing step, not a platform-specific workaround.

Proposed Fix

Make line-ending normalization a required first step in envelope parsing, documented in every place agents are told to parse envelopes.

Tasks

• T1: Add normalization step to retrieval guidance [tier-3]

  • What: In artifact-envelopes.md §4 (Retrieval Guidance), add an explicit "Step 0: Normalize" before the agent query strategy. The current one-line note in normalization rules is necessary but insufficient — agents reading the retrieval guidance won't see it. Add a code example showing normalization before regex matching.
  • Files: skills/shiplog/references/artifact-envelopes.md (modify)
  • Allowed to change: §4 Retrieval Guidance, agent query strategy block
  • Must not change: §1 field schema, §2 kinds, §3 supersession model
  • Verification: Read the retrieval guidance and confirm normalization is the documented first step
  • Accept when: An agent following §4 normalizes line endings before any regex match

• T2: Add normalization note to Phase 6 triage scan [tier-3]

  • What: In SKILL.md Phase 6 step 5 (triage scan), add a note that the bulk-fetched bodies must be normalized before envelope parsing. Reference the normalization rule in artifact-envelopes.md.
  • Files: skills/shiplog/SKILL.md (modify)
  • Allowed to change: Phase 6 step 5 only
  • Must not change: Other phases or steps
  • Verification: Read Phase 6 and confirm the normalization note is present
  • Accept when: An agent following the triage scan workflow knows to normalize before parsing

---

Authored-by: claude/opus-4.6 (claude-code)
Discovered during #102. Cross-platform parsing robustness.