ahadiff 1.1.0__tar.gz

ahadiff-1.1.0/.gitignore

@@ -0,0 +1,148 @@
+# Cloned reference repos (test/exploration only)
+repo/
+
+# Graphify output (generated artifacts)
+graphify-out/
+
+# Playwright MCP cache
+.playwright-mcp/
+
+# Eval screenshots (generated during testing)
+eval-screenshots/
+
+# Local AhaDiff per-repo state
+.ahadiff/
+
+# macOS
+.DS_Store
+.DS_Store?
+._*
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+dist/
+build/
+.venv/
+*.egg
+
+# JavaScript
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.*
+
+# Claude Code local dev artifacts (review reports, team plans, memory)
+.claude/
+
+# CCG local dev artifacts (review reports, team plans, scratch)
+.ccg/
+.codex/
+
+# Generated agent skill installs (local only)
+.agents/
+
+# Internal planning artifacts (research prompts, audit reports, kept local)
+plan/
+
+# Development screenshots & test patches (local only)
+*.png
+!viewer/public/icons/ahadiff-192.png
+!viewer/public/icons/ahadiff-512.png
+# Committed media: README/USER_GUIDE-embedded screenshots & burned-subtitles tutorial videos
+# Only the 16 README-embedded screenshots (8 EN + 8 ZH). Other dev/eval captures stay ignored.
+!docs/video/public/screenshots/en/en-concepts-graph.png
+!docs/video/public/screenshots/en/en-dashboard.png
+!docs/video/public/screenshots/en/en-diff.png
+!docs/video/public/screenshots/en/en-lesson.png
+!docs/video/public/screenshots/en/en-quiz.png
+!docs/video/public/screenshots/en/en-review.png
+!docs/video/public/screenshots/en/en-rundetail-overview.png
+!docs/video/public/screenshots/en/en-settings.png
+!docs/video/public/screenshots/zh/zh-concepts-graph.png
+!docs/video/public/screenshots/zh/zh-dashboard.png
+!docs/video/public/screenshots/zh/zh-diff.png
+!docs/video/public/screenshots/zh/zh-lesson.png
+!docs/video/public/screenshots/zh/zh-quiz.png
+!docs/video/public/screenshots/zh/zh-review.png
+!docs/video/public/screenshots/zh/zh-rundetail-overview.png
+!docs/video/public/screenshots/zh/zh-settings.png
+!docs/video/output/*.burned-subtitles.mp4
+*.patch
+!benchmarks/fixtures/**/*.patch
+
+# Large media source files (keep only burned-subtitles MP4 for users)
+*.wav
+*.mp3
+*.m4a
+*.ogg
+*.webm
+*.mov
+docs/video/output/*clean*.mp4
+
+# Local dev output dirs
+/output/
+artifacts/
+/screenshots/
+.claude-tmp/
+
+# TypeScript incremental cache
+*.tsbuildinfo
+
+# Benchmark run outputs (regenerated by benchmarks/scripts/run_all.sh;
+# derived results, not source — baseline json embeds dev-machine absolute paths)
+benchmarks/results/
+
+# Development-only tracked files (kept locally for reference)
+result.json
+blueprint-snapshot.md
+snapshot-01-dashboard.md
+docs/VALIDATION_AUDIT.zh.md
+docs/USER_GUIDE.*.txt
+viewer/AUDIT-REPORT.md
+viewer/AUDIT_V6_FIDELITY.md
+viewer/V6_DEEP_ANALYSIS.md
+
+# Release cleanup: development-only directories and files
+
+# Development HTML mockups and prototypes (root + ui/)
+AhaDiff Warm*.html
+AhaDiff-Blueprint.html
+AhaDiff-Competitors-Research.html
+ui/
+
+# Internal development documentation and planning
+doc/
+docs/EVAL_SCORING_ENHANCEMENT_PLAN.md
+docs/EVAL_SCORING_ENHANCEMENT_REVIEW.md
+docs/plans/
+
+# Codex / Aider / dev conventions (not for end users)
+AGENTS.md
+CLAUDE.md
+CONVENTIONS.md
+R0-feature-matrix.md
+
+# Video build intermediates (keep final burned-subtitles MP4 + screenshots)
+docs/video/content/
+docs/video/output/asr/
+docs/video/output/script/
+docs/video/output/subtitles/
+docs/video/scripts/
+docs/video/src/
+docs/video/package.json
+docs/video/pnpm-lock.yaml
+docs/video/remotion.config.ts
+docs/video/tsconfig.json
+docs/video/README.md
+docs/video/public/captions/
+docs/video/.gitignore

ahadiff-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AhaDiff Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ahadiff-1.1.0/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: ahadiff
+Version: 1.1.0
+Summary: Local-first verified diff learning layer.
+Project-URL: Homepage, https://github.com/AGI-is-going-to-arrive/ahadiff
+Project-URL: Repository, https://github.com/AGI-is-going-to-arrive/ahadiff
+Project-URL: Documentation, https://github.com/AGI-is-going-to-arrive/ahadiff
+Project-URL: Issues, https://github.com/AGI-is-going-to-arrive/ahadiff/issues
+Author: AhaDiff
+License-Expression: MIT
+License-File: LICENSE
+Keywords: code-review,diff,learning,llm,local-first,srs
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: fsrs<7,>=6.3.1
+Requires-Dist: genanki<1,>=0.13
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: portalocker<4,>=3.1
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: rich<15,>=14
+Requires-Dist: starlette<1,>=0.49
+Requires-Dist: tree-sitter-c-sharp<1,>=0.23
+Requires-Dist: tree-sitter-go<1,>=0.25
+Requires-Dist: tree-sitter-java<1,>=0.23
+Requires-Dist: tree-sitter-javascript<1,>=0.25
+Requires-Dist: tree-sitter-php<1,>=0.24
+Requires-Dist: tree-sitter-ruby<1,>=0.23
+Requires-Dist: tree-sitter-rust<1,>=0.24
+Requires-Dist: tree-sitter-typescript<1,>=0.23
+Requires-Dist: tree-sitter<1,>=0.24
+Requires-Dist: typer<1,>=0.16
+Requires-Dist: uvicorn<1,>=0.38
+Requires-Dist: watchdog<7,>=6
+Provides-Extra: anki
+Provides-Extra: optimizer
+Requires-Dist: fsrs[optimizer]<7,>=6.3.1; extra == 'optimizer'
+Provides-Extra: tree-sitter
+Provides-Extra: watchdog
+Description-Content-Type: text/markdown
+
+# AhaDiff (知返)
+
+> **Ship with AI. Learn it back.**
+>
+> Every AI-written git diff becomes a verified Aha lesson, with code-linked evidence, active-recall quizzes, spaced review, and a self-improving quality ratchet.
+
+[中文](./README.zh.md) · [Landing page](https://agi-is-going-to-arrive.github.io/ahadiff/) · [User Guide](./docs/USER_GUIDE.en.html) · [English tutorial video (subtitled)](./docs/video/output/ahadiff-tutorial.en.burned-subtitles.mp4) · [Chinese tutorial video (Bilibili)](https://www.bilibili.com/video/BV1b57k6yEWm)
+
+---
+
+## What it is
+
+**AhaDiff** is a **local-first learning layer for AI coding**.
+
+It is not a PR summary or a repo wiki. It reads a single git diff and turns that change into:
+
+- A **lesson** that teaches what changed and why
+- A **claims ledger** where conclusions trace back to `file:line` evidence
+- A **quiz and review loop** so the knowledge comes back later
+- A **quality history** that makes runs comparable over time
+
+All repo-local state lives in `.ahadiff/`: run artifacts under `runs/`, and SRS / result history in `review.sqlite`.
+
+> Code Wiki explains a repo. AhaDiff teaches you what changed, and verifies every claim against the diff.
+
+## Why
+
+AI writes code faster, but developers can understand less of what actually changed. AhaDiff exists to close that loop:
+
+1. **AI ships, understanding returns to humans**: a commit message is not enough.
+2. **Every claim needs evidence**: no hallucinated functions, no fabricated causality.
+3. **Knowledge should compound**: repeated concepts should build history and backlinks.
+4. **Quality should be comparable**: replace "looks fine" with a stable score and ratchet.
+
+## Prerequisites
+
+- Python 3.11+ with Python's `sqlite3` runtime at SQLite 3.51.3+; patched backport branches 3.50.4+ and 3.44.6+ are also accepted. Run `ahadiff doctor` to check the runtime Python actually uses.
+- git (on PATH)
+- [uv](https://docs.astral.sh/uv/): install with `curl -LsSf https://astral.sh/uv/install.sh | sh` or `brew install uv`
+- An LLM provider: remote (OpenAI / Anthropic / Gemini / Azure / any OpenAI-compatible) with API key, or local (LM Studio / Ollama, no key needed)
+
+## Install
+
+```bash
+pip install ahadiff
+ahadiff --version   # should print ahadiff 1.1.0
+```
+This ships a working WebUI out of the box, and all default features work with no extras.
+
+`pip install 'ahadiff[optimizer]'` is only needed for FSRS parameter auto-optimization, which pulls in a heavy torch dependency. Base review and scheduling work without it.
+
+### From source (contributors)
+
+```bash
+git clone https://github.com/AGI-is-going-to-arrive/ahadiff.git
+cd ahadiff
+uv tool install --editable .
+cd viewer && pnpm install && pnpm build   # builds the dev WebUI
+```
+
+## Configure a provider
+
+AhaDiff needs an LLM to generate lessons. Set up once per repo:
+```bash
+ahadiff init
+
+# Register and test a provider (OpenAI-compatible example)
+export OPENAI_API_KEY="<your-provider-api-key>"
+export AHADIFF_PROVIDER_BASE_URL="<provider-base-url>"
+ahadiff provider test \
+  --name default \
+  --provider-class openai \
+  --base-url "$AHADIFF_PROVIDER_BASE_URL" \
+  --api-key-env OPENAI_API_KEY
+```
+`provider test` sends a small probe request. If it succeeds, the provider is saved to `.ahadiff/config.toml`. When the provider exposes model limits, AhaDiff records split input / output limits; otherwise auto capture falls back to the bundled model registry or conservative defaults.
+
+`api_key_env` is the environment variable name, not the secret. Repo config accepts `AHADIFF_*` names and the common provider names (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `AZURE_OPENAI_API_KEY`). Identifier-shaped values are treated as environment-variable names and fail closed when unset, so a missing variable is not sent as a literal bearer token.
+
+Supported provider classes: `openai`, `openai_responses`, `gemini`, `anthropic`, `azure`, `newapi`, `lmstudio`, `ollama`. Advanced OpenAI-compatible or local setups can use `providers.<name>.capability_overrides` for known boolean capabilities such as native JSON schema support; invalid keys or non-boolean values are rejected. NewAPI disables `supports_native_json_schema` by default; if your NewAPI gateway backend actually supports native JSON schema, you can add `capability_overrides = { supports_native_json_schema = true }` in the provider config. See [User Guide](./docs/USER_GUIDE.en.html) for details.
+
+The Settings provider card can also preview model limits before you save, using only the draft provider class, model, and optional limits profile. It does not call the remote provider or read the API key for that preview. Leaving `max_output_tokens` empty means Auto; when a known trusted output max is exceeded, save-time config clamps it and returns a warning. Unknown, low-confidence, route-specific, or local-runtime limits are shown as warnings instead of being presented as hard facts.
+
+For GPT-5.5 specifically, the bundled registry keeps two profiles: ordinary `openai` access budgets 400k context, while `openai_responses` / API access budgets 1.05M. A live probe can still override the registry when the endpoint reports a trustworthy total context.
+
+> AhaDiff defaults to strict_local privacy: nothing leaves your machine unless you explicitly configure a remote provider.
+
+## Your first lesson
+
+```bash
+# Learn from your latest commit
+ahadiff learn --last
+
+# Open the local web UI to read your lesson
+ahadiff serve
+```
+`ahadiff serve` opens http://127.0.0.1:8765 automatically. Pass `--no-browser` to stay in the terminal. You'll see the Dashboard with your first run, then click through to Lesson, Diff, and Quiz.
+
+Two more things to try:
+```bash
+ahadiff quiz <run_id>    # test yourself on what you just learned
+ahadiff review           # spaced-repetition review of past cards
+```
+See the [User Guide](./docs/USER_GUIDE.en.html) for all 10 diff capture sources, export options, concept graphs, and advanced commands.
+
+## Features
+
+- **Learn**: `ahadiff learn` supports 10 diff capture sources: working tree (`--staged --unstaged --include-untracked`), unstaged (`--unstaged`), staged (`--staged`), last commit (`--last`, or omit a capture-source flag), revision/range (`REVISION`), time-window (`--since`; add `--author` only when that filter matches one commit), patch file/stdin (`--patch FILE|-`), patch URL (`--patch-url`), file compare (`--compare`), and directory compare (`--compare-dir`, macOS/Linux only). Recursive directory compare requires the secure directory file descriptor available on macOS/Linux. Patch files are resolved inside the repo root; use stdin for external generated patches. Patch file/stdin and patch URL runs do not have a repository symbol index; when only hunk evidence is available, AhaDiff can still generate a lesson from weak diff-anchored claims instead of claiming symbol-level proof.
+- **Evidence-linked claims**: every lesson conclusion is tied to `file:line` evidence, with verification states such as verified, weak, not proven, contradicted, and rejected.
+- **Structured LLM output**: generation uses schema-aware JSON contracts where supported, defaults to JSON object mode with one bounded validation retry, and keeps the existing parser, repair, and degraded fallback paths. Truncated or malformed fallback JSON is retried instead of being accepted.
+- **Adaptive capture limits**: fresh configs default to auto capture sizing; existing customized capture settings stay manual. Auto mode uses provider probes, the bundled model registry, output reserves, safety reserves, and CJK diff density, while runtime patch intake remains capped at 50 MiB. Settings previews provider limits from the current draft provider class, model, and optional limits profile before saving, without remote probing on every edit.
+- **Quiz and review**: `ahadiff quiz` tests the run you just learned; source evidence stays locked until you answer. `ahadiff review` brings back older cards with spaced repetition. Quiz count is fixed by default (3 questions, configurable from 1 to 30) and can adapt to diff size when enabled (default range 3-12).
+- **Scoring**: each run gets an 8-dimension deterministic score, with an optional advisory LLM judge when configured. No-spec `spec_alignment` is shown as N/A / `0/0` and excluded from the overall score; judge results never override `score.json.verdict`. Diff Coverage is based on visible `line_map.json` files and line-weighted hunks, and hard-gate details show the adaptive claim-anchor threshold used for that run. If the optional judge fails, the deterministic score is still kept and the failure is saved as a redacted `judge_failure.json`.
+- **WebUI**: `ahadiff serve` opens Welcome, Dashboard, Lesson, Diff, Quiz, Review, Concepts, Run Detail, Settings, and Guide. The viewer uses a light, editorial paper-style theme, with fonts bundled locally so nothing loads from a CDN. Run Detail shows Score, Judge, Artifacts, and a sanitized judge-failure panel when the optional LLM judge could not complete. The Welcome Before/After demo keeps long raw diffs collapsed with a line count and a Show all / Collapse control; short or empty diffs stay simple.
+- **New Run dialog**: Dashboard can start quick learn runs for working tree, unstaged, staged, or last commit changes, with advanced cards for `--since`, revision/range, patch URL, pasted patch text, file compare, and directory compare.
+- **Export**: from the CLI, `ahadiff export-results` writes `results.tsv` and `ahadiff export preview` writes a local static preview bundle. The WebUI (and the `serve` API) also export TSV / JSON and Anki `.apkg`; `.apkg` export uses the bundled `genanki`, available by default.
+- **Concept graph**: AhaDiff extracts cross-diff concepts and shows them in a Canvas graph with health checks.
+- **AI tool integration**: project-level guidance for 15 CLI / IDE / CI targets. Settings groups the targets, shows localized usage hints and a provider-free local demo, and keeps write/remove behind confirmation. Guide shows commands plus read-only cards that explain usage and preview the files AhaDiff would write. Supported targets include Claude, Codex, Gemini, Antigravity IDE, Antigravity CLI, Copilot, OpenCode, Cursor, Cline, Continue, Roo, Windsurf, Aider, GitHub Actions, and Git hooks.
+- **Auto-iteration**: `ahadiff improve` optimizes prompts in an isolated worktree and keeps only better results.
+- **Privacy**: three tiers: strict_local, redacted_remote, explicit_remote. The default is strict_local.
+- **i18n**: English and Chinese for the WebUI and prompt output language. CLI help and most CLI diagnostics are in English.
+- **Cross-platform**: macOS and Linux are the primary tested platforms; Windows is supported for the core CLI and serve flows. `--compare-dir` and the `hooks` install target are macOS/Linux only. Installer writes and rollbacks use atomic replacement; POSIX restores file mode before replace, while Windows uses a best-effort mode restore after replace.
+- **Validation scope**: the latest local pre-release audit covered backend unit/integration/eval tests, ruff/pyright, wheel build, viewer Vitest/typecheck/build, real-serve smoke, Guide browser checks, i18n parity, and live learn runs for the documented capture sources. A clean full Playwright matrix, remote CI, and a real Windows runner remain separate release gates.
+- **Security**: URL secret redaction, provider URL validation, provider API-key environment validation, input validation, prompt injection detection, safety hard gates, and redacted judge-failure reporting.
+
+## Screenshots
+
+<p align="center">
+  <img src="./docs/video/public/screenshots/en/en-dashboard.png" alt="Dashboard: runs, scores, ratchet trajectory" width="800">
+</p>
+
+<details>
+<summary>Welcome: first-run entry point</summary>
+<img src="./docs/video/public/screenshots/en/en-welcome.png" alt="Welcome page with first-run quick start" width="800">
+</details>
+
+<details>
+<summary>Lesson: AI-generated lesson from your diff</summary>
+<img src="./docs/video/public/screenshots/en/en-lesson.png" alt="Lesson page" width="800">
+</details>
+
+<details>
+<summary>Diff Viewer: claim-linked code evidence</summary>
+<img src="./docs/video/public/screenshots/en/en-diff.png" alt="Diff viewer with claim highlights" width="800">
+</details>
+
+<details>
+<summary>Quiz: active recall from the lesson</summary>
+<img src="./docs/video/public/screenshots/en/en-quiz.png" alt="Quiz page" width="800">
+</details>
+
+<details>
+<summary>Review: spaced repetition cards</summary>
+<img src="./docs/video/public/screenshots/en/en-review.png" alt="Review page" width="800">
+</details>
+
+<details>
+<summary>Concept Graph: cross-diff knowledge map</summary>
+<img src="./docs/video/public/screenshots/en/en-concepts-graph.png" alt="Concept graph" width="800">
+</details>
+
+<details>
+<summary>Concepts Ledger: learned concepts table</summary>
+<img src="./docs/video/public/screenshots/en/en-concepts.png" alt="Concepts ledger table" width="800">
+</details>
+
+<details>
+<summary>Run Detail: scores and evaluation breakdown</summary>
+<img src="./docs/video/public/screenshots/en/en-rundetail-overview.png" alt="Run detail overview" width="800">
+</details>
+
+<details>
+<summary>Run Detail Score: 8-dimension score breakdown</summary>
+<img src="./docs/video/public/screenshots/en/en-rundetail-score.png" alt="Run detail score breakdown" width="800">
+</details>
+
+<details>
+<summary>Settings: provider, preferences, and AI tool guidance</summary>
+<img src="./docs/video/public/screenshots/en/en-settings.png" alt="Settings page" width="800">
+</details>
+
+## AI tool integration
+
+AhaDiff writes repo-local guidance files for the current project; it does not install the AhaDiff CLI again or write global user directories:
+```bash
+ahadiff install --detect        # auto-detect your tools
+ahadiff install claude          # also: cursor, copilot, codex, gemini, antigravity, antigravity-cli, aider, windsurf, cline, roo, continue, ...
+```
+15 targets supported. Run `ahadiff install --help` for the full list, or configure in the WebUI under Settings → AI Tool Guidance.
+
+Settings groups targets into CLI / IDE / CI, shows quick-start steps, example prompts, expected behavior, platform notes, and a provider-free local demo. Guide uses the same usage hints inside default-collapsed tool cards and shows what files would be written before you apply changes; actual write/remove stays in Settings.
+
+Guide and the New Run dialog keep cards, note markers, and footer actions readable in Windows high-contrast / forced-colors mode; usage hints use the same tokenized type scale as the rest of the viewer.
+
+Some targets write tool-native generated files. Examples include `.claude/skills/ahadiff/SKILL.md`, `.agents/skills/ahadiff/SKILL.md`, `.gemini/skills/ahadiff/SKILL.md`, `.agents/skills/ahadiff-antigravity/SKILL.md`, `.agents/skills/ahadiff-antigravity-cli/SKILL.md`, `.agents/rules/ahadiff.md`, `.github/instructions/ahadiff.instructions.md`, `.opencode/agents/ahadiff.md`, `.clinerules/ahadiff.md`, `.continue/rules/ahadiff.md`, `.cursor/rules/ahadiff.mdc`, `.roo/rules/ahadiff.md`, and `.windsurf/rules/ahadiff.md`. Repo guidance sections stay in user-managed files such as `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, and `.github/copilot-instructions.md`. Uninstall only removes AhaDiff-generated files and AhaDiff marked sections.
+
+This repository ignores generated `.agents/` installs, so repo-local Codex / Antigravity skill output remains local unless a user explicitly tracks it.
+
+## 8-Dimension Rubric
+
+| # | Dimension | Weight | Hard gate |
+|---|-----------|--------|-----------|
+| 1 | Accuracy | 20 | Base gate: < 14 → FAIL. Runtime policy may lower this threshold for very large visible diffs, but unsafe rejected-claim ratios and safety gates still block PASS. |
+| 2 | Evidence | 18 | Base gate: < 12 → FAIL. Runtime policy may lower this threshold for very large visible diffs, but invalid or missing evidence still counts against the run. |
+| 3 | Diff Coverage | 14 | Adaptive claim-anchor gate. Normal diffs fail below 7.70; large broad diffs use a lower threshold, while one/two-file many-hunk diffs use a stricter one. The exact ratio, regime, and visible basis are written into hard gate details. |
+| 4 | Learnability | 14 | None |
+| 5 | Quiz Transfer | 10 | None |
+| 6 | Spec Alignment | 10 | None |
+| 7 | Conciseness | 8 | None |
+| 8 | Safety & Privacy | 6 | Unmitigated Critical → FAIL |
+
+Three verdicts: **PASS** ≥ 80 / **CAUTION** 60–80 / **FAIL** < 60. Hard gates can still force **FAIL** even when the overall score is high; contradicted claims require zero tolerance, and unmitigated Critical safety findings fail the run.
+
+## Repository Layout
+
+```text
+ahadiff/
+├─ src/ahadiff/         # Python source
+├─ viewer/              # React 19 frontend
+├─ tests/               # Test suite
+├─ prompts/             # LLM prompt templates
+├─ benchmarks/          # Eval benchmark fixtures
+├─ docs/                # Landing page, user guides, tutorial videos
+├─ .github/workflows/   # CI/CD
+├─ pyproject.toml       # Python package config
+└─ LICENSE              # MIT
+```
+
+## Core Philosophy (N-File Contract)
+
+AhaDiff extends the Karpathy / autoresearch three-file contract into an N-file variant:
+
+| File | Who edits | Role |
+|------|-----------|------|
+| `program.md` | Human | Natural-language state machine for the improve loop |
+| evaluation bundle | **Immutable** | `evaluator.py` + `rubric.py` + `rubric.yaml` + `gates.py` + `deterministic.py`, locked as a unit |
+| `prompts/*.md` | Agent | The improve loop edits only allowlisted generation prompts; `eval_judge.md` is a judge prompt resource, not part of that writable set |
+
+Loop: edit → commit → evaluate → keep if better, reset if worse → record the result for review and future runs.
+
+## Inspirations, Design Axioms, and License
+
+### Inspirations
+
+- **karpathy/autoresearch**: N-file contract and git ratchet
+- **alchaincyf/darwin-skill**: 8-dimension rubric and Phase 2.5 rewrite
+- **Evol-ai/SkillCompass**: PASS / CAUTION / FAIL and weakest-dimension-first
+- **ZJU-REAL/SkillZero**: helpfulness-driven retention and compact context
+- **safishamsi/graphify**: repo-level graph overlay
+- **karpathy/llm-wiki** gist: persistent compounding wiki
+
+### Design Axioms
+
+1. **Evidence first**: every claim must trace back to `file:line`
+2. **Learning over summary**: quizzes and review beat pretty summaries
+3. **Local-first trust**: privacy tiers are explicit, and local stays local by default
+4. **Paper-like seriousness**: academic feel, not a loud SaaS landing page
+5. **One accent per style**: warm paper background plus a single accent color
+
+### Acknowledgements
+
+Thanks to the [linux.do](https://linux.do/) community for feedback and support.
+
+### License
+
+[MIT](./LICENSE)
+
+---
+
+> AhaDiff / 知返: Δ知 ↺