@benzotti/jedi 0.1.32 → 0.1.34

package/dist/index.js

@@ -9355,7 +9355,7 @@ Recognise natural language JDI intents and invoke the matching skill via the Ski
 
 Extract flags from context: "in a worktree" \u2192 \`--worktree\`, "lightweight" \u2192 \`--worktree-lightweight\`, "single agent" \u2192 \`--single\`, "use teams" \u2192 \`--team\`. If the intent is unclear, ask. Never guess.
 
-Planning and implementation are separate gates \u2014 NEVER auto-proceed to implementation after plan approval.
+Planning and implementation are separate human-gated phases \u2014 NEVER auto-proceed to implementation after plan approval. When a plan is approved, STOP and wait for an explicit implementation request.
 
 ## Iterative Refinement
 
@@ -9379,7 +9379,7 @@ Recognise natural language JDI intents and invoke the matching skill via the Ski
 
 Extract flags from context: "in a worktree" \u2192 \`--worktree\`, "lightweight" \u2192 \`--worktree-lightweight\`, "single agent" \u2192 \`--single\`, "use teams" \u2192 \`--team\`. If the intent is unclear, ask. Never guess.
 
-Planning and implementation are separate gates \u2014 NEVER auto-proceed to implementation after plan approval.
+Planning and implementation are separate human-gated phases \u2014 NEVER auto-proceed to implementation after plan approval. When a plan is approved, STOP and wait for an explicit implementation request.
 
 ## Iterative Refinement
 
@@ -9975,6 +9975,9 @@ function buildReviewPrompt(ctx, prNum, meta, diff) {
     ``,
     meta,
     ``,
+    ...buildLearningsBlock(ctx.techStack),
+    `Cross-reference learnings against every change \u2014 flag violations and praise adherence.`,
+    ``,
     `## Diff`,
     "```diff",
     diff,
