@benzotti/jedi 0.1.31 → 0.1.33

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
 
@@ -9873,6 +9873,24 @@ function buildProjectContext(ctx) {
   }
   return lines;
 }
+function buildLearningsBlock(techStack) {
+  const lower = techStack.toLowerCase();
+  const base = ".jdi/framework/learnings";
+  const files = [`${base}/general.md`];
+  if (/php|laravel/.test(lower))
+    files.push(`${base}/backend.md`);
+  if (/react|typescript|\.ts|frontend|vite/.test(lower))
+    files.push(`${base}/frontend.md`);
+  if (/test|vitest|pest/.test(lower))
+    files.push(`${base}/testing.md`);
+  if (/docker|ci|deploy/.test(lower))
+    files.push(`${base}/devops.md`);
+  return [
+    `## Learnings`,
+    `Read these learnings files and follow any conventions found (learnings override defaults):`,
+    ...files.map((f3) => `- ${f3}`)
+  ];
+}
 function agentPaths(cwd) {
   return {
     baseProtocol: resolve3(cwd, ".jdi/framework/components/meta/AgentBase.md"),
@@ -9905,6 +9923,8 @@ function buildImplementPrompt(ctx, planPath, overrideFlag) {
     ``,
     ...buildProjectContext(ctx),
     ``,
+    ...buildLearningsBlock(ctx.techStack),
+    ``,
     `## Task`,
     `Execute implementation plan: ${resolve3(ctx.cwd, planPath)}${overrideFlag ? `
 Override: ${overrideFlag}` : ""}`,
@@ -9934,6 +9954,8 @@ function buildQuickPrompt(ctx, description) {
     `- Working directory: ${ctx.cwd}`,
     `- Project type: ${ctx.projectType}`,
     ``,
+    ...buildLearningsBlock(ctx.techStack),
+    ``,
     `## Instructions`,
     `1. Make the minimal change needed to accomplish the task`,
     `2. Keep changes focused \u2014 do not refactor surrounding code`,
@@ -9953,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,
@@ -9970,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)?`,
@@ -10058,6 +10084,34 @@ async function writeState(cwd, state) {
 }
 
 // src/utils/state-handlers.ts
+async function transitionToPlanReady(cwd, planPath, planName) {
+  const state = await readState(cwd) ?? {};
+  state.position = {
+    ...state.position,
+    plan: planPath,
+    plan_name: planName,
+    status: "planning"
+  };
+  state.current_plan = {
+    ...state.current_plan,
+    path: planPath
+  };
+  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 = {
@@ -10076,6 +10130,23 @@ 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.tasks_completed = (state.progress.tasks_completed ?? 0) + 1;
+  }
+  await updateSessionActivity(cwd, state);
+}
 async function updateSessionActivity(cwd, state) {
   state.session = {
     ...state.session,
@@ -10599,7 +10670,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}`);
@@ -11709,6 +11781,8 @@ Say **\`Hey Jedi implement\`** when you're ready to go.`;
         ``,
         ...contextLines,
         ``,
+        ...buildLearningsBlock(techStack),
+        ``,
         fenceUserInput("conversation-history", conversationHistory),
         ``,
         `## Feedback on Implementation`,
@@ -11836,6 +11910,8 @@ Use the ClickUp ticket above as the primary requirements source.` : ``,
             `Read ${resolve11(cwd, ".jdi/framework/components/meta/AgentTeamsOrchestration.md")} for Agent Teams orchestration (if needed).`,
             ``,
             ...contextLines,
+            ``,
+            ...buildLearningsBlock(techStack),
             historyBlock,
             `## Task`,
             `Execute the current implementation plan. Read state.yaml for the active plan path.`,
@@ -11856,6 +11932,8 @@ Use the ClickUp ticket above as the primary requirements source.` : ``,
             `Read ${baseProtocol} for the base agent protocol.`,
             ``,
             ...contextLines,
+            ``,
+            ...buildLearningsBlock(techStack),
             historyBlock,
             `## Task`,
             `Make this quick change:`,
@@ -11931,6 +12009,8 @@ Use the ClickUp ticket above as the primary requirements source.` : ``,
           ``,
           ...contextLines,
           ``,
+          ...buildLearningsBlock(techStack),
+          ``,
           `## Task`,
           `Execute the most recently created implementation plan in .jdi/plans/.`,
           `Follow the implement-plan orchestration.`,
@@ -12063,10 +12143,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.31",
+  version: "0.1.33",
   description: "JDI - Context-efficient AI development framework for Claude Code",
   type: "module",
   bin: {
@@ -12128,7 +12312,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
 
@@ -38,10 +40,11 @@ You MUST write files using Write/Edit tools. Returning plan content as text is N
 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)
+3. `.jdi/config/variables.yaml`
+4. `.jdi/ROADMAP.yaml` (add plan entry)
+5. `.jdi/REQUIREMENTS.yaml` (add traceability)
+
+**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 +90,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 +106,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 +147,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

@@ -22,10 +22,16 @@ Create an implementation plan using a single planner agent (includes research).
 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.
+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,27 @@ 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 />`.

package/package.json

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