@exellix/ai-tasks 9.1.0 → 10.0.0

package/.docs/upstream-issue/2026-03-21_woroces-ai-tasks_ISSUE-006_web-scope-question-from-cni-entity.md

@@ -1,46 +0,0 @@
-# ISSUE-006 — Render web-scope search question from Narrix entity / CNI (CVE, vendor, label)
-
-**Status:** Implemented in `@woroces/ai-tasks` (`src/narrix/buildWebScopeScopeInput.ts`, `narrix.*` config fields). See `documenations/web-scoping-in-ai-tasks.md` §3.2.1.
-
-**Issue:** ISSUE-006  
-**Package to fix:** `@woroces/ai-tasks`  
-**Date:** 2026-03-21  
-**Type:** Feature request  
-**Related index:** [`2026-03-21_worox-graphs_ISSUE-000_gap-analysis-index.md`](./2026-03-21_worox-graphs_ISSUE-000_gap-analysis-index.md)  
-**Complements:** [`2026-03-21_worox-graphs_ISSUE-008_enrich-web-scope-question-from-execution-input.md`](./2026-03-21_worox-graphs_ISSUE-008_enrich-web-scope-question-from-execution-input.md) (same problem, fix in executor)
-
----
-
-## Problem
-
-Web scoping uses a **generic** `inputs.question` (e.g. “What is the exploitability of this vulnerability?”) without embedding CVE id, vendor, or product from the current entity. Search queries stay broad; evidence is less targeted than it could be.
-
-`@woroces/ai-tasks` (or NARRIX pre-processing inside it) often has access to **CNI / entity facts** after Narrix runs — ideal place to render `baseQuestion + entityArgs` before calling the scoper.
-
----
-
-## Desired behavior
-
-1. Keep `questionId` / pack routing as today.
-2. Before `scopeGeneric` / internal web scope, compute `webScopeQuestion = render(template, { cve, vendor, label, ... })`.
-3. Pass that string into the scoper as the `question` argument.
-
----
-
-## Options (from prior design discussion)
-
-- **Downstream-heavy:** `ai-tasks` renders from `narrixResult.entity` / CNI (this issue).
-- **Executor-heavy:** `worox-graphs` enriches before scope (ISSUE-008). Both can coexist; prefer one owner to avoid double logic.
-
----
-
-## Acceptance criteria
-
-1. For vuln-group–style jobs, logged or asserted `queriesUsed` contains vulnerability-specific tokens (e.g. CVE id) when entity provides them.
-2. No regression when entity facts are missing (fallback to base question).
-
----
-
-## Longer design notes
-
-See also `.docs/web-scoping/feature-request-narrix-web-scope-question-templating.md` (narrative duplicate; **this ISSUE file is the canonical tracker name** for `@woroces/ai-tasks`).

package/.docs/web-scopper-embed.md

