@poetic-ai/poetic 1.42.0

package/templates/guard-kit/config.json.template

@@ -0,0 +1,6 @@
+{
+  "baseRef": null,
+  "extraDenyPaths": [],
+  "extraSecretPatterns": [],
+  "extraArtifactPatterns": []
+}

package/templates/guard-kit/poetic-guard.yml.template

@@ -0,0 +1,189 @@
+# Poetic Guard reference workflow (kit version {{KIT_VERSION}}).
+#
+# Emitted by `poetic guard print-ci`. This is NOT installed into your repo
+# automatically: copy it to .github/workflows/poetic-guard.yml, commit it on a
+# branch, land it on your default branch, confirm one green run, and only then
+# require the "Poetic Guard" check in branch protection. The ordered procedure
+# and the criteria this satisfies (C4..C7) live in .poetic/guard/GUARD_SETUP.md.
+#
+# ---------------------------------------------------------------------------
+# MUST NOT CHANGE (security-critical — editing these breaks the guarantee):
+#   * permissions: contents: read (least privilege; do not widen).
+#   * The trusted-base extraction: the gate is run from the BASE branch's copy
+#     of check.mjs, not the PR's copy. A PR could otherwise strip its own
+#     guard-integrity check before it runs. Keep the `git show ... > file`,
+#     the `test -s` non-empty guard, and `set -euo pipefail` exactly as-is.
+#   * fetch-depth: 0 (the gate needs history to find the merge base; a shallow
+#     clone makes it fail closed instead of passing silently).
+#   * Both triggers: pull_request_target AND merge_group. pull_request_target
+#     is what makes GitHub load THIS workflow file from the base/default
+#     branch; `on: pull_request` would load the PR's copy, so a PR could
+#     rewrite the YAML to skip the gate and still publish a green
+#     "Poetic Guard" context. A merge queue re-runs required checks in the
+#     queue; omitting merge_group leaves queued PRs unguarded / stuck.
+#   * Checkout the BASE / default branch (the pull_request_target default).
+#     Do NOT set checkout `ref:` to the PR head — that would make the
+#     workspace the untrusted tree used to run scripts. Fetch the PR head
+#     SHA only as a git object for the gate's diff.
+#   * The pull_request_target `types:` list must keep `edited`. Every check
+#     below is computed against the BASE branch, and the required status is
+#     bound to the head SHA — so retargeting a PR to a different base leaves
+#     the previous base's green result standing for an unexamined range.
+#     `edited` is the only event GitHub fires for a base change (with
+#     changes.base), and the default types (opened, synchronize, reopened)
+#     do not include it. Re-running on `edited` re-reports this context for
+#     the same head SHA against the new base. Title/body edits also fire it;
+#     a redundant re-run is the intended cost.
+#   * The job `name:` is the status-check CONTEXT you require in branch
+#     protection. Keep it a stable literal ("Poetic Guard") — never an
+#     expression, or the required context name changes per run and can never
+#     be satisfied.
+#
+# CUSTOMIZE FREELY (safe to adapt to your project):
+#   * runs-on: swap the runner label for a self-hosted/larger runner.
+#   * timeout-minutes: raise/lower for your repo size.
+#   * ADD paths-filters ONLY with care. Filtering a REQUIRED check means PRs
+#     that touch no matching path never report the check and sit forever
+#     "Expected — Waiting for status". Recommended: do NOT paths-filter this
+#     workflow. If your team wants automerge without the guard blocking on
+#     kit-upgrade PRs (exit 2), use the two-context split documented in
+#     GUARD_SETUP.md instead of a paths-filter.
+# ---------------------------------------------------------------------------
+
+name: Poetic Guard
+
+# All PRs (no branch filter) plus merge-queue runs. Do not add a branches
+# filter unless you deliberately want some PRs unguarded.
+#
+# pull_request_target loads this YAML from the base branch. `edited` is
+# load-bearing, not cosmetic: it is the event a base retarget fires, and
+# without it the head SHA keeps the green this gate published for its former
+# base. The other three are GitHub's defaults, restated because naming `types`
+# at all replaces them.
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited]
+  merge_group:
+
+# Cancel superseded runs: a new push to the same PR obsoletes the in-flight
+# run, and the required status is bound to the new head SHA, so canceling the
+# stale run cannot wedge the current head's check.
+# pull_request_target sets github.ref to the BASE branch, so the group must
+# key on the PR number (not github.ref) or every PR targeting the same base
+# would share one slot and cancel each other.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# Least privilege: the gate only reads the tree and git history.
+# pull_request_target's default token is write-capable — this block is what
+# pins it to read. Do not add pull-requests: write or secrets.
+permissions:
+  contents: read
+
+jobs:
+  poetic-guard:
+    # This literal is the status-check context you require in branch
+    # protection. Keep it stable and expression-free.
+    name: Poetic Guard
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      # SHA-pinned (supply-chain): a mutable tag on a security-critical gate's
+      # own actions would let a retagged action compromise the gate.
+      # pull_request_target default ref is the base/default branch. Do not set
+      # `ref:` to the PR head — the workspace must stay the trusted base tree.
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          # Full history so the gate can compute the merge base. A shallow
+          # clone makes the gate fail closed, not pass silently.
+          fetch-depth: 0
+
+      # check.mjs requires Node >= 24; the runner's ambient node may be older.
+      # Pin the runtime explicitly so the gate never depends on image defaults.
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: '24'
+
+      - name: Run Poetic Guard (trusted base copy)
+        # Fail closed on every error, unset variable, and pipe failure.
+        run: |
+          set -euo pipefail
+
+          # Resolve the base BRANCH name for both event types. Fail closed if
+          # it cannot be determined (a missing base must never empty the diff
+          # and skip every check).
+          if [ "${GITHUB_EVENT_NAME}" = "pull_request_target" ]; then
+            # pull_request_target exposes the base branch directly.
+            BASE_BRANCH="${GITHUB_BASE_REF:?Error: GITHUB_BASE_REF is empty on a pull_request_target event}"
+            PR_SHA="$(jq -r '.pull_request.head.sha // empty' "${GITHUB_EVENT_PATH}")"
+            if [ -z "${PR_SHA}" ]; then
+              echo "Error: could not resolve pull_request.head.sha from the event payload (fail closed)." >&2
+              exit 1
+            fi
+            PR_NUMBER="$(jq -r '.pull_request.number // empty' "${GITHUB_EVENT_PATH}")"
+            if [ -z "${PR_NUMBER}" ]; then
+              echo "Error: could not resolve pull_request.number from the event payload (fail closed)." >&2
+              exit 1
+            fi
+          elif [ "${GITHUB_EVENT_NAME}" = "merge_group" ]; then
+            # merge_group leaves GITHUB_BASE_REF empty; the base branch lives in
+            # the event payload as merge_group.base_ref (a full ref like
+            # refs/heads/main). Strip the refs/heads/ prefix.
+            BASE_REF_FULL="$(jq -r '.merge_group.base_ref // empty' "${GITHUB_EVENT_PATH}")"
+            if [ -z "${BASE_REF_FULL}" ]; then
+              echo "Error: could not resolve merge_group.base_ref from the event payload (fail closed)." >&2
+              exit 1
+            fi
+            BASE_BRANCH="${BASE_REF_FULL#refs/heads/}"
+          else
+            echo "Error: unsupported event '${GITHUB_EVENT_NAME}' for the Poetic Guard gate (fail closed)." >&2
+            exit 1
+          fi
+
+          if [ -z "${BASE_BRANCH}" ]; then
+            echo "Error: base branch resolved empty (fail closed)." >&2
+            exit 1
+          fi
+
+          # Fetch the base branch so origin/<base> is resolvable for the diff.
+          git fetch --no-tags origin "+refs/heads/${BASE_BRANCH}:refs/remotes/origin/${BASE_BRANCH}"
+
+          # pull_request_target workspace is the base tree. Fetch the PR head
+          # SHA as a git object only (GitHub's pull ref, including forks) and
+          # point HEAD at that object so the gate diffs against it. Do not
+          # checkout the PR — that would replace the trusted workspace.
+          if [ "${GITHUB_EVENT_NAME}" = "pull_request_target" ]; then
+            git fetch --no-tags origin "+refs/pull/${PR_NUMBER}/head:refs/poetic/pr-head"
+            FETCHED_SHA="$(git rev-parse --verify "refs/poetic/pr-head^{commit}")"
+            if [ "${FETCHED_SHA}" != "${PR_SHA}" ]; then
+              echo "Error: fetched PR head ${FETCHED_SHA} does not match event sha ${PR_SHA} (fail closed)." >&2
+              exit 1
+            fi
+            git update-ref --no-deref HEAD "${PR_SHA}"
+          fi
+
+          # TRUSTED BASE: run the gate from the BASE branch's committed copy of
+          # check.mjs, never the PR's copy. A PR cannot strip its own
+          # guard-integrity check this way. RUNNER_TEMP (per-job temp dir,
+          # always set on GitHub runners) avoids the predictable shared /tmp
+          # path a concurrent process on a persistent self-hosted runner could
+          # race or pre-create.
+          git show "origin/${BASE_BRANCH}:.poetic/guard/check.mjs" > "${RUNNER_TEMP}/guard-check.mjs"
+
+          # Non-empty guard: an empty file would run as a silent pass under node.
+          test -s "${RUNNER_TEMP}/guard-check.mjs"
+
+          # Point the extracted gate at the trusted workspace guard dir (config,
+          # baselines). The workspace is the BASE checkout, so config is not
+          # PR-controlled. The gate diffs git objects (HEAD = PR sha vs base).
+          # The gate's exit code passes straight through:
+          #   0  clean.
+          #   1  hard finding (secret / artifact path / baseline inflation) -> blocks.
+          #   2  ONLY guard-machinery changed (exit 2) -> also blocks this check.
+          # Exit 2 is expected on legitimate kit-upgrade PRs and means "a human
+          # should review the gate change". Teams that want such PRs to
+          # automerge should split contexts per GUARD_SETUP.md rather than
+          # weaken this required check. Never mask the gate's exit code (no
+          # error suppression, no `|| true`).
+          POETIC_GUARD_DIR="$PWD/.poetic/guard" node "${RUNNER_TEMP}/guard-check.mjs"

