@worca/app 1.3.0-rc.2 → 1.4.0-rc.1

package/README.md

@@ -90,10 +90,25 @@ and durations, the clarify Q&A, agent transcripts, and logs:
 - **AI-assisted agent creation** — describe a new agent in the UI and Worca
   generates both its system prompt and metadata (or paste your own prompt and
   let it infer just the wiring); edit, regenerate, and save.
+- **Ask forms** — an agent that needs a human can ship the UI its question is
+  asked with: JSON in its sidecar, drawn by worca from a fixed widget catalog
+  (galleries, rankings, per-item review lists, previews of the files it just
+  produced), validated on the way back, with a text projection for the CLI, chat
+  and History. Plugins can ship them too.
 - **Per-agent model & effort** — pick model and reasoning effort per agent,
   per workflow, or per run, with a clear resolution order and "save as
   workflow defaults".
 
+### Scripts
+
+- **Cards that run your own program** — a script card keeps the whole outside of
+  an agent card (typed ports, verdict routing, loops) and replaces the inside
+  with your own `node` or `shell` program, so a test gate or a
+  transform costs no model call; the **Scripts** page creates, edits, duplicates
+  and deletes them, and its test bench runs one by itself with hand-filled
+  inputs — saved as named cases with an optional expectation, re-run one at a
+  time or all at once — through the very same runner a pipeline run uses.
+
 ### Workflow Composer
 
 - **Compose your own pipeline** — drag agents onto a canvas and wire their typed
@@ -137,16 +152,32 @@ and durations, the clarify Q&A, agent transcripts, and logs:
 ### Plugins & chat
 
 - **Plugin system with marketplaces** — plugins contribute task sources
