crewscore 0.2.2__tar.gz → 0.2.4__tar.gz

crewscore-0.2.4/.github/workflows/crewscore-selftest.yml

@@ -0,0 +1,106 @@
+# Self-test for the composite CrewScore action in this repo.
+# Installs from github.action_path so it works before PyPI publish.
+name: CrewScore Self-Test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  selftest:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Score sample prompt (smoke, threshold 0)
+        id: score
+        uses: ./
+        with:
+          prompt-file: examples/sample-prompt.md
+          threshold: "0"
+
+      - name: Assert score and tier outputs parse
+        run: |
+          echo "score=${{ steps.score.outputs.score }}"
+          echo "tier=${{ steps.score.outputs.tier }}"
+          python -c "
+          import sys
+          score = int(sys.argv[1])
+          tier = sys.argv[2]
+          assert 0 <= score <= 100, score
+          assert tier, 'tier output empty'
+          print(f'OK score={score} tier={tier!r}')
+          " "${{ steps.score.outputs.score }}" "${{ steps.score.outputs.tier }}"
+
+      - name: Threshold gate fails when score is below threshold
+        run: |
+          set +e
+          crewscore test --prompt-file examples/sample-prompt.md --json --threshold 50
+          EXIT=$?
+          set -e
+          if [ "$EXIT" -ne 2 ]; then
+            echo "Expected exit code 2 for bare sample prompt under threshold 50, got $EXIT"
+            exit 1
+          fi
+          echo "Threshold failure behaved as expected (exit 2)"
+
+      - name: Open rules catalog is non-empty
+        run: |
+          crewscore rules --json > /tmp/rules.json
+          python -c "
+          import json
+          data = json.load(open('/tmp/rules.json'))
+          assert data['rule_count'] > 0
+          assert data['method']['llm_calls'] is False
+          assert 'structural_analysis' in data['method']['source_of_truth']
+          print('OK rules', data['rule_count'], data['ruleset'])
+          "
+
+      - name: Repo scan discovers AGENTS.md (threshold 0)
+        id: scan
+        uses: ./
+        with:
+          scan-path: "."
+          threshold: "0"
+
+      - name: Assert scan outputs
+        run: |
+          echo "scan_score=${{ steps.scan.outputs.score }}"
+          echo "scan_tier=${{ steps.scan.outputs.tier }}"
+          python -c "
+          import sys
+          score = int(sys.argv[1])
+          assert 0 <= score <= 100, score
+          print('OK scan score', score)
+          " "${{ steps.scan.outputs.score }}"
+
+      - name: Markdown summary writer
+        run: |
+          crewscore test --prompt-file examples/sample-prompt.md --summary /tmp/cs-summary.md --no-explain
+          test -s /tmp/cs-summary.md
+          grep -q 'crewscore-hygiene@' /tmp/cs-summary.md
+          grep -q 'rules' /tmp/cs-summary.md
+          echo "OK summary markdown"
+
+      - name: Scan summary + corpus gradient
+        run: |
+          crewscore scan examples/corpus --summary /tmp/cs-scan.md --json > /tmp/cs-scan.json
+          test -s /tmp/cs-scan.md
+          grep -q 'Worst score' /tmp/cs-scan.md || grep -q 'Path' /tmp/cs-scan.md
+          python -c "
+          import json
+          from pathlib import PurePosixPath, PureWindowsPath
+          rows = json.load(open('/tmp/cs-scan.json'))
+          by = {}
+          for r in rows:
+              p = r['path'].replace('\\\\', '/')
+              by[PurePosixPath(p).name] = int(r['overall'])
+          assert by['01-bare-assistant.md'] == 0
+          assert by['05-hardened-ops.md'] >= 70
+          assert by['05-hardened-ops.md'] > by['04-partial-hygiene.md']
+          print('OK corpus', by)
+          "

{crewscore-0.2.2 → crewscore-0.2.4}/.github/workflows/example-ci.yml

