@exellix/ai-tasks 7.8.0

package/documenations/bug-report-xynthesis-and-synthesis-call.md

@@ -0,0 +1,217 @@
+# Bug report bundle: `@exellix/xynthesis` + `@exellix/ai-tasks` (synthesis / `runSynthesisCall`)
+
+> **Superseded (xynthesis ≥ 3.6):** `runSynthesisCall` was removed upstream; ai-tasks now uses **`executeXynthesisAction`** (`ExecuteXynthesisActionRequest`). See [BREAKING-CHANGES.md](../BREAKING-CHANGES.md).
+
+Use this document to open **GitHub issues** (xynthesis repo vs ai-tasks repo) or as an internal RCA. Each section is written so you can paste the **Issue** block into a tracker.
+
+**Thread coverage (everything we discussed maps here):**
+
+| Topic | Where |
+|--------|--------|
+| Failures: `flattenRunSynthesisCallRequest` / `systemPrompt` undefined; flat vs nested API | **§A** |
+| Root cause: **ai-tasks** still used legacy flat `runSynthesisCall` args after xynthesis 3.5+ nested contract | **§A** |
+| Why “synthesis” / **Xynthesis** naming and overload of `runSynthesisCall` | **§B** |
+| “We don’t pass prompts—we pass catalog / skill refs” vs reality (resolution in ai-tasks today) | **§C** + **Target** |
+| **Target API:** `actionId` + pre/post phase, **identity** object (not “workScope” as product term), **`config`** for model/tokens/timeout, **one** host entrypoint, xynthesis resolves content | **Target** (top) |
+| E2E: **resolved model id** required | **§D** |
+| Finalize warnings; **`missinngFields`** typo | **§E** |
+| Activix owner, sidekick `trim`, required `jobId`/`taskId` types | **§F** → checklist |
+| Paste-ready GitHub titles | Bottom list |
+
+---
+
+## Target: one clear AI-call contract (what we want vs what exists)
+
+This section states the **intended** host-facing shape for “do an LLM hop through Xynthesis,” independent of today’s split between `runSynthesisCall`, sidekick gateway calls, and ai-tasks template resolution.
+
+### What we need (desired)
+
+1. **Single logical identifier for the step**  
+   - Today you might think in terms of **`preActionId`** vs **`postActionId`**.  
+   - **Unify** to one field, e.g. **`actionId`**, plus an explicit **phase**: **`"pre" | "post"`** (or an enum).  
+   - Xynthesis (or a thin resolver next to it) uses **`actionId` + `phase`** to know **which catalog row / template bundle / evaluator** applies—**not** the caller shipping full system/user prompt text as the primary input.
+
+2. **Runtime identity is not “workScope” in product language**  
+   - Callers pass one **`identityObject`** (or keep the name **`identity`**): the **runtime correlation / run-context** object (session, job, task, agent, correlation ids, skill linkage—whatever the pipeline already carries).  
+   - **Internally**, Activix / gateway may still map subsets of this to `jobId` / `taskId` / `runContext`; that is an **implementation detail**. The **public** story should be: “here is the **identity object** for this call,” not “here is workScope” as the mental model for product engineers.
+
+3. **All LLM knobs live under `config`**  
+   - **`model`**, **`maxTokens`** (and caps), **`timeoutMs`**, **`maxOutputLength`**, **`temperature`**, **`topP`**, **`outputExpectation`**, etc. should be grouped in a single **`config`** object on the request, not scattered as top-level siblings mixed with identity and action selection.
+
+4. **One primary entrypoint for “AI calls” from hosts**  
+   - However many modules exist inside `@exellix/xynthesis` today, **hosts (e.g. ai-tasks) should converge on one documented function** for: *given **action** + **phase** + **identity** + **config**, resolve prompts from the registry and invoke the gateway.*  
+   - Optional escape hatch: **`overrides.prompts`** only for tests or extraordinary cases—not the default path.
+
+**Illustrative target shape (conceptual TypeScript, not implemented):**
+
+```ts
+runXynthesisAiAction({
+  actionId: string;           // catalog / strategy id for this pre or post step
+  actionPhase: "pre" | "post";
+  identity: IdentityObject; // full runtime correlation object (see above)
+  config: {
+    model?: string;
+    maxTokens?: number;
+    timeoutMs?: number;
+    maxOutputLength?: number;
+    temperature?: number;
+    topP?: number;
+    outputExpectation?: OutputExpectation;
+    // …
+  };
+  /** Optional: variables merged into resolved templates (record, web snippets, etc.) */
+  templateContext?: Record<string, unknown>;
+  /** Optional: gateway wire ids if not derived from `identity` */
+  gateway?: Partial<SynthesisCallGatewayContext>;
+});
+```
+
+Xynthesis (or a dedicated resolver it calls) is responsible for: **`(actionId, actionPhase)` → load template / instructions → build prompts → call invoker** using **`config`** and **`identity`** for logging and gateway requests.
+
+### What we have today (reality)
+
+| Area | Today |
+|------|--------|
+| **Entrypoints** | Multiple: **`runSynthesisCall`**, **`runSidekickGatewayCall`**, **`runStructuredSynthesisGatewayCall`**, finalize/repair paths, etc. Hosts must learn several shapes. |
+| **Prompt source** | **Callers often materialize** `systemPrompt` / `userPrompt` (or `renderedInstructions` / `renderedPrompt`) **before** Xynthesis. Catalog/skill resolution for ai-tasks lives largely in **ai-tasks** (`skillKey`, `resolveRawTemplate`, `getRenderedTemplates`), not behind a single **`actionId`** API in Xynthesis. |
+| **Identity** | **`workScope`** + **`gateway`** on `RunSynthesisCallRequest`: `workScope.jobId` / `taskId` / optional `identity`, plus separate **`gateway`** `{ aiRequestId, agentId, sessionId, temperature }`. Product-wise this splits “who/where” across two buckets. |
+| **Config** | **`model`**, **`timeoutMs`**, **`maxTokens`**, **`maxOutputLength`**, **`topP`**, **`outputExpectation`** are **top-level** fields on `RunSynthesisCallRequest` (and duplicated patterns elsewhere)—not grouped under a single **`config`**. |
+| **Pre vs post** | Expressed indirectly (different code paths, step types, env prefixes like `SYNTHESIS` vs `POST_STEP_*`), not as **`actionId` + `actionPhase`**. |
+
+### What we need to do (gap closure)
+
+| Step | Owner | Note |
+|------|--------|------|
+| Specify **catalog binding**: how **`actionId`** maps to rows (Catalox catalog id? strategy key? composite key including app id). | Architecture | Without this, Xynthesis cannot “know where to look.” |
+| Either **implement resolution inside Xynthesis** or **define a single resolver interface** (injected) that Xynthesis calls so the **host does not pass raw prompts** on the default path. | Xynthesis (+ ai-tasks) | Pure ai-tasks-only resolver preserves one package boundary but does not unify “one Xynthesis entry” unless Xynthesis exports the façade. |
+| Introduce **`runXynthesisAiAction`** (name TBD) that maps internally to today’s invoker + Activix, and **deprecate** scattered public shapes over time. | Xynthesis | Reduces host cognitive load; internal adapter can build `RunSynthesisCallRequest` for a transition period. |
+| Refactor **ai-tasks** to pass **`actionId` + `actionPhase` + `identity` + `config`** into that façade; keep **`skillKey`** and pipeline context on **`identity`** or **`templateContext`** as needed. | ai-tasks | Aligns runtime with this document. |
+| Document that **`workScope`** in low-level types is the **wire/Activix projection** of **`identity`**, not the product name for the object. | Docs | Reduces “it isn’t workScope” confusion. |
+
+### Feasible ways to get there (short list)
+
+1. **Facade in Xynthesis (preferred for “one thing”)** — New API resolves **`actionId` + `phase`** via Catalox/skills client injected at init; builds prompts; calls existing invoker. Legacy APIs remain as `@deprecated` wrappers.  
+2. **Facade in ai-tasks only** — Faster locally, but **does not** give “Xynthesis knows where to look” as a package guarantee; Xynthesis stays low-level.  
+3. **Hybrid** — Xynthesis exports the unified **`runXynthesisAiAction`** signature; default implementation delegates template fetch to a callback registered by ai-tasks (inversion of control), still one host call site.
+
+---
+
+## A. What is the *actual* `runSynthesisCall` API? (not the flat shape)
+
+**Answer for engineers:** The **only** supported input type is `RunSynthesisCallRequest` — **nested** `gateway`, `prompts`, and `workScope`. The package’s own `.d.ts` states: *“This is the only supported input shape for `runSynthesisCall`.”*
+
+**Correct shape (conceptual):**
+
+```ts
+runSynthesisCall({
+  gateway: {
+    aiRequestId: string,
+    agentId: string,
+    sessionId: string,
+    temperature: number,
+  },
+  prompts: {
+    systemPrompt: string,
+    userPrompt: string,
+  },
+  workScope: {
+    jobId: string,
+    taskId: string,
+    identity?: ActivityRunContext,
+  },
+  model?: string | OpenRouterModel | ModelPick,
+  timeoutMs?: number,
+  maxTokens?: number,
+  // …see `RunSynthesisCallRequest` in `@exellix/xynthesis`
+});
+```
+
+**Legacy / wrong shape (still seen in some consumers):**
+
+```ts
+// NOT supported — was never the typed public contract after the nested migration
+runSynthesisCall({
+  systemPrompt,
+  userPrompt,
+  jobId,
+  taskId,
+  agentId,
+  ...
+});
+```
+
+Passing the flat object makes `flattenRunSynthesisCallRequest` read `r.prompts.systemPrompt` when `prompts` is missing → **`TypeError: Cannot read properties of undefined (reading 'systemPrompt')`**.
+
+**Where this showed up:** ai-tasks **`npm test`** — multiple failures under **`intermediateSteps`** (and any path using **`runPostStepLlmCall`** → **`runSynthesisCall`**) with that stack trace; not a bug in “reading templates” inside xynthesis flatten—it is **missing `prompts` on the request object**.
+
+| Repo        | Issue type | Action |
+|------------|------------|--------|
+| **ai-tasks** | Defect     | Migrate all `runSynthesisCall` call sites to `RunSynthesisCallRequest` (e.g. `runPostStepLlmCall.ts`). |
+| **xynthesis** | DX / compat (optional) | At runtime, detect flat legacy objects and either adapt or throw a **single clear error** (“use `prompts` + `workScope` + `gateway`”). |
+
+---
+
+## B. Why is it called *synthesis* (and the package *Xynthesis*)?
+
+- **English domain term:** In this product line, “synthesis” means **combining multiple sources** (Narrix, memory, web evidence, templates) into a **unified context** before or alongside LLM steps. The Greek root is σύνθεσις → English **synthesis** (standard spelling: **s-y-n-t-h-e-s-i-s**).
+- **Package name `xynthesis`:** Branding (leading **X**) on the same concept; it is not a different technical term.
+- **Naming overload (real confusion):** `runSynthesisCall` is also used for **any** single completion that goes through the same invoker path (e.g. audit / polish / question-driven PRE calls in ai-tasks). So the name reads like “only context synthesis,” but operationally it is **“one gateway-backed LLM completion with synthesis-style telemetry/config.”** That overload is a **documentation and API naming** problem, not a typo.
+
+**Suggested upstream issue (xynthesis):** Document in JSDoc that `runSynthesisCall` is the **generic single-hop LLM invoke** for the package; optionally alias or document `runGatewayLlmCall` / similar in a future major if you want clearer vocabulary.
+
+---
+
+## C. Product expectation: “catalog id only, never materialized prompts”
+
+**Observation:** `@exellix/xynthesis` does **not** expose a first-class API of the form “Catalox catalog id + row id → fetch template → invoke.” Template/skill resolution for **ai-tasks** happens **before** xynthesis (e.g. `skillKey`, `resolveRawTemplate`, `getRenderedTemplates`), then **materialized** `systemPrompt` / `userPrompt` (or sidekick `renderedInstructions` / `renderedPrompt`) are passed in.
+
+**This is architectural layering**, not necessarily a bug—unless the product mandate is that **no** layer below the catalog resolver may accept prompt strings. If that mandate is firm:
+
+| Repo        | Issue |
+|------------|--------|
+| **xynthesis** (feature) | Optional higher-level entry: accept **skill/catalog handles** and delegate resolution (or document explicitly that resolution is **out of scope**). |
+| **ai-tasks** (docs) | State clearly: “xynthesis executes; ai-tasks + skills resolve templates.” |
+
+---
+
+## D. Resolved model id required (`runSynthesisCall requires a resolved model id`)
+
+**Symptom:** E2E / real gateway tests fail with  
+`Error: runSynthesisCall requires a resolved model id (set model on the request or use a strategy pick that maps to a concrete model).`
+
+**Classification:** Expected when **`model`** is omitted and no strategy/env resolves one. Fix is **callers/tests/env** (`SYNTHESIS_MODEL`, `LLM_MODEL_*`, or explicit `model` on the request), unless xynthesis intentionally guarantees a default (today it does not).
+
+| Repo     | Action |
+|----------|--------|
+| **ai-tasks** | Ensure E2E sets a resolvable model when the test is not skipped. |
+| **xynthesis** (DX) | Optionally document default resolution order in one place. |
+
+---
+
+## E. Finalize / work-scope warnings and log typo
+
+**Symptom:** Warnings such as missing `jobId` / `taskId` on `runXynthesisFinalize` when test payloads omit work scope.
+
+**Symptom:** Log field typo **`missinngFields`** (double **n**) in warning payloads — hurts grep and professionalism.
+
+| Repo        | Action |
+|------------|--------|
+| **xynthesis** | Fix typo `missinngFields` → `missingFields` (consider backward compat if anything parses logs). |
+| **ai-tasks / tests** | Pass `jobId` / `taskId` into finalize in tests where the contract requires them. |
+
+---
+
+## F. Related items already tracked in-repo
+
+See [`xynthesis-upstream-fixes-checklist.md`](./xynthesis-upstream-fixes-checklist.md) for Activix `diagnostics.owner`, `runSidekickGatewayCall` `.trim()` on undefined ids, and TypeScript required `jobId`/`taskId` on structured params.
+
+---
+
+## Paste-ready issue titles (suggested)
+
+1. **xynthesis:** `runSynthesisCall`: validate request shape / deprecate flat args with clear error (avoid `TypeError` on `prompts.systemPrompt`).
+2. **xynthesis:** Document that `runSynthesisCall` is the generic single-hop LLM API; clarify “synthesis” vs audit/polish use cases.
+3. **xynthesis:** Fix typo `missinngFields` in finalize / warning metadata.
+4. **ai-tasks:** Migrate `runPostStepLlmCall` (and any other callers) to `RunSynthesisCallRequest` + full `SynthesisCallGatewayContext`.
+5. **ai-tasks:** E2E synthesis: require resolvable `model` or skip with explicit reason (align with env docs).
+6. **xynthesis (+ ai-tasks):** Design and implement a **single host-facing LLM entry** (`actionId` + `pre`/`post` phase, **`identity` object**, **`config`** blob, resolver for catalog content); deprecate multiple parallel public shapes over time.

