@orchestraworks/cli 0.5.8 → 0.7.0

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.
@@ -265,8 +266,8 @@ unless you set one, so it wins over the open default and over the usual allow ru
 **Live effect.** The edge reads the environment's rules on each request. So an apply that changes the rules
 reaches every machine at once, machines already running included, from their next request.
 
-**How it relates.** On a request a rule allows, the edge adds the secret or connection whose `hosts` cover the
-host, and only on `https` (section 6). Calls to the Orchestra platform itself skip these rules: the agent's
+**How it relates.** On a request a rule allows, the edge adds a secret or connection whose `hosts` cover the
+host, only on `https`, and only when the request names it or an environment default covers it (section 6). Calls to the Orchestra platform itself skip these rules: the agent's
 role decides them (section 1). So a machine blocked from the code host still downloads a file through
 `orchestra files get-content`. The worker points each harness's tools at the edge through proxy variables, so
 a service the agent runs in a container needs its name in `NO_PROXY` in the environment's settings.
@@ -291,10 +292,19 @@ resolved at the edge on an allow); AGENTS.md "Egress And Credentials". Kit: cli/
 **What it's for.** It lets agents use a key without seeing it. No agent, no person and no apply output ever shows
 the value.
 
-**What it is.** A *secret* is a stored value that can be written and never read back. It declares its `hosts`
-and an `injection` recipe, the headers it sets, and the network edge adds it to each allowed `https` request
-to one of those hosts. This is *credential injection at the network edge*. When two credentials cover one
-host, the request names one with a reference, `orchestra:secret/<id>`, in place of its key.
+**What it is.** A *secret* is a stored value that can be written and never read back. It declares an
+`injection` recipe, the headers it sets and the `hosts` it sets them on, and the network edge adds it to an
+allowed `https` request to one of those hosts. A secret with no recipe is stored only, and the edge never adds it. This is *credential injection at the network edge*. The edge adds it only in two cases:
+
+- The request names it with a reference, `orchestra:secret/<id>` or `orchestra:connection/<id>`, in place
+  of its key. A `Secret` or `Connection` set as an environment `env` value is written as that reference:
+  `ANTHROPIC_API_KEY` for claude, `GH_TOKEN` for `gh`, `GITLAB_TOKEN` for `glab`, `ORCHESTRA_GIT_CREDENTIAL`
+  for git. `routeModelsViaGateway({ key })` names the gateway key this way for claude and codex. The
+  `linear`, `slack` and `teams` commands take `--connection-id <id>`.
+- The environment's `credentials` list covers the host, for a request that names nothing. The first
+  covering entry serves; with `replace: false`, a request carrying its own value keeps it.
+
+A request that names nothing and that no default covers leaves as it was sent.
 
 **How it relates.** A secret is added only where a network rule lets the request leave (section 5). Never put
 a key in an environment's settings or in instructions: the machine's processes read every setting.
@@ -325,8 +335,9 @@ network rules carry the option (sections 2 and 5).
 **A Claude or Codex subscription.**
 
 - *Claude.* `claude setup-token` prints a long-lived token. It is stored as a secret, and the network edge
-  adds it to each call to `api.anthropic.com`. The machine holds only a placeholder token and an empty API
-  key, so no agent and no person sees the real one. Never put the token in an environment's settings: they
+  adds it to each call to `api.anthropic.com` that names it. The environment's `env` names the secret in
+  `CLAUDE_CODE_OAUTH_TOKEN` by reference, `orchestra:secret/<id>`, beside an empty API key, so no agent
+  and no person sees the real one. Never put the token in an environment's settings: they
   are plain text.
 - *Codex.* A personal access token, made by a ChatGPT Business or Enterprise member, or a separate ChatGPT
   sign-in kept on a `/home` volume that every machine using it shares. A Codex sign-in stays off the model
@@ -337,7 +348,8 @@ network rules carry the option (sections 2 and 5).
 
 **An Orchestra account, through the model gateway.** The model gateway is a hosted service at
 `models.orchestraworks.ai`. One endpoint reaches OpenAI, Anthropic and open models. A *gateway key* is a key
