@exellix/ai-tasks 9.0.6 → 9.1.1

package/.docs/possible-components/pre-component/builder-guide.md

@@ -1,127 +0,0 @@
-# Pre-Task component — **builder guide** (single entry for implementation)
-
-Use this file plus the linked handler specs. **Full** platform rules (Activix field shapes, identity merge algorithm): [`../integration/platform.md`](../integration/platform.md).
-
----
-
-## 1. What you are building
-
-A **Pre-Task engine** that runs **before MAIN** and returns:
-
-- Possibly updated `jobMemory` / `taskMemory` / `executionMemory` / `input`
-- Optional **`contextMarkdown`** override for the MAIN skill prompt
-- Optional **`synthesizedContext`** artifact on `executionMemory`
-- **`intermediateSteps`** for observability
-
-**Protocol:** [`unified-protocol.md`](unified-protocol.md).
-
----
-
-## 2. Stack (minimum you must honor)
-
-| Topic | Rule |
-|-------|------|
-| LLM calls | **aifunctions-js** (`ask` / compatible client). Not a separate ai-gateway product API. |
-| Synthesized-context step | **@athenices/xynthesis** for templates, modes, validation; **SynthesisInvoker** calls aifunctions-js. |
-| Observability | **Activix** phase records where the host enables it; top-level **`identity`** on every record per `docs/activix-identity.md`. |
-| Correlation | Prefer **`correlationId === taskId`** for one run. |
-
----
-
-## 3. NPM dependencies (pin to tested versions from `@woroces/ai-tasks`)
-
-| Package | Role in pre paths |
-|---------|-------------------|
-| `aifunctions-js` | All generative calls (scoping, System-2, synthesis invoker). |
-| `@athenices/xynthesis` | Synthesized-context PRE handler. |
-| `@woroces/ai-skills` | `enrichMemoriesWithScoping`, `resolveRawTemplate`, executor (host). |
-| `@woroces/memory-narrix-adapter` | `adaptMemoryToNarrixInput` (narrix preprocessor). |
-| `@narrices/narrix-*` | Ingest, adapters, runner, packs, web-scoper (see `package.json` of ai-tasks). |
-| `@xronoces/activix` | Phase recording (with host wrapper). |
-
-Also used indirectly: `handlebars` (if you render web scope templates in-host).
-
----
-
-## 4. Host contract (skills / task runtime)
-
-The pre engine **does not** replace the skills client. The host must provide:
-
-| Capability | Used by |
-|------------|---------|
-| `enrichMemoriesWithScoping(skillKey, "task", memoryBundle)` | Synthesis PRE, direct-path enrich (same as today). |
-| `resolveRawTemplate(skillKey, "instructions" \| "prompt")` → raw markdown | Structured synthesis + template cores. |
-| Optional: same client’s `generateContextMarkdown` / executor | After pre returns, MAIN still runs in host. |
-
----
-
-## 5. Request fields this engine reads (`RunTaskRequest`)
-
-| Field | Handler |
-|-------|---------|
-| `narrix?: NarrixPreProcessorConfig` | [`handler-narrix-preprocessor.md`](handler-narrix-preprocessor.md) |
-| `executionPipeline` with PRE `synthesized-context` | [`handler-synthesized-context.md`](handler-synthesized-context.md) |
-| `aiScoping?: AIScopingInstruction[]` | [`handler-ai-scoping.md`](handler-ai-scoping.md) |
-| `includeContextInPrompt`, `taskMemory`, `jobMemory`, `executionMemory`, `skillKey`, `input`, `identity`, `jobId`, `agentId` | Multiple |
-
-**Note:** `executionType: narrix-then-direct` + `narrixInput` is a **different** flow (Narrix then MAIN with `taskMemory.narrix`); it still uses `narrixRunHandler` and is **host-orchestrated** in `task-sdk.ts`. If your pre package only covers “pipeline + scoping + narrix preprocessor”, document whether `narrix-then-direct` stays in the host.
-
----
-
-## 6. Environment variables (pre-relevant)
-
-| Variable | Handler / area |
-|----------|----------------|
-| `AI_SCOPING_MODEL`, `AI_SCOPING_CONCURRENCY`, `AI_SCOPING_TIMEOUT_MS` | AI scoping |
-| `SYNTHESIS_MODEL`, `SYNTHESIS_TIMEOUT_MS`, `SYNTHESIS_MAX_OUTPUT_LENGTH` | Synthesis PRE |
-| `NARRIX_SYSTEM2_MODE`, `NARRIX_SYSTEM2_MODEL`, `NARRIX_SYSTEM2_MAX_ITERATIONS`, `NARRIX_SYSTEM2_ENABLE_WRITES`, `NARRIX_SYSTEM2_SAVE_ARTIFACTS`, `NARRIX_SYSTEM2_ARTIFACT_DIR`, … | System-2 |
-| `TAVILY_API_KEY` | Web scope (default search) |
-| `MONGO_LOGS_DB` | Default `bindingDefaultsDb` merged into `execution` (current SDK behavior) |
-
-Centralize in one config module in your package.
-
----
-
-## 7. Source file manifest (current `ai-tasks`)
-
-Copy or depend on these paths when extracting:
-
-| Path | Notes |
-|------|--------|
-| `src/aiScoping/*` | Scoping + `validateAiScoping.ts` |
-| `src/internal/runLlmTextCall.ts` | Shared LLM primitive |
-| `src/synthesis/resolveSourceMaterial.ts`, `synthesisGatewayCompat.ts`, `index.ts` | Synthesis wiring + xynthesis re-exports |
-| `src/narrix/**` except tests | Narrix run, web scoper, system2, context markdown builders |
-| `src/utils/jsonPaths.ts` | `getByPath` for scoping sources |
-| `src/types/task-types.ts` | Types listed in handler docs |
-
----
-
-## 8. Definition of done (acceptance)
-
-- [ ] Handlers run in order: narrix preprocessor (if any) → pipeline PRE synthesized-context (if any) → (host) enrich → ai scoping (if any).  
-- [ ] Synthesis: markdown + structured modes behave per [`handler-synthesized-context.md`](handler-synthesized-context.md); `fallbackToDirect` respected.  
-- [ ] Scoping: parallel bounded concurrency; missing paths skipped; validation before LLM.  
-- [ ] Web scope: never throws to caller; `webContext` optional on `executionMemory`.  
-- [ ] System-2: PatchPlan JSON validated; iteration cap enforced.  
-- [ ] Activix + `identity` on each recorded phase when host passes client.  
-- [ ] Test hooks: scoping / synthesis / llmPlan / web scoper injectable.
-
----
-
-## 9. Types (canonical source)
-
-Implementations should align with **`src/types/task-types.ts`**: `AIScopingInstruction`, `AIScopedItem`, `SynthesisConfig`, `SynthesizedContextArtifact`, `ContextSourcePolicy`, `WebEvidenceConfig`, `ExecutionStep`, `NarrixPreProcessorConfig`, `IntermediateStep`, and pipeline constants (`SYNTHESIZED_CONTEXT`). Re-export or depend on a shared types package when splitting repos.
-
----
-
-## 10. Read next
-
-1. [`unified-protocol.md`](unified-protocol.md)  
-2. [`handler-narrix-preprocessor.md`](handler-narrix-preprocessor.md)  
-3. [`handler-synthesized-context.md`](handler-synthesized-context.md)  
-4. [`handler-ai-scoping.md`](handler-ai-scoping.md)  
-5. [`handler-web-scope.md`](handler-web-scope.md)  
-6. [`handler-narrix-system2.md`](handler-narrix-system2.md)  
-7. [`gaps-and-artifacts.md`](gaps-and-artifacts.md)  
-8. Merge / shared checklist: [`../integration/roadmap-and-checklists.md`](../integration/roadmap-and-checklists.md) Phase B, [`../integration/reintegrate-into-ai-tasks.md`](../integration/reintegrate-into-ai-tasks.md)

