karajan-code 3.3.0 → 3.4.1

package/src/config/loader.js

@@ -187,8 +187,8 @@ function stripRuntimeOnlyKeys(config) {
   // warning on every subsequent kj run.
   if (out.sonarqube && typeof out.sonarqube === "object"
       && Object.prototype.hasOwnProperty.call(out.sonarqube, "enabled")) {
-    const { enabled: _drop, ...rest } = out.sonarqube;
-    void _drop;
+    const rest = { ...out.sonarqube };
+    delete rest.enabled;
     out.sonarqube = rest;
   }
   return out;

package/src/golden/asserter.js

@@ -10,12 +10,14 @@
  * allowed_loc_range need filesystem access — PR-3a wires those.
  */
 
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
 const COMMIT_LINE = /^- `([^`]+)`\s+(.*)$/;
 const SCORE_LINE = /^\*\*Score\*\*:\s*(\d+)\s*\/\s*100/m;
 const AUDIT_ROW = /^\|\s*`audit`\s*\|\s*([^|]+?)\s*\|/m;
 
 function extractSection(content, heading) {
-  const re = new RegExp(`^## ${heading}\\s*$([\\s\\S]*?)(?=^## |\\Z)`, "m");
+  const re = new RegExp(`^## ${escapeRegExp(heading)}\\s*$([\\s\\S]*?)(?=^## |\\Z)`, "m");
   const m = content.match(re);
   return m ? m[1].trim() : "";
 }

package/src/golden/schema.js

@@ -12,7 +12,7 @@ const NonNegInt = v.pipe(v.number(), v.integer(), v.minValue(0));
 const LocRangeSchema = v.pipe(v.array(NonNegInt), v.length(2),
   v.check((arr) => arr[0] <= arr[1], "allowed_loc_range: min must be <= max"));
 
