AI-Harness-Scorecard_One-Click_Kit

AI Harness Scorecard — One-Click Kit (Windows)

Grade your AI project's safety and governance in one click. Checks 31 best-practice rules and returns an A → F grade. You don't need to be a developer.

📘 New to computers or AI?

This README is a quick summary. There are full beginner walkthroughs that explain every term step by step:

• 🇺🇸 English: 👉 USER_GUIDE.md (glossary · every menu · every error fix · FAQ)
• 🇰🇷 Korean: 👉 사용설명서.md (same content in Korean)

If this is your first time, we strongly recommend reading a guide first.

📑 Table of Contents

1. What is this?
2. How it works (at a glance)
3. Who is this for?
4. ⚡ Quick Start (3 steps)
5. ⬇️ How to download
6. Requirements (what you need)
7. 🖥️ Main Menu
8. Full Menu Reference
9. 🔁 Common Workflows
10. Grading System
11. AUTO-FIX (raise your score)
12. GitHub Token (optional)
13. 📁 File & Doc Locations
14. Update / Uninstall
15. Troubleshooting
16. Safety / Privacy
17. CLI Commands (advanced)
18. Related Links · License

What is this?

These days it's common to ask AI to write code for you. But unreviewed AI-generated code can be risky.

AI Harness Scorecard is a free Windows tool that scans any Git repository (project folder) and scores it on 31 AI-governance checks. It tells you whether your project has proper safeguards for AI-generated code — architecture docs, branch protection, required code reviews, audit trails — and returns a report-card style A→F grade.

🏥 Think of it as a health check-up. It inspects your folder and reports a safety score — it never touches your files.

You do not need to be a developer to use it. Just double-click a file and press a number.

ℹ️ This kit is a Windows launcher (.bat) + Korean/English guides layered on top of the open-source Python package ai-harness-scorecard (the real scan engine). It lets you use it with double-clicks and number choices instead of complex commands.

How it works (at a glance)

[ Double-click RUN.bat ]
        │
        ▼
  ┌──────────────────────────────┐
  │  Pick a number (1-9, 0)       │
  └──────────────────────────────┘
        │
        ├─ 1/2: Scan a folder on your PC, right where it is (no internet)
        │
        ├─ 3: GitHub URL → clone to a temp folder → scan → auto-delete the clone
        │
        ▼
  The scan engine (ai-harness-scorecard) runs 31 checks
        │
        ▼
  Score (0-100) + grade (A-F) + category breakdown shown on screen
        │
        ├─ (optional) 5/6/7: save results as .md / .json / a badge file
        └─ (optional) 8: create missing template files to raise your score

• Read-only check-up: it never edits or deletes files in the folder being scanned.
• Works offline: menus 1 & 2 (your own folders) run without internet.
• Self-cleaning: temp scan files and GitHub clones delete themselves when done.

Who is this for?

⚡ Quick Start (3 steps)

For a detailed step-by-step walkthrough (with terms explained), see USER_GUIDE.md.

Step 1 — Install Python (one time only)

1. Go to https://www.python.org/downloads/
2. Click the big yellow "Download Python" button → run the installer
3. ⚠️ On the first screen, check "Add Python to PATH" (this is essential)
4. Click Install Now and wait for it to finish

Step 2 — Install the tool (one time only)

1. Open the folder containing INSTALL.bat and RUN.bat
2. Double-click INSTALL.bat → wait 1–3 minutes
3. When asked "Open RUN.bat now?" type Y and press Enter

Step 3 — Run a scan (every time)

1. Double-click RUN.bat
2. Pick a number: 1 = this folder / 2 = another folder / 3 = a GitHub URL
3. Read your grade (A→F) on screen

That's it. No commands, no config files to edit.

⬇️ How to download

If these files are already in your folder, the download is done. Jump to Step 2 (Install).

Option A — Download as ZIP (easiest, no Git needed)

1. Open the kit's GitHub page: https://github.com/sodam-ai/AI-Harness-Scorecard_One-Click_Kit
2. Click the green Code button → Download ZIP
3. Right-click the ZIP → "Extract All"
4. You should see INSTALL.bat, RUN.bat inside the extracted folder
   • 📁 Recommended location: somewhere easy with a short path, like Desktop or Documents.

Option B — Clone with Git (if you have Git)

git clone https://github.com/sodam-ai/AI-Harness-Scorecard_One-Click_Kit.git

Requirements (what you need)

✅ = required / ⬜ = nice to have. Easiest start: install Python and your own-folder scans (menus 1 & 2) work right away.

