@karajan-family/code 4.21.0

package/src/policy/add.js

@@ -0,0 +1,111 @@
+/**
+ * `kj policy add "<regla hablada>"` (PL-C, KJC-TSK-0735) — el usuario habla,
+ * kj escribe: un agente traduce a UNA regla candidata del vocabulario
+ * CERRADO, parsePolicy valida el merge (lo intraducible se RECHAZA, jamás
+ * se inventa — el YAML es artefacto, no interfaz), se propone el diff y NO
+ * se aplica sin confirmación explícita (--yes).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import { parsePolicy } from "@karajan-family/governance";
+import { createAgent } from "../agents/index.js";
+import { resolveRole } from "../config/role-resolver.js";
+
+const PROMPT = (text) => `Traduce esta regla de proyecto hablada a un FRAGMENTO YAML del vocabulario
+cerrado v1 de policy de Karajan. Vocabulario COMPLETO (nada fuera de esto):
+roles.<rol>.write|shell con allow/deny (listas de globs o patrones de
+comando), enforcement (warn|deny), class (security); invariants con
+{id, kind: diff-threshold, metric: net_lines_added, max, enforcement}.
+Responde SOLO el fragmento YAML (claves raíz: roles y/o invariants), sin
+explicación ni fences. Si la regla NO cabe en el vocabulario, responde
+exactamente: NO_TRADUCIBLE.
+
+Regla: ${text}`;
+
+async function defaultTranslate({ text, config, logger }) {
+  const role = resolveRole(config, "reviewer");
+  const res = await createAgent(role.provider, config, logger).reviewTask({ prompt: PROMPT(text), role: "reviewer" });
+  if (!res?.ok) throw new Error(`el agente traductor (${role.provider}) falló: ${res?.error || "sin salida"}`);
+  return String(res.output || "").replace(/^```[a-z]*\n?|```\s*$/g, "").trim();
+}
+
+// Merge conservador: las listas se CONCATENAN (añadir jamás borra), los
+// escalares nuevos solo entran donde no había valor.
+function mergeFragment(doc, frag) {
+  const out = { version: 1, ...doc };
+  for (const [role, caps] of Object.entries(frag.roles || {})) {
+    out.roles ||= {};
+    out.roles[role] ||= {};
+    for (const [cap, spec] of Object.entries(caps || {})) {
+      const cur = (out.roles[role][cap] ||= {});
+      for (const [k, v] of Object.entries(spec || {})) {
+        cur[k] = Array.isArray(v) ? [...new Set([...(cur[k] || []), ...v])] : (cur[k] ?? v);
+      }
+    }
+  }
+  if (frag.invariants) out.invariants = [...(doc.invariants || []), ...frag.invariants];
+  return out;
+}
+
+const naiveDiff = (oldText, newText) => {
+  const oldLines = new Set(oldText.split("\n"));
+  const newLines = new Set(newText.split("\n"));
+  return [
+    ...[...oldLines].filter((l) => l.trim() && !newLines.has(l)).map((l) => `- ${l}`),
+    ...[...newLines].filter((l) => l.trim() && !oldLines.has(l)).map((l) => `+ ${l}`),
+  ].join("\n");
+};
+
+export async function policyAddCommand({ text, config = {}, flags = {}, logger = console, deps = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  if (!text?.trim()) {
+    logger.error?.('policy add: falta la regla — kj policy add "el coder no toca los workflows"');
+    return 1;
+  }
+  const { translateFn = defaultTranslate } = deps;
+  const raw = await translateFn({ text, config, logger });
+  if (raw.includes("NO_TRADUCIBLE")) {
+    logger.error?.("policy add: la regla no cabe en el vocabulario cerrado v1 — no se inventa nada; exprésala como write/shell/diff-threshold o queda como instrucción de prompt");
+    return 1;
+  }
+  let frag;
+  try {
+    frag = yaml.load(raw);
+  } catch (err) {
+    logger.error?.(`policy add: el agente no devolvió YAML válido (${err.message}) — nada que aplicar`);
+    return 1;
+  }
+  if (typeof frag !== "object" || frag === null || Object.keys(frag).some((k) => !["roles", "invariants"].includes(k))) {
+    logger.error?.("policy add: el fragmento solo puede declarar roles y/o invariants — rechazado (vocabulario cerrado)");
+    return 1;
+  }
+
+  const file = join(projectDir, ".karajan", "policy.yml");
+  let current = "";
+  try {
+    current = readFileSync(file, "utf8");
+  } catch { /* sin policy previa: se propone crearla */ }
+  const merged = mergeFragment(current ? yaml.load(current) || {} : {}, frag);
+  const proposed = yaml.dump(merged, { lineWidth: 100 });
+  const { errors } = parsePolicy(proposed);
+  if (errors.length > 0) {
+    for (const e of errors) logger.error?.(`✗ ${e}`);
+    logger.error?.("policy add: la regla traducida no valida contra el vocabulario del motor — rechazada, no se inventa");
+    return 1;
+  }
+
+  logger.info?.(`policy add — diff propuesto para .karajan/policy.yml:\n${naiveDiff(current, proposed)}`);
+  if (current.includes("#")) {
+    logger.warn?.("⚠ policy add: el fichero actual tiene comentarios y el rewrite NO los preserva — revisa el diff antes de confirmar");
+  }
+  if (!flags.yes) {
+    logger.info?.("policy add: NADA aplicado — re-ejecuta con --yes para escribir (la confirmación es tuya, no del agente)");
+    return 0;
+  }
+  // Primer run sin .karajan/ (catch de codex): crear el padre, no reventar.
+  mkdirSync(join(projectDir, ".karajan"), { recursive: true });
+  writeFileSync(file, proposed, "utf8");
+  logger.info?.("✓ policy add: regla aplicada — los gates (review, pre-commit, tier C) la aplican desde ya");
+  return 0;
+}

