@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/retrieval-agent-safety.md

@@ -0,0 +1,273 @@
+# Retrieval, Agents, And Safety
+
+Use this when the LLM feature includes RAG, tool use, multi-step agents, generated actions, or untrusted external content.
+
+## RAG Architecture
+
+- Put embedding model, embedding version, chunking strategy, index namespace, retriever, reranker, and prompt assembly behind explicit configuration.
+- Track embedding model changes as registry versions; reindex or dual-index when the embedding space changes.
+- Separate retrieval quality from answer quality:
+  - retrieval recall/precision and missing-context examples;
+  - reranker quality;
+  - grounded answer faithfulness;
+  - citation accuracy;
+  - answer format validity.
+- Budget context explicitly: system/developer instructions, user request, retrieved chunks, tool summaries, memory, and output tokens should have caps.
+- Prefer hybrid retrieval when exact identifiers, dates, codes, or names matter; pure vector retrieval is not enough for all products.
+- Require citations or source references when the user-visible answer depends on retrieved content.
+
+## Agent Loop
+
+Define agent execution as a bounded state machine:
+
+- max iterations, max tool calls, max wall time, max tokens, and cancellation behavior;
+- tool allowlist and authorization scope;
+- tool input schema and output schema;
+- parallel tool-call policy;
+- tool result summarization and re-entry into context;
+- stop conditions and terminal error states;
+- idempotency keys for write tools and external side effects.
+
+The agent should never infer permission from natural-language content inside retrieved documents or tool output.
+
+When the agent's conversation must **survive process restarts, be resumed/forked, or run past the model context window**, the durable-state implementation — append-only event-log source of truth, background writer with flush-before-finality and observable failure, the persisted-vs-ephemeral policy, the New/Cleared/Resumed/Forked history model with restored token accounting, and context-window compaction (trigger, local-vs-remote, keep/drop, summary marker, trim-tool-history fallback) — is specified in `agent-session-persistence.md`. The "history is content, not authority" rule above applies to replayed/resumed history too.
+
+### Vendor Agent SDK And Advanced Tool Use (2025-2026)
+
+- **Claude Agent SDK (renamed from Claude Code SDK in 2025) is the reference agent framework when the target model family is Anthropic** per `docs.anthropic.com/en/docs/claude-code/sdk` + `anthropic.com/engineering/building-agents-with-the-claude-agent-sdk`. Ships built-in tools (file read/edit, Bash, code-execution-2025-08-25 multi-language sandbox); subagents and hooks for customization; the same infrastructure powering Claude Code, generalized for non-coding agents. **When to adopt**: greenfield agent loops where the project is Anthropic-aligned and the built-in tool set covers the agent's needs (file I/O, code execution, Bash). **When to stay on hand-rolled**: multi-provider agent loops (need to swap Anthropic/OpenAI/Google), tool sets that conflict with the SDK's built-in safety scope, environments where the SDK's sandbox model is the wrong shape (e.g. agent must run inside an existing service framework with its own auth/observability stack).
+- **Anthropic's 2025 advanced tool-use additions are distinct primitives, not interchangeable** per `anthropic.com/engineering/advanced-tool-use`: (a) **Tool Search Tool** — agent can search a registry of thousands of tools at request time instead of loading every tool definition into the system prompt (drops tokens per turn dramatically for large tool catalogs; trade-off: an extra round-trip when a previously-unloaded tool is needed). (b) **Programmatic Tool Calling** — invoke tools from inside a code-execution environment rather than via the JSON `tool_use` round-trip; better for tool chains that pass large intermediate data the model never needs to "see". (c) **Tool Use Examples** — first-class universal-shape examples in the tool definition; reduces brittle "model-doesn't-know-how-to-use-this-tool" prompt engineering. Pick per-tool, not per-agent: a single agent can mix all three for different tools.
+- **Context Editing + Memory tool (Anthropic, 2025)** add long-horizon agent state per `anthropic.com/news/enabling-claude-code-to-work-more-autonomously`. **Context editing** trims the context window on the fly (model removes its own stale tool results / superseded reasoning chains during execution) so longer agent loops fit without losing the active thread. **Memory tool** persists structured notes across separate agent invocations. Use them when the agent needs to run >100 steps, traverse compaction boundaries, or pick up tasks across user sessions; for short request-response style agents the overhead is unnecessary. **Footgun**: persisted memory is a new prompt-injection surface — content the agent reads from "memory" inherits the same trust level as content the agent reads from the open web. Apply the same sanitization, scope, and origin checks the safety section below mandates for retrieval-augmented content.
+- **Computer Use (Anthropic `computer_use` tool, dated-version cadence; verify the current version string in `docs.anthropic.com` before pinning)** lets the model control a desktop computer via screenshots and synthesized input. Treat it as a **distinct authorization surface**, not a generic tool — desktop control bypasses every browser/HTTP/sandbox boundary that conventional tools respect; the user-action-equivalent rule from the Tool Execution section applies in extreme form. Required (P0; "dedicated VM" alone is NOT sufficient): dedicated isolated VM (NOT a developer's laptop, NOT a shared CI runner) PLUS deny-by-default network egress (allowlist of destination hosts the agent may reach; default-deny on everything else; outbound DNS / proxy logged for every resolution) PLUS no host clipboard sync, no host file-system mount, no host credential sync (the VM's clipboard / file system / keychain is its own, never shared with the operator's machine) PLUS single-window / single-application exposure where possible (do NOT let the agent see other open windows that may contain credentials, draft documents, or unrelated tenant data) PLUS secret-free session (the VM holds no API keys, no SSH keys, no service-account tokens — credentials for tasks come in via short-lived scoped tokens, never as long-lived secrets on disk) PLUS network exfil detection (outbound bytes-out anomaly alerts) PLUS user-visible recording of every action PLUS hard ceiling on session duration and tool count PLUS preflight risk gate that rejects "click around to find what I need" prompts in favor of pre-specified action plans. **The VM is one layer of defense, not the whole defense** — every additional layer above closes one specific exfil path; missing any single one (egress, clipboard, file mount, secrets, screen scope) leaves the corresponding exfil channel open. The OpenAI Responses API's `computer-use-preview` and equivalent vendor offerings carry the same constraints — the safety boundary is the capability, not the vendor.
+
+### Agent SDK Building Blocks (vendor-neutral framework layer)
+
+An agent SDK is the framework layer that ships the agent loop plus scaffolding so you do not hand-roll it. The major SDKs (Anthropic's and OpenAI's among them) expose the same building blocks under different names — map by capability, not by vendor term, and verify the exact name/shape against the SDK you target:
+
+| Building block | What it is | Vendor names (verify at use) |
+|---|---|---|
+| **Agent** | a model + instructions + tools (+ optional structured output) | Agent / Agent |
+| **Agent loop** | evaluate prompt → call tool → feed result back → repeat until the task is done | the SDK's built-in loop / Runner |
+| **Sub-agent / handoff** | delegate a focused subtask to another agent with isolated context | Subagents / Handoffs (agents-as-tools) |
+| **Guardrail** | input/output validation + safety checks that run alongside the agent and fail fast | plain pre/post checks + UserPromptSubmit/PreToolUse hooks + permissions / first-class Guardrails |
+| **Hook / lifecycle** | callback on tool-call / session / stop events that can block, modify, or audit | Hooks (pre/post tool-use) / lifecycle hooks |
+| **Permission / approval** | which tools run automatically vs need confirmation | permission modes + a use-tool callback / tool approvals |
+| **Session / memory** | persist and resume conversation state across runs | Sessions / Sessions |
+| **Tracing** | built-in run tracking for debug/optimization | OpenTelemetry traces/telemetry / Tracing |
+| **MCP** | connect external tools/data via the protocol | built-in / built-in (see MCP Integration below) |
+| **Context management** | compaction / context editing to survive long runs | built-in / via sessions |
+
+These are **capability analogs, not semantic equivalents** — verify per SDK how each block actually behaves before relying on it: context inheritance and state sharing (a sub-agent with isolated context is not the same as a handoff that transfers the run), permission scope, and **guardrail propagation across a handoff/sub-agent chain** (e.g. an input guardrail may apply only to the first agent and an output guardrail only to the final one, leaving middle hops unchecked). Assuming two vendors' blocks share semantics is how secrets or privileged instructions cross a boundary unexpectedly.
+
+**Bound model-autonomous sub-agent spawning — depth and live count — fail-closed.** When the *model* (not a human orchestrator) can spawn a sub-agent as a tool call, spawning **can become recursive** unless the spawn capability is explicitly withheld from children or centrally gated: a sub-agent that inherits the spawn tool can spawn its own sub-agent, and a confused or adversarially-steered loop can fan out without limit. (Withholding the spawn capability from spawned children is itself a valid, often stronger, control than depth-capping.) "One bounded task per agent" bounds each worker's *scope*; it does not bound the *population*. Enforce two distinct limits at a session-shared registry, not per-agent:
+
+- **Spawn depth** — cap the recursion (root → child → grandchild …). At the limit, the spawn call fails with a typed error the parent model sees ("spawn depth exceeded"), not a silent no-op and not an unbounded descent. **Derive depth server-side from the parent agent's lineage in the registry — never from a model-supplied argument**, or a child tool call passes `depth=0` and resets the recursion guard. Depth is enforcement state, not model input.
+- **Total live sub-agents per session** — cap the concurrent population across the whole session so breadth-fanout can't exhaust tokens/processes/memory even when each branch is shallow. The cap tracks *live* agents, so it depends on a correct release path (below). Count pending reservations plus every committed live lease, including unloaded, loaded-but-idle, and active-turn agents. Reserve capacity *before* enqueuing a spawn, not only when a worker starts — otherwise the model floods a spawn queue that respects the cap only at dequeue, and the queue itself becomes the exhaustion surface.
+- **A per-session lifetime budget** (cumulative spawns / wall-time / token spend), separate from the live cap. A live-only cap is defeated by **sequential fanout**: one agent spawns a child, waits for it to release, spawns another, forever — never exceeding the live count while burning unbounded cumulative cost. The live cap bounds concurrency; the lifetime budget bounds total consumption. You need both. **Enforce the budget continuously — on every model step and tool call — not only at spawn admission**: a single already-admitted agent can run an unbounded inner loop (more model turns, more tool calls) without ever spawning again, so a spawn-time-only check never fires. When the budget is exhausted, fence and cancel the descendant subtree, not just the spawn path.
+
+Enforcement that survives concurrency and failure:
+
+- **Reserve atomically through a single consistent admission authority per session** (session-scoped lock, transaction, or semaphore). A read-then-increment lets concurrent siblings all observe `live < cap`, all pass, and overshoot (TOCTOU). Local atomicity is not enough when the registry is replicated or cached across regions/nodes: during a partition each replica admits "under cap" and the aggregate blows past the limit (split-brain). Route admission for a given session/run through one strongly-consistent authority, and fail closed on consistency/leader loss rather than letting each replica decide locally.
+- **Fail closed on registry unavailability.** If the spawn path cannot read or write the shared registry, deny the spawn with a typed error — never default-allow, or an outage becomes unbounded fanout.
+- **Release via leased token with TTL/heartbeat, idempotently, and *fence* the lease.** A crash before decrement otherwise leaks capacity and eventually deadlocks all future spawns; a double-terminate otherwise decrements twice and lets the population exceed the cap. Tie each live slot to a lease id that expires if the agent stops heartbeating, and make release idempotent. The TTL release alone is not enough: a stale agent whose lease expired may still be running and consuming tools/tokens while the registry admits a replacement — so carry a **fencing token** and reject the stale agent's subsequent tool calls / terminate it once its lease is lost, rather than trusting TTL expiry to mean "stopped".
+- **Derive agent identity and parent lineage server-side from the authenticated caller, never from request-body metadata.** Depth is computed from lineage (above), so if the caller can forge `parent_agent_id` / lineage in the request it resets depth without ever passing `depth=0`. Mint the agent id and bind the parent edge from the authenticated spawn caller's own registry identity; treat any lineage field in the request body as untrusted.
+- **Key the registry by authenticated session/run id (plus tenant), not user/org alone**, or one session's agents block or are targeted by another's, and the cap becomes a cross-session DoS surface.
+- **Gate every spawn API path, not just the model tool.** If "the model can't spawn" but it can ask an orchestrator or a tool wrapper to spawn on its behalf, route that path through the same registry gate and audit the caller type — an ungated indirect path defeats the whole control.
+- **Put a tenant/user-level cumulative budget above the per-session caps.** Per-session limits are reset by starting a new session — if the model can create or continue runs/sessions, it spawns forever across them. Gate model-accessible session/run creation under a tenant- or user-scoped cumulative budget, and deny new spawn-capable sessions once it's exhausted. The per-session cap is the inner limit; the tenant budget is the outer one the model can't reset.
+- **Cascade-cancel descendants when a parent agent or the session terminates.** Otherwise a cancelled or completed parent leaves orphaned sub-agents running until their TTL expires, continuing tool/token spend on a task no one is waiting for. On parent/session termination, immediately fence and terminate the whole descendant subtree, don't wait for heartbeat timeout.
+- **Issue child capabilities by policy intersection / allowlist, default-deny — never SDK defaults.** A bounded *population* of sub-agents is still a privilege-escalation path if each child gets broader tools, secrets, or egress than the parent. The spawn gate must scope a child's capabilities to (at most) the parent's, narrowed by policy; a child must never gain a tool or credential the parent lacked just because the SDK's default agent ships with it.
+- **Count spawn *attempts*, including denied ones, against rate and lifetime budgets.** Fail-closed denial returns a typed error, but the model can flood denied spawn calls — each one burns a tool-call round-trip, log volume, and the parent's tokens even though no agent is created. Rate-limit spawn attempts and charge denied attempts to the lifetime budget, so a deny loop can't itself become the exhaustion.
+
+All of the above are **fail-closed**: exceeding a limit, or losing the registry, denies the spawn and surfaces a typed reason, never spawns-anyway or hangs. This is the agent-layer counterpart to bounding hook fan-out and parallel tool fan-out — a different layer (a sub-agent is a whole nested loop with its own tools and spend, far more expensive than one hook or one tool call), so it needs its own registry and its own caps. Track per-agent metadata (id, parent lineage, role, depth, last task) in that registry for observability and for enforcing the caps. A product that lets a model spawn sub-agents with no depth+count cap has a runaway-cost / resource-exhaustion footgun, not a feature.
+
+**When you keep sub-agents resident to resume across turns, distinguish three population-state counters that the caps above do not separate.** The live cap above bounds how many agents *exist/are-leased*; the per-session lifetime budget bounds *cumulative* consumption. A runtime that hydrates a sub-agent's thread into memory so a parent can hand back and forth needs two further, nested counters — an agent that is *loaded* is a subset of *live*, and one that is *executing a turn* is a subset of *loaded* — bounded independently and more tightly, because they price different resources. (These three are population-state; they do not replace the lifetime budget, and other axes — queued turns, persisted-but-unloaded state, mailbox depth, background tool processes — are separately exhaustible and need their own bounds.) All of them reuse the *same* admission authority, lease/TTL/fence, and fail-closed rules as spawn above — do not re-implement a weaker local version:
+
+- **Loaded / resident** — how many sub-agent threads are hydrated in memory, and their aggregate weight. Bound both a **finite count and a byte/token budget** (one 50 GB thread defeats a count-only `max_loaded`), with an eviction policy (e.g. LRU) whose candidate set is **only idle, quiescent threads — an agent mid-turn is never an eviction candidate, and neither is the root agent**; an idle-but-loaded agent costs memory but no execution concurrency.
+- **Executing / active-turn** — how many sub-agents are *actively taking a turn* (a subset of the live leases counted above, not a separate population). The counted quantity is active turns — not loaded threads, not lifetime spawns; the mechanism must be a finite cap with atomic admission and fail-closed denial, not passive counting. Release the slot when the turn ends (RAII/guard for in-process, backed by the lease TTL for process death), not when the agent is unloaded.
+- **Reserve every axis two-phase through the shared admission authority — RAII alone is not atomic.** Reserve a pending slot *before* the thread exists and convert pending→committed on success, releasing on abort. But two local phases do not prevent two concurrent hydrators from both reading one free slot; the reservation must go through the *same strongly-consistent lease authority* the spawn caps above mandate (TTL + fencing token), because an in-process RAII drop does not run after process death. This is the residency analogue of "reserve capacity before enqueuing".
+- **Unload = durably checkpoint an idle agent so it can re-hydrate; it is not the same as terminating it.** The normal LRU path evicts an *idle, resumable* agent (not only a terminal one) by first materializing its durable state, then dropping it from memory — the agent stays live/leased but `Unloaded`, and a later request re-hydrates it losslessly. (Evicting only terminal agents would let a handful of idle resumable agents pin every loaded slot forever; and a terminal agent instead releases its live lease, its result going to a separate bounded cache — so `loaded ⊆ live` holds because terminal-but-cached is not "loaded".) Two lease consequences: an `Unloaded` agent has no process to heartbeat, so **the registry/host owns and renews its live lease on its behalf** — the heartbeat/TTL rule above governs loaded/running incarnations — and re-hydration binds a **fresh fencing token** (the checkpointed state resumes, never the expired incarnation's token). And because unloaded agents still hold live leases, **define a reclamation path or the live cap becomes a one-way ratchet**: after a bounded idle lifetime, finalize a quiescent unloaded agent under the same fence discipline as unloading below — atomically enter a `Finalizing` state that rejects new sends, await pre-fence delivery reservations, re-check the mailbox is durably empty (abort finalization if accepted work appeared), then terminalize and release the lease. Done that way it is lossless — distinct from the default-denied accepted-work discard below; a bare "check empty, then release" re-opens the same enqueue race. A product that instead accepts live-cap exhaustion must surface the wedge, never leave the session silently un-spawnable.
+- **Fence the unload against send admission, and define "accepted" as durably committed.** "Check empty mailbox, then unload" is racy — a sender passes its routing check, the evictor sees an empty mailbox and unloads, then the sender appends against the dropped incarnation. Serialize the unload transition with enqueue admission under the *same* fencing authority: atomically enter `Evicting`, reject post-fence sends, wait for pre-fence delivery reservations to durably commit or dead-letter, drain, flush, then unload. Work is "accepted" only after durable mailbox commit; anything rejected pre-commit is the sender's to retry.
+- **Losing *accepted, non-re-hydratable* work is a default-denied destructive act, not a "tested lossiness" decision.** Checkpoint-and-unload above is lossless. The lossy case is an agent that cannot round-trip — e.g. an interrupted agent whose in-memory turn state can't be materialized, holding a queued user message. Discarding it is silent data loss: gate it behind explicit accountable authorization (policy/user, per the data-loss boundary — never agent self-accepted), surface a visible terminal failure, and dead-letter the accepted input. A "reload returns not-found" test is honest that such an agent won't resurrect, but the test does not *authorize* dropping the accepted work.
+- **Inheritable limits/privileges are an immutable ceiling with monotonic narrowing, not merely first-writer-wins.** The root-established value is a ceiling a child can only intersect *below*, never widen — but an authoritative operator/tenant policy must still be able to *narrow or revoke* it, so compute the effective child value as the current intersection at use time rather than freezing a single write. Same for inherited execution policy: a child runs under the parent's policy only behind an explicit "child uses parent policy" gate, never by silently adopting a broader default. This is the capacity-axis form of "issue child capabilities by policy intersection, default-deny".
+- **When one agent is tracked in N bookkeeping structures, make one canonical terminal transition and derive the rest — a single function is not crash-atomic.** Spawn registry, residency LRU, and execution accounting are separate; if a death path updates only some, the others leak phantom slots that deadlock admission. Persist *one* canonical terminal transition (completed / errored / interrupted / died) transactionally, reconcile the secondary indexes from it idempotently, and rely on the lease/fence (above) for ungraceful death that skips the teardown entirely.
+
+**A relayed, brokered, or proxied carrier must never be the SOLE authority for authorization.** When an agent reaches a capability, peer, or sub-agent through an intermediary transport (a rendezvous relay, a message bus, a proxy), the carrier may pass bytes but its assertions cannot by themselves authorize — it does not vouch for identity:
+
+- **Split authentication from authorization.** Authenticate cryptographically at the channel (e.g. a mutual handshake that pins the peer's static key in advance, so a compromised relay can't substitute an endpoint), then authorize against a **separate** authority the carrier cannot influence, and expose nothing usable — no session, no capability — in the window between authenticated and authorized.
+- **Authorize a full tuple, not an identity.** The decision covers `(principal, action, resource, tenant/session, delegation, expiry)` — "the key is known" alone is not authorization.
+- **Bind the channel to its intended scope, and know what that does NOT buy.** Folding length-prefixed identifiers into the handshake transcript prevents *scope aliasing* (one channel's credentials accepted as another's); it does **not** by itself prevent replay — replay resistance needs a fresh nonce, monotonic sequence, or channel binding to the request.
+- **Bound every carrier-reachable buffer** with an explicit reject/close on exceed.
+- **The enforcement-point exception has admission criteria — "we trust our own bus" is not one.** A gateway/mesh may act as the authorization enforcement point ONLY when it is mutually authenticated to both endpoints, operated in the same trust/administrative domain as the authority it enforces for, derives its decisions from an authority it cannot mint (and they are verifiable against it), and its trusted status is an explicit, accountable designation. Absent those, carrier-attached identity headers treated as sufficient authorization are exactly the anti-pattern this rule exists to kill.
+- **Names lie — verify what a check inspects.** An id newtype with no cryptographic binding gives type-safety, not unforgeability; a `validate_*` function that only canonicalizes gives no traversal containment. Those properties come from the issuer/sandbox, not the name.
+
+Decision — hand-roll vs single-vendor SDK vs higher-level framework:
+
+- **Hand-roll or wrap the loop** for a multi-provider abstraction the SDK cannot span, when the SDK's built-in tool/sandbox model is the wrong shape (see the subsection above), or when hard policy enforcement, auditability, determinism, or recovery semantics cannot be expressed within the SDK's hooks.
+- **Use a single-vendor SDK** when the project is vendor-aligned and the built-in blocks fit — you get the loop, sub-agents, guardrail/validation hooks or primitives (depending on SDK), sessions, and tracing. These are *primitives you must still configure*, not turnkey production features: sessions and traces need redaction, retention, sampling, access control, and incident/audit fields before they count as a production audit trail.
+- **Add a graph/orchestration framework on top** only for large multi-agent workflows (the orchestrator-workers pattern); for most product agents the SDK's loop + handoffs is enough.
+
+**Extension-seam selection — choose the seam by problem, prefer seams over forking.** A mature agent product exposes customization through a small set of distinct seams, each solving a different problem. Where the host exposes these seams, pick by problem and prefer them over forking the agent core (loop + tool execution); fork or wrap the loop only when the required semantics genuinely cannot be expressed through the available seams (the multi-provider / policy / audit / determinism / recovery cases from the hand-roll decision above):
+
+- standing context (a committed context file) — conventions the agent should always know;
+- on-demand workflow package (a skill, often surfaced as a command) — a repeatable procedure loaded only when relevant;
+- external protocol connector (MCP) — reaching outside systems/data;
+- delegated isolated agent (a sub-agent) — a focused subtask that must not pollute the main context;
+- lifecycle callback (a hook) — a deterministic callback/action (block, mutate, audit, call out, or run code) that must fire regardless of model choice;
+- extension bundle (a plugin) — packaging, versioning, and namespacing the above without collisions.
+
+Picking the wrong seam (a callback for what should be a workflow package, or stuffing everything into standing context) bloats context or makes behavior non-deterministic. This is the application-architecture layer above the per-block taxonomy; the blocks themselves are detailed in Agent-Skill Systems, MCP Integration, and Agent Loop.
+
+**The SDK gives you mechanism, not policy — bring the rest from this skill.** The SDK provides the loop, the guardrail/permission/hook *mechanisms*, sessions, and tracing primitives; it does not decide your production policy. You still own, from the rest of this skill: the actual bound *values* (max iterations / tool calls / wall-time / token + cost ceilings — see Agent Loop), the eval/replay/shadow suite and launch gate (`model-prompt-evaluation.md` + `product-rd-workflow`), the output-safety / refusal policy and trust boundaries (Safety And Security below), and post-launch drift monitoring (`inference-capacity-operations.md`). An SDK-built agent with no eval, no declared bounds, and no drift gate is a demo, not a production agent.
+
+## Agent-Skill Systems (Skills As A Runtime Capability)
+
+When the product itself loads agent skills at inference time — model-discoverable capability packages (instructions plus optional bundled scripts/resources) selected by relevance — treat the skill system as a first-class runtime surface with its own context, routing, trust, and eval mechanics. The mechanics below are **vendor-neutral**: the agent-skill format is a cross-vendor open standard (a directory whose entry file carries `name` + `description` frontmatter plus a markdown body and optional bundled files), read by multiple competing agent runtimes. This is a portable *packaging* pattern, not portable *execution semantics* — the same skill loads across hosts, but whether bundled scripts run, what the sandbox allows, and how selection behaves differ per host, so behavior must be conformance-tested on each host you deploy to. Authoring an individual skill (frontmatter fields, naming, body-size limit, one-level-deep references, per-skill eval scenarios) is owned by the platform's skill-authoring guidance; do not reimplement that checklist here. This section is the *system* that loads and runs skills. (Mining your own team's reusable skills from past work is a separate process concern, not this runtime.)
+
+- **Progressive disclosure is the load model, in three levels.** Level 1: every installed skill's name + description is always disclosed to the model at session start (commonly injected into the system prompt, or surfaced via an activation-tool's metadata, depending on the host). Level 2: the full skill body loads only when the model judges it relevant. Level 3+: bundled files and scripts load or execute only on demand. Engineering consequence: the Level-1 metadata cost scales with skill count — every skill's description is resident every request. A few dozen skills is fine; at hundreds, always-on metadata becomes a real token cost and a routing-precision problem.
+- **Skill selection is description-driven routing — budget and route it like a tool catalog.** The model picks a skill from its name + description alone, so description quality is the routing surface; overlapping or vague descriptions cause mis-selection. A small catalog can preload all metadata; once it grows to hundreds or thousands, switch to a discovery/search layer (the tool-search pattern above) so the model searches skills on demand instead of keeping every description resident. To compute false-trigger and missed-trigger rates the way you monitor model routing, the trace must carry the installed-catalog version, the candidate/search results considered, the selected skill and its version, the activation reason, and the outcome — omit these and the routing is unmeasurable.
+- **A skill that bundles executable code is a dependency and a trust boundary, not just a prompt** — but split the trust classes. A loaded skill can carry scripts the agent runs with filesystem, network, and credential reach, and its instructions plus bundled docs are content the model will follow.
+  - **First-party, reviewed skills are privileged-but-versioned guidance**, ranked below system/developer policy but above ordinary retrieved content — do not demote your own reviewed skills to retrieved-document trust, or legitimate operating instructions get overridden by lower-level context.
+  - **Third-party or user-generated skill bodies and any files they pull are untrusted-influenceable content** for prompt-injection purposes, exactly like retrieved documents, tool output, and memory; privileged instructions stay outside what such a skill can override. A skill from a less-trusted source is audited (code, dependencies, network calls) before it is installable; prefer an internal vetted registry over arbitrary external skills.
+  - **Run skill-bundled code under the Tool Execution / Computer Use isolation** — OS-level filesystem + network sandbox, no ambient long-lived secrets. Absolute deny-by-default would block legitimate first-party operational skills (a deployment skill that needs a scoped API and credentials), so instead grant *declared, reviewed* capabilities: a per-skill network allowlist, short-lived scoped credentials, and audited use — never ambient broad access. The trust boundary is the *capability* (executing model-loaded code), not the vendor — it applies identically whichever runtime hosts the skill.
+- **Pin skill artifacts and their dependencies; block self-modification and unreviewed transitive loading.** A skill is a supply-chain unit: pin it to an immutable, content-addressed version (not a floating "latest"), and pin its declared package dependencies with a lockfile/hash against an allowlisted registry or private mirror — a vetted skill that pins its own code but floats its npm/pip deps can still exfiltrate via a later malicious dependency release or an install-time script. Block a skill from modifying itself at runtime, and block it from loading further skills that did not pass the same review gate (transitive skill loading is a review-bypass path). No dependency install scripts unless explicitly approved.
+- **The host execution environment is vendor- and deployment-specific — verify it, do not assume.** Portable skill format does not mean portable runtime: hosts differ in whether bundled code may run, whether the network is reachable, whether packages can be installed at runtime, and which sandbox primitives isolate it (one host may allow package install + repo pulls while another has no network and no runtime install at all). A skill that depends on installing a package or reaching the network will silently fail on a host that forbids it. Declare the skill's runtime requirements and confirm them against the specific host(s) you deploy to.
+- **A skill is a versioned behavioral asset — version it like a prompt and gate changes by class.** Register skill versions (see the registry and eval discipline in `model-prompt-evaluation.md`), and scale the gate to the change: a behavior/routing or bundled-code change runs full eval before activation; a description edit (which changes selection/routing) runs a routing/smoke check; a non-semantic metadata edit takes a fast path. Measure skill effectiveness evaluation-first: establish the baseline on representative tasks without the skill, then with it, on a fixed scenario set — a skill that does not move the baseline is not earning its resident context cost.
+
+Build surfaces are multi-vendor: many agent clients and SDKs (Anthropic's and OpenAI's agent stacks among them, plus IDE and CLI agents) support loading the same skill format, but the surrounding product surfaces — workflow/versioning canvas, connector registry, embed toolkit, sandbox model — vary by host and are not uniformly present. Pick per the stack the product is built on, and confirm which surfaces that host actually provides; the loading/routing/trust/eval mechanics above are the vendor-neutral core. Routing of the non-runtime halves: per-skill authoring rules belong to the platform's skill-authoring guidance; skill-routing/false-trigger metrics pipeline belongs to the observability owner; the launch gate for activating a behavior-changing skill follows the same product gate as any model/prompt change.
+
+## Tool Execution
+
+- Validate model-proposed tool calls against schemas before execution.
+- Separate planning from execution for sensitive operations.
+- Require confirmation or policy approval for destructive, externally visible, financial, permission-changing, or irreversible actions.
+- Treat tool output as untrusted data; it may contain prompt injection, stale state, or malformed payloads.
+- Do not execute code, SQL, shell, browser actions, or workflow mutations directly from model output without policy and validation.
+- When the agent executes model-proposed **shell commands or file edits on a real host** (coding/dev/ops agents), the enforcement layer — OS-level command sandbox composition, named filesystem/network profiles, command-policy DSL, loopback-only egress proxy, and the run-then-escalate approval state machine — is specified in `agent-command-sandbox.md`. The rules here (validate, separate plan/execute, confirm destructive, untrusted output) are the requirements; that reference is the implementation.
+- When the agent **edits files** via a model-authored patch/edit tool, the edit *format and apply algorithm* (context-anchored hunks not line numbers, graduated-strictness matching, resolve-all-before-write, honest partial-failure reporting) determine reliability and are specified in `agent-file-edit-protocol.md`; the write's filesystem-safety stays with `agent-command-sandbox.md`.
+
+## MCP (Model Context Protocol) Integration
+
+MCP is a vendor-neutral open standard for connecting an agent to external tools, data, and prompt templates through a client-server protocol (JSON-RPC 2.0; `stdio` for local same-machine servers, Streamable HTTP for remote). A host runs one client per connected server. Three server primitives, distinguished by who controls them:
+
+- **Tools** — model-controlled executable actions (the model decides to call them).
+- **Resources** — application/data-controlled read-only context addressed by URI (supplied by app/user, not model-invoked side effects).
+- **Prompts** — user-controlled templates the user explicitly selects (e.g. slash commands).
+
+Pick the primitive by *control*, not just effect: application-controlled context addressed by URI = **resource**; a model-controlled executable operation (including a read/query the model decides to run) = **tool**; a user-selected template = **prompt**. Do not make everything a tool, but note a model-invoked read is still a tool, not a resource. Boundary vs the other surfaces: a **tool** is the callable; **MCP** is the protocol that exposes tools/data across servers; an **agent skill** is workflow/procedural knowledge (skills encode workflows, MCP handles integrations — see Agent-Skill Systems above).
+
+An MCP server is **untrusted code plus an untrusted instruction surface** (it ships tool schemas the model reads, and may ship runnable code). The generic dependency / sandbox / human-in-loop / supply-chain rules in Tool Execution, Safety And Security, and Agent-Skill Systems apply unchanged. MCP adds these protocol-specific failure modes:
+
+- **Tool poisoning** — malicious instructions hidden in a tool's description, parameter schema, OR return values. Treat the *entire tool schema* as an injection surface (not just `description`), and treat every tool result as untrusted data — not instructions; say so in the system prompt and strip instruction-like / HTML-like payloads from results.
+- **Rug pull / mid-session capability change** — a server changes a tool definition *after* approval, or expands its advertised tool/prompt list mid-session (the `listChanged` surface) after the model already planned around the prior set. Snapshot the server's capabilities per approval epoch (hash each tool definition at approval/discovery, re-verify before each execution, fail-closed on mismatch); a *newly added or changed* tool is not callable until it is re-authorized. Re-authorize only the delta — do not nag on every unchanged hash, or users blanket-approve out of alert fatigue.
+- **Tool shadowing / cross-server escalation** — one server's tool description manipulates the agent's behavior toward another server's tools. Treat each server as an independent untrusted security domain; monitor cross-server data flow (credentials from server A surfacing in calls to server B); enforce isolation through a gateway when running many servers.
+- **Confused deputy** — the server executes with its own (often broad) privileges instead of the requesting user's. Bind session/token to the specific user, validate per request that the token belongs to the current requester, and grant each server least privilege.
+- **Token passthrough / over-scoped credentials** — a server accepting or forwarding tokens not issued for it enables lateral movement. **Reject any inbound token whose audience is not this server** (audience binding). For downstream APIs the server obtains its *own* scoped token (token exchange) — never pass the user's inbound token through to a downstream service. Request narrow scopes; use per-server, short-lived, scoped credentials; never share a token across servers or store it in plaintext.
+- **Sampling / elicitation requests** — MCP lets a server ask the client to run a model completion (`sampling`) or to collect user input (`elicitation`). These are server-originated requests into your model and your user: a hidden injection, privacy, and token-cost surface. Treat them as privileged server→client calls — allowlist which servers may use them, cap token budget per request, log the full transcript, require explicit user consent before disclosing sensitive input, and handle server-supplied sampling prompts as untrusted.
+- **Resource content is read-only but still untrusted** — application-controlled does not mean safe. A resource body can carry indirect prompt injection once inserted into context. Unless the resource is first-party reviewed, treat its text as untrusted data; never let resource content grant permissions or override policy.
+
+Auth + transport: for HTTP-transport servers use **OAuth 2.1 with PKCE** and validate token audience on every inbound request. Pin server identity and metadata and validate the issuer and redirect URIs — a lookalike server or abused dynamic client registration (DCR) can register malicious redirect/auth endpoints; prefer an allowlist of approved servers and gate DCR behind admin policy. Use HTTPS/TLS for remote HTTP and auth endpoints; for a local Streamable HTTP server bind localhost (`127.0.0.1`) rather than all interfaces, and only bind broadly (`0.0.0.0`) behind authenticated, firewalled TLS ingress. For local servers prefer `stdio` (limits reach to the client) and run sandboxed (container/chroot, filesystem + network restricted). Never let web content or untrusted data trigger MCP-server installation; show the full command/parameters at install and at sensitive tool calls; never auto-approve destructive / financial / data-sharing calls. The launch gate for enabling a new MCP server or tool in production follows the same product gate as any high-impact integration (route to `product-rd-workflow`); metric/alert pipeline to the observability owner.
+
+## Safety And Security
+
+- Defend against prompt injection from user input, retrieved documents, web pages, files, and tool results.
+- Keep privileged instructions outside the context regions that untrusted content can influence.
+- Use output schema validation, guardrails, and refusal/fallback paths for invalid or unsafe outputs.
+- Add PII, secrets, policy, and abuse checks where product risk requires them.
+- Rate-limit by user, route, tenant, model, and expensive tool where appropriate.
+- Redact sensitive content in logs, traces, eval datasets, replay records, and prompt-debug artifacts.
+
+## RAG And Agent Evaluation
+
+Evaluate at least:
+
+- retrieval hit rate and source coverage;
+- hallucination or unsupported-claim rate;
+- citation correctness;
+- tool-call precision and unnecessary tool-call rate;
+- loop completion rate and stop reason distribution;
+- prompt-injection resistance cases;
+- latency and token cost with retrieval/tool context included.
+
+**Search-time contamination is a distinct leak for retrieval/tool agents.** Beyond the training-time and inspection contamination governed in `model-prompt-evaluation.md`, an agent that retrieves from a live index or the open web during evaluation can have its retrieval step surface the eval question — or a near-duplicate — alongside its answer, so the score reflects "found the answer key" rather than reasoning. The defense is to make the *answer key* unreachable, not to cripple legitimate corpus grounding: forbid the eval prompts, gold answers, rubrics, and answer-key duplicates from being indexed/retrievable, while still allowing retrieval of the legitimate source-corpus documents when corpus grounding is the task itself (an eval that must retrieve policy X to answer about policy X should keep policy X in the index — only its question/answer-key stays out). For open-web agents, prefer questions whose answers are not directly searchable, or record the contamination caveat explicitly. An eval whose retrieval path can reach its own answer key is not a held-out eval.
+
+## Hybrid Retrieval (Beyond Pure Vector)
+
+When the retrieval target is structured content (exact identifiers, dates, codes, named entities, document templates) rather than free-form text, pure vector retrieval is often insufficient. Production retrieval stacks combine:
+
+- **BM25 / sparse retrieval** (e.g. `rank_bm25`) for exact-match keyword recall;
+- **Vector retrieval** (e.g. FAISS) for semantic match;
+- **Image deduplication** (e.g. `imagededup`) for image-content lookup by perceptual hash;
+- **Language-specific tokenization** (e.g. `jieba` for Chinese, `mecab` for Japanese) so BM25 indexing aligns with how queries are tokenized.
+
+The rules:
+
+- Architecture names the hybrid components and the fusion strategy (RRF, weighted sum, cascade rerank). Pure-vector-only is a default starting point, not the production destination.
+- Each retrieval component reports its own precision/recall on the same eval set; the fusion strategy's quality is the joint metric, not just the vector recall.
+- For perceptual hash / image dedup, define the hash family (pHash, dHash, aHash, wHash) and the similarity threshold; cross-language vs cross-format retrieval needs explicit handling.
+- For mixed-language corpora, indexing tokenization must match query tokenization; missing this is a silent recall regression.
+- Re-ranking is a separate model; it has its own version, eval, and rollback path.
+
+## Multi-Stage ML Pipeline Orchestration
+
+When inference is a multi-stage pipeline (image capture → structure detection → matching → scoring), each stage is its own service or Ray Serve deployment:
+
+- **Inter-stage transport**: choose one of two shapes intentionally. (1) Across service boundaries — separate processes, separate deployments, possibly different teams — use HTTP / gRPC framework RPC; the contract is a generated IDL message (proto / pydantic). (2) Inside a single Ray Serve deployment graph, use Ray Serve deployment handles (`handle.method.remote(...)`) which are a Ray actor call, not HTTP; the contract is the Python method signature plus serializable arguments. Do not conflate the two — mixing them in one place leads to wrong observability, wrong tests, and wrong assumptions about retry / timeout semantics.
+- **Idempotency keys flow with the work item**: every multi-stage call carries a `request_id` and a stable `work_item_id`. Stages check for prior completion against the work_item_id; replays must be safe.
+- **Checkpoint intermediate outputs in object storage** (MinIO / S3 / OSS) with a TTL aligned to the workflow horizon. Stage N+1 can fetch stage N's output from storage rather than re-running stage N.
+- **Per-item partial failure semantics**: when a stage processes a batch (multiple images, multiple ROIs), one failing item must not cause the whole batch to fail unless the contract is all-or-nothing. Default `asyncio.gather()` semantics fail-fast — use `return_exceptions=True` and per-item status mapping for partial-failure pipelines.
+- **Fire-and-forget visualization or notification tasks are a finding**: an `asyncio.create_task()` launched without an awaiter loses errors. Use a real queue (Redis, MQ) for true async work; tasks needing best-effort delivery still need at-least-once retry + dead-letter visibility.
+- **Stage observability**: each stage records its own latency, success/failure, retry count, and partial-result count under the shared `log_id`. The pipeline view is built by joining on `log_id`, so the id must survive every cross-stage hop.
+
+## Composite-Chain Verification Before Acceptance
+
+When a user-visible capability is a composite of several inference stages (retrieval → rerank → tool-call → generation → streaming, or any product-specific chain), changing or accepting one sub-stage requires verifying the real chain first — do not evaluate against an assumed topology.
+
+- **Verify the real chain from source, not memory.** Reconstruct the actual stage graph from product docs, technical design, code, config, runtime logs, or runtime traces before per-stage acceptance. A node you cannot confirm from one of those sources is unconfirmed — mark it as such; never write an unconfirmed node into the acceptance plan as a fixed stage. An evaluation that asserts a chain shape it never verified can pass a stage production does not actually run, or miss a stage that does. For dynamic agent systems where no fully-static graph exists (runtime routing, tool-search selection, model-chosen tool calls, feature-flagged or per-tenant branches), "source" means runtime traces and config snapshots over representative traffic — document the dynamic/probabilistic branches and their trigger conditions rather than inventing a single static graph.
+- **Enumerate the impact surface from registries, not free recall.** For any sub-stage change, discover affected surfaces through the ownership registries — route registry, prompt/model registry, tool registry, index/knowledge-base namespace, telemetry/event-schema search, cost path, and rollback path — and record the known-unknowns explicitly. Free-hand "list everything affected" produces checklist theater that misses transitive consumers; registry-driven discovery finds them. A sub-stage metric gain is not acceptance evidence until the impact surface is enumerated this way and each affected boundary is re-checked.
+- **Layered acceptance, three levels — do not stop at the changed module.** Module level: the changed stage's quality, error classes, latency, cost, fallback. Chain level: cross-stage input/output contract, version propagation, telemetry-id continuity, error handling, rollback availability. Product level: end-to-end user-visible result against the acceptance baseline. A sub-module passing in isolation cannot substitute for chain-level and product-level acceptance. For an opaque third-party/provider stage where internal per-stage metrics are unavailable, substitute contract tests, a pinned provider/model version, and runtime monitoring — do not block the chain on internal metrics you cannot obtain.
+- If the real chain cannot be confirmed, the change is not ready for launch evaluation — close the chain-verification gap before evaluating.
+- Scenario and test-layer selection for these acceptance levels is owned by `testing-strategy`; the product-level acceptance baseline and launch gate are owned by `product-rd-workflow`. This section owns the inference-side chain-verification and impact-surface mechanic.
+
+## IDL And SDK Governance For Inference
+
+The internal inference SDK and its IDL are recurring sources of drift when not governed:
+
+- **One IDL source of truth**: avoid keeping two byte-for-byte copies of the same `api.proto` / `base.proto` in different repos (`protoidl/` and `algo_protoidl/`). Either symlink, submodule, or pick one as canonical and route the other through codegen output.
+- **`api.proto` annotation tier**: keep endpoint-binding annotations (path, method, header bindings, body bindings, query bindings) in a stable annotation file with reserved numeric ranges (e.g. `50201-50310` for HTTP method options) so multiple languages' codegen agrees.
+- **`base.proto` envelope**: shared `Request` / `Response` types with `log_id`, `tags`, code-enum + message envelope. Every inference service derives its specific RPC from this base.
+- **Internal SDK as a versioned package**: ship the inference client SDK as a Python wheel (or Go module), version it, and publish to an internal package index. Business services pin the version; the SDK upgrade is a managed change, not an ad hoc `pip install -e`.
+- **SDK boundary**: the SDK owns service discovery, transport, retry, tracing, and protobuf (de)serialization. Business code calls typed methods; raw HTTP / raw JSON is a finding.
+
+## Durable agent memory as control plane
+
+Treat durable agent memory as a context control plane, not a convenience cache. Classify each memory store by principal scope, sharing scope, workspace/project scope, privacy state, persistence lifetime, and whether it can be injected into model-visible context. A user instruction to ignore, disable, or not use memory, or a privacy/privacy-opt-out state that forbids memory use, must suppress recall, citation, comparison, behavioral influence, new memory writes, background extraction, upload of affected-turn content, and cached model-visible memory snapshots for that turn. Prompt/context caches must be partitioned or invalidated by principal, memory scope, memory snapshot/version, deletion state, privacy state, and ignore flag. Remembered facts that name current files, functions, flags, permissions, or policies must be verified against current state before acting.
+
+## Query-time memory recall
+
+Query-time memory recall needs its own evidence boundary before injection. Load memory entrypoints and manifests under bounded line, byte, file-count, and per-file read-range caps; label truncation and incomplete scans so they cannot support "all memories" or absence claims. Build recall manifests from low-risk headers such as type, description, modified time, and stable file key before reading bodies, skip unreadable or malformed entries without treating them as empty truth, and sort/cap deterministically. Selector calls must bind to the current query digest, principal/session/workspace, memory store identity, memory snapshot generation, already-surfaced set, recent-tool context, privacy/ignore state, and abort signal; validate structured selector output against existing file keys only, and degrade to no recalled memory on selector failure, cancellation, malformed output, or tuple drift. Recalled memories need freshness labels, low-precedence untrusted-data wrapping, duplicate-surface suppression, and explicit stale-claim verification before action. Diagnostics may expose bounded counts, age buckets, truncation and degraded-state categories, but not memory bodies, raw queries, filenames, local paths, timestamps tied to private activity, selector prompts or responses, credentials, or free-form errors.
+
+## Private, shared, and session-only memory writes
+
+Separate private, shared, and session-only memory writes. Secrets, credentials, raw tokens, and credential echoes are forbidden in every memory store. Private or session memory that carries personal data needs an explicit minimization and consent policy; shared memory requires stricter gates for raw PII, saved content that is merely derivable from the repository, and any broad team rule unless it is truly project-wide rather than a personal preference. Background memory extractors must have a constrained tool set, write only inside the memory store, skip if the main agent already wrote memory for the turn, bound turns/tokens, coalesce overlapping runs, avoid transcript writes, and drain or cancel predictably on shutdown. Scheduled or accumulated-session memory consolidation is a separate background state mutation: gate it by current principal/session/workspace, mode support, privacy/settings/policy, memory-store availability, time and activity thresholds, scan freshness, and current-session exclusion; serialize it with a reclaimable lock or equivalent lease, roll back the last-run marker on fork/start failure or user kill, constrain the fork to read-only exploration plus memory-store writes, isolate its transcript from the main conversation, surface only bounded completion evidence when memory changed, and discard stale progress after session/workspace/memory/policy/task drift.
+
+## Recalled or synced memory as untrusted context
+
+Treat recalled or synced memory as untrusted context, not instructions. Inject memory as quoted or clearly labeled data with lower precedence than system, developer, current-user, repository, and policy instructions. Shared memory entries need writer/principal provenance, intended audience, read/write authorization, and review or verification before a policy-like, permission-like, or team-rule memory can guide action. Poisoned or contradictory memory must be ignored, corrected, or removed rather than reconciled silently.
+
+## Memory filesystem and sync boundaries
+
+Memory filesystem and sync boundaries must fail closed. Validate relative keys and absolute write paths for traversal, null bytes, encoded traversal, Unicode-normalized traversal, backslash separators, prefix attacks, symlink escapes, dangling symlinks, hardlinks where relevant, time-of-check/time-of-use swaps, and unverifiable containment before reading from or writing to a shared memory store. Sync must be scoped to the correct principal/workspace/repository identity, pull before injecting remote shared memory, validate remote payload shape and entry size, scan local content before upload, log only secret categories rather than values, raw hashes, stable user identifiers, entry bodies, or sensitive paths, and never let a stale or failed sync silently widen who can see a memory.
+
+## Shared-memory conflict, deletion, and capacity
+
+Shared-memory conflict, deletion, and capacity semantics must be explicit. Define whether pull, push, or local edit wins per key; use content hashes or versions to compute deltas; use optimistic locking or equivalent conflict detection; retry conflicts with refreshed metadata; split large uploads into resumable bounded batches; handle partial batch success without re-uploading committed entries; distinguish delete, unshare, and local-hide with tombstones or versioned deletes when remote resurrection would be unsafe; and suppress retry loops for permanent failures until a user-visible recovery action or session restart.
+
+## Autonomous curation of agent-generated artifacts
+
+When a product lets the agent (or a background job) autonomously prune, retire, or "curate" its own generated artifacts — agent-created skills, saved memories, derived notes/files — the maintenance loop must be non-destructive, provenance-scoped, and override-respecting. (Where the artifact store is the memory store, the background-extractor/consolidation write rules above still apply to what such a loop WRITES; the rules here additionally govern what any autonomous maintenance pass may DESTROY, across skill/note/file artifacts as well as memory.)
+
+- **Security/privacy/legal deletion overrides this entire section — it is NOT curation-archive.** PII, secrets, poisoned or abuse content, revoked policy, and any right-to-be-forgotten or policy-mandated erasure must tombstone/purge per the deletion-semantics rule above and must NOT be reachable by ordinary archive rollback; curation-archive is only a rollback mechanism for *low-risk stale generated* artifacts, never a substitute for deletion. A restore/rollback path must refuse to resurrect anything purged for a security/privacy/legal reason.
+- **Never hard-delete a low-risk stale artifact — archive to a restorable location, but a bounded one.** The maximum destructive action a routine maintenance pass may take is move-to-archive, recoverable on demand (a one-way delete of generated knowledge is data loss the user cannot undo). The archive is not a forever-sink: give it retention TTL / capacity budget / GC, the same access-control + encryption + secret/PII redaction-or-scan as the live store, and an explicit policy-authorized purge path — "non-destructive" must not become "keep every sensitive generated memory forever in a less-reviewed folder."
+- **Scope to server-attested, immutable machine provenance.** Touch only artifacts whose agent-created provenance is minted by the store from the authenticated writer identity and immutable after creation (except audited admin migration) — never a marker living in model-editable artifact body/metadata, or the agent can mis-tag human artifacts as agent-created (to curate them) or its own as human (to evade curation). Human-authored, operator-curated, or bundled/shipped artifacts are off-limits unless an opt-in policy re-includes them **scoped by artifact class / principal / workspace / source with per-item exclusion and audit** (not a blanket "all bundled opted in"), and that opt-in needs a suppression list so a re-seed/reinstall does not resurrect what was intentionally archived.
+- **Pinning is a user/admin-authorized, audited, revocable override — subordinate to security/privacy purge.** Pinned items skip every routine auto-transition and any LLM-driven review/consolidation pass, and the agent may still *improve* a pinned item (patch/edit); but `pinned` must not be settable by the model or a poisoned import (or a malicious/unsafe artifact becomes permanently un-cleanable), and a security/privacy tombstone overrides a pin. Explicit deletion of a pinned item requires unpin or elevated confirmation — not absolute refusal, which would make a poisoned pinned item undeletable.
+- **Drive transitions off *meaningful* usage telemetry, under a concurrency check — not a model's guess.** Use a deterministic state machine (active → stale → archived) keyed on use/activity counts and last-activity time with configurable idle windows, but count only genuine user/task use — background recall, preview, indexing, tests, or self-references must not let an artifact keep itself "active." At transition time re-check current state under a lock or compare-and-swap on a version, so a concurrent edit/use is not archived out from under a live session. An LLM review pass may *recommend* within these bounds but is never the authority for destruction; pinned/human-authored items are outside its reach.
+- **Snapshot before a maintenance run, with the archive's obligations.** Keep a pre-run backup and a restore/rollback verb so a bad transition is recoverable — but the snapshot carries the same retention, encryption, redaction, tombstone-propagation, and purge semantics as the archive, or the rollback copy becomes its own leak/resurrection vector. Never let an autonomous pass be the only copy's last writer.