@webex/contact-center 3.12.0-next.84 → 3.12.0-next.85

package/ai-docs/RULES.md

@@ -1,74 +1,102 @@
-# Contact Center SDK - Coding Standards & Rules
+# Rules — @webex/contact-center
+
+> Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md). These rules are extracted from current package code and reviewed package documentation.
+
+## Coverage Map (which docs/specs to trust)
+| Module | Manifest coverage state | What it means here |
+|---|---|---|
+| `src` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
+| `src/metrics` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
+| `src/services` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
+| `src/services/agent` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
+| `src/services/config` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
+| `src/services/core` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
+| `src/services/task` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
+| `src/services/task/state-machine` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
+| `src/utils` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
+
+## Autonomy & Ask-First
+- **May proceed:** read-only inspection and approved low-risk documentation maintenance.
+- **Ask first / plan + confirm:** code changes, public contract changes, state-machine changes, security-sensitive work, or new dependencies.
+- **Never without explicit human approval:** push, publish, deploy, delete, or post externally.
 
-> **Purpose**: Defines the coding standards, conventions, and architectural rules that all code in `@webex/contact-center` must follow.
+Before submitting code:
 
----
+- [ ] All public APIs have JSDoc with `@public`, `@param`, `@returns`, `@example`
 
-## TypeScript Standards
+- [ ] LoggerProxy used for all logging with module/method context
+
+- [ ] MetricsManager tracks success/failure for all operations
+
+- [ ] Error handling follows `getErrorDetails` pattern
+
+- [ ] No `console.log` or `console.error`
+
+- [ ] No hardcoded credentials or sensitive data
+
+- [ ] Event constants used (not string literals)
+
+- [ ] Types exported appropriately
+
+- [ ] Unit tests added/updated
+
+- [ ] No `any` types without justification
+
+## Naming
+- Use PascalCase classes/files, camelCase methods, SCREAMING_SNAKE_CASE constants, and typed event constants from their owning module.
+
+> **Purpose**: Defines the coding standards, conventions, and architectural rules that all code in `@webex/contact-center` must follow.
 
-### Strict Mode
 - TypeScript strict mode is enabled
+
 - Avoid `any` type unless absolutely necessary (document justification with `// eslint-disable-line`)
+
 - Prefer `unknown` over `any` for unknown types
-- All public APIs must have explicit return types
 
-### Naming Conventions
+- All public APIs must have explicit return types
 
 | Element | Convention | Example |
-|---------|------------|---------|
+|---|---|---|
 | Classes | PascalCase | `ContactCenter`, `TaskManager` |
+
+| Element | Convention | Example |
+|---|---|---|
 | Interfaces | PascalCase with `I` prefix for contracts | `IContactCenter`, `ITask`, `IVoice` |
+
+| Element | Convention | Example |
+|---|---|---|
 | Types | PascalCase | `SetStateResponse`, `BuddyAgentsResponse` |
+
+| Element | Convention | Example |
+|---|---|---|
 | Enums/Constants | SCREAMING_SNAKE_CASE | `CC_EVENTS`, `METRIC_EVENT_NAMES` |
+
+| Element | Convention | Example |
+|---|---|---|
 | Methods | camelCase | `stationLogin`, `setAgentState` |
+
+| Element | Convention | Example |
+|---|---|---|
 | Private properties | camelCase with `$` prefix for SDK references | `$webex`, `$config` |
+
+| Element | Convention | Example |
+|---|---|---|
 | Regular private | camelCase | `agentConfig`, `eventEmitter` |
+
+| Element | Convention | Example |
+|---|---|---|
 | Module constants | SCREAMING_SNAKE_CASE | `CC_FILE`, `READY` |
 
-### File Naming
 - Component files: `PascalCase.ts` (e.g., `TaskManager.ts`, `WebSocketManager.ts`)
-- Type files: `types.ts` in service folders
-- Constant files: `constants.ts` in service folders
-- Index files: `index.ts` for exports
 
----
+- Type files: `types.ts` in service folders
 
-## JSDoc Standards
+- Constant files: `constants.ts` in service folders
 
-### Public APIs (MANDATORY)
+- Index files: `index.ts` for exports
 
 All public methods and types must have comprehensive JSDoc:
 