package/.docs/possible-components/pre-component/gaps-and-artifacts.md

@@ -1,35 +0,0 @@
-# Pre-Task component — gaps, code, templates
-
-What is **missing, external, or optional to add** when packaging the pre engine. **Behavior, env tables, dependencies, acceptance:** [`builder-guide.md`](builder-guide.md).
-
-## Code modules (current `ai-tasks` anchors)
-
-| Area | Paths / packages | Note |
-|------|------------------|------|
-| AI scoping | `src/aiScoping/*` (incl. `validateAiScoping.ts`) | Depends on `src/internal/runLlmTextCall.ts`. |
-| Synthesis source wiring | `src/synthesis/resolveSourceMaterial.ts`, `synthesisGatewayCompat.ts` | Re-export surface: `src/synthesis/index.ts` → **@athenices/xynthesis**. |
-| Narrix pre + web | `src/narrix/*` (large), `task-sdk` orchestration | System-1 ingest lives largely in **external** Narrix packages. |
-| System-2 | `src/narrix/system2/*` | Tied to `runLlmTextCall`. |
-| Types | `src/types/task-types.ts` (`AIScoping*`, `SynthesisConfig`, pipeline types) | May need a shared types package when extracting. |
-
-## Templates & assets
-
-| Asset | Status in repo | Action for standalone pre package |
-|-------|----------------|-------------------------------------|
-| Synthesis markdown templates | Loaded via **@athenices/xynthesis** `loadSynthesisTemplates()` | Confirm templates ship **inside** xynthesis or **vendor** copies into the pre package; audit/polish disk templates belong in **post** spec only. |
-| Skill instructions/prompt | **@woroces/ai-skills** `resolveRawTemplate` | Pre component needs a **host callback**; not bundled in pre-only package. |
-| AI scoping | **No** separate disk template — prompts inline in `runScopingCall.ts` | Optional: externalize to `templates/pre/scoping-system.md` for versioning. |
-| Narrix System-2 | System prompt **inline** in `llmPlan.ts` | Optional: externalize for tuning without code change. |
-
-## Environment variables
-
-Canonical table: [`builder-guide.md`](builder-guide.md) §6.
-
-## Tests / DI hooks to preserve
-
-`setScopingGateway`, `setSynthesisInvoker` / `setSynthesisGateway`, `setLlmPlanGateway`, `setWebScoperForTesting` — or equivalent constructor injection in a new package.
-
-## Open decisions
-
-- Whether **narrix-preprocessor** ships inside pre package or stays a **peer** dependency.  
-- Single **Activix** wrapper module shared with post (owned under integration / shared lib).

