@rudderhq/server 0.7.2 → 0.7.4

package/skills/app-builder/assets/scaffold/next.config.ts

@@ -1,8 +1,27 @@
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
+  devIndicators: false,
   output: "standalone",
   poweredByHeader: false,
+  turbopack: {
+    root: process.cwd(),
+  },
+  webpack(config, { isServer }) {
+    if (isServer) {
+      config.externals.push((
+        { request }: { request?: string },
+        callback: (error?: Error | null, result?: string) => void,
+      ) => {
+        if (request?.startsWith("node:")) {
+          callback(null, `commonjs ${request}`);
+          return;
+        }
+        callback();
+      });
+    }
+    return config;
+  },
 };
 
 export default nextConfig;

package/skills/app-builder/assets/scaffold/package.json

@@ -17,7 +17,8 @@
     "db:migrate": "tsx scripts/migrate.ts",
     "db:seed": "tsx scripts/seed.ts",
     "data:snapshot": "tsx scripts/snapshot.ts",
-    "verify": "tsc --noEmit && vitest run && next build",
+    "ui:check": "node scripts/validate-rudder-ui.mjs",
+    "verify": "pnpm ui:check && tsc --noEmit && vitest run && next build",
     "predev": "tsx scripts/migrate.ts && tsx scripts/seed.ts"
   },
   "dependencies": {

package/skills/app-builder/assets/scaffold/rudder.app.json

@@ -13,7 +13,7 @@
     "packageManager": "managed-pnpm",
     "openPath": "/",
     "readinessPath": "/api/__rudder/health",
-    "readinessTimeoutMs": 300000
+    "readinessTimeoutMs": 600000
   },
   "data": {
     "provider": "sqlite",

package/skills/app-builder/assets/scaffold/rudder.ui.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "preset": "rudder",
+  "revision": 1,
+  "sourceOwnership": "app",
+  "appearance": {
+    "designStyle": "luma",
+    "baseColor": "neutral",
+    "accentTheme": "emerald",
+    "colorMode": "system"
+  },
+  "density": "compact"
+}

package/skills/app-builder/assets/scaffold/scripts/validate-rudder-ui.mjs

@@ -0,0 +1,50 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const requiredFiles = [
+  "components.json",
+  "app/globals.css",
+  "components/ui/button.tsx",
+  "components/ui/field.tsx",
+  "components/ui/table.tsx",
+  "components/ui/empty.tsx",
+];
+
+function fail(message) {
+  console.error(`Rudder UI preset invalid: ${message}`);
+  process.exit(1);
+}
+
+let preset;
+try {
+  preset = JSON.parse(await readFile(path.join(root, "rudder.ui.json"), "utf8"));
+} catch {
+  fail("rudder.ui.json is missing or invalid JSON");
+}
+
+if (preset?.schemaVersion !== 1 || preset?.preset !== "rudder") {
+  fail("unsupported preset identity");
+}
+if (!Number.isInteger(preset?.revision) || preset.revision < 1) {
+  fail("revision must be a positive integer");
+}
+if (preset?.sourceOwnership !== "app") {
+  fail("generated Apps must own their component source");
+}
+
+for (const relativePath of requiredFiles) {
+  try {
+    await access(path.join(root, relativePath));
+  } catch {
+    fail(`required file is missing: ${relativePath}`);
+  }
+}
+
+const css = await readFile(path.join(root, "app/globals.css"), "utf8");
+for (const token of ["--background", "--foreground", "--primary", "--destructive", "--border", "--ring", "--radius"]) {
+  if (!css.includes(`${token}:`)) fail(`semantic token is missing: ${token}`);
+}
+if (!css.includes("@theme inline")) fail("Tailwind semantic token mapping is missing");
+
+console.log(`Rudder UI preset ${preset.revision}: ok`);

package/skills/app-builder/assets/scaffold/tests/e2e/app.spec.ts