@@ -1,93 +0,0 @@
-# Feature Request: NARRIX Web Scoper (question-driven web context)
-
-## Overview
-
-This feature request proposes adding support in `@woroces/ai-tasks` for **question-driven web context** when the NARRIX pre-processor runs. When a task request includes `narrix` and a question (or questionId), ai-tasks should optionally call **@narrices/narrix-web-scoper** to plan and fetch web context (via @narrices/search-adapter), merge it with narrative from memory, and pass the combined context to the task so that answers can use both data-scoped narrative and web search as needed.
-
-**Depends on (or extends):** [ai-tasks-narrix-pre-processor-feature-request.md](ai-tasks-narrix-pre-processor-feature-request.md) — the NARRIX pre-processor must have built or received CNI before web-scoper can run.
-
-## Background
-
-- **Question-driven flow:** Graph nodes often carry a question (`inputs.question`) and/or `metadata.narrix.questionId`. Some questions are best answered from **narrative already in memory** (e.g. from NARRIX scoping/discovery on the record); others benefit from **web search** (e.g. public threat intel, vendor docs). The desired behavior is to support both in one flow: narrative on memory + search on the web as needed.
-- **narrix-web-scoper:** The package `@narrices/narrix-web-scoper` is a CNI-aware web context planner and mapper. It uses `@narrices/narrix-cni` and `@narrices/search-adapter` to plan what to search for from the CNI (and optional question) and map retrieval results into a structured web context. It is designed to run where CNI is already available.
-- **Where CNI lives:** In the intended architecture, when ai-tasks runs the NARRIX pre-processor (resolve input → CNI conversion → engine-enrich → inject context → run task), CNI exists internally after the CNI conversion step. That is the right place to optionally run web-scoper before or in tandem with engine-enrich, so the task receives both NARRIX narrative and web-derived context.
-
-## Problem
-
-- There is no way for the NARRIX pre-processor to extend scoped data with web search.
-- Tasks that could benefit from both narrative (memory) and web context currently get only one or the other, or require a separate graph node for web search (which we want to avoid).
-
-## Proposed contract
-
-### 1. Opt-in on request
-
-When `request.narrix` is present, support an optional flag to enable web context (so existing behavior is unchanged):
-
-- **Option A (recommended):** Extend the `narrix` object with `enableWebScope?: boolean`. If `true`, the pre-processor runs web-scoper when it has CNI and question/questionId.
-- **Option B:** A separate request-level field, e.g. `narrixWebScope?: boolean` or `request.options?.enableNarrixWebScope`. Document that it is only honored when `request.narrix` is set.
-
-worox-graphs (or other callers) would set this from e.g. `node.metadata.narrix.enableWebScope` or a graph-level variable.
-
-### 2. When to run web-scoper
-
-- **Precondition:** NARRIX pre-processor has already built or obtained CNI (after “CNI conversion” in the pre-processor flow).
-- **Precondition:** A question is available for the current task: either `request.narrix.questionId` or `request.inputs?.question` / `request.input?.question` (or the same from executionMemory/jobContext if that is where the pre-processor reads question from).
-- **Precondition:** Web scope is enabled (e.g. `request.narrix.enableWebScope === true`).
-- **Action:** Call `@narrices/narrix-web-scoper` with (CNI, datasetId, optional questionId/question, and any options the package exposes). Obtain the planned/mapped web context (exact API to be taken from the package’s public API).
-
-### 3. Where to inject web context
-
-Merge the web-scoper output into the context that the task receives, in a well-defined place, for example:
-
-- **Option A:** Merge into the same structure used for NARRIX enrichment (e.g. `executionMemory.narrixEnriched.webContext` or `jobContext._narrix.webContext`), so the task sees one enriched object that includes both narrative and web context.
-- **Option B:** A dedicated path such as `executionMemory.webContext` or `jobContext.webContext` that the task and templates can reference.
-
-Document the chosen path so that worox-graphs and skill templates can rely on it.
-
-### 4. Dependencies
-
-- ai-tasks (or the module that implements the NARRIX pre-processor) should add:
-  - `@narrices/narrix-web-scoper` (and its peer/transitive dependencies, e.g. `@narrices/narrix-cni`, `@narrices/search-adapter` as required by the package).
-
-No change required in worox-graphs for this feature beyond optionally setting `enableWebScope` when building the request (once ai-tasks supports it).
-
-### 5. Failure and fallback
-
-- If web-scoper fails (e.g. search-adapter timeout, API error), the pre-processor should either:
-  - **Strict:** Fail the task with a clear error, or
-  - **Lenient (recommended default):** Log the error, omit web context for this run, and continue with only NARRIX narrative. Document the behavior.
-
-### 6. Question availability
-
-The pre-processor already has access to:
-
-- `request.narrix` (datasetId, questionId, etc.)
-- `request.input` / `request.inputs` (e.g. question text)
-- Possibly `executionMemory` / `jobContext` (if question is passed from the graph there)
-
-Use the same resolution order as for other NARRIX inputs so that questionId and/or question text are available when invoking web-scoper.
-
-## Expected behavior summary
-
-| Scenario | Behavior |
-|----------|----------|
-| `request.narrix` absent | No change; no NARRIX pre-processing. |
-| `request.narrix` present, `enableWebScope` absent or false | Pre-processor runs as today (CNI → engine-enrich → inject narrative). No web-scoper call. |
-| `request.narrix` present, `enableWebScope` true, question/questionId available, CNI built | Run web-scoper with CNI + question; merge web context into the injected context; then run engine-enrich (if applicable) and task with combined narrative + web context. |
-| Web-scoper fails (lenient) | Log error; inject only NARRIX narrative; task runs without web context. |
-
-## Implementation notes (for ai-tasks)
-
-- **Placement:** In the NARRIX pre-processor path, after CNI is built and before (or in parallel with) engine-enrich. If engine-enrich consumes `sourceMeta` or similar, extend it with the web context so the runner can use it if needed.
-- **API:** Consult `@narrices/narrix-web-scoper`’s public API (e.g. a `planAndMap(cni, options)` or similar) and wire it with datasetId, questionId/question, and any required adapter config (e.g. search-adapter API keys from env).
-- **Tests:** Add unit/integration tests that mock the search-adapter and assert that when `enableWebScope` is true and question is present, web context is merged into the context passed to the task (and that when web-scoper fails, the chosen fallback behavior is applied).
-
-## worox-graphs changes (when feature exists)
-
-- Optional: Extend graph node schema to allow `metadata.narrix.enableWebScope` (or read from variables) and pass it through to `RunTaskRequest.narrix.enableWebScope` so authors can enable question-driven web scope per node or per graph without code changes.
-
-## References
-
-- [ai-tasks-narrix-pre-processor-feature-request.md](ai-tasks-narrix-pre-processor-feature-request.md) — NARRIX as task-level pre-processor (input contract, CNI, engine-enrich, inject context).
-- `@narrices/narrix-web-scoper` — CNI-aware web context planner; uses `@narrices/search-adapter` for retrieval.
-- [question-questionId-first-class-experience.md](question-questionId-first-class-experience.md) — Question and questionId as first-class in worox-graphs (resolution, request build).