-  (e.g. GitHub Issues), agents, skills, workflow templates, models, and chat
-  channels. Install from a marketplace with an explicit consent ceremony
-  (what's installed, which secrets are required, which setup commands run);
-  updates show a commit-level preview before you accept.
+  (e.g. GitHub Issues), agents (with their ask forms), scripts, skills, workflow
+  templates, models, and chat channels. Install from a marketplace with an
+  explicit consent ceremony (what's installed, which ask forms an agent can show
+  and which file types they may display, which secrets are required, which setup
+  commands run); updates show a commit-level preview before you accept.
 - **Drive runs from chat** — bundled two-way **Telegram**, **Slack**,
   **Discord**, and **Microsoft Teams** channels: get notified on questions,
   finishes, failures, and cost pauses, and answer back with commands —
   `/status`, `/cost`, `/answer`, `/approve`, `/pause`, `/resume`, `/stop`,
   and more — with allowlist-based authorization.
 
+### Scheduled runs
+
+- **Run it later** — schedule a pipeline for a date and time, or on a repeat
+  ("every weekday at 02:00"), from New pipeline, an Ask card, the CLI
+  (`--at`, `--every`, `--cron`) or the API (`scheduledFor`, `repeat`). The
+  **Schedules** view lists what is planned and an activity feed of every miss,
+  failure and self-pause. Runs start while `worca ui` (or a `--wait` terminal) is
+  up and the machine is awake. A run can also start after another run, on its
+  branch, so runs form a train. See [docs/scheduled-runs.md](docs/scheduled-runs.md).
+- **Ask Worca schedules too** — "run the dependency upgrade every weekday at 2am"
+  becomes a run card whose main button is *Schedule*. It lists, explains, pauses,
+  resumes and skips schedules on request; moving, editing, cancelling or deleting
+  one is a card you confirm. Name a tracker issue ("fix Jira bug PROJ-123 with
+  auto, tonight") and the card runs from the issue itself, read when the run starts.
+
 ### Costs & budgets
 
 - **Cost tracking everywhere** — per-run and per-step cost estimates, a
@@ -170,6 +201,26 @@ and durations, the clarify Q&A, agent transcripts, and logs:
 
 See [`docs/team-metrics.md`](docs/team-metrics.md).
 
+### Team policy
+
+- **Team-set caps and expectations, distributed by git** — a product manager or lead publishes
+  a policy to an orphan `worca-policy` branch on the project's `origin` (protect it so only
+  maintainers push); every teammate's Worca reads it. A project carries its own policy or
+  follows another project's; a workspace follows a policy home.
+- **Soft by design** — every value is a *default* the developer may change or a *soft
+  constraint* the tighter of team and local applies to. Going past a team cap is allowed
+  after a confirmation (with an optional or required reason) and is recorded to team
+  metrics. Nothing blocks a run; unattended (`--yes`) runs warn instead of pausing.
+- **What a policy can set** — per-pipeline and total cost caps, an advisory pooled budget,
+  Ask Worca limits, a default guardrail set and a minimum tier, allowed models and step
+  defaults, marketplaces and required plugins (offered through a setup checklist, never
+  installed without a click), a default workflow, human-in-the-loop, and more.
+- **A Team policy page** — the effective policy per project or workspace (team value, yours,
+  what applies) and an editor that publishes in one commit.
+- **`worca policy show|pull|init|setup`** and `--past-team-cap [--reason "…"]` on runs.
+
+See [`docs/team-policy.md`](docs/team-policy.md).
+
 ### Models
 
 - **Bring your own models** — register any model id (a proxy, a fine-tune, an
@@ -183,6 +234,13 @@ See [`docs/team-metrics.md`](docs/team-metrics.md).
   haiku/sonnet/opus/fable tier keys so nothing falls back to the Anthropic API,
   and *Hide built-in models* (Settings › Models) drops the built-ins from every
   picker.
+- **GitHub Copilot and OpenAI-compatible endpoints, built in** — Worca's own
+  in-process bridge lets the Claude Code CLI run against a Copilot subscription
+  (Claude models through Copilot's native Anthropic endpoint, thinking intact;
+  GPT, Gemini and the rest through a translation layer) or any
+  `/chat/completions` endpoint — no LiteLLM, no second daemon. Sign in once on
+  Settings › Models › Providers, import Copilot's models, pick them anywhere.
+  See [`docs/models.md`](docs/models.md).
 
 ### Storage
 
@@ -264,20 +322,39 @@ worca --project /path/to/your/project --prompt "Add a /search endpoint" --workfl
 # pause with Ctrl+C, continue later (survives restarts)
 worca resume <pipelineId>
 
+# run it later: once, from this terminal, or on a repeat (needs `worca ui` up, or --wait)
+worca --project /path/to/your/project --prompt "Upgrade dependencies" --at "tomorrow 02:00"
+worca --project /path/to/your/project --prompt "Upgrade dependencies" --at 02:00 --wait --yes
+worca --project /path/to/your/project --file ./nightly.md --every "weekdays 02:00"
+worca schedule list
+
 # offline demo — full pipeline, no tokens
 worca --project /path/to/your/project --prompt "demo task" --mock --yes
 
 # flush pending team-metrics run records (headless machines with no UI server)
 worca metrics push
 
-# share a saved pipeline: as JSON, or as a plugin folder bundling your agents + skills
+# team policy: what applies to this project, fetch the branch now, meet the setup checklist
+worca policy show
+worca policy pull
+worca policy setup --install
+
+# share a saved pipeline: as JSON, or as a plugin folder bundling your agents, scripts + skills
 worca workflow export wf_my-flow --format json --out my-flow.json
 worca workflow import my-flow.json
 worca workflow export wf_my-flow --format plugin --target ./my-flow-plugin
+
+# scripts: list, scaffold and test a script card — no server needed
+worca script list
+worca script new runTests --runtime shell
+worca script test runTests
+worca script test shell --param command="npm test" --cwd .
+worca plugin new-script tidy --dir ./my-plugin
+worca plugin validate ./my-plugin --run-cases
 ```
 
 Run `worca --help` for all subcommands (projects, plugins, marketplaces,
-workflows, config, doctor) and flags.
+workflows, scripts, config, doctor) and flags.
 
 Exit codes, for scripts and CI wrappers: `0` the run finished (or an
 interactive run paused and you can resume it); `1` a hard error, a stop, or an
@@ -306,6 +383,8 @@ The skill starts the same deterministic orchestrator.
 - [Architecture](docs/ARCHITECTURE.md) — the whole stack in one picture
 - [Guardrails](docs/guardrails.md) — policy model, enforcement, limitations
 - [Team metrics](docs/team-metrics.md) — git-backed, team-wide run records
+- [Team policy](docs/team-policy.md) — team-set cost caps, plugins, models and guardrails from a `worca-policy` branch
+- [Models](docs/models.md) — the catalog, providers (GitHub Copilot, OpenAI-compatible) and the built-in bridge
 - [Getting started](docs/getting-started.md) — the in-app checklist, welcome and spotlight guides
 - [Storage](docs/storage.md) — where state lives, project keys, migration
 - [Releasing](docs/RELEASING.md) — how `@worca/app` versions are published

package/agents/clarify.meta.json

@@ -1,6 +1,7 @@
 {
   "key": "clarify",
   "metaVersion": 2,
+  "humanEffort": { "hours": 0.25 },
   "mockRole": "clarify",
   "inputs": [{ "id": "task", "type": "md" }],
   "outputs": [{ "id": "answers", "type": "json", "filename": "clarify.json", "artifactKind": "clarify" }],

package/agents/memoryDefragmenter.meta.json

@@ -1,11 +1,12 @@
 {
   "key": "memoryDefragmenter",
   "metaVersion": 2,
+  "humanEffort": { "factor": 0 },
   "mockRole": "memory-defrag",
   "sideEffect": "memory",
   "inputs": [
     { "id": "task", "type": "md", "required": true,
-      "directive": "Defragment the memory scope named below. Work only inside the mounted memory directory given in your system prompt (the `## Worca memory` block) \u2014 it sits under the project directory at .claude/rules/worca/; never touch anything else in the project directory." }
+      "directive": "Defragment the memory scope named below. Work only inside the memory directory your system prompt names (the `## Worca memory` block) \u2014 it sits outside the project checkout, in the run's own memory directory; the copy under the cwd's `.claude/rules/worca/` is read-only, so never write there. Never touch anything in the project directory." }
   ],
   "outputs": [
     { "id": "report", "type": "md", "filename": "defrag-report.md" },

package/agents/reviewer.meta.json

@@ -6,6 +6,66 @@
   "wantsRequest": true,
   "workspaceStrategy": "review",
   "verdict": { "filename": "impl-review-cycle{cycle}.json" },
+  "ask": {
+    "forms": {
+      "review-findings": {
+        "version": 1,
+        "title": "Confirm these findings",
+        "data": {
+          "type": "object",
+          "required": ["findings"],
+          "properties": {
+            "summary": { "type": "string", "maxLength": 4000 },
+            "findings": {
+              "type": "array",
+              "maxItems": 20,
+              "items": {
+                "type": "object",
+                "required": ["id", "title"],
+                "properties": {
+                  "id": { "type": "string", "maxLength": 64 },
+                  "severity": { "type": "string", "enum": ["critical", "major", "minor", "suggestion"] },
+                  "title": { "type": "string", "maxLength": 200 },
+                  "detail": { "type": "string", "maxLength": 2000 }
+                }
+              }
+            }
+          }
+        },
+        "answer": {
+          "type": "object",
+          "required": ["findings"],
+          "properties": {
+            "findings": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["id", "verdict"],
+                "properties": {
+                  "id": { "type": "string" },
+                  "verdict": { "type": "string", "enum": ["keep", "waive"], "default": "keep" },
+                  "note": { "type": "string", "maxLength": 2000 }
+                }
+              }
+            },
+            "notes": { "type": "string", "maxLength": 4000 }
+          }
+        },
+        "layout": [
+          { "widget": "markdown", "bind": "data.summary" },
+          { "widget": "review-list", "bind": "data.findings", "field": "findings", "label": "Findings" },
+          { "widget": "textarea", "field": "notes", "label": "Notes" }
+        ],
+        "example": {
+          "summary": "Two findings I would waive if the deviation was intended.",
+          "findings": [
+            { "id": "f1", "severity": "major", "title": "Plan deviation: the retry lives in the caller", "detail": "The plan put it in the client. Was that intentional?" },
+            { "id": "f2", "severity": "minor", "title": "No unit test for the empty-list branch", "detail": "It is covered by the integration test only." }
+          ]
+        }
+      }
+    }
+  },
   "inputs": [
     { "id": "plan", "type": "md" },
     { "id": "done", "type": "void", "required": false, "as": "worktree" }

package/agents/worca-cc-code-reviewer.md

@@ -59,6 +59,39 @@ Severity definitions (use them honestly):
 
 After writing both files, emit a short assistant note with the absolute paths of the review markdown and the review JSON, and the count of critical/major issues.
 
+## Asking the user about findings (when questions are enabled)
+
+If your task prompt carries an "Asking the user" block, you may ask ONCE — and only
+when the answer changes the verdict. Use it for findings you would waive if the
+author's intent were different (a deviation that may have been deliberate, a
+missing test that may be covered elsewhere). Do not use it to ask for permission
+to review, and never ask about a finding you are certain of.
+
+Write this to the questions file instead of the legacy `{"questions":[…]}` shape:
+
+```json
+{ "form": "review-findings",
+  "data": {
+    "summary": "One paragraph: what you are unsure about and why it matters.",
+    "findings": [
+      { "id": "f1", "severity": "major", "title": "Plan deviation: the retry lives in the caller",
+        "detail": "The plan put it in the client. Was that intentional?" }
+    ] } }
+```
+
+Then STOP — do no further work. You are resumed with:
+
+```json
+{ "form": "review-findings", "version": 1,
+  "values": { "findings": [ { "id": "f1", "verdict": "waive", "note": "Deliberate, see ADR-12." } ],
+              "notes": "" } }
+```
+
+A `waive` verdict means that finding must NOT appear as blocking in
+`review-cycleN.json`; record the waiver and the user's note in the review markdown
+so the decision is visible. A `keep` verdict changes nothing. Every finding you did
+not ask about is yours to judge as usual.
+
 ## Output contract reminders
 - The review JSON must be valid and match the shape above (`severity` from {critical, major, minor, suggestion}); it is parsed by `safeParseJson` / `readReview`.
 - Base findings on the real `git diff`, not assumptions. The review artifacts go only to the two absolute paths given — the one other place you may write is the memory directory your system prompt's `## Worca memory` block names (see the section below).

