@worca/app 1.2.0-rc.3 → 1.3.0-rc.2

package/README.md

@@ -19,6 +19,19 @@ Claude Code — all running the same engine. See the
 
 ## How a run works
 
+Pick **Auto** (`--workflow auto` on the CLI; the web picker's Auto entry ships with
+the UI update) and worca picks the workflow for you: it classifies the task (a
+free-form prompt, a partial plan, or a complete plan; web feature or not; trivial or
+large) from the task text, the attached files and a small offline fingerprint of the
+repository, knowing every agent by its metadata and the front matter of its agent
+file (never the agent's full instructions), assembles a matching workflow from those
+agents, reuses a saved workflow when one has exactly that shape — otherwise the
+proposal is saved as a new workflow when you accept it — and, with *Human in the
+loop* on, shows you the proposal first so you can accept it, ask for changes in plain
+text, or cancel. Turn the switch off and the run decides on its own, asks no
+questions, and never stops for you. Pick any saved workflow instead to skip all of
+this.
+
 1. **Clarify** — instead of assuming, the planner turns hidden decisions into
    multiple-choice questions (2–4 options plus free text). Your answers are
    appended to the plan so reviewers see them.
@@ -145,6 +158,18 @@ and durations, the clarify Q&A, agent transcripts, and logs:
 
 ![Statistics — spend, time worked, outcomes, and per-day charts](docs/screenshots/stats.png)
 
+### Team metrics
+
+- **A shared, git-backed record** — every finished run is pushed as one file to an orphan
+  `worca-metrics` branch on the project's own `origin`; there is no separate metrics server.
+- **Opt-in per project, with delegation** — enable it on the repository itself, or delegate to
+  another project (or a workspace's metrics home) that already records.
+- **A Team metrics page** — project and workspace scope, spend/runs/duration/autonomy/review
+  KPIs, breakdowns and a CSV export.
+- **`worca metrics push`** — flush pending run records from the CLI, e.g. on a headless machine.
+
+See [`docs/team-metrics.md`](docs/team-metrics.md).
+
 ### Models
 
 - **Bring your own models** — register any model id (a proxy, a fine-tune, an
@@ -215,6 +240,12 @@ worca ui --port 4318 --open     # another port; open the browser when up
 `status` remember the port of the last started UI, so they usually need no
 flag. See `worca ui help`.
 
+**Appearance.** Settings › General › Appearance picks **System** (follow the
+operating system), **Light** or **Dark** — one setting for every browser that
+opens this Worca. The web UI relies on CSS `light-dark()` (and `::backdrop`
+inheriting the dialog's scheme), so it needs Chrome/Edge 123, Firefox 120 or
+Safari 17.5 (or newer).
+
 ### CLI
 
 ```bash
@@ -224,12 +255,21 @@ worca --project /path/to/your/project --prompt "Add a /search endpoint"
 # use a markdown brief as the prompt
 worca --project /path/to/your/project --file ./brief.md --title "Search feature"
 
+# let worca pick the workflow for the task (Auto), review the proposal first
+worca --project /path/to/your/project --prompt "Add a /search endpoint" --workflow auto
+
+# Auto run with no proposal and no questions (loop-budget, recovery, cost and error pauses still apply; add --yes when nothing can answer them, e.g. in CI)
+worca --project /path/to/your/project --prompt "Add a /search endpoint" --workflow auto --no-human
+
 # pause with Ctrl+C, continue later (survives restarts)
 worca resume <pipelineId>
 
 # 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
 worca workflow export wf_my-flow --format json --out my-flow.json
 worca workflow import my-flow.json
@@ -265,6 +305,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
+- [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
 - [Contributing](CONTRIBUTING.md) — developing Worca from source

package/agents/memoryDefragmenter.meta.json

@@ -0,0 +1,24 @@
+{
+  "key": "memoryDefragmenter",
+  "metaVersion": 2,
+  "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." }
+  ],
+  "outputs": [
+    { "id": "report", "type": "md", "filename": "defrag-report.md" },
+    { "id": "done", "type": "void" }
+  ],
+  "domain": "shared",
+  "displayName": "Memory defragment",
+  "description": "Restructures one memory scope: merges duplicates, splits overgrown topics, drops stale rules, tightens hooks.",
+  "color": "violet",
+  "icon": "<path d=\"M4 6h16M4 12h16M4 18h10\" stroke-linecap=\"round\"/><path d=\"M17 15l2 2 4-4\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>",
+  "agentFile": "worca-cc-memory-defragmenter.md",
+  "runnerType": "producer",
+  "fanOut": false,
+  "asksQuestions": false,
+  "order": 8
+}

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

@@ -61,9 +61,14 @@ After writing both files, emit a short assistant note with the absolute paths of
 
 ## 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. Write only to the two absolute paths given.
+- 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).
 - Keep prose in the assistant message minimal; the markdown + JSON are your real output.
 
+## Worca memory
+After the verdict is written: if you flagged a defect class that will recur in this area — a class, never this diff's individual bugs — record the rule that prevents it in the memory directory your system prompt's `## Worca memory` block names, following the WRITE TRIGGER there.
+It qualifies only if it cost a cycle (or would cost the next reviewer one) or contradicted what the implementer assumed, AND will still be true next month.
+At most 1–2 files per run, and prefer editing an existing file over adding one. Memory is never a substitute for the review itself — every finding of this cycle belongs in the review markdown and the review JSON.
+
 ## Workspace runs
 You are NOT used for workspace runs: a workspace pipeline substitutes the **Workspace Reviewer** (`workspaceReviewer`), which fans out one reviewer per changed member and synthesizes one merged verdict. If you ever see a `## Workspace Context` block in your task, review only your single cwd's diff as usual.
 

package/agents/worca-cc-implementer.md

@@ -66,11 +66,16 @@ If (and only if) you had to deviate, append a brief, factual note so it survives
 ## Quality bar
 - No TODOs, stubs, placeholders, or commented-out dead code in what you ship.
 - Match the project's existing style and structure exactly.
-- Only the files the plan (implement) or the review (fix) require should change.
+- Only the files the plan (implement) or the review (fix) require should change (the memory directory your system prompt names is not part of the change set).
 - All tests green before you finish.
 
 After finishing, emit a concise assistant note summarizing: mode, which plan steps or review issues you handled, the tests you added/ran and their result, and any deviations (or "No deviations"). This summary is returned to the orchestrator.
 
+## Worca memory
+Once the suite is green: if this run hit a trap, an unstated invariant or a verification recipe that cost you a cycle — or that contradicted what you assumed when you started — and it will still be true next month, record it in the memory directory your system prompt's `## Worca memory` block names, following the WRITE TRIGGER there.
+In **fix** mode the review that bounced you is the highest-signal source: the rule that would have prevented the finding, never the finding itself.
+At most 1–2 files per run, and prefer editing an existing file over adding one. Memory is never a substitute for this run's own outputs — DEVIATIONS.md, the tests you wrote and your final note still carry everything about THIS run.
+
 ## Workspace runs
 When the task prompt carries a `## Workspace Context` block, your task names ONE plan task plus the project(s) it touches (its `Projects:` tag) and a `## Workspace projects` block gives each member's worktree directory. Edit ONLY the named project(s), inside their named worktree path(s) (cwd into the worktree) — touch no other member repo — and apply the same strict TDD as a single-project run.
 

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

@@ -0,0 +1,32 @@
+---
+name: worca-cc-memory-defragmenter
+description: Memory defragmenter for worca. Restructures ONE scope of worca's durable memory (global or one project) inside the run's memory mount — merges duplicate topics, splits overgrown files, removes stale or contradicted rules, tightens hooks — and writes a short report. Never touches the project directory. Invoked by the Memory defragment workflow, never directly by a human.
+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.
+
+## 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).
+- **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
+
+1. Read EVERY `*.md` file of the scope directory (Glob it; the bodies are in your context already, but Edit needs the file read in this session).
+2. Decide the target structure. Rules:
+   - **One topic per file.** Merge files that cover the same topic into one; keep the older, better-named file and fold the other's body in, then remove the file you folded in (step 3).
+   - **Split** a file that has grown past one topic (or past ~8 KB) into focused files with short kebab-case names (`[A-Za-z0-9._-]`, no leading dot, no `.md` in the name field).
+   - **Remove** a rule that is stale, superseded or contradicted; when two rules conflict, the one with the newer `updated` stamp wins.
+   - **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.
+   - 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.
+
+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/worca-cc-planner.md

@@ -69,9 +69,13 @@ After writing the file, emit a short assistant note confirming the absolute plan
 This is a variant of PLAN mode. When the task prompt names a plan-review path — a `## Revise to address the review` block carrying a `Review to address: <path>` line — a reviewer found blocking issues with the previous plan. Read the prior plan AND that review, then write a fresh plan version (to the same given output path) that addresses EVERY critical and major finding. Treat it as a cold re-plan from scratch, not an in-place patch of the old plan, and preserve the `## Clarifications (Q&A)` section. All PLAN requirements still apply.
 
 ## Output contract reminders
-- Write files with absolute paths taken from the prompt. Never write outside the pipeline dir / the given plan path.
+- Write files with absolute paths taken from the prompt. Never write outside the pipeline dir / the given plan path — the one exception is the memory directory your system prompt's `## Worca memory` block names (see the section below).
 - Keep assistant chatter minimal; your real output is the file you write.
 
+## Worca memory
+After the plan is written: if exploring the codebase surfaced a constraint the plan had to design around — one that cost you a cycle, or that contradicted what you assumed when you started, and will still be true next month — record it in the memory directory your system prompt's `## Worca memory` block names, following the WRITE TRIGGER there.
+At most 1–2 files per run, and prefer editing an existing file over adding one. Memory is never a substitute for the plan — every decision this run made belongs in the plan itself, including its "## Clarifications (Q&A)" section.
+
 ## Workspace runs
 When the task prompt carries a `## Workspace Context` block, you are planning across a SET of member projects. Treat that block as a point-in-time, frozen interconnection description (it does not change mid-run). Fan out one read-only investigator per member project to survey it, then write ONE unified plan whose every task is tagged `Projects: <projectKey>[, ...]` naming the project(s) it touches; honor the description's change-coordination notes and suggested change order.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/app",
-  "version": "1.2.0-rc.3",
+  "version": "1.3.0-rc.2",
   "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",
@@ -44,12 +44,15 @@
     "cli": "node --disable-warning=ExperimentalWarning src/cli/worca-cc.mjs",
     "install:agents": "node scripts/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",
-    "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/*.mjs; s=$?; node test/helpers/no-real-claude/assert-none.mjs || s=1; exit $s"
+    "verify:theme": "node --disable-warning=ExperimentalWarning scripts/verify-theme-cdp.mjs",
+    "verify:memory": "node --disable-warning=ExperimentalWarning scripts/verify-memory-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": {
     "@highlightjs/cdn-assets": "11.12.0",

package/src/cli/render.mjs

@@ -146,3 +146,39 @@ export function formatRunSummary(state) {
   }));
   return lines;
 }
+
+/**
+ * The interactive Auto proposal (spec §9): what the question panel shows in the
+ * browser, as text. Pure — the payload is `question.workflow` (auto/proposal.mjs).
+ * Stages follow the proposal's DISPATCH `order` (a reused composer row's node order
+ * is arbitrary); every model/plugin-authored string in the payload was cleaned by
+ * the assembler (single line, no control characters), so it is safe to print.
+ * @param {object} w the proposal
+ * @returns {string[]} lines
+ */
+export function formatWorkflowProposal(w) {
+  const p = w && typeof w === 'object' ? w : {};
+  const where = p.match
+    ? `(same shape as your saved workflow "${p.match.name}" — Accept reuses it)`
+    : `(no saved workflow has this shape — Accept saves it as "${p.name ?? ''}")`;
+  const lines = [`? Auto proposes a workflow · round ${p.round || 1}  ${where}`];
+  if (p.reasoning) lines.push(`  ${p.reasoning}`);
+  // buildProposal defaults `size` to 'medium', so every REAL proposal prints this line;
+  // the guard only spares the unit fixtures that carry neither field.
+  const cues = [p.size, ...(Array.isArray(p.signals) ? p.signals : [])].filter(Boolean);
+  if (cues.length) lines.push(`  ${cues.join(' · ')}`);
+  const nodes = p.manifest?.graph?.nodes || [];
+  const wires = p.manifest?.graph?.wires || [];
+  const agents = nodes.filter((n) => n.kind === 'agent');
+  const ordered = Array.isArray(p.order) && p.order.length
+    ? p.order.map((id) => agents.find((n) => n.id === id)).filter(Boolean)
+    : agents;
+  const labelOf = (id) => nodes.find((n) => n.id === id)?.label || id;
+  const tune = (n) => [n.model, n.effort].filter(Boolean).join(' · ');
+  lines.push(`  stages: ${ordered.map((n) => `${n.label || n.key}${tune(n) ? ` (${tune(n)})` : ''}${n.fanOut ? ' ⤴' : ''}`).join(' → ')}`);
+  for (const l of wires.filter((x) => x.loop)) lines.push(`  loop: ${labelOf(l.from.node)} → ${labelOf(l.to.node)} (max ${l.maxCycles} cycles)`);
+  if (p.ignoredProjectOverrides) lines.push('  note: this project\'s saved settings for that workflow are not applied to Auto runs');
+  for (const msg of p.warnings || []) lines.push(`  ! ${msg}`);
+  if (Number(p.costUsd) > 0) lines.push(`  classifier cost so far: $${Number(p.costUsd).toFixed(2)}`);
+  return lines;
+}

package/src/cli/worca-cc.mjs

@@ -27,7 +27,7 @@ import {
   normalizeProjectPath,
 } from '../core/projects.mjs';
 import { projectKey } from '../core/store.mjs';
-import { formatExecLine, formatGateHeader, formatRunSummary } from './render.mjs';
+import { formatExecLine, formatGateHeader, formatRunSummary, formatWorkflowProposal } from './render.mjs';
 import { pauseExitCode, describePauseReason, promptOptions, REASON } from '../core/failure-policy.mjs';
 import { effectiveDebugSpawn } from '../core/settings.mjs';
 import {
@@ -97,6 +97,7 @@ function parseArgs(argv) {
     install: null,
     sourceBranch: undefined,
     featureBranch: undefined,
+    memoryScope: undefined,
     help: false,
     _: [],
   };
@@ -112,6 +113,7 @@ function parseArgs(argv) {
     '--install',
     '--source-branch',
     '--branch',
+    '--memory-scope',
   ]);
   const map = {
     '--project': 'project',
@@ -125,6 +127,7 @@ function parseArgs(argv) {
     '--install': 'install',
     '--source-branch': 'sourceBranch',
     '--branch': 'featureBranch',
+    '--memory-scope': 'memoryScope',
   };
 
   for (let i = 0; i < argv.length; i++) {
@@ -141,6 +144,10 @@ function parseArgs(argv) {
       out.auto = true;
       continue;
     }
+    if (arg === '--no-human') {
+      out.humanInLoop = false;
+      continue;
+    }
     if (arg === '--ui') {
       out.ui = true;
       continue;
@@ -171,6 +178,8 @@ function parseArgs(argv) {
         // MOCK runner treats it as the Ask Worca recipe — that pair is refused below,
         // after --mock/WORCA_MOCK are known (review of PR #376).
         fail(`--permission-mode must be one of ${PERMISSION_MODES.join(', ')}, got: ${value}`);
+      } else if (key === 'memoryScope' && !['global', 'project'].includes(String(value))) {
+        fail(`--memory-scope must be one of global, project, got: ${value}`);
       } else {
         out[key] = value;
       }
@@ -226,6 +235,7 @@ Subcommands:
   ui [start|stop|restart|status]
                               Run the web UI (default http://localhost:4317). See: worca ui help
   workflow <cmd> [...]        Export a workflow (Claude Code skill, JSON, or plugin) / import JSON: list|export|import. See: worca workflow help
+  metrics push [--project <path>]   Push pending team-metrics run records (headless flush)
   help                        Print this help (same as --help).
   version                     Print the version (same as --version).
 
@@ -240,6 +250,10 @@ Options:
   --permission-mode <m>    Claude permission mode: default | acceptEdits | plan |
                            bypassPermissions (default acceptEdits)
   --workflow <id>          Saved pipeline template to run (default: wf_default — the built-in graph)
+                           auto (= wf_auto) lets worca pick the workflow per task
+  --no-human               Auto workflow only: no proposal, no clarify, no agent questions (loop-budget, recovery, cost and error pauses still apply)
+  --memory-scope <s>       Memory defragment workflow only: global | project — the scope the
+                           run restructures (--workflow wf_memory_defrag needs it; no --prompt needed)
   --source-branch <name>   Branch to fork the per-run worktree from (default: current HEAD)
   --branch <name>          Feature branch name (default: claude proposes one)
   --mock                   Offline mock mode (no claude, no tokens)
@@ -385,6 +399,27 @@ async function askRecovery(rl, recovery) {
   return { decision };
 }
 
+/**
+ * Ask the Auto workflow proposal (spec §9). Empty input accepts, `r` reads one line of
+ * revise text, `c` cancels the run. Returns the `workflow` answer payload.
+ */
+async function askWorkflow(rl, workflow) {
+  out('');
+  for (const line of formatWorkflowProposal(workflow)) out(c('yellow', line));
+  out('  a) Accept and run');
+  out('  r) Revise — describe what to change');
+  out('  c) Cancel the run');
+  for (;;) {
+    const raw = (await question(rl, c('cyan', 'Choose [a/r/c]: '))).trim().toLowerCase();
+    if (raw === '' || raw === 'a' || raw === 'accept') return { decision: 'accept' };
+    if (raw === 'c' || raw === 'cancel') return { decision: 'cancel' };
+    if (raw === 'r' || raw === 'revise') {
+      const text = (await question(rl, c('cyan', 'What should change? '))).trim();
+      if (text) return { decision: 'revise', text };
+    }
+  }
+}
+
 // ── shared drive loop ────────────────────────────────────────────────────────────
 
 /**
@@ -430,7 +465,13 @@ async function attachAndDrive(orch, flags, start) {
   // `Failed to read answer: readline was closed` and exited 0 with the row left
   // `running` — a CI job read success on an abandoned run.
   if (!flags.auto && !stdinCanAnswer()) {
-    fail('stdin cannot answer prompts (it is /dev/null or closed) — pass --yes for a non-interactive run.');
+    // `--no-human` silences the Auto proposal, the clarify card and agent questions only;
+    // the loop-budget and recovery gates still ask (spec D3), so a CI user who passed it
+    // must be told which flag is missing (PR #434 review, finding 4).
+    const hint = flags.humanInLoop === false
+      ? '--no-human leaves the loop-budget and recovery gates interactive; pass --yes for a non-interactive run.'
+      : 'pass --yes for a non-interactive run.';
+    fail(`stdin cannot answer prompts (it is /dev/null or closed) — ${hint}`);
   }
   const rl = flags.auto ? null : makeRl();
   let answering = false; // serialize interactive prompts vs. log rendering
@@ -536,6 +577,9 @@ async function attachAndDrive(orch, flags, start) {
       } else if (kind === 'recovery') {
         const payload = await askRecovery(rl, recovery);
         orch.answer(id, payload);
+      } else if (kind === 'workflow') {
+        const answer = await askWorkflow(rl, payload.workflow);
+        orch.answer(id, answer);
       } else if (kind === 'questions') {
         out(c('yellow', c('bold', `${agent || 'Agent'} has questions:`)));
         const payload = await askClarify(rl, questions || []);
@@ -856,6 +900,12 @@ async function cmdAdd(argv) {
   try {
     await addProject({ name, path: target });
     out(`Added project "${name}" -> ${target}`);
+    // CLI-only machines have no hourly loop (decision 25): warm the discovery cache now
+    // so a teammate's team-metrics branch is seen without waiting on the UI server.
+    try {
+      const m = await import('../core/metrics/sync.mjs');
+      await m.discoverProject(target, { force: true });
+    } catch { /* metrics never block `worca add` */ }
     return 0;
   } catch (err) {
     process.stderr.write(`worca: ${err?.message || err}\n`);
@@ -1160,7 +1210,9 @@ async function cmdResume(argv) {
     auto,
     resume: saved,
   });
-  return attachAndDrive(orch, { auto }, () => orch.resume());
+  const code = await attachAndDrive(orch, { auto }, () => orch.resume());
+  await drainMetricsFlushes();
+  return code;
 }
 
 // ── plugin subcommands ─────────────────────────────────────────────────────────
@@ -1891,9 +1943,9 @@ async function cmdWorkflow(argv) {
   try {
     switch (verb) {
       case 'list': {
-        // GRAPH_DEFAULT_WORKFLOW (the built-in default) is not in the user store, so
-        // prepend it — mirrors the server/UI, which always show it first.
-        const items = [wf.GRAPH_DEFAULT_WORKFLOW, ...(await wf.listWorkflows())];
+        // The built-ins (Default, Memory defragment) are not in the user store, so
+        // prepend them — mirrors the server/UI, which always show them first.
+        const items = [wf.GRAPH_DEFAULT_WORKFLOW, wf.GRAPH_MEMORY_DEFRAG_WORKFLOW, ...(await wf.listWorkflows())];
         for (const w of items) out(`${w.id}\t${w.name}\t${(w.domain || 'general')}`);
         return 0;
       }
@@ -2012,9 +2064,67 @@ async function cmdWorkflow(argv) {
   }
 }
 
+// ── metrics subcommand ───────────────────────────────────────────────────────────
+
+const METRICS_HELP = `worca metrics — team metrics (git-backed, team-wide run records)
+
+Usage:
+  worca metrics push [--project <path>]   Flush pending run records to their worca-metrics branch.
+                                          Without --project, every outbox on this machine is flushed.
+  worca metrics help
+
+Exit codes: 0 all pushed (or nothing pending) · 1 at least one outbox could not be pushed.
+`;
+
+async function cmdMetrics(argv) {
+  const verb = argv[0];
+  const rest = argv.slice(1);
+  if (!verb || verb === 'help') { process.stdout.write(METRICS_HELP); return 0; }
+  const sync = await import('../core/metrics/sync.mjs');
+  try {
+    switch (verb) {
+      case 'push': {
+        const a = pluginArgs(rest, ['--project'], []);
+        if (a._.length) fail(`unexpected argument "${a._[0]}" — see: worca metrics help`);
+        // CLI-only machines have no hourly loop: refresh stale discovery caches (TTL-respecting) so a
+        // branch a teammate enabled is seen here too. Best-effort; offline keeps the cached verdicts.
+        await sync.discoverAll().catch(() => {});
+        const results = a.project ? [await sync.flushProject(resolve(a.project))] : await sync.flushAll();
+        if (!results.length) { out('worca metrics push: nothing pending'); return 0; }
+        let failed = 0;
+        for (const r of results) {
+          if (r.ok) {
+            out(`${c('green', '✓')} ${r.slug}: ${r.pushed ? `pushed ${r.pushed} run(s)` : 'nothing pending'}`);
+          } else {
+            failed += 1;
+            out(`${c('red', '✗')} ${r.slug ?? '(project)'}: ${r.code}${r.pending ? ` — ${r.pending} run(s) still pending` : ''}`);
+            if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);
+            if (r.hint) out(`  hint: ${r.hint}`);
+          }
+        }
+        return failed ? 1 : 0;
+      }
+      default:
+        fail(`unknown metrics verb "${verb}" — see: worca metrics help`);
+    }
+  } catch (err) {
+    process.stderr.write(`worca metrics ${verb}: ${err?.message || err}\n`);
+    return 1;
+  }
+}
+
+/** Await in-flight metrics pushes before the CLI exits (decision 24). Never blocks past its
+ *  own budget and never changes the run's exit code — metrics must not gate the CLI. */
+async function drainMetricsFlushes() {
+  try {
+    const { drainFlushes } = await import('../core/metrics/sync.mjs');
+    await drainFlushes({ timeoutMs: 30_000 });
+  } catch { /* metrics never block the CLI exit */ }
+}
+
 // ── main ──────────────────────────────────────────────────────────────────────────
 
-const SUBCOMMANDS = new Set(['add', 'list', 'remove', 'resume', 'doctor', 'plugin', 'marketplace', 'config', 'ui', 'workflow']);
+const SUBCOMMANDS = new Set(['add', 'list', 'remove', 'resume', 'doctor', 'plugin', 'marketplace', 'config', 'ui', 'workflow', 'metrics']);
 
 /** Levenshtein distance, two-row. Only ever called on short argv tokens. */
 function editDistance(a, b) {
@@ -2074,6 +2184,7 @@ async function main() {
     if (sub === 'config') return cmdConfig(rest);
     if (sub === 'ui') return cmdUi(rest);
     if (sub === 'workflow') return cmdWorkflow(rest);
+    if (sub === 'metrics') return cmdMetrics(rest);
   }
   // `worca --ui [...]` is the historical spelling of `worca ui start [...]`; hand the
   // remaining tokens to the ui parser so --port/--open/--mock work with either.
@@ -2105,6 +2216,10 @@ async function main() {
     fail('--permission-mode dontAsk cannot be combined with --mock: the mock runner reserves it for the Ask Worca assistant.');
   }
 
+  // A defragment run needs no task text: synthesise the same brief the UI wrapper sends.
+  if (flags.memoryScope && !flags.prompt && !flags.file && !flags._.length) {
+    flags.prompt = flags.memoryScope === 'global' ? 'Defragment global memory.' : 'Defragment the memory of this project.';
+  }
   if (!flags.prompt && !flags.file) {
     // Allow a bare positional prompt: `worca "do the thing"`. A lone token that
     // near-misses a subcommand is a typo, not a task — refuse it here, before a
@@ -2151,12 +2266,22 @@ async function main() {
   // Validate --workflow before spawning anything: an unknown or archived template
   // must fail with one line, not a stack trace half-way through a run. The read row
   // doubles as createOrchestratorFor's routing hint (it skips a second row read).
+  // `--workflow auto` is the Auto entry (spec D15); `--no-human` means nothing elsewhere.
+  if (flags.workflow === 'auto') flags.workflow = 'wf_auto';
+  if (flags.humanInLoop === false && flags.workflow !== 'wf_auto') {
+    out(c('yellow', '--no-human only affects the Auto workflow (--workflow auto); ignored for this run.'));
+  }
   let row;
   if (flags.workflow) {
     const { assertRunnableWorkflow } = await import('../core/workflows.mjs');
     try { row = await assertRunnableWorkflow(flags.workflow); }
     catch (err) { fail(`${err && err.message ? err.message : String(err)}`); }
   }
+  {
+    const { validateMemoryScope } = await import('../core/memory-sync.mjs');
+    const reason = validateMemoryScope({ workflowId: flags.workflow || 'wf_default', memoryScope: flags.memoryScope, isWorkspace: false });
+    if (reason) fail(reason);
+  }
 
   const orch = await createOrchestratorFor({
     projectDir,
@@ -2166,6 +2291,7 @@ async function main() {
     extras,
     workflowId: flags.workflow || undefined,
     template: row,
+    memoryScope: flags.memoryScope || undefined,
     branch: { source: flags.sourceBranch, feature: flags.featureBranch },
     claude: {
       permissionMode: flags.permissionMode,
@@ -2173,12 +2299,15 @@ async function main() {
       mock: flags.mock,
     },
     auto: flags.auto,
+    humanInLoop: flags.humanInLoop === false ? false : undefined,
   });
 
   out(c('bold', `orchestrator — project: ${projectDir}`));
   if (flags.mock) out(c('yellow', 'mock mode: no claude will be spawned'));
 
-  return attachAndDrive(orch, flags, () => orch.run());
+  const code = await attachAndDrive(orch, flags, () => orch.run());
+  await drainMetricsFlushes();
+  return code;
 }
 
 main()

package/src/core/agent-registry.mjs

@@ -17,6 +17,7 @@ import { readPluginsLock, pluginCurrentDir } from './plugins-lock.mjs'; // plugi
 import { declaredApi, NOT_META_V2 } from './plugin-manifest.mjs'; // plugin API declared by a layer's manifest
 import { normalizeAgentMeta, DEFAULT_ORDER } from '../shared/graph/agent-meta.mjs'; // meta v2 (one source: registry + store + UI)
 import { MOCK_WRITER_ROLES } from './claude-runner.mjs';             // mockRole vocabulary (no cycle: claude-runner imports no registry)
+import { readFrontmatterSync } from './frontmatter.mjs';
 
 /**
  * Default location of the agent metadata sidecars, relative to this module.
@@ -213,32 +214,6 @@ export function pluginAgentLayers() {
   }
 }
 
-/**
- * Fallback palette blurb: the agent .md's YAML frontmatter `description:` line,
- * stored VERBATIM (clarify 2026-08-09: the UI clamps, the bubble wants the full
- * text — never truncate here). Single-line values only (plain or quoted);
- * folded/multi-line scalars are out of scope by design (spec 2026-08-09; every
- * shipped .md uses a single-line scalar) and degrade to '' — the block-scalar
- * indicator is detected, never stored. Any read/parse failure returns '' so
- * scanLayer never throws because of the fallback.
- */
-function frontmatterDescription(mdPath) {
-  let text;
-  try { text = readFileSync(mdPath, 'utf8'); } catch { return ''; }
-  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!fm) return '';
-  const line = fm[1].match(/^description:[ \t]*(.+)$/m);
-  if (!line) return '';
-  let v = line[1].trim();
-  // Folded/literal block scalars ('>', '>-', '|', '|+', …): the captured value
-  // is just the indicator, not the text — degrade to '' rather than store junk.
-  if (/^[>|][+-]?$/.test(v)) return '';
-  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
-    v = v.slice(1, -1).trim();
-  }
-  return v;
-}
-
 /** Scan one layer dir for *.meta.json; stamps the COMPUTED origin/agentPath/
  *  descriptionDerived fields (none of which normalizeMeta returns, so none can
  *  be persisted back into a sidecar). */
@@ -294,15 +269,18 @@ function scanLayer(dir, origin, { requireMetaV2 = false, builtFor = null, onDrop
       continue;
     }
     meta.agentPath = meta.agentFile ? join(dir, meta.agentFile) : null; // layer-correct abs path
+    // The agent .md's frontmatter (name/description/tools/model), read from the
+    // file HEAD only (frontmatter.mjs) — COMPUTED like origin/agentPath, never
+    // stored (normalizeMeta's fixed key set drops it on every write path). The
+    // Auto classifier reads it (auto-workflow P1); the chat catalog can too.
+    meta.frontmatter = meta.agentPath ? readFrontmatterSync(meta.agentPath) : null;
     // Description fallback (spec 2026-08-09): empty sidecar description →
-    // the .md frontmatter description. Only costs a file read when empty.
-    // descriptionDerived marks the RESOLVED description as computed too: unlike
-    // origin/agentPath, `description` has a slot in normalizeMeta, so without
-    // this flag every write path would bake the fallback into the sidecar and
-    // the blurb would stop tracking the .md (and could never be cleared).
-    if (!meta.description && meta.agentPath) {
-      meta.description = frontmatterDescription(meta.agentPath);
-      if (meta.description) meta.descriptionDerived = true;             // computed, never stored
+    // the .md frontmatter description. descriptionDerived marks the RESOLVED
+    // description as computed too, so no write path bakes the fallback into
+    // the sidecar and the blurb keeps tracking the .md.
+    if (!meta.description && meta.frontmatter?.description) {
+      meta.description = meta.frontmatter.description;
+      meta.descriptionDerived = true;                                    // computed, never stored
     }
     metas.push(meta);
   }