package/documenations/core-runtime-tokens-and-strategies.md

@@ -0,0 +1,123 @@
+# Core Token and Strategies
+
+This document explains two "core" topics in `@exellix/ai-tasks`:
+
+1. Token-related fields and behavior in the task runtime.
+2. Execution strategy behavior (legacy strategy layer and current core path).
+
+## 1) Core token behavior
+
+In this codebase, token-related behavior appears in three practical places:
+
+- **Template tokens** (`templateTokens`) for prompt rendering overlays.
+- **AI scoping tokens** (`aiScoped[].token`) for scoped enrichment labels.
+- **Model usage** metadata on third-party responses where applicable (observability only; not used for strategy selection).
+
+### 1.1 Template tokens (`templateTokens`)
+
+`RunTaskRequest` supports `templateTokens` and `templateRenderOptions` and passes them downstream to skill execution.
+
+- Purpose: override/overlay render-time template values for a single invoke.
+- Scope: per `runTask` call.
+- Precedence: intended as top-priority overlay during template rendering (gateway side).
+
+Related request fields:
+
+- `templateRenderOptions`
+- `templateTokens`
+
+Where it matters:
+
+- `runTask` builds `enrichedInput` and forwards request fields to executor.
+- DIRECT execution ultimately calls skills/gateway path where templates are rendered.
+
+### 1.2 AI scoping tokens (`aiScoped[].token`)
+
+When `input.aiScoping` is present, `runTask` executes AI scoping and injects results into task input:
+
+- Field injected into input: `input.aiScoped`
+- Shape: array of `{ token, scopedInfo }`
+- Meaning:
+  - `token`: label/key for a scoped target
+  - `scopedInfo`: generated scoped context text
+
+This is token-like labeling for downstream prompts/logic, not provider token counting.
+
+## 2) Core execution path vs strategy layer
+
+There are two layers in the repo:
+
+- **Core runtime path** in `src/core/task-sdk.ts` (canonical behavior).
+- **Strategy abstraction** in `src/strategies/*` (factory + direct strategy).
+
+### 2.1 Canonical runtime branch logic (current behavior)
+
+`WorexClientTasks.runTask()` in `src/core/task-sdk.ts` is the primary orchestrator:
+
+1. Early **`resolveRunTaskRuntimeKnobs`**: `narrixMode` (`off` \| `preprocessor` \| `handler`), `inputStrategyKey` (defaults `no-narrative`, not inferred from Narrix), and validated **`executionStrategies`** (required array; `[]` = plain MAIN).
+2. Optional Narrix **preprocessor** when `narrixMode === "preprocessor"` and `request.narrix` (record path + optional web scope after Narrix).
+3. Optional structured Narrix **handler** when `narrixMode === "handler"` (set explicitly, or inferred when only `narrixInput` is present without `request.narrix`).
+4. Local task short-circuit (`getLocalTask(skillKey)`).
+5. Optional `executionPipeline` (**PRE** Xynthesis steps → **MAIN** → **POST**). PRE receives the post–Narrix / post–web request state.
+6. MAIN execution via **`runMainWithExecutionStrategies`**: optional FuncX **planner** chain (once each, sorted by `priority`), then **`runDirect`** / `_executeDirect`; optional **optimizer** loop retries MAIN until satisfied or `maxIterations`.
+
+This is the main production flow for memory enrichment, context generation, ai scoping, and executor invocation.
+
+### 2.2 Strategy abstraction (`src/strategies`)
+
+The strategy layer defines an extensible interface:
+
+- `IExecutionStrategy`:
+  - `execute(request)`
+  - `getType()`
+  - `canHandle(request)`
+
+`ExecutionStrategyFactory` currently:
+
+- Registers the direct strategy under the ai-skills `ExecutionType.DIRECT` key.
+- Picks the first strategy whose `canHandle(request)` is true (today: when `executionStrategies` is an array — convenience **`executeDirect`** passes `[]`).
+
+`DirectExecutionStrategy` currently:
+
+- Sets `executionType: DIRECT` on the **`RunSkillRequest`** sent to ai-skills.
+- Converts `RunTaskRequest` to `RunSkillRequest` shape.
+- Calls `skillsClient.runSkill()`.
+
+## 3) How strategy and core fields interact
+
+### 3.1 `executionStrategies`
+
+- **Required** array on **`RunTaskRequest`**: **`planner`** rows (`phase: "before"`) and **`optimizer`** rows (`phase: "after"`), each with **`priority`**. **`[]`** means plain MAIN (no FuncX wrappers).
+- Resolved and sorted in **`resolveExecutionStrategies`** (called from **`resolveRunTaskRuntimeKnobs`**).
+
+### 3.2 `executionPipeline`
+
+- Preferred orchestration path when provided.
+- Requires exactly one MAIN step.
+- PRE supports `synthesized-context`.
+- POST supports `audit` and `polish`.
+
+### 3.3 `coreSkillId`
+
+`coreSkillId` is a graph/runtime identity field (node identity mapping), not a token field.
+
+- In direct strategy helper, it may map to `skillId` for skills compatibility.
+- In core runtime, identity fields (`graphId`, `nodeId`, `coreSkillId`, etc.) are passed for tracking/context.
+
+## 4) Practical guidance
+
+- Use `templateTokens` when you need per-invocation template overrides.
+- Use `aiScoping` when you need scoped context fragments (`aiScoped[].token`/`scopedInfo`).
+- Prefer `executionPipeline` for multi-step flows.
+- Use `narrixMode` + `narrixInput` / `narrix` instead of any legacy execution-type label on `RunTaskRequest`.
+- Treat strategy classes as extension points; treat `task-sdk.ts` as canonical behavior source.
+
+## 5) Related files
+
+- `src/core/task-sdk.ts`
+- `src/types/task-types.ts`
+- `src/strategies/execution-strategy.interface.ts`
+- `src/strategies/strategy-factory.ts`
+- `src/strategies/direct-execution-strategy.ts`
+- `src/methods/convenience-methods.ts`
+- `src/execution-strategies/*`

