@synap-core/workspace-templates 0.11.0 → 0.23.0

package/capabilities/github-merge.capability.json

@@ -0,0 +1,99 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "github-merge",
+    "name": "GitHub — merge a pull request",
+    "description": "Merge a pull request from an approval, on a token the pod holds: pinned to the head the person approved, and refused when the head moved, a required check is not green, or the repository is not in the list. One verb, github_merge_pr. Separate from github-read, which never writes.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": false
+  },
+  "spec": {
+    "key": "github-merge",
+    "name": "GitHub — merge",
+    "description": "Merges ONE pull request on GitHub (https://api.github.com) when the person approves it: github_merge_pr {repo, pr, expectedHeadSha, base, method}. Before merging it reads the pull request and its checks and refuses, with the reason, when the repository is not in this install's list, the PR is not open or targets another base, its head is not the approved one, or a required check is missing or not green (any failed check refuses too). The merge itself is pinned to the approved sha, so GitHub refuses it if the head moved meanwhile. Ship steps run on the pod, not on an agent's machine (decision 4d6d7922).",
+    "params": [
+      {
+        "name": "githubToken",
+        "label": "GitHub token (merge)",
+        "type": "password",
+        "required": true,
+        "description": "A fine-grained GitHub token. Repository access = ONLY the repositories listed below (never one that lands through a merge queue). Permissions = Pull requests: Read and write, Contents: Read and write, Checks: Read, Commit statuses: Read. Stored encrypted in YOUR vault (not pod-wide); only the person who installed it can approve a merge through it."
+      },
+      {
+        "name": "repos",
+        "label": "Repositories it may merge",
+        "type": "text",
+        "required": true,
+        "description": "Comma-separated owner/repo, e.g. Synap-core/app-bases,Synap-core/browser. A repository not listed is refused before anything is read."
+      },
+      {
+        "name": "requiredChecks",
+        "label": "Required checks",
+        "type": "text",
+        "required": true,
+        "default": "synap/devbox",
+        "description": "Comma-separated check or commit-status names that must be green on the head, e.g. synap/devbox. Empty is refused: a merge with nothing vouching for the head never runs."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "githubMergeTokenSecret",
+        "name": "{{name}} GitHub token (merge)",
+        "value": "{{githubToken}}",
+        "type": "api_key",
+        "service": "github",
+        "description": "The installer's own GitHub token with write access to the listed repositories, used only by github_merge_pr. Not pod-wide."
+      }
+    ],
+    "tools": [
+      {
+        "name": "github_merge_api",
+        "kind": "api",
+        "description": "Authenticated access to the GitHub REST API for github_merge_pr: it reads a pull request and its checks, then merges it. `config.baseUrl` pins api.github.com; `config.auth` injects the vaulted token as `Authorization: Bearer <token>`.",
+        "credentialRef": "githubMergeTokenSecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.github.com",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Bearer "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "github_merge_pr",
+        "intent": "run_external_job",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Merge one pull request, pinned to the head the person approves. Returns { merged, mergeCommitSha, url, detail }. Refuses with the reason (nothing merged) when the repository is not in this install's list, the PR is not open, a draft, or targets another base, its head is not expectedHeadSha, or a required check is missing or not green (any failed check refuses too). Args: { repo: string (owner/name), pr: number, expectedHeadSha: string (the full 40-character head sha), base: string (the branch it lands on), method?: 'merge' | 'squash' | 'rebase' (default merge) }. The proposal reads \"Merge <repo>#<pr> into <base> at <sha8>\".",
+        "requires": [
+          "github_merge_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "repo": "string",
+          "pr": "number",
+          "expectedHeadSha": "string",
+          "base": "string",
+          "method": "string?"
+        },
+        "code": "// MERGE ONE PULL REQUEST, pinned to the head the person approved (decision\n// 4d6d7922, D1-D3). Executor wraps this body as (async (args, context) => {\n// <code> }). It refuses, with the reason, before it merges anything:\n//   1. the repo is not in this install's merge list (backend lands through its\n//      merge queue, never this verb);\n//   2. the PR is not open, is a draft, or targets another base;\n//   3. its head moved since the approval (expectedHeadSha);\n//   4. a required check is missing or not green, or any check failed.\n// Then it merges with GitHub's own sha pin (409 when the head moved meanwhile).\n// A failed read THROWS: nothing is ever merged on a guess.\nconst ALLOWED = '{{repos}}'\n  .split(',')\n  .map((s) => s.trim().replace(/^https?:\\/\\/(?:www\\.)?github\\.com\\//i, '').replace(/\\/+$/, '').toLowerCase())\n  .filter(Boolean);\nconst REQUIRED = '{{requiredChecks}}'.split(',').map((s) => s.trim()).filter(Boolean);\nconst H = { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'synap-pod-github-merge' };\n\nconst m = /^([A-Za-z0-9_.-]+)\\/([A-Za-z0-9_.-]+)$/.exec(String(args?.repo ?? '').trim());\nif (!m) throw new Error('github_merge_pr: repo must be owner/name, e.g. Synap-core/app-bases.');\nconst [, owner, name] = m;\nconst full = `${owner}/${name}`;\nif (!ALLOWED.includes(full.toLowerCase())) {\n  throw new Error(`github_merge_pr: ${full} is not in this pod's merge list (${ALLOWED.join(', ') || 'empty'}). Add it to the capability's repositories, or land it another way.`);\n}\nconst pr = Number(args?.pr);\nif (!Number.isInteger(pr) || pr <= 0) throw new Error('github_merge_pr: pr must be the pull request number.');\nconst sha = String(args?.expectedHeadSha ?? '').trim().toLowerCase();\nif (!/^[0-9a-f]{40}$/.test(sha)) throw new Error('github_merge_pr: expectedHeadSha must be the full 40-character head commit the person approves.');\nconst base = String(args?.base ?? '').trim();\nif (!base) throw new Error('github_merge_pr: base must name the branch it lands on (e.g. main).');\nconst method = String(args?.method ?? 'merge').trim() || 'merge';\nif (!['merge', 'squash', 'rebase'].includes(method)) throw new Error('github_merge_pr: method is merge, squash or rebase.');\nif (REQUIRED.length === 0) {\n  throw new Error('github_merge_pr: no required checks are configured, so nothing would vouch for this head. Set the capability\\'s required checks.');\n}\n\nconst get = async (path) => {\n  const r = await callProvider('github_merge_api', 'GET', path, undefined, { headers: H });\n  if (!r || r.status < 200 || r.status >= 300) {\n    throw new Error(`github_merge_pr: GitHub answered HTTP ${r?.status ?? '?'} for ${path} (token missing, expired, or without access to ${full}?).`);\n  }\n  return r.body ?? {};\n};\n\nconst p = await get(`/repos/${owner}/${name}/pulls/${pr}`);\nconst where = `${full}#${pr}`;\nif (p.merged === true) throw new Error(`github_merge_pr: ${where} is already merged.`);\nif (p.state !== 'open') throw new Error(`github_merge_pr: ${where} is ${p.state ?? 'not open'}.`);\nif (p.draft === true) throw new Error(`github_merge_pr: ${where} is a draft.`);\nconst head = String(p.head?.sha ?? '').toLowerCase();\nif (head !== sha) {\n  throw new Error(`github_merge_pr: ${where} moved since it was approved: approved ${sha.slice(0, 8)}, head is now ${head.slice(0, 8) || '?'}. Ask again for the new head.`);\n}\nif (p.base?.ref !== base) throw new Error(`github_merge_pr: ${where} targets ${p.base?.ref ?? '?'}, not ${base}.`);\n\n// The head's checks: each check run (latest per name) and each commit status\n// (GitHub's combined status keeps the latest per context).\nconst state = new Map();\nconst runs = await get(`/repos/${owner}/${name}/commits/${sha}/check-runs?per_page=100`);\nconst latest = new Map();\nfor (const r of runs.check_runs ?? []) {\n  const prev = latest.get(r.name);\n  if (!prev || Number(r.id) > Number(prev.id)) latest.set(r.name, r);\n}\nfor (const [n, r] of latest) {\n  state.set(n, r.status !== 'completed' ? 'pending' : ['success', 'neutral', 'skipped'].includes(r.conclusion) ? 'green' : 'failed');\n}\nconst combined = await get(`/repos/${owner}/${name}/commits/${sha}/status`);\nfor (const s of combined.statuses ?? []) {\n  state.set(s.context, s.state === 'success' ? 'green' : s.state === 'pending' ? 'pending' : 'failed');\n}\nconst missing = REQUIRED.filter((n) => !state.has(n));\nconst notGreen = REQUIRED.filter((n) => state.has(n) && state.get(n) !== 'green');\nconst failed = [...state].filter(([, v]) => v === 'failed').map(([n]) => n);\nif (missing.length || notGreen.length || failed.length) {\n  const parts = [];\n  if (missing.length) parts.push(`missing: ${missing.join(', ')}`);\n  if (notGreen.length) parts.push(`not green: ${notGreen.map((n) => `${n} (${state.get(n)})`).join(', ')}`);\n  if (failed.length) parts.push(`failed: ${failed.join(', ')}`);\n  throw new Error(`github_merge_pr: ${where} at ${sha.slice(0, 8)} is not ready to merge (${parts.join('; ')}).`);\n}\n\nconst res = await callProvider('github_merge_api', 'PUT', `/repos/${owner}/${name}/pulls/${pr}/merge`, { sha, merge_method: method }, { headers: H });\nif (!res || res.status !== 200 || res.body?.merged !== true) {\n  throw new Error(`github_merge_pr: GitHub refused to merge ${where} (HTTP ${res?.status ?? '?'}: ${res?.body?.message ?? 'no reason given'}).`);\n}\nconst mergeSha = String(res.body.sha ?? '');\nreturn {\n  merged: true,\n  mergeCommitSha: mergeSha || null,\n  url: p.html_url ?? `https://github.com/${full}/pull/${pr}`,\n  detail: `Merged ${where} at ${sha.slice(0, 8)} into ${base} as ${mergeSha.slice(0, 8) || '?'}.`,\n};",
+        "metadata": {
+          "verbType": "write"
+        }
+      }
+    ],
+    "provides": [
+      "run_external_job"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/github-read.capability.json

@@ -0,0 +1,325 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "github-read",
+    "name": "GitHub — pull requests, checks and releases (read)",
+    "description": "Read your GitHub pull requests, their checks, the latest release and how a branch compares with main, on your own token. Read-only: five GET verbs, no write. \"Merged\" and \"checks green\" are read from GitHub, not taken from a report.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "github-read",
+    "name": "GitHub — read",
+    "description": "Read-only GitHub REST API (https://api.github.com) on the person's OWN token: one pull request (state, merged, merge commit, head sha), the check runs on a commit, the latest release, a compare of a branch or sha against a base, and one criterion CHECK (github_check_pr_merged) a session criterion of kind capability runs to grade \"merged\" itself. Bring your own: the token is yours, stored in your vault (not pod-wide), and nothing here goes through a Synap-run proxy. An agent reads through it only with a vault grant you give it. Every verb is a fixed GET with typed parameters (owner, repo, number, ref, or the PR url of the outcome a check grades), never a passthrough; nothing writes to GitHub. TOKEN: a fine-grained personal access token limited to the repositories you want readable, with read access to Pull requests, Contents and Checks (Metadata is implied), or a classic token (no scope for public repositories, `repo` for private ones). A missing, expired or under-scoped token fails loudly (401/403/404 from GitHub), never reads as 'not merged' or 'no checks'. Rate limit: 5,000 requests an hour per token.",
+    "params": [
+      {
+        "name": "githubToken",
+        "label": "GitHub token (read-only)",
+        "type": "text",
+        "required": true,
+        "description": "A GitHub personal access token, read-only. Fine-grained (recommended): Repository access = the repositories you want the pod to read; Permissions = Pull requests: Read, Contents: Read, Checks: Read. Classic: no scope for public repositories, `repo` for private ones. Stored encrypted in YOUR vault (not pod-wide) and sent as `Authorization: Bearer <token>`; never persisted in this template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "githubReadTokenSecret",
+        "name": "{{name}} GitHub token (read-only)",
+        "value": "{{githubToken}}",
+        "type": "api_key",
+        "service": "github",
+        "description": "The person's own read-only GitHub token, used by every github_* verb of this capability. Not pod-wide: an agent needs a vault grant from its owner to read through it."
+      }
+    ],
+    "tools": [
+      {
+        "name": "github_api",
+        "kind": "api",
+        "description": "Authenticated READ access to the GitHub REST API. `config.baseUrl` pins api.github.com; `config.auth` injects the vaulted token as `Authorization: Bearer <token>`. Only this capability's GET verbs call it.",
+        "credentialRef": "githubReadTokenSecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.github.com",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Bearer "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "github_pr_get",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "One pull request: is it open, closed or merged, and with which commit. Use it to check \"merged\" yourself instead of trusting a report. Returns { number, title, state ('open' | 'closed'), draft, merged (boolean), mergedAt, mergeCommitSha, mergeableState, headSha, headRef, baseRef, url, updatedAt }. headSha is what github_pr_checks reads. Args: { owner: string (e.g. \"Synap-core\"), repo: string (e.g. \"backend\"), number: number }.",
+        "requires": [
+          "github_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "owner": "string",
+          "repo": "string",
+          "number": "number"
+        },
+        "providerSpec": {
+          "tool": "github_api",
+          "method": "GET",
+          "pathTemplate": "/repos/{{owner}}/{{repo}}/pulls/{{number}}",
+          "paramMapping": {
+            "owner": {
+              "required": true,
+              "encode": "uri"
+            },
+            "repo": {
+              "required": true,
+              "encode": "uri"
+            },
+            "number": {
+              "required": true,
+              "encode": "uri"
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "number": "number",
+              "title": "title",
+              "state": "state",
+              "draft": "draft",
+              "merged": "merged",
+              "mergedAt": "merged_at",
+              "mergeCommitSha": "merge_commit_sha",
+              "mergeableState": "mergeable_state",
+              "headSha": "head.sha",
+              "headRef": "head.ref",
+              "baseRef": "base.ref",
+              "url": "html_url",
+              "updatedAt": "updated_at"
+            }
+          },
+          "headers": {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "synap-pod-github-read"
+          }
+        },
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "github_pr_checks",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "The check runs on one commit — what CI says about a pull request's head. Pass the pull request's headSha (from github_pr_get) or a branch name as `ref`. Each run has { name, status ('queued' | 'in_progress' | 'completed'), conclusion ('success' | 'failure' | 'neutral' | 'cancelled' | 'skipped' | 'timed_out' | 'action_required' | null while running), url, startedAt, completedAt, app }. The checks are green only when every run is completed with success, neutral or skipped; a run still queued or in progress is not green yet. Returns { total, count, checkRuns }. Args: { owner: string, repo: string, ref: string (a sha or a branch), perPage?: number (default 100, max 100) }.",
+        "requires": [
+          "github_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "owner": "string",
+          "repo": "string",
+          "ref": "string",
+          "perPage": "number?"
+        },
+        "providerSpec": {
+          "tool": "github_api",
+          "method": "GET",
+          "pathTemplate": "/repos/{{owner}}/{{repo}}/commits/{{ref}}/check-runs",
+          "query": {
+            "per_page": "{{perPage}}"
+          },
+          "paramMapping": {
+            "owner": {
+              "required": true,
+              "encode": "uri"
+            },
+            "repo": {
+              "required": true,
+              "encode": "uri"
+            },
+            "ref": {
+              "required": true,
+              "encode": "uri"
+            },
+            "perPage": {
+              "default": 100,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          },
+          "responseShape": {
+            "collectionPath": "check_runs",
+            "collectionAs": "checkRuns",
+            "item": {
+              "name": "name",
+              "status": "status",
+              "conclusion": "conclusion",
+              "url": "html_url",
+              "startedAt": "started_at",
+              "completedAt": "completed_at",
+              "app": "app.slug"
+            },
+            "scalar": {
+              "total": "total_count",
+              "count": "@count"
+            }
+          },
+          "headers": {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "synap-pod-github-read"
+          }
+        },
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "github_release_latest",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "The latest published release of a repository (drafts and pre-releases are not \"latest\"). Use it to tell which version is out. Returns { tag, name, publishedAt, targetCommitish, url }. A repository with no release answers 404 (an error, never \"no release\" read as an empty result). Args: { owner: string, repo: string }.",
+        "requires": [
+          "github_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "owner": "string",
+          "repo": "string"
+        },
+        "providerSpec": {
+          "tool": "github_api",
+          "method": "GET",
+          "pathTemplate": "/repos/{{owner}}/{{repo}}/releases/latest",
+          "paramMapping": {
+            "owner": {
+              "required": true,
+              "encode": "uri"
+            },
+            "repo": {
+              "required": true,
+              "encode": "uri"
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "tag": "tag_name",
+              "name": "name",
+              "publishedAt": "published_at",
+              "targetCommitish": "target_commitish",
+              "url": "html_url"
+            }
+          },
+          "headers": {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "synap-pod-github-read"
+          }
+        },
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "github_compare",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "How a branch or commit stands against a base: is it behind main, and by how much; does a deployed sha contain a merge commit (compare base = the merge commit, head = the deployed sha: 'identical' or 'ahead' means it does). Returns { status ('identical' | 'ahead' | 'behind' | 'diverged'), aheadBy, behindBy, totalCommits, mergeBaseSha, url }. Args: { owner: string, repo: string, head: string (a branch or sha), base?: string (default \"main\") }.",
+        "requires": [
+          "github_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "owner": "string",
+          "repo": "string",
+          "head": "string",
+          "base": "string?"
+        },
+        "providerSpec": {
+          "tool": "github_api",
+          "method": "GET",
+          "pathTemplate": "/repos/{{owner}}/{{repo}}/compare/{{base}}...{{head}}",
+          "query": {
+            "per_page": "1"
+          },
+          "paramMapping": {
+            "owner": {
+              "required": true,
+              "encode": "uri"
+            },
+            "repo": {
+              "required": true,
+              "encode": "uri"
+            },
+            "head": {
+              "required": true,
+              "encode": "uri"
+            },
+            "base": {
+              "default": "main",
+              "encode": "uri"
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "status": "status",
+              "aheadBy": "ahead_by",
+              "behindBy": "behind_by",
+              "totalCommits": "total_commits",
+              "mergeBaseSha": "merge_base_commit.sha",
+              "url": "html_url"
+            }
+          },
+          "headers": {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "synap-pod-github-read"
+          }
+        },
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "github_check_pr_merged",
+        "intent": "fetch_record",
+        "kind": "code",
+        "scope": "pod",
+        "description": "A criterion CHECK: is a pull request merged? Returns { passed, detail, merged, state, mergeCommitSha, url } — `passed` is what a session criterion reads. As a capability criterion (check.kind capability, capability github_check_pr_merged), key the criterion like the outcome that holds the PR (pr-<repo>-<n>, ref = the PR url): the evaluator hands that outcome over and the url comes from its ref. Called by hand, pass { url }. A failed read (no token, no access, GitHub down) is an error, so the check reads unmeasured, never 'not merged'. Args: { outcome?: object (from the evaluator), url?: string (a GitHub pull request url) }.",
+        "requires": [
+          "github_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "outcome": "object?",
+          "url": "string?",
+          "sessionId": "string?",
+          "criterionKey": "string?"
+        },
+        "code": "// A CRITERION CHECK: is this pull request merged? Executor wraps this body as\n// (async (args, context) => { <code> }). The session evaluator calls it with\n// { sessionId, criterionKey, outcome: {key, kind, label, ref?} } — the session's\n// outcome slot with the criterion's key — so key the criterion like the PR's\n// outcome (pr-<repo>-<n>) and the PR url comes from outcome.ref.url. A person\n// or agent may pass `url` directly instead.\n// callProvider('github_api', …) resolves this capability's tool by NAME and\n// injects the vaulted token as `Authorization: Bearer <token>` (config.auth).\n// A failed read THROWS (the check reads \"unmeasured\"), never \"not merged\".\nconst url = String(args?.outcome?.ref?.url ?? args?.url ?? '').trim();\nconst m = /^https?:\\/\\/(?:www\\.)?github\\.com\\/([A-Za-z0-9_.-]+)\\/([A-Za-z0-9_.-]+)\\/pull\\/(\\d+)(?:[\\/?#].*)?$/i.exec(url);\nif (!m) {\n  throw new Error('github_check_pr_merged: no GitHub pull request url. Key the criterion like the outcome that holds the PR (pr-<repo>-<n>, ref = its url), or pass { url }.');\n}\nconst [, owner, repo, number] = m;\nconst res = await callProvider('github_api', 'GET', `/repos/${owner}/${repo}/pulls/${number}`, undefined, {\n  headers: { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'synap-pod-github-read' },\n});\nif (!res || res.status < 200 || res.status >= 300) {\n  throw new Error(`github_check_pr_merged: GitHub answered HTTP ${res?.status ?? '?'} for ${owner}/${repo}#${number} (token missing, expired or without read access to this repository?)`);\n}\nconst pr = res.body ?? {};\nconst merged = pr.merged === true;\nconst detail = merged\n  ? `${owner}/${repo}#${number} merged ${pr.merged_at ?? ''} as ${pr.merge_commit_sha ?? '?'}: ${pr.html_url ?? url}`\n  : `${owner}/${repo}#${number} is not merged (state ${pr.state ?? '?'}${pr.draft ? ', draft' : ''}): ${pr.html_url ?? url}`;\nreturn { passed: merged, detail, merged, state: pr.state ?? null, mergeCommitSha: pr.merge_commit_sha ?? null, url: pr.html_url ?? url };",
+        "metadata": {
+          "readOnly": true
+        }
+      }
+    ],
+    "provides": [
+      "fetch_record",
+      "list_records"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/governance-tighten-recommender.capability.json

@@ -0,0 +1,81 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "governance-tighten-recommender",
+    "name": "Governance — Tighten Recommender",
+    "description": "Reviews the agent proposals you rejected each day. When you keep rejecting the same kind of change, it files a review item suggesting that change should always need approval. Nothing changes until you approve.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "governance-tighten-recommender",
+    "name": "Governance Tighten Recommender",
+    "description": "Config-first daily governance calibration: once a day, scan recent REJECTED agent proposals, cluster them by shape, and — for any write-motif the humans reject consistently (a conservative floor: at least 5 rejections of that shape AND a high reject-rate) — file a pending governance.tighten_lane proposal. Approving one inserts a governance_rules row with verdict:'propose', pinning that agent motif back to REVIEW. This is the mirror image of the trusted-lane WIDEN scanner (packages/jobs/src/workers/governance-lane-scanner.ts): widen PROPOSES opening an auto-approve lane once an agent earns trust; tighten PROPOSES closing one when the humans keep saying no. Governed + never silent: the only side effect is filing PENDING review items — nothing tightens without a human approval. Option B packaging: a governed builtin verb (governance.recommend_tighten) invoked by a cron automation, so the whole loop is stored, user-editable config rather than a hardcoded worker.",
+    "params": [],
+    "vault": [],
+    "tools": [],
+    "skills": [],
+    "provides": [],
+    "playbooks": [],
+    "automations": [
+      {
+        "name": "Governance Tighten Recommender — Daily",
+        "description": "Every day at 04:30: run governance.recommend_tighten, which scans each agent's recent rejected proposals and files a governance.tighten_lane review item for any consistently-rejected write-motif. Seeded ACTIVE so the cron schedules (a draft never gets a nextRunAt). The verb is read-only w.r.t. graph data (it only files review items), so the capability node auto-runs unattended.",
+        "triggerType": "cron",
+        "triggerConfig": {
+          "expression": "30 4 * * *"
+        },
+        "status": "active",
+        "metadata": {
+          "kind": "calibration-recommender",
+          "mirrors": "governance-lane-scanner"
+        },
+        "flowDefinition": {
+          "nodes": [
+            {
+              "id": "trigger",
+              "type": "trigger",
+              "position": {
+                "x": 0,
+                "y": 0
+              },
+              "data": {
+                "triggerType": "cron",
+                "label": "Every day at 04:30",
+                "config": {
+                  "expression": "30 4 * * *"
+                }
+              }
+            },
+            {
+              "id": "recommend-tighten",
+              "type": "capability",
+              "position": {
+                "x": 0,
+                "y": 120
+              },
+              "data": {
+                "label": "Scan rejections → recommend tighten",
+                "verbId": "governance.recommend_tighten",
+                "inputMapping": {},
+                "_note": "governance.recommend_tighten takes NO params — it scans pod-wide agent proposals and files governance.tighten_lane review items itself, exactly like the widen scanner job. Read-only w.r.t. graph data (files review items only), so the node auto-runs without spawning a proposal for the verb itself."
+              }
+            }
+          ],
+          "edges": [
+            {
+              "id": "e-recommend",
+              "source": "trigger",
+              "target": "recommend-tighten"
+            }
+          ]
+        }
+      }
+    ]
+  },
+  "dependencies": []
+}