-to it, stored as a secret. The network edge adds it to each model call, so no agent and no person sees it.
+to it, stored as a secret. `routeModelsViaGateway({ key })` names it to each harness, and the network edge
+adds it to each model call, so no agent and no person sees it.
 Without it, an agent's first message fails with "Invalid API key".
 
 - *Routing.* `orchestra model-configs` sets which providers serve a model, and in which order, so a call
@@ -348,10 +360,11 @@ Without it, an agent's first message fails with "Invalid API key".
 - *A cap.* Each gateway key can carry a monthly cap, set in the console at **Settings › Gateway keys**.
 
 **Their own provider API key.** The team's Anthropic or OpenAI API key is a secret that the network edge adds
-to calls straight to the provider, with no gateway in between.
+to calls straight to the provider, with no gateway in between. The environment names it in `ANTHROPIC_API_KEY`
+or `ORCHESTRA_WORKER_OPENAI_API_KEY`, or lists it in `credentials`.
 
 **How it relates.** Each option reaches the model through an ordinary allow rule on the model's host, and a
-secret whose `hosts` name that host (sections 5 and 6). An agent on the model gateway turns it on in its model settings (section 2). An agent on a
+secret whose recipe's `hosts` name that host (sections 5 and 6). An agent on the model gateway turns it on in its model settings (section 2). An agent on a
 subscription or its own key turns it off. For plan questions, send the person to **Settings › Plan & usage**
 in the console.
 
@@ -433,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.
@@ -451,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.
@@ -647,7 +757,7 @@ local/launch/modelkey.go (model key carriers per harness, the gateway address va
 worker/facts/families.json (how each harness takes the gateway address); on develop at f62fad1481,
 agents/runtime/assembly/common/placeholder-env (the images' placeholder ANTHROPIC_API_KEY),
 LauncherProperties.kt (the gallery images at Versions/latest), launcher/config/config.go (Dsv5 default);
-worker/facts/families.json (the ORCHESTRA_WORKER_ names), worker/service/manager_windows.go (SfdkWorker),
+worker/facts/families.json (the ORCHESTRA_WORKER_ names), worker/service/service.go (OrchestraWorker, and the previous SfdkWorker),
 infra/packer/azure-windows-runtime.pkr.hcl (the startup task), launcher/cloud/cloud.go (the VM tags);
 the proven list is the test run of 2026-10-05. -->
 
@@ -677,8 +787,8 @@ the proven list is the test run of 2026-10-05. -->
     1. The environment's `env` (`provisionSpec.env`). A declared value replaces our image's placeholder,
        never a real value. The platform stores `env` values in plain text, an environment read returns
        them, and the machine's startup data carries them.
-    2. Baked into the team's image at machine scope: on Windows the `SfdkWorker` service's `Environment`
-       registry value, on Linux a drop-in on `sfdk-worker.service`.
+    2. Baked into the team's image at machine scope: on Windows the `OrchestraWorker` service's
+       `Environment` registry value, on Linux a drop-in on `orchestra-worker.service`.
     3. The `onStartAgent` hook writes the harness's own key file: `.claude/.credentials.json` for a Claude
        sign-in, `.codex/auth.json` for `codex`, `.pi/agent/auth.json` for `pi`. A raw Claude API key has
        no file.
@@ -686,6 +796,10 @@ the proven list is the test run of 2026-10-05. -->
     `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN` for a Claude subscription token; `ORCHESTRA_WORKER_OPENAI_API_KEY`
     or `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN` for `codex`. With a gateway key, keep the agent's
     model gateway on. The platform sets the gateway address.
+  - An install replaces the service an earlier release registered as `SfdkWorker` on Windows,
+    `sfdk-worker.service` on Linux or `ai.livingcomputers.sfdk.worker` on macOS. The new ones are
+    `OrchestraWorker`, `orchestra-worker.service` and `ai.livingcomputers.orchestra.worker`. Change your own
+    scripts that name the old ones.
   - Never restart the worker service to load a key. A restart after the worker registered stops the
     machine's work, and the platform parks the VM.
   - The details: the orchestra-fdk skill's `references/environment.md`, "Tokens on a compute provider's