@@ -27,12 +27,14 @@ jobs:
         uses: actions/checkout@v4
 
       # Published action (recommended for consumer repos):
+      # permissions: { contents: read, pull-requests: write }  # for sticky PR comments
       # - name: CrewScore
       #   uses: shmindmaster/crewscore@v1
       #   with:
       #     prompt-file: agents/system-prompt.md
       #     threshold: "50"
       #     # explain: "true"
+      #     # pr-comment: "true"   # default on pull_request
 
       # Repo-wide structural scan (preferred when you have multiple agent files):
       # - name: CrewScore scan
@@ -49,6 +51,7 @@ jobs:
         with:
           prompt-file: examples/sample-prompt.md
           threshold: "50"
+          pr-comment: "false"
 
       # Local scan example (uncomment when `crewscore scan` is available):
       # - name: CrewScore scan

{crewscore-0.2.2 → crewscore-0.2.4}/AGENTS.md

@@ -53,8 +53,9 @@ Legacy CLI entry point `agent-guard` still maps to the same `crewscore.cli:main`
 
 ```
 crewscore/
-  cli.py                 # click entry (test, fix, scan)
+  cli.py                 # click entry (test, fix, scan, rules, export-eval)
   scoring.py             # shared result model / tiers
+  summary.py             # PR/job markdown (transparent)
   vendor_scorecard.py    # assess-vendor command
   web_export.py          # builds score-engine.js payload
   report.py              # HTML report + SVG badge
@@ -62,9 +63,11 @@ crewscore/
     structural_analysis.py
     fix_patterns.py
 scripts/export_web_engine.py
+scripts/score_corpus.py  # examples/corpus leaderboard
+examples/corpus/         # synthetic bare→hardened demo fixtures
 score-engine.js          # generated — commit after pattern changes
 index.html               # builder-first site (uses score-engine.js)
-action.yml               # composite GH Action (prompt-file or scan-path)
+action.yml               # composite GH Action (scan/test + sticky PR comment)
 docs/launch/             # launch copy kit
 docs/next-steps-eval.md  # Promptfoo / garak handoff
 tests/

{crewscore-0.2.2 → crewscore-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crewscore
-Version: 0.2.2
+Version: 0.2.4
 Summary: CrewScore — offline structural production-readiness scorecard for AI agent system prompts.
 Project-URL: Homepage, https://crewscore.ai
 Project-URL: Repository, https://github.com/shmindmaster/crewscore
@@ -97,7 +97,7 @@ Scores reflect **prompt-text signals**. They are a useful smoke test, not a guar
 Honest principles we ship by:
 
 1. CrewScore measures **presence of hygiene signals in text**, not agent behavior.
-2. Scores are **rule-pack versioned** (`crewscore-hygiene@0.2.2`) and **deterministic** — no LLM, no hidden model.
+2. Scores are **rule-pack versioned** (`crewscore-hygiene@0.2.3`) and **deterministic** — no LLM, no hidden model.
 3. **Every rule is public.** List them anytime:
    ```bash
    crewscore rules              # human: formula + every rule_id + regex
@@ -137,12 +137,19 @@ crewscore scan .
 crewscore scan ./agents --json
 crewscore scan . --threshold 50
 crewscore scan . --json --threshold 50
