karajan-code 2.14.1 → 2.14.3

package/README.md

@@ -23,7 +23,11 @@
 
 ---
 
-> **v2.14.1 released** — Patch. Two more planner pathologies surfaced by dogfooding v2.14.0 against GRETA Plan 2: the **self-fix loop could regress** (iter 1 would drop 15→10 issues, iter 2 then deleted HUs the first iter had added, reaching 17 — worse than before iter 2 started) and the **planner declared `blocked_by` on async observers** (HUs that an async guardrail or cron *reacts to* were marked as depending on the guardrail, breaking the GRETA "AVISA-no-BLOQUEA" principle). Fixes: P5 snapshots the plan before each self-fix iter and reverts if `newCount > currentCount`; P6 lists six async-observer patterns in the planner prompt with a "consume vs react" heuristic. After P5+P6, regenerating Plan 2 GRETA returns to the baseline-iter-1 quality (9 findings) instead of v2.14.0's 17. 2 PRs (#684, #685). 4580/4580 tests passing. Safe upgrade from 2.14.0.
+> **v2.14.3 released** — Patch. Three preflight improvements surfaced by the first real `kj run` against a greenfield project (greta-app): (1) `gh` keyring auth is now recognized — Karajan no longer demands `GH_TOKEN` env var when the user has done `gh auth login --web` (KJC-BUG-0049 puntual). (2) New **degradable checks** system: when a preflight check fails on an optional feature (e.g. `auto_pr` without gh token), the feature is silently disabled with a WARN instead of aborting the entire run. (3) New **project-aware preflight**: detects signals (Dockerfile / firebase.json / pyproject.toml / Cargo.toml / *.tf / .env.example), checks the corresponding tools are installed, validates write permissions on `projectDir/.kj/.karajan`, compares `.env` vs `.env.example`, and validates `gh` push access to the actual remote (not just global auth). New command `kj doctor --project` runs only this phase. 2 PRs (#690, #691). 4608/4608 tests passing. Safe upgrade from 2.14.2.
+>
+> **v2.14.2** — Patch. More dogfooding fallout from GRETA Plan 2 v2.14.1: the **▶ Run button** on the HU Board appeared on every `pending` card regardless of `blocked_by` (you could launch a HU whose deps don't exist yet — the user caught it instantly), and titles on the board lost their **`[EPICA]` prefix** at some point in v2.14.x evolution, making it impossible to tell at a glance which area of the plan a card belonged to. Fixes: `canRunHu` now requires `blockedBy.length === 0` before showing ▶; the planner prompt now demands `description: "[EPICA] one-sentence description"` with INFRA/SHARED fallbacks. Plus a new doc `docs/task-templates/spec-conventions.md` collecting the 6 SPEC conventions the planner v2.14.x understands (épicas, scope exclusions, transversal deps, reuse, async observers, explicit deps), so users don't have to rediscover them by dogfooding. 2 PRs (#687, #688). 4584/4584 tests passing. Safe upgrade from 2.14.1.
+>
+> **v2.14.1** — Patch. Two more planner pathologies surfaced by dogfooding v2.14.0 against GRETA Plan 2: the **self-fix loop could regress** (iter 1 would drop 15→10 issues, iter 2 then deleted HUs the first iter had added, reaching 17 — worse than before iter 2 started) and the **planner declared `blocked_by` on async observers** (HUs that an async guardrail or cron *reacts to* were marked as depending on the guardrail, breaking the GRETA "AVISA-no-BLOQUEA" principle). Fixes: P5 snapshots the plan before each self-fix iter and reverts if `newCount > currentCount`; P6 lists six async-observer patterns in the planner prompt with a "consume vs react" heuristic. After P5+P6, regenerating Plan 2 GRETA returns to the baseline-iter-1 quality (9 findings) instead of v2.14.0's 17. 2 PRs (#684, #685). 4580/4580 tests passing. Safe upgrade from 2.14.0.
 >
 > **v2.14.0** — Quality pass. 16 PRs absorbing bug blockers (Solomon no longer rubber-stamps security issues misclassified as "style", coder filesystem-leak detection gains a second layer that catches `cd <abs> && pnpm init` even when the dir pre-existed, Sonar admin password rotation now surfaces silent failures), the four planner pathologies surfaced by the GRETA Plan 2 dogfooding (scope respect, transversal one-to-many deps, explicit `reuse` marker, and a brand-new **self-fix loop** where the plan-reviewer re-invokes the planner with structured feedback until zero issues remain), HU Board polish (zombie-TTL for crashed-runner prompts, less aggressive rate-limit with SSE exempt), and the first wave of `tests/` reorg (issue #368): ~93 files moved from root to mirror-subfolders. **4577/4577 tests passing**, **0 regressions** across all 16 PRs. Safe upgrade from 2.13.0.
 >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.14.1",
+  "version": "2.14.3",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/checks/project-checks.js

@@ -0,0 +1,245 @@
+/**
+ * Project-aware preflight checks (KJC-TSK-0393).
+ *
+ * `kj doctor` (global) y el preflight estándar verifican el ENTORNO de Karajan
+ * (CLIs instaladas, node, dirs ~/.karajan/, sonar). Pero **nada** validaba que
+ * el PROYECTO actual tuviera lo que necesita: tools detectables por signals
+ * (docker si hay Dockerfile, firebase si hay firebase.json, etc.), permisos
+ * write sobre projectDir, configuración inicializada, .env consistente con
+ * .env.example.
+ *
+ * Este módulo registra checks dinámicos basados en signals del proyecto. Se
+ * integra en preflight-checks.js como "fase project-aware" tras la fase global.
+ * También expone `kj doctor --project` para ejecutar solo esta fase manualmente.
+ *
+ * Filosofía: si un check falla, el mensaje incluye el comando EJECUTABLE para
+ * resolverlo (no "Run X or Y"), y siempre que sea posible se marca como
+ * `degradable` (KJC-BUG-0049) para no abortar runs por features opcionales.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+import { checkBinary } from "../utils/agent-detect.js";
+import { getInstallCommand } from "../utils/os-detect.js";
+import { STRATEGY } from "./types.js";
+
+/**
+ * Detect signals del proyecto. Devuelve un set de tags con qué hay en el
+ * projectDir. Pure-function, solo I/O de filesystem síncrono (rápido).
+ *
+ * @param {string} projectDir
+ * @returns {Set<string>}
+ */
+export function detectProjectSignals(projectDir) {
+  const signals = new Set();
+  if (!projectDir || !fs.existsSync(projectDir)) return signals;
+  const has = (rel) => fs.existsSync(path.join(projectDir, rel));
+  if (has("package.json")) signals.add("node");
+  if (has("Dockerfile") || has("docker-compose.yml") || has("compose.yml")) signals.add("docker");
+  if (has("firebase.json") || has(".firebaserc")) signals.add("firebase");
+  if (has("pyproject.toml") || has("requirements.txt") || has("setup.py")) signals.add("python");
+  if (has("Cargo.toml")) signals.add("rust");
+  if (has("go.mod")) signals.add("go");
+  if (has(".env.example") || has(".env.sample") || has(".env.template")) signals.add("env-example");
+  if (has(".env")) signals.add("env");
+  // Terraform / OpenTofu
+  try {
+    const entries = fs.readdirSync(projectDir);
+    if (entries.some((e) => e.endsWith(".tf") || e.endsWith(".tofu"))) signals.add("terraform");
+  } catch { /* unreadable dir */ }
+  return signals;
+}
+
+/**
+ * Check de tool específico del signal. Si el signal está presente pero la tool
+ * no, emite WARN con install command ejecutable.
+ */
+function createToolCheck({ signal, tool, label, signals }) {
+  return {
+    name: `project:tool:${tool}`,
+    label,
+    strategy: STRATEGY.MANUAL,
+    applies: () => signals.has(signal),
+    async detect() {
+      const res = await checkBinary(tool);
+      if (res.ok) {
+        return { ok: true, severity: "info", detail: `${tool} ${res.version} — required by ${signal} signal` };
+      }
+      const installCmd = getInstallCommand(tool) || `<install ${tool} for your OS>`;
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `${tool} no instalada pero el proyecto tiene signal '${signal}' (puede no necesitarla para esta HU, pero la mayoría sí)`,
+        fix: installCmd,
+      };
+    },
+  };
+}
+
+/**
+ * Permisos write check. Critical: si projectDir, .kj/ o .karajan/ no son
+ * escribibles, el pipeline va a fallar muy tarde con errores oscuros.
+ */
+function createWritePermsCheck({ projectDir }) {
+  return {
+    name: "project:write-perms",
+    label: "Write permissions (projectDir + .kj/ + .karajan/)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const targets = [
+        projectDir,
+        path.join(projectDir, ".kj"),
+        path.join(projectDir, ".karajan"),
+      ];
+      const failed = [];
+      for (const target of targets) {
+        try {
+          if (!fs.existsSync(target)) continue;
+          fs.accessSync(target, fs.constants.W_OK);
+        } catch {
+          failed.push(target);
+        }
+      }
+      if (failed.length === 0) {
+        return { ok: true, severity: "info", detail: "Karajan puede escribir en projectDir, .kj/ y .karajan/" };
+      }
+      return {
+        ok: false,
+        severity: "fail",
+        detail: `Sin permisos de escritura en: ${failed.join(", ")}`,
+        fix: `chmod -R u+w ${failed.join(" ")}`,
+      };
+    },
+  };
+}
+
+/**
+ * .env consistency check: si existe .env.example pero NO .env, o si las vars
+ * que .env.example declara faltan en .env, emite WARN con la lista.
+ */
+function createEnvConsistencyCheck({ projectDir, signals }) {
+  return {
+    name: "project:env-consistency",
+    label: ".env consistency (vs .env.example)",
+    strategy: STRATEGY.MANUAL,
+    applies: () => signals.has("env-example"),
+    async detect() {
+      const exampleFile = ["env.example", ".env.sample", ".env.template"]
+        .map((n) => path.join(projectDir, n.startsWith(".") ? n : `.${n}`))
+        .find((p) => fs.existsSync(p));
+      const realFile = path.join(projectDir, ".env");
+      const declaredVars = parseEnvKeys(exampleFile);
+      if (declaredVars.length === 0) {
+        return { ok: true, severity: "info", detail: ".env.example sin variables declaradas" };
+      }
+      const realVars = fs.existsSync(realFile) ? new Set(parseEnvKeys(realFile)) : new Set();
+      const missing = declaredVars.filter((k) => !realVars.has(k));
+      if (missing.length === 0) {
+        return { ok: true, severity: "info", detail: `.env tiene las ${declaredVars.length} variables declaradas en .env.example` };
+      }
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `.env no declara ${missing.length} variable(s) que sí están en .env.example: ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? "..." : ""}`,
+        fix: `cp ${path.basename(exampleFile)} .env && edit it`,
+      };
+    },
+  };
+}
+
+function parseEnvKeys(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    return content
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#") && l.includes("="))
+      .map((l) => l.split("=")[0].trim())
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+/**
+ * gh remote-specific check: cuando auto_pr está activo, no basta con que `gh`
+ * esté autenticado en general (eso lo cubre token:gh ya). Hay que verificar
+ * que el usuario tiene push access AL REMOTE de este proyecto.
+ */
+function createGhRemoteCheck({ projectDir }) {
+  return {
+    name: "project:gh-remote-access",
+    label: "GitHub push access (current remote)",
+    strategy: STRATEGY.MANUAL,
+    applies: (config) => config?.git?.auto_pr === true,
+    degradable: {
+      disables: ["git.auto_pr"],
+      warn: "auto_pr DESACTIVADO — no se pueden crear PRs al remote actual. Verifica permisos con `gh repo view`",
+    },
+    async detect() {
+      // Verifica que el remote responde a ls-remote (read access mínimo,
+      // proxy para push access — el push real solo se valida al pushear).
+      try {
+        const res = await runCommand("git", ["-C", projectDir, "ls-remote", "--heads", "origin"], { reject: false });
+        if (res.exitCode === 0) {
+          return { ok: true, severity: "info", detail: "Remote origin accesible vía git ls-remote" };
+        }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `git ls-remote origin falló (exit ${res.exitCode}): ${(res.stderr || "").slice(0, 120)}`,
+          fix: "Verifica el remote con `git remote -v` y la auth con `gh repo view`",
+        };
+      } catch (err) {
+        return { ok: false, severity: "warn", detail: `git ls-remote error: ${err.message}`, fix: "Verifica git remote y auth gh" };
+      }
+    },
+  };
+}
+
+/**
+ * `kj init` ran check: si no existe ~/.karajan/kj.config.yml NI .karajan/coder-rules.md,
+ * el usuario probablemente no ejecutó `kj init`. WARN con instrucción ejecutable.
+ */
+function createKjInitCheck({ projectDir }) {
+  return {
+    name: "project:kj-init-ran",
+    label: "Karajan project initialized",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const projectKjFile = path.join(projectDir, ".karajan", "coder-rules.md");
+      const globalKjFile = path.join(process.env.HOME || "", ".karajan", "kj.config.yml");
+      if (fs.existsSync(projectKjFile) || fs.existsSync(globalKjFile)) {
+        return { ok: true, severity: "info", detail: "Karajan config presente (global o local del proyecto)" };
+      }
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "No se encontró kj.config.yml global ni .karajan/coder-rules.md local — probablemente falta `kj init`",
+        fix: "kj init",
+      };
+    },
+  };
+}
+
+/**
+ * Construye el set completo de project-aware checks basado en projectDir.
+ *
+ * @param {{ projectDir: string }} ctx
+ * @returns {Check[]}
+ */
+export function getProjectChecks({ projectDir }) {
+  if (!projectDir) return [];
+  const signals = detectProjectSignals(projectDir);
+  return [
+    createKjInitCheck({ projectDir }),
+    createWritePermsCheck({ projectDir }),
+    createToolCheck({ signal: "docker", tool: "docker", label: "Docker (project signal)", signals }),
+    createToolCheck({ signal: "firebase", tool: "firebase", label: "firebase-cli (project signal)", signals }),
+    createToolCheck({ signal: "python", tool: "python3", label: "Python 3 (project signal)", signals }),
+    createToolCheck({ signal: "rust", tool: "cargo", label: "Cargo / Rust (project signal)", signals }),
+    createToolCheck({ signal: "go", tool: "go", label: "Go (project signal)", signals }),
+    createToolCheck({ signal: "terraform", tool: "terraform", label: "Terraform (project signal)", signals }),
+    createEnvConsistencyCheck({ projectDir, signals }),
+    createGhRemoteCheck({ projectDir }),
+  ];
+}

