@ikieaneh/opencode-kit 0.5.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ikieaneh/opencode-kit",
+  "version": "0.5.0",
+  "description": "Standardized OpenCode orchestration framework \u2014 contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
+  "license": "MIT",
+  "author": "RizkiRachman",
+  "type": "module",
+  "main": ".opencode/plugins/opencode-kit.js",
+  "exports": {
+    ".": {
+      "import": ".opencode/plugins/opencode-kit.js"
+    }
+  },
+  "bin": {
+    "opencode-kit": "./src/cli.js"
+  },
+  "files": [
+    ".opencode/plugins/",
+    ".claude-plugin/",
+    "src/",
+    "rules/",
+    "templates/",
+    "skills/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "orchestration",
+    "workflow",
+    "agents",
+    "enforcement",
+    "contract",
+    "scoring",
+    "adr"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RizkiRachman/opencode-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/RizkiRachman/opencode-kit/issues"
+  },
+  "homepage": "https://github.com/RizkiRachman/opencode-kit#readme"
+}

package/rules/rules.json

@@ -0,0 +1,123 @@
+{
+  "version": "0.1.0",
+  "strict": true,
+  "description": "Machine-enforceable rules for OpenCode agents. CRITICAL = BLOCK agent. HIGH = FLAG orchestrator. LOW = advisory.",
+
+  "state_machine": {
+    "transitions": [
+      { "from": "INIT", "to": "PLAN", "require_score": null },
+      { "from": "PLAN", "to": "PLAN_SCORED", "require_score": null },
+      { "from": "PLAN_SCORED", "to": "EXECUTE", "require_score": 70 },
+      { "from": "EXECUTE", "to": "EXECUTE_SCORED", "require_score": null },
+      { "from": "EXECUTE_SCORED", "to": "REVIEW", "require_score": 70 },
+      { "from": "REVIEW", "to": "REVIEW_SCORED", "require_score": null },
+      { "from": "REVIEW_SCORED", "to": "COMPLETE", "require_score": 70 },
+      { "from": "*", "to": "BLOCKED", "condition": "score < 50 OR retry_attempts >= 3" },
+      { "from": "BLOCKED", "to": "INIT", "condition": "user_intervention" }
+    ]
+  },
+
+  "rules": [
+    {
+      "id": "PREFLIGHT_001",
+      "severity": "CRITICAL",
+      "description": "Agent MUST load contract.json before any tool call",
+      "condition": "first_action_not_contract_load",
+      "action": "BLOCK",
+      "message": "⛔ PREFLIGHT FAILED: contract.json not loaded. Run: lean-ctx ctx_knowledge recall --query \"orchestration-contract\""
+    },
+    {
+      "id": "PREFLIGHT_002",
+      "severity": "CRITICAL",
+      "description": "Agent MUST NOT work on main branch",
+      "condition": "git_branch_is_main",
+      "action": "BLOCK",
+      "message": "⛔ PREFLIGHT FAILED: Current branch is main. Create a feature branch first."
+    },
+    {
+      "id": "PREFLIGHT_003",
+      "severity": "CRITICAL",
+      "description": "Agent MUST validate contract.state before proceeding",
+      "condition": "contract_state_mismatch",
+      "action": "BLOCK",
+      "message": "⛔ STATE FAILED: Contract state is ${actual}. Expected one of: ${expected}"
+    },
+    {
+      "id": "IMPACT_001",
+      "severity": "CRITICAL",
+      "description": "Agent MUST run gitnexus_impact before editing any symbol",
+      "condition": "edit_without_impact_analysis",
+      "action": "BLOCK",
+      "message": "⛔ IMPACT FAILED: Edit attempted without gitnexus_impact analysis. Run: gitnexus_impact({target, direction: \"upstream\"})"
+    },
+    {
+      "id": "PERSIST_001",
+      "severity": "HIGH",
+      "description": "Agent MUST persist contract after every delegation/phase change",
+      "condition": "delegation_without_persist",
+      "action": "FLAG",
+      "message": "⚠️ PERSIST WARNING: Contract not persisted after delegation. Run: lean-ctx ctx_knowledge remember category architecture key orchestration-contract value <updated JSON>"
+    },
+    {
+      "id": "SCORE_001",
+      "severity": "HIGH",
+      "description": "Scoring MUST be computed after each subagent returns",
+      "condition": "delegation_returned_without_scoring",
+      "action": "FLAG",
+      "message": "⚠️ SCORE WARNING: Subagent output not scored. Run scoring pipeline (Tier 1 rules + Tier 2 judge)"
+    },
+    {
+      "id": "WRITE_001",
+      "severity": "CRITICAL",
+      "description": "Agent MUST follow writing order: Port → Service → Mapper → Adapter → Constants → Events → Tests",
+      "condition": "writing_order_violation",
+      "action": "FLAG",
+      "message": "⚠️ WRITING ORDER: Files created in wrong order. Expected order: port → service → mapper → adapter → constants → events → tests"
+    },
+    {
+      "id": "BRANCH_001",
+      "severity": "HIGH",
+      "description": "Agent MUST push feature branch before significant work",
+      "condition": "significant_work_without_push",
+      "action": "FLAG",
+      "message": "⚠️ BRANCH WARNING: Feature branch exists but not pushed. Run: git push -u origin $(git branch --show-current)"
+    },
+    {
+      "id": "LEARN_001",
+      "severity": "HIGH",
+      "description": "Learner agent MUST update ALL 11 memory systems in post-flight matrix",
+      "condition": "learner_skipped_memory_system",
+      "action": "FLAG",
+      "message": "⚠️ LEARNER WARNING: Not all memory systems updated. See AGENTS.md §1.7 for full matrix."
+    },
+    {
+      "id": "SCORE_002",
+      "severity": "HIGH",
+      "description": "Tier 2 LLM judge MUST use the canonical judge prompt from rules.json scoring.tier2.judge_prompt or templates/judge-prompt.md",
+      "condition": "judge_prompt_not_from_canonical_source",
+      "action": "FLAG",
+      "message": "⚠️ SCORE WARNING: Judge prompt must use canonical source. See .opencode/rules/rules.json scoring.tier2.judge_prompt"
+    }
+  ],
+
+  "scoring": {
+    "tier1": {
+      "schema_valid_deduction": 15,
+      "permissions_violated_deduction": 40,
+      "blast_radius_high_deduction": 40,
+      "writing_order_wrong_deduction": 15,
+      "required_fields_missing_deduction": 15,
+      "subtotal_threshold": 70
+    },
+    "tier2": {
+      "enabled": true,
+      "judge_prompt": "You are an impartial judge evaluating an AI agent's output. Score 0-100 based on: (1) Requirements fulfillment 0-40, (2) Governance compliance 0-30, (3) Completeness 0-20, (4) Edge cases and risks 0-10. Return JSON: { score: N, rationale: '...', missing_items: [...] }"
+    },
+    "thresholds": {
+      "pass": 70,
+      "retry": 50,
+      "max_attempts": 3,
+      "escalation": 50
+    }
+  }
+}

