@desplega.ai/agent-swarm 1.103.0 → 1.104.0

package/src/tools/script-connections/tool.ts

@@ -0,0 +1,167 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById } from "@/be/db";
+import {
+  listScriptConnections,
+  setScriptConnectionEnabled,
+  upsertCredentialBinding,
+  upsertScriptConnection,
+} from "@/be/script-connections";
+import { placeholderForConfigKey } from "@/scripts-runtime/credential-broker";
+import { createToolRegistrar } from "@/tools/utils";
+
+const scriptConnectionsInputSchema = z.object({
+  action: z
+    .enum(["list", "upsert-openapi", "disable"])
+    .describe("List, create/update, or disable a script connection."),
+  id: z.string().uuid().optional(),
+  slug: z.string().min(1).max(80).optional(),
+  displayName: z.string().max(160).optional(),
+  scope: z.enum(["global", "agent", "repo"]).default("global").optional(),
+  scopeId: z.string().uuid().nullable().optional(),
+  baseUrl: z.string().url().optional(),
+  allowedHosts: z.array(z.string().min(1)).optional(),
+  credentialBindingId: z.string().uuid().nullable().optional(),
+  configKey: z.string().min(1).max(255).optional(),
+  headerTemplate: z.string().min(1).optional(),
+  queryTemplate: z.string().min(1).optional(),
+  openapiSpecJson: z.string().optional(),
+  enabled: z.boolean().default(true).optional(),
+});
+
+const scriptConnectionsOutputSchema = z.object({
+  yourAgentId: z.string().uuid().optional(),
+  success: z.boolean(),
+  message: z.string(),
+  connections: z.array(z.unknown()),
+});
+
+export const registerScriptConnectionsTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "script-connections",
+    {
+      title: "Script Connections",
+      description:
+        "Lead-only registry management for scripts ctx.api/ctx.mcp connections. Phase 1 supports OpenAPI ctx.api connections with generated args and response types.",
+      annotations: { idempotentHint: true },
+      inputSchema: scriptConnectionsInputSchema,
+      outputSchema: scriptConnectionsOutputSchema,
+    },
+    async (args, requestInfo) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: 'Agent ID not found. Set the "X-Agent-ID" header.' }],
+          structuredContent: {
+            success: false,
+            message: 'Agent ID not found. Set the "X-Agent-ID" header.',
+            connections: [],
+          },
+        };
+      }
+
+      const agent = getAgentById(requestInfo.agentId);
+      if (!agent?.isLead) {
+        return {
+          content: [{ type: "text", text: "Only the lead can manage script connections." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Only the lead can manage script connections.",
+            connections: [],
+          },
+        };
+      }
+
+      if (args.action === "list") {
+        const connections = listScriptConnections({ includeDisabled: true });
+        return {
+          content: [{ type: "text", text: `Found ${connections.length} script connection(s).` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Found ${connections.length} script connection(s).`,
+            connections,
+          },
+        };
+      }
+
+      if (args.action === "disable") {
+        if (!args.id) {
+          return {
+            content: [{ type: "text", text: "id is required for disable." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "id is required for disable.",
+              connections: listScriptConnections({ includeDisabled: true }),
+            },
+          };
+        }
+        setScriptConnectionEnabled(args.id, false);
+        const connections = listScriptConnections({ includeDisabled: true });
+        return {
+          content: [{ type: "text", text: "Script connection disabled." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: "Script connection disabled.",
+            connections,
+          },
+        };
+      }
+
+      if (!args.slug || !args.baseUrl || !args.openapiSpecJson) {
+        return {
+          content: [{ type: "text", text: "slug, baseUrl, and openapiSpecJson are required." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "slug, baseUrl, and openapiSpecJson are required.",
+            connections: listScriptConnections({ includeDisabled: true }),
+          },
+        };
+      }
+
+      let credentialBindingId = args.credentialBindingId ?? null;
+      if (!credentialBindingId && args.configKey) {
+        const placeholder = placeholderForConfigKey(args.configKey);
+        const binding = upsertCredentialBinding({
+          configKey: args.configKey,
+          allowedHosts: args.allowedHosts ?? [new URL(args.baseUrl).hostname],
+          headerTemplate: args.headerTemplate ?? `Authorization: Bearer ${placeholder}`,
+          queryTemplate: args.queryTemplate,
+          scope: args.scope ?? "global",
+          scopeId: args.scope === "global" ? null : (args.scopeId ?? null),
+        });
+        credentialBindingId = binding.id;
+      }
+
+      const connection = upsertScriptConnection({
+        id: args.id,
+        slug: args.slug,
+        displayName: args.displayName,
+        kind: "openapi",
+        scope: args.scope ?? "global",
+        scopeId: args.scope === "global" ? null : (args.scopeId ?? null),
+        baseUrl: args.baseUrl,
+        allowedHosts: args.allowedHosts ?? [new URL(args.baseUrl).hostname],
+        credentialBindingId,
+        openapiSpecJson: args.openapiSpecJson,
+        enabled: args.enabled !== false,
+      });
+
+      const connections = listScriptConnections({ includeDisabled: true });
+      return {
+        content: [{ type: "text", text: `Script connection ${connection.slug} saved.` }],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: !connection.generationError,
+          message: connection.generationError
+            ? `Saved but generation failed: ${connection.generationError}`
+            : `Script connection ${connection.slug} saved.`,
+          connections,
+        },
+      };
+    },
+  );
+};

package/src/tools/swarm-config/delete-config.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { deleteSwarmConfig, getSwarmConfigLookupById } from "@/be/db";
+import { scheduleIntegrationsReload } from "@/http/core";
 import { createToolRegistrar } from "@/tools/utils";
 
 export const registerDeleteConfigTool = (server: McpServer) => {
@@ -58,6 +59,10 @@ export const registerDeleteConfigTool = (server: McpServer) => {
           };
         }
 
+        if (existing.scope === "global") {
+          scheduleIntegrationsReload();
+        }
+
         return {
           content: [
             {

package/src/tools/swarm-config/set-config.ts

@@ -1,11 +1,13 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
-import { maskSecrets, upsertSwarmConfig } from "@/be/db";
+import { getAgentById, maskSecrets, upsertSwarmConfig } from "@/be/db";
 import {
   isReservedConfigKey,
   reservedKeyError,
   validateConfigValue,
 } from "@/be/swarm-config-guard";
+import { scheduleIntegrationsReload } from "@/http/core";
+import { CREDENTIAL_BINDINGS_CONFIG_KEY } from "@/scripts-runtime/credential-broker";
 import { createToolRegistrar } from "@/tools/utils";
 import { SwarmConfigSchema, SwarmConfigScopeSchema } from "@/types";
 
@@ -93,6 +95,22 @@ export const registerSetConfigTool = (server: McpServer) => {
           };
         }
 
+        if (key.toUpperCase() === CREDENTIAL_BINDINGS_CONFIG_KEY) {
+          const agent = getAgentById(requestInfo.agentId);
+          if (!agent?.isLead) {
+            const message =
+              "Only the lead can manage SCRIPT_CREDENTIAL_BINDINGS. Use the credential-bindings tool.";
+            return {
+              content: [{ type: "text", text: message }],
+              structuredContent: {
+                yourAgentId: requestInfo.agentId,
+                success: false,
+                message,
+              },
+            };
+          }
+        }
+
         const validationError = validateConfigValue(key, value);
         if (validationError) {
           return {
@@ -115,6 +133,10 @@ export const registerSetConfigTool = (server: McpServer) => {
           description,
         });
 
+        if (scope === "global") {
+          scheduleIntegrationsReload();
+        }
+
         const [masked] = maskSecrets([config]);
 
         return {

package/src/tools/tool-config.ts

@@ -66,11 +66,16 @@ export const DEFERRED_TOOLS = new Set([
   "list-services",
   "update-service-status",
 
-  // Config (4)
+  // Config (5)
   "set-config",
   "get-config",
   "list-config",
   "delete-config",
+  "credential-bindings",
+  "script-connections",
+
+  // Memory (1)
+  "memory-edit",
 
   // Repos (2)
   "get-repos",

package/src/types.ts

@@ -1001,6 +1001,8 @@ export const EventNameSchema = z.enum([
   "system.error",
   // Script catalog events
   "script.global_upsert",
+  // Schedule events
+  "schedule.deleted",
 ]);
 
 export const SwarmEventSchema = z.object({
@@ -1146,6 +1148,7 @@ export const AgentMemorySchema = z.object({
   id: z.string().uuid(),
   agentId: z.string().uuid().nullable(),
   scope: AgentMemoryScopeSchema,
+  key: z.string().nullable().optional(),
   name: z.string().min(1).max(500),
   content: z.string(),
   summary: z.string().nullable(),
@@ -1156,10 +1159,13 @@ export const AgentMemorySchema = z.object({
   totalChunks: z.number().int().min(1).default(1),
   tags: z.array(z.string()),
   createdAt: z.string(),
+  updatedAt: z.string().nullable().optional(),
   accessedAt: z.string(),
   expiresAt: z.string().nullable().optional(),
   accessCount: z.number().int().min(0).default(0).optional(),
   embeddingModel: z.string().nullable().optional(),
+  contentHash: z.string().nullable().optional(),
+  version: z.number().int().min(1).default(1).optional(),
 });
 
 export type AgentMemoryScope = z.infer<typeof AgentMemoryScopeSchema>;

package/src/workflows/executors/swarm-script.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { buildScriptCredentialBindings } from "../../be/script-credential-broker";
 import { getScript, getScriptVersion } from "../../be/scripts/db";
 import { DEFAULT_SCRIPT_RESOURCES } from "../../scripts-runtime/executors/types";
 import { runScript } from "../../scripts-runtime/loader";
@@ -72,6 +73,7 @@ export class SwarmScriptExecutor extends BaseExecutor<
       args: config.args,
       fsMode: "none",
       agentId: agentId ?? "workflow",
+      egressSecrets: buildScriptCredentialBindings({ agentId: agentId ?? undefined }),
       timeoutMs: config.timeoutMs,
     });
 

package/templates/community/dora-metrics/PLAYBOOK.md

@@ -0,0 +1,294 @@
+# DORA Metrics for Your Codebase, on Autopilot
+
+An Agent-Swarm playbook template for running recurring DORA metrics reports on any Git repository that has a reliable deployment tag signal.
+
+## What You Get
+
+This setup gives your swarm a stable DORA report page for one repository:
+
+- Deployment Frequency: release throughput over a configurable window.
+- Lead Time for Changes: median time from commit to the release tag that deployed it.
+- Change Failure Rate: proxy estimate from revert/hotfix-style remediation signals.
+- Failed Deployment Recovery Time: proxy estimate from the failed-release tag to the fixing tag.
+- A weekly refresh that updates the same page in place, so the URL does not change.
+
+The key caveat is part of the product: Deployment Frequency and Lead Time for Changes are exact when release tags map to production deployments. Change Failure Rate and Failed Deployment Recovery Time are proxy estimates until you connect a formal incident source.
+
+## Template Files
+
+The community template lives in `templates/community/dora-metrics/` and contains:
+
+- `PLAYBOOK.md`: this playbook.
+- `run.sh`: the parameterized runner.
+- `report.mjs`: the static report generator.
+- `lead-prompt.md`: the copy-paste Lead kickoff prompt.
+
+Install shape:
+
+```bash
+mkdir -p /workspace/dora-metrics
+cp templates/community/dora-metrics/run.sh /workspace/dora-metrics/
+cp templates/community/dora-metrics/report.mjs /workspace/dora-metrics/
+cp templates/community/dora-metrics/lead-prompt.md /workspace/dora-metrics/
+chmod +x /workspace/dora-metrics/run.sh
+```
+
+Parameterize each run with environment variables:
+
+```bash
+BASE_DIR=/workspace/dora-metrics \
+REPO_NAME=my-repo \
+REPO_URL=https://github.com/OWNER/REPO.git \
+BRANCH=main \
+TAG_PATTERN='v*' \
+WINDOW_DAYS=90 \
+bash /workspace/dora-metrics/run.sh
+```
+
+## Libraries and Runtime Shape
+
+The workflow uses:
+
+- Git tags: the canonical deployment event, when `TAG_PATTERN` maps 1:1 to production releases.
+- Git commit history: exact commit timestamps used for lead time.
+- GitHub CLI: optional but preferred for merged PR title metadata when identifying hotfix/revert signals.
+- jq: required utility dependency for predictable JSON handling in the runner environment.
+- Node.js: runs `report.mjs`, which computes metrics and writes static `report.html` plus `summary.json`.
+
+The generated HTML is static. The only network fetch at view time is D3:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js"></script>
+```
+
+## Template Directory Structure
+
+Use a workspace outside the target repository so report artifacts do not pollute the codebase:
+
+```text
+/workspace/dora-metrics/
+  run.sh
+  report.mjs
+  lead-prompt.md
+  repos/
+    <repo-name>/             # scratch clone, push URL disabled
+  out/
+    <repo-name>/
+      <YYYY-MM-DD>/
+        tags.tsv
+        recent-commits.tsv
+        remediation-commits.tsv
+        prs.json
+        revision.txt
+        revision-summary.txt
+        summary.json
+        report.html
+        latest-pointer.json
+      latest.json
+      latest.html
+      latest-pointer.json
+```
+
+## First-Run Behavior
+
+`run.sh` does the following:
+
+- Installs `git`, `jq`, and `nodejs` if missing.
+- Clones the target repository into a scratch directory.
+- Disables the scratch clone push URL so the scheduled job cannot push accidentally.
+- Fetches the configured branch and release tags matching `TAG_PATTERN`.
+- Writes release tag, recent commit, remediation commit, and optional PR metadata.
+- Runs `report.mjs`.
+- Copies the latest artifacts to stable `latest.html`, `latest.json`, and `latest-pointer.json` paths.
+
+## Runner Parameters
+
+Set these variables before calling `run.sh`:
+
+```bash
+BASE_DIR=/workspace/dora-metrics
+REPO_NAME=my-repo
+REPO_URL=https://github.com/OWNER/REPO.git
+BRANCH=main
+TAG_PATTERN='v*'
+WINDOW_DAYS=90
+HOTFIX_WINDOW_HOURS=24
+LOCAL_SOURCE=              # optional local git clone seed
+RUN_DATE=2026-06-26        # optional, defaults to current UTC date
+```
+
+The runner extracts release tags with:
+
+```bash
+git -C "$REPO_DIR" for-each-ref "refs/tags/$TAG_PATTERN" --sort=creatordate --format='%(refname:short)%09%(objectname)%09%(creatordate:iso-strict)%09%(creatordate:unix)'
+```
+
+It extracts remediation signals with:
+
+```bash
+git -C "$REPO_DIR" log "origin/$BRANCH" --since="$WINDOW_DAYS days ago" --grep='revert' --grep='rollback' --grep='hotfix' --grep='fix-forward' --regexp-ignore-case
+```
+
+When authenticated, it also asks `gh pr list` for merged PR titles so hotfix-style PRs can contribute to the proxy stability keys.
+
+## Metric Definitions and Bands
+
+The report uses the four DORA keys and 2024 performance bands as configurable constants in `report.mjs`.
+
+| Metric | Source | Quality | Band logic |
+|---|---|---|---|
+| Deployment Frequency | `TAG_PATTERN` release tags in the window | EXACT | Elite: at least daily. High: daily to weekly. Medium: weekly to monthly. Low: slower. |
+| Lead Time for Changes | Commit timestamp to containing release tag timestamp | EXACT | Elite: under 1 day. High: 1 day to 1 week. Medium: 1 week to 1 month. Low: slower. |
+| Change Failure Rate | Releases paired to revert, rollback, hotfix, or fix-forward signals | PROXY | 2024 cluster thresholds: ~5%, ~20%, ~10%, ~40%. Medium's lower CFR than High is a known 2024 cluster anomaly. |
+| Failed Deployment Recovery Time | Failed-release proxy tag to fixing tag | PROXY | Elite: under 1 hour. High/Medium: under 1 day. Low: slower. |
+
+The stability keys are intentionally labeled as proxy/estimated because a release tag plus commit/PR title heuristic is not an incident tracker. It can undercount fix-forward/manual incidents and overcount ordinary fixes.
+
+## Report Generator
+
+`report.mjs` parses the runner outputs, computes the four metrics, and embeds the final data in a static HTML file.
+
+The generator interface:
+
+```bash
+node /workspace/dora-metrics/report.mjs \
+  /workspace/dora-metrics/out/<repo-name>/<YYYY-MM-DD> \
+  /workspace/dora-metrics/repos/<repo-name> \
+  <repo-name> \
+  <YYYY-MM-DD> \
+  <BRANCH> \
+  <WINDOW_DAYS> \
+  <HOTFIX_WINDOW_HOURS> \
+  <TAG_PATTERN>
+```
+
+The generated report includes:
+
+- Four DORA metric cards.
+- `EXACT` / `PROXY` quality labels.
+- Deployment and lead-time charts.
+- Recent deployments table.
+   - Proxy remediation signal table.
+- D3 v7 loaded from CDN at view time.
+
+## Step-by-Step Playbook
+
+1. Confirm the deployment signal.
+
+   The default assumes `v*` tags map 1:1 to production releases. If your repository tags packages without deploying them, stop and configure a better deployment signal before using this template.
+
+2. Install the template.
+
+   Copy `run.sh`, `report.mjs`, and `lead-prompt.md` from `templates/community/dora-metrics/` into `/workspace/dora-metrics`, then make the runner executable.
+
+3. Run it once manually.
+
+   ```bash
+   BASE_DIR=/workspace/dora-metrics \
+   REPO_NAME=my-repo \
+   REPO_URL=https://github.com/OWNER/REPO.git \
+   BRANCH=main \
+   TAG_PATTERN='v*' \
+   WINDOW_DAYS=90 \
+   bash /workspace/dora-metrics/run.sh
+   ```
+
+4. Review local output.
+
+   ```bash
+   ls /workspace/dora-metrics/out/my-repo/latest.html
+   ls /workspace/dora-metrics/out/my-repo/latest.json
+   ```
+
+5. Publish the HTML to your swarm page system.
+
+   Create the page once, then store the returned stable page ID somewhere your scheduled task can read it. On later runs, update that same page by ID instead of creating a new page.
+
+   ```text
+   First run:
+     create page from /workspace/dora-metrics/out/my-repo/latest.html
+     save PAGE_ID=<stable-page-id>
+
+   Later runs:
+     update page PAGE_ID with /workspace/dora-metrics/out/my-repo/latest.html
+   ```
+
+6. Wire a weekly schedule.
+
+   Use a code-capable worker because this job may need to repair the script when upstream repo conventions, branch names, tag patterns, or page APIs change.
+
+   ```yaml
+   name: weekly-dora-metrics
+   cadence:
+     cron: "0 22 * * 0"
+     timezone: "UTC"
+   target:
+     worker: "<code-capable-worker>"
+   env:
+     BASE_DIR: "/workspace/dora-metrics"
+     REPO_NAME: "my-repo"
+     REPO_URL: "https://github.com/OWNER/REPO.git"
+     BRANCH: "main"
+     TAG_PATTERN: "v*"
+     WINDOW_DAYS: "90"
+     HOTFIX_WINDOW_HOURS: "24"
+     PAGE_ID: "<stable-page-id>"
+   task:
+     - run /workspace/dora-metrics/run.sh
+     - update the existing page PAGE_ID in place with latest.html
+     - verify D3 charts render and the exact/proxy labels are visible
+     - if the run fails, diagnose and repair the runner/report generator before reporting failure
+   ```
+
+7. Keep the same page URL.
+
+   The report should update in place. The page URL should not change between weekly runs.
+
+## Copy-Paste Lead Prompt
+
+The canonical copy lives in `lead-prompt.md` in the template and is also included below so this playbook can stand alone.
+
+# Lead Kickoff Prompt
+
+Copy this into your agent-swarm Lead to bootstrap the recurring report.
+
+```text
+Bootstrap a recurring DORA metrics report for my repository.
+
+Parameters:
+- Repository URL: <REPO_URL>
+- Default branch: <BRANCH>
+- Release tag pattern: <TAG_PATTERN, default v*>
+- Report name/slug: <REPORT_NAME>
+- Analysis window: <WINDOW_DAYS, default 90>
+- Hotfix/revert matching window: <HOTFIX_WINDOW_HOURS, default 24>
+- Cadence: weekly by default, cron "0 22 * * 0" in <TIMEZONE>
+- Stable page behavior: create the page once, then update the same page ID in place on every run.
+
+Requirements:
+1. Work outside the target repository under /workspace/dora-metrics.
+2. Install the community template files there: run.sh, report.mjs, and lead-prompt.md.
+3. Clone the repository into /workspace/dora-metrics/repos/<REPORT_NAME>, disable its push URL, fetch the requested branch, and fetch release tags matching <TAG_PATTERN>.
+4. Treat <TAG_PATTERN> tags as production deployments only if they map 1:1 to production releases.
+5. Compute Deployment Frequency and Lead Time for Changes exactly from tags and commits.
+6. Compute Change Failure Rate and Failed Deployment Recovery Time as proxy estimates from revert/hotfix signals.
+7. Label CFR and recovery time as proxy/estimated everywhere. Do not present them as precise incident metrics unless a formal incident source is added.
+8. Publish the first report as a swarm page and persist its stable page ID in the workflow configuration.
+9. Create a weekly schedule that executes run.sh, updates the same page ID, verifies render, and self-repairs local runner/report failures.
+10. Do not push any PR unless I explicitly ask for a versioned repository change.
+
+Deliver back:
+- The stable page URL.
+- The workspace paths for run.sh, report.mjs, latest.html, and latest.json.
+- The schedule name, cron, timezone, and how to change them.
+- A one-line caveat naming which metrics are exact and which are proxy estimates.
+- Any prerequisites or assumptions you could not satisfy automatically.
+```
+
+## References
+
+- [DORA metrics guide](https://dora.dev/guides/dora-metrics/): official definitions for Deployment Frequency, Lead Time for Changes, Change Failure Rate, and Failed Deployment Recovery Time.
+- [2024 Accelerate State of DevOps Report](https://dora.dev/research/2024/dora-report/): 2024 performance bands and cluster-analysis context.
+- [DORA research program](https://dora.dev/research/): background on the annual DORA reports and metric evolution.
+- [GitHub CLI](https://cli.github.com/manual/): optional PR metadata source used to enrich hotfix/revert proxy detection.
+- [D3.js](https://d3js.org): JavaScript library used for the browser-side charts.

package/templates/community/dora-metrics/README.md

@@ -0,0 +1,39 @@
+# DORA Metrics for Your Codebase, on Autopilot
+
+Community template for running recurring DORA metrics reports from an agent-swarm instance.
+
+Files:
+
+- `PLAYBOOK.md`: end-to-end setup and weekly schedule playbook.
+- `run.sh`: parameterized runner for any Git repository that uses release tags.
+- `report.mjs`: static HTML + JSON report generator.
+- `lead-prompt.md`: copy-paste prompt for your agent-swarm Lead.
+
+Quick start:
+
+```bash
+mkdir -p /workspace/dora-metrics
+cp run.sh report.mjs lead-prompt.md /workspace/dora-metrics/
+chmod +x /workspace/dora-metrics/run.sh
+
+BASE_DIR=/workspace/dora-metrics \
+REPO_NAME=my-repo \
+REPO_URL=https://github.com/OWNER/REPO.git \
+BRANCH=main \
+TAG_PATTERN='v*' \
+WINDOW_DAYS=90 \
+bash /workspace/dora-metrics/run.sh
+```
+
+Default weekly schedule cadence:
+
+```yaml
+cron: "0 22 * * 0"
+timezone: "UTC"
+```
+
+Change the `cron` field to adjust when the report refreshes. Keep the same page ID when publishing refreshes so the report URL remains stable.
+
+Deployment Frequency and Lead Time for Changes are exact when `TAG_PATTERN` maps 1:1 to production releases. Change Failure Rate and Failed Deployment Recovery Time are proxy estimates from revert/hotfix signals and are labeled that way in the generated report.
+
+See `PLAYBOOK.md` for the full setup flow, references, and metric-definition notes.

package/templates/community/dora-metrics/lead-prompt.md

@@ -0,0 +1,56 @@
+# Lead Kickoff Prompt
+
+Copy this into your agent-swarm Lead to bootstrap the recurring report.
+
+```text
+Bootstrap a recurring DORA metrics report for my repository.
+
+Parameters:
+- Repository URL: <REPO_URL>
+- Default branch: <BRANCH>
+- Release tag pattern: <TAG_PATTERN, default v*>
+- Report name/slug: <REPORT_NAME>
+- Analysis window: <WINDOW_DAYS, default 90>
+- Hotfix/revert matching window: <HOTFIX_WINDOW_HOURS, default 24>
+- Cadence: weekly by default, cron "0 22 * * 0" in <TIMEZONE>
+- Stable page behavior: create the page once, then update the same page ID in place on every run.
+
+Requirements:
+1. Work outside the target repository under /workspace/dora-metrics.
+2. Install the community template files there:
+   - run.sh
+   - report.mjs
+   - lead-prompt.md
+3. On first run, install missing runtime dependencies:
+   - git
+   - jq
+   - Node.js
+   - GitHub CLI is optional but preferred for PR title metadata.
+4. Clone the repository into /workspace/dora-metrics/repos/<REPORT_NAME>, disable its push URL, fetch the requested branch, and fetch release tags matching <TAG_PATTERN>.
+5. Treat <TAG_PATTERN> tags as production deployments only if they map 1:1 to production releases. If they do not, stop and ask for the correct deployment signal.
+6. Compute the four DORA keys:
+   - Deployment Frequency: EXACT from release tags.
+   - Lead Time for Changes: EXACT from commit timestamps to the containing release tag.
+   - Change Failure Rate: PROXY from revert, rollback, hotfix, and fix-forward signals near release tags.
+   - Failed Deployment Recovery Time: PROXY from failed-release proxy tag to fixing tag.
+7. Label CFR and recovery time as proxy/estimated everywhere. Do not present them as precise incident metrics unless a formal incident source is added.
+8. Generate a static report with:
+   - Four DORA metric cards.
+   - EXACT/PROXY quality labels.
+   - Deployment and lead-time charts.
+   - Recent deployments table.
+   - Proxy remediation signal table.
+9. Publish the first report as a swarm page and persist its stable page ID in the workflow configuration.
+10. Create a schedule pinned to a code-capable worker:
+    - Default cadence: weekly, cron "0 22 * * 0".
+    - To change the cadence, edit the cron field and timezone only.
+    - Each run executes run.sh, updates the same page ID in place, verifies the page renders, and self-repairs the runner/report if the failure is local and fixable.
+11. Do not push any PR unless I explicitly ask for a versioned repository change.
+
+Deliver back:
+- The stable page URL.
+- The workspace paths for run.sh, report.mjs, latest.html, and latest.json.
+- The schedule name, cron, timezone, and how to change them.
+- A one-line caveat naming which metrics are exact and which are proxy estimates.
+- Any prerequisites or assumptions you could not satisfy automatically.
+```