package/.docs/possible-components/pre-component/handler-ai-scoping.md

@@ -1,45 +0,0 @@
-# Handler: AI memory scoping (`direct.ai-scoping`)
-
-> **Platform:** LLM + Activix + `identity` — [`../integration/platform.md`](../integration/platform.md).
-
-## Purpose
-
-Before MAIN, optionally turn memory slices into concise text. Each instruction is one LLM call over **only** resolved source content; results merge into `input.aiScoped[]`.
-
-## Trigger (current repo)
-
-- `RunTaskRequest.aiScoping?: AIScopingInstruction[]`
-- After enrich, before `executor.execute` in `_executeDirect` (`src/core/task-sdk.ts`).
-- Code: `src/aiScoping/runAiScoping.ts`, `runScopingCall.ts`.
-
-## Inputs
-
-| Field | Notes |
-|--------|--------|
-| Bundle | `jobMemory` / `taskMemory` / `executionMemory`; paths via `getByPath`. |
-| Instructions | `source`, `instructions` (NL), `targetToken` per item. |
-| Concurrency / timeout | Defaults 5 workers, 30s/item; env `AI_SCOPING_*`. |
-
-Skipped if source path missing (no error). `validateAiScoping` before calls.
-
-## Single call (`runScopingCall`)
-
-- Fixed system: use only source, no invention, plain text, no markdown fences.
-- User: `Instructions:\n…\n\nSource content:\n…` (serialized value).
-- `runLlmTextCall`: temp 0.2, maxTokens 2048; test hook `setScopingGateway`.
-
-## Orchestration (`runAiScoping`)
-
-Bounded parallel workers; failures → omit that item (tolerant).
-
-## Output
-
-`AIScopedItem[]` → merged into object `input` as `aiScoped`.
-
-## Non-goals
-
-Not full RAG; chunks are independent. No automatic memory writeback.
-
-## Types
-
-`AIScopingInstruction`, `AIScopedItem` — `src/types/task-types.ts`.

