@ssheleg/agent-stack 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## v0.17.0 — the descriptions stop colliding, and the claims get their dates
+
+Wave-2 of the 2026-08-29 family audit (rows AST-02, AST-03, AST-04, AST-06, AST-11), plus
+the harness-engineering externals read 2026-08-30.
+
+- **AST-02: `agent-orchestrator` gives "checker node" back to `agent-evals`.** The quoted
+  trigger appeared verbatim in both descriptions, so the router had two skills advertising
+  one phrase. `agent-evals` owns it; the orchestrator's description already carries "a
+  checker before convergence" in prose, which is the claim it actually makes.
+- **AST-11: the single-word triggers "agent" / "агент" narrow to "agent system" /
+  "агентная система".** A one-word trigger matching every sentence with the word *agent*
+  in it is how a skill teaches the router to route around the boundary its own description
+  draws ("Not for a single LLM call in a script"). The multiword triggers carry the load.
+- **`agent-harness` advertises "ReAct loop" and "react pattern" instead of bare "ReAct"** —
+  a phrase the umbrella's deferred hook trigger can carry without firing on every mention
+  of the React framework. The body prose still explains ReAct by its own name.
+- **AST-06: the harness↔orchestrator boundary names its four seams instead of claiming
+  one.** `agent-harness` §Boundaries said the two skills "meet in one place" while the
+  pack actually crosses at four: orchestrator §3 → harness `tools.md` (describing a tool
+  vs assembling the list), orchestrator §10 → harness `system-prompt.md` (what the prompt
+  says vs rebuilding it per request), harness static-or-dynamic → orchestrator
+  `graph-engineering.md`, and `context-engineering.md` (compaction) vs `system-prompt.md`
+  (filling). The rewrite states explicitly that shape-of-the-work doctrine has ONE home —
+  `agent-orchestrator/references/graph-engineering.md` — and the harness intro stops
+  claiming "the shape of the work" as its own ground, which was the sentence that made
+  both skills owners of one table.
+- **AST-03/AST-04: `agent-interop`'s undated external claims get their dates.** "Moved in
+  the last twelve months", "SDKs and blog posts still document v0.3" and "its own overview
+  page still introduces `binds`" sat undated inside the very section whose rule is *a
+  protocol claim without a date is a guess* — all three now anchor to **2026-08-13**, the
+  stamp every reference in the skill already carries. The neighbourhood table gains a
+  "Verdicts as of 2026-08-13" line, since `test/validate.py` gates stamps only under
+  `references/` and the table lives in SKILL.md.
+- **`agent-harness` cites the outside term for its ground: harness engineering.** OpenAI's
+  harness-engineering article and Anthropic's harness-design article (both read
+  2026-08-30) name the layer this skill covers, with the measured leverage — ARC-AGI-3
+  harness-level changes moved a fixed model 13.3%→38.3% at a sixth of the tokens (as
+  reported 2026-08-30). "harness engineering" joins the description triggers: users will
+  say it. The deeper work is filed, not done: board rows **AST-A1** (coverage check
+  against OpenAI's nine-subsystem taxonomy, identity/approval policy the suspected gap)
+  and **AST-B** (the dated generator-evaluator citation in `agent-evals`, deferred to
+  evals day).
+
+## v0.16.1 — the installers refuse the shadow, and the pack stops mis-selling itself
+
+- **Both installers refuse to write plain copies over an installed plugin.** The family
+  audit of 2026-08-29 reproduced the shadow live: a bare `npx @ssheleg/telegram-dev`
+  created three plain copies in `~/.claude/skills/` while that plugin was enabled — and
+  this member had **no plugin check at all**, in either installer, so a bare
+  `npx @ssheleg/agent-stack` on a machine with the plugin would have shipped **four**
+  shadows, one per skill, each serving its frozen version forever. `bin/agent-stack.js`
+  and `install.sh` now implement make-skill v0.25.0's canon (`distribution.md`, "The
+  installer must refuse the shadow it documents"): detect from the TARGET home's
+  `installed_plugins.json` (keys are `<name>@<marketplace>`, and the two names differ
+  often), keep the `marketplaces/` dir read only as the fallback signal, refuse with
+  exit **3** and a remedy that names the spec read from the JSON
+  (`claude plugin marketplace update agent-stack` + `claude plugin update
+  agent-stack@<marketplace>`, plus the family launcher), offer `--force` as the recorded
+  deliberate override, fail open on a missing or corrupt JSON, and gate only the
+  `~/.claude` write — no other agent has plugins.
+- **`test/installer_test.js` joins `npm test` and CI** — 11 cases against throwaway
+  HOMEs: fresh / rerun-skip / `--force` / unknown-arg, plugin-present refusal (exit
+  code, remedy text, nothing written — all three asserted), a differently-named
+  marketplace in the remedy spec, corrupt JSON failing open, no false refusal on other
+  plugins or an `agent-stack-extra` prefix-collider, the marketplaces-dir fallback, and
+  the same matrix for `install.sh`. Watched failing before trusted: **7 of 11 red**
+  against the pre-fix installers (`git stash` the two, run, pop). The suite follows the
+  house residue rule — a failing case keeps its HOME, and the run ends by saying what it
+  left. It replaces the inline fresh-HOME-only step in `validate.yml`, which is the CI
+  shape that let the plugin-present case go unrun everywhere.
+- **A successful install now says how the next version arrives** — the last line names
+  `npx @ssheleg/agent-stack@latest --force` and the family launcher, in both installers.
+- **AST-01: the plugin stops selling itself as two skills.** `plugin.json` and
+  `marketplace.json` both opened with "Two skills: agent-orchestrator … and agent-evals"
+  while the pack ships **four** — `agent-interop` and `agent-harness` were invisible in
+  `claude plugin details` and on the marketplace. Both descriptions now name all four
+  skills with what each covers.
+
 ## v0.16.0 — the whole survey, not just its taxonomy
 
 v0.15.0 took the taxonomy and the named failure modes. This takes the rest: the write

package/bin/agent-stack.js

@@ -16,6 +16,44 @@ const os = require('os');
 
 const ROOT = path.resolve(__dirname, '..');
 const REPO = 'ssheleg/agent-stack';
+const PLUGIN = 'agent-stack';
+
+// Exit codes are the contract: 0 installed or skipped, 1 corrupted package,
+// 2 usage error, 3 refused — the plugin channel owns this agent (--force overrides).
+const EXIT_PLUGIN_PRESENT = 3;
+
+/**
+ * The plugin spec (`<name>@<marketplace>`) installed for `name` in this home,
+ * or null.
+ *
+ * `installed_plugins.json` is the record of what is actually installed. The
+ * `plugins/marketplaces/<name>` directory under-reports: a marketplace added
+ * from a local `directory` source has no dir there at all, and plugin names
+ * differ from marketplace names, so a check keyed on it stays green while the
+ * shadow lands. Absence and corruption both read as "no plugin": the fresh
+ * HOME is the common case, and an installer that crashes on a parse error
+ * refuses the machines that need it most.
+ */
+function installedPluginSpec(home, name) {
+  try {
+    const raw = fs.readFileSync(
+      path.join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    const plugins =
+      parsed && typeof parsed === 'object' &&
+      parsed.plugins && typeof parsed.plugins === 'object'
+        ? parsed.plugins
+        : parsed;
+    if (!plugins || typeof plugins !== 'object') return null;
+    for (const spec of Object.keys(plugins)) {
+      if (spec === name) return `${name}@${name}`;
+      if (spec.startsWith(name + '@')) return spec;
+    }
+  } catch {
+    // missing or corrupt = no plugin — fail open on absence, never crash
+  }
+  return null;
+}
 
 function usage() {
   console.log(`agent-stack installer
@@ -25,6 +63,12 @@ Usage:
                                        into ~/.claude (skip existing unless --force)
   npx @ssheleg/agent-stack --help
 
+Exit codes:
+  0 installed or skipped   2 usage error
+  1 corrupted package      3 refused: the agent-stack PLUGIN is installed in
+                             this home — plain copies would shadow it (pass
+                             --force to write them anyway)
+
 Other install paths:
   Claude Code plugin:  /plugin marketplace add ${REPO}
                        /plugin install agent-stack@agent-stack
@@ -86,6 +130,41 @@ function main(argv) {
   }
 
   const home = os.homedir();
+
+  // One channel per agent. A plain ~/.claude/skills/<name> beside the installed
+  // agent-stack plugin is two listings of the same skill per skill this pack
+  // ships, and the stale copy wins — the exact shadow make-skill's distribution
+  // canon forbids (§ "The installer must refuse the shadow it documents").
+  // Refuse rather than create it, and refuse LOUDLY: a presence check keyed on
+  // the marketplaces/ dir alone that exits 0 is the fail-open class — a
+  // directory-sourced marketplace has no dir there, plugin names differ from
+  // marketplace names, and exit 0 reads as success to every script above it.
+  // Reproduced live 2026-08-29: a bare `npx @ssheleg/telegram-dev` shipped
+  // three shadows past exactly this hole while the plugin was enabled. Only the
+  // ~/.claude write is gated — no other agent has plugins.
+  const spec = installedPluginSpec(home, PLUGIN);
+  const marketplace = path.join(home, '.claude', 'plugins', 'marketplaces', PLUGIN);
+  const viaMarketplaceDir = !spec && fs.existsSync(marketplace);
+  if ((spec || viaMarketplaceDir) && !force) {
+    const found = spec
+      ? `installed as the Claude Code plugin ${spec}\n` +
+        '         (declared in ~/.claude/plugins/installed_plugins.json)'
+      : `registered as a Claude Code marketplace\n         (${marketplace})`;
+    console.error(
+      `refused: agent-stack is already ${found}.\n` +
+      `         Plain copies in ~/.claude/skills/ (${names.join(', ')})\n` +
+      '         would shadow the plugin and serve this frozen version forever.\n' +
+      '         Update the plugin channel instead:\n' +
+      '           claude plugin marketplace update agent-stack\n' +
+      `           claude plugin update ${spec || 'agent-stack@agent-stack'}\n` +
+      '         Family launcher (updates every member, prunes shadow copies):\n' +
+      '           npx --yes sshlg-skills@latest update\n' +
+      '         Pass --force to write the plain copies anyway — a deliberate choice\n' +
+      '         to run two channels, where the stale one wins.'
+    );
+    return EXIT_PLUGIN_PRESENT;
+  }
+
   for (const name of names) {
     installOne(
       `${name} skill`,
@@ -95,6 +174,15 @@ function main(argv) {
       force
     );
   }
+  // The last line says how the next version arrives — "Installed" is not a
+  // complete sentence. Auto-update is off on purpose: this member composes
+  // with its family, and per-marketplace autoUpdate moves each member on its
+  // own clock, into combinations nobody tested together.
+  console.log(
+    '\nUpdates: rerun `npx @ssheleg/agent-stack@latest --force`, or refresh the\n' +
+    'whole family with `npx --yes sshlg-skills@latest update` (every channel,\n' +
+    'and it prunes plain copies that would shadow a plugin).'
+  );
   return 0;
 }
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/plant_guard_test.py"
+    "test": "python3 test/validate.py && python3 test/plant_guard_test.py && node test/installer_test.js"
   },
   "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.",
   "bin": {

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

@@ -1,8 +1,8 @@
 {
   "name": "agent-stack",
   "displayName": "Agent Stack",
-  "description": "Two skills: agent-orchestrator — 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 — run/trace/thread evals, judges, and fixtures grown from production.",
-  "version": "0.16.0",
+  "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.17.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -8,7 +8,8 @@ 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", "static or dynamic", "audit this agent",
+  engineering", "harness engineering", "ReAct loop", "react pattern", "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.
@@ -18,7 +19,13 @@ description: >-
 
 `agent-orchestrator` wires the loop. `agent-evals` proves it behaves. `agent-interop` gets
 it talking to other processes. **This skill is the layer between them and the model: the
-prompt, the tools, and the shape of the work.**
+prompt, the tools, and the choice of technique.** The outside term for this ground is
+**harness engineering** — OpenAI's article of that name (`openai.com/index/harness-engineering`,
+read 2026-08-30) and Anthropic's harness-design guidance
+(`anthropic.com/engineering/harness-design-long-running-apps`, read 2026-08-30) both name
+this same layer, and its leverage is measured: on ARC-AGI-3, harness-level changes alone
+moved a fixed model from 13.3% to 38.3% while spending a sixth of the tokens (as reported
+2026-08-30).
 
 It runs in both directions. Building one and auditing one are the same checklist read
 forwards and backwards, which is why they live together here.
@@ -146,10 +153,22 @@ is then unfalsifiable — including this audit. Say so first, and make it the fi
 
 **Against `agent-orchestrator`.** That skill owns the loop's *plumbing*: iteration guards,
 trimming, sub-agent dispatch, provider routing, memory layers, checkpoints. This one owns
-what the model is *told*. They meet in one place:
-`agent-orchestrator/references/context-engineering.md` covers **compaction** — what to drop
-when the window fills — while this skill's `system-prompt.md` covers what to put there in
-the first place. Filling and emptying, two files.
+what the model is *told*. They meet at four seams, each crossing in exactly one place:
+
+1. **Describing a tool** so the model picks the right one is this skill's
+   `references/tools.md`; assembling the tool *list* per request from capability flags is
+   the orchestrator's §3, which points here for the wording.
+2. **What the prompt says** — altitude, vocabulary, enumerated statuses — is this skill's
+   `references/system-prompt.md`; *rebuilding* that prompt per request, in the same pass
+   as the tools, is the orchestrator's §10.
+3. **The shape of the work** — the static/dynamic table, the fake-edge test, the checker
+   before a convergence — has ONE home, and it is not here:
+   `agent-orchestrator/references/graph-engineering.md`. This skill's static-or-dynamic
+   section stops at the decision and links there for the model.
+4. **The context window:** `agent-orchestrator/references/context-engineering.md` covers
+   **compaction** — what to drop when the window fills — while this skill's
+   `system-prompt.md` covers what to put there in the first place. Filling and emptying,
+   two files.
 
 **Against `agent-evals`.** That skill measures whether an agent behaves, from execution
 records. This one reviews how it was *built*, from its source and prompts. An audit that

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

@@ -24,19 +24,20 @@ registry, and the gateway between them.
 
 ## Rule zero — a protocol claim without a date is a guess
 
-Every one of these specifications moved in the last twelve months, and each moved in a way
-that silently breaks code written against the previous revision. Concretely, and each one
-measured against the live specification rather than recalled:
+Every one of these specifications moved in the twelve months before **2026-08-13** — the
+date every reference below was read — and each moved in a way that silently breaks code
+written against the previous revision. Concretely, and each one measured on that date
+against the live specification rather than recalled:
 
 - MCP replaced the `initialize` handshake with `server/discover` and made the protocol
   **stateless**; a client that opens with `initialize` is speaking a revision that is on its
   way out.
 - MCP **deprecated `sampling`, `roots` and `logging`** — three things an older model will
   reach for first, because for a year they were the interesting part of the client side.
-- A2A renamed its wire surface between v0.x and v1.0, and SDKs and blog posts still document
-  v0.3.
+- A2A renamed its wire surface between v0.x and v1.0, and SDKs and blog posts still
+  documented v0.3 as of 2026-08-13.
 - agentgateway **deprecated `binds`** in favour of `gateways` — while its own overview page
-  still introduces `binds` as a core concept.
+  still introduced `binds` as a core concept as of 2026-08-13.
 
 So: **every reference in this skill opens with a `**Spec pinned:**` line**, and
 `test/validate.py` fails the build without one. That is a mechanical check, not an
@@ -119,6 +120,8 @@ it); prompt wording; a single LLM call in a script.
 ## The neighbourhood — one verdict each
 
 Named so an agent stops guessing, with the verdict stated rather than implied.
+**Verdicts as of 2026-08-13**, the day this skill's references were pinned — this ground
+moves, so re-verify anything marked *watch* before building on it.
 
 | Thing | What it actually is | Verdict |
 |---|---|---|

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

@@ -7,9 +7,9 @@ description: >-
   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,
-  spend-delta polling, budget and loop guards, per-tenant keys. Triggers - "agent",
+  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", "checker node", "агент", "оркестратор",
+  loop", "memory layer", "LLM billing", "token wallet", "агентная система", "оркестратор",
   "суб-агент", "роутер моделей", "человек в цикле", "слой памяти", "биллинг LLM", "граф задач".
   Not for a single LLM call in a script, or prompt wording.
 ---