package/src/policy/decisions.js

@@ -0,0 +1,42 @@
+/**
+ * Adaptador del registro de decisiones para karajan-code (GOV-C,
+ * KJC-TSK-0747): almacén `.karajan/policy-decisions.jsonl`; policy_hash =
+ * sha256 del policy.yml CRUDO (null sin policy — la decisión lo dice, no
+ * lo inventa). Append no atómico entre procesos: aceptado, el chokepoint
+ * de commit es secuencial.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { recordDecision } from "@karajan-family/governance";
+
+const filePath = (projectDir) => join(projectDir, ".karajan", "policy-decisions.jsonl");
+
+export function policyFileHash(projectDir) {
+  try {
+    return createHash("sha256").update(readFileSync(join(projectDir, ".karajan", "policy.yml"), "utf8"), "utf8").digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/** @returns {object} the sealed record. */
+export function recordGateDecision(projectDir, entry) {
+  return recordDecision({
+    entry,
+    deps: {
+      lastLine: () => {
+        try {
+          const lines = readFileSync(filePath(projectDir), "utf8").split("\n").filter((l) => l.trim());
+          return lines.at(-1) ?? null;
+        } catch {
+          return null;
+        }
+      },
+      append: (line) => {
+        mkdirSync(join(projectDir, ".karajan"), { recursive: true });
+        appendFileSync(filePath(projectDir), `${line}\n`, "utf8");
+      },
+    },
+  });
+}

package/src/policy/engine.js

