docs: prepare for gnome review team sharing

Front-load AI transparency by moving "How This Was Built" to position 4
in README (right after reviewer invitation). Strengthen community
messaging to frame rules as reviewer-owned. Name hara-hachi-bu as
regression baseline. Promote scripts/new-rule.sh as primary contribution
path in CONTRIBUTING.md with fixture validation checklist and debugging
tips. Separate hara-hachi-bu regression into standalone runner. Fix
stale counts in GOVERNANCE.md and ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ZviBaratz

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+### Changed
+
+- Moved "How This Was Built" section earlier in README for transparency
+- Promoted `scripts/new-rule.sh` as primary contribution workflow in CONTRIBUTING.md
+- Added fixture validation checklist and debugging tips to CONTRIBUTING.md
+- Separated hara-hachi-bu regression into `tests/run-regression.sh`
+- Named hara-hachi-bu as regression baseline in README
+- Strengthened community ownership messaging in README
+- Updated stale assertion/fixture counts in docs
+
 ### Bug Fixes
 
 - **ego-review**: Added "NOT a signal" exception to ai-slop checklist item #4 — `_destroyed` + `_initializing` (re-entrancy guard) is not the over-engineered state machine anti-pattern (#1, PR #4)

CONTRIBUTING.md

@@ -8,6 +8,8 @@ Thank you for your interest in improving GNOME extension review tooling.
 
 ## For Reviewers: Add a Check in 5 Minutes
 
