@operatorstack/yield 0.1.38 → 0.3.0

package/README.md

@@ -30,9 +30,43 @@ programs. The canonical workflow stays inside your repository beside the code
 and dependencies it uses. Generated `SKILL.md` files only help coding agents
 discover it.
 
+Write the workflow in code. Use `AgentTask` only where a bounded step needs
+coding-agent judgment, then continue with structured data in normal code.
+
 Verified with Cursor, Codex, and Claude Code. Registry-backed project paths are
 available for 73 more coding agents.
 
+## Start with your coding agent
+
+Run the command for your project:
+
+| Language   | Command                                                                                                        |
+| ---------- | -------------------------------------------------------------------------------------------------------------- |
+| TypeScript | `npm create @operatorstack/yield@latest`                                                                       |
+| Python     | `uvx --from yieldskill yskill bootstrap --language python`                                                     |
+| Rust       | `cargo install yieldskill --root .yield --locked`, then `.yield/bin/yskill bootstrap --root . --language rust` |
+| Go         | `go run github.com/operatorstack/yield/cmd/yskill@latest bootstrap --root . --language go`                     |
+
+Yield detects the repository, language, and installed coding agents. It shows
+every proposed file and dependency change. It asks before it writes. It then
+installs, tests, and registers the `yield-workflow-builder` skill workflow.
+
+Restart your coding agent. To create a new skill workflow, ask:
+
+```text
+Use Yield to create a tested skill workflow for releasing my package.
+```
+
+To convert an existing `SKILL.md`, ask:
+
+```text
+Use Yield to convert my existing release SKILL.md into a tested skill workflow.
+```
+
+The builder can create a skill workflow from a description. It can also
+convert an existing `SKILL.md`. Yield does not use install hooks to change the
+repository.
+
 ## Move repeated instructions into code
 
 A release skill often starts as prose:
@@ -40,26 +74,29 @@ A release skill often starts as prose:
 > Run the tests. Review the release. Stop if the review finds a critical issue.
 > Ask me before publishing. Publish the package, then verify the registry.
 
-Yield makes the order and stopping rules executable:
+Yield makes the order and stopping rules executable. The coding agent reviews
+what the deterministic check may miss; the program still owns the gate,
+approval, publish, and verification steps:
 
 <!-- release-example:start -->
+
 ```typescript
-import { defineSkill } from "@operatorstack/yield";
+import { defineSkill } from "@operatorstack/yield"
 
-type Review = { critical: number; summary: string };
+type Review = { critical: number; summary: string }
 
 defineSkill((ctx) => {
   // Yield runs commands itself and records their output and exit status.
-  const tests = ctx.runCommand("test", "echo tests-ok", 300);
+  const tests = ctx.runCommand("test", "echo tests-ok", 300)
 
   // A failed requirement stops the workflow and keeps its evidence.
-  ctx.require(tests.exit_code === 0, "the test command succeeds", tests);
+  ctx.require(tests.exit_code === 0, "the test command succeeds", tests)
 
   // Review gives TypeScript its compile-time type. The JSON schema checks the
   // coding agent's response at runtime before this workflow can continue.
   const review = ctx.agentTask<Review>(
     "review-release",
-    "Review this release. Report critical findings and a short summary.",
+    "Review this release for correctness problems that the test command may miss. Report critical findings and a short summary.",
     { stdout: tests.stdout, stderr: tests.stderr },
     {
       type: "object",
@@ -69,28 +106,29 @@ defineSkill((ctx) => {
         summary: { type: "string", minLength: 1 },
       },
     },
-  );
-  ctx.require(review.critical === 0, "the review has no critical findings", review);
+  )
+  ctx.require(review.critical === 0, "the review has no critical findings", review)
 
   // Yield emits these fixed choices. A supported host may show native controls;
   // otherwise the coding agent asks through its normal interface.
   const approval = ctx.askUser("approve-publish", "Publish this package?", [
     { value: "yes", label: "Publish" },
     { value: "no", label: "Stop" },
-  ]);
-  if (approval !== "yes") ctx.refused("the operator declined publication");
+  ])
+  if (approval !== "yes") ctx.refused("the operator declined publication")
 
   // Publishing cannot start before approval. Verification is a separate step,
   // so completion requires evidence that the registry contains the release.
-  const publish = ctx.runCommand("publish", "echo publish-ok", 600);
-  ctx.require(publish.exit_code === 0, "the publish command succeeds", publish);
+  const publish = ctx.runCommand("publish", "echo publish-ok", 600)
+  ctx.require(publish.exit_code === 0, "the publish command succeeds", publish)
 
-  const registry = ctx.runCommand("verify-registry", "echo registry-ok", 300);
-  ctx.require(registry.exit_code === 0, "the registry contains the release", registry);
+  const registry = ctx.runCommand("verify-registry", "echo registry-ok", 300)
+  ctx.require(registry.exit_code === 0, "the registry contains the release", registry)
 
-  return { published: true, summary: review.summary };
-});
+  return { published: true, summary: review.summary }
+})
 ```