package/src/checks/runner.js

@@ -98,6 +98,17 @@ export async function runChecks(checks, ctx, options = {}) {
         entry.runMs = Date.now() - start;
         entry.status = resolveStatusFromDetect(entry.check, result);
         entry.detail = result.detail;
+        // KJC-BUG-0049: si el check es degradable y falló (status FAIL/WARN tras
+        // resolveStatusFromDetect), aplicar disables al overrides y degradar a WARN.
+        // Así el preflight no aborta — la feature opcional se desactiva con aviso.
+        if (!result.ok && entry.check.degradable && (entry.status === STATUS.FAIL || entry.status === STATUS.WARN)) {
+          for (const dotPath of entry.check.degradable.disables || []) {
+            setDotPath(overrides, dotPath, false);
+          }
+          entry.status = STATUS.WARN;
+          entry.detail = `${result.detail} → ${entry.check.degradable.warn}`;
+          entry.degraded = true;
+        }
       } catch (err) {
         entry.runMs = Date.now() - start;
         if (err instanceof TimeoutError) {
@@ -227,6 +238,24 @@ function summarize(reports) {
   return summary;
 }
 
+/**
+ * Set a dot-path on a target object, creating intermediate objects as needed.
+ * Used by the `degradable` check support (KJC-BUG-0049) to disable feature
+ * flags like `git.auto_pr` when their preflight check fails.
+ *
+ * @example setDotPath({}, "git.auto_pr", false) // → { git: { auto_pr: false } }
+ */
+function setDotPath(target, dotPath, value) {
+  const parts = String(dotPath).split(".");
+  let cursor = target;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i];
+    if (cursor[k] == null || typeof cursor[k] !== "object") cursor[k] = {};
+    cursor = cursor[k];
+  }
+  cursor[parts.at(-1)] = value;
+}
+
 /**
  * Deep-merge (shallow for now, one level deep) remediation changes into overrides.
  * Remediation outputs like { hu_board: { port: 4007 } } should not overwrite a

package/src/checks/tokens.js

@@ -21,6 +21,7 @@
 
 import { checkBinary } from "../utils/agent-detect.js";
 import { getRequiredProviderEnvs, normalizeProvider } from "../utils/provider-env.js";
+import { runCommand } from "../utils/process.js";
 import { STRATEGY } from "./types.js";
 
 /**
@@ -95,6 +96,13 @@ function createGhTokenCheck() {
     strategy: STRATEGY.PROMPT,
     applies: (config) => config?.git?.auto_pr === true,
     describe: "Run 'gh auth login' to authenticate with GitHub",
+    // KJC-BUG-0049: auto_pr es feature opcional. Si falta el token, no abortar
+    // el run — desactivar auto_pr y auto_push (sin push no hay PR posible) y
+    // continuar. El usuario verá WARN y el commit local sigue funcionando.
+    degradable: {
+      disables: ["git.auto_pr", "git.auto_push"],
+      warn: "auto_pr y auto_push DESACTIVADOS para este run (commit local sí funciona). Ejecuta `gh auth login` para reactivar.",
+    },
     async detect() {
       const envOk = !!process.env.GH_TOKEN || !!process.env.GITHUB_TOKEN;
       if (envOk) {
@@ -111,10 +119,25 @@ function createGhTokenCheck() {
           extra: { hasGh: false },
         };
       }
+      // KJC-BUG-0049 — el check anterior asumía que un usuario sin env var no
+      // tiene auth válida y abortaba el run. Pero `gh` puede estar autenticado
+      // por keyring/OAuth (caso default tras `gh auth login --web`) y operar
+      // sin env var. Si `gh auth status` devuelve exit 0 (logged in), el flujo
+      // de `auto_pr` funciona — Karajan ya no necesita `GH_TOKEN` en env.
+      try {
+        const auth = await runCommand("gh", ["auth", "status"], { reject: false });
+        if (auth.exitCode === 0) {
+          return {
+            ok: true,
+            severity: "info",
+            detail: "`gh` authenticated via keyring/OAuth (no env var needed)",
+          };
+        }
+      } catch { /* fall through to FAIL */ }
       return {
         ok: false,
         severity: "fail",
-        detail: "No GH_TOKEN/GITHUB_TOKEN; `gh` is installed but auth status unknown",
+        detail: "No GH_TOKEN/GITHUB_TOKEN and `gh auth status` reports not logged in",
         fix: "Run 'gh auth login' or export GH_TOKEN=...",
         extra: { hasGh: true },
       };

