@ssheleg/agent-stack 0.24.2 → 0.25.1

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+## 0.25.1 — workbench harness contracts, with a bounded ECC transfer
+
+- Distinguish a kernel harness from the operating layer around an existing agent.
+  The family is the latter; skills are components, not an OS security boundary.
+- Add an on-demand `agent-harness` reference for install ownership and loaded
+  state, bounded hooks and failure policy, evidence-bearing handoff, artifact-bound
+  eval receipts, replay limits and scoped learning. Existing family owners remain
+  authoritative; no duplicate runtime, schemas or receipt store is introduced.
+- Attribute the selective ECC review to commit
+  `2b6e839771e53096d8451a213d40dc64ec8acac0`; retain the adoption matrix,
+  source digests, acceptance cases and explicit limits in the research ledger.
+- Version 0.25.0 was not released: its protected tag was mistakenly created
+  at the previous revision after GitHub rejected a merge method. The queued
+  release was cancelled. Version 0.25.1 preserves the tag history and publishes
+  the reviewed change from its actual merged commit.
+- No new hook, network dependency, telemetry or service is installed. Structural
+  checks are not represented as measured improvements in agent outcomes.
+
+## 0.24.3 — the budget stops being estimated, and two skills stop naming a file they do not ship
+
+Hygiene from the 2026-09-13 family audit (HK-11).
+
+- **The body budget is MEASURED.** This gate divided by a calibrated 3.9 chars/token; the
+  calibration drifted. Measured 2026-09-14 against the authority's tokenizer:
+  `agent-evals` estimated **~4961** and measured **4374**; `agent-orchestrator` estimated
+  **~4762** and measured **4309** — two files reported past the working limit with 300+
+  tokens of real headroom. make-skill v0.28.0 closed the same defect in the family
+  auditor by measuring. With no tokenizer installed the check now **discloses** rather
+  than issuing a verdict from the wrong instrument.
+- **`agent-harness` and `agent-interop` named `test/validate.py`** — a repository file
+  that does not ship inside a skill, so it resolves at the repo root and nowhere an
+  installed reader stands. Both say "this pack's repository validator" now.
+- **`agent-harness` declares `compatibility`**: it ships `scripts/audit_agent.py`, and a
+  skill that needs an interpreter says so in front matter.
+- **`plugin.json`'s homepage** matches `package.json` and the forge
+  (`skills.sshlg.me/skills/agent-stack/`) instead of the GitHub URL.
+- **The README names what loads on demand** — 27 reference files, counted per skill from
+  the tree, not stated — and both invocation forms (`/agent-stack:<skill>` and
+  `/<skill>`), because which one resolves depends on how the pack was installed. The
+  installer line said "both skills" over a pack of four.
+
 ## v0.24.2 — the ledger section names the version it ships
 
 The previous patch wrote the ledger section BEFORE bumping the version, so the

package/README.md

@@ -25,7 +25,10 @@ add` puts this pack — at rank 500.
 Production patterns for building AI agent orchestrators — and for billing the
 LLM access they burn.
 
-Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills).
+Part of the [ssheleg agent harness](https://github.com/ssheleg/sshlg-skills):
+a workbench layer of routing, delivery contracts and evidence around existing
+agent hosts. This pack provides its agent-engineering skills. It does not replace
+the host runtime or provide an OS security boundary.
 
 ---
 
@@ -88,7 +91,7 @@ ACP, AGNTCY, AP2, Agent Skills — so an agent stops guessing.
 model, and the one where most agent bugs actually live: *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*. Before adding a
-retry or a sub-agent, it asks four questions about the text. Seven references —
+retry or a sub-agent, it asks four questions about the text. Eight references —
 `system-prompt.md` (right altitude, enumerated vocabulary, and the three things reasoning
 models changed — starting with **do not add chain-of-thought**), `tools.md` (the
 agent–computer interface, with a worked before/after and poka-yoke), `techniques.md`
@@ -98,6 +101,10 @@ environment's job), `audit.md` (seven tracks, evidence tiers, a plan instead of
 plus **`pi.md` and `pi-sdk.md`, the doctrine as a worked implementation**: Pi read end to
 end, each mechanism matched to the rule it instantiates, its divergences named, and the
 eight extension seams where a permission gate or a context rewrite can actually live.
+`workbench-contracts.md` adds the operating layer around a host: managed install
+ownership, bounded hooks, evidence-bearing handoff, artifact-bound evaluation and
+observation limits, adapted selectively from a pinned ECC review. These are design
+contracts; the pack installs no new hook, service or telemetry collector.
 
 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 —
@@ -160,7 +167,7 @@ waterfall, and model-routing precedence.
 /plugin install agent-stack@agent-stack
 ```
 
