@webex/contact-center 3.12.0-next.9 → 3.12.0-next.91

package/ai-docs/REVIEW_CHECKLIST.md

@@ -0,0 +1,41 @@
+# Review-Check Catalog — @webex/contact-center
+
+> Run by a runtime different from the generator. Findings remain drafts until explicitly published.
+
+## Core checks (always run)
+
+| # | Check | What it verifies | Severity if it fails |
+|---|---|---|---|
+| C1 | Spec-currency + WHAT/WHY | Specs/docs and code land together; every requirement states WHAT and WHY | Blocking |
+| C2 | Contract correctness | Provides/Requires and public API/event/type deltas are complete | Blocking |
+| C3 | Code-vs-spec match | Signatures, flows, states, timeouts, and architecture match code | Blocking |
+| C4 | Test adequacy | Positive/negative cases and 85% package threshold | Important |
+| C5 | Error handling/input validation | Structured failures, tracking ids, validation, no swallowed errors | Important |
+| C6 | Security baseline | Host auth, no secrets/sensitive logs, safe transport mapping | Blocking |
+
+## Coverage-conditional checks (run by the touched module's manifest coverage state)
+
+| # | Check | When it applies | What it verifies | Severity |
+|---|---|---|---|---|
+| K1 | Regression guard | Partial module or modified/removed guarantee | Characterization and invariants | Blocking |
+| K2 | Grounding | Partial module | Stable file-path evidence; code cross-check | Important |
+| K3 | Drift threshold | Any tracked module | Drift remains within policy | Important |
+| K4 | Coverage-state accuracy | Promotion/demotion | Status matches evidence | Medium |
+
+## Cross-cutting checks
+
+| # | Check | What it verifies | Severity |
+|---|---|---|---|
+| X1 | Cross-runtime review | Validator differs from Codex generator | Blocking |
+| X2 | Observability | LoggerProxy/metrics adequate; no sensitive logging | Medium |
+| X3 | Rollout safety | Defaults, compatibility, rollback/recovery safe | Important |
+
+## How the set is selected
+
+1. Run all six core checks.
+2. Add K1–K4 for current Partial modules.
+3. Add X1–X3 for high-risk, contract, security, state, transport, or autonomous changes.
+
+## Output
+
+- Compliance matrix, severity-sorted findings, and Pass / Pass-with-warnings / Blocked verdict. Draft only.

package/ai-docs/RULES.md

