@orchestraworks/cli 0.6.0 → 0.7.0

package/README.md

@@ -20,7 +20,7 @@ The full guide to every construct, secrets, connections and troubleshooting is [
 ```bash
 npm install -g @orchestraworks/cli         # the CLI, on your path as `orchestra`
 npm install @orchestraworks/cli            # the current release
-npm install @orchestraworks/cli@0.6.0      # this exact release
+npm install @orchestraworks/cli@0.7.0      # this exact release
 ```
 
 Then `import { Factory, Agent, … } from "@orchestraworks/cli"` normally — the package `exports` entry resolves

package/node_modules/@orchestraworks/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/client",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Orchestra public API TypeScript client",
   "author": "Living Computers",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "The Orchestra command line.",
   "license": "Apache-2.0",
@@ -109,13 +109,13 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.3.0",
-    "@orchestraworks/client": "0.6.0",
-    "@orchestraworks/worker": "0.0.142",
+    "@orchestraworks/client": "0.7.0",
+    "@orchestraworks/worker": "0.0.143",
     "commander": "^14.0.0",
     "liquidjs": "^10.28.0"
   },
   "optionalDependencies": {
-    "@orchestraworks/local": "0.0.142"
+    "@orchestraworks/local": "0.0.143"
   },
   "bundleDependencies": [
     "@orchestraworks/client"

package/skills/orchestra/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orchestra
-description: Use when you need to understand or explain an Orchestra concept - organization, role, agent, version, environment, machine, network rules, secret, reaching a model (subscription, model gateway and gateway key, own key), session, pipeline, work item, workflow rules, trigger, skill, file, plan, or the factory as code - or how the orchestra command line works, what the platform cannot do yet, and where an agent's knowledge belongs. A reference to read, not a list of steps.
+description: Use when you need to understand or explain an Orchestra concept - organization, role, agent, version, environment, machine, network rules, secret, reaching a model (subscription, model gateway and gateway key, own key), session, pipeline, work item and its check gates, workflow rules and the judge, trigger, skill, file, plan, or the factory as code - or how the orchestra command line works, what the platform cannot do yet, and where an agent's knowledge belongs. A reference to read, not a list of steps.
 ---
 
 # Orchestra: the ideas behind the platform
@@ -120,8 +120,9 @@ reaches the program on its standard input. It starts like any agent:
   to the agent. A schedule trigger targets a pipeline, never an agent directly.
 
 A `script` agent cannot use skills or model settings (the platform refuses both with a 400), and it cannot
-judge, read or write prose the way a model does. A turn runs its whole program again, so the program must be
-safe to run twice. It is billed as an agent: **Settings › Plan & usage** shows the plan.
+read, write or judge prose the way a model does. It can be a judge of a fixed rule, such as "the description
+has a Release notes section": the program decides and writes the check itself (section 11). A turn runs its
+whole program again, so the program must be safe to run twice. It is billed as an agent: **Settings › Plan & usage** shows the plan.
 
 **Cannot yet.**
 - Change an agent's harness after it is created. Make a new agent instead.
@@ -445,12 +446,90 @@ it, puts the code bundle's file id in it, and assigns it to an Engineer Agent.
 
 **Cannot yet.** Declare items in the factory code. Create them with `orchestra work-items create`.
 
+### Checks and gates
+
+<!-- Sources, on develop at b155aff3a8: docs/architecture/work-plane.md:197-205 (a reopen clears every check;
+one vote per writer per key; counts; nothing declares a key ahead), :274-277 (approval as an IAM-restricted
+key; isAssignee; passUsers), :480-486 (what requires reads), :490-493 (POST /decisions writes nothing), :575
+(one key per grant), :634 (.result is the latest write; .writer.* is the latest writer; counts read 0 when
+absent), :656-657 (setCheck, clearCheck; the author holds the key at save), :673 (body {result, summary?,
+evidence?}; owner and admin write every key);
+docs/architecture/iam.md:48-56 (statement shape), :1055 (no managed role but owner and admin holds the
+action); cli/src/constructs/pipeline.ts:218-228 (allowCheck; apply writes no IAM);
+cli/src/engine/pipeline-reconcile.ts:441-455 (the printed notice); cli/src/generated/cli-commands.json,
+operationId setWorkItemCheck (set-check flags: --result, --summary; evidence only through --body);
+platform/src/main/kotlin/ai/livingcomputers/softwarefactory/workplane/controller/WorkplaneWorkItemController.kt:267
+(the item path takes an id or a slug). -->
+
+**What it's for.** A gate keeps an item out of a stage until the work passed a test, a review or a person's
+approval.
+
+**What it is.** A *check* is a named key on an item, such as `ci`, `review` or `approval`. Each writer has
+one *vote* on a key: `PASS`, `FAIL` or `SKIP`, with an optional summary and evidence links. A writer's new
+vote replaces its own earlier vote. Nobody declares a key ahead: a stage's `requires` names the keys it
+reads. A *gate* is a stage's `requires` list. The platform reads it when something moves the item into the
+stage, and refuses the move when a condition is false. A gate never asks anybody: it reads the stored votes.
+
+A stage's `requires` can read these fields of a key:
+
+| Field | Value |
+|---|---|
+| `checks.<key>.result` | The result of the latest vote: `PASS`, `FAIL` or `SKIP` |
+| `checks.<key>.pass`, `.fail` | How many writers voted `PASS`, `FAIL` (0 when nobody voted) |
+| `checks.<key>.passUsers`, `.passAgents` | How many people, agents, voted `PASS` |
+| `checks.<key>.writer.isAssignee` | Whether the writer of the latest vote held the item when it voted |
+
+`.writer.isAssignee` reads the latest vote only. With two approvers, it cannot prove that neither of them
+is the assignee.
+
+**Who can write a key.** IAM decides, one key at a time: the action `work-items:setWorkItemCheck` on the
+resource `work-items/*/checks/<key>`. Owner and admin write every key. No other built-in role holds the
+action, so each agent, service account or group of people that votes needs a policy for its key. A
+policy is a list of statements, such as:
+
+```json
+{ "effect": "allow", "actions": ["work-items:setWorkItemCheck"], "resources": ["work-items/*/checks/ci"] }
+```
+
+In the factory code, `pipeline.allowCheck(agent, "review")` names that grant. Apply does not write it: it
+prints the statement for an administrator to attach to the agent's membership.
+
+**How a vote is written.**
+
+- The command: `orchestra work-items set-check <item> <key> --result PASS --summary "…"`. `<item>` is the
+  item's id or its slug, such as `bug-12`. Evidence links go in a JSON file passed with `--body @vote.json`.
+- The API: `PUT /work-items/{id}/checks/{key}` with `{result, summary?, evidence?}`.
+- A workflow rule: `setCheck` writes the rule's own vote, and `clearCheck` removes every vote on a key. The
+  person who applies the rule must hold the key.
+- A judge: a rule's `evaluate` asks an agent to vote (section 11).
+
+**A reopen clears every check.** A move from a closed stage (`DONE` or `CANCELED`) back to an open one
+removes every vote on every key, before the target stage's gate is read.
+
+**Not a check writer.** `POST /decisions` reads the text typed into the console's "+ Create" box and
+proposes the fields of a new item. It writes nothing, and it never writes a check.
+
+**Recipes.** The orchestra-fdk skill's `references/authoring.md`, "Check gates", has five complete
+examples: a model judge, a CI result, a script judge, a two-person approval and a decision model judge.
+
 ## 11. Workflow rules and the judge
 
 <!-- Sources, on develop at 19459f9ebb: docs/architecture/multi-agent-workflows.md:18-30 (a workflow is a named,
 versioned list of rules for one pipeline); docs/architecture/work-plane.md:364-370 (workflow entries pick which
 version runs on which items), :266-279 (evaluate asks a judge to decide one check; refused when the judge is the
-assignee), :573 (rule actions); AGENTS.md "API Conventions" (no runs, no graph engine). -->
+assignee), :573 (rule actions); AGENTS.md "API Conventions" (no runs, no graph engine). Judge facts, on develop
+at b155aff3a8: docs/architecture/work-plane.md:279-285 (the judge writes under its own grant, else 403; a gate
+never calls a judge; a failed judge turn writes no SESSION_FAILED, so an inStageFor rule re-runs evaluate), :658
+(evaluate starts or wakes the judge's session); platform/src/main/kotlin/ai/livingcomputers/softwarefactory/
+workplane/service/WorkItemSessionService.kt:188-208 (the turn's text names the item, the criterion and the PUT
+line); worker/script-harness/index.js:682-717 (a script turn's exit code sets the session outcome, not a check).
+A decision model judge, on 3664271a69: https://docs.typesafe.ai/api.md and platform/src/main/kotlin/ai/
+livingcomputers/softwarefactory/integration/typesafe/TypeSafeDecisionClient.kt (choice and noul questions);
+docs/architecture/work-plane.md:496-498 (a decision model picks among options and writes no text), :562-564 (the
+platform's own calls run on its key). The session lookup, on 20b09bc114: WorkItemSessionService.kt:332-392
+(converse finds the judge's link on the item, else startConversation starts a session with a link to that item
+alone); docs/architecture/work-plane.md:193-194 (session keeps the items a link names); docs/architecture/
+fwp.md:1060-1063 (ORCHESTRA_SESSION_ID on every harness process, the script's command included). -->
 
 **What it's for.** Rules do the routine moves, so people and agents do not have to: assign the next agent, move
 an item, ask for a review.
@@ -463,6 +542,25 @@ what it does: move, assign, create an item, or evaluate. There are no workflow r
 the judge's session on the item. The judge writes the check, and a stage that requires it then lets the item in.
 The item's own assignee cannot be its judge.
 
+A judge can also be a script agent that asks a *decision model*, such as TypeSafe's Jev, with the customer's own
+key. That model picks one of a fixed list of options, or gives the probability of yes, and writes no text. The
+recipe is in section 10's Recipes.
+
+**What a judge must know.**
+
+- The judge's turn names the item, the key and the criterion, and the `PUT /work-items/<id>/checks/<key>`
+  call to make. The judge must make that call itself, for example with `orchestra work-items set-check`.
+  The platform does not read the judge's reply or its session outcome into the check.
+- The judge's session is on that one item: a judge of two items has two sessions. A program can find its
+  item with `orchestra work-items list --session "$ORCHESTRA_SESSION_ID"` and read none of the turn's text.
+- The judge needs its own grant on the key (section 10). Without it, its write gets a 403, and the gate
+  stays shut.
+- A rule that names the item's assignee as the judge is refused, with a note in the item's feed.
+- A failed judge turn writes no `SESSION_FAILED` entry, so no failure rule sees it. To recover, add a rule
+  on `inStageFor` that runs `evaluate` again while the check is still absent.
+- A gate does not start a judge. Something must run `evaluate` before the move, usually a rule on entering
+  the stage before the gated one.
+
 **How it relates.** Rules move items through stages (section 9) and write to checks (section 10).
 
 **In the starter.** None yet. Agents and people move items by hand.

package/skills/orchestra-fdk/references/authoring.md

@@ -961,6 +961,491 @@ new Trigger(factory, "bug-intake", {
   each to what you declared. A revert made in the app shows in `orchestra fdk diff` as the rules apply
   would write back.
 
+## Check gates
+
+A *gate* is a stage's `requires` list. It keeps an item out of the stage until its checks say so. A
+*check* is a named key on an item. Each writer has one vote on it: `PASS`, `FAIL` or `SKIP`, with an
+optional summary and evidence links. The orchestra skill's section 10, "Checks and gates", explains the
+model. This section is the setup.
+
+**Set up a gate in four steps.**
+
+1. **Pick a key**, such as `ci`, `review` or `approval`. Nothing declares it ahead.
+2. **Write the gate.** Add conditions over the key to the stage's `requires`. A condition is
+   `{ field, op, value }`, and a count takes a number value: `{ field: "checks.approval.passUsers", op:
+   "gte", value: 2 }`. A stage reads `checks.<key>.result`, the counts `.pass`, `.fail`, `.passUsers` and
+   `.passAgents`, and `.writer.isAssignee`, which describes the latest vote only.
+3. **Grant the key to each writer.** The action is `work-items:setWorkItemCheck` on the resource
+   `work-items/*/checks/<key>`, one key per grant. Only owner and admin hold it by default. For an agent,
+   `pipeline.allowCheck(agent, "<key>")` declares the grant, and apply prints the statement for an
+   administrator to attach. Apply writes no IAM.
+4. **Make something vote.** A judge agent that a rule's `evaluate` asks, a CI job or a person runs
+   `orchestra work-items set-check <item> <key> --result PASS|FAIL|SKIP --summary "…"`. `<item>` is the
+   item's id or its slug, such as `feat-12`. Evidence links go in a JSON file passed with
+   `--body @vote.json`. A rule can also vote with `setCheck`, or clear every vote with `clearCheck`; the
+   person who applies that rule must hold the key.
+
+Before you rely on a gate, read the orchestra skill's section 11, "What a judge must know", and the
+reopen rule in its section 10. The examples follow those rules: a rule runs `evaluate` on entering the
+stage before the gated one, the judge votes with `orchestra work-items set-check`, and an `inStageFor`
+rule asks again while the check is absent.
+
+The examples build on the `factory` app and the import line of § The construct model. Example 3 runs on its
+`runtime` environment, and Examples 1 and 5 declare their own. Each example imports only the names that
+section and the earlier examples do not import, so all of them paste into one `main.ts`.
+
+### Example 1: a model judge on an OpenAI model
+
+A `codex` agent judges the `review` key through the model gateway. Its environment, `codexRuntime`, differs
+from `runtime` in two places:
+
+- **`env` sets `INITIAL_AGENT_MODE: "agent-full-access"`.** Codex opens each session with a command
+  sandbox that has no network. Without this mode, the judge cannot reach the platform to vote. The
+  egress policy still decides which hosts the judge may reach.
+- **The egress policy carries the gateway rule**, `routeModelsViaGateway`, with the gateway key's secret.
+  An agent whose model settings turn on the model gateway needs it.
+
+```ts
+import {
+  GatewayKey, Pipeline, Workflow, check, clearCheck, entered, evaluate, inStageFor, move, rule,
+} from "@orchestraworks/cli";
+
+const gatewayKey = new Secret(factory, "model-gateway-key", {
+  value: SecretValue.fromGatewayKey(new GatewayKey(factory, "model-gateway")),
+  injection: {
+    headers: [{ name: "Authorization", value: "Bearer ${secret}" }],
+    removeHeaders: ["x-api-key"],
+    hosts: ["models.orchestraworks.ai"],
+  },
+});
+
+const codexRuntime = new Environment(factory, "codex-runtime", {
+  name: "Codex judge environment",
+  image: Image.fromTag("acme/support-agent:1.0.0"),
+  platform: { os: "linux", arch: "amd64" },
+  resources: { cpu: "2", memory: "4G" },
+  env: { INITIAL_AGENT_MODE: "agent-full-access" },
+  egress: EgressPolicy.denyAll()
+    .applyPreset(egressPreset.softwareDevelopment())
+    .routeModelsViaGateway({ key: gatewayKey }),
+});
+
+const reviewer = new Agent(factory, "reviewer", {
+  environment: codexRuntime,
+  harness: "codex",
+  modelSettings: { model: "gpt-6.1-sol", enableModelGateway: true },
+  instructions: `You judge work items. You never change the code or the item.
+
+When a turn asks you to set a check:
+1. Read the item: orchestra work-items get <item id>
+2. Decide against the criterion the turn gives.
+3. Record the decision. Only this command counts; your reply is not read:
+   orchestra work-items set-check <item id> <key> --result PASS --summary "<one line: why>"
+   Use --result FAIL when the work does not meet the criterion. Use the item id and key the turn names.`,
+});
+
+const features = new Pipeline(factory, "features", {
+  itemSlugPrefix: "feat",
+  stages: [
+    { slug: "building", category: "IN_PROGRESS" },
+    { slug: "review", category: "IN_PROGRESS" },
+    { slug: "done", category: "DONE", requires: [{ field: "checks.review.result", op: "is", value: "PASS" }] },
+  ],
+}).allowCheck(reviewer, "review");
+
+const askReviewer = evaluate({
+  agent: reviewer,
+  check: "review",
+  criterion: "The change does what the item asks, its tests pass, and it adds no unrelated change.",
+});
+
+new Workflow(factory, "features-review", {
+  pipeline: features,
+  description: "Asks the reviewer agent to judge each feature in Review and moves the item on its vote.",
+  rules: [
+    rule({
+      name: "Clear the old vote and ask the reviewer on entering Review",
+      when: entered("review"),
+      then: [clearCheck("review"), askReviewer],
+    }),
+    rule({
+      name: "Ask the reviewer again after an hour with no vote",
+      when: inStageFor("review", "1h"),
+      if: { field: "checks.review.result", op: "isAbsent" },
+      then: [askReviewer],
+    }),
+    rule({ name: "Move a passed review to Done", when: check("review").is("PASS"), then: [move("done")] }),
+    rule({ name: "Send a failed review back to Building", when: check("review").is("FAIL"), then: [move("building")] }),
+  ],
+});
+```
+
+The first rule clears the vote of an earlier stay, so the second rule sees an absent check. A rule that
+writes or clears a check needs its author to hold the key, so the person who applies this workflow holds
+`review`, as owner and admin do. An `inStageFor` rule fires once in each stay in the stage. For more
+tries, add a second rule with a longer duration.
+
+**Attach the judge's grant before its first vote.** `allowCheck` only prints the policy statement, and a
+judge without it gets a 403. An administrator attaches it with the policy and membership commands of
+Example 2: write the policy for the `review` key, and take the membership id from the `membershipId` field
+that `orchestra agents get <agent id>` answers. The agent's membership already holds the policies the
+platform attached at its create, so keep them in `attach.json`.
+
+### Example 2: a CI result from GitHub Actions
+
+The CI job runs the tests and votes on the `ci` key as a service account. The FDK neither creates a
+service account nor writes a policy, so the setup is four commands, run once by an administrator:
+
+```bash
+orchestra service-accounts create --name github-ci       # note its id, svc_…, and its membershipId
+orchestra policies create --body @ci-check-policy.json   # note its id, pol_…
+orchestra organization-memberships update <membership id> --body @attach.json
+orchestra api-keys create --principal-type SERVICE_ACCOUNT --principal-id <svc id> --name github-ci \
+  --output-file github-ci-key.json
+```
+
+`ci-check-policy.json`:
+
+```json
+{
+  "name": "Write the ci check",
+  "document": {
+    "statements": [
+      { "effect": "allow", "actions": ["work-items:setWorkItemCheck"], "resources": ["work-items/*/checks/ci"] }
+    ]
+  }
+}
+```
+
+`attach.json` replaces the membership's whole list of directly attached policies. Read the list first with
+`orchestra organization-memberships get <membership id>` and keep each entry in it:
+
+```json
+{ "policyAssignments": [{ "policyId": "<pol id>", "allTeams": true }] }
+```
+
+The platform shows a key's token once, in the answer to its create, and stores only its digest. The CLI
+masks the token on the screen, so the last command writes the whole answer to `github-ci-key.json`. Store
+its `token` field as the repository secret `CHECKS_CI_KEY`, then delete the file. The gate:
+
+```ts
+{ slug: "merged", category: "DONE", requires: [{ field: "checks.ci.result", op: "is", value: "PASS" }] }
+```
+
+The job must know the item. This example uses a team convention: the branch name starts with the item's
+slug, such as `feat-12-export-csv`. Use whatever convention your team keeps, such as a line in the pull
+request body.
+
+```yaml
+name: tests
+on: pull_request
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - id: test
+        run: npm ci && npm test
+      - name: Vote on the work item's ci check
+        if: always()
+        env:
+          ORCHESTRA_BASE_URL: https://api.orchestraworks.ai
+          ORCHESTRA_API_TOKEN: ${{ secrets.CHECKS_CI_KEY }}
+          HEAD_REF: ${{ github.head_ref }}
+          TEST_OUTCOME: ${{ steps.test.outcome }}
+        run: |
+          item=$(printf '%s' "$HEAD_REF" | grep -oE '^feat-[0-9]+' || true)
+          if [ -z "$item" ]; then echo "The branch name names no work item"; exit 0; fi
+          result=FAIL
+          if [ "$TEST_OUTCOME" = success ]; then result=PASS; fi
+          run_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          printf '{"evidence":["%s"]}' "$run_url" > vote.json
+          npx --yes @orchestraworks/cli work-items set-check "$item" ci \
+            --result "$result" --summary "Tests: $TEST_OUTCOME" --body @vote.json
+```
+
+Each run replaces the account's earlier vote, so a fix pushed after a `FAIL` turns the check to `PASS`.
+`ORCHESTRA_BASE_URL` is required: the CLI never sends a token to an address it did not read from you.
+
+A GitHub event cannot write this check without the CI change. The GitHub connection delivers only
+`issues`, `issue_comment` and `pull_request` events, and none of them carries a test result.
+
+### Example 3: a script judge
+
+A `script` agent's `instructions` are a Bash program, so it judges a fixed rule with no model. Each turn's
+text reaches the program on standard input, and this program reads none of it. `evaluate` runs the judge in a
+session on that one item (the orchestra skill's section 11). So the program lists the items of its own
+session, `ORCHESTRA_SESSION_ID`, decides, and votes with `orchestra`. With no item or more than one, it stops
+with no vote. The machine image ships `orchestra` and `jq`. `orchestra` sends the agent's own token on each
+platform call, so the program holds no credential. The command also gets `PLATFORM_BASE_URL` and
+`ORCHESTRA_ORGANIZATION_ID`.
+
+```ts
+import { changed } from "@orchestraworks/cli";
+
+const notesJudge = new Agent(factory, "notes-judge", {
+  environment: runtime,
+  harness: "script",
+  instructions: `set -euo pipefail
+items=$(orchestra work-items list --session "$ORCHESTRA_SESSION_ID" --output json)
+if [ "$(printf '%s' "$items" | jq '.data | length')" != 1 ]; then
+  echo "This session is not on exactly one work item." >&2
+  exit 1
+fi
+id=$(printf '%s' "$items" | jq -r '.data[0].id')
+description=$(printf '%s' "$items" | jq -r '.data[0].description // ""')
+if printf '%s' "$description" | grep -q '^## Release notes'; then
+  orchestra work-items set-check "$id" notes --result PASS --summary "The description has a Release notes section."
+else
+  orchestra work-items set-check "$id" notes --result FAIL --summary "Add a '## Release notes' section to the description."
+fi`,
+});
+
+const releases = new Pipeline(factory, "releases", {
+  itemSlugPrefix: "rel",
+  stages: [
+    { slug: "drafting", category: "TODO" },
+    { slug: "review", category: "IN_PROGRESS", requires: [{ field: "checks.notes.result", op: "is", value: "PASS" }] },
+    { slug: "released", category: "DONE" },
+  ],
+}).allowCheck(notesJudge, "notes");
+
+const askNotesJudge = evaluate({
+  agent: notesJudge,
+  check: "notes",
+  criterion: "The description has a Release notes section.",
+});
+
+new Workflow(factory, "releases-notes", {
+  pipeline: releases,
+  description: "Asks the notes judge to check each release's description while it is drafted.",
+  rules: [
+    rule({ name: "Ask the notes judge on entering Drafting", when: entered("drafting"), then: [askNotesJudge] }),
+    rule({
+      name: "Ask the notes judge again after ten minutes with no vote",
+      when: inStageFor("drafting", "10m"),
+      if: { field: "checks.notes.result", op: "isAbsent" },
+      then: [askNotesJudge],
+    }),
+    rule({ name: "Ask the notes judge again on a recheck label", when: changed("labels.recheck"), then: [askNotesJudge] }),
+  ],
+});
+```
+
+- **The exit code sets the session outcome, not the check.** Exit 0 after any vote, `FAIL` included.
+  Exit non-zero only when the program could not vote; that turn fails, and the `inStageFor` rule asks
+  again.
+- **The judge does not see later edits.** A `FAIL` stays until a new turn asks again. So the last rule
+  asks again when a person sets or changes the `recheck` label after a fix.
+- **A turn runs the whole program again**, so it must be safe to run twice. A second vote replaces the
+  first, so this program is.
+- **Attach the `notes` grant** the way Example 1 attaches its judge's grant.
+- **The program reads only the description.** The item's JSON also holds the checks' summaries, and the
+  `FAIL` summary names the section, so a search of the whole JSON would find it there.
+
+### Example 4: approval by two people
+
+The `approval` key is granted to people through a role. The gate asks for two people's `PASS`, no `FAIL`,
+and a latest voter who does not hold the item.
+
+1. Create the policy with `orchestra policies create --body @approval-policy.json`, the same shape as in
+   example 2 with the resource `work-items/*/checks/approval`. The FDK names a policy by id; it does not
+   create one.
+2. Declare the role in code:
+
+   ```ts
+   import { Policy, Role } from "@orchestraworks/cli";
+
+   const approver = new Role(factory, "approver", {
+     name: "Approver",
+     policies: [Policy.fromId(factory, "pol_…")], // the policy from step 1
+   });
+   ```
+
+3. Give each approver the role at the pipeline's team, or at all teams:
+   `orchestra team-memberships create --membership-id <person's membership id> --team-id <team id>
+   --role-id <role id>`. A member holds one role per scope, so a person who already holds a role at that
+   scope needs one custom role that lists both sets of policies. The FDK declares team memberships for
+   agents and service accounts only, not for people.
+4. Write the gate:
+
+   ```ts
+   {
+     slug: "released",
+     category: "DONE",
+     requires: [
+       { field: "checks.approval.passUsers", op: "gte", value: 2 },
+       { field: "checks.approval.fail", op: "is", value: 0 },
+       { field: "checks.approval.writer.isAssignee", op: "is", value: false },
+     ],
+   }
+   ```
+
+An approver votes with `orchestra work-items set-check rel-7 approval --result PASS --summary "…"`.
+`passUsers` counts people only, so an agent's vote does not count toward the two. One `FAIL` holds the item
+until that person votes again.
+
+**The limit of the self-approval guard.** `.writer.isAssignee` reads the latest vote only. If the assignee
+votes first and a second person votes last, the guard passes. With two approvers, it cannot prove that
+neither of them holds the item. Keep the assignee out of the approver role when that matters.
+
+### Example 5: a decision model judge (Jev)
+
+<!-- Sources, on 74243daf6c: https://docs.typesafe.ai/api.md (the endpoint, the noul and choice questions and
+answers, a choice's criteria map, back off on 429 and 529); platform/src/main/kotlin/ai/livingcomputers/
+softwarefactory/integration/typesafe/TypeSafeDecisionClient.kt (that shape as encoded; a choice answer needs a
+string choice and a number confidence; one attempt) and platform/src/test/resources/typesafe/
+decision-transcript.json (every field name); platform/…/config/DecisionsProperties.kt:31 (a pinned version, never
+jev-latest: a new version changes the confidences); docs/architecture/work-plane.md:490-498, 562-564 (POST
+/decisions writes nothing; the platform's calls, on its key); platform/…/workplane/service/
+WorkItemSessionService.kt:332-392 (a judge's session is linked to one item); platform/…/common/api/Page.kt:11-16
+(rows under `data`); cli/src/constructs/environment.ts:717-722 and docs/architecture/egress.md:919-921, 1364-1371
+(an environment credential is added to a request to its hosts that names none, whatever the agent);
+cli/src/engine/reconcile.ts:368 and secrets-apply.ts:254-257 (apply reads the variable from its own environment);
+docs/architecture/commercial-plans-and-credits.md:268, 432 (the individual plan refuses a Secret create);
+cli/src/constructs/rules.ts:149-152 (entered fires on every entry); agents/runtime/image/Dockerfile:43 (curl, jq);
+cli/src/constructs/pipeline.ts:31-35 (`next` lists the stage slugs a move may go to);
+docs/architecture/work-plane.md:650 (a rule's move is judged against `next`); platform/…/workplane/model/
+WorkItem.kt:344 (a create with no stage lands in the first stage); platform/…/workplane/service/
+WorkplaneWorkItemService.kt:372 (a move to the item's own stage does nothing); execve(2) (one argument holds at
+most 128 KiB on Linux) and curl(1) `--data-binary` (`@-` reads the body from standard input as it is). -->
+
+A *decision model* answers by picking, not by writing: one option from a fixed list, or the probability of yes.
+TypeSafe's Jev is one. Here a `script` agent asks Jev if a request is ready to build. Jev picks `PASS` or `FAIL`
+with a confidence, and the agent votes on `ready`.
+
+- **Bring your own TypeSafe key.** The platform calls Jev only to read the text typed into the console's
+  "+ Create" box, with its own key. That call cannot write a check, and no agent gets that key. Each call this
+  judge makes bills your TypeSafe account.
+- **Set `TYPESAFE_API_KEY` in the shell that runs `orchestra fdk apply`.** Apply reads the key from that variable
+  and writes it to the Secret. On the `individual` plan, apply refuses a Secret: see the orchestra skill's
+  section 6, "Secret".
+- **The program never holds the key.** The Secret's recipe sets `Authorization: Bearer` on `api.typesafe.ai`. The
+  environment lists the Secret in `credentials`. So the edge adds the key to each request that any program on
+  this environment's machines sends to `api.typesafe.ai`, and no program holds it. Use this environment for the
+  judge only.
+- **The request and the answer follow TypeSafe's published reference**, https://docs.typesafe.ai/api.md. The
+  request is `{model, state, questions}`. The program asks one `choice` question, whose `criteria` map each
+  option to a description: here `PASS` and `FAIL`, each described from the criterion. The answer gives the
+  picked option, its confidence and each option's probability. For example: `{"answers": {"ready": {"type":
+  "choice", "choice": "PASS", "confidence": 0.88, "probabilities": {"PASS": 0.94, "FAIL": 0.06}}}}`. The image
+  ships `curl` beside `orchestra` and `jq`.
+
+```ts
+const typesafeKey = new Secret(factory, "typesafe-api-key", {
+  value: SecretValue.fromEnv("TYPESAFE_API_KEY"),
+  injection: {
+    headers: [{ name: "Authorization", value: "Bearer ${secret}" }],
+    hosts: ["api.typesafe.ai"],
+  },
+});
+
+const decisionRuntime = new Environment(factory, "decision-runtime", {
+  name: "Decision model judge environment",
+  image: Image.fromTag("acme/support-agent:1.0.0"),
+  platform: { os: "linux", arch: "amd64" },
+  resources: { cpu: "2", memory: "4G" },
+  credentials: [{ credential: typesafeKey }],
+  egress: EgressPolicy.denyAll()
+    .applyPreset(egressPreset.softwareDevelopment())
+    .allow("typesafe-api", { hosts: ["api.typesafe.ai"], priority: 300 }),
+});
+
+const readyCriterion = "The description says what to build and how to tell that it is done.";
+const minConfidence = 0.8;
+const unsureResult: "PASS" | "FAIL" = "FAIL";
+
+const readyJudge = new Agent(factory, "ready-judge", {
+  environment: decisionRuntime,
+  harness: "script",
+  instructions: `set -euo pipefail
+items=$(orchestra work-items list --session "$ORCHESTRA_SESSION_ID" --output json)
+if [ "$(printf '%s' "$items" | jq '.data | length')" != 1 ]; then
+  echo "This session is not on exactly one work item." >&2
+  exit 1
+fi
+id=$(printf '%s' "$items" | jq -r '.data[0].id')
+body=$(printf '%s' "$items" | jq --arg criterion '${readyCriterion}' '{
+  model: "jev-1.13.0",
+  state: (.data[0] | {title, description: (.description // "")}),
+  questions: {ready: {
+    type: "choice",
+    instructions: ("Is this true of the work item? " + $criterion),
+    criteria: {PASS: ("True: " + $criterion), FAIL: ("Not true: " + $criterion)}
+  }}
+}')
+answer=$(printf '%s' "$body" |
+  curl -sS --fail --max-time 30 -H 'content-type: application/json' --data-binary @- https://api.typesafe.ai/v1/systemone)
+choice=$(printf '%s' "$answer" | jq -er '.answers.ready.choice | select(. == "PASS" or . == "FAIL")')
+confidence=$(printf '%s' "$answer" | jq -e '.answers.ready.confidence | numbers')
+if jq -en --argjson c "$confidence" '$c >= ${minConfidence}' > /dev/null; then
+  result=$choice
+  summary="The decision model picked $choice with confidence $confidence."
+else
+  result=${unsureResult}
+  summary="The decision model was unsure: it picked $choice with confidence $confidence."
+fi
+orchestra work-items set-check "$id" ready --result "$result" --summary "$summary"`,
+});
+
+const requests = new Pipeline(factory, "requests", {
+  itemSlugPrefix: "req",
+  stages: [
+    { slug: "drafting", category: "TODO", next: ["inbox"] },
+    { slug: "inbox", category: "TODO" },
+    { slug: "building", category: "IN_PROGRESS", requires: [{ field: "checks.ready.result", op: "is", value: "PASS" }] },
+    { slug: "done", category: "DONE" },
+  ],
+}).allowCheck(readyJudge, "ready");
+
+const askReadyJudge = evaluate({ agent: readyJudge, check: "ready", criterion: readyCriterion });
+
+new Workflow(factory, "requests-ready", {
+  pipeline: requests,
+  description: "Asks the decision model judge if each request in Inbox is ready, and sends it back on a FAIL.",
+  rules: [
+    rule({
+      name: "Clear the old vote and ask the ready judge on entering Inbox",
+      when: entered("inbox"),
+      then: [clearCheck("ready"), askReadyJudge],
+    }),
+    rule({
+      name: "Ask the ready judge again after ten minutes with no vote",
+      when: inStageFor("inbox", "10m"),
+      if: { field: "checks.ready.result", op: "isAbsent" },
+      then: [askReadyJudge],
+    }),
+    rule({ name: "Send a request that is not ready back to Drafting", when: check("ready").is("FAIL"), then: [move("drafting")] }),
+  ],
+});
+```
+
+- **The rules work as Example 1's**, with Drafting and Inbox in place of Building and Review. By default, a new
+  request lands in Drafting, the first stage. Move it to Inbox to ask the judge. No rule moves a passed
+  request: a person moves it to Building.
+- **A PASS holds until the request next enters Inbox.** A request in Drafting can move only to Inbox, so it
+  reaches Building only through Inbox. Each entry into Inbox clears the vote and asks again. After a fix or an
+  edit, move the request back to Inbox to ask again. A move to the stage the request is in does nothing. So
+  from Inbox, move it to Drafting first.
+- **The program reads nothing from the turn.** It finds the item as Example 3 does, and the key and the
+  criterion are fixed in it. So no text from the turn reaches the question. The item's title and description
+  go in `state`. A long description can be longer than the limit for one command-line argument. So the
+  program gives the item's JSON and the TypeSafe body to `jq` and `curl` on standard input. The cost is one
+  judge for each criterion. One constant gives the criterion to the rule and to the program. Keep single
+  quotes out of it, because the program quotes it in them.
+- **The vote.** At a confidence of `minConfidence` or more, the vote is Jev's pick, `answers.ready.choice`. Below
+  it, the vote is `unsureResult`. The summary gives the pick and the confidence, and says when Jev was unsure.
+- **`FAIL` as the unsure result fails closed.** An unsure answer keeps the gate shut, and the `FAIL` rule sends
+  the request back to Drafting, as in Example 1. Set `unsureResult` to `PASS` only where a wrong pass costs
+  little.
+- **Pin the model version**, `jev-1.13.0` here. Never use `jev-latest`: a new version changes the confidences,
+  and `minConfidence` then means something else. Choose `minConfidence` from Jev's answers on your own items.
+- **One call, no retry.** TypeSafe asks a caller to back off on 429 and 529. On an HTTP error or no answer in
+  30 seconds, the program exits non-zero with no vote. It does the same when `choice` is not exactly `PASS` or
+  `FAIL`, or `confidence` is not a number. The `inStageFor` rule then asks again, as in Example 1.
+- **Attach the `ready` grant** the way Example 1 attaches its judge's grant.
+- **Example 3's warnings on the exit code and on running twice hold here too.**
+
 ## The six design principles
 
 These decide the design questions authoring throws up. When something feels like it needs new API

package/templates/engineering-team/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@orchestraworks/cli": "^0.6.0"
+    "@orchestraworks/cli": "^0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/templates/todo-factory/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@orchestraworks/cli": "^0.6.0"
+    "@orchestraworks/cli": "^0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",