[codex] Document cross-platform path assertions

[TabishB]

Summary

• Add test guidance that calls out Unix-only path separator assumptions in CLI output assertions.
• Tell contributors to use platform-aware path helpers or normalize display output before comparing.
• Add a patch changeset for the docs update.

Validation

• pnpm exec changeset status --since=origin/main
• git diff --check

Summary by CodeRabbit

• Documentation
  • Added cross-platform guidance for CLI tests: avoid hard-coded Unix path separators, use platform-safe path construction, normalize human-readable output for comparisons, and include Windows-separator regression coverage when path behavior changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f46dc72b-becf-4963-94eb-ebdf58faf438

📥 Commits

Reviewing files that changed from the base of the PR and between a4d856c and ef0634c.

📒 Files selected for processing (1)

• test/AGENTS.md

---

📝 Walkthrough

Walkthrough

Adds a patch changeset and updates test/AGENTS.md with a "Cross-Platform Paths" section describing how to write CLI test assertions that handle Windows path separators, normalize human-readable outputs, and add Windows-focused regression coverage.

Changes

Windows Path Handling Test Guidance

Layer / File(s)	Summary
Release entry .changeset/windows-path-guidance.md	Changeset entry documents a patch release for @fission-ai/openspec and notes the added Windows path guidance.
Test guidance documentation test/AGENTS.md	Adds a "Cross-Platform Paths" section: form expected paths with platform-safe utilities, normalize human-readable CLI output for assertions, and include Windows-separator regression tests when path behavior changes.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1057: Updates test assertions for Windows workspace paths and CLI arguments by canonicalizing expectations, aligning with this guidance.

Suggested reviewers

• alfred-openspec

Poem

🐰 I hop through folders, paths in paw,
Forward, back — I check them all.
Tests now gentle, no slash debate,
Windows or Unix, they pass the gate. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '[codex] Document cross-platform path assertions' directly and clearly summarizes the main change: adding documentation for cross-platform path handling in test assertions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/document-main-ci-matrix

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

test/AGENTS.md (1)

16-16: ⚡ Quick win

Consider mentioning FileSystemUtils.toPosixPath() as a normalization option.

The guidance recommends normalizing strings before comparing but doesn't specify how. Since FileSystemUtils.toPosixPath() exists specifically for converting paths to forward slashes (as shown in the file-system.ts snippet), mentioning it here would make the guidance more actionable.

📝 Suggested enhancement

-- For human-readable output, either assert a deliberately normalized display format or normalize both actual and expected strings before comparing.
+- For human-readable output, either assert a deliberately normalized display format or normalize both actual and expected strings before comparing (e.g., using `FileSystemUtils.toPosixPath()` to convert backslashes to forward slashes).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/AGENTS.md` at line 16, Update the guidance to mention
FileSystemUtils.toPosixPath() as a concrete normalization option: edit the
sentence about normalizing human-readable output to recommend either asserting a
normalized display format or normalizing both sides (e.g., by calling
FileSystemUtils.toPosixPath() on paths) before comparing, and include a short
note that toPosixPath converts backslashes to forward slashes for cross-platform
consistency.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/AGENTS.md`:
- Line 16: Update the guidance to mention FileSystemUtils.toPosixPath() as a
concrete normalization option: edit the sentence about normalizing
human-readable output to recommend either asserting a normalized display format
or normalizing both sides (e.g., by calling FileSystemUtils.toPosixPath() on
paths) before comparing, and include a short note that toPosixPath converts
backslashes to forward slashes for cross-platform consistency.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ad7e06a1-fff1-433c-8005-12795632e34f

📥 Commits

Reviewing files that changed from the base of the PR and between 7fdb177 and a4d856c.

📒 Files selected for processing (2)

• .changeset/windows-path-guidance.md
• test/AGENTS.md

[alfred-openspec]

Looks good. The docs now include the concrete FileSystemUtils.toPosixPath() normalization guidance CodeRabbit asked for, and checks are green.