@autohq/cli 0.1.477 → 0.1.479

package/dist/agent-bridge.js

@@ -30866,7 +30866,7 @@ Object.assign(lookup, {
 // package.json
 var package_default = {
   name: "@autohq/cli",
-  version: "0.1.477",
+  version: "0.1.479",
   license: "SEE LICENSE IN README.md",
   publishConfig: {
     access: "public"
@@ -38169,8 +38169,10 @@ var SpendCapRuntimeErrorResponseSchema = external_exports.object({
   issues: external_exports.array(external_exports.unknown()).optional()
 });
 
-// ../../packages/schemas/src/templates/public-source.ts
+// ../../packages/schemas/src/templates/variable-contract.ts
 var import_yaml = __toESM(require_dist(), 1);
+
+// ../../packages/schemas/src/templates/public-source.ts
 var MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN = "https://www.auto.sh";
 var MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH = "/api/v1/templates";
 var SOURCE_COMMENT_PREFIX = `# Source: ${MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN}${MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH}/`;
@@ -49762,6 +49764,21 @@ triggers:
       ]
     }
   ],
+  "@auto/herald": [
+    {
+      version: "1.0.0",
+      files: [
+        {
+          path: "agents/herald.yaml",
+          content: '# Source: https://www.auto.sh/api/v1/templates/%40auto/herald/1.0.0/agents/herald.yaml\n# Required variables: branchPrefix, changelogPath, githubConnection, heartbeatCron, heartbeatTimezone, repoFullName, scanWindowDays, slackChannel, slackConnection, trustedApprovalMentionIds, validationCommandSet\nname: herald\nlabels:\n  purpose: changelog-curator\nimports:\n  - ../fragments/environments/agent-runtime.yaml\nsession:\n  archiveAfterInactive:\n    seconds: 86400\nharness: codex\nmodel:\n  provider: openai\n  id: gpt-5.6-sol\nreasoningEffort: high\nconcurrency: 1\nidentity:\n  displayName: Herald\n  username: herald\n  avatar:\n    asset: .auto/assets/herald.png\n    sha256: 50395a53249a96be9ca1eb160bde02c8ceb681bf08b589c8472ed493efceeb64\n  description:\n    Curates scheduled public changelogs from merged work judged user-facing and\n    valuable, for human wording and merge review.\ndisplayTitle: "Herald changelog: {{heartbeat.scheduledAt}}"\nsystemPrompt: |\n  You are Herald, the changelog curator for {{ $repoFullName }}. You prepare\n  human-reviewed changelog pull requests and never merge them.\n\n  Source of truth and public contract:\n  - `{{ $changelogPath }}` is the maintained changelog file and the sole state\n    for changelog idempotency and deduplication. Read the complete file before\n    planning an edit. Never create a parallel changelog source or depend on a\n    repository-specific changelog helper or generated data model.\n  - Preserve the file\'s existing format, ordering, headings, release grouping,\n    and editorial conventions. If the repository renders or publishes the file\n    elsewhere, preserve that presentation too. When an existing convention\n    exposes a lead entry as a teaser, the newest included entry must read well\n    standing alone.\n  - Internal source PR identifiers and merge timestamps are provenance. Never\n    put PR numbers, GitHub links, merge timestamps, provenance labels, or\n    PR-oriented wording in a headline, bullet, public changelog, rendered\n    page, or PR screenshot. This provenance ban applies to public changelog\n    content and rendering. The operational Slack approval message is not public\n    changelog content: it must include Herald\'s own changelog PR link, window,\n    counts, and validation summary, but never candidate PR links, candidate\n    provenance, or raw private content.\n  - Do not use labels or prewritten maintainer copy as eligibility authority;\n    Herald owns the bounded editorial judgment described below.\n\n  Editorial voice:\n  - Write every bullet as one complete, benefit-led sentence in present tense:\n    name the surface a user recognizes and state the outcome, not the\n    implementation. Concrete user impact is the register; vague reassurance is\n    not.\n  - Headlines are specific and thematic when the existing changelog format uses\n    them. Keep every headline distinct and write it in outcome language.\n  - Prefer substantive updates of roughly three to five entries. Never pad\n    with ineligible or trivial work to reach a count; a thin window ships a\n    short update or none at all.\n  - When the repository\'s changelog house style requires it, avoid digits,\n    apostrophes, and quotation marks in headlines and bullets. Treat this as\n    editorial guidance, not a claim that provenance validation rejects all such\n    characters.\n  - Avoid internal codenames and engineering jargon. If a change cannot be\n    described without internal context, it is not ready for the public\n    changelog.\n\n  Scan and selection:\n  - The scan window is exactly {{ $scanWindowDays }} days ending at the\n    heartbeat\'s `scheduledAt` timestamp. Use explicit inclusive ISO boundaries\n    and retain the overlap on every run so late merges are discovered.\n  - Search all merged PRs in that window, follow pagination to completion, and\n    fetch enough PR, file, diff, merge, review, and comment data to evaluate\n    every PR. If any page or required field is missing, truncated, stale, or\n    ambiguous, fail the run closed: do not edit, push, open a PR, or post raw\n    content. Report the incomplete surface and counts in the session output.\n  - Evaluate every merged PR in the window. No label or maintainer-supplied\n    public copy is required. Include a PR when the evidence supports a concrete,\n    externally observable outcome that is valuable to users: a new or improved\n    capability, a meaningful user-facing fix, better reliability, performance,\n    or accessibility, or materially less workflow friction.\n  - Exclude internal agent/process work, CI- or test-only changes, refactors,\n    dependency or maintenance work, and any change with no evidenced\n    user-visible outcome. Do not infer value from the PR title, files touched,\n    diff size, or author alone. For mixed PRs, include only the evidence-backed\n    user-facing outcome.\n  - Exclude private tenant details. Include a security-related change only when\n    a high-level user benefit is directly verifiable and can be stated without\n    vulnerability, exploit, tenant, or internal-defense details. When truth or\n    safety is uncertain, exclude the candidate and record the private reason;\n    never infer or publish a sensitive claim.\n  - Human wording or inclusion feedback in the Herald Slack thread or PR review\n    is steering input, not an eligibility prerequisite. Requests for more\n    inclusion mean re-evaluate excluded PRs against the same evidence and safety\n    rubric; requests for less inclusion mean remove or defer candidates. Human\n    steering never overrides completeness, provenance, or sensitive-content\n    safeguards.\n  - Count every scanned, included, and excluded PR. Keep exclusion reasons in\n    the private session summary, not in public copy or Slack.\n\n  Changelog update:\n  - Treat the complete existing contents of `{{ $changelogPath }}` as the\n    idempotency and deduplication state. Before writing, compare every proposed\n    user-facing outcome with every existing entry. If the file already describes\n    the same outcome, do not add it again. An overlapping rerun with no new or\n    corrected outcome is a no-op.\n  - A human-requested correction in PR review or the Herald Slack thread updates\n    the matching existing changelog entry; it never appends a duplicate. If the\n    intended entry cannot be identified confidently from the file contents and\n    review context, fail closed and ask for clarification.\n  - Add at most one new changelog section or release group per run when the\n    existing file format uses groups. Follow the file\'s established ordering and\n    date/version conventions. Group newly included outcomes together; corrections\n    may update older entries in the same focused PR.\n  - If there are no additions or corrections, open nothing. Report the exact\n    window, scanned count, included count, excluded count, and validation\n    result in the session output, then archive the session.\n\n  Pull-request workflow:\n  - Work from current `main` on `{{ $branchPrefix }}<YYYY-MM-DD>`. Search for an\n    existing open Herald changelog PR before creating one. Update that one\n    focused PR when it exists; otherwise create exactly one. Never create a\n    second PR for the same run and never enable auto-merge.\n  - Change only `{{ $changelogPath }}` and directly related tests or rendering\n    code unless a minimal\n    compatibility fix is required. Preserve the public presentation.\n  - Run the configured validation command set exactly as provided:\n    {{ $validationCommandSet }}\n  - Inspect the full literal diff and any rendered public output. Verify no\n    internal provenance appears in the changelog or rendered markup.\n  - After opening or updating the PR, confirm its attributed held\n    `github.pull_request` binding exists. Keep the branch and PR current,\n    address CI/review feedback with normal follow-up commits, repair merge\n    conflicts, and wait for green aggregate CI plus an exact-head `pr-review`\n    thumbs-up. Never merge.\n  - Post exactly one concise Slack message in `{{ $slackChannel }}` after the\n    PR exists. Tag {{ $trustedApprovalMentionIds }} for explicit public-copy\n    wording and merge approval. Include the PR link, inclusive\n    {{ $scanWindowDays }}-day window, included and excluded counts, and\n    validation summary. Invite replies in that thread to request more or less\n    inclusion. Do not include raw candidate, private, tenant, security, or\n    provenance content.\n  - While a PR is open, do not archive the session. On PR close, report the\n    final status and end the turn without self-archiving. The event router\n    releases the held binding only after the close delivery settles; the\n    configured inactivity policy may archive the unbound session later.\n\ninitialPrompt: |\n  Run the scheduled Herald changelog curation at {{heartbeat.scheduledAt}}.\n  Scan the inclusive {{ $scanWindowDays }}-day merged-PR window, apply the\n  fail-closed selection and changelog-file idempotency and deduplication\n  contract, and either prepare one human-reviewed PR or report an empty run\n  without opening anything.\nmounts:\n  - kind: git\n    repository: "{{ $repoFullName }}"\n    mountPath: /workspace/repo\n    ref: main\n    auth:\n      kind: githubApp\n      commitAuthor:\n        name: auto-dot-sh[bot]\n        email: 292914954+auto-dot-sh[bot]@users.noreply.github.com\n      capabilities:\n        contents: write\n        pullRequests: write\n        issues: read\n        checks: read\n        actions: read\n        workflows: none\n        secrets: none\n        merge: none\nworkingDirectory: /workspace/repo\nbindings:\n  github.pull_request:\n    lifecycle: held\n    bind: onAttributedEvent\n    continuity: agent\n    context:\n      role: implementer\n      workflow: herald\n      phase: implementation\ntools:\n  auto:\n    kind: local\n    implementation: auto\n  chat:\n    kind: local\n    implementation: chat\n    auth:\n      kind: connection\n      provider: slack\n      connection: "{{ $slackConnection }}"\n  github:\n    kind: github\n    tools:\n      - search_pull_requests\n      - pull_request_read\n      - get_file_contents\n      - list_commits\n      - actions_list\n      - actions_get\n      - get_job_logs\n      - create_pull_request\n      - update_pull_request\n      - upsert_issue_comment\n      - add_reply_to_pull_request_comment\n      - pull_request_review_write\ntriggers:\n  - name: changelog-heartbeat\n    kind: heartbeat\n    cron: "{{ $heartbeatCron }}"\n    timezone: "{{ $heartbeatTimezone }}"\n    message: |\n      Herald run scheduled at {{heartbeat.scheduledAt}}. Scan the inclusive\n      {{ $scanWindowDays }}-day window, then prepare one focused changelog PR\n      or report an empty run without opening anything.\n    routing:\n      kind: spawn\n  - name: check-failed\n    event: github.check_run.completed\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n      $.github.checkRun.conclusion: failure\n      $.github.checkRun.name:\n        notIn:\n          - All checks\n      $.github.checkRun.headIsCurrent:\n        notIn:\n          - false\n    message: |\n      Check {{github.checkRun.name}} failed on Herald PR\n      #{{github.pullRequest.number}}. Confirm it belongs to the current head,\n      diagnose it, and push a normal focused fix without enabling auto-merge.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n  - name: aggregate-ci-passed\n    event: github.check_run.completed\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n      $.github.checkRun.conclusion: success\n      $.github.checkRun.name: All checks\n      $.github.checkRun.headIsCurrent:\n        notIn:\n          - false\n    message: |\n      Aggregate CI passed on Herald PR #{{github.pullRequest.number}}. Inspect\n      the exact-head pr-review result and address any remaining feedback before\n      reporting the PR ready for human wording and merge review.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n  - name: pr-conversation\n    events:\n      - github.issue_comment.created\n      - github.issue_comment.edited\n      - github.pull_request_review.submitted\n      - github.pull_request_review.edited\n      - github.pull_request_review_comment.created\n      - github.pull_request_review_comment.edited\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n      $.github.auto.externalBot: false\n    message: |\n      A review or conversation update arrived on Herald PR\n      #{{github.pullRequest.number}}. Address wording or correctness feedback\n      on the existing branch, preserving the public/provenance boundary.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n  - name: slack-inclusion-steering\n    event: chat.message.subscribed\n    connection: "{{ $slackConnection }}"\n    where:\n      $.chat.provider: slack\n      $.auto.authored: false\n    message: |\n      {{message.author.userName}} replied in Herald\'s changelog approval thread:\n\n      {{message.text}}\n\n      Channel: {{chat.channelId}}\n      Thread: {{chat.threadId}}\n\n      Treat this as human steering on wording or inclusion. A request for more\n      inclusion means re-evaluate excluded PRs against the same evidence and\n      safety rubric; a request for less inclusion means remove or defer the\n      named candidates. Never relax scan completeness, private/tenant/security\n      safeguards, or the public provenance ban. Update the same focused PR,\n      rerun validation, and reply concisely in the thread with the outcome.\n    routing:\n      kind: deliver\n      routeBy:\n        kind: attributedSessions\n      onUnmatched: drop\n  - name: merge-conflict\n    event: github.pull_request.merge_conflict\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n    message: |\n      Herald PR #{{github.pullRequest.number}} has a merge conflict. Fetch the\n      latest main, resolve it minimally, and rerun affected validation.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n  - name: pr-closed\n    event: github.pull_request.closed\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n    message: |\n      Herald PR #{{github.pullRequest.number}} closed\n      (merged={{github.pullRequest.merged}}). Report final status and end the\n      turn without self-archiving. This trigger releases the held binding only\n      after delivery settles; inactivity archival can happen later.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n      release: true\n'
+        },
+        {
+          path: "fragments/environments/agent-runtime.yaml",
+          content: "# Source: https://www.auto.sh/api/v1/templates/%40auto/herald/1.0.0/fragments/environments/agent-runtime.yaml\nharness: codex\nenvironment:\n  name: agent-runtime\n  image:\n    kind: preset\n    name: node24\n  resources:\n    memoryMB: 8192\n"
+        }
+      ]
+    }
+  ],
   "@auto/incident-response": [
     {
       version: "1.0.0",
@@ -68564,6 +68581,7 @@ var TEMPLATE_DESCRIPTIONS = {
   "@auto/default": "Auto's minimum general-purpose runtime contract, implicitly imported by the permanent Default agent in every project.",
   "@auto/engineering-tier": "An engineering-tier fleet: senior and junior engineers with PR ownership, a live-iteration designer, and a session introspector.",
   "@auto/handoff": "A handoff coder that takes ownership of delegated PRs or coding tasks and reports back when ready.",
+  "@auto/herald": "A scheduled changelog curator that judges merged work for user-facing value and prepares one provenance-free, human-reviewed public changelog PR per run.",
   "@auto/incident-response": "A first responder for production alerts: investigates, delivers an evidence-based triage report, and opens a draft fix PR when the cause is clear; -slack entrypoint for channel triage.",
   "@auto/inspector": "A root-cause investigator that reproduces unusual behavior, bisects it, and produces a case file before anyone changes the code.",
   "@auto/intern": "A low-cost GLM 5.2 generalist for quick questions and bounded fixes, with calibrated escalation when work exceeds the intern lane.",

package/dist/index.js

@@ -22590,12 +22590,70 @@ var init_content_source = __esm({
   }
 });
 
-// ../../packages/schemas/src/templates/public-source.ts
+// ../../packages/schemas/src/templates/variable-contract.ts
 import { parseAllDocuments } from "yaml";
+function readTemplateVariableContract(document, path2) {
+  const value = document.templateVariables;
+  if (value === void 0) {
+    return { declared: false, required: /* @__PURE__ */ new Set(), optional: /* @__PURE__ */ new Set() };
+  }
+  if (!isRecord(value)) {
+    throw new Error(
+      `Invalid templateVariables in ${path2}: expected a map with required and optional lists`
+    );
+  }
+  const required2 = readVariableNames(value.required, "required", path2);
+  const optional2 = readVariableNames(value.optional, "optional", path2);
+  const overlap = [...required2].filter((name) => optional2.has(name)).sort();
+  if (overlap.length > 0) {
+    throw new Error(
+      `Invalid templateVariables in ${path2}: variables cannot be both required and optional (${overlap.join(", ")})`
+    );
+  }
+  return { declared: true, required: required2, optional: optional2 };
+}
+function readVariableNames(value, kind, path2) {
+  if (value === void 0) {
+    return /* @__PURE__ */ new Set();
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `Invalid templateVariables.${kind} in ${path2}: expected a list of variable names`
+    );
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const name of value) {
+    if (typeof name !== "string" || !VARIABLE_NAME_PATTERN.test(name)) {
+      throw new Error(
+        `Invalid templateVariables.${kind} in ${path2}: names must match [A-Za-z_][A-Za-z0-9_]*`
+      );
+    }
+    if (names.has(name)) {
+      throw new Error(
+        `Invalid templateVariables.${kind} in ${path2}: duplicate variable ${name}`
+      );
+    }
+    names.add(name);
+  }
+  return names;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var VARIABLE_NAME_PATTERN;
+var init_variable_contract = __esm({
+  "../../packages/schemas/src/templates/variable-contract.ts"() {
+    "use strict";
+    VARIABLE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+  }
+});
+
+// ../../packages/schemas/src/templates/public-source.ts
 var MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN, MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH, SOURCE_COMMENT_PREFIX;
 var init_public_source = __esm({
   "../../packages/schemas/src/templates/public-source.ts"() {
     "use strict";
+    init_variable_contract();
     MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN = "https://www.auto.sh";
     MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH = "/api/v1/templates";
     SOURCE_COMMENT_PREFIX = `# Source: ${MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN}${MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH}/`;
@@ -34198,6 +34256,21 @@ triggers:
           ]
         }
       ],
+      "@auto/herald": [
+        {
+          version: "1.0.0",
+          files: [
+            {
+              path: "agents/herald.yaml",
+              content: '# Source: https://www.auto.sh/api/v1/templates/%40auto/herald/1.0.0/agents/herald.yaml\n# Required variables: branchPrefix, changelogPath, githubConnection, heartbeatCron, heartbeatTimezone, repoFullName, scanWindowDays, slackChannel, slackConnection, trustedApprovalMentionIds, validationCommandSet\nname: herald\nlabels:\n  purpose: changelog-curator\nimports:\n  - ../fragments/environments/agent-runtime.yaml\nsession:\n  archiveAfterInactive:\n    seconds: 86400\nharness: codex\nmodel:\n  provider: openai\n  id: gpt-5.6-sol\nreasoningEffort: high\nconcurrency: 1\nidentity:\n  displayName: Herald\n  username: herald\n  avatar:\n    asset: .auto/assets/herald.png\n    sha256: 50395a53249a96be9ca1eb160bde02c8ceb681bf08b589c8472ed493efceeb64\n  description:\n    Curates scheduled public changelogs from merged work judged user-facing and\n    valuable, for human wording and merge review.\ndisplayTitle: "Herald changelog: {{heartbeat.scheduledAt}}"\nsystemPrompt: |\n  You are Herald, the changelog curator for {{ $repoFullName }}. You prepare\n  human-reviewed changelog pull requests and never merge them.\n\n  Source of truth and public contract:\n  - `{{ $changelogPath }}` is the maintained changelog file and the sole state\n    for changelog idempotency and deduplication. Read the complete file before\n    planning an edit. Never create a parallel changelog source or depend on a\n    repository-specific changelog helper or generated data model.\n  - Preserve the file\'s existing format, ordering, headings, release grouping,\n    and editorial conventions. If the repository renders or publishes the file\n    elsewhere, preserve that presentation too. When an existing convention\n    exposes a lead entry as a teaser, the newest included entry must read well\n    standing alone.\n  - Internal source PR identifiers and merge timestamps are provenance. Never\n    put PR numbers, GitHub links, merge timestamps, provenance labels, or\n    PR-oriented wording in a headline, bullet, public changelog, rendered\n    page, or PR screenshot. This provenance ban applies to public changelog\n    content and rendering. The operational Slack approval message is not public\n    changelog content: it must include Herald\'s own changelog PR link, window,\n    counts, and validation summary, but never candidate PR links, candidate\n    provenance, or raw private content.\n  - Do not use labels or prewritten maintainer copy as eligibility authority;\n    Herald owns the bounded editorial judgment described below.\n\n  Editorial voice:\n  - Write every bullet as one complete, benefit-led sentence in present tense:\n    name the surface a user recognizes and state the outcome, not the\n    implementation. Concrete user impact is the register; vague reassurance is\n    not.\n  - Headlines are specific and thematic when the existing changelog format uses\n    them. Keep every headline distinct and write it in outcome language.\n  - Prefer substantive updates of roughly three to five entries. Never pad\n    with ineligible or trivial work to reach a count; a thin window ships a\n    short update or none at all.\n  - When the repository\'s changelog house style requires it, avoid digits,\n    apostrophes, and quotation marks in headlines and bullets. Treat this as\n    editorial guidance, not a claim that provenance validation rejects all such\n    characters.\n  - Avoid internal codenames and engineering jargon. If a change cannot be\n    described without internal context, it is not ready for the public\n    changelog.\n\n  Scan and selection:\n  - The scan window is exactly {{ $scanWindowDays }} days ending at the\n    heartbeat\'s `scheduledAt` timestamp. Use explicit inclusive ISO boundaries\n    and retain the overlap on every run so late merges are discovered.\n  - Search all merged PRs in that window, follow pagination to completion, and\n    fetch enough PR, file, diff, merge, review, and comment data to evaluate\n    every PR. If any page or required field is missing, truncated, stale, or\n    ambiguous, fail the run closed: do not edit, push, open a PR, or post raw\n    content. Report the incomplete surface and counts in the session output.\n  - Evaluate every merged PR in the window. No label or maintainer-supplied\n    public copy is required. Include a PR when the evidence supports a concrete,\n    externally observable outcome that is valuable to users: a new or improved\n    capability, a meaningful user-facing fix, better reliability, performance,\n    or accessibility, or materially less workflow friction.\n  - Exclude internal agent/process work, CI- or test-only changes, refactors,\n    dependency or maintenance work, and any change with no evidenced\n    user-visible outcome. Do not infer value from the PR title, files touched,\n    diff size, or author alone. For mixed PRs, include only the evidence-backed\n    user-facing outcome.\n  - Exclude private tenant details. Include a security-related change only when\n    a high-level user benefit is directly verifiable and can be stated without\n    vulnerability, exploit, tenant, or internal-defense details. When truth or\n    safety is uncertain, exclude the candidate and record the private reason;\n    never infer or publish a sensitive claim.\n  - Human wording or inclusion feedback in the Herald Slack thread or PR review\n    is steering input, not an eligibility prerequisite. Requests for more\n    inclusion mean re-evaluate excluded PRs against the same evidence and safety\n    rubric; requests for less inclusion mean remove or defer candidates. Human\n    steering never overrides completeness, provenance, or sensitive-content\n    safeguards.\n  - Count every scanned, included, and excluded PR. Keep exclusion reasons in\n    the private session summary, not in public copy or Slack.\n\n  Changelog update:\n  - Treat the complete existing contents of `{{ $changelogPath }}` as the\n    idempotency and deduplication state. Before writing, compare every proposed\n    user-facing outcome with every existing entry. If the file already describes\n    the same outcome, do not add it again. An overlapping rerun with no new or\n    corrected outcome is a no-op.\n  - A human-requested correction in PR review or the Herald Slack thread updates\n    the matching existing changelog entry; it never appends a duplicate. If the\n    intended entry cannot be identified confidently from the file contents and\n    review context, fail closed and ask for clarification.\n  - Add at most one new changelog section or release group per run when the\n    existing file format uses groups. Follow the file\'s established ordering and\n    date/version conventions. Group newly included outcomes together; corrections\n    may update older entries in the same focused PR.\n  - If there are no additions or corrections, open nothing. Report the exact\n    window, scanned count, included count, excluded count, and validation\n    result in the session output, then archive the session.\n\n  Pull-request workflow:\n  - Work from current `main` on `{{ $branchPrefix }}<YYYY-MM-DD>`. Search for an\n    existing open Herald changelog PR before creating one. Update that one\n    focused PR when it exists; otherwise create exactly one. Never create a\n    second PR for the same run and never enable auto-merge.\n  - Change only `{{ $changelogPath }}` and directly related tests or rendering\n    code unless a minimal\n    compatibility fix is required. Preserve the public presentation.\n  - Run the configured validation command set exactly as provided:\n    {{ $validationCommandSet }}\n  - Inspect the full literal diff and any rendered public output. Verify no\n    internal provenance appears in the changelog or rendered markup.\n  - After opening or updating the PR, confirm its attributed held\n    `github.pull_request` binding exists. Keep the branch and PR current,\n    address CI/review feedback with normal follow-up commits, repair merge\n    conflicts, and wait for green aggregate CI plus an exact-head `pr-review`\n    thumbs-up. Never merge.\n  - Post exactly one concise Slack message in `{{ $slackChannel }}` after the\n    PR exists. Tag {{ $trustedApprovalMentionIds }} for explicit public-copy\n    wording and merge approval. Include the PR link, inclusive\n    {{ $scanWindowDays }}-day window, included and excluded counts, and\n    validation summary. Invite replies in that thread to request more or less\n    inclusion. Do not include raw candidate, private, tenant, security, or\n    provenance content.\n  - While a PR is open, do not archive the session. On PR close, report the\n    final status and end the turn without self-archiving. The event router\n    releases the held binding only after the close delivery settles; the\n    configured inactivity policy may archive the unbound session later.\n\ninitialPrompt: |\n  Run the scheduled Herald changelog curation at {{heartbeat.scheduledAt}}.\n  Scan the inclusive {{ $scanWindowDays }}-day merged-PR window, apply the\n  fail-closed selection and changelog-file idempotency and deduplication\n  contract, and either prepare one human-reviewed PR or report an empty run\n  without opening anything.\nmounts:\n  - kind: git\n    repository: "{{ $repoFullName }}"\n    mountPath: /workspace/repo\n    ref: main\n    auth:\n      kind: githubApp\n      commitAuthor:\n        name: auto-dot-sh[bot]\n        email: 292914954+auto-dot-sh[bot]@users.noreply.github.com\n      capabilities:\n        contents: write\n        pullRequests: write\n        issues: read\n        checks: read\n        actions: read\n        workflows: none\n        secrets: none\n        merge: none\nworkingDirectory: /workspace/repo\nbindings:\n  github.pull_request:\n    lifecycle: held\n    bind: onAttributedEvent\n    continuity: agent\n    context:\n      role: implementer\n      workflow: herald\n      phase: implementation\ntools:\n  auto:\n    kind: local\n    implementation: auto\n  chat:\n    kind: local\n    implementation: chat\n    auth:\n      kind: connection\n      provider: slack\n      connection: "{{ $slackConnection }}"\n  github:\n    kind: github\n    tools:\n      - search_pull_requests\n      - pull_request_read\n      - get_file_contents\n      - list_commits\n      - actions_list\n      - actions_get\n      - get_job_logs\n      - create_pull_request\n      - update_pull_request\n      - upsert_issue_comment\n      - add_reply_to_pull_request_comment\n      - pull_request_review_write\ntriggers:\n  - name: changelog-heartbeat\n    kind: heartbeat\n    cron: "{{ $heartbeatCron }}"\n    timezone: "{{ $heartbeatTimezone }}"\n    message: |\n      Herald run scheduled at {{heartbeat.scheduledAt}}. Scan the inclusive\n      {{ $scanWindowDays }}-day window, then prepare one focused changelog PR\n      or report an empty run without opening anything.\n    routing:\n      kind: spawn\n  - name: check-failed\n    event: github.check_run.completed\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n      $.github.checkRun.conclusion: failure\n      $.github.checkRun.name:\n        notIn:\n          - All checks\n      $.github.checkRun.headIsCurrent:\n        notIn:\n          - false\n    message: |\n      Check {{github.checkRun.name}} failed on Herald PR\n      #{{github.pullRequest.number}}. Confirm it belongs to the current head,\n      diagnose it, and push a normal focused fix without enabling auto-merge.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n  - name: aggregate-ci-passed\n    event: github.check_run.completed\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n      $.github.checkRun.conclusion: success\n      $.github.checkRun.name: All checks\n      $.github.checkRun.headIsCurrent:\n        notIn:\n          - false\n    message: |\n      Aggregate CI passed on Herald PR #{{github.pullRequest.number}}. Inspect\n      the exact-head pr-review result and address any remaining feedback before\n      reporting the PR ready for human wording and merge review.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n  - name: pr-conversation\n    events:\n      - github.issue_comment.created\n      - github.issue_comment.edited\n      - github.pull_request_review.submitted\n      - github.pull_request_review.edited\n      - github.pull_request_review_comment.created\n      - github.pull_request_review_comment.edited\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n      $.github.auto.externalBot: false\n    message: |\n      A review or conversation update arrived on Herald PR\n      #{{github.pullRequest.number}}. Address wording or correctness feedback\n      on the existing branch, preserving the public/provenance boundary.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n  - name: slack-inclusion-steering\n    event: chat.message.subscribed\n    connection: "{{ $slackConnection }}"\n    where:\n      $.chat.provider: slack\n      $.auto.authored: false\n    message: |\n      {{message.author.userName}} replied in Herald\'s changelog approval thread:\n\n      {{message.text}}\n\n      Channel: {{chat.channelId}}\n      Thread: {{chat.threadId}}\n\n      Treat this as human steering on wording or inclusion. A request for more\n      inclusion means re-evaluate excluded PRs against the same evidence and\n      safety rubric; a request for less inclusion means remove or defer the\n      named candidates. Never relax scan completeness, private/tenant/security\n      safeguards, or the public provenance ban. Update the same focused PR,\n      rerun validation, and reply concisely in the thread with the outcome.\n    routing:\n      kind: deliver\n      routeBy:\n        kind: attributedSessions\n      onUnmatched: drop\n  - name: merge-conflict\n    event: github.pull_request.merge_conflict\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n    message: |\n      Herald PR #{{github.pullRequest.number}} has a merge conflict. Fetch the\n      latest main, resolve it minimally, and rerun affected validation.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n  - name: pr-closed\n    event: github.pull_request.closed\n    connection: "{{ $githubConnection }}"\n    where:\n      $.github.repository.fullName: "{{ $repoFullName }}"\n    message: |\n      Herald PR #{{github.pullRequest.number}} closed\n      (merged={{github.pullRequest.merged}}). Report final status and end the\n      turn without self-archiving. This trigger releases the held binding only\n      after delivery settles; inactivity archival can happen later.\n    routing:\n      kind: bind\n      target: github.pull_request\n      onUnmatched: drop\n      release: true\n'
+            },
+            {
+              path: "fragments/environments/agent-runtime.yaml",
+              content: "# Source: https://www.auto.sh/api/v1/templates/%40auto/herald/1.0.0/fragments/environments/agent-runtime.yaml\nharness: codex\nenvironment:\n  name: agent-runtime\n  image:\n    kind: preset\n    name: node24\n  resources:\n    memoryMB: 8192\n"
+            }
+          ]
+        }
+      ],
       "@auto/incident-response": [
         {
           version: "1.0.0",
@@ -53031,6 +53104,7 @@ var init_hardcoded = __esm({
       "@auto/default": "Auto's minimum general-purpose runtime contract, implicitly imported by the permanent Default agent in every project.",
       "@auto/engineering-tier": "An engineering-tier fleet: senior and junior engineers with PR ownership, a live-iteration designer, and a session introspector.",
       "@auto/handoff": "A handoff coder that takes ownership of delegated PRs or coding tasks and reports back when ready.",
+      "@auto/herald": "A scheduled changelog curator that judges merged work for user-facing value and prepares one provenance-free, human-reviewed public changelog PR per run.",
       "@auto/incident-response": "A first responder for production alerts: investigates, delivers an evidence-based triage report, and opens a draft fix PR when the cause is clear; -slack entrypoint for channel triage.",
       "@auto/inspector": "A root-cause investigator that reproduces unusual behavior, bisects it, and produces a case file before anyone changes the code.",
       "@auto/intern": "A low-cost GLM 5.2 generalist for quick questions and bounded fixes, with calibrated escalation when work exceeds the intern lane.",
@@ -54686,6 +54760,7 @@ var init_templates = __esm({
     init_hardcoded();
     init_subscription();
     init_catalog();
+    init_variable_contract();
   }
 });
 
@@ -57684,7 +57759,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@autohq/cli",
-      version: "0.1.477",
+      version: "0.1.479",
       license: "SEE LICENSE IN README.md",
       publishConfig: {
         access: "public"
@@ -57945,7 +58020,7 @@ function compileAgentDocument(document, path2, stack, context) {
       `Agent import cycle detected: ${[...stack, resolvedPath].join(" -> ")}`
     );
   }
-  if (!isRecord2(document)) {
+  if (!isRecord3(document)) {
     throw new Error(`Invalid agent authoring file ${path2}: expected object`);
   }
   const imports = importPaths(document).map(
@@ -58070,25 +58145,25 @@ function authoringDocumentApplyShape(document, path2) {
   };
 }
 function finalizeAgentApplyShape(document, path2) {
-  if (!isRecord2(document) || !isRecord2(document.spec)) {
+  if (!isRecord3(document) || !isRecord3(document.spec)) {
     return { resource: document, resources: [] };
   }
   const next = structuredClone(document);
   const spec = next.spec;
   const resources = [];
-  if (isRecord2(spec.environment)) {
+  if (isRecord3(spec.environment)) {
     const environment = inlineEnvironmentResource(spec.environment, path2);
     spec.environment = environment.metadata.name;
     resources.push(environment);
   }
-  if (isRecord2(spec.identity)) {
+  if (isRecord3(spec.identity)) {
     const identity2 = inlineIdentityResource(spec.identity, next, path2);
     spec.identity = identity2.metadata.name;
     resources.push(identity2);
   }
   if (Array.isArray(spec.triggers)) {
     spec.triggers = spec.triggers.map((trigger) => {
-      if (!isRecord2(trigger) || !("name" in trigger)) {
+      if (!isRecord3(trigger) || !("name" in trigger)) {
         return trigger;
       }
       const compiledTrigger = { ...trigger };
@@ -58136,7 +58211,7 @@ function inlineIdentityResource(document, agentDocument, path2) {
     }
     spec[key] = value;
   }
-  if (metadata.name === void 0 && isRecord2(agentDocument.metadata) && typeof agentDocument.metadata.name === "string") {
+  if (metadata.name === void 0 && isRecord3(agentDocument.metadata) && typeof agentDocument.metadata.name === "string") {
     metadata.name = agentDocument.metadata.name;
   }
   const parsed = IdentityApplyRequestSchema.safeParse({ metadata, spec });
@@ -58172,7 +58247,7 @@ function resolveFileBackedFields(spec, path2) {
   };
 }
 function resolveFileBackedString(value, input) {
-  if (!isRecord2(value) || !("file" in value)) {
+  if (!isRecord3(value) || !("file" in value)) {
     return value;
   }
   const file2 = value.file;
@@ -58190,8 +58265,8 @@ function resolveFileBackedString(value, input) {
   return readFileSync8(resolve3(dirname8(input.path), filePath), "utf8");
 }
 function removalDirectives(document, path2) {
-  const raw = isRecord2(document.remove) ? document.remove : {};
-  if (!isRecord2(raw)) {
+  const raw = isRecord3(document.remove) ? document.remove : {};
+  if (!isRecord3(raw)) {
     return [];
   }
   const directives = [];
@@ -58213,18 +58288,18 @@ function stringList(value, label) {
   });
 }
 function applyRemoval(value, removal) {
-  if (!isRecord2(value)) {
+  if (!isRecord3(value)) {
     return value;
   }
   const next = structuredClone(value);
-  if (!isRecord2(next.spec)) {
+  if (!isRecord3(next.spec)) {
     return next;
   }
   const spec = { ...next.spec };
   next.spec = spec;
   switch (removal.target) {
     case "tools": {
-      if (!isRecord2(spec[removal.target])) {
+      if (!isRecord3(spec[removal.target])) {
         return next;
       }
       const collection = {
@@ -58268,7 +58343,7 @@ function mergeValues2(base, override, path2) {
   if (Array.isArray(base) && Array.isArray(override)) {
     return mergeArrays(base, override, path2);
   }
-  if (isRecord2(base) && isRecord2(override)) {
+  if (isRecord3(base) && isRecord3(override)) {
     const merged = { ...base };
     for (const [key, value] of Object.entries(override)) {
       merged[key] = mergeValues2(merged[key], value, [...path2, key]);
@@ -58311,7 +58386,7 @@ function isNamedArrayMergePath(path2) {
   return path2 === "spec.mounts" || path2 === "spec.triggers";
 }
 function collectionItemKey(collection, item) {
-  if (!isRecord2(item)) {
+  if (!isRecord3(item)) {
     return void 0;
   }
   if (typeof item.name === "string") {
@@ -58343,7 +58418,7 @@ function isAgentFile(path2) {
     return false;
   }
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var AGENT_FILE_EXTENSIONS, AGENT_SPEC_FIELDS, AGENT_METADATA_FIELDS;
@@ -58752,7 +58827,7 @@ function sourceFileIndex(files) {
 function isAbsoluteSourcePath(path2) {
   return path2.startsWith("/");
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var APPLY_DIRECTORIES, PROJECT_APPLY_RESOURCE_DIRECTORIES;
@@ -58831,7 +58906,7 @@ function resolveTemplateImportPath(importPath, fileIndex) {
   return key;
 }
 function removalDirectives2(document, path2) {
-  const raw = isRecord3(document.remove) ? document.remove : {};
+  const raw = isRecord4(document.remove) ? document.remove : {};
   const directives = [];
   for (const [target, value] of Object.entries(raw)) {
     const names = stringList2(value, `remove.${target}`);
@@ -58976,7 +59051,7 @@ function mergeValues3(base, override) {
   if (override === void 0) {
     return base;
   }
-  if (isRecord3(base) && isRecord3(override)) {
+  if (isRecord4(base) && isRecord4(override)) {
     const merged = { ...base };
     for (const [key, value] of Object.entries(override)) {
       merged[key] = mergeValues3(merged[key], value);
@@ -58996,7 +59071,7 @@ function sortJson(value) {
   if (Array.isArray(value)) {
     return value.map(sortJson);
   }
-  if (isRecord3(value)) {
+  if (isRecord4(value)) {
     return Object.fromEntries(
       Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nested]) => [key, sortJson(nested)])
     );
@@ -59012,7 +59087,9 @@ var init_helpers = __esm({
       "import",
       "imports",
       "remove",
-      "variables"
+      "templateVariables",
+      "variables",
+      "when"
     ]);
     AGENT_METADATA_FIELD_KEYS = ["name", "labels", "annotations"];
   }
@@ -59032,7 +59109,7 @@ function fileBackedStringField() {
   };
 }
 function rejectDirectiveObject(value, input) {
-  if (isRecord3(value) && "append" in value) {
+  if (isRecord4(value) && "append" in value) {
     throw new Error(
       `Invalid agent authoring file ${input.path}: ${input.field} does not support directive objects; append is supported on ${APPEND_CAPABLE_FIELDS}`
     );
@@ -59040,7 +59117,7 @@ function rejectDirectiveObject(value, input) {
   return value;
 }
 function resolveFileBackedString2(value, input) {
-  if (!isRecord3(value)) {
+  if (!isRecord4(value)) {
     return value;
   }
   if ("file" in value && !("append" in value)) {
@@ -59138,11 +59215,11 @@ function rejectUnresolvedAppendDirective(value) {
   );
 }
 function appendDirectiveFromMarker(value) {
-  if (!isRecord3(value)) {
+  if (!isRecord4(value)) {
     return void 0;
   }
   const marker = value[APPEND_DIRECTIVE_MARKER_KEY];
-  if (!isRecord3(marker)) {
+  if (!isRecord4(marker)) {
     return void 0;
   }
   return marker;
@@ -59164,7 +59241,7 @@ function inlineEnvironmentField() {
     target: "spec",
     merge: (base, override) => mergeValues3(base, override),
     compile: (value, context) => {
-      if (!isRecord3(value)) {
+      if (!isRecord4(value)) {
         return { resources: [], value };
       }
       const resource = inlineEnvironmentResource2(value, context.path);
@@ -59177,7 +59254,7 @@ function inlineIdentityField() {
     target: "spec",
     merge: (base, override) => mergeValues3(base, override),
     compile: (value, context) => {
-      if (!isRecord3(value)) {
+      if (!isRecord4(value)) {
         return { resources: [], value };
       }
       const resource = inlineIdentityResource2(
@@ -59190,7 +59267,7 @@ function inlineIdentityField() {
   };
 }
 function assertAgentAuthoringDocument(document, path2) {
-  if (!isRecord3(document) || !("kind" in document)) {
+  if (!isRecord4(document) || !("kind" in document)) {
     return;
   }
   if (document.kind === "session") {
@@ -59343,12 +59420,12 @@ function compileRoutingInlineBindings(input) {
   const bindings = input.bindings ? cloneBindings(input.bindings) : {};
   const compiledTriggers = [];
   for (const trigger of input.triggers) {
-    if (!isRecord3(trigger) || trigger.kind === "heartbeat") {
+    if (!isRecord4(trigger) || trigger.kind === "heartbeat") {
       compiledTriggers.push(trigger);
       continue;
     }
     const routing = trigger.routing;
-    if (!isRecord3(routing)) {
+    if (!isRecord4(routing)) {
       compiledTriggers.push(trigger);
       continue;
     }
@@ -59379,7 +59456,7 @@ function extractDeliverContribution(routing, path2) {
   if (bindBlock === void 0) {
     return void 0;
   }
-  if (!isRecord3(bindBlock)) {
+  if (!isRecord4(bindBlock)) {
     throw inlineShapeError(
       path2,
       "deliver",
@@ -59409,7 +59486,7 @@ function extractBindArmContribution(routing, path2) {
 }
 function extractSpawnArmContribution(routing, path2) {
   const bindBlock = routing.bind;
-  if (!isRecord3(bindBlock)) {
+  if (!isRecord4(bindBlock)) {
     return void 0;
   }
   if (bindBlock.lifecycle === void 0 && bindBlock.continuity === void 0) {
@@ -59447,7 +59524,7 @@ function mergeContributionIntoBindings(bindings, contribution, path2) {
 }
 function ensureEntry(bindings, target) {
   const existing = bindings[target];
-  if (isRecord3(existing)) {
+  if (isRecord4(existing)) {
     return existing;
   }
   const entry = {};
@@ -59469,7 +59546,7 @@ function stripInlineRoutingFields(trigger, routing) {
       return { ...trigger, routing: rest };
     }
     case "spawn": {
-      if (!isRecord3(routing.bind)) {
+      if (!isRecord4(routing.bind)) {
         return trigger;
       }
       const {
@@ -59534,7 +59611,7 @@ function rejectSingletonTarget(target, path2, arm) {
 function cloneBindings(bindings) {
   const clone2 = {};
   for (const [key, value] of Object.entries(bindings)) {
-    clone2[key] = isRecord3(value) ? { ...value } : value;
+    clone2[key] = isRecord4(value) ? { ...value } : value;
   }
   return clone2;
 }
@@ -59584,7 +59661,7 @@ function triggersField() {
       const withNamesStripped = removeAuthoringTriggerNames(value);
       const { triggers, bindings } = compileRoutingInlineBindings({
         triggers: withNamesStripped,
-        bindings: isRecord3(context.draft.spec.bindings) ? context.draft.spec.bindings : void 0,
+        bindings: isRecord4(context.draft.spec.bindings) ? context.draft.spec.bindings : void 0,
         path: context.path
       });
       context.draft.spec.bindings = bindings;
@@ -59593,7 +59670,7 @@ function triggersField() {
   };
 }
 function mountItemKey(item) {
-  if (!isRecord3(item)) {
+  if (!isRecord4(item)) {
     return void 0;
   }
   if (typeof item.name === "string") {
@@ -59605,7 +59682,7 @@ function mountItemKey(item) {
   return void 0;
 }
 function triggerItemKey(item) {
-  if (!isRecord3(item)) {
+  if (!isRecord4(item)) {
     return void 0;
   }
   if (typeof item.name === "string") {
@@ -59658,7 +59735,7 @@ function removeAuthoringTriggerNames(value) {
     return value;
   }
   return value.map((trigger) => {
-    if (!isRecord3(trigger) || !("name" in trigger)) {
+    if (!isRecord4(trigger) || !("name" in trigger)) {
       return trigger;
     }
     const next = { ...trigger };
@@ -59681,7 +59758,7 @@ function namedMapField() {
     target: "spec",
     merge: (base, override) => mergeValues3(base, override),
     remove: (value, names) => {
-      if (!isRecord3(value)) {
+      if (!isRecord4(value)) {
         return value;
       }
       const next = { ...value };
@@ -59780,7 +59857,7 @@ function mergeSourceLocations(base, override) {
         continue;
       }
       const prefix = `${target}.${key}`;
-      if (!isRecord3(value)) {
+      if (!isRecord4(value)) {
         merged = Object.fromEntries(
           Object.entries(merged).filter(
             ([path2]) => path2 !== prefix && !path2.startsWith(`${prefix}.`)
@@ -59907,14 +59984,14 @@ function readVariableScope(document, path2) {
   if (declared === void 0) {
     return /* @__PURE__ */ new Map();
   }
-  if (!isRecord3(declared)) {
+  if (!isRecord4(declared)) {
     throw new Error(
       `Invalid variables in ${path2}: variables must be a map of name to value`
     );
   }
   const scope = /* @__PURE__ */ new Map();
   for (const [name, value] of Object.entries(declared)) {
-    if (!VARIABLE_NAME_PATTERN.test(name)) {
+    if (!VARIABLE_NAME_PATTERN2.test(name)) {
       throw new Error(
         `Invalid variable name "${name}" in ${path2}: names must match [A-Za-z_][A-Za-z0-9_]*`
       );
@@ -59923,6 +60000,66 @@ function readVariableScope(document, path2) {
   }
   return scope;
 }
+function registerTemplateVariableContract(declarations, contract, path2) {
+  for (const [kind, names] of [
+    ["required", contract.required],
+    ["optional", contract.optional]
+  ]) {
+    for (const name of names) {
+      const existing = declarations.get(name);
+      if (existing && existing.kind !== kind) {
+        throw new Error(
+          `Conflicting template variable declaration for "${name}": ${existing.kind} in ${existing.path}, ${kind} in ${path2}`
+        );
+      }
+      declarations.set(name, existing ?? { kind, path: path2 });
+    }
+  }
+}
+function assertRequiredTemplateVariables(required2, variables, path2) {
+  for (const name of [...required2].sort()) {
+    if (!variables.has(name)) {
+      throw new Error(
+        `Required template variable "${name}" is missing for imported ${path2}`
+      );
+    }
+  }
+}
+function includeConditionalTemplateDocument(input) {
+  const optional2 = new Set(
+    [...input.declarations.entries()].filter(([, declaration]) => declaration.kind === "optional").map(([name]) => name)
+  );
+  const referencedOptional = optionalVariableReferences(
+    input.document,
+    optional2
+  );
+  const condition = readVariableCondition(input.document.when, input.path);
+  if (referencedOptional.size > 0) {
+    if (!condition || referencedOptional.size !== 1 || !referencedOptional.has(condition)) {
+      throw new Error(
+        `Optional template variables in ${input.path} must be referenced only inside a document gated by matching when.variable`
+      );
+    }
+  }
+  if (!condition) {
+    return true;
+  }
+  if (!optional2.has(condition)) {
+    throw new Error(
+      `Invalid when.variable in ${input.path}: "${condition}" must be declared in templateVariables.optional`
+    );
+  }
+  const value = input.variables.get(condition);
+  if (value === void 0) {
+    return false;
+  }
+  if (value.trim().length === 0) {
+    throw new Error(
+      `Optional template variable "${condition}" in ${input.path} must be non-empty when supplied`
+    );
+  }
+  return true;
+}
 function substituteVariables(document, scope, site) {
   if (scope.size === 0) {
     return document;
@@ -59936,7 +60073,7 @@ function substituteValue(value, scope, site) {
   if (Array.isArray(value)) {
     return value.map((item) => substituteValue(item, scope, site));
   }
-  if (isRecord3(value)) {
+  if (isRecord4(value)) {
     return Object.fromEntries(
       Object.entries(value).map(([key, nested]) => [
         key,
@@ -59971,13 +60108,49 @@ function coerceVariableValue(name, value, path2) {
 function availableNames(scope) {
   return [...scope.keys()].sort().map((name) => `{{ $${name} }}`).join(", ");
 }
-var VARIABLE_DECLARATIONS_FIELD, VARIABLE_NAME_PATTERN, VARIABLE_REFERENCE_PATTERN;
+function readVariableCondition(value, path2) {
+  if (value === void 0) return void 0;
+  if (!isRecord4(value) || typeof value.variable !== "string" || value.variable.length === 0 || Object.keys(value).some((key) => key !== "variable")) {
+    throw new Error(
+      `Invalid when in ${path2}: expected exactly { variable: <optional variable name> }`
+    );
+  }
+  return value.variable;
+}
+function optionalVariableReferences(value, optional2) {
+  const found = /* @__PURE__ */ new Set();
+  collectOptionalVariableReferences(value, optional2, found);
+  return found;
+}
+function collectOptionalVariableReferences(value, optional2, found) {
+  if (typeof value === "string") {
+    for (const match of value.matchAll(VARIABLE_REFERENCE_PATTERN)) {
+      if (match[1] && optional2.has(match[1])) found.add(match[1]);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectOptionalVariableReferences(item, optional2, found);
+    }
+    return;
+  }
+  if (isRecord4(value)) {
+    for (const [key, nested] of Object.entries(value)) {
+      if (key !== "templateVariables" && key !== "when") {
+        collectOptionalVariableReferences(nested, optional2, found);
+      }
+    }
+  }
+}
+var VARIABLE_DECLARATIONS_FIELD, VARIABLE_NAME_PATTERN2, VARIABLE_REFERENCE_PATTERN;
 var init_template_variables = __esm({
   "../../packages/schemas/src/project-apply-files/template-variables.ts"() {
     "use strict";
+    init_templates();
     init_source();
     VARIABLE_DECLARATIONS_FIELD = "variables";
-    VARIABLE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+    VARIABLE_NAME_PATTERN2 = /^[A-Za-z_][A-Za-z0-9_]*$/;
     VARIABLE_REFERENCE_PATTERN = /\{\{\s*\$([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
   }
 });
@@ -60064,7 +60237,7 @@ function projectCompiledTriggerSourceLocations(locations, authoredTriggers) {
   );
   let compiledIndex = 0;
   for (const [authoredIndex, trigger] of authoredTriggers.entries()) {
-    if (!isRecord3(trigger)) {
+    if (!isRecord4(trigger)) {
       continue;
     }
     const events = authoredTriggerEvents(trigger);
@@ -60132,9 +60305,24 @@ function validateAgentFragmentDocument(document, path2, context) {
       `Agent import cycle detected: ${[...context.stack, normalizedPath].join(" -> ")}`
     );
   }
-  if (!isRecord3(document)) {
+  if (!isRecord4(document)) {
     throw new Error(`Invalid agent fragment file ${path2}: expected object`);
   }
+  const variableContract = readTemplateVariableContract(
+    document,
+    normalizedPath
+  );
+  registerTemplateVariableContract(
+    context.templateVariableKinds,
+    variableContract,
+    normalizedPath
+  );
+  includeConditionalTemplateDocument({
+    document,
+    declarations: context.templateVariableKinds,
+    variables: context.variables,
+    path: normalizedPath
+  });
   for (const imported of importPaths2(document).map(
     (importPath) => resolveImportPath2(importPath, normalizedPath, context.fileIndex)
   )) {
@@ -60144,6 +60332,7 @@ function validateAgentFragmentDocument(document, path2, context) {
       {
         fileIndex: context.fileIndex,
         stack: [...context.stack, normalizedPath],
+        templateVariableKinds: context.templateVariableKinds,
         variables: context.variables
       }
     );
@@ -60182,20 +60371,59 @@ function conflictingGeneratedResourceMessage(key, existing, record2) {
   return `Conflicting generated resource "${key}" from agent authoring: ${location}. Inline generated resources must be identical when they share a name.`;
 }
 function compileAgentDocumentValue(document, path2, fileIndex, contextVariables) {
+  const templateVariableKinds = /* @__PURE__ */ new Map();
+  collectTemplateVariableContracts(
+    document,
+    path2,
+    fileIndex,
+    [],
+    templateVariableKinds
+  );
   const draft = compileAgentDocument2(document, path2, {
     fileIndex,
     stack: [],
+    templateVariableKinds,
     variables: /* @__PURE__ */ new Map(),
     ...contextVariables && Object.keys(contextVariables).length > 0 ? { contextVariables: new Map(Object.entries(contextVariables)) } : {}
   });
   const authoredTriggers = structuredClone(draft.spec.triggers);
-  const removals = isRecord3(document) ? removalDirectives2(document, normalizeSourcePath(path2)) : [];
+  const removals = isRecord4(document) ? removalDirectives2(document, normalizeSourcePath(path2)) : [];
   return {
     ...compileAgentDraftResources(draft, path2, removals),
     sourceLocations: draft.sourceLocations,
     authoredTriggers
   };
 }
+function collectTemplateVariableContracts(document, path2, fileIndex, stack, declarations) {
+  const normalizedPath = normalizeSourcePath(path2);
+  if (stack.includes(normalizedPath)) {
+    throw new Error(
+      `Agent import cycle detected: ${[...stack, normalizedPath].join(" -> ")}`
+    );
+  }
+  if (!isRecord4(document)) {
+    throw new Error(`Invalid agent authoring file ${path2}: expected object`);
+  }
+  registerTemplateVariableContract(
+    declarations,
+    readTemplateVariableContract(document, normalizedPath),
+    normalizedPath
+  );
+  const imports = [
+    ...stack.length === 0 && document.name === BUILT_IN_DEFAULT_AGENT_NAME ? [BUILT_IN_DEFAULT_AGENT_TEMPLATE_IMPORT] : [],
+    ...importPaths2(document)
+  ];
+  for (const importPath of imports) {
+    const imported = resolveImportPath2(importPath, normalizedPath, fileIndex);
+    collectTemplateVariableContracts(
+      readSingleDocument2(imported, fileIndex),
+      imported,
+      fileIndex,
+      [...stack, normalizedPath],
+      declarations
+    );
+  }
+}
 function compileAgentDocument2(document, path2, context) {
   const normalizedPath = normalizeSourcePath(path2);
   if (context.stack.includes(normalizedPath)) {
@@ -60203,13 +60431,35 @@ function compileAgentDocument2(document, path2, context) {
       `Agent import cycle detected: ${[...context.stack, normalizedPath].join(" -> ")}`
     );
   }
-  if (!isRecord3(document)) {
+  if (!isRecord4(document)) {
     throw new Error(`Invalid agent authoring file ${path2}: expected object`);
   }
+  const variableContract = readTemplateVariableContract(
+    document,
+    normalizedPath
+  );
+  registerTemplateVariableContract(
+    context.templateVariableKinds,
+    variableContract,
+    normalizedPath
+  );
   const variables = context.stack.length === 0 ? new Map([
     ...context.contextVariables ?? /* @__PURE__ */ new Map(),
     ...readVariableScope(document, normalizedPath)
   ]) : context.variables;
+  assertRequiredTemplateVariables(
+    variableContract.required,
+    variables,
+    normalizedPath
+  );
+  if (context.stack.length > 0 && !includeConditionalTemplateDocument({
+    document,
+    declarations: context.templateVariableKinds,
+    variables,
+    path: normalizedPath
+  })) {
+    return emptyAgentDraft();
+  }
   let merged = emptyAgentDraft();
   const imports = [
     ...context.stack.length === 0 && document.name === BUILT_IN_DEFAULT_AGENT_NAME ? [BUILT_IN_DEFAULT_AGENT_TEMPLATE_IMPORT] : [],
@@ -60221,16 +60471,47 @@ function compileAgentDocument2(document, path2, context) {
       normalizedPath,
       context.fileIndex
     );
+    const rawImportedDocument = readSingleDocument2(imported, context.fileIndex);
+    if (!isRecord4(rawImportedDocument)) {
+      throw new Error(
+        `Invalid agent authoring file ${imported}: expected object`
+      );
+    }
+    const importedContract = readTemplateVariableContract(
+      rawImportedDocument,
+      imported
+    );
+    registerTemplateVariableContract(
+      context.templateVariableKinds,
+      importedContract,
+      imported
+    );
+    assertRequiredTemplateVariables(
+      importedContract.required,
+      variables,
+      imported
+    );
+    if (!includeConditionalTemplateDocument({
+      document: rawImportedDocument,
+      declarations: context.templateVariableKinds,
+      variables,
+      path: imported
+    })) {
+      continue;
+    }
     const importedDocument = substituteVariables(
-      readSingleDocument2(imported, context.fileIndex),
+      rawImportedDocument,
       variables,
-      { importPath }
+      {
+        importPath
+      }
     );
     merged = mergeAgentDrafts(
       merged,
       compileAgentDocument2(importedDocument, imported, {
         fileIndex: context.fileIndex,
         stack: [...context.stack, normalizedPath],
+        templateVariableKinds: context.templateVariableKinds,
         variables
       })
     );
@@ -60247,6 +60528,7 @@ var init_agent_authoring = __esm({
   "../../packages/schemas/src/project-apply-files/agent-authoring.ts"() {
     "use strict";
     init_default_agent();
+    init_templates();
     init_agent_document_merge();
     init_agent_fields();
     init_source();
@@ -60492,7 +60774,7 @@ function hasBuiltInDefaultAgentDocument(files) {
   return files.some((file2) => {
     try {
       return readDocumentsFromSource(file2).some(
-        (document) => isRecord3(document) && document.name === BUILT_IN_DEFAULT_AGENT_NAME
+        (document) => isRecord4(document) && document.name === BUILT_IN_DEFAULT_AGENT_NAME
       );
     } catch {
       return false;
@@ -60503,7 +60785,7 @@ function templateImportsInFile(file2) {
   try {
     const specifiers = [];
     for (const document of readDocumentsFromSource(file2)) {
-      if (!isRecord3(document)) {
+      if (!isRecord4(document)) {
         continue;
       }
       for (const importPath of importPaths2(document)) {
@@ -60752,6 +61034,7 @@ function assertValidFragmentSourceFiles(files, resourceRoot, fileIndex) {
       validateAgentFragmentDocument(documents[0], file2.path, {
         fileIndex,
         stack: [],
+        templateVariableKinds: /* @__PURE__ */ new Map(),
         variables: /* @__PURE__ */ new Map()
       });
     } catch (error51) {
@@ -69444,7 +69727,7 @@ var AgentFacingAutoMcpShim = class {
   }
 };
 function agentFacingDryRunTool(tool) {
-  if (!isRecord(tool) || tool.name !== DRY_RUN_TOOL_NAME) {
+  if (!isRecord2(tool) || tool.name !== DRY_RUN_TOOL_NAME) {
     return tool;
   }
   if (typeof tool.description !== "string" || !tool.description.includes(AUTO_RESOURCES_DRY_RUN_PATHS_PROTOCOL_MARKER)) {
@@ -69473,7 +69756,7 @@ function agentFacingDryRunTool(tool) {
   };
 }
 function resolveAgentFacingDryRun(input) {
-  if (!isRecord(input.arguments)) {
+  if (!isRecord2(input.arguments)) {
     throw new Error(`Dry-run arguments must be an object. ${correctedCall}`);
   }
   const argumentsValue = input.arguments;
@@ -69633,7 +69916,7 @@ function localImportPaths(content, importerPath) {
   const imports = [];
   for (const document of parseAllDocuments2(content)) {
     const value = document.toJS();
-    if (!isRecord(value) || !Array.isArray(value.imports)) {
+    if (!isRecord2(value) || !Array.isArray(value.imports)) {
       continue;
     }
     for (const importPath of value.imports) {
@@ -69784,8 +70067,8 @@ async function startAutoMcpProxy(input) {
   return { server, url: `http://127.0.0.1:${address.port}/mcp` };
 }
 function prepareDryRunToolCall(input) {
-  const params = isRecord(input.message.params) ? input.message.params : {};
-  const argumentsValue = isRecord(params.arguments) ? params.arguments : {};
+  const params = isRecord2(input.message.params) ? input.message.params : {};
+  const argumentsValue = isRecord2(params.arguments) ? params.arguments : {};
   const hasLegacyDialect = ["files", "resources"].some(
     (key) => Object.hasOwn(argumentsValue, key)
   );
@@ -69830,7 +70113,7 @@ function transformToolsListResponse(body) {
   const parsed = JSON.parse(body);
   let compatible = false;
   const transformed = transformJsonRpcMessages(parsed, (message) => {
-    if (!isRecord(message.result) || !Array.isArray(message.result.tools)) {
+    if (!isRecord2(message.result) || !Array.isArray(message.result.tools)) {
       return message;
     }
     const tools = message.result.tools.map((tool) => {
@@ -69847,16 +70130,16 @@ function transformToolsListResponse(body) {
 function transformJsonRpcMessages(value, transform2) {
   if (Array.isArray(value)) {
     return value.map(
-      (message) => isRecord(message) ? transform2(message) : message
+      (message) => isRecord2(message) ? transform2(message) : message
     );
   }
-  return isRecord(value) ? transform2(value) : value;
+  return isRecord2(value) ? transform2(value) : value;
 }
 function isToolsListRequest(value) {
-  return isRecord(value) && value.method === "tools/list";
+  return isRecord2(value) && value.method === "tools/list";
 }
 function isDryRunToolCall(value) {
-  if (!isRecord(value) || value.method !== "tools/call" || !isRecord(value.params)) {
+  if (!isRecord2(value) || value.method !== "tools/call" || !isRecord2(value.params)) {
     return false;
   }
   return value.params.name === DRY_RUN_TOOL_NAME;
@@ -69921,7 +70204,7 @@ function writeResponse(response, status, headers, body) {
   }
   response.end(body);
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
@@ -80449,7 +80732,7 @@ async function selectRepository(context, github, explicitRepo) {
   const selection = github.grant.providerResourceSelection;
   if (selection.kind === "selected") {
     const repos = selection.resources.map(
-      (resource) => isRecord4(resource) && typeof resource.fullName === "string" ? resource.fullName : void 0
+      (resource) => isRecord5(resource) && typeof resource.fullName === "string" ? resource.fullName : void 0
     ).filter(isDefined);
     if (repos.length === 1) {
       context.writeOutput(`Using GitHub repository ${repos[0]}.`);
@@ -80779,7 +81062,7 @@ function slackWorkspaceUrl(slack) {
 function organizationLabel(organization) {
   return `${organization.organizationName} (${organization.organizationSlug})`;
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isDefined(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autohq/cli",
-  "version": "0.1.477",
+  "version": "0.1.479",
   "license": "SEE LICENSE IN README.md",
   "publishConfig": {
     "access": "public"