karajan-code 4.20.1 → 4.22.0

package/README.md

@@ -9,8 +9,8 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/v/karajan-code.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/dw/karajan-code.svg" alt="npm downloads"></a>
+  <a href="https://www.npmjs.com/package/@karajan-family/code"><img src="https://img.shields.io/npm/v/%40karajan-family%2Fcode.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@karajan-family/code"><img src="https://img.shields.io/npm/dw/%40karajan-family%2Fcode.svg" alt="npm downloads"></a>
   <a href="https://github.com/manufosela/karajan-code/actions"><img src="https://github.com/manufosela/karajan-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node.js"></a>
@@ -58,7 +58,7 @@ kj init && kj env install && kj harden && kj review --install-gate
 git config core.hooksPath .karajan/hooks
 ```
 
-Requires git and at least one AI agent CLI — two enables cross-AI review; three enables arbitration. All install routes (npm, binaries, brew, Python wrapper) in the [install docs](https://karajancode.com/docs/v4/install/).
+Requires git and at least one AI agent CLI — two enables cross-AI review; three enables arbitration. The npm route is `npm install -g @karajan-family/code` (published as `karajan-code` before joining the scope; the legacy name still installs the same versions). All install routes (npm, binaries, brew, Python wrapper) in the [install docs](https://karajancode.com/docs/v4/install/).
 
 ## The daily loop
 
@@ -85,6 +85,8 @@ With a declared `.karajan/policy.yml`, the policy layer enforces at three tiers,
 
 Tier B is the guarantee floor — hosts without hooks lose A, never B; C re-verifies both. Security-class rules and consumer defaults are non-exemptable at every tier: no escape, no arbitration, no grant.
 
+Every chokepoint decision lands in a hash-chained log (`kj policy anchor` seals its head in git), and `kj policy report` turns that log into evidence of process: per rule, how often it warned, denied or was exempted, which denials are still open, which grants are alive, expired or renewed — so a rule "gains teeth" on data, not on a hunch, and a renewed exception is read for what it is: the policy asking to change.
+
 ## Headless mode
 
 The classic multiagent pipeline lives on for CI and automation: `kj run "<task>"` orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. Agents and CI pass `--non-interactive` (or `KJ_NON_INTERACTIVE=1`): safe gates auto-answer, FAIL findings stop the run with a real exit code. `kj advanced` lists the full surface. [Headless mode docs](https://karajancode.com/docs/v4/headless/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.20.1",
+  "version": "4.22.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -38,7 +38,8 @@
     "packages/ai-trash",
     "packages/core",
     "packages/hu-board",
-    "packages/governance"
+    "packages/governance",
+    "packages/console"
   ],
   "imports": {
     "#utils/*": "./src/utils/*",
@@ -122,6 +123,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "smol-toml": "^1.7.0",
     "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "^0.28.0",
     "eslint": "^10.4.1",

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

@@ -192,6 +192,7 @@ function render() {
     case 'board': return renderBoard();
     case 'sessions': return renderSessions();
     case 'graph': return renderGraph();
+    case 'governance': return renderGovernance();
     default: return renderDashboard();
   }
 }

package/packages/hu-board/public/index.html

@@ -24,6 +24,7 @@
       <button class="nav-btn" data-view="graph" title="Dependency graph of the selected project's HUs — who blocks whom. Useful before scheduling work.">Graph</button>
       <button class="nav-btn" data-view="dashboard" title="Per-project landing: stats grid + project list. Click a project card to focus the kanban / graph on that project.">Dashboard</button>
       <button class="nav-btn" data-view="sessions" title="Every kj run that has touched the board, newest first. Filter by project; click a session to inspect its iterations, commits and checkpoints.">Sessions</button>
+      <button class="nav-btn" data-view="governance" title="The acta: policy rules by friction, the hash-chained decision log and its anchor, standing exceptions with owner and expiry, renewals and signals.">Governance</button>
       <a class="nav-btn" href="/pipeline.html" title="Live observability of pipeline runs (Karajan v2.7+): stage timings, agent calls, decision logs.">Pipeline</a>
       <a class="nav-btn" href="/rag.html" title="RAG retrieval-quality dashboard: chunk counts, embedder provider, db size.">RAG</a>
       <a class="nav-btn" href="/wiki.html" title="Search the per-project QMD semantic wiki (docs, plans, reviews).">Wiki</a>
@@ -59,6 +60,7 @@
   <script src="/utils/board-view.js"></script>
   <script src="/utils/dashboard-view.js"></script>
   <script src="/utils/graph-view.js"></script>
+  <script src="/utils/governance-view.js"></script>
   <script src="/utils/project-picker-view.js"></script>
   <script src="/utils/story-detail-view.js"></script>
   <script src="/utils/preflight-view.js"></script>

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

@@ -826,6 +826,28 @@ a:hover {
 }
 
 /* ---- Empty State ---- */
+/* GUI-B (KJC-TSK-0772) — governance view */
+.gov-dir { display: flex; gap: 0.5rem; align-items: center; }
+.gov-dir__input { min-width: 18rem; padding: 0.3rem 0.5rem; font-family: inherit; }
+.gov-btn { padding: 0.3rem 0.75rem; cursor: pointer; }
+.gov-note { margin: 0.5rem 0; opacity: 0.85; }
+.gov-note--warn { color: #d9a400; }
+.gov-red { color: #e5484d; }
+.gov-small { font-size: 1.1rem; line-height: 1.4; }
+.gov-scroll { overflow-x: auto; max-width: 100%; }
+.gov-table { width: 100%; border-collapse: collapse; font-size: 0.9rem; }
+.gov-table th, .gov-table td { padding: 0.4rem 0.6rem; text-align: left; border-bottom: 1px solid rgba(128, 128, 128, 0.25); white-space: nowrap; }
+.gov-badge { display: inline-block; padding: 0.1rem 0.45rem; border-radius: 999px; font-size: 0.75rem; border: 1px solid currentColor; }
+.gov-badge--deny { color: #e5484d; }
+.gov-badge--warn { color: #d9a400; }
+.gov-badge--security { color: #b44dff; }
+.gov-row--soon td { background: rgba(217, 164, 0, 0.12); }
+.gov-list { margin: 0.5rem 0 1rem 1.25rem; }
+.gov-grant { display: flex; flex-wrap: wrap; gap: 0.5rem; align-items: center; margin: 0.75rem 0; }
+.gov-grant select, .gov-grant input { padding: 0.3rem 0.5rem; font-family: inherit; }
+.gov-pre { white-space: pre-wrap; font-size: 0.85rem; margin: 0 0 1rem; max-height: 18rem; overflow: auto; }
+.gov-pre:empty { display: none; }
+
 .empty-state {
   text-align: center;
   padding: 60px 20px;

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

@@ -0,0 +1,149 @@
+// GUI-B (KJC-TSK-0772) — Governance view: the "acta". A live exception is
+// invisible; here every rule shows its friction, every grant its owner and
+// expiry, every renewal its count. Read-only (actions land in GUI-C).
+// Classic script (no exports), same conventions as dashboard-view.js:
+// api() from utils/api.js, esc() from formatters.js.
+
+const GOV_DIR_KEY = 'kj.governance.dir';
+let govBusy = false;
+
+async function renderGovernance() {
+  const app = document.getElementById('app');
+  // Server-push re-renders the current view on every event; never wipe a
+  // form the user is typing in or a proposal still being translated.
+  const typing = () => { const a = document.activeElement; return govBusy || Boolean(a && a.id && a.id.startsWith('gov-') && app.contains(a)); };
+  if (typing()) return;
+  const dir = localStorage.getItem(GOV_DIR_KEY) || '';
+  app.innerHTML = '<div class="loading"><div class="loading__spinner"></div><p>Loading governance...</p></div>';
+  try {
+    const data = await api('/api/governance' + (dir ? '?dir=' + encodeURIComponent(dir) : ''));
+    if (typing()) return; // the user started typing while we fetched: keep their form
+    if (!data || data.ok === false) {
+      app.innerHTML = govDirForm((data && data.dir) || dir) + `<div class="empty-state"><div class="empty-state__title">Governance unavailable</div><div class="empty-state__text">${esc((data && data.error) || 'governance unavailable')}</div><div class="empty-state__path">Type the absolute directory of a project that ran <code>kj harden</code> and press Load.</div></div>`;
+      return;
+    }
+    localStorage.setItem(GOV_DIR_KEY, data.dir);
+    app.innerHTML = govDirForm(data.dir) + govIdentity(data.identity) + govChain(data.report, data.anchor) + govRules(data.policy, data.report) + govGrants(data.report.grants, data.policy) + govSignals(data.report.signals);
+  } catch (err) {
+    app.innerHTML = govDirForm(dir) + `<div class="empty-state"><div class="empty-state__title">Governance unavailable</div><div class="empty-state__text">${esc(err.message)}</div></div>`;
+  }
+}
+
+function govSetDir() {
+  localStorage.setItem(GOV_DIR_KEY, document.getElementById('gov-dir').value.trim());
+  renderGovernance();
+}
+
+// GUI-C (KJC-TSK-0773): actions call the same CLI commands through the board.
+async function govPost(path, body) {
+  const res = await fetch(path, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ dir: localStorage.getItem(GOV_DIR_KEY) || '', ...body }) });
+  const data = await res.json().catch(() => ({ ok: false, error: `API error: ${res.status}` }));
+  return data;
+}
+
+function govSay(text, warn) {
+  const el = document.getElementById('gov-msg');
+  if (el) { el.textContent = text; el.className = warn ? 'gov-note gov-note--warn' : 'gov-note'; }
+}
+
+// Spoken rule: propose shows the diff kj would write; apply asks first, then --yes.
+async function govRule(apply) {
+  const text = document.getElementById('gov-rule-text').value.trim();
+  const out = document.getElementById('gov-rule-out');
+  if (!text) return govSay('say the rule first', true);
+  if (apply && !(await showConfirm(`Write this rule into .karajan/policy.yml?\n\n${text}\n\nThe diff shown below is what lands.`, { title: 'Apply rule', okLabel: 'Apply' }))) return;
+  govRuleText = text;
+  govRuleOut = apply ? 'applying…' : 'translating…';
+  out.textContent = govRuleOut;
+  govBusy = true;
+  const r = await govPost('/api/governance/rule', { text, apply: apply === true }).finally(() => { govBusy = false; });
+  govRuleOut = r.output || r.error || '';
+  const pre = document.getElementById('gov-rule-out');
+  if (pre) pre.textContent = govRuleOut;
+  if (!r.ok) return govSay(r.error || 'rule refused', true);
+  if (apply) { govRuleText = ''; renderGovernance(); }
+}
+
+async function govAnchor() {
+  const r = await govPost('/api/governance/anchor', {});
+  if (!r.ok) return govSay(r.error || 'anchor failed', true);
+  renderGovernance();
+}
+
+async function govGrant() {
+  const rule = document.getElementById('gov-grant-rule').value.trim();
+  const until = document.getElementById('gov-grant-until').value;
+  const reason = document.getElementById('gov-grant-reason').value.trim();
+  if (!rule || !until || !reason) return govSay('rule, until and reason are required — an exception without who/why/until is a hole', true);
+  const iso = new Date(`${until}T23:59:59Z`).toISOString();
+  if (!(await showConfirm(`Grant a standing exception to ${rule} until ${iso}?\n\n${reason}\n\nIt is recorded with this clone's declared identity and expires on its own.`, { title: 'Grant exception', okLabel: 'Grant' }))) return;
+  const r = await govPost('/api/governance/grant', { rule, until: iso, reason });
+  if (!r.ok) return govSay(r.error || 'grant refused', true);
+  renderGovernance();
+}
+
+const govDirForm = (dir) => `
+  <div class="section-header"><span class="section-header__title">Governance</span>
+    <span class="gov-dir"><input id="gov-dir" class="gov-dir__input" value="${esc(dir)}" placeholder="/absolute/project/dir" aria-label="Project directory">
+    <button class="gov-btn" onclick="govSetDir()">Load</button></span></div>`;
+
+const govIdentity = (id) => id && id.declared
+  ? `<p class="gov-note">Identity declared for this clone: <strong>${esc(id.gh_user)}</strong> · ${esc(id.git_email)}</p>`
+  : '<p class="gov-note gov-note--warn">Identity NOT declared for this clone — <code>kj identity set</code> (the Sentinel fails closed on gh and mutating git until then).</p>';
+
+function govChain(report, anchor) {
+  const d = report.decisions;
+  const chain = report.chain.ok
+    ? `<div class="stat-card__value stat-card__value--green">intact</div><div class="stat-card__label">chain · ${report.chain.length} decisions</div>`
+    : `<div class="stat-card__value gov-red">BROKEN</div><div class="stat-card__label">at entry ${esc(String(report.chain.at))} — ${esc(report.chain.reason || '')}</div>`;
+  const anchorBtn = report.chain.ok && (anchor.stale || !anchor.sealed) ? ' <button class="gov-btn" onclick="govAnchor()">Anchor now</button>' : '';
+  const anch = !anchor.sealed
+    ? `<div class="stat-card__value stat-card__value--yellow">none</div><div class="stat-card__label">anchor${anchorBtn}</div>`
+    : `<div class="stat-card__value ${anchor.stale ? 'stat-card__value--yellow' : 'stat-card__value--green'}">${anchor.length}/${anchor.current}</div><div class="stat-card__label">anchored · ${anchor.stale ? 're-seal pending' : 'up to date'}${anchorBtn}</div>`;
+  const cps = Object.entries(d.chokepoints || {}).map(([k, v]) => `${esc(k)} ${v}`).join(' · ') || 'none';
+  return `<div class="stats-grid">
+    <div class="stat-card">${chain}</div><div class="stat-card">${anch}</div>
+    <div class="stat-card"><div class="stat-card__value">${d.allow}</div><div class="stat-card__label">allow</div></div>
+    <div class="stat-card"><div class="stat-card__value ${d.deny ? 'gov-red' : ''}">${d.deny}</div><div class="stat-card__label">deny · ${d.open} open</div></div>
+    <div class="stat-card"><div class="stat-card__value stat-card__value--purple">${d.exempt}</div><div class="stat-card__label">exempt</div></div>
+    <div class="stat-card"><div class="stat-card__value gov-small">${esc(cps)}</div><div class="stat-card__label">chokepoints</div></div></div>`;
+}
+
+function govRules(policy, report) {
+  const rows = new Map();
+  for (const r of policy.rules || []) rows.set(r.rule_id, { ...r, warns: 0, denies: 0, exempts: 0, open: 0 });
+  for (const i of policy.invariants || []) rows.set(i.id, { rule_id: i.id, enforcement: i.enforcement, class: null, warns: 0, denies: 0, exempts: 0, open: 0 });
+  for (const r of report.rules || []) rows.set(r.rule_id, { ...(rows.get(r.rule_id) || {}), ...r });
+  const head = policy.declared
+    ? (policy.error ? `<p class="gov-note gov-note--warn">policy.yml invalid: ${esc(policy.error)}</p>` : '')
+    : '<p class="gov-note">No <code>.karajan/policy.yml</code> declared — only the consumer defaults apply. Speak a rule: <code>kj policy add "…"</code>.</p>';
+  if (rows.size === 0) return `<div class="section-header"><span class="section-header__title">Rules</span></div>${head}<p class="gov-note">No rule has warned or denied yet.</p>${govRuleBox()}`;
+  const body = [...rows.values()].sort((a, b) => (b.denies + b.warns) - (a.denies + a.warns)).map((r) => `
+    <tr><td><code>${esc(r.rule_id)}</code></td><td><span class="gov-badge gov-badge--${esc(r.enforcement || 'warn')}">${esc(r.enforcement || 'warn')}</span>${r.class === 'security' ? ' <span class="gov-badge gov-badge--security" title="non-exemptable: no escape, no arbitration, no grant">security</span>' : ''}</td>
+    <td>${r.warns}</td><td class="${r.denies ? 'gov-red' : ''}">${r.denies}</td><td>${r.exempts}</td><td class="${r.open ? 'gov-red' : ''}">${r.open}</td></tr>`).join('');
+  return `<div class="section-header"><span class="section-header__title">Rules by friction</span><span class="section-header__count">${rows.size}</span></div>${head}
+    <div class="gov-scroll"><table class="gov-table"><thead><tr><th>rule</th><th>enforcement</th><th>warn</th><th>deny</th><th>exempt</th><th>open</th></tr></thead><tbody>${body}</tbody></table></div>${govRuleBox()}`;
+}
+
+// Typed text and the last proposal survive the server-push re-renders.
+let govRuleText = '';
+let govRuleOut = '';
+const govRuleBox = () => `<div class="gov-grant"><input id="gov-rule-text" class="gov-dir__input" value="${esc(govRuleText)}" oninput="govRuleText=this.value" placeholder="say a rule: the coder never writes .env files" aria-label="Spoken rule">
+  <button class="gov-btn" onclick="govRule(false)">Propose</button><button class="gov-btn" onclick="govRule(true)">Apply</button></div><pre id="gov-rule-out" class="gov-pre" aria-live="polite">${esc(govRuleOut)}</pre>`;
+
+function govGrants(g, policy) {
+  const soon = new Set((g.soon || []).map((e) => e.ts || e.expiresAt + e.rule_id));
+  const row = (e) => `<tr class="${soon.has(e.ts || e.expiresAt + e.rule_id) ? 'gov-row--soon' : ''}"><td><code>${esc(e.rule_id)}</code></td><td>${esc(e.expiresAt || '')}</td><td>${esc((e.who && e.who.git) || '?')}</td><td>${esc(e.justification || '')}</td></tr>`;
+  const alive = (g.alive || []).length
+    ? `<div class="gov-scroll"><table class="gov-table"><thead><tr><th>rule</th><th>until</th><th>granted by</th><th>why</th></tr></thead><tbody>${g.alive.map(row).join('')}</tbody></table></div>`
+    : '<p class="gov-note">No standing exception alive.</p>';
+  const renewals = (g.renewals || []).map((r) => `<li class="gov-red"><code>${esc(r.rule_id)}</code> granted ${r.count} times — a renewed exception is the policy asking to change</li>`).join('');
+  // Only non-security rules can be granted: the inexemptable never gets a form.
+  const grantable = (policy.rules || []).filter((r) => r.class !== 'security').map((r) => `<option value="${esc(r.rule_id)}">${esc(r.rule_id)}</option>`).join('');
+  const form = grantable
+    ? `<div class="gov-grant"><select id="gov-grant-rule" aria-label="Rule">${grantable}</select><input id="gov-grant-until" type="date" aria-label="Until"><input id="gov-grant-reason" class="gov-dir__input" placeholder="why, written now" aria-label="Reason"><button class="gov-btn" onclick="govGrant()">Grant until</button></div>`
+    : '<p class="gov-note">Nothing grantable: no declared non-security rule.</p>';
+  return `<div class="section-header"><span class="section-header__title">Standing exceptions</span><span class="section-header__count">${(g.alive || []).length} alive · ${(g.soon || []).length} expiring · ${(g.expired || []).length} expired · ${g.point || 0} one-off</span></div>${alive}${renewals ? `<ul class="gov-list">${renewals}</ul>` : ''}${form}<p id="gov-msg" class="gov-note"></p>`;
+}
+
+const govSignals = (signals) => `<div class="section-header"><span class="section-header__title">Signals</span></div>${(signals || []).length ? `<ul class="gov-list">${signals.map((s) => `<li>⚠ ${esc(s)}</li>`).join('')}</ul>` : '<p class="gov-note">None.</p>'}`;

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