package/.docs/possible-components/pre-component/handler-narrix-preprocessor.md

@@ -1,49 +0,0 @@
-# Handler: Narrix preprocessor (`narrix-preprocessor`)
-
-> **Platform:** [`../integration/platform.md`](../integration/platform.md).  
-> **Sub-steps:** [`handler-web-scope.md`](handler-web-scope.md), [`handler-narrix-system2.md`](handler-narrix-system2.md) (inside `narrixRunHandler`).
-
-## Purpose
-
-When `RunTaskRequest.narrix` is set, adapt task memory to a **Narrix run input**, execute **`narrixRunHandler`** (local skill `skills/skill.local:narrixRun`), attach enrichment to **`executionMemory`** and **`jobMemory`**, optionally fetch **web evidence**.
-
-## Trigger (current repo)
-
-- `request.narrix` present → phase `narrix` in `task-sdk.ts` before local-task dispatch and pipeline.  
-- Uses `adaptMemoryToNarrixInput` from `@woroces/memory-narrix-adapter` with path preferences (`executionMemory.input.raw`, `jobMemory.currentRecord`, …).  
-- Failure to adapt → **throw** (strict). Narrix run `ok: false` → **throw**.
-
-## Config (`NarrixPreProcessorConfig`) — fields builders need
-
-| Field | Role |
-|-------|------|
-| `datasetId` | Required. |
-| `attachToField` | Default `_narrix`; where attachment lives on `executionMemory`. |
-| `deterministicSort` | Default true (narrative ordering). |
-| `enableWebScope` | After success, call web scoper → `executionMemory.webContext`. |
-| `webScopeTemplates`, `webScopeQuestionTemplate`, `webScopeObjects`, `webScoping` | Web query shaping (see `NarrixPreProcessorConfig` in `task-types.ts`). |
-| `engineConfigPath`, `packsRoot`, `assumptionsPolicy` | Reserved / future. |
-
-Full interface: `src/types/task-types.ts`.
-
-## Success path (summary)
-
-1. `adaptMemoryToNarrixInput(...)` → `narrixInput`.  
-2. `narrixRunHandler({ input, ctx })` with skill/job/graph ids from request.  
-3. `buildNarrixAttachment(success)` → store under `executionMemory[attachToField]` and `jobMemory._narrix` (current behavior).  
-4. If `enableWebScope`: `resolveWebScopeQuestionAndTemplates` + `runWebScope` → merge `webContext` (lenient).  
-
-## Related execution mode
-
-**`narrix-then-direct`** uses resolved `narrixInput` + `narrixRunHandler` + `applyNarrixScope` and writes **`taskMemory.narrix`** — different injection shape. Implement either in the same package behind flags or document as **host-only** if out of scope.
-
-## Code anchors
-
-- `src/core/task-sdk.ts` (narrix block)  
-- `src/narrix/task.ts` (`narrixRunHandler`)  
-- `src/narrix/buildNarrixAttachment.ts`, `buildWebScopeScopeInput`, `webScoper.ts`  
-- `src/activix/phaseTracking.ts` (`withPhaseRecord`)
-
-## Dependencies
-
-Narrix ingest/runner/packs packages; `NARRIX_DISABLED` / flags in `src/narrix/flags.ts` may disable behavior.

