@boyingliu01/xp-gate 0.10.12 → 0.10.14

package/lib/__tests__/doctor.test.js

@@ -102,6 +102,15 @@ describe('doctor', () => {
     );
   }
 
+  function tuiJsonPath() {
+    return path.join(tmpHome, '.config', 'opencode', 'tui.json');
+  }
+
+  function ensureTuiRegistered() {
+    fs.mkdirSync(path.dirname(tuiJsonPath()), { recursive: true });
+    fs.writeFileSync(tuiJsonPath(), JSON.stringify({ plugin: ['@boyingliu01/opencode-plugin/tui'] }, null, 2));
+  }
+
   function setupLocalInstall() {
     createXpGatePreCommit(projectHooksDir());
     createXpGatePrePush(projectHooksDir());
@@ -183,6 +192,7 @@ describe('doctor', () => {
 
   it('AC-05: doctor reports all checks passed for healthy local install', async () => {
     setupLocalInstall();
+    ensureTuiRegistered();
     seedVersionCache();
     mockExecSuccess();
     const { doctor } = require('../doctor');
@@ -198,6 +208,7 @@ describe('doctor', () => {
 
   it('AC-05: doctor reports all checks passed for healthy global install', async () => {
     setupGlobalInstall();
+    ensureTuiRegistered();
     seedVersionCache();
     mockExecSuccess();
     const { doctor } = require('../doctor');
@@ -352,6 +363,7 @@ describe('doctor', () => {
 
   it('AC-10: doctor --fix corrects core.hooksPath in global mode', async () => {
     setupGlobalInstall();
+    ensureTuiRegistered();
     seedVersionCache();
     // Mock hooksPath pointing somewhere else
     execSpy = vi.spyOn(childProcess, 'execSync').mockImplementation((cmd) => {
@@ -455,6 +467,7 @@ describe('doctor', () => {
 
   it('passes version check when config version matches package version', async () => {
     setupLocalInstall();
+    ensureTuiRegistered();
     seedVersionCache();
     // Write config with matching version
     const pkg = JSON.parse(fs.readFileSync(
@@ -476,6 +489,7 @@ describe('doctor', () => {
 
   it('passes version check when config has no version field (legacy)', async () => {
     setupLocalInstall();
+    ensureTuiRegistered();
     seedVersionCache();
     // Config without version field — legacy install, should not fail
     mockExecSuccess();
@@ -521,6 +535,7 @@ describe('doctor', () => {
 
   it('passes templateDir check when templateDir matches current platform', async () => {
     setupLocalInstall();
+    ensureTuiRegistered();
     seedVersionCache();
     // Write config with correct qoder templateDir
     const cfg = JSON.parse(fs.readFileSync(configFile(), 'utf8'));
@@ -546,6 +561,7 @@ describe('doctor', () => {
 
   it('passes templateDir check when config has no templateDir field (legacy)', async () => {
     setupLocalInstall();
+    ensureTuiRegistered();
     seedVersionCache();
     // Config without templateDir — legacy install, should not fail
     mockExecSuccess();
@@ -563,6 +579,7 @@ describe('doctor', () => {
 
   it('AC-004-01: doctor shows upgrade prompt at end when outdated', async () => {
     setupLocalInstall();
+    ensureTuiRegistered();
     mockExecSuccess();
     // Remove version cache so checkUpgrade hits the real npm registry
     const cachePath = path.join(tmpHome, '.xp-gate', 'version-cache.json');
@@ -582,6 +599,7 @@ describe('doctor', () => {
 
   it('AC-004-02: doctor does NOT show upgrade prompt when up to date', async () => {
     setupLocalInstall();
+    ensureTuiRegistered();
     mockExecSuccess();
     // Write a cache with a future version so checkUpgrade says "not outdated"
     const cachePath = path.join(tmpHome, '.xp-gate', 'version-cache.json');
@@ -606,6 +624,7 @@ describe('doctor', () => {
 
   it('AC-004-03: doctor does NOT fail when version check throws', async () => {
     setupLocalInstall();
+    ensureTuiRegistered();
     seedVersionCache();
     mockExecSuccess();
     // Write corrupt cache to trigger checkUpgrade error path
@@ -642,4 +661,140 @@ describe('doctor', () => {
       expect.stringContaining('Restored')
     );
   });
+
+  // === Check 9: TUI auto-registration (tui.json) ===
+
+  it('Check 9: PASS when tui.json has @boyingliu01/opencode-plugin/tui registered', async () => {
+    setupLocalInstall();
+    seedVersionCache();
+    mockExecSuccess();
+    // Create tui.json with the plugin registered
+    fs.mkdirSync(path.dirname(tuiJsonPath()), { recursive: true });
+    fs.writeFileSync(tuiJsonPath(), JSON.stringify({ plugin: ['@boyingliu01/opencode-plugin/tui'] }, null, 2));
+    const { doctor } = require('../doctor');
+
+    const result = await doctor([]);
+
+    expect(result).toBe(0);
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining('@boyingliu01/opencode-plugin/tui registered')
+    );
+  });
+
+  it('Check 9: FAIL when tui.json is missing', async () => {
+    setupLocalInstall();
+    seedVersionCache();
+    mockExecSuccess();
+    // Ensure no tui.json
+    if (fs.existsSync(tuiJsonPath())) fs.unlinkSync(tuiJsonPath());
+    const { doctor } = require('../doctor');
+
+    const result = await doctor([]);
+
+    expect(result).toBe(1);
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining('TUI registration: Not registered')
+    );
+  });
+
+  it('Check 9: FAIL when tui.json exists without @boyingliu01/opencode-plugin/tui entry', async () => {
+    setupLocalInstall();
+    seedVersionCache();
+    mockExecSuccess();
+    fs.mkdirSync(path.dirname(tuiJsonPath()), { recursive: true });
+    fs.writeFileSync(tuiJsonPath(), JSON.stringify({ plugin: ['some-other-plugin'] }, null, 2));
+    const { doctor } = require('../doctor');
+
+    const result = await doctor([]);
+
+    expect(result).toBe(1);
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining('TUI registration: Not registered')
+    );
+  });
+
+  it('Check 9: WARN when tui.json exists but has no plugin array', async () => {
+    setupLocalInstall();
+    seedVersionCache();
+    mockExecSuccess();
+    fs.mkdirSync(path.dirname(tuiJsonPath()), { recursive: true });
+    fs.writeFileSync(tuiJsonPath(), JSON.stringify({ someKey: 'value' }, null, 2));
+    const { doctor } = require('../doctor');
+
+    const result = await doctor([]);
+
+    expect(result).toBe(1);
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining('TUI registration: Not registered')
+    );
+  });
+
+  it('Check 9: FAIL with backup when tui.json is corrupt JSON', async () => {
+    setupLocalInstall();
+    seedVersionCache();
+    mockExecSuccess();
+    fs.mkdirSync(path.dirname(tuiJsonPath()), { recursive: true });
+    fs.writeFileSync(tuiJsonPath(), 'this is not { valid json');
+    const { doctor } = require('../doctor');
+
+    const result = await doctor([]);
+
+    expect(result).toBe(1);
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining('TUI registration: Corrupt')
+    );
+  });
+
+  // === --fix TUI registration ===
+
+  it('--fix: diagnoses TUI not registered then re-diagnoses after fix', async () => {
+    setupLocalInstall();
+    seedVersionCache();
+    mockExecSuccess();
+    // No tui.json
+    if (fs.existsSync(path.join(tmpHome, '.config', 'opencode'))) {
+      fs.rmSync(path.join(tmpHome, '.config', 'opencode'), { recursive: true, force: true });
+    }
+    const { doctor } = require('../doctor');
+
+    const result = await doctor(['--fix']);
+
+    expect(result).toBe(0);
+    // After fix, tui.json should exist with the plugin registered
+    expect(fs.existsSync(tuiJsonPath())).toBe(true);
+    const tui = JSON.parse(fs.readFileSync(tuiJsonPath(), 'utf8'));
+    expect(tui.plugin).toContain('@boyingliu01/opencode-plugin/tui');
+  });
+
+  it('--fix: append to existing tui.json plugin array', async () => {
+    setupLocalInstall();
+    seedVersionCache();
+    mockExecSuccess();
+    fs.mkdirSync(path.dirname(tuiJsonPath()), { recursive: true });
+    fs.writeFileSync(tuiJsonPath(), JSON.stringify({ plugin: ['some-other-plugin'] }, null, 2));
+    const { doctor } = require('../doctor');
+
+    const result = await doctor(['--fix']);
+
+    expect(result).toBe(0);
+    const tui = JSON.parse(fs.readFileSync(tuiJsonPath(), 'utf8'));
+    expect(tui.plugin).toContain('some-other-plugin');
+    expect(tui.plugin).toContain('@boyingliu01/opencode-plugin/tui');
+  });
+
+  it('--fix: idempotent — does not duplicate entry when already registered', async () => {
+    setupLocalInstall();
+    seedVersionCache();
+    mockExecSuccess();
+    fs.mkdirSync(path.dirname(tuiJsonPath()), { recursive: true });
+    fs.writeFileSync(tuiJsonPath(), JSON.stringify({ plugin: ['@boyingliu01/opencode-plugin/tui'] }, null, 2));
+    const { doctor } = require('../doctor');
+
+    const result = await doctor(['--fix']);
+
+    expect(result).toBe(0);
+    const tui = JSON.parse(fs.readFileSync(tuiJsonPath(), 'utf8'));
+    // Should still have exactly one entry
+    expect(tui.plugin.filter(p => p === '@boyingliu01/opencode-plugin/tui').length).toBe(1);
+  });
 });

package/lib/doctor.js

@@ -229,6 +229,9 @@ function diagnose() {
   // --- Check 6: Environment dependencies ---
   checkEnv(checks);
 
+  // --- Check 7: TUI auto-registration ---
+  issues += diagnoseTuiRegistration(checks);
+
   return { checks, issues };
 }
 
@@ -438,6 +441,7 @@ function fixIssues(checks, config) {
   fixed = fixHooksByMode(config, srcDir) || fixed;
   fixed = fixGlobalHooksPath(config) || fixed;
   fixed = fixMissingAdapters(config.mode, srcDir, getAdaptersDirByMode(config)) || fixed;
+  fixed = fixTuiRegistration() || fixed;
 
   if (!fixed) {
     console.log('  No fixable issues found.');
@@ -499,6 +503,124 @@ function diagnoseOpenCodePlugin(checks) {
   return 0;
 }
 
+/**
+ * TUI registration path and expected plugin entry.
+ */
+const TUI_JSON_PATH = path.join(HOME_DIR, '.config', 'opencode', 'tui.json');
+const TUI_PLUGIN_ENTRY = '@boyingliu01/opencode-plugin/tui';
+
+/**
+ * Read and parse tui.json, returning { data, error }.
+ * data = parsed object on success, null on file missing, undefined on corrupt.
+ */
+function readTuiJson() {
+  if (!fs.existsSync(TUI_JSON_PATH)) return { data: null, error: null };
+  try {
+    const raw = fs.readFileSync(TUI_JSON_PATH, 'utf8');
+    const data = JSON.parse(raw);
+    return { data, error: null };
+  } catch (e) {
+    return { data: undefined, error: `Corrupt JSON: ${e.message}` };
+  }
+}
+
+/**
+ * Check 9: TUI auto-registration in ~/.config/opencode/tui.json.
+ * @returns {number} issue count
+ */
+function diagnoseTuiRegistration(checks) {
+  const { data, error } = readTuiJson();
+
+  if (error) {
+    checks.push({ name: 'TUI registration', status: 'FAIL', detail: error });
+    return 1;
+  }
+
+  if (data === null) {
+    checks.push({ name: 'TUI registration', status: 'FAIL', detail: 'Not registered' });
+    return 1;
+  }
+
+  const plugins = Array.isArray(data.plugin) ? data.plugin : [];
+  if (plugins.includes(TUI_PLUGIN_ENTRY)) {
+    checks.push({ name: 'TUI registration', status: 'PASS', detail: `${TUI_PLUGIN_ENTRY} registered` });
+    return 0;
+  }
+
+  checks.push({ name: 'TUI registration', status: 'FAIL', detail: 'Not registered' });
+  return 1;
+}
+
+/**
+ * Fix TUI registration: ensure @boyingliu01/opencode-plugin/tui is in tui.json.
+ * Uses atomic write (tmp + renameSync) for JSON safety.
+ * On corrupt JSON: backup to .corrupt-{timestamp}.bak then rebuild.
+ * Idempotent: skips if already registered.
+ * @returns {boolean} Whether a fix was applied
+ */
+function fixTuiRegistration() {
+  const { data, error } = readTuiJson();
+
+  // Corrupt JSON: backup old file, rebuild from scratch
+  if (error && data === undefined) {
+    const ts = Date.now();
+    const backupPath = `${TUI_JSON_PATH}.corrupt-${ts}.bak`;
+    try {
+      fs.copyFileSync(TUI_JSON_PATH, backupPath);
+      console.log(`  ⚠ TUI config corrupted — backed up to ${backupPath}`);
+    } catch { /* non-critical */ }
+    // Rebuild fresh
+    const dir = path.dirname(TUI_JSON_PATH);
+    fs.mkdirSync(dir, { recursive: true });
+    const newConfig = { plugin: [TUI_PLUGIN_ENTRY] };
+    const tmpPath = `${TUI_JSON_PATH}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(newConfig, null, 2));
+    fs.renameSync(tmpPath, TUI_JSON_PATH);
+    console.log(`  ✓ Registered ${TUI_PLUGIN_ENTRY} in TUI (rebuilt after corrupt backup)`);
+    return true;
+  }
+
+  // File doesn't exist: create it
+  if (data === null) {
+    const dir = path.dirname(TUI_JSON_PATH);
+    fs.mkdirSync(dir, { recursive: true });
+    const newConfig = { plugin: [TUI_PLUGIN_ENTRY] };
+    const tmpPath = `${TUI_JSON_PATH}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(newConfig, null, 2));
+    fs.renameSync(tmpPath, TUI_JSON_PATH);
+    console.log(`  ✓ Created TUI config with ${TUI_PLUGIN_ENTRY}`);
+    return true;
+  }
+
+  // File exists, check if plugin already registered (idempotent)
+  const plugins = Array.isArray(data.plugin) ? data.plugin : [];
+  if (plugins.includes(TUI_PLUGIN_ENTRY)) return false;
+
+  // Append plugin entry
+  data.plugin = plugins.concat([TUI_PLUGIN_ENTRY]);
+  const tmpPath = `${TUI_JSON_PATH}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+  fs.renameSync(tmpPath, TUI_JSON_PATH);
+  console.log(`  ✓ Added ${TUI_PLUGIN_ENTRY} to TUI config`);
+  return true;
+}
+
+/**
+ * Wrapper for init.js: ensure TUI is registered without console output.
+ * Returns true if the plugin is already registered or was just added.
+ */
+function ensureTuiRegistration() {
+  const { data } = readTuiJson();
+  if (data === null || data === undefined) {
+    fixTuiRegistration();
+    return;
+  }
+  const plugins = Array.isArray(data.plugin) ? data.plugin : [];
+  if (!plugins.includes(TUI_PLUGIN_ENTRY)) {
+    fixTuiRegistration();
+  }
+}
+
 async function doctor(args) {
   const fixMode = args.includes('--fix');
 
@@ -551,4 +673,8 @@ module.exports = {
   fixMissingHooks,
   fixCoreHooksPath,
   fixMissingAdapters,
+  diagnoseTuiRegistration,
+  fixTuiRegistration,
+  ensureTuiRegistration,
+  readTuiJson,
 };

package/lib/init.js

@@ -340,6 +340,12 @@ async function installLocal(args) {
   injectKarpathyPrinciples(projectRoot);
   configureOpenCodePlugin(srcDir, projectRoot);
 
+  // Auto-register TUI plugin globally (idempotent)
+  try {
+    const { ensureTuiRegistration } = require('../lib/doctor.js');
+    ensureTuiRegistration();
+  } catch { /* non-critical: TUI registration is best-effort */ }
+
   console.log('\nInstallation complete!');
   console.log('Run git commit to trigger quality gates');
   return 0;
@@ -390,6 +396,12 @@ async function setupGlobal(args) {
   const manifest = generateGlobalManifest(srcDir);
   updateConfig({ lastInit: new Date().toISOString(), mode: 'global', templateDir: TEMPLATE_DIR, manifest });
 
+  // Auto-register TUI plugin globally (idempotent)
+  try {
+    const { ensureTuiRegistration } = require('../lib/doctor.js');
+    ensureTuiRegistration();
+  } catch { /* non-critical: TUI registration is best-effort */ }
+
   console.log('\nGlobal setup complete!');
   console.log('All git repositories will now use xp-gate quality gates.');
   console.log('Per-project adapters can still override by creating <repo>/githooks/');

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.10.12",
+  "version": "0.10.14",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "./bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.10.12",
+  "version": "0.10.14",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 10 quality gates (Gate 0-9), Sprint Flow (11 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/claude-code/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

package/plugins/claude-code/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 **11-phase** development pipeline: ISOLATE → AUTO-ESTIMATE → THINK → PLAN → BUILD → REVIEW → USER ACCEPTANCE → FEEDBACK → SHIP → LAND → CLEANUP. Phase 2 default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE in Phase 1: design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/claude-code/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/opencode/__tests__/tui-plugin.test.ts

@@ -13,7 +13,6 @@ import { describe, it, before, after } from "node:test"
 import assert from "node:assert/strict"
 import { randomUUID } from "node:crypto"
 import { mkdirSync, writeFileSync, rmSync } from "node:fs"
-import { join } from "node:path"
 import { tmpdir } from "node:os"
 
 // Import the functions under test
@@ -421,3 +420,124 @@ void describe("multi-sprint rendering", () => {
     assert.ok(output.includes("Minimal sprint"))
   })
 })
+
+// ── Early-phase placeholder rendering ──
+
+/**
+ * Renders panel content with early-phase placeholder fallback.
+ * Mirrors the planned renderContent(dir, sprints, upgradeNotice) from tui-plugin.ts.
+ * Expected to be the actual implementation after TDD cycle.
+ */
+import { existsSync } from "node:fs"
+import { dirname, resolve, parse, join } from "node:path"
+
+function findGitRoot(startDir: string): string | null {
+  let current = resolve(startDir);
+  const root = parse(current).root;
+  const seen = new Set<string>();
+  while (current !== root) {
+    if (seen.has(current)) break;
+    seen.add(current);
+    if (existsSync(join(current, '.git'))) return current;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  if (existsSync(join(root, '.git'))) return root;
+  return null;
+}
+
+function renderContentWithPlaceholder(
+  dir: string,
+  sprints: { state: Record<string, unknown>; sourcePath: string; worktreeExists: boolean }[],
+  upgradeNotice: string | null,
+): string | null {
+  if (sprints.length > 0) {
+    return upgradeNotice || null
+  }
+
+  const hasStateDir = existsSync(join(dir, ".sprint-state"))
+  const gitRoot = findGitRoot(dir)
+  const hasWorktreesRoot = gitRoot ? existsSync(join(gitRoot, ".worktrees")) : false
+
+  if (hasStateDir) {
+    const placeholder = "SPRINT FLOW\n  → 初始化中..."
+    return [upgradeNotice, placeholder].filter(Boolean).join("\n---\n")
+  }
+
+  if (hasWorktreesRoot) {
+    const placeholder = "SPRINT FLOW\n  · 准备中..."
+    return [upgradeNotice, placeholder].filter(Boolean).join("\n---\n")
+  }
+
+  return upgradeNotice || null
+}
+
+void describe("early-phase placeholder rendering", () => {
+  const tmpDir = join(tmpdir(), "xp-gate-tui-placeholder-" + randomUUID())
+
+  before(() => {
+    mkdirSync(tmpDir, { recursive: true })
+  })
+
+  after(() => {
+    rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  void it("returns null when no sprints and no .sprint-state/ directory and no .worktrees/", () => {
+    const result = renderContentWithPlaceholder(tmpDir, [], null)
+    assert.equal(result, null, "Should return null when nothing exists")
+  })
+
+  void it("returns '初始化中...' placeholder when .sprint-state/ directory exists but no sprint data", () => {
+    mkdirSync(join(tmpDir, ".sprint-state"), { recursive: true })
+    const result = renderContentWithPlaceholder(tmpDir, [], null)
+    assert.ok(result !== null, "Should return a placeholder string")
+    assert.ok(result!.includes("SPRINT FLOW"), "Should include SPRINT FLOW header")
+    assert.ok(result!.includes("初始化中"), "Should include 初始化中...")
+  })
+
+  void it("returns '准备中...' placeholder when .worktrees/ directory exists but no sprint data", () => {
+    // Must create .git/ dir for findGitRoot() to succeed
+    // Note: test 2 (above) may have created .sprint-state/ — clean it first
+    rmSync(join(tmpDir, ".sprint-state"), { recursive: true, force: true })
+    mkdirSync(join(tmpDir, ".git"), { recursive: true })
+    mkdirSync(join(tmpDir, ".worktrees"), { recursive: true })
+
+    const result = renderContentWithPlaceholder(tmpDir, [], null)
+    assert.ok(result !== null, "Should return a placeholder string")
+    assert.ok(result!.includes("SPRINT FLOW"), "Should include SPRINT FLOW header")
+    assert.ok(result!.includes("准备中"), "Should include 准备中...")
+  })
+
+  void it("prefers .sprint-state/ placeholder over .worktrees/ when both exist", () => {
+    mkdirSync(join(tmpDir, ".sprint-state"), { recursive: true })
+    const result = renderContentWithPlaceholder(tmpDir, [], null)
+    assert.ok(result!.includes("初始化中"), "Should prefer 初始化中 when .sprint-state/ exists")
+    assert.ok(!result!.includes("准备中"), "Should NOT show 准备中 when .sprint-state/ exists")
+  })
+
+  void it("includes upgrade notice banner above placeholder when both present", () => {
+    const notice = "✓ Auto-upgraded from v0.10.12 to v0.10.13"
+    const result = renderContentWithPlaceholder(tmpDir, [], notice)
+    assert.ok(result !== null)
+    assert.ok(result!.includes("Auto-upgraded"), "Should include upgrade notice")
+    assert.ok(result!.includes("SPRINT FLOW"), "Should include placeholder below notice")
+    // Upgrade notice should appear before SPRINT FLOW
+    const noticePos = result!.indexOf("Auto-upgraded")
+    const sprintPos = result!.indexOf("SPRINT FLOW")
+    assert.ok(noticePos < sprintPos, "Upgrade notice should come before SPRINT FLOW")
+  })
+
+  void it("shows upgrade notice only when no sprints and no placeholder dirs", () => {
+    // Reset — remove .sprint-state/ and .worktrees/
+    rmSync(join(tmpDir, ".sprint-state"), { recursive: true, force: true })
+    rmSync(join(tmpDir, ".worktrees"), { recursive: true, force: true })
+
+    const notice = "↑ New version v1.0.0 available"
+    const result = renderContentWithPlaceholder(tmpDir, [], notice)
+    assert.ok(result !== null, "Should return upgrade notice even without sprint dirs")
+    assert.ok(result!.includes("New version"), "Should include upgrade notice text")
+    assert.ok(!result!.includes("SPRINT FLOW"), "Should NOT show placeholder when nothing exists")
+  })
+})

package/plugins/opencode/index.ts

@@ -322,6 +322,8 @@ export const XpGatePlugin = async (input: OpenCodePluginInput) => {
       if (!checked) {
         checked = true
         const msg = await runBackgroundUpdates(directory).catch(() => null)
+        // Primary notification: upgrade-notice.json → TUI sidebar banner
+        // Fallback: stderr for users without TUI panel registered
         if (msg) process.stderr.write(`${msg}\n`)
       }
     },

package/plugins/opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/opencode-plugin",
-  "version": "0.10.12",
+  "version": "0.10.14",
   "type": "module",
   "main": "index.ts",
   "description": "XP-Gate quality gates + AI workflow skills + Sprint Flow TUI sidebar for OpenCode",

package/plugins/opencode/scripts/prepack.cjs

@@ -80,6 +80,21 @@ function main() {
   }
 
   console.error(`[prepack] done: ${copied} skills bundled for @boyingliu01/opencode-plugin`);
+
+  // Validate tui-plugin.ts structural integrity (Issue #248: stale cache detection)
+  const tuiFile = path.join(PLUGIN_ROOT, 'tui-plugin.ts');
+  const tuiContent = fs.readFileSync(tuiFile, 'utf8');
+  const ok1 = tuiContent.includes('discoverActiveSprints') && tuiContent.includes('.worktrees');
+  const ok2 = !tuiContent.match(/from\s+["'][^"']*\.\.\/\.\.\/src[^"']*["']/);
+  if (!ok1) {
+    console.error('[prepack] ERROR: tui-plugin.ts is missing discoverActiveSprints — old version detected');
+    process.exit(1);
+  }
+  if (!ok2) {
+    console.error('[prepack] ERROR: tui-plugin.ts contains broken import paths to ../../src/...');
+    process.exit(1);
+  }
+  console.error('[prepack] OK: tui-plugin.ts structural checks passed');
 }
 
 main();

package/plugins/opencode/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

package/plugins/opencode/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 **11-phase** development pipeline: ISOLATE → AUTO-ESTIMATE → THINK → PLAN → BUILD → REVIEW → USER ACCEPTANCE → FEEDBACK → SHIP → LAND → CLEANUP. Phase 2 default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE in Phase 1: design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/opencode/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/opencode/tui-plugin.ts

@@ -329,11 +329,29 @@ function renderMultiSprintSidebar(sprints: DiscoveredSprint[]): string | null {
   return blocks.join("\n---\n");
 }
 
-function renderContent(sprints: DiscoveredSprint[], upgradeNotice: string | null): string | null {
+function renderContent(sprints: DiscoveredSprint[], upgradeNotice: string | null, dir: string): string | null {
   const sprintContent = renderMultiSprintSidebar(sprints)
-  if (upgradeNotice && sprintContent) return `${upgradeNotice}\n---\n${sprintContent}`
-  if (upgradeNotice) return upgradeNotice
-  return sprintContent
+
+  if (sprintContent) {
+    return [upgradeNotice, sprintContent].filter(Boolean).join("\n---\n")
+  }
+
+  // Early-phase placeholders: when no sprint data yet, check for directory hints
+  const hasStateDir = existsSync(join(dir, ".sprint-state"))
+  const gitRoot = findGitRoot(dir)
+  const hasWorktreesRoot = gitRoot ? existsSync(join(gitRoot, ".worktrees")) : false
+
+  if (hasStateDir) {
+    const placeholder = "SPRINT FLOW\n  → 初始化中..."
+    return [upgradeNotice, placeholder].filter(Boolean).join("\n---\n")
+  }
+
+  if (hasWorktreesRoot) {
+    const placeholder = "SPRINT FLOW\n  · 准备中..."
+    return [upgradeNotice, placeholder].filter(Boolean).join("\n---\n")
+  }
+
+  return upgradeNotice || null
 }
 
 // ── Upgrade notice ──
@@ -376,15 +394,14 @@ const tuiPlugin: TuiSlotPlugin = {
       const dir = process.env.XP_GATE_PROJECT_DIR || process.cwd();
       const now = Date.now();
 
-      // Use cache if still valid for current directory
       if (_cache && _cache.dir === dir && now - _cache.ts < CACHE_TTL_MS) {
-        return renderContent(_cache.data, _cache.upgradeNotice);
+        return renderContent(_cache.data, _cache.upgradeNotice, dir);
       }
 
       const sprints = discoverActiveSprints(dir);
       const upgradeNotice = renderUpgradeNotice()
       _cache = { data: sprints, ts: now, dir, upgradeNotice };
-      return renderContent(sprints, upgradeNotice);
+      return renderContent(sprints, upgradeNotice, dir);
     },
   },
 }

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.10.12",
+  "version": "0.10.14",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. Includes 10 quality gates (Gate 0-9), Sprint Flow (11 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

package/plugins/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 **11-phase** development pipeline: ISOLATE → AUTO-ESTIMATE → THINK → PLAN → BUILD → REVIEW → USER ACCEPTANCE → FEEDBACK → SHIP → LAND → CLEANUP. Phase 2 default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE in Phase 1: design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.

package/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

package/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 **11-phase** development pipeline: ISOLATE → AUTO-ESTIMATE → THINK → PLAN → BUILD → REVIEW → USER ACCEPTANCE → FEEDBACK → SHIP → LAND → CLEANUP. Phase 2 default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE in Phase 1: design must pass Delphi review (≥90% consensus) before any coding.

package/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-06-24
-**Commit:** f8338d6
+**Generated:** 2026-06-25
+**Commit:** 1fe912a
 **Branch:** main
-**Version:** 0.10.12.0
+**Version:** 0.10.14.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.