+crewscore scan . --summary crewscore-summary.md
+crewscore test --prompt-file ./AGENTS.md --summary crewscore-summary.md
+
+# Synthetic demo gradient (bare → hardened)
+crewscore scan examples/corpus
 ```
 
 - Prints a table of path → overall → tier (JSON with `--json`).
 - `--threshold N` exits `2` if **any** file scores below `N`.
+- `--summary PATH` writes transparent PR/job markdown (formula + open rule IDs for single-file; table for scan).
 - Exit `1` if no candidate files are found.
 - Skips `node_modules`, `.git`, `venv`, `dist`, `__pycache__`, `.venv`.
+- Demo fixtures: [examples/corpus/](examples/corpus/) + [LEADERBOARD.md](examples/corpus/LEADERBOARD.md).
 
 Use this as the default CI gate for monorepos with multiple agent artifacts.
 
@@ -264,6 +271,9 @@ on: [pull_request]
 jobs:
   score:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write   # sticky PR comment with open rule findings
     steps:
       - uses: actions/checkout@v4
       - name: CrewScore
@@ -275,6 +285,8 @@ jobs:
           prompt-file: ./agents/system-prompt.md
           threshold: "50"
           # explain: "true"   # optional: matched vs missing signals
+          # pr-comment: "true"  # default: sticky PR comment on pull_request
+          # summary: crewscore-summary.md
       - name: Report
         if: always()
         run: |
@@ -290,10 +302,14 @@ jobs:
 | `scan-path` | one of | — | Path for `crewscore scan` (worst score becomes the output) |
 | `threshold` | no | `50` | Fail the step (exit 2) when overall score is below this |
 | `explain` | no | `false` | Pass `true` to include matched/missing signals |
+| `summary` | no | `crewscore-summary.md` | Markdown path (also appends to `GITHUB_STEP_SUMMARY`) |
+| `pr-comment` | no | `true` | On `pull_request`, post/update a sticky comment with the summary |
 
 Provide **either** `prompt-file` **or** `scan-path` (not neither). For scan mode, outputs use the **minimum** overall across discovered files.
 
-**Outputs:** `score` (0–100), `tier` (label string).
+**Outputs:** `score` (0–100), `tier` (label string), `summary-path` (markdown file if written).
+
+Sticky PR comments need `permissions: pull-requests: write` on the job. Set `pr-comment: "false"` to disable.
 
 The composite action installs CrewScore from the action path (`pip install "${{ github.action_path }}"`), so monorepo / pre-PyPI self-tests work with `uses: ./`.
 
@@ -341,6 +357,13 @@ CrewScore is the cheap lint / structural pre-gate. When you need **live** behavi
 
 Structural scores do **not** measure jailbreak resistance or multi-turn tool abuse. Use those tools after the prompt text has basic hygiene. Details: [docs/next-steps-eval.md](docs/next-steps-eval.md).
 
+Generate starter stubs (does **not** run live evals):
+
+```bash
+crewscore export-eval --prompt-file ./agents/system-prompt.md -o ./crewscore-eval
+# → promptfooconfig.yaml + README-EVAL.md (Promptfoo + garak notes)
+```
+
 ---
 
 ## Fix patterns

{crewscore-0.2.2 → crewscore-0.2.4}/README.md

@@ -70,7 +70,7 @@ Scores reflect **prompt-text signals**. They are a useful smoke test, not a guar
 Honest principles we ship by:
 
 1. CrewScore measures **presence of hygiene signals in text**, not agent behavior.
-2. Scores are **rule-pack versioned** (`crewscore-hygiene@0.2.2`) and **deterministic** — no LLM, no hidden model.
+2. Scores are **rule-pack versioned** (`crewscore-hygiene@0.2.3`) and **deterministic** — no LLM, no hidden model.
 3. **Every rule is public.** List them anytime:
    ```bash
    crewscore rules              # human: formula + every rule_id + regex
@@ -110,12 +110,19 @@ crewscore scan .
 crewscore scan ./agents --json
 crewscore scan . --threshold 50
 crewscore scan . --json --threshold 50