package/documenations/downstream-environment.md

@@ -0,0 +1,48 @@
+# Downstream Environment
+
+This appendix summarizes env ownership between `@exellix/ai-tasks` and downstream layers.
+
+## Env read directly by ai-tasks
+
+Common examples used directly in this package:
+
+- `MONGO_LOGS_DB`
+- `SYNTHESIS_MODEL`
+- `SYNTHESIS_TIMEOUT_MS`
+- `SYNTHESIS_MAX_OUTPUT_LENGTH`
+- `SYNTHESIS_TEMPLATES_PATH`
+- `POST_STEP_MODEL`
+- `POST_STEP_TIMEOUT_MS`
+- `AUDIT_*` and `POLISH_*` post-step settings
+- `USE_NARRIX_INGEST`
+- `NARRIX_DEBUG`
+- `TAVILY_API_KEY`
+- `WEB_CONTEXT_MARKDOWN_MAX_CHARS`
+- `ACTIVIX_*`
+
+## Env used downstream (via ai-skills/gateway/providers)
+
+Examples typically consumed by downstream services/libraries:
+
+- `OPENAI_API_KEY`, `GROK_API_KEY`
+- `OPEN_ROUTER_KEY` / `OPENROUTER_API_KEY`
+
+## Xynthesis / Mongo / Activix
+
+- Telemetry and registry requirements: [`xynthesis-activix-telemetry.md`](./xynthesis-activix-telemetry.md)
+- **Upstream fix and test checklist** (xynthesis repo): [`xynthesis-upstream-fixes-checklist.md`](./xynthesis-upstream-fixes-checklist.md)
+
+Other downstream examples:
+
+- `GITHUB_TOKEN`, `GITHUB_REPO_URL`
+- Mongo collection-level activity settings from tracking libs
+
+## Practical rule
+
+- Configure provider/content env vars for downstream execution.
+- Configure ai-tasks env vars for orchestration behavior (synthesis, post-steps, Narrix/web scope, activity tracking).
+
+## Related appendices
+
+- `documenations/web-scoping-in-ai-tasks.md`
+- `documenations/activix.md`