package/rules/validation.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# opencode-kit rules validation — validate agent actions against rules.json
+# Usage: bash rules/validation.sh [--strict]
+#   --strict: treat HIGH rules as BLOCK (default: FLAG only)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+. "$SCRIPT_DIR/src/platform.sh"
+
+RULES_FILE=".opencode/rules/rules.json"
+CONTRACT_FILE=".opencode/orchestration/contract.json"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+STRICT="${1:-}"
+
+echo "[opencode-kit] 🔍 Rules Validation"
+echo ""
+
+# --- Check rules.json exists ---
+if [ ! -f "$RULES_FILE" ]; then
+  echo -e "${RED}❌ $RULES_FILE not found. Cannot validate.${NC}"
+  exit 1
+fi
+
+# --- Check contract.json exists ---
+if [ ! -f "$CONTRACT_FILE" ]; then
+  echo -e "${RED}❌ $CONTRACT_FILE not found. Cannot validate state.${NC}"
+  exit 1
+fi
+
+# --- Parse rules.json using python or jq ---
+if [ -n "$PYTHON_CMD" ]; then
+  PARSE_CMD="$PYTHON_CMD -c"
+elif command -v jq &>/dev/null; then
+  PARSE_CMD="jq -r"
+else
+  echo -e "${RED}❌ Neither Python nor jq found. Cannot parse rules.json.${NC}"
+  exit 1
+fi
+
+echo "  Rules file: $RULES_FILE"
+echo "  Contract:   $CONTRACT_FILE"
+echo ""
+
+TOTAL_VIOLATIONS=0
+CRITICAL_VIOLATIONS=0
+HIGH_VIOLATIONS=0
+
+# --- Validate 1: Branch rule ---
+echo -e "${CYAN}[PREFLIGHT_002]${NC} Branch validation..."
+BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo -e "${RED}  ❌ VIOLATION: On '$BRANCH' branch${NC}"
+  echo "     → Create a feature branch: git checkout -b feature/<YYYYMMDD>-<description>"
+  CRITICAL_VIOLATIONS=$((CRITICAL_VIOLATIONS + 1))
+  TOTAL_VIOLATIONS=$((TOTAL_VIOLATIONS + 1))
+else
+  echo "  ✅ Branch: $BRANCH (safe)"
+fi
+
+# --- Validate 2: Contract state ---
+echo -e "${CYAN}[STATE_001]${NC} Contract state validation..."
+STATE=$($PYTHON_CMD -c "
+import json
+with open('$CONTRACT_FILE') as f: d=json.load(f)
+print(d.get('state','UNKNOWN'))
+" 2>/dev/null)
+VALID_STATES="INIT PLAN PLAN_SCORED EXECUTE EXECUTE_SCORED REVIEW REVIEW_SCORED COMPLETE BLOCKED"
+if echo "$VALID_STATES" | grep -qw "$STATE"; then
+  echo "  ✅ State: $STATE (valid)"
+else
+  echo -e "${RED}  ❌ VIOLATION: Invalid state '$STATE'${NC}"
+  echo "     → Valid states: $VALID_STATES"
+  CRITICAL_VIOLATIONS=$((CRITICAL_VIOLATIONS + 1))
+  TOTAL_VIOLATIONS=$((TOTAL_VIOLATIONS + 1))
+fi
+
+# --- Validate 3: Contract has required fields ---
+echo -e "${CYAN}[SCHEMA_001]${NC} Contract schema validation..."
+$PYTHON_CMD -c "
+import json, sys
+with open('$CONTRACT_FILE') as f: d=json.load(f)
+errors = []
+if not d.get('requirements',{}).get('goal'): errors.append('requirements.goal is empty')
+if d.get('score',{}).get('combined') is None: errors.append('score.combined is missing')
+if d.get('state') not in ['INIT','PLAN','PLAN_SCORED','EXECUTE','EXECUTE_SCORED','REVIEW','REVIEW_SCORED','COMPLETE','BLOCKED']:
+  errors.append('state is invalid')
+if errors:
+  print('VIOLATION:' + '; '.join(errors))
+  sys.exit(1)
+else:
+  print('OK')
+" 2>&1 || true
+# (soft check — don't block)
+
+# --- Validate 4: gitnexus impact check (if git diff shows changes) ---
+echo -e "${CYAN}[IMPACT_001]${NC} Impact analysis check..."
+if git diff --stat HEAD 2>/dev/null | grep -q .; then
+  echo -e "${YELLOW}  ⚠️  Uncommitted changes detected — run gitnexus_impact before editing${NC}"
+  HIGH_VIOLATIONS=$((HIGH_VIOLATIONS + 1))
+  TOTAL_VIOLATIONS=$((TOTAL_VIOLATIONS + 1))
+else
+  echo "  ✅ No uncommitted changes (or changes already analyzed)"
+fi
+
+# --- Validate 5: Contract persisted check (lean-ctx) ---
+echo -e "${CYAN}[PERSIST_001]${NC} Persistence check..."
+if command -v lean-ctx &>/dev/null; then
+  if lean-ctx ctx_knowledge recall --query "orchestration-contract" &>/dev/null; then
+    echo "  ✅ Contract persisted in lean-ctx"
+  else
+    echo -e "${YELLOW}  ⚠️  Contract NOT found in lean-ctx — persist after changes${NC}"
+    HIGH_VIOLATIONS=$((HIGH_VIOLATIONS + 1))
+    TOTAL_VIOLATIONS=$((TOTAL_VIOLATIONS + 1))
+  fi
+else
+  echo -e "${YELLOW}  ⚠️  lean-ctx not available — cannot verify persistence${NC}"
+fi
+
+# --- Summary ---
+echo ""
+echo "[opencode-kit] 📊 Validation Summary"
+echo "  CRITICAL violations: $CRITICAL_VIOLATIONS"
+echo "  HIGH violations:     $HIGH_VIOLATIONS"
+echo "  Total violations:    $TOTAL_VIOLATIONS"
+echo ""
+
+if [ "$TOTAL_VIOLATIONS" -eq 0 ]; then
+  echo -e "${GREEN}[opencode-kit] ✅ All rules validated. No violations.${NC}"
+  exit 0
+elif [ "$CRITICAL_VIOLATIONS" -gt 0 ]; then
+  echo -e "${RED}[opencode-kit] ❌ CRITICAL violations found. Run preflight.sh to identify blockers.${NC}"
+  exit 1
+elif [ "$STRICT" = "--strict" ] && [ "$HIGH_VIOLATIONS" -gt 0 ]; then
+  echo -e "${YELLOW}[opencode-kit] ⛔ HIGH violations in strict mode. Fix before proceeding.${NC}"
+  exit 1
+else
+  echo -e "${YELLOW}[opencode-kit] ⚠️  HIGH violations found (FLAG only — non-blocking).${NC}"
+  exit 0
+fi

package/skills/adr-generator/SKILL.md

@@ -0,0 +1,42 @@
+---
+description: Auto-generate Architecture Decision Records when making architectural decisions. Logs to contract.json decisions.adr_log[].
+---
+
+# ADR Generator
+
+When making an architectural decision, record it in `contract.json` → `decisions.adr_log[]`.
+
+## ADR Format
+
+```json
+{
+  "id": "ADR-003",
+  "date": "2026-06-11",
+  "title": "Decision title",
+  "context": "Why this decision was needed",
+  "decision": "What was decided",
+  "alternatives": "What was considered and rejected",
+  "consequences": "Positive and negative effects"
+}
+```
+
+## When to Record
+
+- Any non-trivial architectural choice
+- Any rejected approach that future agents might propose again
+- Any convention or rule change
+- When asked "is this decision recorded?"
+
+## Auto-ID
+
+- Read existing `adr_log[]` from contract
+- Next ID = max ADR-NNN + 1
+- If no existing log, start at ADR-001
+
+## CLI Alternative
+
+```sh
+bash src/adr.sh --title "..." --context "..." --decision "..." --alternatives "..." --consequences "..."
+```
+
+The CLI script handles ID assignment, duplicate detection, and contract injection automatically.

package/skills/learner/SKILL.md

@@ -0,0 +1,44 @@
+---
+description: Post-execution learning agent. Extract lessons, persist knowledge, update memory systems.
+---
+
+# Learner Agent
+
+Run after every completed task. You are the last agent — you make learning durable.
+
+## Mandatory: Update ALL Memory Systems
+
+| System | Tool | What to Do |
+|--------|------|------------|
+| lean-ctx knowledge | `ctx_knowledge remember` | Persist gotchas, patterns, decisions |
+| STATE.md | Append | Append completed work, update focus |
+| Orchestration contract | `ctx_knowledge remember` | Set state=COMPLETE, append lessons |
+| gitnexus | `npx gitnexus analyze` | Re-index code intelligence |
+| Handoff pack | memory-mcp | Label: `handoff.learner.<task_id>` |
+| ctx_session | `ctx_session save` | Persist conversation |
+
+## Extract Three Categories
+
+### What went well (1-3)
+- Decisions/patterns that led to smooth execution
+- Should this be a permanent pattern?
+
+### What went wrong (1-3)
+- Where was time/tokens wasted?
+- What blocked progress or required rework?
+
+### What to change next time (1-2)
+- Concrete, actionable — not vague advice
+- "Always load contract before edits" not "be more careful"
+
+## Output Format
+
+```json
+{
+  "lessons_learned": ["What went well: ...", "What went wrong: ..."],
+  "knowledge_updates": [
+    { "category": "gotchas", "key": "...", "value": "...", "severity": "warning" }
+  ],
+  "next_session_tips": "..."
+}
+```

package/skills/orchestration-template/SKILL.md

@@ -0,0 +1,41 @@
+---
+description: MANDATORY — Load orchestration contract before any work. Validates state, branch, phase.
+---
+
+# Orchestration Template
+
+**MANDATORY on EVERY task start.** Forces agent to load contract from lean-ctx BEFORE any work.
+
+## Contract Protocol
+
+1. **LOAD** — Run: `lean-ctx ctx_knowledge recall --query "orchestration-contract"`
+   - If found: extract state, session, requirements, decisions, governance
+   - If NOT found: check `.opencode/orchestration/contract.json` → create fresh
+
+2. **VALIDATE** — Check state transition is legal per rules.json state_machine
+   - If illegal: set state=BLOCKED, persist, STOP
+
+3. **PERSIST** — After every delegation or phase change:
+   ```
+   lean-ctx ctx_knowledge remember \
+     category architecture \
+     key orchestration-contract \
+     value "<updated JSON>"
+   ```
+
+## State Machine
+
+```
+INIT → PLAN → PLAN_SCORED → EXECUTE → EXECUTE_SCORED → REVIEW → REVIEW_SCORED → COMPLETE
+                                                                                         ↘
+BLOCKED (any phase) → user intervention → retry
+```
+
+**Transition Rules:**
+- Each phase transition requires score ≥ 70 to proceed
+- Score < 50 → BLOCKED
+- Max 3 retry attempts
+
+## Rules References
+- `rules.json` — machine-readable enforcement rules
+- `contract.json` — shared state contract

package/skills/qa-expert/SKILL.md

@@ -0,0 +1,26 @@
+---
+description: Quality assurance — test strategy, coverage analysis, edge case detection, regression prevention.
+---
+
+# QA Expert
+
+## Test Standards
+
+- **One assertion per test** — each test validates exactly one behavior
+- **Cover all branches** — happy path, empty, null, boundary, error
+- **Test alongside code** — write tests in same phase as implementation, not after
+
+## Edge Cases to Check
+
+- Null/empty inputs for every param
+- Boundary values (max length, pagination limits, date ranges)
+- Concurrent access (if shared state exists)
+- Timeout failures, network retries
+- Malformed data (bad JSON, wrong types)
+
+## Coverage Goals
+
+- Domain services: ≥ 95% instruction coverage
+- Adapters (web/persistence): ≥ 85%
+- Mappers: ≥ 100% (trivial mappings can still break)
+- Overall project: ≥ 90%

package/skills/scoring-pipeline/SKILL.md

@@ -0,0 +1,43 @@
+---
+description: Score every subagent output after delegation. Tier 1 (rule checks) + Tier 2 (LLM judge) + verdict.
+---
+
+# Scoring Pipeline
+
+After every subagent delegation returns, run three-tier scoring before proceeding.
+
+## Tier 1 — Rule-Based Checks
+
+Start at 100. Deduct for each violation:
+
+| Check | Deduction |
+|-------|:---------:|
+| Schema valid (required fields present) | -15 |
+| Permissions violated (forbidden patterns) | -40 |
+| Blast radius unsafe (HIGH/CRITICAL) | -40 |
+| Writing order wrong | -15 |
+| Required fields missing | -15 |
+
+If subtotal < 70 → skip Tier 2, use subtotal as combined score.
+
+## Tier 2 — LLM Judge
+
+Use prompt from `.opencode/rules/rules.json` → `scoring.tier2.judge_prompt`:
+
+```
+Score 0-100 on:
+- Fulfills requirements? (0-40)
+- Follows governance? (0-30)
+- Completeness? (0-20)
+- Edge cases covered? (0-10)
+```
+
+Return JSON: `{ "score": N, "rationale": "...", "missing_items": [...] }`
+
+## Tier 3 — Verdict
+
+| Score | Verdict | Action |
+|:-----:|---------|--------|
+| ≥ 70 | PASS | Advance to next phase |
+| 50–69 | RETRY | Fix issues (if attempt < max) |
+| < 50 | BLOCKED | Escalate to user |

package/skills/system-analyst/SKILL.md

@@ -0,0 +1,28 @@
+---
+description: System analysis — architecture evaluation, dependency mapping, impact analysis, execution trace.
+---
+
+# System Analyst
+
+## Before Touching Code
+
+1. **Trace the execution flow**: Use `gitnexus_query` to find processes related to the change
+2. **Map dependencies**: Run `gitnexus_impact({target, direction: "upstream"})` — report blast radius
+3. **Check the knowledge graph**: `graphify query "<question>"` — find how components connect
+4. **Identify communities**: What functional areas does this touch?
+
+## Impact Analysis Guide
+
+| Risk Level | Meaning | Action |
+|:----------:|---------|--------|
+| LOW | 0-3 consumers | Safe to change |
+| MEDIUM | 4-9 consumers | Flag orchestrator |
+| HIGH | 10+ consumers | BLOCK — get approval |
+| CRITICAL | Core infrastructure | BLOCK — design review required |
+
+## Architecture Checklist
+
+- [ ] Hexagonal boundaries respected? (domain doesn't import infrastructure)
+- [ ] No JPA annotations in domain models?
+- [ ] Ports return nullable, not Optional?
+- [ ] Writing order correct? (Port → Service → Mapper → Adapter → Constants → Events → Tests)

package/skills/token-optimize/SKILL.md

@@ -0,0 +1,32 @@
+---
+description: Guidelines for efficient token usage — read strategically, batch operations, minimize context.
+---
+
+# Token Optimization
+
+## Reading Strategy
+
+- **Search before read**: use `gitnexus_query` or `grep` before reading files
+- **Read sections, not whole files**: use `ctx_read(path, mode: "lines:N-M")`
+- **Use `ctx_read` compression modes**: `map` for structure, `signatures` for signatures, `full` only when needed
+- **Cache re-reads**: `ctx_read` is cached — subsequent reads of unchanged files cost ~13 tok
+
+## Batching
+
+- **Batch independent reads**: Use `ctx_multi_read` to read multiple files in one call
+- **Batch independent writes**: Use `write` calls in parallel
+- **Batch grep patterns**: Combine related patterns in a single grep call
+
+## Delegation
+
+- **Delegate discovery to @explorer** — 2x faster, 1/2 cost for codebase search
+- **Delegate docs to @librarian** — 10x better at finding API docs
+- **Delegate bounded work to @fixer** — 2x faster, 1/2 cost for bounded edits
+- **Delegate analysis to @observer** — isolates large binary files from context
+
+## Anti-Patterns
+
+- ❌ Reading full files you only need a snippet of
+- ❌ Grep + read individual results instead of batch reading
+- ❌ Keeping large context when only the summary is needed
+- ❌ Re-reading the same file in multiple tool calls

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,60 @@
+---
+description: Run verification commands before claiming work is complete. Evidence before assertions.
+---
+
+# Verification Before Completion
+
+**Never claim work is complete without running verification first.**
+
+## Verification Order
+
+For any code change, run in order:
+
+### 1. Formatting
+```bash
+mvn spotless:apply  # or equivalent formatter
+```
+
+### 2. Compilation
+```bash
+mvn compile
+# Expected: BUILD SUCCESS
+```
+
+### 3. Architecture (if ArchUnit present)
+```bash
+mvn test -Dtest="*Architecture*"
+# Expected: all 7 ArchUnit rules pass
+```
+
+### 4. Unit Tests
+```bash
+mvn test
+# Expected: 0 failures, 0 errors
+```
+
+### 5. Full Verification
+```bash
+mvn verify
+# Expected: BUILD SUCCESS
+```
+
+### 6. Static Analysis (if configured)
+```bash
+# SpotBugs, PMD CPD, OWASP dependency check
+```
+
+## Evidence Rules
+
+- ❌ "Tests should pass" → running isn't evidence
+- ❌ "I didn't break anything" → verification is evidence
+- ✅ Show the actual output for each command
+- ✅ If a test fails, report the specific failure, don't bury it
+
+## Checklist
+
+- [ ] Formatting passes (spotless)
+- [ ] Compiles without errors
+- [ ] All tests pass (0 failures, 0 errors)
+- [ ] No new warnings (or documented)
+- [ ] `gitnexus_detect_changes()` confirms expected scope only