+crewscore scan . --summary crewscore-summary.md
+crewscore test --prompt-file ./AGENTS.md --summary crewscore-summary.md
+
+# Synthetic demo gradient (bare → hardened)
+crewscore scan examples/corpus
 ```
 
 - Prints a table of path → overall → tier (JSON with `--json`).
 - `--threshold N` exits `2` if **any** file scores below `N`.
+- `--summary PATH` writes transparent PR/job markdown (formula + open rule IDs for single-file; table for scan).
 - Exit `1` if no candidate files are found.
 - Skips `node_modules`, `.git`, `venv`, `dist`, `__pycache__`, `.venv`.
+- Demo fixtures: [examples/corpus/](examples/corpus/) + [LEADERBOARD.md](examples/corpus/LEADERBOARD.md).
 
 Use this as the default CI gate for monorepos with multiple agent artifacts.
 
@@ -237,6 +244,9 @@ on: [pull_request]
 jobs:
   score:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write   # sticky PR comment with open rule findings
     steps:
       - uses: actions/checkout@v4
       - name: CrewScore
@@ -248,6 +258,8 @@ jobs:
           prompt-file: ./agents/system-prompt.md
           threshold: "50"
           # explain: "true"   # optional: matched vs missing signals
+          # pr-comment: "true"  # default: sticky PR comment on pull_request
+          # summary: crewscore-summary.md
       - name: Report
         if: always()
         run: |
@@ -263,10 +275,14 @@ jobs:
 | `scan-path` | one of | — | Path for `crewscore scan` (worst score becomes the output) |
 | `threshold` | no | `50` | Fail the step (exit 2) when overall score is below this |
 | `explain` | no | `false` | Pass `true` to include matched/missing signals |
+| `summary` | no | `crewscore-summary.md` | Markdown path (also appends to `GITHUB_STEP_SUMMARY`) |
+| `pr-comment` | no | `true` | On `pull_request`, post/update a sticky comment with the summary |
 
 Provide **either** `prompt-file` **or** `scan-path` (not neither). For scan mode, outputs use the **minimum** overall across discovered files.
 
-**Outputs:** `score` (0–100), `tier` (label string).
+**Outputs:** `score` (0–100), `tier` (label string), `summary-path` (markdown file if written).
+
+Sticky PR comments need `permissions: pull-requests: write` on the job. Set `pr-comment: "false"` to disable.
 
 The composite action installs CrewScore from the action path (`pip install "${{ github.action_path }}"`), so monorepo / pre-PyPI self-tests work with `uses: ./`.
 
@@ -314,6 +330,13 @@ CrewScore is the cheap lint / structural pre-gate. When you need **live** behavi
 
 Structural scores do **not** measure jailbreak resistance or multi-turn tool abuse. Use those tools after the prompt text has basic hygiene. Details: [docs/next-steps-eval.md](docs/next-steps-eval.md).
 
+Generate starter stubs (does **not** run live evals):
+
+```bash
+crewscore export-eval --prompt-file ./agents/system-prompt.md -o ./crewscore-eval
+# → promptfooconfig.yaml + README-EVAL.md (Promptfoo + garak notes)
+```
+
 ---
 
 ## Fix patterns

crewscore-0.2.4/action.yml

@@ -0,0 +1,186 @@
+name: CrewScore
+description: Structural production-readiness scorecard for AI agent system prompts
+author: shmindmaster
+branding:
+  icon: shield
+  color: blue
+
+inputs:
+  prompt-file:
+    description: Path to a single system prompt file to score (required if scan-path is empty)
+    required: false
+    default: ""
+  scan-path:
+    description: Directory/path to scan for agent instruction files via crewscore scan. When set, scores all discovered files and reports the worst (minimum) overall.
+    required: false
+    default: ""
+  threshold:
+    description: Exit non-zero (code 2) if overall score is below this value (0-100)
+    required: false
+    default: "50"
+  explain:
+    description: Include matched vs missing guardrail signals (pass "true" to enable)
+    required: false
+    default: "false"
+  summary:
+    description: Write transparent markdown summary to this path (also appends to GITHUB_STEP_SUMMARY when set)
+    required: false
+    default: "crewscore-summary.md"
+  pr-comment:
+    description: On pull_request events, post or update a sticky PR comment with the summary (requires pull-requests: write)
+    required: false
+    default: "true"
+
+outputs:
+  score:
+    description: Overall structural score (0-100); for scan mode, the worst (minimum) overall across files
+    value: ${{ steps.run.outputs.score }}
+  tier:
+    description: Score tier label
+    value: ${{ steps.run.outputs.tier }}
+  summary-path:
+    description: Path to the markdown summary file (if written)
+    value: ${{ steps.run.outputs.summary-path }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install CrewScore from action path
+      shell: bash
+      run: pip install "${{ github.action_path }}"
+
+    - name: Run CrewScore
+      id: run
+      shell: bash
+      run: |
+        set -euo pipefail
+        PROMPT_FILE="${{ inputs.prompt-file }}"
+        SCAN_PATH="${{ inputs.scan-path }}"
+        THRESHOLD="${{ inputs.threshold }}"
+        EXPLAIN="${{ inputs.explain }}"
+        SUMMARY="${{ inputs.summary }}"
+
+        if [ -z "$SCAN_PATH" ] && [ -z "$PROMPT_FILE" ]; then
+          echo "Either prompt-file or scan-path is required" >&2
+          exit 1
+        fi
+
+        set +e
+        if [ -n "$SCAN_PATH" ]; then
+          ARGS=(scan "$SCAN_PATH" --json --threshold "$THRESHOLD")
+          if [ "$EXPLAIN" = "true" ]; then
+            ARGS+=(--explain)
+          fi
+          if [ -n "$SUMMARY" ]; then
+            ARGS+=(--summary "$SUMMARY")
+          fi
+          OUTPUT=$(crewscore "${ARGS[@]}")
+          EXIT=$?
+        else
+          ARGS=(test --prompt-file "$PROMPT_FILE" --json --threshold "$THRESHOLD")
+          if [ "$EXPLAIN" = "true" ]; then
+            ARGS+=(--explain)
+          fi
+          if [ -n "$SUMMARY" ]; then
+            ARGS+=(--summary "$SUMMARY")
+          fi
+          OUTPUT=$(crewscore "${ARGS[@]}")
+          EXIT=$?
+        fi
+        set -e
+        echo "$OUTPUT"
+        if [ -n "$SUMMARY" ] && [ -f "$SUMMARY" ]; then
+          echo "Wrote summary markdown: $SUMMARY"
+          echo "summary-path=$SUMMARY" >> "$GITHUB_OUTPUT"
+        else
+          echo "summary-path=" >> "$GITHUB_OUTPUT"
+        fi
+        # Single-file test JSON: {overall, tier, ...}
+        # scan --json: list of {path, overall, tier, ...} — take min overall (worst).
+        echo "$OUTPUT" | python -c "
+        import json, os, sys
+        data = json.load(sys.stdin)
+        if isinstance(data, list):
+            worst = min(data, key=lambda x: int(x['overall']))
+            score, tier = worst['overall'], worst['tier']
+        else:
+            items = data.get('files') or data.get('results')
+            if items:
+                worst = min(items, key=lambda x: int(x['overall']))
+                score, tier = worst['overall'], worst['tier']
+            else:
+                score, tier = data['overall'], data['tier']
+        with open(os.environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as f:
+            f.write(f'score={score}\n')
+            f.write(f'tier={tier}\n')
+        "
+        exit "$EXIT"
+
+    - name: Sticky PR comment
+      if: ${{ always() && inputs.pr-comment == 'true' && github.event_name == 'pull_request' && steps.run.outputs.summary-path != '' }}
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+        SUMMARY_PATH: ${{ steps.run.outputs.summary-path }}
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+        REPO: ${{ github.repository }}
+      run: |
+        set -euo pipefail
+        if [ ! -f "$SUMMARY_PATH" ]; then
+          echo "No summary file at $SUMMARY_PATH; skip PR comment"
+          exit 0
+        fi
+        if [ -z "${PR_NUMBER:-}" ]; then
+          echo "No PR number; skip PR comment"
+          exit 0
+        fi
+        MARKER="<!-- crewscore-sticky -->"
+        BODY_FILE=$(mktemp)
+        {
+          printf '%s\n\n' "$MARKER"
+          cat "$SUMMARY_PATH"
+        } > "$BODY_FILE"
+        # Find existing sticky comment by marker (gh --paginate yields JSON array).
+        COMMENT_ID=$(
+          gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" --paginate \
+          | MARKER="$MARKER" python -c "
+        import json, os, sys
+        marker = os.environ['MARKER']
+        raw = sys.stdin.read().strip()
+        comments = []
+        if raw:
+            try:
+                data = json.loads(raw)
+                comments = data if isinstance(data, list) else []
+            except json.JSONDecodeError:
+                # Multiple pages can appear as ][ between arrays.
+                fixed = raw.replace('][', ',')
+                data = json.loads(fixed)
+                comments = data if isinstance(data, list) else []
+        for c in comments:
+            if marker in (c.get('body') or ''):
+                print(c['id'])
+                break
+        "
+        )
+        # Prefer raw JSON input for reliable multiline body.
+        python -c "
+        import json, pathlib, sys
+        body = pathlib.Path(sys.argv[1]).read_text(encoding='utf-8')
+        print(json.dumps({'body': body}))
+        " "$BODY_FILE" > "${BODY_FILE}.json"
+        if [ -n "${COMMENT_ID:-}" ]; then
+          gh api --method PATCH "repos/${REPO}/issues/comments/${COMMENT_ID}" \
+            --input "${BODY_FILE}.json"
+          echo "Updated sticky PR comment id=$COMMENT_ID"
+        else
+          gh api --method POST "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+            --input "${BODY_FILE}.json"
+          echo "Created sticky PR comment"
+        fi
+        rm -f "$BODY_FILE" "${BODY_FILE}.json"

{crewscore-0.2.2 → crewscore-0.2.4}/crewscore/__init__.py

@@ -1,3 +1,3 @@
 """CrewScore — offline structural production-readiness scorecard for AI agent prompts."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"

{crewscore-0.2.2 → crewscore-0.2.4}/crewscore/cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import os
 import sys
 from pathlib import Path
 
@@ -11,11 +12,13 @@ from rich.console import Console
 from rich.panel import Panel
 
 from crewscore import __version__
+from crewscore.export_eval import write_eval_stubs
 from crewscore.report import render_badge_svg, render_html_report, share_text
 from crewscore.rules_catalog import SCORING_METHOD, catalog_payload, scoring_transparency_block
 from crewscore.scan import discover_prompt_files, score_paths
 from crewscore.scoring import DIMENSIONS, RULESET_ID, build_result, tier_color
 from crewscore.scorers import structural_analysis
+from crewscore.summary import format_scan_markdown, format_score_markdown
 from crewscore.vendor_scorecard import assess_vendor
 
 console = Console()
@@ -94,7 +97,13 @@ main.add_command(assess_vendor)
     default=None,
     help="Write an SVG badge to this path",
 )
-def test(prompt, prompt_file, as_json, threshold, explain, report, badge):
+@click.option(
+    "--summary",
+    type=click.Path(),
+    default=None,
+    help="Write GitHub-flavored markdown summary (PR/step comment body) to this path",
+)
+def test(prompt, prompt_file, as_json, threshold, explain, report, badge, summary):
     """Run structural production-readiness analysis on an agent system prompt.
 
     Offline, deterministic regex scan — not live red-teaming.
@@ -137,6 +146,17 @@ def test(prompt, prompt_file, as_json, threshold, explain, report, badge):
         badge_path.parent.mkdir(parents=True, exist_ok=True)
         badge_path.write_text(render_badge_svg(result), encoding="utf-8")
 
+    md_body = format_score_markdown(result, findings=findings)
+    if summary:
+        summary_path = Path(summary)
+        summary_path.parent.mkdir(parents=True, exist_ok=True)
+        summary_path.write_text(md_body, encoding="utf-8")
+    # Always append to GitHub Actions job summary when running in GHA.
+    if os.environ.get("GITHUB_STEP_SUMMARY"):
+        with Path(os.environ["GITHUB_STEP_SUMMARY"]).open("a", encoding="utf-8") as fh:
+            fh.write(md_body)
+            fh.write("\n")
+
     if as_json:
         payload = result.to_dict()
         payload["findings"] = findings
@@ -336,6 +356,59 @@ def rules_cmd(as_json: bool, dimension: str | None):
     console.print()
 
 
+@main.command("export-eval")
+@click.option("--prompt", "-p", help="System prompt string to export")
+@click.option(
+    "--prompt-file",
+    "-f",
+    type=click.Path(exists=True),
+    help="Path to system prompt file",
+)
+@click.option(
+    "--output-dir",
+    "-o",
+    type=click.Path(),
+    default="./crewscore-eval",
+    help="Directory for Promptfoo / garak handoff stubs (default: ./crewscore-eval)",
+)
+def export_eval(prompt, prompt_file, output_dir):
+    """Write live-eval stubs (Promptfoo config + garak notes) after structural gate.
+
+    Does not run Promptfoo or garak. Honest handoff only.
+    """
+    if prompt:
+        system_prompt = prompt
+        source = "prompt"
+    elif prompt_file:
+        system_prompt = Path(prompt_file).read_text(encoding="utf-8")
+        source = str(prompt_file)
+    else:
+        err_console.print("[red]Error: Provide --prompt or --prompt-file[/red]")
+        sys.exit(1)
+
+    paths = write_eval_stubs(
+        Path(output_dir),
+        system_prompt=system_prompt,
+        prompt_source=source,
+    )
+    console.print()
+    console.print(
+        Panel(
+            "[bold]Live eval handoff stubs[/bold]",
+            border_style="cyan",
+            expand=False,
+        )
+    )
+    console.print()
+    for p in paths:
+        console.print(f"  [green]wrote[/green] {p}")
+    console.print()
+    console.print(
+        "  [dim]CrewScore remains structural only. "
+        "Run Promptfoo/garak yourself — see README-EVAL.md[/dim]"
+    )
+    console.print()
+
 
 @main.command()
 @click.option("--prompt", "-p", help="System prompt string to fix")
@@ -513,7 +586,13 @@ def fix(prompt, prompt_file, apply, output, as_json):
     is_flag=True,
     help="Show matched vs missing signals for the lowest-scoring file",
 )
-def scan(path, as_json, threshold, explain):
+@click.option(
+    "--summary",
+    type=click.Path(),
+    default=None,
+    help="Write GitHub-flavored markdown summary (PR/step comment body) to this path",
+)
+def scan(path, as_json, threshold, explain, summary):
     """Discover and score agent prompt files under PATH (default: .).
 
     Looks for AGENTS.md, CLAUDE.md, system-prompt.md, and files under
@@ -546,6 +625,18 @@ def scan(path, as_json, threshold, explain):
         abs_by_rel[rel] = abs_path
         item["path"] = rel
 
+    md_body = format_scan_markdown(scored)
+    if summary:
+        summary_path = Path(summary)
+        summary_path.parent.mkdir(parents=True, exist_ok=True)
+        summary_path.write_text(md_body, encoding="utf-8")
+    if os.environ.get("GITHUB_STEP_SUMMARY"):
+        with Path(os.environ["GITHUB_STEP_SUMMARY"]).open(
+            "a", encoding="utf-8"
+        ) as fh:
+            fh.write(md_body)
+            fh.write("\n")
+
     if as_json:
         click.echo(json.dumps(scored, indent=2, sort_keys=True))
     else: