@exellix/ai-tasks 7.8.0

package/documenations/feature-request-ai-skills-raw-template-access.md

@@ -0,0 +1,82 @@
+# 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.
+

package/documenations/feature-request-athenix-core-directive.md

@@ -0,0 +1,145 @@
+# Feature Request: Athenix `core:` Directive Tokens
+
+## Summary
+
+Add first-class support in `@x12i/rendrix` for semantic directive tokens:
+
+- `{{core:analysis}}`
+- `{{core:decision}}`
+- `{{core:question}}`
+
+These are **not** memory paths and must not be resolved via normal object lookup.
+
+## Why
+
+`@exellix/ai-tasks` uses template-declared task semantics to drive structured synthesis.
+
+Using path-like syntax such as `{{core.analysis}}` is incorrect because parser/runtime treats it as:
+
+- lookup object `core`
+- then property `analysis`
+
+That conflates semantic declaration with data lookup and causes false missing-token errors.
+
+We need directive syntax where `core:` is a command namespace, not path traversal.
+
+## Requested Behavior
+
+### 1) Parse `core:` as directive token (not path token)
+
+When parser sees:
+
+- `{{core:analysis}}`
+
+it should emit a dedicated token type (example `kind: "core"` or `kind: "directive"` with `directive: "core"`).
+
+It must **not** classify this as path/helper token.
+
+### 2) Do not perform memory-path resolution for `core:` tokens
+
+Renderer should not try to read:
+
+- `workingMemory.core.analysis`
+
+for `{{core:analysis}}`.
+
+No missing-path error should be thrown due to absent `core` object.
+
+### 3) Introspection output must expose directive value
+
+`listTokens()` (or equivalent) should include structured fields, e.g.:
+
+```ts
+{
+  kind: "core",
+  raw: "core:analysis",
+  directive: "core",
+  value: "analysis",
+  start: 123,
+  end: 141
+}
+```
+
+## API / Type Additions (Conceptual)
+
+```ts
+export type TemplateTokenKind =
+  | "path"
+  | "helper"
+  | "block"
+  | "core"
+  | "unknown";
+
+export interface TemplateTokenRef {
+  raw: string;
+  kind: TemplateTokenKind;
+  path?: string;        // only for path-kind
+  directive?: string;   // "core" for core-kind
+  value?: string;       // "analysis" for core-kind
+  start: number;
+  end: number;
+}
+```
+
+Optional utility:
+
+```ts
+export function listDirectiveValues(
+  template: string,
+  directive: string
+): string[];
+```
+
+## Rendering Semantics
+
+For `core:` tokens:
+
+- default render output can be empty string (`""`) unless overridden,
+- or configurable render policy (e.g. keep literal / empty / custom formatter),
+- but never path lookup failure.
+
+For all other required tokens:
+
+- existing strict behavior remains unchanged.
+
+## Validation Rules
+
+Parser-level validation should enforce:
+
+- `{{core:...}}` must include non-empty value segment
+- whitespace-trimmed value allowed (`{{core: analysis}}` -> `analysis`)
+
+Optional strict mode (consumer-level) can validate value against allowed set.
+
+## Backward Compatibility
+
+- Additive change.
+- Existing path tokens keep current behavior.
+- No change required for templates not using `core:`.
+
+## Acceptance Criteria
+
+1. `listTokens("...{{core:analysis}}...")` returns token with `kind: "core"` and `value: "analysis"`.
+2. Rendering template containing `{{core:analysis}}` does not throw missing-path errors when no `core` object exists.
+3. Existing strict missing-token behavior for non-core path tokens is unchanged.
+4. Unit tests added for:
+   - single and multiple core directives
+   - whitespace around colon/value
+   - invalid `{{core:}}`
+   - coexistence with normal path/helper tokens
+
+## Example
+
+Template:
+
+```md
+System contract:
+- {{core:analysis}}
+- {{core:decision}}
+```
+
+Expected:
+
+- introspection detects two core directives: `analysis`, `decision`
+- rendering does not require `core.analysis` or `core.decision` in memory
+

package/documenations/feature-request-athenix-token-extraction.md

