karajan-code 4.35.0 → 4.36.0

package/package.json

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

package/packages/hu-board/public/utils/board-view.js

@@ -267,7 +267,8 @@ async function renderBoard() {
       try {
         const res = await fetch('/api/rag/query', {
           method: 'POST', headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ text, topK: 5, scope: ragScope?.value || 'all' }),
+          // KJC-TSK-0885: the scoped view searches its own project's index.
+          body: JSON.stringify({ text, topK: 5, scope: ragScope?.value || 'all', ...(scopedProjectSlug ? { project: scopedProjectSlug } : {}) }),
         });
         const body = await res.json();
         if (!res.ok) { ragResults.innerHTML = `<span style="color:var(--color-red);">Error: ${esc(body.error || res.status)}</span>`; return; }

package/packages/hu-board/public/utils/config-editor.js

@@ -27,7 +27,10 @@ async function showConfigEditor(scope = 'global') {
   // resuelve <projectDir> desde KJ_PROJECT_DIR || cwd.
   let cfg;
   try {
-    const r = await fetch(`/api/config?scope=${encodeURIComponent(scope)}`);
+    // KJC-TSK-0885: a scoped view (/p/<slug>, app.js) names its project, so
+    // 'project' is THAT project's file, not the daemon's cwd.
+    const project = scopedProjectSlug ? `&project=${encodeURIComponent(scopedProjectSlug)}` : '';
+    const r = await fetch(`/api/config?scope=${encodeURIComponent(scope)}${project}`);
     if (!r.ok) throw new Error(`HTTP ${r.status}`);
     cfg = await r.json();
   } catch (err) {
@@ -163,7 +166,7 @@ async function showConfigEditor(scope = 'global') {
       const r = await fetch('/api/config', {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ patch, scope }),
+        body: JSON.stringify({ patch, scope, ...(scopedProjectSlug ? { project: scopedProjectSlug } : {}) }),
       });
       if (!r.ok) {
         const body = await r.json().catch(() => ({}));

package/packages/hu-board/public/utils/terminal-panel.js

@@ -28,7 +28,8 @@ async function openConversationPanel() {
       headers: { 'Content-Type': 'application/json' },
       // Sin agente en el body: decide el servidor (kj go --window fija el
       // elegido por env; sin él, claude).
-      body: JSON.stringify({}),
+      // KJC-TSK-0885: la vista scoped (/p/<slug>) abre la terminal en SU proyecto.
+      body: JSON.stringify(scopedProjectSlug ? { project: scopedProjectSlug } : {}),
     });
     started = await res.json();
     if (!res.ok) throw new Error(started.error || `HTTP ${res.status}`);

package/packages/hu-board/src/config-yaml.js

@@ -52,9 +52,11 @@ function getProjectDir() {
   return process.env.KJ_PROJECT_DIR || process.cwd();
 }
 
-function configPath(scope = 'global') {
+// KJC-TSK-0885: a scoped view passes its project's dir; only without one does
+// the daemon's KJ_PROJECT_DIR || cwd stand in (dashboard, old clients).
+function configPath(scope = 'global', projectDir = null) {
   if (scope === 'project') {
-    return join(getProjectDir(), '.karajan', 'kj.config.yml');
+    return join(projectDir || getProjectDir(), '.karajan', 'kj.config.yml');
   }
   // Same path the parent uses (src/utils/paths.js::getKarajanHome).
   // KJC-TSK-0420: delegate to db.js::getKjHome — gives us KARAJAN_HOME
@@ -63,7 +65,7 @@ function configPath(scope = 'global') {
   return join(getKjHome(), 'kj.config.yml');
 }
 
-function backupPath(scope = 'global') { return `${configPath(scope)}.bak`; }
+function backupPath(scope = 'global', projectDir = null) { return `${configPath(scope, projectDir)}.bak`; }
 
 /**
  * v2.30.0 — Categorías para agrupar los campos en el modal. El backend
@@ -433,13 +435,13 @@ function applyModelMode(parsed, mode) {
  *
  * Returns sane defaults when the file doesn't exist yet.
  */
-export function readConfig({ scope = 'global' } = {}) {
+export function readConfig({ scope = 'global', projectDir = null } = {}) {
   // PR4 — accept scope. Default 'global' preserves the previous behavior;
   // 'project' reads <projectDir>/.karajan/kj.config.yml.
   if (!SCOPES.includes(scope)) {
     throw new Error(`Scope inválido: ${scope}. Permitidos: ${SCOPES.join(', ')}`);
   }
-  const p = configPath(scope);
+  const p = configPath(scope, projectDir);
   let parsed = {};
   let exists = false;
   if (existsSync(p)) {
@@ -471,16 +473,16 @@ export function readConfig({ scope = 'global' } = {}) {
  *
  * @returns {{ path: string, written: boolean, applied: object[], errors: string[] }}
  */
-export function writeConfigPatch(patch, { scope = 'global' } = {}) {
+export function writeConfigPatch(patch, { scope = 'global', projectDir = null } = {}) {
   // PR4 — same shape as readConfig: scope decides target file.
   if (!SCOPES.includes(scope)) {
     return { path: '', scope, written: false, applied: [], errors: [`Scope inválido: ${scope}. Permitidos: ${SCOPES.join(', ')}`] };
   }
   if (!patch || typeof patch !== 'object') {
-    return { path: configPath(scope), scope, written: false, applied: [], errors: ['patch debe ser un objeto'] };
+    return { path: configPath(scope, projectDir), scope, written: false, applied: [], errors: ['patch debe ser un objeto'] };
   }
   // Read current state (or empty if file doesn't exist yet).
-  const p = configPath(scope);
+  const p = configPath(scope, projectDir);
   let parsed = {};
   if (existsSync(p)) {
     try { parsed = yaml.load(readFileSync(p, 'utf8'), { json: true }) || {}; }
@@ -517,7 +519,7 @@ export function writeConfigPatch(patch, { scope = 'global' } = {}) {
   // existing file first so the user can recover.
   const dir = dirname(p);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  if (existsSync(p)) { try { copyFileSync(p, backupPath(scope)); } catch { /* best-effort */ } }
+  if (existsSync(p)) { try { copyFileSync(p, backupPath(scope, projectDir)); } catch { /* best-effort */ } }
   const dump = yaml.dump(parsed, { lineWidth: 120 });
   // mkstemp would be nicer but we want to stay in the same dir for
   // a guaranteed-atomic rename across the same filesystem.

package/packages/hu-board/src/project-dir.js

@@ -0,0 +1,42 @@
+/**
+ * KJC-TSK-0885 (BRD-P2, ADR 0011): the project behind a scoped view.
+ *
+ * The daemon's cwd is not the project (one board serves every project), so a
+ * `/p/<slug>` view sends its slug and the server resolves the directory. It
+ * never takes a path from the client: it reads the `projectDir` the project's
+ * own plans recorded, and accepts it only if it exists and its slug is the one
+ * asked for, so a plan cannot point the board at another directory.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getHuBoardPlansDirs } from './db.js';
+import { deriveProjectIdFromDir } from './sync.js';
+
+const SLUG_RE = /^[a-zA-Z0-9_.-]+$/;
+
+/** @returns {string|null} the project's directory, or null when unresolvable. */
+export function projectDirForSlug(slug, { plansDirs = getHuBoardPlansDirs() } = {}) {
+  if (typeof slug !== 'string' || !SLUG_RE.test(slug) || slug.startsWith('.')) return null;
+  for (const root of plansDirs) {
+    let names;
+    try { names = readdirSync(join(root, slug)); } catch { continue; }
+    for (const name of names.filter((n) => n.endsWith('.json'))) {
+      let dir;
+      try { dir = JSON.parse(readFileSync(join(root, slug, name), 'utf8'))?.projectDir; } catch { continue; }
+      if (typeof dir === 'string' && deriveProjectIdFromDir(dir) === slug && existsSync(dir)) return dir;
+    }
+  }
+  return null;
+}
+
+/**
+ * The project a request is about: none when it names none (dashboard), its
+ * directory when it resolves, and an Error that says why when it does not.
+ */
+export function requestProjectDir(project) {
+  if (project === undefined || project === null || project === '') return null;
+  const dir = projectDirForSlug(project);
+  if (!dir) throw new Error(`project "${project}" has no plan recording where it lives: run a kj command in it once`);
+  return dir;
+}

package/packages/hu-board/src/routes/api.js

@@ -49,6 +49,7 @@ import { subscribe as subscribeEvents } from '../event-bus.js';
 import { runKjCommand, listSupportedCommands } from '../command-runner.js';
 import { runPreflight } from '../preflight.js';
 import { readConfig, writeConfigPatch } from '../config-yaml.js';
+import { requestProjectDir } from '../project-dir.js';
 import { BOOT_TIME, PKG_VERSION } from '../boot-info.js';
 import { addTombstone, getDb, isTombstoned as isTombstonedFn, removeTombstone, listTombstones } from '../db.js';
 import { publish as publishEvent } from '../event-bus.js';
@@ -1095,7 +1096,8 @@ router.post('/projects/:id/run', (req, res) => {
 router.get('/config', (req, res) => {
   try {
     const scope = req.query?.scope || 'global';
-    const data = readConfig({ scope });
+    // KJC-TSK-0885: a scoped view names its project; the daemon's cwd is not it.
+    const data = readConfig({ scope, projectDir: requestProjectDir(req.query?.project) });
     res.json(data);
   } catch (err) {
     res.status(400).json({ error: err.message });
@@ -1116,7 +1118,9 @@ router.put('/config', (req, res) => {
   try {
     const patch = req.body?.patch;
     const scope = req.body?.scope || 'global';
-    const result = writeConfigPatch(patch, { scope });
+    let projectDir;
+    try { projectDir = requestProjectDir(req.body?.project); } catch (err) { return res.status(400).json({ error: err.message }); }
+    const result = writeConfigPatch(patch, { scope, projectDir });
     if (!result.written) {
       return res.status(400).json({ error: 'No se pudo guardar la configuración', details: result });
     }
@@ -1353,13 +1357,17 @@ router.post('/rag/query', async (req, res) => {
   if (typeof text !== 'string' || text.length === 0) {
     return res.status(400).json({ error: "'text' is required (non-empty string)" });
   }
+  // KJC-TSK-0885 (ADR 0011): a scoped view searches ITS project's index; the
+  // machine-wide store (no filter) returned chunks of any repo.
+  let projectDir;
+  try { projectDir = requestProjectDir(req.body?.project); } catch (err) { return res.status(400).json({ error: err.message }); }
   try {
     const { openVecStore, countChunks } = await import('karajan-core/vec-store');
     // KJC-TSK-0632: resolved from karajan-core — the board carries zero
     // relative imports into the CLI src tree (see no-cli-imports test).
     const { makeEmbedder } = await import('karajan-core/rag/embedders/factory');
     const { query } = await import('karajan-core/rag/retriever');
-    const db = openVecStore({ dim: 768 });
+    const db = openVecStore({ dim: 768, ...(projectDir ? { path: path.join(projectDir, '.karajan', 'rag.db') } : {}) });
     try {
       if (countChunks(db) === 0) return res.json({ hits: [], empty: true, topK, scope });
       const embedder = makeEmbedder({});

package/packages/hu-board/src/terminal-wire.js

@@ -9,6 +9,8 @@
 import { Router } from 'express';
 import { WebSocket, WebSocketServer } from 'ws';
 
+import { requestProjectDir } from './project-dir.js';
+
 const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
 const WS_PATH = '/api/terminal/ws';
 
@@ -20,7 +22,9 @@ export function terminalRouter(manager, { defaultAgent = 'claude' } = {}) {
   const router = Router();
   router.post('/start', (req, res) => {
     try {
-      res.json(manager.start({ agent: req.body?.agent ?? defaultAgent }));
+      // KJC-TSK-0885: la vista scoped nombra su proyecto; el servidor resuelve el dir.
+      const projectDir = requestProjectDir(req.body?.project);
+      res.json(manager.start({ agent: req.body?.agent ?? defaultAgent, ...(projectDir ? { cwd: projectDir } : {}) }));
     } catch (err) {
       res.status(400).json({ error: err.message });
     }

package/packages/hu-board/src/terminal.js

@@ -47,8 +47,12 @@ export function createTerminalManager({ spawnPty, cwd, env = process.env, prompt
 
   return {
     /** Arranca (o devuelve) LA sesión — reutilizar la viva evita que cada
-     *  recarga multiplique agentes. @param {{agent: string}} params */
-    start({ agent }) {
+     *  recarga multiplique agentes. KJC-TSK-0885: `cwd` es el proyecto de la
+     *  vista; sin él, el del daemon. @param {{agent: string, cwd?: string}} params */
+    start({ agent, cwd: wanted = cwd }) {
+      if (session && session.cwd !== wanted) {
+        throw new Error(`terminal: ya hay una sesión viva en ${session.cwd}; termínala antes de abrir otra en ${wanted}.`);
+      }
       if (session) return { termId: session.termId, token: session.token, reused: true };
       // hasOwn: sin él, "constructor"/"__proto__" indexarían el prototipo.
       const spec = Object.hasOwn(TERMINAL_AGENTS, agent) ? TERMINAL_AGENTS[agent] : null;
@@ -65,10 +69,11 @@ export function createTerminalManager({ spawnPty, cwd, env = process.env, prompt
         name: 'xterm-256color',
         cols: 120,
         rows: 32,
-        cwd,
+        cwd: wanted,
         env: cleanEnv,
       });
       const current = {
+        cwd: wanted,
         termId: `term-${randomBytes(8).toString('hex')}`,
         token: randomBytes(16).toString('hex'),
         pty,

package/src/audit/harness-scorecard.js

@@ -40,9 +40,16 @@ export function hintForReason(reason, image) {
   }
 }
 
+/**
+ * KJC-BUG-0228 (issue #1840) — OPT-IN. La imagen por defecto es de un tercero y
+ * dejo de existir en el registro publico, asi que el paso venia activo, fallaba
+ * con "pull access denied" y se saltaba en cada `kj audit`. kj no puede depender
+ * por defecto de algo que otro puede borrar: quien quiera el scorecard lo pide,
+ * y quien tenga su propia imagen la declara en `audit.harness.image`.
+ */
 export function normalizeHarnessConfig(h = {}) {
   return {
-    enabled: h.enabled !== false,
+    enabled: h?.enabled === true,
     image: h.image || D.image,
     pullTimeoutMs: pos(h.pull_timeout_ms, D.pullTimeoutMs),
     assessTimeoutMs: pos(h.assess_timeout_ms, D.assessTimeoutMs),

package/src/audit/harness-section.js

@@ -20,7 +20,12 @@ const ts = () => new Date().toISOString().replaceAll(/[:.]/g, "-");
 
 export async function runHarnessSection({ projectDir, harnessConfig = null, runAssess = runHarnessAssess } = {}) {
   const cfg = normalizeHarnessConfig(harnessConfig || {});
-  if (!cfg.enabled) return { ok: true, skipped: true, reason: "disabled" };
+  // KJC-BUG-0228: desactivado por defecto, y DICHO. Un paso que desaparece en
+  // silencio del informe se lee como un paso aprobado.
+  if (!cfg.enabled) {
+    const asked = harnessConfig?.enabled === false;
+    return { ok: true, skipped: true, reason: asked ? "disabled" : "opt-in" };
+  }
   const res = await runAssess(projectDir, cfg);
   if (!res.ok) return { ok: false, error: res.error, reason: res.reason, hint: res.hint, image: cfg.image };
   const outDir = path.join(projectDir, ".karajan", "audit-runs", ts());
@@ -38,7 +43,13 @@ export async function runHarnessSection({ projectDir, harnessConfig = null, runA
 }
 
 export function formatHarnessSection(summary) {
-  if (!summary || summary.skipped) return "";
+  if (!summary) return "";
+  // KJC-BUG-0228: cuando no corre porque nadie lo pidio, se dice como pedirlo.
+  // Callarlo dejaba un informe que parecia completo sin serlo.
+  if (summary.reason === "opt-in") {
+    return "## Harness Scorecard\n\n_not run: it is opt-in (`audit.harness.enabled: true`), and it needs a scorecard image you can pull — declare yours in `audit.harness.image`._\n";
+  }
+  if (summary.skipped) return "";
   if (!summary.ok) {
     const reason = summary.reason ? ` (${summary.reason})` : "";
     const hint = summary.hint ? `\n\n${summary.hint}\n` : "";

package/src/checks/rag-coverage.js

@@ -4,21 +4,22 @@
  * Red only when an index EXISTS and is incomplete or stale: a machine with
  * no index yet (CI, a fresh clone) gets the command, not a failure.
  */
-import { openVecStore } from "../rag/vec-store.js";
+import { openProjectStore } from "../rag/project-store.js";
 import { ragIndexCoverage } from "../rag/coverage.js";
+import { ragExclude } from "../rag/indexable.js";
 import { STRATEGY } from "./types.js";
 
-export function createRagCoverageCheck({ openStore = (dim) => openVecStore({ dim }) } = {}) {
+export function createRagCoverageCheck({ openStore = (dim, projectDir) => openProjectStore({ projectDir, dim }) } = {}) {
   return {
     name: "rag-coverage",
     label: "RAG index coverage (ADR 0010)",
     strategy: STRATEGY.NONE,
     async detect({ config = {}, projectDir = process.cwd() } = {}) {
-      const db = openStore(config?.rag?.embedder?.dim || 768);
+      const db = openStore(config?.rag?.embedder?.dim || 768, projectDir);
       try {
         let c;
         try {
-          c = await ragIndexCoverage(projectDir, { db });
+          c = await ragIndexCoverage(projectDir, { db, exclude: ragExclude(config) });
         } catch (err) {
           // Corrupt store, unreachable stamp, git failure: a failing check,
           // never a silent pass. The only tolerated non-red state is "no index".
@@ -41,7 +42,10 @@ export function createRagCoverageCheck({ openStore = (dim) => openVecStore({ dim
           const sample = gaps.slice(0, 3).join(", ") + (gaps.length > 3 ? ", …" : "");
           return { ok: false, severity: "fail", detail: `${c.missing.length} source(s) outside the RAG index, ${c.stale.length} stale (${sample}) — ${fix}` };
         }
-        return { ok: true, severity: "info", detail: `${c.indexed}/${c.total} sources indexed at ${c.lastIndexedCommit.slice(0, 9)}` };
+        // KJC-BUG-0221: lo que kj genera no se exige indexado, pero se dice —
+        // una exencion que no se ve es indistinguible de un gate que dejo de mirar.
+        const generated = c.generated?.length ? `, ${c.generated.length} generated by kj (not required)` : "";
+        return { ok: true, severity: "info", detail: `${c.indexed}/${c.total} sources indexed at ${c.lastIndexedCommit.slice(0, 9)}${generated}` };
       } finally {
         db.close();
       }

package/src/checks/runner.js

@@ -92,8 +92,14 @@ export async function runChecks(checks, ctx, options = {}) {
     entries.map(async (entry) => {
       if (entry.status === STATUS.SKIPPED) return;
       const start = Date.now();
+      // Per-check override: checks that spawn slow tools (e.g. `npx <pkg>` cold
+      // start) declare detectTimeoutMs so the blanket pipeline timeout doesn't
+      // kill them. Falls back to the pipeline-wide timeoutMs.
+      const detectTimeoutMs = Number.isFinite(entry.check.detectTimeoutMs)
+        ? entry.check.detectTimeoutMs
+        : timeoutMs;
       try {
-        const result = await withTimeout(entry.check.detect({ config, signal }), timeoutMs, entry.check.name);
+        const result = await withTimeout(entry.check.detect({ config, signal }), detectTimeoutMs, entry.check.name);
         entry.detectResult = result;
         entry.runMs = Date.now() - start;
         entry.status = resolveStatusFromDetect(entry.check, result);
@@ -112,9 +118,21 @@ export async function runChecks(checks, ctx, options = {}) {
       } catch (err) {
         entry.runMs = Date.now() - start;
         if (err instanceof TimeoutError) {
-          entry.detectResult = { ok: false, severity: "warn", detail: `Timeout after ${timeoutMs}ms` };
-          entry.status = STATUS.TIMEOUT;
-          entry.detail = entry.detectResult.detail;
+          entry.detectResult = { ok: false, severity: "warn", detail: `Timeout after ${detectTimeoutMs}ms` };
+          // A timeout on a degradable (optional) check must not block the
+          // pipeline: degrade to WARN and disable its feature flags, same as
+          // a regular failure (KJC-BUG-0049 semantics).
+          if (entry.check.degradable) {
+            for (const dotPath of entry.check.degradable.disables || []) {
+              setDotPath(overrides, dotPath, false);
+            }
+            entry.status = STATUS.WARN;
+            entry.detail = `${entry.detectResult.detail} → ${entry.check.degradable.warn}`;
+            entry.degraded = true;
+          } else {
+            entry.status = STATUS.TIMEOUT;
+            entry.detail = entry.detectResult.detail;
+          }
         } else {
           entry.detectResult = { ok: false, severity: "fail", detail: `Detection error: ${err.message}` };
           entry.status = STATUS.FAIL;
@@ -172,7 +190,11 @@ export async function runChecks(checks, ctx, options = {}) {
       entries.filter((e) => e.remediated).map(async (entry) => {
         const start = Date.now();
         try {
-          const result = await withTimeout(entry.check.detect({ config: verifyConfig, signal }), timeoutMs, `${entry.check.name}:reverify`);
+          const result = await withTimeout(
+            entry.check.detect({ config: verifyConfig, signal }),
+            Number.isFinite(entry.check.detectTimeoutMs) ? entry.check.detectTimeoutMs : timeoutMs,
+            `${entry.check.name}:reverify`
+          );
           entry.runMs += Date.now() - start;
           if (!result.ok) {
             entry.status = STATUS.FAIL;

package/src/checks/skills.js

@@ -23,6 +23,16 @@ export function createOpenSkillsCheck() {
     strategy: STRATEGY.PROMPT,
     applies: skillsEnabled,
     describe: "Install OpenSkills globally: npm install -g openskills",
+    // Detection shells out to `npx openskills --version`; a cold npx cache
+    // downloads the package first (~8s observed), well above the pipeline's
+    // 3s blanket timeout. Must exceed openskills-client's internal 15s timeout.
+    detectTimeoutMs: 20_000,
+    // Optional feature: even if detection times out, degrade instead of
+    // blocking the whole preflight (skill injection is skipped for the run).
+    degradable: {
+      disables: ["skills.enabled"],
+      warn: "skill auto-install disabled for this run",
+    },
     async detect() {
       const available = await isOpenSkillsAvailable();
       if (available) {

package/src/checks/types.js

@@ -59,7 +59,11 @@
  * @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.
+ *                                                  sonar advisory, etc.) que no son blockers absolutos. También aplica
+ *                                                  cuando el detect agota su timeout (timeout → WARN, no TIMEOUT).
+ * @property {number} [detectTimeoutMs]          - per-check detect timeout override. Use for checks that spawn slow
+ *                                                  tools (e.g. `npx <pkg>` cold start) where the pipeline-wide
+ *                                                  timeoutMs would kill an otherwise healthy detect.
  */
 
 /**

package/src/cli/register-meta.js

@@ -11,7 +11,7 @@ import { identityCommand } from "../commands/identity.js";
 import { policyCommand } from "../commands/policy.js";
 import { claimsCommand, claimsGateCommand } from "../commands/claims.js";
 import { stewardSweepCommand } from "../commands/steward.js";
-import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand, ragCoversCommand } from "../commands/rag.js";
+import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand, ragCoversCommand, ragMigrateCommand } from "../commands/rag.js";
 import { qmdQueryCommand } from "../commands/qmd.js";
 import { ragMcpCommand } from "../commands/rag-mcp.js";
 import { watchStartCommand, watchStopCommand, watchStatusCommand } from "../commands/watch.js";
@@ -480,6 +480,7 @@ export function registerMeta(program, { pkgVersion }) {
       // KJC-BUG-0197: manipulación y desfase son hechos distintos y se leen
       // distinto. Un desfase no es un defecto: los guardias que corren están
       // sellados, solo son más viejos que las plantillas de este árbol.
+      else if (res.regenerated?.length && res.ok && !res.drift?.length) console.log(`sentinel verify: ${res.reason}`);
       else if (res.drift?.length && res.ok) console.log(`sentinel verify: scripts sellados, con desfase (${res.drift.join(", ")}) — ${res.reason}`);
       else console.log(res.ok ? "sentinel verify: scripts intactos" : `sentinel verify: modificados fuera de kj harden: ${res.mismatched.join(", ")} — restaura con kj harden`);
       process.exitCode = res.ok ? 0 : 1;
@@ -526,6 +527,7 @@ export function registerMeta(program, { pkgVersion }) {
     .description("Index plans + onboarding (and optionally project sources) into the local vector store")
     .option("--with-sources", "Also index the projectDir's JS/TS files")
     .option("--since <ref>", "Only re-index files changed since <ref> ('auto' uses the last indexed commit; falls back to full index if unset). KJC-TSK-0455.")
+    .option("--file <paths...>", "Index exactly these files (a missing one leaves the index): the remedy for a file absent from the index")
     .option("--json", "Output the totals as JSON")
     .action(async (flags) => {
       await withConfig(pkgVersion, "rag-index", flags, async ({ config, logger }) => {
@@ -534,6 +536,15 @@ export function registerMeta(program, { pkgVersion }) {
     });
   // KJC-BUG-0216: el gate rag-first no puede pedir lo imposible. Esto responde
   // si el RAG PUEDE hablar de un fichero, y si no, por que.
+  // KJC-TSK-0888 (ADR 0011): el paso al indice por proyecto, sin reindexar.
+  rag.command("migrate")
+    .description("Copy this project's chunks from the machine-wide index into its own .karajan/rag.db, embeddings included (no re-embedding); the global index is left untouched")
+    .option("--json", "Emit the result as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rag-migrate", flags, async ({ config }) => {
+        await ragMigrateCommand({ config, flags });
+      });
+    });
   rag.command("covers <file>")
     .description("Whether the RAG can answer about a file: exit 0 when indexed, 1 with the reason it cannot (no adapter, skipped path, empty or stale index)")
     .option("--json", "Emit the state as JSON")
@@ -564,7 +575,7 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--rag-mode <mode>", "hybrid (default) | semantic (cosine only) | keyword (BM25 only)", "hybrid")
     .option("--alpha <n>", "Hybrid weight for semantic component (0..1). Default 0.6", "0.6")
     .option("--where <clause>", "Metadata filter, e.g. 'symbol=loadConfig' or 'hu_id=HU-003 AND kind=plan'")
-    .option("--library", "Query the distilled engineering canon (pattern cards shipped with kj + ~/.karajan/library + project .karajan/library) instead of the project corpus. Cards carry problem signatures, when-NOT-to-apply and canonical citations (KJC-TSK-0697).")
+    .option("--library", "Query the distilled engineering canon (pattern cards shipped with kj + ~/.karajan/library, in ~/.karajan/library.db) instead of the project corpus; a project's own .karajan/library cards live in its index and answer normal queries. Cards carry problem signatures, when-NOT-to-apply and canonical citations (KJC-TSK-0697).")
     .option("--rerank", "Apply cross-encoder rerank to top-K (needs @huggingface/transformers, slower but more precise)")
     .option("--rerank-model <name>", "Cross-encoder model id. Default: Xenova/ms-marco-MiniLM-L-6-v2")
     .option("--json", "Output the hits as JSON")
@@ -627,10 +638,10 @@ export function registerMeta(program, { pkgVersion }) {
     await withConfig(pkgVersion, "watch:start", flags, async ({ config, logger }) => watchStartCommand({ config, logger, flags }));
   });
   watch.command("stop").description("Stop the watcher daemon").action(async () => {
-    await withConfig(pkgVersion, "watch:stop", {}, async ({ logger }) => watchStopCommand({ logger }));
+    await withConfig(pkgVersion, "watch:stop", {}, async ({ config, logger }) => watchStopCommand({ config, logger }));
   });
   watch.command("status").description("Report watcher daemon state").action(async () => {
-    await withConfig(pkgVersion, "watch:status", {}, async ({ logger }) => watchStatusCommand({ logger }));
+    await withConfig(pkgVersion, "watch:status", {}, async ({ config, logger }) => watchStatusCommand({ config, logger }));
   });
 
   program

package/src/commands/board.js

@@ -2,8 +2,9 @@ import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import net from "node:net";
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { getKarajanHome } from "../utils/paths.js";
+import { projectSlug as slugOfDir } from "../plan/plan-store.js";
 import { getPortOccupant } from "../utils/port-occupant.js";
 
 const BOARD_DIR = path.resolve(import.meta.dirname, "../../packages/hu-board");
@@ -76,18 +77,29 @@ async function findAvailablePort(desiredPort, maxTries = 10) {
 }
 
 /**
- * Build the board URL. When `projectSlug` is provided, the URL points at
- * the per-project view via the SPA hash route (`#board/<slug>`) so the
- * caller's project shows up pre-filtered instead of "All projects". The
- * frontend router is hash-based (see public/utils/init-listeners.js); a
- * real `/p/<slug>` path is not a route and silently falls back to the
- * global dashboard. KJC-BUG-0093.
+ * Build the board URL. KJC-TSK-0884 (ADR 0011, board scoped): with a project,
+ * the scoped view `/p/<slug>`, one project with the multi-project affordances
+ * hidden (app.js scoped-mode, served by the SPA fallback; checked in a browser).
+ * It replaces KJC-BUG-0093's `#board/<slug>`, which kept the global dashboard.
  * @param {number} port
  * @param {string|null} [projectSlug]
  * @returns {string}
  */
 export function buildBoardUrl(port, projectSlug) {
-  return projectSlug ? boardUrl(port, `/#board/${projectSlug}`) : boardUrl(port);
+  return projectSlug ? boardUrl(port, `/p/${encodeURIComponent(projectSlug)}`) : boardUrl(port);
+}
+
+/**
+ * KJC-TSK-0884: the board slug of a project is its PARENT repo's, even from a
+ * `kj worktree` lane, or the lane opens an empty view.
+ */
+export function boardSlug(projectDir) {
+  let dir = projectDir;
+  try {
+    const common = execFileSync("git", ["-C", projectDir, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (path.basename(common) === ".git") dir = path.dirname(common);
+  } catch { /* not a git repo: the dir is the project */ }
+  return slugOfDir(dir);
 }
 
 /**

package/src/commands/bootstrap.js

@@ -42,6 +42,8 @@ const CONTRACT_PATHS = [
   "CLAUDE.md",
   "AGENTS.md",
   "GEMINI.md",
+  // KJC-TSK-0879: in a Rulesync repo kj's rules live in .rulesync/rules/karajan.md.
+  ".rulesync",
 ];
 const CONTRACT_MESSAGE = "chore(bootstrap): el contrato del método, para que quien clone lo herede";
 

package/src/commands/env.js

@@ -7,7 +7,7 @@
 import { installPlaybook, renderPlaybook } from "../environment/playbook.js";
 import { renderBrief, listBriefs } from "../environment/briefs.js";
 import { existsSync } from "node:fs";
-import { openVecStore, projectSlug, getLastIndexedCommit, dbPath } from "../rag/vec-store.js";
+import { projectSlug, getLastIndexedCommit } from "../rag/vec-store.js";
 import { ragIndexCommand } from "./rag.js";
 import { renderPendingBlock, PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 import { onnxConfig, persistOnnxChoice, resetEmptyStore } from "../rag/onnx-fallback.js";
@@ -19,13 +19,15 @@ import { createWizard } from "../utils/wizard.js";
 import { hardenCommand } from "./harden.js";
 import { reviewGateCommand } from "./review-gate.js";
 import { join } from "node:path";
+import { openProjectStore, projectDbPath } from "../rag/project-store.js";
+import { maybeRulesyncGenerate } from "../utils/rulesync.js";
 
 function hasRagIndex(config, projectDir) {
   // KJC-BUG-0128: probing must never CREATE the store — openVecStore runs
   // the DDL, and a table born at the default dim (768) breaks the ONNX
   // fallback (384) later. No file → no index, without side effects.
-  if (!existsSync(dbPath())) return false;
-  const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+  if (!existsSync(projectDbPath(projectDir))) return false;
+  const db = openProjectStore({ projectDir, dim: config?.rag?.embedder?.dim || 768 });
   try { return Boolean(getLastIndexedCommit(db, projectSlug(projectDir))); }
   finally { db.close(); }
 }
@@ -74,6 +76,8 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     config, // KJC-TSK-0865: the panel travels with the method
   });
   console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);
+  // KJC-TSK-0879: in a Rulesync repo, spread the rules only if the project opted in.
+  maybeRulesyncGenerate({ projectDir, config, logger: console });
 
   // KJC-TSK-0711 — RAG as a native tool: agents use what is in their
   // toolbox, so the official path must be cheaper than the grep shortcut.
@@ -169,7 +173,7 @@ export async function envInstallCommand({ config = null, logger = null, flags =
         // KJC-BUG-0128: an empty store may carry a vec table at the wrong
         // dim (the old probe created it at 768) — reset it so ONNX (384)
         // can index. A store with data is never touched.
-        if (!resetEmptyStore()) {
+        if (!resetEmptyStore(projectDir)) {
           console.log("  the vector store already has data at another dimension — not switching automatically");
           return false;
         }