@ssheleg/agent-stack 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## [0.10.0] — 2026-08-15
+
+### Added
+
+- **`agent-orchestrator/references/graph-engineering.md` — deciding the shape of the work
+  before doing it.** The pack could wire a loop, prove it behaved, connect it and tell it
+  what to do, and had nothing to say about the question that comes before all four: *does
+  this actually have to happen in a line?* Node and edge, the fake-edge test, the diamond,
+  the two ways a diamond fails silently, the checker node, static versus dynamic, and the
+  cost table that says when a graph is not worth building.
+
+  Sourced from *Graph Engineering with Claude*
+  (`https://x.com/Mahaximus_/status/2082442856417956173`, published 2026-07-29), and the
+  link is kept so the original can be re-read rather than remembered through the summary.
+  Four sections are **this pack's** and are marked as such in the file: what the host
+  actually runs, the barrier distinction, what a checker costs, and auditability as a hard
+  rule rather than a preference.
+
+- **What Claude Code actually executes, with version evidence.** The source's one
+  operational claim aged out six weeks after publication: the `workflow` keyword it names
+  was renamed to `ultracode` in **v2.1.160**, and the YAML it shows is a way of describing
+  a graph in a prompt rather than a syntax the host parses — the execution contract is a
+  script whose primitives are `agent()`, `parallel()` (a barrier) and `pipeline()` (none).
+  Every claim in that section carries the `v2.1.x` changelog entry that establishes it,
+  which is why the correction reads as a dated fact rather than as an error by the author.
+
+- **`agent-harness` — *Static or dynamic, the second question*.** The workflow-versus-agent
+  table decided one thing and left the other open. Six rows, and one of them is hard: a run
+  that has to be auditable is static, because a graph that picks its own next nodes produces
+  a shape nobody drew, and then *"here is the design"* and *"here is what happened"* stop
+  being the same document.
+
+- **`agent-evals` §5a — the checker node as an evaluator that runs inside the graph.** Its
+  five catches split three code checks and two judge calls, so §5's *cheap checks first*
+  applies to a position in the graph rather than to a suite. And the part that makes it eval
+  work: **a checker that has never rejected anything is a finding, not a reassurance** — its
+  verdicts are scores with a source, and its rejection rate belongs on the same dashboard as
+  its pass rate.
+
+- **A sixth scanner detector, `unguarded-fanout`.** `asyncio.gather` with no
+  `return_exceptions=True`, or `Promise.all` with no `allSettled` and no per-branch
+  `.catch`: the first sibling to fail cancels the batch, the others' completed work is
+  discarded, and the node consuming the results cannot tell a failed branch from an empty
+  one. Conservative like the rest — the capturing form anywhere in the file silences it.
+
+### Changed
+
+- **The self-test proves silence as well as noise.** `PLANTS` and `CLEAN` replaced the
+  single dict, because one detector now reads two languages and needed a plant in each, and
+  because a detector that fires on the defect *and* on its fix has no discriminating power.
+  A fan-out that **does** capture its branches is now a fixture the pass must stay silent
+  on. `self-test: 6/6` → **`9/9`** (seven plants, two clean fixtures), counted by running it.
+
+- **`agent-orchestrator` §5 no longer contradicts its own data model.** `PlanStage` declared
+  `depends_on` and the executor beside it walked `plan.stages` in list order — a plan that
+  went to the trouble of saying it need not be serialised, serialised. It now executes in
+  dependency layers (Kahn), gates a layer of more than one on the checker before anything
+  consumes it, and `ExecutionPlan` grows the `layers()` that makes the declaration mean
+  something. A cycle fails the plan rather than deadlocking the run.
+
+### Removed
+
+- **The hardcoded context-window table.** `references/patterns.md` carried nine vendor model
+  ids with their windows and a `DEFAULT_CONTEXT_WINDOW` of 16 000. Every number was correct
+  when written and none survived: ids were renamed, long-context variants shipped under the
+  same family name, and a system reading that table would size its budget for a window an
+  order of magnitude smaller than the one it was given. Replaced by the resolution order —
+  configuration, then the provider, then a conservative floor **with a loud log line** — and
+  the check is mechanical: no vendor model id remains anywhere in the shipped skill text.
+  Two illustrative ones in `SKILL.md` and `llm-proxy-billing.md` went with it, because a
+  class fixed in one place and left in two others is not fixed.
+
+- **Two duplicated homes.** §8's learning tables and §10's prompt-assembly snippet restated
+  what `references/patterns.md` and `agent-harness/references/system-prompt.md` already own.
+  Both now state the decision and point at the home. `SKILL.md` is **502 lines / 5670
+  tokens** against a 4750 working budget — the number is counted, it is over, and the next
+  addition to this body should split rather than absorb.
+
 ## [0.9.0] — 2026-08-15
 
 ### Added

package/README.md

@@ -11,7 +11,7 @@ Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills).
 
 Four skills — `agent-orchestrator` for wiring the loop, `agent-evals` for proving it
 behaves, `agent-interop` for everything it talks to outside its own process,
-`agent-harness` for what it is **told** — and eighteen references they load on demand,
+`agent-harness` for what it is **told** — and nineteen references they load on demand,
 plus one scanner.
 
 **The orchestrator** (`SKILL.md`) — what the agent reads first:
@@ -31,6 +31,10 @@ plus one scanner.
   decay, plus conflict resolution when a new learning contradicts an old one
 - context budget allocation by priority
 - self-learning feedback loops
+- **the shape of the work, decided before the work**: an edge that carries no data is
+  no edge, a plan that declares `depends_on` is executed in dependency layers rather
+  than in list order, and a parallel layer gets a checker before the node that
+  consumes it
 
 **The evals skill** (`agent-evals/SKILL.md`) — how you know any of it works. An
 agent's behaviour is not in its source, so the artifact under test is the
@@ -74,9 +78,16 @@ eight extension seams where a permission gate or a context rewrite can actually
 
 It runs in both directions: **building a harness and auditing somebody else's are one
 checklist read forwards and backwards.** `scripts/audit_agent.py` is the mechanical half —
-five conservative detectors, and it always prints what it *cannot* see plus a denominator,
+six conservative detectors, and it always prints what it *cannot* see plus a denominator,
 so its silence is never read as a pass.
 
+**`references/graph-engineering.md`** — deciding the shape of the work before
+doing it: node and edge, the fake-edge test, the diamond and the two ways it
+fails silently, the checker node and what it costs, static versus dynamic with
+auditability as the hard rule, when a graph is not worth building, and what a
+host actually executes when it fans out — with the version evidence, because the
+keyword the source named was renamed six weeks after it was published.
+
 **`references/context-engineering.md`** — what the loop gives up when the window
 runs out: the five-rung compaction ladder and why to re-measure between rungs,
 the tool-pair boundary invariant, typed carryover blocks copied across the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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