@@ -0,0 +1,124 @@
+# Feature Request: Athenix Token Introspection and Selective Resolution
+
+## Summary
+
+`@exellix/ai-tasks` needs first-class support in Athenix parser for:
+
+1. Inspecting templates to discover tokens before rendering.
+2. Resolving values for a selected token set from a runtime context, without fully rendering output.
+
+This is required to implement template-contract-driven semantics (for example task core tokens) in a deterministic, pre-render-safe way.
+
+## Problem
+
+Current behavior in downstream runtime integrations can make full-template rendering unsuitable as a source of truth for semantic discovery:
+
+- Semantic tokens may be transformed/removed by template rendering pipelines.
+- Some integrations lazily initialize content resolvers.
+- Full rendered text is a poor boundary for extracting contract-level meaning.
+
+For `ai-tasks`, we must:
+
+- discover semantic tokens from template contract (`{{...}}`) pre-render,
+- then resolve token values against runtime memory/context,
+- then drive synthesis and execution from those resolved semantics.
+
+Without parser-native support, we are forced into brittle string probing.
+
+## Requested Capability
+
+### 1) Token Introspection API
+
+Return token metadata from a template without rendering.
+
+Conceptual API:
+
+```ts
+export interface TemplateTokenRef {
+  raw: string;             // original token expression
+  path?: string;           // normalized dot-path if applicable
+  kind: "path" | "helper" | "block" | "unknown";
+  start: number;           // source offset
+  end: number;             // source offset
+}
+
+export function listTokens(template: string, options?: {
+  includeDuplicates?: boolean; // default false
+}): TemplateTokenRef[];
+```
+
+### 2) Selective Token Resolution API
+
+Resolve only requested tokens from context, without full template rendering.
+
+Conceptual API:
+
+```ts
+export interface ResolveTokenValuesInput {
+  template: string;
+  context: Record<string, unknown>;
+  selectors: string[]; // e.g. ["core.*", "question", "metadata.intent"]
+  options?: {
+    strict?: boolean; // throw if selected token missing/invalid
+  };
+}
+
+export interface ResolvedTokenValue {
+  token: string;              // matched token expression
+  selector: string;           // selector that matched
+  value: unknown;             // resolved value
+  found: boolean;
+}
+
+export function resolveTokenValues(
+  input: ResolveTokenValuesInput
+): ResolvedTokenValue[];
+```
+
+## Behavioral Requirements
+
+1. **Pre-render safe**: no dependency on rendered final text.
+2. **Deterministic**: same template+context => same result.
+3. **Selector support**: dot-path and wildcard matching (`core.*`).
+4. **No implicit coercion surprises**: raw `unknown` values should be returned.
+5. **Stable with missing values**: explicit `found: false` (or strict throw).
+6. **Works with current Athenix token syntax** used across Woroces stack.
+
+## Why This Matters
+
+For template-driven orchestration, semantics belong to the template contract.
+The runtime should not infer semantics from caller hints or post-render text.
+
+Parser-native token introspection + selective resolution enables:
+
+- reliable template core discovery,
+- robust runtime validation,
+- traceable synthesis inputs,
+- less integration-specific glue logic.
+
+## Real Integration Use Case (`@exellix/ai-tasks`)
+
+Structured synthesis requires:
+
+- detect template core tokens (for example `core.analysis`, `core.decision`),
+- resolve relevant values from memory/context,
+- block execution when required semantic tokens are absent.
+
+This must happen before synthesis prompt rendering and must not rely on rendered output text.
+
+## Acceptance Criteria
+
+1. Add parser APIs (or equivalent methods) for token listing and selective token value resolution.
+2. Include docs with examples for token selectors and missing-token handling.
+3. Add tests for:
+   - nested paths,
+   - wildcard selectors,
+   - missing tokens in strict/non-strict mode,
+   - duplicate token references,
+   - mixed token kinds.
+4. Confirm compatibility with existing template render pipeline.
+
+## Notes
+
+- This request is additive; it should not break existing `render()` usage.
+- If preferred, these capabilities can be exposed under a utility namespace instead of top-level exports.

package/documenations/funcx-catalog-hosting-checklist.md