-```typescript
-/**
- * Brief description of what this does.
- *
- * @description
- * Longer description if needed with:
- * - Bullet points for features
- * - Multiple lines for clarity
- *
- * @param {ParamType} paramName - Description of the parameter
- * @returns {Promise<ReturnType>} Description of return value
- * @throws {Error} Description of when errors are thrown
- *
- * @public
- *
- * @example
- * ```typescript
- * const result = await cc.methodName({
- *   param: 'value',
- * });
- * console.log(result);
- * ```
- */
-public async methodName(data: ParamType): Promise<ReturnType> {
-  // implementation
-}
-```
-
-### Private/Internal APIs
-
 Use `@private` or `@ignore` tag:
 
 ```typescript
@@ -82,8 +110,6 @@ private helperMethod(): void {
 }
 ```
 
-### Type Definitions
-
 ```typescript
 /**
  * Description of what this type represents.
@@ -97,11 +123,24 @@ export type MyType = {
 };
 ```
 
----
+Add new events to `src/metrics/constants.ts`:
 
-## Logging Standards
+```typescript
+export const METRIC_EVENT_NAMES = {
+  // Existing events...
+  NEW_OPERATION_SUCCESS: 'new operation success',
+  NEW_OPERATION_FAILED: 'new operation failed',
+} as const;
+```
 
-### Always Use LoggerProxy
+- **TypeScript patterns**: [`patterns/typescript-patterns.md`](patterns/typescript-patterns.md)
+
+- **Testing patterns**: [`patterns/testing-patterns.md`](patterns/testing-patterns.md)
+
+- **Event patterns**: [`patterns/event-driven-patterns.md`](patterns/event-driven-patterns.md)
+
+## Logging
+- Use LoggerProxy with module/method context and tracking identifiers; never use console logging in implementation or log credentials/sensitive data.
 
 ```typescript
 // ✅ REQUIRED pattern
@@ -113,17 +152,25 @@ LoggerProxy.info('Starting operation', {
 });
 ```
 
-### Log Levels
-
 | Level | Use Case | Example |
-|-------|----------|---------|
+|---|---|---|
 | `trace` | Detailed debugging | Entry/exit of complex functions |
+
+| Level | Use Case | Example |
+|---|---|---|
 | `log` | General information | Operation completed successfully |
+
+| Level | Use Case | Example |
+|---|---|---|
 | `info` | Important milestones | Starting registration, login |
+
+| Level | Use Case | Example |
+|---|---|---|
 | `warn` | Potential issues | Deprecated usage, fallback behavior |
-| `error` | Failures | API errors, exceptions |
 
-### Logging Context (Required)
+| Level | Use Case | Example |
+|---|---|---|
+| `error` | Failures | API errors, exceptions |
 
 ```typescript
 // All log calls MUST include module and method
@@ -137,11 +184,22 @@ LoggerProxy.info('Starting operation', {
 }
 ```
 
----
+Never log sensitive data:
+
+```typescript
+// ❌ WRONG
+LoggerProxy.log(`User token: ${token}`);
 
-## Error Handling Standards
+// ✅ CORRECT
+LoggerProxy.log('Token received', {
+  module: 'Auth',
+  method: 'login',
+  // No sensitive data in logs
+});
+```
 
-### Standard Error Pattern
+## Error Handling
+- Preserve structured backend details and tracking ids through shared Core helpers; never swallow failures or synthesize success.
 
 ```typescript
 import {getErrorDetails} from './services/core/Utils';
@@ -172,8 +230,6 @@ try {
 }
 ```
 
-### Never Swallow Errors
-
 ```typescript
 // ❌ WRONG - silently swallowing errors
 try {
@@ -194,56 +250,8 @@ try {
 }
 ```
 
