@luanpdd/kit-mcp 1.6.0 → 1.7.0

package/kit/framework/workflows/plan-phase.md

@@ -234,43 +234,15 @@ Se "Executar discuss-phase primeiro":
 
 ## 5. Tratar Pesquisa
 
-**Pular se:** flag `--gaps` ou flag `--skip-research` ou flag `--reviews`.
+**Pular se:** `--gaps`, `--skip-research`, ou `--reviews`.
 
-**Se `has_research` for true (do init) E sem flag `--research`:** Usar existente, pular para o passo 6.
+**Se `has_research` true e sem `--research`:** usar existente, ir pra passo 6.
 
-**Se RESEARCH.md ausente OU flag `--research`:**
+**Se ausente OR `--research`:** sem flag explícita e sem `--auto`, perguntar (AskUserQuestion ou lista numerada se TEXT_MODE):
+- "Pesquisar primeiro (Recomendado)" — investiga domínio/padrões/deps antes de planejar. Melhor pra features novas, integrações novas, mudanças arquiteturais.
+- "Pular pesquisa" — planeja direto do contexto. Melhor pra bug fix, refactor simples, tarefas bem compreendidas.
 
-**Se sem flag explícita (`--research` ou `--skip-research`) e não `--auto`:**
-Perguntar ao usuário se deseja pesquisar, com uma recomendação contextual baseada na fase:
-
-Se `TEXT_MODE` for true, apresentar como lista numerada de texto simples:
-```
-Pesquisar antes de planejar a Fase {X}: {phase_name}?
-
-1. Pesquisar primeiro (Recomendado) — Investigar domínio, padrões e dependências antes do planejamento. Melhor para novas funcionalidades, integrações desconhecidas ou mudanças arquiteturais.
-2. Pular pesquisa — Planejar diretamente a partir do contexto e requisitos. Melhor para correções de bugs, refatorações simples ou tarefas bem compreendidas.
-
-Digite o número:
-```
-
-Caso contrário usar AskUserQuestion:
-```
-AskUserQuestion([
-  {
-    question: "Pesquisar antes de planejar a Fase {X}: {phase_name}?",
-    header: "Pesquisa",
-    multiSelect: false,
-    options: [
-      { label: "Pesquisar primeiro (Recomendado)", description: "Investigar domínio, padrões e dependências antes do planejamento. Melhor para novas funcionalidades, integrações desconhecidas ou mudanças arquiteturais." },
-      { label: "Pular pesquisa", description: "Planejar diretamente a partir do contexto e requisitos. Melhor para correções de bugs, refatorações simples ou tarefas bem compreendidas." }
-    ]
-  }
-])
-```
-
-Se o usuário selecionar "Pular pesquisa": pular para o passo 6.
-
-**Se `--auto` e `research_enabled` for false:** Pular pesquisa silenciosamente (preserva comportamento automatizado).
+Se "Pular": passo 6. Se `--auto` e `research_enabled=false`: pular silenciosamente.
 
 Exibir banner:
 ```
@@ -365,51 +337,16 @@ test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED
 > Pular se `workflow.ui_phase` for explicitamente `false` E `workflow.ui_safety_gate` for explicitamente `false` em `.planning/config.json`. Se as chaves estiverem ausentes, tratar como habilitado.
 
 ```bash