🖥️ Main Menu (what you see when you run RUN.bat)

 ============================================================
  AI HARNESS SCORECARD  -  MAIN MENU
 ============================================================
   Version : (installed version)
   GitHub  : Not logged in  (scans check local files only)
 ============================================================
  ---- GRADE Checks ----
   1.  Grade THIS folder      this folder (no internet needed)
   2.  Grade a LOCAL folder   any folder on your computer
   3.  Grade a GITHUB REPO    paste a GitHub URL to scan

  ---- GITHUB Login ----
   4.  GitHub Login / Logout  login adds web-setting checks

  ---- SAVE Reports ----
   5.  Save Markdown report   save results as .md document
   6.  Save JSON data report  save results as .json data
   7.  Generate badge file    score badge for your README

  ---- FIX ISSUES ----
   8.  AUTO-FIX               create missing files (raise score)

  ---- TOOL ----
   9.  Version / Update / Help
   0.  Exit
 ============================================================
   Type a number (0-9) and press ENTER:

👉 Press the number you want and hit Enter. New here? Start with 1 to safely see how a scorecard looks.

Full Menu Reference

🔁 Common Workflows

Grading System

Low grade? Use menu 8 (AUTO-FIX) to create missing files, fill them in, and scan again.

AUTO-FIX (Menu 8) — Raise Your Score

Creates required-but-missing files as templates so your project can pass the checks:

⚠️ Important: Created files are empty templates — edit them to match your real project. ✅ Safe: Existing files are never overwritten.

GitHub Token (optional)

Menu 4 lets you log in with a GitHub Personal Access Token. This unlocks checks that only work via the GitHub API:

• Branch protection rules
• Required code reviews
• GitHub Actions CI pipeline

Without a token, 20+ local file checks still run.

Create a token (2 minutes):

1. Go to https://github.com/settings/tokens → Generate new token (classic)
2. Name it AI Harness Scorecard, check repo and read:org
3. Generate token → copy the token (starts with ghp_)
4. RUN.bat → 4 → 1 → paste your token

Saved at %USERPROFILE%\.ai_harness_token.

⚠️ Security: Stored in plain text. Never share or upload it. (It is also listed in .gitignore so it can't be committed.)

📁 File & Doc Locations (where everything lives)

AI-Harness-Scorecard_One-Click_Kit/
├── INSTALL.bat          ← ① Run first (one time only)
├── RUN.bat              ← ② Main program — run this every time
├── UNINSTALL.bat        ← ③ Removes everything cleanly
├── 사용설명서.md         ← Korean beginner guide (full walkthrough)
├── USER_GUIDE.md        ← English beginner guide (full walkthrough)
├── README.md            ← This file (English)
├── README.ko.md         ← Korean README (kept in sync)
├── LICENSE              ← License terms (Apache License 2.0)
├── .gitignore           ← Local-only files kept out of Git
│
└── (generated after scanning/saving — excluded by .gitignore)
    ├── scorecard-report.md      ← Menu 5: Markdown report
    ├── scorecard-report.json    ← Menu 6: JSON report
    └── scorecard-badge.json     ← Menu 7: Badge

Elsewhere on your computer (Windows environment-variable paths)

💡 This kit needs no .env / environment-variable setup of its own. The %USERPROFILE% / %TEMP% above are standard Windows path placeholders.

Update / Uninstall

• Update: RUN.bat → 9 → 2 (internet required)
• Uninstall: Double-click UNINSTALL.bat → Y → removes the tool, token, and report files
  • The kit folder itself (INSTALL.bat, etc.) stays. To remove it entirely, delete the folder in File Explorer.

Troubleshooting

For detailed fixes for every error, see USER_GUIDE.md → Troubleshooting.

Safety / Privacy

• ✅ Scans read only — your files are never changed or deleted.
• ✅ No data sent anywhere, except GitHub's official API when you provide a token for GitHub checks.
• ✅ Menus 1 & 2 work fully offline. Temp files clean themselves up.
• ⚠️ The token file (.ai_harness_token) is plain text — keep it private. (It's in .gitignore so it can't be committed.)
• ✅ Admin rights only needed if a normal install fails.
• ℹ️ Transparency: during a scan, RUN.bat writes small helper scripts (grade summary, AUTO-FIX) to the Windows temp folder (%TEMP%) and deletes them on exit. Nothing is sent externally. (Some antivirus tools are sensitive to .bat files creating temp files, but the behavior stays local.)

CLI Commands (advanced)

Only if you prefer typing commands. The menu is enough for most users.

ai-harness-scorecard assess .                                  # Grade current folder
ai-harness-scorecard assess . --github-token ghp_XXXXXX        # With token
ai-harness-scorecard assess . --format markdown -o report.md   # Save Markdown
ai-harness-scorecard assess . --format json                    # Save JSON
ai-harness-scorecard assess . --badge badge.json               # Generate badge
ai-harness-scorecard --help                                    # Help

Related Links

• Beginner guide (English): USER_GUIDE.md
• Beginner guide (Korean): 사용설명서.md
• Upstream package (scan engine): https://github.com/markmishaev76/ai-harness-scorecard
• Python download: https://www.python.org/downloads/
• Git download: https://git-scm.com/download/win

License

Apache License 2.0 — Copyright 2025 SoDam AI Studio

This kit (the installer/runner scripts and documentation) is a Windows launcher and guide created by SoDam AI Studio. The actual scan engine, the open-source package ai-harness-scorecard, is subject to its own author's license. See LICENSE for full terms.