# Framework Reference Policy

Pinned framework references provide deterministic local guidance for AI and
operator work. Use them before browsing during normal implementation.

## Use Order

1. Read the relevant local reference bundle:
   - frontend: `ai/references/frontend-frameworks/`
   - backend/runtime: `ai/references/backend-frameworks/`
2. Use the repo standards that point to those references:
   - Angular/UI: `ai/standards/angular.md`, `ai/standards/ui-review.md`
   - Nest/backend: `ai/standards/nest.md`
   - Runtime/Node/TypeScript: `ai/standards/runtime-sop.md`
3. Run the reference validator when changing the reference bundle or framework
   standards:

```sh
yarn references:validate
```

4. Browse official documentation only when:
   - the pinned reference is missing;
   - the task is version-sensitive;
   - a dependency version changed;
   - the chunk explicitly asks for latest/current framework guidance.

## Refresh Rule

Refresh pinned references deliberately with:

```sh
node ai/references/scripts/fetch-framework-references.mjs
```

After refresh, review the diff before relying on changed guidance. Do not treat
latest remote documentation as canonical until the repo copy is updated or the
chunk explicitly records a latest-docs exception.

## Selector And UI Proof Rule

UI tests may use stable `data-testid` attributes or accessibility-owned labels.
Production behavior must not depend on test selectors. Runtime Action Panel
truth must come from Runtime/backend-owned GraphQL state, not DOM scraping or
socket payloads.