-export const GoldenTaskSchema = v.looseObject({
+const GoldenTaskSchema = v.looseObject({
   id: v.pipe(NonEmptyString, v.regex(/^[a-z0-9_-]+$/, "id must be lowercase a-z0-9_-")),
   title: NonEmptyString,
   prompt: NonEmptyString,

package/src/hu/auto-generator.js

@@ -106,7 +106,7 @@ function filterConflictingHints(hints) {
  * @param {string[]} hints
  * @returns {"python"|"go"|"rust"|"javascript"}
  */
-export function resolveLanguageFromHints(hints) {
+function resolveLanguageFromHints(hints) {
   if (!hints || hints.length === 0) return "javascript";
   if (hints.some((h) => HINT_PYTHON.has(h))) return "python";
   if (hints.some((h) => HINT_GO.has(h))) return "go";

package/src/lang/tree-sitter-loader.js

@@ -24,7 +24,7 @@ async function initRuntime() {
   return runtimePromise;
 }
 
-export function grammarPath(id) {
+function grammarPath(id) {
   return resolve(GRAMMAR_DIR, `${id}.wasm`);
 }
 
@@ -43,7 +43,3 @@ export function getLoaded(id) {
   return cache.get(id) || null;
 }
 
-export function resetForTests() {
-  cache.clear();
-  runtimePromise = null;
-}

package/src/mcp/handlers/management-handlers.js

@@ -16,6 +16,7 @@ import {
 } from "../shared-helpers.js";
 import { buildDashboardJson } from "../../utils/status-dashboard.js";
 import { loadMostRecentSession } from "../../session/store.js";
+import { escapeRegExp } from "../../utils/escape-regexp.js";
 
 const AGENT_ROLES = new Set(["coder", "reviewer", "tester", "security", "solomon"]);
 
@@ -72,9 +73,9 @@ export async function handleAgents(a) {
 function parseHumanResponseOverrides(humanResponse, overrides) {
   for (const role of AGENT_ROLES) {
     const patterns = [
-      new RegExp(String.raw`use\s+(\w+)\s+(?:as|for)\s+${role}`, "i"),
-      new RegExp(String.raw`${role}\s*[:=]\s*(\w+)`, "i"),
-      new RegExp(String.raw`set\s+${role}\s+(?:to|=)\s*(\w+)`, "i")
+      new RegExp(String.raw`use\s+(\w+)\s+(?:as|for)\s+${escapeRegExp(role)}`, "i"),
+      new RegExp(String.raw`${escapeRegExp(role)}\s*[:=]\s*(\w+)`, "i"),
+      new RegExp(String.raw`set\s+${escapeRegExp(role)}\s+(?:to|=)\s*(\w+)`, "i")
     ];
     for (const pat of patterns) {
       const m = pat.exec(humanResponse);

package/src/orchestrator/drivers/post-loop.js

@@ -34,7 +34,6 @@ import { emitProgress, makeEvent } from "../../utils/events.js";
 import { runTesterStage, runSecurityStage, runFinalAuditStage } from "../post-loop-stages.js";
 import { invokeSolomon } from "../solomon-escalation.js";
 import { tryCiComment } from "../ci-integration.js";
-import { writeIterationsJournal } from "../session-journal.js";
 import { getIntegration } from "../integrations.js";
 
 export async function handlePostLoopStages({ config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults, ciEnabled: _ciEnabled, testerEnabled, securityEnabled, askQuestion, logger, brainCtx }) {
@@ -129,103 +128,56 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
   if (rtkSavings) setRtkSavings(session, rtkSavings);
   await saveSession(session);
 
-  // --- Journal: write final files ---
+  // --- Journal: write final files (shared writer, KJC-BUG-0084) ---
   const journalDir = session._journalDir;
   if (journalDir) {
+    // 2026-05-07 dogfooding: gitResult.commits only carries the post-loop
+    // commit (scaffold). Compute the full range from session_start_sha so
+    // every commit the run produced shows up in execution order.
+    let allCommits;
+    try { allCommits = (await listCommitsBetween(session.head_at_start || session.session_start_sha)) || []; }
+    catch { allCommits = gitResult?.commits || []; }
+    const summaryCommits = allCommits.length > 0 ? allCommits : (gitResult?.commits || []);
+
+    // KJC-TSK-0376 — plan adherence metric (deepeval-inspired). When the
+    // run executed against a known plan (`kj run --plan <id>`), score how
+    // faithfully the coder followed it. Pure offline; safe-by-default
+    // (try/catch swallows missing helper or unreadable plan).
+    let planAdherence = null;
     try {
-      await writeIterationsJournal(journalDir, session._journalIterations || []);
-      // decisions.md: writes only when Solomon was invoked (AC of KJC-TSK-0287).
-      // Pulls structured data from session.solomonRulings + session.brainDecisions.
-      const { writeDecisionsJournal: writeDecisionsJournalV2 } =
-        await import("../../session/journal/decisions-writer.js");
-      const decisionsResult = await writeDecisionsJournalV2(session, { journalDir, logger });
-      // KJC-TSK-0288: use the new tree-writer with directory grouping
-      const { writeTreeJournal: writeTreeJournalV2 } =
-        await import("../../session/journal/tree-writer.js");
-      const treeResult = await writeTreeJournalV2(journalDir, session.session_start_sha, { logger });
-
-      const journalFiles = [...(session._journalFiles || [])];
-      if (session._journalIterations?.length) journalFiles.push("iterations.md");
-      if (decisionsResult.written) journalFiles.push("decisions.md");
-      if (treeResult.written) journalFiles.push("tree.txt");
-
-      // KJC-TSK-0289: use the richer summary writer (stages table, budget
-      // breakdown, brain/solomon counts, typed links to other journal files).
-      const { writeSummaryJournal: writeSummaryJournalV2 } =
-        await import("../../session/journal/summary-writer.js");
-      const startedAt = session._startedAt ? new Date(session._startedAt).toISOString() : undefined;
-      // 2026-05-07 dogfooding: gitResult.commits only carries the post-loop
-      // commit (scaffold), not the coder's own commit. The summary's
-      // "Commits" section was therefore misleading — it claimed the run
-      // produced one chore commit when in fact the coder had also written
-      // a docs/feat commit. Compute the full range from session_start_sha
-      // so every commit between then and HEAD shows up in execution order.
-      // try/catch (instead of `.catch(...)`) so we tolerate both promise
-      // rejection AND a sync return of undefined — the latter happens
-      // when a test mocks listCommitsBetween with a plain vi.fn() that
-      // resetAllMocks has stripped of its mockResolvedValue.
-      let allCommits = [];
-      try { allCommits = (await listCommitsBetween(session.head_at_start || session.session_start_sha)) || []; }
-      catch { allCommits = gitResult?.commits || []; }
-      const summaryCommits = allCommits.length > 0 ? allCommits : (gitResult?.commits || []);
-
-      // KJC-TSK-0376 — plan adherence metric (deepeval-inspired). When the
-      // run executed against a known plan (`kj run --plan <id>`), score how
-      // faithfully the coder followed it. Pure offline; safe-by-default
-      // (try/catch swallows missing helper or unreadable plan).
-      let planAdherence = null;
-      try {
-        const planId = session._planRef?.planId
-          || stageResults?.huReviewer?.planId
-          || null;
-        if (planId) {
-          const projectDir = config?.projectDir
-            || session.config_snapshot?.projectDir
-            || process.cwd();
-          const plan = await loadPlan(projectDir, planId).catch(() => null);
-          if (plan && Array.isArray(plan.hus) && plan.hus.length > 0) {
-            const filesChanged = await listFilesChangedSince(
-              session.head_at_start || session.session_start_sha,
-            ).catch(() => []);
-            planAdherence = computePlanAdherenceScore({
-              commits: summaryCommits,
-              plan,
-              filesChanged,
-            });
-          }
+      const planId = session._planRef?.planId
+        || stageResults?.huReviewer?.planId
+        || null;
+      if (planId) {
+        const projectDir = config?.projectDir
+          || session.config_snapshot?.projectDir
+          || process.cwd();
+        const plan = await loadPlan(projectDir, planId).catch(() => null);
+        if (plan && Array.isArray(plan.hus) && plan.hus.length > 0) {
+          const filesChanged = await listFilesChangedSince(
+            session.head_at_start || session.session_start_sha,
+          ).catch(() => []);
+          planAdherence = computePlanAdherenceScore({
+            commits: summaryCommits,
+            plan,
+            filesChanged,
+          });
         }
-      } catch (err) {
-        logger?.warn?.(`Plan adherence calculation skipped: ${err.message}`);
       }
-
-      await writeSummaryJournalV2(journalDir, {
-        task: session.task,
-        result: "APPROVED",
-        sessionId: session.id,
-        iterations: i,
-        durationMs: Date.now() - (session._startedAt || Date.now()),
-        budget: budgetSummary(),
-        stages: stageResults,
-        commits: summaryCommits,
-        files: journalFiles,
-        startedAt,
-        finishedAt: new Date().toISOString(),
-        brainDecisions: Array.isArray(session.brainDecisions) ? session.brainDecisions.length : 0,
-        solomonInvocations: Array.isArray(session.solomonRulings) ? session.solomonRulings.length : 0,
-        // KJC-TSK-0327: surface skill-source decisions in the summary so the
-        // post-mortem shows which process skills (addyosmani) and stack skills
-        // (OpenSkills) actually shaped the role prompts.
-        skills: {
-          addyosmani: session.addyosmaniSkills,
-          installed: session.autoInstalledSkills,
-          recommended: session.skillsRecommended,
-        },
-        planAdherence,
-      }, { logger });
-      logger.info(`Session journal written to ${journalDir}`);
     } catch (err) {
-      logger.warn(`Journal write failed (non-blocking): ${err.message}`);
+      logger?.warn?.(`Plan adherence calculation skipped: ${err.message}`);
     }
+
+    const { writeSessionJournal } = await import("../../session/journal/write-all.js");
+    await writeSessionJournal({
+      session, logger,
+      result: "APPROVED",
+      iterations: i,
+      budget: budgetSummary(),
+      stages: stageResults,
+      commits: summaryCommits,
+      planAdherence,
+    });
   }
 
   // Mirror the same enriched commit list into the session:end event so the

package/src/orchestrator/flow-runner.js

@@ -247,6 +247,31 @@ async function _runFlowInner({ task, config, logger, flags = {}, emitter = null,
     await sealSessionStatusIfStillRunning(ctx.session, result);
     return result;
   } finally {
+    // --- Journal: best-effort write for non-approved endings (KJC-BUG-0084) ---
+    // finalizeApprovedSession writes the journal on the happy path and sets
+    // session._journalWritten. Every other terminal ending (sonar_repeat
+    // stall, stage_error, thrown stage, budget exceeded) used to leave only
+    // triage.md behind — losing the Cache hits table, budget breakdown and
+    // commits exactly on the runs where the post-mortem matters most.
+    // Paused sessions are skipped: they resume later and the eventual
+    // finalize overwrites the journal with the real outcome.
+    try {
+      const s = ctx.session;
+      if (s && s._journalDir && !s._journalWritten && s.status !== "paused") {
+        const { writeSessionJournal } = await import("../session/journal/write-all.js");
+        const badge = s.status && s.status !== "running" ? s.status.toUpperCase() : "FAILED";
+        await writeSessionJournal({
+          session: s, logger,
+          result: badge,
+          iterations: s._journalIterations?.length || 0,
+          budget: typeof ctx.budgetSummary === "function" ? ctx.budgetSummary() : null,
+          stages: ctx.stageResults || {},
+        });
+      }
+    } catch (err) {
+      logger.warn(`Final journal write failed (non-blocking): ${err.message}`);
+    }
+
     // --- Cleanup auto-installed skills ---
     const autoSkills = ctx.session?.autoInstalledSkills;
     if (autoSkills && autoSkills.length > 0) {

package/src/orchestrator/fs-leak-detector.js

@@ -156,11 +156,16 @@ export function detectTranscriptCdLeaks(transcript, projectDir) {
   const projectDirAbs = projectDir ? path.resolve(projectDir) : null;
   const homeDir = os.homedir();
   // Capture cd target + the next ~200 chars of the same line for write-cmd lookup.
-  const cdRegex = /\bcd\s+(~\/[^\s&|;`'"\n]+|\$HOME\/[^\s&|;`'"\n]+|\/[^\s&|;`'"\n]+)([^\n]{0,200})/g;
+  // Two-step (S5843, complexity 31): capture ANY cd target with one simple
+  // class, then filter to the absolute/home-rooted shapes the original
+  // single alternation required (~/, $HOME/, /).
+  const cdRegex = /\bcd\s+([^\s&|;`'"\n]+)([^\n]{0,200})/g;
+  const absoluteTargetRe = /^(?:~\/|\$HOME\/|\/)/;
   const writeCmdRegex = /\b(mkdir|touch|cp|mv|git\s+init|(?:pnpm|npm|yarn)\s+(?:init|create)|npx\s+create|cat\s*>|echo\s+[^|]*>|>>?\s*\S)/i;
   const leaks = new Set();
   let match;
   while ((match = cdRegex.exec(transcript)) !== null) {
+    if (!absoluteTargetRe.test(match[1])) continue;
     const original = match[1];
     let target = original;
     const rest = match[2] || "";

package/src/orchestrator/preflight-checks.js

@@ -11,6 +11,7 @@
 
 import { checkBinary } from "../utils/agent-detect.js";
 import { isSonarReachable, sonarUp } from "../sonar/manager.js";
+import { resolveSonarProjectKey, canResolveSonarProjectKey } from "../sonar/project-key.js";
 import { runCommand } from "../utils/process.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { msg, getLang } from "../utils/messages.js";
@@ -137,6 +138,28 @@ async function checkSonarAuth(config) {
   return { name: "sonar-auth", ok: false, detail: "Could not validate or generate Sonar token" };
 }
 
+/**
+ * KJC-BUG-0083 — run the real project-key resolver at preflight time so a
+ * repo Sonar cannot scan aborts BEFORE the first coder iteration instead
+ * of dying in sonar_repeat after burning tokens. Sonar stays mandatory
+ * for code tasks (v2.7.4 contract); this only moves the failure earlier.
+ */
+async function checkSonarProjectKey(config) {
+  // No remote at all (fresh local project): the SonarStage already skips
+  // cleanly via canResolveSonarProjectKey, so preflight must not block.
+  // The hard-fail case is the inconsistent one: a remote EXISTS but the
+  // resolver cannot parse it — that's what looped into sonar_repeat.
+  if (!(await canResolveSonarProjectKey(config))) {
+    return { name: "sonar-project-key", ok: true, detail: "No git remote — Sonar stage will skip cleanly" };
+  }
+  try {
+    const key = await resolveSonarProjectKey(config);
+    return { name: "sonar-project-key", ok: true, detail: `Project key resolved: ${key}` };
+  } catch (err) {
+    return { name: "sonar-project-key", ok: false, detail: err.message };
+  }
+}
+
 async function checkSecurityAgent(config) {
   const provider = config.roles?.security?.provider
     || config.roles?.coder?.provider
@@ -311,6 +334,34 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     }
   }
 
+  // --- 3b. Sonar project key derivable (KJC-BUG-0083) ---
+  // The scanner derives its project key from git remote.origin.url. With
+  // an unparseable remote (local-path bare, exotic URL) and no explicit
+  // sonarqube.project_key, every iteration's scan threw, the run burned
+  // coder tokens and died in sonar_repeat. Run the REAL resolver here —
+  // canResolveSonarProjectKey() is weaker (any non-empty remote passes) —
+  // so the run fails fast with the actionable message before iteration 1.
+  if (sonarEnabled && result.ok) {
+    const keyCheck = await checkSonarProjectKey(config);
+    result.checks.push(keyCheck);
+
+    emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
+      status: keyCheck.ok ? "ok" : "fail",
+      message: `Sonar project key: ${keyCheck.detail}`,
+      detail: keyCheck
+    }));
+
+    if (!keyCheck.ok) {
+      result.ok = false;
+      result.errors.push({
+        check: "sonar-project-key",
+        message: "Sonar cannot scan this repository: no project key can be derived.",
+        fix: withDocLink("Set sonarqube.project_key in kj.config.yml, or point remote.origin.url at a valid SSH/HTTPS remote.", "sonar_docker")
+      });
+      logger.error("Preflight: Sonar project key not derivable — failing fast before burning iterations");
+    }
+  }
+
   // --- 4. Security agent (graceful — only warning, not blocking) ---
   if (securityEnabled) {
     const secCheck = await checkSecurityAgent(config);

package/src/orchestrator/solomon-rules.js

@@ -70,7 +70,18 @@ export function evaluateRules(context, rulesConfig = {}) {
     const styleKeywords = /\b(naming|name|rename|style|format|formatting|indent|spacing|camelCase|snake_case|convention|cosmetic|readability|comment|jsdoc|documentation|whitespace|semicolon|quotes|trailing)\b/i;
     // Anti-style: if any of these match, the issue is NOT style — it's a real correctness/security concern.
     // Fixes KJC-BUG-0026 (Solomon approving legitimate security blockers misclassified as "style").
-    const securityKeywords = /\b(sql\s*injection|xss|csrf|ssrf|rce|injection|vulnerab|exploit|sanitiz|escape\b|encod\b|cors|auth|authn|authz|password|secret|credential|token|api[-_\s]*key|private[-_\s]*key|hash|cipher|crypto|encrypt|decrypt|tls|ssl|certificate|leak|sensitive|pii|privacy|insecure|unsafe|race[-_\s]*condition|deadlock|memory[-_\s]*leak|null[-_\s]*deref|uaf|overflow|traversal|prototype[-_\s]*pollution|deserializ|eval\b|exec\b|spawn|shell|command[-_\s]*injection)\b/i;
+    // Decomposed by concern (S5843, complexity 71 → 7 named groups).
+    // The union of tokens is byte-identical to the original alternation.
+    const SECURITY_KEYWORD_GROUPS = [
+      /\b(sql\s*injection|xss|csrf|ssrf|rce|injection|vulnerab|exploit)\b/i,
+      /\b(sanitiz|escape\b|encod\b|cors|traversal|prototype[-_\s]*pollution|deserializ)\b/i,
+      /\b(auth|authn|authz|password|secret|credential|token|api[-_\s]*key|private[-_\s]*key)\b/i,
+      /\b(hash|cipher|crypto|encrypt|decrypt|tls|ssl|certificate)\b/i,
+      /\b(leak|sensitive|pii|privacy|insecure|unsafe)\b/i,
+      /\b(race[-_\s]*condition|deadlock|memory[-_\s]*leak|null[-_\s]*deref|uaf|overflow)\b/i,
+      /\b(eval\b|exec\b|spawn|shell|command[-_\s]*injection)\b/i,
+    ];
+    const securityKeywords = { test: (text) => SECURITY_KEYWORD_GROUPS.some((re) => re.test(text)) };
     const securityCategories = new Set(["security", "correctness", "bug", "vulnerability"]);
     const styleSeverities = new Set(["low", "minor"]);
     const blockingSeverities = new Set(["critical", "high", "blocker", "major"]);

package/src/prompts/architect.js

@@ -1,5 +1,6 @@
 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.",
@@ -9,19 +10,28 @@ const SUBAGENT_PREAMBLE = [
 
 export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
 
-export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
+/**
+ * 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);
-  const sections = [SUBAGENT_PREAMBLE, ...(langInstruction ? [langInstruction] : [])];
-
-  if (instructions) {
-    sections.push(instructions);
+  let skillSection = null;
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    skillSection = buildSkillSection(skills, { provider, role: "architect" });
   }
 
-  sections.push(
-    "You are the architect in a multi-role AI pipeline.",
-    "Analyze the task and produce a concrete architecture design including layers, patterns, data model, API contracts, dependencies, and tradeoffs.",
-    "## Architecture Guidelines",
-    [
+  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",
@@ -30,34 +40,19 @@ export async function buildArchitectPrompt({ task, instructions, researchContext
       "- List external and internal dependencies",
       "- Document tradeoffs and their rationale",
       "- If critical decisions cannot be made without more information, list clarifying questions"
-    ].join("\n"),
-    "Return a single valid JSON object and nothing else.",
-    '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}'
-  );
-
-  if (productContext) {
-    sections.push(`## Product Context\n${productContext}`);
-  }
-
-  if (domainContext) {
-    sections.push(`## Domain Context\n${domainContext}`);
-  }
-
-  if (researchContext) {
-    sections.push(`## Research Context\n${researchContext}`);
-  }
-
-  sections.push(`## Task\n${task}`);
-
-  if (projectDir) {
-    const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills, { provider, role: "architect" });
-    if (skillSection) {
-      sections.push(skillSection);
-    }
-  }
+    ].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),
+  ]);
+}
 
-  return sections.join("\n\n");
+export async function buildArchitectPrompt(options) {
+  return joinLayout(await buildArchitectPromptLayout(options));
 }
 
 function filterStrings(arr) {

package/src/prompts/audit.js

@@ -49,13 +49,10 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     const stackLines = ["## Project Stack"];
     if (stack.language) stackLines.push(`- Language: ${stack.language}`);
     if (stack.frameworks?.length) stackLines.push(`- Frameworks: ${stack.frameworks.join(", ")}`);
-    const tier = stack.isFullstack
-      ? "fullstack (frontend + backend)"
-      : stack.isFrontend
-        ? "frontend-only"
-        : stack.isBackend
-          ? "backend-only"
-          : "unknown";
+    let tier = "unknown";
+    if (stack.isFullstack) tier = "fullstack (frontend + backend)";
+    else if (stack.isFrontend) tier = "frontend-only";
+    else if (stack.isBackend) tier = "backend-only";
     stackLines.push(`- Tier: ${tier}`);
     if (stack.isFullstack) {
       stackLines.push("Apply BOTH backend heuristics (queries, sync I/O, caching) AND frontend heuristics (bundle size, lazy loading, render-blocking) where each layer applies.");
@@ -241,7 +238,8 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
         lines.push(`### ${severity} (${issues.length})`);
         const slice = issues.slice(0, Math.max(0, remaining));
         for (const issue of slice) {
-          const loc = issue.component ? `${issue.component}${issue.line ? `:${issue.line}` : ""}` : "";
+          const lineSuffix = issue.line ? `:${issue.line}` : "";
+          const loc = issue.component ? `${issue.component}${lineSuffix}` : "";
           const rule = issue.rule ? ` [${issue.rule}]` : "";
           lines.push(`  - ${loc}${rule} ${issue.message || ""}`.trim());
         }
@@ -332,8 +330,10 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
       lines.push(`### ${severity} (${findings.length})`);
       const slice = findings.slice(0, Math.max(0, remaining));
       for (const f of slice) {
-        const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
-        const cwe = f.cwe ? ` (${Array.isArray(f.cwe) ? f.cwe.join(", ") : f.cwe})` : "";
+        const lineSuffix = f.line ? `:${f.line}` : "";
+        const loc = f.file ? `${f.file}${lineSuffix}` : "";
+        const cweText = Array.isArray(f.cwe) ? f.cwe.join(", ") : f.cwe;
+        const cwe = f.cwe ? ` (${cweText})` : "";
         lines.push(`  - ${loc} [${f.rule}]${cwe}: ${f.message || ""}`.trim());
       }
       if (findings.length > slice.length) {
@@ -355,7 +355,8 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     lines.push(`- Unused files: ${(deadExports.files || []).length}`);
     const allItems = [...(deadExports.exports || []), ...(deadExports.files || [])].slice(0, 40);
     for (const item of allItems) {
-      const loc = `${item.path}${item.line ? `:${item.line}` : ""}`;
+      const lineSuffix = item.line ? `:${item.line}` : "";
+      const loc = `${item.path}${lineSuffix}`;
       const name = item.name ? ` \`${item.name}\`` : "";
       lines.push(`  - [${item.severity}] ${loc} [${item.rule}]${name}`);
     }