feat: reusable label-gated PR review loop (review / security / tests)

.github/actions/muse-prompts/action.yml

@@ -0,0 +1,29 @@
+# Ships the Muse review agents' prompt templates to the runner.
+#
+# The templates are the markdown files in ./prompts — contract.md (the shared
+# JSON output contract) plus one lens file per agent (review.md, security.md,
+# tests.md). Edit those files to tune the reviewers; {{AGENT}}, {{PREFIX}},
+# {{ROUND}}, and {{MAX_FINDINGS}} are substituted at runtime by the workflow.
+#
+# Why an action at all: reusable workflows never check out their own repo, so
+# files next to the YAML don't exist on the runner. Referencing this composite
+# action remotely is what downloads the platform-tools tarball; action_path
+# then points at this directory.
+
+name: "Muse review prompts"
+description: "Exposes the Muse review prompt templates directory to the calling job"
+
+outputs:
+  dir:
+    description: "Absolute path to the prompt templates directory"
+    value: ${{ steps.locate.outputs.dir }}
+
+runs:
+  using: composite
+  steps:
+    - name: Locate prompt templates
+      id: locate
+      shell: bash
+      env:
+        ACTION_PATH: ${{ github.action_path }}
+      run: echo "dir=${ACTION_PATH}/prompts" >> "$GITHUB_OUTPUT"

.github/actions/muse-prompts/prompts/contract.md

@@ -0,0 +1,32 @@
+You are the "{{AGENT}}" reviewer in an automated three-agent pull
+request review. Review ONLY this pull request's changes (diff plus
+its immediate context). Cite file paths and line numbers as they
+appear in the diff. This is round {{ROUND}}.
+
+Output a single raw JSON object — no markdown fences, no prose:
+{
+  "verdict": "pass" | "warn" | "fail",
+  "summary": "2-4 plain-language sentences",
+  "findings": [
+    {"id": "{{PREFIX}}-{{ROUND}}-1", "severity": "critical|high|medium|low|nit",
+     "file": "path/to/file", "line": 123, "title": "short title",
+     "detail": "why this matters", "suggestion": "concrete fix"}
+  ],
+  "resolved": [
+    {"id": "<id of a PREVIOUS finding>", "status": "resolved" | "unresolved",
+     "note": "one line of evidence"}
+  ]
+}
+
+Rules:
+- "findings" holds NEW issues only, at most {{MAX_FINDINGS}}, ordered by
+  severity, ids numbered {{PREFIX}}-{{ROUND}}-1, {{PREFIX}}-{{ROUND}}-2, …
+  Merge duplicates. No praise, no restating the diff, no formatting
+  nits (formatters handle style). An empty array is a fine answer.
+- If PREVIOUS FINDINGS are provided below: verify EVERY one against
+  the current code and list each in "resolved" with status
+  resolved/unresolved plus evidence. Do NOT repeat unresolved ones in
+  "findings" — they are carried forward automatically. Focus new
+  review effort on the CHANGES SINCE LAST REVIEW section.
+- "verdict": "fail" if any critical/high finding stands (new or
+  unresolved), "warn" if only medium/low, "pass" when clean or nits.

.github/actions/muse-prompts/prompts/review.md

@@ -0,0 +1,8 @@
+Your lens: GENERAL CODE REVIEW.
+Hunt for: logic errors and unhandled edge cases; error-handling gaps
+(swallowed errors, unwraps/panics on fallible paths); concurrency and
+race hazards; API misuse; breaking changes to public contracts;
+duplicated code that should reuse an existing helper; violations of
+the project guidelines included below.
+Ignore: formatting/style, naming taste, and hypothetical refactors
+with no concrete defect.

.github/actions/muse-prompts/prompts/security.md

@@ -0,0 +1,10 @@
+Your lens: SECURITY.
+Hunt for: injection (command, SQL, path traversal); secrets or tokens
+hardcoded, logged, or written to disk; unsafe deserialization of
+untrusted input; missing validation at trust boundaries (IPC,
+network, filesystem, subprocess arguments); sandbox / entitlement /
+permission expansions; SSRF or unvalidated URLs; crypto misuse;
+dependency changes that expand the attack surface; PII or sensitive
+data exposed in logs and error messages.
+Severity discipline: reachable-by-untrusted-input = critical/high;
+defense-in-depth hardening = medium/low.