@@ -2,7 +2,7 @@
   "name": "agent-stack",
   "displayName": "Agent Stack",
   "description": "Two skills: agent-orchestrator \u2014 tool-calling loops, multi-stage pipelines with checkpoints, provider routing with fallback, four-layer memory, context engineering, plus the wallet side of reselling LLM access; and agent-evals \u2014 run/trace/thread evals, judges, and fixtures grown from production.",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -7,9 +7,10 @@ description: >-
   evals. Covers the three observability primitives (run, trace, thread) crossed with three
   eval granularities (single-step, full-turn, multi-turn), the offline/online/ad-hoc
   timing axis, pass-fail rubrics over scalar scores, cheap code checks before model
-  judges, simulated users with adversarial personas, annotation queues, and what to
-  instrument so any of it is possible. Triggers - "agent eval", "eval suite", "LLM judge",
-  "regression fixture", "trajectory eval", "is the agent getting better", "эвалы агента",
+  judges, the checker node as an evaluator running inside the graph, simulated users with
+  adversarial personas, annotation queues, and what to instrument so any of it is
+  possible. Triggers - "agent eval", "eval suite", "LLM judge", "regression fixture",
+  "trajectory eval", "checker node", "is the agent getting better", "эвалы агента",
   "оценка агента", "LLM-судья", "регрессионный набор", "как проверить агента". Not for
   unit tests of ordinary code, or for benchmarking a model.
 license: MIT
@@ -159,6 +160,44 @@ domain expert and accept that this tier stays human.
 
 ---
 
+## 5a. The checker node — an evaluator that runs inside the graph
+
+Everything above evaluates a run *afterwards*. One evaluator runs **during** it, and it is
+the one most systems are missing: a **checker node** sitting between a parallel layer and
+the node that consumes it. Its only job is *usable / not usable*, and the convergence
+depends on **it** rather than on the branches — otherwise the gate has a bypass.
+
+It matters here because it is the same machinery as §5, positioned differently:
+
+| It catches | Decided by |
+|---|---|
+| an empty or null output | a code check |
+| a confidence signal below the downstream bar | a code check |
+| a shape that will break the consumer's parsing | a code check |
+| two outputs that cannot both be true | a judge |
+| an output answering a different question than the one asked | a judge |
+
+Three of five are free. Run them first — §5's *cheap checks first*, applied to a position
+in the graph rather than to a suite.
+
+**A checker is a node, so it can be wrong, and its failure mode is silent approval.** A
+model checker that has never been shown a bad input passes everything, and a graph with a
+checker that always says yes is **worse** than one with none: the missing checkpoint has
+been replaced by a false one that everything downstream now trusts. Three consequences,
+and they are eval work rather than orchestration work:
+
+- **Watch it refuse a planted bad output** before trusting it, exactly as §5 requires of
+  any judge before it scores unattended.
+- **Record every verdict as a score bound to the run**, with `source: code_check` or
+  `llm_judge` (§7). A checker whose verdicts are not stored cannot be asked afterwards how
+  often it fired, which means it cannot be calibrated.
+- **A checker that has never rejected anything is a finding, not a reassurance.** Put the
+  rejection rate on the same dashboard as the pass rate; a rate of zero is either a
+  perfect upstream or a broken gate, and only the stored verdicts can tell you which.
+
+Where the checker sits in the shape, and why the convergence needs one at all:
+`agent-orchestrator/references/graph-engineering.md`.
+
 ## 6. The corpus grows from production
 
 Never author the suite up front. Every production failure and every thumbs-down becomes a
@@ -215,6 +254,8 @@ None of the above runs without these, and they are the part people skip:
 - [ ] Pass/fail rubrics with enumerated failure conditions, written with behaviour owners
 - [ ] Code checks before model judges
 - [ ] Judge calibrated against human labels before it is trusted
+- [ ] Every checker node watched refusing a planted output, its verdicts stored as scores,
+      and its rejection rate on the dashboard — a checker at zero rejections is a finding
 - [ ] Domain-expert review for output a general judge cannot grade
 - [ ] Every production failure minimised into a permanent fixture
 - [ ] Annotation queue with filters, and the two reviewer roles kept separate

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

@@ -8,9 +8,10 @@ description: >-
   instead of a score, plus a scanner. Carries Pi as a worked kernel implementation — SDK, RPC
   and extension seams — for embedding or extending a harness. Triggers - "system prompt",
   "tool description", "agent picks the wrong tool", "agent loops forever", "prompt
-  engineering", "ReAct", "workflow or agent", "audit this agent", "embed an agent", "agent
-  SDK", "Pi harness", "системный промпт", "агент не вызывает тул", "аудит агента", "встроить
-  агента". Not for the loop's plumbing, its evals, or its protocols — those are siblings.
+  engineering", "ReAct", "workflow or agent", "static or dynamic", "audit this agent",
+  "embed an agent", "agent SDK", "Pi harness", "системный промпт", "агент не вызывает тул",
+  "аудит агента", "встроить агента". Not for the loop's plumbing, its evals, or its
+  protocols — those are siblings.
 ---
 
 # Agent harness — what the agent is told, and how to audit what someone else told theirs
@@ -81,6 +82,30 @@ that only where a fixed path genuinely cannot be written.
 from a known set. Orchestration invents the set per request. If you can enumerate the
 branches, you wanted routing and it is cheaper.
 
+### Static or dynamic — the second question, and it is not the same one
+
+Having chosen a workflow, one thing is still open: **is its shape known before it runs?**
+A **static** graph has every node and edge decided up front. A **dynamic** one grows — a
+node finishes, reads what it found, and decides what comes next.
+
+| Reach for | When |
+|---|---|
+| **static** | the task repeats and the structure is the same every time |
+| **static** | predictability and speed matter more than flexibility |
+| **static** | **always first** — go dynamic 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** | **the run has to be auditable** — see below |
+
+**The audit rule is hard, not a preference.** 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. Most
+workflows that feel like they need a dynamic graph need a better static one.
+
+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 — is
+`agent-orchestrator/references/graph-engineering.md`.
+
 ---
 
 ## References
@@ -151,6 +176,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
 - [ ] 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/scripts/audit_agent.py

@@ -158,14 +158,50 @@ def check_hardcoded_model(rel, text, lines):
             "tenant, system default — is the shape that bills correctly")
 
 