package/src/checks/types.js

@@ -41,6 +41,12 @@
  * @property {Object} [changes]                  - runtime config overrides to merge into the active session
  */
 
+/**
+ * @typedef {Object} DegradableSpec
+ * @property {string[]} disables        - dot-paths del config a desactivar si el check falla (e.g. ["git.auto_pr", "git.auto_push"])
+ * @property {string} warn              - mensaje WARN que se muestra al usuario explicando qué se desactivó y por qué
+ */
+
 /**
  * @typedef {Object} Check
  * @property {string} name                       - slug, unique across all checks (e.g. "node-version")
@@ -50,6 +56,10 @@
  * @property {(ctx: RemediationContext) => Promise<RemediationResult>} [remediate]
  * @property {string} [describe]                 - shown to user when strategy is "prompt"
  * @property {(config: Object) => boolean} [applies]  - if false, check is SKIPPED (lazy evaluation). Default: always applies.
+ * @property {DegradableSpec} [degradable]       - KJC-BUG-0049: si está definido y el check falla, en lugar de abortar
+ *                                                  el preflight, se desactivan los flags listados en `disables` y se emite
+ *                                                  WARN con `warn`. Útil para features opcionales (auto_pr, auto_push,
+ *                                                  sonar advisory, etc.) que no son blockers absolutos.
  */
 
 /**

package/src/cli/register-pipeline.js

@@ -177,6 +177,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("-y, --yes", "Auto-confirm prompts for invasive remediations (CI mode)")
     .option("--json", "Emit machine-readable JSON instead of human output")
     .option("--verbose", "Include fix hints and timing for every check")
+    .option("--project", "Run ONLY project-aware checks (signals, tools per signal, write perms, .env consistency, gh remote access) — useful to validate a specific project before kj run")
     .action(async (flags) => {
       const exitCode = await withConfig(pkgVersion, "doctor", {}, (ctx) =>
         doctorCommand({
@@ -185,6 +186,7 @@ export function registerPipeline(program, { pkgVersion }) {
           yes: !!flags.yes,
           json: !!flags.json,
           verbose: !!flags.verbose,
+          projectOnly: !!flags.project,
         })
       );
       if (Number.isInteger(exitCode)) process.exit(exitCode);

package/src/commands/doctor.js

@@ -26,13 +26,25 @@ import { getTokenChecks } from "../checks/tokens.js";
 import { getMcpHealthChecks } from "../checks/mcp-health.js";
 import { getSkillsChecks } from "../checks/skills.js";
 import { getDirSetupChecks } from "../checks/dir-setup.js";
+import { getProjectChecks } from "../checks/project-checks.js";
 
 /**
  * Build the list of Check objects applicable to the current config.
+ *
+ * KJC-TSK-0393: cuando `projectOnly === true`, devuelve SOLO los project-aware
+ * checks (signals, tools per signal, write perms, .env consistency, gh remote
+ * access). Útil para validar un proyecto específico sin re-correr todos los
+ * checks globales (CLIs, node, sonar, etc.).
+ *
  * @param {Object} config
+ * @param {{ projectOnly?: boolean }} [opts]
  * @returns {import("../checks/types.js").Check[]}
  */