@@ -0,0 +1,444 @@
+# 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.
+
+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
+
+## 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.
+
+- 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
+
+| 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` |
+
+- 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
+
+All public methods and types must have comprehensive JSDoc:
+
+Use `@private` or `@ignore` tag:
+
+```typescript
+/**
+ * Internal utility function.
+ * @private
+ * @ignore
+ */
+private helperMethod(): void {
+  // implementation
+}
+```
+
+```typescript
+/**
+ * Description of what this type represents.
+ * @public
+ */
+export type MyType = {
+  /** Description of this field */
+  fieldName: string;
+  /** Optional field description */
+  optionalField?: number;
+};
+```
+
+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;
+```
+
+- **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
+import LoggerProxy from '../../logger-proxy';
+
+LoggerProxy.info('Starting operation', {
+  module: 'ModuleName',
+  method: 'methodName',
+});
+```
+
+| 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 |
+
+| Level | Use Case | Example |
+|---|---|---|
+| `error` | Failures | API errors, exceptions |
+
+```typescript
+// All log calls MUST include module and method
+{
+  module: 'FileName',      // Required: Class/file name
+  method: 'methodName',    // Required: Current method name
+  trackingId?: string,     // Optional: Request correlation ID
+  interactionId?: string,  // Optional: Task/call ID
+  data?: object,           // Optional: Additional context
+  error?: Error,           // Optional: Error object for error logs
+}
+```
+
+Never log sensitive data:
+
+```typescript
+// ❌ WRONG
+LoggerProxy.log(`User token: ${token}`);
+
+// ✅ CORRECT
+LoggerProxy.log('Token received', {
+  module: 'Auth',
+  method: 'login',
+  // No sensitive data in logs
+});
+```
+
+## 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';
+import {Failure} from './services/core/GlobalTypes';
+
+try {
+  const result = await this.riskyOperation();
+  return result;
+} catch (error) {
+  const failure = error.details as Failure;
+  
+  // 1. Track failure metrics
+  this.metricsManager.trackEvent(
+    METRIC_EVENT_NAMES.OPERATION_FAILED,
+    MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure),
+    ['operational']
+  );
+  
+  // 2. Get detailed error (logs automatically)
+  const {error: detailedError} = getErrorDetails(
+    error,
+    'methodName',
+    'ModuleName'
+  );
+  
+  // 3. Throw augmented error
+  throw detailedError;
+}
+```
+
+```typescript
+// ❌ WRONG - silently swallowing errors
+try {
+  await riskyOperation();
+} catch (error) {
+  // doing nothing
+}
+
+// ✅ CORRECT - at minimum log the error
+try {
+  await riskyOperation();
+} catch (error) {
+  LoggerProxy.error(`Operation failed: ${error}`, {
+    module: 'ModuleName',
+    method: 'methodName',
+  });
+  throw error;
+}
+```
+
+## 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:
+
+```typescript
+// Access services through Services singleton
+this.services = Services.getInstance({
+  webex: this.$webex,
+  connectionConfig: this.getConnectionConfig(),
+});
+
+// Use services
+await this.services.agent.stationLogin({data});
+await this.services.config.getAgentConfig(orgId, agentId);
+```
+
+Agent/contact services use factory pattern:
+
+```typescript
+// services/agent/index.ts
+export default function routingAgent(routing: AqmReqs) {
+  return {
+    methodName: routing.req((p: {data: ParamType}) => ({
+      url: '/v1/endpoint',
+      host: WCC_API_GATEWAY,
+      data: p.data,
+      err: createErrDetailsObject,
+      method: HTTP_METHODS.POST,  // Optional, defaults to POST
+      notifSuccess: {
+        bind: {
+          type: CC_EVENTS.SUCCESS_EVENT,
+          data: {type: CC_EVENTS.SUCCESS_EVENT},
+        },
+        msg: {} as SuccessType,
+      },
+      notifFail: {
+        bind: {
+          type: CC_EVENTS.FAIL_EVENT,
+          data: {type: CC_EVENTS.FAIL_EVENT},
+        },
+        errId: 'Service.aqm.agent.methodName',
+      },
+    })),
+  };
+}
+```
+
+1. External packages (`@webex/*`, `events`, `uuid`)
+
+2. Internal absolute imports (types, constants)
+
+3. Relative imports (local files)
+
+```typescript
+// 1. External
+import {WebexPlugin} from '@webex/webex-core';
+import EventEmitter from 'events';
+import {v4 as uuidv4} from 'uuid';
+
+// 2. Internal types/constants
+import {WebexSDK, CCPluginConfig, AgentLogin} from './types';
+import {READY, CC_FILE, METHODS} from './constants';
+
+// 3. Relative imports
+import Services from './services';
+import LoggerProxy from './logger-proxy';
+import {getErrorDetails} from './services/core/Utils';
+```
+
+- 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.
+
+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).
+
+## 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
+
+## 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.
+
+## 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
+// 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']
+);
+```
+
+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';
+
+// ✅ CORRECT
+this.emit(AGENT_EVENTS.AGENT_STATE_CHANGE, eventData);
+
+// ❌ WRONG
+this.emit('stateChange', eventData);
+```
+
+Always use async/await over raw Promises:
+
+```typescript
+// ✅ CORRECT
+public async fetchData(): Promise<Data> {
+  const result = await this.service.getData();
+  return result;
+}
+
+// ❌ AVOID (when possible)
+public fetchData(): Promise<Data> {
+  return this.service.getData().then(result => result);
+}
+```
+
+Always clean up resources:
+
+```typescript
+public async deregister(): Promise<void> {
+  // Remove event listeners
+  this.taskManager.off(TASK_EVENTS.TASK_INCOMING, this.handleIncomingTask);
+  this.services.webSocketManager.off('message', this.handleWebsocketMessage);
+  
+  // Close connections
+  if (!this.services.webSocketManager.isSocketClosed) {
+    this.services.webSocketManager.close(false, 'Reason');
+  }
+  
+  // Clear state
+  this.agentConfig = null;
+}
+```
+
+## 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.
+
+## 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 |