@exellix/ai-tasks 8.5.0 → 8.5.3

package/documenations/upstream-feature-requests/funcx-generic-xynthesis-hosting.md

@@ -0,0 +1,268 @@
+# `@x12i/funcx` — generic envelope hosting for xynthesis-domain capabilities
+
+**Filed by:** `@exellix/ai-tasks` + `@exellix/xynthesis`  
+**Baseline reviewed:** `@x12i/funcx` **4.4.0** (npm; `xynthesis` dependency `^4.4.0`)  
+**Consumers:** `@exellix/xynthesis` 4.4+ (LLM orchestration), `@exellix/ai-tasks` 8.5+ (envelope builders + adapters)  
+**Out of scope:** `@exellix/ai-skills` MAIN gateway prompts
+
+**Related:**
+
+- [**funcx-pre-post-sidekick-actions.md**](./funcx-pre-post-sidekick-actions.md) — pre/post sidekick built-ins + `SidekickGenericEnvelope`
+- [`funcx-scoping-integration-gaps.md`](../funcx-scoping-integration-gaps.md) §6 — execution-strategy adapter contracts
+- [`funcx-catalog-hosting-checklist.md`](../funcx-catalog-hosting-checklist.md) — deploy / smoke-test checklist
+- Consumer map: `xynthesis/src/catalog/sidekickFuncxCatalogMap.ts`, `xynthesis/src/sidekickFuncxEnvelope.ts`
+- Envelope builders: [`genericExecutionFuncxEnvelope.ts`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts), [`auditChecklistFuncxEnvelope.ts`](../../src/post-steps/audit/auditChecklistFuncxEnvelope.ts)
+
+---
+
+## 0. Target architecture
+
+| Layer | Responsibility |
+|-------|----------------|
+| **FuncX** | Host prompts (Catalox `fx/*` content + `content:primitives:sync`), validate I/O, `run(functionId, envelope, runOptions)` |
+| **xynthesis** | Model resolve, Optimixer / `outputExpectation`, JSON parse, Activix, `InvokeAttemptSummary`; gate FuncX prompts with `XYNTHESIS_FUNCX_SIDEKICK=1` |
+| **ai-tasks** | Build envelopes; merge adapted JSON into `RunTaskRequest`; no inline `DEFAULT_SYSTEM` for migrated steps |
+
+**Two envelope families** (do not conflate):
+
+1. **`GenericExecutionEnvelope`** — `@x12i/funcx/functions` type for **execution / research** built-ins (`execution/plan`, `execution/evaluate-result`, `research/plan-questions`, …).
+2. **`SidekickGenericEnvelope`** — defined in **xynthesis** (`sidekickFuncxEnvelope.ts`) for **pre/post sidekick** built-ins (`pre/synthesize`, `post/audit`, …). FuncX should accept the same *shape* at `run()` time; a dedicated exported type is optional (FR-PRE-POST-8).
+
+---
+
+## 1. FuncX 4.4.0 — shipped structure (source of truth)
+
+Reviewed from `@x12i/funcx` **4.4.0** (`dist/functions`, README). Use this when implementing or extending FRs.
+
+### 1.1 Call surface
+
+```ts
+import { run, getRunJsonResult, buildAskAttribution } from "@x12i/funcx/functions";
+import type { GenericExecutionEnvelope } from "@x12i/funcx/functions";
+
+const raw = await run("execution/plan", envelope, {
+  client,
+  model: resolvedSlug,
+  timeoutMs: 60_000,
+  responseFormat: { kind: "json_object" },
+  includeUsage: true,
+});
+const json = getRunJsonResult(raw);
+```
+
+| Mechanism | Behavior |
+|-----------|----------|
+| **Id normalization** | Slash ids in constants (`execution/plan`) → hyphen registry keys (`execution-plan`) inside router |
+| **Constants** | `FUNCX_EXECUTION_PLAN_FUNCTION_ID`, `FUNCX_EXECUTION_EVALUATE_RESULT_FUNCTION_ID`, `FUNCX_RESEARCH_PLAN_QUESTIONS_FUNCTION_ID` |
+| **Schema** | `genericExecutionEnvelopeJsonSchema` (draft Ajv object; `goal` required at runtime for built-ins) |
+| **Unwrap** | `getRunJsonResult` / `isHttpRunSuccessBody` — HTTP `{ result, usage }` vs in-process plain object |
+
+### 1.2 `GenericExecutionEnvelope` (shipped)
+
+```ts
+type GenericExecutionEnvelope = {
+  goal?: unknown;       // runtime: non-empty string for execution/research built-ins
+  input?: unknown;
+  context?: unknown;
+  result?: unknown;     // optimizer / evaluate-result
+  args?: Record<string, unknown>;
+  attribution?: Record<string, unknown>;
+  client?: Client;      // in-process only; omit on HTTP
+};
+```
+
+**Not on the type today:** `strategyArgs` (xynthesis merges into `args` before `run()` — see §2.3).
+
+### 1.3 `buildAskAttribution` (shipped)
+
+`buildAskAttribution(implFunctionId, req)` merges:
+
+- Top-level / `attribution.*`: `projectId`, `traceId`, `jobId`, `taskId`, `agentId`, `runId`, `parentRunId`, `actorId`, `subjectId`
+- `attribution.tags` and top-level `tags`
+- Preserves implementing `functionId`; stores caller `attribution.functionId` in `tags.callerFunctionId`
+
+**xynthesis / ai-tasks today:** `buildSidekickFuncxAttribution` / `buildExecutionStrategyAttribution` set `runId`←jobId, `subjectId`←taskId, `actorId`←agentId — compatible with FuncX merge rules.
+
+### 1.4 `RunOptions` (shipped — partial vs orchestrator needs)
+
+| Field | Shipped in 4.4.0 |
+|-------|------------------|
+| `client`, `model`, `backend`, `timeoutMs`, `signal` | Yes |
+| `responseFormat` (`json_object` / text) | Yes |
+| `includeUsage`, `validateOutput`, `profile` (race) | Yes |
+| `temperature`, `topP`, `reasoningEffort` | **No** on `RunOptions` (still use `Client.ask` / xynthesis `FuncxInvoker` for sampling) |
+
+### 1.5 Hosting model (content + router)
+
+| Class | Examples | How prompts run |
+|-------|----------|-----------------|
+| **Content-backed** | `execution-plan`, `execution-evaluate-result`, `research-plan-questions`, `research-plan-web-search`, `research-plan-scoped-questions` | Catalox `fx/{id}/` via `executeFuncxFromContent`; instructions rendered with `renderInstructionTemplate(instructions, { input: request, variables })` where **`request` is the full envelope** passed to `run()` |
+| **Code-bound router** | Primitives, runx.*, repair JSON, … | TS handlers; generic execution family delegates to `run("execution-plan", …)` |
+| **Legacy (deprecate)** | `ai-tasks-plan-task`, `ai-tasks-optimizer-evaluate` | Hyphen ids; same envelope family; superseded by `execution-plan` / `execution-evaluate-result` |
+
+**Seed bundle:** `content-seed/functions/genericExecutionResearch.seed.json` → `npm run content:primitives:sync` (see FuncX README § Catalox merged primitive seeds).
+
+**Executor primitives (all functions):** `executeFuncx` → `callAI` with `buildFuncxUserPrompt(buildPrompt(request))` — user message is JSON (or prefixed JSON body), not xynthesis-style pre-rendered system+user strings.
+
+### 1.6 Built-in I/O types (shipped — align adapters)
+
+| Registry id | `run()` alias | Input highlights | Output highlights |
+|-------------|---------------|------------------|-------------------|
+| `execution-plan` | `execution/plan` | `goal`, `input?`, `context?`, `args?`, `attribution?` | `plan?`, `instructions?`, `steps[]`, `assumptions[]`, `missingInputs[]`, `metadata?` |
+| `execution-evaluate-result` | `execution/evaluate-result` | + required `result` | `satisfied`, `feedback?`, `suggestedChanges[]`, `issues[]`, `metadata?` |
+| `research-plan-questions` | `research/plan-questions` | same envelope | `questions[]`, `skipped?`, `reasonCodes?`, `confidence?` |
+
+ai-tasks adapters: `adaptExecutionPlanResult`, `adaptEvaluateResultResponse`, `adaptResearchPlanQuestionsResult`.
+
+---
+
+## 2. Consumer prep (shipped in mono-repo)
+
+| Artifact | Package | Status |
+|----------|---------|--------|
+| `sidekickFuncxCatalogMap.ts` | xynthesis | **Shipped** — actionType ↔ `funcxFunctionId` ↔ Catalox catalog |
+| `sidekickFuncxEnvelope.ts` | xynthesis | **Shipped** — `buildSidekickGenericEnvelope`, `buildExecutionStrategyGenericEnvelope` |
+| `ENV_SIDEKICK_FUNCX` (`XYNTHESIS_FUNCX_SIDEKICK=1`) | xynthesis | **Shipped** — gate; no `run()` wiring in gateway yet |
+| Catalox `XynthesisActionItem.funcx` | xynthesis seed | **Shipped** — `functionId` + `contentVersion: "0.0.0-pending-funcx"` |
+| `auditChecklistFuncxEnvelope.ts` | ai-tasks | **Shipped** — `post/audit-checklist`, `post/audit-merge` envelopes |
+| Execution via xynthesis actions | ai-tasks 8.5+ | **Shipped** — not direct `run()` from ai-tasks |
+| `runExecutionStrategyViaXynthesis` | ai-tasks | **Shipped** — still uses xynthesis disk templates + `FuncxInvoker.ask` |
+
+### 2.1 `strategyArgs` merge (consumer — no FuncX FR)
+
+`buildExecutionStrategyGenericEnvelope` folds `req.strategyArgs` into **`args`** (and sets `args.iterationIndex` for optimizer). **Do not** wait for a FuncX type extension; hosts must merge before `run()`.
+
+### 2.2 Template token convention (parity gap)
+
+| Source | User-prompt tokens |
+|--------|-------------------|
+| **xynthesis disk** (`executionStrategyPromptTemplate.ts`) | `goal`, `input_json`, `context_json`, `result_json`, `args_json`, `strategy_args_json`, `iteration_index` |
+| **FuncX content render** (envelope = `request`) | Typically `{{input.goal}}`, `{{input.context}}`, … via rendrix `input` = full envelope |
+
+**FR-GEN-1** (revised): FuncX should export **`envelopeToTemplateVariables(envelope)`** that produces **both** conventions (or document Catalox seeds must use `input.*` paths). Until then, FR-GEN-9 parity diffs must compare normalized renders, not raw file text.
+
+---
+
+## 3. Audit — instructions vs `run()` (current)
+
+| Capability | Prompt host today | Envelope | FuncX built-in 4.4.0 |
+|------------|-------------------|----------|----------------------|
+| execution-plan / optimizer / web-scope | xynthesis templates + `ask` | `GenericExecution*` via builders | **Yes** — not called from xynthesis yet |
+| synthesis, audit, fix, pick-best, craft-final | xynthesis disk / Catalox + `ask` | `SidekickGenericEnvelope` when wired | **No** — see [funcx-pre-post-sidekick-actions.md](./funcx-pre-post-sidekick-actions.md) |
+| ai-tasks checklist audit / merge | ai-tasks Handlebars | `auditChecklistFuncxEnvelope` | **No** (`post/audit-checklist`, `post/audit-merge`) |
+| ai-scoping | inline `SCOPING_SYSTEM` | none | **No** |
+
+---
+
+## 4. Feature request tracker (aligned to 4.4.0)
+
+| FR id | Topic | Status @ 4.4.0 |
+|-------|--------|----------------|
+| **FR-GEN-0** | Baseline: envelope, constants, `buildAskAttribution`, `getRunJsonResult`, execution/research built-ins, `genericExecutionResearch` seed | **Shipped** |
+| **FR-GEN-1** | `envelopeToTemplateVariables` (+ document `input.*` vs `*_json` tokens) | **Open** |
+| **FR-GEN-2** | Per-function `args` JSON Schema + template knobs (`customGuidelines`, …) | **Open** (partially by convention) |
+| **FR-GEN-3** | Published output schemas shared with xynthesis parsers | **Open** (TS types exist; no shared JSON Schema artifact) |
+| **FR-GEN-4** | `RunOptions`: `temperature`, `topP`, `reasoningEffort` | **Open** (partial: model, timeout, responseFormat shipped) |
+| **FR-GEN-5** | `runGenericExecution({ functionId, envelope, runOptions })` embedder helper | **Open** |
+| **FR-GEN-6** | Post-step checklist / merge built-ins | **Open** → FR-PRE-POST-2 |
+| **FR-GEN-7** | AI scoping built-in | **Open** |
+| **FR-GEN-8** | `strategyArgs` on wire | **Closed (consumer)** — merge into `args` in xynthesis |
+| **FR-GEN-9** | Catalox seed ↔ xynthesis template parity CI | **Open** |
+| **FR-GEN-10** | Deprecate `ai-tasks-plan-task` / `ai-tasks-optimizer-evaluate` | **Open** |
+| **FR-GEN-11** | Rich audit `context` sub-schema on envelope | **Open** (checklist envelope shipped in ai-tasks) |
+| **FR-GEN-12** | Golden fixtures package | **Open** |
+| **FR-PRE-POST-*** | Pre/post sidekick built-ins | **Open** — [funcx-pre-post-sidekick-actions.md](./funcx-pre-post-sidekick-actions.md) |
+
+---
+
+## 5. Open FR details (only what 4.4.0 does not cover)
+
+### FR-GEN-1 — Template variables from envelope
+
+**Need:** One function used by content-backed built-ins and xynthesis so Catalox instructions and `xynthesis/templates/*` stay aligned.
+
+**Ask:**
+
+```ts
+envelopeToTemplateVariables(
+  envelope: GenericExecutionEnvelope | SidekickGenericEnvelope
+): Record<string, string>;
+```
+
+Minimum keys: parity with `buildExecutionStrategyUserVars` **and** nested `input.goal` style for `renderInstructionTemplate`.
+
+### FR-GEN-2 — `args` contract
+
+Document reserved keys per `functionId` in `fx/*/meta.json`. Execution/research: `maxQuestions`, `allowSkip`, `sourceType`, `iterationIndex`, `customGuidelines`, `templateMode`, …
+
+### FR-GEN-3 — Shared output JSON Schema
+
+Export versioned schemas next to built-ins; xynthesis `parseExecutionStrategyPayload` / sidekick parsers consume same files.
+
+### FR-GEN-4 — Orchestrator sampling on `run()`
+
+Add optional `temperature`, `topP`, `reasoningEffort` to `RunOptions` (or document that embedders must use `executeFuncxFromContent` + custom `callAI` until then). xynthesis today passes sampling via **`FuncxInvoker.ask`**, not `run()`.
+
+### FR-GEN-5 — `runGenericExecution`
+
+Thin wrapper: resolve content → render → `askJson` → `getRunJsonResult` → return `{ value, usage, model }`. Sidekick variant accepts `SidekickGenericEnvelope` (FR-PRE-POST-5).
+
+### FR-GEN-9 — Seed parity
+
+Compare `genericExecutionResearch.seed.json` + deployed `fx/execution-plan/*` to `xynthesis/templates/execution-*` using **FR-GEN-1** normalized variables.
+
+### FR-GEN-10 — Legacy ids
+
+Alias `ai-tasks-plan-task` → `execution-plan`, `ai-tasks-optimizer-evaluate` → `execution-evaluate-result`; mark deprecated in seed meta.
+
+---
+
+## 6. Convergence path
+
+```mermaid
+flowchart LR
+  subgraph consumers
+    AT[ai-tasks envelope builders]
+    XY[xynthesis run* / gateway]
+  end
+  subgraph funcx44 [FuncX 4.4 shipped]
+    RUN[run slash id]
+    ATTR[buildAskAttribution]
+    SEED[genericExecutionResearch seed]
+  end
+  subgraph funcxNext [FuncX next]
+    PRE[pre/post built-ins]
+    VARS[envelopeToTemplateVariables]
+  end
+  AT --> XY
+  XY -->|XYNTHESIS_FUNCX_SIDEKICK=1| RUN
+  RUN --> ATTR
+  RUN --> SEED
+  PRE --> RUN
+  VARS --> SEED
+```
+
+1. **Done:** execution/research envelopes + built-ins + attribution (4.4.0).
+2. **Next FuncX:** FR-GEN-1, FR-PRE-POST-1..4, FR-GEN-9 (before xynthesis deletes duplicate renderers).
+3. **xynthesis:** Wire `invokeExecutionStrategyAction` / gateway to `run(resolveSidekickFuncxFunctionId(...), envelope, opts)` behind `XYNTHESIS_FUNCX_SIDEKICK=1`.
+4. **ai-tasks:** Switch audit/polish/scoping to envelope + `run()` after post built-ins land.
+
+---
+
+## 7. Non-goals
+
+- ai-skills MAIN `instructions` / `prompt`.
+- Template **cores** (`{{core:analysis}}`) inside FuncX — stay rendrix/ai-skills; `pre/synthesize` envelope carries **pre-rendered** downstream blocks in `input`.
+- Forcing ai-tasks to call `@x12i/funcx` directly for execution strategies (xynthesis remains facade).
+
+---
+
+## 8. Version note
+
+| Package | Version | Notes |
+|---------|---------|-------|
+| `@x12i/funcx` | **4.4.0** (npm latest reviewed) | Baseline for §1 |
+| `@exellix/xynthesis` | **4.4.3** | FuncX map + envelopes; execution hop still disk+ask |
+| `@exellix/ai-tasks` | **8.5.2** | xynthesis actions; checklist envelopes ready |
+
+When FuncX ships pre/post built-ins, bump `contentVersion` on Catalox items from `0.0.0-pending-funcx` and enable `XYNTHESIS_FUNCX_SIDEKICK=1` in CI.

