@ssheleg/agent-stack 0.23.1 → 0.24.0

package/CHANGELOG.md

@@ -1,3 +1,45 @@
+## 0.24.0 — the agent stack closes its audit findings
+
+Sherlock external-v3 (24 findings), each carrying its own executable regression
+under `test/audit_regressions/`.
+
+CI now MEASURES the token budget with a real tokenizer instead of estimating it
+from character count — the pinned auditor had been issuing a token verdict from a
+chars/3.9 estimate, which is the defect that script's own doctrine names.
+
+## v0.23.2 — a path that resolves only from the neighbour's directory, and the description with no room left
+
+Family audit 2026-09-06 (wave AUDIT-WAVE-0906) brought three findings for this member.
+Two changed files; the third changed a board instead.
+
+**Two references pointed at `references/kv-cache.md` from directories where it does not
+exist.** `agent-evals/references/otel-genai.md:137` and
+`agent-interop/references/mcp-scale.md:92` both named the bare path; the file lives only
+in sibling `agent-orchestrator`. The prose around each named the sibling, so a reader
+could recover the target — but the path as written resolves to nothing from either
+skill's own root, and a bare `references/x.md` means *this skill's file* by the
+validator's own rule (`test/validate.py:263-267`). The check never saw them because it
+reads SKILL.md alone; these sat in reference files nothing scans. Both now read
+`../agent-orchestrator/references/kv-cache.md`, which resolves from each skill's root —
+and the leading `../` keeps the validator's lookbehind from reading it as a claim on a
+local file.
+
+**`agent-interop`'s description sat at exactly 970/970 — the working limit with zero
+headroom** — so the next trigger, the next boundary clause, any edit at all would have
+fought the gate before doing its work. Eleven characters of connective prose trimmed
+("another agent" → "an agent"; two list-internal "and"s → commas): now **959/970**, with
+every quoted trigger phrase untouched — **14 before, 14 after**, English and Russian,
+counted by re-folding the YAML scalar rather than by eyeballing the diff.
+
+**The audit also asked for a debulk of `agent-orchestrator` and `agent-evals`, and that
+was declined rather than done blind.** Re-measured at this commit: **4655/4750** (98.0%)
+and **4631/4750** (97.5%), both `0 GAP`. The family precedent (B-141 class) is that
+manufacturing headroom with no pending edit is negative-value work: room bought today is
+spent by nobody, and a trim chosen without the edit it serves cuts on the wrong line.
+Filed as board row **B-135** — the debulk belongs to the release that next edits these
+bodies, beside B-129's standing record that the durable remedy for `agent-orchestrator`
+is a split, not a trim.
+
 ## v0.23.1 — the registry card stopped being ten releases stale
 
 `SKILL-CARD.md` carries the fields Anthropic's Skills-for-enterprise guidance asks every

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/plant_guard_test.py && node test/installer_test.js"
+    "test": "python3 test/validate.py && python3 test/plant_guard_test.py && node test/installer_test.js && npm run test:audit",
+    "test:audit": "for t in test/audit_regressions/*.py; do python3 \"$t\" || exit 1; done"
   },
-  "description": "Production patterns for AI agent orchestrators — tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay — plus the wallet side of reselling LLM access. This package is the installer CLI.",
+  "description": "Production patterns for AI agent orchestrators \u2014 tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay \u2014 plus the wallet side of reselling LLM access. This package is the installer CLI.",
   "bin": {
     "agent-stack": "bin/agent-stack.js"
   },

package/plugins/agent-stack/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "agent-stack",
   "displayName": "Agent Stack",
   "description": "Four skills: agent-orchestrator — tool-calling loops, pipelines with checkpoints, provider routing with fallback, memory architecture, plus the wallet side of reselling LLM access; agent-evals — run/trace/thread evals, LLM judges, and fixtures grown from production; agent-interop — MCP servers and clients, A2A agent cards, the MCP Registry, and gateways; agent-harness — system prompts, tool shaping, workflow-vs-agent, and auditing an agent system.",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/agent-stack/skills/agent-evals/SKILL.md

@@ -76,7 +76,7 @@ Assert on three axes at once, with three different mechanisms:
 
 | Axis | Assert | With |
 |---|---|---|
-| Trajectory | what the run **must not** do, and what it must have touched — never the order | set/subset matchers, forbidden-call lists |
+| Trajectory | what the run **must not** do, what it must have touched, and the mandatory **happens-before** edges — never the full exact order | set/subset matchers, forbidden-call lists, partial-order (a before b) |
 | Final response | quality, tone, policy compliance | rubric or judge |
 | **State change** | the memory row exists, the file was written, the artifact is there | direct inspection of the side effect |
 
@@ -152,19 +152,26 @@ assertions, tool-call correctness — all deterministic, all faster and cheaper
 call. Send to a judge only what cannot be decided by code.
 
 **Read the trajectory; do not match it.** An agent that reaches a correct answer through
-three wrong tool calls is a latent outage — and asserting the *sequence* to catch that is
-measurably the wrong instrument. Anthropic names the instinct and rejects its strict form:
-exact tool-order assertions are *"too rigid and results in overly brittle tests, as agents
-regularly find valid approaches that eval designers didn't anticipate"*, and the worked
+three wrong tool calls is a latent outage — and asserting the *exact sequence* to catch
+that is measurably the wrong instrument. Anthropic rejects its strict form: exact
+tool-order assertions are *"too rigid and results in overly brittle tests, as agents
+regularly find valid approaches that eval designers didn't anticipate"* — the worked
 case is an agent that solved a τ²-bench booking task through a policy loophole, failing
 the eval as written while serving the user better. Grade **what was produced and what
-changed**, and let the path vary.
+changed**, and let the incidental path vary.
 
-The opposite edge is measured too, so this is not "grade the final answer": a grader blind
-to the trajectory misses **44% of safety violations and 13% of robustness failures**,
+The opposite edge is measured too: a grader blind to the trajectory misses **44% of safety violations and 13% of robustness failures**,
 because a policy breach on the way to a correct result leaves no trace in the outcome. Use
 the trajectory for the claims the outcome cannot carry — a forbidden call, a missing
-confirmation, a secret read — as a **set and a forbidden list**, never as an order.
+confirmation, a secret read — as a **set and a forbidden list**.
+
+What is forbidden is the redundant **exact global sequence**, not order as such.
+A few **happens-before** edges are semantically mandatory: authorization
+precedes its effect, a fresh read precedes the write depending on it, a
+transaction commits before what publishes it. Assert those as a **partial
+order** (a before b), never a total one — reordering two independent reads must
+pass, reordering confirm/charge or acquire/write must fail — and keep the
+negative example (a confirm-after-charge trace) beside the rubric.
 
 **Calibrate the judge before trusting it.** Collect human labels on the same traces,
 measure agreement, iterate the judge prompt until agreement is high — *then* let it score
@@ -253,10 +260,16 @@ with no production in it is imagination.** The requirement itself gets its id an
 definition of done from `task-pipeline`'s REQ spine — what this pack owns is the
 observable's *form*, not the register it hangs on.
 
-**The first release has no production, so its offline gate is observables only** (§3). That
-is not the corpus rule suspended for a special case: the corpus is empty because nothing has
-run yet, and it fills from the first real traces. Inventing *inputs* to fill it sooner would
-still be imagination.
+**The first release has no production — so it runs against a SEED corpus, and
+observable-only is not release-ready.** A criterion with no input proves
+no capability, so a greenfield feature seeds a curated/synthetic/manual corpus with at least a **happy**, an **adversarial** and a
+**failure/retry** trial. Each seed input carries its **provenance**
+(`curated`/`synthetic`/`manual`) and is SUPPLEMENTED by production traces,
+never declared full coverage. The release gate requires EXECUTED trials;
+observables with nothing run against them are `specification-ready`, not
+`release-ready`. A corrupted fixture, input or runner is a `TEST_ERROR`,
+never a behaviour pass/fail; cases are isolated, so B's result never depends
+on whether A ran.
 
 **Never author the suite up front** — the *corpus*, that is: the inputs. Every production
 failure and every thumbs-down becomes a fixture:
@@ -300,7 +313,11 @@ None of the above runs without these, and they are the part people skip:
   of `human` | `llm_judge` | `code_check`. A score with no source cannot be calibrated,
   audited, or trusted differently from its neighbours.
 - **Whole prompts, not just messages** — instructions, tool schemas and context as they