-UI_PHASE_CFG=$(node "./.claude/framework/bin/tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
-UI_GATE_CFG=$(node "./.claude/framework/bin/tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null || echo "true")
-```
-
-**Se ambos forem `false`:** Pular para o passo 6.
-
-Verificar se a fase tem indicadores de frontend:
-
-```bash
-PHASE_SECTION=$(node "./.claude/framework/bin/tools.cjs" roadmap get-phase "${PHASE}" 2>/dev/null)
-echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1
-HAS_UI=$?
-```
-
-**Se `HAS_UI` for 0 (indicadores de frontend encontrados):**
-
-Verificar UI-SPEC existente:
-```bash
-UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-```
-
-**Se UI-SPEC.md encontrado:** Definir `UI_SPEC_PATH=$UI_SPEC_FILE`. Exibir: `Usando contrato de design de UI: ${UI_SPEC_PATH}`
-
-**Se UI-SPEC.md ausente E `UI_GATE_CFG` for `true`:**
-
-Se `TEXT_MODE` for true, apresentar como lista numerada de texto simples:
-```
-A Fase {N} tem indicadores de frontend mas sem UI-SPEC.md. Gerar um contrato de design antes do planejamento?
+`UI_PHASE_CFG` / `UI_GATE_CFG` (default true). Se ambos false, pular pra passo 6.
 
-1. Gerar UI-SPEC primeiro — Execute /fase-ui {N} então re-execute /planejar-fase {N}
-2. Continuar sem UI-SPEC
-3. Não é uma fase de frontend
+**Detecção:** grep `-iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget"` na descrição da fase. Se sem match, pular silenciosamente.
 
-Digite o número:
-```
-
-Caso contrário usar AskUserQuestion:
-- header: "Contrato de Design de UI"
-- question: "A Fase {N} tem indicadores de frontend mas sem UI-SPEC.md. Gerar um contrato de design antes do planejamento?"
-- options:
-  - "Gerar UI-SPEC primeiro" → Exibir: "Execute `/fase-ui {N} ${WS}` então re-execute `/planejar-fase {N} ${WS}`". Sair do workflow.
-  - "Continuar sem UI-SPEC" → Continuar para o passo 6.
-  - "Não é uma fase de frontend" → Continuar para o passo 6.
-
-**Se `HAS_UI` for 1 (sem indicadores de frontend):** Pular silenciosamente para o passo 6.
+**Se match encontrado:**
+- UI-SPEC.md existe → usar (`UI_SPEC_PATH`); exibir confirmação
+- UI-SPEC.md ausente E `UI_GATE_CFG=true` → AskUserQuestion (ou lista numerada se TEXT_MODE):
+  - "Gerar UI-SPEC primeiro" → exibir `/fase-ui {N} ${WS}` e sair do workflow
+  - "Continuar sem UI-SPEC" → passo 6
+  - "Não é frontend" → passo 6
 
 ## 6. Verificar Planos Existentes
 
@@ -511,28 +448,13 @@ Output consumed by /execute-phase. Plans need:
 
 Every task MUST include these fields — they are NOT optional:
 
-1. **`<read_first>`** — Files the executor MUST read before touching anything. Always include:
-   - The file being modified (so executor sees current state, not assumptions)
-   - Any "source of truth" file referenced in CONTEXT.md (reference implementations, existing patterns, config files, schemas)
-   - Any file whose patterns, signatures, types, or conventions must be replicated or respected
-
-2. **`<acceptance_criteria>`** — Verifiable conditions that prove the task was done correctly. Rules:
-   - Every criterion must be checkable with grep, file read, test command, or CLI output
-   - NEVER use subjective language ("looks correct", "properly configured", "consistent with")
-   - ALWAYS include exact strings, patterns, values, or command outputs that must be present
-   - Examples:
-     - Code: `auth.py contains def verify_token(` / `test_auth.py exits 0`
-     - Config: `.env.example contains DATABASE_URL=` / `Dockerfile contains HEALTHCHECK`
-     - Docs: `README.md contains '## Installation'` / `API.md lists all endpoints`
-     - Infra: `deploy.yml has rollback step` / `docker-compose.yml has healthcheck for db`
-
-3. **`<action>`** — Must include CONCRETE values, not references. Rules:
-   - NEVER say "align X with Y", "match X to Y", "update to be consistent" without specifying the exact target state
-   - ALWAYS include the actual values: config keys, function signatures, SQL statements, class names, import paths, env vars, etc.
-   - If CONTEXT.md has a comparison table or expected values, copy them into the action verbatim
-   - The executor should be able to complete the task from the action text alone, without needing to read CONTEXT.md or reference files (read_first is for verification, not discovery)
-
-**Why this matters:** Executor agents work from the plan text. Vague instructions like "update the config to match production" produce shallow one-line changes. Concrete instructions like "add DATABASE_URL=postgresql://... , set POOL_SIZE=20, add REDIS_URL=redis://..." produce complete work. The cost of verbose plans is far less than the cost of re-doing shallow execution.
+1. **`<read_first>`** — files o executor DEVE ler antes de tocar em qualquer coisa: o arquivo sendo modificado, "source of truth" do CONTEXT.md, qualquer arquivo cujas convenções/tipos/assinaturas precisem ser replicados.
+
+2. **`<acceptance_criteria>`** — condições verificáveis com grep/file read/test command/CLI output. NUNCA linguagem subjetiva ("looks correct"); SEMPRE strings/patterns exatos. Ex: `auth.py contains "def verify_token("`, `test_auth.py exits 0`, `.env.example contains "DATABASE_URL="`.
+
+3. **`<action>`** — valores CONCRETOS, nunca referências. NUNCA "align X with Y"; SEMPRE valores reais (config keys, function signatures, SQL, imports, env vars). Se CONTEXT.md tem tabela de comparação, copie no `<action>` literal. Executor deve completar só com texto do action.
+
+**Por quê:** instruções vagas ("update config to match production") geram one-line changes; instruções concretas ("add DATABASE_URL=..., POOL_SIZE=20, REDIS_URL=...") geram trabalho completo. Custo de plano verboso é ínfimo vs custo de redo de execução shallow.
 </deep_work_rules>
 
 <quality_gate>
@@ -725,58 +647,17 @@ Rotear para `<offer_next>` OU `auto_advance` dependendo de flags/config.
 
 Verificar gatilho de avanço automático:
 
-1. Analisar flag `--auto` de $ARGUMENTS
-2. **Sincronizar flag de cadeia com intenção** — se o usuário invocou manualmente (sem `--auto`), limpar a flag de cadeia efêmera de qualquer cadeia `--auto` anterior interrompida. Isso NÃO toca em `workflow.auto_advance` (preferência persistente do usuário):
-   ```bash
-   if [[ ! "$ARGUMENTS" =~ --auto ]]; then
-     node "./.claude/framework/bin/tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null
-   fi
-   ```
-3. Ler tanto a flag de cadeia quanto a preferência do usuário:
-   ```bash
-   AUTO_CHAIN=$(node "./.claude/framework/bin/tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-   AUTO_CFG=$(node "./.claude/framework/bin/tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
-   ```
-
-**Se flag `--auto` presente OU `AUTO_CHAIN` for true OU `AUTO_CFG` for true:**
-
-Exibir banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- framework ► AVANÇANDO AUTOMATICAMENTE PARA EXECUÇÃO
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Planos prontos. Iniciando execute-phase...
-```
-
-Iniciar execute-phase usando a ferramenta Skill para evitar sessões Task aninhadas (que causam freezes de runtime devido ao aninhamento profundo de agentes):
-```
-Skill(skill="framework:executar-fase", args="${PHASE} --auto --no-transition ${WS}")
-```
-
-A flag `--no-transition` diz ao execute-phase para retornar status após verificação em vez de encadear mais. Isso mantém a cadeia de avanço automático plana — cada fase roda no mesmo nível de aninhamento em vez de criar agentes Task mais profundos.
+**Detecção:** flag `--auto` em $ARGUMENTS, OR `workflow._auto_chain_active=true`, OR `workflow.auto_advance=true`.
 
-**Lidar com retorno do execute-phase:**
-- **FASE CONCLUÍDA** → Exibir resumo final:
-  ```
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   framework ► FASE ${PHASE} CONCLUÍDA ✓
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+**Sync de cadeia:** se invocação manual (sem `--auto`), zere `workflow._auto_chain_active` (não toque `workflow.auto_advance`).
 
-  Pipeline de avanço automático finalizado.
+**Quando ativo:** dispare `Skill(skill="framework:executar-fase", args="${PHASE} --auto --no-transition ${WS}")`. A flag `--no-transition` diz pra execute-phase retornar status após verificação (não encadear), mantendo cadeia plana.
 
-  Próximo: /discutir-fase ${NEXT_PHASE} --auto ${WS}
-  ```
-- **LACUNAS ENCONTRADAS / VERIFICAÇÃO FALHOU** → Exibir resultado, parar cadeia:
-  ```
-  Avanço automático parado: Execução precisa de revisão.
-
-  Revisar a saída acima e continuar manualmente:
-  /executar-fase ${PHASE} ${WS}
-  ```
+**Roteamento de retorno:**
+- `FASE CONCLUÍDA` → próximo: `/discutir-fase ${NEXT_PHASE} --auto ${WS}` (após `/clear`)
+- `LACUNAS ENCONTRADAS` / `VERIFICAÇÃO FALHOU` → parar cadeia. Continuar: `/executar-fase ${PHASE} ${WS}`
 
-**Se nem `--auto` nem config habilitado:**
-Rotear para `<offer_next>` (comportamento existente).
+**Quando inativo:** rotear para `<offer_next>`.
 
 </process>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
   "type": "module",
   "bin": {

package/src/cli/index.js

@@ -33,7 +33,10 @@ import { createServer } from '../ui/server.js';
 import { readLock, lockPathFor } from '../ui/lockfile.js';
 import { wrapProgressForUi } from '../ui/wrapper.js';
 import { openBrowser } from '../ui/browser.js';
+import { checkUpgrade, getLocalVersion } from './upgrade-check.js';
 import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
 
 // Read package.json version at boot so `--version` is always accurate. Falls
 // back to a string if the file lookup fails (e.g. unusual install layout).
@@ -391,6 +394,14 @@ ui.command('start')
       const url = `http://127.0.0.1:${actualPort}/`;
       process.stderr.write(`${c.cyan(icons.info)} kit-mcp ui listening on ${url}\n`);
       process.stderr.write(`${c.dim(`  project: ${projectRoot}`)}\n`);
+      // U4: non-blocking upgrade check. Warns if local install is behind npm latest.
+      // Cached for 24h via ~/.kit-mcp/version-check.json so we don't hit npm on every start.
+      checkUpgrade().then((info) => {
+        if (info?.behind) {
+          process.stderr.write(`${c.yellow(icons.warn)} kit-mcp v${info.local} → v${info.latest} disponível\n`);
+          process.stderr.write(`${c.dim('   atualize com: npm i -g @luanpdd/kit-mcp@latest')}\n`);
+        }
+      }).catch(() => { /* offline / silent */ });
       if (opts.open !== false) {
         await openBrowser(url);
       }
@@ -457,6 +468,174 @@ ui.command('open')
     }
   });
 
+// --- doctor (DX diagnostic) ---
+program.command('doctor')
+  .description('Diagnose kit-mcp setup: version, sidecar, hook, settings.json, lockfile, .planning/.')
+  .option('--project-root <path>', 'Project to diagnose (default: cwd)')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const checks = await runDoctorChecks(projectRoot);
+    const failed = checks.filter(c => c.status === 'fail').length;
+    const warned = checks.filter(c => c.status === 'warn').length;
+
+    if (program.opts().json) {
+      out({ checks, failed, warned }, () => '');
+      process.exit(failed > 0 ? 1 : 0);
+    }
+
+    process.stdout.write(`\n${c.bold('kit-mcp doctor')} — ${projectRoot}\n\n`);
+    for (const check of checks) {
+      const sym = check.status === 'pass' ? c.green(icons.check)
+                : check.status === 'warn' ? c.yellow(icons.warn)
+                : c.red(icons.cross);
+      process.stdout.write(`${sym}  ${c.bold(check.label)}\n`);
+      if (check.detail)  process.stdout.write(`   ${c.dim(check.detail)}\n`);
+      if (check.fix)     process.stdout.write(`   ${c.cyan('fix:')} ${check.fix}\n`);
+    }
+    process.stdout.write('\n');
+    if (failed > 0) {
+      process.stdout.write(`${c.red(icons.cross)} ${failed} check(s) failed\n`);
+      process.exit(1);
+    } else if (warned > 0) {
+      process.stdout.write(`${c.yellow(icons.warn)} ${warned} warning(s) — kit-mcp is functional\n`);
+    } else {
+      process.stdout.write(`${c.green(icons.check)} all checks passed\n`);
+    }
+  });
+
+async function runDoctorChecks(projectRoot) {
+  const checks = [];
+
+  // 1. Version + upgrade availability
+  const upgrade = await checkUpgrade();
+  if (!upgrade) {
+    checks.push({ label: 'version', status: 'fail',
+      detail: 'could not read local package.json',
+      fix: 'reinstall via `npm i -g @luanpdd/kit-mcp@latest`' });
+  } else if (upgrade.latest === null) {
+    checks.push({ label: 'version', status: 'warn',
+      detail: `local v${upgrade.local} (offline — could not check npm)` });
+  } else if (upgrade.behind) {
+    checks.push({ label: 'version', status: 'warn',
+      detail: `local v${upgrade.local}, latest v${upgrade.latest}`,
+      fix: 'npm i -g @luanpdd/kit-mcp@latest' });
+  } else {
+    checks.push({ label: 'version', status: 'pass',
+      detail: `v${upgrade.local} (latest)` });
+  }
+
+  // 2. Sidecar lockfile + healthz
+  const lock = readLock(projectRoot);
+  if (!lock) {
+    checks.push({ label: 'sidecar', status: 'warn',
+      detail: 'not running for this project',
+      fix: 'kit ui start (or omit if you don\'t need the live viewer)' });
+  } else {
+    try {
+      await getHealthz(lock.port);
+      checks.push({ label: 'sidecar', status: 'pass',
+        detail: `running on port ${lock.port} (pid ${lock.pid})` });
+    } catch (err) {
+      checks.push({ label: 'sidecar', status: 'fail',
+        detail: `lockfile says port ${lock.port} but unreachable: ${err.message}`,
+        fix: 'kit ui stop && kit ui start' });
+    }
+  }
+
+  // 3. ~/.claude/settings.json — exists + valid JSON + hooks present?
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  let settings = null;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    checks.push({ label: 'settings.json', status: 'pass',
+      detail: settingsPath });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      checks.push({ label: 'settings.json', status: 'warn',
+        detail: 'not found (expected for fresh Claude Code)',
+        fix: 'will be created automatically by Claude Code' });
+    } else {
+      checks.push({ label: 'settings.json', status: 'fail',
+        detail: `invalid JSON at ${settingsPath}: ${err.message}`,
+        fix: 'edit the file or restore from .claude/settings.json.bak' });
+    }
+  }
+
+  // 4. Hook installed?
+  if (settings) {
+    const hooks = settings.hooks?.PostToolUse;
+    const hasHook = Array.isArray(hooks) && hooks.some((h) =>
+      Array.isArray(h.hooks) && h.hooks.some((cmd) =>
+        typeof cmd.command === 'string' && cmd.command.includes('sidecar-tool-publisher')));
+    if (hasHook) {
+      checks.push({ label: 'observability hook', status: 'pass',
+        detail: 'sidecar-tool-publisher registered as PostToolUse' });
+    } else {
+      checks.push({ label: 'observability hook', status: 'warn',
+        detail: 'sidecar-tool-publisher not registered',
+        fix: 'see kit/hooks/sidecar-tool-publisher.js for installation snippet' });
+    }
+  }
+
+  // 5. Bundled kit dirs exist
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const kitRoot = path.resolve(here, '..', '..', 'kit');
+  const expected = ['agents', 'commands', 'skills'];
+  const missing = expected.filter((d) => {
+    try { return !fs.statSync(path.join(kitRoot, d)).isDirectory(); }
+    catch { return true; }
+  });
+  if (missing.length === 0) {
+    checks.push({ label: 'bundled kit', status: 'pass',
+      detail: `agents/, commands/, skills/ found in ${kitRoot}` });
+  } else {
+    checks.push({ label: 'bundled kit', status: 'fail',
+      detail: `missing: ${missing.join(', ')} in ${kitRoot}`,
+      fix: 'reinstall via `npm i -g @luanpdd/kit-mcp@latest`' });
+  }
+
+  // 6. .planning/ in projectRoot — only warn if absent (not all projects use the framework)
+  const planningDir = path.join(projectRoot, '.planning');
+  if (fs.existsSync(planningDir)) {
+    const stateOk = fs.existsSync(path.join(planningDir, 'STATE.md'));
+    const roadmapOk = fs.existsSync(path.join(planningDir, 'ROADMAP.md'));
+    if (stateOk && roadmapOk) {
+      checks.push({ label: '.planning/', status: 'pass',
+        detail: 'STATE.md + ROADMAP.md present' });
+    } else {
+      checks.push({ label: '.planning/', status: 'warn',
+        detail: `present but missing ${[!stateOk && 'STATE.md', !roadmapOk && 'ROADMAP.md'].filter(Boolean).join(', ')}`,
+        fix: 'run `kit saude` to repair, or `/novo-marco` if mid-cycle' });
+    }
+  } else {
+    checks.push({ label: '.planning/', status: 'warn',
+      detail: 'no framework state in this project',
+      fix: 'run `/novo-projeto` to bootstrap, or skip if not using the framework' });
+  }
+
+  // 7. Stale lockfile cleanup hint
+  try {
+    const tmpdir = os.tmpdir();
+    const orphans = fs.readdirSync(tmpdir).filter(n => /^kit-mcp-ui-[0-9a-f]{16}\.lock$/.test(n));
+    const stale = [];
+    for (const name of orphans) {
+      try {
+        const lock = JSON.parse(fs.readFileSync(path.join(tmpdir, name), 'utf8'));
+        try { process.kill(lock.pid, 0); } catch (err) {
+          if (err.code === 'ESRCH') stale.push(name);
+        }
+      } catch { /* skip unreadable */ }
+    }
+    if (stale.length > 0) {
+      checks.push({ label: 'orphan lockfiles', status: 'warn',
+        detail: `${stale.length} stale lockfile(s) in ${tmpdir}`,
+        fix: stale.map(n => `rm "${path.join(tmpdir, n)}"`).join(' && ') });
+    }
+  } catch { /* tmpdir scan is best-effort */ }
+
+  return checks;
+}
+
 // Helpers for kit ui (live in cli/ — stdout/console allowed here)
 async function postShutdown(port) {
   return new Promise((resolve, reject) => {

package/src/cli/upgrade-check.js

@@ -0,0 +1,135 @@
+// upgrade-check.js — non-blocking check for newer kit-mcp on npm.
+//
+// Both `kit doctor` (U1) and `kit ui start` (U4) call this. Result is cached
+// to ~/.kit-mcp/version-check.json for 24h so we don't hit the npm registry on
+// every boot. Falls back gracefully when offline or when the request fails.
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import https from 'node:https';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PACKAGE_NAME = '@luanpdd/kit-mcp';
+const CHECK_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const REQUEST_TIMEOUT_MS = 1500;
+
+function cacheFile() {
+  return path.join(os.homedir(), '.kit-mcp', 'version-check.json');
+}
+
+async function readCache() {
+  try {
+    const raw = await fs.readFile(cacheFile(), 'utf8');
+    const obj = JSON.parse(raw);
+    if (typeof obj.checkedAt !== 'number' || typeof obj.latest !== 'string') return null;
+    if (Date.now() - obj.checkedAt > CHECK_TTL_MS) return null;
+    return obj;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(obj) {
+  try {
+    await fs.mkdir(path.dirname(cacheFile()), { recursive: true });
+    await fs.writeFile(cacheFile(), JSON.stringify(obj), 'utf8');
+  } catch {
+    /* cache failures are silent — not critical */
+  }
+}
+
+function fetchLatest() {
+  // Use the registry's package endpoint. Falls back to gracefully on any error.
+  return new Promise((resolve) => {
+    const req = https.request({
+      method: 'GET',
+      hostname: 'registry.npmjs.org',
+      path: `/${encodeURIComponent(PACKAGE_NAME)}/latest`,
+      headers: { 'accept': 'application/json' },
+      timeout: REQUEST_TIMEOUT_MS,
+    }, (res) => {
+      if (res.statusCode !== 200) { res.resume(); resolve(null); return; }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        try {
+          const j = JSON.parse(body);
+          resolve(typeof j.version === 'string' ? j.version : null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { try { req.destroy(); } catch { /* noop */ } resolve(null); });
+    req.end();
+  });
+}
+
+export async function getLocalVersion() {
+  // Read package.json from the kit-mcp install root (parent of src/).
+  try {
+    const pkgPath = path.resolve(__dirname, '../../package.json');
+    const raw = await fs.readFile(pkgPath, 'utf8');
+    const j = JSON.parse(raw);
+    return typeof j.version === 'string' ? j.version : null;
+  } catch {
+    return null;
+  }
+}
+
+// Compare semver-like x.y.z lexically by component. Returns -1/0/1.
+// Missing components default to 0 ("1.5" === "1.5.0").
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const parts = v.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    while (parts.length < 3) parts.push(0);
+    return parts;
+  };
+  const [a1, a2, a3] = parse(a);
+  const [b1, b2, b3] = parse(b);
+  if (a1 !== b1) return a1 < b1 ? -1 : 1;
+  if (a2 !== b2) return a2 < b2 ? -1 : 1;
+  if (a3 !== b3) return a3 < b3 ? -1 : 1;
+  return 0;
+}
+
+// checkUpgrade({ force }): returns { local, latest, behind, source } or null on failure.
+//   force=true bypasses the 24h cache.
+export async function checkUpgrade({ force = false } = {}) {
+  const local = await getLocalVersion();
+  if (!local) return null;
+
+  if (!force) {
+    const cached = await readCache();
+    if (cached?.latest) {
+      return {
+        local,
+        latest: cached.latest,
+        behind: compareVersions(local, cached.latest) < 0,
+        source: 'cache',
+      };
+    }
+  }
+
+  const latest = await fetchLatest();
+  if (!latest) {
+    // Network failed; surface what we have.
+    return { local, latest: null, behind: false, source: 'offline' };
+  }
+
+  await writeCache({ checkedAt: Date.now(), latest });
+  return {
+    local,
+    latest,
+    behind: compareVersions(local, latest) < 0,
+    source: 'network',
+  };
+}
+
+export const __test = { compareVersions, PACKAGE_NAME, CHECK_TTL_MS };

package/src/core/gates.js

@@ -22,7 +22,19 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname  = path.dirname(__filename);
 export const DEFAULT_GATES_ROOT = path.resolve(__dirname, '../../gates');
 
+// P2: TTL cache for listGates (mirrors PERF-01 in kit.js). Gates change rarely;
+// inside a single Claude Code session we may call listGates → getGate → gatesForStage
+// in sequence — without cache, that's 3 full directory walks of the gates dir.
+const GATES_CACHE_TTL_MS = 30_000;
+const gatesCache = new Map(); // gatesRoot -> { value, ts }
+
+export function clearGatesCache() { gatesCache.clear(); }
+
 export async function listGates(gatesRoot = DEFAULT_GATES_ROOT) {
+  const cached = gatesCache.get(gatesRoot);
+  if (cached && Date.now() - cached.ts < GATES_CACHE_TTL_MS) {
+    return cached.value;
+  }
   let entries;
   try { entries = await fs.readdir(gatesRoot, { withFileTypes: true }); }
   catch { return []; }
@@ -40,7 +52,9 @@ export async function listGates(gatesRoot = DEFAULT_GATES_ROOT) {
       absPath: abs,
     });
   }
-  return out.sort((a, b) => a.id.localeCompare(b.id));
+  const value = out.sort((a, b) => a.id.localeCompare(b.id));
+  gatesCache.set(gatesRoot, { value, ts: Date.now() });
+  return value;
 }
 
 export async function getGate(id, gatesRoot = DEFAULT_GATES_ROOT) {