feat(reference-curator): implement Python scripts + Gemini quality gate

Build the refcurator shared Python package and 7 CLI scripts that were previously specification-only. Add Gemini CLI as an independent pre-distillation quality evaluator, replacing the circular Claude-self-review pattern. Key changes: - shared/lib/src/refcurator/: 7-module package (config, db, models, utils, manifest, gemini) with PyMySQL + JSON file dual backend - 7 Click CLI scripts: discover, crawl_mgr, repo, distiller, reviewer, exporter, pipeline — each with subcommands for data management - Gemini quality gate: evaluates raw content BEFORE distillation using 5 criteria (relevance, authority, completeness, freshness, distill_value) - Pipeline reordered: discovery → crawl → store → evaluate → distill → export - Bug fixes from Codex adversarial review: - FileBackend now hard-fails on JOIN/aggregate/GROUP BY queries - Exporter uses MAX(review_id) to prevent shipping stale approvals - Distiller updates existing rows on refactor instead of forking - Updated all 7 CLAUDE.md directives with real script references - install.sh updated with refcurator package install step 51/51 E2E tests passing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 18:19:52 +09:00
parent 133df68b81
commit f215c11c32
23 changed files with 3917 additions and 583 deletions
--- a/custom-skills/90-reference-curator/05-quality-reviewer/code/CLAUDE.md
+++ b/custom-skills/90-reference-curator/05-quality-reviewer/code/CLAUDE.md
@@ -1,103 +1,93 @@
 # Quality Reviewer

-QA loop for reference library content. Scores distilled materials, routes decisions, and provides actionable feedback.
+Pre-distillation quality gate using Gemini CLI as an independent evaluator. Assesses raw crawled content before distillation to filter out low-quality sources early. Also supports manual scoring and routing for edge cases.

 ## Trigger Keywords
-"review content", "quality check", "QA review", "assess distilled content", "check reference quality"
+"review content", "quality check", "QA review", "evaluate sources", "check reference quality"

-## Decision Flow
+## Primary Flow: Gemini Pre-Distillation Gate

 ```
-[Distilled Content]
+[Raw Crawled Content]
       │
       ▼
-┌─────────────────┐
-│ Score Criteria  │ → accuracy, completeness, clarity, PE quality, usability
-└─────────────────┘
+┌────────────────────┐
+│ Gemini CLI Eval    │ → relevance, authority, completeness, freshness, distill_value
+└────────────────────┘
       │
-       ├── ≥ 0.85 → APPROVE → markdown-exporter
-       ├── 0.60-0.84 → REFACTOR → content-distiller
-       ├── 0.40-0.59 → DEEP_RESEARCH → web-crawler
-       └── < 0.40 → REJECT → archive
+       ├── ≥ 0.75 → APPROVE → proceed to distillation
+       ├── 0.50-0.74 → DEEP_RESEARCH → re-crawl for better sources
+       └── < 0.50 → REJECT → skip distillation entirely
 ```

-## Scoring Criteria
+## Evaluation Criteria (Gemini)

-| Criterion | Weight | Checks |
-|-----------|--------|--------|
-| **Accuracy** | 0.25 | Factual correctness, up-to-date, attribution |
-| **Completeness** | 0.20 | Key concepts, examples, edge cases |
-| **Clarity** | 0.20 | Structure, concise language, logical flow |
-| **PE Quality** | 0.25 | Techniques, before/after, explains why |
-| **Usability** | 0.10 | Easy reference, searchable, appropriate length |
+| Criterion | Weight | What It Checks |
+|-----------|--------|----------------|
+| **Relevance** | 0.25 | Does content match the curation topic? |
+| **Authority** | 0.25 | Official docs / research paper, or blog spam? |
+| **Completeness** | 0.20 | Full article, or nav fragment / error page / stub? |
+| **Freshness** | 0.15 | Up-to-date or outdated information? |
+| **Distill Value** | 0.15 | Unique info worth summarizing, or redundant? |

 ## Workflow

