Unescape stings before inserting into DB.

[SorraTheOrc]

Problem statement

Unescape input strings (description, comment body, audit-text, etc.) before they are persisted so that stored work item text does not contain unnecessary escape sequences. Currently some inputs may be stored with backslash-escaped characters or other escape artifacts due to upstream escaping, which reduces readability and can confuse downstream consumers.

Note: Title corrected to "Unescape strings before inserting into DB." per intake clarification.

Headline

Unescape and normalize plain-text fields in the persistence layer so stored work item text is human-readable and free of accidental escape artifacts.

Users

• Primary: developers and engineers who read and edit Worklog items and expect plain, human-readable text in the database and CLI/TUI outputs.
• Secondary: automation or integrations that read work item fields (scripts, export/import tools) which expect normalized text.

Example user stories

• As a support engineer, when I view a work item in the CLI or TUI, I want descriptions and comments to show normal characters (not escaped sequences) so I can read them quickly.
• As an integration developer, when I export work items, I want stored text to be stable and not contain escape artifacts that require additional post-processing.

Success criteria

• All new writes to text fields (description, comment body, audit-text, and other free-text fields) are unescaped before being persisted. Verified by unit tests that exercise the persistence layer.
• Existing tests that rely on text content (CLI/TUI integration tests) continue to pass or are updated intentionally with minimal diffs.
• No data migrations are performed; existing DB rows remain unchanged.
• A centralised change is made in the persistence/write path so the fix covers CLI, TUI, and any other writers without duplicating logic.
• Add at least one unit test that demonstrates unescaping behaviour (e.g. input "Line
  Break" persists as "Line
  Break" rendered as a real newline when displayed), and one integration test that writes via the CLI or TUI and asserts the persisted DB value does not contain backslash escape artifacts.
• Ensure JSON or structured fields are not accidentally modified by the normalization step (only plain text fields should be touched).

Constraints

• No migrations: per intake decision, existing DB records must not be modified.
• Must not alter intended or meaningful escaping: the implementation must only remove accidental escaping artifacts and must preserve intentional characters like double quotes (") and backticks (`) where the repository currently allows them.
• Keep changes minimal and well-tested; prefer a single small change in the persistence layer over many ad-hoc fixes.

Risks & assumptions

• Risk: Unintended transformation of text that is intentionally escaped (false positives). Mitigation: implement conservative normalization that targets obvious escape artifacts and include unit tests showing preserved intentional characters.
• Risk: Tests that assert exact raw DB content may fail. Mitigation: update tests intentionally and keep diffs minimal; add guidance in the PR description about the expected change.
• Risk: Over-broad application may alter structured fields (JSON). Mitigation: only apply normalization to known plain-text fields; add a safety check to skip JSON/structured fields.
• Assumption: All writers funnel through a persistence write path that can be changed once to cover CLI, TUI and other writers. If not, additional small adapters will be required.
• Scope-scope creep risk: additional features (e.g., migrating historic data, building heuristics for many escape styles) should be recorded as separate work items and not expanded here.

Existing state

• Work item WL-0MNGQ5E99001WLMJ currently documents the issue and is marked in-progress at stage "idea".
• The codebase contains multiple input paths for text: CLI flags (create/update --audit-text), TUI input handlers (src/tui/), and a persistence layer (SQLite-backed persistence under src/ persistence modules). Tests exist for CLI audit-text round-trips and for TUI rendering/persistence.

Desired change

• Implement a small unescape/normalize function and apply it in the persistence write path so that any text saved to the DB is normalized.
• Add targeted unit tests for the new normalization function and a small integration test that verifies an example write via the CLI or TUI results in an unescaped string stored in the DB (without changing existing rows).

Related work

• tests/integration/audit-roundtrip.test.ts — integration test that exercises --audit-text round-trip; useful test harness for a small integration test.
• src/commands/create.ts and src/commands/update.ts — CLI entry points that accept --audit-text; these call into the shared update/create logic and are likely writers of text fields.
• src/tui/persistence.ts and src/tui/controller.ts — TUI components and persistence helpers where user-entered text is collected and saved.
• WL-0MNFZ7J0T000EQDL — Stabilize CLI GitHub push tests against timeout flakiness; referenced because tests in that item exercise CLI flows which also use --audit-text.
• WL-0MMNCOJ0V0IFM2SN — Audit Read Path in Show Outputs; related to how audit text is presented and read back from persistence.

Related work (automated report)

• WL-0MMNCOJ0V0IFM2SN "Audit Read Path in Show Outputs" — Completed intake that defines how structured audit text is read and rendered. Relevant because it documents read-path expectations and redaction rules that must be preserved when changing persisted audit text.
• WL-0MLDJ34RQ1ODWRY0 "Replace comment-based audits with structured audit field" — Umbrella work that migrated audit data model to a structured field; helps explain why audit-text is persisted and where it appears in code paths.
• WL-0MNFZ7J0T000EQDL "Stabilize CLI GitHub push tests against timeout flakiness" — Includes CLI test harnesses that exercise --audit-text roundtrips and test utilities; useful reference for a small integration test harness.
• Files: src/commands/create.ts, src/commands/update.ts, src/tui/persistence.ts, src/tui/controller.ts, src/audit.ts — these locations contain write-paths, audit helpers and TUI persistence hooks where changes should be carefully placed or coordinated.

This conservative report lists items with clear relevance to persistence and read surfaces for audit/text fields. It is intentionally limited to items that define read/write contracts or provide test harnesses useful for validation. For any broader migration or history-preservation work, create a follow-up item and link it to this one.

Appendix: Clarifying questions & answers

• Q: "Is the work-item title typo intended or should it be corrected to 'Unescape strings before inserting into DB.'?" — Answer (user): "Yes — correct to 'strings' (Recommended)". Source: interactive reply. Final: yes.
• Q: "Should this change perform a migration to fix already-stored DB values, or only ensure correct behavior for future inserts?" — Answer (user): "Only future inserts (Recommended)". Source: interactive reply. Final: only future inserts.
• Q: "Which code paths should this intake cover? Pick all that apply (you can also type a custom path)." — Answer (user/selection): "Persistence layer (centralize unescape in DB write path) (Recommended)". Source: interactive reply. Final: persistence layer.

[SorraTheOrc]

effort_and_risk_skill

Effort and Risk Report

Effort | Small | 4.33h
Risk | Low | 4/20
Confidence | 74% | unknowns: Whether any writers bypass the persistence layer and require small adapters

{
  "effort": {
    "unit": "hours",
    "tshirt": "Small",
    "o": 2.0,
    "m": 4.0,
    "p": 8.0,
    "expected": 4.33,
    "recommended": 8.33,
    "range": [
      6.0,
      12.0
    ]
  },
  "risk": {
    "probability": 2.1,
    "impact": 2.1,
    "score": 4,
    "level": "Low",
    "top_drivers": [],
    "mitigations": [
      "Add targeted tests and integration checks",
      "Lock dependencies and add compatibility tests",
      "Schedule extra review for risky components"
    ]
  },
  "confidence_percent": 74,
  "assumptions": [
    "Writers funnel through a single persistence write path",
    "No DB migrations required"
  ],
  "unknowns": [
    "Whether any writers bypass the persistence layer and require small adapters"
  ]
}