@luanpdd/kit-mcp 1.34.0 → 1.36.0

package/README.md

@@ -10,7 +10,7 @@
 > Entregue como **MCP server**. Você usa direto via `npx`, sem instalar nada.
 
 <!-- AUTOGEN-COUNTS-START -->
-**Bundled workflow:** 73 agents · 90 commands · 98 skills · 23 gates
+**Bundled workflow:** 74 agents · 91 commands · 99 skills · 23 gates
 <!-- AUTOGEN-COUNTS-END -->
 
 ---

package/bin/cli.js

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
-import '../src/cli/index.js';
+#!/usr/bin/env node
+import '../src/cli/index.js';

package/bin/mcp.js

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
-import { startStdio } from '../src/mcp-server/index.js';
-startStdio().catch((e) => {
-  process.stderr.write(`kit-mcp failed to start: ${e.stack ?? e.message}\n`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+import { startStdio } from '../src/mcp-server/index.js';
+startStdio().catch((e) => {
+  process.stderr.write(`kit-mcp failed to start: ${e.stack ?? e.message}\n`);
+  process.exit(1);
+});

package/bin/ui.js

@@ -1,74 +1,74 @@
-#!/usr/bin/env node
-// bin/ui.js — entry point for the sidecar HTTP server.
-//
-// Used both directly (when the user runs `kit ui start`) and as the spawn target
-// when `--auto-spawn` is enabled on an MCP tool.
-//
-// Logging discipline: all output goes to stderr. stdout is reserved so that
-// callers can pipe `node bin/ui.js | jq` without UI server chatter contaminating
-// data streams (and so that this file can never poison an MCP stdio channel).
-
-import process from 'node:process';
-import { createServer } from '../src/ui/server.js';
-
-function parseArgs(argv) {
-  const args = { projectRoot: process.cwd(), port: undefined, idleMs: undefined };
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = argv[i];
-    if (a === '--project-root' && argv[i + 1]) { args.projectRoot = argv[i + 1]; i += 1; }
-    else if (a === '--port' && argv[i + 1]) { args.port = Number(argv[i + 1]); i += 1; }
-    else if (a === '--idle-ms' && argv[i + 1]) { args.idleMs = Number(argv[i + 1]); i += 1; }
-    else if (a === '--version') { args.printVersion = true; }
-    else if (a === '--help' || a === '-h') { args.help = true; }
-  }
-  return args;
-}
-
-const args = parseArgs(process.argv.slice(2));
-
-if (args.help) {
-  process.stderr.write([
-    'kit-mcp sidecar entry — usually invoked via `kit ui start`',
-    '',
-    'Usage: node bin/ui.js [options]',
-    '  --project-root <path>   project root for lockfile keying (default: cwd)',
-    '  --port <n>              bind to a specific port (default: auto-pick 7100-7199)',
-    '  --idle-ms <ms>          idle shutdown timeout (default: 0 = never; pass e.g. 1800000 for 30min)',
-    '  --version               print version and exit',
-    '  --help                  this text',
-    '',
-  ].join('\n'));
-  process.exit(0);
-}
-
-let pkgVersion = null;
-try {
-  const { default: pkg } = await import('../package.json', { with: { type: 'json' } });
-  pkgVersion = pkg.version;
-} catch {
-  // ok — version may not be available in some packaged contexts
-}
-
-if (args.printVersion) {
-  process.stderr.write(`${pkgVersion ?? 'unknown'}\n`);
-  process.exit(0);
-}
-
-const server = createServer({
-  projectRoot: args.projectRoot,
-  version: pkgVersion,
-  idleMs: args.idleMs,
-});
-
-try {
-  const { port } = await server.start({ port: args.port });
-  process.stderr.write(`[kit-mcp ui] listening on http://127.0.0.1:${port}/\n`);
-  process.stderr.write(`[kit-mcp ui] project: ${args.projectRoot}\n`);
-} catch (err) {
-  if (err.code === 'ELIVE') {
-    process.stderr.write(`[kit-mcp ui] sidecar already running for this project (pid=${err.lock?.pid}, port=${err.lock?.port})\n`);
-    process.exit(2);
-  }
-  process.stderr.write(`[kit-mcp ui] failed to start: ${err.message}\n`);
-  process.exit(1);
-}
+#!/usr/bin/env node
+// bin/ui.js — entry point for the sidecar HTTP server.
+//
+// Used both directly (when the user runs `kit ui start`) and as the spawn target
+// when `--auto-spawn` is enabled on an MCP tool.
+//
+// Logging discipline: all output goes to stderr. stdout is reserved so that
+// callers can pipe `node bin/ui.js | jq` without UI server chatter contaminating
+// data streams (and so that this file can never poison an MCP stdio channel).
+
+import process from 'node:process';
+import { createServer } from '../src/ui/server.js';
+
+function parseArgs(argv) {
+  const args = { projectRoot: process.cwd(), port: undefined, idleMs: undefined };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--project-root' && argv[i + 1]) { args.projectRoot = argv[i + 1]; i += 1; }
+    else if (a === '--port' && argv[i + 1]) { args.port = Number(argv[i + 1]); i += 1; }
+    else if (a === '--idle-ms' && argv[i + 1]) { args.idleMs = Number(argv[i + 1]); i += 1; }
+    else if (a === '--version') { args.printVersion = true; }
+    else if (a === '--help' || a === '-h') { args.help = true; }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.help) {
+  process.stderr.write([
+    'kit-mcp sidecar entry — usually invoked via `kit ui start`',
+    '',
+    'Usage: node bin/ui.js [options]',
+    '  --project-root <path>   project root for lockfile keying (default: cwd)',
+    '  --port <n>              bind to a specific port (default: auto-pick 7100-7199)',
+    '  --idle-ms <ms>          idle shutdown timeout (default: 0 = never; pass e.g. 1800000 for 30min)',
+    '  --version               print version and exit',
+    '  --help                  this text',
+    '',
+  ].join('\n'));
+  process.exit(0);
+}
+
+let pkgVersion = null;
+try {
+  const { default: pkg } = await import('../package.json', { with: { type: 'json' } });
+  pkgVersion = pkg.version;
+} catch {
+  // ok — version may not be available in some packaged contexts
+}
+
+if (args.printVersion) {
+  process.stderr.write(`${pkgVersion ?? 'unknown'}\n`);
+  process.exit(0);
+}
+
+const server = createServer({
+  projectRoot: args.projectRoot,
+  version: pkgVersion,
+  idleMs: args.idleMs,
+});
+
+try {
+  const { port } = await server.start({ port: args.port });
+  process.stderr.write(`[kit-mcp ui] listening on http://127.0.0.1:${port}/\n`);
+  process.stderr.write(`[kit-mcp ui] project: ${args.projectRoot}\n`);
+} catch (err) {
+  if (err.code === 'ELIVE') {
+    process.stderr.write(`[kit-mcp ui] sidecar already running for this project (pid=${err.lock?.pid}, port=${err.lock?.port})\n`);
+    process.exit(2);
+  }
+  process.stderr.write(`[kit-mcp ui] failed to start: ${err.message}\n`);
+  process.exit(1);
+}

package/gates/ai-prompt-stability.md

@@ -1,120 +1,120 @@
----
-id: ai-prompt-stability
-stage: pre-execute
-blocking: false
-description: Valida que prompts/tools LLM em produção (qualquer arquivo em `prompts/` ou referenciado por código de produção como prompt) têm characterization tests linkados. Skip se projeto não usa LLM. Opt-in via workflow.ai_prompt_gate.
----
-
-# AI prompt stability gate
-
-**When to run:** pre-execute (consultive default; blocking se `workflow.ai_prompt_gate=true`).
-
-**Skill canônica:** [`ai-prompt-characterization`](../kit/skills/ai-prompt-characterization/SKILL.md)
-
-**Agent invocado:** [`legacy-characterizer`](../kit/agents/legacy-characterizer.md) (modo prompt)
-
-## Check
-
-```bash
-#!/usr/bin/env bash
-# PT-BR: validar que prompts em prod têm characterization tests
-set -e
-
-# detectar prompts em prod (heurística — paths canônicos)
-PROMPT_FILES=""
-for d in prompts src/prompts supabase/functions/*/prompts; do
-  [ -d "$d" ] && PROMPT_FILES="$PROMPT_FILES $(find "$d" -type f \( -name "*.md" -o -name "*.txt" -o -name "*.prompt" \) 2>/dev/null)"
-done
-
-if [ -z "$PROMPT_FILES" ]; then
-  echo "INFO: nenhum prompt em prod detectado — gate skip."
-  exit 0
-fi
-
-# detectar gate mode
-GATE_BLOCKING=false
-if [ -f ".planning/config.json" ] && command -v jq >/dev/null; then
-  CFG=$(jq -r '.workflow.ai_prompt_gate // empty' .planning/config.json 2>/dev/null)
-  [ "$CFG" = "true" ] && GATE_BLOCKING=true
-fi
-
-# para cada prompt, verificar characterization tests
-PROMPTS_OK=()
-PROMPTS_MISSING=()
-
-for prompt in $PROMPT_FILES; do
-  STEM=$(basename "$prompt" | sed 's/\.[^.]*$//')
-  HAS_CHAR=false
-  for chardir in tests/characterization/prompts test/characterization/prompts __tests__/characterization/prompts; do
-    if find "$chardir" -path "*${STEM}*" 2>/dev/null | head -1 | grep -q . ; then
-      HAS_CHAR=true
-      break
-    fi
-  done
-
-  if [ "$HAS_CHAR" = "true" ]; then
-    PROMPTS_OK+=("$prompt")
-  else
-    LINES=$(wc -l < "$prompt" 2>/dev/null | tr -d ' ')
-    if [ "${LINES:-0}" -gt 50 ]; then  # threshold: prompts > 50 linhas requerem char
-      PROMPTS_MISSING+=("$prompt (lines=$LINES)")
-    fi
-  fi
-done
-
-if [ ${#PROMPTS_MISSING[@]} -eq 0 ]; then
-  echo "✓ ai-prompt-stability — todos os prompts > 50 linhas têm characterization tests."
-  exit 0
-fi
-
-echo ""
-echo "⚠ ai-prompt-stability — prompts sem characterization detectados:"
-echo ""
-for p in "${PROMPTS_MISSING[@]}"; do
-  echo "  - $p"
-done
-echo ""
-echo "Skill canônica: kit/skills/ai-prompt-characterization/SKILL.md"
-echo ""
-echo "Caminhos para resolver:"
-echo "  /caracterizar-prompt <prompt-file>            (gera characterization tests)"
-echo "  /caracterizar-prompt <prompt> --num-intents 5 (5 intents canônicas)"
-echo ""
-
-if [ "$GATE_BLOCKING" = "true" ]; then
-  echo "MODE: blocking (workflow.ai_prompt_gate=true)"
-  echo "Resolve antes de prosseguir."
-  exit 1
-else
-  echo "MODE: consultive (warning apenas)"
-  echo "Para tornar blocking: setar workflow.ai_prompt_gate=true em .planning/config.json"
-  exit 0
-fi
-```
-
-## Configuração
-
-```json
-{
-  "workflow": {
-    "ai_prompt_gate": false,
-    "ai_prompt_min_lines": 50,
-    "ai_prompt_paths": ["prompts/**", "src/prompts/**", "supabase/functions/*/prompts/**"]
-  }
-}
-```
-
-**Default:** `ai_prompt_gate` = false (consultive). Promove para blocking se projeto tem ≥ 5 prompts em prod.
-
-## Quando NÃO rodar
-
-- Projeto não usa LLM em produção
-- Prompts são apenas para dev tooling (não prod)
-- Prompts < 50 linhas (threshold default)
-
-## Ver também
-
-- [`ai-prompt-characterization`](../kit/skills/ai-prompt-characterization/SKILL.md) — knowledge base
-- [`legacy-characterization-tests`](../kit/skills/legacy-characterization-tests/SKILL.md) — characterization clássico
-- [`legacy-refactor-safety`](./legacy-refactor-safety.md) — gate análogo para refactor de código
-- [`llm-as-dependency`](../kit/skills/llm-as-dependency/SKILL.md) — fakear LLM em business logic tests
+---
+id: ai-prompt-stability
+stage: pre-execute
+blocking: false
+description: Valida que prompts/tools LLM em produção (qualquer arquivo em `prompts/` ou referenciado por código de produção como prompt) têm characterization tests linkados. Skip se projeto não usa LLM. Opt-in via workflow.ai_prompt_gate.
+---
+
+# AI prompt stability gate
+
+**When to run:** pre-execute (consultive default; blocking se `workflow.ai_prompt_gate=true`).
+
+**Skill canônica:** [`ai-prompt-characterization`](../kit/skills/ai-prompt-characterization/SKILL.md)
+
+**Agent invocado:** [`legacy-characterizer`](../kit/agents/legacy-characterizer.md) (modo prompt)
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: validar que prompts em prod têm characterization tests
+set -e
+
+# detectar prompts em prod (heurística — paths canônicos)
+PROMPT_FILES=""
+for d in prompts src/prompts supabase/functions/*/prompts; do
+  [ -d "$d" ] && PROMPT_FILES="$PROMPT_FILES $(find "$d" -type f \( -name "*.md" -o -name "*.txt" -o -name "*.prompt" \) 2>/dev/null)"
+done
+
+if [ -z "$PROMPT_FILES" ]; then
+  echo "INFO: nenhum prompt em prod detectado — gate skip."
+  exit 0
+fi
+
+# detectar gate mode
+GATE_BLOCKING=false
+if [ -f ".planning/config.json" ] && command -v jq >/dev/null; then
+  CFG=$(jq -r '.workflow.ai_prompt_gate // empty' .planning/config.json 2>/dev/null)
+  [ "$CFG" = "true" ] && GATE_BLOCKING=true
+fi
+
+# para cada prompt, verificar characterization tests
+PROMPTS_OK=()
+PROMPTS_MISSING=()
+
+for prompt in $PROMPT_FILES; do
+  STEM=$(basename "$prompt" | sed 's/\.[^.]*$//')
+  HAS_CHAR=false
+  for chardir in tests/characterization/prompts test/characterization/prompts __tests__/characterization/prompts; do
+    if find "$chardir" -path "*${STEM}*" 2>/dev/null | head -1 | grep -q . ; then
+      HAS_CHAR=true
+      break
+    fi
+  done
+
+  if [ "$HAS_CHAR" = "true" ]; then
+    PROMPTS_OK+=("$prompt")
+  else
+    LINES=$(wc -l < "$prompt" 2>/dev/null | tr -d ' ')
+    if [ "${LINES:-0}" -gt 50 ]; then  # threshold: prompts > 50 linhas requerem char
+      PROMPTS_MISSING+=("$prompt (lines=$LINES)")
+    fi
+  fi
+done
+
+if [ ${#PROMPTS_MISSING[@]} -eq 0 ]; then
+  echo "✓ ai-prompt-stability — todos os prompts > 50 linhas têm characterization tests."
+  exit 0
+fi
+
+echo ""
+echo "⚠ ai-prompt-stability — prompts sem characterization detectados:"
+echo ""
+for p in "${PROMPTS_MISSING[@]}"; do
+  echo "  - $p"
+done
+echo ""
+echo "Skill canônica: kit/skills/ai-prompt-characterization/SKILL.md"
+echo ""
+echo "Caminhos para resolver:"
+echo "  /caracterizar-prompt <prompt-file>            (gera characterization tests)"
+echo "  /caracterizar-prompt <prompt> --num-intents 5 (5 intents canônicas)"
+echo ""
+
+if [ "$GATE_BLOCKING" = "true" ]; then
+  echo "MODE: blocking (workflow.ai_prompt_gate=true)"
+  echo "Resolve antes de prosseguir."
+  exit 1
+else
+  echo "MODE: consultive (warning apenas)"
+  echo "Para tornar blocking: setar workflow.ai_prompt_gate=true em .planning/config.json"
+  exit 0
+fi
+```
+
+## Configuração
+
+```json
+{
+  "workflow": {
+    "ai_prompt_gate": false,
+    "ai_prompt_min_lines": 50,
+    "ai_prompt_paths": ["prompts/**", "src/prompts/**", "supabase/functions/*/prompts/**"]
+  }
+}
+```
+
+**Default:** `ai_prompt_gate` = false (consultive). Promove para blocking se projeto tem ≥ 5 prompts em prod.
+
+## Quando NÃO rodar
+
+- Projeto não usa LLM em produção
+- Prompts são apenas para dev tooling (não prod)
+- Prompts < 50 linhas (threshold default)
+
+## Ver também
+
+- [`ai-prompt-characterization`](../kit/skills/ai-prompt-characterization/SKILL.md) — knowledge base
+- [`legacy-characterization-tests`](../kit/skills/legacy-characterization-tests/SKILL.md) — characterization clássico
+- [`legacy-refactor-safety`](./legacy-refactor-safety.md) — gate análogo para refactor de código
+- [`llm-as-dependency`](../kit/skills/llm-as-dependency/SKILL.md) — fakear LLM em business logic tests

package/gates/budget-description.md

@@ -1,68 +1,68 @@
----
-id: budget-description
-stage: pre-verify
-blocking: true
-description: Valida que cada agent/command/skill tem `description:` ≤ 200 chars no frontmatter (anti-pitfall A2 — CLAUDE.md inflation).
----
-
-# Budget description gate
-
-**When to run:** pre-verify, antes de commit final do milestone.
-
-## Check
-
-```bash
-#!/usr/bin/env bash
-# PT-BR: itera por todos os agent/command/skill, valida frontmatter description ≤ 200 chars
-set -e
-
-VIOLATIONS=0
-
-# function que extrai description do YAML frontmatter
-check_description() {
-  local file="$1"
-  local desc
-  desc=$(awk '/^description:/{sub(/^description: ?/, ""); print; exit}' "$file" 2>/dev/null || true)
-  if [ -z "$desc" ]; then
-    echo "WARN: $file — sem description: no frontmatter"
-    return 0
-  fi
-  local len=${#desc}
-  if [ "$len" -gt 200 ]; then
-    echo "FAIL: $file — description tem $len chars (max 200)"
-    VIOLATIONS=$((VIOLATIONS + 1))
-  fi
-}
-
-# itera agents
-for f in kit/agents/*.md; do
-  [ -f "$f" ] && check_description "$f"
-done
-
-# itera commands
-for f in kit/commands/*.md; do
-  [ -f "$f" ] && check_description "$f"
-done
-
-# itera skills (SKILL.md em subdirs)
-for f in kit/skills/*/SKILL.md; do
-  [ -f "$f" ] && check_description "$f"
-done
-
-if [ "$VIOLATIONS" -gt 0 ]; then
-  echo "Total violations: $VIOLATIONS (max description length 200 chars)"
-  exit 1
-fi
-
-echo "✓ Todos os agents/commands/skills têm description ≤ 200 chars"
-exit 0
-```
-
-## Verdict
-
-- **passed** — todas as descriptions ≤ 200 chars
-- **block** — pelo menos uma description > 200 chars (CLAUDE.md inflation)
-
-## Notes
-
-Anti-pitfall A2 da v1.8: cluster `supabase-*` adiciona 19+ entradas em CLAUDE.md. Sem este budget, descriptions verbosas inflam CLAUDE.md em ~3-4 KB+ — desfaz otimização de v1.6/v1.7.
+---
+id: budget-description
+stage: pre-verify
+blocking: true
+description: Valida que cada agent/command/skill tem `description:` ≤ 200 chars no frontmatter (anti-pitfall A2 — CLAUDE.md inflation).
+---
+
+# Budget description gate
+
+**When to run:** pre-verify, antes de commit final do milestone.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: itera por todos os agent/command/skill, valida frontmatter description ≤ 200 chars
+set -e
+
+VIOLATIONS=0
+
+# function que extrai description do YAML frontmatter
+check_description() {
+  local file="$1"
+  local desc
+  desc=$(awk '/^description:/{sub(/^description: ?/, ""); print; exit}' "$file" 2>/dev/null || true)
+  if [ -z "$desc" ]; then
+    echo "WARN: $file — sem description: no frontmatter"
+    return 0
+  fi
+  local len=${#desc}
+  if [ "$len" -gt 200 ]; then
+    echo "FAIL: $file — description tem $len chars (max 200)"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+}
+
+# itera agents
+for f in kit/agents/*.md; do
+  [ -f "$f" ] && check_description "$f"
+done
+
+# itera commands
+for f in kit/commands/*.md; do
+  [ -f "$f" ] && check_description "$f"
+done
+
+# itera skills (SKILL.md em subdirs)
+for f in kit/skills/*/SKILL.md; do
+  [ -f "$f" ] && check_description "$f"
+done
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS (max description length 200 chars)"
+  exit 1
+fi
+
+echo "✓ Todos os agents/commands/skills têm description ≤ 200 chars"
+exit 0
+```
+
+## Verdict
+
+- **passed** — todas as descriptions ≤ 200 chars
+- **block** — pelo menos uma description > 200 chars (CLAUDE.md inflation)
+
+## Notes
+
+Anti-pitfall A2 da v1.8: cluster `supabase-*` adiciona 19+ entradas em CLAUDE.md. Sem este budget, descriptions verbosas inflam CLAUDE.md em ~3-4 KB+ — desfaz otimização de v1.6/v1.7.

package/gates/confidence.md

@@ -1,29 +1,29 @@
----
-id: confidence
-stage: pre-plan
-blocking: false
-description: After discovery, gate on the discovery confidence level before planning.
----
-
-# Confidence gate
-
-**When to run:** end of `discovery-phase` workflow, before handing off to `plan-phase`.
-
-## Inputs
-
-- `DISCOVERY.md` of the current phase (must contain `confidence: low | medium | high`)
-
-## Verdict
-
-- **passed (high)** — proceed silently
-- **warn (medium)** — log "discovery completed with medium confidence" and proceed
-- **block (low)**  — present options to the user:
-  - "Aprofundar" — run discovery deeper
-  - "Prosseguir mesmo assim" — accept and plan with caveats noted
-  - "Pausar" — exit workflow
-
-## Notes
-
-Low-confidence discovery is a smell. It usually means the chosen library is too new,
-the integration surface is poorly documented, or the requirements are still vague.
-Forcing this gate prevents planning on shaky ground.
+---
+id: confidence
+stage: pre-plan
+blocking: false
+description: After discovery, gate on the discovery confidence level before planning.
+---
+
+# Confidence gate
+
+**When to run:** end of `discovery-phase` workflow, before handing off to `plan-phase`.
+
+## Inputs
+
+- `DISCOVERY.md` of the current phase (must contain `confidence: low | medium | high`)
+
+## Verdict
+
+- **passed (high)** — proceed silently
+- **warn (medium)** — log "discovery completed with medium confidence" and proceed
+- **block (low)**  — present options to the user:
+  - "Aprofundar" — run discovery deeper
+  - "Prosseguir mesmo assim" — accept and plan with caveats noted
+  - "Pausar" — exit workflow
+
+## Notes
+
+Low-confidence discovery is a smell. It usually means the chosen library is too new,
+the integration surface is poorly documented, or the requirements are still vague.
+Forcing this gate prevents planning on shaky ground.