feat(core): extend grammar with Actor, Outcome, Scenario blocks and native Field syntax

[pmTouchedTheCode]

Summary

Extends the Product Model grammar from 7 to 10 block types to make product requirements more concrete, structured, and semantically precise.

---

New block types

Actor — First-class user role/persona

Explicitly scopes who a requirement applies to. Referenceable from Policy, Constraint, and Scenario via the actor attribute.

<Actor id="guest-shopper" name="Guest Shopper"
  description="Unauthenticated visitor with no saved payment methods." />

Outcome — Measurable success criterion

Anchors a Feature to a quantitative definition of done. Only allowed inside Feature (not Section).

<Outcome id="checkout-cvr" name="Checkout Conversion Rate"
  metric="conversion_rate" baseline="68%" target="75%" timeframe="30d" />

Scenario — Given/When/Then acceptance criteria

Links a structured acceptance test directly to a Policy and optional Actor. Allowed in Feature and Section.

<Scenario id="sc-cart-limit" name="Cart at capacity"
  given="A cart with 50 items" when="User adds a 51st item"
  then="System returns CART_LIMIT_EXCEEDED"
  policy="max-cart-items" actor="guest-shopper" />

---

Native <Field /> syntax for Definition

Replaces the error-prone JSON-encoded fields attribute with readable MDX child elements. Supports min, max, and pattern inline constraints. Legacy JSON attribute still works for backward compatibility.

<Definition id="cart-item" name="Cart Item" version="1.0.0">
  <Field name="quantity" type="number" required min={1} max={99} />
  <Field name="currency" type="enum" values="USD,EUR,GBP" required />
  <Field name="orderId" type="string" pattern="^ORD-\d+$" required />
</Definition>

---

Policy and Constraint enhancements

• trigger on Policy: semantic event name that fires the policy (e.g. cart.item.add), searchable but not runtime-evaluated
• actor on Policy / Constraint: space-separated Actor ID list, parsed into string[] during MDX transformation

<Policy id="max-cart-items" trigger="cart.item.add"
  actor="guest-shopper member-shopper"
  rule="A cart may contain at most 50 distinct line items" enforcement="must">

---

Expanded Link relationship vocabulary

Added 5 product-domain relationships alongside the original 4:

New	Meaning
triggers	from causes to to activate
supersedes	from replaces to (e.g. v2 replacing v1)
validates	from must pass before to can proceed
enables	from unlocks or gates to
blocks	from prevents to while active

---

Validator changes

• Link integrity extended to check Policy.actor[], Constraint.actor[], Scenario.policy, and Scenario.actor references — both per-document and workspace-wide
• grammar-rules enforcement picks up all new block types automatically via the updated GRAMMAR_TABLE

---

Updated grammar table

Block	Allowed in	Children
Actor	Feature, Section	—
Outcome	Feature only	—
Scenario	Feature, Section	—

---

Tests

• grammar.test.ts: updated block type count (7→10), new parent/child assertions
• schema.test.ts: full coverage for ActorBlockSchema, OutcomeBlockSchema, ScenarioBlockSchema; field min/max/pattern; new Link relationships
• parser.test.ts: native <Field /> parsing, backward-compat JSON fields, new block type round-trips, actor array parsing, trigger parsing
• validator.test.ts: grammar placement rules, actor/scenario broken-reference detection
• valid-full.product.mdx fixture updated to use v2 grammar
• checkout.product.mdx example rewritten to demonstrate all new features

[Copilot]

Pull request overview

Extends the Product Model (core grammar + parser + validator) to support richer requirement semantics by adding Actor, Outcome, and Scenario blocks, introducing native <Field /> child syntax for Definition, and expanding link/reference integrity checking.

Changes:

• Added new block types (Actor, Outcome, Scenario) to schemas, AST typing, and grammar rules.
• Implemented native <Field /> parsing for Definition (with legacy JSON fields still supported) plus inline constraints (min/max/pattern) and values → enumValues.
• Expanded link relationship vocabulary and extended link integrity validation to cover Policy/Constraint.actor and Scenario.policy/actor references.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/core/src/grammar.ts	Updates grammar table to allow new block types and enforce Outcome placement rules.
packages/core/src/schema/primitives.ts	Adds new block types to BlockTypeSchema.
packages/core/src/schema/blocks.ts	Introduces Zod schemas for Actor/Outcome/Scenario; extends Policy/Constraint/Link schemas.
packages/core/src/schema/fields.ts	Extends field schema with min/max/pattern constraints.
packages/core/src/schema/index.ts	Re-exports new schemas from the public schema surface.
packages/core/src/types/ast.ts	Exposes new block types through inferred AST typings.
packages/core/src/parser/remark-product-model.ts	Adds collection of native <Field /> child attributes during MDX extraction.
packages/core/src/parser/mdx-to-pmast.ts	Transforms <Field /> children into Definition.fields, parses Policy/Constraint.actor strings, preserves legacy JSON behavior.
packages/core/src/validator/rules/link-integrity.ts	Extends per-document reference checks to include actor/scenario references.
packages/core/src/validator/rules/workspace-link-integrity.ts	Extends cross-workspace reference checks to include actor/scenario references.
packages/core/tests/grammar.test.ts	Updates grammar table tests for 10 block types and new placement rules.
packages/core/tests/schema.test.ts	Adds schema coverage for new blocks, new link relationships, and field constraints.
packages/core/tests/parser.test.ts	Adds parser coverage for <Field />, legacy JSON fields, new blocks, trigger/actor parsing, and new link relationships.
packages/core/tests/validator.test.ts	Adds validator coverage for new grammar placements and new reference integrity checks.
packages/core/tests/fixtures/valid-full.product.mdx	Updates fixture to use new grammar and native <Field /> definitions.
models/examples/checkout.product.mdx	Rewrites example to demonstrate Actors/Outcomes/Scenarios, native Fields, triggers/actors, and new relationships.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.