@@ -0,0 +1,82 @@
+/**
+ * karajan-code policy ADAPTER (GOV-A, KJC-TSK-0745, ADR 0003). El motor
+ * vive en @karajan-family/governance (packages/governance): aquí queda SOLO lo
+ * que es de este dominio — dónde vive el fichero de policy, los defaults
+ * inexcepcionables del supervisor del Sentinel, y el mapeo de tools del
+ * harness (Write/Edit/Bash…) a capabilities del kernel. La superficie
+ * pública de este módulo no cambia: loadPolicy/evalToolCall/checkStagedDiff
+ * siguen siendo lo que los gates de PL-B consumen.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  ALLOW_VERDICT,
+  checkArtifacts,
+  denyVerdict,
+  evalShell,
+  evalWrite,
+  parsePolicy,
+  DEFAULT_POLICY as KERNEL_DEFAULT_POLICY,
+} from "@karajan-family/governance";
+
+// Defaults inexcepcionables de karajan-code: los ficheros del supervisor
+// (antes hardcodeados en el PRETOOL del Sentinel — PL-B). Misma semántica
+// textual: nombrarlos deniega, con o sin root, y la policy no los debilita.
+export const SUPERVISOR_DEFAULTS = [
+  {
+    id: "defaults.supervisor.write",
+    pattern: /\.claude\/settings\.json\b|\.karajan\/(hooks|harness)\//,
+    message: "nombra ficheros del supervisor — solo el humano los modifica, fuera de la sesión",
+  },
+];
+
+// Tools del harness: mapeo acción → capability del kernel. Registro cerrado
+// (fallo de solomon: lo desconocido no se permite a un rol DECLARADO).
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+const READONLY_TOOLS = new Set(["Read", "Grep", "Glob", "LS", "WebFetch", "WebSearch"]);
+
+export const DEFAULT_POLICY = KERNEL_DEFAULT_POLICY;
+
+function defaultReadFile(projectDir) {
+  try {
+    return readFileSync(join(projectDir, ".karajan", "policy.yml"), "utf8");
+  } catch (err) {
+    // Solo ENOENT es "sin policy"; EACCES/EIO seria un fallback silencioso.
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+/**
+ * @returns {{policy: object, errors: string[]}} errors non-empty ⇒ the file
+ * declares something the engine cannot enforce — callers must surface it.
+ */
+export function loadPolicy({ projectDir = process.cwd(), deps = {} } = {}) {
+  const { readFile = defaultReadFile } = deps;
+  let raw;
+  try {
+    raw = readFile(projectDir);
+  } catch (err) {
+    return {
+      policy: { ...KERNEL_DEFAULT_POLICY, defaults: SUPERVISOR_DEFAULTS },
+      errors: [`policy.yml: ilegible (${err.code || err.message}) — presente pero no leible NO es "sin policy"`],
+    };
+  }
+  return parsePolicy(raw, { defaults: SUPERVISOR_DEFAULTS });
+}
+
+/** One tool call against the policy. `root` permite evaluar file_path
+ *  absolutos. Un rol DECLARADO solo usa tools del registro: lo desconocido
+ *  es no-verificable ⇒ deny (roles sin declarar quedan como hoy). */
+export function evalToolCall(policy, { role = "coder", tool, input = {}, root = null }) {
+  if (WRITE_TOOLS.has(tool)) return evalWrite(policy, role, input.file_path || input.notebook_path, root);
+  if (tool === "Bash") return evalShell(policy, role, input.command);
+  if (READONLY_TOOLS.has(tool) || !policy.roles?.[role]) return ALLOW_VERDICT;
+  return denyVerdict(`roles.${role}.tools`, `tool "${tool}" fuera del registro de la policy — no verificable para el rol declarado ${role}`);
+}
+
+/** El gate del RESULTADO en este dominio: los artefactos son los ficheros
+ *  del diff staged y la métrica sale de numstat. */
+export function checkStagedDiff(policy, facts) {
+  return checkArtifacts(policy, facts);
+}

package/src/policy/exceptions.js

