@ikieaneh/opencode-kit 0.6.0 → 0.6.1

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.6.0",
+  "version": "0.6.1",
   "author": {
     "name": "Rizki Rachman",
     "url": "https://github.com/RizkiRachman"

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

@@ -210,6 +210,28 @@ export const OpencodeKitPlugin = async ({ client, directory }) => {
       const bootstrap = getBootstrapContent();
       if (!bootstrap || !output.messages.length) return;
 
+      // Check contract for rule_overrides and inject them into bootstrap
+      const contractPath = path.join(projectDir, '.opencode', 'orchestration', 'contract.json');
+      let finalBootstrap = bootstrap;
+      if (fs.existsSync(contractPath)) {
+        try {
+          const contractRaw = fs.readFileSync(contractPath, 'utf8');
+          const contract = JSON.parse(contractRaw);
+          if (contract.validation && contract.validation.rule_overrides) {
+            const overrides = contract.validation.rule_overrides;
+            const overrideKeys = Object.keys(overrides);
+            if (overrideKeys.length > 0) {
+              const overrideText = overrideKeys
+                .map(id => `  - ${id}: action → ${overrides[id]}`)
+                .join('\n');
+              finalBootstrap = bootstrap + `\n## Rule Overrides (from contract)\n\nThe following rule severities have been overridden:\n${overrideText}\n`;
+            }
+          }
+        } catch (err) {
+          log('warn', `Failed to parse contract for rule_overrides: ${err.message}`);
+        }
+      }
+
       const firstUser = output.messages.find(m => m.info.role === 'user');
       if (!firstUser || !firstUser.parts.length) return;
 
@@ -217,7 +239,7 @@ export const OpencodeKitPlugin = async ({ client, directory }) => {
       if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('opencode-kit'))) return;
 
       const ref = firstUser.parts[0];
-      firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
+      firstUser.parts.unshift({ ...ref, type: 'text', text: finalBootstrap });
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikieaneh/opencode-kit",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Standardized OpenCode orchestration framework — contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
   "license": "MIT",
   "author": "RizkiRachman",
@@ -41,6 +41,10 @@
     "type": "git",
     "url": "git+https://github.com/RizkiRachman/opencode-kit.git"
   },
+  "scripts": {
+    "lint": "eslint src/ test/",
+    "format": "prettier --check src/ test/"
+  },
   "bugs": {
     "url": "https://github.com/RizkiRachman/opencode-kit/issues"
   },

package/src/cli.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 /**
- * opencode-kit CLI — version and help
+ * opencode-kit CLI — version, help, and project commands
  * Usage: npx opencode-kit --version
  *        npx opencode-kit --help
+ *        npx opencode-kit doctor
+ *        npx opencode-kit status
+ *        npx opencode-kit analytics
  */
 import { fileURLToPath } from 'url';
 import path from 'path';
 import fs from 'fs';
+import { spawnSync } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkgPath = path.resolve(__dirname, '../package.json');
@@ -27,10 +31,13 @@ Usage:
   npx opencode-kit [command]
 
 Commands:
-  init [--force]    Scaffold orchestration framework into project
-  update [--dry-run] Pull latest templates from GitHub
-  --version, -v     Print version
-  --help, -h        Print this help
+  init [--force]         Scaffold orchestration framework into project
+  update [--dry-run]     Pull latest templates from GitHub
+  doctor                 Run project health checks
+  status                 Show project status
+  analytics              Show project analytics
+  --version, -v          Print version
+  --help, -h             Print this help
 
 Plugin mode:
   Add "opencode-kit" to opencode.json plugin array (FIRST position).
