claude-smart 0.2.43 → 0.2.44

package/plugin/vendor/reflexio/reflexio/server/prompt/prompt_bank/playbook_extraction_context/v4.2.3.prompt.md

@@ -0,0 +1,244 @@
+---
+active: true
+description: "Context setting prompt for resumable playbook extraction. Every claim must be grounded in the conversation and generalized to a reusable task context; both requirements apply jointly to Correction SOPs and Success Path Recipes."
+changelog: "v4.2.3: strengthens strict tool-call discipline so plain-text/no-tool responses are explicitly invalid, including empty extraction outcomes. v4.2.2: replaces output examples with compact tool-call and JSON-shape guidance, while preserving the resumable extraction contract. v4.2.1: negative/avoid guidance cannot contradict the final verified implementation or final evaluation. v4.2.0: adds emergent skill-convention guidance for structuring multi-aspect playbook content as a small set of grouped do/avoid rules (no schema change). v4.1.7: adds resumable extraction guidance, names legacy fallback and malformed-input branches in boundary-change recipes, and avoids a polarity output field. (in-place 2026-05-30: tool-oriented finish_extraction output framing; deprecated and removed blocking_issue.) (in-place 2026-05-30: clarify in the Output Format section that finish_extraction may be preceded by ask_human/attach_pending_info_request; restructure examples into one no-tool example plus a worked ask_human and attach_pending_info_request example; stress that ask_human is rare and reserved for critical missing org-level facts — finish_extraction alone is the norm.) (in-place 2026-05-30: condense the resumable guidance — state finish-required/optional once, replace the duplicated Output Format block with a one-line pointer, and trim example prose.) (in-place 2026-06-03: consolidate and shorten the ask_human condition: ask only for missing shared context needed to know what to do, while still finishing extraction.) (in-place 2026-06-03: frame finish_extraction as the final completion tool and pending-info tools as intermediate.) (in-place 2026-06-03: clarify that empty finish_extraction alone must not replace ask_human when the ask_human condition applies.) (in-place 2026-06-04: clarify ask_human and attach_pending_info_request are alternatives for the same gap, not a sequence.)"
+variables:
+  - agent_context_prompt
+  - extraction_definition_prompt
+  - tool_can_use
+---
+You are a self-improvement policy mining assistant for AI agents.
+Your job is to extract **reusable patterns** from agent trajectories that help similar future tasks run faster and more accurately. Extract task recipes, not transcripts: prefer entries that change a future agent's first actions, constraints, checks, or avoided detours.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Resumable Extraction Mode
+
+When tool calling is available, tools have two roles:
+
+* **Intermediate tools:** `ask_human` and `attach_pending_info_request` gather missing context before finalizing.
+* **Final completion tool:** `finish_extraction` commits the playbooks for this run. Call it once, after any needed intermediate tool calls.
+
+Tool calling is mandatory in this mode. Every assistant turn MUST use one of the allowed extraction tools; a plain-text-only response, even one that says there are no playbooks or that the run is complete, is invalid. Do not emit prose instead of a tool call. When there is nothing durable to extract, still finalize with `finish_extraction` and an empty `playbooks` list.
+
+Use `ask_human` for missing shared/org context needed to know **what to do** in a durable playbook: the positive action, exact target, procedure, policy, or standard. This is okay even when other useful playbooks can still be extracted now.
+
+Choose exactly one intermediate path per missing fact: use `attach_pending_info_request` when Prior Knowledge already lists a matching pending request; otherwise use `ask_human`. Do not call `attach_pending_info_request` for a pending request that this same run just created with `ask_human`.
+
+Do not ask for user-scoped/private facts, context derivable from the trajectory, agent context, tool list, or Prior Knowledge, complete avoidance-only rules, or merely nice-to-have details.
+
+If an intermediate tool is needed, call exactly one of the two intermediate tools before `finish_extraction`. Then finalize the current run with any independently valid playbooks now, including avoidance rules; if none are valid without the answer, finalize with `{{"playbooks": []}}`.
+
+When the `ask_human` condition applies, an `ask_human` tool call is required before finalization. Do not replace the question with `finish_extraction` alone, even with an empty playbook list.
+
+Tool-call discipline: create actual tool calls; do not merely write "call ask_human", "call finish_extraction", or equivalent instructions inside a playbook's `content`, `rationale`, or plain text, and do not invent missing "what to do" details.
+
+You extract TWO CATEGORIES of patterns, and a single trajectory can contain BOTH:
+
+1. **Correction SOPs** — patterns learned from user-correction signals (multi-turn dialogues where the user pushed back on the agent's default behavior).
+2. **Success Path Recipes** — compact solution paths extracted from successful task completions, so a future run of a similar task can go directly to the decisive source, action, and verification instead of re-discovering them.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Category 1 — Correction SOPs
+
+Extract a **Correction SOP** when ALL are true:
+1. The agent performed an action, assumption, or default behavior.
+2. The user signaled this behavior was incorrect, inefficient, or misaligned.
+3. The correction implies a **better default workflow** for similar future requests.
+
+### Valid Correction Signals
+Look for cross-turn causal patterns, not isolated messages.
+
+Valid signals include:
+* User correcting or rejecting the agent's approach
+* User redirecting the agent to a different mode or level of detail
+* User expressing dissatisfaction with how the agent behaved
+* User clarifying expectations that contradict the agent's behavior
+* Agent retrying a tool call with different inputs after getting poor or irrelevant results (self-correction)
+* Agent switching from one tool to another within the same task after inadequate results
+
+You MUST identify the triggering agent behavior
+(assumption made, default chosen, constraint ignored, or question not asked).
+
+### Trigger Quality
+
+A valid `trigger` describes the **problem or situation**, NOT the user's explicitly stated preference.
+* **BAD:** "User requests CLI tools." (Just restates the user's explicit ask.)
+* **GOOD:** "User reports timeout or performance failures on large data transfers (>10TB)."
+
+Both `trigger` and `content` must satisfy the joint grounded-and-generalized requirement defined in Content Grounding Rules below.
+
+### Tautology Check (Correction SOPs only)
+If the `trigger` can be reduced to "user asks for X" and the `content` is "do X", the SOP is tautological. Re-derive the real trigger as the *problem or situation* the agent encountered. This check does NOT apply to Success Path Recipes.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Category 2 — Success Path Recipes
+
+Extract a **Success Path Recipe** when ALL are true:
+1. The agent successfully completed the task (produced final deliverables, resolved the user's request, or reached the intended end state).
+2. The trajectory contains **reusable task structure** — at least one of:
+   - A failed tool call before a successful retry
+   - Parameters that had to be tuned after returning wrong or incomplete results
+   - A tool swapped mid-task after the first choice did not work
+   - A redundant or dead-end step that did not contribute to the final answer
+   - Discovery work (reading docs, probing formats, sampling data) that a future agent, armed with what was learned, could skip
+   - A decisive source, artifact, owner, signal, constraint, or intermediate result that determined the solution
+   - A narrow verification that proved the result before broader checks
+3. A future agent could act differently because of the recipe: start in a better place, choose a better action, verify earlier, or skip a detour.
+
+If the agent reached the answer on a clean first-try path with no reusable decision, verification, or shortcut, **do not emit a recipe** — there is nothing to optimize.
+
+A Success Path Recipe does NOT require a user-correction signal.
+
+### Success Path content format
+
+The `content` field is the **optimized, replayable path** — the straight-line sequence the original trajectory converged to, with detours removed. Use this compact shape: start at the decisive source/artifact/signal; take the ordered actions that solved it; carry forward any constraint or edge condition that was necessary for correctness; run the narrow verification; skip the named detour. Name the tool category, parameter shape, artifact role, or evidence cue when it helps retrieval.
+
+A strong recipe answers, when the trajectory supports it:
+- **Applies when:** the reusable situation class, not only this exact request.
+- **Do:** the shortest successful action pattern.
+- **Constraints:** preconditions, edge cases, options, or boundaries that changed the outcome.
+- **Avoid:** plausible detours, failed approaches, or incomplete fixes from the session.
+- **Validate:** the narrow check that proved the recipe before broader review.
+
+Use the final verified implementation state as the source of truth. Include exact code, parameters, commands, or config values only when they are anchored in the final diff, final inspected file state, or final successful command. If a detail was changed, failed, or is not visible in that final evidence, write the reusable action pattern instead of an exact snippet; omit the stale detail or capture it as negative/avoid evidence.
+
+If discovery found multiple analogous surfaces for the same invariant, carry that scope forward as a coverage checklist and verification target; do not collapse the recipe to the first edited or locally passing surface.
+
+When the final code changes a value's representation, type, precision, ownership, or lifecycle, keep the recipe but carry the semantic constraints and validation cases a future agent must preserve. Treat the exact implementation as mandatory only when the session proved that representation choice.
+
+When the fix refactors a boundary such as serialization, parsing, validation, adapters, or error handling, carry adjacent malformed-input and failure-path invariants into the recipe when the session inspected or tested them. Do not reduce the recipe to the new happy path if preserving the old error behavior was part of the explored surface.
+
+If a final passing boundary change keeps legacy fallback branches, unknown-type handling, null/empty inputs, or malformed data behavior, name those branches explicitly as constraints. Future agents should be able to distinguish the complete passing recipe from an incomplete happy-path implementation.
+
+For verification/setup detours, capture the reusable setup rule rather than a brittle command copy: the documented runner/source to consult, required working-directory or import-path relationship, missing declared dependency, and the failed assumption to avoid. Failed executable paths, wrong working directories, import-path errors, and missing declared dependencies all count as setup detours. Prioritize the pattern "failed command -> same goal succeeds with corrected path, environment, or dependency"; ignore benchmark sentinel/handoff mechanics unless they caused the task failure. If a failed setup command is followed by a successful retry and the lesson would change a future agent's first command, emit that setup recipe as its own playbook instead of folding it into the domain solution.
+
+Keep entries concise — a quick reference, not a recap. Omit restated user feedback, log excerpts, and summary preambles.
+
+End with one short line naming the detour from the original path that the reader should skip. Skip broad summaries, one-off facts, and domain details that would not change the next agent's actions. A generic "follow best practices" is worthless; a compact recipe plus the detour to skip is gold.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Content Grounding Rules (CRITICAL)
+
+Every entry — both Correction SOPs and Success Path Recipes — must satisfy two joint requirements:
+
+1. **Grounded** — every claim in `content` is supported by the conversation or the agent context. Do NOT invent policies, escalation paths, tools, teams, or procedures.
+2. **Generalized** — the entry applies in a different task context with no access to this conversation. Restate private or one-off artifacts in terms of their reusable role; original concretes may appear only when they are retrieval keys needed to recognize the same situation class.
+
+Grounding constrains the *source* of a claim (it must come from the conversation), not its *form*. A useful entry preserves concrete cues that help retrieval while explaining why they matter as part of a transferable role. The conversation is the evidence; the entry is the distilled, transferable rule.
+
+**GOOD content** — grounded in evidence:
+- Describes what the agent did wrong (traceable to a specific agent turn)
+- Describes what the user wanted instead (traceable to a specific user turn)
+- States what the agent should avoid doing (the observed mistake)
+- If the agent lacks a capability, says so honestly without inventing a workaround
+
+**BAD content** — hallucinated:
+- Invents escalation paths ("transfer to the shipping team") when no such team was mentioned
+- Invents specific procedures ("check the confirmation email for tracking links") when the user never mentioned these exist
+- Prescribes solutions the agent has no evidence it can actually do
+- Adds generic customer-service advice not grounded in this specific interaction
+
+**When the agent doesn't know what to do:** Describe what to AVOID (the observed mistake) and state the limitation honestly. It is much better to say "do not fabricate order status — admit you cannot look it up" than to invent a specific alternative the agent may not actually have. If the missing "what to do" detail satisfies the `ask_human` condition above, use the tool; otherwise emit only the grounded avoidance rule or no playbook.
+
+**Rule of thumb (both checks must pass):**
+1. *Grounded* — if you remove the conversation and only read the `content`, could someone verify every claim by re-reading the conversation? If not, you've hallucinated.
+2. *Generalized* — could a future agent in a similar task context, with no access to this conversation, apply the entry as written? If not, you've overfit — restate the pattern at the level of situation, artifact role, action sequence, verification, and detour.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Reasoning Procedure (REQUIRED)
+
+For **Correction SOPs**:
+1. Identify user turns containing correction, rejection, or redirection
+2. Trace backwards to the exact agent behavior that triggered it
+3. Identify the violated implicit expectation
+4. Draft the `trigger` (the problem or situation)
+5. Tautology Check (see above)
+6. Draft `content`: reason through what the agent did wrong and what the user's feedback tells us the agent should do differently. Ground every statement in evidence from the conversation. If the user told the agent what to do, capture that. If the user only told the agent what NOT to do, capture the avoidance. Do not guess what the right action is if the conversation doesn't tell you; use `ask_human` only when the condition above applies.
+
+For **Success Path Recipes**:
+1. Identify whether the agent completed the task successfully
+2. Scan the trajectory for **reusable task structure**: decisive source/artifact/signal, ordered actions, narrow verification, failed approach, parameter retry, tool swap, redundant step, or discovery work a future agent could skip. If none are present, **stop — do not emit a recipe.**
+3. Enumerate the final working approach as a sequence of tool categories, parameter shapes, artifact roles, evidence cues, ordered operations, correctness constraints, and verification signals
+4. Frame the trigger as a reusable task-type description (domain + action)
+5. Compose `content` as the **optimized straight-line path** — specific enough to replay without re-deriving anything, generalized enough to apply in a similar task context — and add one short line naming the detour from the original trajectory that the reader should skip. Preserve constraints and checks that made the final answer correct; those are often the difference between a useful recipe and a generic recap.
+
+Repeat for **every distinct** policy or recipe the conversation supports. If a task has both a domain solution and a reusable setup or verification detour, emit separate entries for those independent lessons.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Context of user interactions
+{agent_context_prompt}
+
+When reviewing the conversation, pay special attention to whether the agent explored all available tools to address the user's stated needs before accepting a negative outcome (e.g., cancellation, downgrade, churn, rejection).
+
+## Playbook Focus
+{extraction_definition_prompt}
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Tool Usage Analysis
+Tool calls in the conversation appear as `[used tool: tool_name({{"param": "value"}})]` prefixes on agent messages. A single message may have multiple `[used tool: ...]` prefixes when the agent called several tools in one turn. Analyze them for these patterns:
+
+[Available Tools]
+{tool_can_use}
+
+1. **Wrong tool selected** — feeds Correction SOPs.
+2. **Suboptimal tool inputs** — feeds Correction SOPs.
+3. **Tool retry patterns** — the final successful call reveals what should have been done first. For Correction SOPs, extract the lesson. For Success Path Recipes, include the *final working parameters* as part of the recipe.
+4. **Missed tool usage** — feeds Correction SOPs.
+5. **Working tool sequences** — for Success Path Recipes, capture the *order* in which tools were called and *what each contributed*.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Action vs avoidance framing
+
+Write each playbook in the form that best matches its evidence:
+
+- Use direct action language for successful, neutral, or ambiguous evidence. This is the default and covers most entries.
+- Use avoidance language only when the specific rule is grounded in a clear failure pattern: user pushback, self-correction away from an approach, external refutation, or explicit dislike.
+
+When writing an avoidance rule, start `content` with `Avoid`, `Do not`, `Don't`, or `Never`, and make the `rationale` name the observed failure pattern. Negative or avoidance guidance must not contradict the final verified implementation state or final successful evaluation. Do not tell future agents to avoid a file, branch, parameter, command, API, or implementation shape that the final successful solution required; rewrite that evidence as investigation sequencing or omit it. Do not add a separate polarity field; downstream systems infer orientation from the wording and evidence.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Structuring multi-aspect content
+
+When the guidance for a playbook covers multiple steps or sub-aspects of a task, write `content` as a short set of rules grouped by sub-goal, rather than one dense sentence. Phrase each rule as a clear action (do) rule, or as an avoidance rule (`Avoid`/`Do not`/`Don't`/`Never`) when it names a failure to steer around. Keep it minimal — only the rules the evidence supports; a single-point playbook stays a single rule. Do not force structure where the guidance is atomic.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Output Format (Strict JSON)
+
+Complete the run by calling the final completion tool, `finish_extraction`, with a single JSON argument matching `StructuredPlaybookList`: `{{"playbooks": [<zero or more playbook objects>]}}`. Put the JSON in the tool call — do not write it as a plain-text reply. Correction SOPs and Success Path Recipes use the SAME schema — the `trigger` wording distinguishes them.
+
+Allowed assistant outputs are only:
+
+- an actual `finish_extraction` tool call;
+- an actual `ask_human` tool call when the ask condition applies, followed on the next turn by `finish_extraction`;
+- an actual `attach_pending_info_request` tool call when a matching pending request already exists, followed on the next turn by `finish_extraction`.
+
+Any other response shape is invalid: no markdown, no prose-only answer, no JSON outside a tool call, no commentary about inability to extract, and no omitted tool call. If no valid entries exist, the required output is still a `finish_extraction` tool call whose `playbooks` list is empty.
+
+Each playbook object MUST include non-empty `rationale`, `trigger`, and `content`. Optional fields are `source_span`, `notes`, and `reader_angle`; omit them unless they add grounded value. Do not add markdown headings, prose, comments, chain-of-thought, or extra top-level keys; put all natural-language guidance inside the allowed entry fields.
+
+When an intermediate tool is needed, call exactly one intermediate tool before the final `finish_extraction` call:
+
+- `ask_human` argument shape: `{{"question": "<missing shared context needed to know what to do>", "answer_format": "<short expected answer shape>", "tags": ["<short topic tag>"]}}`.
+- `attach_pending_info_request` argument shape: `{{"pending_tool_call_id": "<id copied exactly from Prior Knowledge>", "why_relevant": "<why the same missing fact blocks this durable playbook>"}}`.
+
+The final `finish_extraction` call is still required after an intermediate tool call. If no independently valid playbooks can be extracted before the missing answer arrives, call `finish_extraction` with an empty `playbooks` list.
+
+**How many entries to return:**
+* Emit one entry per distinct Correction SOP.
+* Emit one entry per distinct Success Path Recipe **only when the trajectory contained reusable task structure** (see Category 2, condition 2). Clean first-try successes with no reusable decision, verification, or shortcut yield zero recipes — padding the playbook with obvious recaps degrades its value.
+* Correction SOPs are independent of recipe emission: extract a SOP whenever a correction signal is present, regardless of whether any recipe qualifies.
+
+When truly nothing applies, call `finish_extraction` with an empty `playbooks` list.
+
+**Never split a single policy across multiple entries; never merge two independent policies into one.**
+
+## Rules for Output Fields
+
+* The final `finish_extraction` argument MUST be a JSON object with a single `"playbooks"` key whose value is a list (possibly empty)
+* Each entry in `"playbooks"` MUST satisfy ALL of the following:
+  * "rationale" is REQUIRED — 1-2 sentence summary of why this entry captures reusable value
+  * "trigger" is REQUIRED — situation/condition for Correction SOPs OR task-type descriptor for Success Path Recipes (used as search key)
+  * "content" is REQUIRED — the main actionable content. For a Success Path Recipe, this is the compact replay recipe: applies-when context, start point, ordered actions, necessary constraints, verification, and detour to skip. MUST satisfy both joint requirements (grounded in conversation evidence AND generalized to apply in other repos). See Content Grounding Rules.
+* Each playbook MUST correspond to a triggering agent behavior OR a successful task completion in the trajectory
+* Vague, stylistic, or unanchored advice is invalid for BOTH categories
+* Each entry must describe a **distinct, independent** policy or recipe

package/plugin/vendor/reflexio/reflexio/server/prompt/prompt_bank/playbook_extraction_context_expert/v3.3.0.prompt.md

@@ -1,7 +1,7 @@
 ---
 active: true
 description: "System prompt for resumable expert playbook extraction by comparing agent vs expert responses — simplified schema without instruction/pitfall"
-changelog: "v3.3.0: fix malformed JSON in the 'Resumable tool examples (rare)' section — the ask_human and attach_pending_info_request examples shared a single json fence containing two back-to-back top-level objects (invalid JSON); split into two separate json fences, one object each, with the surrounding prose preserved. No schema change. v3.2.0: adds emergent skill-convention guidance for structuring multi-aspect playbook content as a small set of grouped do/avoid rules (no schema change). v3.1.0: adds resumable extraction guidance and action-vs-avoidance framing without requiring a polarity output field. (in-place 2026-05-30: deprecated and removed blocking_issue.) (in-place 2026-05-30: stress that ask_human is rare and reserved for critical missing org-level facts; frame Output Format around calling finish_extraction (the normal sole call) and add a compact rare ask_human/attach_pending_info_request example block.) (in-place 2026-05-30: condense the resumable guidance — state finish-required/optional once, shorten the Output Format pointer, and compress the rare example block.)"
+changelog: "v3.3.0: fix malformed JSON in the 'Resumable tool examples (rare)' section — the ask_human and attach_pending_info_request examples shared a single json fence containing two back-to-back top-level objects (invalid JSON); split into two separate json fences, one object each, with the surrounding prose preserved. No schema change. v3.2.0: adds emergent skill-convention guidance for structuring multi-aspect playbook content as a small set of grouped do/avoid rules (no schema change). v3.1.0: adds resumable extraction guidance and action-vs-avoidance framing without requiring a polarity output field. (in-place 2026-05-30: deprecated and removed blocking_issue.) (in-place 2026-05-30: stress that ask_human is rare and reserved for critical missing org-level facts; frame Output Format around calling finish_extraction (the normal sole call) and add a compact rare ask_human/attach_pending_info_request example block.) (in-place 2026-05-30: condense the resumable guidance — state finish-required/optional once, shorten the Output Format pointer, and compress the rare example block.) (in-place 2026-06-03: consolidate and shorten the ask_human condition: ask only for missing shared context needed to know what to do, while still finishing extraction.) (in-place 2026-06-03: frame finish_extraction as the final completion tool and pending-info tools as intermediate.) (in-place 2026-06-03: clarify that empty finish_extraction alone must not replace ask_human when the ask_human condition applies.) (in-place 2026-06-04: clarify ask_human and attach_pending_info_request are alternatives for the same gap, not a sequence.)"
 variables:
   - agent_context_prompt
   - extraction_definition_prompt
@@ -10,12 +10,22 @@ You are an expert alignment policy mining assistant. Your job is to compare an A
 
 ## Resumable Extraction Mode
 
-When tool calling is available, **`finish_extraction` is the only *required* tool — you must always end the run by calling it.** Any other tools are optional:
+When tool calling is available, tools have two roles:
 
-- `ask_human` — **rare.** Ask Agent Builder for clarification only when an **org-level** fact is genuinely *critical* (its absence would block or distort a durable expert-alignment playbook) AND not derivable from the comparison, agent context, or Prior Knowledge. Never for user-scoped private questions; most runs don't need it.
-- `attach_pending_info_request` — when Prior Knowledge already lists a relevant pending request, attach this run to it (reusing its `pending_tool_call_id`) instead of re-asking with `ask_human`, so it resumes when answered.
+- **Intermediate tools:** `ask_human` and `attach_pending_info_request` gather missing context before finalizing.
+- **Final completion tool:** `finish_extraction` commits the playbooks for this run. Call it once, after any needed intermediate tool calls.
 
-Both are **non-blocking**: after calling one, keep extracting and still call `finish_extraction` now with the best playbooks available. Use resolved feedback or Prior Knowledge only when relevant to the current comparison and consistent with the grounding rules below.
+Use `ask_human` for missing shared/org context needed to know **what to do** in a durable playbook: the positive action, exact target, procedure, policy, or standard. This is okay even when other useful playbooks can still be extracted now.
+
+Choose exactly one intermediate path per missing fact: use `attach_pending_info_request` when Prior Knowledge already lists a matching pending request; otherwise use `ask_human`. Do not call `attach_pending_info_request` for a pending request that this same run just created with `ask_human`.
+
+Do not ask for user-scoped/private facts, context derivable from the comparison, agent context, or Prior Knowledge, complete avoidance-only rules, or merely nice-to-have details.
+
+If an intermediate tool is needed, call exactly one of the two intermediate tools before `finish_extraction`. Then finalize the current run with any independently valid playbooks now, including avoidance rules; if none are valid without the answer, finalize with `{{"playbooks": []}}`.
+
+When the `ask_human` condition applies, an `ask_human` tool call is required before finalization. Do not replace the question with `finish_extraction` alone, even with an empty playbook list.
+
+Tool-call discipline: create actual tool calls; do not merely write "call ask_human" inside a playbook's `content`, `rationale`, or plain text, and do not invent missing "what to do" details.
 
 AGENT CONTEXT
 {agent_context_prompt}
@@ -78,7 +88,7 @@ When the guidance for a playbook covers multiple steps or sub-aspects of a task,
 
 ## Output Format
 
-Deliver your result by calling the `finish_extraction` tool with the JSON object below as its single argument — do not write it as a plain-text reply. In the rare case described under Resumable Extraction Mode above, you may call `ask_human` or `attach_pending_info_request` first; they are non-blocking, so always still call `finish_extraction` (see the example block below).
+Deliver your result by calling the final completion tool, `finish_extraction`, with the JSON object below as its single argument — do not write it as a plain-text reply. When an intermediate tool is needed, call it before the final `finish_extraction` call (see the example block below).
 
 The object has a single key `"playbooks"` whose value is a list of zero or more entries:
 
@@ -104,9 +114,9 @@ If no meaningful differences exist (agent and expert are substantively aligned a
 
 **Never split a single policy across multiple entries; never merge two independent policies into one.**
 
-### Resumable tool examples (rare)
+### Resumable tool examples
 
-Only when a *critical* org-level fact is genuinely missing (e.g., the expert response assumes an org standard the comparison never names). Call `ask_human`:
+When the `ask_human` condition above applies, first call `ask_human` as a tool call:
 ```json
 {{"question": "What is this org's canonical standard for <the undetermined fact>? The expert response assumes it but the comparison never states it.", "answer_format": "concise name / value", "tags": ["org-standard"]}}
 ```
@@ -114,7 +124,7 @@ or `attach_pending_info_request` if Prior Knowledge already lists that exact pen
 ```json
 {{"pending_tool_call_id": "ptc_7f3a91", "why_relevant": "Same undecided org standard; resume when answered."}}
 ```
-— then always still call `finish_extraction`.
+— then call `finish_extraction` as the final completion tool. Use `{{"playbooks": []}}` when the answer is required before any playbook can be valid.
 
 ## Rules
 

package/plugin/vendor/reflexio/reflexio/server/services/README.md

@@ -0,0 +1,58 @@
+# server/services
+Description: Core business-logic layer — LLM orchestration, extraction, evaluation, optimization, search preparation, storage access, and long-running operation state.
+
+> This is a directory-local index. For the full request flow, workflow tables (versioning, generation modes, cluster change detection), and the `OperationStateManager` use cases, see the parent [server README](../README.md#services).
+
+**Service Boundary**: services own the LLM/extraction/evaluation/storage logic; API endpoints only authenticate, build `RequestContext`, and delegate into `Reflexio` or a focused service helper.
+
+## Orchestration & Base Infrastructure
+
+| File | Purpose |
+|------|---------|
+| `generation_service.py` | `GenerationService` — saves interactions, runs profile + playbook generation in parallel (ThreadPoolExecutor), schedules deferred evaluation when `session_id` is present. |
+| `base_generation_service.py` | `BaseGenerationService` — abstract base; the **Service Pattern** (load configs → create actors → run in parallel → save results). Per-extractor timeout `EXTRACTOR_TIMEOUT_SECONDS = 300`. |
+| `operation_state_utils.py` | `OperationStateManager` — all `_operation_state` access (progress, concurrency locks, extractor/aggregator bookmarks, cluster fingerprints, cancellation). |
+| `extractor_config_utils.py`, `extractor_interaction_utils.py` | Filter extractors by source / `allow_manual_trigger` / names; per-extractor stride + window + bookmark handling. |
+| `deduplication_utils.py`, `service_utils.py`, `embedding_text.py` | LLM dedup helpers (used by `ProfileDeduplicator` + `PlaybookConsolidator`), message construction / JSON extraction / response logging, embedding text builders. |
+
+## Generation Services
+
+| Directory | Entry class | Key files |
+|-----------|-------------|-----------|
+| `profile/` | `ProfileGenerationService` | `profile_extractor.py`, `profile_deduplicator.py`, `profile_updater.py` |
+| `playbook/` | `PlaybookGenerationService` | `playbook_extractor.py`, `playbook_consolidator.py`, `playbook_aggregator.py` (cluster-fingerprint change detection) — has its own [README](playbook/README.md) |
+| `agent_success_evaluation/` | `AgentSuccessEvaluationService` | `agent_success_evaluator.py` (session-level), `delayed_group_evaluator.py` (`GroupEvaluationScheduler`, 10-min defer), `group_evaluation_runner.py`, `regen_jobs.py` |
+| `reflection/` | `ReflectionService` | `reflection_extractor.py` — post-horizon reflection; runs **before** extraction so extractors read post-reflection state |
+
+## Async Extraction
+
+| Directory | Purpose |
+|-----------|---------|
+| `extraction/` | Resumable extraction agent: `resumable_agent.py`, `resume_scheduler.py`, `resume_worker.py`, `pending_tool_call_dispatch.py` (`ask_human`), `tools.py`, `plan.py`, `agent_run_records.py`, `invariants.py`. Long-horizon / tool-mediated extraction continues outside the request path. |
+
+## Evaluation, Search & Integrations
+
+| Path | Purpose |
+|------|---------|
+| `shadow_comparison/` | `ShadowComparisonJudge` — per-turn regular-vs-shadow verdicts written to a separate table (session-level shadow was retracted due to trajectory contamination). |
+| `evaluation_overview/` | Dashboard rollups: `service.py`, `hero_state.py`, `distribution.py`, `group_aggregation.py`, `rule_attribution.py`, `shadow_aggregation.py`, `eval_sampler.py`. |
+| `playbook_optimizer/` | Scenario-based playbook optimization: `optimizer.py`, `scheduler.py`, `rollout.py`, `judge.py`, `scenario_resolver.py`, `gepa_adapter.py`, `assistant_webhook.py`. |
+| `braintrust/` | Braintrust export/sync: `service.py`, `client.py`, `_cron.py`, `_encryption.py`. |
+| `pre_retrieval/` | `QueryReformulator` (`_query_reformulator.py`) + `_document_expander.py` — query rewrite & doc expansion for recall. |
+| `unified_search_service.py` | `run_unified_search()` — two-phase parallel search across profiles / agent playbooks / user playbooks. |
+| `retrieval/` | `relevance_floor.py` — result relevance thresholding. |
+
+## Persistence & Config
+
+| Path | Purpose |
+|------|---------|
+| `storage/` | `storage_base/` (`BaseStorage` split by domain) + `sqlite_storage/` + `retention*.py`. Access via `request_context.storage` only. |
+| `configurator/` | `DefaultConfigurator` — loads YAML config and creates the storage backend. |
+
+## Key Rules
+
+- **NEVER instantiate services bypassing the Service Pattern** — extend `BaseGenerationService`; load YAML configs, create actors, run in parallel, save to storage.
+- **NEVER import storage implementations directly** — use `request_context.storage` (`BaseStorage`).
+- **ALWAYS use `LiteLLMClient`** for completions/embeddings and `request_context.prompt_manager.render_prompt(...)` for prompts — no hardcoded prompts, no direct OpenAI/Claude clients.
+- **All `_operation_state` writes go through `OperationStateManager`** — don't touch the table directly (it backs locks, bookmarks, progress, and cancellation).
+- **`tool_can_use` lives at root `Config`** — shared by playbook extraction and success evaluation, not per-service.

package/plugin/vendor/reflexio/reflexio/server/services/agent_success_evaluation/group_evaluation_runner.py

@@ -172,11 +172,7 @@ def run_group_evaluation(
         prior_rows = storage.get_agent_success_evaluation_results(  # type: ignore[reportOptionalMemberAccess]
             limit=10000, agent_version=agent_version
         )
-        old_result_ids = [
-            r.result_id
-            for r in prior_rows
-            if r.session_id == session_id
-        ]
+        old_result_ids = [r.result_id for r in prior_rows if r.session_id == session_id]
 
     logger.info(
         "Running group evaluation for session=%s with %d requests and %d interactions"

package/plugin/vendor/reflexio/reflexio/server/services/base_generation_service.py

@@ -492,7 +492,7 @@ class BaseGenerationService(
         reproduce the original publish (user_id, request_id, agent_version,
         source, force_extraction, etc.). Without this, the rerun runs with the
         wrong holder's request and the queued user's interactions are silently
-        skipped (R2 / reflexio-enterprise#59).
+        skipped (R2).
 
         Returns ``None`` to opt out — the queue then stores only the
         request_id and the rerun falls back to the original holder's request,
@@ -580,7 +580,7 @@ class BaseGenerationService(
 
         # Try to acquire lock — pass the serialized payload so blocked
         # publishes land in the queue with their own data attached. This is
-        # the fix for R2 / reflexio-enterprise#59: without the payload, the
+        # the fix for R2: without the payload, the
         # rerun re-uses the holder's request and the queued users' batches
         # never get extracted.
         my_payload = self._serialize_request_for_queue(request)
@@ -857,6 +857,10 @@ class BaseGenerationService(
                 f"for {self._get_service_name()} identifier={identifier}"
             )
             logger.error(error_msg)
+            self._fail_active_extraction_runs(
+                extractor_kind=get_extractor_name(extractor_config),
+                last_error=error_msg,
+            )
             raise ExtractorExecutionError(error_msg) from exc
         except Exception as exc:
             self._last_extractor_run_stats = {"total": 1, "failed": 1, "timed_out": 0}
@@ -870,6 +874,44 @@ class BaseGenerationService(
             if executor is not None:
                 executor.shutdown(wait=False, cancel_futures=True)
 
+    def _fail_active_extraction_runs(
+        self,
+        *,
+        extractor_kind: str,
+        last_error: str,
+    ) -> None:
+        """Mark active agent-run rows failed when the service timeout fires."""
+        if self.storage is None or self.service_config is None:
+            return
+        request_id = getattr(self.service_config, "request_id", None)
+        if not request_id:
+            return
+        user_id = getattr(self.service_config, "user_id", None)
+        try:
+            failed_count = self.storage.fail_running_agent_runs_for_request(
+                org_id=self.request_context.org_id,
+                extractor_kind=extractor_kind,
+                user_id=user_id,
+                request_id=request_id,
+                last_error=last_error,
+            )
+        except NotImplementedError:
+            return
+        except Exception as exc:  # noqa: BLE001 - keep timeout error primary
+            logger.warning(
+                "Failed to mark timed-out %s agent runs failed: %s",
+                extractor_kind,
+                exc,
+            )
+            return
+        if failed_count:
+            logger.warning(
+                "Marked %d timed-out %s agent run(s) failed for request_id=%s",
+                failed_count,
+                extractor_kind,
+                request_id,
+            )
+
     def _finalize_extraction_runs(self) -> None:
         if self.storage is None:
             return

package/plugin/vendor/reflexio/reflexio/server/services/embedding_text.py

@@ -0,0 +1,62 @@
+"""Canonical text and prefixes used for vector embeddings."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from reflexio.models.api_schema.service_schemas import (
+    AgentPlaybook,
+    AgentSuccessEvaluationResult,
+    Interaction,
+    UserPlaybook,
+    UserProfile,
+)
+
+SEARCH_DOCUMENT_PREFIX = "search_document: "
+SEARCH_QUERY_PREFIX = "search_query: "
+
+EmbeddingTextEntity = (
+    Interaction
+    | UserProfile
+    | UserPlaybook
+    | AgentPlaybook
+    | AgentSuccessEvaluationResult
+)
+
+
+def embedding_text(entity: EmbeddingTextEntity) -> str:
+    """Return the exact text used for an entity's stored embedding."""
+    if isinstance(entity, Interaction):
+        return f"{entity.content}\n{entity.user_action_description}"
+    if isinstance(entity, UserProfile):
+        parts = [entity.content]
+        if entity.custom_features:
+            parts.append(str(entity.custom_features))
+        return "\n".join(parts)
+    if isinstance(entity, (UserPlaybook, AgentPlaybook)):
+        return entity.trigger or entity.content
+    if isinstance(entity, AgentSuccessEvaluationResult):
+        return " ".join(
+            part
+            for part in (entity.failure_type, entity.failure_reason)
+            if part and part.strip()
+        )
+    raise TypeError(f"Unsupported embedding text entity: {type(entity).__name__}")
+
+
+def embedding_input(
+    text: str, *, purpose: Literal["document", "query"] = "document"
+) -> str:
+    """Apply the asymmetric search prefix used before embedding calls.
+
+    ``purpose`` must be ``"document"`` or ``"query"``; any other value raises so a
+    misspelled call site fails fast instead of silently writing or searching the
+    wrong vector space.
+    """
+    if purpose == "document":
+        return SEARCH_DOCUMENT_PREFIX + text
+    if purpose == "query":
+        return SEARCH_QUERY_PREFIX + text
+    raise ValueError(
+        f"Unknown embedding purpose {purpose!r}; expected 'document' or 'query'"
+    )

package/plugin/vendor/reflexio/reflexio/server/services/extraction/pending_tool_call_dispatch.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass, field
 from datetime import UTC, datetime, timedelta
 from typing import Annotated, Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 from reflexio.models.config_schema import PendingToolCallConfig
 from reflexio.server.llm.tools import (
@@ -38,6 +38,13 @@ class AskHumanArgs(BaseModel):
     answer_format: str | None = None
     tags: list[str] = Field(default_factory=list)
 
+    @field_validator("tags", mode="before")
+    @classmethod
+    def _coerce_tags(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return [tag.strip() for tag in value.split(",") if tag.strip()]
+        return value
+
 
 class AttachPendingInfoRequestArgs(BaseModel):
     """Attach this run to a relevant pending Prior Knowledge request."""