package/templates/profiles/README.md

@@ -0,0 +1,56 @@
+# Frontier cast profile templates
+
+Shipped, importable user-profile templates for role-based execution.
+
+| Profile | Orchestrator | Executor | Reviewer |
+| --- | --- | --- | --- |
+| `frontier-codex` | Codex (`frontier`, high effort; no native model fallback) | Grok (`implementation`, 8 subagents) | Codex preferred ahead of Claude, derived (`frontier`, medium effort); gate `advisory` |
+| `frontier-claude` | Claude (`frontier`, fallback `quality`, high effort) | Grok (`implementation`, 8 subagents) | Codex pinned (`frontier`, medium effort); gate `high-severity-blocks` |
+
+These are **deliberate opt-in** personas. Role-based execution stays dormant until an
+operator configures a reviewer gate (for example by activating one of these
+profiles). Copying a template does nothing until the profile is active.
+
+## Install (user-global)
+
+Profiles live under `~/.poetic/config/profiles/` and apply across projects when
+active. CLI flags still win; project/user `roles.*` only fill keys the active
+profile leaves unset.
+
+From an installed package:
+
+```bash
+mkdir -p ~/.poetic/config/profiles
+PKG="$(npm root -g)/@poetic-ai/poetic"
+cp "$PKG/templates/profiles/frontier-codex.json" ~/.poetic/config/profiles/
+# or: frontier-claude.json
+poetic profile use frontier-codex
+poetic config resolved
+```
+
+From a source checkout:
+
+```bash
+mkdir -p ~/.poetic/config/profiles
+cp templates/profiles/frontier-codex.json ~/.poetic/config/profiles/
+poetic profile use frontier-codex
+```
+
+Deactivate by switching profiles (`poetic profile use <other>`) or clearing the
+active profile.
+
+## Design notes
+
+- Dispatchable roles only: `orchestrator`, `executor`, `reviewer`.
+- Semantic registry roles only — no pinned model versions.
+- Model fallback exists only on the orchestrator binding. Executor and reviewer
+  do not have model-fallback fields.
+- Reviewer `provider` is omitted so Poetic derives a reviewer that differs from
+  the **executor** (not from the orchestrator). `providerPreference` orders
+  automatic selection; reviewer may equal the orchestrator provider.
+- Configuring `roles.reviewer.gate` (here `advisory`) engages the
+  execution-policy applier; an unconfigured fallback gate keeps the feature
+  dormant.
+
+See
+[docs/getting-started/EXECUTOR_REVIEWER.md](https://github.com/ebrindley/Poetic/blob/main/docs/getting-started/EXECUTOR_REVIEWER.md).

package/templates/profiles/frontier-claude.json

@@ -0,0 +1,27 @@
+{
+  "$version": 1,
+  "name": "frontier-claude",
+  "createdAt": "2026-07-10T00:00:00.000Z",
+  "updatedAt": "2026-07-10T00:00:00.000Z",
+  "description": "Opt-in frontier cast: Claude frontier orchestrator with quality-model fallback, Grok implementation executor (8 subagents), and Codex frontier reviewer at medium effort. Activating this user-global profile engages strict role-based review.",
+  "roles": {
+    "orchestrator": {
+      "provider": "claude",
+      "modelRole": "frontier",
+      "fallbackModelRole": "quality",
+      "reasoningEffort": "high"
+    },
+    "executor": {
+      "provider": "grok",
+      "modelRole": "implementation",
+      "subagents": 8,
+      "transport": "tmux-exec"
+    },
+    "reviewer": {
+      "provider": "codex",
+      "modelRole": "frontier",
+      "reasoningEffort": "medium",
+      "gate": "high-severity-blocks"
+    }
+  }
+}

package/templates/profiles/frontier-codex.json

@@ -0,0 +1,26 @@
+{
+  "$version": 1,
+  "name": "frontier-codex",
+  "createdAt": "2026-07-10T00:00:00.000Z",
+  "updatedAt": "2026-07-12T00:00:00.000Z",
+  "description": "Opt-in frontier cast: Codex orchestrator, Grok implementation executor (8 subagents), derived frontier reviewer preferring Codex ahead of Claude (reviewer may match orchestrator; must differ from executor). Activating this user-global profile engages role-based execution via a configured reviewer gate.",
+  "roles": {
+    "orchestrator": {
+      "provider": "codex",
+      "modelRole": "frontier",
+      "reasoningEffort": "high"
+    },
+    "executor": {
+      "provider": "grok",
+      "modelRole": "implementation",
+      "subagents": 8,
+      "transport": "tmux-exec"
+    },
+    "reviewer": {
+      "providerPreference": ["codex", "claude"],
+      "modelRole": "frontier",
+      "reasoningEffort": "medium",
+      "gate": "advisory"
+    }
+  }
+}