package/documenations/downstream-test-runtime-teardown-cleanup.md

@@ -0,0 +1,73 @@
+# Downstream Fix: Test/Runtime Teardown Cleanup (Open Handles)
+
+## Summary
+
+`@exellix/ai-tasks` feature behavior is working, but test/runtime process shutdown can be noisy or slow because downstream services may keep active handles after assertions complete.
+
+This is a **downstream lifecycle hygiene** issue (primarily in `@woroces/ai-skills` initialization/teardown), not a blocker for template core discovery functionality.
+
+## Observed Behavior
+
+- Functional tests pass assertions.
+- Node process can keep running longer than expected due to active resources.
+- Typical symptoms include long tail logs after tests are "done" and occasional CI timeout/hang patterns.
+
+## Likely Active Handles
+
+- MongoDB client pools/connections.
+- Activity tracking pipelines (Xronox/logging managers).
+- Timers/retry loops/background intervals.
+- Stream/event listeners that are never removed.
+
+## Why This Matters
+
+- Slower local feedback loops.
+- Flaky CI behavior (non-deterministic process exit).
+- Harder diagnosis when real failures are mixed with lifecycle noise.
+
+## Downstream Fix Scope (`@woroces/ai-skills`)
+
+## 1) Add explicit shutdown API
+
+Expose a deterministic cleanup method (name may vary), for example:
+
+- `await skillsClient.shutdown()`
+
+Expected responsibilities:
+
+- close DB clients and pools
+- stop timers/intervals/retries
+- flush/close activity/log pipelines
+- detach listeners/subscriptions
+
+## 2) Ensure idempotent cleanup
+
+- Calling shutdown multiple times should be safe.
+- Partial initialization should still allow shutdown without throwing.
+
+## 3) Add test-mode guardrails
+
+Provide config/env to avoid starting long-lived infra in unit tests when not required.
+
+Examples:
+
+- disable activity tracking in unit tests
+- disable external telemetry transports
+- lazy-init only when actually needed
+
+## 4) Wire teardown in test harness
+
+In integration/e2e tests that instantiate `WorecesSkillsClient`, ensure `after/afterEach` invokes cleanup.
+
+## Acceptance Criteria
+
+1. Test suites complete and process exits without manual interruption.
+2. No lingering DB/activity logs after final test summary.
+3. Repeated test runs do not increase leaked handles.
+4. CI job runtime is stable and no timeout due to open handles.
+
+## Notes for `@exellix/ai-tasks`
+
+- No additional feature-level change is required for template core discovery.
+- This document is tracked as downstream operational hardening only.
+