package/.docs/possible-components/pre-component/handler-narrix-system2.md

@@ -1,35 +0,0 @@
-# Sub-handler: Narrix System-2 LLM patch plan
-
-> **Platform:** [`../integration/platform.md`](../integration/platform.md).
-
-## Purpose
-
-After Narrix System-1, optionally detect gaps and call an LLM for **PatchPlan** JSON (routing/schema actions), apply patches, optionally re-run System-1.
-
-## Trigger (current repo)
-
-- `narrixRunHandler` → `runWithSystem2` (`src/narrix/system2/runWithSystem2.ts`)
-- LLM: `llmPlan` (`src/narrix/system2/llmPlan.ts`)
-- Env/options: `NARRIX_SYSTEM2_MODE`, `maxIterations`, `enableWrites`, `model`, etc.
-
-## LLM I/O
-
-- User content from `buildSystem2Input(input, result, gapHints)`.
-- System: PatchPlan JSON only; allowed action types defined in code (`rememberDatasetPackRouting`, …).
-- Parse: `extractJsonFromText` + `validatePatchPlan`.
-
-## Invocation
-
-`runLlmTextCall`: temp 0.2, maxTokens 8192; `setLlmPlanGateway` for tests.
-
-## Post-LLM
-
-`applyPatchPlan`, optional `writeArtifacts`, rerun loop under `maxIterations`.
-
-## Non-goals
-
-Not a general agent; closed action set. Does not replace System-1 ingest (external packages).
-
-## Dependencies (repo)
-
-`src/narrix/system2/*`, `src/internal/runLlmTextCall.ts`

package/.docs/possible-components/pre-component/handler-synthesized-context.md

@@ -1,65 +0,0 @@
-# Handler: synthesized context (`pipeline.synthesized-context`)
-
-> **Platform:** **@athenices/xynthesis** for synthesis contracts; **aifunctions-js** inside `SynthesisInvoker`; Activix + `identity` — [`../integration/platform.md`](../integration/platform.md) §1b.
-
-## Purpose
-
-PRE pipeline step: build markdown **context** for MAIN from memory, Narrix attachment, optional web evidence, and rendered skill templates. Modes: **markdown** completion vs **structured** synthesis (cores + validation).
-
-## Trigger (current repo)
-
-- `executionPipeline`: `{ phase: "pre", type: "synthesized-context", config?: SynthesisConfig }`
-- Requires `includeContextInPrompt === true` or `config.autoEnableContext === true`
-- `WorexClientTasks._runSynthesizedContextPreStep` in `src/core/task-sdk.ts`
-
-## Orchestration (high level)
-
-1. Merge `executionMemory` into `jobMemory.execution` (incl. `bindingDefaultsDb` default).  
-2. `enrichMemoriesWithScoping(skillKey, "task", memoryBundle)`.  
-3. Cleanse `execution` for prompts.  
-4. Narrix-shaped attachment from `executionMemory[attachToField]` or `taskMemory.narrix`.  
-5. `buildSynthesizerInputMaterial` (**@athenices/xynthesis** + host `resolveSourceMaterial*`).  
-6. `getRenderedTemplates` (skill raw templates + placeholders).  
-7. Branch: markdown vs structured (below).  
-8. Optional `SynthesizedContextArtifact` on `executionMemory.synthesizedContext`.  
-
-`fallbackToDirect` → empty context instead of throw on materialization failure (when enabled).
-
-## Mode A — Markdown
-
-- `loadSynthesisTemplates`, `buildSynthesisSystemPrompt`, `runSynthesisCall` from **@athenices/xynthesis**.
-- Defaults: model from config → `SYNTHESIS_MODEL` → `gpt-5-nano`; timeout `SYNTHESIS_TIMEOUT_MS` / 30_000.
-
-## Mode B — Structured
-
-- Parts: `localMarkdown` / `supportingMarkdown`; `resolveSynthesisQuestion`; `discoverTemplateCores`.
-- Custom path: `getContextSynthesizer()` if set; else `runStructuredSynthesisGatewayCall`.
-- Output: `buildSynthesizedContextMarkdown(payload)`.
-
-## Xynthesis vs aifunctions-js (single definition)
-
-| Layer | Role |
-|-------|------|
-| **@athenices/xynthesis** | Templates, modes, validation, artifact types, `setSynthesisInvoker`. |
-| **aifunctions-js** | Implement invoker with `client.ask` (or shared helper). |
-
-## Testing / migration
-
-- `setSynthesisInvoker` (preferred).  
-- Legacy: `src/synthesis/synthesisGatewayCompat.ts` → `setSynthesisGateway` for `invoke`-shaped mocks only.
-
-## Downstream
-
-MAIN uses `overrideContext`; `synthesisContextAuthoritative` blocks Narrix/web fill-in when empty. POST audit/polish use captured context markdown.
-
-## Config surface
-
-`SynthesisConfig`: `modelConfig`, `timeoutMs`, `maxOutputLength`, `synthesisInputStrategy`, `contextSourcePolicy`, `memoryPaths`, `webEvidence`, `fallbackToDirect`, structured limits, prompt overrides, mode.
-
-## Risks
-
-Structured mode needs `resolveRawTemplate` / registry; missing templates → errors unless fallback.
-
-## Repo anchors
-
-`src/synthesis/resolveSourceMaterial.ts`, `src/synthesis/synthesisGatewayCompat.ts`, `src/synthesis/index.ts` (re-exports xynthesis).