.github/actions/muse-prompts/prompts/tests.md

@@ -0,0 +1,11 @@
+Your lens: TEST COVERAGE (of this diff, not the whole repository).
+Method: (1) enumerate the behavior changes in this diff — new
+features, changed logic, bug fixes; (2) map each to test changes in
+the diff or clearly-referenced existing tests; (3) report each gap
+as a finding naming the exact behavior plus a CONCRETE test to add:
+suggested test name, scenario, expected result.
+Severity: bug fix without a regression test = high; new core
+behavior untested = high/medium; error paths, migrations, and
+boundary conditions untested = medium; nice-to-have cases = low.
+Non-behavioral changes (docs, CI, pure refactors with existing
+coverage) need no tests — say so and pass.

.github/workflows/reusable-changelog.yml

@@ -1,34 +1,9 @@
-# Reusable workflow: Generate changelog entries using Jules AI
+# Reusable workflow: changelog entries from commits via Jules — single-file
+# Keep-a-Changelog mode by default, or a user-facing/internal split when
+# `internal-changelog-path` is set.
 #
-# Usage in a consuming repo:
-#
-# ```yaml
-# name: Update Changelog
-# on:
-#   workflow_dispatch:
-#   schedule:
-#     - cron: "0 0 * * 1"  # every Monday
-#
-# jobs:
-#   changelog:
-#     permissions:
-#       contents: write
-#     uses: <owner>/<repo>/.github/workflows/reusable-changelog.yml@main
-#     with:
-#       changelog-path: CHANGELOG.md                    # optional
-#       internal-changelog-path: CHANGELOG_INTERNAL.md  # optional — enables the split
-#       pr-branch-prefix: "chore/changelog-"            # optional
-#       runs-on: warp-ubuntu-latest-x64-4x              # optional
-#     secrets: inherit
-# ```
-#
-# Split mode (internal-changelog-path set):
-#   One Jules call classifies every commit into USER-FACING (what a user of the
-#   app can perceive — ships verbatim as release notes / updater notes /
-#   TestFlight "What to Test") vs INTERNAL (refactors, CI, deps, plumbing —
-#   recorded but never shown to users), and both files are patched under their
-#   `## [Unreleased]` headings in a single PR. With the input unset the
-#   workflow behaves exactly as before: one file, one markdown blob.
+# Docs — usage snippet, split-mode classification rules, inputs:
+# docs/muse-workflows.md
 
 name: Reusable Changelog
 

.github/workflows/reusable-pr-description.yml

@@ -1,35 +1,9 @@
-# Reusable workflow: Generate PR title and description using Jules AI
+# Reusable workflow: PR title + description via Jules, with a deterministic
+# Linear section (extraction/verbs/markers are the workflow's job, never the
+# LLM's).
 #
-# Usage in a consuming repo:
-#
-# ```yaml
-# name: Update PR Description
-# on:
-#   pull_request:
-#     types: [opened, edited]
-#
-# jobs:
-#   update-pr:
-#     permissions:
-#       contents: read
-#       pull-requests: write
-#     uses: <owner>/<repo>/.github/workflows/reusable-pr-description.yml@main
-#     with:
-#       trigger-phrase: "@agent pr-title"   # optional
-#       runs-on: warp-ubuntu-latest-x64-4x  # optional (defaults to ubuntu-latest)
-#     secrets: inherit
-# ```
-#
-# Linear integration:
-#   A deterministic pre-step extracts Linear issue IDs from the branch name,
-#   commit messages, and the current PR body. The LLM only picks the verb
-#   (Closes/Fixes/Resolves/Completes vs Part of/Refs) per already-extracted ID;
-#   the workflow renders the final `## Linear` section itself, so IDs can never
-#   be hallucinated or silently dropped. When a LINEAR_API_KEY secret is
-#   available, IDs are enriched with issue titles (cosmetic, non-fatal) and
-#   definitive not-founds are pruned. Linear's GitHub integration reads the
-#   magic words in the PR body: closing verbs move the issue when the PR
-#   merges; linking verbs only relate it.
+# Docs — usage snippet, trigger-phrase gating, Linear mechanics, inputs:
+# docs/muse-workflows.md
 
 name: Reusable PR Description