----
-
-## Metrics Standards
-
-### All Operations Must Track Metrics
-
-```typescript
-// Start timing at method entry
-this.metricsManager.timeEvent([
-  METRIC_EVENT_NAMES.SUCCESS_EVENT,
-  METRIC_EVENT_NAMES.FAILED_EVENT,
-]);
-
-// Track on success
-this.metricsManager.trackEvent(
-  METRIC_EVENT_NAMES.SUCCESS_EVENT,
-  {
-    ...MetricsManager.getCommonTrackingFieldForAQMResponse(response),
-    // Add operation-specific fields
-  },
-  ['behavioral', 'operational']
-);
-
-// Track on failure (in catch block)
-this.metricsManager.trackEvent(
-  METRIC_EVENT_NAMES.FAILED_EVENT,
-  {
-    ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure),
-  },
-  ['behavioral', 'operational']
-);
-```
-
-### Metric Event Naming
-
-Add new events to `src/metrics/constants.ts`:
-
-```typescript
-export const METRIC_EVENT_NAMES = {
-  // Existing events...
-  NEW_OPERATION_SUCCESS: 'new operation success',
-  NEW_OPERATION_FAILED: 'new operation failed',
-} as const;
-```
-
----
-
-## Service Architecture Standards
-
-### Singleton Pattern
+## Imports / Dependencies
+- External packages first, then package types/constants, service imports, local utilities, and type-only imports. New runtime dependencies require approval.
 
 Services use singleton pattern via `Services` class:
 
@@ -259,8 +267,6 @@ await this.services.agent.stationLogin({data});
 await this.services.config.getAgentConfig(orgId, agentId);
 ```
 
-### Service Factory Pattern
-
 Agent/contact services use factory pattern:
 
 ```typescript
