@ssheleg/agent-stack 0.13.4 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## v0.14.1 — the workforce axis: provider lifecycle and workspace-scale memory
+
+(v0.14.0 was burned during release engineering: its tag landed on a commit a
+protected branch could never reach, and the tag rules forbid deletion — so the
+content ships as v0.14.1 and the dead tag stays as its own cautionary receipt.)
+
+The orchestrator gains `references/provider-lifecycle.md` — where providers come
+from and how one earns trust: produced-once/bound-many, the production pipeline
+with its named-consumer gate, knowledge packs whose traps become planted
+fixtures, the canary binding with recorded promotion, the two-extension-mechanisms
+law, workspace lifecycle with the dependency projection, and fleet budgets with
+the run scheduler. `patterns.md` gains the workspace-scale memory rules — the
+journal spine, rebuildable projections with embedding-model versions, isolation
+at the API, promotion with decay, memory-through-the-bundle. The harness audit's
+tools track now asks what the agent was actually equipped with: required,
+installed, loaded — three truths with two receipts. Distilled from the Passion
+Code fabric design review of 2026-08-27.
+
+## v0.13.5 — the shared seam is explicit
+
+Both shared validators now state `diverges: none`, completing the umbrella
+mechanism contract instead of leaving the constant seam implicit.
+
 ## v0.13.4 — shared guards identify their owner
 
 The eval and social-preview validators now declare their umbrella-owned shared

package/README.md