+> **Fastest path:** Run `bash scripts/new-rule.sh` — it scaffolds the YAML rule, test fixture, and assertion file interactively (with next-ID suggestion). The walkthrough below explains what it creates, so you understand the pieces.
+
 You just rejected an extension because it uses `navigator.clipboard` (a browser API that doesn't exist in GJS). Here's how to encode that rejection so ego-lint catches it automatically next time.
 
 ### Step 1: Add the rule to `rules/patterns.yaml`
@@ -85,6 +87,18 @@ if [[ -f "$ASSERTIONS_DIR/your-category.sh" ]]; then
 fi
 ```
 
+### Before running tests: Verify your fixture
+
+Common fixture mistakes that cause confusing failures:
+
+- Directory name contains `@` (e.g., `my-rule@test`)
+- `uuid` in metadata.json matches directory name exactly
+- metadata.json includes a `"url"` field
+- LICENSE file exists with SPDX identifier
+- UUID/name does not contain "gnome" (trademark check will fail)
+
+Or run `bash scripts/validate-fixture.sh` to check all of the above automatically.
+
 ### Step 4: Run tests
 
 ```bash
@@ -93,7 +107,11 @@ bash tests/run-tests.sh
 
 All existing tests must still pass alongside your new assertion.
 
-**Shortcut:** Use `scripts/new-rule.sh` to scaffold all of the above interactively, or `scripts/validate-fixture.sh` to check that your fixtures meet the structural requirements.
+### Debugging tips
+
+- **Pattern doesn't match?** Test your rule in isolation: `bash scripts/validate-rule.sh R-XXXX-NN tests/fixtures/your-fixture@test`
+- **Fixture fails validation?** Run `bash scripts/validate-fixture.sh` to identify structural issues
+- **Not sure which check fires?** Run `./ego-lint tests/fixtures/your-fixture@test --verbose` and look for your rule ID in the output
 
 ## First Contribution Workflow
 

GOVERNANCE.md

@@ -57,4 +57,4 @@ For rule changes:
 1. Proposer opens issue or PR with citation
 2. At least one co-maintainer (or the project lead) reviews
 3. New rules land as advisory; severity upgrades require test validation
-4. Changes that affect blocking rules require running the full test suite (373+ assertions) and regression baseline
+4. Changes that affect blocking rules require running the full test suite (378+ assertions) and regression baseline

README.md

@@ -42,6 +42,12 @@ This tool encodes the mechanical checks you already do by hand — import segreg
 
 You are invited to shape the rules, adjust severity, and add checks for rejection patterns you see often.
 
+## How This Was Built
+
+- **Claude Code wrote the code** — scripts, rules, tests, and docs were developed using [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic's AI coding tool). Every design decision was human-reviewed. The AI slop detection rules are based on patterns observed in real EGO rejections of AI-generated submissions.
+- **Research was AI-assisted** — Discourse mining, guideline extraction, cross-source synthesis, and gap analysis were performed with Claude Code and verified against real EGO reviews on extensions.gnome.org, [gjs.guide](https://gjs.guide) requirements, and GNOME Shell GitLab history. Regression-tested against a real 11-module extension as baseline.
+- **ego-lint itself is AI-free** — The output artifact is deterministic bash + python + YAML. No API calls. No network access. No model inference. AI was the development tool, not the runtime tool.
+
 ## Where to Start
 
 - **Adding rules**: [CONTRIBUTING.md](CONTRIBUTING.md) — 5-minute workflow for adding a check
@@ -139,7 +145,7 @@ The rules and checks are grounded in analysis of real EGO review behavior — no
 - Cross-referenced [gjs.guide](https://gjs.guide) guidelines (109 extracted requirements) with actual reviewer behavior
 - Traced GNOME Shell guideline evolution across versions 44–50 via GitLab history
 - Reverse-engineered patterns from 5 popular approved extensions
-- Regression-tested all checks against a real 11-module extension as baseline
+- Regression-tested all checks against [hara-hachi-bu](https://github.com/ZviBaratz/hara-hachi-bu) (an 11-module power management extension, submitted to EGO) as baseline
 
 Key unwritten rules discovered:
 1. No "GNOME" in UUID, extension name, or schema ID (trademark)
@@ -163,7 +169,7 @@ Full research: [docs/RESEARCH-SUMMARY.md](docs/RESEARCH-SUMMARY.md) | Detailed f
 
 ## Community
 
-This project is looking for community co-maintainers among EGO reviewers. If you'd like to help shape the rules — add checks for rejection patterns you see often, adjust severity, or improve heuristics — open an issue or PR. See [GOVERNANCE.md](GOVERNANCE.md) for how rule decisions are made.
+The rules belong to whoever shapes them. Reviewers who contribute checks, adjust severity, or report false positives define what ego-lint enforces and how. If you see a rejection pattern that ego-lint misses, [adding it](CONTRIBUTING.md) is a 4-line YAML change. See [GOVERNANCE.md](GOVERNANCE.md) for how rule decisions are made.
 
 ### Help Wanted
 
@@ -183,12 +189,6 @@ Self-contained improvements where reviewer expertise would be especially valuabl
 
 Full gap list: [docs/research/gap-analysis.md](docs/research/gap-analysis.md)
 
-## How This Was Built
-
-- **Claude Code wrote the code** — scripts, rules, tests, and docs were developed using [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic's AI coding tool). Every design decision was human-reviewed. The AI slop detection rules are based on patterns observed in real EGO rejections of AI-generated submissions.
-- **Research was AI-assisted** — Discourse mining, guideline extraction, cross-source synthesis, and gap analysis were performed with Claude Code and verified against real EGO reviews on extensions.gnome.org, [gjs.guide](https://gjs.guide) requirements, and GNOME Shell GitLab history. Regression-tested against a real 11-module extension as baseline.
-- **ego-lint itself is AI-free** — The output artifact is deterministic bash + python + YAML. No API calls. No network access. No model inference. AI was the development tool, not the runtime tool.
-
 ## Advanced: Claude Code Plugin (Optional)
 
 ego-lint is the primary offering — it works standalone without Claude Code or any AI. The skills below are experimental extras for developers who use [Claude Code](https://docs.anthropic.com/en/docs/claude-code).

docs/ARCHITECTURE.md

@@ -119,7 +119,7 @@ skills/
 tests/
   run-tests.sh                  Test runner
   assertions/                   Assertion files (sourced by runner)
-  fixtures/                     142 test fixtures
+  fixtures/                     144 test fixtures
 docs/
   ci-integration.md             GitHub Actions / GitLab CI examples
   ARCHITECTURE.md               This file

tests/run-regression.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Standalone regression runner for hara-hachi-bu baseline.
+# Run locally to verify no new false positives from newly added checks.
+# Not part of CI (depends on locally installed extension).
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LINT="$SCRIPT_DIR/skills/ego-lint/scripts/ego-lint.sh"
+PASS_COUNT=0
+FAIL_COUNT=0
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+assert_output_contains() {
+    local label="$1" pattern="$2"
+    if echo "$output" | grep -qE "$pattern"; then
+        echo -e "  ${GREEN}✓${NC} $label"
+        PASS_COUNT=$((PASS_COUNT + 1))
+    else
+        echo -e "  ${RED}✗${NC} $label (expected pattern: $pattern)"
+        FAIL_COUNT=$((FAIL_COUNT + 1))
+    fi
+}
+
+assert_output_not_contains() {
+    local label="$1" pattern="$2"
+    if ! echo "$output" | grep -qE "$pattern"; then
+        echo -e "  ${GREEN}✓${NC} $label"
+        PASS_COUNT=$((PASS_COUNT + 1))
+    else
+        echo -e "  ${RED}✗${NC} $label (should NOT match: $pattern)"
+        FAIL_COUNT=$((FAIL_COUNT + 1))
+    fi
+}
+
+echo "============================================"
+echo "  ego-lint Regression Runner"
+echo "============================================"
+echo ""
+
+# Source the regression assertions
+ASSERTIONS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/assertions"
+if [[ -f "$ASSERTIONS_DIR/hara-hachi-bu-regression.sh" ]]; then
+    source "$ASSERTIONS_DIR/hara-hachi-bu-regression.sh"
+else
+    echo "Assertion file not found: $ASSERTIONS_DIR/hara-hachi-bu-regression.sh"
+    exit 1
+fi
+
+# --- Summary ---
+echo "============================================"
+echo "  Results: $PASS_COUNT passed, $FAIL_COUNT failed"
+echo "============================================"
+
+if [[ "$FAIL_COUNT" -gt 0 ]]; then
+    echo -e "${RED}REGRESSION FAILURES DETECTED${NC}"
+    exit 1
+else
+    echo -e "${GREEN}ALL REGRESSION CHECKS PASSED${NC}"
+    exit 0
+fi

tests/run-tests.sh

@@ -653,11 +653,6 @@ if [[ -f "$ASSERTIONS_DIR/quick-wins.sh" ]]; then
     source "$ASSERTIONS_DIR/quick-wins.sh"
 fi
 
-# Hara-hachi-bu regression (conditional)
-if [[ -f "$ASSERTIONS_DIR/hara-hachi-bu-regression.sh" ]]; then
-    source "$ASSERTIONS_DIR/hara-hachi-bu-regression.sh"
-fi
-
 # --- Summary ---
 echo "============================================"
 echo "  Results: $PASS_COUNT passed, $FAIL_COUNT failed"