@exellix/ai-tasks 8.4.3 → 8.5.2

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

@@ -0,0 +1,294 @@
+# `@x12i/funcx` — generic envelope hosting for xynthesis-domain capabilities
+
+**Filed by:** `@exellix/ai-tasks`  
+**Consumers:** `@exellix/xynthesis` (LLM hops), `@exellix/ai-tasks` (envelope builders + adapters)  
+**Out of scope:** `@exellix/ai-skills` MAIN gateway prompts (skill templates, `instructions` / `prompt` on `RunTaskRequest`)
+
+**Related:**
+
+- [`funcx-scoping-integration-gaps.md`](../funcx-scoping-integration-gaps.md) — scoping `ask()` gaps + §6 execution-strategy wire contracts
+- [`funcx-catalog-hosting-checklist.md`](../funcx-catalog-hosting-checklist.md) — deploy checklist for `run()` resolution
+- [`xynthesis-execution-strategies-option-a.md`](./xynthesis-execution-strategies-option-a.md) — **shipped** xynthesis 4.4 sidekick actions (interim: disk templates + `FuncxInvoker.ask`)
+- Envelope builders (stable): [`genericExecutionFuncxEnvelope.ts`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts)
+- Xynthesis templates today (duplicate host): `xynthesis/templates/execution-plan/`, `execution-evaluate-result/`, `plan-web-scope-questions/`
+
+---
+
+## 0. Target architecture
+
+For every **xynthesis-domain** LLM capability (not ai-skills MAIN):
+
+1. **Wire:** `GenericExecutionEnvelope` — `goal`, `input`, `context`, optional `result`, `args`, `attribution`.
+2. **Prompt host:** FuncX function (built-in or Catalox content) — templates read envelope fields and **`args`** for per-template customization (guidelines, caps, variant keys).
+3. **Orchestration:** `@exellix/xynthesis` owns model resolution, Optimixer / `outputExpectation`, JSON parse, Activix, `InvokeAttemptSummary` — ideally by calling **`run(functionId, envelope, options)`** instead of re-rendering duplicate templates and calling `Client.ask` directly.
+4. **ai-tasks:** Builds envelopes only; merges adapted JSON into `RunTaskRequest` (planner/optimizer/web-scope). No inline system prompts for these paths.
+
+**Today (gap):** FuncX already ships built-ins `execution-plan`, `execution-evaluate-result`, `research-plan-questions` with envelope-shaped I/O, but **xynthesis 4.4 re-hosts prompts** under sidekick templates and uses `executeXynthesisAction` + `FuncxInvoker.ask`. **Post-steps and AI scoping** still use **caller-built** `systemPrompt` / `userPrompt` strings in ai-tasks (partially duplicated vs xynthesis `templates/audit`, `templates/fix`).
+
+---
+
+## 1. Audit — where instructions live
+
+| Capability | Prompt / instructions today | Wire today | Generic envelope? | FuncX `run()`? |
+|------------|----------------------------|------------|-------------------|----------------|
+| **execution-plan** | `xynthesis/templates/execution-plan/*` + `buildExecutionStrategyPrompts` | xynthesis `RunExecutionPlanRequest` | Yes (ai-tasks builds payload) | Built-in exists; **not used** by xynthesis 4.4 |
+| **execution-evaluate-result** | Same pattern | xynthesis request + `result` | Yes | Built-in exists; **not used** |
+| **plan-web-scope-questions** | Same pattern | `goal` / `input` / `context` / `args` | Yes | `research-plan-questions` built-in; **not used** |
+| **synthesis (PRE)** | xynthesis `templates/synthesis/*` | `SidekickInput` + rendered skill text | **Sidekick envelope** (FR-PRE-POST) | **`pre/synthesize`** — **missing** |
+| **post-audit** | **ai-tasks** `loadAuditTemplates` + `DEFAULT_SYSTEM` | Pre-built prompts → `executeXynthesisAction` | **Sidekick envelope** | **`post/audit-checklist`** — **missing** |
+| **post-polish** | **ai-tasks** `loadPolishTemplates` + `DEFAULT_SYSTEM` | Pre-built prompts; Optimixer maps stage → `fix` | **Sidekick envelope** | **`post/fix`** — **missing** |
+| **ai-scoping** | **Inline** `SCOPING_SYSTEM` in `runScopingCall.ts` | Pre-built prompts; no `sidekickAction` | **No** | **Missing** |
+| **audit / fix / pick-best / craft-final** (xynthesis-native) | xynthesis `templates/{audit,fix,...}/*` | `runSidekickGatewayCall` when used | Sidekick envelope | **`post/*`** — **missing** (today: rendrix + `ask`) |
+
+**Duplication risk:** xynthesis 4.4 execution-strategy templates and FuncX `content-seed` / Catalox prompts for the same three capabilities can drift unless one is canonical.
+
+**ai-tasks still correct for:** envelope construction (`buildPlannerGenericPayload`, `buildOptimizerGenericPayload`, `buildResearchPlanQuestionsPayload`) and response adapters (`adaptExecutionPlanResult`, etc.) — keep even when xynthesis calls FuncX internally.
+
+---
+
+## 2. FuncX feature requests (tracker)
+
+| FR id | Topic | Priority |
+|-------|--------|----------|
+| **FR-GEN-1** | Canonical **template context** from `GenericExecutionEnvelope` | P0 |
+| **FR-GEN-2** | **`args` → template customization** contract (document + validate) | P0 |
+| **FR-GEN-3** | **Output JSON schemas** aligned with ai-tasks adapters | P0 |
+| **FR-GEN-4** | **`run()` + `RunOptions`** for model, timeout, `response_format`, attribution | P1 |
+| **FR-GEN-5** | **`runGenericExecution`** helper (envelope → ask → parse → usage) for xynthesis | P1 |
+| **FR-GEN-6** | **Post-step generic** functions (`post/audit`, `post/polish` or `xynthesis/audit`) | P1 |
+| **FR-PRE-POST-*** | **Pre/post sidekick built-ins** + Catalox mapping — see [**funcx-pre-post-sidekick-actions.md**](./funcx-pre-post-sidekick-actions.md) | **P0** |
+| **FR-GEN-7** | **AI scoping** generic function (`scoping/run` or `research/scope-content`) | P2 |
+| **FR-GEN-8** | **`strategyArgs` vs `args`** on wire (or documented merge rule) | P1 |
+| **FR-GEN-9** | **Catalox seed parity** with xynthesis 4.4 templates + CI diff | P1 |
+| **FR-GEN-10** | **Deprecate** legacy `ai-tasks-plan-task` / `ai-tasks-optimizer-evaluate` ids | P2 |
+| **FR-GEN-11** | **Sidekick-shaped** post-steps via envelope (audit checks in `context`) | P2 |
+| **FR-GEN-12** | **Contract tests** package: envelope fixtures → expected adapter output | P1 |
+
+§6 in [`funcx-scoping-integration-gaps.md`](../funcx-scoping-integration-gaps.md) remains the **adapter-level** contract for execution/research ids; this doc adds **hosting + template** requirements.
+
+---
+
+### FR-GEN-1 — Canonical template context from envelope
+
+**Need:** Every generic execution/research built-in must render prompts from a **stable, documented** variable map derived from the envelope — not ad hoc TS string building in each consumer.
+
+**Require FuncX built-ins / Catalox templates to expose at minimum:**
+
+| Token / field | Source |
+|---------------|--------|
+| `goal` | `envelope.goal` (string, trimmed) |
+| `input_json` | `JSON.stringify(envelope.input ?? null)` with documented max length + truncation suffix |
+| `context_json` | `JSON.stringify(envelope.context ?? {})` — same truncation rules |
+| `result_json` | Optimizer / evaluate only — `envelope.result` |
+| `args_json` | `JSON.stringify(envelope.args ?? {})` |
+| `iteration_index` | `envelope.args.iterationIndex` when present (stringified) |
+
+**Ask:** Export `buildGenericExecutionTemplateContext(envelope): Record<string, string>` from `@x12i/funcx/functions` (or document it in `docs/migration-generic-execution.md`) so xynthesis can stop duplicating `executionStrategyPromptTemplate.ts` stringification.
+
+**Acceptance:** xynthesis 4.4 templates and FuncX Catalox seeds use the **same** token names; one integration test compares rendered user prompt hashes for a golden fixture.
+
+---
+
+### FR-GEN-2 — `args` → template-level customization
+
+**Need:** Strategy rows and hosts pass opaque knobs in `args` (minus `functionId`) that **templates** read without new function ids — e.g. `customGuidelines`, `maxQuestions`, `allowSkip`, `templateVariant`, `density`.
+
+**Today (ai-tasks / xynthesis):**
+
+- Planner/optimizer: `strategyArgs` forwarded separately in xynthesis; FuncX types only document `args`.
+- Audit: `customAuditGuidelines` merged in ai-tasks `renderAuditSystem`, not in envelope.
+- Web-scope: `args.maxQuestions`, `args.sourceType`, `args.allowSkip`.
+
+**Ask:**
+
+1. Document **reserved vs extension** keys in `args` per function id (JSON Schema `args` sub-schemas in `fx/*/meta.json`).
+2. Support **nested template overrides** via convention, e.g. `args.promptOverrides.systemSuffix`, `args.customGuidelines`, without breaking generic envelope validation.
+3. Optional: `args._templateProfile: "strict" | "lenient"` to select Catalox template variant.
+
+**Acceptance:** Changing only `args.customGuidelines` in a fixture changes the rendered system prompt in tests; no TypeScript change in consumers.
+
+---
+
+### FR-GEN-3 — Output JSON schemas aligned with ai-tasks adapters
+
+**Need:** Built-in outputs must match what [`adaptExecutionPlanResult`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts), [`adaptEvaluateResultResponse`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts), and [`adaptResearchPlanQuestionsResult`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts) expect.
+
+**Planner (`execution-plan` / `execution/plan`):**  
+`plan?`, `instructions?`, `steps[]`, `assumptions[]`, `missingInputs[]`, optional `prompt`, `variables`, `templateTokens` (top-level or under `metadata`).
+
+**Optimizer (`execution-evaluate-result`):**  
+`satisfied` (boolean), `feedback?`, `suggestedChanges[]`, `issues[]`, optional `variables`, `templateTokens`, `metadata`.
+
+**Research (`research-plan-questions`):**  
+`questions[]` with `question`, optional `reason`, `confidence`; optional `skipped`, `reasonCodes`.
+
+**Ask:** Publish machine-readable schemas next to built-ins; version with semver when fields change. Include **`getRunJsonResult`** normalization examples in docs.
+
+**Gap vs xynthesis 4.4 parsers:** If FuncX adds fields, xynthesis `parseExecutionStrategyPayload` should defer to FuncX schema or share one JSON Schema file.
+
+---
+
+### FR-GEN-4 — `run()` + `RunOptions` for orchestrator controls
+
+**Need:** `@exellix/xynthesis` must pass **resolved model**, timeout, temperature, `response_format: json_object`, and merged **attribution** without re-implementing `ask()` options.
+
+**Ask:**
+
+- Extend `RunOptions` (or documented overload) with: `model`, `timeoutMs`, `temperature`, `topP`, `reasoningEffort`, `responseFormat`, `maxTokens` / completion cap hint.
+- Built-ins call `buildAskAttribution(implFunctionId, envelope)` internally when `attribution` is present.
+- Return shape includes **`usage`** and fields xynthesis maps to `InvokeAttemptSummary` (or document mapping table).
+
+**Acceptance:** xynthesis `invokeExecutionStrategyAction` can replace `executeXynthesisAction` + manual prompts with `run(FUNCX_EXECUTION_PLAN_FUNCTION_ID, payload, options)` while preserving observability parity.
+
+---
+
+### FR-GEN-5 — `runGenericExecution` helper for embedders
+
+**Need:** Thin API for packages that already own parse/Activix but should not fork prompt assembly.
+
+**Proposed export (`@x12i/funcx/functions`):**
+
+```ts
+runGenericExecution(opts: {
+  functionId: string;
+  envelope: GenericExecutionEnvelope;
+  client?: Client;
+  runOptions?: RunOptions;
+}): Promise<{ value: unknown; usage?: Usage; model?: string; raw?: unknown }>;
+```
+
+**Behavior:** Resolve content → render templates from FR-GEN-1 context → `ask` / `askJson` → validate against function output schema → return parsed object.
+
+**Acceptance:** xynthesis deletes duplicate template render path when this ships; tests use `createAskMock` at FuncX boundary only.
+
+---
+
+### FR-GEN-6 — Post-step generic functions (audit, polish)
+
+**Need:** Remove ai-tasks **inline** `DEFAULT_SYSTEM` and duplicate template trees; use envelope + FuncX templates.
+
+**Proposed ids:**
+
+| Capability | Suggested `functionId` | Envelope highlights |
+|------------|------------------------|---------------------|
+| Audit evaluator | `post/audit` or `xynthesis/audit` | `goal`: audit objective; `input`: output under test; `context`: checks, synthesis excerpt, pass metadata; `args`: `customGuidelines`, `passNumber` |
+| Polish | `post/polish` or `xynthesis/fix` | `input`: draft output; `context`: checklist, prior pass notes; `args`: `customGuidelines` |
+
+**Output:** Audit — markdown or structured sections; Polish — JSON `{ polishedOutput, changeNotes }` per current ai-tasks parsers.
+
+**Acceptance:** `runAuditCall` / `runPolishCall` build envelope + `run()`; xynthesis `executeXynthesisAction` only for transport if still needed, or xynthesis wraps FR-GEN-5.
+
+---
+
+### FR-GEN-7 — AI scoping generic function
+
+**Need:** Replace `SCOPING_SYSTEM` constant in [`runScopingCall.ts`](../../src/aiScoping/runScopingCall.ts).
+
+**Proposed id:** `scoping/run` or `research/scope-content`
+
+**Envelope:**
+
+- `goal`: scoping directive (from caller `instructions`)
+- `input`: `{ sourceContent: string }` or raw string policy documented
+- `args`: `outputExpectation` hints, `maxOutputLength`
+
+**Output:** Plain text scoped result (no markdown / fences) — document in schema.
+
+**Acceptance:** No inline system string in ai-tasks; FuncX template owns behavior.
+
+---
+
+### FR-GEN-8 — `strategyArgs` vs `args` on wire
+
+**Need:** ai-tasks execution strategies pass catalog row `args` (minus `functionId`) while xynthesis 4.4 also accepts `strategyArgs` on the request object.
+
+**Options (pick one in FuncX):**
+
+1. **Merge rule:** At `run()` entry, `effectiveArgs = { ...envelope.args, ...envelope.strategyArgs }` if `strategyArgs` is added to `GenericExecutionEnvelope`.
+2. **Document:** Consumers must fold `strategyArgs` into `args` before `run()`; export `mergeStrategyArgs(envelope)` helper.
+
+**Ask:** Update `GenericExecutionEnvelope` TypeScript type and `genericExecutionEnvelopeJsonSchema` if `strategyArgs` becomes first-class.
+
+---
+
+### FR-GEN-9 — Catalox seed parity with xynthesis 4.4
+
+**Need:** Single canonical prompt source.
+
+**Ask:**
+
+1. Diff `xynthesis/templates/execution-*` and `plan-web-scope-questions` against `content-seed/functions/genericExecutionResearch.seed.json` (or per-function seeds).
+2. CI job fails on drift unless bumping `contentVersion`.
+3. Document sync procedure: xynthesis exports → FuncX seed import (or FuncX seed → xynthesis pull).
+
+**Acceptance:** Product can disable xynthesis disk templates when Catalox actions enabled (`isCataloxActionsEnabled`) without behavior change.
+
+---
+
+### FR-GEN-10 — Deprecate legacy ai-tasks function ids
+
+**Need:** FuncX registry still lists `ai-tasks-plan-task`, `ai-tasks-optimizer-evaluate` alongside `execution-plan`, `execution-evaluate-result`.
+
+**Ask:** Mark legacy ids deprecated in meta; route aliases to generic built-ins; remove from seed catalog after one major.
+
+---
+
+### FR-GEN-11 — Sidekick-shaped post-steps via envelope (optional)
+
+**Need:** Audit today uses rich `SidekickInput` (checks array, material blocks). Migrating to envelope should not lose structure.
+
+**Ask:** Define `context.audit` sub-schema (checks, outputText, synthesisSummary, …) in FR-GEN-6 meta so templates stay declarative.
+
+---
+
+### FR-GEN-12 — Contract tests for adapters
+
+**Need:** Prevent drift between FuncX built-in output and ai-tasks adapters.
+
+**Ask:** Ship `test/fixtures/generic-execution/*.json` in `@x12i/funcx` run in CI; ai-tasks imports fixtures or duplicates with cross-package version pin.
+
+---
+
+## 3. Recommended convergence path
+
+```mermaid
+flowchart LR
+  subgraph ai_tasks
+    A[buildPlannerGenericPayload]
+  end
+  subgraph xynthesis
+    B[runExecutionPlan]
+    C{FR-GEN-5 shipped?}
+  end
+  subgraph funcx
+    D[run execution-plan]
+    E[Catalox templates + args]
+  end
+  A --> B
+  B --> C
+  C -->|yes| D
+  C -->|interim 4.4| F[disk templates + ask]
+  D --> E
+  F --> E
+```
+
+1. **FuncX:** Implement FR-GEN-1–3, FR-GEN-9 (canonical prompts + schemas).
+2. **FuncX:** FR-GEN-4–5 so xynthesis can call `run()` without duplicate `executionStrategyPromptTemplate.ts`.
+3. **xynthesis:** Follow-up FR (separate doc) — switch `invokeExecutionStrategyAction` to FuncX `run()`; keep parsers/adapters.
+4. **ai-tasks:** FR-GEN-6–7 for audit/polish/scoping; stop shipping `DEFAULT_SYSTEM` strings.
+5. **Docs:** Update [`funcx-catalog-hosting-checklist.md`](../funcx-catalog-hosting-checklist.md) — built-ins are canonical; Catalox overrides via `args`.
+
+---
+
+## 4. Non-goals
+
+- Changing ai-skills MAIN `instructions` / `prompt` contract.
+- Moving synthesis PRE-step template **cores** (`{{core:analysis}}`) into FuncX — cores stay rendrix/ai-skills; FuncX hosts the **synthesis action** via `pre/synthesize` (see [funcx-pre-post-sidekick-actions.md](./funcx-pre-post-sidekick-actions.md)).
+- Forcing ai-tasks to call `@x12i/funcx` directly again for execution strategies (xynthesis remains the facade after FR-GEN-5).
+
+---
+
+## 5. Version note
+
+- **@x12i/funcx** ≥ **4.2.0** (ai-tasks dep): `FUNCX_*_FUNCTION_ID`, `genericExecutionEnvelopeJsonSchema`, `buildAskAttribution`, `getRunJsonResult`.
+- Built-in ids in registry: `execution-plan`, `execution-evaluate-result`, `research-plan-questions` (slash aliases normalize per README).

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