package/agents/worca-cc-memory-defragmenter.md

@@ -5,13 +5,13 @@ tools: Read, Write, Edit, Glob, Grep
 model: inherit
 ---
 
-You are the **Memory defragment** agent. worca keeps durable rules and preferences as markdown files — one topic per file, YAML frontmatter (`name`, `description`, optional `paths`; worca stamps `source` and `updated`). Your system prompt carries a `## Worca memory` block naming the scope directory you may work in (its absolute path) — a Memory defragment run mounts exactly one; that directory is the only place you read from or write to. Claude Code has already loaded every file of it into your context as rules, but editing needs a fresh Read of the file. The scope directory sits INSIDE your cwd (under `.claude/rules/worca/`); everything else in the project directory is off limits: do not read it, do not edit it, do not create anything there.
+You are the **Memory defragment** agent. worca keeps durable rules and preferences as markdown files — one topic per file, YAML frontmatter (`name`, `description`, optional `paths`; worca stamps `source` and `updated`). Your system prompt carries a `## Worca memory` block naming the scope directory you may work in (its absolute path) — a Memory defragment run mounts exactly one; that directory is the only place you read from or write to. Claude Code has already loaded every file of it into your context as rules, but editing needs a fresh Read of the file. The scope directory sits OUTSIDE the project checkout, in the run's own memory directory (worca has added it to your session's working directories, so Write and Edit work there); the copy Claude Code loaded your rules from, under the cwd's `.claude/rules/worca/`, is read-only — a write there is refused as a sensitive path, so never write there. Everything in the project directory is off limits: do not read it, do not edit it, do not create anything there.
 
 ## Ports
 
 The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
 