package/.docs/possible-components/pre-component/handler-web-scope.md

@@ -1,29 +0,0 @@
-# Sub-step: Web scope / evidence (Narrix add-on)
-
-> **Platform:** Activix + `identity` for phases; no generative LLM here — [`../integration/platform.md`](../integration/platform.md).
-
-## Purpose
-
-After a successful Narrix pre-processor run, optionally fetch search-backed evidence into `executionMemory.webContext` for synthesis / MAIN.
-
-## Trigger (current repo)
-
-- `request.narrix.enableWebScope === true`
-- `resolveWebScopeQuestionAndTemplates` + `runWebScope` in `src/narrix/webScoper.ts`, called from `task-sdk.ts`.
-
-## Stack
-
-- `createWebScoper` + `createSearchAdapter` (Tavily + `TAVILY_API_KEY` default).
-- Errors → `{ available: false, reason: "error", error }` (no throw).
-
-## Testing
-
-`setWebScoperForTesting`, `resetWebScoperSingleton`.
-
-## Relation to synthesis
-
-`SynthesisConfig.webEvidence` / `resolveSourceMaterial*` may consume `webContext` from memory.
-
-## Dependencies
-
-`@narrices/narrix-web-scoper`, `@narrices/search-adapter`

package/.docs/possible-components/pre-component/unified-protocol.md