package/documenations/upstream-feature-requests/funcx-pre-post-sidekick-actions.md

@@ -0,0 +1,213 @@
+# `@x12i/funcx` — built-in functions for xynthesis **pre-actions** and **post-actions**
+
+**Filed by:** `@exellix/ai-tasks` + `@exellix/xynthesis`  
+**Baseline:** `@x12i/funcx` **4.4.0** — execution/research generics **shipped**; pre/post ids below are **not** in registry yet  
+**Blocks:** `XYNTHESIS_FUNCX_SIDEKICK=1` production use, ai-tasks audit/polish off Handlebars  
+**Related:** [funcx-generic-xynthesis-hosting.md](./funcx-generic-xynthesis-hosting.md) (4.4.0 baseline + execution FRs)
+
+---
+
+## 0. Problem
+
+**Shipped in FuncX 4.4.0:** `run("execution/plan" | "execution/evaluate-result" | "research/plan-questions", GenericExecutionEnvelope)` with Catalox content under `genericExecutionResearch` seed.
+
+**Not shipped:** Sidekick pre/post capabilities (`pre/synthesize`, `post/audit`, …). Today:
+
+1. xynthesis loads `xynthesis/templates/{actionType}/` or Catalox `pre-actions` / `post-actions` (same bodies).
+2. LLM hop = **`FuncxInvoker.ask(systemPrompt, userPrompt)`** (transport only).
+3. ai-tasks often builds its **own** audit/polish prompts (`loadAuditTemplates`, `DEFAULT_SYSTEM`).
+
+**Target:** Register pre/post built-ins like execution family → `run(functionId, SidekickGenericEnvelope, runOptions)`; Catalox items keep `funcx.functionId` for overrides only.
+
+---
+
+## 1. Consumer mapping (shipped in xynthesis)
+
+**Source:** `xynthesis/src/catalog/sidekickFuncxCatalogMap.ts`  
+**Envelopes:** `xynthesis/src/sidekickFuncxEnvelope.ts`  
+**Flag:** `XYNTHESIS_FUNCX_SIDEKICK=1` (`isSidekickFuncxEnabled()`)
+
+| Phase | Sidekick `actionType` | Catalox catalog | Item id | FuncX `functionId` | Hyphen alias (router) | In FuncX 4.4 registry? |
+|-------|----------------------|-----------------|---------|-------------------|----------------------|-------------------------|
+| PRE | `synthesis` | `pre-actions` | `synthesis` | `pre/synthesize` | `pre-synthesize` | **No** |
+| PRE | `execution-plan` | `pre-actions` | `execution-plan` | `execution/plan` | `execution-plan` | **Yes** |
+| PRE | `plan-web-scope-questions` | `pre-actions` | `plan-web-scope-questions` | `research/plan-questions` | `research-plan-questions` | **Yes** |
+| POST | `audit` | `post-actions` | `audit` | `post/audit` | `post-audit` | **No** |
+| POST | `fix` | `post-actions` | `fix` | `post/fix` | `post-fix` | **No** |
+| POST | `pick-best` | `post-actions` | `pick-best` | `post/pick-best` | `post-pick-best` | **No** |
+| POST | `craft-final` | `post-actions` | `craft-final` | `post/craft-final` | `post-craft-final` | **No** |
+| POST | `execution-evaluate-result` | `post-actions` | `execution-evaluate-result` | `execution/evaluate-result` | `execution-evaluate-result` | **Yes** |
+
+**ai-tasks-only POST pipeline** (not `SidekickActionType` today):
+
+| Capability | FuncX id | Catalox item | Envelope builder | In registry? |
+|------------|----------|--------------|------------------|--------------|
+| Checklist audit | `post/audit-checklist` | `audit-checklist` | `ai-tasks/.../auditChecklistFuncxEnvelope.ts` | **No** |
+| Audit merge | `post/audit-merge` | `audit-merge` | same module | **No** |
+
+Catalox seed writes `funcx: { functionId, contentVersion: "0.0.0-pending-funcx" }` on every mapped sidekick item (`buildXynthesisSeedPayloads.ts`).
+
+---
+
+## 2. Wire contract — `SidekickGenericEnvelope`
+
+**Defined in xynthesis** (not exported from `@x12i/funcx` 4.4.0). FuncX `run()` should accept this object as the **request** body (same as passing `GenericExecutionEnvelope` for execution ids).
+
+```ts
+type SidekickGenericEnvelope = {
+  goal: string;                    // SidekickInput.task
+  input: Record<string, unknown>; // action-specific (§3)
+  context: {
+    templateCores: string[];
+    taskType?: string;
+    metadata?: Record<string, unknown>;
+    result?: unknown;              // optimizer context when needed
+    iterationIndex?: number;
+    identity?: ActivityRunContext;
+  };
+  args?: Record<string, unknown>;  // templateMode, customGuidelines, …
+  attribution?: SidekickFuncxAttribution;
+};
+```
+
+**Builders (shipped):**
+
+- `buildSidekickGenericEnvelope(input, options?)` — synthesis, audit, fix, pick-best, craft-final
+- `buildExecutionStrategyGenericEnvelope(req)` — planner / optimizer / web-scope (merges `strategyArgs` → `args`)
+
+**Attribution:** `buildSidekickFuncxAttribution({ funcxFunctionId, jobId, taskId, agentId })` — align with FuncX `buildAskAttribution(implId, envelope)`.
+
+### 2.1 Template tokens (for Catalox instructions)
+
+FuncX 4.4 renders instructions with `input` = **full envelope**. For parity with xynthesis rendrix disk templates, implement **FR-GEN-1** `envelopeToTemplateVariables` (see generic hosting doc).
+
+| xynthesis rendrix (disk) | FuncX / rendrix on envelope (`input` = envelope) |
+|--------------------------|--------------------------------------------------|
+| `goal` | `input.goal` |
+| `task`, `question` | `input.goal` (aliases in sidekick templates) |
+| `local_raw`, `supporting_raw` | `input.local_raw`, `input.supporting_raw` (strings; builders stringify) |
+| `rendered_downstream_instructions` | `input.renderedInstructions` |
+| `rendered_downstream_prompt` | `input.renderedPrompt` |
+| `ai_output` | `input.aiOutput` |
+| `used_instructions`, `used_prompt` | `input.usedInstructions`, `input.usedPrompt` |
+| `prior_audit_json` | stringify `input.priorAudit` |
+| `candidates_json` | stringify `input.candidates` |
+| `metadata_json` | stringify `context.metadata` |
+| `template_cores_json` | stringify `context.templateCores` |
+| `goal`, `input_json`, `context_json`, `args_json` | execution family (§3.6) |
+
+---
+
+## 3. Per-function specifications (to implement in FuncX)
+
+Register in router + `content-seed/functions/` (new bundle or extend `genericExecutionResearch` / dedicated `xynthesisSidekick.seed.json`). Follow **4.4.0 patterns**: `meta.json`, IO schemas, `executeFuncxFromContent`, `buildAskAttribution`, `responseFormat: json_object` where noted.
+
+### FR-PRE-POST-1 — `pre/synthesize` (P0)
+
+**Canonical content:** `xynthesis/templates/synthesis/system-structured.md`, `user-structured.md` (+ markdown pair).
+
+**`input`:** `localRaw`, `supportingRaw`, `renderedInstructions`, `renderedPrompt`, plus string mirrors `local_raw`, `supporting_raw`.
+
+**Output:** matches `parseAndValidateSynthesizedPromptPayload` / `SynthesisPayload` (`templateCores`, `task`, `synthesized`, `notes`, `unknowns`, `assumptions`).
+
+**`args`:** `templateMode`, `customGuidelines`, `synthesisPromptOverride`, `maxItemsPerSide`, `maxItemContentChars`.
+
+### FR-PRE-POST-2 — `post/audit-checklist` + `post/audit-merge` (P1)
+
+**Checklist** — migrate ai-tasks `templates/post-steps/audit/`:
+
+**`input`:** `candidateOutput`, `originalInput`, `promptContext`, `mustChecks`, `shouldChecks`, `previousFeedback`, `previousCycle` (see `buildAuditChecklistFuncxEnvelope`).
+
+**Output:** markdown `### Checks` / `### Overall feedback` until JSON schema exists.
+
+**`args`:** `customAuditGuidelines`, `passNumber`, `cycle`, `maxCycles`.
+
+**Merge** — `buildAuditMergeFuncxEnvelope`: `input.candidateA`, `input.candidateB`, `context.task`.
+
+### FR-PRE-POST-3 — `post/audit` (P0)
+
+**Content:** `xynthesis/templates/audit/*`. **`input`:** `aiOutput`, `usedInstructions?`, `usedPrompt?`. **Output:** `parseAuditPayload` shape (`verdict`, `findings[]`, …).
+
+### FR-PRE-POST-4 — `post/fix` (P0)
+
+**Note:** sidekick action is **`fix`** (polish), not `post/polish`. **Content:** `xynthesis/templates/fix/*`. **Output:** `parseFixPayload` (`fixes[]`).
+
+### FR-PRE-POST-5 — `post/pick-best`, `post/craft-final` (P0)
+
+Per `parsePickBestPayload` / `parseCraftFinalPayload` and existing disk templates.
+
+### FR-PRE-POST-6 — Execution ids (P0 — wire only)
+
+**Already in FuncX 4.4.0.** Remaining work:
+
+- [ ] xynthesis: stop `buildExecutionStrategyPrompts` + `ask` when `XYNTHESIS_FUNCX_SIDEKICK=1`
+- [ ] Call `run(resolveSidekickFuncxFunctionId(action), buildExecutionStrategyGenericEnvelope(req), runOptions)`
+- [ ] Catalox `contentVersion` ≥ seed version after parity (FR-GEN-9)
+
+No new FuncX function definitions required if `fx/execution-plan/*` matches xynthesis templates.
+
+---
+
+## 4. Catalox catalog shape (consumer — shipped)
+
+```ts
+// XynthesisActionItem (cataloxXynthesisBootstrap.ts)
+funcx?: {
+  functionId: string;      // slash form from sidekickFuncxCatalogMap
+  contentVersion?: string;   // "0.0.0-pending-funcx" until FuncX seed synced
+};
+```
+
+**Resolution order (target):**
+
+1. `XYNTHESIS_FUNCX_SIDEKICK=1` → `run(item.funcx.functionId, envelope, runOptions)` — prompts from FuncX/Catalox only.
+2. `XYNTHESIS_CATALOX_ACTIONS=1` → Catalox templates + rendrix (**today**).
+3. Else → disk templates (dev/tests).
+
+When (1) is on, Catalox `templates` are **fallback overrides** only if FuncX resolver supports content overrides (same as other `fx/*` functions).
+
+---
+
+## 5. FuncX package tracker (pre/post only)
+
+Depends on [funcx-generic-xynthesis-hosting.md](./funcx-generic-xynthesis-hosting.md) **FR-GEN-1, FR-GEN-4, FR-GEN-5** for shared template + `run()` ergonomics.
+
+| FR id | Topic | Status @ 4.4.0 |
+|-------|--------|----------------|
+| **FR-PRE-POST-1** | `pre/synthesize` built-in + seed | **Open** |
+| **FR-PRE-POST-2** | `post/audit-checklist`, `post/audit-merge` | **Open** (envelope **shipped** in ai-tasks) |
+| **FR-PRE-POST-3** | `post/audit` | **Open** |
+| **FR-PRE-POST-4** | `post/fix` | **Open** |
+| **FR-PRE-POST-5** | `post/pick-best`, `post/craft-final` | **Open** |
+| **FR-PRE-POST-6** | Wire execution/* + research/plan-questions from xynthesis | **Open** (built-ins **shipped**) |
+| **FR-PRE-POST-7** | `buildSidekickTemplateContext` or FR-GEN-1 covering sidekick | **Open** |
+| **FR-PRE-POST-8** | Export `SidekickGenericEnvelope` type from `@x12i/funcx/functions` (optional) | **Open** |
+
+---
+
+## 6. Acceptance criteria
+
+- [ ] `XYNTHESIS_FUNCX_SIDEKICK=1` → `runSidekickGatewayCall` / `runExecutionPlan` use `run()`, not `loadSidekickTemplates`.
+- [ ] Catalox items keep `funcx.functionId`; validator fails if missing when FuncX mode required.
+- [ ] ai-tasks `runAuditPostStep` uses `post/audit-checklist` envelope (no `loadAuditTemplates` / `DEFAULT_SYSTEM`).
+- [ ] Golden: FR-GEN-1 normalized prompt hash matches current xynthesis rendrix output.
+- [ ] `InvokeAttemptSummary` / Activix record FuncX `functionId`, not only transport `xynthesis/synthesis` on `ask`.
+
+---
+
+## 7. Non-goals
+
+- ai-skills MAIN gateway.
+- FuncX ownership of template **cores** — cores stay rendrix; synthesis `input` may include pre-rendered downstream text only.
+
+---
+
+## 8. Version note
+
+| Package | Version |
+|---------|---------|
+| `@x12i/funcx` | **4.4.0** — implement FR-PRE-POST-1..5 in **4.5.x** (suggested) |
+| `@exellix/xynthesis` | **4.4.3** — map + envelopes shipped; gateway wiring pending |
+| `@exellix/ai-tasks` | **8.5.2** — checklist envelopes shipped |
+
+Implement **pre/post content** in FuncX *after* reading §1 of [funcx-generic-xynthesis-hosting.md](./funcx-generic-xynthesis-hosting.md) (do not re-invent envelope / attribution / `getRunJsonResult`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/ai-tasks",
-  "version": "8.5.0",
+  "version": "8.5.3",
   "description": "Task orchestration for the Exellix stack: runTask() with local handlers or LLM-backed execution, task-scoped memory/context enrichment, and executor dispatch via @exellix/ai-skills. ERC-compliant.",
   "type": "module",
   "main": "dist/index.js",
@@ -59,14 +59,8 @@
   "engines": {
     "node": ">=20"
   },
-  "overrides": {
-    "@x12i/activix": "$@x12i/activix",
-    "@x12i/ai-profiles": "$@x12i/ai-profiles",
-    "@x12i/catalox": "$@x12i/catalox",
-    "@x12i/logxer": "$@x12i/logxer"
-  },
   "dependencies": {
-    "@exellix/ai-skills": "^6.0.0",
+    "@exellix/ai-skills": "^6.0.2",
     "@exellix/memorix-narrix-adapter": "^2.0.0",
     "@exellix/narrix-adapter-chat": "^2.0.0",
     "@exellix/narrix-adapter-docs": "^2.0.0",
@@ -78,7 +72,7 @@
     "@exellix/narrix-ingest": "^2.0.0",
     "@exellix/narrix-runner": "^2.0.0",
     "@exellix/narrix-web-scoper": "^2.0.0",
-    "@exellix/xynthesis": "^4.4.0",
+    "@exellix/xynthesis": "^4.4.5",
     "@x12i/activix": "^8.5.0",
     "@x12i/ai-profiles": "^2.1.0",
     "@x12i/catalox": "^5.1.3",