@@ -0,0 +1,60 @@
+/**
+ * Adaptador de excepciones de karajan-code (GOV-A, KJC-TSK-0745). El
+ * registro vive en el kernel (@karajan-family/governance); aquí solo lo que es de
+ * este dominio: la identidad (git user + usuario del SO — DECLARADA, no
+ * autenticada) y el destino append-only `.karajan/policy-exceptions.jsonl`.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { userInfo } from "node:os";
+import { spawnSync } from "node:child_process";
+import { recordPolicyException as kernelRecord } from "@karajan-family/governance";
+
+function defaultIdentity(projectDir) {
+  const git = (args) => spawnSync("git", ["-C", projectDir, "config", ...args], { encoding: "utf8" }).stdout?.trim() || null;
+  // grade DECLARADA: git+os es atribución, no autenticación — el registro
+  // no debe venderse como más evidencia de la que es (GOV-B).
+  return { git: `${git(["user.name"]) ?? "?"} <${git(["user.email"]) ?? "?"}>`, os: userInfo().username, grade: "declarada" };
+}
+
+/**
+ * Standing exceptions del dominio code: las permanentes del jsonl. Parse
+ * TOLERANTE — una línea corrupta se descarta CONTÁNDOLA (el gate la
+ * reporta), jamás rompe la evaluación. Las puntuales no dan standing.
+ * @returns {{standing: object[], discarded: number}}
+ */
+export function loadStandingExceptions(projectDir) {
+  let raw;
+  try {
+    raw = readFileSync(join(projectDir, ".karajan", "policy-exceptions.jsonl"), "utf8");
+  } catch {
+    return { standing: [], discarded: 0 };
+  }
+  const standing = [];
+  let discarded = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      // JSON válido pero no-objeto (null, número…) es tan corrupto como el
+      // que no parsea: se descarta contando (catch de codex, explícito).
+      if (typeof rec !== "object" || rec === null) discarded += 1;
+      else if (rec.scopeKind === "permanente") standing.push(rec);
+    } catch {
+      discarded += 1;
+    }
+  }
+  return { standing, discarded };
+}
+
+function defaultAppend(projectDir, line) {
+  const dir = join(projectDir, ".karajan");
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, "policy-exceptions.jsonl"), line, "utf8");
+}
+
+/** @returns {object} the recorded entry (with ts + who resolved). */
+export function recordPolicyException({ projectDir, entry, deps = {} }) {
+  const { append = defaultAppend, identity = defaultIdentity } = deps;
+  return kernelRecord({ projectDir, entry, deps: { append, identity } });
+}

package/src/privacy/onboarding.js

