frappe-builder 1.1.0-dev.10

package/extensions/frappe-workflow.ts

@@ -0,0 +1,85 @@
+import { getCurrentPhase, db } from "../state/db.js";
+import { isToolAllowedInPhase, getValidPhase, type Phase } from "../state/fsm.js";
+import { appendEntry } from "../state/journal.js";
+
+interface BlockedResponse {
+  blocked: true;
+  tool: string;
+  current_phase: Phase;
+  valid_phase: Phase | "any";
+  message: string;
+}
+
+function buildBlockedResponse(
+  tool: string,
+  currentPhase: Phase,
+  validPhase: Phase | "any"
+): BlockedResponse {
+  return {
+    blocked: true,
+    tool,
+    current_phase: currentPhase,
+    valid_phase: validPhase,
+    message: `${tool} is not available in ${currentPhase} phase. Available in: ${validPhase}`,
+  };
+}
+
+/**
+ * Phase guard logic for beforeToolCall. Returns a blocked response if the tool
+ * is not valid in the current phase, undefined to allow.
+ *
+ * Override: if args.override === true, writes a JSONL entry and allows the tool
+ * regardless of phase. Does NOT disable quality gates (frappe-gates.ts).
+ *
+ * Never throws — always returns a value or undefined.
+ */
+// Tools valid in all phases — never blocked by the phase guard (FR34)
+const ALWAYS_ALLOWED_TOOLS = ["invoke_debugger", "end_debug", "spawn_agent", "get_frappe_docs", "get_audit_log"];
+
+export function beforeToolCall(
+  toolName: string,
+  args: Record<string, unknown>
+): BlockedResponse | undefined {
+  // Always-allowed bypass — checked before everything else
+  if (ALWAYS_ALLOWED_TOOLS.includes(toolName)) return undefined;
+
+  const currentPhase = getCurrentPhase() as Phase;
+
+  // Override bypass — checked BEFORE phase guard (FR10 escape hatch)
+  if (args.override === true) {
+    const session = db
+      .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
+      .get() as { session_id: string } | undefined;
+
+    appendEntry({
+      ts: new Date().toISOString(),
+      sessionId: session?.session_id ?? "unknown",
+      type: "tool_call",
+      payload: {
+        override: true,
+        reason: (args.reason as string) ?? "unspecified",
+        tool: toolName,
+        phase: currentPhase,
+      },
+    });
+    return undefined; // allow
+  }
+
+  // Phase guard
+  if (!isToolAllowedInPhase(toolName, currentPhase)) {
+    return buildBlockedResponse(toolName, currentPhase, getValidPhase(toolName));
+  }
+
+  return undefined; // allow
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.on("tool_call", (event: { toolName?: string; input?: Record<string, unknown> }) => {
+    const result = beforeToolCall(event.toolName ?? "", event.input ?? {});
+    if (result) {
+      return { block: true, reason: result.message };
+    }
+    return undefined;
+  });
+}

package/gates/coverage-check.ts

@@ -0,0 +1,37 @@
+/**
+ * gates/coverage-check.ts — Async coverage gate (NOT a pure function).
+ * Runs `bench run-tests --coverage` via execa and parses the result.
+ *
+ * NOT wired via frappe-gates.ts — integrated directly in completeComponent().
+ * Triggers when the final component is completed in `testing` phase. (FR29)
+ */
+import { execa } from "execa";
+import type { GateContext } from "./types.js";
+
+export type CoverageResult =
+  | { passed: true; coverage: number }
+  | { passed: false; coverage: number; required: string; error?: string };
+
+function parseCoverage(stdout: string): number {
+  const match = stdout.match(/^TOTAL\s+\d+\s+\d+\s+(\d+)%/m);
+  return match ? parseInt(match[1], 10) : 0;
+}
+
+export async function coverageCheck(_context: GateContext): Promise<CoverageResult> {
+  try {
+    const { stdout } = await execa("bench", ["run-tests", "--coverage"], {
+      cwd: process.env.FRAPPE_BENCH_PATH ?? process.cwd(),
+      reject: false,      // don't throw on non-zero exit — coverage data may still be in stdout
+      timeout: 120_000,   // 2 minute timeout
+    });
+
+    const coverage = parseCoverage(stdout ?? "");
+
+    if (coverage < 70) {
+      return { passed: false, coverage, required: "70%" };
+    }
+    return { passed: true, coverage };
+  } catch (err) {
+    return { passed: false, coverage: 0, required: "70%", error: (err as Error).message };
+  }
+}