@@ -1,89 +0,0 @@
-# Pre-Task component — unified protocol
-
-> **Scope:** Target architecture only; not a mandate to change `ai-tasks` code until you choose to.  
-> **Shared platform (aifunctions-js, Activix, identity, Xynthesis):** single source of truth is [`../integration/platform.md`](../integration/platform.md).
-
----
-
-## Goal
-
-One **Pre-Task engine** that:
-
-- Accepts a standard **input envelope** (task request, skills client, memory, optional Activix + correlation + identity).
-- Runs an **ordered chain** of handlers sharing one protocol.
-- Produces **patches** to request/memory/input, optional **context override** for MAIN, optional **synthesis artifact**, and **intermediate steps**.
-
----
-
-## Handler protocol (conceptual)
-
-```ts
-type PreHandlerId =
-  | "narrix-preprocessor"
-  | "pipeline.synthesized-context"
-  | "direct.ai-scoping";
-
-interface PreHandlerContext {
-  request: RunTaskRequest;
-  identity?: Record<string, unknown>;
-  memoryBundle?: unknown;
-  skillsClient?: unknown;
-  correlationId?: string;
-  activix?: unknown;
-  prior: {
-    contextMarkdownOverride?: string;
-    synthesisContextAuthoritative?: boolean;
-    executionMemoryPatch?: Record<string, unknown>;
-  };
-}
-
-interface PreHandlerResult {
-  ok: boolean;
-  patches?: {
-    jobMemory?: Record<string, unknown>;
-    taskMemory?: Record<string, unknown>;
-    executionMemory?: Record<string, unknown>;
-    input?: unknown;
-  };
-  contextMarkdownOverride?: string;
-  synthesisContextAuthoritative?: boolean;
-  artifact?: unknown;
-  intermediateSteps?: IntermediateStep[];
-  error?: { code: string; message: string };
-}
-
-interface PreTaskHandler {
-  id: PreHandlerId;
-  order: number;
-  shouldRun(ctx: PreHandlerContext): boolean;
-  run(ctx: PreHandlerContext): Promise<PreHandlerResult>;
-}
-```
-
-**Composition:** engine merges `patches` in order, concatenates `intermediateSteps`, forwards `prior` to the next handler. Per-handler failure policy (strict vs tolerant) is part of each handler spec.
-
----
-
-## Built-in handlers (index)
-
-| Handler id | Trigger (today) | Detail doc |
-|------------|-----------------|------------|
-| `narrix-preprocessor` | `RunTaskRequest.narrix` | [`handler-narrix-preprocessor.md`](handler-narrix-preprocessor.md); web scope [`handler-web-scope.md`](handler-web-scope.md). |
-| `pipeline.synthesized-context` | `executionPipeline` PRE `synthesized-context` | [`handler-synthesized-context.md`](handler-synthesized-context.md) (**@athenices/xynthesis**). |
-| `direct.ai-scoping` | `RunTaskRequest.aiScoping[]` | [`handler-ai-scoping.md`](handler-ai-scoping.md). |
-
-**Narrix System-2** (`llmPlan`) is a **sub-phase** of narrix (or a nested handler with the same result type). Spec: [`handler-narrix-system2.md`](handler-narrix-system2.md).
-
----
-
-## Canonical execution order
-
-1. `narrix-preprocessor` (if `request.narrix`)  
-2. Pipeline PRE steps — `pipeline.synthesized-context` when present  
-3. MAIN prep inside direct: memory enrich → `direct.ai-scoping` → executor  
-
----
-
-## Extension
-
-New pre feature ⇒ new `PreTaskHandler` + register. For synthesis-like behavior, prefer **Xynthesis** (see platform doc §1b) instead of parallel prompt systems.

package/.docs/prefer-openrouter-routing-policy.md