@@ -292,53 +298,10 @@ export default function routingAgent(routing: AqmReqs) {
 }
 ```
 
----
-
-## Event Standards
-
-### Event Constant Objects
-
-Define events as const objects with `as const`:
-
-```typescript
-export const MY_EVENTS = {
-  SUCCESS: 'MySuccess',
-  FAILED: 'MyFailed',
-} as const;
-
-// Extract union type
-type Enum<T extends Record<string, unknown>> = T[keyof T];
-export type MY_EVENTS = Enum<typeof MY_EVENTS>;
-```
-
-### Event Emission
-
-Always use event constants:
-
-```typescript
-import {AGENT_EVENTS} from './services/agent/types';
-
-// ✅ CORRECT
-this.emit(AGENT_EVENTS.AGENT_STATE_CHANGE, eventData);
-
-// ❌ WRONG
-this.emit('stateChange', eventData);
-```
-
----
-
-## Testing Standards
-
-For full testing patterns including test file location, MockWebex setup, singleton mocking, LoggerProxy mocking, and test structure, see [`patterns/testing-patterns.md`](patterns/testing-patterns.md).
-
----
-
-## Import Standards
-
-### Import Order
-
 1. External packages (`@webex/*`, `events`, `uuid`)
+
 2. Internal absolute imports (types, constants)
+
 3. Relative imports (local files)
 
 ```typescript
@@ -357,44 +320,89 @@ import LoggerProxy from './logger-proxy';
 import {getErrorDetails} from './services/core/Utils';
 ```
 
-### Export Standards
-
 - Public types: Export from `src/types.ts`
+
 - Internal types: Export from service-level `types.ts`
+
 - Services: Use default export for main class, named exports for types
 
----
+## Testing
+- Mirror source paths under `test/unit/spec/`; cover positive and negative behavior and retain the 85% global coverage threshold.
 
-## Accessibility & Security
+For full testing patterns including test file location, MockWebex setup, singleton mocking, LoggerProxy mocking, and test structure, see [`patterns/testing-patterns.md`](patterns/testing-patterns.md).
 
-### No Hardcoded Credentials
+## Security
+- Credentials come from the host Webex SDK; validate inputs, use authenticated service routing, and follow `SECURITY.md`.
 
 Never commit:
+
 - API keys, tokens, secrets
+
 - Passwords or authentication data
+
 - Private keys or certificates
 
-### Sensitive Data Logging
+## Spec-Currency & Drift Thresholds
+- Update specs/docs in the same change as behavior, contracts, state, events, or public types.
+- Partial modules require code cross-checking and characterization before risky changes.
 
-Never log sensitive data:
+## Secrets Policy
+- No hardcoded secrets, tokens, keys, or connection strings; never log them.
+
+## Concurrency & Async
+- Preserve listener identity for cleanup, avoid blocking the event loop, maintain AQM correlation/timeouts, and keep metrics non-blocking.
 
 ```typescript
-// ❌ WRONG
-LoggerProxy.log(`User token: ${token}`);
+// Start timing at method entry
+this.metricsManager.timeEvent([
+  METRIC_EVENT_NAMES.SUCCESS_EVENT,
+  METRIC_EVENT_NAMES.FAILED_EVENT,
+]);
 
-// ✅ CORRECT
-LoggerProxy.log('Token received', {
-  module: 'Auth',
-  method: 'login',
-  // No sensitive data in logs
-});
+// Track on success
+this.metricsManager.trackEvent(
+  METRIC_EVENT_NAMES.SUCCESS_EVENT,
+  {
+    ...MetricsManager.getCommonTrackingFieldForAQMResponse(response),
+    // Add operation-specific fields
+  },
+  ['behavioral', 'operational']
+);
+
+// Track on failure (in catch block)
+this.metricsManager.trackEvent(
+  METRIC_EVENT_NAMES.FAILED_EVENT,
+  {
+    ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure),
+  },
+  ['behavioral', 'operational']
+);
+```
+
+Define events as const objects with `as const`:
+
+```typescript
+export const MY_EVENTS = {
+  SUCCESS: 'MySuccess',
+  FAILED: 'MyFailed',
+} as const;
+
+// Extract union type
+type Enum<T extends Record<string, unknown>> = T[keyof T];
+export type MY_EVENTS = Enum<typeof MY_EVENTS>;
 ```
 
----
+Always use event constants:
+
+```typescript
+import {AGENT_EVENTS} from './services/agent/types';
 
-## Performance Standards
+// ✅ CORRECT
+this.emit(AGENT_EVENTS.AGENT_STATE_CHANGE, eventData);
 
-### Async/Await
+// ❌ WRONG
+this.emit('stateChange', eventData);
+```
 
 Always use async/await over raw Promises:
 
@@ -411,8 +419,6 @@ public fetchData(): Promise<Data> {
 }
 ```
 
-### Cleanup on Deregistration
-
 Always clean up resources:
 
 ```typescript
@@ -431,25 +437,8 @@ public async deregister(): Promise<void> {
 }
 ```
 
----
-
-## Code Review Checklist
-
-Before submitting code:
-
-- [ ] All public APIs have JSDoc with `@public`, `@param`, `@returns`, `@example`
-- [ ] LoggerProxy used for all logging with module/method context
-- [ ] MetricsManager tracks success/failure for all operations
-- [ ] Error handling follows `getErrorDetails` pattern
-- [ ] No `console.log` or `console.error`
-- [ ] No hardcoded credentials or sensitive data
-- [ ] Event constants used (not string literals)
-- [ ] Types exported appropriately
-- [ ] Unit tests added/updated
-- [ ] No `any` types without justification
+## Strict-Compliance Mode
+- In rigorous SDD runs, stop on unresolved questionnaire facts, source-fidelity failures, template-conformance blockers, or validator findings. Generated specs require review by the manifest-configured independent runtime.
 
-## Need More Context?
-
-- **TypeScript patterns**: [`patterns/typescript-patterns.md`](patterns/typescript-patterns.md)
-- **Testing patterns**: [`patterns/testing-patterns.md`](patterns/testing-patterns.md)
-- **Event patterns**: [`patterns/event-driven-patterns.md`](patterns/event-driven-patterns.md)
+## Maintenance
+- Add a rule when a review correction recurs; remove duplication when tooling enforces it. Patterns remain in `patterns/`.

package/ai-docs/SECURITY.md

@@ -0,0 +1,52 @@
+# Security Baseline — @webex/contact-center
+
+> Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md).
+
+## Trust Boundaries
+
+| Boundary | Untrusted side | Trusted side | What is enforced at the crossing |
+|---|---|---|---|
+| Exported SDK methods | Host application input | ContactCenter/module methods | Typed inputs, runtime validation where implemented, typed errors |
+| REST construction | SDK data | Webex request/service routing | Host credentials, service identifier, method/path/payload mapping |
+| WebSocket parsing | Remote messages | ContactCenter/Task/AqmReqs | JSON parsing, event-type mapping, correlation/guards |
+| Logs/metrics | Runtime data | Remote observability systems | Context selection and no credential/sensitive-data logging |
+
+## Authentication & Authorization Model
+
+- **Authentication:** supplied and maintained by the host Webex SDK (`src/services/core/WebexRequest.ts`).
+- **Authorization:** remote WCC services enforce tenant/agent permissions; this package must not bypass host service routing.
+- **Default posture:** no standalone credentials or local authorization store.
+
+## Secret & Credential Handling
+
+- Secrets source and injection: host Webex SDK/runtime configuration; never source code.
+- Rotation: owned by the host credential system and remote services.
+- **Hard rule:** never commit or log secrets, tokens, keys, or connection strings.
+
+## Data Classification & Handling
+
+| Data class | Examples | Storage rule | Logging rule | In transit |
+|---|---|---|---|---|
+| Identity/PII | agent id/name/email, dial number | ephemeral client memory; remote system of record | do not log raw sensitive values | host-resolved HTTPS/WSS |
+| Interaction data | task/customer/call metadata | ephemeral task state; remote system of record | use tracking/interaction ids, minimize payloads | HTTPS/WSS/WebRTC |
+| Credentials | access tokens/service auth | host-owned only | never log | HTTPS/WSS |
+
+## Input Validation & Output Encoding Posture
+
+- Validate public inputs before request construction; use typed constants and endpoint builders; never concatenate credentials or executable commands.
+
+## Transport & Headers
+
+- Authenticated requests use the Webex SDK service catalog and HTTPS. Realtime traffic uses host-resolved WSS; header/environment behavior is owned by `src/services/core/WebexRequest.ts` and the host request layer.
+
+## Known Sensitive Areas & Accepted Risks
+
+| Area | Risk | Mitigation / why accepted | Owner |
+|---|---|---|---|
+| Log upload | Runtime context could contain sensitive values | Shared error helpers upload only approved diagnostic context; never add credentials/payload dumps | Contact Center maintainers |
+| WebSocket event parsing | Malformed/unexpected remote data | Parse defensively, map known event constants, ignore/reject invalid transitions | Core/Task maintainers |
+| Public dial/contact inputs | PII and external numbers | Validate and avoid logging raw values | Contact Center maintainers |
+
+## Reporting & Review
+
+- Security-sensitive changes require package-owner review and independent SDD validation. Report vulnerabilities through the repository's documented Cisco security/support process.

package/ai-docs/SERVICE_STATE.md

@@ -0,0 +1,48 @@
+# Service State (living) — @webex/contact-center
+
+> Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md). Read before adding a surface.
+
+## Current Events
+
+| Event / topic | Direction | Producer/consumer | Payload ref |
+|---|---|---|---|
+| `agent:*` | publish | ContactCenter → application | `src/services/agent/types.ts` |
+| `task:*` | publish | Task/TaskManager → application | `src/services/task/types.ts` |
+| `CC_EVENTS` | consume | WCC WebSocket → Core/ContactCenter/Task/AqmReqs | `src/services/config/types.ts` |
+| realtime transcript/suggestion | consume/publish | RTD WebSocket → owning Task | `src/services/task/TaskManager.ts` |
+
+## Data Stores
+
+| Store | Purpose | Owned by this service? |
+|---|---|---|
+| In-memory PageCache Map | temporary paginated lookup reuse | ephemeral only; yes for cache entries |
+| Remote WCC stores | agent/task/config domain state | no |
+
+## External Dependencies
+
+| Dependency | Used for | Timeout / retry | Circuit breaker / fallback |
+|---|---|---|---|
+| WCC API gateway | agent/task/config/data operations | operation/AQM timeouts | propagate structured failure |
+| WCC WebSocket/RTD | realtime events and completion | reconnect and recovery timers | reconnect/silent relogin/restore failure |
+| Webex Calling | BROWSER call lifecycle | async registration/call timeouts | emit/rethrow calling failure |
+| Webex metrics | telemetry | nonblocking queued submission | log/drop without breaking product flow |
+
+## Key Metrics & Performance Targets
+
+| Signal | Target | Where measured |
+|---|---|---|
+| Unit coverage | 85% branches/functions/lines/statements | package Jest configuration |
+| Operation duration/success/failure | no local numeric SLO routed | MetricsManager event taxonomy |
+| Connection recovery | explicit 8s disconnect, 5s retry, configured restore timeout | Core constants/ConnectionService |
+
+## Feature Flags (current)
+
+| Flag/config | Gates | Current default | Owner | Safe to remove when |
+|---|---|---|---|---|
+| `allowAutomatedRelogin` | silent relogin after recovery | config-defined | ContactCenter | replacement recovery contract exists |
+| `webRtcEnabled` / login option | browser calling path | remote profile | Config/WCC | remote contract removed |
+| task UI/config flags | task controls and operations | profile/config-defined | Task/Config | owning behavior removed |
+
+## Maintenance
+
+- Update the relevant row in the same change as any surface, dependency, timeout, metric, or flag.

package/ai-docs/SPEC_INDEX.md

@@ -0,0 +1,65 @@
+# Spec Index — @webex/contact-center
+
+> Start here → root [`AGENTS.md`](../AGENTS.md). This router mirrors `.sdd/manifest.json`; system overview: [`ARCHITECTURE.md`](ARCHITECTURE.md).
+
+## Module Registry
+
+| Module | Responsibility | Manifest coverage state | Start here |
+|---|---|---|---|
+| `src` | Own the published Webex Contact Center SDK plugin surface, registration lifecycle, public method delegation, and application-facing event routing. | Partial | `ai-docs/contact-center-spec.md` |
+| `src/metrics` | Own timing, taxonomy, queuing, payload preparation, and submission for Contact Center behavioral, operational, and business telemetry. | Partial | `src/metrics/ai-docs/metrics-spec.md` |
+| `src/services` | Own composition and bootstrap order for backend request, realtime, data, and WebRTC service collaborators. | Partial | `src/services/ai-docs/services-spec.md` |
+| `src/services/agent` | Own agent login, logout, state-change, buddy-agent, device-update, and silent-relogin request contracts. | Partial | `src/services/agent/ai-docs/agent-spec.md` |
+| `src/services/config` | Own retrieval and aggregation of remote organization, agent, team, profile, auxiliary-code, dial-plan, and feature configuration. | Partial | `src/services/config/ai-docs/config-spec.md` |
+| `src/services/core` | Own authenticated HTTP, realtime WebSocket lifecycle, AQM request correlation, reconnect/keepalive behavior, and shared error normalization. | Partial | `src/services/core/ai-docs/core-spec.md` |
+| `src/services/task` | Own task creation, media-specific behavior, call-control operations, lifecycle orchestration, task events, and integration with the task state machine. | Partial | `src/services/task/ai-docs/task-spec.md` |
+| `src/services/task/state-machine` | Own deterministic task lifecycle states, transition guards/actions, typed internal events, and state-derived UI-control availability. | Partial | `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` |
+| `src/utils` | Own shared pagination contracts and the bounded in-memory page cache used by Contact Center data services. | Partial | `src/utils/ai-docs/utils-spec.md` |
+
+## Task Routing
+
+| If the task is… | Load |
+|---|---|
+| Understanding the package | `ARCHITECTURE.md` |
+| Working in a module | That module's specification from the registry |
+| Changing exported APIs/events/types | `CONTRACTS.md`, Contact Center spec, and owning module spec |
+| Changing task state | Task and Task State Machine specs |
+| Changing transport/recovery | Core spec and `SECURITY.md` |
+| New feature or defect | Run lifecycle intake against the affected module specs |
+
+## Intake Routing
+
+```text
+New feature / bug / contract change → lifecycle intake questionnaire → feature spec/design
+New module → update module registry + module spec + contracts
+Doc/spec backfill → reconcile target → conformance → coverage → independent validation
+```
+
+## Incident History
+
+| INC id | Date | Module | One-line | Link |
+|---|---|---|---|---|
+| None routed | 2026-07-07 | N/A | No incident/RCA source was supplied during onboarding. | N/A |
+
+## Phase-Based Loading Protocol
+
+| Phase | Load |
+|---|---|
+| Orient | AGENTS.md + this file |
+| Specify | relevant module specs + questionnaire |
+| Build | selected module specs + RULES/patterns |
+| Verify | independent validation and coverage evidence |
+
+## Spec Registry
+
+| Doc | Location | Purpose |
+|---|---|---|
+| Patterns | `patterns/` | Existing implementation conventions |
+| Rules | `RULES.md` | Enforceable do/don't constraints |
+| Glossary | `GLOSSARY.md` | Domain language |
+| Security | `SECURITY.md` | Trust boundaries and sensitive-data rules |
+| Contracts | `CONTRACTS.md` | Public/export/event/dependency index |
+| Service state | `SERVICE_STATE.md` | Current as-built surfaces/dependencies/flags |
+| Getting started | `GETTING_STARTED.md` | Build/test loop |
+| Decision records | `adr/` | Durable architecture decisions |
+| Review catalog | `REVIEW_CHECKLIST.md` | Review gates |