package/gates/frappe-native-check.ts

@@ -0,0 +1,65 @@
+/**
+ * gates/frappe-native-check.ts — pure gate function, no side effects.
+ * No imports from state/, extensions/, or config/.
+ * No async, no db, no I/O. Same input always produces same output.
+ */
+
+export type NativeCheckResult =
+  | { passed: true }
+  | { passed: true; result: "override"; justification: string; detectedPatterns: string[] }
+  | { passed: false; requiresJustification: true; message: string; detectedPatterns: string[] };
+
+export const NON_NATIVE_PATTERNS: { pattern: RegExp; label: string }[] = [
+  // HTTP clients — use frappe.call() or frappe.db instead
+  { pattern: /import\s+axios/, label: "axios (use frappe.call)" },
+  { pattern: /require\(['"]axios['"]\)/, label: "axios (use frappe.call)" },
+  { pattern: /import\s+requests/, label: "requests (use frappe.call)" },
+  { pattern: /from\s+requests\s+import/, label: "requests (use frappe.call)" },
+
+  // Raw database access — use Frappe ORM
+  { pattern: /cursor\.execute\s*\(/, label: "raw SQL cursor (use frappe.db.sql or ORM)" },
+  { pattern: /pymysql|psycopg2|sqlite3\.connect/, label: "direct DB driver (use Frappe ORM)" },
+  { pattern: /mongoose|sequelize|typeorm/i, label: "external ORM (use Frappe DocType)" },
+
+  // Custom auth — use frappe.whitelist()
+  { pattern: /jwt\.sign|jsonwebtoken/, label: "JWT auth (use frappe.whitelist + session)" },
+  { pattern: /passport\.authenticate/, label: "passport auth (use Frappe auth)" },
+
+  // External data processing — use Frappe reports/scripts
+  { pattern: /import\s+pandas/, label: "pandas (use Frappe Script Report)" },
+  { pattern: /import\s+numpy/, label: "numpy (use Frappe computation)" },
+
+  // File system — use Frappe file manager
+  { pattern: /fs\.writeFileSync|fs\.readFileSync/, label: "raw fs (use frappe.get_file_url or File DocType)" },
+
+  // HTTP server — use Frappe whitelisted methods
+  { pattern: /express\(\)|fastapi|flask\.Flask/, label: "external web framework (use Frappe whitelist)" },
+];
+
+/**
+ * Scans `content` for non-Frappe-native patterns.
+ *
+ * - No detected patterns → { passed: true }
+ * - Detected + no justification → { passed: false, requiresJustification: true, ... }
+ * - Detected + justification provided → { passed: true, result: "override", ... }
+ */
+export function checkFrappeNative(content: string, justification?: string): NativeCheckResult {
+  const detectedPatterns = NON_NATIVE_PATTERNS
+    .filter(({ pattern }) => pattern.test(content))
+    .map(({ label }) => label);
+
+  if (detectedPatterns.length === 0) {
+    return { passed: true };
+  }
+
+  if (justification) {
+    return { passed: true, result: "override", justification, detectedPatterns };
+  }
+
+  return {
+    passed: false,
+    requiresJustification: true,
+    message: "This uses a non-Frappe-native approach. Justification required to proceed.",
+    detectedPatterns,
+  };
+}

package/gates/permission-check.ts

@@ -0,0 +1,65 @@
+/**
+ * gates/permission-check.ts — Pure gate function, no side effects.
+ * No imports from state/, extensions/, or config/.
+ * No async, no db, no I/O. Same input always produces same output.
+ *
+ * Scans Python code for @frappe.whitelist() decorated methods that lack
+ * a permission check inside their function body. (FR26)
+ */
+import type { GateContext, GateResult } from "./types.js";
+
+const PERMISSION_PATTERNS = [
+  /frappe\.has_permission\s*\(/,
+  /frappe\.only_for\s*\(/,
+  /frappe\.check_permission\s*\(/,
+  /frappe\.has_role\s*\(/,
+  /frappe\.session\.user/,
+];
+
+function getLineNumber(code: string, offset: number): number {
+  return code.slice(0, offset).split("\n").length;
+}
+
+function extractFunctionBody(code: string, defStart: number): string {
+  const bodyStart = code.indexOf("\n", defStart) + 1;
+  // Find next top-level def/class/decorator (at column 0)
+  const nextTopLevel = /\n(?=def |class |@)/g;
+  nextTopLevel.lastIndex = bodyStart;
+  const match = nextTopLevel.exec(code);
+  return match ? code.slice(bodyStart, match.index) : code.slice(bodyStart);
+}
+
+function hasPermissionCheck(body: string): boolean {
+  return PERMISSION_PATTERNS.some((p) => p.test(body));
+}
+
+export function permissionCheck(code: string, context: GateContext): GateResult {
+  // Only scan Python files
+  if (!context.file.endsWith(".py")) return { passed: true };
+
+  // Find all @frappe.whitelist(...) followed by a def
+  const WHITELIST_DECORATOR = /@frappe\.whitelist\([^)]*\)\s*\ndef\s+(\w+)/g;
+
+  const violations: Array<{ method: string; line: number; reason: string }> = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = WHITELIST_DECORATOR.exec(code)) !== null) {
+    const decoratorOffset = match.index;
+    const methodName = match[1];
+    const line = getLineNumber(code, decoratorOffset);
+
+    // defStart: position of "def " within the full match
+    const defStart = code.indexOf("\ndef ", decoratorOffset) + 1;
+    const body = extractFunctionBody(code, defStart);
+
+    if (!hasPermissionCheck(body)) {
+      violations.push({ method: methodName, line, reason: "missing permission check" });
+    }
+  }
+
+  if (violations.length > 0) {
+    return { passed: false, violations };
+  }
+
+  return { passed: true };
+}

package/gates/query-check.ts

@@ -0,0 +1,40 @@
+/**
+ * gates/query-check.ts — Pure gate function, no side effects.
+ * No imports from state/, extensions/, or config/.
+ * No async, no db, no I/O. Same input always produces same output.
+ *
+ * Detects SQL string concatenation patterns (f-strings, +, %) that
+ * could lead to SQL injection. Requires parameterised queries. (FR27)
+ */
+import type { GateContext, GateResult } from "./types.js";
+
+const SQL_KEYWORD = /\b(SELECT|INSERT|UPDATE|DELETE|FROM|WHERE)\b/i;
+
+const INJECTION_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /f["'].*\{[^}]+\}.*["']/, label: "f-string interpolation" },
+  { pattern: /["']\s*\+\s*\w/, label: "string concatenation (+)" },
+  { pattern: /["']\s*%\s*\w/, label: "%-format interpolation" },
+];
+
+const REASON = "SQL string concatenation detected — use parameterised queries";
+
+export function queryCheck(code: string, context: GateContext): GateResult {
+  if (!context.file.endsWith(".py")) return { passed: true };
+
+  const lines = code.split("\n");
+  const violations: Array<{ line: number; pattern: string; reason: string }> = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!SQL_KEYWORD.test(line)) continue;
+
+    for (const { pattern, label } of INJECTION_PATTERNS) {
+      if (pattern.test(line)) {
+        violations.push({ line: i + 1, pattern: label, reason: REASON });
+        break; // one violation per line — avoid duplicating the same line
+      }
+    }
+  }
+
+  return violations.length > 0 ? { passed: false, violations } : { passed: true };
+}

package/gates/server-side-check.ts

@@ -0,0 +1,67 @@
+/**
+ * gates/server-side-check.ts — Pure gate function, no side effects.
+ * No imports from state/, extensions/, or config/.
+ * No async, no db, no I/O. Same input always produces same output.
+ *
+ * Detects business logic patterns in client-side JavaScript/TypeScript that
+ * should live on the Python server instead. (FR28)
+ */
+import type { GateContext, GateResult } from "./types.js";
+
+const BUSINESS_LOGIC_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  // Arithmetic on financial/quantity fields — price/total calculations
+  {
+    pattern: /frm\.doc\.\w+\s*=\s*frm\.doc\.\w+\s*[*\/+\-]\s*frm\.doc\.\w+/,
+    label: "client-side financial calculation",
+  },
+  // Direct permission decisions based on user identity
+  {
+    pattern: /frappe\.session\.user\s*[=!]={1,2}\s*["']/,
+    label: "client-side permission decision (user identity)",
+  },
+  // Role-based access control in JS
+  {
+    pattern: /frappe\.user\.has_role\s*\(/,
+    label: "client-side permission decision (role check)",
+  },
+  // Direct user_roles access
+  {
+    pattern: /frappe\.user_roles\b/,
+    label: "client-side permission decision (user_roles)",
+  },
+  // Direct DB access from client side — should go via frappe.call
+  {
+    pattern: /frappe\.db\.(get_value|get_list|set_value|insert|delete_doc)\s*\(/,
+    label: "direct DB access from client-side (use frappe.call instead)",
+  },
+];
+
+const REASON = "business logic must be server-side";
+
+function isTestFile(file: string): boolean {
+  return file.includes("/test/") || file.includes(".test.") || file.includes(".spec.");
+}
+
+export function serverSideCheck(code: string, context: GateContext): GateResult {
+  // Only scan JS/TS files
+  if (!context.file.endsWith(".js") && !context.file.endsWith(".ts")) {
+    return { passed: true };
+  }
+  // Exempt test files
+  if (isTestFile(context.file)) return { passed: true };
+
+  const lines = code.split("\n");
+  const violations: Array<{ line: number; pattern: string; reason: string }> = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const { pattern, label } of BUSINESS_LOGIC_PATTERNS) {
+      if (pattern.test(line)) {
+        violations.push({ line: i + 1, pattern: label, reason: REASON });
+        break; // one violation per line
+      }
+    }
+  }
+
+  return violations.length > 0 ? { passed: false, violations } : { passed: true };
+}

package/gates/style-check.ts

@@ -0,0 +1,92 @@
+import path from 'node:path'
+import type { GateContext, GateResult } from './types.js'
+
+type Violation = { line?: number; reason: string; [key: string]: unknown }
+
+const DEF_LINE = /^([^\S\n]*)def\s+(\w+)\s*\([^)]*\)\s*:/gm
+const NON_DESCRIPTIVE = /^(\s*)(x|y|z|data|temp|tmp|val|var|foo|bar|test|obj|res|ret)\s*=/gm
+const SQL_STRING = /frappe\.db\.sql\s*\(\s*["'`]{1,3}([\s\S]*?)["'`]{1,3}/g
+const CAMEL_IDENTIFIER = /\b([a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*)\b/g
+
+const STUB_BODY = /^\s*(pass|return|return None|super\(\)\.__init__\(.*?\))\s*$/
+
+function lineNumber(code: string, index: number): number {
+  return code.slice(0, index).split('\n').length
+}
+
+function hasDocstring(code: string, defStart: number): boolean {
+  const bodyStart = code.indexOf('\n', defStart) + 1
+  const bodyTrimmed = code.slice(bodyStart).trimStart()
+  return bodyTrimmed.startsWith('"""') || bodyTrimmed.startsWith("'''")
+}
+
+function isStubBody(code: string, defStart: number): boolean {
+  const newline = code.indexOf('\n', defStart)
+  if (newline === -1) return true
+  const nextNewline = code.indexOf('\n', newline + 1)
+  const bodyLine = nextNewline === -1
+    ? code.slice(newline + 1)
+    : code.slice(newline + 1, nextNewline)
+  return STUB_BODY.test(bodyLine)
+}
+
+function checkPython(code: string, violations: Array<Violation>): void {
+  // 1. Docstring check
+  let m: RegExpExecArray | null
+  DEF_LINE.lastIndex = 0
+  while ((m = DEF_LINE.exec(code)) !== null) {
+    const fnName = m[2]
+    const defStart = m.index
+    if (!hasDocstring(code, defStart) && !isStubBody(code, defStart)) {
+      violations.push({ function: fnName, line: lineNumber(code, defStart), reason: 'missing docstring' })
+    }
+  }
+
+  // 2. Non-descriptive variable check
+  NON_DESCRIPTIVE.lastIndex = 0
+  while ((m = NON_DESCRIPTIVE.exec(code)) !== null) {
+    const varName = m[2]
+    violations.push({ line: lineNumber(code, m.index), variable: varName, reason: 'non-descriptive variable name' })
+  }
+
+  // 3. SQL camelCase column check
+  SQL_STRING.lastIndex = 0
+  while ((m = SQL_STRING.exec(code)) !== null) {
+    const sqlContent = m[1]
+    const sqlStart = m.index
+    CAMEL_IDENTIFIER.lastIndex = 0
+    let cm: RegExpExecArray | null
+    while ((cm = CAMEL_IDENTIFIER.exec(sqlContent)) !== null) {
+      violations.push({
+        line: lineNumber(code, sqlStart),
+        column: cm[1],
+        reason: 'SQL column must be snake_case',
+      })
+    }
+  }
+}
+
+function checkFilename(context: GateContext, violations: Array<Violation>): void {
+  const basename = path.basename(context.file)
+    .replace(/\.(test|spec)\.(ts|js)$/, '')
+    .replace(/\.(ts|js)$/, '')
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(basename)) {
+    violations.push({ file: context.file, reason: 'TypeScript filename must be kebab-case' })
+  }
+}
+
+export function styleCheck(code: string, context: GateContext): GateResult {
+  const violations: Array<Violation> = []
+  const ext = path.extname(context.file)
+
+  if (ext === '.py') {
+    checkPython(code, violations)
+  } else if (ext === '.ts' || ext === '.js') {
+    checkFilename(context, violations)
+  }
+
+  if (violations.length > 0) {
+    return { passed: false, violations }
+  }
+  return { passed: true }
+}

package/gates/types.ts

@@ -0,0 +1,13 @@
+/** Shared gate types — all Story 6.x gate implementations must satisfy this contract. */
+
+export interface GateContext {
+  file: string;
+  phase: string;
+  sessionId: string;
+}
+
+export type GateResult =
+  | { passed: true }
+  | { passed: false; violations: Array<{ line?: number; reason: string; [key: string]: unknown }> };
+
+export type GateFn = (code: string, context: GateContext) => GateResult;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "frappe-builder",
+  "version": "1.1.0-dev.10",
+  "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
+  "type": "module",
+  "bin": {
+    "frappe-builder": "./dist/cli.mjs"
+  },
+  "pi": {
+    "_note": "TODO: verify 'pi' field schema against @mariozechner/pi-agent-core docs — no schema found in installed package. Reference schema below is a best-guess pending confirmation.",
+    "extensions": [
+      "./extensions/frappe-session.ts",
+      "./extensions/frappe-state.ts",
+      "./extensions/frappe-workflow.ts",
+      "./extensions/frappe-tools.ts",
+      "./extensions/frappe-gates.ts",
+      "./extensions/frappe-ui.ts"
+    ],
+    "agents": "./AGENTS.md"
+  },
+  "scripts": {
+    "build": "bun build --compile --minify src/cli.ts --outfile frappe-builder",
+    "build:ts": "tsdown",
+    "test": "vitest run",
+    "dev": "pi -e ./extensions/frappe-state.ts",
+    "typecheck": "tsc --noEmit",
+    "release": "node scripts/bump-version.mjs"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "@mariozechner/pi-agent-core": "0.62.0",
+    "@mariozechner/pi-ai": "0.62.0",
+    "@mariozechner/pi-coding-agent": "^0.63.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.8.0",
+    "execa": "^9.6.1",
+    "robot3": "^1.2.0"
+  }
+}

package/project-context.md

@@ -0,0 +1,146 @@
+# Project Context: frappe-builder
+
+> AI agent rules and project context for consistent implementation across sessions.
+> Generated: 2026-03-23 | Author: Riz
+
+---
+
+## What This Project Is
+
+**frappe-builder** is a pi-package CLI tool — a Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications. It upgrades the existing BMAD module by replacing all prompt-enforced state management with hook-based code enforcement.
+
+**The core shift:** State is owned by code, not conversation. Prompts cannot enforce anything. Hooks can.
+
+---
+
+## Project Type & Context
+
+- **Type:** Developer tool (CLI / AI agent extension for pi-mono)
+- **Context:** Brownfield — upgrading an existing BMAD module, not building from scratch
+- **Runtime:** TypeScript, Node.js 20+ LTS
+- **Primary platform:** pi-mono agent framework (pi-ai)
+
+---
+
+## Architecture Rules for AI Agents
+
+### State Management
+
+1. **JSONL is the immutable source of truth.** Every tool call appends to `~/.frappe-builder/sessions/{id}.jsonl`. Never overwrite or delete entries.
+2. **SQLite (`state.db`) is derived state.** It is rebuilt from JSONL on demand. Never treat it as authoritative over JSONL.
+3. **`afterToolCall` writes state unconditionally.** No tool call completes without a state write. There is no optional path.
+4. **Every startup is a resume.** There is no "new session" vs "resume" split. Session start always reads JSONL, reconstructs SQLite, and injects state context.
+5. **State injection must complete in <500ms** before the first LLM prompt is sent (NFR1).
+
+### Workflow Enforcement
+
+6. **Robot3 FSM governs all workflow transitions.** Valid states: `idle → requirements → architecture → planning → implementation → testing → documentation → idle`.
+7. **`beforeToolCall` blocks out-of-phase tools.** When blocking, the explanation must name: (a) the blocked tool, (b) the current FSM phase, (c) the phase where the tool becomes valid.
+8. **`--mode quick` bypasses the FSM phase cycle** but never bypasses quality gates. Quality gates are always active.
+9. **`--override-workflow` is the only valid escape hatch.** It must be logged to JSONL with a reason. It does not disable quality gates.
+
+### Quality Gates
+
+10. **Quality gates run before any code is written to disk.** They are static analysis scans — deterministic, not LLM judgement. The same violation always produces the same block.
+11. **Six gates are mandatory:**
+    - Every `@frappe.whitelist()` method must include permission checks
+    - No SQL string concatenation — parameterised queries only
+    - Business logic in Python server-side — no client-side business logic
+    - Frappe-native solution required first — non-Frappe solutions need explicit developer justification
+    - Test coverage ≥70% critical-path before feature marked complete
+    - Docstrings and naming conventions (no `x`, `data`, `temp` variable names)
+12. **No feature is marked complete until all quality gates pass.** No exceptions.
+
+### Frappe Integration
+
+13. **All Frappe tool outputs go through mcp2cli + context-mode.** Raw Frappe API payloads must never enter the LLM context directly.
+14. **Bench commands run via subprocess — whitelisted only.** No raw shell access through the tool layer.
+15. **context7 for Frappe/ERPNext documentation.** Never raw web fetch for docs.
+16. **Bench subprocess calls are non-blocking.** Long-running operations (migrate, build) must not freeze the TUI or agent loop.
+
+### Context Budget
+
+17. **LLM context window is a hard constraint.** Across any 50-turn session, total context must stay ≤80% of the active model's window.
+18. **State injection at session start must consume ≤15% of context window.**
+19. **context-mode degradation is graceful** — falls back to truncated direct output, never crashes.
+
+### Security
+
+20. **LLM API keys live exclusively in `~/.frappe-builder/config.json`.** Never in project files. Never in git.
+21. **Frappe site credentials live in `{project}/.frappe-builder-config.json`** — must be gitignored. System refuses to proceed if not gitignored.
+22. **JSONL session logs are local only** (`~/.frappe-builder/sessions/`). Never transmitted externally.
+
+### Code Style
+
+23. **Generated code is lean and self-documenting.** Descriptive names, no abbreviations. No `x`, `data`, `result`, `temp` variables.
+24. **Every function/method gets a docstring.** No exceptions in generated code.
+25. **Frappe-native patterns first.** Before reaching for an external library or custom solution, verify Frappe's built-in capability is insufficient.
+
+---
+
+## Specialist Agent Map
+
+| FSM Phase | Specialist Auto-Loaded |
+|---|---|
+| `requirements` | frappe-ba (Business Analyst) |
+| `architecture` | frappe-architect |
+| `planning` | frappe-planner |
+| `implementation` | frappe-dev |
+| `testing` | frappe-qa |
+| `documentation` | frappe-docs |
+| Any phase (manual) | frappe-debugger |
+| Base identity (always) | frappe-nexus (via AGENTS.md) |
+
+---
+
+## Tool API Surface
+
+| Tool | Phase Available | Purpose |
+|---|---|---|
+| `set_active_project` | Any | Switch active Frappe project/site |
+| `start_feature` | idle | Begin feature workflow (`--mode quick` for fast path) |
+| `complete_component` | implementation | Mark component done, trigger state cascade |
+| `scaffold_doctype` | implementation | Generate DocType scaffold via bench |
+| `run_tests` | testing | Execute Frappe test suite, record results |
+| `get_project_status` | Any | Read project dashboard from state.db |
+| `frappe_query` | Any | Query Frappe via mcp2cli (sandboxed) |
+| `bench_execute` | Any | Run whitelisted bench commands |
+
+---
+
+## Build Phases
+
+| Phase | Deliverable | Gate |
+|---|---|---|
+| 1 | Core State Infrastructure | start→tools→kill→restart→verify exact reconstruction |
+| 2 | Frappe Tool Layer | All 8 tools functional with mcp2cli + context-mode |
+| 3 | TUI & Visibility | Footer widget live; /status dashboard working |
+| 4 | Quality Gates & Knowledge Base | All 6 gates enforced; 8 specialists converted to pi skills |
+| 5 | Distribution | pi package + npm binary published |
+
+**Phase 1 is the critical path. Everything depends on it.**
+
+---
+
+## What This Is Replacing
+
+| Current (BMAD module) | Replacement |
+|---|---|
+| Prompt-enforced state | `afterToolCall` hook → JSONL + SQLite |
+| Bi-modal New/Resume split | Every startup is a resume |
+| `state/templates/*.yaml` | `state.db` (SQLite) |
+| `standards/state-management.md` | Hook enforcement |
+| `agents/*.agent.yaml` | AGENTS.md + pi skills |
+| `workflows/` step files | Robot3 FSM transitions |
+| STATE CASCADE in all 8 agents | Single `afterToolCall` hook |
+
+---
+
+## Measurable Success Criteria
+
+- Zero state drift incidents in sessions ≥50 turns
+- Agent orientation on resume: ≤1 turn to full context
+- State injection context footprint: <15% of context window
+- State injection latency: <500ms
+- All generated code passes quality gates before written to disk
+- No feature marked complete until all quality gates pass