@@ -0,0 +1,35 @@
+/**
+ * privacy onboarding (KJC-TSK-0707, PV-D) — the user never fills YAML by
+ * hand: `kj env install` asks and kj writes `~/.karajan/privacy.yml`.
+ * Every question skips on Enter; answers are NEVER echoed back.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { privacyConfigPath } from "./scan.js";
+
+export async function ensurePrivacyList({ wizard = null, logger = console, isTTY = process.stdout.isTTY } = {}) {
+  const target = privacyConfigPath();
+  if (existsSync(target)) return { created: false, reason: "present" };
+  if (!isTTY || !wizard) {
+    logger.info?.(`⚠ privacy: no personal denylist yet — re-run interactively or create ${target} (personal:/allow:) so YOUR data blocks at every outbound boundary`);
+    return { created: false, reason: "non-interactive" };
+  }
+  logger.info?.("privacy: let's protect your personal data at every outbound boundary (Enter skips any question).");
+  const csv = (s) => String(s || "").split(",").map((x) => x.trim()).filter(Boolean);
+  const personal = [
+    ...csv(await wizard.input("Personal emails that must NEVER be published (comma-separated):")),
+    ...csv(await wizard.input("Personal phone / ID numbers to block (comma-separated, optional):")),
+    ...csv(await wizard.input("Full name to block (optional):")),
+  ];
+  const allow = csv(await wizard.input("Public identities that are FINE to publish (handles, comma-separated):"));
+  if (personal.length === 0 && allow.length === 0) {
+    logger.info?.("privacy: skipped — generic PII detection still warns; create the denylist later to make YOUR data block");
+    return { created: false, reason: "skipped" };
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, `# kj privacy denylist — GLOBAL, never commit this file to any repo.\n${stringifyYaml({ personal, allow })}`);
+  logger.info?.(`✓ privacy: denylist written to ${target} (${personal.length} entrada(s), values not echoed)`);
+  return { created: true, entries: personal.length };
+}

package/src/privacy/scan.js

@@ -0,0 +1,120 @@
+/**
+ * privacy — the outbound boundary scanner (KJC-TSK-0704, epic KJC-PCS-0070).
+ * Born from a real incident (personal emails published on a landing):
+ * outputs get sanitized at boundaries like inputs do. Engine: karajan-rag's
+ * audited redactPII line by line — detects AND masks in one pass, so a
+ * finding never echoes the datum. On top, the user's denylist from
+ * `~/.karajan/privacy.yml` — GLOBAL, never in a repo: the list is sensitive.
+ */
+
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import os from "node:os";
+import { extname, join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { redactPII } from "karajan-rag";
+
+const SKIP_DIRS = new Set(["node_modules", ".git", ".kj"]);
+const BINARY_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".pdf", ".zip", ".gz", ".tgz", ".woff", ".woff2", ".ttf", ".eot", ".mp4", ".db", ".sqlite"]);
+const MAX_FILE_BYTES = 512 * 1024;
+
+export function privacyConfigPath(home = os.homedir()) {
+  // KJ_PRIVACY_CONFIG: test/CI override of the global denylist location.
+  return process.env.KJ_PRIVACY_CONFIG || join(home, ".karajan", "privacy.yml");
+}
+
+/** Personal denylist + public-identity allowlist. Absent file → generics only. */
+export function loadPrivacyList({ home = os.homedir() } = {}) {
+  try {
+    const raw = parseYaml(readFileSync(privacyConfigPath(home), "utf8")) || {};
+    const clean = (xs) => (Array.isArray(xs) ? xs.map(String).map((s) => s.trim()).filter(Boolean) : []);
+    return { personal: clean(raw.personal), allow: clean(raw.allow), present: true };
+  } catch {
+    return { personal: [], allow: [], present: false };
+  }
+}
+
+const maskValue = (v) => (v.length <= 4 ? "***" : `${v.slice(0, 2)}***${v.slice(-2)}`);
+
+// KJC-TSK-0708 — hardcoded secrets. Known token shapes are never legit in
+// an outbound artifact → block; heuristics (credential assignments and
+// user:pass@ connection strings) warn toward .env / a secret manager.
+const SECRET_SHAPES = [
+  { type: "github-token", re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g },
+  { type: "openai-key", re: /\bsk-[A-Za-z0-9_-]{20,}\b/g },
+  { type: "aws-key", re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { type: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  { type: "google-key", re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { type: "private-key", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+  { type: "jwt", re: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+];
+const SECRET_HEURISTICS = [
+  { type: "secret-assignment", re: /\b(?:password|passwd|pwd|secret|token|api[_-]?key|apikey|auth)["']?\s*[:=]\s*["']([^"']{6,})["']/gi },
+  { type: "conn-string", re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:([^\s@/]+)@/gi },
+];
+
+/**
+ * Scan a text. Returns findings — denylist hits as `severity:"block"`
+ * (masked value), generic PII as `severity:"warn"` (line already redacted).
+ */
+export function scanText(text, { list = loadPrivacyList(), source = "<text>" } = {}) {
+  const findings = [];
+  String(text).split("\n").forEach((line, i) => {
+    let probe = line;
+    for (const a of list.allow) probe = probe.split(a).join(" ");
+    for (const p of list.personal) {
+      let at = probe.toLowerCase().indexOf(p.toLowerCase());
+      if (at === -1) continue;
+      findings.push({ severity: "block", type: "denylist", source, line: i + 1, masked: maskValue(p) });
+      // Blank every occurrence so the generics don't double-report it.
+      while (at !== -1) { probe = probe.slice(0, at) + " ".repeat(p.length) + probe.slice(at + p.length); at = probe.toLowerCase().indexOf(p.toLowerCase()); }
+    }
+    for (const { type, re } of SECRET_SHAPES) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(probe)) !== null) {
+        findings.push({ severity: "block", type, source, line: i + 1, masked: maskValue(m[0]) });
+        probe = probe.slice(0, m.index) + " ".repeat(m[0].length) + probe.slice(m.index + m[0].length);
+        re.lastIndex = m.index + m[0].length;
+      }
+    }
+    for (const { type, re } of SECRET_HEURISTICS) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(probe)) !== null) {
+        findings.push({ severity: "warn", type, source, line: i + 1, masked: `${maskValue(m[1])} — move it to .env or a secret manager` });
+        probe = probe.slice(0, m.index) + " ".repeat(m[0].length) + probe.slice(m.index + m[0].length);
+        re.lastIndex = m.index + m[0].length;
+      }
+    }
+    const red = redactPII(probe);
+    if (red.total > 0) {
+      for (const [type, n] of Object.entries(red.counts)) {
+        if (n > 0) findings.push({ severity: "warn", type, source, line: i + 1, masked: red.text.trim().slice(0, 120) });
+      }
+    }
+  });
+  return findings;
+}
+
+/** Scan files/dirs recursively (skips node_modules/.git, binaries, big files). */
+export function scanPaths(paths, { list = loadPrivacyList() } = {}) {
+  const findings = [];
+  const visit = (p) => {
+    if (!existsSync(p)) return;
+    // Skip symlinks: an ancestor link recurses forever; an outside link ships nothing.
+    const st = lstatSync(p);
+    if (st.isSymbolicLink()) return;
+    if (st.isDirectory()) {
+      for (const name of readdirSync(p)) {
+        if (!SKIP_DIRS.has(name)) visit(join(p, name));
+      }
+      return;
+    }
+    if (BINARY_EXT.has(extname(p).toLowerCase()) || st.size > MAX_FILE_BYTES) return;
+    const content = readFileSync(p);
+    if (content.includes(0)) return; // binary sniff: NUL byte
+    findings.push(...scanText(content.toString("utf8"), { list, source: p }));
+  };
+  for (const p of paths) visit(p);
+  return findings;
+}

