crewscore 0.1.0__tar.gz

crewscore-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Something broken in CLI, Action, or web scorecard
+title: "[bug] "
+labels: bug
+---
+
+## What happened
+
+## Expected
+
+## Repro
+
+```bash
+crewscore test --prompt "..."
+```
+
+## Environment
+
+- OS:
+- `crewscore --version`:
+- Install method: pip / source

crewscore-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature request
+about: New dimension, fix template, or CI surface
+title: "[feat] "
+labels: enhancement
+---
+
+## Problem
+
+## Proposed solution
+
+## Why not a runtime / adversarial tool instead?
+
+CrewScore stays offline structural by default. Say if this must stay structural.

crewscore-0.1.0/.github/ISSUE_TEMPLATE/scoring_feedback.md

@@ -0,0 +1,37 @@
+---
+name: Scoring false positive/negative
+about: Pattern matched wrong or missed a real guardrail
+title: "[scoring] "
+labels: scoring
+---
+
+> **Check [`docs/validation.md`](../../docs/validation.md) first.** Some of this
+> is already known and disclosed. In particular, `cost`, `compliance`, and
+> `audit` ship with known-poor construct validity: `cost` and `audit` hold only
+> five patterns each, and `compliance` is keyword detection over regime names,
+> graded `author-intuition` in the catalog. A report on those three confirms
+> what we already published; a **concrete pattern that would fix it** is what we
+> need. Precision reports on the other five dimensions are very welcome.
+>
+> Note also that the total is coverage, not quality — stating all eight controls
+> clearly, once each, scores 28/100 — so "my good prompt scored low" is expected
+> behavior, not a false negative. Report the specific rule that should have
+> matched instead.
+
+## Dimension
+
+injection / hallucination / citation / cost / human_gate / safe_stop / audit / compliance
+
+## Prompt excerpt (redact secrets)
+
+```
+```
+
+## What CrewScore did
+
+- Score:
+- Matched / missing (from `--explain` if possible):
+
+## What you expected
+
+## Suggested pattern (optional)

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

@@ -0,0 +1,118 @@
+# 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 scores corpus prompts (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 = {}
+          config = {}
+          for r in rows:
+              p = r['path'].replace('\\\\', '/')
+              name = PurePosixPath(p).name
+              # Coding-agent config carries no governance grade at all - not a
+              # zero, not a key. Reading 'overall' off every row is what this
+              # guard exists to stop.
+              if r.get('governance_applicable', True):
+                  by[name] = int(r['overall'])
+              else:
+                  config[name] = r
+          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']
+          assert config, 'corpus lost its coding-agent config fixture'
+          for name, r in config.items():
+              assert 'overall' not in r, name + ' was handed a governance score'
+              assert 'dimensions' not in r, name + ' was handed dimension scores'
+          print('OK corpus', by, 'ungraded config', sorted(config))
+          "

crewscore-0.1.0/.github/workflows/example-ci.yml

@@ -0,0 +1,68 @@
+# Documented copy-paste example for consumers.
+#
+# In your own repo, prefer the published tag:
+#   uses: shmindmaster/crewscore@v1
+#
+# When developing this monorepo (or a fork), local path works:
+#   uses: ./
+#
+# Point prompt-file at your agent system prompt. The sample path below is only
+# for illustration; examples/sample-prompt.md intentionally scores low.
+#
+# Prefer scan-path when the repo has multiple agent artifacts (AGENTS.md,
+# system-prompt.md, prompts/*, etc.). The Action reports the worst (min) overall.
+#
+# workflow_dispatch only so this example does not fail default CI on the bare
+# sample prompt. Use crewscore-selftest.yml for green self-tests.
+name: CrewScore CI Example
+
+on:
+  workflow_dispatch:
+
+jobs:
+  score:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        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
+      #   id: crewscore
+      #   uses: shmindmaster/crewscore@v1
+      #   with:
+      #     scan-path: "."
+      #     threshold: "50"
+
+      # Local composite action (this repo / monorepo self-check) — single file:
+      - name: CrewScore
+        id: crewscore
+        uses: ./
+        with:
+          prompt-file: examples/sample-prompt.md
+          threshold: "50"
+          pr-comment: "false"
+
+      # Local scan example (uncomment when `crewscore scan` is available):
+      # - name: CrewScore scan
+      #   id: crewscore-scan
+      #   uses: ./
+      #   with:
+      #     scan-path: "."
+      #     threshold: "50"
+
+      - name: Use score outputs
+        if: always()
+        run: |
+          echo "score=${{ steps.crewscore.outputs.score }}"
+          echo "tier=${{ steps.crewscore.outputs.tier }}"

