jeo-code 0.1.0 → 0.4.5

package/src/ledger.ts

@@ -0,0 +1,270 @@
+/**
+ * jeo ledger — cross-plan append-only ledger (ledger / review / cleanup).
+ *
+ * Rebranded from gjc/gajae-code → jeo/jeo-code. State lives under .jeo/.
+ *  - Events appended to .jeo/ledger.jsonl (one JSON object per line).
+ *  - State is ALWAYS derived by folding the event log.
+ *  - Zero external dependencies (Node stdlib only).
+ *
+ * See ledger/schema.md for the event model.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const JEO_DIR = ".jeo";
+const LEDGER = path.join(JEO_DIR, "ledger.jsonl");
+
+type EventType =
+  | "plan_registered"
+  | "plan_reviewed"
+  | "goal_checkpointed"
+  | "cleanup_swept"
+  | "pr_linked";
+
+interface LedgerEvent {
+  ts: string;
+  type: EventType;
+  planId: string;
+  [k: string]: unknown;
+}
+
+type LedgerEventInput = {
+  type: EventType;
+  planId: string;
+  [k: string]: unknown;
+};
+
+const REVIEW_STATUSES = ["CLEAR", "WATCH", "BLOCK"] as const;
+const CHECKPOINT_STATUSES = ["complete", "failed"] as const;
+
+function die(msg: string): never {
+  console.error(`jeo ledger: ${msg}`);
+  process.exit(1);
+}
+
+function ensureInit(): void {
+  if (!fs.existsSync(LEDGER)) die(`no ledger at ${LEDGER} — run: jeo ledger init`);
+}
+
+function append(ev: LedgerEventInput): LedgerEvent {
+  ensureInit();
+  const full: LedgerEvent = { ts: new Date().toISOString(), ...ev };
+  fs.appendFileSync(LEDGER, JSON.stringify(full) + "\n");
+  return full;
+}
+
+function readEvents(): LedgerEvent[] {
+  if (!fs.existsSync(LEDGER)) return [];
+  return fs
+    .readFileSync(LEDGER, "utf8")
+    .split("\n")
+    .filter((l) => l.trim().length > 0)
+    .map((l, i) => {
+      try {
+        return JSON.parse(l) as LedgerEvent;
+      } catch {
+        die(`corrupt ledger line ${i + 1}`);
+      }
+    });
+}
+
+function parseArgs(argv: string[]): { positionals: string[]; flags: Record<string, string> } {
+  const positionals: string[] = [];
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) flags[key] = "true";
+      else {
+        flags[key] = next;
+        i++;
+      }
+    } else positionals.push(a);
+  }
+  return { positionals, flags };
+}
+
+function requirePlanId(positionals: string[]): string {
+  const id = positionals[0];
+  if (!id) die("missing <planId>");
+  return id;
+}
+
+interface PlanState {
+  planId: string;
+  title: string;
+  brief?: string;
+  registeredAt?: string;
+  review?: { status: string; evidence: string; at: string };
+  goals: Record<string, { status: string; evidence: string; at: string }>;
+  swept: { evidence: string; at: string }[];
+  prs: string[];
+}
+
+function deriveState(events: LedgerEvent[]): Record<string, PlanState> {
+  const plans: Record<string, PlanState> = {};
+  const ensure = (id: string): PlanState => {
+    if (!plans[id]) plans[id] = { planId: id, title: id, goals: {}, swept: [], prs: [] };
+    return plans[id];
+  };
+  for (const ev of events) {
+    const p = ensure(ev.planId);
+    switch (ev.type) {
+      case "plan_registered":
+        p.title = (ev.title as string) ?? ev.planId;
+        if (ev.brief) p.brief = ev.brief as string;
+        p.registeredAt = ev.ts;
+        break;
+      case "plan_reviewed":
+        p.review = { status: ev.status as string, evidence: (ev.evidence as string) ?? "", at: ev.ts };
+        break;
+      case "goal_checkpointed":
+        p.goals[ev.goal as string] = {
+          status: ev.status as string,
+          evidence: (ev.evidence as string) ?? "",
+          at: ev.ts,
+        };
+        break;
+      case "cleanup_swept":
+        p.swept.push({ evidence: (ev.evidence as string) ?? "", at: ev.ts });
+        break;
+      case "pr_linked":
+        if (ev.pr) p.prs.push(ev.pr as string);
+        break;
+    }
+  }
+  return plans;
+}
+
+/** A plan is "verified" when reviewed CLEAR, all goals complete, and swept at least once. */
+function planVerdict(p: PlanState): string {
+  const goalList = Object.values(p.goals);
+  const allComplete = goalList.length > 0 && goalList.every((g) => g.status === "complete");
+  if (p.review?.status === "CLEAR" && allComplete && p.swept.length > 0) return "verified";
+  if (p.review?.status === "BLOCK") return "blocked";
+  if (goalList.some((g) => g.status === "failed")) return "failed";
+  return "in_progress";
+}
+
+function cmdInit(): void {
+  fs.mkdirSync(JEO_DIR, { recursive: true });
+  if (!fs.existsSync(LEDGER)) {
+    fs.writeFileSync(LEDGER, "");
+    console.log(`jeo ledger: initialized ${LEDGER}`);
+  } else {
+    console.log(`jeo ledger: already exists at ${LEDGER}`);
+  }
+}
+
+function cmdStatus(flags: Record<string, string>): void {
+  const plans = deriveState(readEvents());
+  const list = Object.values(plans).map((p) => ({
+    planId: p.planId,
+    title: p.title,
+    verdict: planVerdict(p),
+    review: p.review?.status ?? "none",
+    goals: Object.fromEntries(Object.entries(p.goals).map(([g, v]) => [g, v.status])),
+    sweeps: p.swept.length,
+    prs: p.prs,
+  }));
+  if (flags.json === "true") {
+    console.log(JSON.stringify({ plans: list }, null, 2));
+    return;
+  }
+  if (list.length === 0) {
+    console.log("jeo ledger: no plans registered yet");
+    return;
+  }
+  console.log("jeo ledger status\n");
+  for (const p of list) {
+    const goalStr =
+      Object.keys(p.goals).length === 0
+        ? "—"
+        : Object.entries(p.goals).map(([g, s]) => `${g}:${s}`).join(" ");
+    console.log(`● ${p.planId}  [${p.verdict}]  ${p.title}`);
+    console.log(`    review=${p.review}  goals=${goalStr}  sweeps=${p.sweeps}  prs=${p.prs.length}`);
+  }
+}
+
+export function runLedger(argv: string[]): void {
+  const [cmd, ...rest] = argv;
+  const { positionals, flags } = parseArgs(rest);
+  switch (cmd) {
+    case "init":
+      cmdInit();
+      break;
+    case "register": {
+      const planId = requirePlanId(positionals);
+      const ev = append({
+        type: "plan_registered",
+        planId,
+        title: flags.title ?? planId,
+        ...(flags.brief ? { brief: flags.brief } : {}),
+      });
+      console.log(`jeo ledger: registered ${planId} @ ${ev.ts}`);
+      break;
+    }
+    case "review": {
+      const planId = requirePlanId(positionals);
+      const status = (flags.status ?? "").toUpperCase();
+      if (!REVIEW_STATUSES.includes(status as (typeof REVIEW_STATUSES)[number]))
+        die(`--status must be one of ${REVIEW_STATUSES.join("|")}`);
+      if (!flags.evidence) die("review requires --evidence");
+      append({ type: "plan_reviewed", planId, status, evidence: flags.evidence });
+      console.log(`jeo ledger: reviewed ${planId} = ${status}`);
+      break;
+    }
+    case "checkpoint": {
+      const planId = requirePlanId(positionals);
+      const status = (flags.status ?? "").toLowerCase();
+      if (!CHECKPOINT_STATUSES.includes(status as (typeof CHECKPOINT_STATUSES)[number]))
+        die(`--status must be one of ${CHECKPOINT_STATUSES.join("|")}`);
+      if (!flags.goal) die("checkpoint requires --goal");
+      if (!flags.evidence) die("checkpoint requires --evidence");
+      append({ type: "goal_checkpointed", planId, goal: flags.goal, status, evidence: flags.evidence });
+      console.log(`jeo ledger: checkpoint ${planId}/${flags.goal} = ${status}`);
+      break;
+    }
+    case "sweep": {
+      const planId = requirePlanId(positionals);
+      if (!flags.evidence) die("sweep requires --evidence");
+      append({ type: "cleanup_swept", planId, evidence: flags.evidence });
+      console.log(`jeo ledger: swept ${planId}`);
+      break;
+    }
+    case "link": {
+      const planId = requirePlanId(positionals);
+      if (!flags.pr) die("link requires --pr");
+      append({ type: "pr_linked", planId, pr: flags.pr });
+      console.log(`jeo ledger: linked ${flags.pr} to ${planId}`);
+      break;
+    }
+    case "status":
+      cmdStatus(flags);
+      break;
+    case undefined:
+    case "help":
+    case "--help":
+      console.log(
+        [
+          "jeo ledger — cross-plan append-only ledger (ledger/review/cleanup)",
+          "",
+          "  init",
+          "  register <planId> --title <t> [--brief <b>]",
+          "  review <planId> --status CLEAR|WATCH|BLOCK --evidence <e>",
+          "  checkpoint <planId> --goal <id> --status complete|failed --evidence <e>",
+          "  sweep <planId> --evidence <e>",
+          "  link <planId> --pr <url>",
+          "  status [--json]",
+        ].join("\n"),
+      );
+      break;
+    default:
+      die(`unknown subcommand: ${cmd} (try: jeo ledger help)`);
+  }
+}
+
+if (import.meta.main) runLedger(process.argv.slice(2));

