@orchestraworks/cli 0.5.8 → 0.7.0

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

@@ -68,8 +68,10 @@ const factory = new Factory({ name: "acme-support" });
 new Secret(factory, "openai-api-key", {
   name: "OpenAI API key",
   value: SecretValue.fromEnv("OPENAI_API_KEY_VALUE"), // read from env at apply — never in the plan
-  hosts: ["api.openai.com"], // where the edge presents it
-  injection: { headers: [{ name: "Authorization", value: "Bearer ${secret}" }] }, // how
+  injection: {
+    headers: [{ name: "Authorization", value: "Bearer ${secret}" }], // how the edge presents it
+    hosts: ["api.openai.com"], // where
+  },
 });
 
 const runtime = new Environment(factory, "runtime", {
@@ -554,26 +556,29 @@ token the platform mints. The **Claude sign-in recipe** is the one to copy when
 on a person's Claude subscription token rather than an API key:
 
 ```ts
-new Secret(factory, "claude-sign-in", {
+const claudeSignIn = new Secret(factory, "claude-sign-in", {
   value: SecretValue.fromEnv("ORCHESTRA_FDK_CLAUDE_CODE_OAUTH_TOKEN"),
-  hosts: ["api.anthropic.com"],
   injection: {
     headers: [{ name: "authorization", value: "Bearer ${secret}" }],
     removeHeaders: ["x-api-key"], // stripped before injection
+    hosts: ["api.anthropic.com"],
   },
 });
 
 // …in the Environment's props:
-env: { CLAUDE_CODE_OAUTH_TOKEN: "software-factory-egress-placeholder", ANTHROPIC_API_KEY: "" },
+env: { CLAUDE_CODE_OAUTH_TOKEN: claudeSignIn, ANTHROPIC_API_KEY: "" },
 egress: EgressPolicy.allowAll()
   .allow("claude-sign-in", { hosts: ["api.anthropic.com"], priority: 300 }),
 ```
 
 It injects `authorization` and nothing else. **Never inject an `anthropic-beta` header**: an injected
-one replaces the harness's own list of beta flags, and every call then answers 400. The placeholder
-`CLAUDE_CODE_OAUTH_TOKEN` makes the harness sign in the subscription way and send its own list, and the
-edge swaps the real token in. The empty `ANTHROPIC_API_KEY` covers the runtime image's placeholder key,
-which the harness would otherwise send instead.
+one replaces the harness's own list of beta flags, and every call then answers 400. A Secret as an `env`
+value is written as its reference, `orchestra:secret/<id>`, with the id resolved at apply. In
+`CLAUDE_CODE_OAUTH_TOKEN` it makes the harness sign in the subscription way and send its own list, and the
+edge reads the reference where the token goes and swaps the real token in. The edge adds a credential only
+to a request that names one, or that an environment default covers (`references/environment.md`, "Naming a
+credential"). The empty `ANTHROPIC_API_KEY` covers the runtime image's placeholder key, which the harness
+would otherwise send instead.
 
 - Sources: `SecretValue.fromEnv(NAME)`, `SecretValue.fromCommandLine(label?)` and
   `SecretValue.fromGatewayKey(key)`, plus the derived recipes `basicAuth`, `registryCredential` and
@@ -613,7 +618,7 @@ which the harness would otherwise send instead.
   `GatewayKey` you declare in the same factory — `new GatewayKey(factory, "model-gateway-key", props)`,
   whose only props are `slug`, `displayName`, `monthlyCreditCap` and `labels` — so apply mints the
   key and writes the token it shows *exactly once* straight into this Secret, which the edge then
-  adds on its `hosts` like any other. It is legal only as the whole top-level value of exactly one Secret:
+  adds on its recipe's `hosts` like any other. It is legal only as the whole top-level value of exactly one Secret:
   nesting it inside another recipe, or a key with zero or two Secrets, is a synth error, and there
   is no importer because an existing key's token is unrecoverable. Rotation is new-slug-only.
 - A **`ModelProviderKey`** is the other credential you can declare: your organization's own key for
@@ -648,11 +653,12 @@ which the harness would otherwise send instead.
   suppresses it and none can supply it either, so a headless apply of a `fromCommandLine`
   declaration refuses at *every* level and tells you to run from a terminal or change the source —
   it never recommends a policy lever that could not clear it.
-- Presenting a secret on the network: the `Secret` itself declares `hosts` (where: an exact host,
-  `*.suffix`, or `*`) and an `injection` recipe (how: the headers it sets, reading `${secret}`, or
-  `${secret.<field>}` for a `SecretValue.fields` value). Egress rules carry no credential, so a rule
-  that passes `credential` or `credentials` is a synth error; a Secret with no `hosts` is presented
-  nowhere.
+- Presenting a secret on the network: the `Secret` itself declares an `injection` recipe — how: the
+  headers it sets, reading `${secret}`, or `${secret.<field>}` for a `SecretValue.fields` value; and
+  where: its `hosts`, each an exact host, `*.suffix`, or `*`. Egress rules carry no credential, so a rule
+  that passes `credential` or `credentials` is a synth error. A Secret with no `injection` is stored
+  only, and one whose recipe has no `hosts` is presented nowhere. The top-level `hosts` prop is
+  deprecated: it is moved into the recipe for one release.
 
 ## How the agents reach a model
 
@@ -668,9 +674,9 @@ on their own computer; run from your shell, its browser step hangs. Never read o
   At apply, the shell exports it from that file into the variable the Secret reads. Declare the Claude
   sign-in recipe (§ Secrets are recipes, never values): a `Secret`, an egress rule that allows
   `api.anthropic.com` and sets `Authorization: Bearer ${secret}` with `x-api-key` removed, and, in the
-  environment's `env`, `CLAUDE_CODE_OAUTH_TOKEN: "software-factory-egress-placeholder"` and an empty
-  `ANTHROPIC_API_KEY`. Turn `enableModelGateway` off for the agent. The machine holds only the
-  placeholder; the edge adds the token. Copying the renewing credentials file instead is the fallback,
+  environment's `env`, `CLAUDE_CODE_OAUTH_TOKEN` set to that Secret and an empty `ANTHROPIC_API_KEY`.
+  Turn `enableModelGateway` off for the agent. The machine holds only the Secret's reference; the edge
+  adds the token. Copying the renewing credentials file instead is the fallback,
   and follows the ChatGPT sign-in steps below.
 - **Codex: a personal access token, where the workspace allows one.** A ChatGPT Business or Enterprise
   member creates it at chatgpt.com/admin/access-tokens, once the workspace owner allows access tokens,
@@ -762,7 +768,7 @@ An environment's `egress` is a policy you build up from one of **two starting po
 - **`EgressPolicy.allowAll()`** allows every host no rule refuses.
 
 Rules fold onto either one the same way: a rule only opens or closes the network, a credential still goes
-only to the hosts its own `hosts` cover, and a deny still refuses.
+only to the hosts its own recipe's `hosts` cover, and a deny still refuses.
 
 Most of what an agent needs to reach arrives ready-made as a **bundle** — a list of rules folded onto
 the policy by one `applyPreset(...)` call — so **reach for the bundles first** and hand-write allow/deny
@@ -955,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
@@ -1079,7 +1570,7 @@ orchestra gateway-keys create --slug ci-smoke --output-file key.json
   export, a CI secret) suppresses the only prompt you would have seen, the command says so in one
   line on **stderr**, naming the lever — stdout stays the response document.
 - **Writing to a factory-managed resource warns.** `apply` stamps what it manages with an
-  `sfdk.managedBy` labels key naming the owning factory, and a write to a stamped resource says so:
+  `orchestra.managedBy` labels key naming the owning factory, and a write to a stamped resource says so:
   the next `apply` reverts it. It is a warning, not a refusal — the fallback has to stay usable in an
   emergency — and it is the CLI telling you this belongs in `main.ts`.