crewscore-0.1.0/.github/workflows/pytest.yml

@@ -0,0 +1,37 @@
+name: pytest
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # Don't let one platform's failure hide the others — we need to know
+      # which platforms are affected, not just that something broke.
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+        exclude:
+          # One Python per non-Linux platform is enough to catch OS-specific
+          # breakage (path handling, console encoding, line endings); the
+          # version matrix is what Linux is for.
+          - {os: windows-latest, python-version: "3.11"}
+          - {os: windows-latest, python-version: "3.12"}
+          - {os: macos-latest, python-version: "3.11"}
+          - {os: macos-latest, python-version: "3.12"}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q

crewscore-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,186 @@
+# Release pipeline for CrewScore.
+#
+# Publishing uses PyPI Trusted Publishing (OIDC), not an API token: there is
+# deliberately no PYPI_TOKEN secret in this repo, because a long-lived token
+# that can publish under this project name is the single worst secret to leak.
+# GitHub mints a short-lived identity token per run instead.
+#
+# ONE-TIME SETUP (must be done by the PyPI project owner, in a browser):
+#   https://pypi.org/manage/project/crewscore/settings/publishing/
+#   Add a trusted publisher with:
+#     Owner: shmindmaster   Repository: crewscore
+#     Workflow: release.yml  Environment: pypi
+# Until that exists, the publish job fails closed with an auth error and
+# nothing is uploaded. The build and verify job still runs and still produces
+# artifacts, so a tag is never silently half-released.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Build and verify only; do not publish"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Test, build, and verify artifacts
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Run the suite
+        run: pytest -q
+
+      # The tag is the release's only claim about which version it is. If it
+      # disagrees with the package, the wrong thing gets published under the
+      # right name and it cannot be taken back.
+      - name: Tag must match the package version
+        if: startsWith(github.ref, 'refs/tags/v') && runner.os == 'Linux'
+        shell: bash
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          PKG=$(python -c "import crewscore; print(crewscore.__version__)")
+          TAG="${REF_NAME#v}"
+          if [ "$PKG" != "$TAG" ]; then
+            echo "Tag $REF_NAME says $TAG but the package says $PKG" >&2
+            exit 1
+          fi
+          echo "OK version $PKG matches tag $REF_NAME"
+
+      # score-engine.js is generated from the Python source. A stale copy means
+      # the website and the CLI disagree, which is the failure this project can
+      # least afford to ship.
+      - name: Web engine must not be stale
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          set -euo pipefail
+          python scripts/export_web_engine.py
+          if ! git diff --quiet -- score-engine.js; then
+            echo "score-engine.js is stale; re-run scripts/export_web_engine.py" >&2
+            git diff --stat -- score-engine.js >&2
+            exit 1
+          fi
+          echo "OK web engine is current"
+
+      - name: Build sdist and wheel
+        if: runner.os == 'Linux'
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+
+      # Install the built artifact somewhere the source tree cannot rescue it.
+      - name: Smoke-test the built wheel in a clean environment
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install --quiet dist/*.whl
+          cd /tmp
+          printf 'You are a helpful assistant.\n' > p.md
+          printf '# Rules\n\nUse pnpm.\n' > AGENTS.md
+          /tmp/clean/bin/crewscore --version
+          /tmp/clean/bin/crewscore test --prompt-file p.md --json > gov.json
+          /tmp/clean/bin/crewscore rules --json > rules.json
+          # The 0.1.0 contract: config carries no governance grade at all.
+          /tmp/clean/bin/crewscore test --prompt-file AGENTS.md --json > cfg.json
+          python - <<'PY'
+          import json
+          cfg = json.load(open('/tmp/cfg.json'))
+          for k in ('overall', 'dimensions', 'findings', 'transparency'):
+              assert k not in cfg, k + ' leaked into a coding-agent config payload'
+          assert cfg['governance_applicable'] is False
+          gov = json.load(open('/tmp/gov.json'))
+          assert isinstance(gov['overall'], int)
+          rules = json.load(open('/tmp/rules.json'))
+          assert rules['rule_count'] > 0
+          assert rules['method']['llm_calls'] is False
+          print('OK wheel honors the published contracts')
+          PY
+
+      - name: Upload artifacts
+        if: runner.os == 'Linux'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: verify
+    if: startsWith(github.ref, 'refs/tags/v') && !inputs.dry-run
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/crewscore
+    permissions:
+      id-token: write # OIDC for trusted publishing — no token stored anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+
+  github-release:
+    name: Create the GitHub release
+    needs: publish
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish release notes from the changelog
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REF_NAME: ${{ github.ref_name }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="${REF_NAME#v}"
+          # Pull just this version's section out of CHANGELOG.md. Uses index()
+          # rather than a dynamic regex: the regex form silently matched
+          # nothing (awk mangles the bracket escapes), which would have shipped
+          # a release with empty notes if the -s check below did not catch it.
+          awk -v hdr="## [$VERSION]" '
+            index($0, hdr) == 1 { inside = 1; next }
+            inside && index($0, "## [") == 1 { exit }
+            inside { print }
+          ' CHANGELOG.md > notes.md
+          if [ ! -s notes.md ]; then
+            echo "No CHANGELOG section for $VERSION" >&2
+            exit 1
+          fi
+          gh release create "$REF_NAME" dist/* \
+            --title "$REF_NAME" --notes-file notes.md

crewscore-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.sqlite3
+agent-guard-report-*.html
+.DS_Store
+
+# Local / agent-only (never publish)
+.superpowers/
+.worktrees/
+_product-experience/
+_production/
+docs/superpowers/
+docs/research/
+docs/launch/
+docs/pmf-research-*.md
+docs/viral-product-spec-*.md
+docs/publish-checklist.md
+docs/ui-*.png
+
+
+# Marketing media pipeline (keep out of public tree)
+scripts/record-hero-demo.mjs
+

crewscore-0.1.0/AGENTS.md

@@ -0,0 +1,143 @@
+# CrewScore — agent instructions
+
+## What this is
+
+Offline CLI that classifies an agent-instruction file by name and judges it one of two ways:
+
+- **Coding-agent config** (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and friends — see `crewscore/profiles.py`) is scanned for **configuration smells** (Context Bloat, Init Fossilization, Lint Leakage — arXiv:2606.15828) and gets **no governance score at all**.
+- **Agent system prompts** (everything else) are scanned for **coverage of 8 governance-signal dimensions** (injection defense, hallucination policy, citations, cost limits, human gates, safe-stop, audit, compliance). The number is a match count against a published pattern list, not a validated quality or maturity ranking — **read `docs/validation.md` before trusting it for anything more than "which controls are missing."** In short: at matched length, CrewScore could not show production prompts scoring higher than amateur ones (delta +0.061, 95% CI −0.05 to +0.17, p=0.36), and three of the eight dimensions (Cost, Compliance, Audit) ship with known-poor construct validity.
+
+It also applies fix patterns (system-prompt profile only — `fix` refuses to write governance templates into coding-agent config) and optionally runs a non-technical AI vendor checklist (self-attest only).
+
+Public brand: **CrewScore** · Domain: **https://crewscore.ai** · PyPI: **`crewscore`** · Repo: **shmindmaster/crewscore**
+
+It does **not** (yet) run live adversarial LLM attacks or parse LangGraph/CrewAI runtimes. For live testing, hand off to Promptfoo / garak — see `docs/next-steps-eval.md`.
+
+Ruleset id: **`crewscore-hygiene@0.1.0`** (`crewscore rules` prints it; `crewscore/scoring.py:RULESET_ID` is the source of truth — it may lag this doc by a patch release mid-work).
+
+## Stack
+
+- Python 3.11+
+- click + rich
+- hatchling packaging
+- pytest
+
+## Commands
+
+All verified by running `py -m crewscore.cli ...` on this branch (Windows; use `py`, not `python`).
+
+```bash
+# install (editable)
+pip install -e ".[dev]"
+
+# repo scan (preferred for CI / monorepos) — classifies each file (auto), scores
+# system prompts on governance, config files on smells; --threshold is a no-op
+# on config and says so in `warnings`
+crewscore scan .
+crewscore scan . --json --threshold 50
+crewscore scan . --max-smells 0             # gate coding-agent config only
+crewscore scan . --profile system_prompt    # force one ruleset for every file found
+
+# score a single prompt (same auto-classification; --profile overrides it)
+crewscore test --prompt "You are a helpful assistant..."
+crewscore test --prompt-file ./system-prompt.md --explain
+crewscore test --prompt-file ./system-prompt.md --json --explain
+crewscore test --prompt-file ./system-prompt.md --json --threshold 50
+crewscore test --prompt-file AGENTS.md --max-smells 0     # config CI gate
+crewscore test --prompt-file ./system-prompt.md --report out.html --badge badge.svg
+
+# apply guardrail patterns (system-prompt profile only)
+crewscore fix --prompt-file ./system-prompt.md --plan          # dry-run: list planned dimensions, no write
+crewscore fix --prompt-file ./system-prompt.md --dry-run       # alias for --plan
+crewscore fix --prompt-file ./system-prompt.md
+crewscore fix --prompt-file ./system-prompt.md --apply
+crewscore fix --prompt-file ./system-prompt.md --output ./guarded.md --json
+
+# fix refuses on coding-agent config: exits 1, prints the reason, JSON has
+# "refused": true; force it anyway with --profile system_prompt (records
+# "forced_governance_write": true)
+crewscore fix --prompt-file AGENTS.md --plan
+crewscore fix --prompt-file AGENTS.md --profile system_prompt --plan --json
+
+# vendor checklist (secondary / self-attest)
+crewscore assess-vendor --name "Acme AI" --answers "y,y,n,dk,y,y,n,y,n,y" --json
+
+# live-eval handoff stubs (Promptfoo config + garak notes; does not run either tool)
+crewscore export-eval --prompt-file ./system-prompt.md --output-dir ./crewscore-eval
+
+# list the open rule catalog (never a black box)
+crewscore rules
+crewscore rules --json
+crewscore rules --dimension injection
+
+# after pattern changes: keep web in lockstep
+python scripts/export_web_engine.py
+
+# tests
+pytest
+```
+
+Legacy CLI entry point `agent-guard` still maps to the same `crewscore.cli:main` after install.
+
+## Layout
+
+```
+crewscore/
+  cli.py                 # click entry (test, fix, scan, rules, export-eval, assess-vendor)
+  scoring.py              # shared result model / tiers / RULESET_ID
+  profiles.py             # artifact classification (filename-only) -> which ruleset applies
+  scan.py                 # repo-walk file discovery + per-file scoring for `scan`
+  smells.py                # offline config-smell detection (arXiv:2606.15828)
+  rules_catalog.py         # open rule catalog + per-dimension provenance
+  summary.py                # PR/job markdown (transparent)
+  vendor_scorecard.py       # assess-vendor command
+  export_eval.py             # Promptfoo/garak handoff stub writer (export-eval command)
+  metrics.py                  # privacy-safe local metrics schema (no prompt text, no network)
+  web_export.py                # builds score-engine.js payload
+  report.py                     # HTML report + SVG badge
+  scorers/
+    structural_analysis.py      # governance-dimension regex matching
+    fix_patterns.py               # FIX_TEMPLATES per dimension
+scripts/
+  export_web_engine.py             # regenerate score-engine.js after pattern changes
+  score_corpus.py                    # examples/corpus leaderboard
+examples/corpus/                      # synthetic bare->hardened demo fixtures
+  prompts/                              # system-prompt fixtures scored by governance dimensions
+  repo-config/AGENTS.md                  # config fixture scored by smells
+score-engine.js                          # generated — commit after pattern changes
+index.html                                 # builder-first site (uses score-engine.js)
+action.yml                                  # composite GH Action (scan/test + sticky PR comment)
+docs/
+  validation.md                             # what the score does/does not measure — read before touching claims
+  next-steps-eval.md                          # Promptfoo / garak handoff (public user doc)
+  demo.svg, hero-demo.gif, hero-demo.mp4        # README hero assets
+tests/
+```
+
+## Product constraints
+
+- Prefer honest capability claims over roadmap theater.
+- Structural scores are pattern matches on prompt text, not proof of runtime behavior.
+- **The number is coverage, not a quality ranking.** A low score is actionable (you likely have not written a control down); a high score only means the text is present. Do not rank prompts, teams, or vendors by it, and do not treat a threshold as a safety bar — see `docs/validation.md`.
+- **Honesty scoring:** do not claim certification, audit, or red-team results; templates can inflate scores; under-score rather than over-claim.
+- **The published formula is the whole formula.** Score is a function of rule matches only. Never add a term (length, recency, file type) that isn't in `rules_catalog.SCORING_METHOD` and the README. A 0.2.x length bonus was removed in 0.3.0 precisely because it was undocumented and rewarded Context Bloat.
+- **Length is never rewarded.** Every line costs the agent context on every run. Fix templates stay terse, and `fix` reports its own context cost.
+- **Never hand a governance grade to coding-agent config.** `AGENTS.md`/`CLAUDE.md`-class files are classified by filename only (`profiles.py:classify_path`, content is never sniffed) and judged on configuration smells instead. Measured on the arXiv:2606.15828 corpus, the governance ruleset scored 100/100 real config files in the worst tier — the number is meaningless for that artifact, and publishing it is the fastest way to look broken. Any new output surface (report, badge, summary, share text, web) must branch on `governance_applicable`. `--profile` is the only override; when a caller forces governance templates onto config via `crewscore fix --profile system_prompt`, the JSON payload must carry `forced_governance_write: true` and human output must warn.
+- **Config `--json` payloads carry no governance fields.** When `governance_applicable` is `false`, `overall`, `dimensions`, `findings`, and `transparency` are **absent** from `crewscore test --json` / `crewscore scan --json` output — not zeroed, omitted. Consumers read `tier`, `smells`, `source`, `warnings`, `profile`, `ruleset` instead. Do not reintroduce those fields for config rows.
+- **Smells are advisory, never scored.** Folding them into the number would silently change what `--threshold N` means in someone's CI. `--max-smells N` is the separate gate for config files; changing smells into a score needs corpus evidence, not a patch release.
+- **Rules declare their provenance.** New dimensions must be graded `evidence-backed` / `plausible` / `author-intuition` in `rules_catalog.DIMENSION_PROVENANCE`; evidence-backed requires a citation. Approximations of a published detector must say so in their output. Per `docs/validation.md`, Cost, Compliance, and Audit currently have known-poor construct validity — treat proposals to strengthen or remove them as scoring work needing evidence, not a doc fix.
+- **Console output must be cp1252-encodable.** Windows redirects stdout through the ANSI code page; a stray arrow character once crashed `crewscore rules`. Use ASCII in printed strings.
+- Prefer `crewscore scan .` / Action `scan-path` for repo-native hygiene; demote vendor checklist in UX and docs.
+- Keep the package dependency-light (no LLM SDKs required for the core path).
+- Fame follows usefulness: explainable findings, fix, CI gate before launch theater.
+- Breaking CLI flags are acceptable if all docs and tests update in the same change.
+- Never document `pip install agent-guard` as *this* product (that PyPI name is taken by another package).
+- **Read `docs/validation.md` before writing or editing any claim about what the governance score proves.** It documents a discrimination study against 1,368 real prompts; do not re-inflate the "production-readiness" framing this file used before 0.1.0 without new evidence to support it.
+
+## Do not
+
+- Reintroduce fake `--langgraph` / `--crewai` loaders or adversarial mode stubs without real implementations.
+- Link to non-existent report hosts or wrong GitHub/PyPI names.
+- Add empty `examples/` / `evaluator/` / `patterns/` directories without content.
+- Overclaim "production safety certification," "production-readiness," or "7 regulated systems" beyond structural scanning and coverage — see `docs/validation.md`.
+- Elevate the vendor self-attest checklist to equal primary product surface.