package/.docs/xynthesis-wiring-and-io.md

@@ -1,12 +0,0 @@
-# Moved
-
-This document was split into focused pages. Start here:
-
-**[flow-io/flow-README.md](./flow-io/flow-README.md)** — high-level blocks
-
-| Topic | Doc |
-|-------|-----|
-| PRE — calling `@exellix/xynthesis` | [flow-io/xynthesis-pre.md](./flow-io/xynthesis-pre.md) |
-| POST — calling `@exellix/xynthesis` | [flow-io/xynthesis-post.md](./flow-io/xynthesis-post.md) |
-| NARRIX | [flow-io/narrix.md](./flow-io/narrix.md) |
-| Web scoping | [flow-io/web-scoping.md](./flow-io/web-scoping.md) |

package/documenations/activix-feature-request-identity.md

@@ -1,123 +0,0 @@
-# Feature request: Activix first-class `identity` object
-
-## Summary
-
-Extend `@xronoces/activix` to support a **first-class `identity` object** on activity records, so downstream systems can attach a stable identity envelope to every activity and query/group activities consistently.
-
-This request is driven by the task methodology used in `@exellix/ai-tasks` (and the wider stack via `ai-skills`/`ai-gateway`).
-
----
-
-## Problem
-
-Today, many systems treat identity as “just more metadata” and bury it inside arbitrary blobs. That makes identity:
-
-- inconsistent across producers,
-- hard to query/index,
-- easy to accidentally rename/flatten,
-- easy to drop during updates,
-- hard to standardize across a multi-package pipeline.
-
-We want identity to be a **first-class citizen** in Activix, not an ad-hoc field hidden in random meta objects.
-
----
-
-## Proposed behavior (contract)
-
-### 1) Record schema supports `identity`
-
-Every Activix record should support a top-level field:
-
-- `identity?: Record<string, unknown>`
-
-Constraints:
-
-- Must be persisted on `startRecord(...)` creation.
-- Must remain intact across lifecycle operations (`completeRecord`, `failRecord`, `patchRecord`) unless explicitly changed.
-- Must be returned by read/query APIs (`getRecord`, `findRecords`, etc).
-
-### 2) Identity is preserved (no mutation by default)
-
-Activix must not:
-
-- rename keys inside `identity`,
-- flatten `identity` into other fields,
-- drop `identity` during updates.
-
-### 3) Query by identity fields must be supported
-
-Because `identity` is an object, querying by identity must be supported by the storage adapter. Minimum requirement:
-
-- `findRecords({ "identity.taskId": "<id>" })` works (Mongo-style dotted-path query)
-
-If Activix abstracts storage backends, the contract should specify which query patterns are supported (at least dotted-path equality for Mongo backend).
-
-### 4) Indexing support (recommended)
-
-To make querying scalable, Activix should support indexes over identity subfields (backend permitting). Recommended index patterns:
-
-- `identity.taskId`
-- optionally `identity.skillId`
-
-This can be implemented as:
-
-- a first-class `indexes` declaration (preferred), or
-- documented guidance for consumers who configure collection indexes.
-
----
-
-## Required API / typing changes
-
-### `startRecord`
-
-Accept `identity` as a top-level field on the record meta payload:
-
-- `ax.startRecord({ ..., identity })`
-
-### `completeRecord` / `failRecord` / `patchRecord`
-
-Ensure identity is not lost:
-
-- If updates omit `identity`, the stored record keeps the previously set `identity`.
-- If updates include `identity`, treat it as a full replace (or document merge semantics explicitly; default to replace to avoid surprising partial merges).
-
-### Type exports
-
-Expose a stable type for records that includes:
-
-- `identity?: Record<string, unknown>`
-
----
-
-## Interaction with `@exellix/ai-tasks`
-
-`@exellix/ai-tasks` generates a unique per-run `taskId` and uses it to:
-
-- attach `identity.taskId` to all activity records for that run, and
-- retrieve “activities for the task” by that `taskId`.
-
-Recommended alignment for the task methodology:
-
-- `correlationId` remains the primary “group a run” field, but we will also carry `identity.taskId`.
-- Optionally, stacks may choose to set `correlationId === identity.taskId` for convenience, but this should not be required by Activix.
-
-See also: `documenations/identity-metadata-contract.md`
-
----
-
-## Backward compatibility
-
-- Records without `identity` remain valid.
-- Existing producers may continue to omit identity.
-- Query APIs should not require identity.
-
----
-
-## Acceptance criteria
-
-- `identity` can be written on `startRecord`.
-- `identity` remains present after `completeRecord` / `failRecord` unless explicitly overwritten.
-- `identity` is returned by `getRecord` and `findRecords`.
-- Dotted-path queries against identity subfields work for Mongo backend (`"identity.taskId"` equality).
-- Index configuration supports `identity.taskId` (either natively or via documented index config).
-

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