@@ -0,0 +1,107 @@
+# FuncX catalog / hosting — checklist for `@exellix/ai-tasks` (+ optional web-scope)
+
+`runTask()` invokes **`run(functionId, payload, { client })`** from **`@x12i/funcx/functions`** for planner and optimizer rows. **Nothing in ai-tasks registers those functions** — your **FuncX library / Catalox content / resolver** must expose them so **`run()`** resolves at runtime.
+
+Use this as your deployment checklist. Wire contracts (envelope + adapters) are summarized in [`funcx-scoping-integration-gaps.md`](./funcx-scoping-integration-gaps.md) §6.
+
+---
+
+## 1. Required function IDs (MAIN wrappers)
+
+| Capability | Canonical `functionId` | Router hyphen alias (often supported) |
+|------------|------------------------|---------------------------------------|
+| Planner | `execution/plan` | `execution-plan` |
+| Optimizer | `execution/evaluate-result` | `execution-evaluate-result` |
+
+Constants in this repo: [`src/execution-strategies/constants.ts`](../src/execution-strategies/constants.ts) — `FUNCX_EXECUTION_PLAN_FUNCTION_ID`, `FUNCX_EXECUTION_EVALUATE_RESULT_FUNCTION_ID`.
+
+## 2. Optional function ID (web-scope via FuncX)
+
+| Capability | Canonical `functionId` |
+|------------|----------------------|
+| Research / web-scope questions | `research/plan-questions` |
+
+Used only when callers run **`runPlanWebScopeQuestions({ backend: "funcx", … })`** or when another host calls **`run()`** with the payload from **`buildResearchPlanQuestionsPayload`** (see [`genericExecutionFuncxEnvelope.ts`](../src/execution-strategies/genericExecutionFuncxEnvelope.ts)).
+
+Constant: **`FUNCX_RESEARCH_PLAN_QUESTIONS_FUNCTION_ID`**.
+
+---
+
+## 3. Request envelope (must match)
+
+All three use the **generic execution envelope** (see **`GenericExecutionEnvelope`** and **`genericExecutionEnvelopeJsonSchema`** exported from **`@x12i/funcx/functions`**):
+
+- **`goal`** — string (required at runtime for built-ins).
+- **`input`**, **`context`**, **`result`** (optimizer only) — opaque JSON-safe values.
+- **`args`** — behavior knobs; planner/optimizer omit **`functionId`** from `args` on the wire (transport uses top-level id).
+- **`attribution`** — correlation; implementations should merge into nested **`ask()`** via **`buildAskAttribution`** / **`AskOptions.attribution`** (see FuncX ≥3.8.2).
+
+**Planner/optimizer payloads** are built in-repo by **`buildPlannerGenericPayload`** / **`buildOptimizerGenericPayload`**.
+
+---
+
+## 4. Response shape (what ai-tasks parses)
+
+After **`run()`**, JSON is normalized with **`getRunJsonResult`** (see **`unwrapFuncxRunValue`** in ai-tasks). Then:
+
+- Planner → **`adaptExecutionPlanResult`** → merged into `instructions` / `prompt` / `variables` / `templateTokens`.
+- Optimizer → **`adaptEvaluateResultResponse`** → `satisfied`, `feedback`, `variables`, `templateTokens`.
+
+Your FuncX implementations must return **one JSON object** compatible with those adapters (see §6 tables in [`funcx-scoping-integration-gaps.md`](./funcx-scoping-integration-gaps.md)).
+
+---
+
+## 5. Where hosting work happens (upstream)
+
+Authoritative procedures live in the **FuncX** repository and your **Catalox / content** pipeline — not in ai-tasks.
+
+| Resource | Purpose |
+|----------|---------|
+| [`https://github.com/x12i/funcx`](https://github.com/x12i/funcx) | Source of truth for **`run()`**, content layout, sync scripts, tests for generic execution/research. |
+| **`@x12i/funcx` npm** (≥ **3.8.2**) | **`run`**, **`getRunJsonResult`**, **`GenericExecutionEnvelope`**, **`genericExecutionEnvelopeJsonSchema`**, **`buildAskAttribution`**. |
+| FuncX **package scripts** (maintainers) | Examples: `content:fill-catalox`, `content:sync`, `content:index` — run in **your** CI/deploy after cloning FuncX with proper `.env` / Catalox credentials. |
+
+**Your checklist:**
+
+1. Confirm the three **function definitions** (instructions + JSON schema + routing id) exist in the FuncX **content tree** / catalog your resolver reads.
+2. Run your org’s **content sync / index** so **`run("execution/plan", …)`** resolves in **dev, staging, prod** (same steps you use for other FuncX functions).
+3. Configure **API keys / OpenRouter / FuncX client** where **`createClient({ backend: "openrouter" })`** is used (same as other FuncX calls from Node).
+4. Smoke-test **`run()`** once per environment with a minimal payload (see §6).
+5. If you use **web-scope FuncX**, register **`research/plan-questions`** the same way.
+
+---
+
+## 6. Minimal verification (after deploy)
+
+From any Node context that uses the same **`@x12i/funcx`** client options as production:
+
+```ts
+import { createClient } from "@x12i/funcx";
+import { run, getRunJsonResult } from "@x12i/funcx/functions";
+
+const client = createClient({ backend: "openrouter" });
+const raw = await run(
+  "execution/plan",
+  {
+    goal: "Smoke test execution/plan registration.",
+    input: {},
+    context: { skillKey: "smoke.skill" },
+    attribution: { tags: { caller: "smoke-test" } },
+  },
+  { client }
+);
+const json = getRunJsonResult(raw);
+console.log("execution/plan ok:", json && typeof json === "object");
+```
+
+Repeat with **`execution/evaluate-result`** (include a dummy **`result`** object) and, if needed, **`research/plan-questions`**.
+
+If **`run()`** throws **unknown function** / **404** / resolver errors, the **catalog or index** for that environment is incomplete — fix hosting before relying on **`runTask`** with planners or optimizers.
+
+---
+
+## 7. Related docs in this repo
+
+- [`RUNTASK_REQUEST.md`](../RUNTASK_REQUEST.md) — `executionStrategies`, FuncX behavior.
+- [`BREAKING-CHANGES.md`](../BREAKING-CHANGES.md) — default ids + **`@x12i/funcx` ≥ 3.8.2**.
+- [`funcx-scoping-integration-gaps.md`](./funcx-scoping-integration-gaps.md) — FR tracker + contracts.

package/documenations/funcx-scoping-integration-gaps.md

@@ -0,0 +1,120 @@
+# FuncX — gaps and feature requests (from `@exellix/ai-tasks`)
+
+This package routes **AI scoping** (and any other callers of `runLlmTextCall`) through **FuncX** (`@x12i/funcx`: `createClient` + `Client.ask`). **Audit / polish post-steps** and **synthesized-context** synthesis use **`@exellix/xynthesis`** (`executeXynthesisAction` / structured gateway), not direct FuncX in those paths. The items below are **not** workarounded in ai-tasks: they are tracked here for upstream improvement.
+
+**Note:** `jobId` / `agentId` are not passed on the **scoping** `ask()` path because the narrow helper used here does not yet thread them through `AskOptions`. Post-step audit/polish pass `jobId` / `agentId` into xynthesis where supported. Task identity remains on `RunTaskRequest` for Activix and other orchestration layers.
+
+## 1. Correlation: job / agent / task identity on `ask()`
+
+**Need:** Every internal call used to carry stable `jobId` and `agentId` (and sometimes skill context) so logs and activity backends can tie completions to a task run.
+
+**Update (@x12i/funcx ≥ 3.6):** `AttributionContext` now includes optional **`jobId`**, **`taskId`**, and **`agentId`** (alongside `functionId`, `projectId`, `traceId`, `tags`). OpenRouter attribution can use `formatOpenRouterUserField(attribution)` where applicable.
+
+**Remaining gap for other call sites:** Not every ai-tasks code path sets these fields on `ask()` yet (e.g. narrow scoping helpers may still omit them). Prefer threading identity from `RunTaskRequest` into `AskOptions.attribution` wherever FuncX is invoked directly.
+
+## 2. High-level “one completion” helper
+
+**Need:** Callers want a single operation: system prompt + user prompt + optional model + timeout → text (and usage), with sensible defaults when `model` is omitted (preset / env).
+
+**Update (@x12i/funcx ≥ 3.6):** **`askOnce`** is exported from the main package (uses `resolveOptionsFromMode` / presets when `model` is omitted). Prefer it for new call sites instead of hand-rolling `AskOptions` when a single completion is enough.
+
+## 3. System-only prompts (empty user message)
+
+**Need:** Some flows put the entire instruction in the system role and pass an empty or minimal user message (e.g. synthesis-style prompts that historically used `workingMemory.input: ""`).
+
+**Update (@x12i/funcx ≥ 3.6):** **`askOnce`** documents using a minimal placeholder user message (e.g. zero-width space) when the entire instruction lives in **`system`** — follow that pattern for portability.
+
+**Remaining:** Confirm per-backend behavior when callers bypass `askOnce` and send raw empty user content.
+
+## 4. Mock / test ergonomics
+
+**Need:** Unit tests inject a fake LLM that returns deterministic `AskResult` without constructing a real client.
+
+**Update (@x12i/funcx ≥ 3.6):** **`createAskMock`**, **`makeAskResult`**, and **`makeUsage`** are exported from `@x12i/funcx` for lightweight doubles.
+
+## 5. Structured usage / cost on `AskResult`
+
+**Need:** Downstream code sometimes surfaced gateway-style `activityId`, cost, or raw provider fields for observability.
+
+**Today:** `AskResult` exposes `text`, `usage`, `model?`, `raw?`. Fine-grained cost semantics live in `usage` / `raw` depending on provider.
+
+**Ask:** If not already stable, document how OpenRouter cost and IDs appear on `AskResult.raw` / `usage` so orchestrators can map to their activity model without adapter-specific parsing.
+
+---
+
+## 6. Execution-strategy FuncX functions (`runTask` MAIN wrappers) — **FR tracker**
+
+**Hosting checklist (catalog / prod):** [`funcx-catalog-hosting-checklist.md`](./funcx-catalog-hosting-checklist.md) — ensure **`execution/plan`**, **`execution/evaluate-result`**, and optionally **`research/plan-questions`** are registered where **`run()`** resolves.
+
+**How FuncX fits:** Each capability is a **`functionId`** (e.g. **`execution/plan`**). `@exellix/ai-tasks` does **not** embed prompts for these steps; it calls **`run(functionId, payload, { client })`** from **`@x12i/funcx/functions`**. Payloads use a **single generic envelope** (`goal`, `input`, `context`, `result?`, `args`, `attribution`). Responses are adapted in-repo ([`genericExecutionFuncxEnvelope.ts`](../src/execution-strategies/genericExecutionFuncxEnvelope.ts)) into gateway merge types.
+
+**Call-site constants (defaults):** [`src/execution-strategies/constants.ts`](../src/execution-strategies/constants.ts) — **`FUNCX_EXECUTION_PLAN_FUNCTION_ID`**, **`FUNCX_EXECUTION_EVALUATE_RESULT_FUNCTION_ID`**, **`FUNCX_RESEARCH_PLAN_QUESTIONS_FUNCTION_ID`**. Per-invocation override: **`executionStrategies[].args.functionId`** only when the target accepts the **same** generic envelope.
+
+**Consumer:** [`runFuncxExecutionStrategy.ts`](../src/execution-strategies/runFuncxExecutionStrategy.ts) (`runPlannerFuncx`, `runOptimizerFuncx`).
+
+| FR id | Topic | Status |
+|-------|--------|--------|
+| **FR-EXEC-1** | FuncX **`execution/plan`** — generic execution planning | **Contract:** generic envelope in + structured plan / instructions / steps out; ai-tasks maps into `instructions` / `prompt` / `variables` / `templateTokens` |
+| **FR-EXEC-2** | FuncX **`execution/evaluate-result`** — MAIN output judgment | **Contract:** generic envelope + **`result`** (MAIN summary); ai-tasks maps `suggestedChanges` / `issues` into feedback / `variables.optimizerSuggestedChanges` |
+| **FR-EXEC-3** | Correlation on nested **`ask()`** | **`attribution`** on outbound envelope includes **`runId` / `subjectId` / `actorId`** and **`tags`** (`jobId`, `taskId`, `agentId`, `caller: ai-tasks`). FuncX implementations should forward into **`AskOptions.attribution`**. |
+| **FR-EXEC-4** | FuncX **`research/plan-questions`** — web-scope / research questions | **Wiring:** `runPlanWebScopeQuestions({ backend: "funcx" })` or hosts call **`run()`** directly with the same envelope built by **`buildResearchPlanQuestionsPayload`**. |
+
+**Tests (no live FuncX):** **`setFuncxExecutionStrategyInvoker()`** stubs planner/optimizer **`run()`** calls.
+
+---
+
+### FR-EXEC-1 — `execution/plan` (planner)
+
+**Purpose:** Before the **first** MAIN `runSkill` call, refine how the skill runs. **`runTask` invokes this at most once per planner row** (sorted by `priority`).
+
+**Function id (canonical):** `execution/plan` (hyphen alias: `execution-plan` accepted by FuncX router).
+
+**Input — generic envelope** (second argument to **`run()`**). Built by **`buildPlannerGenericPayload`**: **`goal`** from skill context; **`input`** = task **`input`**; **`context`** = memories, **`skillKey`**, ids, **`variables`**, etc.; **`args`** = strategy row **`args`** minus **`functionId`**; **`attribution`** from correlation ids.
+
+**FuncX output shape** (indicative): `plan`, `instructions`, `steps[]`, `assumptions[]`, `missingInputs[]`, optional **`prompt` / `variables` / `templateTokens`** or the same under **`metadata`**. **`adaptExecutionPlanResult`** prefers **`instructions`**, then **`plan`**, then rendered **`steps`**, and appends assumptions / missing-input lists into **`instructions`** when present.
+
+**Behavior requirements:** Single JSON object; must **not** execute MAIN; forward **`attribution`** on internal **`ask()`** calls.
+
+---
+
+### FR-EXEC-2 — `execution/evaluate-result` (optimizer)
+
+**Purpose:** After **each** MAIN attempt, judge **`result`** and optionally suggest changes. **`runTask` uses only the first optimizer row** after sort.
+
+**Function id (canonical):** `execution/evaluate-result` (hyphen: `execution-evaluate-result`).
+
+**Input:** Same envelope as FR-EXEC-1 plus **`result`** = bounded MAIN summary (`rawText` ~12k, **`parsed`**, **`metadata`** summarized). **`args.iterationIndex`** is zero-based.
+
+**Output:** **`satisfied`** (boolean), **`feedback`**, **`suggestedChanges[]`**, **`issues[]`**, optional **`variables` / `templateTokens` / `metadata`**. **`adaptEvaluateResultResponse`** merges suggested changes and issues into **`feedback`** and sets **`variables.optimizerSuggestedChanges`** when useful.
+
+---
+
+### FR-EXEC-3 — Correlation on `ask()` for execution-strategy functions
+
+**Need:** **`jobId`**, **`taskId`**, **`agentId`** on every internal LLM call for planner/optimizer/research planning.
+
+**Today (@exellix/ai-tasks):** Outbound payloads include **`attribution`** derived from **`buildExecutionStrategyRequestPayload`** fields. FuncX function implementations should copy **`attribution`** (and/or **`context`**) into **`AskOptions.attribution`** for nested calls.
+
+**Overrides:** Custom **`args.functionId`** targets must honor the **same** envelope and attribution expectations.
+
+---
+
+### FR-EXEC-4 — `research/plan-questions` (web-scope / research question planner)
+
+**Purpose:** Produce **structured research / web-scope questions** for Studio (**Web scoping mode = AI-driven**). Downstream sets **`RunTaskRequest.narrix.webScopeQuestions`** with `source: "ai-driven"` (see [`documenations/web-scoping-in-ai-tasks.md`](./web-scoping-in-ai-tasks.md)).
+
+**Function id (canonical):** `research/plan-questions` (constant **`FUNCX_RESEARCH_PLAN_QUESTIONS_FUNCTION_ID`**).
+
+**Runtime (@exellix/ai-tasks):** Default **`runPlanWebScopeQuestions`** uses **`backend: "xynthesis"`** (prompt + **`parseAndValidatePlanWebScopeQuestionsOutput`**). Set **`backend: "funcx"`** for **`run()`** with **`buildResearchPlanQuestionsPayload`** and **`adaptResearchPlanQuestionsResult`**. Tests may use **`setResearchPlanQuestionsFuncxInvoker`**.
+
+**Input — generic envelope:** **`goal`** = node question; **`input`** = `{ nodeInput, rawRecord? }`; **`context`** = memory / xynthesized summaries; **`args`** includes **`maxQuestions`**, **`sourceType: "web"`**, **`allowSkip: true`**.
+
+**Output — FuncX generic:** `questions[]` with **`question`**, optional **`reason`**, etc. Ai-tasks adapts to **`PlanWebScopeQuestionsOutput`** (stable **`source: "ai-driven"`**, generated **`id`** when missing).
+
+**Correlation (FR-EXEC-3):** Forward **`attribution`** into internal **`ask()`** like other generic functions.
+
+**Tests:** Xynthesis: **`setSynthesisInvoker`**. FuncX: **`setResearchPlanQuestionsFuncxInvoker`** (`test/planWebScopeQuestions/*.test.ts`).
+
+---
+
+**Version note:** Generic execution-strategy **`run()`** payloads, **`getRunJsonResult`**, and **`attribution`** align with **@x12i/funcx** **≥ 3.8.2** recommended. **@exellix/xynthesis** may still use FuncX under the hood on other paths; §1 notes remaining scoping gaps.