@ssheleg/agent-stack 0.24.3 → 0.25.1

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 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).

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 —

package/package.json

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

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

@@ -129,6 +129,7 @@ and this pack's repository validator fails the build on a reference that does no
 | [`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 |
@@ -202,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.