karajan-code 2.30.0 → 2.32.0

package/README.md

@@ -345,6 +345,23 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.32.0 released** — Minor. **AI Harness Scorecard hardening (KJC-PCS-0051)** — Plan A closes five FAILs from the external scorecard audit in one sprint: Prettier `--check`, Coverage v8 reports, Conventional Commits enforcement, nightly drift detection, and an unsafe-code lint policy. Plus two bug fixes shipped alongside.
+>
+> - **Prettier `--check` CI job** (PR #868, KJC-TSK-0464): new `format` job blocks PRs whose formatting drifts from `.prettierrc.json`. Scope narrow at first (`.github/workflows/`, root config); future PRs fold in more dirs under the shrink-budget cap.
+> - **Coverage v8 + CI artifact** (PR #870, KJC-TSK-0465): `vitest.config.js` emits `text + html + lcov` via `@vitest/coverage-v8`. New `coverage` job uploads `coverage/` (14-day retention). Per-glob thresholds enforced when the user opts in; `src/mcp/handlers/**` floor ratcheted to `70/60` to lock the current state — follow-up tracked to climb back to 80/80.
+> - **Conventional Commits on PR head** (PR #872, KJC-TSK-0466): `wagoid/commitlint-github-action@v6` checks every PR commit against `.commitlintrc.json`. CI-side enforcement on top of the pre-commit local hook — bypassing husky no longer escapes the gate.
+> - **Nightly drift workflow** (PR #873, KJC-TSK-0467): new `.github/workflows/nightly.yml` runs the full CI suite every night at 04:17 UTC against `main`. Failures auto-file/update a tracking issue tagged `drift` via `actions/github-script@v8`, so a flaky dep or upstream regression surfaces within 24 h instead of on the next unrelated PR.
+> - **`eslint-plugin-security` policy** (PR #874, KJC-TSK-0468): `eslint.config.js` now blocks `eval`, `new Function`, dynamic `require`, `pseudoRandomBytes` and `mustache`-escape disabling as hard errors; flags `detect-non-literal-regexp` as warn. Noisy members of the recommended preset are intentionally NOT enabled.
+> - **42 tests on `main` repaired** (PR #869, KJC-BUG-0065) and **`await openEditor` race in spec-reviewer refine-loop fixed** (PR #871, KJC-BUG-0066). The hardening sprint sits on a clean `main` again.
+>
+> **v2.31.0 released** — Minor. **Team-shared HU Board** — the full KJC-PRP-0002: opt-in HUs into a `.karajan-shared/` cohort, the board surfaces them with a `shared` badge, and per-HU `assignee` lets multiple machines work the same plan without trampling each other.
+>
+> - **`kj plan share` / `kj plan unshare`** (PRs #860, #862): mueve plans entre `~/.karajan/plans/` (local) y `<projectDir>/.karajan-shared/plans/` (compartido). Idempotente. El loader probará ambos automáticamente.
+> - **`share --only HU-001,HU-003` / `--exclude HU-005`** (PR #863): selective sharing — comparte solo lo que quieres, deja los WIP privados sin partir el plan.
+> - **Board scanner + `shared` badge** (PRs #861, #862): el watcher recorre los dos roots, mete las HUs compartidas en la misma tabla con `is_shared = 1`, y el modal pinta un pill `shared` junto al título del plan.
+> - **`sharedConflictPolicy` escape hatch** (PR #864): `prompt | local-wins | shared-wins` en kj.config.yml. Cuando dos máquinas editan la misma HU compartida, la política decide sin intervención. Log en `~/.karajan/board-conflicts.log`.
+> - **Per-HU `assignee`** (PR #865): handle libre (`@manufosela`, `dev_016`, `becaria`…) por HU. Visible y editable en el modal **solo** en proyectos shared. Migración sqlite idempotente.
+>
 > **v2.30.0 released** — Minor. **Writable config UI on HU Board** — settings modal with grouped sections, atomic-write backend, and a global vs per-project scope toggle. No more hand-editing the YAML.
 >
 > - **Pipeline role toggles** (PR #854): 8 nuevos booleanos en el modal (`planner`, `researcher`, `architect`, `tester`, `security`, `refactorer`, `impeccable`, `brain`) reflejan los defaults reales de `src/config/defaults.js`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.30.0",
+  "version": "2.32.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -55,9 +55,12 @@
     "setup": "node scripts/install.js",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "lint:syntax": "((command -v rg >/dev/null 2>&1 && rg --files src tests | rg '\\.js$') || find src tests -type f -name '*.js') | while IFS= read -r f; do node --check \"$f\"; done",
+    "format:check": "prettier --check .",
+    "format:fix": "prettier --write .",
     "typecheck": "npx -p typescript@5 tsc --noEmit -p tsconfig.json",
     "validate": "npm run lint && npm run lint:syntax && npm test",
     "mcp": "node src/mcp/server.js"
@@ -90,9 +93,11 @@
     "esbuild": "^0.28.0",
     "eslint": "^10.2.1",
     "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-security": "^4.0.0",
     "globals": "^17.5.0",
     "lint-staged": "^16.4.0",
     "postject": "^1.0.0-alpha.6",
+    "prettier": "^3.4.2",
     "simple-git-hooks": "^2.13.1",
     "vitest": "^4.0.0"
   }

package/packages/hu-board/public/app.js

@@ -193,6 +193,10 @@ async function triggerSync() {
 
 const projectInitialsCache = {};
 const projectNameCache = {};
+// KJC-PRP-0002 PR6: cache project.is_shared so the HU modal can gate the
+// "Asignado a" field without re-fetching /api/projects/:id each open.
+// 0/1 mirror what sqlite stores; undefined = not yet hydrated.
+const projectIsSharedCache = {};
 
 /**
  * Humanise a slug-ish project id so the board can show
@@ -251,11 +255,13 @@ async function resolveProjectMeta(projectId) {
     const initials = deriveInitialsFromName(rawName);
     projectInitialsCache[projectId] = initials;
     projectNameCache[projectId] = rawName;
+    projectIsSharedCache[projectId] = project.is_shared === 1 ? 1 : 0;
     return { initials, name: rawName };
   } catch {
     const fallbackName = humaniseProjectName(projectId);
     projectInitialsCache[projectId] = deriveInitialsFromName(fallbackName);
     projectNameCache[projectId] = fallbackName;
+    projectIsSharedCache[projectId] = 0;
     return { initials: projectInitialsCache[projectId], name: fallbackName };
   }
 }
@@ -452,7 +458,7 @@ async function renderDashboard() {
               <button class="project-card__delete" title="Delete project (cascade)" data-project-id="${esc(p.id)}" data-project-name="${esc(p.name || p.id)}">🗑️</button>
               <button class="project-card__is-test" title="${esc(isTestTitle(p))}" data-project-id="${esc(p.id)}" data-is-test="${p.is_test === null || p.is_test === undefined ? '' : p.is_test}">${isTestIcon(p)}</button>
               <div class="project-card__body" onclick="selectProject('${esc(p.id)}')">
-                <div class="project-card__name">${esc(p.name || p.id)}</div>
+                <div class="project-card__name">${p.is_shared === 1 ? '<span class="project-card__shared-badge" title="Team-shared via .karajan-shared/">🔗</span> ' : ''}${esc(p.name || p.id)}</div>
                 <div class="project-card__stats">
                   <div class="project-card__stat">
                     <div class="project-card__stat-value">${p.story_count || 0}</div>
@@ -1668,6 +1674,31 @@ window.saveHuModels = async function saveHuModels(storyId) {
   }
 };
 
+// KJC-PRP-0002 PR6: persist `hu.assignee` (free-form handle of whoever owns
+// this HU on a team-shared board). Empty string → null so the API knows to
+// clear, not store "". The modal only renders the input when the project is
+// `is_shared = 1`, so non-team boards never trigger this path.
+window.saveHuAssignee = async function saveHuAssignee(storyId) {
+  const input = document.getElementById('hu-assignee');
+  const value = input?.value?.trim() || null;
+  try {
+    const res = await fetch(`/api/stories/${encodeURIComponent(storyId)}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ assignee: value }),
+    });
+    if (!res.ok) {
+      const msg = (await res.json().catch(() => ({}))).error || `HTTP ${res.status}`;
+      await showError(msg, { title: 'No se pudo guardar el asignado' });
+      return;
+    }
+    await fetch('/api/sync', { method: 'POST' }).catch(() => {});
+    await renderBoard();
+  } catch (err) {
+    await showError(err.message || String(err), { title: 'Fallo guardando asignado' });
+  }
+};
+
 // KJC-TSK-0408: deshace los cambios de una HU restaurando el snapshot
 // git tomado pre-run. ATENCIÓN: es destructivo (git reset --hard) —
 // confirmamos siempre antes de invocar.
@@ -2435,6 +2466,27 @@ async function showStoryDetail(storyId) {
         </div>
       ` : ''}
 
+      ${projectIsSharedCache[story.project_id] === 1 ? `
+        <!-- KJC-PRP-0002 PR6: per-HU assignee — only surfaced when the
+             project is team-shared. Free-form string; no entity table. -->
+        <div class="modal__section">
+          <div class="modal__section-title">Asignado a</div>
+          <div class="modal__field-value" style="font-family:monospace">${esc(story.assignee || '—')}</div>
+          ${canEdit ? `
+            <div style="margin-top:6px;display:flex;gap:6px;align-items:center">
+              <input id="hu-assignee" type="text" placeholder="@manu, dev_016, becaria…"
+                     value="${esc(story.assignee || '')}"
+                     style="flex:1;padding:4px;background:var(--bg-primary);color:var(--text);border:1px solid var(--border);border-radius:4px;font-family:monospace;font-size:0.8rem">
+              <button onclick="saveHuAssignee('${esc(story.id)}')" class="control-btn"
+                      style="padding:4px 10px;background:var(--bg-primary);color:var(--text);border:1px solid var(--border);border-radius:4px;cursor:pointer;font-size:0.8rem">
+                💾 Save
+              </button>
+            </div>
+            <div style="margin-top:4px;color:var(--text-muted);font-size:0.75rem">vacío → sin asignar</div>
+          ` : ''}
+        </div>
+      ` : ''}
+
       ${story.certified_as ? `
         <div class="modal__section">
           <div class="modal__section-title">Certified Story</div>
@@ -3300,7 +3352,10 @@ async function showConfigEditor(scope = 'global') {
         <span style="font-size:0.85rem;color:var(--text-muted);">${f.value ? 'activado' : 'desactivado'}</span>
       </label>`;
     } else if (f.type === 'number') {
-      input = `<input type="number" id="${id}" data-key="${esc(f.key)}" value="${esc(String(f.value))}"${f.min != null ? ` min="${f.min}"` : ''}${f.max != null ? ` max="${f.max}"` : ''} style="width:120px;padding:6px 8px;background:var(--bg-primary);border:1px solid var(--border);color:var(--text);border-radius:var(--radius-sm);">`;
+      // KJC-BUG-0069 — honour the schema's `step` (e.g. 'any' for floats like
+      // rag.search.alpha=0.6). HTML5 number inputs default to step=1, which
+      // marks any fractional value as stepMismatch and refuses to commit.
+      input = `<input type="number" id="${id}" data-key="${esc(f.key)}" value="${esc(String(f.value))}"${f.min != null ? ` min="${f.min}"` : ''}${f.max != null ? ` max="${f.max}"` : ''}${f.step != null ? ` step="${esc(String(f.step))}"` : ''} style="width:120px;padding:6px 8px;background:var(--bg-primary);border:1px solid var(--border);color:var(--text);border-radius:var(--radius-sm);">`;
     }
     return `
       <div style="margin-bottom:14px;">

package/packages/hu-board/public/styles.css

@@ -770,6 +770,15 @@ a:hover {
   margin-bottom: 8px;
 }
 
+/* KJC-PRP-0002 PR3: 🔗 badge for projects with a plan in .karajan-shared/. */
+.project-card__shared-badge {
+  display: inline-block;
+  font-size: 0.85em;
+  margin-right: 4px;
+  cursor: help;
+  vertical-align: baseline;
+}
+
 .project-card__stats {
   display: grid;
   grid-template-columns: repeat(3, 1fr);

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

@@ -79,6 +79,11 @@ export const CATEGORIES = [
   { id: 'rag',      label: 'RAG (búsqueda de contexto)', icon: '📚', order: 3 },
   { id: 'session',  label: 'Tiempos de sesión',        icon: '⏱',  order: 4 },
   { id: 'quality',  label: 'Calidad',                  icon: '✅', order: 5 },
+  // KJC-PRP-0002 PR5: team-shared HU board controls. Today only carries
+  // the conflict-resolution policy when a planId lives in both
+  // ~/.karajan/plans/ (per-user) and <projectDir>/.karajan-shared/plans/
+  // (team-committed). Will grow as more board-level multi-user knobs land.
+  { id: 'huBoard',  label: 'HU Board (equipo)',        icon: '🔗', order: 6 },
 ];
 
 /**
@@ -230,11 +235,10 @@ export const EDITABLE_FIELDS = [
     help: 'Orquestador IA central: enriquece feedback, comprime outputs y verifica cambios reales. Opt-in.',
     default: false,
   },
-  // v2.30.0 — RAG controls. Sólo se exponen las claves que el código
-  // realmente lee hoy (rag.preload.* en rag-context-stage.js y
-  // rag.embedder.provider en embedders/factory.js). mode/alpha/rerank
-  // se controlan vía flags CLI; cuando se cableen en config se añadirán
-  // aquí (ver task #99).
+  // v2.30.0 — RAG controls. Cubren los tres ejes que afectan al
+  // retrieval en tiempo de pipeline: pre-carga (rag.preload.*),
+  // proveedor de embeddings (rag.embedder.provider) y parámetros de
+  // búsqueda (rag.search.*, cableados al stage en KJC-TSK-0463).
   {
     key: 'ragPreloadEnabled',
     path: 'rag.preload.enabled',
@@ -275,6 +279,58 @@ export const EDITABLE_FIELDS = [
     options: ['ollama', 'openai', 'voyage', 'cohere', 'mistral', 'onnx'],
     default: 'ollama',
   },
+  // KJC-TSK-0463 — search-time knobs ahora cableados al stage.
+  // mode/alpha controlan el fuse semantic vs keyword; rerank activa el
+  // cross-encoder opcional (más calidad, más latencia).
+  {
+    key: 'ragSearchMode',
+    path: 'rag.search.mode',
+    category: 'rag',
+    type: 'select',
+    label: 'Modo de búsqueda RAG',
+    help: '"hybrid" mezcla semántico + BM25 (recomendado). "semantic" sólo embeddings. "keyword" sólo BM25 (útil si los embeddings están desafinados).',
+    options: ['hybrid', 'semantic', 'keyword'],
+    default: 'hybrid',
+  },
+  {
+    key: 'ragSearchAlpha',
+    path: 'rag.search.alpha',
+    category: 'rag',
+    type: 'number',
+    label: 'Alpha del modo hybrid (0-1)',
+    help: 'Peso del scoring semántico vs keyword en modo hybrid. 1.0 = sólo semántico, 0.0 = sólo BM25, 0.6 (default) = inclinado a semántico.',
+    min: 0,
+    max: 1,
+    // KJC-BUG-0069 — number input defaults to step=1 (HTML5), so any
+    // non-integer default fails validity. Allow any fractional value here.
+    step: 'any',
+    default: 0.6,
+  },
+  {
+    key: 'ragSearchRerank',
+    path: 'rag.search.rerank',
+    category: 'rag',
+    type: 'boolean',
+    label: 'Activar rerank cross-encoder',
+    help: 'Re-puntúa los topK supervivientes con un cross-encoder. Mejora calidad pero añade latencia y requiere modelo extra. Opt-in.',
+    default: false,
+  },
+  // KJC-PRP-0002 PR5: when the board scans plans, it visits both
+  // ~/.karajan/plans/<slug>/ (per-user cache) and .karajan-shared/plans/
+  // (team copy). If a planId lives in both, the second pass overwrites
+  // the first. Before this knob the order was hard-coded shared-wins
+  // (per-user → shared) — fine in a team but unsafe for a solo dev who
+  // forgets a stale `.karajan-shared/` exists in the repo.
+  {
+    key: 'huBoardSharedConflictPolicy',
+    path: 'huBoard.sharedConflictPolicy',
+    category: 'huBoard',
+    type: 'select',
+    label: 'Política ante plan compartido y local',
+    help: '"shared-wins" (recomendado en equipo): la copia en .karajan-shared/ pisa la local. "local-wins" (solo dev individual): tu copia en ~/.karajan/plans/ pisa la compartida — útil si todavía estás iterando antes de publicarla.',
+    options: ['shared-wins', 'local-wins'],
+    default: 'shared-wins',
+  },
 ];
 
 const ROLES_FOR_MODEL_MODE = [

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

@@ -304,6 +304,12 @@ export function initDb() {
   try { db.exec('ALTER TABLE stories ADD COLUMN reviewer_model TEXT'); } catch { /* already migrated */ }
   try { db.exec('ALTER TABLE stories ADD COLUMN coder_provider TEXT'); } catch { /* already migrated */ }
   try { db.exec('ALTER TABLE stories ADD COLUMN reviewer_provider TEXT'); } catch { /* already migrated */ }
+  // KJC-PRP-0002 PR6: free-form handle of the human (or dev_XXX AI) who
+  // owns this HU on a team-shared board. NULL = unassigned. Only surfaced
+  // in the UI when the parent project is `is_shared = 1`, but stored
+  // unconditionally so solo devs who later promote a plan don't lose
+  // values they typed pre-share.
+  try { db.exec('ALTER TABLE stories ADD COLUMN assignee TEXT'); } catch { /* already migrated */ }
   try { db.exec('CREATE INDEX IF NOT EXISTS idx_stories_plan ON stories(plan_id)'); } catch { /* ignore */ }
 
   // is_test (KJC-TSK-0371 — board polish #3): per-project flag that
@@ -313,6 +319,11 @@ export function initDb() {
   // The UI surfaces this as a toggle on each project card.
   try { db.exec('ALTER TABLE projects ADD COLUMN is_test INTEGER'); } catch { /* already migrated */ }
 
+  // is_shared (KJC-PRP-0002 PR3): 1 when at least one plan of the project came
+  // from `<projectDir>/.karajan-shared/plans/`. Surfaced as a 🔗 badge on the
+  // board so the user can tell at a glance which projects are team-tracked.
+  try { db.exec('ALTER TABLE projects ADD COLUMN is_shared INTEGER'); } catch { /* already migrated */ }
+
   return db;
 }
 
@@ -330,13 +341,17 @@ export function getDb() {
  * @param {{ id: string, name?: string, first_seen?: string, last_activity?: string, total_stories?: number }} project
  */
 export function upsertProject(project) {
+  // is_shared (KJC-PRP-0002 PR3) is set by sync when a plan came from
+  // `.karajan-shared/`. COALESCE with the existing column keeps the badge
+  // once it's been promoted — a second non-shared plan won't unset it.
   const stmt = getDb().prepare(`
-    INSERT INTO projects (id, name, first_seen, last_activity, total_stories)
-    VALUES (@id, @name, @first_seen, @last_activity, @total_stories)
+    INSERT INTO projects (id, name, first_seen, last_activity, total_stories, is_shared)
+    VALUES (@id, @name, @first_seen, @last_activity, @total_stories, @is_shared)
     ON CONFLICT(id) DO UPDATE SET
       name = COALESCE(@name, name),
       last_activity = COALESCE(@last_activity, last_activity),
-      total_stories = COALESCE(@total_stories, total_stories)
+      total_stories = COALESCE(@total_stories, total_stories),
+      is_shared = COALESCE(@is_shared, is_shared)
   `);
   stmt.run({
     id: project.id,
@@ -344,6 +359,7 @@ export function upsertProject(project) {
     first_seen: project.first_seen || new Date().toISOString(),
     last_activity: project.last_activity || new Date().toISOString(),
     total_stories: project.total_stories || 0,
+    is_shared: project.is_shared ?? null,
   });
 }
 
@@ -360,7 +376,7 @@ export function upsertStory(story) {
       antipatterns, ac_format, acceptance_criteria,
       created_at, updated_at, certified_at, plan_id,
       ac_count, test_count, blocked_by, acceptance_tests, plan_order, spec_section, outcome, result,
-      coder_model, reviewer_model, coder_provider, reviewer_provider
+      coder_model, reviewer_model, coder_provider, reviewer_provider, assignee
     ) VALUES (
       @id, @project_id, @session_id, @status, @title, @original_text,
       @certified_as, @certified_want, @certified_so_that,
@@ -368,7 +384,7 @@ export function upsertStory(story) {
       @antipatterns, @ac_format, @acceptance_criteria,
       @created_at, @updated_at, @certified_at, @plan_id,
       @ac_count, @test_count, @blocked_by, @acceptance_tests, @plan_order, @spec_section, @outcome, @result,
-      @coder_model, @reviewer_model, @coder_provider, @reviewer_provider
+      @coder_model, @reviewer_model, @coder_provider, @reviewer_provider, @assignee
     )
     ON CONFLICT(id) DO UPDATE SET
       status = @status,
@@ -401,7 +417,8 @@ export function upsertStory(story) {
       coder_model = COALESCE(@coder_model, coder_model),
       reviewer_model = COALESCE(@reviewer_model, reviewer_model),
       coder_provider = COALESCE(@coder_provider, coder_provider),
-      reviewer_provider = COALESCE(@reviewer_provider, reviewer_provider)
+      reviewer_provider = COALESCE(@reviewer_provider, reviewer_provider),
+      assignee = COALESCE(@assignee, assignee)
   `);
   stmt.run({
     id: story.id,
@@ -439,6 +456,7 @@ export function upsertStory(story) {
     reviewer_model: story.reviewer_model || null,
     coder_provider: story.coder_provider || null,
     reviewer_provider: story.reviewer_provider || null,
+    assignee: story.assignee || null,
   });
 }
 

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

@@ -557,7 +557,11 @@ const ALLOWED_STORY_STATUSES = new Set(['pending', 'certified', 'done', 'blocked
 // KJC-TSK-0406: coder_model y reviewer_model son editables desde el
 // modal del board. Independientes — el usuario puede subir el reviewer
 // y bajar el coder sin afectar al resto del plan.
-const EDITABLE_HU_FIELDS = ['title', 'scope', 'task_type', 'acceptance_criteria', 'acceptance_tests', 'blocked_by', 'coder_model', 'reviewer_model', 'coder_provider', 'reviewer_provider'];
+// KJC-PRP-0002 PR6: `assignee` is editable from the board modal when the
+// project is team-shared. The whitelist itself is project-agnostic — the
+// modal hides the input on non-shared projects, but accepting the field
+// here doesn't hurt (sync just stores it).
+const EDITABLE_HU_FIELDS = ['title', 'scope', 'task_type', 'acceptance_criteria', 'acceptance_tests', 'blocked_by', 'coder_model', 'reviewer_model', 'coder_provider', 'reviewer_provider', 'assignee'];
 
 router.patch('/stories/:id', (req, res) => {
   try {

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

@@ -24,12 +24,18 @@ router.get("/stats", (_req, res) => {
   if (!existsSync(path)) return res.json({ ok: true, initialized: false, message: "rag.db not initialized — run `kj rag index <dir>` to start indexing.", embedder: embedder() });
   try {
     const db = new Database(path, { readonly: true, fileMustExist: true });
+    // KJC-BUG-0068 — readonly handler cannot run the project_slug migration
+    // (KJC-TSK-0438). Legacy DBs created pre-v2.27 lack the column; detect
+    // and fall back so the dashboard renders instead of crashing with 500.
+    const hasProjectSlug = db.prepare("PRAGMA table_info(chunks)").all().some((c) => c.name === "project_slug");
     const total_chunks = db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
     const by_kind = db.prepare("SELECT kind, COUNT(*) AS n FROM chunks GROUP BY kind").all();
-    const by_project = db.prepare("SELECT COALESCE(project_slug, '(no slug)') AS project, COUNT(*) AS n FROM chunks GROUP BY project_slug ORDER BY n DESC LIMIT 20").all();
+    const by_project = hasProjectSlug
+      ? db.prepare("SELECT COALESCE(project_slug, '(no slug)') AS project, COUNT(*) AS n FROM chunks GROUP BY project_slug ORDER BY n DESC LIMIT 20").all()
+      : [];
     const last_indexed = db.prepare("SELECT MAX(created_at) AS ts FROM chunks").get().ts;
     db.close();
-    res.json({ ok: true, initialized: true, db_path: path, db_size_bytes: statSync(path).size, total_chunks, by_kind, by_project, last_indexed, embedder: embedder() });
+    res.json({ ok: true, initialized: true, db_path: path, db_size_bytes: statSync(path).size, total_chunks, by_kind, by_project, last_indexed, embedder: embedder(), schema_legacy: !hasProjectSlug });
   } catch (err) { res.status(500).json({ ok: false, error: String(err.message || err) }); }
 });
 

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

@@ -14,6 +14,36 @@ import {
   removeTombstone,
 } from './db.js';
 import { publish as publishEvent } from './event-bus.js';
+import { getSharedPlansDir, SHARED_DIR_NAME, isSharedPath } from '../../../src/utils/shared-paths.js';
+import { readConfig } from './config-yaml.js';
+
+/**
+ * KJC-PRP-0002 PR5: resolve the conflict policy that decides who wins
+ * when the same planId is present in both the per-user cache
+ * (~/.karajan/plans/<slug>/) and the shared dir (.karajan-shared/plans/).
+ *
+ * Implementation is "order of last write": `syncPlanFile` upserts by
+ * planId, so whichever scan runs second overwrites whatever the first
+ * one wrote. We just swap the visit order based on policy.
+ *
+ *   shared-wins (default) → per-user first, shared second
+ *   local-wins            → shared first, per-user second
+ *
+ * Reads from kj.config.yml live; absent / malformed config falls back to
+ * the safe team default. Project scope wins over global scope (same
+ * precedence the rest of the config UI honours).
+ */
+function getSharedConflictPolicy() {
+  const pluck = (cfg) => cfg?.raw?.huBoard?.sharedConflictPolicy;
+  const valid = (v) => v === 'local-wins' || v === 'shared-wins';
+  try {
+    const projectCfg = readConfig({ scope: 'project' });
+    if (valid(pluck(projectCfg))) return pluck(projectCfg);
+    const globalCfg = readConfig({ scope: 'global' });
+    if (valid(pluck(globalCfg))) return pluck(globalCfg);
+  } catch { /* swallow — config UI handles surfacing errors */ }
+  return 'shared-wins';
+}
 
 /**
  * Skip + best-effort fs cleanup when the resource is tombstoned. Returns
@@ -381,11 +411,17 @@ export function syncPlanFile(filePath) {
       || slugToTitle(data.task || '')
       || projectId;
 
+    // KJC-PRP-0002 PR3: stamp `is_shared` from the path (authoritative — works
+    // even for legacy plan files without the `shared:true` envelope marker).
+    // OR with existing value so a single shared plan promotes the project,
+    // while unsharing the LAST shared plan still leaves the flag set (we
+    // clear it lazily only when the user explicitly tombstones / re-creates).
     upsertProject({
       id: projectId,
       name: projectName,
       last_activity: data.updatedAt || data.createdAt || new Date().toISOString(),
       total_stories: data.hus.length,
+      is_shared: isSharedPath(filePath) || data.shared === true ? 1 : undefined,
     });
 
     for (let i = 0; i < data.hus.length; i += 1) {
@@ -468,6 +504,10 @@ export function syncPlanFile(filePath) {
         reviewer_model: hu.reviewer_model || null,
         coder_provider: hu.coder_provider || null,
         reviewer_provider: hu.reviewer_provider || null,
+        // KJC-PRP-0002 PR6: optional handle of the owner of this HU
+        // (free-form string). Only surfaced in UI when project is_shared,
+        // but stored unconditionally so values survive share/unshare flips.
+        assignee: typeof hu.assignee === 'string' && hu.assignee.trim() ? hu.assignee.trim() : null,
       });
     }
 
@@ -527,32 +567,72 @@ export function fullScan() {
     }
   }
 
-  // Scan v2 plans (`kj plan` writes to `~/.karajan/plans/<slug>/` after
-  // KJC-PCS-0047 PR 3). `KJ_PLANS_DIR` keeps overriding for test
-  // isolation. A second pass picks up the legacy `~/.kj/plans/`
-  // location for users whose CLI hasn't yet run the migrator (e.g.
-  // the board was started before any `kj` command on a fresh upgrade).
-  const kjDir = process.env.KJ_PLANS_DIR || join(homedir(), '.karajan', 'plans');
-  const legacyKjDir = process.env.KJ_PLANS_DIR ? null : join(homedir(), '.kj', 'plans');
-  for (const root of [kjDir, legacyKjDir]) {
-    if (!root || !existsSync(root)) continue;
-    const projectDirs = readdirSync(root);
-    for (const projDir of projectDirs) {
-      const projPath = join(root, projDir);
-      try {
-        const files = readdirSync(projPath);
-        for (const file of files) {
-          if (file.startsWith('plan-') && file.endsWith('.json')) {
-            syncPlanFile(join(projPath, file));
+  // KJC-PRP-0002 PR5: order plans scans by conflict policy. `syncPlanFile`
+  // upserts by planId, so whichever pass runs LAST wins. Default
+  // shared-wins matches what teams expect (the committed copy is canonical);
+  // local-wins is the escape hatch for a solo dev still iterating before
+  // publishing. Same projectDir scan, only the order changes.
+  const scanPerUserPlans = () => {
+    const kjDir = process.env.KJ_PLANS_DIR || join(homedir(), '.karajan', 'plans');
+    const legacyKjDir = process.env.KJ_PLANS_DIR ? null : join(homedir(), '.kj', 'plans');
+    for (const root of [kjDir, legacyKjDir]) {
+      if (!root || !existsSync(root)) continue;
+      const projectDirs = readdirSync(root);
+      for (const projDir of projectDirs) {
+        const projPath = join(root, projDir);
+        try {
+          const files = readdirSync(projPath);
+          for (const file of files) {
+            if (file.startsWith('plan-') && file.endsWith('.json')) {
+              syncPlanFile(join(projPath, file));
+            }
           }
-        }
-      } catch { /* skip */ }
+        } catch { /* skip */ }
+      }
     }
+  };
+
+  if (getSharedConflictPolicy() === 'local-wins') {
+    scanSharedPlans();
+    scanPerUserPlans();
+  } else {
+    scanPerUserPlans();
+    scanSharedPlans();
   }
 
   console.log('[sync] Full scan completed');
 }
 
+/**
+ * Scans `<projectDir>/.karajan-shared/plans/` for every known projectDir
+ * and feeds each plan into `syncPlanFile`. Discovery sources:
+ *   1. `process.cwd()` — covers the canonical case of running `kj board start`
+ *      from a project root with a freshly cloned `.karajan-shared/` and zero
+ *      local plans yet.
+ *   2. `KJ_SHARED_PROJECT_DIRS` env var (colon-separated paths) — escape
+ *      hatch for users running the board outside the project root or
+ *      tracking several repos with one board instance.
+ */
+function scanSharedPlans() {
+  const dirs = new Set([process.cwd()]);
+  const extra = process.env.KJ_SHARED_PROJECT_DIRS;
+  if (extra) {
+    for (const p of extra.split(':')) if (p) dirs.add(p);
+  }
+  for (const projectDir of dirs) {
+    const sharedDir = getSharedPlansDir(projectDir);
+    if (!existsSync(sharedDir)) continue;
+    try {
+      const files = readdirSync(sharedDir);
+      for (const file of files) {
+        if (file.startsWith('plan-') && file.endsWith('.json')) {
+          syncPlanFile(join(sharedDir, file));
+        }
+      }
+    } catch { /* skip */ }
+  }
+}
+
 /**
  * Starts the file watcher for live sync.
  * @returns {import('chokidar').FSWatcher}
@@ -576,6 +656,17 @@ export function startWatcher() {
 
   const watchTargets = [storiesGlob, sessionsGlob, plansGlob, promptsGlob];
   if (legacyPlansGlob) watchTargets.push(legacyPlansGlob);
+  // KJC-PRP-0002 PR2: live-watch shared plans for the board's cwd + any
+  // dir listed in KJ_SHARED_PROJECT_DIRS. Without this, `kj plan share`
+  // updates would only land via the next fullScan / manual 🔄.
+  const sharedDirs = new Set([process.cwd()]);
+  const extraShared = process.env.KJ_SHARED_PROJECT_DIRS;
+  if (extraShared) {
+    for (const p of extraShared.split(':')) if (p) sharedDirs.add(p);
+  }
+  for (const d of sharedDirs) {
+    watchTargets.push(join(d, SHARED_DIR_NAME, 'plans', 'plan-*.json'));
+  }
   const watcher = watch(watchTargets, {
     ignoreInitial: true,
     awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 },
@@ -585,6 +676,9 @@ export function startWatcher() {
     if (p.includes('hu-stories')) syncStoryFile(p);
     else if (p.includes('sessions')) syncSessionFile(p);
     else if (p.includes(`${plansRoot}${plansRoot.endsWith('/') ? '' : '/'}`) || p.includes('/plans/')) {
+      // Catches both per-user `~/.karajan/plans/<slug>/plan-*.json` and
+      // team-shared `<projectDir>/.karajan-shared/plans/plan-*.json` — the
+      // path-segment match `/plans/` is the same for both.
       syncPlanFile(p);
     } else if (p.includes('/prompts/')) {
       // Prompt files are RPC packets the runner writes when it needs

package/scripts/ai-attribution-guard.yml

@@ -20,8 +20,12 @@ jobs:
           fetch-depth: 0
 
       - name: Check PR diff for AI attribution
+        # KJC-BUG-0072 — never interpolate ${{ github.* }} directly inside a
+        # `run:` block on pull_request workflows. Pin to env vars instead.
+        env:
+          BASE_REF: ${{ github.base_ref }}
         run: |
-          DIFF=$(git diff origin/${{ github.base_ref }}...HEAD \
+          DIFF=$(git diff "origin/${BASE_REF}...HEAD" \
             -- ':!*.png' ':!*.jpg' ':!*.svg' ':!*.ico' \
                ':!*.lock' ':!package-lock.json' ':!yarn.lock' \
                ':!*.min.js' ':!*.min.css' \
@@ -54,8 +58,11 @@ jobs:
           echo "AI attribution guard: clean"
 
       - name: Check commit messages
+        # KJC-BUG-0072 — same hardening as the diff scan: env-pin the ref.
+        env:
+          BASE_REF: ${{ github.base_ref }}
         run: |
-          COMMITS=$(git log --format='%s%n%b' origin/${{ github.base_ref }}...HEAD)
+          COMMITS=$(git log --format='%s%n%b' "origin/${BASE_REF}...HEAD")
 
           COAUTH='Co-Authored-By:.*\b(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)\b'
           ATTR='(Generated|Created|Written|Built|Authored) (by|with|using) .*(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)'

package/src/cli/register-meta.js

@@ -115,15 +115,25 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--scope <scope>", "plans | code | onboarding | all (default: all)", "all")
     .option("--top-k <n>", "Number of hits to return (default: 5)", "5")
     .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project. Default: cwd basename")
-    .option("--mode <mode>", "hybrid (default) | semantic (cosine only) | keyword (BM25 only)", "hybrid")
+    // KJC-BUG-0070 — the global `--mode` flag maps to `review_mode` in
+    // src/config/overrides.js. We expose the rag-specific knob under
+    // `--rag-mode` to avoid the collision (which crashed the command on
+    // first call). Internally we rebind to `flags.mode` so the handler
+    // in src/commands/rag.js stays untouched.
+    .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("--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")
     .action(async (text, flags) => {
+      // Stash the rag-specific mode and remove it from the flags object so
+      // applyScalarAndBooleanOverrides cannot see a `flags.mode` and write
+      // out.review_mode = "hybrid" — that would fail the schema validator.
+      const ragMode = flags.ragMode;
+      delete flags.ragMode;
       await withConfig(pkgVersion, "rag-query", flags, async ({ config, logger }) => {
-        await ragQueryCommand({ text, config, logger, flags });
+        await ragQueryCommand({ text, config, logger, flags: { ...flags, mode: ragMode } });
       });
     });
 

package/src/cli/register-plan.js

@@ -9,6 +9,8 @@ import {
   planRemoveHuCommand,
   planMigrateResultCommand,
   planFixCommand,
+  planShareCommand,
+  planUnshareCommand,
 } from "../commands/plan.js";
 import { parseCanvasMarkdown } from "../canvas/parse-md.js";
 import { validateCanvas } from "../canvas/validate.js";
@@ -140,6 +142,33 @@ export function registerPlan(program, { pkgVersion }) {
     });
   });
 
+  // KJC-PRP-0002 / v2.31.0 PR1: promote a local plan into the project's
+  // `.karajan-shared/plans/` so teammates picking up the repo (or the same
+  // dev on another machine) see it in their HU Board without re-running
+  // the planner. The shared dir is meant to be committed to git.
+  plan.command("share")
+    .description("Promote a local plan to <projectDir>/.karajan-shared/ so the team can see it")
+    .argument("<planId>")
+    .option("--only <ids>", "Comma-separated HU IDs to include (share a subset)")
+    .option("--exclude <ids>", "Comma-separated HU IDs to omit from the shared copy")
+    .action(async (planId, flags) => {
+      await withConfig(pkgVersion, "plan", flags, async ({ config, logger }) => {
+        await planShareCommand({ config, planId, logger, only: flags.only, exclude: flags.exclude });
+      });
+    });
+
+  // KJC-PRP-0002 / v2.31.0 PR3: inverse of `kj plan share`. Removes the plan
+  // from `.karajan-shared/plans/` but keeps the per-user copy intact, so the
+  // dev still has the plan locally while the team stops seeing it.
+  plan.command("unshare")
+    .description("Remove a plan from <projectDir>/.karajan-shared/ (keeps local copy)")
+    .argument("<planId>")
+    .action(async (planId, flags) => {
+      await withConfig(pkgVersion, "plan", flags, async ({ config, logger }) => {
+        await planUnshareCommand({ config, planId, logger });
+      });
+    });
+
   plan.command("add-hu").description("Add HU to plan").argument("<planId>")
     .option("--title <text>", "HU title")
     .option("--type <type>", "Task type: sw|infra|doc|add-tests|refactor|nocode", "sw")

package/src/commands/plan/index.js

@@ -9,3 +9,5 @@ export { planAddHuCommand } from "./add-hu.js";
 export { planRemoveHuCommand } from "./remove-hu.js";
 export { planMigrateResultCommand } from "./migrate-result.js";
 export { planFixCommand } from "./fix.js";
+export { planShareCommand } from "./share.js";
+export { planUnshareCommand } from "./unshare.js";

package/src/commands/plan/share.js

@@ -0,0 +1,85 @@
+/**
+ * kj plan share <planId>
+ *
+ * Promotes a local plan (under `~/.karajan/plans/<projectSlug>/`) to the
+ * project's shared dir (`<projectDir>/.karajan-shared/plans/`) so teammates
+ * pulling the repo see the same HUs in their HU Board. KJC-PRP-0002 / PR1.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../utils/atomic-write.js";
+import { getSharedPlansDir } from "../../utils/shared-paths.js";
+import { loadPlan } from "../../plan/plan-store.js";
+
+function parseIdList(raw) {
+  if (!raw) return null;
+  const ids = String(raw).split(",").map((s) => s.trim()).filter(Boolean);
+  return ids.length ? ids : null;
+}
+
+export async function planShareCommand({ config, planId, logger, only, exclude }) {
+  const log = logger || console;
+  const projectDir = config.projectDir || process.cwd();
+
+  if (!planId) {
+    log.error?.("kj plan share <planId> — planId is required");
+    process.exitCode = 1;
+    return;
+  }
+
+  const onlyIds = parseIdList(only);
+  const excludeIds = parseIdList(exclude);
+  if (onlyIds && excludeIds) {
+    log.error?.("kj plan share — --only and --exclude are mutually exclusive");
+    process.exitCode = 1;
+    return;
+  }
+
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) {
+    log.error?.(`Plan not found: ${planId}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // KJC-PRP-0002 PR4: optional per-HU filter. Lets a dev share a curated
+  // subset of HUs without splitting the plan or hand-editing the JSON.
+  let hus = plan.hus || [];
+  let filterSummary = "";
+  if (onlyIds) {
+    hus = hus.filter((h) => onlyIds.includes(h.id));
+    filterSummary = ` [only: ${onlyIds.join(",")}]`;
+  } else if (excludeIds) {
+    hus = hus.filter((h) => !excludeIds.includes(h.id));
+    filterSummary = ` [excluding: ${excludeIds.join(",")}]`;
+  }
+  if ((onlyIds || excludeIds) && hus.length === 0) {
+    log.error?.(`No HUs left after applying filter — aborting share.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const sharedDir = getSharedPlansDir(projectDir);
+  await fs.mkdir(sharedDir, { recursive: true });
+  const targetFile = path.join(sharedDir, `${plan.planId}.json`);
+
+  // Stamp a `shared: true` marker so consumers (board sync, audit, etc.)
+  // can tell promoted copies from local ones without inspecting the path.
+  const sharedPlan = {
+    ...plan,
+    hus,
+    shared: true,
+    sharedAt: new Date().toISOString(),
+  };
+  if (onlyIds || excludeIds) {
+    sharedPlan.sharedFilter = onlyIds
+      ? { only: onlyIds }
+      : { exclude: excludeIds };
+  }
+  await writeJsonAtomic(targetFile, sharedPlan);
+
+  const rel = path.relative(projectDir, targetFile);
+  log.info?.(`✓ Shared plan ${plan.planId} → ${rel}${filterSummary}`);
+  log.info?.(`  Commit '.karajan-shared/' so your team picks it up.`);
+}

package/src/commands/plan/unshare.js

@@ -0,0 +1,41 @@
+/**
+ * kj plan unshare <planId>
+ *
+ * Inverse of `kj plan share`. Removes the plan from the project's shared dir
+ * (`<projectDir>/.karajan-shared/plans/`). The per-user copy at
+ * `~/.karajan/plans/<projectSlug>/<planId>.json` stays untouched, so the dev
+ * keeps the plan locally while the team stops seeing it. KJC-PRP-0002 / PR3.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSharedPlansDir } from "../../utils/shared-paths.js";
+
+export async function planUnshareCommand({ config, planId, logger }) {
+  const log = logger || console;
+  const projectDir = config.projectDir || process.cwd();
+
+  if (!planId) {
+    log.error?.("kj plan unshare <planId> — planId is required");
+    process.exitCode = 1;
+    return;
+  }
+
+  const sharedDir = getSharedPlansDir(projectDir);
+  const targetFile = path.join(sharedDir, `${planId}.json`);
+
+  try {
+    await fs.unlink(targetFile);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      log.error?.(`Plan not shared: ${planId} (no file at .karajan-shared/plans/)`);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+
+  const rel = path.relative(projectDir, targetFile);
+  log.info?.(`✓ Unshared plan ${planId} (removed ${rel})`);
+  log.info?.(`  Commit '.karajan-shared/' so your team stops seeing it.`);
+}

package/src/commands/plan.js

@@ -12,4 +12,6 @@ export {
   planRemoveHuCommand,
   planMigrateResultCommand,
   planFixCommand,
+  planShareCommand,
+  planUnshareCommand,
 } from "./plan/index.js";

package/src/orchestrator/stages/rag-context-stage.js

@@ -11,8 +11,25 @@ import { query } from "../../rag/retriever.js";
 
 const DEFAULT_TOP_K = 5;
 const DEFAULT_SCOPE = "all";
+const DEFAULT_SEARCH_MODE = "hybrid";
+const DEFAULT_SEARCH_ALPHA = 0.6;
 const MAX_CHUNK_CHARS = 600;
 
+// KJC-TSK-0463 — pull search-time knobs from config so the HU Board
+// modal (rag.search.{mode,alpha,rerank}) actually steers retrieval at
+// pipeline time. Returns the args object query() expects; unset fields
+// fall back to the retriever's own defaults.
+export function resolveSearchOpts(config) {
+  const s = config?.rag?.search ?? {};
+  const out = {
+    mode: typeof s.mode === "string" ? s.mode : DEFAULT_SEARCH_MODE,
+    alpha: Number.isFinite(s.alpha) ? s.alpha : DEFAULT_SEARCH_ALPHA,
+  };
+  if (s.rerank && typeof s.rerank === "object") out.rerankOpts = s.rerank;
+  else if (s.rerank === true) out.rerankOpts = {};
+  return out;
+}
+
 /**
  * Runs the RAG preload stage. Returns:
  *   { skipped: true, reason }                  — when disabled / empty / error
@@ -36,7 +53,8 @@ export async function runRagContextStage({ config, logger, emitter, eventBase, t
       const topK = preload.topK || DEFAULT_TOP_K;
       const scope = preload.scope || DEFAULT_SCOPE;
       const embedder = makeEmbedder(config);
-      const hits = await query(db, embedder, task, { topK, scope });
+      const searchOpts = resolveSearchOpts(config);
+      const hits = await query(db, embedder, task, { topK, scope, ...searchOpts });
       if (hits.length === 0) return { skipped: true, reason: "no-hits" };
       const lines = hits.map((h) => {
         const label = h.metadata?.hu_id || h.metadata?.symbol || h.metadata?.headingPath?.join(" > ") || "block";
@@ -46,7 +64,7 @@ export async function runRagContextStage({ config, logger, emitter, eventBase, t
       const contextBlock = `## Prior context from RAG (auto-retrieved, top ${hits.length})\n\n${lines.join("\n\n")}`;
       emitProgress(emitter, makeEvent("rag-preload:hits", { ...eventBase, stage: "rag-preload" }, {
         message: `RAG preload: injected ${hits.length} chunk(s) into the task context`,
-        detail: { topK, scope, hits: hits.length },
+        detail: { topK, scope, hits: hits.length, mode: searchOpts.mode, alpha: searchOpts.alpha, rerank: Boolean(searchOpts.rerankOpts) },
       }));
       return { skipped: false, contextBlock, hits };
     } finally {

package/src/plan/plan-hu-ops.js

@@ -68,6 +68,12 @@ export function addHu(plan, huData) {
     coder_provider: huData.coder_provider ?? null,
     reviewer_model: huData.reviewer_model ?? null,
     reviewer_provider: huData.reviewer_provider ?? null,
+    // KJC-PRP-0002 PR6: optional handle of the human (or AI dev_XXX) who
+    // owns this HU in a team-shared board. null = unassigned. Free-form
+    // string — the board prints it as-is; no entity table is enforced
+    // because team rosters are out of scope (and would force every solo
+    // dev to register themselves).
+    assignee: huData.assignee ?? null,
     createdAt: new Date().toISOString(),
     updatedAt: new Date().toISOString()
   };
@@ -106,7 +112,7 @@ export function updateHu(plan, huId, patch) {
   // KJC-TSK-0405: coder_model y reviewer_model son override per-HU del
   // routing automático del triage. Independientes — el usuario puede
   // subir el reviewer sin tocar el coder, o viceversa.
-  const allowed = ["title", "task_type", "scope", "acceptance_criteria", "acceptance_tests", "blocked_by", "reuse", "spec_section", "result", "short_id", "coder_model", "reviewer_model", "coder_provider", "reviewer_provider"];
+  const allowed = ["title", "task_type", "scope", "acceptance_criteria", "acceptance_tests", "blocked_by", "reuse", "spec_section", "result", "short_id", "coder_model", "reviewer_model", "coder_provider", "reviewer_provider", "assignee"];
   for (const key of allowed) {
     if (patch[key] !== undefined) hu[key] = patch[key];
   }

package/src/plan/plan-store.js

@@ -8,6 +8,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { writeJsonAtomic } from "../utils/atomic-write.js";
 import { resolveHome } from "../utils/paths.js";
+import { getSharedPlansDir } from "../utils/shared-paths.js";
 import { generatePlanId, normaliseAlias } from "./plan-id.js";
 
 /**
@@ -154,7 +155,15 @@ async function resolveUniqueAlias(dir, ownPlanId, base) {
  */
 export async function loadPlan(projectDir, ref) {
   if (!ref) return null;
-  const dir = plansDir(projectDir);
+  // Local plans take precedence — if a teammate's shared copy and your
+  // working copy share a planId, your local edits win until you re-share.
+  const local = await loadPlanFromDir(plansDir(projectDir), ref);
+  if (local) return local;
+  // Fallback: shared plans committed by a teammate. KJC-PRP-0002 PR1.
+  return loadPlanFromDir(getSharedPlansDir(projectDir), ref);
+}
+
+async function loadPlanFromDir(dir, ref) {
   // 1. Match exacto por planId.json (camino caliente).
   const direct = path.join(dir, `${ref}.json`);
   try {

package/src/spec-review/refine-loop.js

@@ -50,7 +50,7 @@ export async function runRefinePass({ spec, findings, role, projectDir, taskFile
   } catch (err) { return { ok: false, error: `persist failed: ${err.message}`, hashChanged: false }; }
 
   const before = sha256(refineRes.refinedSpec);
-  openEditor(v2Path, { logger, openEditorFn });
+  await openEditor(v2Path, { logger, openEditorFn });
   let after;
   try { after = await _fs.readFile(v2Path, "utf8"); }
   catch (err) { return { ok: false, error: `read v2 failed: ${err.message}`, hashChanged: false }; }

package/src/utils/shared-paths.js

@@ -0,0 +1,41 @@
+/**
+ * Team-shared HU Board paths — KJC-PRP-0002 / v2.31.0 PR1.
+ *
+ * The shared root lives INSIDE the project, not in `~/.karajan/`, so a team
+ * can commit it to git (or sync via Drive/SyncThing) and share plans + HU
+ * stories without each member regenerating them locally.
+ *
+ *   <projectDir>/.karajan-shared/
+ *     plans/<planId>.json     ← `kj plan share <planId>` copies here
+ *     hu-stories/<huId>.md    ← reserved for PR2+ (board reads it)
+ *
+ * Keep the dir name in lockstep with the HU Board sync layer
+ * (`packages/hu-board/src/sync.js`) — diverging the constant breaks the
+ * watcher silently. One source of truth lives here.
+ */
+
+import path from "node:path";
+
+export const SHARED_DIR_NAME = ".karajan-shared";
+
+export function getSharedRoot(projectDir) {
+  return path.join(projectDir, SHARED_DIR_NAME);
+}
+
+export function getSharedPlansDir(projectDir) {
+  return path.join(getSharedRoot(projectDir), "plans");
+}
+
+export function getSharedHuStoriesDir(projectDir) {
+  return path.join(getSharedRoot(projectDir), "hu-stories");
+}
+
+/**
+ * Quick check used by callers that decide whether a plan came from local
+ * (`~/.karajan/plans/`) or from the shared dir. The HU Board uses this to
+ * stamp a `source` column on each record so the UI can render a 🌐 badge.
+ */
+export function isSharedPath(p) {
+  if (!p) return false;
+  return p.split(path.sep).includes(SHARED_DIR_NAME);
+}