SW-217 — Define and test UTF-8 BOM handling for project configuration #399

Summary

The config loader parses UTF-8 text directly with JSON.parse. A UTF-8 BOM at the beginning of an otherwise valid JSON file is currently rejected as invalid JSON. Define a consistent encoding policy and make the error or compatibility behavior explicit.

Workstream

• Workstream: WS-CONFIG
• Primary scope: src/config/project.ts; tests/config-malformed-json.test.ts; docs/reference/configuration.md
• Protected surface: Yes — maintainer review required
• Priority: P2
• Difficulty: low
• Proposed points: 100

Acceptance Criteria

• The project chooses either documented BOM support or a specific actionable BOM error.
• Valid UTF-8 config without a BOM remains unchanged.
• Tests cover BOM-prefixed and non-BOM files.
• Documentation matches actual loader behavior.

Dependencies

None.

Out of Scope

• Unrelated architecture or public command-contract changes.
• New runtime dependencies without maintainer approval.
• Mainnet deployment or remote template execution.

Definition of Done

• Acceptance criteria have deterministic regression coverage.
• Security and compatibility boundaries remain intact.
• Supported-platform CI passes.

Labels

• Stellar Wave (do not apply until activation is explicitly authorized)
• type: test
• area: config
• priority: P2
• difficulty: low
• points: 100
• workstream: config

Sequencing and scope note

Sequencing: implement after SW-216 (#398) so duplicate-key validation remains in place while config text normalization is finalized.