docs: clarify directive grammar and semantic boundaries

[rlippmann]

What changed

• Updated the normative directive grammar specification to make the syntax/semantics boundary explicit:
  • canonical parsing happens before semantic evaluation;
  • directive-shaped invalid input is outside the canonical language;
  • clarify applies only after a successful canonical parse when semantic evaluation requires clarification.
• Updated README and API documentation to align with the canonical directive model:
  • removed wording that implied malformed grammar flows into clarification;
  • removed stale pending-confirmation language from the core boundary documentation.
• Defined normative policy identity semantics:
  • separated parsed operand text from canonical policy identity;
  • clarified that policy identity is a semantic evaluation concern, not a parsing concern;
  • documented representation-level identity rules separately from language interpretation.
• Clarified the policy identity contract:
  • Unicode normalization, apostrophe-character normalization, case folding, and whitespace normalization are representation canonicalization;
  • article removal, spelling correction, contraction expansion, dont → don't, synonym matching, and natural-language equivalence are not core identity rules.
• Clarified premise handling:
  • premise values are semantically opaque strings with representation-level sanitation only;
  • premise values do not use policy-item identity rules.

Why

• The previous documentation mixed grammar recognition, semantic clarification, and historical pending-confirmation behavior.
• Core needs a deterministic canonical language boundary:
  • parse canonical directives first;
  • evaluate their meaning second.
• Policy identity behavior was previously implied through implementation details rather than explicitly defined by the specification.
• This update establishes the contract needed for future validator/conformance work and keeps language-level interpretation outside the compiler core.

Related:

• Related to Reconsider yes/no replacement-intent clarifications when either item is prohibited #187. This PR defines the specification boundary needed for the replacement clarification cleanup but does not change runtime replacement conflict behavior.

Checklist

• pre-commit run (uv run pre-commit run --all-files)
• tests pass (uv run pytest)