-- **in `task`** (md) — which scope to defragment and why (the user's request).
+- **in `task`** (md) — which scope to defragment and why: the user's request, then a `## Memory health` section worca appends — the reasons the scope is flagged and the budgets a finished defragment must meet, with the current figures.
 - **out `report`** (md) — `defrag-report.md`: what you merged, split, removed and why. Write it to the exact path the task prompt gives.
 
 ## What to do
@@ -24,9 +24,11 @@ The engine binds every port to an absolute path in the task prompt — never har
    - **Tighten hooks.** Every `description` is ONE line ≤ 160 characters that says WHEN the file is worth reading, not what it contains.
    - **Keep names** whenever the topic survives (other files and people refer to them). Never rename to a name that differs only by letter case from an existing one.
    - **Keep the frontmatter** (`name`, `description`, `paths` when present, any extra keys). Do not write `source` or `updated` — worca stamps them.
+   - **Clear the health reasons.** The task's `## Memory health` section lists why worca flags this scope; every reason that is about the files (not the write counter) must no longer hold when you finish. Its budgets line overrides the default figures below.
+   - **Keep the always-on budget.** A file WITHOUT `paths` is loaded into the context of EVERY agent on every run; a file with `paths` (comma-separated globs) loads only when an agent reads a matching file, so it costs nothing until then. The always-on bytes are the sum of the path-less files (default budget: under 16 KB for the whole scope). When over it, in this order: (a) give `paths` to every file whose rules concern particular files or directories — take the globs from the paths the file's own body names (`ui/public/scripts-view.mjs`, `test/**`), never invent a path you have not seen in the scope; (b) when only PART of a path-less file is file-specific, split that part out into its own file with `paths`; (c) condense what stays always-on — cut narrative, history, worked examples and repetition, keep each rule and its reason in a line or two. Leave path-less only what every agent needs whatever it touches (how the user works, process rules, project-wide invariants).
    - Stay within the caps: at most 50 files in the scope, each under 32 KB (aim for under 8 KB).
    - Preserve facts. Defragmenting is restructuring, not rewriting: keep every rule that is still true, in fewer and clearer files.
 3. Apply the changes with Write / Edit. To REMOVE a file (merged away, stale), make it EMPTY: Edit it, replacing its entire content — frontmatter included — with nothing. worca's sync-back treats an empty file in the mount as a deletion (an absent file too). Never leave a file that only carries frontmatter.
-4. Write `defrag-report.md` to the `report` output path: a heading, then three lists — **Merged** (`b.md → a.md: why`), **Split** (`x.md → x-1.md, x-2.md: why`), **Removed** (`stale.md: why`) — and one closing line with the file count before and after. Keep it under 60 lines.
+4. Write `defrag-report.md` to the `report` output path: a heading, then three lists — **Merged** (`b.md → a.md: why`), **Split** (`x.md → x-1.md, x-2.md: why`), **Removed** (`stale.md: why`) — and one closing line with the file count before and after, and the always-on bytes before and after. When a health reason still holds, add a **Still flagged** list: the reason and why it could not be cleared without losing a rule that is still true. Keep it under 60 lines.
 
 Never write progress notes, run summaries or anything about this run into the memory scope. Never read or write outside the scope directory except the report path.

package/agents/workspaceScanner.meta.json

@@ -1,6 +1,7 @@
 {
   "key": "workspaceScanner",
   "metaVersion": 2,
+  "humanEffort": { "factor": 0 },
   "mockRole": "workspace-scan",
   "placeable": false,
   "inputs": [{ "id": "task", "type": "md" }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/app",
-  "version": "1.3.0-rc.2",
+  "version": "1.4.0-rc.1",
   "description": "Worca — deterministic multi-agent pipeline that drives Claude Code (headless) through Plan -> Refine -> Implement -> Review, with a CLI, an installable /worca skill, and a web UI.",
   "license": "MIT",
   "author": "Sinisha Djukic",
@@ -36,22 +36,26 @@
     "ui/public/",
     "agents/",
     "skills/",
-    "scripts/install.mjs",
+    "scripts/",
+    "tools/install.mjs",
     "README.md"
   ],
   "scripts": {
     "start": "node --disable-warning=ExperimentalWarning ui/server.mjs",
     "cli": "node --disable-warning=ExperimentalWarning src/cli/worca-cc.mjs",
-    "install:agents": "node scripts/install.mjs",
+    "install:agents": "node tools/install.mjs",
     "smoke": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning src/cli/worca-cc.mjs --project sandbox --prompt \"demo task\" --mock --yes",
     "smoke:auto": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning src/cli/worca-cc.mjs --project sandbox --prompt \"demo task\" --mock --yes --workflow auto",
-    "smoke:workspace": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning scripts/smoke-workspace.mjs",
-    "smoke:plugin": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning scripts/smoke-plugin.mjs",
-    "ask:fixtures": "node --disable-warning=ExperimentalWarning scripts/ask-capture-fixtures.mjs",
-    "verify:composer": "node --disable-warning=ExperimentalWarning scripts/verify-composer-cdp.mjs",
-    "verify:run-monitor": "node --disable-warning=ExperimentalWarning scripts/verify-run-monitor-cdp.mjs",
-    "verify:theme": "node --disable-warning=ExperimentalWarning scripts/verify-theme-cdp.mjs",
-    "verify:memory": "node --disable-warning=ExperimentalWarning scripts/verify-memory-cdp.mjs",
+    "smoke:workspace": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning tools/smoke-workspace.mjs",
+    "smoke:plugin": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning tools/smoke-plugin.mjs",
+    "docker:build": "node tools/docker-build.mjs",
+    "ask:fixtures": "node --disable-warning=ExperimentalWarning tools/ask-capture-fixtures.mjs",
+    "verify:composer": "node --disable-warning=ExperimentalWarning tools/verify-composer-cdp.mjs",
+    "verify:run-monitor": "node --disable-warning=ExperimentalWarning tools/verify-run-monitor-cdp.mjs",
+    "verify:theme": "node --disable-warning=ExperimentalWarning tools/verify-theme-cdp.mjs",
+    "verify:memory": "node --disable-warning=ExperimentalWarning tools/verify-memory-cdp.mjs",
+    "verify:scripts": "node --disable-warning=ExperimentalWarning tools/verify-scripts-cdp.mjs",
+    "verify:ask-forms": "node --disable-warning=ExperimentalWarning tools/verify-ask-forms-cdp.mjs",
     "test": "rm -rf .worca-cc-test && PATH=\"$PWD/test/helpers/no-real-claude:$PATH\" WORCA_HOME=.worca-cc-test node --disable-warning=ExperimentalWarning --test --test-timeout=300000 test/*.mjs; s=$?; node test/helpers/no-real-claude/assert-none.mjs || s=1; exit $s"
   },
   "dependencies": {

package/scripts/git-diff.mjs

@@ -0,0 +1,25 @@
+// scripts/git-diff.mjs — the `gitDiff` card (spec §12.3): `git diff <ref>` in the
+// run's checkout, or per member under ctx.repos on a workspace run (one `## <key>`
+// section each), written as fenced markdown for a downstream reader. No verdict.
+import { spawnSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+
+export default async function ({ outputs, params, ctx, log }) {
+  const ref = typeof params.ref === 'string' && params.ref.trim() ? params.ref.trim() : (ctx.checkpointRef || '');
+  const stat = params.stat === true;
+  // A param is argv, not a shell word — but `--output=<path>` is still a git OPTION, and git runs with worca's privileges.
+  if (ref.startsWith('-')) throw new Error(`a ref must not start with "-": ${ref}`);
+  const args = ['diff', ...(stat ? ['--stat'] : []), ...(ref ? [ref] : [])];
+  const section = (dir, label) => {
+    const r = spawnSync('git', args, { cwd: dir, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (r.status !== 0) log('warn', `git ${args.join(' ')} in ${dir}: ${(r.stderr || '').trim() || `exit ${r.status}`}`);
+    const body = (r.stdout || '').trimEnd();
+    return `${label ? `## ${label}\n\n` : ''}\`\`\`${stat ? 'text' : 'diff'}\n${body || '(no changes)'}\n\`\`\`\n`;
+  };
+  const repos = Array.isArray(ctx.repos) && ctx.repos.length ? ctx.repos : null;
+  const md = repos ? repos.map((r) => section(r.dir, r.key)).join('\n') : section(ctx.cwd, '');
+  const out = outputs.diff?.path;
+  if (!out) throw new Error('the diff output has no path');
+  writeFileSync(out, `# Diff against ${ref || 'the working tree'}\n\n${md}`, 'utf8');
+  return { summary: `diff written (${md.length} chars${repos ? `, ${repos.length} repos` : ''})` };
+}

package/scripts/gitDiff.meta.json

@@ -0,0 +1,18 @@
+{
+  "key": "gitDiff",
+  "metaVersion": 2,
+  "displayName": "Git diff",
+  "description": "Writes the diff of the run's checkout against the run checkpoint (or a ref) as fenced markdown, one section per member on a workspace run. Runs git with worca's privileges.",
+  "domain": "coding",
+  "color": "green",
+  "icon": "<circle cx=\"6\" cy=\"6\" r=\"2\"/><circle cx=\"6\" cy=\"18\" r=\"2\"/><circle cx=\"18\" cy=\"12\" r=\"2\"/><path d=\"M6 8v8M8 6h6a4 4 0 0 1 4 4v0\" stroke-linecap=\"round\"/>",
+  "order": 30,
+  "runtime": "node",
+  "file": "git-diff.mjs",
+  "inputs": [ { "id": "done", "type": "void", "required": false } ],
+  "outputs": [ { "id": "diff", "type": "md", "when": "always", "filename": "diff-cycle{cycle}.md" } ],
+  "params": [
+    { "id": "ref", "type": "string", "label": "Base ref (blank = run checkpoint)" },
+    { "id": "stat", "type": "boolean", "label": "Stat only", "default": false }
+  ]
+}

package/scripts/js-inline.mjs

@@ -0,0 +1,11 @@
+// scripts/js-inline.mjs — the `js` card (spec §12.2): runs `params.source` as an
+// ES module through a data: URL and calls its default export with the SAME api
+// the harness gives a file script, so a snippet that works inline works as a
+// file unchanged. Imports nothing from worca (it runs with WORCA_HOME stripped).
+export default async function (api) {
+  const source = String(api?.params?.source ?? '');
+  if (!source.trim()) throw new Error('the js card has no source');
+  const mod = await import(`data:text/javascript;base64,${Buffer.from(source, 'utf8').toString('base64')}`);
+  if (typeof mod.default !== 'function') throw new Error('the source must `export default async function (api) { … }`');
+  return await mod.default(api);
+}

package/scripts/js.meta.json

@@ -0,0 +1,22 @@
+{
+  "key": "js",
+  "metaVersion": 2,
+  "displayName": "JavaScript",
+  "description": "Runs an inline JavaScript function with worca's privileges: `export default async function ({ inputs, outputs, params, ctx, log })`. Works unchanged as a file script.",
+  "domain": "general",
+  "color": "violet",
+  "icon": "<path d=\"M8 4l-4 8 4 8\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/><path d=\"M16 4l4 8-4 8\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>",
+  "order": 20,
+  "runtime": "node",
+  "file": "js-inline.mjs",
+  "ports": "config",
+  "defaultPorts": {
+    "inputs": [ { "id": "in", "type": "md", "required": false } ],
+    "outputs": [ { "id": "out", "type": "md", "when": "always", "filename": "js-cycle{cycle}.md" } ]
+  },
+  "verdict": { "filename": "js-cycle{cycle}.json" },
+  "params": [
+    { "id": "source", "type": "code", "language": "js", "label": "Source", "required": true,
+      "default": "export default async function ({ inputs, outputs, params, ctx }) {\n  const fs = await import('node:fs');\n  fs.writeFileSync(outputs.out.path, '# js card\\n');\n  return { summary: 'ok' };\n}\n" }
+  ]
+}

package/scripts/py-inline.py

@@ -0,0 +1,27 @@
+# scripts/py-inline.py — the `py` card (workbench spec §7, W17): runs
+# `params.source` in a FRESH module and calls its `main`, with the SAME api the
+# harness gives a file script, so a snippet that works inline works as a file
+# unchanged. Imports nothing from worca and nothing outside the standard library
+# (it runs with WORCA_HOME stripped), and must parse on python 3.8.
+import sys
+import types
+
+
+def main(api):
+    source = api.params.get('source') or ''
+    if not source.strip():
+        raise ValueError('the py card has no source')
+    # A REAL module, registered under its name — not a bare dict. dataclasses,
+    # pickle and typing all look a class's module up in sys.modules; with a dict
+    # namespace a `@dataclass` under `from __future__ import annotations` dies with
+    # "'NoneType' object has no attribute '__dict__'", and the same snippet saved as
+    # a file script works. "Works unchanged as a file script" has to be true.
+    module = types.ModuleType('worca_py_card')
+    module.__file__ = '<py card>'
+    sys.modules[module.__name__] = module
+    exec(compile(source, '<py card>', 'exec'), module.__dict__)
+    entry = getattr(module, 'main', None)
+    if not callable(entry):
+        raise TypeError('the source must define `def main(api): …`')
+    # A coroutine travels back up: the harness awaits whatever main returns.
+    return entry(api)

package/scripts/py.meta.json

@@ -0,0 +1,22 @@
+{
+  "key": "py",
+  "metaVersion": 2,
+  "displayName": "Python",
+  "description": "Runs an inline Python function with worca's privileges: `def main(api)`. Works unchanged as a file script.",
+  "domain": "general",
+  "color": "blue",
+  "icon": "<path d=\"M12 3h3a2 2 0 0 1 2 2v4H9a2 2 0 0 0-2 2v2H5a2 2 0 0 1-2-2V7a2 2 0 0 1 2-2h4\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/><path d=\"M12 21H9a2 2 0 0 1-2-2v-4h8a2 2 0 0 0 2-2v-2h2a2 2 0 0 1 2 2v4a2 2 0 0 1-2 2h-4\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>",
+  "order": 25,
+  "runtime": "python",
+  "file": "py-inline.py",
+  "ports": "config",
+  "defaultPorts": {
+    "inputs": [ { "id": "in", "type": "md", "required": false } ],
+    "outputs": [ { "id": "out", "type": "md", "when": "always", "filename": "py-cycle{cycle}.md" } ]
+  },
+  "verdict": { "filename": "py-cycle{cycle}.json" },
+  "params": [
+    { "id": "source", "type": "code", "language": "python", "label": "Source", "required": true,
+      "default": "def main(api):\n    with open(api.outputs.out.path, 'w', encoding='utf-8') as f:\n        f.write('# py card\\n')\n    return {'summary': 'ok'}\n" }
+  ]
+}

package/scripts/shell.meta.json

@@ -0,0 +1,24 @@
+{
+  "key": "shell",
+  "metaVersion": 2,
+  "displayName": "Shell",
+  "description": "Runs a command in the run's checkout with worca's privileges. Exit 0 fires pass, exit 1 fires fail with the output attached, any other exit pauses the run.",
+  "domain": "general",
+  "color": "amber",
+  "icon": "<path d=\"M4 17l6-5-6-5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/><path d=\"M12 19h8\" stroke-linecap=\"round\"/>",
+  "order": 10,
+  "runtime": "shell",
+  "ports": "config",
+  "defaultPorts": {
+    "inputs": [ { "id": "in", "type": "md", "required": false } ],
+    "outputs": [
+      { "id": "log", "type": "md", "when": "always", "filename": "shell-cycle{cycle}.md" },
+      { "id": "fail", "type": "md", "when": "blocking", "filename": "shell-cycle{cycle}.md" },
+      { "id": "pass", "type": "void", "when": "clean" }
+    ]
+  },
+  "verdict": { "filename": "shell-cycle{cycle}.json" },
+  "params": [
+    { "id": "command", "type": "command", "label": "Command", "description": "Runs through /bin/sh -c (cmd.exe /c on Windows) in the run's checkout.", "required": true }
+  ]
+}

package/skills/worca/SKILL.md

@@ -7,7 +7,7 @@ description: Run the node-graph multi-agent orchestrator over a software task in
 
 Drive the current project through the selected pipeline template (default `wf_default`: Plan → Refine ↺ → Implement → Review ↺ → End). Orchestration is performed by a deterministic Node.js script; this skill just launches it. Artifacts (plans, reviews, pipeline audit logs) are written under `ai-artifacts/` in the project.
 
-The orchestrator repo lives wherever it was installed. `<WORCA_REPO>` below is the absolute path of that repo (the directory containing `src/cli/worca-cc.mjs`). If you installed via `scripts/install.mjs`, the installer rewrites `<WORCA_REPO>` in this file to the real path automatically; otherwise substitute it yourself (or set an `WORCA_REPO` environment variable and use `"$WORCA_REPO"`).
+The orchestrator repo lives wherever it was installed. `<WORCA_REPO>` below is the absolute path of that repo (the directory containing `src/cli/worca-cc.mjs`). If you installed via `tools/install.mjs`, the installer rewrites `<WORCA_REPO>` in this file to the real path automatically; otherwise substitute it yourself (or set an `WORCA_REPO` environment variable and use `"$WORCA_REPO"`).
 
 ## /worca <prompt> — run the pipeline (default action)
 
@@ -29,6 +29,7 @@ Useful flags (pass through when the user asks):
 - `--model <m>` / `--permission-mode <m>` — Claude model / permission mode (default `acceptEdits`).
 - `--mock` — run the full pipeline offline with canned agents (no Claude spawn, no tokens); great for a dry run. Equivalent to setting `WORCA_MOCK=1`.
 - `--yes` / `--non-interactive` — auto-answer (clarify picks the first option; gates choose "continue"). Use for unattended runs.
+- `--at "<when>"` — schedule the run instead of starting it now (`02:00`, `tomorrow 02:00`, `+90m`, `2026-09-19 02:00`). Add `--wait` to hold the terminal and start it there; otherwise the Worca UI server starts it. `--every "weekdays 02:00"` / `--cron "0 2 * * 1-5"` repeat it. Manage with `worca schedule list | cancel <id>`. `--after <id>` starts it when that run ends (`--after-any` also on failure, `--source-from-previous` on its branch).
 
 Example:
 
@@ -52,7 +53,7 @@ This starts `ui/server.mjs` (Express + WebSocket, default port `4317`; set `PORT
 So a teammate can open Claude Code in their own repo and type `/worca <prompt>`, copy the agents and this skill into that project's `.claude/`:
 
 ```bash
-node <WORCA_REPO>/scripts/install.mjs "<targetDir>"
+node <WORCA_REPO>/tools/install.mjs "<targetDir>"
 ```
 
 - Copies `agents/*.md` into `<targetDir>/.claude/agents/` and `skills/worca/` into `<targetDir>/.claude/skills/worca/`.