@ikieaneh/opencode-kit 0.5.7 → 0.5.9

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-kit",
   "description": "Standardized orchestration framework — contract-based, rules-enforced, zero-touch agent workflow",
-  "version": "0.4.0",
+  "version": "0.5.8",
   "author": {
     "name": "Rizki Rachman",
     "url": "https://github.com/RizkiRachman"

package/.opencode/plugins/opencode-kit.js

@@ -184,7 +184,6 @@ export const OpencodeKitPlugin = async ({ client, directory }) => {
 
       // Register user project skills FIRST (higher priority)
       const userSkillsDir = path.join(projectDir, '.opencode/skills');
-      const userSkillsDir = path.join(projectDir, '.opencode/skills');
       if (fs.existsSync(userSkillsDir) && !config.skills.paths.includes(userSkillsDir)) {
         config.skills.paths.push(userSkillsDir);
         log('info', `Registered user skills: ${userSkillsDir}`);

package/README.md

@@ -59,25 +59,67 @@
 <!-- ABOUT THE PROJECT -->
 ## About The Project
 
-`opencode-kit` is a portable orchestration framework for OpenCode-based AI agents. It solves one core problem:
+`opencode-kit` is a **workflow enforcement framework** for AI coding agents. It ensures agents follow a structured process — plan, build, review, learn — instead of jumping straight to implementation.
 
-**Agents skip the workflow and jump straight to implementation.**
+### The Problem
 
-Traditional agent frameworks use conventions (".md files say to load state first") but agents routinely bypass them because there's no enforcement. `opencode-kit` makes the workflow **machine-enforced**, not convention-based.
+AI agents (Claude, Copilot, etc.) are powerful but **unpredictable**. When given a task, they often:
 
-### How it works (v0.4 — Plugin Mode)
+- Skip project conventions and jump directly to writing code
+- Ignore shared state — each session starts from scratch
+- Bypass quality gates — no review, no scoring, no learning
+- Use different approaches on every run — inconsistent results
 
-With `opencode-kit` installed as an OpenCode plugin, enforcement is **global**. No per-project scaffolding needed.
+Traditional frameworks try to fix this with **prose in .md files** ("load the contract before any tool call"). But agents routinely ignore prose because there's no enforcement — it's a suggestion, not a requirement.
 
-1. **Plugin injects enforcement** — every session auto-loads the orchestration contract before any work
-2. **`contract.json`** — shared state machine every agent MUST read/write (local or global)
-3. **`rules.json`** — machine-readable rules with CRITICAL/HIGH severity
-4. **3 auto-registered skills** — `orchestration-template`, `scoring-pipeline`, `adr-generator`
-5. **Config resolution** — `.opencode/` → `~/.config/opencode-kit/` → plugin defaults
+### The Solution
 
-### Built for macOS M-Series
+`opencode-kit` replaces prose conventions with **machine-readable enforcement**:
 
-Developed and tested on Apple Silicon (M1/M2/M3/M4). All scripts use portable POSIX shell with zero Linux-specific dependencies.
+| Instead of ... | opencode-kit uses ... |
+|:---------------|:----------------------|
+| "read the state file" | `contract.json` — a JSON state machine agents MUST read/write |
+| "follow the rules" | `rules.json` — CRITICAL rules BLOCK agents, HIGH rules FLAG them |
+| "check before editing" | `preflight.sh` — an enforcement gate that fails if rules aren't met |
+| "review your work" | **Scoring pipeline** — every output is scored (≥70 PASS, <50 BLOCK) |
+| "remember what you learned" | `postflight.sh` — auto-persists state + telemetry + lessons learned |
+
+The result: **zero-touch agent workflow**. Set a goal, and the system self-executes through Plan → Build → Review → Learn, pausing only when BLOCKED.
+
+### How It Works
+
+As an OpenCode **plugin**, `opencode-kit` injects enforcement into every session globally:
+
+1. **Plugin bootstrap** — every session auto-loads the orchestration contract before any work
+2. **Pre-flight gate** — validates branch, contract state, and rule compliance. BLOCKs on CRITICAL violations
+3. **Contract protocol** — shared state machine (`contract.json`) tracks phase, decisions, scores, telemetry
+4. **Scoring pipeline** — every subagent output scored. ≥70 PASS, 50-69 RETRY, <50 BLOCKED
+5. **ADR logging** — every architectural decision recorded in `decisions.adr_log[]`
+6. **Extension model** — project-specific skills in `.opencode/skills/` override plugin defaults
+
+### The 9 Built-in Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `orchestration-template` | Contract protocol, state machine, persistence rules |
+| `scoring-pipeline` | Tier 1 rule checks + Tier 2 LLM judge + verdict |
+| `adr-generator` | Architecture Decision Record format and auto-ID |
+| `qa-expert` | Test standards, edge cases, coverage goals |
+| `system-analyst` | Impact analysis, execution tracing, architecture checks |
+| `token-optimize` | Efficient reading, batching, and delegation |
+| `verification-before-completion` | Quality gates — formatting, compile, test, verify |
+| `learner` | Post-execution learning, memory persistence |
+| *(extensible)* | Create your own skills in `.opencode/skills/` |
+
+### Built for Cost-Efficient Models
+
+`opencode-kit` was designed for teams using **cost-optimized models** (DeepSeek V4 Flash, Gemini Flash, GPT-4o Mini, etc.) who want to compete with premium models through **process rigor**, not raw intelligence. The scoring pipeline and pre-flight enforcement create a quality floor that cheap models can meet through architecture, not model power.
+
+### Platform Support
+
+- **macOS M-Series** (Apple Silicon) — primary development target
+- **Linux** (Ubuntu) — CI-verified via GitHub Actions
+- **Any OpenCode-compatible environment** with `lean-ctx`, `gitnexus`, `graphify`
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -122,6 +164,17 @@ node --version    # ≥ 18
 git --version     # any recent version
 ```
 
+### Documentation Guides
+
+| Guide | Description |
+|-------|-------------|
+| [Contract Protocol](docs/guides/contract-protocol.md) | State machine, fields, resolution order |
+| [Scoring Pipeline](docs/guides/scoring-pipeline.md) | Tier 1 + Tier 2 + verdict |
+| [Troubleshooting](docs/guides/troubleshooting.md) | Common issues and solutions |
+| [Quickstart](docs/examples/QUICKSTART.md) | 6-step setup from scratch |
+| [Extension Skills](docs/examples/extension-skill-template.md) | Create project-specific skills |
+| [Model Configs](docs/examples/model-configs.md) | Provider configuration examples |
+
 ### Installation
 
 #### Option 1: Install as plugin (recommended)
@@ -224,6 +277,25 @@ INIT → PLAN → PLAN_SCORED → EXECUTE → EXECUTE_SCORED → REVIEW → REVI
 
 Each phase transition requires a score ≥70 to proceed.
 
+### CLI Commands
+
+Once installed, run these from the project root:
+
+| Command | Purpose |
+|---------|---------|
+| `bash .opencode/src/status.sh` | Dashboard — contract state, telemetry, rules |
+| `bash .opencode/src/doctor.sh` | Diagnostics — MCPs, contract, git, persistence |
+| `bash .opencode/src/analytics.sh` | Telemetry aggregation — phase times, cost estimates |
+| `bash .opencode/src/diff.sh` [branch1] [branch2] | Compare contract state between branches |
+| `bash .opencode/src/adr.sh` | Record a new Architecture Decision Record |
+| `bash .opencode/src/telemetry.sh` | View telemetry details |
+| `bash .opencode/src/new-skill.sh` <name> | Scaffold a new skill SKILL.md |
+| `bash .opencode/rules/validation.sh` | Validate rules compliance |
+| `npx opencode-kit --version` | Print version |
+| `npx opencode-kit --help` | Print help |
+
+
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 <!-- STRUCTURE -->
@@ -233,24 +305,42 @@ Each phase transition requires a score ≥70 to proceed.
 opencode-kit/
  ├── rules/
  │   ├── rules.json              ← Machine-enforceable rules (CRITICAL/HIGH/state machine)
- │   └── validation.sh           ← Validates agent actions against rules (future)
+ │   └── validation.sh           ← Validates agent actions against rules
  ├── src/
  │   ├── init.sh                 ← Scaffold into target project
  │   ├── preflight.sh            ← Envelope load gate (zero deps, fails if rules violated)
- │   ├── postflight.sh           ← Auto-persist + scoring pipeline
- │   └── verify.sh               ← Installation health check
+ │   ├── postflight.sh           ← Auto-persist + scoring pipeline + contract migration
+ │   ├── doctor.sh               ← Diagnostic command
+ │   ├── status.sh               ← Dashboard view
+ │   ├── diff.sh                 ← Compare contract across branches
+ │   ├── analytics.sh            ← Telemetry aggregation
+ │   ├── adr.sh                  ← ADR auto-generator
+ │   ├── telemetry.sh            ← Phase telemetry viewer
+ │   ├── new-skill.sh            ← Skill template generator
+ │   ├── update.sh               ← Pull latest from GitHub
+ │   ├── verify.sh               ← Installation health check
+ │   ├── platform.sh             ← Cross-platform detection
+ │   ├── global-config.sh        ← Config resolution chain
+ │   └── cli.js                  ← --version / --help
+ ├── skills/                     ← 9 auto-registered skills
  ├── templates/
- │   ├── contract.json           ← Shared state contract (renamed from "envelope")
- │   ├── superpowers-contract.json
- │   └── agents/
- │       ├── orchestrator.md
- │       ├── planner.md
- │       ├── task-manager.md
- │       ├── code-reviewer.md
- │       ├── learner.md
- │       └── fixer.md
- ├── package.json                ← npm publish for `npx opencode-kit init`
- └── README.md                   ← You are here
+ │   ├── contract.json           ← Shared state contract
+ │   ├── opencode-kit.schema.json ← Agent config schema
+ │   ├── judge-prompt.md          ← LLM judge prompt template
+ │   └── agents/                  ← 6 agent .md templates
+ ├── docs/
+ │   ├── guides/                  ← Usage guides (contract, scoring, troubleshooting)
+ │   ├── examples/                ← Quickstart, model configs, extension skills
+ │   └── plans/                   ← Implementation plans
+ ├── test/                       ← Integration + E2E tests (16 total)
+ ├── .github/workflows/          ← CI (ShellCheck + scaffold + tests)
+ ├── .opencode/plugins/          ← Plugin entry point
+ ├── .claude-plugin/             ← Plugin metadata
+ ├── package.json                ← npm publish
+ ├── CHANGELOG.md
+ ├── CONTRIBUTING.md
+ ├── RELEASE.md
+ └── ROADMAP.md
 ```
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>

package/docs/guides/contract-protocol.md

@@ -0,0 +1,67 @@
+# Contract Protocol
+
+The orchestrator contract (`contract.json`) is the single source of truth for every agent session.
+
+## What it does
+
+- Tracks **state** — what phase the workflow is in (INIT → PLAN → ... → COMPLETE)
+- Stores **requirements** — the goal, acceptance criteria, and constraints
+- Logs **decisions** — Architecture Decision Records (ADRs)
+- Records **scores** — quality metrics from the scoring pipeline
+- Captures **telemetry** — elapsed time, phases completed, agents used
+
+## 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
+- Score < 50 → BLOCKED
+- Max 3 retry attempts before escalation
+
+## Key Fields
+
+```json
+{
+  "state": "INIT",
+  "contract_version": "0.5.8",
+  "requirements": {
+    "goal": "What we're building",
+    "acceptance_criteria": ["testable condition 1"],
+    "constraints": ["must not..."]
+  },
+  "governance": {
+    "active_agent": "orchestrator",
+    "current_guidance": "Instructions for this session",
+    "extension_skills": ["java-conventions"],
+    "permissions": { "do": [], "dont": ["push to main"] }
+  },
+  "decisions": {
+    "adr_log": [
+      { "id": "ADR-001", "date": "2026-06-11", "title": "Use contract protocol", ... }
+    ]
+  },
+  "score": {
+    "combined": 85,
+    "verdict": "PASS"
+  },
+  "metrics": {
+    "phases_completed": ["INIT", "PLAN", "PLAN_SCORED"]
+  }
+}
+```
+
+## Resolution Order
+
+1. `.opencode/orchestration/contract.json` — project override
+2. `~/.config/opencode-kit/contract.json` — global defaults
+3. Plugin `templates/contract.json` — shipped defaults
+
+## CLI
+
+View contract state: `bash .opencode/src/status.sh`
+Compare across branches: `bash .opencode/src/diff.sh [branch1] [branch2]`

package/docs/guides/scoring-pipeline.md

@@ -0,0 +1,60 @@
+# Scoring Pipeline
+
+Every subagent output is scored before the next phase begins.
+
+## Tier 1 — Rule Checks
+
+Automatic checks run by the orchestrator. Start at 100, deduct per violation:
+
+| Check | Deduction |
+|-------|:---------:|
+| Schema valid (required fields present) | -15 |
+| Permissions violated | -40 |
+| Blast radius HIGH/CRITICAL | -40 |
+| Writing order wrong | -15 |
+| Fields missing | -15 |
+
+If subtotal < 70 → skip Tier 2, use subtotal as combined score.
+
+## Tier 2 — LLM Judge
+
+If Tier 1 score ≥ 70, the orchestrator runs a judge via `subtask()`.
+
+```json
+{
+  "score": 85,
+  "rationale": "All requirements met. Writing order correct.",
+  "missing_items": ["Test for null boundary case"]
+}
+```
+
+**Dimensions:**
+| Dimension | Max | What it evaluates |
+|-----------|:---:|-------------------|
+| Requirements | 40 | Does output satisfy goal + acceptance criteria? |
+| Governance | 30 | Follows rules.json + writing order? |
+| Completeness | 20 | All files created? Edge cases documented? |
+| Edge cases | 10 | Nulls, errors, boundaries covered? |
+
+## Tier 3 — Verdict
+
+| Combined Score | Verdict | Action |
+|:--------------:|:-------:|--------|
+| ≥ 70 | **PASS** | Advance to next phase |
+| 50–69 | **RETRY** | Increment retry count, re-delegate |
+| < 50 | **BLOCKED** | Escalate to user |
+
+## Configuration
+
+Thresholds and deductions are in `rules.json` → `scoring`:
+
+```json
+{
+  "scoring": {
+    "tier1": { "schema_valid_deduction": 15, ... },
+    "thresholds": { "pass": 70, "retry": 50, "max_attempts": 3 }
+  }
+}
+```
+
+Projects can override rule severity via `contract.json` → `validation.rule_overrides`.

package/docs/guides/troubleshooting.md

@@ -0,0 +1,78 @@
+# Troubleshooting Guide
+
+## Common Issues
+
+### Plugin doesn't load
+
+**Symptom**: Skills not available, contract not injected.
+
+**Checks:**
+1. Is `@ikieaneh/opencode-kit` in `opencode.json` plugin array? Must be **first**.
+2. Is it installed? `ls node_modules/@ikieaneh/opencode-kit`
+3. Is the plugin array syntax correct? `"plugin": ["@ikieaneh/opencode-kit"]`
+
+### Agent jumps straight to implementation
+
+**Symptom**: Agent starts working without loading contract.
+
+**Fix:** The plugin's `messages.transform` hook injects the bootstrap. Make sure:
+1. Plugin is first in the array
+2. No other plugin overrides the same hook
+3. Run `bash .opencode/src/doctor.sh` to verify
+
+### Contract not found
+
+**Symptom**: "Contract not found" error from preflight.
+
+**Solution:**
+```sh
+bash .opencode/src/doctor.sh
+# Or manually:
+mkdir -p .opencode/orchestration
+cp node_modules/@ikieaneh/opencode-kit/templates/contract.json .opencode/orchestration/contract.json
+```
+
+### Score below threshold
+
+**Symptom**: Workflow keeps retrying or gets blocked.
+
+**Check:**
+- Tier 1 violations (blast radius, permissions)
+- Tier 2 judge feedback — read `judge.missing_items`
+- Retry count — max 3 attempts before BLOCKED
+
+### ShellCheck fails in CI
+
+**Symptom**: GitHub Actions ShellCheck job fails.
+
+**Fix:** Run locally:
+```sh
+shellcheck src/*.sh rules/*.sh
+```
+Look for SC1091 (source path) or SC2001 (sed style) — most are info-level.
+
+### Scaffold test fails in CI
+
+**Symptom**: init.sh exits with error.
+
+**Check:**
+- Are all `mkdir -p` paths created before `cp`?
+- Run locally: `cd /tmp && git init && bash /path/to/init.sh`
+
+### Custom skill not loading
+
+**Symptom**: Skill referenced in opencode.json not available.
+
+**Solution:**
+1. Place skill at `.opencode/skills/<name>/SKILL.md`
+2. Verify frontmatter has `description:` field
+3. Verify SKILL.md starts with `---` (YAML frontmatter)
+4. Run `bash .opencode/src/doctor.sh` to verify
+
+## Diagnostics
+
+```sh
+bash .opencode/src/doctor.sh       # Full health check
+bash .opencode/src/status.sh       # Dashboard view
+bash .opencode/src/analytics.sh    # Telemetry analysis
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikieaneh/opencode-kit",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Standardized OpenCode orchestration framework — contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
   "license": "MIT",
   "author": "RizkiRachman",

package/rules/rules.json

@@ -88,7 +88,7 @@
     },
     {
       "id": "WRITE_001",
-      "severity": "CRITICAL",
+      "severity": "HIGH",
       "description": "Agent MUST follow writing order: Port → Service → Mapper → Adapter → Constants → Events → Tests",
       "condition": "writing_order_violation",
       "action": "FLAG",

package/src/adr.sh

@@ -5,6 +5,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 CONTRACT_FILE=".opencode/orchestration/contract.json"
@@ -85,30 +86,42 @@ if [ -n "$DUP" ]; then
   exit 0
 fi
 
-# --- Build ADR entry ---
-# --- Build ADR entry via heredoc to avoid nested quote issues ---
+# --- Build ADR entry via temp JSON file (avoids shell injection) ---
+# Write ADR fields to temp file to avoid shell interpolation into Python
+ADR_DATA=$(mktemp /tmp/opencode-adr-data-XXXXX.json)
+cat > "$ADR_DATA" << ADRDATA
+{
+  "title": "$TITLE",
+  "context": "$CONTEXT",
+  "decision": "$DECISION",
+  "alternatives": "$ALTERNATIVES",
+  "consequences": "$CONSEQUENCES"
+}
+ADRDATA
+
 $PYTHON_CMD -c "
-import json, sys, os
+import json
 
-title = '$TITLE'
-date_val = '$(date +%Y-%m-%d)'
-next_id = '$NEXT_ID'
+with open('$ADR_DATA') as f:
+    data = json.load(f)
 
 entry = {
-  'id': next_id,
-  'date': date_val,
-  'title': title,
-  'context': '''$(echo "$CONTEXT" | sed "s/'/\\\\'/g")''',
-  'decision': '''$(echo "$DECISION" | sed "s/'/\\\\'/g")''',
-  'alternatives': '''$(echo "$ALTERNATIVES" | sed "s/'/\\\\'/g")''',
-  'consequences': '''$(echo "$CONSEQUENCES" | sed "s/'/\\\\'/g")'''
+  'id': '$NEXT_ID',
+  'date': '$(date +%Y-%m-%d)',
+  'title': data['title'],
+  'context': data['context'],
+  'decision': data['decision'],
+  'alternatives': data['alternatives'],
+  'consequences': data['consequences']
 }
 
 with open('/tmp/opencode-adr-entry.json', 'w') as f:
-  json.dump(entry, f, indent=2)
+    json.dump(entry, f, indent=2)
 print('Entry written')
 "
 
+rm -f "$ADR_DATA"
+
 # --- Inject into contract.json ---
 $PYTHON_CMD -c "
 import json

package/src/analytics.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 TELEMETRY_DIR=".opencode/telemetry"
@@ -68,7 +69,7 @@ for p in phases:
     frm = p.get('from', '?')
     to = p.get('to', '?')
     ms = p.get('elapsed_ms', 0)
-    bar = '█' * max(1, int(ms / max(1, total_ms) * 30))
+    bar = '#' * max(1, int(ms / max(1, total_ms) * 30))
     print(f'    {frm:16s} → {to:16s}  {ms/1000:6.1f}s  {bar}')
 
 # Cost estimate (rough: ~$0.15/1M tokens, ~1000 tok/s)

package/src/diff.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# opencode-kit diff — compare contract state between branches
+# Usage: bash src/diff.sh [branch1] [branch2]
+#   Default: compares current branch vs main
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
+. "$SCRIPT_DIR/platform.sh"
+
+CONTRACT_FILE=".opencode/orchestration/contract.json"
+BRANCH_A="${1:-main}"
+BRANCH_B="${2:-HEAD}"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${CYAN}📋 opencode-kit diff: $BRANCH_A ↔ $BRANCH_B${NC}"
+echo ""
+
+# Extract contract from a git ref
+get_contract_state() {
+  local branch="$1"
+  local content
+  content=$(git show "$branch:$CONTRACT_FILE" 2>/dev/null || echo "")
+  if [ -z "$content" ]; then
+    echo ""
+    return 1
+  fi
+  echo "$content"
+}
+
+CONTRACT_A=$(get_contract_state "$BRANCH_A")
+CONTRACT_B=$(get_contract_state "$BRANCH_B")
+
+if [ -z "$CONTRACT_A" ] && [ -z "$CONTRACT_B" ]; then
+  echo -e "${YELLOW}No contract found in either branch.${NC}"
+  exit 0
+fi
+
+# Show state diff
+if [ -n "$PYTHON_CMD" ]; then
+  $PYTHON_CMD -c "
+import json, sys
+
+def get_state(c):
+    try:
+        d = json.loads(c)
+        return {
+            'state': d.get('state', '?'),
+            'goal': (d.get('requirements', {}) or {}).get('goal', '?'),
+            'score': (d.get('score', {}) or {}).get('combined', '?'),
+            'phases': (d.get('metrics', {}) or {}).get('phases_completed', []),
+            'adrs': len((d.get('decisions', {}) or {}).get('adr_log', [])),
+            'version': d.get('contract_version', '?')
+        }
+    except:
+        return None
+
+a = get_state('''$CONTRACT_A''') if '''$CONTRACT_A''' else None
+b = get_state('''$CONTRACT_B''') if '''$CONTRACT_B''' else None
+
+if a and b:
+    print(f'  Field                   $BRANCH_A          $BRANCH_B')
+    print(f'  {"-"*50}')
+    for field in ['state', 'goal', 'score', 'version']:
+        va = str(a.get(field, '?'))[:20]
+        vb = str(b.get(field, '?'))[:20]
+        marker = ' ←→' if va != vb else '   '
+        print(f'  {field:20s}  {va:20s} {marker} {vb:20s}')
+    print(f'  phases                 {len(a.get(\"phases\",[])):3d} completed     {len(b.get(\"phases\",[])):3d} completed')
+    print(f'  ADRs                   {a.get(\"adrs\",0):3d} recorded      {b.get(\"adrs\",0):3d} recorded')
+elif a and not b:
+    print(f'  Contract exists in $BRANCH_A but NOT in $BRANCH_B')
+    print(f'  State: {a.get(\"state\",\"?\")}')
+elif b and not a:
+    print(f'  Contract exists in $BRANCH_B but NOT in $BRANCH_A')
+    print(f'  State: {b.get(\"state\",\"?\")}')
+" 2>/dev/null || echo -e "${YELLOW}Could not parse contract JSON${NC}"
+fi
+
+# Raw git diff
+echo ""
+echo -e "${CYAN}Raw diff:${NC}"
+if git diff "$BRANCH_A" "$BRANCH_B" -- "$CONTRACT_FILE" 2>/dev/null | head -40; then
+  if ! git diff --exit-code "$BRANCH_A" "$BRANCH_B" -- "$CONTRACT_FILE" &>/dev/null; then
+    :
+  fi
+fi
+echo ""
+echo -e "Run: ${GREEN}bash .opencode/src/diff.sh${NC} (default: main vs HEAD)"
+echo -e "     ${GREEN}bash .opencode/src/diff.sh staging feature-x${NC} (custom branches)"

package/src/doctor.sh

@@ -5,6 +5,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 . "$SCRIPT_DIR/global-config.sh"
 

package/src/global-config.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"

package/src/init.sh

@@ -6,6 +6,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 . "$SCRIPT_DIR/global-config.sh"
 KIT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -88,7 +89,7 @@ if [ -d ".opencode" ]; then
 fi
 
 # --- Scaffold directories ---
-mkdir -p .opencode/orchestration .opencode/rules .opencode/agents .opencode/src
+mkdir -p .opencode/orchestration .opencode/rules .opencode/agents .opencode/src .opencode/templates
 
 # --- Copy templates ---
 echo ""
@@ -154,6 +155,10 @@ if [ "$PLUGIN_MODE" = false ]; then
   chmod +x .opencode/src/analytics.sh
   echo "  ✅ analytics.sh (executable)"
 
+  cp "$KIT_DIR/src/diff.sh" .opencode/src/diff.sh
+  chmod +x .opencode/src/diff.sh
+  echo "  ✅ diff.sh (executable)"
+
   # --- Copy agent templates (pre-flight gates) ---
   for agent in orchestrator planner task-manager code-reviewer learner fixer; do
     if [ -f "$KIT_DIR/templates/agents/$agent.md" ]; then
@@ -175,9 +180,9 @@ echo ""
 echo "[opencode-kit] Running verification..."
 if "$KIT_DIR/src/verify.sh"; then
   echo ""
-  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-  echo -e "${GREEN}  ✅ opencode-kit v0.5.0 initialized${NC}"
-  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo -e "${GREEN}========================================${NC}"
+  echo -e "${GREEN}  ✅ opencode-kit initialized (version: $(cat "$KIT_DIR/package.json" | grep '"version"' | head -1 | cut -d'"' -f4))${NC}"
+  echo -e "${GREEN}========================================${NC}"
   echo ""
   echo "  Next steps:"
   echo "  1. Set GOAL & SCOPE in .opencode/orchestration/contract.json"

package/src/postflight.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 CONTRACT_KEY="orchestration-contract"
@@ -12,6 +13,7 @@ STATE_FILE="STATE.md"
 TELEMETRY_DIR=".opencode/telemetry"
 START_TIME_FILE=".opencode/telemetry/.phase_start"
 STATE_BACKUP_DIR=".opencode/state"
+TEMPLATE_FILE=".opencode/templates/contract.json"
 
 mkdir -p "$TELEMETRY_DIR" "$STATE_BACKUP_DIR"
 
@@ -46,6 +48,46 @@ if [ -z "$CURRENT_CONTRACT" ]; then
   fi
 fi
 
+# --- Step 1b: Contract migration (auto-upgrade old schema) ---
+if [ -n "$CURRENT_CONTRACT" ] && [ -f "$TEMPLATE_FILE" ] && [ -n "$PYTHON_CMD" ]; then
+  MIGRATED=$($PYTHON_CMD -c "
+import json
+
+try:
+    contract = json.loads('''$CURRENT_CONTRACT''')
+    with open('$TEMPLATE_FILE') as f:
+        template = json.load(f)
+
+    # Check version
+    old_ver = contract.get('contract_version', '0.0.0')
+    new_ver = template.get('contract_version', '0.5.2')
+
+    if old_ver == new_ver and all(k in contract for k in ['state','requirements','governance','score']):
+        print('NO_MIGRATION')
+    else:
+        # Merge missing top-level fields from template
+        for key in template:
+            if key not in contract:
+                contract[key] = template[key]
+        # Merge governance.extension_skills if missing
+        if 'extension_skills' not in contract.get('governance', {}):
+            if 'governance' not in contract:
+                contract['governance'] = {}
+            contract['governance']['extension_skills'] = []
+        # Update version
+        contract['contract_version'] = new_ver
+        print(json.dumps(contract))
+except Exception as e:
+    print('MIGRATE_ERROR:'+str(e))
+" 2>/dev/null || echo "MIGRATE_ERROR")
+
+  if [ -n "$MIGRATED" ] && [ "$MIGRATED" != "NO_MIGRATION" ] && [ "$MIGRATED" != "MIGRATE_ERROR" ]; then
+    CURRENT_CONTRACT="$MIGRATED"
+    echo "$MIGRATED" > "$CONTRACT_FILE"
+    echo "  🔄 Contract migrated to v$(echo "$MIGRATED" | $PYTHON_CMD -c "import sys,json; print(json.load(sys.stdin).get('contract_version','?'))" 2>/dev/null)"
+  fi
+fi
+
 # --- Step 2: Persist (try lean-ctx first, fall back to file) ---
 PERSISTED=false
 if lean-ctx ctx_knowledge remember \

package/src/preflight.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 CONTRACT_KEY="orchestration-contract"

package/src/status.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 CONTRACT_FILE=".opencode/orchestration/contract.json"
@@ -18,9 +19,9 @@ BOLD='\033[1m'
 NC='\033[0m'
 
 echo ""
-echo -e "${CYAN}${BOLD}╔══════════════════════════════════════════╗${NC}"
-echo -e "${CYAN}${BOLD}║        opencode-kit Dashboard            ║${NC}"
-echo -e "${CYAN}${BOLD}╚══════════════════════════════════════════╝${NC}"
+echo -e "${CYAN}${BOLD}##══════════════════════════════════════════╗${NC}"
+echo -e "${CYAN}${BOLD}#        opencode-kit Dashboard            #${NC}"
+echo -e "${CYAN}${BOLD}##══════════════════════════════════════════╝${NC}"
 echo ""
 
 # === Contract State ===
@@ -93,10 +94,8 @@ with open('$RULES_FILE') as f:
 rules = r.get('rules', [])
 critical = [x for x in rules if x.get('severity') == 'CRITICAL']
 high = [x for x in rules if x.get('severity') == 'HIGH']
-required_mcps = list(r.get('required_mcps', {}).keys())
-required_mcps = [m for m in required_mcps if m != 'description']
-mcps = list(r.get('required_mcps', {}).keys())
-mcps = [m for m in mcps if m != 'description']
+    mcps = list(r.get('required_mcps', {}).keys())
+    mcps = [m for m in mcps if m != 'description']
 print(f'  {len(critical)} CRITICAL rules, {len(high)} HIGH rules')
 if mcps:
     print(f'  Required MCPs: {\", \".join(mcps)}')

package/src/telemetry.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 TELEMETRY_DIR=".opencode/telemetry"
@@ -36,7 +37,7 @@ case "$MODE" in
         FROM=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('from','?'))" 2>/dev/null)
         TO=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('to','?'))" 2>/dev/null)
         MS=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('elapsed_ms',0))" 2>/dev/null)
-        printf "  %-20s → %-20s  %5.1fs\n" "$FROM" "$TO" "$(echo "scale=1; $MS/1000" | bc 2>/dev/null || echo "$((MS/1000)).$((MS%1000/100))")"
+        printf "  %-20s → %-20s  %5.1fs\n" "$FROM" "$TO" "$($PYTHON_CMD -c "print($MS/1000)" 2>/dev/null || echo "0.0")"
       done
     else
       echo -e "${YELLOW}No phase data yet.${NC}"

package/src/update.sh

@@ -5,6 +5,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 RED='\033[0;31m'

package/templates/contract.json

@@ -68,7 +68,7 @@
     "rules": { "pass": 0, "fail": 0, "deduction": 0, "subtotal": 0 },
     "judge": { "score": 0, "rationale": "", "missing_items": [] },
     "combined": 0,
-    "verdict": "PENDING"
+    "verdict": "INIT"
   },
   "retry": {
     "current_phase": null,