@@ -4,6 +4,7 @@
 [![npm](https://img.shields.io/npm/v/%40ssheleg%2Fagent-stack)](https://www.npmjs.com/package/@ssheleg/agent-stack)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![site](https://img.shields.io/badge/docs-skills.sshlg.me-8ab0ff)](https://skills.sshlg.me/skills/agent-stack/)
+[![skills.sh](https://skills.sh/b/ssheleg/agent-stack)](https://skills.sh/ssheleg/agent-stack)
 
 **Build agent loops, harnesses, evals and protocol boundaries that stay inspectable under production failure.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.13.4",
+  "version": "0.14.1",
   "scripts": {
     "test": "python3 test/validate.py && python3 test/plant_guard_test.py"
   },
@@ -20,7 +20,7 @@
     "SECURITY.md"
   ],
   "repository": "github:ssheleg/agent-stack",
-  "homepage": "https://github.com/ssheleg/agent-stack",
+  "homepage": "https://skills.sshlg.me/skills/agent-stack/",
   "license": "MIT",
   "author": {
     "name": "ssheleg",

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

@@ -2,7 +2,7 @@
   "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.13.4",
+  "version": "0.14.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -56,6 +56,7 @@ Walk them in order. Later tracks assume earlier ones.
 - Is there a default limit on response size, or only an optional one?
 - Do errors **name the next action**?
 - Are destructive tools guarded by shape (`confirm: true`, absolute paths, enums) rather than by instruction?
+- What was the agent **actually equipped with**? Three different truths — *required* by the task, *installed* on the machine, *loaded* by the session — and the receipts are the compiled bundle's lockfile and the session-init capability list. An audit that reads only the config file has checked the first truth of three.
 
 ### 3 — Control flow
 

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

@@ -245,6 +245,10 @@ a floor.
 
 **Layer 0 — carryover state.** Goal, artifacts, verified work and restrictive
 mode cross a compaction boundary as copied typed blocks, not prose (§12).
+
+**Workspace scale.** Managing persistent workspaces rather than sessions shifts
+the scopes — run, workspace, global, doctrine — and adds the journal-spine
+rules: `references/patterns.md` → **Workspace-scale memory**.
 ## 8. Self-Learning Feedback Loops
 
 Three cycles feed the memory layers, and they differ by what supplies the signal: a failed
@@ -381,3 +385,4 @@ there, so this table stays an index and the two cannot drift apart.
 | [`references/runtime.md`](references/runtime.md) | the agent must **survive a crash, a pause, a second message or a schedule** |
 | [`references/governance.md`](references/governance.md) | the question is **permission, not cost** — what it may do, and how you prove it |
 | [`references/llm-proxy-billing.md`](references/llm-proxy-billing.md) | the product **resells LLM access** |
+| [`references/provider-lifecycle.md`](references/provider-lifecycle.md) | the question is the **workforce, not the loop** — where providers come from, produced-once/bound-many, knowledge packs, canary trust, workspace lifecycle, fleet budgets |

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

@@ -20,6 +20,7 @@ that costs no LLM call.
 - [Conflict Resolution Pattern](#conflict-resolution-pattern)
 - [Cross-Resource Learning Transfer](#cross-resource-learning-transfer)
 - [Suggestion Engine (No LLM Cost)](#suggestion-engine-no-llm-cost)
+- [Workspace-scale memory — the journal spine](#workspace-scale-memory--the-journal-spine)
 
 
 ## Data Models
@@ -454,3 +455,37 @@ constant to tune and a constant with two homes is one that will disagree with it
 Both moved out of `SKILL.md` on 2026-08-16. The mechanisms they describe were already
 in this file — the validation loop, the extractors, the confidence arithmetic — so the
 body was holding a second copy of their surface. One home; the body keeps the decision.
+
+## Workspace-scale memory — the journal spine
+
+The four layers in the body's §7 are session-scale: chat, working, learnings, insights.
+When the same machinery manages **persistent workspaces** — long-lived projects that own
+agents, schedules and history and outlive every conversation — the scopes shift, and five
+rules keep the store honest at that scale. *Distilled 2026-08-27 from the Passion Code
+fabric design review; the workforce half of that review is
+`references/provider-lifecycle.md`.*
+
+| Scope | Holds | Lives |
+|---|---|---|
+| run-working | scratch, intermediates, the transcript | one run; artifacts survive by content hash |
+| workspace | decisions, lessons, report context of one project | permanent, append-only, isolated |
+| global | facts promoted above any one workspace | permanent, with decay |
+| doctrine | intent and standards, versioned in git | the source everything else indexes |
+
+1. **One append-only journal is the canonical ledger.** Memory writes are events; every
+   register anyone reads is a projection of them. Corrections supersede; erasure leaves a
+   tombstone. A store built table-first cannot adopt this later — history that predates
+   the journal is unrecoverable at any price.
+2. **Every index is a rebuildable projection**, and an embedding row carries the
+   embedding model's name and version — otherwise the first model upgrade silently mixes
+   incomparable vectors and similarity search degrades without an error.
+3. **Isolation is enforced at the memory API**, from the authenticated caller's scope —
+   never by asking the prompt to respect a boundary. One workspace never writes
+   another's memory; transfer happens only as an explicit, revisioned artifact
+   (`provider-lifecycle.md` names the vehicle).
+4. **Promotion to global carries provenance, confidence, contradiction links and an
+   expiry.** Memory without decay accumulates confident lies, and the global scope is
+   where they do the most damage because nothing above it contradicts them.
+5. **Memory reaches the model only through the compiled per-task bundle.** One entry
+   point means one supply-chain gate and one lockfile that pins what the agent knew —
+   which is the difference between debugging a bad answer and re-litigating it.

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

@@ -0,0 +1,151 @@
+# Provider lifecycle — where agents come from, and how one earns trust
+
+**Load this when** the question is the workforce rather than the loop: an agent is being
+produced, adapted from an existing project, registered, replaced or retired, or a fleet
+of workspaces needs governing. The loop that *runs* a provider is the body; what a call
+costs is `llm-proxy-billing.md`; whether an action is permitted is `governance.md`. This
+file owns the axis none of them hold: a provider's life from intake to retirement.
+
+*Distilled 2026-08-27 from the Passion Code fabric design review (its ADR-0015 and
+agent-production design), generalised for any estate of agent workspaces.*
+
+## Contents
+
+- Produced once, bound many times
+- The production pipeline, stage by stage
+- Knowledge packs — how expertise transfers between projects
+- Trust is earned by watched runs: the canary binding
+- Two extension mechanisms, and only two
+- Workspace lifecycle, and the dependency projection under retirement
+- Fleet governance: hierarchical budgets and the run scheduler
+
+## Produced once, bound many times
+
+The distinction the whole file stands on:
+
+| | **Provider** | **Binding** |
+|---|---|---|
+| Is | the agent as artifact: repo, manifest, capability schemas, service or instruction pack | one workspace's versioned decision to use that provider for a capability |
+| Created by | a production run — rare, expensive, gated | a registry write — cheap, reversible |
+| Versioned as | provider revisions; v2 goes through the same pipeline as v1 | immutable binding revisions; a run pins one |
+| Retired by | archiving its home project | unbinding — history and schedules survive it |
+
+Conflate the axes and every hire becomes a project: nineteen role types across N
+workspaces is nineteen providers and N× bindings, never 19×N projects. Rollout of a new
+provider version is *rebinding*, never mutation of a binding a running task already
+pinned.
+
+## The production pipeline, stage by stage
+
+Producing an agent is an ordinary project whose route is data — a versioned stage list,
+not code. The stages that survived review:
+
+| Stage | Gate that closes it |
+|---|---|
+| **intake** | capability named in the controlled vocabulary; **a consumer named** — the workspace or schedule that will actually call it; workflow-or-agent decided (`agent-harness`: if every step can be named now, it is a workflow behind a capability, not an autonomous agent); transport chosen by the interop rule; money- and publication-adjacent effects declared per agent |
+| **knowledge** | sources named and distilled into a knowledge pack (below); every claim in it cites its origin |
+| **scaffold** | manifest + capability schemas + one safe fixture validate against the pinned contract revision |
+| **instructions** | the instruction pack is a revision, content-hashed, carrying the enumerated vocabulary — status values, capability names — generated from the schema, never retyped |
+| **build** | the ordinary delivery pipeline of the estate, run inside the agent's own workspace |
+| **evals** | golden fixtures pass AND planted defects are rejected, *watched* — on the two clocks `agent-evals` §6 defines: the **observable** for each requirement written at intake, before the build; the corpus grown from production, where the source project's recorded failures count as production |
+| **admission** | shape conformance → protocol negotiation → side-effect-free semantic probes → an immutable admission record |
+| **canary binding** | bound under mandatory checking and a budget cap; unsupervised operation is a later, recorded promotion |
+
+The sharpest gate is the first: **no agent without a named consumer.** A role catalogue
+is not a production queue, and the cheapest agent to operate is the one you did not
+build because nothing would have called it.
+
+Two entry doors, one pipeline: **build** (greenfield) and **adapt** — an existing
+project with a stable surface gets inspected without execution, wrapped behind a
+capability, and enters at scaffold with its own docs as the knowledge source and its own
+recorded failures as the first fixtures.
+
+## Knowledge packs — how expertise transfers between projects
+
+The object that makes "reuse the knowledge, not the code" mechanical rather than
+aspirational:
+
+```
+knowledge_pack(id, revision, content_hash,
+  sources[]:  what was read — repos, docs, audits, retros, with refs
+  distilled:
+    patterns[]   what works here, each citing file:line
+    traps[]      the source's recorded failures and dead ends
+    fixtures[]   ← traps, converted into planted-defect eval cases
+    glossary[]   terms the new agent must use exactly as the source does
+)
+```
+
+Three rules give it teeth:
+
+- **A trap becomes a fixture.** The new agent is not admitted until it has been watched
+  rejecting the exact defects its predecessor was burned by. Knowledge transfers as a
+  check, not as prose an instruction pack hopes the model remembers.
+- **A pack travels as an artifact, never as a memory write.** Workspace memory is
+  isolated (see `patterns.md` → *Workspace-scale memory*); the pack is the legal vehicle
+  between workspaces — explicit, attributable, revisioned.
+- **A pack is an injection surface.** Text composed into a prompt from many sources is
+  supply chain; a pack produced by an agent passes the same eval gate as code.
+
+## Trust is earned by watched runs: the canary binding
+
+Authorship is not evidence. A freshly produced provider — your own included — enters
+under a **canary binding**: its output gates through a checker (the contract lives in
+`graph-engineering.md` §6) and its spend is capped, regardless of who wrote it. Removing
+the supervision is a **promotion**: a recorded decision citing eval results and run
+history, with an author. The record matters more than the ceremony — a checker quietly
+dropped is indistinguishable from one that never existed, and the promotion row is the
+only thing that says which.
+
+Store, per provider revision, the **production provenance**: source repo, the run that
+produced it, its eval set, its admission. "Where did this agent come from" must be a
+query, not an archaeology project.
+
+## Two extension mechanisms, and only two
+
+Everything that extends an agent estate is one of:
+
+1. **a versioned registry entry** — a capability name, a skill, a pipeline, a template,
+   an event kind;
+2. **a provider behind a profile** — an agent, a connector, a checker.
+
+The corollaries do real work: a *connector* is a deterministic provider of `collect.*`
+capabilities (no separate plugin system to build); a *checker* is a provider of
+`check.*` capabilities (so custom checkers ride the same production pipeline and
+admission as any agent, and a checker may never be served by the same binding that
+produced the work it checks). A feature that wants a third extension mechanism is a
+design smell before it is a backlog item.
+
+## Workspace lifecycle, and the dependency projection under retirement
+
+A workspace moves `proposed → active → dormant → archived`, and two transitions carry
+rules that prevent silent damage:
+
+- **dormant pauses its schedules.** A sleeping workspace whose routines still tick burns
+  quota and money invisibly — dormancy that does not stop the clock is a label, not a
+  state.
+- **archived requires the dependency projection to be empty for it**: no active binding
+  in another workspace may still point at this workspace's providers. That projection —
+  who consumes whose capabilities — is cheap to maintain and impossible to reconstruct
+  during an incident; without it, retiring a workspace is a surprise delivered to its
+  dependents at call time.
+
+## Fleet governance: hierarchical budgets and the run scheduler
+
+Per-call spend limits do not govern a fleet. Two objects do, and both are projections
+over the run record rather than new subsystems:
+
+- **A budget hierarchy** — estate → workspace → goal → task — where an exhausted level
+  refuses *admission of new runs* rather than killing running ones, and approaching a
+  cap is an attention signal. The money mechanics — wallets, reservations, reconciliation
+  — are `llm-proxy-billing.md`; the multi-level attribution argument is
+  `governance.md`. What this file adds: the cap must exist at every level, because
+  sixty workspaces individually under budget is still one bill nobody approved.
+- **A run scheduler** — a ceiling on concurrent runs per host, priority classes
+  (incident > scheduled > backfill), and per-provider concurrency tied to the external
+  quota records the collectors keep. A fleet without one discovers its capacity limit
+  as a pile of half-finished runs on the busiest day of the year.
+
+And one heartbeat rule: every scheduled worker writes an observation about itself; a
+stale heartbeat is an attention row. A provider that is not watched is not operated —
+the failure mode of every fleet is not the crash but the silence after it.