@@ -0,0 +1,140 @@
+// GUI-A (KJC-TSK-0771, epic KJC-PCS-0076) — governance snapshot of ONE
+// project for the dashboard: the declared policy, the deterministic report
+// (`kj policy report --json`), the anchor state and the clone's declared
+// identity. The board stays decoupled from the CLI tree (KJC-TSK-0632): the
+// report comes from the kj binary, everything else is read from the
+// project's .karajan/ files. Read-only; actions land in GUI-C.
+import { Router } from "express";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import yaml from "js-yaml";
+import { runCommand } from "karajan-core/process";
+
+const router = Router();
+
+const readYaml = (file) => {
+  if (!existsSync(file)) return { found: false, data: null, error: null };
+  try { return { found: true, data: yaml.load(readFileSync(file, "utf8")), error: null }; }
+  catch (err) { return { found: true, data: null, error: String(err.message || err) }; }
+};
+
+/** policy.yml → flat rules the view can list (rule ids match the engine's). */
+function policySummary(dir) {
+  const { found, data, error } = readYaml(join(dir, ".karajan", "policy.yml"));
+  if (!found) return { declared: false, rules: [], invariants: [], error: null };
+  if (error || !data || typeof data !== "object") return { declared: true, rules: [], invariants: [], error: error || "policy.yml is not a mapping" };
+  const rules = [];
+  for (const [role, caps] of Object.entries(data.roles || {})) {
+    for (const [cap, spec] of Object.entries(caps || {})) {
+      if (!spec || typeof spec !== "object") continue;
+      for (const kind of ["deny", "allow"]) {
+        if (Array.isArray(spec[kind])) rules.push({ rule_id: `roles.${role}.${cap}.${kind}`, role, cap, kind, patterns: spec[kind], enforcement: spec.enforcement || "warn", class: spec.class || null });
+      }
+    }
+  }
+  const invariants = (Array.isArray(data.invariants) ? data.invariants : []).map((i) => ({ ...i, enforcement: i?.enforcement || "warn" }));
+  return { declared: true, version: data.version ?? null, rules, invariants, error: null };
+}
+
+function anchorState(dir, chainLength) {
+  const file = join(dir, ".karajan", "policy-anchor.json");
+  if (!existsSync(file)) return { sealed: false, length: 0, current: chainLength, stale: chainLength > 0 };
+  try {
+    const a = JSON.parse(readFileSync(file, "utf8"));
+    const length = Number(a.length) || 0;
+    return { sealed: true, head: a.head ?? null, ts: a.ts ?? null, length, current: chainLength, stale: chainLength !== length };
+  } catch (err) { return { sealed: false, length: 0, current: chainLength, stale: true, error: String(err.message || err) }; }
+}
+
+function identityState(dir) {
+  const { found, data } = readYaml(join(dir, ".karajan", "identity.local.yml"));
+  const ok = found && data && typeof data === "object" && data.gh_user && data.git_email;
+  return ok ? { declared: true, gh_user: String(data.gh_user), git_email: String(data.git_email) } : { declared: false };
+}
+
+/** The board may run from a package inside a monorepo: climb to the nearest .karajan/. */
+function nearestProject(start) {
+  let cur = resolve(start);
+  for (;;) {
+    if (existsSync(join(cur, ".karajan"))) return cur;
+    const up = resolve(cur, "..");
+    if (up === cur) return resolve(start);
+    cur = up;
+  }
+}
+
+router.get("/", async (req, res) => {
+  // GUI-B: without dir, the project the board was started for (same rule as
+  // the config editor: KJ_PROJECT_DIR || cwd) — the view remembers the rest.
+  const raw = (typeof req.query.dir === "string" && req.query.dir.trim()) || nearestProject(process.env.KJ_PROJECT_DIR || process.cwd());
+  const dir = resolve(raw);
+  if (!existsSync(join(dir, ".karajan")) || !statSync(join(dir, ".karajan")).isDirectory()) {
+    // Data, not a server error: the view shows the attempted dir and lets the user fix it.
+    return res.json({ ok: false, error: "not a karajan project: no .karajan/ directory", dir });
+  }
+  let report;
+  try {
+    // exit 1 = broken chain: the JSON still carries chain.ok=false — data, not a server error.
+    const r = await runCommand("kj", ["policy", "report", "--json"], { cwd: dir });
+    if (r.exitCode === 127) return res.status(503).json({ ok: false, error: "kj not installed", installable: true });
+    const line = String(r.stdout || "").trim().split("\n").findLast((l) => l.startsWith("{"));
+    report = line ? JSON.parse(line) : null;
+    if (!report) return res.status(502).json({ ok: false, error: "kj policy report produced no JSON", exitCode: r.exitCode, stderr: String(r.stderr || "").slice(0, 500) });
+  } catch (err) {
+    if (err?.code === "ENOENT") return res.status(503).json({ ok: false, error: "kj not installed", installable: true });
+    return res.status(500).json({ ok: false, error: String(err.message || err) });
+  }
+  res.json({ ok: true, dir, policy: policySummary(dir), report, anchor: anchorState(dir, report.chain?.length ?? 0), identity: identityState(dir) });
+});
+
+// GUI-C (KJC-TSK-0773): actions go through the SAME CLI commands the
+// terminal uses — the inexemptable (security, defaults.*) is refused by kj
+// itself and its message travels back verbatim; nothing is re-implemented.
+const projectOf = (req) => {
+  const raw = (typeof req.body?.dir === "string" && req.body.dir.trim()) || nearestProject(process.env.KJ_PROJECT_DIR || process.cwd());
+  const dir = resolve(raw);
+  return existsSync(join(dir, ".karajan")) ? dir : null;
+};
+
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+
+async function runKj(res, dir, args) {
+  try {
+    const r = await runCommand("kj", args, { cwd: dir });
+    // kj logs with colours; the board shows text (ESC built by code: no control char in a regex literal).
+    const output = `${r.stdout || ""}${r.stderr || ""}`.replaceAll(ANSI, "").trim();
+    if (r.exitCode === 127) return res.status(503).json({ ok: false, error: "kj not installed", installable: true });
+    if (r.exitCode !== 0) return res.status(409).json({ ok: false, error: output || `kj exited ${r.exitCode}`, exitCode: r.exitCode });
+    return res.json({ ok: true, output });
+  } catch (err) {
+    if (err?.code === "ENOENT") return res.status(503).json({ ok: false, error: "kj not installed", installable: true });
+    return res.status(500).json({ ok: false, error: String(err.message || err) });
+  }
+}
+
+router.post("/grant", async (req, res) => {
+  const dir = projectOf(req);
+  if (!dir) return res.status(404).json({ ok: false, error: "not a karajan project" });
+  const { rule, until, reason } = req.body || {};
+  if (!rule || !until || !String(reason || "").trim()) return res.status(400).json({ ok: false, error: "rule, until (ISO) and reason are required — an exception without who/why/until is a hole" });
+  if (!identityState(dir).declared) return res.status(409).json({ ok: false, error: "identity not declared for this clone — run kj identity set first (the grant must be attributable)" });
+  return runKj(res, dir, ["policy", "grant", "--rule", String(rule), "--until", String(until), "--reason", String(reason).trim()]);
+});
+
+// Spoken rule: `kj policy add <text>` proposes the diff; ONLY apply:true adds
+// --yes. The engine validates the vocabulary; the human confirms in the board.
+router.post("/rule", async (req, res) => {
+  const dir = projectOf(req);
+  if (!dir) return res.status(404).json({ ok: false, error: "not a karajan project" });
+  const text = String(req.body?.text || "").trim();
+  if (!text) return res.status(400).json({ ok: false, error: "text is required — say the rule" });
+  return runKj(res, dir, ["policy", "add", text, ...(req.body?.apply === true ? ["--yes"] : [])]);
+});
+
+router.post("/anchor", async (req, res) => {
+  const dir = projectOf(req);
+  if (!dir) return res.status(404).json({ ok: false, error: "not a karajan project" });
+  return runKj(res, dir, ["policy", "anchor"]);
+});
+
+export default router;

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