-  were sent. A fixture cannot be replayed from a summary.
+  were sent. A fixture cannot be replayed from a summary. And a CANDIDATE's
+  version, output and score are their own records beside the old trace — a
+  regrade of the stored output is labelled regrade, never "the candidate
+  passed": only executing the candidate against the frozen fixture (a real,
+  stochastic call, costed in the receipt) can say the decision changed.
 - **State snapshots at turn boundaries**, so a thread test can assert what carried.
 
 ---

package/plugins/agent-stack/skills/agent-evals/references/otel-genai.md

@@ -10,7 +10,7 @@ three places it will not carry what this skill requires.
 ## Contents
 
 - [Read this before encoding any of it](#read-this-before-encoding-any-of-it)
-- [Span names are formulas, and the operation list is closed](#span-names-are-formulas-and-the-operation-list-is-closed)
+- [Span names are formulas, and the operation set is well-known but extensible](#span-names-are-formulas-and-the-operation-set-is-well-known-but-extensible)
 - [The evaluation event, missing the field §7 requires](#the-evaluation-event-missing-the-field-7-requires)
 - [Content: three tiers, and a hook that runs when nothing else does](#content-three-tiers-and-a-hook-that-runs-when-nothing-else-does)
 - [Tokens are eleven numbers and money is none of them](#tokens-are-eleven-numbers-and-money-is-none-of-them)
@@ -31,11 +31,14 @@ inference span the only attributes marked `Stable` are the ones borrowed from co
 attribute is `Development`.**
 
 So: adopt it, because a moving standard beats a private vocabulary that will never be read
-by anyone else's tooling — and **pin the version you adopted and expect to migrate**. Treat
+by anyone else's tooling — and **pin the version you adopted and expect to migrate**. When
+you encode any field from this file, record the **semconv schema revision and the commit SHA
+you read it at, plus the observation date** beside your instrumentation — a `gen_ai.*` field
+quoted with no revision is a field with no expiry, and this whole spec is `Development`. Treat
 any code that branches on a `gen_ai.*` attribute as code with an expiry date, and re-read
 the spec before quoting a field name from this file.
 
-## Span names are formulas, and the operation list is closed
+## Span names are formulas, and the operation set is well-known but extensible
 
 Span names are computed, not free text:
 
@@ -48,10 +51,15 @@ Span names are computed, not free text:
 | agent creation | `create_agent {gen_ai.agent.name}` | — |
 | MCP | `{mcp.method.name} {target}`, target being the tool or prompt name | — |
 
-`gen_ai.operation.name` is a **closed 17-value enum** — `chat`, `text_completion`,
-`generate_content`, `embeddings`, `retrieval`, `fetch_response`, `execute_tool`,
-`create_agent`, `invoke_agent`, `plan` and the rest. A value outside it is not an extension,
-it is a name a backend cannot group by.
+`gen_ai.operation.name` is a **well-known SET, not a closed enum** — the semconv
+lists `chat`, `text_completion`, `generate_content`, `embeddings`, `retrieval`,
+`fetch_response`, `execute_tool`, `create_agent`, `invoke_agent`, `plan` and the
+rest, and a well-known value is preferred WHERE ONE FITS. But a provider
+operation with no matching well-known value is allowed to carry a custom value:
+it is not silently dropped, and an unknown value is stored RAW so a later
+schema revision can recognise it. A backend groups the well-known values and
+keeps the raw ones addressable — losing them is the failure, not carrying
+them.
 
 **Only two attributes are Required on an inference span.** Everything else that matters —
 the model that actually answered, token counts, finish reasons — is Recommended or
@@ -127,17 +135,43 @@ leaks through the one field it never inspected. Decide naming and redaction toge
 standardises tokens and never money, so cost is always a join against a price table living
 outside the trace — and that join is where the number goes wrong.
 
-Because usage is not one number. It is eleven: `gen_ai.usage.input_tokens`, `output_tokens`,
-`reasoning.output_tokens`, `cache_read.input_tokens`, `cache_write.input_tokens`, and
-per-modality `text.*` / `image.*` / `audio.*` splits including
-`image.cache_read.input_tokens`.
-
-**A cost computed from `input_tokens + output_tokens` alone is wrong in both directions.** It
-bills cache reads at full price — they are the cheap ones — and it misses reasoning tokens and
-cache writes entirely. `references/kv-cache.md` in `agent-orchestrator` is the other half of
+Because usage is not one number, and the counters are of TWO kinds — TOTALS and
+DISJOINT BILLING BUCKETS, and confusing them double-counts. `input_tokens` and
+`output_tokens` are the totals; `reasoning.output_tokens` is a SUBSET of
+`output_tokens` (not an addition to it), and `cache_read.input_tokens` /
+`cache_write.input_tokens` are subsets of `input_tokens`. The per-modality
+`text.*` / `image.*` / `audio.*` splits (including `image.cache_read.input_tokens`)
+partition those same totals by modality — they are not extra tokens either.
+
+**A cost computed from `input_tokens + output_tokens` alone is wrong** because it
+prices the cached portion of the input at the full input rate — cache reads are
+the cheap ones. The fix is NOT to add reasoning or modality counters back onto
+the totals (that bills them twice): it is to **SUBTRACT the cached portion from
+the total and apply the provider's cache-read (and cache-write) rate to it**,
+pricing the remaining full-rate input and the output at their own rates. `../agent-orchestrator/references/kv-cache.md` is the other half of
 this: the cache read is the case worth getting right, because at scale it is most of the
 traffic.
 
+**The worked receipt — a disjoint partition that reconciles.** Say `input_tokens
+= 1000` with `cache_read.input_tokens = 800`, and `output_tokens = 200` with
+`reasoning.output_tokens = 120`, at rates `$3 / $0.30 / $15` per 1k for
+full-input / cache-read / output:
+
+| Bucket | Tokens | Rate /1k | Cost |
+|---|---|---|---|
+| input, full-rate = `input − cache_read` | 200 | $3.00 | $0.60 |
+| `cache_read` (a subset of input) | 800 | $0.30 | $0.24 |
+| output (reasoning is a SUBSET, not added) | 200 | $15.00 | $3.00 |
+| **total** | | | **$3.84** |
+
+Two invariants a receipt MUST satisfy, and an independent example checks: the
+priced token buckets **sum back to the totals** — 200 + 800 = 1000 input, and
+output is 200 (reasoning's 120 is inside it, never a fourth line) — so no token
+is charged twice; and the naive `input + output` at the input/output rates
+($3.00 + $3.00 = $6.00) OVER-charges by pricing the 800 cached tokens at $3
+instead of $0.30. The receipt reconciles with the totals; the naive number does
+not.
+
 And `gen_ai.client.token.usage` carries a hard **MUST NOT report** when the counts are not
 obtainable. A zero is a claim; absence is the honest value. That is the same rule
 `agent-harness/references/audit.md` states for cost attribution — *missing attribution beats
@@ -171,7 +205,14 @@ which:
 |---|---|---|---|
 | **Durable execution** (Temporal) | nothing — recorded results are replayed and only the failed step retries | free, deterministic | can I resume without redoing 20 web searches |
 | **Trace playground** (Phoenix) | the model call, against the live provider, with an edited prompt | a real call | would a different prompt have done better |
-| **Fixture replay** (this skill, §2 single-step) | an assertion over a stored run | free | did the decision at this point change |
-
-They are not interchangeable, and a runbook that says *"replay the run"* has not said what it
-means. Name the sense.
+| **Regrade of a stored output** (this skill, §2 single-step) | nothing — a new assertion over the OLD output | free, deterministic | does the OLD output satisfy the changed rubric — **explicitly NOT a check of the candidate** |
+| **Candidate execution over a frozen fixture** | the CANDIDATE (new prompt / model / tool schema) against frozen inputs | a real model call, stochastic — say so in the receipt | did the candidate's decision change |
+
+They are not interchangeable, and a runbook that says *"replay the run"* has not said what
+it means. Name the sense. The one this table exists to un-blur: **an old output does not
+change when the candidate changes** — a regrade re-marks yesterday's homework under a new
+rubric, and calling it "did the decision change" claims a candidate check that never ran.
+The test with teeth is the fourth row: mutate the candidate to a knowingly wrong tool, and
+the gate's result MUST change; a gate a candidate mutation cannot move is a regrade wearing
+the wrong label. The candidate's version, its output and its score are stored as their own
+records, never overwriting the old trace they are compared against.

package/plugins/agent-stack/skills/agent-evals/references/statistics.md

@@ -38,9 +38,32 @@ The 95% band is roughly `±1.96 · SE`. Computed, not quoted:
 
 ```python
 import math
-def band(p, n): return 1.96 * math.sqrt(p * (1 - p) / n) * 100   # percentage points
+
+def band(p, n):
+    """Wald approximation, percentage points. Valid only for moderate n with p
+    away from the boundary (rule of thumb: n*p >= 10 and n*(1-p) >= 10). At
+    p=0 or p=1 it returns ZERO width — which is exactly wrong: a run that has
+    never failed is not a run with no uncertainty."""
+    return 1.96 * math.sqrt(p * (1 - p) / n) * 100
+
+def wilson(p, n, z=1.96):
+    """Wilson score interval — the DEFAULT for a proportion. Nonzero width at
+    the boundary, honest at small n; use exact (Clopper–Pearson) when n is
+    tiny and the decision is expensive. n == 0 is total uncertainty (0, 1),
+    never a zero-width claim."""
+    if n == 0:
+        return (0.0, 1.0)
+    denom = 1 + z * z / n
+    centre = (p + z * z / (2 * n)) / denom
+    half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / denom
+    return (max(0.0, centre - half), min(1.0, centre + half))
 ```
 
+The table above is Wald and inherits its limits; **a zero or tiny sample is not
+a universal bound.** `wilson(0.0, 5)` spans up to ≈43% — five clean runs still
+leave nearly half the range open — where Wald would print ±0.0 and read as
+certainty.
+
 **So "the new one gets 73% where the old one got 70%, on a hundred cases" is not a
 result.** It is a number inside its own noise. The error shrinks as `1/√n`, which is the
 whole practical consequence: **the fix for a 2–3 pp expected gain is more tasks, not more
@@ -49,9 +72,12 @@ argument.** Quadrupling the set halves the band.
 A corollary worth stating because leaderboards invite the opposite: **differences below
 about 3 pp deserve scepticism until both configurations are documented and matched.**
 
-> The formula assumes independent cases. A benchmark whose tasks share a fixture, an
-> environment or a generator violates that, and the true band is wider than this. Wider,
-> never narrower — so the table is a floor on your uncertainty, not a ceiling.
+> The formula assumes independent (iid) cases. A benchmark whose tasks share a
+> fixture, an environment or a generator violates that, and under the usual
+> assumption — POSITIVE intra-cluster correlation, which is what shared
+> fixtures produce — the true band is wider than this, so treat the table as a
+> floor. That is an assumption, not a theorem: engineered negative dependence
+> can narrow a band, it just never happens by accident in a shared fixture.
 
 ## pass@k and pass^k are different questions
 
@@ -78,6 +104,13 @@ If a failed attempt leaves a charge, a message or a mutated row behind, `pass@k`
 available to you as a metric — you cannot pick the best of five refunds. Sample in a
 sandbox or a rollback-capable environment, and count **every** failure.
 
+**Both are computed over TASK-LEVEL trials.** k repeated trials of one task
+estimate that task's own p_i; the benchmark number is the mean over TASKS of
+the per-task pass@k (or pass^k). Pooling repeated trials of one task into the
+denominator as if each were a new task inflates n with copies of the same
+difficulty — the trials are not independent tasks, and counting them as tasks
+is how a small suite pretends to be a large one.
+
 **A report that gives k without saying which k it means is unreadable.** *k independent
 samples of one task* and *k consecutive tasks on one live pipeline* are different claims.
 
@@ -103,9 +136,12 @@ Two consequences, and they cut in opposite directions:
 
 - **You cannot compute `pass^k` from `pass^1`.** Exponentiating a headline rate gives a
   number far below the truth. Measure `pass^k` directly, at the k you care about.
-- **Anthropic's `0.75³ ≈ 42%` is a worst case, not a forecast.** It is the right shape for
-  an argument — *consistency is a much harder bar* — and the wrong number to put in a
-  release gate.
+- **Anthropic's `0.75³ ≈ 42%` is the INDEPENDENCE BASELINE, not a bound.** Real
+  curves usually sit above it because successes cluster by task (positive
+  dependence), but that is an empirical pattern, not a guarantee — engineered
+  negative dependence can fall below it. The right shape for an argument —
+  *consistency is a much harder bar* — and the wrong number to put in a release
+  gate either way.
 
 The other half of independence is the harness, not the task: Anthropic requires each trial
 start from a clean environment, because *"unnecessary shared state between runs (leftover
@@ -115,8 +151,13 @@ metric mean anything.
 
 ## Pairing: same tasks, same seeds, per-task deltas
 
-**Never subtract two independent averages.** Run both configurations over the *same* task
-list with the *same* fixed seeds, record a per-task win/loss/tie, and test the deltas.
+**Prefer pairing — and never subtract two averages WITHOUT an interval.** Run
+both configurations over the *same* task list with the *same* fixed seeds,
+record a per-task win/loss/tie, and test the deltas: pairing cancels the
+per-task difficulty variance and needs far fewer runs. An UNPAIRED comparison
+of two independent averages is still legitimate when pairing is impossible —
+it just pays for it with the wider two-sample band, and the sin is quoting the
+subtraction bare, as if the band were zero.
 
 ```
 for task in tasks:            # identical list
@@ -138,6 +179,34 @@ for task in tasks:            # identical list
 **Ship on three conditions, not one:** the difference exceeds the noise band, it survives
 the paired analysis, and it reproduces on a rerun.
 
+## The design decides the method — and the receipt names both
+
+Paired, clustered and unpaired are three DIFFERENT corpus structures, and a
+test method borrowed from the wrong one produces confident nonsense. The
+result's receipt names the design AND the method, and they must match:
+
+| Corpus structure | Matching method | Mismatch that looks fine and is not |
+|---|---|---|
+| **paired** — same tasks, same seeds, per-task deltas | McNemar (binary) or a paired bootstrap over the DELTAS | running McNemar on two independent runs pairs rows that share nothing |
+| **clustered** — k dependent repeats per task | a cluster bootstrap that resamples TASKS (each task carries its repeats along) | bootstrapping TRIALS treats dependent repeats as iid and shrinks the band by ~√k for free |
+| **unpaired** — two independent samples | the two-sample (Welch) SE, wider band | quoting the paired-sized band for an unpaired design |
+
+**Dependent repeats are never claimed iid**, and a small sample never buys
+imaginary certainty — the Wilson bounds above are the floor either way.
+
+## Splits are spent once — case ids and groupings are FIXED
+
+The corpus's case IDs and their groupings (which task belongs to which cluster,
+which split) are frozen before any run and never regrouped to taste.
+
+- **Validation** MAY be used for tuning — that is what it is for.
+- **The final holdout is spent ONCE**, on the version already chosen. It is
+  never used to pick between versions; a holdout consulted per candidate is a
+  second validation set wearing a blindfold.
+- **A reused validation example can never be relabelled an "unseen final
+  test"** — the receipt says which split every number came from, and "unseen"
+  is a property of the RUN HISTORY, not of the label somebody wrote today.
+
 ## The harness is a variable, so pin it
 
 The container spec is part of the measurement. On Terminal-Bench 2.0 the gap between the

package/plugins/agent-stack/skills/agent-harness/SKILL.md

@@ -33,13 +33,16 @@ forwards and backwards, which is why they live together here.
 
 ---
 
-## Rule zero — most agent bugs are prompt bugs wearing a stack trace
+## Rule zero — check the prompt first (a diagnostic heuristic, with exceptions)
 
-The instinct when an agent misbehaves is to change the code. The measured reality, in every
-source this skill was built from, is that the largest behavioural changes come from the
-text: **"the biggest performance improvements often come from clearly explaining tool usage
-in the system prompt"**, and **"even small refinements to tool descriptions can yield
-dramatic improvements."**
+The instinct when an agent misbehaves is to change the code. The sources this skill was
+built from pull the other way: **"the biggest performance improvements often come from
+clearly explaining tool usage in the system prompt"**, and **"even small refinements to
+tool descriptions can yield dramatic improvements."** That is vendor guidance about where
+leverage OFTEN lives, not a measured share of defects — so it orders the DIAGNOSIS, never
+the verdict. **The exceptions are the findings a prompt cannot touch:** a deterministic
+race, a hardcoded secret, a timeout wired to the wrong operation — source-level invariant
+violations are code bugs, provable by reading, and no rewording treats them.
 
 Before adding a retry, a router, or a sub-agent, check in this order:
 
@@ -97,11 +100,15 @@ A **static** graph has every node and edge decided up front; a **dynamic** one g
 nodes read their own output and decide what comes next.
 
 **Static first, always** — go dynamic only after the static version hits a wall you can
-name, because dynamic is more powerful and much harder to control. And one row of that
-decision is hard rather than preferential: **a run that has to be auditable is static.**
-A dynamic graph's executed shape is not the shape anybody drew, so *"here is the design"*
-and *"here is what happened"* stop being the same document, and every claim about the run
-becomes unfalsifiable from outside.
+name, because dynamic is more powerful and much harder to control. But **auditability is
+NOT the same axis as static structure** — that conflates the plan drawn beforehand with
+the execution graph saved afterward. A run is auditable when its EXECUTION RECORD is
+complete: every node, edge and event that actually ran, the policy version in force, and
+deterministic bounds (budget / depth / node caps) with provenance. A static graph is the
+PREFERENCE because its executed shape usually matches the drawn one; a dynamic graph is
+auditable too when it keeps that record within those caps. What is never evidence is a
+design DIAGRAM on its own — *"here is what I planned"* is not *"here is what happened"*,
+in either mode.
 
 The six-row table, the rest of the model — the fake-edge test, the diamond, the checker
 node before a convergence — and what a host actually executes when it fans out are one
@@ -145,8 +152,12 @@ The long version is `references/audit.md`. The shape:
    Monday. This is the same rule `agent-evals` applies to eval rubrics and
    `seo-aeo-audit` to sites.
 
-**The finding that ends most audits early:** the system has no evals. Everything downstream
-is then unfalsifiable — including this audit. Say so first, and make it the first item.
+**The finding most audits surface first:** the system has no evals. That is a finding
+about UNKNOWN RELIABILITY — every *behavioural estimate* downstream is unfalsifiable,
+including this audit's. It does NOT dissolve what is provable at the source: a
+demonstrable double charge, a hardcoded secret, a deterministic race keep their own
+findings and their own priority, set by the concrete harm — a general "no evals" never
+masks a specific proven harm.
 
 ---
 
@@ -189,7 +200,7 @@ prompt.
 ## Checklist — a harness worth shipping
 
 - [ ] Workflow-versus-agent decided deliberately, and the simpler option was actually tried
-- [ ] Static-versus-dynamic decided too, and a run that must be auditable is static
+- [ ] Static-versus-dynamic decided too — static preferred for predictability; a run that must be auditable keeps a complete execution record (not merely a static shape)
 - [ ] System prompt at the **right altitude** — heuristics, not hardcoded branches, not vague hope
 - [ ] Every status, category and enum the agent must produce is **enumerated in the prompt**
 - [ ] Today's date, and any other volatile context, injected rather than assumed

package/plugins/agent-stack/skills/agent-harness/references/audit.md

@@ -88,10 +88,21 @@ Walk them in order. Later tracks assume earlier ones.
 - Is tool output treated as **untrusted input**?
 - Can an audit row prove a control was applied — does it carry the **policy version**?
 - Is there a deterministic limit anywhere consequential, or only probabilistic content checks?
+- **The lethal trifecta is a specific EXFILTRATION pattern, not a full threat
+  model.** Private data + untrusted content + external comms in one session is
+  the exfiltration triangle — but a session MISSING one leg is not thereby
+  "safe". Audit **capabilities and effects SEPARATELY**: untrusted content +
+  a write capability, with no private data at all, is an unrelated destructive
+  effect (injected content corrupts state or takes a damaging action) and is
+  its OWN finding. "Only two of the three, therefore a PASS" is the mistake —
+  removing a trifecta leg removes THAT exfiltration path, not every risk.
 
 ### 7 — Evidence
 
-- **Are there evals?** If not, this is finding number one and everything else is unfalsifiable.
+- **Are there evals?** If not, that is finding number one — about unknown reliability: every
+  *behavioural estimate* in this audit is then unfalsifiable. Findings proven at the source
+  (an invariant read off the code, a deterministic reproduction) stand on their own and are
+  prioritized by their concrete harm, not discounted under the general finding.
 - Do they judge the **trajectory**, or only the final answer?
 - Has any production failure become a permanent fixture?
 - Is a judge calibrated against human labels, or trusted because it is a judge?
@@ -110,6 +121,13 @@ Every finding carries one, and the tier is part of the finding:
 **Never present judgement as measured.** A finding whose tier is honest survives the meeting
 where it is challenged; one that is inflated loses the whole report.
 
+Orthogonal to the tier, name the PROOF CLASS, because it decides what "no evals" does to
+the finding: a **source-level invariant proof** (the race, the hardcoded secret, the
+miswired timeout — read off the code) and a **deterministic reproduction** (a script that
+shows the double charge every run) survive a system with no evals untouched; only a
+**behavioural estimate** ("the agent usually recovers") needs an eval suite to be
+falsifiable — and inherits the no-evals finding until one exists.
+
 ## Priority — four axes, and no scalar
 
 `P = blast × confidence / effort` used to sit here, and it contradicted the two sections
@@ -172,6 +190,10 @@ a finding whose tier is `judgement` says so there rather than being quietly disc
 - **Grading instead of planning.** A score ends the conversation the audit was meant to
   start — including a score assembled from honest axes. Publish the axes; do not multiply
   them.
-- **Confusing "no evals" with "not measured yet."** It is the root finding; put it first,
-  because every other conclusion inherits it.
+- **Confusing "no evals" with "not measured yet."** It is the root finding for every
+  behavioural estimate, which inherits it. A source-level proof or deterministic
+  reproduction does NOT inherit it — burying a demonstrable double charge under a general
+  "everything is unfalsifiable" is how the one finding with a victim gets deprioritized.
+- **Treating a broken unit invariant with a prompt change.** Rule zero orders the
+  diagnosis; it does not convert a code bug into a wording bug.
 - **Reading a silent scanner as a clean system.** It is silent about what it can see.

package/plugins/agent-stack/skills/agent-harness/references/tools.md

@@ -124,7 +124,12 @@ the mistake cannot be made**, rather than documenting the mistake.
 - An `enum` instead of a free-text field with a list of valid values in the description.
 - One tool that does the two-step correctly instead of two tools that must be ordered.
 - A required `confirm: true` on a destructive action, so a partially-formed call fails
-  closed.
+  closed. **But `confirm: true` is a SYNTAX GUARD, not user approval** — the MODEL can
+  set the boolean itself, so it proves only that the call is complete, never that a human
+  agreed. Real user approval is a **verifiable grant from a trusted control plane, bound to
+  the principal, action, exact arguments and an expiry** (or an already-existing user
+  authorization); a stale grant does NOT authorize changed arguments, and a client-supplied
+  boolean creates no authorization at all.
 
 ## Annotations, and the risk one tool cannot show you
 
@@ -154,8 +159,12 @@ Three capabilities that are individually ordinary and jointly an exfiltration pa
 2. exposure to **untrusted content**,
 3. the ability to **communicate externally**.
 
-Any two are safe. All three in one session mean untrusted content can instruct the agent to
-read private data and send it out, and no prompt-level instruction reliably prevents it.
+All three in one session mean untrusted content can instruct the agent to read private data
+and send it out, and no prompt-level instruction reliably prevents it. But the trifecta
+names a SUFFICIENT configuration for one SPECIFIC risk — private-data EXFILTRATION — not a
+complete security model: **"any two are safe" over-claims.** Untrusted content plus a write
+capability, with no access to private data at all, still lets injected content corrupt state
+or take a damaging action; drop any leg and you have removed THAT triangle, not every risk.
 
 **The reason it belongs here rather than in a permission check:** the trifecta is a property
 of *the tool set assembled in a session*, so **per-tool analysis cannot see it**. Every tool

package/plugins/agent-stack/skills/agent-interop/SKILL.md

@@ -2,11 +2,11 @@
 name: agent-interop
 description: >-
   Use when an agent must talk to something outside its own process — building or consuming an
-  MCP server, exposing or calling another agent over A2A, publishing to the MCP Registry, or
+  MCP server, exposing or calling an agent over A2A, publishing to the MCP Registry, or
   putting a gateway in front of agent traffic. Carries the MCP 2026-07-28 wire surface and what it
   deprecated (server/discover, stateless per-request _meta, elicitation in form and URL mode,
   subscriptions/listen; sampling, roots, logging and dynamic client registration going),
-  A2A 1.0 agent cards, task states and three bindings, registry namespaces and server.json, tool
+  A2A 1.0 agent cards, task states, three bindings, registry namespaces, server.json, tool
   federation, and what a gateway must do that an API gateway does not. Triggers - "MCP server",
   "MCP client", "A2A", "agent card", "agent interoperability", "MCP registry", "server.json",
   "agentgateway", "tool federation", "MCP-сервер", "карточка агента", "интероперабельность
@@ -71,10 +71,29 @@ tasks, while MCP is more about agents using capabilities."* Real systems run bot
 server whose internals speak MCP — and that is the recommended architecture, not a
 compromise.
 
-**The tell that you picked wrong:** if you find yourself inventing a task lifecycle, a
-progress channel and a resumable handle on top of `tools/call`, you wanted A2A. If you find
-yourself publishing an agent card for something that is one HTTP call with a JSON schema,
-you wanted MCP.
+**The dispatch criterion is WHAT the other side is, not how long it runs.** MCP =
+a CAPABILITY / tool you control the shape of; A2A = an AUTONOMOUS PEER whose
+outcome you delegate and whose insides you cannot see. **Duration is a SECOND
+question, and it is about a Tasks CAPABILITY, not a protocol.** A long-running
+FIXED job you own — a ten-minute export, a batch transform — is MCP with the
+**Tasks** extension (a durable handle: poll, supply input mid-flight, retrieve
+later; see `references/mcp.md`), NOT A2A. So decide by the routing set, and
+never by the word *long-running*:
+
+- long-running FIXED export → **MCP Tasks, when the client/SDK negotiates that
+  extension**;
+- autonomous outsourced negotiation → **A2A** (you delegate the outcome, not
+  the steps);
+- **Tasks unsupported** by the reached client/SDK → an explicit fallback
+  (chunk the job, a job id the caller polls with a plain `tools/call`, or a
+  webhook) — reaching for A2A because Tasks is absent is picking a protocol to
+  dodge a missing extension.
+
+Check the client's ACTUALLY-negotiated extensions before building on Tasks;
+inventing a task lifecycle on top of `tools/call` when Tasks IS available is
+re-implementing the extension, and reaching for A2A when Tasks is merely
+unsupported is the mis-route this audit closes. Publishing an agent card for
+something that is one HTTP call with a JSON schema is still the MCP direction.
 
 ---
 

package/plugins/agent-stack/skills/agent-interop/references/mcp-scale.md

@@ -88,8 +88,8 @@ tokens than the definitions you so carefully removed.
 mitigations below were approximating: `defer_loading` keeps deferred definitions out of the
 system-prompt prefix and appends discovered ones inline as `tool_reference` blocks, leaving the
 cached prefix untouched (at least one tool must stay non-deferred — all-deferred is a 400). The
-economics, the arithmetic and the other invalidators are in `agent-orchestrator`'s
-`references/kv-cache.md`.
+economics, the arithmetic and the other invalidators are in
+`../agent-orchestrator/references/kv-cache.md`.
 
 Three mitigations, in the order they are usually right:
 

package/plugins/agent-stack/skills/agent-interop/references/mcp-ship.md

@@ -13,11 +13,47 @@ repeat it.
 
 ## Contents
 
+- Every example names its SDK — distribution, import, tested version, lifecycle
 - Mounting into an existing web app
 - Auth middleware and a health endpoint
 - Client configuration
 - Debugging a client that will not connect
 
+## Every example names its SDK — distribution, import, tested version, lifecycle
+
+`FastMCP` exists in TWO distributions, and they are not the same package: the
+official `mcp` SDK (`from mcp.server.fastmcp import FastMCP`) and the
+standalone `fastmcp` package, whose 2.x renamed the server class and moved the
+transport args out of the constructor. A snippet that names only the class
+names neither. Every executable example in this file is written against **the
+official `mcp` SDK, pinned**:
+
+```text
+# requirements.txt — the pin IS the example's identity
+mcp==1.12.3          # the version these snippets were verified against (2026-08-13);
+starlette==0.47.*    # re-pin only together with a re-run of the acceptance below
+uvicorn==0.35.*
+```
+
+```python
+from mcp.server.fastmcp import FastMCP   # official SDK — NOT `from fastmcp import FastMCP`
+```
+
+- **Current path (v2/current spec, pinned SDK above):** the snippets below,
+  as written.
+- **v1 / standalone-`fastmcp` migration:** explicitly **out of scope** here.
+  Supporting it means its OWN fixture verified against its own pin — renaming
+  imports and hoping is how the constructor-args move ships a 404.
+- **Lifecycle, in the verified order:** create the server → register tools →
+  build the ASGI app → register `/health` on the OUTER app → wrap with the
+  auth middleware → mount → serve. The health route registers BEFORE the auth
+  wrap, or the probe that says "up" needs a credential to say it.
+- **Proof is a localhost protocol call, never a string in markdown.** The
+  acceptance boots the pinned example in a clean env and asserts:
+  `GET /health` → 200 · unauthenticated `/mcp` → 401 · then `initialize`,
+  `tools/list` and one `tools/call` succeed against `http://127.0.0.1`. A
+  snippet nobody booted is a hope with syntax highlighting.
+
 ## Mounting into an existing web app
 
 The common production shape: you already run a FastAPI/Starlette app, and the MCP server

package/plugins/agent-stack/skills/agent-interop/references/mcp.md

@@ -219,7 +219,11 @@ Opt-in, negotiated, and worth checking before inventing an equivalent:
 
 - **Tasks** — a durable handle for long-running requests: poll for status, supply input
   mid-flight, retrieve the result later. This is the answer to "my tool takes ten minutes",
-  and it exists so you do not hold a connection open or invent a job table.
+  and it exists so you do not hold a connection open or invent a job table. **Duration is a
+  TASKS-capability question, never a reason to switch to A2A**: a long-running FIXED job you
+  own is MCP-with-Tasks. But Tasks is an OPT-IN, NEGOTIATED extension — check the client/SDK
+  actually supports it before building on it; where it is unsupported, the fallback is a
+  chunked job or a caller-polled job id over plain `tools/call`, not a protocol change.
 - **MCP Apps** — interactive UI rendered inline in the conversation.
 - **Skills over MCP** — structured instruction sets discovered and consumed through MCP,
   which is how a server ships Agent Skills rather than only tools.

package/plugins/agent-stack/skills/agent-orchestrator/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   loops, pipelines with human checkpoints, provider routing with fallback/retry, memory
   architecture, retrieval and decay, context budgets, sub-agent coordination, error hierarchies; the
   work as a graph — parallel layers, fake edges, a checker before convergence; for resale:
-  tiered wallets, one markup boundary, two-phase commit across database and provider API,
+  tiered wallets, one markup boundary, the saga across database and provider API,
   spend-delta polling, budget and loop guards, per-tenant keys. Triggers - "agent system",
   "orchestrator", "tool calling", "sub-agent", "LLM router", "fallback chain", "human in the
   loop", "memory layer", "LLM billing", "token wallet", "агентная система", "оркестратор",
@@ -282,10 +282,13 @@ comes from, and what this host actually executes are in
 
 Four rules, and these are the ones that change code:
 
-- **Label every edge with what crosses it. No payload, no edge.** Run the fake-edge test
-  over any chain you inherited: write the steps as boxes, ask of each arrow whether data
-  from A actually enters B, and delete the arrows that only encode the order somebody
-  typed. Two or three per workflow is the normal yield.
+- **Type every edge: data, control, authorization or resource.** Run the fake-edge
+  test over any chain you inherited — and delete an arrow only when it carries NONE
+  of the four: no payload, no causal constraint, no permission, no shared resource.
+  backup→migration, approval→charge and lease→edit carry no bytes and are real;
+  the arrows that only encode the order somebody typed are the two or three per
+  workflow the test normally yields. Before a fan-out, compare read/write sets —
+  read-only branches parallelise, two writers of one thing were a resource edge.
 - **`depends_on` is a claim, so execute by layer.** §5's executor walked `plan.stages` in
   list order beside a model that declared its dependencies — which serialises a plan that
   went to the trouble of saying it need not be. Kahn the graph; a cycle fails the plan
@@ -294,9 +297,11 @@ Four rules, and these are the ones that change code:
   returns a hallucination, and the synthesis node cannot tell: it combines all three and
   answers confidently. The checker decides *usable / not usable* and nothing else, and
   the convergence depends on **the checker**, never directly on a branch.
-- **Static unless you can name what forces dynamic.** A graph that picks its own next
-  nodes cannot be audited afterwards, because the shape that ran is not the shape anyone
-  drew. Where a run has to be explainable, that settles it.
+- **Static unless you can name what forces dynamic** — for predictability, not
+  auditability. A run is auditable when it SAVES its execution record (nodes/edges/events
+  that ran, the policy version, deterministic budget/depth/node caps, provenance); a
+  dynamic graph that keeps that record is auditable too. A design diagram alone is never
+  evidence: the shape drawn is not the shape that ran.
 
 ---
 

package/plugins/agent-stack/skills/agent-orchestrator/references/graph-engineering.md

@@ -120,24 +120,43 @@ already have and ask which of its waits are real.
 
 ## 3. The fake-edge test
 
-Five minutes, no tooling, and it is the highest-yield thing in this file.
+Five minutes, no tooling, and it is the highest-yield thing in this file —
+and its question is **typed**, because "does data cross?" alone deletes real
+constraints (AS-04). An edge is one of four kinds:
+
+| Kind | What crosses | Example that MUST survive |
+|---|---|---|
+| **data** | A's output enters B | findings → draft |
+| **control** | ordering only — a causal constraint with no bytes | backup → migration |
+| **authorization** | a decision that permits B | approval → charge |
+| **resource** | A and B touch one thing that tolerates one writer | two writes to one ledger |
 
 1. Write every step as a box.
 2. Draw an arrow between each pair of consecutive steps.
-3. For each arrow ask: **does data from A actually enter B?** — not *"does B come after
-   A"*.
-4. Yes → keep it, and **write the payload on the arrow**.
-5. No → delete it. That wait was free to give away and you were paying for it.
-6. Everything with no incoming arrow starts immediately.
+3. For each arrow ask, in order: does data from A enter B? does B's SAFETY
+   depend on A having finished (control)? does A PERMIT B (authorization)?
+   do A and B contend for one resource?
+4. Any yes → keep it, **type it, and write the rationale on the arrow** —
+   the payload for a data edge, the constraint for the other three.
+5. No to all four → delete it. That wait encoded the order somebody typed.
+6. Everything with no incoming arrow starts immediately — and **before any
+   fan-out, compare the branches' side-effect footprints and read/write
+   sets**: two read-only reviews genuinely parallelise; two writers of one
+   file were a resource edge nobody drew.
 7. Everything with no outgoing arrow is a final output.
 
-The tell that the test is being done honestly is step 4: if the payload cell is empty,
-the edge is fake, and the person drawing it now has to say so out loud rather than
-leaving the arrow in place because it looked orderly.
+The tell that the test is being done honestly is step 4: an arrow with no
+type and no rationale is fake, and the person drawing it now has to say so
+out loud rather than leaving it in place because it looked orderly. The
+inverse tell is step 5 done lazily: backup→migration, approval→charge and
+lease→edit all carry NO payload, and deleting them for that is how a
+migration runs against nothing — an empty payload cell justifies deletion
+only when there is also no causal, permissive or resource constraint.
 
-**Expect two or three fake edges in any workflow you have not run this against.** The
-classic is *"review file A, then review file B"*: it reads as a sequence, and the review
-of B never once looks at what A returned.
+**Expect two or three fake edges in any workflow you have not run this
+against.** The classic is *"review file A, then review file B"*: it reads as
+a sequence, the review of B never looks at what A returned, and both are
+read-only — no data, no control, no authorization, no resource.
 
 ## 4. The diamond
 
@@ -263,13 +282,20 @@ grows: a node finishes, looks at what it found, and decides what should come nex
 | **static** | **always first** — switch only after the static version hits a wall you can name |
 | dynamic | the scope of the work depends on what is discovered along the way |
 | dynamic | a node must choose its successors from its own output |
-| **never dynamic** | **you will need to audit exactly what ran and why** |
-
-The last row is a hard rule in this pack, not a preference. A dynamic graph's executed
-shape is not the shape anybody drew, so *"here is the graph"* and *"here is what
-happened"* stop being the same document — and every claim about the run becomes
-unfalsifiable from the outside. That is the same failure `agent-evals` names when a
-system has no durable trace.
+| prefer static | **you will need to audit exactly what ran and why** — but see below |
+
+The last row is a PREFERENCE, not a hard ban — and the earlier draft got this wrong by
+equating auditability with static structure, which conflates the plan drawn beforehand
+with the execution graph saved afterward. **Auditability is a property of the RECORD, not
+of the shape:** a run is auditable when its execution record is complete (every node,
+edge and event that ran), the policy version is captured, and the run stayed inside
+deterministic bounds — a **budget, a depth cap and a node cap**, each with provenance. A
+static graph is preferred because its executed shape usually matches the drawn one and it
+is predictable; a DYNAMIC graph under those caps, saving that record, passes the same
+reconstruction audit — the SAME reconstruction that detects a deleted event or edge in
+either mode. What never passes, static or dynamic, is a design DIAGRAM on its own:
+*"here is the graph"* is not *"here is what happened"*. That is the same failure
+`agent-evals` names when a system has no durable trace.
 
 **Most workflows that feel like they need a dynamic graph need a better static one.**
 Dynamic is more powerful and much harder to control; it is the second reach, never the
@@ -364,7 +390,12 @@ session:
 ## Workflow defaults
 
 - A node with no declared dependency starts immediately; do not serialise by habit.
-- Every declared dependency names the data it carries. No payload named ⇒ delete the edge.
+- Every declared dependency carries a type (data/control/authorization/resource)
+  and a rationale. Delete an edge only when it has none of the four — an empty
+  payload alone never justifies deletion: backup→migration carries no bytes and
+  is real.
+- Before a fan-out, compare the branches' side-effect footprints and read/write
+  sets; writers of one resource serialise, read-only branches run in parallel.
 - A checker sits between any parallel layer and the node that consumes it, and the
   consumer depends on the checker rather than on the layer.
 - A checker flags; it never silently passes an incomplete output.

package/plugins/agent-stack/skills/agent-orchestrator/references/llm-proxy-billing.md

@@ -1,7 +1,7 @@
 # Reselling LLM access — metering, wallets and guardrails
 
 **Load this when** the product resells LLM access: tiered wallets and the single
-boundary where markup applies, two-phase commit across a database and a provider API
+boundary where markup applies, the saga across a database and a provider API
 with compensating transactions, advisory locking, optimistic concurrency for reclaims,
 spend-delta polling and its three cases, budget / loop / auto-pause guardrails,
 per-tenant key lifecycle and healing, the refund waterfall, and model-routing
@@ -18,7 +18,8 @@ the patterns hold for any upstream that issues per-tenant keys with limits.
 ## Contents
 
 - [The tiered wallet](#the-tiered-wallet)
-- [Two-phase commit across a DB and an external API](#two-phase-commit-across-a-db-and-an-external-api)
+- [The saga across a DB and an external API](#the-saga-across-a-db-and-an-external-api)
+- [Reconciling an unknown](#reconciling-an-unknown)
 - [Serializing concurrent transfers](#serializing-concurrent-transfers)
 - [Optimistic concurrency for reclaims](#optimistic-concurrency-for-reclaims)
 - [Discovering spend you do not control](#discovering-spend-you-do-not-control)
@@ -67,29 +68,76 @@ the constant changes.
 
 ---
 
-## Two-phase commit across a DB and an external API
+## The saga across a DB and an external API
 
-You have a database you can roll back and an HTTP API you cannot. Order matters,
-and so does what you do when step 2 fails.
+You have a database you can roll back and an HTTP API you cannot. That pair is
+a **saga** — local transactions stitched together by compensations — and it is
+not two-phase commit: 2PC needs a coordinator both participants obey, and the
+provider's API never agreed to prepare/commit. Naming it 2PC is how the next
+defect ships, because 2PC has no *unknown* outcome, and an HTTP call to a
+system you do not control has one all the time.
 
-**DB first, API second, compensate on failure:**
+Every operation that touches the provider carries an **`operation_id`**, minted
+inside the DB transaction, and a state that moves
+`pending → applied | unknown | compensated`:
 
 1. Acquire the lock (below).
 2. Read fresh balances **inside** the transaction — not before it.
 3. Compute the transfer and apply the markup once.
-4. Zero the source tier, increment the destination, write an audit row.
+4. Zero the source tier, increment the destination, write the intent row —
+   `operation_id`, state `pending` — an outbox entry, not a log line.
 5. Commit.
-6. Call the provider to raise the key limit.
-7. **On API failure: a compensating transaction restores every DB value and
-   writes a `compensation` audit row.**
+6. Call the provider to raise the key limit, idempotently where the API allows
+   (send the `operation_id` as the idempotency key).
+7. **On an outcome that proves the call did not apply** — a 4xx validation
+   refusal, a "no such key" — a compensating transaction restores every DB
+   value, writes a `compensation` audit row, and marks the operation
+   `compensated`.
+8. **On an AMBIGUOUS outcome — a timeout, a connection reset after send, a
+   5xx — the operation is marked `unknown` and is NOT compensated.** The
+   provider may have applied the change: compensating on a guess restores a
+   ledger the key no longer matches, and the money drifts in the direction you
+   cannot see. `unknown` resolves only by **reconciliation** — read the
+   provider's actual state (the key's real limit), then mark `applied` or
+   compensate on evidence. Until it resolves, the operation blocks retries of
+   itself: a retry of an `unknown` is how one top-up applies twice.
 
 The alternative — API first, DB second — leaves money on the key that your
 ledger does not know about, and no amount of retrying finds it again. The
-compensating transaction is not optional politeness; it is the only thing that
-makes step 6 recoverable.
-
-Log both the intent and the compensation. An audit trail that records only
-successes cannot answer "where did the $35 go" six weeks later.
+compensating transaction makes the *known* failure recoverable; the `unknown`
+state is what keeps the ambiguous one honest.
+
+Log the intent, the outcome and the compensation, keyed by `operation_id`. An
+audit trail that records only successes cannot answer "where did the $35 go"
+six weeks later — and one that cannot say "we do not know yet" answers it
+wrongly.
+
+## Reconciling an unknown
+
+Three rules, and every one exists because a late HTTP response is a message
+from the past:
+
+- **Ask by the operation's own idempotency key.** Reconciliation queries the
+  provider for what happened to THIS `operation_id` — never "read the limit
+  and guess whose change it reflects". Ambient state is the sum of every
+  operation that ever landed; only the key isolates yours.
+- **The tenant's ledger carries a revision, and every resolve is a CAS.** A
+  reconcile or compensation writes only if the revision it read is still
+  current; a late or concurrent response that lost the race aborts and
+  re-reads, it never blind-writes. Without this, the response to operation A —
+  arriving after operation B moved the same tenant's ledger — "restores"
+  values B already superseded, and the compensation itself becomes the
+  corruption.
+- **Compensate only your own confirmed operation.** A compensation names its
+  `operation_id`, reverses exactly that operation's delta, and runs only after
+  reconciliation confirmed THAT operation did not apply. A response for A is
+  never grounds to touch B's rows — however tempting the arithmetic looks.
+
+**Repeated reconciliation is idempotent.** `unknown → applied` and
+`unknown → compensated` are one-way edges: resolving an already-resolved
+operation reads its state and stops — zero new writes, zero new audit rows. A
+reconciler that runs twice (and it will: cron plus a manual "Sync now" is the
+normal case, not the weird one) must find nothing left to do the second time.
 
 ---
 
@@ -141,16 +189,30 @@ discover spend by **polling a cumulative counter and taking the delta**:
 delta = currentUsage - lastRecordedUsage
 ```
 
-Three cases, and only the first is obvious:
-
-- `lastRecordedUsage == 0 && currentUsage > 0` → **seed the baseline, record
-  nothing.** Recording it charges the tenant for everything spent before you
-  started watching.
-- `currentUsage > lastRecordedUsage` → record `delta`, then immediately enforce
-  budgets (below).
-- `currentUsage < lastRecordedUsage` → the key was recreated. **Resync the
-  baseline, record nothing.** A negative delta treated as spend credits money
-  that was never returned.
+**Zero is a value, not an absence.** The baseline row carries three fields
+BESIDE the sum — `baseline_initialized`, `observed_at`, and
+`provider_key_generation` (the key's id or created-at, whatever the provider
+lets you read) — because `lastRecordedUsage == 0` has two meanings that cost
+money to conflate: "never watched" and "watched from zero". Testing the sum
+for zero eats the first REAL spend of every key you watched from birth,
+silently, as "seeding".
+
+Four cases, decided by the flags, never by the sum:
+
+- `!baseline_initialized` → **seed the baseline, record nothing**, set
+  `baseline_initialized`, stamp `observed_at` and the generation. Recording
+  here charges the tenant for everything spent before you started watching.
+- initialized, `currentUsage > lastRecordedUsage` → record `delta` — including
+  the very first delta of a key whose baseline is a genuine 0 — then
+  immediately enforce budgets (below).
+- initialized, `currentUsage < lastRecordedUsage`, **generation changed** →
+  the key really was recreated: resync the baseline to the new generation,
+  record nothing. The new key's next increase is recorded normally.
+- initialized, `currentUsage < lastRecordedUsage`, **same generation** →
+  **ANOMALY.** Do not resync, do not record, do not guess "recreated" — a
+  counter that went backwards on the same key is the provider disagreeing
+  with your ledger, and reconciliation (above) owns it. A guessed resync here
+  quietly forgives the difference forever.
 
 Sync your stored limit from the provider's authoritative value on the same pass —
 under the lock, with a re-read, so the sync does not clobber a transfer that

package/plugins/agent-stack/skills/agent-orchestrator/references/memory-architecture.md

@@ -235,10 +235,12 @@ The progression, and both ends are wrong:
   access control**.
 
 **What this pack already has, and what it is not.** `agent-sync` gives leases, race-free id
-reservation and a run journal: it decides *who may write this file right now*. That is
-coordination, and it is not shared memory — it says nothing about what an agent should be
-allowed to *read*, or whose experiential memory is trustworthy enough to act on. An agent
-system that needs both needs both.
+reservation and a run journal: it decides *who may write this file right now* — precisely,
+via a per-file **resource claim**, because a task lease authorizes the task and not the file
+(SY-04), and its guarantee is a real cross-machine compare-and-swap only under the git lease
+backend, advisory otherwise. That is coordination, and it is not shared memory — it says
+nothing about what an agent should be allowed to *read*, or whose experiential memory is
+trustworthy enough to act on. An agent system that needs both needs both.
 
 **The design rule:** make shared writes **attributed and scoped**. An entry carries who
 wrote it and under what role, and a reader may weigh it accordingly. Unattributed shared

package/plugins/agent-stack/skills/agent-orchestrator/references/memory-lifecycle.md

@@ -18,7 +18,8 @@ long-term behaviour is a consequence of those frequencies, not of separate boxes
 - [3. Evolution — consolidation](#3-evolution--consolidation)
 - [4. Evolution — updating, and the stability–plasticity dilemma](#4-evolution--updating-and-the-stabilityplasticity-dilemma)
 - [5. Evolution — forgetting](#5-evolution--forgetting)
-- [6. What this pack already implements](#6-what-this-pack-already-implements)
+- [6. The temporal evidence lifecycle](#6-the-temporal-evidence-lifecycle)
+- [7. What this pack already implements](#7-what-this-pack-already-implements)
 
 ## 1. Formation — five ways to turn experience into an entry
 
@@ -134,7 +135,38 @@ constraint, many memory systems avoid directly deleting certain memories."*
 Deletion remains a **correctness and privacy** operation — a person asking to be forgotten
 is not a capacity decision, and `memory-architecture.md` §8 covers it.
 
-## 6. What this pack already implements
+## 6. The temporal evidence lifecycle
+
+One record's timeline, and the two events that are NOT on it:
+
+```
+born ──▶ corroborated ──▶ superseded ──▶ (restored)
+  │       (independent      (reversible:      un-supersede puts it back;
+  │        provenance        is_active=False,  nothing was deleted
+  │        only)             superseded_by)
+  └──▶ expired (volatile fact past its freshness window —
+        out of default retrieval WHATEVER its confidence,
+        verified included)
+```
+
+- **Retrieval is not a lifecycle event.** Reading a record — or the agent
+  restating it in its own words — moves nothing: not confidence, not
+  freshness, not activity. A self-generated repeat scored as confirmation is
+  the compounding error `patterns.md` → Confidence Management refuses; only
+  evidence with independent provenance corroborates.
+- **Supersession is an annotation, and it is reversible.** A new dated fact
+  sets `is_active=False` + `superseded_by` on the old one and KEEPS it: the
+  chain is walkable from either end, an explicit query still reaches the old
+  value, and restoring it (the correction turned out wrong) is clearing two
+  fields, not resurrecting a deleted row. The dated history is the audit
+  trail of what the system believed when.
+- **`verified` is about confidence, never about time.** A volatile fact —
+  a quota, a price, a rate limit — carries a freshness window from its
+  `validity` field, and past that window it leaves default retrieval even at
+  confidence 1.0. Verification exempts a record from confidence DECAY;
+  nothing exempts a fact about the present from the present.
+
+## 7. What this pack already implements
 
 Stated so this file is read as an extension and not as a replacement:
 
@@ -146,9 +178,9 @@ Stated so this file is read as an extension and not as a replacement:
 | Forgetting, time-based | `patterns.md` → Confidence Management |
 | Global integration, cross-scope | `patterns.md` → Cross-Resource Learning Transfer |
 | **Frequency-based forgetting** | **nowhere — and the long-tail trap above is why that is a deliberate omission rather than a gap to close carelessly** |
-| **Temporal annotation instead of deletion** | **nowhere** — Conflict Resolution currently resolves rather than annotates |
+| **Temporal annotation instead of deletion** | `patterns.md` → Conflict Resolution — supersession sets `is_active=False` + `superseded_by` and the old record stays in history, reversible and reachable by explicit query |
 | **Dual-phase updating** | **nowhere** — the pack updates inline |
 
-The last three are named as absent rather than quietly added: each is a real change to a
+The remaining two are named as absent rather than quietly added: each is a real change to a
 mechanism that is in production, and this file's job is to say what the options are, not to
 change `patterns.md` from a survey.

package/plugins/agent-stack/skills/agent-orchestrator/references/patterns.md

@@ -364,26 +364,36 @@ class LearningAnalyzer:
 
 ## Confidence Management
 
+Confidence measures **corroboration, not match frequency**: it moves only on
+evidence with independent provenance — another session, another agent, an
+observed outcome. Retrieving a record, or the agent restating it in its own
+words, bumps nothing: a self-generated repeat scored as confirmation is how an
+early mistake compounds into a "high-confidence" one.
+
 ```
 LEARNING CONFIDENCE:
-  Initial:     0.6
-  Confirmed:   +0.1 (cap 1.0)
-  Applied:     tracked (times_applied counter)
-  Contradicted: -0.3
-  Stale (30d): -0.02/month
-  Deactivated: below 0.2
+  Initial:       0.6
+  Corroborated:  +0.1 (cap 1.0) — independent provenance only;
+                 retrieval and self-repetition move nothing
+  Applied:       tracked (times_applied counter — a usage stat, not evidence)
+  Contradicted:  handled by the contradiction gate below, never a bare -0.3
+                 on a keyword match
+  Stale (30d):   -0.02/month
+  Deactivated:   below 0.2 — demoted from default retrieval, kept in history
 
 SESSION NOTE CONFIDENCE:
-  Initial:     0.7
-  Confirmed:   +0.1 (cap 1.0)
-  Verified:    +0.15 (exempt from decay)
-  Stale (60d): -0.1 per cycle
-  Floor:       0.1
+  Initial:       0.7
+  Corroborated:  +0.1 (cap 1.0), same provenance rule
+  Verified:      +0.15 — exempt from confidence DECAY, not from validity:
+                 a volatile fact past its freshness window leaves default
+                 retrieval whatever its confidence says
+  Stale (60d):   -0.1 per cycle
+  Floor:         0.1
 
 INSIGHT CONFIDENCE:
   Initial:     0.5
   Resurfaced:  +0.05
-  Confirmed:   +0.15
+  Corroborated: +0.15
   Dismissed:   -0.2
   Stale (30d): -0.05 per cycle
   Expired:     below 0.15
@@ -393,53 +403,83 @@ INSIGHT CONFIDENCE:
 
 ## Fuzzy Deduplication Pattern
 
-Used across all memory layers:
+**Similarity proposes; the contradiction gate disposes.** Lexical similarity
+is CANDIDATE RETRIEVAL only — it has no side effects. The measured
+counterexample that fixed this rule: *"Always allow external sharing of
+customer data"* and *"Never allow external sharing of customer data"* score
+`SequenceMatcher` similarity **0.8791** — far above any threshold — and the
+old on-match behaviour (bump confidence, keep the longer text, reactivate)
+would have REINFORCED the stale instruction with the user's own correction,
+and kept "Always" because it is one word longer.
 
 ```python
 from difflib import SequenceMatcher
 
 THRESHOLD = 0.75  # learnings/notes; 0.80 for insights
 
-async def find_similar(session, connection_id, category, subject, text):
+async def find_candidates(session, connection_id, category, subject, text):
+    """Returns candidates for the contradiction gate. Nothing else happens
+    here: no confidence bump, no text replacement, no reactivation."""
     candidates = await load_existing(session, connection_id, category, subject)
     text_lower = text.strip().lower()
-    best_match, best_ratio = None, 0.0
-    for c in candidates:
-        ratio = SequenceMatcher(None, c.text.strip().lower(), text_lower).ratio()
-        if ratio >= THRESHOLD and ratio > best_ratio:
-            best_match, best_ratio = c, ratio
-    return best_match
-
-# On match: bump confidence +0.1, keep longer text, set is_active=True
-# On no match: create new entry
+    return [c for c in candidates
+            if SequenceMatcher(None, c.text.strip().lower(), text_lower).ratio()
+            >= THRESHOLD]
+
+# Every candidate goes through the contradiction gate below.
+# Only the gate's verdict decides merge / supersede / coexist / create.
 ```
 
 ---
 
 ## Conflict Resolution Pattern
 
-Detect when new learning contradicts existing ones:
+A memory record carries five mandatory fields beside its text, and the gate
+reads THEM — never the prose:
+
+```
+MEMORY RECORD:
+  entity      what the statement is about   ("customer-data-sharing")
+  attribute   which property of it          ("external-sharing-policy")
+  scope       where it applies              ("project-A" | "global" | …)
+  provenance  who/what asserted it, when    (session, agent, outcome, user)
+  validity    observed_at + volatile|stable (+ freshness window if volatile)
+  value       the normalized position       ("allow" | "deny" | "30s" | …)
+```
 
 ```python
-CONFLICT_INDICATORS = {"use", "prefer", "always", "never", "should",
-                       "instead", "not", "avoid", "correct", "wrong"}
-
-def resolve_conflicts(existing_learnings, new_lesson, new_confidence):
-    new_keywords = {w for w in new_lesson.lower().split() if w in CONFLICT_INDICATORS}
-    for old in existing_learnings:
-        old_keywords = {w for w in old.lesson.lower().split() if w in CONFLICT_INDICATORS}
-        shared = new_keywords & old_keywords
-        if not shared: continue
-
-        has_negation_flip = (
-            ("not" in new_keywords) != ("not" in old_keywords) or
-            ("never" in new_keywords) != ("never" in old_keywords) or
-            ("avoid" in new_keywords) != ("avoid" in old_keywords))
-
-        if has_negation_flip and old.confidence <= new_confidence:
-            old.is_active = False  # superseded
+def contradiction_gate(old, new):
+    if (old.entity, old.attribute) != (new.entity, new.attribute):
+        return "unrelated"      # similarity alone never merges anything
+    if not scopes_overlap(old.scope, new.scope):
+        return "coexist"        # a correction wins only in its own scope
+    if values_compatible(old.value, new.value):
+        return "corroborates"   # +confidence iff provenance is independent
+    return "contradicts"
+
+def apply_verdict(verdict, old, new):
+    if verdict == "contradicts":
+        # Temporal supersession, reversible: the old record STAYS in history.
+        old.is_active = False
+        old.superseded_by = new.id     # never deleted, never bumped
+        return create(new)             # starts at its own initial confidence
+    if verdict == "corroborates" and independent(old.provenance, new.provenance):
+        old.confidence = min(1.0, old.confidence + 0.1)
+        old.provenance.append(new.provenance)
+        return old
+    if verdict in ("coexist", "unrelated"):
+        return create(new)             # both live; different scope or subject
+    return old                          # self-repetition: no change at all
 ```
 
+Keyword heuristics (negation flips, `always`/`never` pairs) may FLAG a pair
+for the gate; they never decide it. The second measured counterexample is
+why: *"Use Python"* and *"Never use production credentials"* share `use` and
+a negation flip, and the old keyword rule could supersede one with the other
+— two statements about different entities entirely. A number or unit change
+("timeout is 30s" → "timeout is 60s") is a contradiction the negation
+heuristic cannot see and the value comparison catches.
+
 ---
 
 ## Cross-Resource Learning Transfer