package/documenations/examples/xynthesis-run-task-request.example.json

@@ -0,0 +1,170 @@
+{
+  "skillKey": "skills/compliance/vendor-risk-quarterly-review",
+  "executionStrategies": [],
+  "executionPipeline": [
+    {
+      "phase": "pre",
+      "type": "synthesized-context",
+      "config": {
+        "contextSourcePolicy": "narrix-web-memory",
+        "synthesisInputStrategy": "policy",
+        "synthesisMode": "markdown",
+        "modelConfig": {
+          "model": "gpt-5-nano",
+          "temperature": 0.2
+        },
+        "timeoutMs": 45000,
+        "maxOutputLength": 12000,
+        "webEvidence": {
+          "preferCleanContent": true,
+          "maxSources": 5,
+          "dedupeByUrl": true,
+          "maxTotalChars": 24000
+        },
+        "customSynthesizingGuidelines": "Prefer cited facts from local memory and Narrix signals; treat web snippets as supporting only. Flag contradictions explicitly.",
+        "fallbackToDirect": false
+      }
+    },
+    {
+      "phase": "main",
+      "type": "direct"
+    }
+  ],
+  "includeContextInPrompt": true,
+  "jobId": "job_01k6f9a2b3c4d5e6f7g8h9i0",
+  "agentId": "agent_graph_runner_prod_east",
+  "graphId": "wf_vendor_due_diligence_v3",
+  "nodeId": "node_synthesis_gate_14",
+  "prevNodeId": "node_entity_resolver_13",
+  "coreSkillId": "skills/compliance/vendor-risk-quarterly-review",
+  "masterSkillId": "skills/compliance/vendor-due-diligence-pack",
+  "masterSkillActivityId": "act_8r2m1n0p9q8r7s6t",
+  "identity": {
+    "tenantId": "org_acme_security",
+    "workspaceId": "ws_governance_na",
+    "runPurpose": "quarterly_vendor_reassessment",
+    "requestedBy": "governance-console",
+    "correlationHint": "tkt-44821"
+  },
+  "variables": {
+    "reviewQuarter": "2026-Q1",
+    "priority": "P2",
+    "locale": "en-US"
+  },
+  "jobContext": {
+    "engagementCode": "VDR-2026-0142",
+    "policyPackVersion": "2025.12.1"
+  },
+  "input": {
+    "question": "Given current signals and open web mentions, should we escalate Acme Analytics from monitored to conditional approval for PHI-adjacent workloads?",
+    "vendorLegalName": "Acme Analytics LLC",
+    "vendorDuns": "123456789",
+    "dataClassificationsHandled": ["PHI", "PII"],
+    "deadlineIso": "2026-04-02T17:00:00.000Z"
+  },
+  "jobMemory": {
+    "engagement": {
+      "id": "VDR-2026-0142",
+      "openedAt": "2026-01-08T14:22:11.000Z",
+      "ownerTeam": "third_party_risk"
+    },
+    "vendorProfile": {
+      "displayName": "Acme Analytics",
+      "headquarters": "Austin, TX",
+      "lastAssessmentScore": 78,
+      "openFindingsCount": 3
+    },
+    "rawSummary": "Prior assessment (2025-Q4): SOC 2 Type II in scope; two medium findings on access reviews; one low on logging retention. Business sponsor: RevOps. Data flows: product analytics only — new request adds de-identified healthcare cohort exports (BA under review).",
+    "controlsMatrix": {
+      "encryptionAtRest": "AES-256-GCM",
+      "encryptionInTransit": "TLS1.2+",
+      "mfaAdminConsole": true,
+      "customerManagedKeys": false
+    }
+  },
+  "taskMemory": {
+    "previousFindings": [
+      {
+        "id": "fnd_91a",
+        "severity": "medium",
+        "title": "Quarterly access review evidence lagged 12 days"
+      }
+    ],
+    "narrix": [
+      {
+        "entity": {
+          "entityKind": "vendor",
+          "entityKey": "vendor_acme_analytics_llc"
+        },
+        "signals": [
+          {
+            "code": "SUBPROCESSOR_COUNT_DELTA",
+            "severity": "medium",
+            "observedAt": "2026-03-18T09:41:00.000Z",
+            "detail": "Net +2 subprocessors in last 60 days vs prior baseline."
+          },
+          {
+            "code": "INCIDENT_PUBLIC_MENTION",
+            "severity": "low",
+            "observedAt": "2026-03-21T16:05:00.000Z",
+            "detail": "Industry forum thread references a regional outage; vendor status page shows maintenance, not breach."
+          }
+        ],
+        "stories": [
+          {
+            "narrativeTypeId": "vendor-risk-summary",
+            "summary": "Overall posture stable; watch subprocessor churn and new data use cases touching regulated data."
+          }
+        ],
+        "meta": {
+          "datasetId": "vendor_risk_graph_prod",
+          "packVersion": "2026.03.0"
+        }
+      }
+    ]
+  },
+  "executionMemory": {
+    "bindingDefaultsDb": "logs-db",
+    "runAttempt": 1,
+    "priorStepOutputs": {
+      "entityResolution": {
+        "canonicalVendorId": "vendor_acme_analytics_llc",
+        "confidence": 0.94
+      }
+    },
+    "webContext": {
+      "available": true,
+      "context": {
+        "summary": "Recent public pages emphasize enterprise SLA tiers and a March 2026 maintenance window; no regulator or breach disclosures located in the retrieved set.",
+        "findings": [
+          "Vendor status blog documents planned DB failover practice on 2026-03-22.",
+          "Help center article states HIPAA BAA available for enterprise tier — pricing not public."
+        ],
+        "sources": [
+          {
+            "url": "https://status.acmeanalytics.example/incidents/2026-03-maintenance",
+            "title": "Scheduled maintenance — US-East analytics cluster",
+            "snippet": "Customers may see up to 15 minutes of read-only mode during failover rehearsal.",
+            "content": "Full maintenance notice: failover rehearsal for analytics cluster us-east-1. Read-only window expected 02:00–02:15 UTC. No customer data migration."
+          },
+          {
+            "url": "https://trust.acmeanalytics.example/compliance",
+            "title": "Trust & compliance overview",
+            "snippet": "SOC 2 Type II, HIPAA BAA for eligible contracts, subprocessors listed in annex C.",
+            "content": "We maintain SOC 2 Type II. HIPAA BAA is offered for enterprise agreements where regulated data is in scope. Subprocessor list updated monthly."
+          },
+          {
+            "url": "https://community.secforum.example/t/acme-analytics-outage-march-21/88421",
+            "title": "Thread: Acme Analytics latency spike",
+            "snippet": "Several users reported elevated latency; vendor attributed to maintenance overlap.",
+            "content": "Discussion thread — anecdotal reports only; links back to vendor status page for official narrative."
+          }
+        ]
+      }
+    }
+  },
+  "modelConfig": {
+    "model": "gpt-5.1",
+    "temperature": 0.1
+  }
+}