-### Step 1: Load Pending Reviews
+### Step 1: Evaluate Single Document
 ```bash
-python scripts/load_pending_reviews.py --output pending.json
+uv run python scripts/reviewer.py gemini-evaluate --doc-id 123 --topic "prompt engineering"
+
+# With auto-logging of decision:
+uv run python scripts/reviewer.py gemini-evaluate --doc-id 123 --topic "prompt engineering" --auto-approve
 ```

-### Step 2: Score Content
+### Step 2: Batch Evaluate All Pending
 ```bash
-python scripts/score_content.py --distill-id 123 --output assessment.json
+uv run python scripts/reviewer.py gemini-evaluate-pending --topic "prompt engineering" --auto-approve --limit 20
 ```

-### Step 3: Calculate Final Score
+### Step 3: Manual Review (Edge Cases)
+For documents where Gemini evaluation fails or needs human judgment:
 ```bash
-python scripts/calculate_score.py --assessment assessment.json
+# Calculate score from manual assessment
+uv run python scripts/reviewer.py calculate-score --assessment assessment.json
+
+# Route based on score
+uv run python scripts/reviewer.py route --score 0.78
+
+# Log review decision
+uv run python scripts/reviewer.py log-review \
+  --distill-id 123 --decision approve --score 0.85 \
+  --feedback "Manually verified"
 ```

-### Step 4: Route Decision
+### Step 4: Review History
 ```bash
-python scripts/route_decision.py --distill-id 123 --score 0.78
+uv run python scripts/reviewer.py history --distill-id 123
 ```

-Outputs:
- `approve` → Ready for export
- `refactor` → Return to distiller with instructions
- `deep_research` → Need more sources (queries generated)
- `reject` → Archive with reason
+## Prerequisites

-### Step 5: Log Review
-```bash
-python scripts/log_review.py --distill-id 123 --decision refactor --instructions "Add more examples"
-```
-
-## PE Quality Checklist
-
-When scoring `prompt_engineering_quality`:
- [ ] Demonstrates specific techniques (CoT, few-shot, etc.)
- [ ] Shows before/after examples
- [ ] Explains *why* techniques work
- [ ] Provides actionable patterns
- [ ] Includes edge cases and failure modes
- [ ] References authoritative sources
-
-## Auto-Approve Rules
-
-Tier 1 sources with score ≥ 0.80 may auto-approve:
-```yaml
-# In config
-quality:
-  auto_approve_tier1_sources: true
-  auto_approve_min_score: 0.80
-```
+- Gemini CLI: `npm install -g @google/gemini-cli`
+- Google auth: `gemini` (run once interactively to authenticate)
+- `refcurator` package installed

 ## Scripts

- `scripts/load_pending_reviews.py` - Get pending reviews
- `scripts/score_content.py` - Multi-criteria scoring
- `scripts/calculate_score.py` - Weighted average calculation
- `scripts/route_decision.py` - Decision routing logic
- `scripts/log_review.py` - Log review to database
- `scripts/generate_feedback.py` - Generate refactor instructions
+| Command | Purpose |
+|---------|---------|
+| `reviewer.py gemini-evaluate` | Evaluate single doc via Gemini CLI |
+| `reviewer.py gemini-evaluate-pending` | Batch evaluate all pending docs |
+| `reviewer.py calculate-score` | Manual weighted score calculation |
+| `reviewer.py route` | Decision routing from score |
+| `reviewer.py log-review` | Log review decision to DB |
+| `reviewer.py load-pending` | Get pending reviews |
+| `reviewer.py history` | Show review history |

 ## Integration

 | From | Action | To |
 |------|--------|-----|
-| content-distiller | Distilled content | → |
-| → | APPROVE | markdown-exporter |
-| → | REFACTOR + instructions | content-distiller |
-| → | DEEP_RESEARCH + queries | web-crawler-orchestrator |
+| content-repository (raw docs) | Gemini evaluation | → |
+| → | APPROVE | content-distiller |
+| → | DEEP_RESEARCH | web-crawler-orchestrator |
+| → | REJECT | archive (skip distillation) |