Pivot agentic component specs and align implementations (#4296)

* component spec updates

* component fixes and shared concepts

* fix framework-base shared loop platform resolution

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix agentic tests after theme merge

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: JasonVMo

.changeset/bright-tabs-coordinate.md

@@ -0,0 +1,6 @@
+---
+"@fluentui-react-native/components": minor
+"@fluentui-react-native/framework-base": minor
+---
+
+Add TabList group coordination, shared focus-modality and animation hooks, and align component behavior with the ratified React Native contracts.

.github/skills/agentic-component-authoring/SKILL.md

@@ -25,35 +25,46 @@ authoring rule in one always-loaded instruction file.
 
 ## Load focused references
 
-| Work                                                                                | Reference                                                                          |
-| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| Public props, slots, state types, native prop exposure, or exports                  | [Types and slots](references/types-and-slots.md)                                   |
-| Defaults, derived state, interaction hooks, accessibility, or slot construction     | [State and accessibility](references/state-and-accessibility.md)                   |
-| Tokens, style factories, theme caching, state precedence, or slot style application | [Styles and tokens](references/styles-and-tokens.md)                               |
-| Pure slot rendering, component assembly, or display names                           | [Rendering and assembly](references/rendering.md)                                  |
-| Runtime tests, type tests, snapshots, Storybook stories, or validation              | [Tests and stories](references/tests-and-stories.md)                               |
-| Native React Native Windows Fabric components, codegen, registration, or UIA        | [Windows Fabric native components](references/windows-fabric-native-components.md) |
-| Cross-component duplication, shared helper extraction, or dependency hygiene        | [Package optimization](../agentic-component-optimization/SKILL.md)                 |
+| Work                                                                                           | Reference                                                                          |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Flex component source resolution, React Native contract adaptation, provenance, or divergences | [Flex source adaptation](references/spec-source-adaptation.md)                     |
+| Public props, slots, state types, native prop exposure, or exports                             | [Types and slots](references/types-and-slots.md)                                   |
+| Defaults, derived state, interaction hooks, accessibility, or slot construction                | [State and accessibility](references/state-and-accessibility.md)                   |
+| Tokens, style factories, theme caching, state precedence, or slot style application            | [Styles and tokens](references/styles-and-tokens.md)                               |
+| Pure slot rendering, component assembly, or display names                                      | [Rendering and assembly](references/rendering.md)                                  |
+| Runtime tests, type tests, snapshots, Storybook stories, or validation                         | [Tests and stories](references/tests-and-stories.md)                               |
+| Native React Native Windows Fabric components, codegen, registration, or UIA                   | [Windows Fabric native components](references/windows-fabric-native-components.md) |
+| Cross-component duplication, shared helper extraction, or dependency hygiene                   | [Package optimization](../agentic-component-optimization/SKILL.md)                 |
 
 A new higher-order component normally needs every reference. A focused fix should load only the affected reference and
 its immediate neighbors. Keep the component's colocated `SPEC.md` and companion files authoritative for its contract.
 
 ## Workflow
 
-1. Read the repository and package instructions, the component `SPEC.md`, and every companion file referenced by the
-   spec. Use the package-wide optimization guidance only when the change clearly involves repeated patterns or shared
-   dependency boundaries.
-2. Inspect the closest canonical implementation. Use
+1. For a higher-order component, start Agency with the repository's
+   `flex-authoring` profile, invoke `flex-components:<name>`, and follow the
+   [Flex source adaptation](references/spec-source-adaptation.md) reference.
+   Record source identities without copying source bodies.
+2. Read the repository and package instructions, the component `SPEC.md`,
+   `spec/source.json`, and every React Native companion referenced by the
+   spec. For a new component, draft and review those local contract files
+   before implementation. Use the package-wide optimization guidance only when
+   the change clearly involves repeated patterns or shared dependency
+   boundaries.
+3. Inspect the closest canonical implementation. Use
    [`components/button`](../../../packages/agentic/components/src/components/button) for a styled higher-order component
    and [`primitives/icon`](../../../packages/agentic/components/src/primitives/icon) for a direct primitive.
-3. Establish the public contract before implementation: variants, slots, native props, accessibility, interaction
+4. Establish the public contract before implementation: variants, slots, native props, accessibility, interaction
    states, and platform behavior.
-4. Implement in dependency order: types and slots, state and accessibility, styles and slot props, pure rendering,
+5. Implement in dependency order: types and slots, state and accessibility, styles and slot props, pure rendering,
    component assembly, and explicit exports.
-5. Preserve the specification. Record a genuine token or platform gap rather than substituting an unrelated value or
+6. Preserve the specification. Record a genuine token or platform gap rather than substituting an unrelated value or
    web-only behavior.
-6. Add focused tests and stories that exercise the public API and the resolved native output.
-7. Run the smallest declared validation command while iterating. Finish with package format, lint, build, and tests; run
+7. Add focused tests and stories that exercise the public API and the resolved native output.
+8. Reconcile and ratify the local contract against the realized public types,
+   tests, stories, and platform evidence. Upstream changes require explicit
+   re-review and never overwrite the local contract.
+9. Run the smallest declared validation command while iterating. Finish with package format, lint, build, and tests; run
    the Storybook bundle for story changes and the root build when public types, manifests, or project references change.
 
 Do not divide one component implementation into separate sub-agent or sub-skill phases. Its types, state, styling, and

.github/skills/agentic-component-authoring/references/spec-source-adaptation.md

@@ -0,0 +1,81 @@
+# Flex source adaptation
+
+Use this reference when creating or revising a higher-order component contract.
+Flex skills provide design evidence; local React Native documents define FURN
+behavior.
+
+## Resolve one immutable source set
+
+Start Agency with the repository's `flex-authoring` profile and invoke
+`flex-components:<name>`. Confirm that `flex-components`, `flex-system`, and
+`flex-tokens` resolve to the release in
+`packages/agentic/components/spec-source-lock.json`.
+
+Read the component's shared skill and usage material plus its web companions.
+Read mobile companions only when that component provides them. A platform never
+falls back to another platform's files, and files from different revisions must
+not be combined.
+
+Do not copy source prose or token tables into the public repository. Record
+only identifiers and digests in `spec/source.json`.
+
+## Draft the React Native contract
+
+Before implementation, classify every relevant axis, slot, behavior, and token
+along two dimensions:
+
+1. Source surface: shared, web, mobile, Flex system, or an existing FURN
+   implementation.
+2. Disposition: adopted, adapted, intentional divergence, not applicable, or
+   deferred.
+
+Consult the local Flex token map and the closest Win32, macOS, or Windows V1
+implementation. Do not use iOS as the desktop compatibility reference.
+
+Write an original local contract:
+
+- public props, slots, defaults, and state ownership in `SPEC.md`;
+- actual FURN token bindings in `spec/tokens.yaml`;
+- React Native accessibility and UIA/AX behavior in
+  `spec/accessibility.md`;
+- keyboard, pointer, focus, and motion behavior in `spec/interaction.md`;
+- FURN usage and examples in `spec/usage.md`.
+
+Give contract requirements stable IDs and map each one to existing or planned
+types, tests, stories, or platform evidence in the Conformance table. Record
+every divergence in `SPEC.md` with a stable ID, disposition, rationale, status,
+and issue when follow-up work is required.
+
+Translate platform concepts deliberately:
+
+| Flex evidence                        | React Native contract                                                              |
+| ------------------------------------ | ---------------------------------------------------------------------------------- |
+| ARIA attributes or native elements   | `accessibilityRole`, `accessibilityState`, labels, and UIA/AX expectations         |
+| CSS pseudo-classes                   | explicit interaction state and precedence                                          |
+| browser focus selectors and outlines | persistent `FocusVisual`; never conditional `outline*` or native RNW focus visuals |
+| CSS pixel or layout rules            | React Native layout units, minimum targets, and platform behavior                  |
+| unsupported browser capability       | explicit divergence, dependency, or blocker                                        |
+
+Review the draft contract before writing code.
+
+Use `contract-draft` with `review-required` while authoring. A pre-code review
+moves the lifecycle to `contract-reviewed`, records only the source surfaces
+the reviewer actually consulted, and adds the review date. Planned evidence
+paths may remain unrealized at this stage.
+
+## Implement and ratify
+
+Implement the component through the normal types, state, styles, render, and
+assembly stages. Derive tests and stories from the requirement IDs. After
+validation, reconcile the draft against the realized public types and native
+output. Change the contract only through an explicit review; do not make an
+accidental implementation choice authoritative after the fact.
+
+Generating or repinning `spec/source.json` requires access to the private
+Marketplace and x3 repositories. Set lifecycle to `implemented` and
+conformance to `reviewed` only when the contract, implementation, and declared
+evidence agree. Updating
+the immutable source lock or its recorded file identities clears that review
+until each delta is adopted, adapted, rejected, or deferred. Drift at mutable
+Marketplace or x3 HEAD is a candidate proposal and does not invalidate a
+contract ratified against the pinned release.

agency.toml

@@ -0,0 +1,13 @@
+[profiles.flex-authoring]
+
+[[profiles.flex-authoring.plugins.default]]
+plugin = "market:flex-components@curated#206c4996205b027f4d806ac4ac7366f1f0ab0d5a"
+cache_policy = "no-refresh"
+
+[[profiles.flex-authoring.plugins.default]]
+plugin = "market:flex-system@curated#206c4996205b027f4d806ac4ac7366f1f0ab0d5a"
+cache_policy = "no-refresh"
+
+[[profiles.flex-authoring.plugins.default]]
+plugin = "market:flex-tokens@curated#206c4996205b027f4d806ac4ac7366f1f0ab0d5a"
+cache_policy = "no-refresh"

lage.config.mjs

@@ -12,6 +12,9 @@ const config = {
     clean: {
       cache: false,
     },
+    'check:spec-contracts': {
+      cache: false,
+    },
     lint: {
       inputs: ['*', 'src/**/*'],
       outputs: [],
@@ -22,7 +25,7 @@ const config = {
       // which doesn't exist, so lage silently drops the edge. Point at the
       // specific root target with the packageName#task syntax so every
       // package's tests wait for the whole-repo build to finish.
-      dependsOn: ['@fluentui-react-native/root#root-build'],
+      dependsOn: ['@fluentui-react-native/root#root-build', 'check:spec-contracts'],
       inputs: [],
       outputs: [],
     },

packages/agentic/components/AGENTS.md

@@ -19,7 +19,13 @@ invariants; detailed authoring recipes live in the
 
 ## Package invariants
 
-- Read the component `SPEC.md` and all referenced companions before changing its contract.
+- For a higher-order component contract, start Agency with the
+  `flex-authoring` profile, invoke `flex-components:<name>`, and follow the
+  [Flex source adaptation reference](../../../.github/skills/agentic-component-authoring/references/spec-source-adaptation.md).
+- Follow [SPEC-SOURCE.md](./SPEC-SOURCE.md) for provenance fields, contract
+  lifecycle, review state, and drift commands.
+- Read the component `SPEC.md`, `spec/source.json`, and all referenced React
+  Native companions before changing its contract.
 - Use `src/components/button` as the canonical higher-order implementation and `src/primitives/icon` as the canonical
   primitive.
 - Keep public props and slots small, typed, and spec-driven.
@@ -30,3 +36,6 @@ invariants; detailed authoring recipes live in the
   behind variables, spreads, functions, or computed values.
 - Use package scripts for format, lint, build, tests, and snapshots.
 - Do not copy web-only APIs, CSS behavior, or DOM assumptions into React Native.
+- Do not copy or mechanically transform private Flex skill bodies into this
+  public package. Record source identifiers and digests, then author the local
+  React Native contract.