@@ -45,3 +52,38 @@ Docs: ${pkg.homepage}
 `);
   process.exit(0);
 }
+
+/**
+ * Walk up from startDir to find a directory containing .opencode/
+ */
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.opencode'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+const commands = {
+  doctor: '.opencode/src/doctor.sh',
+  status: '.opencode/src/status.sh',
+  analytics: 'src/analytics.sh',
+};
+
+const command = args[0];
+
+if (commands[command]) {
+  const projectRoot = findProjectRoot(path.resolve(__dirname, '..'));
+
+  if (!projectRoot) {
+    console.error('Not in an opencode-kit project');
+    process.exit(1);
+  }
+
+  const scriptPath = path.resolve(projectRoot, commands[command]);
+  const result = spawnSync('bash', [scriptPath], { stdio: 'inherit', cwd: projectRoot });
+  process.exit(result.status);
+}

package/src/doctor.sh

@@ -42,6 +42,32 @@ else
   fi
 fi
 
+# === 1b. Contract schema validation ===
+SCHEMA_FILE=".opencode/templates/contract.schema.json"
+if [ -f "$CONTRACT_FILE" ] && [ -f "$SCHEMA_FILE" ] && [ -n "$PYTHON_CMD" ]; then
+  if $PYTHON_CMD -c "
+import json, sys
+with open('$CONTRACT_FILE') as f: contract = json.load(f)
+with open('$SCHEMA_FILE') as f: schema = json.load(f)
+# Basic required-field validation
+errors = []
+if not contract.get('state'): errors.append('Missing state')
+if not contract.get('requirements', {}).get('goal'): errors.append('Missing requirements.goal')
+if contract.get('state') not in ['INIT','PLAN','PLAN_SCORED','EXECUTE','EXECUTE_SCORED','REVIEW','REVIEW_SCORED','COMPLETE','BLOCKED']:
+  errors.append('Invalid state')
+if errors:
+  print('; '.join(errors))
+  sys.exit(1)
+else:
+  print('OK')
+" 2>/dev/null; then
+    echo -e "  ✅ Contract schema valid"
+  else
+    echo -e "  ⚠️  Contract schema issues found (non-blocking)"
+    ISSUES=$((ISSUES + 1))
+  fi
+fi
+
 # === 2. Rules check ===
 echo -e "${CYAN}[RULES]${NC} Checking rules.json..."
 if [ ! -f "$RULES_FILE" ]; then
@@ -54,7 +80,7 @@ else
   fi
 fi
 
-# === 3. MCP checks ===
+# === 3a. MCP CLI checks ===
 echo -e "${CYAN}[MCP]${NC} Checking required MCPs..."
 if [ -f "$RULES_FILE" ] && [ -n "$PYTHON_CMD" ]; then
   $PYTHON_CMD -c "
@@ -78,6 +104,16 @@ for name, cfg in mcps.items():
 " 2>/dev/null || ISSUES=$((ISSUES + 1))
 fi
 
+# === 3b. MCP connectivity ===
+echo -e "${CYAN}[MCP_CONNECT]${NC} Testing MCP connectivity..."
+if command -v lean-ctx &>/dev/null; then
+  if lean-ctx ctx_knowledge status &>/dev/null 2>&1; then
+    echo -e "  ✅ lean-ctx MCP: responding"
+  else
+    echo -e "  ⚠️  lean-ctx CLI found but MCP not responding (expected in CI)"
+  fi
+fi
+
 # === 4. Git branch ===
 echo -e "${CYAN}[GIT]${NC} Checking branch..."
 BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")

package/src/init.sh

@@ -168,6 +168,13 @@ if [ "$PLUGIN_MODE" = false ]; then
   done
 fi
 
+# --- Copy git hooks ---
+if [ -d "$KIT_DIR/.githooks" ]; then
+  cp -r "$KIT_DIR/.githooks" .githooks
+  chmod +x .githooks/pre-commit .githooks/commit-msg
+  echo "  ✅ .githooks/ (pre-commit, commit-msg)"
+fi
+
 # --- Git ignore .opencode/src (scripts are project-specific) ---
 if [ -f ".gitignore" ]; then
   if ! grep -q ".opencode/src" .gitignore 2>/dev/null; then
@@ -175,6 +182,12 @@ if [ -f ".gitignore" ]; then
   fi
 fi
 
+# --- Configure git hooks ---
+if [ -d ".githooks" ]; then
+  git config core.hooksPath .githooks
+  echo "  ✅ Git hooks configured (.githooks/)"
+fi
+
 # --- Verify ---
 echo ""
 echo "[opencode-kit] Running verification..."

package/src/postflight.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""postflight helper — batch all contract/telemetry/STATE.md operations in one call.
+
+Replaces 11 separate inline Python invocations from postflight.sh with a single
+script that handles: contract read/migration, phase telemetry, summary update,
+STATE.md generation, and contract file persistence.
+
+Usage:
+    postflight.py CONTRACT_FILE TELEMETRY_DIR STATE_FILE STATE_BACKUP_DIR TEMPLATE_FILE [NEW_STATE]
+
+Returns JSON to stdout with extracted values for shell-level echo/log messages.
+"""
+import json
+import os
+import sys
+import datetime
+
+
+def main() -> int:
+    # --- Parse arguments ---
+    contract_file = sys.argv[1] if len(sys.argv) > 1 else '.opencode/orchestration/contract.json'
+    telemetry_dir = sys.argv[2] if len(sys.argv) > 2 else '.opencode/telemetry'
+    state_file = sys.argv[3] if len(sys.argv) > 3 else 'STATE.md'
+    state_backup_dir = sys.argv[4] if len(sys.argv) > 4 else '.opencode/state'
+    template_file = sys.argv[5] if len(sys.argv) > 5 else '.opencode/templates/contract.json'
+    new_state = sys.argv[6] if len(sys.argv) > 6 else None
+
+    start_time_file = os.path.join(telemetry_dir, '.phase_start')
+    phases_file = os.path.join(telemetry_dir, 'phases.jsonl')
+    summary_file = os.path.join(telemetry_dir, 'summary.json')
+
+    now = datetime.datetime.now(datetime.UTC)
+    now_iso = now.strftime('%Y-%m-%dT%H:%M:%SZ')
+
+    # --- Load contract (file or template fallback) ---
+    contract = {}
+    if os.path.exists(contract_file):
+        with open(contract_file) as f:
+            contract = json.load(f)
+    elif os.path.exists(template_file):
+        with open(template_file) as f:
+            contract = json.load(f)
+
+    prev_state = contract.get('state', 'INIT')
+
+    # --- Update state if provided ---
+    if new_state:
+        contract['state'] = new_state
+
+    current_state = contract.get('state', 'UNKNOWN')
+
+    # --- Read start time and calculate phase elapsed ---
+    os.makedirs(telemetry_dir, exist_ok=True)
+    phase_elapsed_ms = 0
+    if os.path.exists(start_time_file):
+        with open(start_time_file) as f:
+            raw = f.read().strip()
+        if raw:
+            try:
+                start_ts = int(raw)
+                phase_elapsed_ms = int((now.timestamp() - start_ts) * 1000)
+            except ValueError:
+                pass
+        os.remove(start_time_file)
+
+    # --- Read last 'to' state from phases.jsonl for telemetry ---
+    last_to_state = 'INIT'
+    if os.path.exists(phases_file):
+        lines = [l.strip() for l in open(phases_file) if l.strip()]
+        if lines:
+            try:
+                last_to_state = json.loads(lines[-1]).get('to', 'INIT')
+            except json.JSONDecodeError:
+                pass
+
+    # --- Record phase telemetry ---
+    phase_entry = {
+        'ts': now_iso,
+        'from': last_to_state,
+        'to': current_state,
+        'elapsed_ms': phase_elapsed_ms,
+    }
+    with open(phases_file, 'a') as f:
+        f.write(json.dumps(phase_entry) + '\n')
+
+    # --- Contract migration (merge missing fields from template) ---
+    migrated = False
+    if os.path.exists(template_file):
+        with open(template_file) as f:
+            template = json.load(f)
+
+        old_ver = contract.get('contract_version', '0.0.0')
+        new_ver = template.get('contract_version', '0.5.2')
+
+        needs_migration = (
+            old_ver != new_ver
+            or not all(k in contract for k in ['state', 'requirements', 'governance', 'score'])
+        )
+
+        if needs_migration:
+            for key in template:
+                if key not in contract:
+                    contract[key] = template[key]
+            if 'extension_skills' not in contract.get('governance', {}):
+                contract.setdefault('governance', {})['extension_skills'] = []
+            contract['contract_version'] = new_ver
+            migrated = True
+
+    # --- Write contract to primary location ---
+    os.makedirs(os.path.dirname(contract_file) or '.', exist_ok=True)
+    with open(contract_file, 'w') as f:
+        json.dump(contract, f, indent=2)
+
+    # --- Backup contract to state backup dir ---
+    os.makedirs(state_backup_dir, exist_ok=True)
+    with open(os.path.join(state_backup_dir, 'contract.json'), 'w') as f:
+        json.dump(contract, f, indent=2)
+
+    # --- Update telemetry summary.json ---
+    total_ms = 0
+    phases = []
+    if os.path.exists(phases_file):
+        with open(phases_file) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                    total_ms += entry.get('elapsed_ms', 0)
+                    phases.append(entry.get('to', ''))
+                except json.JSONDecodeError:
+                    pass
+
+    summary = {
+        'phases_completed': phases,
+        'total_elapsed_ms': total_ms,
+        'total_elapsed_s': round(total_ms / 1000, 1),
+        'updated_at': now_iso,
+    }
+    with open(summary_file, 'w') as f:
+        json.dump(summary, f, indent=2)
+
+    # --- Extract values for STATE.md ---
+    retry = contract.get('retry', {})
+    score_obj = contract.get('score', {})
+    state_val = contract.get('state', 'UNKNOWN')
+    phase_val = retry.get('current_phase', 'none')
+    score_combined = str(score_obj.get('combined', '?'))
+
+    # Issues / blockers
+    issues = retry.get('issues', [])
+    issues_blockers = '\n'.join(f'- {i}' for i in issues) if issues else 'None'
+
+    # ADRs (last 3)
+    adr_log = contract.get('decisions', {}).get('adr_log', [])
+    if adr_log:
+        adr_lines = '\n'.join(
+            f'- {e.get("id", "?")}: {e.get("title", "")}' for e in adr_log[-3:]
+        )
+    else:
+        adr_lines = 'No ADRs recorded'
+
+    # Last completed phase
+    metrics_phases = contract.get('metrics', {}).get('phases_completed', [])
+    last_phase = metrics_phases[-1] if metrics_phases else 'INIT'
+
+    # --- Write STATE.md ---
+    state_md = (
+        '# Project State\n'
+        '\n'
+        '## Current Focus\n'
+        f'Agent orchestration — {state_val} (phase: {phase_val}). Score: {score_combined}.\n'
+        '\n'
+        '## Known Blockers\n'
+        f'{issues_blockers}\n'
+        '\n'
+        '## Active Decisions\n'
+        f'{adr_lines}\n'
+        '\n'
+        '## Recent Changes\n'
+        f'- Last state transition: {last_phase}\n'
+    )
+    state_dir = os.path.dirname(state_file)
+    if state_dir:
+        os.makedirs(state_dir, exist_ok=True)
+    with open(state_file, 'w') as f:
+        f.write(state_md)
+
+    # --- Output JSON summary for shell script consumption ---
+    output = {
+        'state': state_val,
+        'phase': phase_val,
+        'score': score_combined,
+        'prev_state': prev_state,
+        'current_state': current_state,
+        'phase_elapsed_ms': phase_elapsed_ms,
+        'phase_elapsed_s': round(phase_elapsed_ms / 1000, 1),
+        'migrated': migrated,
+        'contract_version': contract.get('contract_version', '?'),
+        'phases_count': len(phases),
+        'total_elapsed_s': summary['total_elapsed_s'],
+        'issues_count': len(issues),
+        'last_to_state': last_to_state,
+    }
+    print(json.dumps(output))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/src/postflight.sh

@@ -11,7 +11,6 @@ CONTRACT_KEY="orchestration-contract"
 CONTRACT_FILE=".opencode/orchestration/contract.json"
 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"
 
@@ -19,171 +18,65 @@ mkdir -p "$TELEMETRY_DIR" "$STATE_BACKUP_DIR"
 
 echo "[opencode-kit] Post-flight: persisting state..."
 
-# --- Telemetry: record phase completion ---
-mkdir -p "$TELEMETRY_DIR"
-PHASE_START=$(cat "$START_TIME_FILE" 2>/dev/null || echo "")
-if [ -n "$PHASE_START" ]; then
-  PHASE_ELAPSED=$(( $(date +%s) - PHASE_START ))
-  # Read current state from contract
-  if [ -f "$CONTRACT_FILE" ]; then
-    CURRENT_STATE=$($PYTHON_CMD -c "
-import json
-with open('$CONTRACT_FILE') as f: d=json.load(f)
-print(d.get('state','UNKNOWN'))
-" 2>/dev/null || echo "UNKNOWN")
-    PREV_STATE=""
-    [ -f "$TELEMETRY_DIR/phases.jsonl" ] && PREV_STATE=$(tail -1 "$TELEMETRY_DIR/phases.jsonl" 2>/dev/null | $PYTHON_CMD -c "import sys,json; print(json.load(sys.stdin).get('to','INIT'))" 2>/dev/null || echo "INIT")
-    echo "{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"from\":\"$PREV_STATE\",\"to\":\"$CURRENT_STATE\",\"elapsed_ms\":$((PHASE_ELAPSED * 1000))}" >> "$TELEMETRY_DIR/phases.jsonl"
-    echo "  📊 Telemetry: $PREV_STATE → $CURRENT_STATE (${PHASE_ELAPSED}s)"
-  fi
-  rm -f "$START_TIME_FILE"
+# --- Resolve contract: try lean-ctx first, fall back to file ---
+LEAN_CTX_CONTRACT=$(lean-ctx ctx_knowledge recall --query "$CONTRACT_KEY" 2>/dev/null || true)
+if [ -n "$LEAN_CTX_CONTRACT" ]; then
+  echo "$LEAN_CTX_CONTRACT" > "$CONTRACT_FILE"
 fi
 
-# --- Step 1: Read contract (try lean-ctx first, fall back to file) ---
-CURRENT_CONTRACT=$(lean-ctx ctx_knowledge recall --query "$CONTRACT_KEY" 2>/dev/null || cat "$CONTRACT_FILE" 2>/dev/null || echo "")
-if [ -z "$CURRENT_CONTRACT" ]; then
-  echo "  ⚠️  No contract found in lean-ctx or file. Creating new from template..."
-  if [ -f "$TEMPLATE_FILE" ]; then
-    CURRENT_CONTRACT=$(cat "$TEMPLATE_FILE")
+# --- Single Python call: batch all contract/telemetry/STATE.md operations ---
+PYTHON_OUTPUT=""
+STATE=""
+if [ -n "$PYTHON_CMD" ]; then
+  PYTHON_OUTPUT=$($PYTHON_CMD "$SCRIPT_DIR/postflight.py" \
+    "$CONTRACT_FILE" "$TELEMETRY_DIR" "$STATE_FILE" \
+    "$STATE_BACKUP_DIR" "$TEMPLATE_FILE" \
+  )
+
+  # Single Python parse call: extract all values as pipe-delimited string
+  IFS='|' read -r STATE PHASE SCORE PREV_STATE CURRENT_STATE ELAPSED_S MIGRATED CONTRACT_VER PHASES_COUNT TOTAL_ELAPSED_S LAST_TO_STATE <<< \
+    "$(echo "$PYTHON_OUTPUT" | $PYTHON_CMD -c "
+import sys, json
+d = json.load(sys.stdin)
+print('|'.join([str(d.get(k, '')) for k in [
+    'state', 'phase', 'score', 'prev_state', 'current_state',
+    'phase_elapsed_s', 'migrated', 'contract_version',
+    'phases_count', 'total_elapsed_s', 'last_to_state'
+]]))
+" 2>/dev/null || echo "UNKNOWN|none|?|INIT|UNKNOWN|0|false|?|0|0|INIT")"
+
+  # --- Echo status messages ---
+  echo "  📊 Telemetry: $PREV_STATE → $CURRENT_STATE (${ELAPSED_S}s)"
+
+  if [ "$MIGRATED" = "true" ]; then
+    echo "  🔄 Contract migrated to v${CONTRACT_VER}"
   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")
+  echo "  📝 Contract state: $STATE (phase: $PHASE, score: $SCORE)"
+  echo "  ✅ STATE.md synced"
 
-  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
+  echo "  📈 Telemetry summary: ${PHASES_COUNT} phases, ${TOTAL_ELAPSED_S}s total"
+else
+  echo "  ⚠️  Python not available, skipping postflight processing"
 fi
 
-# --- Step 2: Persist (try lean-ctx first, fall back to file) ---
-PERSISTED=false
-if lean-ctx ctx_knowledge remember \
-  category architecture \
-  key "$CONTRACT_KEY" \
-  value "$CURRENT_CONTRACT" 2>/dev/null; then
-  echo "  ✅ Contract persisted to lean-ctx"
-  PERSISTED=true
+# --- Persist to lean-ctx ---
+if [ -n "$PYTHON_CMD" ] && [ -f "$CONTRACT_FILE" ]; then
+  CONTRACT_JSON=$(cat "$CONTRACT_FILE")
+  if lean-ctx ctx_knowledge remember \
+    category architecture \
+    key "$CONTRACT_KEY" \
+    value "$CONTRACT_JSON" 2>/dev/null; then
+    echo "  ✅ Contract persisted to lean-ctx"
+  fi
 fi
 
-# File fallback: write to .opencode/state/contract.json
-echo "$CURRENT_CONTRACT" > "$STATE_BACKUP_DIR/contract.json"
+# File fallback always written by Python script to $STATE_BACKUP_DIR/contract.json
 echo "  ✅ Contract persisted to file: $STATE_BACKUP_DIR/contract.json"
 
-# --- Step 3: Sync STATE.md ---
-mkdir -p "$(dirname "$STATE_FILE")"
-if [ -f "$CONTRACT_FILE" ]; then
-  STATE=$(echo "$CURRENT_CONTRACT" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('state','UNKNOWN'))" 2>/dev/null || echo "UNKNOWN")
-  PHASE=$(echo "$CURRENT_CONTRACT" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); r=d.get('retry',{}); print(r.get('current_phase','none'))" 2>/dev/null || echo "none")
-  SCORE=$(echo "$CURRENT_CONTRACT" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); s=d.get('score',{}); print(s.get('combined','?'))" 2>/dev/null || echo "?")
-  echo "  📝 Contract state: $STATE (phase: $PHASE, score: $SCORE)"
-
-  # Create or update STATE.md with current focus
-  cat > "$STATE_FILE" << STATEMD
-# Project State
-
-## Current Focus
-Agent orchestration — $STATE (phase: ${PHASE:-none}). Score: $SCORE.
-
-## Known Blockers
-$(echo "$CURRENT_CONTRACT" | $PYTHON_CMD -c "
-import sys,json
-d=json.load(sys.stdin)
-r=d.get('retry',{})
-issues=r.get('issues',[])
-if issues:
-  for i in issues: print(f'- {i}')
-else:
-  print('None')
-" 2>/dev/null || echo "None")
-
-## Active Decisions
-$(echo "$CURRENT_CONTRACT" | $PYTHON_CMD -c "
-import sys,json
-d=json.load(sys.stdin)
-log=d.get('decisions',{}).get('adr_log',[])
-if log:
-  for entry in log[-3:]:
-    print(f'- {entry.get(\"id\",\"?\")}: {entry.get(\"title\",\"\")}')
-else:
-  print('No ADRs recorded')
-" 2>/dev/null || echo "None")
-
-## Recent Changes
-- Last state transition: $(echo "$CURRENT_CONTRACT" | $PYTHON_CMD -c "
-import sys,json
-d=json.load(sys.stdin)
-phases=d.get('metrics',{}).get('phases_completed',[])
-print(phases[-1] if phases else 'INIT')
-" 2>/dev/null || echo "INIT")
-STATEMD
-  echo "  ✅ STATE.md synced"
-fi
-
-# --- Step 4: Save ctx_session ---
+# --- Save ctx_session ---
 lean-ctx ctx_session save 2>/dev/null && \
   echo "  ✅ Session saved" || \
   echo "  ⚠️  ctx_session save skipped (not available)"
 
-# --- Step 5: Update telemetry summary ---
-if [ -f "$TELEMETRY_DIR/phases.jsonl" ] && [ -n "$PYTHON_CMD" ]; then
-  $PYTHON_CMD -c "
-import json
-total_ms = 0
-agents = set()
-phases = []
-with open('$TELEMETRY_DIR/phases.jsonl') as f:
-  for line in f:
-    line=line.strip()
-    if not line: continue
-    try:
-      entry=json.loads(line)
-      total_ms+=entry.get('elapsed_ms',0)
-      phases.append(entry.get('to',''))
-    except: pass
-
-summary = {
-  'phases_completed': phases,
-  'total_elapsed_ms': total_ms,
-  'total_elapsed_s': round(total_ms/1000, 1),
-  'updated_at': '$(date -u +%Y-%m-%dT%H:%M:%SZ)'
-}
-with open('$TELEMETRY_DIR/summary.json', 'w') as f:
-  json.dump(summary, f, indent=2)
-print(f'  📈 Telemetry summary: {len(phases)} phases, {total_ms/1000:.0f}s total')
-" 2>/dev/null || true
-fi
-
 echo "[opencode-kit] ✅ Post-flight complete."

package/templates/contract.schema.json

@@ -0,0 +1,357 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://opencode.kit/schemas/contract.schema.json",
+  "title": "OpenCode Orchestration Contract Schema",
+  "description": "Validates the orchestration contract envelope used by OpenCode Kit agents for multi-agent coordination and state persistence.",
+  "type": "object",
+
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "http://json-schema.org/draft-07/schema#",
+      "description": "JSON Schema dialect identifier"
+    },
+
+    "state": {
+      "type": "string",
+      "enum": ["INIT", "PLAN", "PLAN_SCORED", "EXECUTE", "EXECUTE_SCORED", "REVIEW", "REVIEW_SCORED", "COMPLETE", "BLOCKED"],
+      "description": "Current lifecycle state of the contract"
+    },
+
+    "contract_version": {
+      "type": "string",
+      "description": "Semantic version of the contract schema"
+    },
+
+    "session": {
+      "type": "object",
+      "properties": {
+        "task_id": { "type": "string" },
+        "branch": { "type": "string" },
+        "created_at": { "type": "string" }
+      },
+      "additionalProperties": true,
+      "description": "Session metadata for traceability and resumption"
+    },
+
+    "scope": {
+      "type": "object",
+      "properties": {
+        "included": { "type": "array", "items": { "type": "string" } },
+        "excluded": { "type": "array", "items": { "type": "string" } },
+        "boundary": { "type": "string" },
+        "parallel_eligible": { "type": "boolean" },
+        "max_parallel_agents": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": true,
+      "description": "Work boundaries and parallelism controls"
+    },
+
+    "requirements": {
+      "type": "object",
+      "properties": {
+        "goal": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Primary objective of the task"
+        },
+        "scope": {
+          "type": "object",
+          "properties": {
+            "included": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "In-scope files, directories, or concerns"
+            },
+            "excluded": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Explicitly out-of-scope items"
+            },
+            "parallel_eligible": {
+              "type": "boolean",
+              "description": "Whether this goal supports parallel agent dispatch"
+            }
+          }
+        },
+        "success_criteria": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Measurable outcomes that define completion"
+        },
+        "acceptance_criteria": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "constraints": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Constraints and guardrails (may be object or array)"
+        }
+      },
+      "required": ["goal"],
+      "additionalProperties": true,
+      "description": "Task requirements, scope, and definition of done"
+    },
+
+    "decisions": {
+      "type": "object",
+      "properties": {
+        "approved_architecture": {
+          "anyOf": [
+            { "type": "string" },
+            { "type": "object" }
+          ],
+          "description": "Approved architecture decision or reference"
+        },
+        "coding_standard": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "rejected_approaches": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "adr_log": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "string" },
+              "title": { "type": "string" },
+              "status": { "type": "string" },
+              "date": { "type": "string" }
+            },
+            "additionalProperties": true
+          },
+          "description": "Architecture Decision Record log"
+        }
+      },
+      "additionalProperties": true,
+      "description": "Architectural decisions and rejected alternatives"
+    },
+
+    "governance": {
+      "type": "object",
+      "properties": {
+        "active_agent": { "type": "string" },
+        "mode": { "type": "string" },
+        "applicable_skills": { "type": "array", "items": { "type": "string" } },
+        "current_guidance": {
+          "type": "string",
+          "description": "Active execution guidance for the current agent"
+        },
+        "rules_references": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "source": { "type": "string" },
+              "sections": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            },
+            "required": ["source", "sections"]
+          },
+          "description": "References to rule documents governing execution"
+        },
+        "extension_skills": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Loaded extension skills for this session"
+        },
+        "permissions": {
+          "type": "object",
+          "properties": {
+            "do": { "type": "array", "items": { "type": "string" } },
+            "dont": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": true
+        },
+        "previous_blockers": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "decisions_log": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "agent": { "type": "string" },
+              "decision": { "type": "string" },
+              "timestamp": { "type": "string" }
+            },
+            "additionalProperties": true
+          },
+          "description": "Historical log of decisions made during execution"
+        }
+      },
+      "additionalProperties": true,
+      "description": "Governance and rule enforcement context"
+    },
+
+    "validation": {
+      "type": "object",
+      "properties": {
+        "block_on": {
+          "type": "object",
+          "properties": {
+            "max_test_failures": { "type": "integer", "minimum": 0 },
+            "max_score_drop": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "max_compile_errors": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": true
+        },
+        "rule_overrides": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true,
+      "description": "Validation thresholds that trigger BLOCKED state"
+    },
+
+    "score": {
+      "type": "object",
+      "properties": {
+        "rules": {
+          "type": "object",
+          "properties": {
+            "pass": { "type": "integer", "minimum": 0 },
+            "fail": { "type": "integer", "minimum": 0 },
+            "deduction": { "type": "number" },
+            "subtotal": { "type": "number" }
+          },
+          "description": "Rule-based scoring breakdown"
+        },
+        "judge": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "score": { "type": "integer", "minimum": 0, "maximum": 100 },
+                "rationale": { "type": "string" },
+                "missing_items": { "type": "array", "items": { "type": "string" } }
+              },
+              "additionalProperties": true
+            },
+            { "type": "null" }
+          ],
+          "description": "LLM judge evaluation (nullable)"
+        },
+        "combined": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Combined score (0-100)"
+        },
+        "verdict": {
+          "type": "string",
+          "enum": ["INIT", "PASS", "RETRY", "BLOCKED"],
+          "description": "Overall scoring verdict"
+        }
+      },
+      "additionalProperties": true,
+      "description": "Scoring and evaluation results"
+    },
+
+    "retry": {
+      "type": "object",
+      "properties": {
+        "attempt": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Current retry attempt number"
+        },
+        "max_attempts": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum allowed retry attempts"
+        },
+        "current_phase": {
+          "anyOf": [
+            { "type": "string" },
+            { "type": "null" }
+          ],
+          "description": "Phase being retried"
+        },
+        "score_threshold": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "escalation_threshold": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "issues": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of issues that triggered retry"
+        }
+      },
+      "additionalProperties": true,
+      "description": "Retry policy and issue tracking"
+    },
+
+    "outputs": {
+      "type": "object",
+      "properties": {
+        "plan": { "type": ["object", "null"] },
+        "architecture": { "type": ["object", "null"] },
+        "code_changes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "file": { "type": "string" },
+              "change_type": { "type": "string", "enum": ["create", "modify", "delete"] },
+              "summary": { "type": "string" }
+            },
+            "additionalProperties": true
+          }
+        },
+        "test_results": { "type": ["object", "null"] },
+        "agent_reports": {
+          "type": "array",
+          "items": { "type": "object" }
+        },
+        "score_summary": { "type": ["object", "null"] }
+      },
+      "additionalProperties": true,
+      "description": "Artifacts produced during execution"
+    },
+
+    "metrics": {
+      "type": "object",
+      "properties": {
+        "cost_tokens": { "type": "integer", "minimum": 0 },
+        "elapsed_ms": { "type": "integer", "minimum": 0 },
+        "agents_used": { "type": "array", "items": { "type": "string" } },
+        "phases_completed": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true,
+      "description": "Execution performance metrics"
+    },
+
+    "lessons_learned": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "category": { "type": "string" },
+          "insight": { "type": "string" },
+          "recommendation": { "type": "string" }
+        },
+        "additionalProperties": true
+      },
+      "description": "Cross-session learning artifacts"
+    }
+  },
+
+  "additionalProperties": true,
+
+  "description": "Top-level fields are all optional to support contract evolution. Use property-specific required constraints for nested mandatory fields."
+}