@@ -1,217 +0,0 @@
-# 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/feature-request-ai-skills-raw-template-access.md

@@ -1,82 +0,0 @@
-# Feature Request: AI-Skills Raw Template Access API
-
-## Summary
-
-`@exellix/ai-tasks` needs a stable, public API from `@woroces/ai-skills` to retrieve **raw template content** (instructions/prompt) for a skill key, before rendering.
-
-This is required for strict template-contract semantics (for example template core token discovery in structured synthesis).
-
-## Problem
-
-In `ai-tasks` synthesis pre-step, we must inspect template tokens before rendering.  
-Current integration paths are not reliable for this:
-
-- `skillsClient.registry.resolve/get` may return `undefined` during runtime pre-step.
-- `diagnoseSkillContent()` logs useful diagnostics but does not return the raw content.
-- `listAvailable()` can be empty in contexts where execution still works later.
-
-Result: `ai-tasks` cannot deterministically read raw instructions/prompt content at pre-step time, so strict token-based validation fails even when skill content exists.
-
-## Requested API
-
-Expose a public method on `WorecesSkillsClient` (or equivalent public content-resolver service):
-
-```ts
-export type TemplateSection = "instructions" | "prompt";
-
-export interface ResolveRawTemplateResult {
-  key: string;                // normalized internal key used by resolver
-  found: boolean;
-  content?: string;           // raw template text (unrendered)
-}
-
-resolveRawTemplate(
-  skillKey: string,
-  section: TemplateSection
-): Promise<ResolveRawTemplateResult>;
-```
-
-Alternative acceptable shape:
-
-```ts
-resolveRawTemplateByKey(key: string): Promise<string | undefined>;
-```
-
-as long as normalization rules are documented and stable.
-
-## Behavioral Requirements
-
-1. Returns **raw template text**, not rendered output.
-2. Works consistently in the same runtime phase where `runSkill/runTask` executes.
-3. No diagnostics-only behavior; must return programmatic result.
-4. No side effects required (no forced diagnose/warmup calls needed by consumer).
-5. Clear normalization rules for keys:
-   - `skills/<id>.instructions`
-   - `skills/<id>.prompt`
-   - and any officially supported aliases.
-
-## Why This Is Needed
-
-`ai-tasks` structured synthesis is now template-contract-driven:
-
-- discover semantic tokens from raw template contract,
-- validate required tokens,
-- block execution if missing.
-
-Without raw-template API, this validation is brittle and environment-dependent.
-
-## Acceptance Criteria
-
-1. Public API added to `WorecesSkillsClient` (or public content registry wrapper).
-2. Works against local registry path and normal runtime registry.
-3. Unit tests cover:
-   - found/missing instructions
-   - found/missing prompt
-   - normalized key mapping
-   - runtime call path parity with execution flow
-4. Docs include examples for consumers (`ai-tasks` and other orchestrators).
-
-## Backward Compatibility
-
-Additive change only; no breaking behavior required.
-