+
 <!-- release-example:end -->
 
 The example uses harmless commands so its fixture can run in any checkout.
@@ -98,7 +136,7 @@ Replace them with the test, publish, and registry commands for your project.
 The complete tested source is in
 [`examples/release-checklist`](https://github.com/operatorstack/yield/tree/main/examples/release-checklist/).
 
-## Use Yield in five steps
+## Advanced: build manually
 
 ### 1. Install Yield
 
@@ -110,7 +148,7 @@ npm exec -- yskill --version
 ```
 
 [Public npm releases](https://www.npmjs.com/package/@operatorstack/yield)
-use trusted publishing. The SDK package and all six runtime packages include
+use trusted publishing. The initializer, SDK, and six runtime packages include
 SLSA v1 provenance.
 
 ### 2. Create the workflow
@@ -203,13 +241,13 @@ The agent follows the generated adapter, runs the canonical workflow in
 If replay produces a different operation, the run fails instead of silently
 forking. Every side effect crosses one of these primitives:
 
-| Primitive | Purpose |
-|---|---|
-| `runCommand` | Execute a command and record its exit code and output. |
-| `agentTask` | Ask the coding agent for schema-valid JSON. |
-| `askUser` | Request an explicit human decision. |
-| `require` | Bind a required claim to recorded evidence. |
-| `blocked` / `refused` | Stop honestly when work cannot or must not continue. |
+| Primitive             | Purpose                                                                 |
+| --------------------- | ----------------------------------------------------------------------- |
+| `runCommand`          | Execute a command and record its exit code and output.                  |
+| `agentTask`           | Delegate one bounded judgment; an optional schema validates the result. |
+| `askUser`             | Request an explicit human decision.                                     |
+| `require`             | Bind a required claim to recorded evidence.                             |
+| `blocked` / `refused` | Stop honestly when work cannot or must not continue.                    |
 
 See the [primitive guides](https://github.com/operatorstack/yield/blob/main/docs/primitives/README.md) and
 [runtime reference](https://github.com/operatorstack/yield/blob/main/docs/reference/cli.md) for the full contract.
@@ -219,12 +257,12 @@ See the [primitive guides](https://github.com/operatorstack/yield/blob/main/docs
 All four SDKs implement the same execution contract. The conformance suite runs
 the same program in every language and compares observable behavior.
 
-| Language | SDK | Example |
-|---|---|---|
-| TypeScript | [`@operatorstack/yield`](https://github.com/operatorstack/yield/tree/main/sdk/typescript/) | [`release-checklist`](https://github.com/operatorstack/yield/tree/main/examples/release-checklist/) |
-| Python | [`yieldskill`](https://github.com/operatorstack/yield/tree/main/sdk/python/) | [`env-doctor`](https://github.com/operatorstack/yield/tree/main/examples/env-doctor/) |
-| Go | [`github.com/operatorstack/yield/sdk/yield`](https://pkg.go.dev/github.com/operatorstack/yield/sdk/yield) | [`investigate`](https://github.com/operatorstack/yield/tree/main/examples/investigate/) |
-| Rust | [`yieldskill`](https://github.com/operatorstack/yield/tree/main/sdk/rust/) | [`data-migration`](https://github.com/operatorstack/yield/tree/main/examples/data-migration/) |
+| Language   | SDK                                                                                                       | Example                                                                                             |
+| ---------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| TypeScript | [`@operatorstack/yield`](https://github.com/operatorstack/yield/tree/main/sdk/typescript/)                | [`release-checklist`](https://github.com/operatorstack/yield/tree/main/examples/release-checklist/) |
+| Python     | [`yieldskill`](https://github.com/operatorstack/yield/tree/main/sdk/python/)                              | [`env-doctor`](https://github.com/operatorstack/yield/tree/main/examples/env-doctor/)               |
+| Go         | [`github.com/operatorstack/yield/sdk/yield`](https://pkg.go.dev/github.com/operatorstack/yield/sdk/yield) | [`investigate`](https://github.com/operatorstack/yield/tree/main/examples/investigate/)             |
+| Rust       | [`yieldskill`](https://github.com/operatorstack/yield/tree/main/sdk/rust/)                                | [`data-migration`](https://github.com/operatorstack/yield/tree/main/examples/data-migration/)       |
 
 Cursor, Codex, and Claude Code are verified integrations. Yield also includes
 registry-backed project paths for 73 more coding agents. Those paths support
@@ -258,10 +296,16 @@ loop, multi-agent orchestrator, or security sandbox.
 Run the main checks from the repository root:
 
 ```bash
+npm run format:check
 go test ./...
 npm run test:release
 ```
 
+Run `npm run format` to format the supported source files. Install the repository
+npm dependencies first. The command also needs Go, Rust, and `uvx`. Generated
+files and evaluation sources with byte-bound receipts stay unchanged until their
+generators or evaluations run.
+
 The [example library](https://github.com/operatorstack/yield/tree/main/examples/library/) contains ten common workflows in all
 four SDKs, including code review, failure investigation, CI repair, dependency
 updates, database migration, security audit, and package release.

package/bin/runtime.mjs

@@ -1,4 +1,4 @@
-import { createRequire } from "node:module";
+import { createRequire } from "node:module"
 
 const packages = new Map([
   ["darwin:x64", "@operatorstack/yield-darwin-amd64"],
@@ -7,14 +7,14 @@ const packages = new Map([
   ["linux:arm64", "@operatorstack/yield-linux-arm64"],
   ["win32:x64", "@operatorstack/yield-windows-amd64"],
   ["win32:arm64", "@operatorstack/yield-windows-arm64"],
-]);
+])
 
 export function runtimePackage(platform = process.platform, arch = process.arch) {
-  const name = packages.get(`${platform}:${arch}`);
+  const name = packages.get(`${platform}:${arch}`)
   if (!name) {
-    throw new Error(`Yield does not provide a runtime for ${platform}/${arch}`);
+    throw new Error(`Yield does not provide a runtime for ${platform}/${arch}`)
   }
-  return name;
+  return name
 }
 
 export function resolveRuntime({
@@ -22,13 +22,13 @@ export function resolveRuntime({
   arch = process.arch,
   resolve = createRequire(import.meta.url).resolve,
 } = {}) {
-  const name = runtimePackage(platform, arch);
+  const name = runtimePackage(platform, arch)
   try {
-    return resolve(name);
+    return resolve(name)
   } catch (error) {
     throw new Error(
       `The runtime package ${name} is missing. Reinstall @operatorstack/yield for ${platform}/${arch}.`,
       { cause: error },
-    );
+    )
   }
 }

package/bin/runtime.test.mjs

@@ -1,6 +1,6 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { resolveRuntime, runtimePackage } from "./runtime.mjs";
+import test from "node:test"
+import assert from "node:assert/strict"
+import { resolveRuntime, runtimePackage } from "./runtime.mjs"
 
 const cases = [
   ["darwin", "x64", "@operatorstack/yield-darwin-amd64"],
@@ -9,22 +9,32 @@ const cases = [
   ["linux", "arm64", "@operatorstack/yield-linux-arm64"],
   ["win32", "x64", "@operatorstack/yield-windows-amd64"],
   ["win32", "arm64", "@operatorstack/yield-windows-arm64"],
-];
+]
 
 test("selects the exact runtime package for every supported target", () => {
   for (const [platform, arch, expected] of cases) {
-    assert.equal(runtimePackage(platform, arch), expected);
-    assert.equal(resolveRuntime({ platform, arch, resolve: (name) => `/packages/${name}` }), `/packages/${expected}`);
+    assert.equal(runtimePackage(platform, arch), expected)
+    assert.equal(
+      resolveRuntime({ platform, arch, resolve: (name) => `/packages/${name}` }),
+      `/packages/${expected}`,
+    )
   }
-});
+})
 
 test("rejects unsupported targets", () => {
-  assert.throws(() => runtimePackage("freebsd", "x64"), /does not provide a runtime/);
-});
+  assert.throws(() => runtimePackage("freebsd", "x64"), /does not provide a runtime/)
+})
 
 test("does not fall back when the selected package is missing", () => {
   assert.throws(
-    () => resolveRuntime({ platform: "linux", arch: "x64", resolve: () => { throw new Error("missing"); } }),
+    () =>
+      resolveRuntime({
+        platform: "linux",
+        arch: "x64",
+        resolve: () => {
+          throw new Error("missing")
+        },
+      }),
     /Reinstall @operatorstack\/yield/,
-  );
-});
+  )
+})

package/bin/yskill.mjs

@@ -1,33 +1,33 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
-import process from "node:process";
-import { resolveRuntime } from "./runtime.mjs";
+import { spawn } from "node:child_process"
+import process from "node:process"
+import { resolveRuntime } from "./runtime.mjs"
 
-let binary;
+let binary
 try {
-  binary = resolveRuntime();
+  binary = resolveRuntime()
 } catch (error) {
-  console.error(`yskill: ${error.message}`);
-  process.exit(1);
+  console.error(`yskill: ${error.message}`)
+  process.exit(1)
 }
 
 const child = spawn(binary, process.argv.slice(2), {
   stdio: "inherit",
   env: { ...process.env, YIELD_LANGUAGE: process.env.YIELD_LANGUAGE ?? "typescript" },
-});
+})
 for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
   process.on(signal, () => {
-    if (!child.killed) child.kill(signal);
-  });
+    if (!child.killed) child.kill(signal)
+  })
 }
 child.on("error", (error) => {
-  console.error(`yskill: could not start the packaged runtime: ${error.message}`);
-  process.exit(1);
-});
+  console.error(`yskill: could not start the packaged runtime: ${error.message}`)
+  process.exit(1)
+})
 child.on("exit", (code, signal) => {
   if (signal && process.platform !== "win32") {
-    process.kill(process.pid, signal);
-    return;
+    process.kill(process.pid, signal)
+    return
   }
-  process.exit(code ?? 1);
-});
+  process.exit(code ?? 1)
+})

package/dist/index.js

@@ -2,6 +2,19 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { exit, env, stdout, stderr } from "node:process";
+function verifySupervisorIdentity() {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync("skill.json", "utf8"));
+    } catch  {
+        return;
+    }
+    if (manifest.version !== 1) return;
+    if (!manifest.yield_version || env.YIELD_SUPERVISOR_VERSION !== manifest.yield_version) {
+        stderr.write(`yield: supervisor version ${env.YIELD_SUPERVISOR_VERSION || "missing"} does not match workflow Yield version ${manifest.yield_version || "missing"}\n`);
+        exit(2);
+    }
+}
 export class Blocked extends Error {
     reason;
     constructor(reason){
@@ -195,6 +208,7 @@ function emit(output) {
     exit(0);
 }
 export function defineSkill(program) {
+    verifySupervisorIdentity();
     const path = env.YIELD_JOURNAL;
     if (!path) {
         stderr.write("yield: YIELD_JOURNAL is not set; this program is run by yskill, not directly\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operatorstack/yield",
-  "version": "0.1.38",
+  "version": "0.3.0",
   "description": "Yield skill-program SDK for TypeScript: turn SKILL.md workflows into resumable programs.",
   "license": "MIT",
   "type": "module",
@@ -50,11 +50,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "optionalDependencies": {
-    "@operatorstack/yield-darwin-amd64": "0.1.38",
-    "@operatorstack/yield-darwin-arm64": "0.1.38",
-    "@operatorstack/yield-linux-amd64": "0.1.38",
-    "@operatorstack/yield-linux-arm64": "0.1.38",
-    "@operatorstack/yield-windows-amd64": "0.1.38",
-    "@operatorstack/yield-windows-arm64": "0.1.38"
+    "@operatorstack/yield-darwin-amd64": "0.3.0",
+    "@operatorstack/yield-darwin-arm64": "0.3.0",
+    "@operatorstack/yield-linux-amd64": "0.3.0",
+    "@operatorstack/yield-linux-arm64": "0.3.0",
+    "@operatorstack/yield-windows-amd64": "0.3.0",
+    "@operatorstack/yield-windows-arm64": "0.3.0"
   }
 }

package/src/index.ts

@@ -71,6 +71,20 @@ interface Journal {
   entries?: { request: Request; response: ResponseEnvelope }[];
 }
 
+function verifySupervisorIdentity(): void {
+  let manifest: { version?: number; yield_version?: string };
+  try {
+    manifest = JSON.parse(readFileSync("skill.json", "utf8")) as { version?: number; yield_version?: string };
+  } catch {
+    return;
+  }
+  if (manifest.version !== 1) return;
+  if (!manifest.yield_version || env.YIELD_SUPERVISOR_VERSION !== manifest.yield_version) {
+    stderr.write(`yield: supervisor version ${env.YIELD_SUPERVISOR_VERSION || "missing"} does not match workflow Yield version ${manifest.yield_version || "missing"}\n`);
+    exit(2);
+  }
+}
+
 type ProgramOutput =
   | { type: "request"; envelope: RequestEnvelope; requirements?: Requirement[] }
   | {
@@ -302,6 +316,7 @@ function emit(output: ProgramOutput): never {
  * the honest terminals.
  */
 export function defineSkill(program: (ctx: Context) => unknown): void {
+  verifySupervisorIdentity();
   const path = env.YIELD_JOURNAL;
   if (!path) {
     stderr.write(