From fcf4e907bfb8989baf506bce99e90e733a4a723d Mon Sep 17 00:00:00 2001 From: NGHTBOY Date: Thu, 27 Aug 2026 14:48:19 +0200 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20bake=20the=20fabric=20review=20into?= =?UTF-8?q?=20the=20pack=20=E2=80=94=20provider=20lifecycle=20and=20worksp?= =?UTF-8?q?ace=20memory?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit provider-lifecycle.md joins the orchestrator's references: 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 workspace-scale memory (journal spine, projections with embedding-model versions, isolation at the API, promotion with decay, memory-through-the- bundle). The harness audit's tools track asks required/installed/loaded. Co-Authored-By: Claude Fable 5 --- .claude-plugin/marketplace.json | 2 +- CHANGELOG.md | 14 ++ package.json | 2 +- .../agent-stack/.claude-plugin/plugin.json | 2 +- .../skills/agent-harness/references/audit.md | 1 + .../skills/agent-orchestrator/SKILL.md | 5 + .../agent-orchestrator/references/patterns.md | 35 ++++ .../references/provider-lifecycle.md | 151 ++++++++++++++++++ 8 files changed, 209 insertions(+), 3 deletions(-) create mode 100644 plugins/agent-stack/skills/agent-orchestrator/references/provider-lifecycle.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 084995a..d936ace 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "displayName": "Agent Stack", "source": "./plugins/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.5", + "version": "0.14.0", "author": { "name": "ssheleg", "url": "https://x.com/sshlg93" diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ce5a87..3ff998a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,19 @@ # Changelog +## v0.14.0 — the workforce axis: provider lifecycle and workspace-scale memory + +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 diff --git a/package.json b/package.json index adb5943..281748e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@ssheleg/agent-stack", - "version": "0.13.5", + "version": "0.14.0", "scripts": { "test": "python3 test/validate.py && python3 test/plant_guard_test.py" }, diff --git a/plugins/agent-stack/.claude-plugin/plugin.json b/plugins/agent-stack/.claude-plugin/plugin.json index aa779ed..1f1b731 100644 --- a/plugins/agent-stack/.claude-plugin/plugin.json +++ b/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.5", + "version": "0.14.0", "author": { "name": "ssheleg", "url": "https://x.com/sshlg93" diff --git a/plugins/agent-stack/skills/agent-harness/references/audit.md b/plugins/agent-stack/skills/agent-harness/references/audit.md index 5e60c41..7cd6ddc 100644 --- a/plugins/agent-stack/skills/agent-harness/references/audit.md +++ b/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 diff --git a/plugins/agent-stack/skills/agent-orchestrator/SKILL.md b/plugins/agent-stack/skills/agent-orchestrator/SKILL.md index 33e2cd5..0a1af0c 100644 --- a/plugins/agent-stack/skills/agent-orchestrator/SKILL.md +++ b/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 | diff --git a/plugins/agent-stack/skills/agent-orchestrator/references/patterns.md b/plugins/agent-stack/skills/agent-orchestrator/references/patterns.md index 8eba8cb..77672bb 100644 --- a/plugins/agent-stack/skills/agent-orchestrator/references/patterns.md +++ b/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. diff --git a/plugins/agent-stack/skills/agent-orchestrator/references/provider-lifecycle.md b/plugins/agent-stack/skills/agent-orchestrator/references/provider-lifecycle.md new file mode 100644 index 0000000..7d8fa02 --- /dev/null +++ b/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. From bc9c201ca420c380ae294b54c1c6ce666ee7f6b3 Mon Sep 17 00:00:00 2001 From: NGHTBOY Date: Thu, 27 Aug 2026 15:04:42 +0200 Subject: [PATCH 2/2] =?UTF-8?q?chore(release):=20ship=20as=20v0.14.1=20?= =?UTF-8?q?=E2=80=94=20the=20v0.14.0=20tag=20is=20unreachable=20by=20rule?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- .claude-plugin/marketplace.json | 2 +- CHANGELOG.md | 6 +++++- package.json | 2 +- plugins/agent-stack/.claude-plugin/plugin.json | 2 +- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index d936ace..426fb4d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "displayName": "Agent Stack", "source": "./plugins/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.14.0", + "version": "0.14.1", "author": { "name": "ssheleg", "url": "https://x.com/sshlg93" diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ff998a..616fc02 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog -## v0.14.0 — the workforce axis: provider lifecycle and workspace-scale memory +## 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 diff --git a/package.json b/package.json index 281748e..5aa430e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@ssheleg/agent-stack", - "version": "0.14.0", + "version": "0.14.1", "scripts": { "test": "python3 test/validate.py && python3 test/plant_guard_test.py" }, diff --git a/plugins/agent-stack/.claude-plugin/plugin.json b/plugins/agent-stack/.claude-plugin/plugin.json index 1f1b731..4e8bb2d 100644 --- a/plugins/agent-stack/.claude-plugin/plugin.json +++ b/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.14.0", + "version": "0.14.1", "author": { "name": "ssheleg", "url": "https://x.com/sshlg93"