-**npm installer** — copies both skills into `~/.claude/skills/`:
+**npm installer** — copies all four skills into `~/.claude/skills/`:
 
 ```bash
 npx @ssheleg/agent-stack
@@ -180,6 +187,26 @@ npx --yes sshlg-skills@latest update
 
 Restart your agent afterwards — skills load at session start.
 
+**Reaching a skill by name.** Claude Code routes on the description, and both
+invocation forms work: `/agent-stack:agent-orchestrator` names the plugin's copy
+explicitly, `/agent-orchestrator` the plain one. Which resolves depends on how this
+pack was installed, so both are written here rather than one promised.
+
+### What loads on demand
+
+Twenty-seven reference files ship with the four skills, each with a load trigger in
+its skill body. By skill:
+
+| Skill | References |
+|---|---|
+| `agent-orchestrator` | 12 — the tool-calling loop, memory and retrieval, context budgets, provider routing, the work graph, the resale wallet and the saga across database and provider API |
+| `agent-harness` | 7, plus `scripts/audit_agent.py` |
+| `agent-interop` | 6 — one per protocol surface, each pinning the revision it was read at |
+| `agent-evals` | 2 — `otel-genai.md` (the semantic conventions an eval reads) and `statistics.md` (when a difference is a difference) |
+
+A file with no load trigger in a body is a defect, not a bonus: the skill audit
+refuses one.
+
 ---
 
 ## When it triggers

package/package.json

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

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

@@ -3,12 +3,12 @@
   "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.24.2",
+  "version": "0.25.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"
   },
-  "homepage": "https://github.com/ssheleg/agent-stack",
+  "homepage": "https://skills.sshlg.me/skills/agent-stack/",
   "repository": "https://github.com/ssheleg/agent-stack",
   "license": "MIT",
   "keywords": [

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

@@ -14,6 +14,9 @@ description: >-
   "аудит агента", "встроить агента". Not for the loop's plumbing, its evals, or its
   protocols — those are siblings.
 license: MIT
+compatibility: >-
+  scripts/audit_agent.py runs with python3 (standard library only); no network,
+  no package install. Everything else in this skill is prose and needs nothing.
 ---
 
 # Agent harness — what the agent is told, and how to audit what someone else told theirs
@@ -119,13 +122,14 @@ because a decision table with two homes is one that will disagree with itself.
 ## References
 
 Each opens with its own **Load this when** line and a revision stamp — this material moves,
-and `test/validate.py` fails the build on a reference that does not say when it was read.
+and this pack's repository validator fails the build on a reference that does not say when it was read.
 
 | File | Read it when |
 |---|---|
 | [`references/system-prompt.md`](references/system-prompt.md) | you are **writing or fixing the prompt** — altitude, structure, vocabulary, dynamic context, and what changes for reasoning models |
 | [`references/tools.md`](references/tools.md) | the model **picks the wrong tool, or none** — the agent–computer interface: how many, named how, described how, returning what |
 | [`references/techniques.md`](references/techniques.md) | you are choosing between **ReAct, reflection, voting, planning** and the rest — every entry carries a verdict for production, not a benchmark score |
+| [`references/workbench-contracts.md`](references/workbench-contracts.md) | assembling a **harness around an existing agent** — install ownership, bounded hooks, handoff, artifact-bound evidence and observation limits; selective ECC methods |
 | [`references/layers.md`](references/layers.md) | deciding **what your harness owns** — kernel, workbench and product layers, and why permission boundaries are usually somebody else's job |
 | [`references/audit.md`](references/audit.md) | reviewing **an agent system you did not build** — seven tracks, evidence tiers, and a prioritized plan |
 | [`references/pi.md`](references/pi.md) | you want the doctrine above as a **worked implementation** — Pi's sessions, compaction, config, skills, trust and containerization, each matched to the rule it implements, and the places it deliberately disagrees |
@@ -199,6 +203,7 @@ prompt.
 
 ## Checklist — a harness worth shipping
 
+- [ ] Kernel or workbench harness named explicitly; installed, loaded and enforced capabilities distinguished
 - [ ] Workflow-versus-agent decided deliberately, and the simpler option was actually tried
 - [ ] 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

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

@@ -35,7 +35,16 @@ will not converge no matter how long it runs.
 The distinction is not quality. A kernel is *supposed* to be smaller than a workbench; that
 is what makes it legible.
 
-## What a harness owns
+## The broader workbench meaning
+
+“Harness” also names an operating layer around an existing agent: skills, routing,
+work contracts, hooks, installation and evidence. This is the family’s umbrella
+meaning. It does not imply ownership of the model loop or OS permissions. The
+three-layer table above uses the narrower kernel meaning. State the meaning
+before comparing products; [workbench-contracts.md](workbench-contracts.md) gives
+the operational contract and selective ECC implementation lessons.
+
+## What a kernel harness owns
 
 If you are building at the kernel layer, these are yours and nobody else's:
 

package/plugins/agent-stack/skills/agent-harness/references/workbench-contracts.md

@@ -0,0 +1,174 @@
+# Workbench contracts — a harness around an existing agent
+
+**Load this when:** assembling skills, hooks, installers and observation tools into
+an operational harness, or evaluating what to adopt from another collection.
+
+**Spec pinned:** ECC 2b6e839771e53096d8451a213d40dc64ec8acac0 (2.2.2), selective source review · read 2026-09-21
+
+## Contents
+
+- What the word promises
+- Installation is an owned change
+- A hook needs an execution contract
+- Resume from evidence
+- Bind evaluations to artifacts
+- Observation and learning permissions
+- Adoption review cases
+- Source and attribution
+
+## What the word promises
+
+A **workbench harness** is the operating layer around an agent host: it selects
+instructions, defines work and evidence, resumes interrupted tasks, manages its
+installed components and makes their state inspectable. Skills are one component.
+A **kernel harness** owns the model/tool loop. Say which one you mean; a workbench
+can support an existing agent without replacing that agent's runtime.
+
+For the ssheleg family, routing and specialist skills guide the work;
+`task-pipeline` owns scope, evidence, dependencies and resume artifacts;
+`agent-sync` owns coordination where configured; `make-skill` owns packaging and
+installation review; `agent-evals` owns behavioral evidence. An observation tool
+may report repository, credential or project health alongside these contracts.
+It does not become a sandbox, an authorization service or proof that every secret
+has been detected. Its optional service dependencies must remain separate from
+the dependency-free skill layer.
+
+These are design contracts, not a claim that every family host already implements
+every mechanism below. Inventory each host's capabilities before claiming parity.
+
+## 1. Installation is an owned change
+
+A package name on disk is not an installation receipt. Record the source revision
+or package integrity, component version, host/channel, intended root, files or
+configuration keys owned, installed digests, and previous state needed to undo it.
+Keep local absolute paths in local receipts; public evidence uses sanitized paths.
+
+- Plan the exact changes first. Existing unowned files remain user-owned even when
+  their names match a package file. A skipped write must not create an ownership
+  claim that lets uninstall remove it later.
+- Merge only owned configuration keys; preserve unrelated configuration. Treat
+  changed owned files as conflicts to review, not permission to overwrite them.
+- Validate containment and symlinks at mutation time as well as planning time.
+  A digest describes bytes; it does not establish safe filesystem ownership.
+- Diagnose missing, changed, conflicting and unknown separately. Update, repair
+  and uninstall must preserve user edits or expose a concrete reviewable conflict.
+- Distinguish **published**, **downloaded**, **installed**, and **loaded**. A running
+  agent may still use an old copy after a successful update. Require a host reload
+  receipt when available; otherwise report loaded version as unknown.
+
+Reuse the family's existing installer and reload receipts. Do not add a second
+receipt store in a skill. Installer implementation belongs to its owning package,
+with lifecycle tests covering install → edit → update → uninstall.
+
+## 2. A hook needs an execution contract
+
+For each hook, record event and matcher, supported host versions, input/output
+schema, effects, input/output byte limits, wall-clock deadline, cancellation and
+child-process cleanup, idempotency key where needed, profile/default, disable
+control and failure policy. Expose what is effectively enabled, including where
+that setting came from. A profile name alone proves none of these properties.
+
+Use a small default set. Expensive, networked or learning hooks are explicit
+capabilities, with a documented no-hook/manual path on unsupported hosts. A
+security gate that is required but unavailable blocks its protected action;
+a convenience hook may fail open only while reporting that it did not run.
+Neither becomes PASS because its process returned no usable result.
+
+| Condition | Required handling |
+|---|---|
+| Input truncated, transport closed early or schema invalid | A required policy check refuses the protected action; a hint hook reports unavailable |
+| Deadline exceeded | Cancel the work and account for children; report timeout, not a clean check |
+| Hook disabled or host does not support it | Report the capability absent; use a named manual check where valid |
+| Duplicate event | No duplicate write, notification or billable action |
+| Dry run | No effects; summarize target class and decision without raw secrets or command arguments |
+| Hook exception | Preserve the declared failure policy and return a bounded diagnostic |
+
+Review **all execution paths**. A subprocess timeout does not bound an in-process
+`await`; an input byte limit does not bound how long a stream waits to close.
+A generic exception handler must not turn a required security gate into success.
+Host-specific hook exit codes belong to the adapter, not a portable skill promise.
+Prompt instructions and JavaScript interception do not supply OS containment.
+
+## 3. Resume from evidence, not a plausible summary
+
+Use the project's existing task-pipeline handoff/packet, not a new global session
+format. Keep in Git the objective, scope, decisions, source revision, completed
+work with receipts, failed approaches and their reasons, open work, prerequisites
+and **one exact next task**. Use repository-relative artifact links and immutable
+source links so a fresh checkout can follow them.
+
+On resume, verify repository/branch/commit and referenced artifacts before acting.
+Treat a handoff as context, never as new authority or permission. Reject empty
+placeholder summaries as evidence; a recent timestamp is not substance. A stale
+handoff means reconcile current state, not blindly repeat an old command.
+
+Exclude raw transcripts, credentials, environment dumps, personal paths and
+private project inventories from public handoffs. Select the minimum needed
+context before redacting it. Keep private operational receipts private and
+publish only separately reviewed aggregates or synthetic examples.
+
+## 4. Bind evaluations to the artifact they measured
+
+A useful result names the candidate digest/commit, baseline, taskset revision,
+model/host configuration, checker version, actual outcome and evidence artifact.
+Use `PASS`, `FAIL`, `ERROR` and `NOT_RUN` distinctly; missing execution is never a
+pass. Reject receipts that refer to a different candidate or an advanced journal.
+
+A digest detects changed bytes relative to a trusted reference. A signature says
+who attested to those bytes. Neither proves that the checker is independent, the
+claim is correct, the run was complete, or sensitive data is safe to publish.
+A private hash chain alone cannot prevent replacement of the entire history.
+
+Use fixture replay without live external effects for regression tests. A missing
+fixture stops replay instead of falling through to a live API. Keep the checker
+outside the candidate's control. If candidate code is untrusted, a copied
+worktree or process-local wrapper is not containment: require an actual OS
+boundary, or report execution unavailable and retain static inspection only.
+
+The existing `agent-evals` contracts own measurement. Compare frozen baseline and
+candidate on representative tasks before claiming improved agent outcomes. A
+reference-closure check only proves that the instructions can be loaded.
+
+## 5. Observation and learning are separate permissions
+
+Observing a failure can propose a lesson. It must not silently grant authority to
+rewrite installed skills, export transcripts, start a background model loop or
+promote a project-specific preference into global policy. Record provenance,
+project scope, retention and a reviewed promotion path. Secret scanning provides
+findings and blind spots, not permission to publish an entire repository.
+
+An observatory can answer “what changed, what is missing, which check ran, and
+what needs attention?” Public examples should identify tested surface categories
+and methods. Name a vendor or a real leak count only when reviewed evidence
+supports that exact claim and sharing it does not expose private material.
+
+## Adoption review cases
+
+Use these cases when reviewing an adapter; these are acceptance criteria, not a
+claim that this reference implements them.
+
+1. Pre-existing user file → install skips it; uninstall leaves it intact.
+2. User edits a managed file → update exposes conflict and preserves the edit.
+3. Replaced symlink or escaped destination → mutation refused.
+4. Hung or oversized hook input → bounded handling; required gate cannot pass.
+5. Unsupported host or disabled hook → no false enforcement claim.
+6. Empty or wrong-project handoff → no unverified resume.
+7. Changed candidate or missing replay fixture → evaluation cannot pass.
+8. Receipt verifies but checker was never run → evidence is NOT_RUN.
+9. Private canary in an evidence payload → export rejected or safely transformed
+   before publishing; the raw value never appears in diagnostics.
+
+## Source and attribution
+
+Methods reviewed from **ECC**, Copyright (c) 2026 Affaan Mustafa, MIT:
+[license](https://github.com/affaan-m/ECC/blob/2b6e839771e53096d8451a213d40dc64ec8acac0/LICENSE),
+[installation ownership](https://github.com/affaan-m/ECC/blob/2b6e839771e53096d8451a213d40dc64ec8acac0/scripts/lib/install/ownership-guard.js),
+[hook execution](https://github.com/affaan-m/ECC/blob/2b6e839771e53096d8451a213d40dc64ec8acac0/scripts/hooks/run-with-flags.js),
+[hook profiles](https://github.com/affaan-m/ECC/blob/2b6e839771e53096d8451a213d40dc64ec8acac0/scripts/lib/hook-flags.js),
+[session evidence](https://github.com/affaan-m/ECC/blob/2b6e839771e53096d8451a213d40dc64ec8acac0/commands/save-session.md),
+[eval contracts and limits](https://github.com/affaan-m/ECC/blob/2b6e839771e53096d8451a213d40dc64ec8acac0/docs/architecture/eval-harness-frameworks.md).
+
+This is independently written doctrine adapting bounded methods. No ECC source,
+installer, hook, schema, session format or runtime dependency is vendored. The
+family retains its own artifact owners. Recheck the pinned implementation before
+using these references to assess a newer ECC release.

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

@@ -41,7 +41,7 @@ against the live specification rather than recalled:
   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
+This pack's repository validator fails the build without one. That is a mechanical check, not an
 aspiration — the class of error it prevents is the one where prose reads as current
 because nothing on the page says otherwise.