-function buildChecks(config) {
+function buildChecks(config, { projectOnly = false } = {}) {
+  const projectDir = config?.projectDir || process.cwd();
+  if (projectOnly) {
+    return getProjectChecks({ projectDir });
+  }
   return [
     ...getSystemChecks(),
     ...getNodeChecks(),
@@ -46,6 +58,7 @@ function buildChecks(config) {
     ...getSkillsChecks(),
     ...getCiChecks(),
     ...getRtkChecks(),
+    ...getProjectChecks({ projectDir }),
   ];
 }
 
@@ -77,8 +90,8 @@ function confirmViaTty(describe) {
  * @param {{ config: Object, checkOnly?: boolean, yes?: boolean, onConfirm?: Function, logger?: Object }} args
  * @returns {Promise<import("../checks/types.js").RunReport>}
  */
-async function runDoctor({ config, checkOnly = false, yes = false, onConfirm, logger }) {
-  const checks = buildChecks(config);
+async function runDoctor({ config, checkOnly = false, yes = false, onConfirm, logger, projectOnly = false }) {
+  const checks = buildChecks(config, { projectOnly });
   return runCheckPipeline(checks, { config }, {
     mode: checkOnly ? "check-only" : "fix",
     yes,
@@ -105,8 +118,8 @@ export async function runChecks({ config }) {
  * @param {{ config: Object, checkOnly?: boolean, yes?: boolean, json?: boolean, verbose?: boolean }} args
  * @returns {Promise<number>}
  */
-export async function doctorCommand({ config, checkOnly = false, yes = false, json = false, verbose = false }) {
-  const report = await runDoctor({ config, checkOnly, yes });
+export async function doctorCommand({ config, checkOnly = false, yes = false, json = false, verbose = false, projectOnly = false }) {
+  const report = await runDoctor({ config, checkOnly, yes, projectOnly });
 
   if (json) {
     console.log(JSON.stringify(report, null, 2));

package/src/orchestrator/preflight-checks.js

@@ -29,6 +29,7 @@ import { getPortChecks } from "../checks/ports.js";
 import { getTokenChecks } from "../checks/tokens.js";
 import { getMcpHealthChecks } from "../checks/mcp-health.js";
 import { getSkillsChecks } from "../checks/skills.js";
+import { getProjectChecks } from "../checks/project-checks.js";
 import { resolveTestHarness } from "../config/test-harness.js";
 
 function parseJsonSafe(text) {
@@ -369,6 +370,10 @@ async function runExtendedPreflight({ config, result, emitter, eventBase, logger
     ...getTokenChecks(config),
     ...getMcpHealthChecks(),
     ...getSkillsChecks(),
+    // KJC-TSK-0393: project-aware checks (signal detection, write perms,
+    // tools per signal, .env consistency, gh remote access). Saltables con
+    // flag --no-project-checks en kj run.
+    ...(config?.flags?.noProjectChecks ? [] : getProjectChecks({ projectDir: config?.projectDir || process.cwd() })),
   ];
   let report;
   try {

package/src/prompts/planner.js

@@ -226,7 +226,7 @@ export function buildPlannerPrompt({ task, context, architectContext, productCon
     "```json",
     "{",
     '  "id": "<short symbolic identifier you choose for this step, e.g. \'INFRA-001\' or \'AUTH-SIGNUP\'>",',
-    '  "description": "<what this step achieves, one sentence>",',
+    '  "description": "<[EPICA] prefix + what this step achieves, one sentence>",',
     '  "commit": "<conventional commit message>",',
     '  "spec_section": "<see rules below>",',
     '  "acceptance_tests": [ /* see rules below */ ],',
@@ -235,6 +235,16 @@ export function buildPlannerPrompt({ task, context, architectContext, productCon
     "}",
     "```",
     "",
+    "### `description` (REQUIRED — MUST start with `[EPICA] ` prefix)",
+    "- The first 80 chars of `description` become the HU's title on the board, so the prefix is the user's only at-a-glance signal of \"which area of the plan does this card belong to\".",
+    "- Identify the EPICA from the task text — typically a heading like `### Épica PROFILE`, `## Auth`, `# Layer N — name`, or a categorical noun the user uses repeatedly (e.g. `INFRA`, `SHARED`, `UI`, `API`).",
+    "- Format: `[EPICA] one-sentence description`. Examples:",
+    "  - `[PROFILE] Subir CV cifrado con envelope encryption a Storage`",
+    "  - `[GUARD] Guardarraíl 4 inline en pipeline processConversation`",
+    "  - `[INFRA] Provisionar Firestore Vector Search por instancia`",
+    "- If no EPICA fits, use `[SHARED]` for cross-cutting utilities or `[INFRA]` for setup steps.",
+    "- Keep the EPICA name short (≤12 chars) and consistent across the plan — group same-area HUs under the SAME tag.",
+    "",
     "### `id` (REQUIRED for cross-references)",
     "- A short symbolic identifier you assign to this step (e.g. `INFRA-001`, `AUTH-SIGNUP`, `team-list-page`).",
     "- It only has to be unique within this plan; the system maps it to a stable internal HU id afterwards.",