+def check_unguarded_fanout(rel, text, lines):
+    """A fan-out whose siblings' failures are not captured.
+
+    `asyncio.gather` without `return_exceptions=True` cancels the whole batch on the first
+    exception: every other branch's completed work is discarded, and the node that consumes
+    the results cannot tell a branch that FAILED from one that returned nothing. `Promise.all`
+    has the identical shape. That is the failure a checker node between a parallel layer and
+    its convergence exists to stop, and it is invisible in a green test run because the happy
+    path never exercises it.
+
+    Conservative twice over, like every detector here: the file must already look
+    agent-related, and the capturing form must be absent from the WHOLE file — one
+    `return_exceptions` or `allSettled` anywhere is taken as evidence the author knows the
+    distinction, and this pass says nothing.
+    """
+    if re.search(r"return_exceptions|allSettled", text):
+        return
+    for i, l in enumerate(lines, 1):
+        if re.search(r"\basyncio\.gather\s*\(", l):
+            add("unguarded-fanout", rel, i,
+                "`asyncio.gather` with no `return_exceptions=True` — the first sibling to "
+                "raise cancels the batch and throws away what the others already produced",
+                "Capture each branch's outcome, then gate the convergence on a checker that "
+                "can tell a failed branch from an empty one")
+        if re.search(r"\bPromise\.all\s*\(", l) and ".catch" not in l:
+            add("unguarded-fanout", rel, i,
+                "`Promise.all` with no `allSettled` and no per-branch `.catch` — one "
+                "rejection discards every other branch's completed result",
+                "Use `Promise.allSettled` or catch per branch, then gate the convergence on "
+                "a checker that can see which branch failed")
+
+
 CHECKS = [check_unbounded_loop, check_tool_without_description, check_swallowed_error,
-          check_no_timeout, check_hardcoded_model]
+          check_no_timeout, check_hardcoded_model, check_unguarded_fanout]
 
 # What no static pass can reach. Printed every run, never suppressed.
 BLIND = [
     "whether the SYSTEM PROMPT is at the right altitude — or whether it is in this repo at all",
     "whether two tool descriptions actually distinguish themselves to a model",
     "whether the workflow/agent choice was made deliberately or defaulted to an agent",
+    "whether a fan-out has a CHECKER between it and the node that consumes it — this pass "
+    "sees an unguarded gather, never a missing gate",
+    "whether a declared dependency graph is actually executed in dependency order, or in "
+    "the order the stages happen to be listed in",
     "whether retries and fallbacks MULTIPLY (three providers x three retries is nine calls)",
     "whether compaction preserves decisions and open questions, or keeps the discussion",
     "whether tool output is treated as untrusted input",
@@ -217,54 +253,86 @@ def report_text(root, seen, considered):
     return "\n".join(out)
 
 
+PY_HEADER = ("import requests\n"
+             "system_prompt = 'x'\n"
+             "tools = [{'name': 't', 'description': 'does a thing'}]\n"
+             "messages = []\n")
+JS_HEADER = ("const system_prompt = 'x';\n"
+             "const tools = [{name: 't', description: 'does a thing'}];\n"
+             "const messages = [];\n")
+
+# (label, the check that MUST fire, filename, body)
+PLANTS = [
+    ("unbounded-loop", "unbounded-loop", "agent.py",
+     PY_HEADER + "while True:\n    pass\n"),
+    ("tool-no-description", "tool-no-description", "agent.py",
+     PY_HEADER + "T = [{'name': 'a', 'description': ''}]\n"),
+    ("swallowed-error", "swallowed-error", "agent.py",
+     PY_HEADER + "try:\n    x = 1\nexcept Exception:\n    pass\n"),
+    ("no-timeout", "no-timeout", "agent.py",
+     PY_HEADER + "r = requests.get('https://example.com')\n"),
+    ("hardcoded-model", "hardcoded-model", "agent.py",
+     PY_HEADER + "a = 'claude-opus-4'\nb = 'claude-opus-4'\n"),
+    ("unguarded-fanout (asyncio)", "unguarded-fanout", "agent.py",
+     PY_HEADER + "out = await asyncio.gather(*(run(t) for t in tasks))\n"),
+    ("unguarded-fanout (promise)", "unguarded-fanout", "agent.js",
+     JS_HEADER + "const out = await Promise.all(tasks.map(t => run(t)));\n"),
+]
+
+# A detector that fires on the defect AND on its fix has no discriminating power. Each
+# clean fixture is the half of the evidence that says which one this is.
+CLEAN = [
+    ("the ordinary correct file", "agent.py",
+     PY_HEADER + "for _ in range(10):\n    pass\n"
+     "r = requests.get('https://example.com', timeout=5)\n"),
+    ("a fan-out that DOES capture its branches", "agent.py",
+     PY_HEADER + "for _ in range(10):\n    pass\n"
+     "out = await asyncio.gather(*(run(t) for t in tasks), return_exceptions=True)\n"),
+]
+
+
 def self_test():
     """Plant each defect and require the matching check to fire.
 
     A detector nobody has watched fire is not evidence that it works, and every plant
     asserts it changed something so a reworded fixture fails HERE rather than reporting a
     healthy checker as broken.
+
+    Two things the shape of this function is deliberate about. A detector that reads two
+    languages gets a plant in **each** — one passing shape is not evidence about the
+    other. And every run also asserts silence on the CORRECT shape of the same defect,
+    which is what separates a detector from a keyword search.
     """
     import tempfile
-    header = ("import requests\n"
-              "system_prompt = 'x'\n"
-              "tools = [{'name': 't', 'description': 'does a thing'}]\n"
-              "messages = []\n")
-    cases = {
-        "unbounded-loop": header + "while True:\n    pass\n",
-        "tool-no-description": header + "T = [{'name': 'a', 'description': ''}]\n",
-        "swallowed-error": header + "try:\n    x = 1\nexcept Exception:\n    pass\n",
-        "no-timeout": header + "r = requests.get('https://example.com')\n",
-        "hardcoded-model": header + "a = 'claude-opus-4'\nb = 'claude-opus-4'\n",
-    }
     failures = 0
-    for kind, body in cases.items():
+    for label, kind, fname, body in PLANTS:
         FINDINGS.clear()
         with tempfile.TemporaryDirectory() as d:
-            p = os.path.join(d, "agent.py")
-            with open(p, "w", encoding="utf-8") as fh:
+            with open(os.path.join(d, fname), "w", encoding="utf-8") as fh:
                 fh.write(body)
-            assert agentish(body), f"PLANT DID NOT LAND: fixture for {kind} is not agent-related"
+            assert agentish(body), f"PLANT DID NOT LAND: fixture for {label} is not agent-related"
             scan(d)
         got = {f["check"] for f in FINDINGS}
         if kind in got:
-            print(f"  OK   {kind}: detected")
+            print(f"  OK   {label}: detected")
         else:
-            print(f"  FAIL {kind}: NOT detected (found {sorted(got) or 'nothing'})")
+            print(f"  FAIL {label}: NOT detected (found {sorted(got) or 'nothing'})")
             failures += 1
-    # and a clean file must produce nothing, or every finding above is noise
-    FINDINGS.clear()
-    with tempfile.TemporaryDirectory() as d:
-        with open(os.path.join(d, "agent.py"), "w", encoding="utf-8") as fh:
-            fh.write(header + "for _ in range(10):\n    pass\n"
-                     "r = requests.get('https://example.com', timeout=5)\n")
-        scan(d)
-    if FINDINGS:
-        print(f"  FAIL clean file produced {len(FINDINGS)} finding(s): "
-              f"{[f['check'] for f in FINDINGS]}")
-        failures += 1
-    else:
-        print("  OK   clean file: silent")
-    print(f"\nself-test: {len(cases) + 1 - failures}/{len(cases) + 1} passed")
+    for label, fname, body in CLEAN:
+        FINDINGS.clear()
+        with tempfile.TemporaryDirectory() as d:
+            with open(os.path.join(d, fname), "w", encoding="utf-8") as fh:
+                fh.write(body)
+            assert agentish(body), f"CLEAN FIXTURE NOT READ: {label} is not agent-related"
+            scan(d)
+        if FINDINGS:
+            print(f"  FAIL {label}: produced {len(FINDINGS)} finding(s): "
+                  f"{[f['check'] for f in FINDINGS]}")
+            failures += 1
+        else:
+            print(f"  OK   {label}: silent")
+    total = len(PLANTS) + len(CLEAN)
+    print(f"\nself-test: {total - failures}/{total} passed")
     return 1 if failures else 0
 
 

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

@@ -5,13 +5,14 @@ description: >-
   use, an AI pipeline — or when metering and billing the LLM access it burns. Covers tool-
   calling loops, multi-stage pipelines with human checkpoints, provider routing with fallback
   and retry, four-layer memory with confidence decay, context budgets, sub-agent coordination
-  and error hierarchies; for resale: tiered wallets, the single markup boundary, two-phase
-  commit across a database and a provider API, spend-delta polling, budget and loop guardrails,
+  and error hierarchies; the work as a graph — parallel layers, fake edges, a checker before
+  a convergence; for resale: tiered wallets, the single markup boundary, two-phase commit
+  across a database and a provider API, spend-delta polling, budget and loop guardrails,
   per-tenant key lifecycle. Triggers - "agent", "orchestrator", "tool calling", "sub-agent",
   "LLM router", "fallback chain", "human in the loop", "memory layer", "LLM billing", "token
-  wallet", "агент", "оркестратор", "суб-агент", "роутер моделей", "человек в цикле", "слой
-  памяти", "биллинг LLM", "лимит бюджета". Not for a single LLM call in a script, or for prompt
-  wording.
+  wallet", "checker node", "агент", "оркестратор", "суб-агент", "роутер моделей", "человек в
+  цикле", "слой памяти", "биллинг LLM", "граф задач". Not for a single LLM call in a script,
+  or for prompt wording.
 ---
 
 # Agent Orchestrator — Production Best Practices
@@ -59,7 +60,7 @@ class AgentContext:
     connection_config: ... | None   # external resource config
     user_id: str | None
     preferred_provider: str | None  # e.g. "openrouter"
-    model: str | None               # e.g. "openai/gpt-4o"
+    model: str | None               # e.g. "<provider>/<model-id>"
     extra: dict[str, Any]           # pipeline_action, flags, overrides
 ```
 
@@ -143,40 +144,28 @@ else:
 
 ## 3. Meta-Tools (Orchestrator-Level)
 
-Define tools that **delegate to sub-agents**, not execute directly:
-
-```python
-QUERY_DATABASE_TOOL = Tool(
-    name="query_database",
-    description="Query the connected database. Handles SQL generation, validation, execution.",
-    parameters=[ToolParameter(name="question", type="string", description="Data question")]
-)
-ASK_USER_TOOL = Tool(
-    name="ask_user",
-    description="Ask the user a structured clarification question.",
-    parameters=[
-        ToolParameter(name="question", type="string", ...),
-        ToolParameter(name="question_type", type="string",
-                      enum=["yes_no", "multiple_choice", "free_text"]),
-        ToolParameter(name="options", type="string", required=False),
-    ]
-)
-```
-
-**Assemble tools dynamically** based on available capabilities:
+The orchestrator's tools **delegate to sub-agents** rather than execute:
+`query_database` takes a question in natural language and the SQL agent behind it owns
+generation, validation and execution. One parameter, one responsibility, and the caller
+never learns the sub-agent exists.
 
 ```python
 def get_tools(*, has_db=False, has_kb=False, has_mcp=False) -> list[Tool]:
+    """Assembled per request from the same capability flags that build the prompt (§10)."""
     tools = []
-    if has_db:
-        tools.extend([QUERY_DB, PROCESS_DATA, MANAGE_RULES, ASK_USER])
-    if has_kb:
-        tools.append(SEARCH_CODEBASE)
-    if has_mcp:
-        tools.append(QUERY_MCP)
+    if has_db:  tools.extend([QUERY_DB, PROCESS_DATA, MANAGE_RULES, ASK_USER])
+    if has_kb:  tools.append(SEARCH_CODEBASE)
+    if has_mcp: tools.append(QUERY_MCP)
     return tools
 ```
 
+Two rules that are this layer's and not the prompt's: **a capability the request does not
+have contributes no tool**, and every enum a tool accepts is closed at the schema
+(`ask_user`'s `question_type` is `yes_no | multiple_choice | free_text`, never free
+prose). How to *describe* a tool so the model picks the right one — the sentence naming
+when to use it, and the neighbour it is confused with — is
+`agent-harness/references/tools.md`.
+
 ---
 
 ## 4. Sub-Agent Retry and Validation
@@ -240,8 +229,8 @@ async def detect_complexity_adaptive(question, llm, history) -> bool:
 ### Pipeline Components
 
 ```
-QueryPlanner   → (single LLM call) → ExecutionPlan (ordered stages)
-StageExecutor  → runs stages sequentially with validation + retry
+QueryPlanner   → (single LLM call) → ExecutionPlan (stages + their depends_on)
+StageExecutor  → runs stages in DEPENDENCY LAYERS with validation + retry (§13)
 StageValidator → checks data shape, row bounds, cross-stage consistency
 StageContext   → in-memory state (plan, results per stage, user feedback)
 PipelineRun    → DB-persisted state for resume/retry across requests
@@ -250,21 +239,27 @@ PipelineRun    → DB-persisted state for resume/retry across requests
 ### Checkpoint Pattern (Human-in-the-Loop)
 
 ```python
-for idx, stage in enumerate(plan.stages):
-    result = await execute_with_retries(stage, context)
-    validation = validator.validate(stage, result, stage_ctx)
+for layer in plan.layers():                       # Kahn over depends_on — never list order
+    results = await run_layer(layer, context)     # execute_with_retries per stage, together
 
-    if not validation.passed:
-        retried = await retry_failed_validation(stage, context, validation)
-        if retried is None:
-            return StageFailedResult(stage, validation)  # ask user
-        result = retried
+    for i, (stage, result) in enumerate(zip(layer, results)):
+        validation = validator.validate(stage, result, stage_ctx)
+        if not validation.passed:
+            results[i] = await retry_failed_validation(stage, context, validation)
+            if results[i] is None:
+                return StageFailedResult(stage, validation)   # ask user
 
-    stage_ctx.set_result(stage.id, result)
+    if len(layer) > 1:                            # cheap per-stage checks ran first; this
+        verdict = checker.check(results)          # one is the cross-item gate (§13)
+        if not verdict.passed:
+            return StageFailedResult(layer, verdict)  # nothing converges on a flagged output
 
-    if stage.checkpoint:
+    for stage, result in zip(layer, results):
+        stage_ctx.set_result(stage.id, result)
+
+    if any(s.checkpoint for s in layer):
         persist_to_db(pipeline_run_id, stage_ctx)
-        return CheckpointResult(stage, result)  # pause for user review
+        return CheckpointResult(layer, results)   # pause for user review
         # User responds: "continue" | "modify" | "retry"
 ```
 
@@ -329,37 +324,22 @@ a floor.
 mode cross a compaction boundary as copied typed blocks, not prose (§12).
 ## 8. Self-Learning Feedback Loops
 
-### Cycle 1: Automatic (Validation Loop)
-
-After every SQL execution cycle, heuristic extractors analyze the attempt sequence:
-
-| Extractor | Detects | Creates |
-|-----------|---------|---------|
-| Table preference | Wrong table A fixed to B | "Use `B` instead of `A`" |
-| Column correction | column_not_found → suggested col | "Use `full_name` not `user_name`" |
-| Format discovery | Division by 100/1000 added | "Amounts in cents, divide by 100" |
-| Schema gotcha | `deleted_at IS NULL` added | "Soft-delete: filter active records" |
-| Performance hint | Timeout fixed by LIMIT/date filter | "Always add LIMIT to this table" |
-
-LLM-based deep analysis (3+ attempts, 1hr cooldown) for cross-query patterns.
-
-### Cycle 2: User Feedback
+Three cycles feed layers 3 and 4, and they differ by what supplies the signal:
 
-```python
-# Thumbs down → analyze_negative_feedback() → learning
-# Data validation:
-#   confirmed  → store benchmark
-#   approximate → benchmark + session note (deviation details)
-#   rejected   → learning + note + flag stale benchmark
-#     Categorize rejection: currency/format → data_format, filter → schema_gotcha,
-#                           table → table_preference, join → schema_gotcha
-```
+| Cycle | Signal | Produces |
+|---|---|---|
+| **Validation** | the attempt sequence of a call that failed and was then fixed | a learning, extracted by heuristic — the wrong table, a renamed column, a unit divisor, a soft-delete filter, a missing `LIMIT`. Deep LLM analysis only past 3 attempts, on a cooldown |
+| **User feedback** | a thumbs-down, or a data verdict of confirmed / approximate / rejected | a benchmark, a session note with the deviation, or a learning plus a flag on the now-stale benchmark |
+| **Lifecycle** | time, and contradiction | decay, conflict resolution by negation flip, and promotion of a pattern seen on two independent resources |
 
-### Cycle 3: Knowledge Lifecycle
+The extractors, the exact confidence arithmetic and the promotion query live in
+`references/patterns.md` — **Learning Extraction Heuristics**, **Confidence Management**
+and **Cross-Resource Learning Transfer** — and not here, because a decay rate is a
+constant to tune and a constant with two homes is one that will disagree with itself.
 
-- **Decay**: stale learnings -0.02/month, notes -0.1/60 days, insights -0.05/30 days
-- **Conflict resolution**: negation flips deactivate old conflicting lessons
-- **Global promotion**: patterns on 2+ resources promoted project-wide
+**The rule the whole section exists for:** a learning is written from a **contrast** — the
+attempt that failed beside the attempt that worked — never from a single successful run.
+A system that learns from its successes learns its own habits.
 
 ---
 
@@ -383,39 +363,26 @@ class WorkflowTracker:
 # orchestrator:sql_agent, orchestrator:llm_retry, orchestrator:warning
 ```
 
-Stream final answer text in chunks for typing effect:
-
-```python
-async def stream_tokens(wf_id, text, chunk_size=12):
-    for i in range(0, len(text), chunk_size):
-        await tracker.emit(wf_id, "token", "streaming", text[i:i+chunk_size])
-```
+The final answer streams in chunks as `token` events on the same bus — a typing effect is
+a chunked emit, not a second mechanism. What makes the feed reliable rather than decorative
+is in `references/runtime.md`: a monotonic id per event so a reconnecting client can resume,
+and the feed being a **view over the durable trace** rather than the record itself.
 
 ---
 
 ## 10. Dynamic System Prompts
 
-Build system prompts dynamically based on available capabilities:
+**Assemble the prompt from the capabilities that are actually present**, in the same pass
+that assembles the tools (§3): one section naming each live capability, the resource map
+if there is one, the current learnings, then the guidelines. A prompt that describes a
+tool the agent was not given is how a model spends a turn calling something that is not
+there.
 
-```python
-def build_system_prompt(*, project_name, db_type, has_connection, has_kb, table_map,
-                        project_overview, recent_learnings):
-    sections = [f"You are an AI data assistant for '{project_name}'."]
-    sections.append("AVAILABLE CAPABILITIES:")
-    if has_connection:
-        sections.append("- query_database: ... SQL agent handles everything")
-        sections.append("- process_data: ... enrich/aggregate/filter")
-        sections.append("- manage_rules: ... CRUD project rules")
-    if has_kb:
-        sections.append("- search_codebase: ... RAG over indexed code")
-
-    if table_map:
-        sections.append(f"DATABASE TABLES: {table_map}")
-    if recent_learnings:
-        sections.append(recent_learnings)  # "AGENT LEARNINGS: ..."
-    sections.append("GUIDELINES: ...")  # routing rules, verification protocol
-    return "\n".join(sections)
-```
+What belongs in that text, at what altitude, and how to enumerate the vocabulary so the
+agent stops inventing status values is the **`agent-harness`** skill's
+`agent-harness/references/system-prompt.md` — one home, and it is not this one. What is *this* skill's
+is the wiring: the prompt is rebuilt per request from the same capability flags the tool
+list is built from, so the two can never disagree.
 
 **Data Verification Protocol** (inject when DB connected):
 - First-time metrics: ask user "Do these numbers match expectations?"
@@ -461,6 +428,33 @@ transcript.
 
 ---
 
+## 13. The Work as a Graph
+
+Before the loop, the pipeline or the sub-agents: **decide the shape.** A node is one unit
+of work; an edge is a dependency, and an edge carries data. The full model, the source it
+comes from, and what this host actually executes are in
+[`references/graph-engineering.md`](references/graph-engineering.md).
+
+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.
+- **`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
+  rather than deadlocking the run.
+- **A parallel layer needs a checker before its convergence.** Three branches run, one
+  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.
+
+---
+
 ## Checklist — Building a New Orchestrator
 
 - [ ] Shared `AgentContext` dataclass with all sub-agents
@@ -485,6 +479,10 @@ transcript.
 - [ ] `ask_user` clarification mechanism
 - [ ] Graceful degradation (partial answers on context overflow or max iterations)
 - [ ] Compaction ladder, tool-pair-safe boundaries, typed carryover, output offload
+- [ ] Every declared dependency names the data it carries — the fake-edge test run once
+- [ ] Plans executed in dependency layers, not in the order the stages were listed
+- [ ] A checker between every parallel layer and the node that consumes it, and that
+      checker watched refusing a planted bad input at least once
 
 ---
 
@@ -496,6 +494,7 @@ stays an index and the two cannot drift apart.
 
 | File | Read it when |
 |---|---|
+| [`references/graph-engineering.md`](references/graph-engineering.md) | you are deciding the **shape of the work** — the fake-edge test, the diamond, the checker node, static versus dynamic, and what the host actually runs |
 | [`references/patterns.md`](references/patterns.md) | you need the **data models and algorithms** under the body |
 | [`references/context-engineering.md`](references/context-engineering.md) | the loop is **running out of window** |
 | [`references/runtime.md`](references/runtime.md) | the agent must **survive a crash, a pause, a second message or a schedule** |

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

@@ -0,0 +1,327 @@
+# Graph engineering — deciding the shape of the work before doing it
+
+**Load this when** a job has more than two steps and you are about to write them in a
+line: choosing between a chain and a graph, finding the dependencies that are not real,
+placing a check between a parallel layer and the node that consumes it, or deciding
+whether the structure may be discovered while it runs.
+
+**Spec pinned:** *Graph Engineering with Claude*, `https://x.com/Mahaximus_/status/2082442856417956173`
+(published 2026-07-29); Claude Code `CHANGELOG.md` v2.1.154 – v2.1.229 · read 2026-08-15
+
+`SKILL.md` §2 owns the tool-calling loop and §5 the multi-stage pipeline. Both assume
+the shape is already decided. **This file is how it gets decided**, and it is upstream of
+every constant in the rest of the pack: a threshold tuned inside the wrong shape is a
+well-measured answer to the wrong question.
+
+## Contents
+
+- [The source, and what this file adds](#the-source-and-what-this-file-adds)
+- [1. Node and edge](#1-node-and-edge)
+- [2. Your loop is already a graph, and most of its edges are fake](#2-your-loop-is-already-a-graph-and-most-of-its-edges-are-fake)
+- [3. The fake-edge test](#3-the-fake-edge-test)
+- [4. The diamond](#4-the-diamond)
+- [5. Two ways a diamond fails silently](#5-two-ways-a-diamond-fails-silently)
+- [6. The checker node](#6-the-checker-node)
+- [7. Static or dynamic](#7-static-or-dynamic)
+- [8. When not to build a graph at all](#8-when-not-to-build-a-graph-at-all)
+- [9. What Claude Code actually executes](#9-what-claude-code-actually-executes)
+- [10. Barrier or no barrier](#10-barrier-or-no-barrier)
+- [11. Project defaults, written once](#11-project-defaults-written-once)
+- [12. The source's four diagrams, and what each one is for](#12-the-sources-four-diagrams-and-what-each-one-is-for)
+- [Where this file disagrees with its source](#where-this-file-disagrees-with-its-source)
+
+## The source, and what this file adds
+
+The model below — node, edge, the fake-edge test, the diamond, the checker node, static
+versus dynamic — is taken from the article pinned above. It is the clearest short
+statement of the idea available, and the link is kept so the original can be re-read
+rather than remembered through this summary.
+
+Four things are **this pack's**, not the source's, and each is marked where it appears:
+
+| Added here | Why the source could not carry it |
+|---|---|
+| §9 — what the host actually runs, with version evidence | the article's one operational claim aged out six weeks after publication (see §9) |
+| §10 — the barrier distinction | the article's diamond has a barrier at every convergence; most convergences do not need one |
+| §6 — what a checker costs, and when it is a rubber stamp | a check nobody measures is a node that always says yes |
+| §7 — the auditability rule as a **hard** rule, not a preference | this pack's own doctrine is that a green nobody watched fail is not evidence |
+
+## 1. Node and edge
+
+**A node is one unit of work.** One input, one output, one job. Not *"research the topic,
+summarise it, and check the sources"* — that is three nodes wearing one name. The
+smaller and more defined the job, the more useful the node, because a node is also the
+unit you retry, cache, review and replace.
+
+**An edge is a dependency, and it carries data.** It exists when the second node
+genuinely consumes what the first produced. Not when the second merely *happens after*
+the first.
+
+That distinction is the whole discipline. Write it on the edge and it stops being
+abstract: `research --findings--> write --draft--> verify`. **An edge you cannot label
+with what crosses it is not an edge.**
+
+## 2. Your loop is already a graph, and most of its edges are fake
+
+A prompt that says *"research this, then summarise, then draft"* is a graph — a single
+unbranching chain in which every step waits for its predecessor. It is correct. It is
+also the slowest possible arrangement of that work and the most brittle: one bad step
+takes the whole chain, and nothing runs while any step is running.
+
+The first move is therefore not to learn a new structure. It is to look at the one you
+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.
+
+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.
+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.
+
+**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.
+
+## 4. The diamond
+
+One node fans out into several independent nodes; those all feed one node that combines
+them. Drawn out, it is a diamond, and it is the shape that makes graphs worth the setup.
+
+```
+                 ┌──────────┐
+                 │  SPLIT   │
+                 └────┬─────┘
+        ┌─────────────┼─────────────┐
+        ▼             ▼             ▼          ← parallel layer
+   ┌─────────┐   ┌─────────┐   ┌─────────┐
+   │ source1 │   │ source2 │   │ source3 │
+   └────┬────┘   └────┬────┘   └────┬────┘
+        └─────────────┼─────────────┘
+                      ▼
+                 ┌──────────┐
+                 │SYNTHESIZE│                  ← convergence
+                 └──────────┘
+```
+
+The convergence waits for the slowest branch, not for the sum of all of them.
+
+**Two rules, and both have to hold:**
+
+1. **The parallel nodes are genuinely independent** — no fake edge dressed as a real one,
+   and no shared mutable state. Two "independent" workers writing one file are one node
+   with a race in it.
+2. **The convergence genuinely needs all of them.** If it needs only the first to answer,
+   the rest are paid-for waste and you wanted a race, not a diamond.
+
+Once you look for it, the shape is everywhere there is a *gather-then-combine*: research,
+multi-file review, market analysis, a fan of checks over one artifact.
+
+## 5. Two ways a diamond fails silently
+
+Both are failures **of the convergence**, which is why sequential chains do not have
+them.
+
+**A bad node goes undetected.** Three branches run, one returns a hallucination, an empty
+result or a misread file, and that output arrives at the synthesis node beside two good
+ones. The synthesis node does not know one of its inputs is wrong. It produces a
+confident answer built partly on garbage. Parallelism bought the speed by deleting the
+checkpoints where a human would have noticed.
+
+**The error cascades and dilutes.** In a chain, a bad step produces a visibly bad output.
+At a convergence, the bad output is *mixed* with good ones, so the damage is spread thin
+and the trace back to its source is gone. By the time anything looks wrong, three nodes
+have averaged it into plausibility.
+
+Both are the same defect: **the convergence trusts its inputs because they arrived.**
+
+## 6. The checker node
+
+A node between the parallel layer and the convergence whose only job is to decide whether
+each output may proceed. It synthesises nothing and writes nothing. It answers *is this
+usable* and then passes, flags, retries or drops.
+
+Five things it must catch — the list is the contract, and a checker that cannot say which
+of the five it is asserting is not a checker:
+
+1. **Empty or null** — the node returned nothing usable.
+2. **Mutually contradictory** — two outputs that cannot both be true.
+3. **Off-topic** — an output that answers a different question than the one asked.
+4. **Under-confident** — a confidence signal below the bar for the downstream decision.
+5. **Malformed** — a shape that will break the convergence node's parsing.
+
+Three of the five are code checks (1, 4, 5) and cost nothing; only 2 and 3 need a model.
+Run them in that order — this is `agent-evals` §5's *cheap checks first*, applied to a
+position in the graph rather than to a test suite.
+
+**What a checker costs, and how it turns into a rubber stamp — this pack's addition.** A
+checker is a node, so it has the failure mode of every node: it can be wrong. A model
+checker that has never been shown a bad input will pass everything, and a graph with a
+checker that always says yes is strictly worse than one with no checker, because the
+absent checkpoint has been replaced by a false one. So:
+
+- **Give it a planted bad input at least once and watch it refuse.** Same rule as any
+  other guard in this family.
+- **Record its verdicts as scores with a source** (`agent-evals` §7), or you can never
+  ask afterwards how often it fired.
+- **A checker that has never rejected anything is a finding**, not a reassurance.
+
+**Wire the convergence to the checker, not to the layer.** The synthesis node depends on
+the checker; the checker depends on the branches. If synthesis also takes a direct edge
+from a branch, the gate has a bypass and the shape is decoration.
+
+## 7. Static or dynamic
+
+A **static** graph has its nodes and edges decided before it runs. A **dynamic** graph
+grows: a node finishes, looks at what it found, and decides what should come next.
+
+| Reach for | When |
+|---|---|
+| **static** | the task repeats and the structure is the same each time |
+| **static** | predictability and speed matter more than flexibility |
+| **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.
+
+**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
+first.
+
+## 8. When not to build a graph at all
+
+The honest cost table. A graph is not free, and for a one-off it usually loses:
+
+| | Chain | Graph |
+|---|---|---|
+| Time to build | low | higher — the dependencies have to be worked out |
+| Time to run | the sum of the steps | the longest path |
+| Debugging | easy — one line to walk | harder — concurrent state, diluted errors |
+| Mid-run failure | poor, but visible immediately | good **only if** there is a checker |
+| A one-off task | right answer | overkill |
+| Something you run weekly | works | better, and the setup amortises |
+| Growth in task size | does not scale | scales |
+
+**Build the graph when the work repeats, or when a mid-run error is expensive enough that
+the checker pays for itself.** Otherwise write the chain and move on — this is
+`agent-harness`'s *start at the simplest thing that works* applied to shape.
+
+## 9. What Claude Code actually executes
+
+**This section is the pack's, not the source's, and it exists because the source's one
+operational claim has since changed.** The article tells the reader that Claude Code has
+a `workflow` keyword which parses a YAML block of `nodes:` and `depends_on:` and
+parallelises it. Two corrections, both from the vendor's own changelog:
+
+| Version | Entry (quoted from `anthropics/claude-code` `CHANGELOG.md`) |
+|---|---|
+| v2.1.154 | "Introducing dynamic workflows: ask Claude to create a workflow and it orchestrates work across tens to hundreds of agents in the background" |
+| v2.1.160 | "Renamed the dynamic-workflow trigger keyword from `workflow` to `ultracode`. The word 'workflow' no longer triggers a run; asking for one in your own words still works" |
+| v2.1.178 | the keyword "trigger[s] only on explicit phrases like 'run a workflow' or 'workflow:', not on any mention of the word" |
+| v2.1.219 | dynamic workflows "default to a medium size guideline (aim for fewer than 15 agents)"; settable via `workflowSizeGuideline` |
+| v2.1.229 | fan-outs "stagger same-prefix sibling agents so subsequent agents read the cached prompt prefix instead of re-paying it" |
+
+So the keyword named in the article stopped being the keyword in v2.1.160, and the
+opt-in today is `ultracode` or an explicit phrase.
+
+**And the YAML is not what runs.** The host does not parse `nodes:`/`depends_on:`. It
+authors and executes a **script** whose primitives are the real contract:
+
+| Primitive | Is | Note |
+|---|---|---|
+| `agent(prompt, opts)` | one subagent | `opts.schema` forces a validated object back, so downstream stages get data, not prose to parse |
+| `parallel(thunks)` | concurrent, **with a barrier** | awaits all; a thrower resolves to `null` rather than rejecting the call |
+| `pipeline(items, ...stages)` | each item through all stages, **no barrier** | item A can be in stage 3 while B is still in stage 1 |
+| `phase(title)` | a progress grouping | display, not semantics |
+| `isolation: "worktree"` | a private checkout per agent | the only safe way to fan out writers |
+
+Concurrency is capped at `min(16, cores − 2)` per run, and a run's total agents at 1000.
+Passing 100 items is fine — they queue.
+
+**Why this matters for the model above:** the article's diamond is `parallel()`, and the
+next section is the distinction it does not draw.
+
+## 10. Barrier or no barrier
+
+**This section is the pack's.** A convergence node is a barrier: nothing downstream of it
+starts until every branch has finished. The article treats that as the definition of a
+diamond. It is actually a *choice*, and the wrong default.
+
+A barrier is correct only when the downstream stage needs **cross-item** context:
+
+- deduplicating or merging across the whole result set before expensive work;
+- an early exit that depends on the total ("zero findings → skip verification");
+- a stage whose prompt genuinely compares one item against the others — **which is
+  exactly what a checker node does**, and is why the checker is a legitimate barrier.
+
+A barrier is **not** justified by:
+
+- *"I need to flatten or filter the results first"* — do that inside a stage;
+- *"the stages are conceptually separate"* — separate is not the same as synchronised;
+- *"it reads more cleanly"* — the cost is real. With five branches where the slowest takes
+  three times the fastest, a barrier idles the four fast ones for two thirds of the wait.
+
+The rule: **pipeline by default; barrier when a stage names the cross-item fact it
+needs.** If it cannot name one, it does not need one.
+
+## 11. Project defaults, written once
+
+Anything you run more than twice deserves its graph conventions recorded where the agent
+reads them (`CLAUDE.md`, or the equivalent for the host), so they are not re-derived per
+session:
+
+```markdown
+## 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.
+- 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.
+- A node that fails pauses the run and reports; nothing downstream consumes a flagged output.
+- Outputs are files with the node's name; the graph passes paths, not transcripts.
+```
+
+The last line is `context-engineering.md`'s *filesystem as context* stated as a graph
+rule: an edge that carries a path costs a few tokens, and an edge that carries a
+transcript costs the window.
+
+## 12. The source's four diagrams, and what each one is for
+
+The article carries four hand-drawn figures. They are not decoration — each one is doing
+a specific job, and knowing which one saves re-reading the prose:
+
+| Figure | What it shows | The job it does |
+|---|---|---|
+| **Cover — "Graph Engineering explained"** | `START` (define the task) → `SPLIT` (break into nodes) → a fan of three workers labelled *research / compare / check* → `CHECKER` (catch errors early) → `OUTPUT` (one clean answer) | The whole argument in one line, and the only figure in which the checker appears as a first-class stage rather than an afterthought |
+| **Node / edge** | Three boxes — `Research` (in: topic, out: findings) → `Write` (in: findings, out: draft) → `Verify` (in: draft, out: final) — with `NODE` and `EDGE` labelled, and **the arrows themselves labelled with the data they carry** | Makes §1 concrete: the payload written on the arrow is what turns "comes after" into "depends on". This is the figure to copy when teaching the model |
+| **The diamond** | One `RESEARCH` node fanning into `SOURCE 1/2/3` (bracketed *parallel layer*), all three converging on `SYNTHESIZE` | The ideal shape, drawn **before** the failure modes — deliberately without a checker, which is what §5 then attacks |
+| **Workflow — how the code runs** | The same shape in code terms: `research_a/b/c` in a parallel layer, three arrows into `checker` annotated *waits for all three*, one arrow from `checker` into `compare` | The repaired shape. Its point is the single edge out of the checker: `compare` depends on the **gate**, not on the branches — §6's last paragraph, drawn |
+
+## Where this file disagrees with its source
+
+- **The keyword.** The source's `workflow` is `ultracode` since v2.1.160 (§9). Treated as
+  a version-dated fact rather than a correction of the author: it was true when written.
+- **The YAML.** The source presents `workflow:` / `nodes:` / `depends_on:` as a syntax the
+  host parses. It is a way of *describing* a graph in a prompt, and it works for that; the
+  execution contract is the script in §9.
+- **The barrier.** The source's diamond always synchronises. This file makes the barrier a
+  decision with a named justification (§10).
+- **The checker's own reliability.** The source introduces the checker and stops. This
+  file requires it to have been watched refusing a planted input, and treats a checker
+  that has never rejected anything as a finding (§6).

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

@@ -248,7 +248,7 @@ Map your public model names to provider ids in **one** function, and give every
 provider a default and a fallback:
 
 ```
-toUpstreamModel(provider, model)   // "gpt-4o" → "openai/gpt-4o"
+toUpstreamModel(provider, model)   // "<public-name>" → "<provider>/<upstream-id>"
 getDefaultModel(provider)          // when the caller names none
 getFallbackModels(provider)        // ordered, tried on 5xx / overload
 ```

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

@@ -139,6 +139,10 @@ class ExecutionPlan:
     @classmethod
     def from_json(cls, raw: str) -> ExecutionPlan: ...
 
+    def layers(self) -> list[list[PlanStage]]:
+        """Kahn's algorithm over `depends_on`. Each returned list may run concurrently."""
+        ...
+
 @dataclass
 class StageResult:
     stage_id: str
@@ -149,6 +153,14 @@ class StageResult:
     error: str | None = None
 ```
 
+**`depends_on` is a claim the executor has to honour.** A plan that declares dependencies
+and is then executed in list order has serialised itself: `stages[3]` waits for
+`stages[2]` whether or not it consumes anything it produced. Execute by **layer** —
+everything whose dependencies are satisfied goes together — and the declaration starts
+paying for itself. Two rules come with it: a cycle is a plan defect and fails the plan
+rather than deadlocking the run, and a layer of more than one stage needs the convergence
+check in `graph-engineering.md` §6 before anything downstream consumes it.
+
 ---
 
 ## Validation Loop (SQL Execution)
@@ -187,21 +199,33 @@ for attempt in range(1, max_retries + 1):
 
 ## Context Window Sizes
 
+**Do not ship a table of model ids.** This file carried one until 2026-08-15 — nine
+vendor ids with their windows, and a `DEFAULT_CONTEXT_WINDOW` of 16 000. Every number in
+it was correct when written and none of it survived a year: generations shipped, ids were
+renamed, long-context variants appeared under the same family name, and a system reading
+that table would have sized its budget for a window an order of magnitude smaller than
+the one it was actually given. A lookup table of somebody else's identifiers is a cache
+with no invalidation.
+
+**Resolve the window at one boundary instead**, in this order, and let every caller ask
+that boundary rather than a constant:
+
+1. **Configuration** — an explicit per-model entry the operator set. It outranks
+   everything, because it is the only source that can encode a limit you have chosen (a
+   budget cap below the real window, a provider tier).
+2. **The provider** — the model list or metadata endpoint most APIs expose. Fetched once
+   per process, cached with a TTL, refreshed on a miss.
+3. **A conservative floor** for a model nothing knows about, plus a **loud log line**
+   naming the model. A silent default is how a new model runs at a fraction of its
+   window for months with nobody noticing.
+
+The floor is a number to be small about, not accurate about: being early to compact costs
+one avoidable rung of the ladder, and being late costs the request.
+
 ```python
-MODEL_CONTEXT_WINDOWS = {
-    "gpt-4o": 128_000,
-    "gpt-4o-mini": 128_000,
-    "gpt-4-turbo": 128_000,
-    "gpt-4": 8_192,
-    "gpt-3.5-turbo": 16_385,
-    "claude-sonnet-4-20250514": 200_000,
-    "claude-3-5-sonnet-20241022": 200_000,
-    "claude-3-haiku-20240307": 200_000,
-    "claude-3-opus-20240229": 200_000,
-}
-DEFAULT_CONTEXT_WINDOW = 16_000
-
-# Token estimation: tiktoken for OpenAI models, ~4 chars/token fallback
+# Token estimation: a real tokenizer where one is available, ~4 chars/token otherwise.
+# The fallback runs LOW on code, JSON and non-Latin text — see context-engineering.md
+# → Estimating what you have left, and apply the padding factor described there.
 def estimate_tokens(text):
     try:
         import tiktoken