package/src/prompts/arbiter.js

@@ -0,0 +1,38 @@
+/**
+ * Arbiter prompt (KJC-TSK-0573, design in docs/specs/autonomous-delivery.md §6).
+ *
+ * The Arbiter is Karajan's autonomous decision authority: given a conflict, it
+ * picks the LEAST-BAD option from a closed set and moves forward — no human.
+ */
+
+/** The closed set of conflict-resolution verdicts. BLOCK_AND_CONTINUE is safe. */
+export const VERDICTS = Object.freeze([
+  "ACCEPT_WITH_DEFECT",
+  "RETRY_DIFFERENT_APPROACH",
+  "DESCOPE_HU",
+  "BLOCK_AND_CONTINUE",
+  "PROCEED",
+]);
+
+export function buildArbiterPrompt({ question, options = [], context = null } = {}) {
+  const allowed = options.length ? options.map((o) => o.value) : VERDICTS;
+  return [
+    "You are the Arbiter — Karajan's autonomous decision authority. There is no human to ask.",
+    "Resolve the conflict below by choosing the LEAST-BAD option and moving forward.",
+    "",
+    "Ground-truth order (what wins when signals disagree):",
+    "  1. Acceptance tests passing — beats any reviewer opinion.",
+    "  2. Must-fix issues (security, correctness, data) — beat style.",
+    "  3. Nice-to-have (style, optional refactors) — never block; record as a defect if dropped.",
+    "Goal: maximize 'the ask is met', minimize irreversible risk. Imperfect-but-delivered beats blocked.",
+    "",
+    `Conflict: ${question}`,
+    context ? `Context: ${JSON.stringify(context)}` : "",
+    "",
+    `Choose exactly one verdict from: ${allowed.join(", ")}`,
+    "Respond with ONLY this JSON (no prose):",
+    '{"verdict":"<one of the allowed>","confidence":0.0,"rationale":"why it is the least-bad option","defect":"residual debt if any, else null","directive":"instruction to the coder when RETRY_DIFFERENT_APPROACH, else null"}',
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/src/prompts/architect.js

@@ -0,0 +1,103 @@
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+import { getLanguageInstruction } from "../utils/locale.js";
+import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on designing the architecture for the task."
+].join(" ");
+
+export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
+
+/**
+ * Build the architect prompt as a { stable, volatile } layout (Φ1,
+ * KJC-PCS-0057): instructions, guidelines, schema, contexts and skills
+ * are identical across invocations on the same project; research
+ * context and the task itself go last.
+ */
+export async function buildArchitectPromptLayout({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
+  const langInstruction = getLanguageInstruction(language);
+  let skillSection = null;
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    skillSection = buildSkillSection(skills, { provider, role: "architect" });
+  }
+
+  return buildPromptLayout([
+    section(SUBAGENT_PREAMBLE, STABLE),
+    section(langInstruction, STABLE),
+    section(instructions, STABLE),
+    section("You are the architect in a multi-role AI pipeline.", STABLE),
+    section("Analyze the task and produce a concrete architecture design including layers, patterns, data model, API contracts, dependencies, and tradeoffs.", STABLE),
+    section("## Architecture Guidelines", STABLE),
+    section([
+      "- Identify the architecture type (layered, microservices, event-driven, etc.)",
+      "- Define the layers and their responsibilities",
+      "- Identify design patterns to apply",
+      "- Define the data model with entities",
+      "- Specify API contracts (endpoints, events, interfaces)",
+      "- List external and internal dependencies",
+      "- Document tradeoffs and their rationale",
+      "- If critical decisions cannot be made without more information, list clarifying questions"
+    ].join("\n"), STABLE),
+    section("Return a single valid JSON object and nothing else.", STABLE),
+    section('JSON schema: {"verdict":"ready|needs_clarification","architecture":{"type":string,"layers":[string],"patterns":[string],"dataModel":{"entities":[string]},"apiContracts":[string],"dependencies":[string],"tradeoffs":[string]},"questions":[string],"summary":string}', STABLE),
+    section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
+    section(domainContext ? `## Domain Context\n${domainContext}` : null, STABLE),
+    section(skillSection, STABLE),
+    section(researchContext ? `## Research Context\n${researchContext}` : null, VOLATILE),
+    section(`## Task\n${task}`, VOLATILE),
+  ]);
+}
+
+export async function buildArchitectPrompt(options) {
+  return joinLayout(await buildArchitectPromptLayout(options));
+}
+
+function filterStrings(arr) {
+  if (!Array.isArray(arr)) return [];
+  return arr.filter((item) => typeof item === "string");
+}
+
+export function parseArchitectOutput(raw) {
+  const text = raw?.trim() || "";
+  const jsonMatch = /\{[\s\S]*\}/.exec(text);
+  if (!jsonMatch) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonMatch[0]);
+  } catch { /* architect output is not valid JSON */
+    return null;
+  }
+
+  const verdict = VALID_VERDICTS.has(parsed.verdict)
+    ? parsed.verdict
+    : "needs_clarification";
+
+  const arch = parsed.architecture && typeof parsed.architecture === "object"
+    ? parsed.architecture
+    : {};
+
+  const dataModel = arch.dataModel && typeof arch.dataModel === "object"
+    ? arch.dataModel
+    : {};
+
+  return {
+    verdict,
+    architecture: {
+      type: typeof arch.type === "string" ? arch.type : "",
+      layers: filterStrings(arch.layers),
+      patterns: filterStrings(arch.patterns),
+      dataModel: {
+        entities: filterStrings(dataModel.entities)
+      },
+      apiContracts: filterStrings(arch.apiContracts),
+      dependencies: filterStrings(arch.dependencies),
+      tradeoffs: filterStrings(arch.tradeoffs)
+    },
+    questions: filterStrings(parsed.questions),
+    summary: parsed.summary || ""
+  };
+}