@@ -0,0 +1,301 @@
+# `@x12i/funcx` — built-in functions for xynthesis **pre-actions** and **post-actions**
+
+**Filed by:** `@exellix/ai-tasks` + `@exellix/xynthesis`  
+**Blocks:** Catalox-only sidekick path (`runXynthesisAiAction`), ai-tasks audit/polish migration off inline templates  
+**Related:** [funcx-generic-xynthesis-hosting.md](./funcx-generic-xynthesis-hosting.md), [funcx-catalog-hosting-checklist.md](../funcx-catalog-hosting-checklist.md)
+
+---
+
+## 0. Problem
+
+Today xynthesis **pre-actions** (synthesis) and **post-actions** (audit, fix, pick-best, craft-final) load prompts from:
+
+1. On-disk `xynthesis/templates/{actionType}/`, or  
+2. Catalox catalogs `pre-actions` / `post-actions` (same template bodies, seeded from disk).
+
+The LLM hop uses **`FuncxInvoker.ask(systemPrompt, userPrompt)`** — a **transport-only** use of FuncX. Prompt text is assembled in xynthesis (`sidekickPromptTemplate.ts` + rendrix), **not** resolved from a FuncX **function id** via `run(functionId, envelope)`.
+
+**ai-tasks** often bypasses even that path: it loads **its own** audit/polish templates and calls `executeXynthesisAction` with pre-built prompts.
+
+**Target:** Each sidekick action has a **first-class FuncX function** (like `execution/plan`). xynthesis calls `run(functionId, envelope, runOptions)`; Catalox `pre-actions` / `post-actions` items **reference** the same `functionId` for content overrides, not duplicate template hosting.
+
+---
+
+## 1. Canonical mapping (FuncX ↔ Catalox ↔ sidekick)
+
+| Phase | Sidekick `actionType` | Catalox catalog | Catalox item id | Proposed FuncX `functionId` | Hyphen alias |
+|-------|----------------------|-----------------|-----------------|----------------------------|--------------|
+| PRE | `synthesis` | `pre-actions` | `synthesis` | `pre/synthesize` | `pre-synthesize` |
+| PRE | `execution-plan` | `pre-actions` | `execution-plan` | `execution/plan` | `execution-plan` |
+| PRE | `plan-web-scope-questions` | `pre-actions` | `plan-web-scope-questions` | `research/plan-questions` | `research-plan-questions` |
+| POST | `audit` | `post-actions` | `audit` | `post/audit` | `post-audit` |
+| POST | `fix` | `post-actions` | `fix` | `post/fix` | `post-fix` |
+| POST | `pick-best` | `post-actions` | `pick-best` | `post/pick-best` | `post-pick-best` |
+| POST | `craft-final` | `post-actions` | `craft-final` | `post/craft-final` | `post-craft-final` |
+| POST | `execution-evaluate-result` | `post-actions` | `execution-evaluate-result` | `execution/evaluate-result` | `execution-evaluate-result` |
+
+**ai-tasks pipeline audit (weighted checks, markdown output)** — separate from sidekick JSON audit until unified:
+
+| Capability | Proposed FuncX id | Catalox (optional) |
+|------------|-------------------|-------------------|
+| Checklist audit evaluator | `post/audit-checklist` | `post-actions` item `audit-checklist` |
+| Audit-cycle synthesis merge | `post/audit-merge` | `post-actions` item `audit-merge` or reuse `pre/synthesize` with `args.profile: "audit-merge"` |
+
+Constants and envelope builders live in xynthesis: `src/catalog/sidekickFuncxCatalogMap.ts`, `src/sidekickFuncxEnvelope.ts`.
+
+---
+
+## 2. Wire contract — sidekick generic envelope
+
+Extend (or sibling-type) **`GenericExecutionEnvelope`** for sidekick actions:
+
+```ts
+type SidekickGenericEnvelope = {
+  /** Directive: question / objective / instruction (maps to SidekickInput.task). */
+  goal: string;
+  /** Action-specific payload (see §3 per function). */
+  input: Record<string, unknown>;
+  /** Shared sidekick context. */
+  context: {
+    templateCores: string[];
+    taskType?: string;
+    metadata?: Record<string, unknown>;
+    /** Optimizer-only / evaluate-only fields when applicable. */
+    result?: unknown;
+    iterationIndex?: number;
+  };
+  /** Template customization — NOT merged into LLM attribution tags by default. */
+  args?: {
+    templateMode?: "structured" | "markdown";
+    customGuidelines?: string;
+    synthesisPromptOverride?: string;
+    /** Checklist audit: passNumber, cycle, maxCycles, … */
+    [key: string]: unknown;
+  };
+  attribution?: GenericFuncxAttribution;
+};
+```
+
+**Template context tokens** (FR-GEN-1 superset) — FuncX must render from envelope, matching xynthesis rendrix vars today:
+
+| Token | Envelope source |
+|-------|-----------------|
+| `task`, `question` | `goal` (both aliases for synthesis compat) |
+| `local_raw` | `input.localRaw` stringified |
+| `supporting_raw` | `input.supportingRaw` stringified |
+| `rendered_downstream_instructions` | `input.renderedInstructions` |
+| `rendered_downstream_prompt` | `input.renderedPrompt` |
+| `ai_output` | `input.aiOutput` |
+| `used_instructions` | `input.usedInstructions` |
+| `used_prompt` | `input.usedPrompt` |
+| `prior_audit_json` | `JSON.stringify(input.priorAudit)` |
+| `candidates_json` | `JSON.stringify(input.candidates)` |
+| `prior_context` | `input.priorContext` |
+| `metadata_json` | `JSON.stringify(context.metadata ?? {})` |
+| `template_cores_json` | `JSON.stringify(context.templateCores)` |
+| `goal`, `input_json`, `context_json`, `args_json` | FR-GEN-1 generic tokens (execution-strategy family) |
+
+**Ask (FuncX):** export `buildSidekickTemplateContext(envelope): Record<string, string>` alongside `buildGenericExecutionTemplateContext`.
+
+---
+
+## 3. Per-function specifications
+
+### FR-PRE-1 — `pre/synthesize` (PRE synthesis)
+
+**Canonical content:** `xynthesis/templates/synthesis/system-structured.md` + `user-structured.md` (and markdown variants).
+
+**Envelope `input`:**
+
+| Field | Type | Required |
+|-------|------|----------|
+| `localRaw` | any | no |
+| `supportingRaw` | any | no |
+| `renderedInstructions` | string | no |
+| `renderedPrompt` | string | no |
+
+**Output JSON** (matches `parseAndValidateSynthesizedPromptPayload` / `SynthesisPayload`):
+
+- `templateCores`, `task`, `synthesized` (`SynthesizedContext`), optional `notes`, `unknowns`, `assumptions`
+
+**`args`:** `templateMode`, `customGuidelines`, `synthesisPromptOverride`, `maxItemsPerSide`, `maxItemContentChars`
+
+**Response format:** `json_object`
+
+---
+
+### FR-POST-1 — `post/audit` (sidekick JSON audit)
+
+**Canonical content:** `xynthesis/templates/audit/*`
+
+**Envelope `input`:**
+
+| Field | Type | Required |
+|-------|------|----------|
+| `aiOutput` | string | yes |
+| `usedInstructions` | string | no |
+| `usedPrompt` | string | no |
+
+**Output JSON** (matches `parseAuditPayload`):
+
+- `verdict`: `"pass" | "fail" | "mixed"`
+- `findings[]`: `{ id, label, content, severity? }`
+- plus sidekick base fields (`notes`, `unknowns`, `assumptions`, …)
+
+---
+
+### FR-POST-2 — `post/audit-checklist` (ai-tasks weighted audit)
+
+**Canonical content:** migrate from ai-tasks `templates/post-steps/audit/` (Handlebars → FuncX templates with same variables).
+
+**Envelope `input`:**
+
+| Field | Type | Required |
+|-------|------|----------|
+| `candidateOutput` | string | yes |
+| `originalInput` | string | yes |
+| `promptContext` | string | no |
+| `mustChecks` | `{ check, weight }[]` | yes |
+| `shouldChecks` | `{ check, weight }[]` | yes |
+| `previousFeedback` | string | no |
+
+**Output:** structured markdown (`### Checks`, `### Overall feedback`) — parsed by ai-tasks `parseAuditOutputFromMarkdown` until FuncX ships JSON schema variant.
+
+**`args`:** `customAuditGuidelines`, `passNumber`, `cycle`, `maxCycles`
+
+---
+
+### FR-POST-3 — `post/fix` (polish / fix)
+
+**Canonical content:** `xynthesis/templates/fix/*`
+
+**Envelope `input`:** `aiOutput`, `usedInstructions?`, `usedPrompt?`, `priorAudit?` (AuditPayload)
+
+**Output JSON:** `fixes[]` with `{ id, label, corrected, rationale? }` per `parseFixPayload`
+
+---
+
+### FR-POST-4 — `post/pick-best`
+
+**Envelope `input`:** `candidates[]` (`{ id, content }`), `usedInstructions?`
+
+**Output JSON:** `selected`, `rankings[]` per `parsePickBestPayload`
+
+---
+
+### FR-POST-5 — `post/craft-final`
+
+**Envelope `input`:** `aiOutput`, `usedInstructions?`, `usedPrompt?`, `priorContext?`
+
+**Output JSON:** per `parseCraftFinalPayload` (`finalOutput`, `rationale?`, …)
+
+---
+
+### FR-PRE-POST-6 — Execution-strategy ids (already exist — wire only)
+
+**No new FuncX content required** if seeds match xynthesis templates (FR-GEN-9). xynthesis must **stop** re-rendering `executionStrategyPromptTemplate.ts` and call:
+
+- `run("execution/plan", envelope)` 
+- `run("execution/evaluate-result", envelope)` 
+- `run("research/plan-questions", envelope)`
+
+Catalox `pre-actions` / `post-actions` items for these actions gain `funcx.functionId` pointing at built-ins; templates in Catalox become **overrides** only.
+
+---
+
+## 4. Catalox catalog shape (consumer-side, after FuncX ships)
+
+Each `XynthesisActionItem` in `pre-actions` / `post-actions` should include:
+
+```json
+{
+  "actionType": "audit",
+  "funcx": {
+    "functionId": "post/audit",
+    "contentVersion": "1.0.0"
+  },
+  "templates": { "structured": { "system": "...", "user": "..." } },
+  "actionOutputDefaults": { ... },
+  "outputIntent": { ... }
+}
+```
+
+**Resolution order (xynthesis):**
+
+1. If `XYNTHESIS_FUNCX_SIDEKICK=1` (new flag): `run(item.funcx.functionId, buildSidekickGenericEnvelope(input), runOptions)`.
+2. Else if `XYNTHESIS_CATALOX_ACTIONS=1`: Catalox templates + rendrix (today).
+3. Else: disk templates (dev/tests).
+
+When (1) is active, Catalox `templates` are **ignored for prompt text** unless FuncX catalog points at Catalox-hosted function content (FuncX content-seed parity).
+
+---
+
+## 5. FuncX package asks (summary tracker)
+
+| FR id | Topic | Priority |
+|-------|--------|----------|
+| **FR-PRE-POST-1** | Register **`pre/synthesize`**, **`post/audit`**, **`post/fix`**, **`post/pick-best`**, **`post/craft-final`** built-ins | **P0** |
+| **FR-PRE-POST-2** | Register **`post/audit-checklist`**, **`post/audit-merge`** for ai-tasks POST pipeline | **P1** |
+| **FR-PRE-POST-3** | **`buildSidekickTemplateContext(envelope)`** export | **P0** |
+| **FR-PRE-POST-4** | Output JSON schemas = xynthesis parser contracts (§3) | **P0** |
+| **FR-PRE-POST-5** | `runSidekickGeneric(opts)` or extend FR-GEN-5 `runGenericExecution` for sidekick envelope | **P1** |
+| **FR-PRE-POST-6** | Content-seed from `xynthesis/templates/{synthesis,audit,fix,...}` + CI drift vs Catalox | **P1** |
+| **FR-PRE-POST-7** | Wire existing **`execution/*`** + **`research/plan-questions`** as canonical for pre/post catalog items (deprecate xynthesis duplicate render path) | **P0** |
+
+Depends on [funcx-generic-xynthesis-hosting.md](./funcx-generic-xynthesis-hosting.md) **FR-GEN-1–5** for `RunOptions`, usage return shape, and generic template context.
+
+---
+
+## 6. Acceptance criteria (end-to-end)
+
+- [ ] With `XYNTHESIS_FUNCX_SIDEKICK=1`, `runSidekickGatewayCall` never calls `loadSidekickTemplates` for registered actions; prompts come from FuncX `run()`.
+- [ ] Catalox `pre-actions` / `post-actions` items include `funcx.functionId`; validation fails if missing when FuncX mode enabled.
+- [ ] ai-tasks `runAuditPostStep` builds `post/audit-checklist` envelope — no `loadAuditTemplates` / `DEFAULT_SYSTEM`.
+- [ ] ai-tasks PRE structured synthesis uses `pre/synthesize` via xynthesis (not local template load + `executeXynthesisAction`).
+- [ ] Golden fixture: same envelope → FuncX rendered prompts hash-equal to current xynthesis rendrix output (FR-GEN-9 parity).
+- [ ] `sidekickAction` on Activix / `InvokeAttemptSummary` records FuncX `functionId`, not only transport `ask`.
+
+---
+
+## 7. Convergence (mermaid)
+
+```mermaid
+flowchart TB
+  subgraph ai_tasks
+    AT[buildSidekick envelope data]
+  end
+  subgraph xynthesis
+    XY[runSidekickGatewayCall / runXynthesisAiAction]
+    MAP[sidekickFuncxCatalogMap]
+    ENV[buildSidekickGenericEnvelope]
+  end
+  subgraph funcx
+    RUN["run(functionId, envelope)"]
+    TPL[Catalox / content-seed templates]
+  end
+  subgraph catalox
+    PRE[pre-actions catalog]
+    POST[post-actions catalog]
+  end
+  AT --> XY
+  XY --> MAP
+  MAP --> ENV
+  ENV --> RUN
+  RUN --> TPL
+  PRE -.->|funcx.functionId + optional override| MAP
+  POST -.->|funcx.functionId + optional override| MAP
+```
+
+---
+
+## 8. Non-goals
+
+- ai-skills MAIN gateway (`instructions` / `prompt` on `RunTaskRequest`).
+- Moving template **cores** (`{{core:analysis}}`) into FuncX — still rendrix/ai-skills concern; synthesis **input** may include pre-rendered downstream blocks only.
+
+---
+
+## 9. Version note
+
+- **@x12i/funcx** ≥ **4.4.0** (xynthesis dep): `run`, `getRunJsonResult`, `GenericExecutionEnvelope`, `Client.ask`.
+- New built-ins require FuncX release + content-seed; xynthesis gates behind **`XYNTHESIS_FUNCX_SIDEKICK=1`** until parity tests pass.