package/src/mcp/AGENTS.md

@@ -0,0 +1,38 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# mcp
+
+## Purpose
+Model Context Protocol (MCP) integration, allowing `jeo-code` to expose tools or consume context from external MCP servers.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `server.ts` | MCP server implementation (if exposing tools) |
+| `client.ts` | MCP client implementation (for consuming external tools) |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Adhere strictly to the MCP specification.
+- Handle JSON-RPC serialization and deserialization safely.
+
+### Testing Requirements
+- Unit test protocol messaging.
+
+### Common Patterns
+- Transport layer abstraction (stdio vs SSE).
+
+## Dependencies
+
+### Internal
+- Connects external capabilities into `src/agent/tools.ts`.
+
+### External
+- Protocol dependencies if not implemented natively.
+
+<!-- MANUAL: -->

package/src/mcp/server.ts

@@ -12,7 +12,7 @@ import {
 } from "./protocol";
 import { TOOLS } from "./tools";
 
-const SERVER_INFO = { name: "joc-mcp", version: "0.1.0" };
+const SERVER_INFO = { name: "jeo-mcp", version: "0.1.0" };
 const PROTOCOL_VERSION = "2024-11-05";
 
 interface ServerOptions {
@@ -20,34 +20,130 @@ interface ServerOptions {
   log?: (line: string) => void;
 }
 
+interface IncomingMessage {
+  payload: string;
+  framed: boolean;
+}
+
 export async function runMcpServer(options: ServerOptions = {}): Promise<void> {
   const tools = options.tools ?? TOOLS;
   const log = options.log ?? (line => process.stderr.write(`${line}\n`));
-  log(`joc-mcp v${SERVER_INFO.version} listening on stdio (${tools.length} tools)`);
+  log(`jeo-mcp v${SERVER_INFO.version} listening on stdio (${tools.length} tools)`);
 
   let buffer = "";
   const decoder = new TextDecoder();
 
   for await (const chunk of (process.stdin as unknown as AsyncIterable<Uint8Array>)) {
     buffer += decoder.decode(chunk, { stream: true });
-    let newlineIndex: number;
-    while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
-      const line = buffer.slice(0, newlineIndex).trim();
-      buffer = buffer.slice(newlineIndex + 1);
-      if (!line) continue;
-      const response = await handleLine(line, tools);
-      if (response) writeResponse(response);
+    const drained = drainIncomingMessages(buffer);
+    buffer = drained.remaining;
+    for (const message of drained.messages) {
+      let response: JsonRpcResponse | null = null;
+      try {
+        response = await handleLine(message.payload, tools);
+      } catch (err) {
+        // A bad request must never kill the stdin read loop (the whole server).
+        response = fail(null, INTERNAL_ERROR, (err as Error)?.message ?? "internal error");
+      }
+      if (response) writeResponse(response, message.framed);
+    }
+  }
+}
+
+export function drainIncomingMessages(buffer: string): { messages: IncomingMessage[]; remaining: string } {
+  const messages: IncomingMessage[] = [];
+  let remaining = buffer;
+
+  while (remaining.length > 0) {
+    const frame = readContentLengthFrame(remaining);
+    if (frame === "incomplete") break;
+    if (frame) {
+      messages.push({ payload: frame.payload, framed: true });
+      remaining = frame.remaining;
+      continue;
     }
+
+    const newlineIndex = remaining.indexOf("\n");
+    if (newlineIndex === -1) break;
+    const line = remaining.slice(0, newlineIndex).trim();
+    remaining = remaining.slice(newlineIndex + 1);
+    if (line) messages.push({ payload: line, framed: false });
+  }
+
+  return { messages, remaining };
+}
+
+function readContentLengthFrame(buffer: string): { payload: string; remaining: string } | "incomplete" | null {
+  const headerEnd = findHeaderEnd(buffer);
+  if (headerEnd === null) return looksLikeHeaderPrefix(buffer) ? "incomplete" : null;
+
+  const header = buffer.slice(0, headerEnd.index);
+  const contentLength = parseContentLength(header);
+  if (contentLength === null) return null;
+
+  const bodyStart = headerEnd.index + headerEnd.separator.length;
+  const body = buffer.slice(bodyStart);
+  const bodyByteLength = Buffer.byteLength(body, "utf8");
+  if (bodyByteLength < contentLength) return "incomplete";
+
+  const split = splitAtUtf8ByteLength(body, contentLength);
+  if (!split) return null;
+
+  return {
+    payload: split.prefix,
+    remaining: split.suffix,
+  };
+}
+
+function splitAtUtf8ByteLength(input: string, byteLength: number): { prefix: string; suffix: string } | null {
+  if (byteLength === 0) return { prefix: "", suffix: input };
+
+  let bytes = 0;
+  let endIndex = 0;
+  for (const char of input) {
+    bytes += Buffer.byteLength(char, "utf8");
+    endIndex += char.length;
+    if (bytes === byteLength) return { prefix: input.slice(0, endIndex), suffix: input.slice(endIndex) };
+    if (bytes > byteLength) return null;
+  }
+  return null;
+}
+
+function findHeaderEnd(buffer: string): { index: number; separator: "\r\n\r\n" | "\n\n" } | null {
+  const crlf = buffer.indexOf("\r\n\r\n");
+  const lf = buffer.indexOf("\n\n");
+  if (crlf === -1 && lf === -1) return null;
+  if (crlf !== -1 && (lf === -1 || crlf < lf)) return { index: crlf, separator: "\r\n\r\n" };
+  return { index: lf, separator: "\n\n" };
+}
+
+function looksLikeHeaderPrefix(buffer: string): boolean {
+  return /^content-length\s*:/i.test(buffer) || /^[A-Za-z-]+\s*:/i.test(buffer);
+}
+
+function parseContentLength(header: string): number | null {
+  for (const line of header.split(/\r?\n/)) {
+    const match = /^content-length\s*:\s*(\d+)\s*$/i.exec(line);
+    if (!match) continue;
+    const length = Number(match[1]);
+    return Number.isSafeInteger(length) && length >= 0 ? length : null;
   }
+  return null;
 }
 
-async function handleLine(line: string, tools: ToolDefinition[]): Promise<JsonRpcResponse | null> {
-  let req: JsonRpcRequest;
+export async function handleLine(line: string, tools: ToolDefinition[]): Promise<JsonRpcResponse | null> {
+  let parsed: unknown;
   try {
-    req = JSON.parse(line) as JsonRpcRequest;
+    parsed = JSON.parse(line);
   } catch {
     return fail(null, PARSE_ERROR, "invalid JSON");
   }
+  // `null`, arrays, and primitives are valid JSON but not JSON-RPC requests — accessing
+  // `req.jsonrpc` on them would throw and (without the loop guard) kill the server.
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return fail(null, INVALID_REQUEST, "malformed JSON-RPC request");
+  }
+  const req = parsed as JsonRpcRequest;
   if (req.jsonrpc !== "2.0" || typeof req.method !== "string") {
     return fail(req.id ?? null, INVALID_REQUEST, "malformed JSON-RPC request");
   }
@@ -92,6 +188,11 @@ async function handleToolCall(req: JsonRpcRequest, tools: ToolDefinition[]): Pro
   return ok(req.id ?? null, result);
 }
 
-function writeResponse(response: JsonRpcResponse): void {
-  process.stdout.write(`${JSON.stringify(response)}\n`);
+function writeResponse(response: JsonRpcResponse, framed: boolean): void {
+  const json = JSON.stringify(response);
+  if (framed) {
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(json, "utf8")}\r\n\r\n${json}`);
+    return;
+  }
+  process.stdout.write(`${json}\n`);
 }

package/src/mcp/tools.ts

@@ -2,17 +2,36 @@ import { resolveProvider } from "../ai";
 import { resolveCredential, type AuthProvider } from "../auth";
 import { readGlobalConfig } from "../agent/state";
 import type { ToolDefinition, ToolResult } from "./protocol";
+import { effectiveCredentialForProvider } from "../ai/model-manager";
+import { jeoEnv } from "../util/env";
 
-const AUTH_PROVIDERS: AuthProvider[] = ["anthropic", "openai", "gemini"];
+const AUTH_PROVIDERS: AuthProvider[] = ["anthropic", "openai", "gemini", "antigravity"]
 
 function textResult(text: string, isError = false): ToolResult {
   return { content: [{ type: "text", text }], isError };
 }
 
+/**
+ * The credential kind jeo would ACTUALLY use for a provider (the effective credential):
+ * an API key wins over OAuth, and an OAuth-only login the bundled adapter can't serve
+ * (e.g. Gemini Cloud Code Assist) reports "none". This matches the real call path, unlike
+ * the bare resolveCredential() kind.
+ */
+async function effectiveKind(provider: AuthProvider): Promise<string> {
+  const cred = await resolveCredential(provider);
+  if (cred.kind === "none") return "none";
+  try {
+    const cfg = await readGlobalConfig();
+    return effectiveCredentialForProvider(provider, cred, cfg, provider).kind;
+  } catch {
+    return "none"; // OAuth-only but unusable by the bundled adapter
+  }
+}
+
 export const TOOLS: ToolDefinition[] = [
   {
-    name: "joc_resolve_provider",
-    description: "Given a model name (e.g. 'claude-3-5-sonnet', 'openai/mock-1', 'gemini-2.0-flash', 'ollama/llama3'), return which provider joc would route the call to.",
+    name: "jeo_resolve_provider",
+    description: "Given a model name (e.g. 'claude-3-5-sonnet', 'openai/mock-1', 'gemini-2.0-flash', 'ollama/llama3'), return which provider jeo would route the call to.",
     inputSchema: {
       type: "object",
       properties: {
@@ -27,7 +46,7 @@ export const TOOLS: ToolDefinition[] = [
     },
   },
   {
-    name: "joc_credential_status",
+    name: "jeo_credential_status",
     description: "Report which auth method is configured for a provider (oauth|api_key|none). Does not reveal the secret.",
     inputSchema: {
       type: "object",
@@ -41,13 +60,14 @@ export const TOOLS: ToolDefinition[] = [
       if (!AUTH_PROVIDERS.includes(provider as AuthProvider)) {
         return textResult(`error: provider must be one of ${AUTH_PROVIDERS.join(", ")}`, true);
       }
-      const credential = await resolveCredential(provider as AuthProvider);
-      return textResult(JSON.stringify({ provider, kind: credential.kind }));
+      const configured = (await resolveCredential(provider as AuthProvider)).kind;
+      const usable = await effectiveKind(provider as AuthProvider);
+      return textResult(JSON.stringify({ provider, kind: usable, configured }));
     },
   },
   {
-    name: "joc_config_snapshot",
-    description: "Return a redacted snapshot of joc's current config: default model, openai/ollama base URLs, and which providers have credentials.",
+    name: "jeo_config_snapshot",
+    description: "Return a redacted snapshot of jeo's current config: default model, openai/ollama base URLs, and which providers have credentials.",
     inputSchema: { type: "object", properties: {} },
     async handler() {
       const cfg = await readGlobalConfig();
@@ -57,17 +77,17 @@ export const TOOLS: ToolDefinition[] = [
         openaiBaseUrl: cfg.openaiBaseUrl ?? null,
         ollamaBaseUrl: cfg.ollamaBaseUrl ?? "http://localhost:11434",
         credentials: {
-          anthropic: (await resolveCredential("anthropic")).kind,
-          openai: (await resolveCredential("openai")).kind,
-          gemini: (await resolveCredential("gemini")).kind,
+          anthropic: await effectiveKind("anthropic"),
+          openai: await effectiveKind("openai"),
+          gemini: await effectiveKind("gemini"),
         },
       };
       return textResult(JSON.stringify(snapshot, null, 2));
     },
   },
   {
-    name: "joc_doctor",
-    description: "Run joc's health probe and return a structured report of provider connectivity. Same probe used by 'joc doctor' CLI.",
+    name: "jeo_doctor",
+    description: "Run jeo's health probe and return a structured report of provider connectivity. Same probe used by 'jeo doctor' CLI.",
     inputSchema: { type: "object", properties: {} },
     async handler() {
       const { runDoctorCommand } = await import("../commands/doctor");
@@ -102,8 +122,8 @@ async function captureCommand(run: () => Promise<void>): Promise<string> {
 
 const PIPELINE_TOOLS: ToolDefinition[] = [
   {
-    name: "joc_deep_interview",
-    description: "DANGER: WRITES FILES + BURNS LLM CREDITS. Runs Socratic requirements interview. Writes .joc/spec.json. Requires default model credential.",
+    name: "jeo_deep_interview",
+    description: "DANGER: WRITES FILES + BURNS LLM CREDITS. Runs Socratic requirements interview. Writes .jeo/spec.json. Requires default model credential.",
     inputSchema: {
       type: "object",
       properties: {
@@ -120,8 +140,8 @@ const PIPELINE_TOOLS: ToolDefinition[] = [
     },
   },
   {
-    name: "joc_ralplan",
-    description: "DANGER: WRITES FILES + BURNS LLM CREDITS. Reads .joc/spec.json, writes .joc/plan.yaml via Planner/Architect/Critic.",
+    name: "jeo_ralplan",
+    description: "DANGER: WRITES FILES + BURNS LLM CREDITS. Reads .jeo/spec.json, writes .jeo/plan.yaml via Planner/Architect/Critic.",
     inputSchema: { type: "object", properties: {} },
     async handler() {
       const { runRalplanCommand } = await import("../commands/ralplan");
@@ -130,8 +150,8 @@ const PIPELINE_TOOLS: ToolDefinition[] = [
     },
   },
   {
-    name: "joc_team",
-    description: "DANGER: WRITES FILES + EDITS CODE + BURNS LLM CREDITS. Executes .joc/plan.yaml via Executor subagent. Modifies the working tree.",
+    name: "jeo_team",
+    description: "DANGER: WRITES FILES + EDITS CODE + BURNS LLM CREDITS. Executes .jeo/plan.yaml via Executor subagent. Modifies the working tree.",
     inputSchema: { type: "object", properties: {} },
     async handler() {
       const { runTeamCommand } = await import("../commands/team");
@@ -140,8 +160,8 @@ const PIPELINE_TOOLS: ToolDefinition[] = [
     },
   },
   {
-    name: "joc_ultragoal",
-    description: "DANGER: BURNS LLM CREDITS. Runs acceptance verification against .joc/spec.json + .joc/plan.yaml.",
+    name: "jeo_ultragoal",
+    description: "DANGER: BURNS LLM CREDITS. Runs acceptance verification against .jeo/spec.json + .jeo/plan.yaml.",
     inputSchema: { type: "object", properties: {} },
     async handler() {
       const { runUltragoalCommand } = await import("../commands/ultragoal");
@@ -151,6 +171,6 @@ const PIPELINE_TOOLS: ToolDefinition[] = [
   },
 ];
 
-if (process.env.JOC_MCP_PIPELINE === "1") {
+if (jeoEnv("MCP_PIPELINE") === "1") {
   TOOLS.push(...PIPELINE_TOOLS);
 }

package/src/md-modules.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/prompts/AGENTS.md

@@ -0,0 +1,41 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# prompts
+
+## Purpose
+Bundled system prompts, role definitions, and workflow skill documentation for the agent.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `system.md` | Core system prompt template |
+
+## Subdirectories
+| Directory | Purpose |
+|-----------|---------|
+| `agents/` | Role-specific prompts (executor, planner, architect, critic) (see `agents/AGENTS.md`) |
+| `skills/` | Bundled workflow skills (deep-interview, ralplan, etc.) (see `skills/AGENTS.md`) |
+
+## For AI Agents
+
+### Working In This Directory
+- Prompts should be clear, concise, and definitive.
+- Updates here directly alter the AI's behavior and personality.
+- Do not remove existing constraints without explicit reason.
+
+### Testing Requirements
+- Prompt changes should be verified via end-to-end testing or `bun run run-evolution.sh`.
+
+### Common Patterns
+- XML-like tags for structural organization within prompts.
+
+## Dependencies
+
+### Internal
+- Injected by `src/agent/session.ts` and `src/skills/`.
+
+### External
+*(None)*
+
+<!-- MANUAL: -->