Enforce RST-only rule for sphinx/sphinx-needs directives — no directives in markdown files

[patdhlk]

Problem

Pharaoh skills (especially pharaoh:author) can generate content that includes Sphinx or sphinx-needs directives. When the target file is markdown (.md), this creates broken output because:

1. ubc CLI does not process markdown files — it indexes RST content only. Needs defined in .md files are invisible to ubc build needs, ubc check, and all ubc-based validation.
2. ubCode extension does not index markdown — same limitation. Needs in .md won't appear in the MCP data, live validation, or schema checks.
3. Sphinx directive syntax in markdown is invalid unless the project uses MyST-Parser with specific configuration — and even then, compatibility is partial and fragile.

This means a need authored into a .md file silently disappears from the traceability graph. No error, no warning — just missing data.

Current behavior

Pharaoh skills may write sphinx-needs directives (e.g., .. req::, .. spec::, .. decision::) into markdown files when the surrounding context is markdown. There is no guard preventing this.

Required behavior

Binary rule: no Sphinx or sphinx-needs directive content in markdown files.

When a Pharaoh skill needs to write directive content and the target location is a .md file, it must choose one of two paths:

Option A: Convert the markdown file to RST

• Rename <file>.md to <file>.rst
• Convert the markdown content to RST syntax (headings, links, lists, code blocks)
• Add the directive content to the converted file
• Update any references to the old filename

Option B: Create a separate RST file for directive content

• Keep the .md file as-is (for prose, documentation, etc.)
• Create a new .rst file alongside it (e.g., requirements.rst, specifications.rst) for the directive content
• Add an appropriate toctree or cross-reference link between them

Decision logic

The sphinx-needs-expert subagent should be consulted when the choice between Option A and Option B is unclear. General heuristic:

Situation	Recommendation
File is mostly prose with 1-2 needs to add	Option B — create separate RST file
File is a requirements/specs document being converted	Option A — convert entire file to RST
File is in a directory with other RST files	Option A — match the directory convention
File is user-facing docs (README, guides)	Option B — keep markdown for readability
Unsure	Ask the user, explain the tradeoff

Where to enforce

This rule must be checked in every skill that writes files:

• pharaoh:author — primary authoring skill, most likely to hit this
• pharaoh:decide — writes decision needs
• pharaoh:spec — generates spec docs (these are markdown, but their plan tables invoke pharaoh:author which writes RST)
• pharaoh:retrofit (future, see pharaoh:retrofit — Help users introduce sphinx-needs and traceability into existing codebases #3) — content conversion skill, directly handles the md→rst question

Implementation approach

Add a shared instruction (similar to skills/shared/data-access.md and skills/shared/strictness.md) that all file-writing skills reference:

skills/shared/file-format.md — rules for file format selection:

• Check target file extension before writing any directive content
• If .md: do NOT write directives, apply Option A or Option B
• If .rst: proceed normally
• If creating a new file for directive content: always use .rst
• Log/report the decision to the user

Acceptance criteria

• No Pharaoh skill writes Sphinx or sphinx-needs directives into .md files
• skills/shared/file-format.md exists with the enforcement rules
• pharaoh:author references the shared file-format instructions
• pharaoh:decide references the shared file-format instructions
• When a skill encounters a .md target, it either converts or creates a separate .rst file
• The user is informed when a file format decision is made
• sphinx-needs-expert can be consulted for ambiguous cases