@@ -10,6 +10,7 @@ import apiRoutes from './routes/api.js';
 import pipelineRoutes from './routes/pipeline.js';
 import ragRoutes from './routes/rag.js';
 import wikiRoutes from './routes/wiki.js';
+import governanceRoutes from './routes/governance.js';
 import { authMiddleware } from './auth.js';
 import { getOrCreateToken, getTokenPath } from './token-store.js';
 import { reapZombieSessions } from './zombie-reaper.js';
@@ -301,6 +302,7 @@ async function main() {
   app.use('/api/pipeline', authMiddleware(), pipelineRoutes);
   app.use('/api/rag', authMiddleware(), ragRoutes);
   app.use('/api/wiki', authMiddleware(), wikiRoutes);
+  app.use('/api/governance', authMiddleware(), governanceRoutes);
 
   // SPA fallback: serve index.html for non-API, non-static routes
   app.get('/{*splat}', (_req, res) => {

package/scripts/install.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { tomlPath } from "./toml-value.js";
 
 const rl = readline.createInterface({ input, output });
 const REGISTRY_PATH = path.join(os.homedir(), ".karajan", "instances.json");
@@ -259,10 +260,10 @@ async function setupCodexMcp({ rootDir, kjHome }) {
   const block = [
     '[mcp_servers."karajan-mcp"]',
     'command = "node"',
-    `args = ["${path.join(rootDir, "src", "mcp", "server.js")}"]`,
-    `cwd = "${rootDir}"`,
+    `args = [${tomlPath(path.join(rootDir, "src", "mcp", "server.js"))}]`,
+    `cwd = ${tomlPath(rootDir)}`,
     '[mcp_servers."karajan-mcp".env]',
-    `KJ_HOME = "${kjHome}"`
+    `KJ_HOME = ${tomlPath(kjHome)}`
   ].join("\n");
 
   const updated = upsertCodexMcpBlock(toml, block);

package/scripts/postinstall.js

@@ -11,6 +11,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { tomlPath } from "./toml-value.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(__dirname, "..");
@@ -92,10 +93,10 @@ async function setupCodexMcp(kjHome) {
   const block = [
     '[mcp_servers."karajan-mcp"]',
     'command = "node"',
-    `args = ["${path.join(ROOT_DIR, "src", "mcp", "server.js")}"]`,
-    `cwd = "${ROOT_DIR}"`,
+    `args = [${tomlPath(path.join(ROOT_DIR, "src", "mcp", "server.js"))}]`,
+    `cwd = ${tomlPath(ROOT_DIR)}`,
     '[mcp_servers."karajan-mcp".env]',
-    `KJ_HOME = "${kjHome}"`
+    `KJ_HOME = ${tomlPath(kjHome)}`
   ].join("\n");
 
   const updated = upsertCodexMcpBlock(toml, block);

package/scripts/toml-value.js

@@ -0,0 +1,18 @@
+/**
+ * A filesystem path as a TOML value (KJC-BUG-0151, issue #1426 from dfosela).
+ *
+ * In a double-quoted TOML string `\` opens an escape sequence, so a Windows
+ * path like `C:\Users\...` is not valid TOML: `\U` is read as a unicode escape.
+ * kj wrote the karajan-mcp block that way and codex then failed to load its
+ * ENTIRE config — `codex login` included. kj thought it had configured the MCP;
+ * what it had done was break a tool the user had not touched.
+ *
+ * A literal string (single quotes) interprets nothing, which is exactly what a
+ * path needs. Only a path containing a single quote falls back to the basic
+ * form, escaped properly — never left broken.
+ */
+export function tomlPath(value) {
+  const s = String(value);
+  if (!s.includes("'")) return `'${s}'`;
+  return `"${s.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}

package/src/checks/ai-trash.js

@@ -23,7 +23,7 @@ function createAiTrashCheck() {
         ok: false,
         severity: "warn",
         detail: "kj-trash not found — destructive ops unprotected",
-        fix: "Install karajan-code globally (npm i -g karajan-code) so kj-trash is on PATH, then run `kj-trash install --claude-code`",
+        fix: "Install karajan-code globally (npm i -g @karajan-family/code) so kj-trash is on PATH, then run `kj-trash install --claude-code`",
       };
     },
   };

package/src/checks/mcp-health.js

@@ -109,7 +109,7 @@ export function createKarajanMcpCheck() {
         detail: result.ok
           ? result.detail
           : `karajan-mcp did not respond: ${result.detail} — OPTIONAL in v4: your agent runs kj directly; only shell-less hosts need MCP`,
-        fix: result.ok ? undefined : "Only if you need MCP: install via npm (`npm i -g karajan-code`) — the standalone binary does not bundle it",
+        fix: result.ok ? undefined : "Only if you need MCP: install via npm (`npm i -g @karajan-family/code`) — the standalone binary does not bundle it",
         extra: { binPath },
       };
     },

package/src/checks/native-build.js

@@ -45,7 +45,7 @@ export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpm
             ok: false,
             severity: "warn",
             detail: "better-sqlite3 native build was skipped — pnpm blocks dependency build scripts by default",
-            fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g karajan-code`",
+            fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g @karajan-family/code`",
           };
         }
         return {
@@ -55,7 +55,7 @@ export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpm
           // modules by design — name the consequence (RAG/board/MCP need the
           // npm install) instead of implying the install is broken.
           detail: `better-sqlite3 failed to load: ${firstLine} — DB-backed features (RAG, board, MCP) unavailable; the standalone binary does not bundle native modules`,
-          fix: "Reinstall to rebuild native modules: `npm i -g karajan-code`",
+          fix: "Reinstall to rebuild native modules: `npm i -g @karajan-family/code`",
         };
       }
     },

package/src/checks/release-check.js

@@ -9,6 +9,37 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { runCommand } from "../utils/process.js";
 import { loadPrivacyList, scanPaths } from "../privacy/scan.js";
+import { checkStagedDiff, loadPolicy } from "../policy/engine.js";
+
+// KJC-TSK-0769 — the effect boundary: what ships is re-evaluated against the
+// policy IN FORCE now, not the one each PR was merged under. Artifact rules
+// only: diff-threshold invariants are PR-scoped by definition — skipped, and
+// said — so no line metric is needed (without a tag, the whole tree counts).
+async function policyRangeCheck(projectDir) {
+  const { policy, errors } = loadPolicy({ projectDir });
+  if (errors.length > 0) return { name: "policy", ok: false, detail: `policy.yml invalid — ${errors[0]}` };
+  const described = await runCommand("git", ["-C", projectDir, "describe", "--tags", "--abbrev=0", "--match", "v[0-9]*"]);
+  const tag = described.exitCode === 0 ? described.stdout.trim() : null;
+  const scope = tag ? `${tag}..HEAD` : "whole history (no previous tag)";
+  const prScoped = new Set((policy.invariants ?? []).filter((i) => i.kind === "diff-threshold").map((i) => i.id));
+  try {
+    const listed = await runCommand("git", tag
+      ? ["-C", projectDir, "diff", `${tag}..HEAD`, "--name-only"]
+      : ["-C", projectDir, "ls-tree", "-r", "--name-only", "HEAD"]);
+    if (listed.exitCode !== 0) throw new Error((listed.stderr || "git failed").trim());
+    const files = listed.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+    const violations = checkStagedDiff(policy, { role: "coder", files, netLinesAdded: null }).filter((v) => !prScoped.has(v.rule_id));
+    const hard = violations.filter((v) => v.enforcement === "deny");
+    const skipped = prScoped.size > 0 ? `; ${prScoped.size} diff-threshold invariant(s) skipped (PR-scoped)` : "";
+    if (hard.length > 0) {
+      const list = hard.map((v) => `[${v.rule_id}]${v.file ? ` ${v.file}` : ""}`).join(", ");
+      return { name: "policy", ok: false, detail: `${hard.length} deny violation(s) in ${scope} against the current policy: ${list}` };
+    }
+    return { name: "policy", ok: true, detail: `${scope} clean against the current policy (${violations.length} warning(s))${skipped}` };
+  } catch (err) {
+    return { name: "policy", ok: false, detail: `could not evaluate ${scope}: ${err.message}` };
+  }
+}
 
 const semverCmp = (a, b) => {
   const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
@@ -93,10 +124,39 @@ async function declaredItems(projectDir, config, version) {
   return checks;
 }
 
+/**
+ * MIG-B (KJC-TSK-0752, ADR 0004): while a package dual-publishes under two npm
+ * names, their `latest` dist-tags must move in LOCKSTEP. A torn dual-publish —
+ * one name released, the other not — is invisible from the repo (both installs
+ * "work") and every surface that teaches one name silently diverges from the
+ * other. The pair is read from scripts/dual-publish.mjs, which is the one
+ * place that knows it; no dual script, no check.
+ */
+export async function dualPublishCheck(projectDir, pkg, run = runCommand) {
+  const script = join(projectDir, "scripts", "dual-publish.mjs");
+  if (!pkg?.name || !existsSync(script)) return null;
+  const src = readFileSync(script, "utf8");
+  const legacy = (src.match(/LEGACY_NAME = "([^"]+)"/) || [])[1];
+  const scoped = (src.match(/SCOPED_NAME = "([^"]+)"/) || [])[1];
+  if (!legacy || !scoped || pkg.name !== legacy) return null;
+  const latest = async (name) => {
+    const out = await run("npm", ["view", name, "dist-tags.latest"], { cwd: projectDir });
+    if (out.exitCode !== 0) throw new Error(`npm view ${name} failed`);
+    return (out.stdout || "").trim();
+  };
+  try {
+    const [a, b] = await Promise.all([latest(legacy), latest(scoped)]);
+    const ok = Boolean(a) && a === b;
+    return { name: "dual-publish", ok, detail: ok ? `${legacy} and ${scoped} both at ${a}` : `dist-tags diverge: ${legacy}@${a || "?"} vs ${scoped}@${b || "?"} — a torn dual-publish; publish the missing name before releasing on top` };
+  } catch (err) {
+    return { name: "dual-publish", ok: false, detail: `could not read npm dist-tags (${err.message}) — the lockstep cannot be verified, and unverified is not ok` };
+  }
+}
+
 export async function runReleaseCheck({ projectDir = process.cwd(), config = {} } = {}) {
   const { checks, version, pkg } = await genericChecks(projectDir);
   const pack = await packPrivacyCheck(projectDir, pkg);
-  if (pack) checks.push(pack);
-  checks.push(...await declaredItems(projectDir, config, version));
+  const dual = await dualPublishCheck(projectDir, pkg);
+  checks.push(...(pack ? [pack] : []), ...(dual ? [dual] : []), await policyRangeCheck(projectDir), ...await declaredItems(projectDir, config, version));
   return { ok: checks.every((c) => c.ok), version, checks };
 }