@@ -9992,6 +9995,7 @@ function buildReviewPrompt(ctx, prNum, meta, diff) {
     `- Does it follow the project's existing patterns?`,
     `- Are naming conventions consistent?`,
     `- Is the code well-organised?`,
+    `- Does it follow the team's documented learnings?`,
     ``,
     `### Security`,
     `- Any injection risks (SQL, XSS, command)?`,
@@ -10080,6 +10084,72 @@ async function writeState(cwd, state) {
 }
 
 // src/utils/state-handlers.ts
+var import_yaml4 = __toESM(require_dist(), 1);
+import { join as join9 } from "path";
+import { existsSync as existsSync9 } from "fs";
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match)
+    return null;
+  try {
+    return import_yaml4.parse(match[1]);
+  } catch {
+    return null;
+  }
+}
+async function transitionToPlanReady(cwd, planPath, planName) {
+  const state = await readState(cwd) ?? {};
+  const fullPlanPath = planPath.startsWith("/") ? planPath : join9(cwd, planPath);
+  let phase;
+  let planNumber;
+  let taskFiles = [];
+  if (existsSync9(fullPlanPath)) {
+    const content = await Bun.file(fullPlanPath).text();
+    const fm = parseFrontmatter(content);
+    if (fm) {
+      if (fm.phase != null)
+        phase = Number(fm.phase);
+      if (fm.plan != null)
+        planNumber = String(fm.plan);
+      if (Array.isArray(fm.task_files))
+        taskFiles = fm.task_files;
+    }
+  }
+  state.position = {
+    ...state.position,
+    ...phase != null ? { phase } : {},
+    plan: planNumber ?? planPath,
+    plan_name: planName,
+    status: "planning"
+  };
+  state.current_plan = {
+    ...state.current_plan,
+    path: planPath,
+    tasks: taskFiles,
+    completed_tasks: [],
+    current_task_index: taskFiles.length > 0 ? 0 : null
+  };
+  state.progress = {
+    ...state.progress,
+    tasks_total: taskFiles.length,
+    tasks_completed: 0
+  };
+  state.review = {
+    ...state.review,
+    status: "in_review",
+    scope: "plan"
+  };
+  await updateSessionActivity(cwd, state);
+}
+async function transitionToApproved(cwd) {
+  const state = await readState(cwd) ?? {};
+  state.review = {
+    ...state.review,
+    status: "approved",
+    approved_at: new Date().toISOString()
+  };
+  await updateSessionActivity(cwd, state);
+}
 async function transitionToExecuting(cwd, taskId, taskName) {
   const state = await readState(cwd) ?? {};
   state.position = {
@@ -10098,6 +10168,24 @@ async function transitionToComplete(cwd) {
   };
   await updateSessionActivity(cwd, state);
 }
+async function advanceTask(cwd, completedTaskId) {
+  const state = await readState(cwd) ?? {};
+  if (state.current_plan) {
+    const completed = state.current_plan.completed_tasks ?? [];
+    if (!completed.includes(completedTaskId)) {
+      completed.push(completedTaskId);
+    }
+    state.current_plan.completed_tasks = completed;
+    const tasks = state.current_plan.tasks ?? [];
+    const nextIndex = completed.length;
+    state.current_plan.current_task_index = nextIndex < tasks.length ? nextIndex : null;
+  }
+  if (!state.progress) {
+    state.progress = { phases_total: 0, phases_completed: 0, plans_total: 0, plans_completed: 0, tasks_total: 0, tasks_completed: 0 };
+  }
+  state.progress.tasks_completed = (state.progress.tasks_completed ?? 0) + 1;
+  await updateSessionActivity(cwd, state);
+}
 async function updateSessionActivity(cwd, state) {
   state.session = {
     ...state.session,
@@ -10278,15 +10366,15 @@ var statusCommand = defineCommand({
 import { relative } from "path";
 
 // src/utils/resolve-components.ts
-import { join as join9, basename } from "path";
+import { join as join10, basename } from "path";
 import { homedir } from "os";
 async function resolveComponents(cwd) {
   const components = [];
   const seen = new Set;
   const sources = [
-    { dir: join9(cwd, ".jdi", "framework", "components"), source: "project" },
-    { dir: join9(homedir(), ".jdi", "components"), source: "user" },
-    { dir: join9(import.meta.dir, "../framework/components"), source: "builtin" }
+    { dir: join10(cwd, ".jdi", "framework", "components"), source: "project" },
+    { dir: join10(homedir(), ".jdi", "components"), source: "user" },
+    { dir: join10(import.meta.dir, "../framework/components"), source: "builtin" }
   ];
   for (const { dir, source } of sources) {
     try {
@@ -10295,7 +10383,7 @@ async function resolveComponents(cwd) {
         const name = basename(file, ".md");
         if (!seen.has(name)) {
           seen.add(name);
-          components.push({ name, path: join9(dir, file), source });
+          components.push({ name, path: join10(dir, file), source });
         }
       }
     } catch {}
@@ -10441,8 +10529,8 @@ Use --all to stage and commit all, or stage files manually.`);
 });
 
 // src/commands/pr.ts
-import { existsSync as existsSync9 } from "fs";
-import { join as join10 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { join as join11 } from "path";
 async function hasGhCli() {
   const { exitCode } = await exec(["which", "gh"]);
   return exitCode === 0;
@@ -10493,8 +10581,8 @@ var prCommand = defineCommand({
     let verificationChecks = [];
     const planPath = state?.current_plan?.path;
     if (planPath) {
-      const fullPlanPath = join10(cwd, planPath);
-      if (existsSync9(fullPlanPath)) {
+      const fullPlanPath = join11(cwd, planPath);
+      if (existsSync10(fullPlanPath)) {
         try {
           const planContent = await Bun.file(fullPlanPath).text();
           const nameMatch = planContent.match(/^#\s+(.+)/m);
@@ -10517,8 +10605,8 @@ ${taskLines.map((l2) => `- ${l2.split("|").slice(2, 3).join("").trim()}`).join(`
       }
     }
     let template = "";
-    const templatePath = join10(cwd, ".github", "pull_request_template.md");
-    if (existsSync9(templatePath)) {
+    const templatePath = join11(cwd, ".github", "pull_request_template.md");
+    if (existsSync10(templatePath)) {
       template = await Bun.file(templatePath).text();
     }
     const title = branch.replace(/^(feat|fix|chore|docs|refactor|test|ci)\//, "").replace(/[-_]/g, " ").replace(/^\w/, (c3) => c3.toUpperCase());
@@ -10621,7 +10709,8 @@ ${data.body}` : ""
         meta = metaResult.stdout;
       }
     }
-    const prompt2 = buildReviewPrompt({ cwd: process.cwd(), projectType: "", techStack: "", qualityGates: "", learningsPath: null, codebaseIndexPath: null, adapter: null }, String(prNum), meta, diffResult.stdout);
+    const ctx = await gatherPromptContext(process.cwd());
+    const prompt2 = buildReviewPrompt(ctx, String(prNum), meta, diffResult.stdout);
     if (args.output) {
       await Bun.write(resolve7(process.cwd(), args.output), prompt2);
       consola.success(`Review prompt written to ${args.output}`);
@@ -10813,7 +10902,7 @@ var quickCommand = defineCommand({
 });
 
 // src/commands/worktree.ts
-import { existsSync as existsSync10 } from "fs";
+import { existsSync as existsSync11 } from "fs";
 function slugify(name) {
   return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
 }
@@ -10847,7 +10936,7 @@ var worktreeCommand = defineCommand({
     }
     const slug = slugify(args.name);
     const worktreePath = `${root}/.worktrees/${slug}`;
-    if (existsSync10(worktreePath)) {
+    if (existsSync11(worktreePath)) {
       consola.error(`Worktree already exists at ${worktreePath}`);
       return;
     }
@@ -11013,7 +11102,7 @@ Specify a worktree name: jdi worktree-remove <name>`);
 
 // src/commands/plan-review.ts
 import { resolve as resolve9 } from "path";
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync12 } from "fs";
 function parsePlanSummary(content) {
   const nameMatch = content.match(/^# .+?: (.+)$/m);
   const name = nameMatch?.[1] ?? "Unknown";
@@ -11052,7 +11141,7 @@ var planReviewCommand = defineCommand({
       consola.error("No plan found. Run `jdi plan` first.");
       return;
     }
-    if (!existsSync11(planPath)) {
+    if (!existsSync12(planPath)) {
       consola.error(`Plan not found: ${planPath}`);
       return;
     }
@@ -11142,7 +11231,7 @@ Tasks (${tasks.length}):`);
 
 // src/commands/plan-approve.ts
 import { resolve as resolve10 } from "path";
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync13 } from "fs";
 var planApproveCommand = defineCommand({
   meta: {
     name: "plan-approve",
@@ -11171,7 +11260,7 @@ var planApproveCommand = defineCommand({
       consola.error("No plan to approve. Run `jdi plan` first.");
       return;
     }
-    if (!existsSync12(planPath)) {
+    if (!existsSync13(planPath)) {
       consola.error(`Plan not found: ${planPath}`);
       return;
     }
@@ -11648,16 +11737,16 @@ Say **\`Hey Jedi implement\`** when you're ready to go.`;
       return;
     }
     if (intent.command === "ping") {
-      const { existsSync: existsSync13 } = await import("fs");
-      const { join: join12 } = await import("path");
-      const frameworkExists = existsSync13(join12(cwd, ".jdi/framework"));
-      const claudeMdExists = existsSync13(join12(cwd, ".claude/CLAUDE.md"));
-      const stateExists = existsSync13(join12(cwd, ".jdi/config/state.yaml"));
-      const learningsExists = existsSync13(join12(cwd, ".jdi/persistence/learnings.md"));
+      const { existsSync: existsSync14 } = await import("fs");
+      const { join: join13 } = await import("path");
+      const frameworkExists = existsSync14(join13(cwd, ".jdi/framework"));
+      const claudeMdExists = existsSync14(join13(cwd, ".claude/CLAUDE.md"));
+      const stateExists = existsSync14(join13(cwd, ".jdi/config/state.yaml"));
+      const learningsExists = existsSync14(join13(cwd, ".jdi/persistence/learnings.md"));
       let version = "unknown";
       try {
-        const pkgPath = join12(cwd, "node_modules/@benzotti/jedi/package.json");
-        if (existsSync13(pkgPath)) {
+        const pkgPath = join13(cwd, "node_modules/@benzotti/jedi/package.json");
+        if (existsSync14(pkgPath)) {
           const pkg = JSON.parse(await Bun.file(pkgPath).text());
           version = pkg.version;
         }
@@ -11773,11 +11862,12 @@ Say **\`Hey Jedi implement\`** when you're ready to go.`;
         `## Instructions`,
         `Read state.yaml and existing plan files. Apply feedback incrementally \u2014 do not restart from scratch.`,
         `If the feedback is a question, answer it conversationally. If it implies a plan change, update the plan.`,
+        `Maintain the SPLIT plan format: update the index file and individual task files (.T{n}.md) separately.`,
         ``,
         `## Response Format (MANDATORY)`,
-        `1-2 sentence summary of what changed. Then the full updated plan in a collapsible block:`,
+        `1-2 sentence summary of what changed. Then the updated plan summary in a collapsible block:`,
         `\`<details><summary>View full plan</summary> ... </details>\``,
-        `Use the same plan structure as the initial plan (tasks table, per-task details, verification).`,
+        `Show the tasks manifest table and brief summaries \u2014 full task details are in the task files.`,
         `End with: "Any changes before implementation?"`
       ].join(`
 `);
@@ -11810,8 +11900,14 @@ Use the ClickUp ticket above as the primary requirements source.` : ``,
             `## Learnings`,
             `Before planning, read .jdi/persistence/learnings.md and .jdi/framework/learnings/ if they exist. Apply any team preferences found.`,
             ``,
+            `## Plan File Format`,
+            `CRITICAL: You MUST write plan files in SPLIT format as defined in your spec (Step 7a):`,
+            `1. Write the index file: \`.jdi/plans/{phase}-{plan}-{slug}.plan.md\` \u2014 contains frontmatter with \`task_files:\` list and a manifest table only (NO inline task details)`,
+            `2. Write each task as a separate file: \`.jdi/plans/{phase}-{plan}-{slug}.T{n}.md\` \u2014 one file per task with full implementation details`,
+            `This split format is MANDATORY \u2014 it reduces token usage by letting agents load only their assigned task.`,
+            ``,
             `## Response Format`,
-            `Follow the planning workflow in your spec to write plan files. Then respond with EXACTLY this structure (no deviations, no meta-commentary like "You are now active as..." or "Plan created"):`,
+            `After writing the split plan files, respond with EXACTLY this structure (no deviations, no meta-commentary):`,
             ``,
             `1-2 sentence summary of the approach.`,
             ``,
@@ -11828,16 +11924,7 @@ Use the ClickUp ticket above as the primary requirements source.` : ``,
             `|------|------|------|------|------|`,
             `| T1 | {name} | {S|M|L} | auto | 1 |`,
             ``,
-            `### T1 \u2014 {Task Name}`,
-            `**Objective:** {what this achieves}`,
-            ``,
-            `**Steps:**`,
-            `1. {step}`,
-            ``,
-            `**Done when:** {completion criterion}`,
-            ``,
-            `---`,
-            `(repeat for each task)`,
+            `(For each task, show a brief 1-2 line summary \u2014 full details are in the task files)`,
             ``,
             `### Verification`,
             `- [ ] {check 1}`,
@@ -12036,8 +12123,8 @@ Use the ClickUp ticket above as the primary requirements source.` : ``,
 });
 
 // src/commands/setup-action.ts
-import { join as join12, dirname as dirname3 } from "path";
-import { existsSync as existsSync13, mkdirSync as mkdirSync4 } from "fs";
+import { join as join13, dirname as dirname3 } from "path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync4 } from "fs";
 var setupActionCommand = defineCommand({
   meta: {
     name: "setup-action",
@@ -12046,18 +12133,18 @@ var setupActionCommand = defineCommand({
   args: {},
   async run() {
     const cwd = process.cwd();
-    const workflowDest = join12(cwd, ".github", "workflows", "jedi.yml");
-    if (existsSync13(workflowDest)) {
+    const workflowDest = join13(cwd, ".github", "workflows", "jedi.yml");
+    if (existsSync14(workflowDest)) {
       consola.warn(`Workflow already exists at ${workflowDest}`);
       consola.info("Skipping workflow copy. Delete it manually to regenerate.");
     } else {
-      const templatePath = join12(import.meta.dir, "../action/workflow-template.yml");
-      if (!existsSync13(templatePath)) {
+      const templatePath = join13(import.meta.dir, "../action/workflow-template.yml");
+      if (!existsSync14(templatePath)) {
         consola.error("Workflow template not found. Ensure @benzotti/jedi is properly installed.");
         process.exit(1);
       }
       const dir = dirname3(workflowDest);
-      if (!existsSync13(dir))
+      if (!existsSync14(dir))
         mkdirSync4(dir, { recursive: true });
       const template = await Bun.file(templatePath).text();
       await Bun.write(workflowDest, template);
@@ -12093,10 +12180,114 @@ var setupActionCommand = defineCommand({
 `));
   }
 });
+
+// src/commands/state.ts
+var planReadyCommand = defineCommand({
+  meta: {
+    name: "plan-ready",
+    description: "Transition state after plan creation"
+  },
+  args: {
+    "plan-path": {
+      type: "string",
+      description: "Path to the plan file",
+      required: true
+    },
+    "plan-name": {
+      type: "string",
+      description: "Human-readable plan name",
+      required: true
+    }
+  },
+  async run({ args }) {
+    const cwd = process.cwd();
+    await transitionToPlanReady(cwd, args["plan-path"], args["plan-name"]);
+    consola.success(`State \u2192 plan-ready (${args["plan-name"]})`);
+  }
+});
+var approvedCommand = defineCommand({
+  meta: {
+    name: "approved",
+    description: "Transition state after plan approval"
+  },
+  async run() {
+    const cwd = process.cwd();
+    await transitionToApproved(cwd);
+    consola.success("State \u2192 approved");
+  }
+});
+var executingCommand = defineCommand({
+  meta: {
+    name: "executing",
+    description: "Transition state when implementation starts"
+  },
+  args: {
+    "task-id": {
+      type: "string",
+      description: "Current task ID",
+      required: false
+    },
+    "task-name": {
+      type: "string",
+      description: "Current task name",
+      required: false
+    }
+  },
+  async run({ args }) {
+    const cwd = process.cwd();
+    await transitionToExecuting(cwd, args["task-id"], args["task-name"]);
+    consola.success("State \u2192 executing");
+  }
+});
+var completeCommand = defineCommand({
+  meta: {
+    name: "complete",
+    description: "Transition state after implementation finishes"
+  },
+  async run() {
+    const cwd = process.cwd();
+    await transitionToComplete(cwd);
+    consola.success("State \u2192 complete");
+  }
+});
+var advanceTaskCommand = defineCommand({
+  meta: {
+    name: "advance-task",
+    description: "Mark a task as completed and advance to next"
+  },
+  args: {
+    "task-id": {
+      type: "positional",
+      description: "ID of the completed task",
+      required: true
+    }
+  },
+  async run({ args }) {
+    const cwd = process.cwd();
+    await advanceTask(cwd, args["task-id"]);
+    const state = await readState(cwd);
+    const completed = state?.current_plan?.completed_tasks?.length ?? 0;
+    const total = state?.current_plan?.tasks?.length ?? 0;
+    consola.success(`Task ${args["task-id"]} completed (${completed}/${total})`);
+  }
+});
+var stateCommand = defineCommand({
+  meta: {
+    name: "state",
+    description: "Manage JDI state transitions"
+  },
+  subCommands: {
+    "plan-ready": planReadyCommand,
+    approved: approvedCommand,
+    executing: executingCommand,
+    complete: completeCommand,
+    "advance-task": advanceTaskCommand
+  }
+});
 // package.json
 var package_default = {
   name: "@benzotti/jedi",
-  version: "0.1.32",
+  version: "0.1.34",
   description: "JDI - Context-efficient AI development framework for Claude Code",
   type: "module",
   bin: {
@@ -12158,7 +12349,8 @@ var main = defineCommand({
     "plan-review": planReviewCommand,
     "plan-approve": planApproveCommand,
     action: actionCommand,
-    "setup-action": setupActionCommand
+    "setup-action": setupActionCommand,
+    state: stateCommand
   }
 });
 runMain(main);

package/framework/agents/jdi-planner.md

@@ -15,14 +15,16 @@ You create executable implementation plans with proper task sizing, dependency m
 
 ## CRITICAL: Scope Discipline
 
-You MUST only plan what was explicitly requested. Never infer, assume, or add extras.
+Do not add unrelated extras (tooling, testing, linting, CI) unless the user explicitly requests them. But you MUST thoroughly investigate the full scope of what WAS requested — including implicit requirements.
 
 **Rules:**
-1. **Only include what was asked for.** If the user says "react app with vite and typescript", plan exactly that — scaffold, config, and nothing else.
-2. **Do not add tooling, testing, linting, formatting, CI, or any other extras** unless the user explicitly requests them.
-3. **Do not make subjective decisions.** If something is ambiguous (e.g. folder structure, routing library, state management), list it as an open question and ask the user — do not guess.
-4. **Suggest optional additions separately.** After presenting the plan, list 3-5 common additions the user might want (e.g. "Would you also like: testing (Vitest)? linting (ESLint)? formatting (Prettier)?"). These are suggestions, NOT part of the plan.
-5. **Same request = same plan.** Two identical requests must produce structurally identical plans. Achieve this by following the templates exactly and not improvising.
+1. **Do not add unrelated extras.** If the user says "react app with vite and typescript", plan scaffold and config — not linting, CI, or testing unless asked.
+2. **DO investigate the full scope of the request.** "Scope discipline" means no unrelated additions — it does NOT mean ignoring requirements that are clearly implied by the request. If the user asks for a UI view with specific columns, you must verify those columns exist in the backend response, and plan to add them if they don't.
+3. **When reference PRs/tickets are provided, analyse them thoroughly.** Read the actual diff, files changed, patterns used, columns/fields added, routes created, and data flow. The user provides reference PRs so you follow the same pattern — extract the full pattern, don't just skim.
+4. **When the user says "backend is already done", verify it.** Read the actual API endpoint, check what fields it returns, and confirm they match the frontend requirements. If there's a gap, include it in the plan.
+5. **Do not make subjective decisions.** If something is ambiguous (e.g. folder structure, routing library, state management), list it as an open question and ask the user — do not guess.
+6. **Suggest optional additions separately.** After presenting the plan, list 3-5 common additions the user might want. These are suggestions, NOT part of the plan.
+7. **Same request = same plan.** Two identical requests must produce structurally identical plans. Achieve this by following the templates exactly and not improvising.
 
 ## CRITICAL: Read Learnings First
 
@@ -35,13 +37,18 @@ Before planning, ALWAYS:
 
 You MUST write files using Write/Edit tools. Returning plan content as text is NOT acceptable.
 
-Required files:
-1. `.jdi/plans/{phase}-{plan}-{slug}.plan.md` (index file)
-2. `.jdi/plans/{phase}-{plan}-{slug}.T{n}.md` (one per task)
-3. `.jdi/config/state.yaml`
-4. `.jdi/config/variables.yaml`
-5. `.jdi/ROADMAP.yaml` (add plan entry)
-6. `.jdi/REQUIREMENTS.yaml` (add traceability)
+**SANDBOX OVERRIDE:** Plan file creation is an EXCEPTION to AgentBase sandbox rules. You MUST use the Write tool to create plan files directly — do NOT defer them to `files_to_create`. Plan files WILL persist when written via the Write tool. This override applies ONLY to `.jdi/plans/` and `.jdi/config/` files listed below.
+
+Required files (SPLIT FORMAT — one file per task):
+1. `.jdi/plans/{phase}-{plan}-{slug}.plan.md` (index file — manifest table only, NO inline task details)
+2. `.jdi/plans/{phase}-{plan}-{slug}.T{n}.md` (one per task — full implementation details)
+3. `.jdi/config/variables.yaml`
+4. `.jdi/ROADMAP.yaml` (add plan entry)
+5. `.jdi/REQUIREMENTS.yaml` (add traceability)
+
+The split format is MANDATORY. Each task MUST be a separate `.T{n}.md` file. The index file contains ONLY the frontmatter (with `task_files:` list) and a manifest table — NEVER inline task implementation details.
+
+**Do NOT manually edit `.jdi/config/state.yaml`** — state transitions are handled via CLI commands (e.g. `npx jdi state plan-ready`).
 
 ## File Naming
 
@@ -87,6 +94,15 @@ Never use time estimates. Use S/M/L sizing in task manifests and plan summaries.
 4. Research: standard stack, architecture patterns, common pitfalls
 5. Findings feed directly into planning (no separate RESEARCH.md)
 
+### Step 0b: Reference Analysis (when provided)
+
+If the user provides reference PRs, tickets, or example implementations:
+
+1. **Reference PRs**: Fetch each PR's diff (`gh pr diff {number}`), list of changed files (`gh pr view {number} --json files`), and description. Analyse the **complete pattern**: what files were changed, what columns/fields were added, what routes were created, what data transformations were applied. The reference PR defines the pattern you must follow — extract every detail.
+2. **Existing backend/API work**: When the user states "backend is already done" or implies API endpoints exist, verify by reading the actual route files, controllers, and response shapes. Confirm the API returns all fields the frontend will need. If fields are missing, include them in the plan.
+3. **ClickUp/ticket context**: If a ticket URL is provided, read the ticket's description, acceptance criteria, and any attached specifications. Cross-reference against what the plan covers.
+4. **Data requirements for UI work**: When planning a view/page/table, explicitly list every column/field the UI needs, verify each one exists in the API response, and plan to add any that are missing (both backend and frontend).
+
 ### Step 1: Discovery
 
 <JDI:TaskBreakdown source="requirements" />
@@ -94,6 +110,8 @@ Never use time estimates. Use S/M/L sizing in task manifests and plan summaries.
 #### Mandatory Verification (never skip)
 - **Bug fixes**: Grep the symptom across entire codebase. Trace every occurrence through all layers. Do not stop at first match.
 - **API boundaries**: Read backend route, controller, and request validation (or frontend consumer). Never assume endpoint fields.
+- **UI views/tables**: List every column from the requirements. Verify each column's data source exists in the backend response. Plan to add missing fields end-to-end (backend + frontend).
+- **Reference PR patterns**: If reference PRs were provided, verify the plan covers every layer those PRs touched (routes, controllers, types, components, hooks, etc.).
 
 ### Step 2: Scope Estimation
 If >4 tasks or >3 hours, split into multiple plans.
@@ -133,12 +151,9 @@ Types: `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-actio
 
 ### Step 7: Generate Plan Document and Update Scaffolding (WRITE FILES)
 
-<JDI:StateUpdate />
-
-#### 7-pre: Update State Files
-Read `.jdi/config/state.yaml` (create from template if missing). Update: `position.phase`, `position.plan`, `position.status` → `"planning"`, `progress.plans_total`, `progress.tasks_total`, `current_plan.path`, `current_plan.tasks`. Each task entry must include `file:` field pointing to the task file path.
+**Do NOT manually edit `.jdi/config/state.yaml`** — use `npx jdi state` CLI commands for transitions. Only record decisions, deviations, or blockers via `<JDI:StateUpdate />`.
 
-#### 7-pre-b: Update Variables
+#### 7-pre: Update Variables
 Read `.jdi/config/variables.yaml` (create from template if missing). Update: `feature.name`, `feature.description`, `feature.type`.
 
 #### 7a: Write Plan Files (Split Format)

package/framework/commands/create-plan.md

@@ -20,12 +20,18 @@ Create an implementation plan using a single planner agent (includes research).
 2. Read codebase context (`.jdi/codebase/SUMMARY.md` if exists)
 3. Read scaffolding (.jdi/PROJECT.yaml, REQUIREMENTS.yaml, ROADMAP.yaml) — create from templates if missing
 4. Quick Mode Detection — suggest /jdi:quick for trivial tasks
-5. Spawn `jdi-planner` agent (subagent_type="general-purpose") — creates PLAN.md with tasks, deps, waves
-6. Collect and execute deferred ops
-7. Update state.yaml: status → `"plan_ready"`, worktree state if active
-8. Initialise review: `review.status` → `"draft"`, `review.revision` → 1, `review.scope` → `"plan"`
-9. **Present summary** (name, objective, task table, files) then ask: _"Provide feedback to refine, or say **approved** to finalise."_
-10. **Review loop**: approval → update state to `"approved"`, confirm. Feedback → revise plan in-place, increment revision, re-present summary. Repeat until approved. This is natural conversation — no separate command needed.
+5. Spawn `jdi-planner` agent (subagent_type="general-purpose") — creates split plan files (index .plan.md + per-task .T{n}.md files). The planner MUST write these files directly via Write tool (sandbox override for plan files).
+6. Collect and execute deferred ops — if the agent returned `files_to_create`, create them now using Write tool. Verify split plan files exist: index `.plan.md` + individual `.T{n}.md` task files.
+7. **Update state via CLI** — do NOT manually edit state.yaml. Run:
+   ```bash
+   npx jdi state plan-ready --plan-path ".jdi/plans/{plan-file}" --plan-name "{plan name}"
+   ```
+8. **Present summary** (name, objective, task table, files) then ask: _"Provide feedback to refine, or say **approved** to finalise."_
+9. **Review loop**: Feedback → revise plan in-place, increment revision, re-present summary. Repeat until approved. Approval → run `npx jdi state approved`, then **STOP**.
+
+## HARD STOP — Planning Gate
+
+After the user approves the plan, your work is **DONE**. Output: _"Plan approved and finalised. Run `/jdi:implement-plan` when ready to execute."_ Then **STOP completely**. Do NOT invoke `/jdi:implement-plan`, do NOT spawn implementation agents, do NOT begin writing source code. Planning and implementation are separate human-gated phases.
 
 Agent base (read FIRST for cache): .jdi/framework/components/meta/AgentBase.md | Agent spec: .jdi/framework/agents/jdi-planner.md
 

package/framework/commands/implement-plan.md

@@ -15,18 +15,18 @@ Execute a PLAN.md with complexity-based routing.
 
 1. Read codebase context (`.jdi/codebase/SUMMARY.md` if exists)
 2. Read plan index file and state.yaml — parse frontmatter for tasks, deps, waves, tech_stack
-3. **Format detection:** If frontmatter contains `task_files:`, this is a split plan — task details are in separate files. If absent, legacy monolithic plan — all tasks inline.
-4. **Complexity routing** (`<JDI:ComplexityRouter />`): Simple (≤3 tasks, single stack/wave) → single agent. Complex → Agent Teams swarm. Override: `--team` / `--single`
-5. **Tech routing**: PHP → jdi-backend | TS/React → jdi-frontend | Full-stack → both
-6. Execute:
+3. **Read learnings:** Always read `.jdi/framework/learnings/general.md`. Then read domain-specific learnings based on tech_stack from plan frontmatter: PHP → `backend.md`, TS/React → `frontend.md`. Follow any conventions found — learnings override defaults.
+4. **Format detection:** If frontmatter contains `task_files:`, this is a split plan — task details are in separate files. If absent, legacy monolithic plan — all tasks inline.
+5. **Complexity routing** (`<JDI:ComplexityRouter />`): Simple (≤3 tasks, single stack/wave) → single agent. Complex → Agent Teams swarm. Override: `--team` / `--single`
+6. **Tech routing**: PHP → jdi-backend | TS/React → jdi-frontend | Full-stack → both
+7. Execute:
    - **Single agent:** Pass `PLAN: {index-path}`. For split plans, agent reads task files one at a time via `file:` field in state.yaml.
    - **Agent Teams:** For split plans, pass `TASK_FILE: {task-file-path}` in each agent's spawn prompt so they load only their assigned task file(s). For legacy plans, pass `PLAN: {plan-path}` as before.
-7. Collect and execute deferred ops (files, commits)
-8. Run verification (tests, lint, typecheck)
-9. Cleanup → update state
-10. Initialise review: `review.status` → `"draft"`, `review.revision` → 1, `review.scope` → `"implementation"`
+8. Collect and execute deferred ops (files, commits)
+9. Run verification (tests, lint, typecheck)
+10. **Update state via CLI** — do NOT manually edit state.yaml. Run `npx jdi state executing` before execution and `npx jdi state complete` after. Use `npx jdi state advance-task {task-id}` after each task completes.
 11. **Present summary** (tasks completed, files changed, verification results, deviations) then ask: _"Provide feedback to adjust, or say **approved** to finalise."_
-12. **Review loop**: approval → update state to `"complete"`, suggest commit/PR. Feedback → apply code changes, run tests, increment revision, re-present. Repeat until approved. Natural conversation — no separate command needed.
+12. **Review loop**: Feedback → apply code changes, run tests, increment revision, re-present. Approval → suggest commit/PR. Natural conversation — no separate command needed.
 
 Agent base (read FIRST for cache): .jdi/framework/components/meta/AgentBase.md | Agent specs: .jdi/framework/agents/jdi-backend.md, .jdi/framework/agents/jdi-frontend.md
 Orchestration: .jdi/framework/components/meta/AgentTeamsOrchestration.md | Routing: .jdi/framework/components/meta/ComplexityRouter.md

package/framework/commands/pr-review.md

@@ -5,11 +5,29 @@ description: "JDI: Review pull request"
 
 # /jdi:pr-review
 
+Review a pull request with learnings-aware analysis.
+
+## Flags
+
+- `--no-comments` — Do not post comments to GitHub. Write review to `.jdi/reviews/PR-{number}-review.md` instead.
+
 ## Delegation
 
+Parse flags from $ARGUMENTS. Map `--no-comments` to `post="false"`.
+
 Use Task tool with subagent_type="general-purpose" and prompt:
 
 Read ./.jdi/framework/components/meta/AgentBase.md for the base protocol.
+
+Read learnings before reviewing — these represent the team's coding standards and MUST be cross-referenced during review:
+- Always read: `.jdi/framework/learnings/general.md`
+- For PHP/Laravel PRs: also read `.jdi/framework/learnings/backend.md`
+- For React/TypeScript PRs: also read `.jdi/framework/learnings/frontend.md`
+- For test changes: also read `.jdi/framework/learnings/testing.md`
+- For CI/Docker changes: also read `.jdi/framework/learnings/devops.md`
+Apply learnings as additional review criteria — flag violations and praise adherence.
+
 Read ./.jdi/framework/components/quality/PRReview.md for review instructions.
+{If --no-comments flag was present: Include `post="false"` parameter — invoke as `<JDI:PRReview post="false" />`}
 
 Review PR: $ARGUMENTS

package/framework/components/meta/StateUpdate.md

@@ -6,7 +6,13 @@ description: Record decisions, deviations, and blockers in state.yaml
 
 # StateUpdate
 
-> **Status transitions are handled by the TypeScript framework.** Do NOT update `position`, `progress`, `current_plan`, `review`, or `session` fields in state.yaml — the CLI manages these automatically.
+> **Status transitions are handled via CLI commands.** Do NOT manually edit `position`, `progress`, `current_plan`, `review`, or `session` fields in state.yaml. Use these commands instead:
+>
+> - `npx jdi state plan-ready --plan-path "{path}" --plan-name "{name}"`
+> - `npx jdi state approved`
+> - `npx jdi state executing`
+> - `npx jdi state complete`
+> - `npx jdi state advance-task {task-id}`
 
 Use state.yaml ONLY to record decisions, deviations, or blockers:
 

package/framework/components/quality/PRReview.md

@@ -74,9 +74,20 @@ If context provided:
 
 Read each changed file in its entirety (not just the diff). **NEVER** use limit/offset.
 
+### Step 5b: Cross-Reference Learnings (MANDATORY)
+
+If learnings files were loaded (via the command stub or agent prompt), cross-reference every changed file against the team's learnings:
+
+1. For each finding from the review checklist, check if a learning exists that addresses it — cite the learning in your comment.
+2. Flag any code that **violates** a documented learning (e.g. a learning says "always use path aliases" but the PR uses relative imports).
+3. **Praise** code that follows learnings the team has documented — this reinforces good patterns.
+4. If no learnings were loaded, skip this step (but note it in your review summary as a gap).
+
+Learnings-based findings should use the same severity classification as other findings. A violation of a documented team convention is at minimum a **minor** finding.
+
 ### Step 6: Perform Code Review
 
-Apply <JDI:PRReview:Checklist /> to analyse each change.
+Apply <JDI:PRReview:Checklist /> to analyse each change. Include learnings violations alongside standard checklist findings.
 
 ### Step 7: Categorise Findings (Internal)
 

package/framework/templates/CLAUDE-SHARED.md

@@ -30,13 +30,31 @@ When you learn something new from a review or feedback, update the appropriate c
 
 ## Scope Discipline
 
-Only do what was explicitly requested. Do not add extras, tooling, or features the user did not ask for.
+Do not add unrelated extras, tooling, or features the user did not ask for. But DO investigate the full scope of what was requested — including implicit requirements that are clearly part of the ask (e.g. if a UI view needs columns, verify the backend provides them).
 If something is ambiguous, ask — do not guess.
 NEVER use time estimates (minutes, hours, etc). Use S/M/L t-shirt sizing for all task and plan sizing.
 Follow response templates exactly as instructed in the prompt — do not improvise the layout or structure.
 
-## Approval Gate
+## Approval Gate — HARD STOP
 
-Planning and implementation are separate gates — NEVER auto-proceed to implementation after planning or plan refinement.
-When the user provides refinement feedback on a plan, ONLY update the plan files in `.jdi/plans/`. Do NOT implement code.
-Implementation only happens when the user explicitly approves ("approved", "lgtm", "looks good", "ship it") or explicitly requests implementation ("implement", "build", "execute").
+Planning and implementation are **separate human-gated phases**. NEVER auto-proceed to implementation after planning or plan refinement.
+
+- When the user says "approved" / "lgtm" / "looks good" to a **plan**: this means the plan is finalised. It does NOT mean "go implement it." Finalise the plan review, output _"Plan approved. Run `/jdi:implement-plan` when ready."_, then **STOP**.
+- When the user provides refinement feedback on a plan, ONLY update the plan files in `.jdi/plans/`. Do NOT implement code.
+- Implementation ONLY happens when the user explicitly requests it: "implement", "build", "execute", or `/jdi:implement-plan`.
+
+## State Management
+
+Do NOT manually edit `.jdi/config/state.yaml` for status transitions. Use the CLI instead:
+
+- `npx jdi state plan-ready --plan-path "{path}" --plan-name "{name}"` — after plan creation
+- `npx jdi state approved` — after plan approval
+- `npx jdi state executing` — before implementation starts
+- `npx jdi state complete` — after implementation finishes
+- `npx jdi state advance-task {task-id}` — after each task completes
+
+You may only append to `decisions`, `deviations`, or `blockers` arrays in state.yaml directly via `<JDI:StateUpdate />`.
+
+## Self-Testing (Jedi development only)
+
+If the current project is the Jedi framework itself (`@benzotti/jedi`), run `bun test` after modifying prompt builders, action commands, or framework files. This catches regressions in split format references, learnings inclusion, and framework invariants.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benzotti/jedi",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "JDI - Context-efficient AI development framework for Claude Code",
   "type": "module",
   "bin": {