@@ -1,114 +0,0 @@
-# `PREFER_OPENROUTER` routing policy (Exellix stack)
-
-Normative contract for **OpenRouter vs vendor-direct** model routing across `@exellix/ai-tasks`, `@exellix/graph-engine`, graphs-studio, and `@x12i/ai-profiles` consumers.
-
-## Summary
-
-| Env / API field | Meaning |
-|-----------------|---------|
-| **`PREFER_OPENROUTER`** | Operator **preference**: use OpenRouter when an OpenRouter API key is available. |
-| **`preferOpenRouter`** | Same semantics as env; use on `resolveInvocationPlan({ policy })` and model-resolution options. |
-
-**Vendor API keys** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …) do **not** change this policy. They are used only when effective routing is **direct**. To force vendor-direct routing, set `PREFER_OPENROUTER=false`.
-
----
-
-## Decision table (effective routing)
-
-After resolving `preferOpenRouter` (explicit → env → default **`true`**):
-
-| `preferOpenRouter` | `OPENROUTER_API_KEY` / `OPEN_ROUTER_KEY` | **Effective routing** | Wire model id (example) |
-|--------------------|--------------------------------------------|------------------------|-------------------------|
-| `false` | (any) | **direct** | `anthropic/claude-sonnet-4-5` |
-| `true` | present | **openrouter** | `openrouter/anthropic/claude-sonnet-4.5` |
-| `true` | absent | **direct** (fallback) + warning | `anthropic/claude-sonnet-4-5` |
-
-**Prefer** means “use OpenRouter when you *can*”; missing key → honest direct fallback.
-
----
-
-## Environment
-
-```env
-# Prefer OpenRouter when OPENROUTER_API_KEY is set (default when omitted)
-PREFER_OPENROUTER=true
-
-# Force vendor-direct for all phases (MAIN + PRE/POST resolution)
-# PREFER_OPENROUTER=false
-
-OPENROUTER_API_KEY=sk-or-...
-ANTHROPIC_API_KEY=sk-ant-...   # used only when effective routing is direct
-```
-
----
-
-## API (`@exellix/ai-tasks`)
-
-```ts
-import { resolveInvocationPlan } from "@exellix/ai-tasks";
-
-const plan = await resolveInvocationPlan({
-  profiles: {
-    preActionModel: "cheap",
-    skillModel: "cyber@default",
-    postActionModel: "cheap",
-  },
-  policy: {
-    preferOpenRouter: true,
-    openrouterApiKeyPresent: !!process.env.OPENROUTER_API_KEY,
-  },
-});
-```
-
-Policy fields on `resolveInvocationPlan`, `resolveProfileInvocationRouting`, and `resolveModelReference`:
-
-- **`preferOpenRouter`** — operator preference (see decision table).
-- **`openrouterApiKeyPresent`** — optional snapshot; defaults to env detection in-process.
-
-Internal mapping to `@x12i/ai-profiles`:
-
-```ts
-resolveAIProfile(profile, {
-  preferOpenRouter: effectivePreferOpenRouter, // from resolvePreferOpenRouterPolicy()
-});
-```
-
----
-
-## Per-phase behavior (`runTask`)
-
-All phases (PRE / MAIN / POST) use the **same** `resolvePreferOpenRouterPolicy()` snapshot at plan and execute time.
-
-| Phase | Consumer | Notes |
-|-------|----------|-------|
-| PRE / POST | `@exellix/xynthesis` | Alias on wire; xynthesis resolves via ai-profiles with same effective routing. |
-| MAIN (skill) | `@exellix/ai-skills` | Concrete model id on wire; must include `openrouter/` prefix when effective routing is openrouter. |
-
-Plan output: trust **`routing`** + **`engineLabel`**, not model-id prefix alone.
-
----
-
-## Migration checklist (other components)
-
-### graphs-studio / BFF
-
-- [ ] POST `/api/exellix/invocation-plan` body: `policy.preferOpenRouter`.
-- [ ] Simulate Engine layer: call `resolveInvocationPlan` only; do not re-derive from choices matrix.
-- [ ] Update UI copy: “prefers OpenRouter when key present” vs “always OpenRouter”.
-
-### `@exellix/graph-engine`
-
-- [ ] Pass `policy: { preferOpenRouter, openrouterApiKeyPresent }` into `resolveInvocationPlan` before execute.
-- [ ] Thread same snapshot into `runTask` policy (when execute parity lands on request env).
-
-### `@exellix/xynthesis`
-
-- [ ] Funcx OpenRouter client: align with effective routing fallback when key missing.
-
----
-
-## Related
-
-- [`.docs/ai-tasks-model-profile-aliases-7x.md`](ai-tasks-model-profile-aliases-7x.md) — profile slots on `RunTaskRequest`
-- `src/invocation/preferOpenRouterPolicy.ts` — implementation in ai-tasks
-- `src/invocation/resolveInvocationPlan.ts` — pre-run plan API