@@ -4,7 +4,7 @@ test("creates a contact and keeps it after reload", async ({ page }) => {
   const suffix = crypto.randomUUID();
   const name = `Avery ${suffix.slice(0, 8)}`;
   await page.goto("/");
-  await expect(page.getByRole("heading", { name: "Customer workspace" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Contacts", exact: true })).toBeVisible();
   await page.getByLabel("Name").fill(name);
   await page.getByLabel("Email").fill(`${suffix}@example.test`);
   await page.getByLabel("Company").fill("Acme");
@@ -14,6 +14,40 @@ test("creates a contact and keeps it after reload", async ({ page }) => {
   await expect(page.getByText(name)).toBeVisible();
 });
 
+test("ships the Rudder UI preset in system light and dark modes", async ({ browser }) => {
+  const lightPage = await browser.newPage({ colorScheme: "light" });
+  await lightPage.goto("/");
+  await expect(lightPage.getByText("Pipeline Desk")).toBeVisible();
+  const lightStyle = await lightPage.evaluate(() => {
+    const style = getComputedStyle(document.documentElement);
+    return {
+      background: getComputedStyle(document.body).backgroundColor,
+      radius: style.getPropertyValue("--radius"),
+    };
+  });
+  expect(Number.parseFloat(lightStyle.radius)).toBe(0.375);
+
+  const darkPage = await browser.newPage({ colorScheme: "dark" });
+  await darkPage.goto("/");
+  const darkBackground = await darkPage.evaluate(() => (
+    getComputedStyle(document.body).backgroundColor
+  ));
+  expect(darkBackground).not.toBe(lightStyle.background);
+  await lightPage.close();
+  await darkPage.close();
+});
+
+test("keeps the primary workflow usable at 390px", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto("/");
+  await expect(page.getByRole("heading", { name: "Contacts", exact: true })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Add contact" })).toBeVisible();
+  await expect(page.getByLabel("Search contacts")).toBeVisible();
+  await expect(page.getByRole("button", { name: "Delete Maya Chen" })).toBeVisible();
+  await expect(page.getByText("Northwind").first()).toBeVisible();
+  await expect(page.locator("nextjs-portal")).toBeHidden();
+});
+
 test("shows the empty-search state", async ({ page }) => {
   await page.goto("/");
   await page.getByLabel("Search contacts").fill("no matching record");

package/skills/app-builder/evals/evals.json

@@ -9,6 +9,7 @@
       "assertions": [
         "Does not ask the user to choose a framework, database, package manager, or process topology.",
         "Uses the maintained App Builder scaffold and SQLite persistence.",
+        "Uses the versioned Rudder UI preset and its semantic shadcn primitives instead of inventing a generic dashboard theme.",
         "Does not ask for or place email credential values in Chat or source.",
         "Includes the primary contact workflow plus import, persistence, and a production-shaped edge case in verification."
       ]
@@ -32,7 +33,7 @@
       "files": [],
       "assertions": [
         "Does not inspect or mutate real customer records merely to design the table.",
-        "Uses the existing scaffold components and avoids decorative dashboard clutter.",
+        "Uses the existing Rudder UI preset components and semantic tokens, preserves readable density, and avoids decorative dashboard clutter.",
         "Verifies the table at desktop width and a 390px viewport.",
         "Captures rendered screenshot evidence and checks an empty or error state."
       ]

package/skills/app-builder/references/design-guidelines.md

@@ -2,6 +2,11 @@
 
 Design for the user's actual workflow rather than for a technology demo.
 
+For new maintained Apps, begin with the scaffold's versioned Rudder UI preset.
+Do not replace its semantic tokens with a generic shadcn preset, a one-off
+palette, or copied host application CSS. The generated App owns its component
+source and must remain independently runnable outside Rudder.
+
 - Put the primary action and current work state above decorative summaries.
 - Use tables for operational lists, with search, meaningful filters, sorting,
   pagination when needed, empty states, and clear row actions.
@@ -11,10 +16,22 @@ Design for the user's actual workflow rather than for a technology demo.
   navigation, not both.
 - Prefer readable density for CRM and marketing data. Avoid oversized KPI cards,
   excessive gradients, glass panels, and placeholder charts.
-- Use the scaffold's component primitives and theme tokens before adding new
-  one-off styling.
+- Use the scaffold's shadcn primitives and semantic theme tokens before adding
+  new components or one-off styling. Compose `Button`, `Input`, `Field`,
+  `Table`, `Badge`, `Alert`, `Empty`, `Skeleton`, and `Separator` instead of
+  recreating those patterns with styled `div` elements.
+- Keep Rudder's default visual character: calm, dense, operational, quiet, and
+  precise. Use compact radii, low-contrast borders, restrained elevation, one
+  clear primary action, and color for state or emphasis rather than decoration.
+- Use semantic utilities such as `bg-background`, `text-foreground`,
+  `bg-muted`, and `text-destructive`. Do not hardcode product colors in
+  workflow components or add component-local dark-mode colors.
+- Treat the preset as a starting system, not a brand lock. When the brief calls
+  for a distinct brand, keep the component structure, density, accessibility,
+  and state behavior while changing the named token layer deliberately.
 - Support keyboard use, visible focus, semantic headings, accessible names, and
   error text that does not rely on color.
 - Verify at desktop width and at 390px mobile width unless the brief excludes
   mobile.
 - Show loading, empty, error, populated, and destructive-operation states.
+- Run `pnpm ui:check` before final verification for new maintained Apps.

package/skills/app-builder/references/rudder-ui-preset.md

@@ -0,0 +1,73 @@
+# Rudder UI Preset
+
+The maintained scaffold includes a versioned, source-owned shadcn preset for
+building local operator tools that feel immediately at home in Rudder.
+
+## Source Of Truth
+
+- `rudder.ui.json` identifies the preset and revision.
+- `components.json` makes the generated project a conventional shadcn project.
+- `app/globals.css` owns semantic color, radius, typography, and light/dark
+  tokens.
+- `components/ui/` owns copied component source. Generated Apps do not import
+  components or CSS from the Rudder repository at runtime.
+- `scripts/validate-rudder-ui.mjs` checks that the preset contract remains
+  present before handoff.
+
+For new Apps, use this preset without asking the user to select a shadcn style,
+base palette, accent, radius, or component library. The default is Rudder's
+spacious-but-compact `luma` character, neutral surfaces, emerald action color,
+and system light/dark mode.
+
+## Composition Rules
+
+1. Start with the shipped primitives. Extend them with variants when the same
+   need recurs; do not restyle each call site.
+2. Use semantic Tailwind utilities rather than raw color utilities. New named
+   product colors belong in the token layer.
+3. Keep normal controls between 32 and 36 pixels high, use compact radii, and
+   reserve pills for true circular or exceptional status affordances.
+4. Bind native `button`, `input`, `select`, and `textarea` text to the inherited
+   semantic foreground color so system dark mode cannot reintroduce browser-UA
+   contrast regressions.
+5. Use one primary panel or table region. Cards group independent objects or
+   actions; they are not wrappers for every section.
+6. Operational lists require search or filtering when useful, readable row
+   actions, empty/loading/error states, and horizontal containment on narrow
+   screens.
+7. Use Lucide icons for familiar actions. Icon-only controls need accessible
+   labels; icons inside buttons inherit their size from `Button`.
+8. Preserve keyboard focus, semantic headings, persistent labels, inline
+   validation, and destructive confirmation.
+
+## Appearance Boundary
+
+The preset is copied into the App as a stable creation-time baseline. It does
+not read Rudder's browser-local Appearance preferences or import host CSS at
+runtime. This keeps the App portable and prevents a later Rudder theme change
+from silently changing an independently branded product.
+
+An App may add a documented host-theme bridge later, but light/dark following
+must be optional and the standalone URL must still render correctly. Changing
+that boundary is product behavior, not an incidental styling edit.
+
+## Existing Projects
+
+Do not install or overwrite the preset in an existing project by default.
+Inspect its framework, component library, tokens, and brand first. If the user
+explicitly asks to align it with Rudder, preserve application behavior and
+choose a bounded migration:
+
+- token-only alignment when components are already coherent;
+- primitive-by-primitive alignment when a source-owned component system exists;
+- full preset adoption only when the user accepts the wider visual change.
+
+Never run a shadcn overwrite command over locally modified components without
+explicit approval and a reviewed diff.
+
+## Verification
+
+Run `pnpm ui:check`, typecheck, tests, build, and the App's Playwright suite.
+In Browser, inspect the primary workflow, loading or empty state, inline error,
+destructive action, desktop layout, 390px layout, and light/dark contrast.
+Capture the useful populated state rather than a decorative empty dashboard.

package/skills/app-builder/references/scaffold-contract.md

@@ -25,6 +25,8 @@ definition through **Apps + > Add local web project** before anything runs.
 
 - Next.js App Router, React, and TypeScript
 - Tailwind CSS with shadcn-style component source owned by the project
+- a versioned Rudder UI preset with semantic light/dark tokens and compact
+  operator-tool primitives
 - SQLite with Drizzle ORM
 - Zod at API, import, and form boundaries
 - Vitest for unit tests and Playwright for browser tests
@@ -36,6 +38,8 @@ implementation detail and must not become a user decision.
 ## Required Files And Behaviors
 
 - `rudder.app.json` uses schema version 1 and a maintained template revision.
+- `rudder.ui.json` identifies the source-owned Rudder UI preset revision;
+  `components.json` keeps the project compatible with the normal shadcn CLI.
 - `/api/__rudder/health` returns readiness only after the app can open its
   selected database.
 - `RUDDER_APP_DATA_MODE=development|production` selects the database without
@@ -64,6 +68,12 @@ manifest.
 ## Commands
 
 - `pnpm dev`: migrate the development database, then run loopback development.
+- On Windows, Rudder's managed preview may select Next.js webpack while keeping
+  `node:*` built-ins external to the server bundle. This preserves the short
+  managed dependency layout required by native package executables without
+  changing the App's website output. The managed runtime supplies the same
+  compatibility to existing revision-1 Apps without rewriting their
+  `next.config.ts`, `next-env.d.ts`, or other App-owned source files.
 - `pnpm typecheck`: TypeScript validation.
 - `pnpm test`: unit and API-contract tests.
 - `pnpm build`: production build.
@@ -73,5 +83,7 @@ manifest.
 - `pnpm data:snapshot`: copy the selected SQLite database to `data/snapshots/`
   using SQLite's backup API.
 - `pnpm verify`: typecheck, tests, and build.
+- `pnpm ui:check`: validate the maintained Rudder UI preset files and semantic
+  token contract.
 
 Formal app start must not silently migrate real data. Promotion owns that step.

package/skills/app-builder/references/verification.md

@@ -18,6 +18,12 @@ substitute a shell HTTP response for UI acceptance.
 8. Capture current screenshots of the useful final state.
 9. Materialize screenshots in Chat, Run, or Library evidence.
 
+Only after all required checks pass may the Agent report
+`verified_source_ready` for the originating App. That report is not a prose
+claim: it is a run-scoped handoff that causes Desktop to repeat its maintained
+checks, start the attested loopback process, and open the App for the user.
+Questions, partial results, and blockers must never emit the handoff.
+
 Close temporary run-owned tabs after verification. Never use the user's
 persistent app view as an Agent test fixture when that could mutate formal
 data.

package/skills/app-builder/scripts/report-build-status.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+const STATUS = process.argv[2];
+const APP_ID = process.argv[3];
+const ALLOWED_STATUSES = new Set(["building", "verified_source_ready", "failed"]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+if (!ALLOWED_STATUSES.has(STATUS) || !UUID_PATTERN.test(APP_ID ?? "")) {
+  console.error("Usage: report-build-status.mjs <building|verified_source_ready|failed> <app-id>");
+  process.exit(2);
+}
+
+const apiUrl = process.env.RUDDER_API_URL?.trim();
+const apiKey = process.env.RUDDER_API_KEY?.trim();
+const orgId = process.env.RUDDER_ORG_ID?.trim();
+const runId = process.env.RUDDER_RUN_ID?.trim();
+if (!apiUrl || !apiKey || !orgId || !runId) {
+  console.error("Rudder run context is unavailable; do not report a completed App handoff.");
+  process.exit(2);
+}
+
+const base = apiUrl.replace(/\/+$/u, "");
+const apiBase = new URL(base).pathname.replace(/\/+$/u, "").endsWith("/api")
+  ? base
+  : `${base}/api`;
+const endpoint = `${apiBase}/app-builder/${encodeURIComponent(APP_ID)}/build?orgId=${encodeURIComponent(orgId)}`;
+const headers = {
+  authorization: `Bearer ${apiKey}`,
+  "content-type": "application/json",
+};
+const currentResponse = await fetch(
+  `${apiBase}/orgs/${encodeURIComponent(orgId)}/app-builder`,
+  { headers },
+);
+if (!currentResponse.ok) {
+  console.error(`Rudder could not read the App handoff state (${currentResponse.status}).`);
+  process.exit(1);
+}
+const current = (await currentResponse.json()).find((app) => app.id === APP_ID);
+if (!current) {
+  console.error("Rudder App handoff identity was not found in this organization.");
+  process.exit(1);
+}
+const duplicateRunId = STATUS === "verified_source_ready"
+  ? current.latestVerificationRunId
+  : current.latestBuildRunId;
+if (current.buildStatus === STATUS && duplicateRunId === runId) {
+  console.log(`App Builder status: ${current.buildStatus}`);
+  process.exit(0);
+}
+const allowedCurrentStatuses = STATUS === "building"
+  ? new Set(["preparing", "ready", "launch_failed", "failed"])
+  : STATUS === "verified_source_ready"
+    ? new Set(["building"])
+    : new Set(["preparing", "building"]);
+if (!allowedCurrentStatuses.has(current.buildStatus)) {
+  console.error(
+    `Rudder rejected the stale App handoff transition ${current.buildStatus} -> ${STATUS}.`,
+  );
+  process.exit(1);
+}
+const response = await fetch(
+  endpoint,
+  {
+    method: "PATCH",
+    headers,
+    body: JSON.stringify({
+      status: STATUS,
+      expectedStatus: current.buildStatus,
+      runId,
+      runKind: STATUS === "verified_source_ready" ? "verification" : "build",
+    }),
+  },
+);
+
+if (!response.ok) {
+  const detail = await response.text();
+  console.error(`Rudder rejected the App handoff (${response.status}): ${detail.slice(0, 500)}`);
+  process.exit(1);
+}
+
+const app = await response.json();
+console.log(`App Builder status: ${app.buildStatus}`);

package/skills/rudder-docs/SKILL.md

@@ -134,8 +134,8 @@ Read only the reference needed for the request:
    installed CLI fallback catalog plus exact command semantics.
 3. [Agent creation](references/agent-creation.md) — permission-aware Agent
    configuration, governed hiring, approval, revision, and evidence workflow.
-4. [Plugin authoring](references/plugin-authoring.md) — current scaffold,
-   manifest, worker, UI, capability, route, and verification workflow.
+4. [Plugin authoring](references/plugin-authoring.md) — Codex-compatible
+   package layout, manifest, Skills, MCPs, Apps, and verification workflow.
 5. [Work practices](references/operating-practices.md) — exact
    conditional behavior for ownership, reviews, approvals, budgets,
    workspaces, Library handoff, authentication, and safe git use.

package/skills/rudder-docs/evals/retrieval-authority-evals.json

@@ -258,5 +258,45 @@
     "expected_public_path": "https://docs.rudderhq.dev/zh/reference/permissions-and-platforms",
     "expected_anchor": "boundaries",
     "illustrative_case_sufficient": false
+  },
+  {
+    "query": "How does Rudder build, review, approve, and sign Windows Desktop releases?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": [],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/code-signing-policy",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Rudder 如何构建、审查、批准并签名 Windows Desktop 发布产物？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": [],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/code-signing-policy",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Which Rudder data stays local and which optional services process data?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ANALYTICS.TELEMETRY.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/privacy",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "哪些 Rudder 数据保留在本地，哪些可选服务会处理数据？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ANALYTICS.TELEMETRY.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/privacy",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
   }
 ]

package/skills/rudder-docs/evals/trigger-evals.json

@@ -20,11 +20,11 @@
     "should_trigger": true
   },
   {
-    "query": "Scaffold a new Rudder Plugin named @acme/quality-gate in a temporary external package directory. Verify the current create-rudder-plugin and SDK workflow first, then run its typecheck, tests, and build.",
+    "query": "Create a Codex-compatible Rudder Plugin named quality-gate in a temporary directory with one Skill. Verify plugin.json and the current import boundary, then test the package.",
     "should_trigger": true
   },
   {
-    "query": "Rudder Plugin 的 worker capability、same-origin UI、routePath 和 ctx.assets 现在到底有哪些边界？请查当前 authoring guide、SDK 和源码后回答。",
+    "query": "Rudder Plugin 的 Codex package、Skills、MCP、App、导入检查和运行权限现在有哪些边界？请查当前 authoring guide 和源码后回答。",
     "should_trigger": true
   },
   {

package/skills/rudder-docs/references/api-reference.md

@@ -246,8 +246,6 @@ or editing that URL by hand.
 
 - `GET /api/approvals/:approvalId`
 - `GET /api/approvals/:approvalId/issues`
-- `GET /api/approvals/:approvalId/comments`
-- `POST /api/approvals/:approvalId/comments`
 - `POST /api/approvals/:approvalId/request-revision`
 - `POST /api/approvals/:approvalId/resubmit`
 - `POST /api/approvals/:approvalId/approve`

package/skills/rudder-docs/references/cli-reference.md

@@ -52,6 +52,11 @@ operating-practices guide for operating behavior:
 | `rudder_agent_skills_create` | `rudder agent skills create [agent-id] --name <name> [--enable]` | Create an agent-private skill package under AGENT_HOME/skills. | yes | no | no | attached when available |
 | `rudder_agent_skills_enable` | `rudder agent skills enable <agent-id> <selection-ref...>` | Add skill selections to an agent without replacing existing enabled skills. | yes | no | no | attached when available |
 | `rudder_agent_skills_sync` | `rudder agent skills sync <agent-id>` | Sync the desired enabled skill set for an agent. | yes | no | no | attached when available |
+| `rudder_goal_list` | `rudder goal list [--lifecycle <draft|active|closed|all>] [--focus <true|false>] [--facet <facet>] [--limit <n>]` | Discover Goals owned by the authenticated Agent; defaults to active Goals and returns current progress, next step, and attention state. | no | required | required | no |
+| `rudder_goal_context` | `rudder goal context <goal-id>` | Read the owned Goal agreement and current operating context before acting: contract revision, criteria, boundaries, progress, next step, attention, proposals, and recent feedback. | no | no | required | no |
+| `rudder_goal_progress` | `rudder goal progress <goal-id> --summary <text> --evidence-refs <json> --idempotency-key <key>` | Record evidence-backed progress for a Goal owned by the authenticated Agent and attribute it to the current Run. | yes | no | required | required |
+| `rudder_goal_change_propose` | `rudder goal change propose <goal-id> --contract-revision <n> --after-contract <json> --rationale <text> --idempotency-key <key>` | Propose a reviewable change to the current Goal contract when evidence shows its outcome, criteria, boundaries, or deadlines should change. | yes | no | required | required |
+| `rudder_goal_result_propose` | `rudder goal result propose <goal-id> --contract-revision <n> --criteria <json> --evidence-refs <json> --risk-summary <text> --idempotency-key <key>` | Submit an evidence-backed Goal result for mandatory human acceptance without closing the Goal. | yes | no | required | required |
 | `rudder_issue_get` | `rudder issue get <issue>` | Read a full issue by UUID or identifier. | no | no | no | no |
 | `rudder_issue_list` | `rudder issue list --org-id <id>` | List issues with optional status, assignee, and project filters without requiring a search query. | no | required | no | no |
 | `rudder_issue_search` | `rudder issue search <query> [--org-id <id>]` | Search issues with the server-side issue index across title, identifier, description, and comments. | no | required | no | no |
@@ -64,7 +69,7 @@ operating-practices guide for operating behavior:
 | `rudder_issue_review` | `rudder issue review <issue> --decision <decision> --comment-file <path>` | Record a structured reviewer decision with a required comment. | yes | no | no | attached when available |
 | `rudder_issue_commit` | `rudder issue commit <issue> --sha <sha> --message <subject>` | Report a code commit created during issue work as structured issue activity. | yes | no | no | attached when available |
 | `rudder_issue_done` | `rudder issue done <issue> --comment-file <path> [--image <path>]` | Mark an issue done with a required completion comment, optionally uploading images. | yes | no | no | attached when available |
-| `rudder_issue_block` | `rudder issue block <issue> --comment-file <path> [--image <path>]` | Mark an issue blocked with a required blocker comment, optionally uploading images. | yes | no | no | attached when available |
+| `rudder_issue_block` | `rudder issue block <issue> --comment-file <path> [--image <path>]` | Request human assistance after bounded recovery attempts; repeated matching claims are audited before the Issue becomes blocked. | yes | no | no | attached when available |
 | `rudder_project_list` | `rudder project list --org-id <id>` | List projects in an organization. | no | required | no | no |
 | `rudder_project_get` | `rudder project get <project-id-or-shortname> [--org-id <id>]` | Read one project by ID or shortname. | no | no | no | no |
 | `rudder_project_create` | `rudder project create --org-id <id> --name <name>` | Create a project in the organization. | yes | required | no | attached when available |
@@ -147,7 +152,7 @@ Operating rules live in [ownership, checkout, and wake scope](operating-practice
 
 - progress: `rudder issue comment <issue> --body-file <path> [--image <path>]`
 - done: `rudder issue done <issue> --comment-file <path> [--image <path>]`
-- blocked: `rudder issue block <issue> --comment-file <path> [--image <path>]`
+- assistance/block audit: `rudder issue block <issue> --comment-file <path> [--image <path>]`
 
 Issue comment and close-out commands accept comment bodies only from files or stdin. For multiline Markdown, command names, code spans, code blocks, test summaries, or screenshot evidence, pass `--body-file <path>` or `--comment-file <path>`, or pass `-` to read the body from stdin.
 

package/skills/rudder-docs/references/operating-practices.md

@@ -83,12 +83,16 @@ because work is executable, durable, long-running, or reviewable.
 ## Review And Close-Out
 
 Use the close-out signal matching the outcome: a progress comment when work
-remains, done with completion evidence, blocked with a blocker comment, or an
-explicit handoff comment with an ownership change.
-
-If blocked, set the issue to `blocked`, identify the blocker, name the next
-actor or action, and leave the blocker comment before exit. Do not present
-partial work as complete.
+remains, done with completion evidence, a blocker claim after bounded recovery,
+or an explicit handoff comment with an ownership change.
+
+Complete the real task. If an action fails, investigate and try a bounded,
+materially different recovery path before requesting human help. A blocker
+claim must identify the blocker and exact human input or action required.
+Rudder records the Assistance Request and audits the same blocker across
+separate execution Runs; the first claim does not directly establish a blocked
+Issue. Do not repeat a failed action inside one Run merely to increase the
+audit count, and do not present partial work as complete.
 
 A reviewer does not take over implementation unless explicitly asked. Ordinary
 explicit reviewer work may happen in any issue status while preserving